# Glomo Webhooks

## Order Webhooks

Order webhooks notify you about events related to orders.

| Event Type | Description |
|  --- | --- |
|  active  | The order has been created and is awaiting payment. |
|  paid  | The order has been paid successfully. |
|  expired  | The order has expired. |
|  action_required  | The order needs more details to be processed. |
|  under_review  | The order is under review. |
|  failed  | The order has failed. |


### Sample Payload


```Sample
{
    "entity_type": "orders",
    "event_type": "paid",
    "data": {
        "id": "order_6819d8046mpKt",
        "customer_id": "cust_6819d7d0lrLvP",
        "document_id": null,
        "status": "paid",
        "currency": "USD",
        "amount": 10000,
        "purpose_code": "P0014",
        "invoice_number": null,
        "invoice_description": "",
        "invoice_amount": 0,
        "reference_number": "REF1234",
        "product": {
            "name": "product name",
            "description": "product description"
        },
        "payment_methods": "card",
        "created_at": "2025-05-06T09:36:04Z",
        "updated_at": "2025-05-08T13:12:54Z",
        "rfi_documents": {
            "rfi_doc_id": "rfi_doc_123",
            "name": "Passport"
        },
        "notes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}
```

## Payment Webhooks

Payment webhooks notify you about events related to payment processing.

| 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. |
|  failed  | The payment has failed. |
|  funds_available  | Funds are available with Glomo and can be included in a payout or settlement |


### 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": "swift_transfer",
      "id": "swift_686f7cc3sSnky",
      "details": {
        "sender_name": "Test Name",
        "sender_country": "IND",
        "sender_account_number": "50100116025317",
        "sender_bank_name": "HDFC Bank",
        "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,
    "error_message": null,
    "funds_available": false
  }
}
```

## Payment Link Webhooks

Payment Link webhooks notify you about events related to payment links.

| Event Type | Description |
|  --- | --- |
|  active  | The payment link has been created and is awaiting payment. |
|  paid  | The payment link has been paid successfully. |
|  partially_paid  | The payment link has been partially paid. |
|  action_required  | The payment link needs more details to be processed.. |
|  expired  | The payment link has expired. |
|  under_review  | The payment link is under review. |
|  cancelled  | The payment link has been cancelled. |
|  failed  | The payment link couldn't be created. |


### Sample Payload


```Sample
{
  "entity_type": "payment_link",
  "event_type": "success",
  "data": {
    "id": "plink_6819d8046mpKt",
    "customer_id": "cust_6819d7d0lrLvP",
    "document_id": null,
    "status": "paid",
    "currency": "USD",
    "amount": 10000,
    "purpose_code": "P0014",
    "expires_at": "2025-05-15T18:30:00Z",
    "last_reminder_sent_at": "2025-05-06T09:36:12Z",
    "invoice_amount": 0,
    "invoice_description": "",
    "invoice_number": null,
    "payment_link": "https://glomopay.com/payment-links/plink_6819d8046mpKt",
    "reminder_frequency": 0,
    "created_at": "2025-05-06T09:36:04Z",
    "updated_at": "2025-05-08T13:12:54Z",
    "notes": {
      "key1":"value1",
      "key2":"value2"
    }
  }
}
```

## Payout Webhooks

Payout webhooks notify you about payout lifecycle events.

| Event Type | Description |
|  --- | --- |
|  pending_approval  | The payout has been submitted under maker-checker and is awaiting approval. |
|  in_progress  | The payout has been accepted and is being processed. |
|  action_required  | The payout requires more details to be processed. |
|  success  | The payout has been successfully processed. |
|  failed  | The payout has failed. |
|  cancelled  | The payout has been cancelled. Includes auto-cancellation when a linked quote expires before submission, in which case `error_code` is `QUOTE_EXPIRED`. |


### Sample Payload


```Sample
{
  "entity_type": "payout",
  "event_type": "in_progress",
  "data": {
    "id": "payout_9z8y7x6w5v",
    "beneficiary_id": "bene_a1b2c3d4e5",
    "source_amount": 100000,
    "source_currency": "USD",
    "destination_amount": 8235000,
    "destination_currency": "INR",
    "purpose_code": "PYR002",
    "status": "in_progress",
    "fees": {
      "txn_fee": {
        "currency": "USD",
        "amount": 500
      },
      "fx_fee": {
        "currency": "USD",
        "amount": 250
      }
    },
    "mid_market_rate": {
      "currency": "INR",
      "rate": 83.12
    },
    "documents": [
      "doc_11aa22bb33"
    ],
    "utr": null,
    "created_at": "2026-06-03T10:20:00Z",
    "updated_at": "2026-06-03T10:20:00Z",
    "fee_collection_mode": "merchant",
    "request_id": "req-7f3a9c20",
    "payment_rail": "neft",
    "invoice_number": "INV-2026-001",
    "notes": {
      "internal_ref": "batch-42"
    },
    "error_code": null,
    "error_description": null,
    "quote_id": "quote_3m4n5o6p7q"
  }
}
```

## Beneficiary Webhooks

Beneficiary webhooks notify you about beneficiary lifecycle events.

| Event Type | Description |
|  --- | --- |
|  active  | The beneficiary has been approved and is active. |
|  rejected  | The beneficiary has been rejected. |


### Sample Payload


```Sample
{
  "entity_type": "beneficiary",
  "event_type": "active",
  "data": {
    "id": "bene_6989dfe1AgGFI",
    "name": "Test auto approve 2",
    "category": "payout",
    "email": "finance@acme.com",
    "phone": "+14155551234",
    "nickname": "ACME Primary Account",
    "status": "active",
    "created_at": "2026-02-09T13:23:45Z",
    "updated_at": "2026-02-09T13:24:42Z",
    "type": "business",
    "documents": [
      "doc_68e7980auYRAs"
    ],
    "address": {
      "address_line1": "123 Business Park",
      "address_line2": "Suite 100",
      "city": "New York",
      "state": "NY",
      "country_code": "USA",
      "postal_code": "10001"
    },
    "bank_account": {
      "account_number": "1234657557",
      "name": "Citibank NA",
      "swift_code": "CITIUS33",
      "local_routing_number": "021000089",
      "currency": "USD",
      "address": {
        "address_line1": "388 Greenwich Street",
        "address_line2": null,
        "city": "New York",
        "state": "NY",
        "country_code": "USA",
        "postal_code": "10013"
      },
      "intermediate_bank": {
        "name": "JPMorgan Chase Bank",
        "country": "USA",
        "swift_code": "CHASUS33",
        "account_number": "123456789"
      }
    },
    "upi_account": null
  }
}
```

## Refund Webhooks

Refund webhooks notify you about refund lifecycle events.

| Event Type | Description |
|  --- | --- |
|  success  | The refund has been successfully processed. |
|  action_required  | The refund requires more details to be processed. |
|  failed  | The refund failed. |


### Sample Payload


```Sample
{
  "entity_type": "refund",
  "event_type": "success",
  "data": {
    "id": "refund_682c42dfkOVpL",
    "payment_id": "payt_681cadccoSbsj",
    "customer_id": "cust_6819d7d0lrLvP",
    "amount": 10000,
    "currency": "USD",
    "balance_used": {
      "currency": "USD",
      "amount": 10000
    },
    "status": "success",
    "reason": "Requested By Customer",
    "fees": {
      "fx_fees": {
        "currency": "USD",
        "amount": 0
      },
      "txn_fees": {
        "currency": "USD",
        "amount": 200
      }
    },
    "documents": [],
    "created_at": "2025-05-20T08:52:47Z",
    "updated_at": "2025-05-20T08:53:55Z"
  }
}
```

## Settlement Webhooks

Settlement webhooks notify you about settlement lifecycle events.

| Event Type | Description |
|  --- | --- |
|  initiate  | The settlement has been successfully initiated. |
|  success  | The settlement has been successfully processed. |
|  action_required  | The settlement requires more details to be processed. |
|  failed  | The settlement failed. |
|  cancelled  | The settlement was cancelled by glomo. |


### Sample Payload


```Sample
{
  "entity_type": "settlement",
  "event_type": "success",
  "data": {
    "id": "setl_688774f9Iny7U",
    "status": "success",
    "payment_method": "swift_transfer",
    "amount": 29100,
    "currency": "USD",
    "fees": {
      "fx_fee": {
        "amount": 0,
        "currency": "USD"
      },
      "txn_fee": {
        "amount": 288,
        "currency": "USD"
      }
    },
    "utr": "HDFC123456789012",
    "created_at": "2025-07-28T13:02:49.572Z",
    "updated_at": "2025-07-28T13:05:40.216Z",
    "receipt_ids": [
      "doc_6829c85fm0s0Z"
    ]
  }
}
```

## Internal Transfer Webhooks

Internal Transfer webhooks notify you about events related to internal transfers between merchant accounts.

| Event Type | Description |
|  --- | --- |
|  success  | The internal transfer has been successfully processed. |
|  failed  | The internal transfer has failed. |


### Sample Payload


```Sample
{
  "entity_type": "internal_transfer",
  "event_type": "success",
  "data": {
    "id": "inttransfer_68ef608dXUXqr",
    "from_merchant_id": "merch_68cc1216xPrdU",
    "to_merchant_id": "merch_68cc0571y5S4h",
    "owner_merchant_id": "merch_68cc0571y5S4h",
    "transfer_amount": 10000,
    "transfer_currency": "AED",
    "reference": "Test internal transfer",
    "fees": {
      "txn_fee": {
        "currency": "AED",
        "amount": 0
      },
      "fx_fee": {
        "currency": "AED",
        "amount": 0
      }
    },
    "error_code": null,
    "error_description": null,
    "created_at": "2025-10-15T08:51:25Z",
    "updated_at": "2025-10-15T08:51:25Z"
  }
}
```

## Subscription Webhooks

Subscription webhooks notify you about events related to subscriptions.

| Event Type | Description |
|  --- | --- |
|  active  | The subscription is active. |
|  authorized  | The subscription has been authorized and recurring payments will start on the scheduled date |
|  cancelled  | The subscription has been cancelled and no further billing will occur. |
|  completed  | The subscription has run its full billing cycle and is complete. |
|  expired  | The subscription has expired and is no longer valid. |
|  halted  | The subscription has been halted and is pending manual reactivation. |
|  paused  | The subscription has been paused. No further payments will be charged until resumed. |
|  updated  | The subscription has been updated. |


### Sample Payload


```Sample
{
    "entity_type": "subscription",
    "event_type": "completed",
    "data": {
        "id": "sub_5JU9yv0lGSUP",
        "customer_id": "cust_5JU9yv0lGSUP",
        "product_name": "ShieldGuard Insurance",
        "product_description": "Flexible, monthly insurance for belongings, travel, and digital assets, easy to manage",
        "plan_name": "ShieldGuard Lite",
        "plan_description": "Simple, monthly insurance plan that covers your basic belongings and key digital assets",
        "reference_number": "R0001",
        "status": "active",
        "amount": 1000,
        "currency": "USD",
        "interval_type": "month",
        "interval_count": 1,
        "billing_cycles": 12,
        "start_date": "2025-01-01",
        "end_date": "2025-12-01",
        "expires_at": "2025-01-07",
        "next_payment_date": "2025-02-01",
        "subscription_link_url": "https://glomopay.com/subscription/sub_5JU9yv0lGSUP",
        "cancelled_at": "2025-01-15",
        "notes": {
            "key1": "value1",
            "key2": "value2"
        }
    }
}
```

## Merchant Webhooks

Merchant webhooks notify you about lifecycle events related to a merchant account. This applies to partner platform merchants only.

| Event Type | Description |
|  --- | --- |
|  action_required  | Glomo requires additional information about the business to proceed with the onboarding |
|  pending  | The merchant is pending onboarding on Glomo's end. |
|  success  | The merchant onboarding completed successfully. |
|  offboarded  | The merchant has been offboarded and access has been revoked. |


### Sample Payload


```Sample
{
  "data": {
    "entity_type": "merchant",
    "event_type": "success",
    "data": {
      "owner_merchant_id": "merch_6909a7b8z9ZHi",
      "merchant_id": "merch_696f362cYrLa1",
      "status": "success",
      "name": "merchant name",
      "registration_number": "your registration number",
      "registration_country": "IND",
      "address": {
        "address_line1": "123 Main St",
        "address_line2": "",
        "city": "Bangalore",
        "state": "Karnataka",
        "pincode": "560060",
        "country": "IND"
      },
      "operation_countries": [
        "IND"
      ],
      "entity_type": "individual",
      "category": "Agricultural Services",
      "sub_category": "Veterinary Services",
      "created_at": "2026-01-20T08:00:44Z",
      "updated_at": "2026-01-20T08:00:44Z",
      "jwt_token": "jwt_token",
      "public_key": "public_key",
      "gender": "male",
      "date_of_birth": "2001-08-04"
    }
  }
}
```

## Virtual Account Webhooks

Virtual account webhooks notify you about virtual account lifecycle events.

| Event Type | Description |
|  --- | --- |
|  active  | Virtual account is activated successfully |
|  inactive  | Virtual account is marked as inactive |


### Sample Payload

#### AED


```Sample
{
  "entity_type": "virtual_account",
  "event_type": "active",
  "data": {
    "account_id": "va_695b907fS58rY",
    "currency": "AED",
    "name": "Test Merchant Name",
    "status": "active",
    "merchant_id": "merch_694bb0289P4Cz",
    "created_at": "2026-01-05T10:20:47Z",
    "updated_at": "2026-01-05T10:20:47Z",
    "account_number": "AE580863912382801669068"
  }
}
```

#### EUR


```Sample
{
  "entity_type": "virtual_account",
  "event_type": "active",
  "data": {
    "account_id": "va_695b8fbaWj7bp",
    "currency": "EUR",
    "name": "Test Merchant Name",
    "status": "active",
    "merchant_id": "merch_694bb0289P4Cz",
    "created_at": "2026-01-05T10:17:30Z",
    "updated_at": "2026-01-05T10:17:30Z",
    "iban": "DK2089000025417759"
  }
}
```

#### GBP


```Sample
{
  "entity_type": "virtual_account",
  "event_type": "active",
  "data": {
    "account_id": "va_695b8fbaKQL3s",
    "currency": "GBP",
    "name": "Test Merchant Name",
    "status": "active",
    "merchant_id": "merch_694bb0289P4Cz",
    "created_at": "2026-01-05T10:17:30Z",
    "updated_at": "2026-01-05T10:25:36Z",
    "account_number": "25417759",
    "sort_code": "608382"
  }
}
```

#### AUD


```Sample
{
  "entity_type": "virtual_account",
  "event_type": "active",
  "data": {
    "account_id": "va_695b91dfpy8QG",
    "currency": "AUD",
    "name": "Test Merchant Name",
    "status": "active",
    "merchant_id": "merch_694bb0289P4Cz",
    "created_at": "2026-01-05T10:26:39Z",
    "updated_at": "2026-01-05T10:26:39Z",
    "account_number": "025417789",
    "bsb_number": "252000"
  }
}
```

#### USD ACH


```Sample
{
  "entity_type": "virtual_account",
  "event_type": "active",
  "data": {
    "account_id": "va_695cc483YWZHQ",
    "currency": "USD",
    "name": "Test Merchant Name",
    "status": "active",
    "merchant_id": "merch_694bb0289P4Cz",
    "created_at": "2026-01-06T08:14:59Z",
    "updated_at": "2026-01-06T08:14:59Z",
    "account_number": "5277155107",
    "routing_number": "111000025",
    "payment_rails": "ach"
  }
}
```

#### USD Fedwire


```Sample
{
  "entity_type": "virtual_account",
  "event_type": "active",
  "data": {
    "account_id": "va_695cc483wlI4h",
    "currency": "USD",
    "name": "Test Merchant Name",
    "status": "active",
    "merchant_id": "merch_694bb0289P4Cz",
    "created_at": "2026-01-06T08:14:59Z",
    "updated_at": "2026-01-06T08:14:59Z",
    "account_number": "5277155107",
    "routing_number": "026009593",
    "payment_rails": "wire"
  }
}
```

## KYC Journey Webhooks

KYC Journey webhooks notify you about KYC verification lifecycle events.

| Event Type | Description |
|  --- | --- |
|  initiated  | The KYC verification has been initiated. |
|  in_progress  | The KYC verification is being processed. |
|  completed  | The KYC verification has been completed successfully. |
|  rejected  | The KYC verification has been rejected. |
|  action_required  | The KYC verification requires additional information to proceed. |
|  under_review  | The KYC verification is under review. |
|  failed  | The KYC verification failed. The `failure_reason` field describes the cause. |


### Sample Payload


```Sample
{
  "entity_type": "kyc_journey",
  "event_type": "completed",
  "data": {
    "id": "kyc_6819d8046mpKt",
    "status": "completed",
    "customer_id": "cust_6819d7d0lrLvP",
    "bank_enabled": true,
    "bank_name": "HDFC bank"
  }
}
```

### Sample Payload — Failed


```Sample
{
  "entity_type": "kyc_journey",
  "event_type": "failed",
  "data": {
    "id": "kyc_6819d8046mpKt",
    "status": "failed",
    "customer_id": "cust_6819d7d0lrLvP",
    "failure_reason": "CKYC bureau verification failed with prefilled data"
  }
}
```

> **Note:** `customer_id` is `null` for KYC links created with an email address only (no existing customer record). Consumers should handle this case.


> **Note:** `bank_enabled` and `bank_name` are only present when the KYC journey is part of an LRS (Liberalised Remittance Scheme) flow, initiated via a Payment Session. `bank_enabled` indicates whether the customer's bank is supported for LRS remittance. `bank_name` is the human-readable name of the resolved bank (e.g. `"HDFC bank"`, `"Axis bank"`). Both fields are omitted for standalone KYC journeys not linked to an LRS Payment.


## Balance Webhooks

Balance webhooks notify you about credits to your Funded Balance. They apply only to merchants on the Funded Balance model.

When an Add Balance top-up succeeds, the standard [Payment webhook](#payment-webhooks) also fires for the Add Fund payment (`event_type: success`, with `payin_type: add_funds`).

| Event Type | Description |
|  --- | --- |
|  balance.funded_balance.credited  | An Add Balance top-up has been credited to the Funded Balance. |


### Sample Payload


```Sample
{
  "entity_type": "balance",
  "event_type": "balance.funded_balance.credited",
  "data": {
    "payment_id": "addfunds_691eeb9aV79Uk",
    "amount": 5000000,
    "currency": "USD",
    "bank_transfer_reference": "UTR123456789012",
    "funds_credit_date": "2026-05-20",
    "balance_available_after_credit": 12500000,
    "balance_pending_after_credit": 0,
    "timestamp": "2026-05-12T10:20:47Z"
  }
}
```

| Field | Description |
|  --- | --- |
| `payment_id` | Identifier of the Add Fund payment that credited the balance. |
| `amount` | Credited amount, in the smallest currency unit (see [Understanding Payment Amounts](#understanding-payment-amounts)). |
| `currency` | Currency of the credit, in [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217) format. |
| `bank_transfer_reference` | Reference of the inbound bank transfer (e.g. UTR). `null` if not yet available. |
| `funds_credit_date` | Date the funds were credited. `null` if not available. |
| `balance_available_after_credit` | Funded Balance available (this currency) after the credit, in the smallest currency unit. |
| `balance_pending_after_credit` | Funded Balance pending (this currency) after the credit, in the smallest currency unit. |
| `timestamp` | Event time, in ISO 8601 format. |