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

Name	Type	Description
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

Name	Type	Description
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

200 Transaction successfully processed

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

400 Transaction failed due to field validation error

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

Request Example with Card Details

Request JSON

Subscription API

{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11111",
        "document": "84932568207",
        "email": "[e-mail]",
        "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
}

Response JSON

Response Example

{
    "subscription_id": 700000001,
    "deposit_id": 300604089,
    "user_id": "80000001",
    "merchant_invoice_id": "test82347893",
    "payment_info": {
        "type": "CREDIT_CARD",
        "result": "SUCCESS",
        "payment_method": "VI",
        "payment_method_name": "Visa",
        "amount": 1000.00,
        "currency": "BRL",
        "created_at": "2022-03-15 12:24:53"
    }
    "subscription_info": {
        "payment_period": 0,
        "type": "monthly",
        "start_date": "2022-03-15 12:24:53",
        "end_date": "2023-03-01 00:00:00"
    }
}

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

Name	Type	Description
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

Name	Type	Description
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

200 Transaction successfully processed

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

400 Transaction failed due to field validation error

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

Request Example without Card Details

Request JSON

Subscription API

{
    "invoice_id": "800000001",
    "amount": 1000,
    "country": "BR",
    "currency": "BRL",
    "payer": {
        "id": "11111",
        "document": "84932568207",
        "email": "[e-mail]",
        "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
}

Response JSON

Response Example

{
    "subscription_id": 700000001,
    "deposit_id": 300604089,
    "user_id": "80000001",
    "merchant_invoice_id": "test82347893",
    "redirect_url": "https://pay.directa24.com/eyJhbGciOiJIUzM4NCJ9.eyJqdGkiOiI0NjE4ODIwODIiLCJpYXQiOjE2NDg1MjI0NjAsImV4cCI6MTY1MTExNDQ2MH0.t_fRgBbVR7mXTydJu2VMOEe99noc3j34hb5hj34b5j34brj3qO_5C?q=0",
    payment_info: {
        "type": "CREDIT_CARD",
        "result": "PENDING",
        "payment_method_supported": ["VI", "MC", "AE"],
        "amount": 1000.00,
        "currency": "BRL",
        "created_at": "2022-03-15 12:24:53",
        "expiration_date": "2022-03-15 13:24:53"        
    },
    "subscription_info": {
        "payment_period": 0,
        "type": "monthly",
        "start_date": "2022-03-15 12:24:53",
        "end_date": "2023-03-01 00:00:00"
    }
}

An async notification will be sent to your notification_url to confirm the result of the payment.

Webhook JSON

Notification Example

{
    "subscription_id": 700000001,
    "deposit_id": 300604089
}

Use the Deposit Status Endpoint to check the status of this deposit, or use the Subscription Status Endpoint to check the status of the Subscription.

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 name	Format	Description
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 name	Format	Description
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 name	Format	Description	Default	Validations	Required
country	string (length: 2)	Country code of the deposit in ISO 3166-1 alpha-2 code format		Country codes	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	See Currencies	Yes
invoice_id	string (max length: 128)	Unique deposit ID on the merchant end	random string	^[A-Za-z0-9-_]*$	Yes
payer	object[]	Object containing details about the payer		Payer object	Yes
credit_card	object[]	Object containing the credit card details		Credit card object	Yes
subscription	object[]	Object containing the subscription details		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 name	Format	Description	Required
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	Luhn Algorithm	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 name	Format	Description	Default	Validations	Required
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		document validations	Yes
document_type	string (max length: 10)	Customer's document type. Optional, if sent must be a valid document type		document types validations	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[]	Object containing customer's address details		address object	No
phone	string (max length: 32)	Valid customer's phone number		phone number validations	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	zip_code validations	No