API Reference
Login to SandboxCreate Account

Add a Payment Method

post
https://api-test.qualpay.com/platform/vault/customer//billing

Tokenizes and adds a payment method to a customer profile in Customer Vault. This returns the tokenized card number (or card ID) in the card_id field. You can use this card ID in lieu of the card number in Payment Gateway API requests.

You can add a limitless number of payment methods to a customer profile. By default, the system designates the first payment method added as the primary payment method, and it uses that for subscription payments. Send a 'Set Primary Payment Method' request to change the primary payment method.

Path Params
string
required

The customer ID, returned as the customer_id value in an 'Add a Customer' response.

Body Params

Customer

string

Format: Variable length, up to 64 AN
Description: Business name, if applicable.
Conditional Requirement: When adding an ACH payment method, the following is required:
(a) tr_number, dda_number, billing_first_name, and billing_last_name, or
(b) tr_number, dda_number, and billing_firm_name.

string

Format: Variable length, up to 32 AN
Description: Billing first name.
Conditional Requirement: When adding an ACH payment method, the following is required:
(a) tr_number, dda_number, billing_first_name, and billing_last_name, or
(b) tr_number, dda_number, and billing_firm_name.

string

Format: Variable length, up to 32 AN
Description: Billing last name.
Conditional Requirement: When adding an ACH payment method, the following is required:
(a) tr_number, dda_number, billing_first_name, and billing_last_name, or
(b) tr_number, dda_number, and billing_firm_name.

string

Format: Fixed length, 32 AN
Description: Card ID received from a tokenization request. card_id may be used in place of card_number or card_swipe. Duplicate cards are not permitted for a customer in the system. The card_id should be permanent. If a single-use card_id should be used, set the verify field to true, which makes the card_id permanent.
Conditional Requirement: When adding a billing card, the following is required:
(a) card_number, exp_date, and billing_zip, or
(b) card_id and billing_zip.

string

Format: Variable length, up to 16 AN
Description: The full card number. When a card is added, it is immediately tokenized, and a card_id value is generated and stored in Vault. Duplicate cards are not permitted for a customer in the system.
Conditional Requirement: When adding a billing card, the following is required:
(a) card_number, exp_date, and billing_zip, or
(b) card_id and billing_zip.

string

Format: Fixed length, 4 N, MMYY format
Description: Expiration date of the cardholder's card number.
Conditional Requirement: When adding a billing card, the following is required:
(a) card_number, exp_date, and billing_zip, or
(b) card_id and billing_zip.

string

Format: Fixed length, 9 N
Description: Bank transit/routing number. Applicable for ACH account numbers.
Conditional Requirement: When adding an ACH payment method, the following is required:
(a) tr_number, dda_number, billing_first_name, and billing_last_name, or
(b) tr_number, dda_number, and billing_firm_name.

string

Format: Variable length, up to 17 N
Description: Owner's account number at the bank. Applicable for ACH account numbers.
Conditional Requirement: When adding an ACH payment method, the following is required:
(a) tr_number, dda_number, billing_first_name, and billing_last_name, or
(b) tr_number, dda_number, and billing_firm_name.

string

Format: Variable length, up to 128 AN
Description: Billing street address. This address will also be used for AVS verification if AVS verification is enabled.

string

Format: Variable length, up to 128 AN
Description: Billing address line 2.

string

Format: Variable length, up to 64 AN
Description: Billing city.

string

Format: Variable length, up to 3 AN
Description: Billing state.

string
required

Format: Variable length, up to 10 AN
Description: Billing zip code. This field will also be used for AVS verification if AVS verification is enabled.
Conditional Requirement: When adding a billing card, the following is required:
(a) card_number, exp_date, and billing_zip, or
(b) card_id and billing_zip.

string

Format: Fixed length, 4 N
Description: Billing zip+4 code if applicable.

string

Format: Variable length, up to 128 AN
Description: Billing country.

string

Format: Fixed length, 3 AN
Description: ISO numeric country code for the billing address. Refer to Country Codes for a list of country codes.

billing_email
array of strings

Format: Variable length, up to 128 AN
Description: An array of billing email addresses.

billing_email
string

Format: Variable length, up to 4 N
Description: CVV2 or CID value from the signature panel on the back of the cardholder's card. If present during a request where verify is set to true, the value will be sent to the issuer for validation. This field is not stored in Customer Vault.

int64

Format: Variable length, up to 16 AN
Description: Identifies the merchant to whom this request applies. Optional field, applicable only if the request is sent on behalf of another merchant.
Conditional Requirement: Required if this request is on behalf of another merchant.

boolean

Description: Set this field to true if this should be the default card. The default card will be used in recurring billing payments.
Default: false

string

Format: Fixed length, 1 AN
Description: Bank account type. Applicable for ACH account numbers. Possible values:

  • C = Personal checking account
  • S = Personal savings account
  • K = Business checking account
  • V = Business savings account

Default: C

boolean

Description: Set this field to true if card_number or card_id should be verified by the issuer before adding to Customer Vault. When this field is set to true, the customer is added to Customer Vault regardless of whether verification succeeds.
Default: false

Responses

Updated 6 months ago

Language
Credentials
Basic
base64
:
URL
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 6 months ago