PCI Subscription Creation Endpoint

Endpoint

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

Process

  1. Merchant collects payment details directly from customer

  2. Merchant submits complete subscription request including credit card data

  3. System processes payment and creates subscription immediately

  4. API returns subscription confirmation directly in the response

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

Create a new subscription with credit card details

post

This endpoint allows PCI merchants to create a new subscription with direct credit card details.

Header parameters
Content-TypestringRequired

Media type of the body sent to the API.

Default: application/json
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
descriptionstringOptional

Description of the subscription

Example: Premium Subscription
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
200
Subscription created successfully
application/json
post
POST /v3/subscriptions HTTP/1.1
Host: cc-api-stg.directa24.com
Content-Type: application/json
X-Date: 2025-06-26T07:35:38.481Z
X-Login: text
Authorization: text
Accept: */*
Content-Length: 680

{
  "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
  },
  "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"
}
{
  "subscription_id": 358
}

Successful Response Structure

Field
Type
Description
Example

subscription_id

Integer

Unique identifier of the created subscription

1234

Example response

{
  "subscription_id": 358
}

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

Tests in STG Environment.

Last updated

Was this helpful?