> For the complete index of the 402pay docs, see [llms.txt](https://developer.402pay.co/llms.txt).

# Request the remainder

Ask the customer of an underpaid payment for exactly what's left, once its quote has expired.

`POST https://dash.402pay.co/api/v1/payments/{id}/request-remainder`

For a payment that's `underpaid` after its quote expired, from a link or the API. It opens a checkout for exactly what's left, in the same coin and network, attached to the same payment: its `remainder` is `true`. When the rest arrives, the payment gains a `remainder_paid` event and succeeds, and no second payment is made. Send the customer to the `url` in the response.

Returns the payment, with a `remainder_requested` event in its timeline, and the new checkout. Asking again while that checkout is open returns the same one. Requires an `Idempotency-Key`.

> While the original quote is live, 15 minutes after the short transfer by default, checkout is still asking the customer for the rest at the same address, so this returns 409 `remainder_unavailable` with the time the quote ends.

### Path

- `id` (string, required): The payment's ID, such as `pmt_QI02vLdJGd48hBbg`.

### Errors

- 404 `not_found` No payment with that ID belongs to your business.
- 400 `idempotency_key_required` The request has no `Idempotency-Key` header.
- 409 `payment_not_underpaid` The payment isn't `underpaid`.
- 409 `remainder_unavailable` The quote is still live, so the customer can still send the rest to the same address, or the payment has no checkout page left, such as a deleted link's.
- 409 `nothing_due` Nothing is left to collect.
- 409 `not_accepting` Your wallet can no longer receive on the payment's network.
- 403 `business_suspended` 402pay suspended your business, so it can't open new checkouts.
- 403 `test_mode_unavailable` A test key can't request a remainder on a live business, so use a live key.
- 503 `temporarily_unavailable` 402pay paused new checkouts, or payments on the payment's network, for now. Try again later.

Any request can also fail on its key or its body. See [errors](https://developer.402pay.co/api/errors.md).

Request, cURL:

```bash
curl -X POST "https://dash.402pay.co/api/v1/payments/pmt_uYs2XjkL1jGJt44v/request-remainder" \
  -H "Authorization: Bearer $PAY402_SECRET_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
```

Request, Node.js:

```js
const response = await fetch("https://dash.402pay.co/api/v1/payments/pmt_uYs2XjkL1jGJt44v/request-remainder", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAY402_SECRET_KEY}`,
    "Idempotency-Key": crypto.randomUUID(),
  },
});
const { data } = await response.json();
```

Request, Python:

```python
import os
import uuid

import requests

response = requests.post(
    "https://dash.402pay.co/api/v1/payments/pmt_uYs2XjkL1jGJt44v/request-remainder",
    headers={
        "Authorization": f"Bearer {os.environ['PAY402_SECRET_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
)
data = response.json()["data"]
```

Response, 201 Created:

```json
{
  "data": {
    "kind": "remainder_request",
    "payment": {
      "id": "pmt_uYs2XjkL1jGJt44v",
      "kind": "payment",
      "status": "underpaid",
      "amount": 19900,
      "currency": "USD",
      "fee_payer": "business",
      "customer_fee": 0,
      "amount_received": 17910,
      "reporting": {
        "currency": "USD",
        "amount": 19900,
        "fee": 0,
        "transaction_fee": 0,
        "customer_fee": 0,
        "net": 0
      },
      "fee_rate_bps": 0,
      "method": {
        "rail": "crypto",
        "asset": "USDC",
        "network": "polygon",
        "amount": "179.10",
        "expected_amount": "199.00",
        "overpaid_amount": null,
        "from_address": "0xd2554462b44e258265af12a7d051e47bda66e5b6",
        "tx_hash": "0x1d346f1e2fdd7e6a7bdd4d0193dba2a938dfdb7beef4fab2669d55fef2607812",
        "explorer_url": "https://polygonscan.com/tx/0x1d346f1e2fdd7e6a7bdd4d0193dba2a938dfdb7beef4fab2669d55fef2607812"
      },
      "settlement": {
        "destination": "wallet",
        "asset": "USDC",
        "network": "polygon",
        "amount": "179.10",
        "wallet_id": "wal_1fIGZOrILmsCO0jw",
        "address": "0x7Ba69aE8cEf2987739F6E70e903F95a5028e3531",
        "tx_hash": "0x1d346f1e2fdd7e6a7bdd4d0193dba2a938dfdb7beef4fab2669d55fef2607812",
        "explorer_url": "https://polygonscan.com/tx/0x1d346f1e2fdd7e6a7bdd4d0193dba2a938dfdb7beef4fab2669d55fef2607812"
      },
      "customer_id": "cst_gWFWcc7Ga0Pv7LSC",
      "link_id": "lnk_nt842tPNne3lf0ka",
      "url": null,
      "reference": null,
      "metadata": {},
      "success_url": null,
      "cancel_url": null,
      "expires_at": null,
      "canceled_at": null,
      "checkout_id": "chk_OuPmQnhYyQqpp2qZ",
      "description": "Team plan, monthly",
      "country": "US",
      "failure_code": null,
      "failure_message": null,
      "confirmed_at": null,
      "created_at": "2026-09-26T21:22:47.055Z",
      "updated_at": "2026-09-26T21:38:24.275Z",
      "events": [
        {
          "type": "created",
          "created_at": "2026-09-26T21:22:47.055Z",
          "data": null
        },
        {
          "type": "method_selected",
          "created_at": "2026-09-26T21:22:47.055Z",
          "data": {
            "rail": "crypto",
            "asset": "USDC",
            "network": "polygon"
          }
        },
        {
          "type": "detected",
          "created_at": "2026-09-26T21:22:47.069Z",
          "data": {
            "amount": "179.10",
            "network": "polygon",
            "tx_hash": "0x1d346f1e2fdd7e6a7bdd4d0193dba2a938dfdb7beef4fab2669d55fef2607812"
          }
        },
        {
          "type": "underpaid",
          "created_at": "2026-09-26T21:22:47.069Z",
          "data": {
            "expected": "199.00",
            "received": "179.10"
          }
        },
        {
          "type": "expired",
          "created_at": "2026-09-26T21:37:47.069Z",
          "data": null
        },
        {
          "type": "remainder_requested",
          "created_at": "2026-09-26T21:38:24.275Z",
          "data": {
            "checkout_id": "chk_XKOWx49himYIAnet",
            "amount": 1990,
            "currency": "USD"
          }
        }
      ]
    },
    "checkout": {
      "id": "chk_XKOWx49himYIAnet",
      "kind": "checkout",
      "status": "open",
      "rail": "crypto",
      "link_id": "lnk_nt842tPNne3lf0ka",
      "payment_id": "pmt_uYs2XjkL1jGJt44v",
      "amount": 1990,
      "currency": "USD",
      "breakdown": {
        "currency": "USD",
        "price": 1990,
        "processing_fee": null,
        "network_fee": 2,
        "total": 1992
      },
      "crypto": {
        "asset": "USDC",
        "network": "polygon",
        "amount": "19.90",
        "address": "0xb5C513376614F24fBf807B8c2B1FA3fD1E637A52",
        "payment_uri": "ethereum:0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359@137/transfer?address=0xb5C513376614F24fBf807B8c2B1FA3fD1E637A52&uint256=19900000",
        "rate": {
          "amount": 100,
          "currency": "USD"
        },
        "received_amount": "0.00",
        "remaining_amount": null,
        "remaining_payment_uri": null,
        "overpaid_amount": null,
        "detected_network": null,
        "tx_hash": null,
        "explorer_url": null
      },
      "card": null,
      "confirmations": {
        "current": 0,
        "required": 4
      },
      "remainder": true,
      "canceled_by": null,
      "replaced_by": null,
      "failure_code": null,
      "review_reason": null,
      "success_url": null,
      "expires_at": "2026-09-26T21:53:24.271Z",
      "sent_at": null,
      "created_at": "2026-09-26T21:38:24.271Z",
      "updated_at": "2026-09-26T21:38:24.271Z",
      "email": "harper.wilson@example.com",
      "reporting": {
        "currency": "USD",
        "amount": 1990,
        "fee": 0,
        "transaction_fee": 0,
        "customer_fee": 0,
        "net": 1990
      },
      "fee_rate_bps": 0
    },
    "url": "https://checkout.402pay.co/checkout/v6e4mrczwg?s=chk_XKOWx49himYIAnet"
  }
}
```