{
  "openapi": "3.0.0",
  "paths": {
    "/atlas/payment": {
      "post": {
        "operationId": "AtlasController_payment",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAtlasPaymentDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The payment was created and is awaiting the payer.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiEnvelopeDto"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AtlasPaymentResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request body is malformed — a required field missing or empty, or a field of the wrong type. `message` is an array here, one entry per failed constraint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "401": {
            "description": "The signature is missing, or does not verify. An unknown project, an unknown merchant, a forged signature and an upstream lookup failure are deliberately the same answer, so this endpoint cannot be used to test whether an identifier exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "404": {
            "description": "The engine does not know the `project` you named.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "422": {
            "description": "The payment was refused: no scenario matched, no route was usable, the provider refused it, or every provider route failed. The payin usually exists all the same — it is persisted as ABANDONED with the reason before this is raised, so if you sent an `external_id` you can still find it through `POST /atlas/payin/status`. `message` is a `CODE: reason` from the routing failure — `PROVIDER_ERROR` when the one provider tried returned an error, whether it refused the payment or its integration could not be reached, `ROUTE_FAILED` when our own integration did not answer at all, `FOREIGN_SEGMENTS_MISSING` when one of your segments is bound to one of ours and this request declared no segment memberships at all — send `segments` (even `[]` for \"none\") to comply — or a plain sentence for a project that is inactive or is not a payin project; those are refused before a payin is created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "500": {
            "description": "The request could not be completed. Nothing about the payment is implied either way — do not treat it as a rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          }
        },
        "tags": [
          "Atlas"
        ]
      }
    },
    "/atlas/payout": {
      "post": {
        "operationId": "AtlasController_payout",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAtlasPayoutDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The payout exists — either freshly created and routed, or the same one already on file for a repeated `external_id` — and is returned as `data`.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiEnvelopeDto"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AtlasPayoutResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request body is malformed — a required field missing or empty, or a field of the wrong type. `message` is an array here, one entry per failed constraint. One payout-specific exception: insufficient wallet balance answers here too, but with a different, flat body that carries no `statusCode`/`error` — `{ \"code\": \"NOT_ENOUGH_BALANCE_ERROR\", \"message\": \"Not enough balance.\" }` — beempay's own contract, which merchant integrations are written against. The payout row is kept, terminal `FAILED`, and its `external_id` is freed rather than consumed, so topping up the wallet and resending the same request creates a new payout rather than returning the refused one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "401": {
            "description": "The signature is missing, or does not verify. An unknown project, an unknown merchant, a forged signature and an upstream lookup failure are deliberately the same answer, so this endpoint cannot be used to test whether an identifier exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "404": {
            "description": "The engine does not know the `project` you named.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "422": {
            "description": "The payout was refused on its merits: no matching scenario, no usable routing, no wallet for the routed gateway to debit, a wallet formula that could not be evaluated, no base currency configured for the merchant, a conversion rate that could not be fetched, a banned customer, or a project that is inactive or is not a `PAYOUT` project. Every reason but the last persists the payout as FAILED with that reason before this is raised, so a repeat of the same `external_id` returns that same FAILED payout rather than trying again. `message` is a `CODE: reason` from the failure, or a plain sentence for a project refused before a payout row exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "500": {
            "description": "The request could not be completed. Nothing about the payment is implied either way — do not treat it as a rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          }
        },
        "tags": [
          "Atlas"
        ]
      }
    },
    "/atlas/refund": {
      "post": {
        "operationId": "AtlasController_refund",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAtlasRefundDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The refund was accepted.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiEnvelopeDto"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AtlasRefundResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request body is malformed — a required field missing or empty, or a field of the wrong type. `message` is an array here, one entry per failed constraint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "401": {
            "description": "The signature is missing, or does not verify. An unknown project, an unknown merchant, a forged signature and an upstream lookup failure are deliberately the same answer, so this endpoint cannot be used to test whether an identifier exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "404": {
            "description": "The payin named by `payin_id` no longer exists. Rare: an unknown payin is normally a 401, and only a merchant already resolved from cache reaches this.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "422": {
            "description": "The refund could not be attempted — the payin never completed, its provider is not reachable, or the call to the provider failed. A provider that answers and declines is not this: that is a 201 carrying a refund whose `status` is `failed`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "500": {
            "description": "The request could not be completed. Nothing about the payment is implied either way — do not treat it as a rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          }
        },
        "tags": [
          "Atlas"
        ]
      }
    },
    "/atlas/refund/status": {
      "post": {
        "operationId": "AtlasController_refundStatus",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AtlasRefundStatusDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Current state of the refund.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiEnvelopeDto"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AtlasRefundResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request body is malformed — a required field missing or empty, or a field of the wrong type. `message` is an array here, one entry per failed constraint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "401": {
            "description": "The signature is missing, or does not verify. An unknown project, an unknown merchant, a forged signature and an upstream lookup failure are deliberately the same answer, so this endpoint cannot be used to test whether an identifier exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "404": {
            "description": "No refund exists for that `reference_id`.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "500": {
            "description": "The request could not be completed. Nothing about the payment is implied either way — do not treat it as a rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          }
        },
        "tags": [
          "Atlas"
        ]
      }
    },
    "/atlas/payin/status": {
      "post": {
        "operationId": "AtlasController_payinStatus",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AtlasPayinStatusDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Current state of the payment.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiEnvelopeDto"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AtlasPayinStatusResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request body is malformed — a required field missing or empty, a field of the wrong type, or both `payin_id` and `external_id` supplied when exactly one is allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "401": {
            "description": "The signature is missing, or does not verify. An unknown project, an unknown merchant, a forged signature and an upstream lookup failure are deliberately the same answer, so this endpoint cannot be used to test whether an identifier exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "404": {
            "description": "No payin in that project matches the identifier you supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "500": {
            "description": "The request could not be completed. Nothing about the payment is implied either way — do not treat it as a rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          }
        },
        "tags": [
          "Atlas"
        ]
      }
    },
    "/atlas/payout/status": {
      "post": {
        "operationId": "AtlasController_payoutStatus",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AtlasPayoutStatusDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Current state of the payout.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiEnvelopeDto"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AtlasPayoutStatusResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request body is malformed — a required field missing or empty, a field of the wrong type, or both `payout_id` and `external_id` supplied when exactly one is allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "401": {
            "description": "The signature is missing, or does not verify. An unknown project, an unknown merchant, a forged signature and an upstream lookup failure are deliberately the same answer, so this endpoint cannot be used to test whether an identifier exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "404": {
            "description": "No payout in that project matches the identifier you supplied.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "500": {
            "description": "The request could not be completed. Nothing about the payment is implied either way — do not treat it as a rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          }
        },
        "tags": [
          "Atlas"
        ]
      }
    },
    "/atlas/project/list": {
      "post": {
        "operationId": "AtlasController_projectList",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AtlasProjectListDto"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Projects available to the calling merchant.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ApiEnvelopeDto"
                    },
                    {
                      "properties": {
                        "data": {
                          "$ref": "#/components/schemas/AtlasProjectListResponse"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "The request body is malformed — a required field missing or empty, or a field of the wrong type. `message` is an array here, one entry per failed constraint.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "401": {
            "description": "The signature is missing, or does not verify. An unknown project, an unknown merchant, a forged signature and an upstream lookup failure are deliberately the same answer, so this endpoint cannot be used to test whether an identifier exists.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          },
          "500": {
            "description": "The request could not be completed. Nothing about the payment is implied either way — do not treat it as a rejection.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ApiErrorDto"
                }
              }
            }
          }
        },
        "tags": [
          "Atlas"
        ]
      }
    }
  },
  "info": {
    "title": "Atlas API",
    "description": "Merchant-facing REST API for payments, refunds and status lookups. Every request is signed; every response is wrapped in a success envelope.",
    "version": "1.0.0",
    "contact": {}
  },
  "tags": [],
  "servers": [
    {
      "url": "https://api.example.com",
      "description": "Placeholder — your base URL is issued with your credentials"
    }
  ],
  "components": {
    "schemas": {
      "ApiErrorDto": {
        "type": "object",
        "properties": {
          "statusCode": {
            "type": "number",
            "example": 401,
            "description": "Repeats the HTTP status code of the response."
          },
          "message": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "type": "string"
                }
              }
            ],
            "example": "invalid signature",
            "description": "A single string for a rejection raised by the API or relayed from the engine. An array of strings — one per failed constraint — when the request body fails validation, which is the only case that produces more than one reason at a time."
          },
          "error": {
            "type": "string",
            "example": "Unauthorized",
            "description": "The status code's reason phrase, e.g. `Bad Request`."
          }
        },
        "required": [
          "statusCode",
          "message",
          "error"
        ]
      },
      "ApiEnvelopeDto": {
        "type": "object",
        "properties": {
          "success": {
            "type": "boolean",
            "example": true,
            "description": "False never reaches here; a failure is an HTTP error."
          },
          "data": {
            "type": "object",
            "description": "The endpoint payload."
          },
          "timestamp": {
            "type": "string",
            "example": "2026-07-02T00:00:00.000Z",
            "description": "When the response was produced, ISO 8601."
          }
        },
        "required": [
          "success",
          "data",
          "timestamp"
        ]
      },
      "AtlasPaymentResponse": {
        "type": "object",
        "properties": {
          "payin_id": {
            "type": "string",
            "example": "payin_abc123",
            "description": "The payment's identifier in Atlas."
          },
          "redirect_url": {
            "type": "string",
            "example": "https://pay.example.com/hpp/payin_abc123",
            "description": "Always present. Non-empty for a REDIRECT-flow project: send the payer here to complete the payment. An **empty string** when the project uses a DIRECT flow, in which case `payment_details` carries the answer. At most one of the two is non-empty — a HOST payment awaiting a callback has neither — so test the value. The key is always there, and treating its presence as meaningful sends the payer to an empty URL."
          },
          "payment_details": {
            "type": "string",
            "example": "[{\"type\":\"qr\",\"value\":\"0002010102\"}]",
            "description": "Always present. Non-empty for a DIRECT-flow project (QR, PayID, bank reference): a JSON array, as a string, of typed items to show the payer instead of redirecting. An **empty string** when the project redirects instead, in which case `redirect_url` carries the answer. At most one of the two is non-empty — a HOST payment awaiting a callback has neither — so test the value, not the presence of the key."
          }
        },
        "required": [
          "payin_id",
          "redirect_url",
          "payment_details"
        ]
      },
      "CreateAtlasPaymentDto": {
        "type": "object",
        "properties": {
          "project": {
            "type": "string",
            "description": "Which of your projects the payment belongs to — the `project` value from `POST /atlas/project/list`, not the name you gave it in the admin. The project decides the currency, the routing and whether the payer is redirected or shown payment details. An identifier this endpoint does not recognise is a `404`.",
            "example": "VxvcO2tgL9URWTIWGlgPB"
          },
          "amount": {
            "type": "string",
            "description": "How much to charge, as a decimal string: digits, optionally a `.` and more digits. No sign, no grouping separators, no currency symbol — `70.00` and `70` are both accepted, `€70`, `70,00` and `-70` are not. A string and not a number so that a value like `70.10` cannot be rounded on the way here by a client that parsed it as a float.",
            "example": "70.00"
          },
          "currency": {
            "type": "string",
            "description": "The currency of `amount`: an ISO 4217 code, exactly three letters, upper case. Lower case is refused rather than corrected. This is the currency the payer is charged in; a gateway that settles in another one converts, and the webhook then carries `gate_amount` and `gate_currency` alongside these.",
            "example": "EUR"
          },
          "success_url": {
            "type": "string",
            "description": "Where the payer goes after a payment that succeeded. Absolute URL. Used exactly as sent — nothing is appended to it, so a page that needs to know which order it is looking at must carry that in the URL itself. The payer arrives here by clicking through from the hosted page rather than being bounced automatically, and a payer who closes the tab instead never arrives at all: the status webhook, not this URL, is what tells you how the payment ended.",
            "example": "https://shop.example.com/success"
          },
          "failure_url": {
            "type": "string",
            "description": "Where the payer goes after a payment that failed. Absolute URL. Reached the same way as `success_url`, under the same rules — used exactly as sent, and by a payer who clicks through rather than one who is bounced automatically.",
            "example": "https://shop.example.com/failure"
          },
          "cancel_url": {
            "type": "string",
            "description": "Where the payer goes after cancelling the payment themselves — the hosted page offers that as a way out. Absolute URL. Reached the same way as `success_url`, under the same rules — used exactly as sent, and by a payer who clicks through rather than one who is bounced automatically.",
            "example": "https://shop.example.com/cancel"
          },
          "callback_url": {
            "type": "string",
            "description": "Where this payment's status webhooks are sent: a signed `POST` from the platform to this URL every time the payin changes status. It is how the outcome reaches you, so it is required even for a project whose payers never leave your site, and it must be reachable from the internet. Any `2xx` acknowledges a delivery.",
            "example": "https://shop.example.com/callback"
          },
          "signature": {
            "type": "string",
            "description": "HMAC-SHA256 over the request, as a lower-case hex digest. Canonical string: take every field you send except `signature`. An array is always included, even when empty — write it as `[first,second]`, members in the order you send them, and `[]` when it is empty. Any other field whose value is empty is dropped. Sort what is left by field name and join the values with `|`. Values are stringified first, so an unquoted `12` signs as `12` and `true` as `true`. The key is your merchant secret, hex-decoded to bytes. Signed here: every field of this body except `signature` itself — the seven required ones, `external_id` when you send it, the `card_*` fields when the project takes a card, and every optional payer or activity field you send, sorted together as one flat set.",
            "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
          },
          "activity_payin_count": {
            "type": "integer",
            "example": 3,
            "description": "How many payments this user has made. Whole numbers only."
          },
          "activity_payout_count": {
            "type": "integer",
            "example": 1,
            "description": "How many payouts this user has taken. Whole numbers only."
          },
          "segments": {
            "description": "The payer's memberships in your own segments, by the name or id you registered against each segment in the admin. A key we have no segment bound to is ignored. **Sending `[]` and omitting the field are different:** `[]` says the payer is in none of your segments, while omitting it says nothing at all — and if any of your segments is bound, a request that says nothing is refused rather than guessed. Include it in the signature as `[first,second]`, members in the order you send them, and `[]` when empty.",
            "example": [
              "crm_vip"
            ],
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "card_number": {
            "type": "string",
            "pattern": "^\\d{13,19}$",
            "description": "The card number, digits only — no spaces and no dashes. Sent only by a project configured for the HOST flow, which accepts the card in this request. Sending it to a project on any other flow is a `400`, and sending nothing to a HOST project is also a `400`. Handling a raw card number on your own page puts your integration in PCI DSS scope; a project on the invoice flow, where the payer types the card on our hosted page, does not.",
            "example": "4111111111111111"
          },
          "card_holder": {
            "type": "string",
            "description": "The name embossed on the card, as the payer gave it. Sent only by a project configured for the HOST flow, which accepts the card in this request. Sending it to a project on any other flow is a `400`, and sending nothing to a HOST project is also a `400`. Handling a raw card number on your own page puts your integration in PCI DSS scope; a project on the invoice flow, where the payer types the card on our hosted page, does not.",
            "example": "JANE DOE"
          },
          "card_exp_month": {
            "type": "string",
            "pattern": "^(0?[1-9]|1[0-2])$",
            "description": "Expiry month, `1`–`12`. Both `04` and `4` are accepted. Sent only by a project configured for the HOST flow, which accepts the card in this request. Sending it to a project on any other flow is a `400`, and sending nothing to a HOST project is also a `400`. Handling a raw card number on your own page puts your integration in PCI DSS scope; a project on the invoice flow, where the payer types the card on our hosted page, does not.",
            "example": "04"
          },
          "card_exp_year": {
            "type": "string",
            "pattern": "^\\d{2}(\\d{2})?$",
            "description": "Expiry year, two digits or four — `30` and `2030` are the same year. Sent only by a project configured for the HOST flow, which accepts the card in this request. Sending it to a project on any other flow is a `400`, and sending nothing to a HOST project is also a `400`. Handling a raw card number on your own page puts your integration in PCI DSS scope; a project on the invoice flow, where the payer types the card on our hosted page, does not.",
            "example": "2030"
          },
          "card_cvv": {
            "type": "string",
            "pattern": "^\\d{3,4}$",
            "description": "The three or four digit security code. It is used for this one authorisation and its value is never stored — not masked, not encrypted, not written anywhere. The audit trail does record that a CVV was present, as the literal marker `[masked]` in place of the value, never the value itself. Sent only by a project configured for the HOST flow, which accepts the card in this request. Sending it to a project on any other flow is a `400`, and sending nothing to a HOST project is also a `400`. Handling a raw card number on your own page puts your integration in PCI DSS scope; a project on the invoice flow, where the payer types the card on our hosted page, does not.",
            "example": "123"
          },
          "external_id": {
            "type": "string",
            "description": "The merchant's own reference for this payment. Persisted by engine as the\npayin's external_id, which is what POST /atlas/payin/status looks a payin\nup by. Being a top-level field it enters the signature when sent, and\nchanges nothing for a merchant who omits it."
          },
          "description": {
            "type": "string"
          },
          "crypto_address": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "voucher_number": {
            "type": "string"
          },
          "pay_id": {
            "type": "string"
          },
          "ip": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "user_email": {
            "type": "string"
          },
          "user_private_key": {
            "type": "string"
          },
          "user_first_name": {
            "type": "string"
          },
          "user_last_name": {
            "type": "string"
          },
          "user_middle_name": {
            "type": "string"
          },
          "user_phone": {
            "type": "string"
          },
          "user_country": {
            "type": "string"
          },
          "user_city": {
            "type": "string"
          },
          "user_state": {
            "type": "string"
          },
          "user_document": {
            "type": "string"
          },
          "user_document_type": {
            "type": "string"
          },
          "user_birthday_date": {
            "type": "string"
          },
          "user_address": {
            "type": "string"
          },
          "user_address_number": {
            "type": "string"
          },
          "user_zip": {
            "type": "string"
          },
          "user_tax": {
            "type": "string"
          },
          "user_personal_id": {
            "type": "string"
          },
          "affiliate_id": {
            "type": "string"
          },
          "activity_register_date": {
            "type": "string"
          },
          "activity_first_payment_date": {
            "type": "string"
          },
          "activity_payin_amount": {
            "type": "string"
          },
          "activity_payout_amount": {
            "type": "string"
          },
          "activity_kyc": {
            "type": "boolean"
          }
        },
        "required": [
          "project",
          "amount",
          "currency",
          "success_url",
          "failure_url",
          "cancel_url",
          "callback_url",
          "signature"
        ]
      },
      "AtlasPayoutResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "payout_abc123",
            "description": "The payout's identifier in Atlas."
          },
          "status": {
            "type": "string",
            "example": "ROUTED",
            "description": "Current lifecycle state of the payout: `CREATED`, `ROUTED`, `APPROVED`, `PROCESSING`, `COMPLETED`, `PARTIALLY_COMPLETED`, `FAILED`, `EXPIRED` or `CANCELED`. A payout this request just created is always `ROUTED` — a payout that fails during creation ends the request as an error instead (see the 422 response), so this endpoint never itself returns a freshly `FAILED` payout as a success. Any other value means the request repeated an `external_id` already on file: this endpoint then returns the existing payout as-is, in whatever state it has reached since — approval, provider dispatch and settlement all happen through a separate, operator- or worker-driven path this endpoint doesn't expose."
          },
          "sub_status": {
            "type": "string",
            "example": "AWAITING_APPROVAL",
            "description": "The specific reason behind `status`, from a closed vocabulary — `AWAITING_APPROVAL`, `AWAITING_DISPATCH`, `SENT_TO_PROVIDER`, `NOT_ENOUGH_BALANCE`, `NO_SCENARIO`, `NO_ROUTE`, `NO_WALLET`, and others the payout reaches further along. **Always present as a key.** A freshly created payout carries `AWAITING_APPROVAL`; an **empty string** — not an absent key — for a `status` the state machine pairs with none, which is `CREATED`, `COMPLETED` and `PARTIALLY_COMPLETED`."
          },
          "external_id": {
            "type": "string",
            "example": "cashout-1042",
            "description": "Your own idempotency key, echoed back exactly as sent — this is what makes a resend of the same request return the same payout instead of paying out twice. **Always present as a key**, the same guarantee `sub_status` has. In practice it is never empty through this endpoint, since `external_id` is itself a required field of the request; the empty string this key could otherwise carry is only the default for the nullable column it is read from."
          }
        },
        "required": [
          "id",
          "status",
          "sub_status",
          "external_id"
        ]
      },
      "CreateAtlasPayoutDto": {
        "type": "object",
        "properties": {
          "signature": {
            "type": "string",
            "description": "HMAC-SHA256 over the request, as a lower-case hex digest. Canonical string: take every field you send except `signature`. An array is always included, even when empty — write it as `[first,second]`, members in the order you send them, and `[]` when it is empty. Any other field whose value is empty is dropped. Sort what is left by field name and join the values with `|`. Values are stringified first, so an unquoted `12` signs as `12` and `true` as `true`. The key is your merchant secret, hex-decoded to bytes. Signed here: every field of this body except `signature` itself — `project`, `amount`, `currency` and `external_id`, `callback_url` when you send it, and every optional recipient or activity field you send, sorted together as one flat set.",
            "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
          },
          "project": {
            "type": "string"
          },
          "amount": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "external_id": {
            "type": "string",
            "description": "The merchant's own idempotency key. Required here, and load-bearing: the\nwhole create is debounced on it, so the same request sent twice pays out\nonce. That is the difference from `external_id` on a payment, where it is\na convenience you may leave out."
          },
          "callback_url": {
            "type": "string"
          },
          "card_number": {
            "type": "string"
          },
          "card_holder": {
            "type": "string"
          },
          "card_exp_month": {
            "type": "string"
          },
          "card_exp_year": {
            "type": "string"
          },
          "iban": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "account_holder": {
            "type": "string"
          },
          "bank_code": {
            "type": "string"
          },
          "bank_country": {
            "type": "string"
          },
          "bank_address": {
            "type": "string"
          },
          "crypto_address": {
            "type": "string"
          },
          "crypto_address_tag": {
            "type": "string"
          },
          "crypto_network": {
            "type": "string"
          },
          "crypto_currency": {
            "type": "string"
          },
          "wallet_number": {
            "type": "string"
          },
          "payment_email": {
            "type": "string"
          },
          "user_id": {
            "type": "string"
          },
          "user_email": {
            "type": "string"
          },
          "user_first_name": {
            "type": "string"
          },
          "user_last_name": {
            "type": "string"
          },
          "user_middle_name": {
            "type": "string"
          },
          "user_phone": {
            "type": "string"
          },
          "user_country": {
            "type": "string"
          },
          "user_city": {
            "type": "string"
          },
          "user_state": {
            "type": "string"
          },
          "user_document": {
            "type": "string"
          },
          "user_document_type": {
            "type": "string"
          },
          "user_birthday_date": {
            "type": "string"
          },
          "user_address": {
            "type": "string"
          },
          "user_address_number": {
            "type": "string"
          },
          "user_zip": {
            "type": "string"
          },
          "user_tax": {
            "type": "string"
          },
          "user_personal_id": {
            "type": "string"
          },
          "affiliate_id": {
            "type": "string"
          },
          "activity_register_date": {
            "type": "string"
          },
          "activity_first_payment_date": {
            "type": "string"
          },
          "activity_payin_amount": {
            "type": "string"
          },
          "activity_payout_amount": {
            "type": "string"
          },
          "activity_kyc": {
            "type": "boolean"
          },
          "activity_payin_count": {
            "type": "number"
          },
          "activity_payout_count": {
            "type": "number"
          }
        },
        "required": [
          "signature",
          "project",
          "amount",
          "currency",
          "external_id"
        ]
      },
      "AtlasRefundResponse": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "example": "refund_1",
            "description": "The refund's identifier."
          },
          "reference_id": {
            "type": "string",
            "example": "payin_9",
            "description": "The payin being refunded."
          },
          "status": {
            "type": "string",
            "example": "processed",
            "description": "Current state of the refund."
          },
          "amount": {
            "type": "string",
            "example": "1.00",
            "description": "Refunded amount, as a decimal string."
          },
          "currency": {
            "type": "string",
            "example": "USD",
            "description": "Currency of the refund, ISO 4217."
          },
          "provider_refund_id": {
            "type": "string",
            "example": "prov_1",
            "description": "The provider's own refund identifier."
          }
        },
        "required": [
          "id",
          "reference_id",
          "status",
          "amount",
          "currency",
          "provider_refund_id"
        ]
      },
      "CreateAtlasRefundDto": {
        "type": "object",
        "properties": {
          "signature": {
            "type": "string",
            "description": "HMAC-SHA256 over the request, as a lower-case hex digest. Canonical string: take every field you send except `signature`. An array is always included, even when empty — write it as `[first,second]`, members in the order you send them, and `[]` when it is empty. Any other field whose value is empty is dropped. Sort what is left by field name and join the values with `|`. Values are stringified first, so an unquoted `12` signs as `12` and `true` as `true`. The key is your merchant secret, hex-decoded to bytes. Signed here: `description` and `payin_id` — in that order, since `description` sorts first — with `description` left out when you do not send it.",
            "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
          },
          "payin_id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          }
        },
        "required": [
          "signature",
          "payin_id"
        ]
      },
      "AtlasRefundStatusDto": {
        "type": "object",
        "properties": {
          "signature": {
            "type": "string",
            "description": "HMAC-SHA256 over the request, as a lower-case hex digest. Canonical string: take every field you send except `signature`. An array is always included, even when empty — write it as `[first,second]`, members in the order you send them, and `[]` when it is empty. Any other field whose value is empty is dropped. Sort what is left by field name and join the values with `|`. Values are stringified first, so an unquoted `12` signs as `12` and `true` as `true`. The key is your merchant secret, hex-decoded to bytes. Signed here: `reference_id` alone, so the canonical string is just that value.",
            "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
          },
          "reference_id": {
            "type": "string"
          }
        },
        "required": [
          "signature",
          "reference_id"
        ]
      },
      "AtlasPayinStatusResponse": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "string",
            "example": "1.00",
            "description": "Amount the payer was charged, as a decimal string."
          },
          "currency": {
            "type": "string",
            "example": "USD",
            "description": "Currency the payer was charged in, ISO 4217."
          },
          "status": {
            "type": "string",
            "example": "completed",
            "description": "Current state of the payment."
          },
          "created_at": {
            "type": "string",
            "example": "2026-07-02T00:00:00.000Z",
            "description": "When the payment was created, ISO 8601."
          },
          "updated_at": {
            "type": "string",
            "example": "2026-07-02T00:00:00.000Z",
            "description": "When it last changed, ISO 8601."
          },
          "gate_amount": {
            "type": "string",
            "example": "1.00",
            "description": "Amount after gateway conversion, when one happened."
          },
          "gate_currency": {
            "type": "string",
            "example": "EUR",
            "description": "Currency after gateway conversion, when one happened."
          },
          "sub_status": {
            "type": "string",
            "example": "AWAITING_CALLBACK",
            "description": "The specific reason behind `status`. Omitted when the current status is one the state machine pairs with none."
          }
        },
        "required": [
          "amount",
          "currency",
          "status",
          "created_at",
          "updated_at"
        ]
      },
      "AtlasPayinStatusDto": {
        "type": "object",
        "properties": {
          "payin_id": {
            "type": "string",
            "example": "payin_abc123",
            "description": "Atlas's own identifier for the payment. Send exactly one of `payin_id` / `external_id`: sending neither is rejected, and so is sending both."
          },
          "external_id": {
            "type": "string",
            "example": "order-1024",
            "description": "The reference you sent as `external_id` on `POST /atlas/payment`. Send exactly one of `payin_id` / `external_id`: sending neither is rejected, and so is sending both."
          },
          "signature": {
            "type": "string",
            "description": "HMAC-SHA256 over the request, as a lower-case hex digest. Canonical string: take every field you send except `signature`. An array is always included, even when empty — write it as `[first,second]`, members in the order you send them, and `[]` when it is empty. Any other field whose value is empty is dropped. Sort what is left by field name and join the values with `|`. Values are stringified first, so an unquoted `12` signs as `12` and `true` as `true`. The key is your merchant secret, hex-decoded to bytes. Signed here: `external_id`, `payin_id` and `project` — in that order — and since exactly one of the first two is sent, the canonical string is two values, not three.",
            "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
          },
          "project": {
            "type": "string"
          }
        },
        "required": [
          "signature",
          "project"
        ]
      },
      "AtlasPayoutStatusResponse": {
        "type": "object",
        "properties": {
          "amount": {
            "type": "string",
            "example": "100.00",
            "description": "Amount of the payout, as a decimal string."
          },
          "currency": {
            "type": "string",
            "example": "USD",
            "description": "Currency of the payout, ISO 4217."
          },
          "status": {
            "type": "string",
            "example": "PROCESSING",
            "description": "Current lifecycle state of the payout: `CREATED`, `ROUTED`, `APPROVED`, `PROCESSING`, `COMPLETED`, `PARTIALLY_COMPLETED`, `FAILED`, `EXPIRED` or `CANCELED`."
          },
          "created_at": {
            "type": "string",
            "example": "2026-07-02T00:00:00.000Z",
            "description": "When the payout was created, ISO 8601."
          },
          "updated_at": {
            "type": "string",
            "example": "2026-07-02T00:00:00.000Z",
            "description": "When it last changed, ISO 8601."
          },
          "gate_amount": {
            "type": "string",
            "example": "100.00",
            "description": "Amount after gateway conversion, when one happened."
          },
          "gate_currency": {
            "type": "string",
            "example": "EUR",
            "description": "Currency after gateway conversion, when one happened."
          },
          "sub_status": {
            "type": "string",
            "example": "AWAITING_APPROVAL",
            "description": "The specific reason behind `status`, from the same vocabulary as `POST /atlas/payout`. Omitted when the current status is one the state machine pairs with none."
          },
          "external_id": {
            "type": "string",
            "example": "cashout-1042",
            "description": "Your own idempotency key, echoed back exactly as sent. In practice this is never absent through this endpoint, since a payout's `external_id` is a required field of `POST /atlas/payout`."
          }
        },
        "required": [
          "amount",
          "currency",
          "status",
          "created_at",
          "updated_at"
        ]
      },
      "AtlasPayoutStatusDto": {
        "type": "object",
        "properties": {
          "payout_id": {
            "type": "string",
            "example": "payout_abc123",
            "description": "Atlas's own identifier for the payout. Send exactly one of `payout_id` / `external_id`: sending neither is rejected, and so is sending both."
          },
          "external_id": {
            "type": "string",
            "example": "cashout-1042",
            "description": "The reference you sent as `external_id` on `POST /atlas/payout`. Send exactly one of `payout_id` / `external_id`: sending neither is rejected, and so is sending both."
          },
          "signature": {
            "type": "string",
            "description": "HMAC-SHA256 over the request, as a lower-case hex digest. Canonical string: take every field you send except `signature`. An array is always included, even when empty — write it as `[first,second]`, members in the order you send them, and `[]` when it is empty. Any other field whose value is empty is dropped. Sort what is left by field name and join the values with `|`. Values are stringified first, so an unquoted `12` signs as `12` and `true` as `true`. The key is your merchant secret, hex-decoded to bytes. Signed here: `external_id`, `payout_id` and `project` — in that order — and since exactly one of the first two is sent, the canonical string is two values, not three.",
            "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
          },
          "project": {
            "type": "string"
          }
        },
        "required": [
          "signature",
          "project"
        ]
      },
      "AtlasCatalogField": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "example": "user_email",
            "description": "Field name to send in the payment body."
          },
          "label": {
            "type": "string",
            "example": "Email",
            "description": "Human-readable label for a payment form."
          },
          "type": {
            "type": "string",
            "example": "string",
            "description": "Value type expected for this field."
          },
          "default_value": {
            "type": "string",
            "example": "jane@example.com",
            "description": "Value used when none is supplied."
          },
          "format": {
            "type": "string",
            "example": "email",
            "description": "Additional format constraint, when the field has one."
          }
        },
        "required": [
          "name",
          "label",
          "type"
        ]
      },
      "AtlasCatalogProject": {
        "type": "object",
        "properties": {
          "project": {
            "type": "string",
            "example": "VxvcO2tgL9URWTIWGlgPB",
            "description": "Identifier to send as `project` on every request about this project. Opaque — 21 characters of `A-Za-z0-9_-` — and not the project name shown in the admin."
          },
          "type": {
            "type": "string",
            "example": "card",
            "description": "Payment method family."
          },
          "flow_type": {
            "type": "string",
            "example": "REDIRECT",
            "description": "How the payer completes the payment."
          },
          "currencies": {
            "example": [
              "USD",
              "EUR"
            ],
            "description": "Currencies this project accepts.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "currencies_any": {
            "type": "boolean",
            "example": false,
            "description": "True when any currency is accepted and the list is advisory."
          },
          "countries_mode": {
            "type": "string",
            "example": "allow",
            "description": "Whether `countries` is an allow-list or a block-list."
          },
          "countries": {
            "example": [
              "DE",
              "FR"
            ],
            "description": "Countries the mode applies to.",
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "required_fields": {
            "description": "Fields the payment must carry for this project.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AtlasCatalogField"
            }
          },
          "optional_fields": {
            "description": "Fields the payment may carry for this project.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AtlasCatalogField"
            }
          }
        },
        "required": [
          "project",
          "type",
          "flow_type",
          "currencies",
          "currencies_any",
          "countries_mode",
          "countries",
          "required_fields",
          "optional_fields"
        ]
      },
      "AtlasProjectListResponse": {
        "type": "object",
        "properties": {
          "projects": {
            "description": "Projects available to the calling merchant.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AtlasCatalogProject"
            }
          }
        },
        "required": [
          "projects"
        ]
      },
      "AtlasProjectListDto": {
        "type": "object",
        "properties": {
          "signature": {
            "type": "string",
            "description": "HMAC-SHA256 over the request, as a lower-case hex digest. Canonical string: take every field you send except `signature`. An array is always included, even when empty — write it as `[first,second]`, members in the order you send them, and `[]` when it is empty. Any other field whose value is empty is dropped. Sort what is left by field name and join the values with `|`. Values are stringified first, so an unquoted `12` signs as `12` and `true` as `true`. The key is your merchant secret, hex-decoded to bytes. Signed here: `country`, `currency` and `merchant` — in that order — with either filter left out when you do not send it.",
            "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
          },
          "merchant": {
            "type": "string",
            "description": "Merchant tiny id."
          },
          "country": {
            "type": "string",
            "description": "Optional ISO 3166-1 alpha-2 filter. Not validated as a country code here —\nengine normalises it and an unknown code simply matches nothing, which is a\nmore useful answer than a 400."
          },
          "currency": {
            "type": "string",
            "description": "Optional ISO 4217 filter. Same reasoning as `country`."
          }
        },
        "required": [
          "signature",
          "merchant"
        ]
      }
    }
  }
}
