Our API Docs just got a new look!
GuidesAPI Reference

Card-on-file

Server2Server with additional card-on-file integration

PCI Compliant merchants willing to stored their client´s cards on D24´s vault, have to generate a request to our API for storing cards.

Visit the API Reference for more information on card-on-file API. Saving card Card-on-file API allows merchants to create, retrieve and delete card tokens. form D24 Vault.

Example request to card-on-file API
 curl -L \
  --request POST \
  --url 'https://cc-api-stg.directa24.com/v3/tokenization' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-22T19:04:34.730Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "credit_card": {
      "holder_name": "Luis Perez",
      "expiration_month": 10,
      "expiration_year": 2028,
      "number": "4111111111111111",
      "cvv": "123"
    },
    "payer": {
      "country": "BR",
      "first_name": "John",
      "last_name": "Smith",
      "document_type": "CPF",
      "document": "84932568207"
    },
    "micro_deposit_enabled": false
  }'

micro_deposit_enabled parameter

This parameter allows you to create a small amount transaction on the card (which is immediately refunded) prior storing it. This can be a done as a mechanism for only storing valid cards. Note that if the microdeposit fails, the card won't be stored.

Example response of card-on-file API
{
  "holder_name": "Luis Perez",
  "expiration_month": 10,
  "expiration_year": 2028,
  "last_four_digits": "1111",
  "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0"
}

In the response you will receive the card_identifier parameter, which later can be used for creating transactions on that client's card.

Example request of Server2Server with card_identifier
curl -L \
  --request POST \
  --url 'https://cc-api-stg.directa24.com/v3/deposits' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Smith"
    },
    "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0",
    "client_ip": "123.123.123.123"
  }'
Server2Server saving the card used in the deposit

Merchants using our Server2Server solution can opt to save the card used within the deposit request.

In order to do so, they can send the parameter tokenize_card with value true in the deposit request.

Server2Server example request with tokenize_card
curl -L \
  --request POST \
  --url 'https://cc-api-stg.directa24.com/v3/deposits' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Smith"
    },
    "credit_card": {
      "cvv": "123",
      "number": "4111111111111111",
      "expiration_month": "10",
      "expiration_year": "25",
      "holder_name": "JOHN SMITH"
    },
    "tokenize_card":true,
    "client_ip": "123.123.123.123"
  }'

In the synchronous response you will receive the card_identifier generated for that card.

Example response with the card_identifier
{
  "deposit_id": 300604089,
  "user_id": "80000001",
  "merchant_invoice_id": "800000001",
  "payment_info": {
    "type": "CREDIT_CARD",
    "result": "SUCCESS",
    "payment_method": "VI",
    "payment_method_name": "Visa",
    "amount": 1000,
    "currency": "BRL",
    "created_at": "2025-07-15T12:57:14.936Z"
  },
  "card_identifier": "d0d9207b-395e-4742-95bc-66d4caf1037a"
}
Example request of Server2Server with card_identifier
curl -L \
  --request POST \
  --url 'https://cc-api-stg.directa24.com/v3/deposits' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Smith"
    },
    "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0",
    "client_ip": "123.123.123.123"
  }'
Fragments Lite

Merchants using our Fragments Lite solution can opt to save the card used within the deposit request.

In order to do so, they can send the parameter tokenize_card with value true in the deposit request. In the response they will receive the card_identifier which can be used for creating subsequent charges on that user's card.

Example request Fragments Lite with tokenize_card
curl -L \
  --request POST \
  --url 'https://cc-api-stg.directa24.com/v3/deposits' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Smith"
    },
    "card_token": "C4RD_T0K3N_G3N3R4T3D_W1TH_FR4GM3N7S_L1T3",
    "tokenize_card": true,
    "client_ip": "123.123.123.123"
  }'
Example response with the card_identifier
{
  "deposit_id": 300604089,
  "user_id": "80000001",
  "merchant_invoice_id": "800000001",
  "payment_info": {
    "type": "CREDIT_CARD",
    "result": "SUCCESS",
    "payment_method": "VI",
    "payment_method_name": "Visa",
    "amount": 1000,
    "currency": "BRL",
    "created_at": "2025-07-15T12:57:14.936Z"
  },
  "card_identifier": "d0d9207b-395e-4742-95bc-66d4caf1037a"
}
Example request of Fragments Lite with card_identifier
curl -L \
  --request POST \
  --url 'https://cc-api-stg.directa24.com/v3/deposits' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-15T12:57:14.936Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
      "id": "11111",
      "document": "84932568207",
      "document_type": "CPF",
      "email": "[email protected]",
      "first_name": "John",
      "last_name": "Smith"
    },
    "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0",
    "client_ip": "123.123.123.123"
  }'
Fragments all-in-one

To implement card-on-file with the Fragments all-in-one, follow the same client-side flow as described for the OneShot solution below. The distinction for card-on-file is handled on the backend.

OneShot

Merchants willing to use our OneShot solution can also make use of card-on-file for generating deposits on their clients' cards.

The parameter tokenize_card should be sent in the deposit request as true.

Example OneShot request
curl -L \
  --request POST \
  --url 'https://api-stg.directa24.com/v3/deposits' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-17T13:13:15.442Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "MX",
    "currency": "MXN",
    "payer": {
        "id": "11",
        "document": "CURP4321TEST",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "email": "[email protected]"
    },
    "payment_method": "CC",
    "tokenize_card":true,
    "client_ip": "123.123.123.123",
    "back_url": "https://www.mercahnt.com/deposit_cancelled",
    "success_url": "https://www.merchant.com/deposit_completed",
    "error_url": "https://www.merchant.com/deposit_error",
    "notification_url": "https://www.d24.com/d24/notify"
    "logo": "https://www.merchant.com/merchant-logo.png",
}'

After the deposit is completed by the user you will receive a webhook notifying that the deposit status changed. When retrieving the deposit status you will obtain the card_identifier.

Response of the status retrieve endpoint
{
  "user_id": "11",
  "deposit_id": 300004285,
  "invoice_id": "1000000001",
  "country": "MX",
  "currency": "MXN",
  "local_amount": 1000,
  "usd_amount": 53.22,
  "bonus_amount": 00.00,
  "bonus_relative": false,
  "payment_method": "VI",
  "payment_type": "CREDIT_CARD",
  "status": "COMPLETED",
  "payer": {
    "document": "CURP4321TEST",
    "document_type": "CPF",
    "email": "[email protected]",
    "first_name": "Ricardo",
    "last_name": "Carlos"
  },
  "fee_amount": 2.5,
  "fee_currency": "USD",
  "refunded": false,
  "current_payer_verification": "UNMATCHED",
  "card_detail": {
    "card_holder": "Ricardo Carlos",
    "brand": "Visa",
    "masked_card": "1234 56** **** 6789",
    "expiration": "2028-12",
    "card_type": "DEBIT",
    "transaction_result": "Transaction Approved",
    "authorization_code": "000000",
    "card_identifier": "d0d9207b-395e-4742-95bc-66d4caf1037a"
  }
}

The card_identifier :

  • is the token associated to the card that the user selected to pay.

  • it can be used unlimited times, until the card expires.

For creating deposits with the card_identifier, you just need to include it in the deposit request.

Example request OneShot with card_identifier
curl -L \
  --request POST \
  --url 'https://api-stg.directa24.com/v3/deposits' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-17T13:13:15.442Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id" : "1000000001",
    "amount": "1000",
    "country": "MX",
    "currency": "MXN",
    "payer": {
        "id": "11",
        "document": "CURP4321TEST",
        "first_name": "Ricardo",
        "last_name": "Carlos",
        "email": "[email protected]"
    },
    "payment_method": "CC",
    "card_identifier": "CID-2210908e-6d8e-468d-9eb3-d551e8b541a0",
    "client_ip": "123.123.123.123",
    "back_url": "https://www.mercahnt.com/deposit_cancelled",
    "success_url": "https://www.merchant.com/deposit_completed",
    "error_url": "https://www.merchant.com/deposit_error",
    "notification_url": "https://www.d24.com/d24/notify"
    "logo": "https://www.merchant.com/merchant-logo.png",
}'

As a response you will directly receive the final status of the payment. You can also retrieve the additional details by using the deposit status endpoint.

Example response OneShot with card_identifier
{
  "deposit_id": 1324874939,
  "payment_status": "APPROVED",
  "success": true
}
PreviousInstallmentsNextSubscriptions

Last updated

Was this helpful?