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)
- Note that when the start_date is within the same day that the subscription is being created, the first charge will be created immediately.
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.onekeypayments.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.

Collect the customer's card information securely via your PCI-compliant form
Call our card-on-file API to store the card
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

Associate the card_identifier with your internal subscription record
Generate a unique external_subscription_id in your system
Store both identifiers for future transactions

Process recurring charges

When it's time to charge the customer:

Call our Server2Server deposit endpoint
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.onekeypayments.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 with card-on-file

Subscription creation

The OneShot solution can create subscriptions in cards that were previously stored on file.

Note that this subscription flow has a pre-requisite to have a card stored on file. Please visit Card-on-file section to explore the ways in which this can be done.

The integration should scope the endpoint v3/subscriptions , while sending the card_identifier and the subscription details within the subscription[] object such as:

start_date for when the charges should start (e.g.: 2025-07-23)
- Note that when the start_date is within the same day that the subscription is being created, the first charge will be created immediately.
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://api-stg.onekeypayments.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
    },
    
,
    "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

OneShot with redirect

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)
- Note that when the start_date is within the same day that the subscription is being created, the first charge will be created immediately.
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.onekeypayments.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

PreviousCard-on-file NextBank transfers and cash vouchers

Last updated 3 months ago

Was this helpful?

hashtagSubscription creation

hashtagRetrieve the deposit status

hashtagRetrieve the Subscription details

hashtagReattempts logic

hashtagTokenize the customer's card

hashtagCreate a subscription

hashtagProcess recurring charges

hashtagSubscription endpoints

hashtagSubscription creation

hashtagRetrieve the deposit status

hashtagRetrieve the Subscription details

hashtagReattempts logic

hashtagSubscription creation

hashtagRetrieve the deposit status

hashtagRetrieve the Subscription details

hashtagReattempts logic

Subscription creation

Retrieve the deposit status

Retrieve the Subscription details

Reattempts logic

Tokenize the customer's card

Create a subscription

Process recurring charges

Subscription endpoints

Subscription creation

Retrieve the deposit status

Retrieve the Subscription details

Reattempts logic

Subscription creation

Retrieve the deposit status

Retrieve the Subscription details

Reattempts logic