Atlas API

Getting started

The shortest path from nothing to a created payment.

This walks through a single call to POST /atlas/payment — enough to see a real redirect URL come back. The full field list is on that reference page; Authentication and the signature covers the signing rule in depth. This page just runs it once.

Get a project and a merchant secret

Every request names a project — one is issued with your access, or list what's already available to your merchant with POST /atlas/project/list, which needs merchant (your merchant tiny id) alongside the signature. You'll also need your merchant secret: a hex-encoded key, used as-is to sign every request (see Authentication).

Build the request body

POST /atlas/payment needs seven required fields — project, amount, currency, success_url, failure_url, cancel_url, callback_url — plus signature. Everything else on the reference page is optional; user_email below is one of them, included because a project may require it (check required_fields on the project's entry from /atlas/project/list).

{
  "project": "VxvcO2tgL9URWTIWGlgPB",
  "amount": "1.00",
  "currency": "USD",
  "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",
  "user_email": "[email protected]"
}

Sign it

Take every field above except signature (there isn't one yet), sort them by field name, join the values with |, and HMAC-SHA256 the result with your merchant secret, hex-decoded to bytes:

amount|callback_url|cancel_url|currency|failure_url|project|success_url|user_email

which for the body above is the literal string

1.00|https://shop.example.com/callback|https://shop.example.com/cancel|USD|https://shop.example.com/failure|VxvcO2tgL9URWTIWGlgPB|https://shop.example.com/success|[email protected]

Signed with the secret 5f3a9c1e0b7d4826a1c9e2f6b8d0473c, that produces:

610cb7d5b70f23b49f1aa4d3000752c0030f0aa46f80b5546a5e9ffd1d0e805f

Authentication and the signature has this rule in full, plus the same worked example in curl, Node.js, Python and PHP.

Send it

SECRET_HEX="5f3a9c1e0b7d4826a1c9e2f6b8d0473c"
BASE_URL="https://api.example.com"   # the base URL issued with your credentials

MESSAGE="1.00|https://shop.example.com/callback|https://shop.example.com/cancel|USD|https://shop.example.com/failure|VxvcO2tgL9URWTIWGlgPB|https://shop.example.com/success|[email protected]"
SIGNATURE=$(printf '%s' "$MESSAGE" \
  | openssl dgst -sha256 -mac HMAC -macopt hexkey:$SECRET_HEX \
  | awk '{print $2}')

curl -X POST "$BASE_URL/atlas/payment" \
  -H "Content-Type: application/json" \
  -d '{
    "project": "VxvcO2tgL9URWTIWGlgPB",
    "amount": "1.00",
    "currency": "USD",
    "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",
    "user_email": "[email protected]",
    "signature": "'"$SIGNATURE"'"
  }'

Read the response

{
  "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; exactly one is non-empty for any given project. Send the payer to redirect_url when it's non-empty; render payment_details when it is instead. Payments explains why, and what each flow looks like end to end.

From here, the payer completes (or abandons) the payment at that URL, and Atlas posts a signed status update to your callback_url as things change — see Webhooks. You can also poll POST /atlas/payin/status with the payin_id you got back, or your own external_id if you sent one.

On this page