Skip to main content

Charge a Card

Streamline card transactions with a secure, proxy-powered solution.

Charging a card involves finalizing the transaction by requesting approval from the card networks and issuers to transfer funds. In checkout flows, this operation typically constitutes a Customer-Initiated Transaction (CIT), where the cardholder actively authorizes the payment. Properly flagged CITs help issuers distinguish these transactions from merchant-initiated ones, often leading to higher approval rates and a smoother payment experience.

Charge a Card Diagram

This guide will show you how to use the Proxy to charge a card with your chosen Payment Service Provider (PSP) while offloading PCI compliance scope with ease. We’ll explore a variety of processor-specific standards and their unique verification quirks, offering practical examples you can adapt to your selected PSP.

If you are not yet collecting your customers' cards with Basis Theory, here are a few guides you can explore:

Getting Started​

To get started, you will need to create a Basis Theory Account and a TEST Tenant.

Make sure to use your work email (e.g., john.doe@yourcompany.com)

Private Application​

You will need a Private Application to allow your backend to call Basis Theory APIs. Click here to create one using the Basis Theory Customer Portal.

This will create an application with the following Access Controls:

  • Permissions: token:use, token:create
Save the API Key from the created Private Application as it will be used later in this guide.

First Charge​

Payment service providers (PSPs) may differ in how they handle this operation, offering workflows like "authorization and capture" or "direct charge." Understanding these variations allows merchants to optimize the process for efficiency and reliability, ensuring seamless processing in multi-psp scenarios and consistent fund settlement.

Given you have previously created a Token Intent:

Token Intent sample
{
  "id": "d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4",
  "type": "card",
  "tenant_id": "4aee08b9-5557-474b-a120-252e01fc7b0f",
  "fingerprint": "BKJYqf2tcvhTHSXN7EvBJLviN3PBYRgwoJgce8VAfnSr",
  "card": {
    "bin": "424242",
    "last4": "4242",
    "expiration_month": 10,
    "expiration_year": 2028,
    "brand": "visa",
    "funding": "credit",
    "authentication": "sca_required",
    "issuer_country": {
      "alpha2": "GB",
      "name": "UNITED KINGDOM OF GREAT BRITAIN AND NORTHERN IRELAND",
      "numeric": "826"
    }
  },
  "created_by": "0bc89db5-fadd-4d57-af93-10472e35ebd3",
  "created_at": "2025-03-10T14:23:56.5580574+00:00",
  "expires_at": "2025-03-11T14:23:56.5580575+00:00"
}

Here is how you can leverage the Ephemeral Proxy, a tool that transparently performs detokenization, to share the sensitive cardholder data to the Payments Processor or Acquirer API.

In Checkout.com, you can charge a card by calling the /payments API.

Request a Payment
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <PRIVATE_API_KEY>' \
-H 'BT-PROXY-URL: https://api.sandbox.checkout.com/payments' \
-H 'Authorization: Bearer <CHECKOUT_SECRET_KEY>' \
-H 'Content-Type: application/json' \
--data '{
  "source": {
    "type": "card",
    "number": "{{ token_intent: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data.number\" }}",
    "expiry_month": "{{ token_intent: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"MM\" }}",
    "expiry_year": "{{ token_intent: d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4 | json: \"$.data\" | card_exp: \"YYYY\" }}",
    "cvv": "{{ token_intent: d96b9925-85d7-495e-88fe-a9c3ecb23b61 | json: \"$.data.cvc\" }}",
    "store_for_future_use": true
  },
  "amount": 1000,
  "currency": "USD",
  "processing_channel_id": "pc_svyx12xvaaduraq3ckb2gwnvzq"
}'
Payment Response
{
  "id": "pay_myvj6zxrt45edgrswrliyxbtnq",
  "approved": true,
  "status": "Authorized",
  "amount": 1000,
  "currency": "USD",
  "source": {
    "type": "card",
    "id": "src_gguer4xlawke3ctljczft7573a",
    ...
  },
  "scheme_id": "647537243670773",
  ...
}
You are not restricted to the Payment Processors listed above. As long as your partner can accept cards through an API endpoint, you can invoke it using the Ephemeral Proxy.

We are working to add more full-featured processor-specific examples. Please refer to Proxy examples for more request samples.

Don't hesitate to contact us if you need assistance with performing card transactions against a specific processor.

Save a Card​

Once a card has been processed for the first time, merchants can store details in the long-term for future use and enable express checkouts, repeat transactions for subscription services, recurring payments and consumption-based charges. Merchants are responsible for obtaining explicit customer consent before saving card details, ensuring compliance with data protection regulations and fostering trust.

To do that, we can convert the Token Intent into a Token, by calling the Create Token API and passing the token_intent_id.

Create Token
curl "https://api.basistheory.com/tokens" \
  -H "BT-API-KEY: <PRIVATE_API_KEY>" \
  -H "Content-Type: application/json" \
  -X "POST" \
  -d '{
    "token_intent_id": "d2cbc1b4-5c3a-45a3-9ee2-392a1c475ab4"
  }'

This operation returns a new or existing persistent Token depending on your fingerprinting and deduplication options:

Token sample
{
  "id": "1cd9c8bf-99fd-4784-ba69-68b15b301019",
  "tenant_id": "74eca6ab-f94d-49bc-9f3c-6144eb3415ac",
  "type": "card",
  "card": {
    "bin": "42424242",
    "brand": "visa",
    "last4": "4242",
    "expiration_month": 12,
    "expiration_year": 2025,
    "funding": "credit",
    "authentication": "sca_required"
  },
  "fingerprint": "BKJYqf2tcvhTHSXN7EvBJLviN3PBYRgwoJgce8VAfnSr",
  "_extras": {
    "deduplicated": false
  },
  ...
}
Click here to learn more about the token conversion behavior.

What you should store in your database:

  1. (Required) The token id, associating it with the rightful customer account.
  2. The card details (brand, last4, expiration_month, and expiration_year) if your plan to use it for things like rendering a stored card to your customer.
  3. The Processor Token if you plan to directly charge that card with the Processor (without going through Basis Theory Proxy).
  4. The Network Transaction identifier returned by the processor during the initial transaction;
    • This allows you to seamlessly charge the card with new processors or acquirers in the future and achieve the best approval rates.
    • Refer to your current processor’s documentation or support for guidance on accessing this value.

Subsequent Charges​

Once you've securely saved a card in the vault and generated a persistent token, you are ready to perform subsequent charges. Whether you have returning customers purchasing with a saved card, or you are performing recurring billing, the token allows you to process payments seamlessly without storing sensitive card details directly in your system.

If your business or payment processor needs it due to risk preferences, click here to find out how to recollect the CVC for a saved card.

Using the PAN​

If you charged or verified a card used a different acquirer than the one required for subsequent charges, we recommend using this method, which relies on the Basis Theory Proxy to securely route tokenized cardholder data to the payment processor.

In Checkout.com, you can charge a saved card by calling the /payments API.

Pass the Network Transaction identifier of the first charge into the previous_payment_id field.

Request a Payment
curl 'https://api.basistheory.com/proxy' \
-X 'POST' \
-H 'BT-API-KEY: <PRIVATE_API_KEY>' \
-H 'BT-PROXY-URL: https://api.sandbox.checkout.com/payments' \
-H 'Authorization: Bearer <CHECKOUT_SECRET_KEY>' \
-H 'Content-Type: application/json' \
--data '{
  "source": {
    "type": "card",
    "number": "{{ token: 1cd9c8bf-99fd-4784-ba69-68b15b301019 | json: \"$.data.number\" }}",
    "expiry_month": "{{ token: 1cd9c8bf-99fd-4784-ba69-68b15b301019 | json: \"$.data\" | card_exp: \"MM\" }}",
    "expiry_year": "{{ token: 1cd9c8bf-99fd-4784-ba69-68b15b301019 | json: \"$.data\" | card_exp: \"YYYY\" }}",
    "stored": true
  },
  "amount": 1000,
  "currency": "USD",
  "processing_channel_id": "pc_svyx12xvaaduraq3ckb2gwnvzq",
  "previous_payment_id": "<first_network_transaction_identifier>"
}'
Payment Response
{
  "id": "pay_myvj6zxrt45edgrswrliyxbtnq",
  "approved": true,
  "status": "Authorized",
  "amount": 1000,
  "currency": "USD",
  "source": {
    "type": "card",
    "id": "src_gguer4xlawke3ctljczft7573a",
    ...
  },
  "scheme_id": "647537243670773",
  ...
}
You are not restricted to the Payment Processors listed above. As long as your partner can accept cards through an API endpoint, you can invoke it using the Ephemeral Proxy.

We are working to add more full-featured processor-specific examples. Please refer to Proxy examples for more request samples.

Don't hesitate to contact us if you need assistance with performing card transactions against a specific processor.

Using the Processor Token​

If you have already charged or verified a card using a payments processor and saved its token, we recommend using this method, which doesn't require going through Basis Theory.

In Checkout.com, you can charge a saved card by calling the /payments API.

Request a Payment
curl 'https://api.sandbox.checkout.com/payments' \
-X 'POST' \
-H 'Authorization: Bearer <CHECKOUT_SECRET_KEY>' \
-H 'Content-Type: application/json' \
--data '{
  "source": {
    "type": "id",
    "id": "src_gguer4xlawke3ctljczft7573a",
  },
  "amount": 1000,
  "currency": "USD",
  "processing_channel_id": "pc_svyx12xvaaduraq3ckb2gwnvzq"
}'
Payment Response
{
  "id": "pay_myvj6zxrt45edgrswrliyxbtnq",
  "approved": true,
  "status": "Authorized",
  "amount": 1000,
  "currency": "USD",
  "source": {
    "type": "card",
    "id": "src_gguer4xlawke3ctljczft7573a",
    ...
  },
  "scheme_id": "647537243670773",
  ...
}