POST Create Subscription

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/subscription/card' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'X-Merchant-ID: your_merchant_id' \
--header 'X-Request-ID: your-request-id' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "card_token_abc123",
    "plan_name": "Plan Premium",
    "periodicity": "monthly",
    "customer_data": {
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "+57",
        "phone_number": "3121234567",
        "email": "customer@example.com",
        "full_name": "John Doe"
    },
    "start_date": "2026-01-01"
}'

{
    "code": "CREATED",
    "status": true,
    "message": "Suscripción creada exitosamente",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "Los datos proporcionados no son válidos."
}

{
    "message": "Missing required header: X-Merchant-ID"
}

{
    "message": "Missing required header: X-Request-ID"
}

{
    "code": "UNAUTHORIZED",
    "status": false,
    "message": "Unauthorized."
}

{
    "code": "NOT_FOUND",
    "status": false,
    "message": "Comerciante no encontrado con UUID: {merchant_uuid}"
}

{
    "code": "ACCESS_DENIED",
    "status": false,
    "message": "El comerciante está inactivo"
}

{
    "code": "SUBSCRIPTION_CREATION_FAILED",
    "status": false,
    "message": "Mensaje de error de excepción de negocio"
}

{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error inesperado"
}

POST

api

subscription

card

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/subscription/card' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'X-Merchant-ID: your_merchant_id' \
--header 'X-Request-ID: your-request-id' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "card_token_abc123",
    "plan_name": "Plan Premium",
    "periodicity": "monthly",
    "customer_data": {
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "+57",
        "phone_number": "3121234567",
        "email": "customer@example.com",
        "full_name": "John Doe"
    },
    "start_date": "2026-01-01"
}'

{
    "code": "CREATED",
    "status": true,
    "message": "Suscripción creada exitosamente",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "Los datos proporcionados no son válidos."
}

{
    "message": "Missing required header: X-Merchant-ID"
}

{
    "message": "Missing required header: X-Request-ID"
}

{
    "code": "UNAUTHORIZED",
    "status": false,
    "message": "Unauthorized."
}

{
    "code": "NOT_FOUND",
    "status": false,
    "message": "Comerciante no encontrado con UUID: {merchant_uuid}"
}

{
    "code": "ACCESS_DENIED",
    "status": false,
    "message": "El comerciante está inactivo"
}

{
    "code": "SUBSCRIPTION_CREATION_FAILED",
    "status": false,
    "message": "Mensaje de error de excepción de negocio"
}

{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error inesperado"
}

Create a new subscription for recurring payments with credit or debit card. This endpoint allows you to associate a card with a subscription plan, defining the periodicity of recurring payments (monthly, yearly, or custom).

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/subscription/card' \
--header 'Token-Top: your_auth_token' \
--header 'Authorization: Basic your_auth_key' \
--header 'X-Merchant-ID: your_merchant_id' \
--header 'X-Request-ID: your-request-id' \
--header 'Content-Type: application/json' \
--data-raw '{
    "token": "card_token_abc123",
    "plan_name": "Plan Premium",
    "periodicity": "monthly",
    "customer_data": {
        "legal_doc": "1234567890",
        "legal_doc_type": "CC",
        "phone_code": "+57",
        "phone_number": "3121234567",
        "email": "customer@example.com",
        "full_name": "John Doe"
    },
    "start_date": "2026-01-01"
}'

{
    "code": "CREATED",
    "status": true,
    "message": "Suscripción creada exitosamente",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000"
    }
}

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "Los datos proporcionados no son válidos."
}

{
    "message": "Missing required header: X-Merchant-ID"
}

{
    "message": "Missing required header: X-Request-ID"
}

{
    "code": "UNAUTHORIZED",
    "status": false,
    "message": "Unauthorized."
}

{
    "code": "NOT_FOUND",
    "status": false,
    "message": "Comerciante no encontrado con UUID: {merchant_uuid}"
}

{
    "code": "ACCESS_DENIED",
    "status": false,
    "message": "El comerciante está inactivo"
}

{
    "code": "SUBSCRIPTION_CREATION_FAILED",
    "status": false,
    "message": "Mensaje de error de excepción de negocio"
}

{
    "code": "SERVICE_ERROR",
    "status": false,
    "message": "Ocurrió un error inesperado"
}

Required Headers

string

required

Merchant authentication token

string

required

Basic authentication (Basic Auth)

string

required

Unique identifier of the merchant invoking Card Payment services

string

required

Unique tracking identifier for the request

string

required

Must be “application/json”

Request Body Parameters

string

required

Token of the card associated with the subscription. This token is obtained through the TumiPay SDK.

string

required

Identifier name of the subscription plan (e.g., “Premium Plan”, “Basic Plan”).

string

required

Periodicity of recurring payments. Possible values:

monthly: Monthly payments
yearly: Yearly payments
custom: Custom periodicity according to plan configuration

object

required

Show Customer data

string

required

Customer identity document number

string

required

Document type. Possible values: CC, CE, PPN (Colombia)

string

required

Country phone code (e.g., “+57” for Colombia)

string

required

Phone number without country code

string

required

Customer email address

string

required

Customer full name

string

required

Subscription start date in YYYY-MM-DD format (e.g., “2026-01-01”).

Validation Rules

Required Fields

Field	Type	Rules	Description
`token`	string	required, max:60	Card subscription token
`plan_name`	string	required, max:20	Subscription plan name
`periodicity`	string	required	Subscription periodicity
`customer_data`	object	required	Customer data
`customer_data.legal_doc`	string	required, max:15	Customer legal document number
`customer_data.legal_doc_type`	string	required	Legal document type
`customer_data.phone_code`	string	required, max:4	Country phone code
`customer_data.phone_number`	string	required, max:20	Customer phone number
`customer_data.email`	string	required, email, max:255	Customer email address
`customer_data.full_name`	string	required, max:50	Customer full name
`start_date`	string	required, date_format:Y-m-d	Subscription start date (format: YYYY-MM-DD)

Allowed Values

periodicity

daily
weekly
biweekly
monthly
threefortnights
bimonthly
quarterly
fourmonths
halfyearly
yearly
custom

customer_data.legal_doc_type

CC - Cédula de Ciudadanía
CE - Cédula de Extranjería
NIT - Número de Identificación Tributaria
TI - Tarjeta de Identidad
PAS - Pasaporte

customer_data.phone_code

+57 - Colombia

Common Validation Error Messages

The following are common validation error messages returned by the API (in Spanish):

:attribute es obligatorio. - Required field missing
:attribute debe ser una cadena de texto. - Invalid data type (expected string)
:attribute debe ser un número. - Invalid data type (expected numeric)
:attribute debe ser un arreglo. - Invalid data type (expected array)
:attribute debe ser una dirección de correo electrónico válida. - Invalid email format
:attribute no puede tener más de :max caracteres. - Maximum length exceeded
:attribute debe ser mayor o igual a :min. - Minimum value not met
:attribute debe tener el formato YYYY-MM-DD. - Invalid date format
:attribute no es válido. - Invalid value

Response Fields

Success Response (200 OK)

string

required

Response code. Value: "CREATED" when the subscription is created successfully

boolean

required

Operation status. true when successful, false when there is an error

string

required

Descriptive message about the operation result

object

required

Show Subscription data

string

required

Unique identifier of the created subscription. This ID will be used for subsequent operations (preauthorization, cancellation, etc.)

HTTP Status Codes

Status Code	Description	Response Body
`200 OK`	Successful operation or business error	`status: true` for success, `status: false` for business error
`400 Bad Request`	Missing required header (`X-Merchant-ID` or `X-Request-ID`)	Simple error message
`401 Unauthorized`	Authentication failed (invalid `Token-Top` or `Authorization`)	`code: "UNAUTHORIZED"`
`403 Forbidden`	Inactive merchant	`code: "ACCESS_DENIED"`
`404 Not Found`	Merchant not found	`code: "NOT_FOUND"`
`422 Unprocessable Entity`	Validation error in request data	`code: "VALIDATION_ERROR"`
`500 Internal Server Error`	Internal server error	`code: "SERVICE_ERROR"`

Response Codes

Code	Description
`CREATED`	Subscription created successfully
`VALIDATION_ERROR`	Validation error in sent data
`UNAUTHORIZED`	Authentication error
`NOT_FOUND`	Merchant not found
`ACCESS_DENIED`	Inactive merchant
`SUBSCRIPTION_CREATION_FAILED`	Business error when creating subscription (provider, invalid token, etc.)
`SERVICE_ERROR`	Internal server error

Headers

X-Merchant-ID

string

required

Unique identifier of the Merchant invoking Card Payment services. Should not be used to authenticate end users.

X-Request-ID

string

required

Tracking identifier associated with the request, used to establish a correlation_id between ecosystem components.

Token-Top

string

required

Token for authentication.

Authorization

string

required

Basic authentication.

Body

application/json

token

string

required

Example:

"card_token_abc123"

plan_name

string

required

Example:

"Plan Premium"

periodicity

enum<string>

required

Available options:

daily,

weekly,

biweekly,

monthly,

threefortnights,

bimonthly,

quarterly,

fourmonths,

halfyearly,

yearly,

custom

Example:

"monthly"

customer_data

object

required

Show child attributes

start_date

string<date>

required

Example:

"2026-01-01"

Response

Subscription created successfully or business error. Check 'status' field in the body.

Response when creating a subscription. The 'status' field can be true (success) or false (business error) even with HTTP 200.

code

string

required

Response code. Values: 'CREATED' (success), 'SUBSCRIPTION_CREATION_FAILED' (business error)

Example:

"CREATED"

status

boolean

required

Operation status. true for success, false for error

Example:

true

message

string

required

Descriptive message about the result

Example:

"Suscripción creada exitosamente"

data

object

Show child attributes

Getting Started

Merchant API

PayIn API

PayOut API

Card Payment API

Integration

POST Create Subscription

Required Headers

Request Body Parameters

Validation Rules

Required Fields

Allowed Values

periodicity

customer_data.legal_doc_type

customer_data.phone_code

Common Validation Error Messages

Response Fields

Success Response (200 OK)

HTTP Status Codes

Response Codes

Headers

Body

Response

​Required Headers

​Request Body Parameters

​Validation Rules

​Required Fields

​Allowed Values

​periodicity

​customer_data.legal_doc_type

​customer_data.phone_code

​Common Validation Error Messages

​Response Fields

​Success Response (200 OK)

​HTTP Status Codes

​Response Codes

Headers

Body

Response

Required Headers

Request Body Parameters

Validation Rules

Required Fields

Allowed Values

periodicity

customer_data.legal_doc_type

customer_data.phone_code

Common Validation Error Messages

Response Fields

Success Response (200 OK)

HTTP Status Codes

Response Codes