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"
}| Field | What it is |
|---|---|
merchant | Required. 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. |
country | Optional filter, ISO 3166-1 alpha-2. |
currency | Optional filter, ISO 4217. |
signature | Required, 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-fquJGZQfUzV1S4CrxThe 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
| Field | What to do with it |
|---|---|
project | The 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. |
type | The payment method family, e.g. card. Useful for labelling a choice you offer the payer. |
flow_type | How 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_any | The currencies this project accepts. When currencies_any is true the list is advisory rather than exhaustive. |
countries, countries_mode | Which 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_fields | The 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_fields | Fields 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 a404. 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:
projectsis[]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.