POST Cancel Subscription

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/subscription/card/cancel' \
--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 '{
    "subscription_id": "sub_93af8f63-97d1-4be0-9e0d-f6fd8c2d92a0"
}'

{
    "code": "SUCCESS",
    "status": true,
    "message": "Suscripción cancelada exitosamente",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
        "cancellation_date": "2025-12-23T10:30:45.123Z"
    }
}

{
    "code": "ALREADY_CANCELLED",
    "status": true,
    "message": "La suscripción ya estaba cancelada",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
        "cancellation_date": "2025-12-23T10:30:45.123Z"
    }
}

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "subscription_id is required."
}

{
    "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": "No se pudo localizar la suscripción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "Esta operación de suscripción no se puede realizar. Estado actual: FAILED"
}

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

POST

api

subscription

card

cancel

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/subscription/card/cancel' \
--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 '{
    "subscription_id": "sub_93af8f63-97d1-4be0-9e0d-f6fd8c2d92a0"
}'

{
    "code": "SUCCESS",
    "status": true,
    "message": "Suscripción cancelada exitosamente",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
        "cancellation_date": "2025-12-23T10:30:45.123Z"
    }
}

{
    "code": "ALREADY_CANCELLED",
    "status": true,
    "message": "La suscripción ya estaba cancelada",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
        "cancellation_date": "2025-12-23T10:30:45.123Z"
    }
}

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "subscription_id is required."
}

{
    "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": "No se pudo localizar la suscripción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "Esta operación de suscripción no se puede realizar. Estado actual: FAILED"
}

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

Cancel an existing subscription. The operation is idempotent: if the subscription is already cancelled, the system returns the ALREADY_CANCELLED status without generating an error.

curl --request POST 'https://tumipay-card-payments.staging.topup.com.co/production/api/subscription/card/cancel' \
--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 '{
    "subscription_id": "sub_93af8f63-97d1-4be0-9e0d-f6fd8c2d92a0"
}'

{
    "code": "SUCCESS",
    "status": true,
    "message": "Suscripción cancelada exitosamente",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
        "cancellation_date": "2025-12-23T10:30:45.123Z"
    }
}

{
    "code": "ALREADY_CANCELLED",
    "status": true,
    "message": "La suscripción ya estaba cancelada",
    "data": {
        "subscription_id": "550e8400-e29b-41d4-a716-446655440000",
        "cancellation_date": "2025-12-23T10:30:45.123Z"
    }
}

{
    "code": "VALIDATION_ERROR",
    "status": false,
    "message": "subscription_id is required."
}

{
    "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": "No se pudo localizar la suscripción solicitada con UUID: 550e8400-e29b-41d4-a716-446655440000"
}

{
    "code": "INVALID_STATE",
    "status": false,
    "message": "Esta operación de suscripción no se puede realizar. Estado actual: FAILED"
}

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

Unique identifier of the subscription to cancel. This ID is obtained when creating the subscription.

Validation Rules

Required Fields

Field	Type	Rules	Description
`subscription_id`	string	required, max:36	UUID of the subscription to cancel

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 no puede tener más de :max caracteres. - Maximum length exceeded
:attribute no es válido. - Invalid value

Response Fields

Success Response (200 OK)

string

required

Response code. Possible values:

"SUCCESS": Subscription cancelled successfully
"ALREADY_CANCELLED": The subscription was already cancelled (idempotent operation)

boolean

required

Operation status. true when successful (even if already cancelled)

string

required

Descriptive message about the cancellation result

object

required

Show Cancellation data

string

required

Unique identifier of the cancelled subscription

string

required

Cancellation date and time in ISO 8601 format with UTC timezone (format: Y-m-d\TH:i:s.v\Z)

HTTP Status Codes

Status Code	Description	Response Body
`200 OK`	Successful operation (cancelled or already cancelled)	`status: true`, `code: "SUCCESS"` or `"ALREADY_CANCELLED"`
`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"`
`404 Not Found`	Subscription not found	`code: "NOT_FOUND"`
`409 Conflict`	Invalid state (subscription cannot be cancelled)	`code: "INVALID_STATE"`
`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
`SUCCESS`	Subscription cancelled successfully
`ALREADY_CANCELLED`	The subscription was already cancelled (idempotency)
`VALIDATION_ERROR`	Validation error in sent data
`UNAUTHORIZED`	Authentication error
`NOT_FOUND`	Subscription not found
`INVALID_STATE`	The subscription cannot be cancelled due to its current state
`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

subscription_id

string

required

Example:

"sub_93af8f63-97d1-4be0-9e0d-f6fd8c2d92a0"

Response

Subscription cancelled successfully or was already cancelled (idempotency). Check 'code' field to distinguish between 'SUCCESS' and 'ALREADY_CANCELLED'.

Response to the cancellation process. The 'status' field is always true (even for ALREADY_CANCELLED) due to idempotency.

code

enum<string>

required

Response code. Values: 'SUCCESS' (cancelled successfully), 'ALREADY_CANCELLED' (was already cancelled)

Available options:

SUCCESS,

ALREADY_CANCELLED

Example:

"SUCCESS"

status

boolean

required

Operation status. Always true for successful responses (even if already cancelled)

Example:

true

message

string

required

Descriptive message about the cancellation result

Example:

"Suscripción cancelada exitosamente"

data

object

required

Show child attributes

Getting Started

Merchant API

PayIn API

PayOut API

Card Payment API

Integration

POST Cancel Subscription

Required Headers

Request Body Parameters

Validation Rules

Required Fields

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

​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

Common Validation Error Messages

Response Fields

Success Response (200 OK)

HTTP Status Codes

Response Codes