# Card payments for Payment Setup API

To accept card payments, you must:

1. Create a payment setup.
2. Update the payment setup with the card details.
3. Confirm the payment.

---

## Create a payment setup

Call the [Create a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/createAPaymentSetup) endpoint.

> **Information**
>
> The Payment Setup API supports [idempotency](https://www.checkout.com/docs/developer-resources/api/idempotency.md). You can safely retry API requests without the risk of duplicate requests.

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/setups`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups`

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "USD",
  "amount": 2000,
  "reference": "ORDER_01234",
  "description": "Card payment",
  "payment_type": "Regular",
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

In the request body, provide the following:

- `processing_channel_id` – The [processing channel's](https://www.checkout.com/docs/business-operations/use-the-dashboard/manage-processing-channels.md) unique identifier
- `amount` – The payment amount
- `currency` – The payment currency

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 2000,
  "currency": "USD",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "Card payment",
  "payment_methods": {
    "card": {
      "status": "pending",
      "flags": []
    }
  },
  "available_payment_methods": [
    "card"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

For card, `payment_methods` contains the following fields:

- `status` – The [status of the payment method](https://www.checkout.com/docs/payments/accept-payments/accept-a-payment-using-the-payment-setup-api#Payment_method_status).
- `flags` – An array of error codes or indicators that highlight missing or invalid information.

---

## Update the payment setup

When the customer selects card as the payment method on the checkout page, collect their card details and call the [Update a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/updateAPaymentSetup) endpoint to submit them.

You can provide either a card token or the full card details.

**Card token**

A token is a secure representation of sensitive payment details. Requesting a payment with the token ensures that the details do not reach your server.

When updating the payment setup, provide the following fields:

| Field | Description |
| --- | --- |
| `payment_methods.card.token`<br>`object` | A Checkout.com token representing the card. Required if `payment_methods.card.details` is not provided. |
| `payment_methods.card.token.id`<br>`string` | The token identifier, prefixed by `tok_`.<br><br>**Required** |
| `payment_methods.card.account_holder.type`<br>`string` | The card account holder type.<br><br>Supported values:<br><br>- `individual`<br>- `corporate`<br>- `government`<br><br>**Required** |
| `payment_methods.card.account_holder.first_name`<br>`string` | The card account holder's first name.<br><br>Max length: 35 <br><br>**Required** |
| `payment_methods.card.account_holder.last_name`<br>`string` | The card account holder's last name.<br><br>Max length: 35 <br><br>**Required** |
| `payment_methods.card.account_holder.middle_name`<br>`string` | The card account holder's middle name.<br><br>Max length: 35 |
| `payment_methods.card.account_holder.account_name_inquiry`<br>`boolean` | Indicates whether the ANI (account name inquiry) check is performed with the card scheme (Visa or Mastercard). |
| `payment_methods.card.phone`<br>`object` | The customer's phone number. |
| `payment_methods.card.phone.country_code`<br>`string` | The phone number's international country calling code.<br><br>Min length: 1 <br><br>Max length: 7 |
| `payment_methods.card.phone.number`<br>`string` | The phone number.<br><br>Min length: 6 <br><br>Max length: 25 |
| `payment_methods.card.store_for_future_use`<br>`boolean` | Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response. |
| `payment_methods.card.preferred_scheme`<br>`string` | The preferred card scheme for co-badged cards.<br><br>Supported values:<br><br>- `visa`<br>- `mastercard`<br>- `cartes_bancaires` |

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "USD",
  "amount": 2000,
  "reference": "ORDER_01234",
  "description": "Card payment",
  "payment_type": "Regular",
  "payment_methods": {
    "card": {
      "token": {
        "id": "tok_4gzeau5lnbcubj3fjzaqpdbdrm"
      },
      "account_holder": {
        "type": "individual",
        "first_name": "Toby",
        "last_name": "Arden"
      }
    }
  }
}
```

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 2000,
  "currency": "USD",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "Card payment",
  "payment_methods": {
    "card": {
      "status": "ready",
      "flags": [],
      "schemes": [
        "visa",
        "mastercard"
      ]
    }
  },
  "available_payment_methods": [
    "card"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

**Full card details**

If your level of [PCI compliance](https://www.checkout.com/docs/business-operations/ensure-regulatory-compliance/pci-compliance.md) is SAQ D, you can request a payment using the card's full details.

When updating the payment setup, provide the following fields:

| Field | Description |
| --- | --- |
| `payment_methods.card.details`<br>`object` | The card details. Required if `payment_methods.card.token` is not provided. |
| `payment_methods.card.details.number`<br>`string` | The card number (without separators).<br><br>**Required** |
| `payment_methods.card.details.expiry_month`<br>`integer` | The expiry month of the card.<br><br>Minimum: 1 <br><br>Maximum: 12 <br><br>**Required** |
| `payment_methods.card.details.expiry_year`<br>`integer` | The expiry year of the card.<br><br>**Required** |
| `payment_methods.card.details.cvv`<br>`string` | The card verification value/code. 3 digits, except for American Express (4 digits).<br><br>Min length: 3 <br><br>Max length: 4 |
| `payment_methods.card.details.name`<br>`string` | The cardholder's name. |
| `payment_methods.card.details.stored`<br>`boolean` | Set to `true` for payments that use stored card details. |
| `payment_methods.card.details.allow_update`<br>`boolean` | Indicates whether to use the Real-Time Account Updater to update the card information. |
| `payment_methods.card.account_holder.type`<br>`string` | The card account holder type.<br><br>Supported values:<br><br>- `individual`<br>- `corporate`<br>- `government`<br><br>**Required** |
| `payment_methods.card.account_holder.first_name`<br>`string` | The card account holder's first name.<br><br>Max length: 35 <br><br>**Required** |
| `payment_methods.card.account_holder.last_name`<br>`string` | The card account holder's last name.<br><br>Max length: 35 <br><br>**Required** |
| `payment_methods.card.account_holder.account_name_inquiry`<br>`boolean` | Indicates whether the ANI (account name inquiry) check is performed with the card scheme (Visa or Mastercard). |
| `payment_methods.card.account_holder.middle_name`<br>`string` | The card account holder's middle name.<br><br>Max length: 35 |
| `payment_methods.card.phone`<br>`object` | The customer's phone number. |
| `payment_methods.card.phone.country_code`<br>`string` | The phone number's international country calling code.<br><br>Min length: 1 <br><br>Max length: 7 |
| `payment_methods.card.phone.number`<br>`string` | The phone number.<br><br>Min length: 6 <br><br>Max length: 25 |
| `payment_methods.card.store_for_future_use`<br>`boolean` | Set to `true` if you intend to reuse the payment credentials in subsequent payments. If set to `false`, a payment instrument will not be included in the payment response. |
| `payment_methods.card.preferred_scheme`<br>`string` | The preferred card scheme for co-badged cards.<br><br>Supported values:<br><br>- `visa`<br>- `mastercard`<br>- `cartes_bancaires` |

### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "USD",
  "amount": 2000,
  "reference": "ORDER_01234",
  "description": "Card payment",
  "payment_type": "Regular",
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  },
  "payment_methods": {
    "card": {
      "details": {
        "number": "4242424242424242",
        "expiry_month": 6,
        "expiry_year": 2028,
        "cvv": "100",
        "name": "Toby Arden"
      },
      "account_holder": {
        "type": "individual",
        "first_name": "Toby",
        "last_name": "Arden"
      }
    }
  }
}
```

### Response example

```json
{
  "id": "set_rcmepwrchqab2wsergcafvijfy",
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "amount": 2000,
  "currency": "USD",
  "payment_type": "Regular",
  "reference": "ORDER_01234",
  "description": "Card payment",
  "payment_methods": {
    "card": {
      "status": "ready",
      "flags": [],
      "schemes": [
        "visa",
        "mastercard"
      ]
    }
  },
  "available_payment_methods": [
    "card"
  ],
  "settings": {
    "success_url": "https://example.com/payments/success",
    "failure_url": "https://example.com/payments/failure"
  }
}
```

The response returns a `ready` status when the payment details have been successfully validated. The payment is ready to confirm.

### Co-badged cards

The response also includes a `schemes` array listing the card schemes associated with the card.

Some cards are enrolled in more than one card scheme, for example, a card that supports both Visa and Cartes Bancaires. When the customer uses one of these co-badged cards, the `schemes` field in the response lists the available schemes for that card.

To route the payment through a specific card scheme, set `preferred_scheme` when updating the payment setup. Supported `preferred_scheme` values are:

- `cartes_bancaires`
- `mastercard`
- `visa`

> **Information**
>
> If the card is not co-badged, or the requested scheme is not available for the card, Checkout.com ignores the field and processes the payment through the default scheme.

### Account funding transactions

If the card payment funds an account or wallet (for example, a wallet top-up or a person-to-person transfer), provide account funding transaction (AFT) details when you update the payment setup.

AFTs are subject to additional regulatory requirements, including mandatory sender and recipient information. Review the [sender and recipient field requirements](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction.md#field_validation_requirements) when processing AFTs to ensure that your requests meet the requirements for the card scheme and operating region.

When updating the payment setup, provide the following fields:

> **Note**
>
> Which `sender` and `recipient` fields are mandatory depends on the card scheme and the operating region. Review the [sender and recipient field requirements](https://www.checkout.com/docs/payments/manage-payments/perform-an-account-funding-transaction.md#field_validation_requirements) before going live. Payments that fail to meet these requirements are declined with a `422` status code.

| Field | Description |
| --- | --- |
| `account_funding_transaction.enabled`<br>`boolean` | Set to `true` to process this payment as an account funding transaction.<br><br>**Required** |
| `account_funding_transaction.purpose`<br>`string` | The purpose of the account funding transaction.<br><br>Supported values:<br><br>- `donations`<br>- `education`<br>- `emergency_need`<br>- `expatriation`<br>- `family_support`<br>- `financial_services`<br>- `gifts`<br>- `income`<br>- `insurance`<br>- `investment`<br>- `it_services`<br>- `leisure`<br>- `loan_payment`<br>- `medical_treatment`<br>- `other`<br>- `pension`<br>- `royalties`<br>- `savings`<br>- `travel_and_tourism` |
| `account_funding_transaction.sender.date_of_birth`<br>`string` | The sender's date of birth, in `yyyy-mm-dd` format. |
| `account_funding_transaction.sender.reference`<br>`string` | A unique reference for the sender of the payment. |
| `account_funding_transaction.sender.identification.type`<br>`string` | The type of identification used to identify the sender.<br><br>Supported values:<br><br>- `passport`<br>- `driving_licence`<br>- `national_id` |
| `account_funding_transaction.sender.identification.number`<br>`string` | The sender's identification number. |
| `account_funding_transaction.sender.identification.issuing_country`<br>`string` | The two-letter ISO country code of the country that issued the identification.<br><br>Min length: 2 <br><br>Max length: 2 |
| `account_funding_transaction.recipient.date_of_birth`<br>`string` | The recipient's date of birth, in `yyyy-mm-dd` format. |
| `account_funding_transaction.recipient.account_number`<br>`string` | An identifier for the recipient's account, such as part of the PAN (first six and last four digits), an IBAN, an internal account number, or a phone number.<br><br>Max length: 34 |
| `account_funding_transaction.recipient.first_name`<br>`string` | The recipient's first name.<br><br>Max length: 50 |
| `account_funding_transaction.recipient.last_name`<br>`string` | The recipient's last name.<br><br>Max length: 50 |
| `account_funding_transaction.recipient.address`<br>`object` | The recipient's address. |

The `sender` type, first and last name fields are mapped from the `payment_methods.<card|applepay|googlepay>.account_holder` fields:

- `payment_methods.<card|applepay|googlepay>.account_holder.type`
- `payment_methods.<card|applepay|googlepay>.account_holder.first_name`
- `payment_methods.<card|applepay|googlepay>.account_holder.last_name`

#### Request example

```json
{
  "processing_channel_id": "pc_wzjki6hw5puepb5fnvqlizj2e4",
  "currency": "USD",
  "amount": 2000,
  "reference": "ORDER_01234",
  "description": "Card payment",
  "payment_type": "Regular",
  "account_funding_transaction": {
    "enabled": true,
    "purpose": "financial_services",
    "sender": {
      "date_of_birth": "1990-12-31",
      "reference": "0fc88634-78c1-4286-9cb6-6ca358730c8c",
      "identification": {
        "type": "passport",
        "number": "1234567890",
        "issuing_country": "US"
      }
    },
    "recipient": {
      "date_of_birth": "1990-12-31",
      "account_number": "123456******1234",
      "first_name": "Hannah",
      "last_name": "Bret"
    }
  },
  "payment_methods": {
    "card": {
      "token": {
        "id": "tok_4gzeau5lnbcubj3fjzaqpdbdrm"
      },
      "account_holder": {
        "type": "individual",
        "first_name": "Toby",
        "last_name": "Arden"
      }
    }
  }
}
```

---

## Confirm the payment

When the payment status changes to `ready`, confirm the payment by calling the [Confirm a payment setup](https://api-reference.checkout.com/tag/Payment-Setups/#operation/confirmAPaymentSetup) endpoint and provide:

- The payment setup `id` as the `{id}` path parameter.
- `card` as the `{payment_method_name}` path parameter.

**Production**

`POST` `https://{prefix}.api.checkout.com/payments/setups/{id}/confirm/card`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments/setups/{id}/confirm/card`

A successful response returns a `payment_id` that you can use to track the payment.