# Payment Webhooks

Payment webhooks notify you about events related to payment processing.

> **Note:** The sample payloads on this page are pretty-printed. The body Glomo sends is the RFC 8785 canonical form of the same object, and the `X-Glomopay-Signature` header is computed over those bytes. See [Webhook Authentication & Security](/platform/webhooks#webhook-authentication--security).


Payments with `payin_type: add_funds` represent a direct wallet top-up and fire only as `event_type: success`.

| Event Type | Description |
|  --- | --- |
|  success  | The payment has been successfully processed. |
|  in_progress  | The payment is being processed. |
|  action_required  | The payment needs more details to be processed. |
|  under_review  | The payment is under review (e.g. after RFI documents are submitted). |
|  failed  | The payment has failed. |
|  funds_available  | Funds are available with Glomo and can be included in a payout or settlement |
|  compliance_action_required  | The payment has been flagged for a compliance review and requires additional documents. See `compliance_status` and `rfi` in the payload. |
|  compliance_under_review  | The requested documents have been submitted and are being reviewed. |
|  compliance_approved  | The compliance review is complete and the payment has been cleared. |
|  compliance_rejected  | The compliance review is complete and the payment has been rejected. |


## Understanding Payment Amounts

The payment webhook includes three different amount fields that represent different stages of the payment flow:

| Field | Description | Example |
|  --- | --- | --- |
| `requested_amount``requested_currency` | The original amount the merchant requested (in settlement currency, excluding customer-borne fees) | Merchant requests $1,000 USD |
| `payment_amount``payment_currency` | The total amount the customer pays (in order currency, includes customer-borne fees) | Customer pays 3,745.80 AED (includes 1% txn fee + 1% FX fee) |
| `converted_amount``converted_currency` | The final amount after currency conversion (in settlement currency, includes all fees) | Total amount received is $1,020 USD |


**Fees Breakdown:**

- `txn_fee`: Transaction processing fee
- `fx_fee`: Foreign exchange/currency conversion fee
- `referral_fee`: Referral or platform fee (if applicable)


**Note on amounts:** All amounts are represented in the smallest currency unit. For example, if the amount is $299.00, then 29900 is passed in this field. In the case of three decimal currencies, such as KWD, BHD and OMR, to represent an amount of 295.991, we will pass the value as 295990. And in the case of zero decimal currencies such as JPY, for amount ￥295, we will pass the value as 295.

## Sample Payload

```Sample
{
  "entity_type": "payment",
  "event_type": "in_progress",
  "data": {
    "id": "payt_686f7cc3pe69T",
    "payin_id": "order_686f7c8c7txqj",
    "payin_type": "orders",
    "customer_id": "cust_686f7c6evv6Nv", // only valid for regular businesses
    "merchant_id": "merch_68cc1216xPrdU", // only valid for platform businesses
    "product_name": null,
    "product_description": null,
    "status": "active",
    "payment_amount": 374580,
    "payment_currency": "AED",
    "converted_amount": 102000,
    "converted_currency": "USD",
    "requested_amount": 100000,
    "requested_currency": "USD",
    "purpose_code": "P1301",
    "sender_name": "SHORYA KUMAR PRADEEP",
    "paid_at": null,
    "country": "IND",
    "fees": {
      "txn_fee": {
        "currency": "USD",
        "amount": 1000
      },
      "fx_fee": {
        "currency": "USD",
        "amount": 1000
      },
      "referral_fee": {
        "currency": "USD",
        "amount": 0
      }
    },
    "documents": [],
    "payment_method": {
      "type": "bank_transfer",
      "details": {
        "sender_name": "Test Name",
        "sender_account_number": "50100116025317",
        "receiver_account_number": "98765432109876",
        "sender_country": "IND",
        "sender_bank_name": "JPMORGAN CHASE BANK,N.A.",
        "sender_bank_country": "USA",
        "sender_bank_address": "270 Park Avenue, New York",
        "swift_code": "CHASUS33",
        "local_routing_number": null,
        "external_reference": "GLM7A2C1",
        "transfer_type": "swift",
        "remittance_information": "Test Remittance Information"
      }
    },
    "fee_bearer": "customer",
    "created_at": "2025-07-10T08:41:39Z",
    "updated_at": "2025-07-10T08:41:52Z",
    "error_code": null,
    "error_description": null,
    "customer_error_description": null,
    "error_message": null,
    "funds_available": false
  }
}
```

## Sample Payload — Compliance Action Required

- `compliance_status` and `rfi` are present on every payment webhook event once a payment has been screened — not only on `compliance_action_required`.
- `rfi.documents_required` and `rfi.response_deadline` are present only when `compliance_status` is `action_required`.
- Other compliance events (`compliance_under_review`, `compliance_approved`, `compliance_rejected`) include `rfi.id`, `rfi.reason_code_description` and `rfi.reason_code`, without `documents_required` or `response_deadline`.


```Sample
{
  "entity_type": "payment",
  "event_type": "compliance_action_required",
  "data": {
    "id": "payt_686f7cc3pe69T",
    "status": "success",
    "compliance_status": "action_required",
    "rfi": {
      "id": "rfi_6a72a39b38jDD",
      "reason_code_description": "The payment has been flagged for a compliance review and requires additional information before it can credited to your account.",
      "reason_code": "COMPLIANCE_REVIEW",
      "documents_required": [
        {
          "rfi_doc_id": "rfidoc_6a72a39bGslYe",
          "description": "Upload documents supporting this payment: invoice matching the transaction amount and date, card statement for the billing cycle containing this transaction, bank statement showing the card bill repayment, proof of source of funds for the repaying account, and a note stating the purpose of the transfer.",
          "multiple_allowed": true,
          "max_count": 15
        },
        {
          "rfi_doc_id": "rfidoc_6a72a39b38jDD",
          "description": "Passport",
          "multiple_allowed": false,
          "max_count": 1
        }
      ],
      "response_deadline": "2026-08-21T10:29:00Z"
    },
    "payment_amount": 374580,
    "payment_currency": "AED",
    "funds_available": false
    // ...remaining fields are the same as any other payment webhook, see the sample payload above
  }
}
```