Get started with Issuing

Last updated: April 11, 2024

Use the Issuing API and sandbox environment to issue a card to a cardholder and perform a test transaction.

Information

This is a quick start guide. For an in-depth guide to issuing cards, see our Issue a card page.

You create a cardholder.
You create a card and issue it to the cardholder.
You simulate an authorization request with the issued card.
You simulate clearing the authorization.

Make sure you have a test account with Checkout.com, and that it has card issuing capabilities enabled. You must also set up OAuth 2.0 authentication to authenticate your API requests.

To receive notifications for the various issuing-related events triggered throughout the steps, configure your webhook receiver.

Create a cardholder. You'll issue a card to the cardholder in the next step.

post

https://api.sandbox.checkout.com/issuing/cardholders


1{
2  "type": "individual",
3  "first_name": "John",
4  "last_name": "Smith",
5  "email": "[email protected]",
6  "billing_address": {
7    "address_line1": "123 High Street",
8    "address_line2": "Flat 456",
9    "city": "London",
10    "zip": "SW1A 1AA",
11    "country": "GB"
12  }
13}


1{
2  "id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
3  "type": "individual",
4  "status": "active",
5  "created_date": "2019-09-10T10:11:12Z",
6  "last_modified_date": "2019-09-10T10:11:12Z",
7  "_links": {
8    "self": {
9      "href": "https://api.sandbox.checkout.com/issuing/cardholders/crh_d3ozhf43pcq2xbldn2g45qnb44"
10    }
11  }
12}

Make a note of the cardholder id value in the response. You'll need this to issue the card in the next step.

In the following example, you'll issue a single-use virtual card to the cardholder you created previously. You'll also activate the card so that the cardholder can use it to perform transactions immediately.

Pass the cardholder id returned in the previous response to the cardholder_id field.

post

https://api.sandbox.checkout.com/issuing/cards


1{
2  "type": "virtual",
3  "cardholder_id": "crh_d3ozhf43pcq2xbldn2g45qnb44",
4  "reference": "X-123456-N11",
5  "card_product_id": "pro_7syjig3jq3mezlc3vjrdpfitl4",
6  "display_name": "John Smith",
7  "is_single_use": true,
8  "activate_card": true
9}


1{
2  "id": "crd_fa6psq242dcd6fdn5gifcq1491",
3  "display_name": "John Smith",
4  "last_four": 1234,
5  "expiry_month": 5,
6  "expiry_year": 2025,
7  "billing_currency": "GBP",
8  "issuing_country": "GB",
9  "reference": "X-123456-N11",
10  "created_date": "2019-09-10T10:11:12Z",
11  "_links": {
12    "self": {
13      "href": "https://api.sandbox.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491"
14    },
15    "credentials": {
16      "href": "https://api.sandbox.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/credentials"
17    },
18    "revoke": {
19      "href": "https://api.sandbox.checkout.com/issuing/cards/crd_fa6psq42dcdd6fdn5gifcq1491/revoke"
20    }
21  }
22}

Note

If you receive a card_product_required response error, you may have more than one card product configured in your account. You'll need to provide a card_product_id value in your request, which you can find in the Dashboard under Issuing > Card products.

For security purposes, the card's credentials are not returned in the response.

Make a note of the card id value in the response. You'll need this to simulate an authorization in the next step.

Perform an authorization request with the newly issued card.

Pass the card id returned in the previous response to the card.id field.

post

https://api.sandbox.checkout.com/issuing/simulate/authorizations


1{
2  "card": {
3    "id": "crd_fa6psq242dcd6fdn5gifcq1491",
4    "expiry_month": 5,
5    "expiry_year": 2025
6  },
7  "transaction": {
8    "type": "purchase",
9    "amount": 2500,
10    "currency": "GBP"
11  }
12}


1{
2  "id": "trx_3vs4p7sagwlu3ejw7gkrssj2s4",
3  "status": "Authorized"
4}

Information

If you've configured the authorization relay service on your account, you'll be able to approve or decline the incoming authorization request synchronously.

If the authorization was successful, the response will include "status": "Authorized". Single-use cards are automatically revoked after a single successful authorization.

If the authorization was unsuccessful, the response will include "status": "Declined". Authorization may fail due to insufficient funds in your issuing balance, or spending controls configured in your account.

Make a note of the transaction id value in the response. You'll need this to simulate clearing the authorization in the next step.

If the authorization request was successful, you can simulate clearing the authorization.

Call the following endpoint with the transaction id returned in the previous response.

post

https://api.sandbox.checkout.com/issuing/simulate/authorizations/{id}/presentments


1{
2  "amount": 2500
3}

When you clear the authorization, the transaction status will be updated in the Dashboard. To view the transaction timeline, go to Issuing > Transactions and select the transaction.

Simulate a transaction

Test other transaction flows in the sandbox environment, including incremental authorizations and reversals.

Manage cards

Learn how to activate, suspend, or revoke a card you've issued.

Get started with Issuing

Information

Issue a card and perform a test transaction

Before you start

Step 1: Create a cardholder

Request example

Response example

Step 2: Issue a card to the cardholder

Request example

Response example

Note

Step 3: Simulate an authorization request

Request example

Response example

Information

Step 4: Simulate clearing the authorization

Request example

Next steps

Simulate a transaction

Manage cards