Payments
A complete signed request, the redirect flow end to end, and the response contract both flows share.
POST /atlas/payment creates a payment. Send a
flat JSON body — signed per Authentication — and the
platform returns the payment's id (payin_id) and everything you need to
get the payer to pay.
A complete request
The body below is the one to start from. Seven of its fields are required and the rest are not, but this is close to what a finished integration actually sends: an order reference of your own, who the payer is, and what they have done with you before.
{
"project": "VxvcO2tgL9URWTIWGlgPB",
"amount": "70.00",
"currency": "EUR",
"external_id": "order-1024",
"description": "Add Balance",
"success_url": "https://shop.example.com/success",
"failure_url": "https://shop.example.com/failure",
"cancel_url": "https://shop.example.com/cancel",
"callback_url": "https://shop.example.com/callback",
"ip": "203.0.113.42",
"user_id": "user-4821",
"user_email": "[email protected]",
"user_first_name": "Jane",
"user_last_name": "Doe",
"user_phone": "+61400000000",
"user_country": "AU",
"user_state": "Victoria",
"user_city": "Melbourne",
"user_address": "1 Example Street",
"user_zip": "3000",
"affiliate_id": "aff-17",
"activity_payin_amount": "0",
"activity_payin_count": 0,
"activity_payout_amount": "0",
"activity_payout_count": 0,
"signature": "cc28c0c1777c5c601204bcf8fa13518e1e26bcfce889ffabe00bece51f7ae2a5"
}That signature is real, not a placeholder: it is the HMAC-SHA256 of the
canonical string below under the same example secret the rest of the
documentation uses, 5f3a9c1e0b7d4826a1c9e2f6b8d0473c. Sign the body yourself
and you should get the same digest — if you don't, the difference is in your
canonical string, and this is a cheap place to find it.
0|0|0|0|aff-17|70.00|https://shop.example.com/callback|https://shop.example.com/cancel|EUR|Add Balance|order-1024|https://shop.example.com/failure|203.0.113.42|VxvcO2tgL9URWTIWGlgPB|https://shop.example.com/success|1 Example Street|Melbourne|AU|[email protected]|Jane|user-4821|Doe|+61400000000|Victoria|3000The four leading zeros are the activity fields, sorted first by name. They are
in the string because 0 and "0" are values — it is the empty string that
gets dropped, not the falsy one.
What each group of fields is for
| Fields | Why you send them |
|---|---|
project, amount, currency, success_url, failure_url, cancel_url, callback_url, signature | Required on every payment. Without all eight the request is a 400 before anything else is looked at. |
external_id | Your own reference. It is what POST /atlas/payin/status looks a payment up by, and it comes back on every webhook — send one on every payment, including the ones you expect to fail. |
description | Free text carried with the payment, and shown to the payer at the top of the hosted page on some themes. Write it as something a payer will recognise — Add Balance, not ORD-1024-RETRY2. |
ip | The payer's address as your server saw it — not your server's own. |
user_* | Who the payer is. A project's required_fields may make some of these mandatory, and see the warning below about what a missing one costs. |
activity_*, affiliate_id | What this payer has done with you before, and where they came from. Recorded against the customer behind the payment. |
The full list, with types, is on the
reference page — user_document, user_birthday_date
and a dozen others exist for the providers that ask for them.
An omitted field can cost you a provider
Each gateway declares the payload fields it needs, and routing skips any
gateway whose declared fields are not all present in the request — the reason
is recorded as missing required fields: .... So an optional field is optional
to the API and not necessarily to the route you wanted, and if it removes the
last usable route the payment is refused with a 422 rather than routed
somewhere worse.
An empty string counts as absent for this, exactly as it does for the
signature. "user_email": "" is not a smaller version of sending it.
POST /atlas/project/list returns each
project's required_fields, which is the list to build your request from.
Two flows, one response shape
A project routes a payment one of two ways, and the response carries the result of either without you needing to know in advance which one applies:
- Redirect. Send the payer to a hosted payment page. The response's
redirect_urlis that page. - Direct. Show the payer something in your own UI instead — a QR code, a
PayID, a bank reference. The response's
payment_detailsis a JSON array, encoded as a string, of typed items to render.
{
"success": true,
"data": {
"payin_id": "payin_abc123",
"redirect_url": "https://pay.example.com/hpp/payin_abc123",
"payment_details": ""
},
"timestamp": "2026-07-02T00:00:00.000Z"
}Both redirect_url and payment_details are always present as keys. The
one that doesn't apply to this payment is an empty string — not an absent
key. A direct-flow payment looks like this instead:
{
"success": true,
"data": {
"payin_id": "payin_abc123",
"redirect_url": "",
"payment_details": "[{\"type\":\"qr\",\"value\":\"0002010102\"}]"
},
"timestamp": "2026-07-02T00:00:00.000Z"
}Branch on the value, not the key
Checking if (data.redirect_url) works; checking 'redirect_url' in data
does not — the key is there either way. At most one of the two values is
non-empty — a HOST payment awaiting a callback has neither — so test the
value, not the key.
The redirect flow, step by step
Create the payment
Send the request above. A 201 with a non-empty redirect_url means the
payment exists and has been routed to a provider. Store payin_id against
your order before you do anything else — it is the handle for everything that
follows, and it is the one thing you cannot recover later if you sent no
external_id.
Send the payer to redirect_url
Use it verbatim, as a top-level navigation of the payer's browser. Don't rebuild it, don't append to it, and don't cache it against a different order: the URL belongs to this one payment.
Treat the link as single-use and short-lived. Where the payment page is hosted by the platform, opening it consumes it — a reload, a back-button return, or a second tab gets "This payment link is invalid or has expired" rather than the form, and so does anyone who opens it after it times out. Where the payer is sent to a provider's own page instead, that page has its own rules, which is the second reason not to build a flow that depends on reopening one.
So: a payer who abandons a payment and comes back later needs a new payment,
not the old link. Create one — a fresh POST /atlas/payment with a new
external_id — and store it against the same order on your side.
The payer finishes and comes back
When the payment ends, the hosted page shows the payer an outcome — completed,
failed, or cancelled — with a Return to site button that goes to the
matching URL from your request: success_url, failure_url or cancel_url.
Two consequences worth designing around:
- The return is a click, not an automatic bounce. A payer who closes the tab at that screen never reaches your site at all, and their payment is unaffected either way.
- Your URL is used exactly as you sent it. Nothing is appended — no
payin_id, noexternal_id, no status. If your success page needs to know which order it is looking at, put that in the URL yourself when you build the request:https://shop.example.com/success?order=1024.
Learn the outcome from the webhook
Atlas posts a signed POST to your callback_url as the payment's status
changes — PROCESSING, ACCEPTED, COMPLETED, FAILED, CANCELED (plus the
retired EXPIRED, still delivered for payments created before that status
was replaced). This is the outcome. It arrives whether or not the payer ever
came back to your site, which is the whole reason it exists. See
Webhooks for the body, the signature rule, and why one may
arrive twice.
Reconcile what you might have missed
POST /atlas/payin/status answers for a single
payment, by payin_id or by your external_id. Use it to close the gap after
an outage on your side, or when a payer is standing in front of you and a
webhook has not arrived yet — not as your main signal. See
when to poll versus wait.
Landing on success_url is not proof of payment
It means the payer clicked a button on a page that said the payment
succeeded. Treat it as a cue to show a "we're confirming your payment" screen,
and release the goods when the COMPLETED webhook arrives or
payin/status says so. Anything else is a checkout that can be completed by
typing your own success URL into a browser.
Projects in background mode
A card project (INVOICE or HOST) can be switched to background mode. The payment is then tried through every gateway the project routes it to — after a decline, after a failed 3-D Secure check, after a gateway error — until one accepts it or none is left. The payer waits on our page between attempts.
What changes for your integration:
- Every card payment answers the same way: a
201withpayin_id, statusPROCESSING, a non-emptyredirect_urland an emptypayment_details— even when the first gateway would have approved the payment at once. - On a HOST project, always send the payer to
redirect_url. A HOST integration that expects a synchronous result has to change before the project is switched. - You get one webhook per payment: the final one. Attempts in between are not reported.
- The payer comes back to your
success_urlorfailure_urlonce the payment has its outcome.
Background mode is switched on and off by your account manager, and only while the project is deactivated.
When there is no redirect at all
Three different things can leave you without a redirect_url, and they are
not confusable in the response:
- The project is a direct-flow one. A
201, an emptyredirect_url, andpayment_detailsto render — the section above. The three return URLs are still required and still signed, because a project's flow type is not something you choose per request. - The project is a HOST one, awaiting a callback. A
201,payin_idset, and bothredirect_urlandpayment_detailsempty — there is nothing to redirect to and nothing to render, because your own page already collected the card and sent it in the request. Watch for the webhook or pollpayin/status, the same as any other payment. - The payment was refused. A
422, nodataat all. No scenario matched, no route was usable, or every provider route failed. The payin usually exists all the same, persisted asFAILEDwith the reason — so if you sent anexternal_idyou can still find it throughPOST /atlas/payin/statusand show the payer something better than a blank page. The whole list of error responses, with what each one means, is on the reference page.