Our API Docs just got a new look!
GuidesAPI Reference

Subscriptions

Server2Server

The endpoints described in this solution are restricted for usage of PCI compliant merchants that can securely handle credit card information.

Subscription creation

The Server2Server solution can handle subscriptions, the integration should scope the endpoint v3/subscriptions and sending the subscription details within the subscription[] object such as:

  • start_date for when the charges should start (e.g.: 2025-07-23)

  • plan indicating the frequency with which the charges shoud occur (e.g.: MONTHLY)

  • plan_unit" indicating how many times the plan should be charged (e.g: 3)

  • auto_renewal indicating if the subscription should autorenew when it finishes.

curl -L \
  --request POST \
  --url 'https://cc-api-stg.directa24.com/v3/subscriptions' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-23T13:15:37.549Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "INV123456",
    "amount": 70,
    "currency": "BRL",
    "country": "BR",
    "payer": {
      "id": "PAYER123",
      "document": 123456789,
      "document_type": "CPF",
      "email": "[email protected]",
      "first_name": "Roberto",
      "last_name": "Carlos"
    },
    "description": "Premium Subscription",
    "subscription": {
      "start_date": "2025-07-23",
      "plan": "MONTHLY",
      "plan_unit": 3,
      "auto_renewal": false
    },
    "credit_card": {
      "cvv": "123",
      "card_number": "4111111111111111",
      "expiration_month": "12",
      "expiration_year": "25",
      "holder_name": "John Doe"
    },
    "client_ip": "192.168.1.1",
    "back_url": "https://example.com/back",
    "success_url": "https://example.com/success",
    "error_url": "https://example.com/error",
    "notification_url": "https://example.com/notify"
  }'

You will receive the identifier of the created subscription (subscription_id) as a response.

Response of the Server2Server subscription endpoint
{
  "subscription_id": 358
}

We will take care of doing all the subsequent charges based on the subscription[] information provided.

You will receive webhook notifications each time that a deposit was charged in concept of a subscription, in order for you to retrieve the status and matching it to the subscription_id :

Example webhook notification
{
    "deposit_id": 3000000001
}

For more information regarding webhooks, visit the API Reference.

Retrieve the deposit status

When you retrieve the status of a deposit, you will know to which subscription_id correspond.

Example response deposit status retrieve with subscription_id
{
  "user_id": "11",
  "deposit_id": 3000000001,
  "subscription_id":358,
  "invoice_id": "989409592",
  "country": "BR",
  "currency": "BRL",
  "local_amount": 70,
  "usd_amount": 12.60,
  "bonus_amount": 00.00,
  "bonus_relative": false,
  "payment_method": "VI",
  "payment_type": "CREDIT_CARD",
  "status": "COMPLETED",
  "payer": {
    "id": "PAYER123",
    "document": 123456789,
    "document_type": "CPF",
    "email": "[email protected]",
    "first_name": "Roberto",
    "last_name": "Carlos"
  },
  "fee_amount": 2.5,
  "fee_currency": "USD",
  "refunded": false,
  "current_payer_verification": "UNMATCHED",
  "card_detail": {
    "card_holder": "Roberto Carlos",
    "brand": "Visa",
    "masked_card": "4111 11** **** 1111",
    "expiration": "2025-12",
    "card_type": "CREDIT",
    "transaction_result": "Transaction Approved"
  }
}

For more information regarding deposit status retrieval, visit the API Reference.

Retrieve the Subscription details

You can then retrieve the status of the subscription with the subscription_id for further details.

{
  "id": 219,
  "status": "PENDING",
  "start_date": "2025-07-23",
  "end_date": "2025-10-23",
  "last_renovation_date": null,
  "creation_date": "2025-07-23T13:15:37.54",
  "subscription_plan": "MONTHLY",
  "plan_unit": 3,
  "amount": 70,
  "auto_renewal": false,
  "last_modified_date": "2025-07-23T13:15:37.54",
  "renewals": 0,
  "cancellation_date": null,
  "currency": "BRL",
  "last_charge_date": "2020-10-03",
  "payment_method": "VI",
  "invoice_id": "INV123456",
  "error_url": "https://example.com/error",
  "success_url": "https://example.com/success",
  "back_url": "https://example.com/back",
  "description": "Premium Subscription",
  "country": "BR",
  "deposits": [
    {
      "deposit_id": "3000000001",
      "status": "COMPLETED"
    }
  ]
}

For more information regarding the Subscription details endpoint, visit the API Reference.

Reattempts logic

Note that if by any means, a deposit within a subscription fails, in the spirit of maximizing the success scenario we will reattempt the transaction twice. One attempt each subsequent day will be performed.

Server2Server with an external billing engine

The endpoints described in this solution are restricted for usage of PCI compliant merchants that can securely handle credit card information.

Tokenize the customer's card

Our card-on-file API lets you securely store customer payment information and charge recurring payments without handling sensitive card data after the initial tokenization.

  1. Collect the customer's card information securely via your PCI-compliant form

  2. Call our card-on-file API to store the card

  3. Receive a card_identifier token that represents the stored card

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"
}

Create a subscription

  1. Associate the card_identifier with your internal subscription record

  2. Generate a unique external_subscription_id in your system

  3. Store both identifiers for future transactions

Process recurring charges

When it's time to charge the customer:

  1. Call our Server2Server deposit endpoint

  2. Instead of sending full card details, send:

    • The card_identifier token

    • Your external_subscription_id

Example request Server2Server with an external billing engine
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",
     "external_subscription_id": "ABC1234",
    "client_ip": "123.123.123.123"
  }'

Subscription endpoints

Note that as this solution handles all the subscription on the merchant's end, no subscription entity is created on our end. Therefore the subscription endpoints should be used.

OneShot

Subscription creation

The OneShot solution can handle subscriptions, the integration should scope the endpoint v3/subscriptions and sending the subscription details within the subscription[] object such as:

  • start_date for when the charges should start (e.g.: 2025-07-23)

  • plan indicating the frequency with which the charges shoud occur (e.g.: MONTHLY)

  • plan_unit" indicating how many times the plan should be charged (e.g: 3)

  • auto_renewal indicating if the subscription should auto-renew when it finishes.

Example request OneShot for Subscriptions
curl -L \
  --request POST \
  --url 'https://api-stg.directa24.com/v3/subscriptions' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-07-24T13:44:21.195Z' \
  --header 'X-Login: text' \
  --header 'Authorization: text' \
  --data '{
    "invoice_id": "INV123456",
    "amount": 50,
    "currency": "BRL",
    "country": "BR",
    "payer": {
      "id": "PAYER123",
      "document": 123456789,
      "document_type": "CPF",
      "email": "[email protected]",
      "first_name": "Roberto",
      "last_name": "Carlos"
    },
    "description": "Premium Subscription",
    "subscription": {
      "start_date": "2025-01-01",
      "plan": "MONTHLY",
      "plan_unit": 1,
      "auto_renewal": false
    },
    "client_ip": "192.168.1.1",
    "back_url": "https://example.com/back",
    "success_url": "https://example.com/success",
    "error_url": "https://example.com/error",
    "notification_url": "https://example.com/notify"
  }'

We will take care of doing all the subsequent charges based on the subscription[] information provided.

In the response you will receive:

  • the subscription_id

  • the redirect_url containing the credit card form for the user to input their card details.

Example response subscriptions OneShot 
{
  "subscription_id": 358,
  "redirect_url": "https://checkout.cc-stg.checkoutogate.net/validate/6mIsesbbmvYn2hzAOwuYQSMAYIyISUgl?subscriptionId=513",
  "expiration_date": "2025-03-06 15:58:02",
  "payment_amount": 50,
  "redirect": true
}

Note that we will perform micro deposit charges to the card prior accepting it as. payment method for the subscription billing.

Webhook notifications will be sent each time that changes occured within a deposit, such as status changes to completed, in order for you to retrieve the status and matching it to the subscription_id :

Example webhook notification
{
    "deposit_id": 3000000001
}

For more information regarding webhooks, visit the API Reference.

Retrieve the deposit status

When you retrieve the status of a deposit, you will know to which subscription_id correspond.

Example response deposit status retrieve with subscription_id
{
  "user_id": "11",
  "deposit_id": 3000000001,
  "subscription_id":358,
  "invoice_id": "989409592",
  "country": "BR",
  "currency": "BRL",
  "local_amount": 50,
  "usd_amount": 12.60,
  "bonus_amount": 00.00,
  "bonus_relative": false,
  "payment_method": "VI",
  "payment_type": "CREDIT_CARD",
  "status": "COMPLETED",
  "payer": {
    "id": "PAYER123",
    "document": 123456789,
    "document_type": "CPF",
    "email": "[email protected]",
    "first_name": "Roberto",
    "last_name": "Carlos"
  },
  "fee_amount": 2.5,
  "fee_currency": "USD",
  "refunded": false,
  "current_payer_verification": "UNMATCHED",
  "card_detail": {
    "card_holder": "Roberto Carlos",
    "brand": "Visa",
    "masked_card": "4111 11** **** 1111",
    "expiration": "2025-12",
    "card_type": "CREDIT",
    "transaction_result": "Transaction Approved"
  }
}

For more information regarding deposit status retrieval, visit the API Reference.

Retrieve the Subscription details

You can then retrieve the status of the subscription with the subscription_id for further details.

{
  "id": 219,
  "status": "PENDING",
  "start_date": "2025-07-23",
  "end_date": "2025-10-23",
  "last_renovation_date": null,
  "creation_date": "2025-07-23T13:15:37.54",
  "subscription_plan": "MONTHLY",
  "plan_unit": 3,
  "amount": 70,
  "auto_renewal": false,
  "last_modified_date": "2025-07-23T13:15:37.54",
  "renewals": 0,
  "cancellation_date": null,
  "currency": "BRL",
  "last_charge_date": "2020-10-03",
  "payment_method": "VI",
  "invoice_id": "INV123456",
  "error_url": "https://example.com/error",
  "success_url": "https://example.com/success",
  "back_url": "https://example.com/back",
  "description": "Premium Subscription",
  "country": "BR",
  "deposits": [
    {
      "deposit_id": "3000000001",
      "status": "COMPLETED"
    }
  ]
}

For more information regarding the Subscription details endpoint, visit the API Reference.

Reattempts logic

Note that if by any means, a deposit within a subscription fails, in the spirit of maximizing the success scenario we will reattempt the transaction twice. One attempt each subsequent day will be performed.

PreviousCard-on-fileNextBank transfers and cash vouchers

Last updated

Was this helpful?