OneShot Subscription Creation

The OneShot flow is designed for merchants who are not PCI compliant and cannot handle payment card data directly.

Endpoint

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

Process

1. Merchant submits subscription request with customer and billing information

2. API returns a redirect URL to our secure payment page

3. Customer completes payment on our PCI-compliant page

4. System creates subscription and notifies merchant via webhook

5. Customer is redirected to merchant's success/error URL

Request Example

{
  "invoice_id": "INV123456",
  "amount": 70.00,
  "currency": "BRL",
  "country": "BR",
  "payer": {
    "id": "PAYER123",
    "document": "123456789",
    "document_type": "CPF",
    "email": "[email protected]",
    "first_name": "John",
    "last_name": "Doe"
  },
  "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"
}

Create a new subscription

post

This endpoint allows the creation of a new subscription with payment details.

Header parameters

Content-Typestring · default: "application/json"required

Media type of the body sent to the API.

X-Datestring · date-timerequired

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

X-Loginstringrequired

Merchant X-Login API Key.

Authorizationstringrequired

Authorization control hash.

X-Idempotency-Keystringoptional

Unique idempotency key for ensuring that the same request is not processed more than once.

Body

invoice_idstringrequired

Unique identifier for the invoice

Example: INV123456

amountnumber · doublerequired

Amount to be charged for the subscription

Example: 70

currencystringrequired

Three-letter currency code (ISO 4217)

Example: BRL

countrystringrequired

Two-letter country code (ISO 3166-1 alpha-2)

Example: BR

payerobjectrequired

descriptionstringoptional

Description of the subscription

Example: Premium Subscription

subscriptionobjectrequired

client_ipstringoptional

IP address of the client

Example: 192.168.1.1

back_urlstring · urioptional

URL to redirect after payment process

Example: https://example.com/back

success_urlstring · urioptional

URL to redirect after successful payment

Example: https://example.com/success

error_urlstring · urioptional

URL to redirect after failed payment

Example: https://example.com/error

notification_urlstring · urioptional

URL to send payment status notifications

Example: https://example.com/notify

Responses

application/json

application/json

application/json

application/json

cURL

JavaScript

Python

HTTP

cURL

curl -L \
  --request POST \
  --url 'https://api-stg.directa24.com/v3/subscriptions' \
  --header 'Content-Type: application/json' \
  --header 'X-Date: 2025-04-01T23:16:54.235Z' \
  --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-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"
  }'

200

400

422

503

200

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

Subscription created successfully

Successful Response fields

Field	Type	Description	Example
subscription_id	Integer	Unique identifier of the created subscription	1234
redirect_url	String (URI)	URL to redirect the user to complete the subscription process	"https://checkout.cc-dev.directa24.net/validate/6mIsesbbmvYn2hzAOwuYQSMAYIyISUgl?subscriptionId=513"
expiration_date	String (Date-time)	Expiration date and time for the subscription checkout process	"2025-03-06 15:58:02"
payment_amount	Number (Double)	Amount to be charged for the subscription	70.00
redirect	Boolean	Indicates if the user should be redirected to complete the process	true

Response Example

{
  "subscription_id": 1234,
  "redirect_url": "https://checkout.cc-dev.directa24.net/validate/6mIsesbbmvYn2hzAOwuYQSMAYIyISUgl?subscriptionId=513",
  "expiration_date": "2025-03-06 15:58:02",
  "payment_amount": 70.00,
  "redirect": true
}

Error Response Structure

Field	Type	Description	Example
code	Integer	Error code indicating the type of error	400
description	String	Human-readable description of the error	"Invalid input data"
type	String	Machine-readable error type identifier	"VALIDATION_ERROR"

Bad Request - Invalid input data

{
  "code": 400,
  "description": "Invalid input data",
  "type": "VALIDATION_ERROR"
}

Unprocessable Entity - Validation error

{
  "code": 422,
  "description": "Validation error",
  "type": "VALIDATION_ERROR"
}

Service Unavailable - Error creating subscription

{
  "code": 503,
  "description": "Error creating subscription",
  "type": "SERVICE_ERROR"
}

Subscription Plans

The following subscription frequencies are supported:

Plan	Description
DAILY	Recurring billing every day
WEEKLY	Recurring billing every week
MONTHLY	Recurring billing every month
ANNUALLY	Recurring billing every year