# Run payment accounts for your customers

This guide takes one customer from onboarding to a payout. You create the customer, which opens their payment account. The customer then adds funds with a card. You show the balance and the statement, and you send money to a beneficiary. [Payment accounts](/payment-accounts) explains the account, its balances and its statuses.

All request and response bodies on this page are examples. IDs, amounts and rates are illustrative. The [API reference](/api-reference/openapi) has the full schemas.

## Before you start

- **Secret key.** Make every call from your server, with your secret key as the bearer token. See [Authentication](/platform/authentication). The base URL is `https://api.glomopay.com/api` for test and live. The key decides the environment.
- **KYC record.** You need the customer's name, date of birth, nationality, address and the date of your last KYC check. Send the PAN when you hold one.
- **Webhooks.** Register a webhook URL to receive `payout` events. See [Webhooks](/platform/webhooks). If you have no active webhook endpoint, Glomo does not send payout events.
- **Amounts.** All amounts are integers in minor units. USD has two decimals, so `100000` is USD 1,000.00.


| Step | Call |
|  --- | --- |
| 1. Onboard the customer | `POST /v1/customer`, then `GET /v1/payment-accounts?customer_id=` |
| 2. Add funds with a card | `POST /v1/payment-accounts/{id}/orders`, the Glomo checkout, then `GET /v1/payment-accounts/{id}/orders/{order_id}` |
| 3. Show the balance and the statement | `GET /v1/payment-accounts/{id}`, `GET /v1/payment-accounts/{id}/transactions` |
| 4. Send money | `POST /v1/payment-accounts/{id}/beneficiaries`, `POST .../quotes/preview`, `POST .../quotes`, `POST .../payouts`, then payout webhooks |


## Step 1: Onboard the customer

### Create the customer

**`createCustomer`** · `POST /v1/customer` · [API reference](/api-reference/openapi/customer/createcustomer)

Create the customer once, with the KYC record you hold. Glomo opens the customer's payment account in the same call. The response is the customer object. It does not include the payment account.

These fields have rules for a payment account customer:

| Field | Required | Rule |
|  --- | --- | --- |
| `dob` | Yes | `YYYY-MM-DD`. Must be before today. |
| `nationality` | Yes | ISO 3166-1 alpha-3, for example `IND`. |
| `kyc.last_kyc_date` | Yes | The date of your last KYC check, `YYYY-MM-DD`. Can be today. Cannot be in the future. |
| `kyc.pan_number` | No | A valid PAN in upper case. |


`kyc` accepts only `pan_number` and `last_kyc_date`. Other keys return `400`.

```curl
curl -i -X POST \
  'https://api.glomopay.com/api/v1/customer' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Aarav Nair",
    "customer_type": "individual",
    "email": "aarav.nair@example.com",
    "phone": "+971501234567",
    "address": "Unit 1204, Marina Heights",
    "city": "Dubai",
    "state": "Dubai",
    "country": "ARE",
    "pincode": "00000",
    "dob": "1988-04-17",
    "nationality": "IND",
    "kyc": {
      "pan_number": "ABCDE1234F",
      "last_kyc_date": "2026-09-25"
    }
  }'
```

The response is `201 Created` with the customer. Keep its `id`, for example `cust_6ab599fdEvVur`.

Create each customer only once. A second create call for the same customer returns `400`. To find the account of a customer you already created, use List payment accounts.

To update the customer later, use [Update a customer](/api-reference/openapi/customer/updatecustomer) (`PATCH /v1/customer/{id}`). For a payment account customer it takes `email`, `phone`, the address fields and `kyc.last_kyc_date`.

### Find the payment account

**`listPaymentAccounts`** · `GET /v1/payment-accounts` · [API reference](/api-reference/openapi/payment_account/listpaymentaccounts)

Send the customer ID as `customer_id` to get the account that Create a customer opened. Store the account `id` with your customer record.

```curl
curl -i -X GET \
  'https://api.glomopay.com/api/v1/payment-accounts?customer_id=cust_6ab599fdEvVur' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
```

```json
{
  "data": [
    {
      "id": "pacct_6ab59a10Hk3Zq",
      "customer_id": "cust_6ab599fdEvVur",
      "status": "active",
      "created_at": "2026-10-15T09:15:33Z",
      "updated_at": "2026-10-15T09:15:33Z"
    }
  ],
  "page_meta": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 20,
    "pages": 1,
    "count": 1
  }
}
```

The account opens as `active`. If your agreement with Glomo needs the customer's consent first, the account opens as `draft` and becomes `active` when the customer gives consent. A `draft` account cannot receive funds or send payouts, so read `status` before you offer Add funds.

## Step 2: Add funds with a card

### Create an add-funds order

**`createPaymentAccountOrder`** · `POST /v1/payment-accounts/{id}/orders` · [API reference](/api-reference/openapi/payment_account/createpaymentaccountorder)

Create an order for the amount to add. The account is credited the order amount. When a card fee applies, the card is charged the order amount plus the fee, and the fee shows on the statement line in `fees`. The card is charged in USD. When the card is in another currency, the card issuer converts the amount.

| Field | Required | Rule |
|  --- | --- | --- |
| `amount` | Yes | A JSON integer in minor units, above zero. A string such as `"100000"` returns `400`. |
| `currency` | Yes | `USD`. |
| `request_id` | No | Your ID for the order. On the same account, a repeated value returns the original order. Use a value that is unique to you, for example with your own prefix. |


```curl
curl -i -X POST \
  'https://api.glomopay.com/api/v1/payment-accounts/pacct_6ab59a10Hk3Zq/orders' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": 100000,
    "currency": "USD",
    "request_id": "acme-load-0001"
  }'
```

Example response, `201 Created`, trimmed:

```json
{
  "id": "paload_6ab59a06f9xuk",
  "customer_id": "cust_6ab599fdEvVur",
  "payment_account_id": "pacct_6ab59a10Hk3Zq",
  "status": "active",
  "currency": "USD",
  "amount": 100000,
  "remaining_amount": 100000,
  "already_paid_amount": 0,
  "expires_at": "2027-01-15T09:15:42Z",
  "request_id": "acme-load-0001",
  "checkout_url": "https://api.glomopay.com/api/public/v1/checkout/redirect?resource_id=paload_6ab59a06f9xuk&public_key=live_6ab59a01EXAMPLE1"
}
```

The order expires 3 months after it is created.

| HTTP | `code` or `message` | Meaning |
|  --- | --- | --- |
| `400` | `Payment account cannot accept money` | The account is not `active`. |
| `400` | `Order already exists for this request_id` | This `request_id` is already in use. Send a new one. |
| `404` | Not found | The account does not exist or you do not own it. |
| `422` | `order_amount_above_cap` | The amount is above the order limit for the currency. |
| `422` | `order_cap_unavailable` | No order limit is set for the currency, so the order is refused. |


### Open the checkout

The Glomo checkout collects the card, checks that Glomo can take it, runs 3D Secure and charges it. The card data goes directly to Glomo and never passes through your servers.

Open the checkout with the order's `checkout_url`, or with the order ID and the public key in that URL. Always take the public key from `checkout_url`.

- **Web.** Use the [Glomo Unified SDK](/platform/sdk/unified-sdk) with `orderId` and the `public_key` from `checkout_url`.
- **Native app.** Open `checkout_url` in a WebView as a top-level page, as the API returned it. See [Web Checkout in a Mobile App (WebView)](/platform/sdk/experimental). Do not `fetch()` the URL and do not add `mode`.


```html
<button id="add-funds-button">Add funds</button>
<script type="module">
  import { GlomoCheckoutApi } from 'https://unified-sdk.glomopay.com/index.js';

  const checkout = new GlomoCheckoutApi({
    publicKey: '<PUBLIC_KEY_FROM_CHECKOUT_URL>',
    orderId: 'paload_6ab59a06f9xuk',
  });

  checkout.on('payment.success', function (response) {
    // Tell your server. Your server confirms the result with Get an add-funds order.
    window.location.href = '/wallet/add-funds/result?order=' + response.orderId;
  });

  checkout.on('payment.failure', function (response) {
    window.location.href = '/wallet/add-funds/failed?order=' + response.orderId;
  });

  checkout.on('checkout.closed', function () {
    // The customer closed the checkout. Nothing was charged.
  });

  document.getElementById('add-funds-button').addEventListener('click', () => {
    checkout.open();
  });
</script>
```

| Event | Meaning |
|  --- | --- |
| `payment.success` | The card payment succeeded. Confirm it on your server before you show funds as added. |
| `payment.failure` | The card was declined or the payment did not complete. The order stays payable, so the customer can try again. |
| `checkout.closed` | The customer closed the checkout. Nothing was charged. |


### Confirm the result on your server

**`getPaymentAccountOrder`** · `GET /v1/payment-accounts/{id}/orders/{order_id}` · [API reference](/api-reference/openapi/payment_account/getpaymentaccountorder)

When the checkout reports a result, call Get an add-funds order from your server and use its `status` as the result. Do not credit the customer on a client-side event alone.

```curl
curl -i -X GET \
  'https://api.glomopay.com/api/v1/payment-accounts/pacct_6ab59a10Hk3Zq/orders/paload_6ab59a06f9xuk' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
```

| Order `status` | Show the customer |
|  --- | --- |
| `paid` | Payment received. Read the balances with Get a payment account. |
| `active` | Not paid yet. The customer can try again. |
| `expired`, `cancelled`, `failed` | The order cannot be paid. Create a new order. |


When the order is `paid`, the money is in `pending` until Glomo clears its compliance checks, and then it moves to `available`. On the statement, the card payment line has `funds_available` `false` while the money is in `pending`, and `true` when it is in `available`.

## Step 3: Show the balance and the statement

### Get the balance

**`getPaymentAccount`** · `GET /v1/payment-accounts/{id}` · [API reference](/api-reference/openapi/payment_account/getpaymentaccount)

```curl
curl -i -X GET \
  'https://api.glomopay.com/api/v1/payment-accounts/pacct_6ab59a10Hk3Zq' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
```

```json
{
  "id": "pacct_6ab59a10Hk3Zq",
  "customer_id": "cust_6ab599fdEvVur",
  "status": "active",
  "created_at": "2026-10-15T09:15:33Z",
  "updated_at": "2026-10-15T09:15:33Z",
  "balances": {
    "available": [
      {
        "amount": 40000,
        "currency": "USD"
      }
    ],
    "pending": [
      {
        "amount": 0,
        "currency": "USD"
      }
    ],
    "on_hold": [
      {
        "amount": 60000,
        "currency": "USD"
      }
    ]
  }
}
```

If the balances are not available for a short time, the call returns `500`. Retry it.

### List the statement

**`listPaymentAccountTransactions`** · `GET /v1/payment-accounts/{id}/transactions` · [API reference](/api-reference/openapi/payment_account/listpaymentaccounttransactions)

The statement lists credits and debits, newest first. Filter with `type` (`credit` or `debit`), `currency`, and `before` and `after` on `processed_at`. Page with `page` and `per_page` (default 20, maximum 100).

```curl
curl -i -X GET \
  'https://api.glomopay.com/api/v1/payment-accounts/pacct_6ab59a10Hk3Zq/transactions?after=2026-10-01' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'
```

```json
{
  "data": [
    {
      "id": "pactxn_6ab5a3f1Pq8Wm",
      "type": "debit",
      "amount": 60000,
      "currency": "USD",
      "funds_available": null,
      "source": {
        "type": "payout",
        "id": "payout_6ab5a2e7Tn4Yc"
      },
      "processed_at": "2026-10-15T11:02:10Z"
    },
    {
      "id": "pactxn_6ab59b40Lx2Rb",
      "type": "credit",
      "amount": 100000,
      "currency": "USD",
      "funds_available": true,
      "source": {
        "type": "payment",
        "id": "payt_6ab59b22oXGRy"
      },
      "processed_at": "2026-10-15T09:18:05Z"
    }
  ],
  "page_meta": {
    "current": 1,
    "previous": null,
    "next": null,
    "per_page": 20,
    "pages": 1,
    "count": 2
  }
}
```

### Show a receipt

**`getPaymentAccountTransaction`** · `GET /v1/payment-accounts/{id}/transactions/{txn_id}` · [API reference](/api-reference/openapi/payment_account/getpaymentaccounttransaction)

Get a transaction returns the statement line with the details a receipt needs: `source.status`, `status_history`, the fees the customer paid, and for a payout the beneficiary, the conversion and the rail. For a card payment it also returns the card brand, type and last four digits. The API reference has an example of each.

## Step 4: Send money

### Add a beneficiary

**`createPaymentAccountBeneficiary`** · `POST /v1/payment-accounts/{id}/beneficiaries` · [API reference](/api-reference/openapi/payment_account/createpaymentaccountbeneficiary)

Add the bank account or UPI ID that the customer sends money to. The beneficiary belongs to this payment account and receives payouts only from it. The body is the same as [Create a beneficiary (v2)](/api-reference/openapi/beneficiary_v2/createbeneficiaryv2), with these differences:

- `category` is `payout`, and it is the default. Any other value returns `400`.
- `beneficiary.documents` returns `400`.


```curl
curl -i -X POST \
  'https://api.glomopay.com/api/v1/payment-accounts/pacct_6ab59a10Hk3Zq/beneficiaries' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "category": "payout",
    "beneficiary": {
      "name": "Aarav Nair",
      "type": "individual",
      "email": "aarav.nair@example.com",
      "nickname": "My NRE account",
      "address": {
        "address_line1": "12 Marina Walk",
        "city": "Kochi",
        "state": "Kerala",
        "country_code": "IND",
        "postal_code": "682001"
      }
    },
    "bank_account": {
      "account_number": "000111222333",
      "local_routing_number": "HDFC0000123",
      "currency": "INR"
    }
  }'
```

Example response, `201 Created`:

```json
{
  "id": "bene_6ab5a1c9gflRf",
  "payment_account_id": "pacct_6ab59a10Hk3Zq",
  "name": "Aarav Nair",
  "category": "payout",
  "type": "individual",
  "email": "aarav.nair@example.com",
  "phone": null,
  "nickname": "My NRE account",
  "status": "active",
  "notes": null,
  "address": {
    "address_line1": "12 Marina Walk",
    "address_line2": null,
    "city": "Kochi",
    "state": "Kerala",
    "country_code": "IND",
    "postal_code": "682001"
  },
  "bank_account": {
    "account_number": "000111222333",
    "name": "HDFC Bank",
    "swift_code": null,
    "local_routing_number": "HDFC0000123",
    "currency": "INR",
    "category": null,
    "address": {
      "address_line1": "MG Road",
      "address_line2": null,
      "city": "Kochi",
      "state": "Kerala",
      "country_code": "IND",
      "postal_code": null
    },
    "intermediate_bank": null
  },
  "upi_account": null,
  "created_at": "2026-10-15T10:40:12Z",
  "updated_at": "2026-10-15T10:40:12Z"
}
```

A new beneficiary is `active`, or `pending` while Glomo verifies it. A payout to a `pending` or `rejected` beneficiary returns `400`. If the account already has a beneficiary with the same account number, the call returns `409`.

To list, read or remove beneficiaries, use [List beneficiaries](/api-reference/openapi/payment_account/listpaymentaccountbeneficiaries), [Get a beneficiary](/api-reference/openapi/payment_account/getpaymentaccountbeneficiary) and [Delete a beneficiary](/api-reference/openapi/payment_account/deletepaymentaccountbeneficiary). There is no update call: to change a beneficiary, delete it and add it again.

### Preview the price

**`previewPaymentAccountQuote`** · `POST /v1/payment-accounts/{id}/quotes/preview` · [API reference](/api-reference/openapi/payment_account/previewpaymentaccountquote)

Show the customer the rate, the fees and the amount the beneficiary receives. A preview saves nothing, so it has no `id` and no `expires_at`. Call it each time the customer changes the amount.

| Field | Rule |
|  --- | --- |
| `resource` | `payout`. Any other value returns `400`. |
| `source_amount` or `destination_amount` | Send one, as an integer in minor units. Send `destination_amount` when the customer types the amount the beneficiary must get. |
| `source_currency`, `destination_currency` | Required. |
| `payment_method` | `type` `bank_transfer` and `subtype` `local_transfer` or `swift_transfer`. |


A `local_transfer` to INR returns one price for each rail that the amount fits: `upi` up to ₹1 lakh, `imps` up to ₹5 lakh and `neft` up to ₹1 crore.

```curl
curl -i -X POST \
  'https://api.glomopay.com/api/v1/payment-accounts/pacct_6ab59a10Hk3Zq/quotes/preview' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "resource": "payout",
    "source_currency": "USD",
    "destination_currency": "INR",
    "source_amount": 60000,
    "payment_method": {
      "type": "bank_transfer",
      "subtype": "local_transfer"
    }
  }'
```

Example response, `200 OK`, trimmed to one rail:

```json
{
  "quotes": [
    {
      "resource": "payout",
      "resource_type": null,
      "payment_account_id": "pacct_6ab59a10Hk3Zq",
      "payment_method": {
        "type": "bank_transfer",
        "subtype": "local_transfer",
        "rail": "imps"
      },
      "source_currency": "USD",
      "destination_currency": "INR",
      "fx_rate": 88.2,
      "effective_fx_rate": 87.8325,
      "source_amount": 60000,
      "destination_amount": 5225850,
      "fees": {
        "txn_fee": {
          "currency": "USD",
          "amount": 500
        },
        "fx_fee": {
          "currency": "USD",
          "amount": 250
        }
      },
      "fee_breakdown": {
        "fx_fee": [
          {
            "amount": 250,
            "currency": "USD",
            "bearer": "merchant",
            "collection_mode": "immediate",
            "taxes": []
          }
        ],
        "txn_fee": [
          {
            "amount": 500,
            "currency": "USD",
            "bearer": "merchant",
            "collection_mode": "immediate",
            "taxes": []
          }
        ],
        "referral_fee": []
      }
    }
  ]
}
```

The amounts follow this formula:

```
(source_amount - txn_fee - fx_fee) x fx_rate = destination_amount
(60000 - 500 - 250) x 88.2 = 5225850
```

### Lock the quote

**`createPaymentAccountQuote`** · `POST /v1/payment-accounts/{id}/quotes` · [API reference](/api-reference/openapi/payment_account/createpaymentaccountquote)

When the customer confirms, send the same body to lock the price. The response has one quote for each rail. Pick the quote for a rail that the beneficiary supports, and send its `id` to Create a payout before `expires_at`. A `upi` quote needs a beneficiary with a UPI ID, and a bank rail such as `imps` or `neft` needs a bank account in the destination currency. A quote expires 30 minutes after it is locked.

A quote does not hold funds. The balance is checked when you create the payout. A quote pays one payout only, and only from the account that locked it.

Example response, `201 Created`, trimmed to one rail:

```json
{
  "quotes": [
    {
      "id": "quote_6ab5a2d4Wc7Nh",
      "resource": "payout",
      "resource_type": null,
      "payment_account_id": "pacct_6ab59a10Hk3Zq",
      "expires_at": "2026-10-15T11:30:20Z",
      "payment_method": {
        "type": "bank_transfer",
        "subtype": "local_transfer",
        "rail": "imps"
      },
      "source_currency": "USD",
      "destination_currency": "INR",
      "fx_rate": 88.2,
      "effective_fx_rate": 87.8325,
      "source_amount": 60000,
      "destination_amount": 5225850,
      "fees": {
        "txn_fee": {
          "currency": "USD",
          "amount": 500
        },
        "fx_fee": {
          "currency": "USD",
          "amount": 250
        }
      },
      "fee_breakdown": {
        "fx_fee": [
          {
            "amount": 250,
            "currency": "USD",
            "bearer": "merchant",
            "collection_mode": "immediate",
            "taxes": []
          }
        ],
        "txn_fee": [
          {
            "amount": 500,
            "currency": "USD",
            "bearer": "merchant",
            "collection_mode": "immediate",
            "taxes": []
          }
        ],
        "referral_fee": []
      }
    }
  ]
}
```

### Create the payout

**`createPaymentAccountPayout`** · `POST /v1/payment-accounts/{id}/payouts` · [API reference](/api-reference/openapi/payment_account/createpaymentaccountpayout)

| Field | Required | Rule |
|  --- | --- | --- |
| `quote_id` | Yes | A quote locked on this account. |
| `beneficiary_id` | Yes | An `active` beneficiary of this account. |
| `purpose_code` | Yes | One of the codes below. |
| `request_id` | Yes | Up to 64 characters, unique on the account. A repeated value returns the original payout. |
| `notes` | No | Your own key-value pairs. A few key names are reserved, and a body that uses one returns `400` naming the key. |


| Purpose code | Purpose |
|  --- | --- |
| `S0023` | Transfer to my own overseas account |
| `S1301` | Family support or living expenses |
| `S1302` | Gift to family or friend |
| `S1303` | Donation to charity |
| `S0305` | Education: tuition and student expenses |
| `S0304` | Medical treatment |
| `S0306` | Travel or holiday |
| `S0001` | Investments: stocks and securities |
| `S0005` | Investments: property or real estate |
| `S0601` | Insurance premium |
| `S1306` | Tax payment |


```curl
curl -i -X POST \
  'https://api.glomopay.com/api/v1/payment-accounts/pacct_6ab59a10Hk3Zq/payouts' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "quote_id": "quote_6ab5a2d4Wc7Nh",
    "beneficiary_id": "bene_6ab5a1c9gflRf",
    "purpose_code": "S0023",
    "request_id": "acme-po-0001",
    "notes": {
      "channel": "mobile_app"
    }
  }'
```

Example response, `201 Created`:

```json
{
  "id": "payout_6ab5a2e7Tn4Yc",
  "payment_account_id": "pacct_6ab59a10Hk3Zq",
  "beneficiary_id": "bene_6ab5a1c9gflRf",
  "source_amount": 60000,
  "source_currency": "USD",
  "destination_amount": 5225850,
  "destination_currency": "INR",
  "purpose_code": "S0023",
  "status": "in_progress",
  "fees": {
    "txn_fee": {
      "currency": "USD",
      "amount": 500
    },
    "fx_fee": {
      "currency": "USD",
      "amount": 250
    }
  },
  "mid_market_rate": {
    "currency": "INR",
    "rate": 88.2
  },
  "documents": [],
  "receipt_ids": [],
  "utr": null,
  "created_at": "2026-10-15T11:01:02Z",
  "updated_at": "2026-10-15T11:01:02Z",
  "fee_collection_mode": "immediate",
  "request_id": "acme-po-0001",
  "payment_rail": "imps",
  "invoice_number": null,
  "notes": {
    "channel": "mobile_app"
  },
  "error_code": null,
  "error_description": null,
  "customer_error_description": null,
  "quote_id": "quote_6ab5a2d4Wc7Nh",
  "taxes": [],
  "estimated_credit_date": "2026-10-15"
}
```

**Always read `status` in the create response.** The call returns `201` for every payout it creates:

| `status` | What it means |
|  --- | --- |
| `in_progress` | The payout is being processed. Its source amount has moved from `available` to `on_hold`. |
| `action_required` | Glomo needs more information before the payout can continue. Nothing is held yet. The amount moves to `on_hold` when the payout continues to `in_progress`. |
| `failed` | The payout could not start, for example because a compliance check could not complete. Nothing is held. |
| `cancelled` | Rare. The quote expired while the payout was being created, and `error_code` is `QUOTE_EXPIRED`. |


A `failed` or `cancelled` payout has used its quote and its `request_id`. To try again, lock a new quote and send a new `request_id`.

If you send a `request_id` that the account already used, you get the original payout back, in its current status, and the rest of the body is ignored.

| HTTP | `code` or `message` | Meaning |
|  --- | --- | --- |
| `400` | `INSUFFICIENT_BALANCE` | The `available` balance does not cover the payout. Nothing was created. `message` gives the extra amount needed. The same error is returned when the balance cannot be read for a moment, so a retry with the same `request_id` is safe. |
| `400` | `Payment account cannot send money` | The account is not `active`. |
| `400` | `Payouts are not available` | Payouts are not enabled for your account. Contact Glomo. |
| `400` | `Purpose code ... is not allowed for payment account payouts` | Use a code from the list above. |
| `400` | `Beneficiary verification is pending`, `Beneficiary has been rejected` | The beneficiary is not `active`. |
| `400` | `No rails available for this beneficiary` | The beneficiary does not support the quote's rail or destination currency. Pick a quote for a rail it supports. The quote is not used. |
| `400` | `Quote has expired`, `Quote has already been used` | Lock a new quote. |
| `400` | `Fee amount is equal to or higher than the total transaction amount, try increasing the amount` | The fees take the whole amount. Lock a quote for a larger amount. |
| `404` | Not found | The account, the quote or the beneficiary is not found on this account. |
| `409` | `Another transaction on this payment account is in progress` | Another transaction on this account, such as another payout, is in progress. Nothing was done. Retry with the same `request_id`. |


### Follow the payout

Glomo sends [payout webhooks](/platform/webhooks/payout) to you for every status change. `data` is the same payout object as the Create a payout response, with `payment_account_id` and the `request_id` you sent.

| Event | What to do |
|  --- | --- |
| `in_progress` | Show the payout as in progress. You can receive this event more than once for one payout. |
| `action_required` | Glomo needs more information before the payout can continue. Show the payout as in progress and wait for the next event. |
| `success` | The beneficiary is paid. The amount leaves `on_hold`, and a debit line is added to the statement. |
| `failed` | The payout failed. The amount goes back to `available`. `error_code` gives the reason. |
| `cancelled` | The payout was stopped before it was paid. The amount goes back to `available`. |


Create a payout is idempotent on `request_id`. If you miss a webhook, send the same request again: you get the payout back in its current status, and no second payout is made.

## Errors and pagination

Every error is a flat object with `error` (the HTTP reason) and `message`. Some errors also have `code`, for example `INSUFFICIENT_BALANCE` and `order_amount_above_cap`. When `code` is present, use it. When it is not, use the HTTP status. `message` is for your logs, so do not parse it.

```json
{
  "error": "Bad Request",
  "message": "Payment account cannot send money"
}
```

Every list returns `data` and `page_meta`. Lists take `page` (from 1) and `per_page` (default 20, maximum 100, a higher value is reduced to 100). List transactions also takes `before` and `after`. See [Pagination](/platform/pagination).