Atlas API

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|3000

The 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

FieldsWhy you send them
project, amount, currency, success_url, failure_url, cancel_url, callback_url, signatureRequired on every payment. Without all eight the request is a 400 before anything else is looked at.
external_idYour 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.
descriptionFree 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.
ipThe 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_idWhat 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_url is that page.
  • Direct. Show the payer something in your own UI instead — a QR code, a PayID, a bank reference. The response's payment_details is 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, no external_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 201 with payin_id, status PROCESSING, a non-empty redirect_url and an empty payment_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_url or failure_url once 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 empty redirect_url, and payment_details to 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_id set, and both redirect_url and payment_details empty — 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 poll payin/status, the same as any other payment.
  • The payment was refused. A 422, no data at all. No scenario matched, no route was usable, or every provider route failed. The payin usually exists all the same, persisted as FAILED with the reason — so if you sent an external_id you can still find it through POST /atlas/payin/status and 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.

On this page