Skip to content

Authorization

Overview of the Authorization Event Type

The authorization webhook is triggered when a transaction decision is required for card programs that have opted into Real-Time Authorization. This occurs whenever a transaction request is received.

What You Can Do With This Webhook

This webhook is essential for card programs supporting real-time authorization, as it enables your system to approve or decline a transaction request when a cardholder initiates a transaction.

  • When triggered, this webhook provides detailed transaction data, including merchant details and amount.
  • You must respond within 1.1 seconds using the authorization_id as the identifier.

Sample Webhook Payload

{
  "eventName": "request",
  "eventType": "authorization",
  "data": {
    "mcc": "5732",
    "wallet": "",
    "card_id": "5355a6ea-072e-44ba-accd-446ae0799342",
    "channel": "ECOMMERCE",
    "created_at": "2025-05-29T02:54:32.655Z",
    "message_id": "e7f780ce-142f-4e79-9665-1525b40c1700",
    "bill_amount": 4.5,
    "bill_currency": "840",
    "exchange_rate": "1.00",
    "merchant_city": "",
    "merchant_data": {
      "mcc_code": "5732",
      "merchant_id": "merchant1",
      "mcc_category": "Electronics Stores",
      "merchant_city": "",
      "merchant_name": "Merchant",
      "merchant_state": null,
      "merchant_country": "HK",
      "merchant_post_code": null
    },
    "merchant_name": "Merchant",
    "billing_amount": 4.5,
    "merchant_state": null,
    "transaction_id": "tid_fNjNpXr041",
    "conversion_rate": "1.00",
    "merchant_amount": 4.5,
    "authorization_id": "e7f780ce-142f-4e79-9665-1525b40c1700",
    "billing_currency": "840",
    "merchant_address": null,
    "merchant_country": "HK",
    "transaction_date": "2025-05-29T02:54:32.655Z",
    "transaction_type": "100",
    "conversation_rate": "1.00",
    "merchant_currency": "840",
    "settlement_amount": 4.5,
    "lifecycle_event_id": "e7f780ce-142f-4e79-9665-1525b40c1700",
    "mcc_padding_amount": 0,
    "transaction_amount": 4.5,
    "settlement_currency": "840",
    "transaction_currency": "840",
    "actual_authentication_method": "not_applicable",
    "fees": {
      "authorization_fee": "0.05",
      "settlement_fee": "0.05",
      "fx_markup_fee": "0.22"
    }
  }
}

Responding to the Authorization Request

To approve or decline an authorization request, your system must respond within 1.6 seconds with an authorization response.

Sample Response Payload

{
  "authorization_id": "b4a33cc4-67a4-4d9a-9f3b-b3d3b728a65f",
  "response_code": "00"
}

Response Codes

Response Code Action Description
00 Approve transaction Transaction is successfully authorized.
51 Decline transaction Insufficient funds. Returned as 5E in decline_reason.response_code.
57 Decline transaction Transaction not permitted (e.g., restricted MCC).
41 Decline transaction Card reported lost.
43 Decline transaction Stolen card capture.
46 Decline transaction Card is inactive and transactions cannot be processed.
59 Decline transaction Something went wrong. May indicate a potential fraud case.
61 Decline transaction ATM withdrawal limit exceeded. Try a smaller amount or wait to reset.
62 Decline transaction ATM withdrawals not allowed in this country.
65 Decline transaction Exceeded allowed number of ATM withdrawals. Try again later.

🚨 Important Note for Real-Time Authorization Card Programs

Only the response codes listed above may be used to reply to an authorization request webhook.

Using any other response codes may result in the transaction being declined with a generic R12 code and may lead to misrouting or support confusion.