Skip to main content
A payment request is the object you create and submit to start a payment. It describes:
  • Which account the funds are coming from and which token to send
  • Which account should receive funds and which token they should get
  • How much (in the token’s smallest unit)
  • Your authorization to release the funds
Submitting a payment request is not the same as a direct transfer. The money doesn’t move the moment you submit — Atum coordinates finding a settlement provider and completing delivery after your request is accepted. Identity credentials, when you attach them, travel with the request as a separate verifiable presentation. They do not replace the signature below. See What is Atum ID?. You can also constrain which settlement providers may fulfill this payment, by identity. That is not a credential-type filter — see Policy enforcement.

​
What you sign locally

Before submitting, your app signs the request with your private key. The gateway validates the signature but never sees your private key — signing always happens on your machine.

​
Push and pull payments

The same payment request model works for both directions: Push — the sender initiates (Anna sends $100 to Bob):
Pull — the recipient initiates, sender authorizes (Bob requests $100 from Anna):
The accounts don’t change — only who creates the request does.

​
Settlement providers on this payment

You can optionally restrict which settlement providers may fulfill this request. Set settler_requirements on the request: an allow list (whitelist) and/or a deny list (blacklist) of settlement-provider identities (DIDs). If both are present, the deny list wins. You set this per payment. The Payment Gateway applies it. It matches named identities, not credential types. This is not counterparty authorization (recipient consent), and it is not a way to require a credential type of the other side. See Policy enforcement.

​
What happens after you submit

  1. Gateway validates the request and returns a payment_id
  2. Settlement providers compete to fulfill it
  3. Funds move on-chain asynchronously
  4. You collect the outcome (re-attempt the same purchase for x402/MPP flows, or read /status out of band)
See Atum payment lifecycle for the full sequence. For HTTP payment retries, see Idempotency.

​
Next steps

After you finish this page, the following go deeper: