Tokenize Payment Cards

Kibo commerce APIs never take a raw card number. Before you save a card to a customer account or apply a card payment to a checkout or order, you send the card details to the Kibo payment service on the PCI payments host. The payment service stores the card and returns a card ID. You then use that ID, called paymentServiceCardId, in every other API call. This keeps card data off your servers and out of the commerce APIs, which reduces your PCI DSS scope. For background on how payments work in Kibo, see Payments: A Conceptual Guide.

How It Works

The shopper enters card details in your checkout or account page.
The shopper’s browser sends the details directly to the PCI payments host.
The payment service returns a card id and a masked card number, numberPart.
Your storefront sends the id as paymentServiceCardId, with numberPart, to the commerce APIs:
- to save the card to a customer account, or
- to pay for a checkout or order.

Call the card endpoint from the shopper’s browser. Do not send card numbers or CVVs through your own servers, and do not log or store them. Only the returned id and numberPart should reach your application.

The PCI Payments Host

Card requests go to the PCI payments host, not to your tenant host. This is the same host you set as pciHost in the TypeScript SDK or as KIBO_PCI_HOST in the Nuxt.js storefront. For example, a sandbox tenant at https://t1000000.sb.usc1.gcp.kibocommerce.com uses the PCI payments host https://payments-sb.usc1.gcp.kibocommerce.com. If you do not know the PCI payments host for your environment, contact Kibo Support. The card endpoints are:

Operation	Method and path
Create a card	`POST /payments/commerce/payments/cards/`
Update a card	`PUT /payments/commerce/payments/cards/{cardId}`
Delete a card	`DELETE /payments/commerce/payments/cards/{cardId}`

Send your tenant ID in the x-vol-tenant header and your site ID in the x-vol-site header. These requests do not take an access token, so the shopper’s browser can call them without your application credentials.

Create a Card

Send the card details in the request body.

POST https://payments-sb.usc1.gcp.kibocommerce.com/payments/commerce/payments/cards/
x-vol-tenant: 1000000
x-vol-site: 1000001
Content-Type: application/json

{
  "cardNumber": "4111111111111111",
  "cardType": "VISA",
  "cardHolderName": "Jane Shopper",
  "expireMonth": 12,
  "expireYear": 2030,
  "cvv": "123"
}

Field	Description
`cardNumber`	The full card number, digits only. If `isTokenized` is `true`, a token from your payment gateway instead.
`cardType`	The card type, such as `VISA`, `MC`, `AMEX`, `DISCOVER`, or `JCB`.
`cardHolderName`	The name on the card.
`expireMonth`	The expiration month, from 1 to 12.
`expireYear`	The expiration year, such as `2030`.
`cvv`	The card security code.
`isTokenized`	Optional. Set to `true` when `cardNumber` holds a token from your payment gateway’s own card capture, not a card number. Omit it for a card number.
`cardIssueNumber`, `cardIssueMonth`, `cardIssueYear`	Optional. Issue details, for cards that have them.

For VISA, MC, AMEX, DISCOVER, and JCB cards, the payment service checks the card number and expiration date before it stores the card. An invalid card returns an error. A successful request returns 200 OK:

{
  "id": "4177f567253f40eea469c4d225d786ad",
  "numberPart": "************1111",
  "isSuccessful": true,
  "balance": 0
}

Field	Description
`id`	The card ID. Use it as `paymentServiceCardId` in the commerce APIs.
`numberPart`	The card number with all but the last four digits masked. Keep it with the `id`.
`isSuccessful`	`true` when the card was stored.
`balance`	Not used for payment cards.

Keep both id and numberPart. The commerce APIs need both to identify the card, and the payment service needs numberPart when it authorizes a payment.

Save the Card to a Customer Account

To let a shopper reuse the card, add it to their account with Add Account Card (POST /api/commerce/customer/accounts/{accountId}/cards). Set the card id to the paymentServiceCardId.

{
  "id": "4177f567253f40eea469c4d225d786ad",
  "nameOnCard": "Jane Shopper",
  "cardType": "VISA",
  "cardNumberPart": "************1111",
  "expireMonth": 12,
  "expireYear": 2030,
  "contactId": 1,
  "isDefaultPayMethod": true
}

contactId is the ID of the billing contact on the customer account. For a full example, see Add a Saved Credit Card in the Customer API developer guide.

Pay with the Card

To pay for a checkout or an order, create a payment action with a CreatePayment action name. Use Create Payment Action for a checkout or Create Payment Action for an order. Put the card in newBillingInfo.card:

{
  "actionName": "CreatePayment",
  "amount": 99.99,
  "currencyCode": "USD",
  "newBillingInfo": {
    "paymentType": "CreditCard",
    "paymentWorkflow": "Mozu",
    "billingContact": { ... },
    "card": {
      "paymentServiceCardId": "4177f567253f40eea469c4d225d786ad",
      "cardNumberPartOrMask": "************1111",
      "paymentOrCardType": "VISA",
      "nameOnCard": "Jane Shopper",
      "expireMonth": 12,
      "expireYear": 2030,
      "isTokenized": true
    }
  }
}

Set cardNumberPartOrMask to the numberPart value from the create response. For a card saved on the customer account, use the account card’s id and cardNumberPart. For every field in billingInfo, see Payment Types API Reference.

Update a Card

To change a stored card, such as a new expiration date, send PUT to the card’s ID with the fields you want to change. Fields you leave out keep their current values. Always include cardNumber: to keep the stored number, send the masked numberPart from the create response.

PUT https://payments-sb.usc1.gcp.kibocommerce.com/payments/commerce/payments/cards/4177f567253f40eea469c4d225d786ad
x-vol-tenant: 1000000
x-vol-site: 1000001
Content-Type: application/json

{
  "cardNumber": "************1111",
  "expireMonth": 6,
  "expireYear": 2031
}

The response has the same fields as the create response. The id does not change. If the card is saved to a customer account, also update the account card with Update Account Card so the account shows the same details.

Delete a Card

To remove a card from the payment service, send DELETE to the card’s ID. A successful request returns 204 No Content.

DELETE https://payments-sb.usc1.gcp.kibocommerce.com/payments/commerce/payments/cards/4177f567253f40eea469c4d225d786ad
x-vol-tenant: 1000000
x-vol-site: 1000001

If the card is saved to a customer account, remove it from the account with Delete Account Card.

Payment Types API Reference: the BillingInfo object for each payment type.
Payment Actions: authorizing, capturing, voiding, and crediting payments.
Customer API Developer Guide: customer accounts, contacts, and saved cards.
Payments: A Conceptual Guide: how the payment subsystem works.

Catalog

Customers

B2B

Fulfillment

Inventory

Locations

Marketing

CMS

Orders

Publishing

Order Routing

Reporting

Search

Subscriptions

System

Call Center

Content

Import/Export

Kibo AI

Dropship

How It Works

The PCI Payments Host

Create a Card

Save the Card to a Customer Account

Pay with the Card

Update a Card

Delete a Card

​How It Works

​The PCI Payments Host

​Create a Card

​Save the Card to a Customer Account

​Pay with the Card

​Update a Card

​Delete a Card

​Related Guides

How It Works

The PCI Payments Host

Create a Card

Save the Card to a Customer Account

Pay with the Card

Update a Card

Delete a Card

Related Guides