Skip to main content
POST
/
api
/
subscription
/
card
curl --request POST 'https://tumipay-card-payments.staging.tumipay.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": "[email protected]",
        "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"
    }
}
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.tumipay.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": "[email protected]",
        "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"
    }
}

​
Required Headers

​
Token-Top
string
required
Merchant authentication token
​
Authorization
string
required
Basic authentication (Basic Auth)
​
X-Merchant-ID
string
required
Unique identifier of the merchant invoking Card Payment services
​
X-Request-ID
string
required
Unique tracking identifier for the request
​
Content-Type
string
required
Must be “application/json”

​
Request Body Parameters

​
token
string
required
Token of the card associated with the subscription. This token is obtained through the TumiPay SDK.
​
plan_name
string
required
Identifier name of the subscription plan (e.g., “Premium Plan”, “Basic Plan”).
​
periodicity
string
required
Periodicity of recurring payments. Possible values:
  • monthly: Monthly payments
  • yearly: Yearly payments
  • custom: Custom periodicity according to plan configuration
​
customer_data
object
required
​
start_date
string
required
Subscription start date in YYYY-MM-DD format (e.g., “2026-01-01”).

​
Validation Rules

​
Required Fields

FieldTypeRulesDescription
tokenstringrequired, max:60Card subscription token
plan_namestringrequired, max:20Subscription plan name
periodicitystringrequiredSubscription periodicity
customer_dataobjectrequiredCustomer data
customer_data.legal_docstringrequired, max:15Customer legal document number
customer_data.legal_doc_typestringrequiredLegal document type
customer_data.phone_codestringrequired, max:4Country phone code
customer_data.phone_numberstringrequired, max:20Customer phone number
customer_data.emailstringrequired, email, max:255Customer email address
customer_data.full_namestringrequired, max:50Customer full name
start_datestringrequired, date_format:Y-m-dSubscription start date (format: YYYY-MM-DD)

​
Allowed Values

​
periodicity

  • daily
  • weekly
  • biweekly
  • monthly
  • threefortnights
  • bimonthly
  • quarterly
  • fourmonths
  • halfyearly
  • yearly
  • custom
  • 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)

​
code
string
required
Response code. Value: "CREATED" when the subscription is created successfully
​
status
boolean
required
Operation status. true when successful, false when there is an error
​
message
string
required
Descriptive message about the operation result
​
data
object
required

​
HTTP Status Codes

Status CodeDescriptionResponse Body
200 OKSuccessful operation or business errorstatus: true for success, status: false for business error
400 Bad RequestMissing required header (X-Merchant-ID or X-Request-ID)Simple error message
401 UnauthorizedAuthentication failed (invalid Token-Top or Authorization)code: "UNAUTHORIZED"
403 ForbiddenInactive merchantcode: "ACCESS_DENIED"
404 Not FoundMerchant not foundcode: "NOT_FOUND"
422 Unprocessable EntityValidation error in request datacode: "VALIDATION_ERROR"
500 Internal Server ErrorInternal server errorcode: "SERVICE_ERROR"

​
Response Codes

CodeDescription
CREATEDSubscription created successfully
VALIDATION_ERRORValidation error in sent data
UNAUTHORIZEDAuthentication error
NOT_FOUNDMerchant not found
ACCESS_DENIEDInactive merchant
SUBSCRIPTION_CREATION_FAILEDBusiness error when creating subscription (provider, invalid token, etc.)
SERVICE_ERRORInternal 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:
monthly,
yearly,
custom
Example:

"monthly"

​
customer_data
object
required
​
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