Subscriptions Endpoint

Learn how to use the Subscriptions endpoint to create recurring payments with cards.

Subscription API Requests

A request made through the Subscription API allows you to charge the users a recurring amount on their cards, either by sending the Card Details on the request if you are PCI Compliant or by redirecting the user to our hosted payment page where we will collect the card details allowing you to remain PCI Compliant.

When the credit_card object is sent, the transaction is confirmed (or denied) synchronously, therefore you can continue the payment flow on your page transparently. With the Hosted Checkout, we send you a webhook once the user completes the payment.

PCI Compliant Subscriptions Endpoint

The usage of this endpoint with the credit_card object is restricted to PCI Compliant merchants* who have shared their PCI AOC certificate with their Account Manager.

Subscription creation

POST https://cc-api-stg.directa24.com/v3/subscriptions

This endpoint allows you to generate recurring cards transactions by sending the card details and the recurring options

Headers

NameTypeDescription

Content-Type*

string

application/json

X-Date*

string

ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ

X-Login*

string

Merchant X-Login API Key

Authorization*

string

Authorization control hash

X-Idempotency-Key

string

Unique idempotency key

Request Body

NameTypeDescription

country*

string

Country of the transaction

amount*

number

Amount of the transaction

currency*

string

Currency of the amount specified

invoice_id*

string

Unique deposit ID on the merchant end

payer*

object

Object containing details about the customer. See "Payer object" section for details

credit_card*

object

Object containing the credit card details

description

string

Descriptor for the transaction

client_ip*

string

Valid IPv4/v6 Address of the customer

device_id

string

Unique customer's device ID created using our JS library

fee_on_payer

boolean

Used to specify if you want to let the customer assume the deposit fee

subscription*

object

Object containing the details of the subscription

{
  "deposit_id": 300604089,
  "user_id": "80000001",
  "merchant_invoice_id": "test766106146",
  "payment_info": {
      "type": "CREDIT_CARD",
      "result": "SUCCESS",
      "payment_method": "AE",
      "payment_method_name": "American Express",
      "amount": 505.95,
      "currency": "MXN",
      "created_at": "2021-02-05 22:10:45"
  }
}

Request Example with Card Details

Subscription API
{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11111",
        "document": "84932568207",
        "email": "johnSmith12@hotmail.com",
        "first_name": "John",
        "last_name": "Smith",
        "address": {
            "street": "Calle 13",
            "city": "bahia",
            "state": "SP",
            "zip_code": "12345-678"
        }
    },
    "credit_card": {
        "cvv": "123",
        "card_number": "4111111111111111",
        "expiration_month": "10",
        "expiration_year": "25",
        "holder_name": "JOHN SMITH"
    },
    "subscription": {
        "start_date": "2023-04-12",
        "plan": "MONTHLY",
        "plan_unit": 3,
        "auto_renewal": false
    },
    "description": "Monthly subscription. Pack premium",
    "client_ip": "123.123.123.123",
    "device_id": "knakvuejffkiebyab",
    "fee_on_payer": false
}

Redirect Subscriptions Endpoint

Subscription creation

POST https://api-stg.directa24.com/v3/subscriptions

This endpoint allows you to generate recurring cards transactions by sending the recurring options, and avoiding the card details.

Headers

NameTypeDescription

Content-Type*

string

application/json

X-Date*

string

ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ

X-Login*

string

Merchant X-Login API Key

Authorization*

string

Authorization control hash

X-Idempotency-Key

string

Unique idempotency key

Request Body

NameTypeDescription

country*

string

Country of the transaction

amount*

number

Amount of the transaction

currency*

string

Currency of the amount specified

invoice_id*

string

Unique deposit ID on the merchant end

payer*

object

Object containing details about the customer. See "Payer object" section for details

description

string

Descriptor for the transaction

client_ip*

string

Valid IPv4/v6 Address of the customer

device_id

string

Unique customer's device ID created using our JS library

fee_on_payer

boolean

Used to specify if you want to let the customer assume the deposit fee

subscription*

object

Object containing the details of the subscription

{
  "deposit_id": 300604089,
  "user_id": "80000001",
  "merchant_invoice_id": "test766106146",
  "payment_info": {
      "type": "CREDIT_CARD",
      "result": "SUCCESS",
      "payment_method": "AE",
      "payment_method_name": "American Express",
      "amount": 505.95,
      "currency": "MXN",
      "created_at": "2021-02-05 22:10:45"
  }
}

Request Example without Card Details

Subscription API
{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11111",
        "document": "84932568207",
        "email": "johnSmith12@hotmail.com",
        "first_name": "John",
        "last_name": "Smith",
        "address": {
            "street": "Calle 13",
            "city": "bahia",
            "state": "SP",
            "zip_code": "12345-678"
        }
    },
    "subscription": {
        "start_date": "2023-04-12",
        "plan": "MONTHLY",
        "plan_unit": 3,
        "auto_renewal": false
    },
    "notification_url": "https://webhook.site/token",  "
    "description": "Monthly subscription. Pack premium",
    "client_ip": "123.123.123.123",
    "device_id": "knakvuejffkiebyab",
    "fee_on_payer": false
}
User Journey after redirection

Users will see our hosted payment page where they will be capable of filling in their card details to create the subscription.

Response Fields Details

Response Fields

Field nameFormatDescription

subscription_id

Integer

IF of the subscription generated on our ID. Store this ID for future reference

deposit_id

Integer

ID of the deposit generated on our end. Store this ID for future reference

user_id

String

ID of the user. If you didn't send it, it is generated by us

merchant_invoice_id

String

ID of the deposit on your end. If you didn't send it, it is generated by us

redirect_url

String

URL to redirect the user to our Hosted Checkout. Only shown if you didn't send the credit_card object

payment_info[]

Object

Object containing the information about the payment

payment_info.type

String

Type of transaction (Always CREDIT_CARD)

payment_info.result

String

Status of the transaction: [SUCCESS, REJECTED, PENDING]

payment_info.reason

String

Transaction result. Only shown in case of rejection

payment_info.reason_code

String

Code of the result. Only shown in case of rejection

payment_info.payment_method

String

Payment method code. See the list here.

payment_info.payment_method_name

String

Payment method name. See the list here.

payment_info.payment_method_supported

Array

An array of the card types supported. Only shown if you didn't send the credit_card object

payment_info.amount

Number

Amount sent to the card acquirer

payment_info.currency

String

Currency of the amount sent to the card acquirer

payment_info.created_at

String

Transaction date time

payment_info.expiration_date

String

Transaction expiration datetime

subscription_info[]

Object

Object containing information about the Subscription

subscription_info.payment_period

Number

Payment period with 0 meaning the initial payment

subscription_info.type

String

Type of subscription

subscription_info.start_date

String

Datetime in which the subscription started

subscription_info.end_date

String

Datetime in which the subscription ends

Error Response Fields Details

Response Fields

Field nameFormatDescription

code

Number

Error code. See the list of error codes

description

String

Description of the error

details[]

String

Details about the errors. It is shown in case of invalid details

type

String

Error code name. It is not always shown. See the list of error codes

Response Examples

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "payer.document: Invalid document type and/or document",
        "payer.address.state: Invalid State for Country"
    ]
}

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "amount: invalid numeric format",
        "country: Invalid value. Accepted values: AR|BR|CL|CM|CN|CO|EC|GH|IN|ID|KE|MY|MX|NG|PA|PE|PH|PY|TH|TZ|UG|UY|VN|ZA"
    ]
}

{
    "code": 502,
    "description": "Invalid request body",
    "type": "INVALID_REQUEST_BODY"
}

{
    "code": 304,
    "description": "The user limit has been exceeded",
    "type": "USER_LIMIT_EXCEEDED"
}

{
    "code": 201,
    "description": "Field validation error. Check details",
    "details": [
        "creditCard.cardNumber: size must be between 13 and 20, rejected value is 345678***********1090"
    ]
}

Status reasons

Along with every REJECTED transaction, we will provide you with a reason and a reason_code you can use to map the error codes on your end.

Transaction status

Reason code

Reason

REJECTED

EXTERNAL_HIGH_RISK

The card issuer rejected the payment because of their anti-fraud rules

REJECTED

TRX_NOT_SUPPORTED

Transaction type is not supported for acquirer

REJECTED

INVALID_CARD_NUMBER

Invalid credit card number

REJECTED

INVALID_CARD_HOLDER

Invalid card holder

REJECTED

INVALID_CARD_EXPIRATION

Invalid expiration date

REJECTED

INVALID_SECURITY_CODE

Invalid CVV/CVV2

REJECTED

INVALID_ISSUER

Invalid card issuer

REJECTED

INVALID_PIN

Invalid card pin

REJECTED

DUPLICATE_PAYMENT

Payment duplicated

REJECTED

MAX_ATTEMPTS_REACHED

Max attempts reached for this user and card

REJECTED

INSUFFICIENT_FUNDS

Insufficient funds

REJECTED

AUTHORIZATION_CALL_REQUIRED

The transaction was rejected because the user needs to call their bank to activate the card

REJECTED

CARD_BIN_NOT_FOUND

Credit card bin number not found

REJECTED

CARD_EXPIRED

Credit card expired

REJECTED

CARD_DECLINED

Card declined by issuer

REJECTED

CARD_REPORTED_STOLEN

Card reported as stolen

REJECTED

CARD_REPORTED_LOST

Card reported as lost

REJECTED

CARD_RESTRICTED_BY_BANK

The card was blocked by the bank

REJECTED

CARD_REQUESTED_BY_BANK

The card is requested by the bank

REJECTED

CARD_BLACKLISTED

Card blacklisted

REJECTED

CARD_DISABLED

Card disabled

REJECTED

OTHER_REASON

Generic rejection reason

Request Fields Description

Field nameFormatDescriptionDefaultValidationsRequired

country

string (length: 2)

Country code of the deposit in ISO 3166-1 alpha-2 code format

Yes

amount

decimal (max decimals: 2)

Deposit amount in the currency specified

Number of up to 18 integers and 2 decimals places

Yes

currency

string (length: 3)

Currency code of the amount in ISO 4217 format

USD

Yes

invoice_id

string (max length: 128)

Unique deposit ID on the merchant end

random string

^[A-Za-z0-9-_]*$

Yes

payer

object[]

Yes

credit_card

object[]

Yes

subscription

object[]

Yes

description

string (max length: 100)

Transaction description. It could be shown on the customers credit card extract

String of up to 100 characters

No

client_ip

string

Valid IPv4 or IPv6 Address

IPv4/v6 Address

Yes

device_id

string (max length: 100)

Unique customer's device ID created using our JS library. Used to identify and prevent fraud

String of up to 100 characters

No

fee_on_payer

boolean

Choose if the deposit's fee will be paid by the customer or debited from your balance

false

[true, false]

No

Request Objects

Subscription Object

Field nameFormatDescriptionRequired

start_date

ISO8601 Datetime with Timezone: yyyy-MM-dd'T'HH:mm:ssZ

Datetime that will start the subscription billing cycle.

Yes

plan

Value of enum: [MONTHLY, YEARLY]

Frequency of collections. It can be MONTHLY or YEARLY

Yes

plan_unit

integer

Amount of times that the subscription will be charged.

Yes

auto_renewal

boolean

Used to indicate if the subscription will auto-renovate after a complete billing cycle.

Yes

Credit Card Object

Field name

Format

Description

Validations

Required

cvv

String (max length: 4 digits)

Credit card CVV/CVV2 code

^\d{3,4}$

size must be between 3 and 4

Yes

card_number

String (max length: 16 digits)

The credit card number consisting of up to 16 digits

Yes

expiration_month

String(length: 2)

Credit card expiration month

^(1[0-2]|0[1-9]|[1-9])$

Yes

expiration_year

String(length: 2)

Credit card expiration year last two digits

^\d{2}$

Valid year: 25

Yes

holder_name

String (max length: 256)

The name of the credit card owner

Valid name

Yes

Payer Object

Field nameFormatDescriptionDefaultValidationsRequired

id

string (max length: 128)

Customer's ID generated on your end. Used to locate user's transaction on our Merchant Panel

If none is sent, we will autogenerate it

^[A-Za-z0-9]*$

Recommended

document

string (max length: 30)

Customer's document ID. Ensure it is correct and the user can't change it every time he/she deposits

Yes

document_type

string (max length: 10)

Customer's document type. Optional, if sent must be a valid document type

Yes

email

string (max length: 255)

Valid customer's email address

Valid email address

Yes

first_name

string (max length: 128)

Customer's first name

String of up to 128 characters

Yes

last_name

string (max length: 128)

Customer's last name

String of up to 128 characters

Yes

address

object[]

No

phone

string (max length: 32)

Valid customer's phone number

No

birth_date

string (max length: 8)

Customer's birthdate in format yyyyMMdd. E.g.: 19801027

Numeric format expected: yyyyMMdd

No

Payer.address Object

Field name

Format

Description

Validations

Required

street

string (max length: 255)

Customer's street

String of up to 255 characters

No

city

string (max length: 128)

Customer's city

String of up to 128 characters

No

state

string (max length: 3)

Customer's state code in ISO 3166-2 code format

Valid state code in ISO 3166-2 format. Check our States endpoint here

No

zip_code

string (max length: 16)

Customer's zip code

No

Last updated