> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# Statuses & Events

> The statuses and webhook events for blockchain payments.

## Statuses

| Status           | Description                                                      | Webhook Event             |
| ---------------- | ---------------------------------------------------------------- | ------------------------- |
| `created`        | Payment initiated in Lead's system.                              | `.payment_created`        |
| `under_review`   | Payment flagged for manual review by compliance.                 | `.payment_under_review`   |
| `awaiting_funds` | Waiting for stablecoins to arrive (external wallet source only). | `.payment_awaiting_funds` |
| `submitted`      | Funds transferred to destination, settlement in progress.        | `.payment_submitted`      |
| `posted`         | Settlement complete, funds delivered to destination.             | `.payment_posted`         |
| `rejected`       | Payment rejected by Lead or partner; funds reversed.             | `.payment_rejected`       |
| `canceled`       | Payment canceled by Lead or customer.                            | `.payment_canceled`       |

#### Funding source: USD at Lead

<Frame>
  <img src="https://mintcdn.com/lead/jWNk1F1P6GyMYHcT/images/Global-money-movement---Page-1-(56).png?fit=max&auto=format&n=jWNk1F1P6GyMYHcT&q=85&s=bc42996335cdf30428c599ca088a165b" alt="Global Money Movement Page 1 (56)" width="2972" height="664" data-path="images/Global-money-movement---Page-1-(56).png" />
</Frame>

#### Funding source: Stablecoins outside of Lead

<Frame>
  <img src="https://mintcdn.com/lead/jWNk1F1P6GyMYHcT/images/Global-money-movement---Page-1-(55).png?fit=max&auto=format&n=jWNk1F1P6GyMYHcT&q=85&s=a2373974e4e14c395fae937b00083482" alt="Global Money Movement Page 1 (55)" width="2972" height="664" data-path="images/Global-money-movement---Page-1-(55).png" />
</Frame>

## Events

| **Event**                 | **Description**                                                                                                                                                                                       |
| :------------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `.payment_created`        | The blockchain payment object has been created.                                                                                                                                                       |
| `.payment_under_review`   | The payment has been flagged and undergoing manual review. Can be rejected or cleared to carry on.                                                                                                    |
| `.payment_awaiting_funds` | Lead is waiting for funds to be transferred to the Lead wallet in order to continue with the payment. <br />Only valid in the case of the source of `debtor.account_identifier.type: wallet_address`. |
| `.payment_submitted`      | The payment has been submitted.                                                                                                                                                                       |
| `.payment_posted`         | The payment has posted, funds are in the destination account/wallet.                                                                                                                                  |
| `.payment_rejected`       | The payment has been rejected by Lead or its partners.                                                                                                                                                |
| `.payment_canceled`       | The payment has been cancelled by Lead because the funds were never received.                                                                                                                         |

## **Awaiting Funds Webhook Payload**

If the status of the payment changes to `awaiting_funds`, the object will include a `funding_instructions` section with the details of where to send the funds to. See the object definition above for the details of the `funding_instructions` property.

```json theme={null}
{
    "id": "event_12345",
    "created_at": "2026-02-24T11:22:33Z",
    "event": "blockchain.payment_awaiting_funds",
    "object":
    {
        "id": "blockchain_payment_8888",
        "debtor":
        {
            "account_identifier":
            {
                "type": "wallet_address",
                "value": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            },
            "chain": "base",
            "refund_wallet_address": "0xB9m86771c6218b36c1d19D4a2e9Eb0cE3606eB49",
            "funding_instructions":
            {
                "from_wallet_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
                "chain": "base",
                "amount": 1000000,
                "currency_code": "USDC",
                "to_wallet_address": "0x022e3fD8662c84AF51fF06d7DcAe0b675416dab4"
            },
            "entity_id": "entity_67890"
        },
        "creditor":
        {
            "payment_rail": "clabe",
            "clabe":
            {
                "account_number": "00218090010000001234"
            },
            "type": "business",
            "business":
            {
                "business_name": "Acme Mexico SA de CV"
            },
            "address":
            {
                "line_one": "Av. Reforma 123",
                "city": "Ciudad de México",
                "country": "MX",
                "postal_code": "06600"
            }
        },
        "creditor_agent":
        {
            "bank_name": "BBVA México",
            "country_code": "MX"
        },
        "amounts":
        {
            "instructed_amount": 1000000,
            "instructed_currency_code": "USDC",
            "settlement_currency_code": "MXN",
            "settlement_amount": 17461350,
            "settlement_exchange_rate": 1746
        },
        "payment_purpose":
        {
            "type": "invoice_payment"
        },
        "reference": "INV-MXN-2026-001",
        "status": "awaiting_funds",
        "created_at": "2026-02-24T11:22:33Z",
        "updated_at": "2026-02-24T11:22:33Z"
    }
}
```

## **Example Webhook Payload for Other Events**

All other events will not contain funding instructions as these won’t be relevant to the status its in.

```json theme={null}
{
    "id": "event_12345",
    "created_at": "2026-02-24T11:22:33Z",
    "event": "blockchain.payment_posted",
    "object":
    {
        "id": "blockchain_payment_8888",
        "debtor":
        {
            "identifier":
            {
                "type": "wallet_address",
                "value": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"
            },
            "chain": "base",
            "refund_address": "0xB9m86771c6218b36c1d19D4a2e9Eb0cE3606eB49"
        },
        "creditor":
        {
            "payment_rail": "clabe",
            "clabe":
            {
                "account_number": "00218090010000001234"
            },
            "type": "business",
            "business":
            {
                "business_name": "Acme Mexico SA de CV"
            },
            "address":
            {
                "line_one": "Av. Reforma 123",
                "city": "Ciudad de México",
                "country": "MX",
                "postal_code": "06600"
            }
        },
        "creditor_agent":
        {
            "bank_name": "BBVA México",
            "country_code": "MX",
            "address":
            {
                "line_one": "Av. Paseo de la Reforma 505",
                "city": "Ciudad de México",
                "country": "MX",
                "postal_code": "06500"
            }
        },
        "amounts":
        {
            "instructed_amount": 1000000,
            "instructed_currency_code": "USDC",
            "settlement_currency_code": "MXN",
            "settlement_amount": 17461350,
            "settlement_exchange_rate": 1746
        },
        "payment_purpose":
        {
            "type": "invoice_payment"
        },
        "reference": "INV-MXN-2026-001",
        "status": "posted",
        "created_at": "2026-02-24T11:22:33Z",
        "updated_at": "2026-02-24T11:22:33Z"
    }
}
```