Request the remainder

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

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.

Request

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

Response201 Created

{  "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"  }}