# Webhooks #### Common Headers All webhooks include HTTP header: {% hint style="info" %} Header: `X-CP-Callback-Type` : type of webhook event (see individual webhooks below) {% endhint %} {% stepper %} {% step %} ### 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 ```json { "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 {% endstep %} {% step %} ### 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 ```json { "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 {% endstep %} {% step %} ### 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 ```json { "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 {% endstep %} {% step %} ### 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 ```json { "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 {% endstep %} {% step %} ### 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 ```json { "san": "3abdea0c20250820015603" } ``` #### Request parameters * san (string) — Unique card identifier in the CinCin system {% endstep %} {% step %} ### Unfreeze card webhook Called when a previously frozen card is unfrozen and ready for use. Headers: ``` X-CP-Callback-Type: CARD_UNFREEZE ``` #### Request body ```json { "san": "3abdea0c20250820015603" } ``` #### Request parameters * san (string) — Unique card identifier in the CinCin system {% endstep %} {% step %} ### 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 ```json { "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 {% endstep %} {% step %} ### Extra-fee CinCin charge webhook Called when additional fees are charged through the CinCin. Headers: ``` X-CP-Callback-Type: EXTRA_FEE_CAP ``` #### Request body ```json { "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 {% endstep %} {% step %} ### 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 ```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 } ``` #### 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 {% endstep %} {% endstepper %} *** #### 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)