Search Overlay

Add a Card to a Profile

POST /customervault/v1/profiles/profile_id/cards

See our full API documentation for a complete description of the parameters required for the card creation request.

The Customer Vault API allows you to store multiple credit cards against your customer's profile. For billing purposes, each credit card can be associated with a different address, or all credit cards can be associated with the same billing address, depending on your business needs.

To add a credit card to a profile and associate it with the address you just created, you must use the profile ID (716adb4f-6b85-4089-ba9c-d9c0eb649cd7 in the previous example) and make a POST request to the cards endpoint of the relevant profile. The POST body contains the card information and a billingAddressId parameter containing the address ID you want to associate the card with (81ffcddf-ad82-40d2-aaa0-c4f9c376ad65 in the previous example).

curl -X POST \
-u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
-H 'Content-Type: application/json' \
-d ' {
"nickName":"Personal Visa",
"holderName" : "John Smith",
"cardNum" : "4530910000012345",
"cardExpiry" : {
"month" : 12,
"year" : 2019
"billingAddressId" : "81ffcddf-ad82-40d2-aaa0-c4f9c376ad65"

Before trying the example, you should:

  • Replace the API key (after the -u) with the API key you have received.
  • Replace the profile ID and billingAddressId values with the ID values returned when you created an example profile and address respectively.
Element Type Required? Description
billingAddressId string No This is the ID returned when the address was created. This is the address associated with the card.
accountId string No This is a merchant account ID (FMA) that the merchant provides and will be linked to the card from this request. For ex: 1002370290.
cardExpiry object Yes

This is the card's expiry date. The following parameters are required:

  • month – number, length=2
  • year – number, length=4
cardNum string Yes This is the card number.
defaultCardIndicator boolean No This is the flag that marks this card as the default for the profile.
holderName string Yes This is the cardholder's name.
merchantRefNum string No This is the merchant's own card identification.
nickName string No This is an alias for this address defined by the customer e.g., "home address".

"id" : "178ae2b8-85a5-4761-b1dd-4f14ac73571b",
"status" : "ACTIVE",
"holderName" : "John Smith",
"cardBin" : "453091",
"lastDigits" : "2345",
"cardExpiry" : {
"month" : 12,
"year" : 2019
"cardType" : "VI",
"paymentToken" : "CaBP0abDKgROjYU",
"billingAddressId" : "81ffcddf-ad82-40d2-aaa0-c4f9c376ad65",
"defaultCardIndicator" : false

The response parameters not contained in the request are described below:

Element Type Description


This is the card ID returned in the response.
cardType enum

This is the card brand. Possible values are

  • AM - American Express
  • DC - Diners Club
  • DI - Discover
  • MC - Mastercard
  • VI - Visa
cardCategory enum

This denotes the card category. Possible values are:

  • CREDIT – Credit card
  • DEBIT – Debit card
  • PREPAID – Prepaid card
  • UNKNOWN – BIN not found in database


This is a token that represents the card and is returned in the response.
On this Page