commerce/payments/cards

These APIs are used to register, update, and remove customer credit cards. The Create operation is the most frequently used one - when paying for an order using a credit card, the storefront first takes the full credit card information and calls Create on the PaymentService to store the card. The PaymentService responds with a SyncResponse containing a card ID. Any further references to that credit card are done using the card ID so that eCommerce doesn't have the full credit card info in hand. With the card ID, the storefront can call CreatePaymentAction (either for single-ship or multi-ship) to add a payment for that credit card to the order/checkout.

JSON Example

PublicCard Properties

Property Description
cardHolderName

type: string

The card holder full name.

cardIssueMonth

type: int

The month the credit card was issued; used by some cards.

cardIssueNumber

type: string

For Amex Cards, this is an additional field for verification that is used in conjunction with a CVV

cardIssueYear

type: int

The issue year; used by some cards.

cardNumber

type: string

This is the full number of the card.

cardType

type: string

The type of credit card, such as Visa or Amex.

cvv

type: string

The CVV code for the credit card.

expireMonth

type: int

The two-digit month a credit card expires for a payment method.

expireYear

type: int

The four-digit year the credit card expires for a payment method.

Operations

Operation Name Request URI Description
Create POST %3fresponseFields%3d%7bresponseFields%7d

Registers a card and adds a payment to the order or checkout.

Delete DELETE %7bcardId%7d

Removes a card from the order or checkout.

GetGiftCardBalance POST %7bcardId%7d%2fbalance%3fresponseFields%3d%7bresponseFields%7d

The Gift Card Balance APIs support processing gift cards through payment gateways. This API is used for gift cards that have already been registered with PaymentService via the payments/cards Create operation. In order to retrieve the card’s balance, you need the card ID (which is supplied in the endpoint) and the masked card number with the last 4 digits (cardNumberPart). PaymentService will use the last 4 digits along with the info it has stored for that card ID to reconstruct the full card info for doing a balance request to the gateway.

GetUnregisteredGiftCardBalance POST balance%3fresponseFields%3d%7bresponseFields%7d

The Get Gift Card Balance APIs support processing gift cards through payment gateways. This API is used for cards that have not been registered with PaymentService yet. Since there’s no card ID to look up, the full card number must be provided in the cardNumberPart. This is used on storefront when you first try to add a gift card payment. eCommerce checks to see if the gift card has a balance first so that empty cards are not registered.

Update PUT %7bcardId%7d%3fresponseFields%3d%7bresponseFields%7d

Updates the information of existing card records.