Webhooks

Common Headers

All webhooks include HTTP header:

Header: X-CP-Callback-Type : type of webhook event (see individual webhooks below)

1

Issue card webhook

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

Request body

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

Request parameters

• docid (number) — Tracking document ID

• request_id (string) — Request identifier provided in the request

• status (string) — Actual status of the operation

• san (string) — Unique card identifier in the CinCin system

• params (object) — Additional parameters for the card issuance

• params.amount (decimal) — Initial card balance amount

• params.currency (string) — Currency code

2

TopUp card webhook

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

Request body

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

Request parameters

• docid (number) — Tracking document ID

• request_id (string) — Request identifier provided in the request

• status (string) — Actual status of the operation

• san (string) — Unique card identifier in the CinCin system

• params (object) — Additional parameters for the topup transaction

• params.amount (decimal) — Topup amount added to the card

• params.currency (string) — Currency code

3

Withdrawal card webhook

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

Request body

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

Request parameters

• docid (number) — Tracking document ID

• request_id (string) — Request identifier provided in the request

• status (string) — Actual status of the operation

• san (string) — Unique card identifier in the CinCin system

• params (object) — Additional parameters for the withdrawal transaction

• params.amount (decimal) — Withdrawal amount

• params.currency (string) — Currency code

4

Block card webhook

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

Request body

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

Request parameters

• docid (number) — Tracking document ID

• request_id (string) — Request identifier provided in the request

• status (string) — Actual status of the operation

• san (string) — Unique card identifier in the CinCin system

• params (object) — Additional parameters for the block operation

• params.amount (decimal) — Released balance amount from the blocked card

• params.currency (string) — Currency code

5

Freeze card webhook

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

Headers:

X-CP-Callback-Type: CARD_FREEZE

Request body

{
  "san": "3abdea0c20250820015603"
}

Request parameters

• san (string) — Unique card identifier in the CinCin system

6

Unfreeze card webhook

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

Headers:

X-CP-Callback-Type: CARD_UNFREEZE

Request body

{
  "san": "3abdea0c20250820015603"
}

Request parameters

• san (string) — Unique card identifier in the CinCin system

7

Extra-fee card charge webhook

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

Headers:

X-CP-Callback-Type: EXTRA_FEE_CARD

Request body

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

Request parameters

• san (string) — Unique card identifier in the CinCin system

• amount (decimal) — Fee amount charged

• feeType (string) — Type of fee

• txId (string) — Original transaction ID associated with the fee

• settlementDiff (boolean) — Indicates if there's a settlement difference

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 CinCin charge webhook

Called when additional fees are charged through the CinCin.

Headers:

X-CP-Callback-Type: EXTRA_FEE_CAP

Request body

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

Request parameters

• san (string) — Unique card identifier in the CinCin system

• amount (decimal) — Fee amount charged

• feeType (string) — Type of fee

• txId (string) — Original transaction ID associated with the fee

• settlementDiff (boolean) — Indicates if there's a settlement difference

9

Transaction card webhook

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

Headers:

X-CP-Callback-Type: CARD_TRANSACTION

Request body

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

Request parameters (required)

• san (string) — Unique card identifier in the CinCin system

• txId (string) — Transaction identifier

• txType (string) — Type of transaction

• txAmount (decimal) — Transaction amount in original currency

• txCurrency (string) — Currency code for transaction

• billAmount (decimal) — Billing amount (converted to card currency)

• billCurrency (string) — Currency code for billing

Request parameters (optional)

• originTxnId (string) — Original transaction ID (for reversals/refunds)

• forcePost (boolean) — Indicates if transaction was force-posted

• txDate (string) — Transaction date in ISO 8601 format (UTC)

• expenseDate (string) — Expense posting date in ISO 8601 format (UTC)

• merchantName (string) — Name of the merchant

• merchantCountry (string) — ISO 3166-1 alpha-3 country code

• mcc (string) — Merchant Category Code with description

• authCode (string) — Authorization code from payment network

• fee (decimal) — 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 webhook endpoint should respond with an HTTP status code:

• 200 OK — Webhook processed successfully

• 4xx/5xx — Error occurred (webhook may be retried)