> For the complete documentation index, see [llms.txt](https://docs.cardspro.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.cardspro.com/api/operations-callbacks.md).

# 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 <a href="#common-headers" id="common-headers"></a>

All callbacks include the following HTTP headers:

<table><thead><tr><th width="222.333251953125">Header</th><th width="236.4444580078125">Description</th><th>Example Values</th></tr></thead><tbody><tr><td><code>X-CP-Callback-Type</code></td><td>Type of callback event</td><td>See individual callbacks below</td></tr></tbody></table>

### 1. Issue Card Callback <a href="#id-1-issue-card-callback" id="id-1-issue-card-callback"></a>

Called when a card issuance operation is completed, regardless of success or failure (see `status` field for outcome).

**Headers:**

```
X-CP-Callback-Type: CARD_ISSUE
```

**Callback Body:**

```json
{
  "docid": 397465223,
  "request_id": "112-2F9-333-070",
  "status": "EXECUTED",
  "san": "3abdea480025082008472",
  "params":{
    "amount":69.72,
    "currency":"USD"
  }
}
```

**Fields:**

<table><thead><tr><th width="171.6666259765625">Field</th><th width="125">Type</th><th width="107">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>docid</code></td><td>Number</td><td>Yes</td><td>Document identifier for the issued card</td></tr><tr><td><code>request_id</code></td><td>String</td><td>Yes</td><td>User request identifier</td></tr><tr><td><code>status</code></td><td>String</td><td>Yes</td><td>Operation status (EXECUTED, DECLINED)</td></tr><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>params</code></td><td>Object</td><td>No</td><td>Additional parameters for the card issuance</td></tr><tr><td><code>params.amount</code></td><td>Decimal</td><td>Yes</td><td>Initial card balance amount</td></tr><tr><td><code>params.currency</code></td><td>String</td><td>Yes</td><td>Currency code (e.g., USD, EUR)</td></tr></tbody></table>

***

### 2. TopUp Card Callback <a href="#id-2-topup-card-callback" id="id-2-topup-card-callback"></a>

Called when a card topup operation is completed, regardless of success or failure (see `status` field for outcome).

**Headers:**

```
X-CP-Callback-Type: CARD_TOPUP
```

**Callback Body:**

```json
{
  "docid": 3974652656,
  "request_id": "112-2F9-333-073",
  "status": "EXECUTED",
  "san": "3abdea0c20250820015603",
  "params": {
    "amount": 405.3,
    "currency": "USD"
  }
}
```

**Fields:**

<table><thead><tr><th width="171.4444580078125">Field</th><th width="124.111083984375">Type</th><th width="109.2222900390625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>docid</code></td><td>Number</td><td>Yes</td><td>Document identifier for the topup transaction</td></tr><tr><td><code>request_id</code></td><td>String</td><td>Yes</td><td>User request identifier</td></tr><tr><td><code>status</code></td><td>String</td><td>Yes</td><td>Operation status (EXECUTED, DECLINED)</td></tr><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>params</code></td><td>Object</td><td>No</td><td>Additional parameters for the topup transaction</td></tr><tr><td><code>params.amount</code></td><td>Decimal</td><td>Yes</td><td>Topup amount added to the card</td></tr><tr><td><code>params.currency</code></td><td>String</td><td>Yes</td><td>Currency code (e.g., USD, EUR)</td></tr></tbody></table>

***

### 3. Withdrawal Card Callback <a href="#id-3-block-card-callback" id="id-3-block-card-callback"></a>

Called when a card withdrawal operation is completed, regardless of success or failure (see `status` field for outcome).

**Headers:**

```
X-CP-Callback-Type: CARD_WITHDRAWAL
```

**Callback Body:**

```json
{
  "docid": 362817383,
  "request_id": "389189423091B9V8",
  "status": "EXECUTED",
  "san": "mock-skqytz",
  "params": {
    "amount": 55.42,
    "currency": "USD"
  }
}
```

**Fields:**

<table><thead><tr><th width="169.22216796875">Field</th><th width="126.3333740234375">Type</th><th width="110.333251953125">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>docid</code></td><td>Number</td><td>Yes</td><td>Document identifier for the topup transaction</td></tr><tr><td><code>request_id</code></td><td>String</td><td>No</td><td>User request identifier</td></tr><tr><td><code>status</code></td><td>String</td><td>Yes</td><td>Operation status (EXECUTED, DECLINED)</td></tr><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>params</code></td><td>Object</td><td>No</td><td>Additional parameters for the withdrawal transaction</td></tr><tr><td><code>params.amount</code></td><td>Decimal</td><td>Yes</td><td>Withdrawal amount</td></tr><tr><td><code>params.currency</code></td><td>String</td><td>Yes</td><td>Currency code (e.g., USD, EUR)</td></tr></tbody></table>

### 4. Block Card Callback <a href="#id-3-block-card-callback" id="id-3-block-card-callback"></a>

Called when a card block operation is completed, regardless of success or failure (see `status` field for outcome).

**Headers:**

```
X-CP-Callback-Type: CARD_BLOCK
```

**Callback Body:**

```json
{
  "docid": 3974652610,
  "request_id": "11D-2F9-333-077",
  "status": "EXECUTED",
  "san": "3abdea0c20250820018903",
  "params": {
    "amount": 55.3,
    "currency": "USD"
  }
}
```

**Fields:**

<table><thead><tr><th width="177">Field</th><th width="116.3333740234375">Type</th><th width="111.4443359375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>docid</code></td><td>Number</td><td>Yes</td><td>Document identifier for the topup transaction</td></tr><tr><td><code>request_id</code></td><td>String</td><td>No</td><td>User request identifier</td></tr><tr><td><code>status</code></td><td>String</td><td>Yes</td><td>Operation status (EXECUTED, DECLINED)</td></tr><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>params</code></td><td>Object</td><td>No</td><td>Additional parameters for the topup transaction</td></tr><tr><td><code>params.amount</code></td><td>Decimal</td><td>Yes</td><td>Released balance amount from the blocked card</td></tr><tr><td><code>params.currency</code></td><td>String</td><td>Yes</td><td>Currency code (e.g., USD, EUR)</td></tr></tbody></table>

### 5. Freeze Card Callback <a href="#id-4-freeze-card-callback" id="id-4-freeze-card-callback"></a>

Called when a card is temporarily frozen. A frozen card can be unfrozen later.

**Headers:**

```
X-CP-Callback-Type: CARD_FREEZE
```

**Callback Body:**

```json
{
  "san": "3abdea0c20250820015603"
}
```

**Fields:**

<table><thead><tr><th width="164.6666259765625">Field</th><th width="121.2222900390625">Type</th><th width="120.3333740234375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr></tbody></table>

***

### 6. Unfreeze Card Callback <a href="#id-5-unfreeze-card-callback" id="id-5-unfreeze-card-callback"></a>

Called when a previously frozen card is unfrozen and ready for use.

**Headers:**

```
X-CP-Callback-Type: CARD_UNFREEZE
```

**Callback Body:**

```json
{
  "san": "3abdea0c20250820015603"
}
```

**Fields:**

<table><thead><tr><th width="130.3333740234375">Field</th><th width="131.666748046875">Type</th><th width="170.888916015625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr></tbody></table>

***

### 7. Extra-Fee Card Charge Callback <a href="#id-6-extra-fee-card-charge-callback" id="id-6-extra-fee-card-charge-callback"></a>

Called when additional fees are charged to a card for specific transaction types.

**Headers:**

```
X-CP-Callback-Type: EXTRA_FEE_CARD
```

**Callback Body:**

```json
{
  "san": "e5792c6821240906122702",
  "amount": 0.25,
  "feeType": "success",
  "txId": "original_tx_id",
  "settlementDiff": true
}
```

**Fields:**

<table><thead><tr><th width="167.111083984375">Field</th><th width="131.6666259765625">Type</th><th width="123.6666259765625">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>amount</code></td><td>Decimal</td><td>Yes</td><td>Fee amount charged</td></tr><tr><td><code>feeType</code></td><td>String</td><td>Yes</td><td>Type of fee (see Fee Types below)</td></tr><tr><td><code>txId</code></td><td>String</td><td>Yes</td><td>Original transaction ID associated with the fee</td></tr><tr><td><code>settlementDiff</code></td><td>Boolean</td><td>Yes</td><td>Indicates if there's a settlement difference</td></tr></tbody></table>

**Fee Types:**

* `success` - Fee for successful transaction
* `expense` - Expense-related fee
* `decline` - Fee for declined transaction
* `reversal` - Fee for transaction reversal
* `force_post` - Fee for forced post transaction
* `cancellation` - Fee for transaction cancellation
* `pending` - Fee for pending transaction
* `overdraft` - Overdraft fee

***

### 8. Extra-Fee Capitalist Charge Callback <a href="#id-7-extra-fee-capitalist-charge-callback" id="id-7-extra-fee-capitalist-charge-callback"></a>

Called when additional fees are charged through the Capitalist.

**Headers:**

```
X-CP-Callback-Type: EXTRA_FEE_CAP
```

**Callback Body:**

```json
{
  "san": "e5792c6821240906122702",
  "amount": 0.30,
  "feeType": "decline",
  "txId": "original_tx_id",
  "settlementDiff": false
}
```

**Fields:**

<table><thead><tr><th width="174.4444580078125">Field</th><th width="127.888916015625">Type</th><th width="120.3333740234375">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>amount</code></td><td>Decimal</td><td>Yes</td><td>Fee amount charged</td></tr><tr><td><code>feeType</code></td><td>String</td><td>Yes</td><td>Type of fee (see Fee Types above)</td></tr><tr><td><code>txId</code></td><td>String</td><td>Yes</td><td>Original transaction ID associated with the fee</td></tr><tr><td><code>settlementDiff</code></td><td>Boolean</td><td>Yes</td><td>Indicates if there's a settlement difference</td></tr></tbody></table>

***

### 9. Transaction Card Callback <a href="#id-8-transaction-card-callback" id="id-8-transaction-card-callback"></a>

Called when a card transaction occurs. This is the most common callback type.

**Headers:**

```
X-CP-Callback-Type: CARD_TRANSACTION
```

**Callback Body:**

```json
{
  "san": "3abdea0c20250820015603",
  "txId": "A2001264138954887169",
  "originTxnId": "ad6258fa-d554-4607-a5e8-4b8025533b92",
  "txType": "expense",
  "forcePost": false,
  "txDate": "2025-12-17T12:12:07.076Z",
  "expenseDate": "2025-12-18T12:00:43.351Z",
  "txAmount": 10000.0,
  "txCurrency": "VND",
  "billAmount": 0.39,
  "billCurrency": "USD",
  "merchantName": "Grab* A-8OASB3PWW4ITAV HA NOI VNM",
  "merchantCountry": "VNM",
  "mcc": "4121 LIMOUSINES AND TAXICABS",
  "authCode": "299164",
  "fee": 0.12
}
```

**Required Fields:**

<table><thead><tr><th width="177">Field</th><th width="136.6666259765625">Type</th><th width="117">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>san</code></td><td>String</td><td>Yes</td><td>Secure Account Number(card id)</td></tr><tr><td><code>txId</code></td><td>String</td><td>Yes</td><td>Transaction identifier</td></tr><tr><td><code>txType</code></td><td>String</td><td>Yes</td><td>Type of transaction (see Transaction Types below)</td></tr><tr><td><code>txAmount</code></td><td>Decimal</td><td>Yes</td><td>Transaction amount in original currency</td></tr><tr><td><code>txCurrency</code></td><td>String</td><td>Yes</td><td>Currency code for transaction</td></tr><tr><td><code>billAmount</code></td><td>Decimal</td><td>Yes</td><td>Billing amount (converted to card currency)</td></tr><tr><td><code>billCurrency</code></td><td>String</td><td>Yes</td><td>Currency code for billing</td></tr></tbody></table>

**Optional Fields:**

<table><thead><tr><th width="178.2222900390625">Field</th><th width="123.22216796875">Type</th><th width="112.5555419921875">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>originTxnId</code></td><td>String</td><td>No</td><td><p>Original transaction ID </p><p>(for expense/reversals/refunds)</p></td></tr><tr><td><code>forcePost</code></td><td>Boolean</td><td>No</td><td>Indicates if transaction was force-posted</td></tr><tr><td><code>txDate</code></td><td>String</td><td>No</td><td>Transaction date in ISO 8601 format (UTC)</td></tr><tr><td><code>expenseDate</code></td><td>String</td><td>No</td><td>Expense posting date in ISO 8601 format (UTC)</td></tr><tr><td><code>merchantName</code></td><td>String</td><td>No</td><td>Name of the merchant</td></tr><tr><td><code>merchantCountry</code></td><td>String</td><td>No</td><td>ISO 3166-1 alpha-3 country code</td></tr><tr><td><code>mcc</code></td><td>String</td><td>No</td><td>Merchant Category Code with description</td></tr><tr><td><code>authCode</code></td><td>String</td><td>No</td><td>Authorization code from payment network</td></tr><tr><td><code>fee</code></td><td>Decimal</td><td>No</td><td>Additional fee amount (always greater than 0 when present)</td></tr></tbody></table>

**Transaction Types:**

| Type                    | Description                       |
| ----------------------- | --------------------------------- |
| `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   |

### 10. KYC Status Change Callback <a href="#id-8-transaction-card-callback" id="id-8-transaction-card-callback"></a>

Called when the KYC status changes.

**Headers:**

```
X-CP-Callback-Type: KYC_CHANGE
```

**Callback Body:**

```json
{
  "kycExternalUserId": "your unique user id",
  "status": "DECLINED",
  "reason": "photo is dirty",
  "uuid": "uuid-of-kyc"
}
```

{% hint style="info" %}
&#x20;**Body of callback for KYC status change is the same as** [**`Query KYC status response`**](/api/kyc/query-kyc-status.md)&#x20;
{% endhint %}

***

### Response Format <a href="#response-format" id="response-format"></a>

Your callback endpoint should respond with an HTTP status code:

* **200 OK** - Callback processed successfully
* **4xx/5xx** - Error occurred (callback may be retried)