Operations callbacks
Card operations callbacks
This document describes the REST callback API for Card operations. Callbacks are HTTP POST requests sent to your configured endpoint when specific card events occur. All callbacks use HTTP headers to identify the callback type and card type.
Common Headers
All callbacks include the following HTTP headers:
X-CP-Callback-Type
Type of callback event
See individual callbacks below
1. Issue Card Callback
Called when a card issuance operation is completed, regardless of success or failure (see status field for outcome).
Headers:
X-CP-Callback-Type: CARD_ISSUERequest Body:
{
"docid": 397465223,
"request_id": "112-2F9-333-070",
"status": "EXECUTED",
"san": "3abdea480025082008472",
"params":{
"amount":69.72,
"currency":"USD"
}
}Fields:
docid
Number
Yes
Document identifier for the issued card
request_id
String
Yes
User request identifier
status
String
Yes
Operation status (EXECUTED, DECLINED)
san
String
Yes
Secure Account Number(card id)
params
Object
No
Additional parameters for the card issuance
params.amount
Decimal
Yes
Initial card balance amount
params.currency
String
Yes
Currency code (e.g., USD, EUR)
2. TopUp Card Callback
Called when a card topup operation is completed, regardless of success or failure (see status field for outcome).
Headers:
Request Body:
Fields:
docid
Number
Yes
Document identifier for the topup transaction
request_id
String
Yes
User request identifier
status
String
Yes
Operation status (EXECUTED, DECLINED)
san
String
Yes
Secure Account Number(card id)
params
Object
No
Additional parameters for the topup transaction
params.amount
Decimal
Yes
Topup amount added to the card
params.currency
String
Yes
Currency code (e.g., USD, EUR)
3. Withdrawal Card Callback
Called when a card withdrawal operation is completed, regardless of success or failure (see status field for outcome).
Headers:
Request Body:
Fields:
docid
Number
Yes
Document identifier for the topup transaction
request_id
String
No
User request identifier
status
String
Yes
Operation status (EXECUTED, DECLINED)
san
String
Yes
Secure Account Number(card id)
params
Object
No
Additional parameters for the withdrawal transaction
params.amount
Decimal
Yes
Withdrawal amount
params.currency
String
Yes
Currency code (e.g., USD, EUR)
4. Block Card Callback
Called when a card block operation is completed, regardless of success or failure (see status field for outcome).
Headers:
Request Body:
Fields:
docid
Number
Yes
Document identifier for the topup transaction
request_id
String
No
User request identifier
status
String
Yes
Operation status (EXECUTED, DECLINED)
san
String
Yes
Secure Account Number(card id)
params
Object
No
Additional parameters for the topup transaction
params.amount
Decimal
Yes
Released balance amount from the blocked card
params.currency
String
Yes
Currency code (e.g., USD, EUR)
5. Freeze Card Callback
Called when a card is temporarily frozen. A frozen card can be unfrozen later.
Headers:
Request Body:
Fields:
san
String
Yes
Secure Account Number(card id)
6. Unfreeze Card Callback
Called when a previously frozen card is unfrozen and ready for use.
Headers:
Request Body:
Fields:
san
String
Yes
Secure Account Number(card id)
7. Extra-Fee Card Charge Callback
Called when additional fees are charged to a card for specific transaction types.
Headers:
Request Body:
Fields:
san
String
Yes
Secure Account Number(card id)
amount
Decimal
Yes
Fee amount charged
feeType
String
Yes
Type of fee (see Fee Types below)
txId
String
Yes
Original transaction ID associated with the fee
settlementDiff
Boolean
Yes
Indicates if there's a settlement difference
Fee Types:
success- Fee for successful transactionexpense- Expense-related feedecline- Fee for declined transactionreversal- Fee for transaction reversalforce_post- Fee for forced post transactioncancellation- Fee for transaction cancellationpending- Fee for pending transactionoverdraft- Overdraft fee
8. Extra-Fee Capitalist Charge Callback
Called when additional fees are charged through the Capitalist.
Headers:
Request Body:
Fields:
san
String
Yes
Secure Account Number(card id)
amount
Decimal
Yes
Fee amount charged
feeType
String
Yes
Type of fee (see Fee Types above)
txId
String
Yes
Original transaction ID associated with the fee
settlementDiff
Boolean
Yes
Indicates if there's a settlement difference
9. Transaction Card Callback
Called when a card transaction occurs. This is the most common callback type.
Headers:
Request Body:
Required Fields:
san
String
Yes
Secure Account Number(card id)
txId
String
Yes
Transaction identifier
txType
String
Yes
Type of transaction (see Transaction Types below)
txAmount
Decimal
Yes
Transaction amount in original currency
txCurrency
String
Yes
Currency code for transaction
billAmount
Decimal
Yes
Billing amount (converted to card currency)
billCurrency
String
Yes
Currency code for billing
Optional Fields:
originTxnId
String
No
Original transaction ID
(for reversals/refunds)
forcePost
Boolean
No
Indicates if transaction was force-posted
txDate
String
No
Transaction date in ISO 8601 format (UTC)
expenseDate
String
No
Expense posting date in ISO 8601 format (UTC)
merchantName
String
No
Name of the merchant
merchantCountry
String
No
ISO 3166-1 alpha-3 country code
mcc
String
No
Merchant Category Code with description
authCode
String
No
Authorization code from payment network
fee
Decimal
No
Additional fee amount (always greater than 0 when present)
Transaction Types:
authorization
Pre-authorization hold on funds
authorization_decline
Declined authorization attempt
expense
Completed transaction expense
reversal
Transaction reversal/cancellation
refund
Refund to card
verification
Card verification transaction
verification_decline
Declined verification attempt
verification_expense
Completed verification expense
maintenance_fee
Card maintenance or service fee
Response Format
Your callback endpoint should respond with an HTTP status code:
200 OK - Callback processed successfully
4xx/5xx - Error occurred (callback may be retried)
Last updated