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

# Payment request callbacks

## Processing payment request callbacks

Payment request callbacks are sent whenever the status of a payment request changes.

When you receive a callback with `"status": "paid"`, the payment request has been successfully paid and can be treated as completed on your side.

Use `foreign_id` to identify the payment request or order in your system and map it to the user for whom the payment request was created.

## Payment request callback payload examples

<Tabs>
  <Tab title="Exchange rate is fixed">
    Sent when the payment request is created with a fixed exchange rate and is waiting for payment. At this stage, no funds have been received yet.

    ```json highlight={5} theme={null}
    {
      "payment_request_id": "019c0ebf-81e5-751d-aa57-fb9e2cba23c2",
      "foreign_id": "order_12345",
      "type": "payment_request",
      "status": "processing",
      "end_user_email": "test@test.com",
      "payment_request_address": {
        "id": "019c0ebf-84a1-7bdc-a09c-8b62294cc75d",
        "currency": {
          "iso": "BTC",
          "network_name": "bitcoin"
        },
        "convert_to": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je"
      },
      "payment_request_amount": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "amount": "0.3"
      },
      "currency_sent": {
        "currency": {
          "iso": "BTC",
          "network_name": "bitcoin"
        },
        "expected_amount": "0.0094",
        "received_amount": "0",
        "remaining_amount": "0.0094"
      },
      "fixed_at": 1769773958,
      "expires_at": 1769774157,
      "valid_until": 1769774157
    }
    ```
  </Tab>

  <Tab title="A new transaction is detected">
    Sent when a new payment transaction is detected for the payment request. The payment request remains in `processing` status until the full required amount is received.

    ```json highlight={5} theme={null}
    {
      "payment_request_id": "019c0f25-e7db-7ca3-b19f-a7916b5a4905",
      "foreign_id": "order_34567",
      "type": "payment_request",
      "status": "processing",
      "end_user_email": "example@example.com",
      "payment_request_address": {
        "id": "019c0f25-eb0d-70bd-b282-8e58de5d1b7c",
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "convert_to": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "address": "0x114da762447ccb464ac29134B2930e0570139F83"
      },
      "payment_request_amount": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "amount": "0.3"
      },
      "currency_sent": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "expected_amount": "0.3",
        "received_amount": "0.15",
        "remaining_amount": "0.15"
      },
      "transactions": [
        {
          "id": "019c0f26-25fc-7738-bdf1-85708ec6e67c",
          "currency": {
            "iso": "ETH",
            "network_name": "ethereum"
          },
          "address": "0x114da762447ccb464ac29134B2930e0570139F83",
          "amount": "0.15",
          "txid": "0x12882dbbd810304bd0d9707472dbb40f8c2f7d9a1e6b3c4d5f60718293a4b5c6",
          "status": "confirmed",
          "late_payment": false
        }
      ],
      "fixed_at": 1769780669,
      "expires_at": 1769780868,
      "valid_until": 1769780868
    }
    ```
  </Tab>

  <Tab title="Payment request paid">
    Sent when the full required amount has been received and the payment request is successfully completed.

    ```json highlight={5} theme={null}
    {
      "payment_request_id": "019c0f25-e7db-7ca3-b19f-a7916b5a4905",
      "foreign_id": "order_34567",
      "type": "payment_request",
      "status": "paid",
      "end_user_email": "example@example.com",
      "payment_request_address": {
        "id": "019c0f25-eb0d-70bd-b282-8e58de5d1b7c",
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "convert_to": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "address": "0x114da762447ccb464ac29134B2930e0570139F83"
      },
      "payment_request_amount": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "amount": "0.3"
      },
      "currency_sent": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "expected_amount": "0.3",
        "received_amount": "0.3",
        "remaining_amount": "0"
      },
      "currency_received": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "amount": "0.3"
      },
      "transactions": [
        {
          "id": "019c0f26-25fc-7738-bdf1-85708ec6e67c",
          "currency": {
            "iso": "ETH",
            "network_name": "ethereum"
          },
          "address": "0x114da762447ccb464ac29134B2930e0570139F83",
          "amount": "0.15",
          "txid": "0xa3f1c9d8427e6b5c1098d7e6f5a4b3c291807f6e5d4c3b2a1908f7e6d5c4b3a2",
          "status": "confirmed",
          "late_payment": false
        },
        {
          "id": "6425cf81-da66-4c60-8a53-6dbdf118ce09",
          "currency": {
            "iso": "ETH",
            "network_name": "ethereum"
          },
          "address": "0x114da762447ccb464ac29134B2930e0570139F83",
          "amount": "0.15",
          "txid": "0x12882dbbd810304bd0d9707472dbb40f8c2f7d9a1e6b3c4d5f60718293a4b5c6",
          "status": "confirmed",
          "late_payment": false
        }
      ],
      "fees": [
        {
          "type": "transfer_fee",
          "currency": {
            "iso": "ETH",
            "network_name": "ethereum"
          },
          "amount": "0.00007808"
        },
        {
          "type": "fee_payment_request_crypto",
          "currency": {
            "iso": "ETH",
            "network_name": "ethereum"
          },
          "amount": "0.00854354"
        }
      ],
      "fixed_at": 1769780669,
      "expires_at": 1769780868,
      "valid_until": 1769780868
    }
    ```
  </Tab>

  <Tab title="Payment request failed">
    Sent when the payment request is not successfully completed before expiry. Use the transaction details and amounts to understand what was received.

    ```json highlight={5} theme={null}
    {
      "payment_request_id": "019c0de8-4576-7e4f-85c7-43a5cb5e9f2d",
      "foreign_id": "order_82652.32794293783",
      "type": "payment_request",
      "status": "failed",
      "end_user_email": "test@test.net",
      "payment_request_address": {
        "id": "019c0de8-49df-762a-9705-4c304627dfd0",
        "currency": {
          "iso": "BTC",
          "network_name": "bitcoin"
        },
        "convert_to": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je"
      },
      "payment_request_amount": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "amount": "0.3"
      },
      "currency_sent": {
        "currency": {
          "iso": "BTC",
          "network_name": "bitcoin"
        },
        "expected_amount": "0.0094",
        "received_amount": "0.009",
        "remaining_amount": "0.0004"
      },
      "transactions": [
        {
          "id": "019c0de8-54a3-7163-b59c-95f38d982a31",
          "currency": {
            "iso": "BTC",
            "network_name": "bitcoin"
          },
          "address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je",
          "txid": "cf3c308839d67ab6bce3b2f275fcc197c5c19dc208efc35dbc0a68ff355d78e3",
          "amount": "0.009",
          "status": "confirmed",
          "late_payment": false
        }
      ],
      "fixed_at": 1769759853,
      "expires_at": 1769760051,
      "valid_until": 1769760051
    }
    ```
  </Tab>

  <Tab title="Payment request expired (without a fixed rate)">
    Sent when the payment request expires before payment is received and no fixed exchange rate was locked for the request.

    ```json highlight={5} theme={null}
    {
      "payment_request_id": "019bea8c-7d69-7632-8472-77443ac78a17",
      "foreign_id": "order_85566.25193543735",
      "type": "payment_request",
      "status": "expired",
      "end_user_email": "ckane@example.com",
      "payment_request_amount": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "amount": "0.3"
      },
      "expires_at": 1769166664
    }
    ```
  </Tab>

  <Tab title="Payment request expired (with a fixed rate)">
    Sent when the payment request expires after a fixed exchange rate was locked, but no sufficient payment was received before expiry.

    ```json highlight={5} theme={null}
    {
      "payment_request_id": "019c0ebf-81e5-751d-aa57-fb9e2cba23c2",
      "foreign_id": "order_12345",
      "type": "payment_request",
      "status": "expired",
      "end_user_email": "test@test.com",
      "payment_request_address": {
        "id": "019c0ebf-84a1-7bdc-a09c-8b62294cc75d",
        "currency": {
          "iso": "BTC",
          "network_name": "bitcoin"
        },
        "convert_to": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je"
      },
      "payment_request_amount": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "amount": "0.3"
      },
      "currency_sent": {
        "currency": {
          "iso": "BTC",
          "network_name": "bitcoin"
        },
        "expected_amount": "0.0094",
        "received_amount": "0",
        "remaining_amount": "0.0094"
      },
      "fixed_at": 1769773958,
      "expires_at": 1769774157,
      "valid_until": 1769774157
    }
    ```
  </Tab>

  <Tab title="Late payment received">
    Sent when a payment is received after the payment request has already expired or failed. Such transactions are marked with `late_payment: true`.

    ```json highlight={5} theme={null}
    {
      "payment_request_id": "019c0de8-4576-7e4f-85c7-43a5cb5e9f2d",
      "foreign_id": "order_82652.32794293783",
      "type": "payment_request",
      "status": "failed",
      "end_user_email": "test@test.net",
      "payment_request_address": {
        "id": "019c0de8-49df-762a-9705-4c304627dfd0",
        "currency": {
          "iso": "BTC",
          "network_name": "bitcoin"
        },
        "convert_to": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je"
      },
      "payment_request_amount": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "amount": "0.3"
      },
      "currency_sent": {
        "currency": {
          "iso": "BTC",
          "network_name": "bitcoin"
        },
        "expected_amount": "0.0094",
        "received_amount": "0.009",
        "remaining_amount": "0.0004"
      },
      "transactions": [
        {
          "id": "019c0de8-54a3-7163-b59c-95f38d982a31",
          "currency": {
            "iso": "BTC",
            "network_name": "bitcoin"
          },
          "address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je",
          "txid": "cf3c308839d67ab6bce3b2f275fcc197c5c19dc208efc35dbc0a68ff355d78e3",
          "amount": "0.009",
          "status": "confirmed",
          "late_payment": false
        },
        {
          "id": "019c0de8-54a3-7163-b59c-95f38d982a32",
          "currency": {
            "iso": "BTC",
            "network_name": "bitcoin"
          },
          "address": "tb1qj0d4rsczat6dx3yy065g98rrz5hewkrdcrz7je",
          "txid": "9b7f2a0c6d3e4f1a8c9d0e1f2a3b4c5d6e7f8091a2b3c4d5e6f708192a3b4c5d",
          "amount": "0.0004",
          "status": "confirmed",
          "late_payment": true
        }
      ],
      "fixed_at": 1769759853,
      "expires_at": 1769760051,
      "valid_until": 1769760051
    }
    ```
  </Tab>

  <Tab title="Payment request restricted">
    Sent when the payer is not allowed to complete the payment.

    ```json highlight={5,7} theme={null}
    {
      "payment_request_id": "019c0de8-4576-7e4f-85c7-43a5cb5e9f2d",
      "foreign_id": "order_82652.32794293783",
      "type": "payment_request",
      "status": "failed",
      "end_user_email": "test@test.net",
      "status_reason": "Service is restricted for the payer. Payments from this payer cannot be processed",
      "end_user_reference": "account_14578",
      "payment_request_amount": {
        "currency": {
          "iso": "ETH",
          "network_name": "ethereum"
        },
        "amount": "0.3"
      },
      "expires_at": 1769166664
    }
    ```
  </Tab>
</Tabs>