Atlas API

Projects

How to discover which projects you can charge against, and what each one will accept.

Every Atlas request names a project, and a project is more than an identifier: it decides the currency, the countries, how the payer completes the payment, and which fields the payment body must carry. POST /atlas/project/list is how you find out what yours are without asking anyone.

Call it once while you build the integration. It is a catalogue, not a per-payment lookup — nothing about it changes between two payments a second apart, and it changes only when someone reconfigures your account.

The request

{
  "merchant": "FFs-fquJGZQfUzV1S4Crx",
  "currency": "EUR",
  "signature": "71b69a667a7cc08f8c9c130b52ae97601da9436cccb8f205655f6924cae6d0e6"
}
FieldWhat it is
merchantRequired. Your merchant identifier — the same shape as a project's, 21 characters of A-Za-z0-9_-, issued with your credentials. This is the one endpoint that names your merchant outright; the others infer it from the project.
countryOptional filter, ISO 3166-1 alpha-2.
currencyOptional filter, ISO 4217.
signatureRequired, as everywhere. Computed under your merchant secret — the key issued alongside the merchant identifier above, not a per-project one.

The signature covers country, currency and merchant — the same rule as every other endpoint (sort the field names, join the values with |), which here works out to that order, minus whichever filters you left out. For the body above:

EUR|FFs-fquJGZQfUzV1S4Crx

The filters are not validated

An unknown country or currency is not an error — it simply matches no projects, and you get an empty list. That is deliberate: a filter is a question, and "nothing matches" is a real answer to it. The consequence is that a typo in currency looks exactly like a merchant with nothing configured, so check the value before concluding the account is empty.

The response

{
  "success": true,
  "data": {
    "projects": [
      {
        "project": "VxvcO2tgL9URWTIWGlgPB",
        "type": "card",
        "flow_type": "REDIRECT",
        "currencies": ["EUR", "USD"],
        "currencies_any": false,
        "countries_mode": "allow",
        "countries": ["DE", "FR"],
        "required_fields": [
          { "name": "user_email", "label": "Email", "type": "string", "format": "email" }
        ],
        "optional_fields": [
          { "name": "user_phone", "label": "Phone", "type": "string" }
        ]
      }
    ]
  },
  "timestamp": "2026-07-02T00:00:00.000Z"
}

What each field is telling you

FieldWhat to do with it
projectThe value to send as project on every payment, payout, refund and status request. Opaque — don't parse it, and don't expect it to resemble the name you gave the project in the admin.
typeThe payment method family, e.g. card. Useful for labelling a choice you offer the payer.
flow_typeHow the payer completes the payment — one of REDIRECT, DIRECT, INVOICE, HOST. You do not have to branch on it: the payment response says which of redirect_url and payment_details is filled (both empty for HOST), and that is the check to write.
currencies, currencies_anyThe currencies this project accepts. When currencies_any is true the list is advisory rather than exhaustive.
countries, countries_modeWhich payers the project is for. countries_mode says whether the list is an allow-list or a block-list — the same list means opposite things under the two, so read the mode first.
required_fieldsThe fields a payment for this project must carry, beyond the seven every payment needs. Build your request from this list rather than from a guess.
optional_fieldsFields the project will accept. Not decoration: see below.

Each entry in the two field lists carries a name — the name to send in the payment body, exactly as given — plus a label fit for a form, a type, and sometimes a format or a default_value.

Send the optional fields too, where you have them

optional_fields is not a list of things you may safely skip. Each gateway declares the fields it needs, and routing skips any gateway whose declared fields are missing from the request — so an omitted optional field can cost you a route, and if it costs you the last one the payment is refused with a 422. See An omitted field can cost you a provider.

What comes back when something is wrong

  • An unknown merchant is a 401, not a 404. The endpoint never confirms whether an identifier exists — an unknown merchant, a forged signature and a signature computed under the wrong merchant secret all produce the same refusal. It cannot be used to probe which merchants exist.
  • A merchant with no projects is an empty list, not an error: projects is [] and the call succeeds.

From here

The project you picked, plus its required_fields, is everything the payment body needs on top of the amount and the URLs — Payments has the complete request and the flow around it, and Getting started runs one end to end.

On this page