> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kibocommerce.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokenize Payment Cards

> Send card details to the Kibo PCI payments host, get a paymentServiceCardId, and use it for saved cards and order payments.

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](https://docs.kibocommerce.com/concept-guides/payments.md).

## How It Works

1. The shopper enters card details in your checkout or account page.
2. The shopper's browser sends the details directly to the PCI payments host.
3. The payment service returns a card `id` and a masked card number, `numberPart`.
4. 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.

> [!WARNING]
>
> 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](https://docs.kibocommerce.com/pages/typescript-sdk.md) or as `KIBO_PCI_HOST` in the [Nuxt.js storefront](https://docs.kibocommerce.com/pages/nuxtjs.md).

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.

```http theme={null}
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`:

```json theme={null}
{
  "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](https://docs.kibocommerce.com/api-reference/customeraccount/add-account-card.md) (`POST /api/commerce/customer/accounts/{accountId}/cards`). Set the card `id` to the `paymentServiceCardId`.

```json theme={null}
{
  "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](https://docs.kibocommerce.com/developer-guides/customer.md#example-4-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](https://docs.kibocommerce.com/api-reference/checkout/create-payment-action.md) for a checkout or [Create Payment Action](https://docs.kibocommerce.com/api-reference/order/create-payment-action.md) for an order. Put the card in `newBillingInfo.card`:

```json theme={null}
{
  "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](https://docs.kibocommerce.com/pages/payment-types-api-reference.md#creditcard).

## 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.

```http theme={null}
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](https://docs.kibocommerce.com/api-reference/customeraccount/update-account-card.md) 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`.

```http theme={null}
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](https://docs.kibocommerce.com/api-reference/customeraccount/delete-account-card.md).

## Related Guides

* [Payment Types API Reference](https://docs.kibocommerce.com/pages/payment-types-api-reference.md): the `BillingInfo` object for each payment type.
* [Payment Actions](https://docs.kibocommerce.com/pages/payment-actions.md): authorizing, capturing, voiding, and crediting payments.
* [Customer API Developer Guide](https://docs.kibocommerce.com/developer-guides/customer.md): customer accounts, contacts, and saved cards.
* [Payments: A Conceptual Guide](https://docs.kibocommerce.com/concept-guides/payments.md): how the payment subsystem works.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.