Skip to main content
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"
    }
}
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"
    }
}

​
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

​
subscription_id
string
required
Unique identifier of the subscription to cancel. This ID is obtained when creating the subscription.

​
Validation Rules

​
Required Fields

FieldTypeRulesDescription
subscription_idstringrequired, max:36UUID 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)

​
code
string
required
Response code. Possible values:
  • "SUCCESS": Subscription cancelled successfully
  • "ALREADY_CANCELLED": The subscription was already cancelled (idempotent operation)
​
status
boolean
required
Operation status. true when successful (even if already cancelled)
​
message
string
required
Descriptive message about the cancellation result
​
data
object
required

​
HTTP Status Codes

Status CodeDescriptionResponse Body
200 OKSuccessful operation (cancelled or already cancelled)status: true, code: "SUCCESS" or "ALREADY_CANCELLED"
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"
404 Not FoundSubscription not foundcode: "NOT_FOUND"
409 ConflictInvalid state (subscription cannot be cancelled)code: "INVALID_STATE"
422 Unprocessable EntityValidation error in request datacode: "VALIDATION_ERROR"
500 Internal Server ErrorInternal server errorcode: "SERVICE_ERROR"

​
Response Codes

CodeDescription
SUCCESSSubscription cancelled successfully
ALREADY_CANCELLEDThe subscription was already cancelled (idempotency)
VALIDATION_ERRORValidation error in sent data
UNAUTHORIZEDAuthentication error
NOT_FOUNDSubscription not found
INVALID_STATEThe subscription cannot be cancelled due to its current state
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
​
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