openapi: 3.0.1 info: title: Frhyp API description: "## Changes\n \nFor API changes please see [API Changelog](https://help.frhyp.com/manual/reference/api-changelog/)\n\ \ \n## Guides\n\n* [How to make your first API call](https://help.frhyp.com/manual/guides/make-your-first-api-call/)\n\ * [How to generate API client library](https://help.frhyp.com/manual/guides/openapi/)\n* [Test cards](https://help.frhyp.com/manual/reference/test-cards/)\n\ * [OpenAPI Specification](/api/openapi)\n\n## Authentication\n\nEvery endpoint\ \ requires an `Authorization` header. Which scheme applies depends on\nthe endpoint:\n\ \n| Endpoint | Scheme |\n|---|---|\n| `POST /payments/transfer/{requestorId}`\ \ | `OAuth` — RSA-signed, see [Transfer](https://help.frhyp.com/manual/reference/transfer/) |\n| everything\ \ else | `Bearer` |\n\n### Bearer\n\n```\nAuthorization: Bearer \n\ ```\n\nThe access token is an opaque string issued together with your *requestor*\ \ (end\npoint) in the console. It is not a JWT and carries no readable claims\ \ — do not try\nto decode or refresh it.\n\nA token is valid only for the combination\ \ of three things:\n\n1. the **requestor id** in the path (`/payments/sale/{requestorId}`),\ \ or the\n **merchant login** for `/balance/*` and `/report/transaction/*`;\n\ 2. the **API host** the request arrives at — a token issued for one host does\ \ not\n work on another, even for the same requestor;\n3. the token value itself.\n\ \nIf an **IP allowlist** is configured for your requestor, the request must also\ \ come\nfrom an allowed address. The gateway takes the client address from the\ \ first public\nentry of `X-Forwarded-For`, falling back to `X-Real-IP` — so if\ \ you have your own\nproxy in front, make sure it appends to `X-Forwarded-For`\ \ rather than replacing it.\n\nSend the token only from your backend. It is a\ \ server-side credential and must\nnever appear in browser code, in a mobile app,\ \ or in a URL.\n\n### Errors\n\nEvery error body carries `errorCode`, `errorMessage`\ \ and `errorCorrelationId`.\nQuote the correlation id when you contact support\ \ — it identifies the exact request\nin the gateway logs. Note that `errorCode`\ \ is unique only **together with the HTTP\nstatus**: the same number appears under\ \ different statuses.\n\n| HTTP | errorCode | errorMessage | What to fix |\n|---|---|---|---|\n\ | 400 | `-5` | `Cannot parse requestor id: …` | the last path segment is not a\ \ number |\n| 400 | `-6` | `No Authorization header` | header absent or empty\ \ |\n| 400 | `-7` | `Authorization header should start with 'Bearer '` | wrong\ \ scheme, or a missing space after `Bearer` |\n| 401 | `-7` | `Access token not\ \ found` | wrong token, wrong requestor, or the right token on the wrong host\ \ |\n| 401 | `-20` | `Bad client ip address: …` | source address is not in the\ \ allowlist |\n\n`401 Access token not found` deliberately does not say which\ \ of the three parts did\nnot match. Check them in this order: host, requestor\ \ id, token.\n" version: 1.0.0 servers: - url: https://test.frhyp.com/api description: Test tags: - name: card-info description: | Card lookups that do not move money. `get-card-info` resolves the issuing bank, its country and currency from a card number — use it to route a payment, to show the customer which bank they are about to pay with, or to block card types you do not accept before creating an order. `get-card-history` returns deposit and withdrawal history scores for a card. It is a risk signal, not a decision: combine it with your own rules. Neither call creates an order or charges anything. - name: exchange-rate description: | Currency rates as a specific provider quotes them. The rates are informational: they let you show a customer an expected amount before a cross-currency payment. The rate actually applied to a transaction is fixed at processing time by the provider, and can differ from what this endpoint returned a moment earlier. - name: balance description: | Current balances of a merchant. Three figures matter and they are not the same: `realBalance` is everything on the balance, `totalShortTermHold` and `totalRollingReserve` are the parts you cannot touch yet, and `liveBalance` is what is actually available after pending outgoing operations (`totalProcessingAmount`) are deducted. Balances are read-only here — they move as a result of payments and settlements, not through this API. - name: payments description: | ## Payments Card payments: one-step purchases (`sale`), two-step authorization and capture (`auth` + `capture`), reversals, card-to-card transfers, and zero-amount account verification. Two integration styles run through the same endpoints. The `*-form` variants hand the customer to a payment form hosted by the gateway, so card data never touches your servers; the others take card data directly, which puts your systems in PCI DSS scope. See [Choosing an integration method](https://help.frhyp.com/manual/guides/choosing-integration-method/). Every call returns a `StatusResponse` and an HTTP `200` means only that the request was accepted. The payment result is `orderState`, and it may still be non-final when you get the response. - name: recurring description: | Card registration for repeat payments. Once an order has been approved, register its card to get a `cardId`. Later payments then reference that `cardId` with `paymentMethod: CARD_ID` instead of card data, which keeps card numbers out of your systems for subsequent charges. The stored identifier is scoped to your requestor. It is not a payment instrument on its own: it only works through this API, for this requestor. - name: report description: | Transaction reports for reconciliation and bookkeeping. The report returns one row per **transaction**, not per order: a single order that was authorized and then captured produces several rows, linked by `orderSystemId`. This is the endpoint to reconcile against your own ledger and against the acquirer statement. For the state of one specific order, use `/payments/status` instead — it is cheaper and answers immediately. - name: 3ds description: | For more details, refer to the [3-D Secure](https://help.frhyp.com/manual/guides/3ds/) reference. - name: webhook description: | The callback the gateway sends to **you** when an order changes state. This is the recommended way to learn a payment's outcome: it removes the polling loop around `/payments/status`, and it is the only way to hear about changes that happen long after the original request, such as a chargeback. The body is the same `StatusResponse` object that `/payments/status` returns, so one handler can serve both. The endpoint documented here describes that payload — you implement it on your side and register the URL for your requestor. paths: /3ds/_Overview: head: tags: - 3ds summary: Overview description: | For more details, refer to the [3-D Secure](https://help.frhyp.com/manual/guides/3ds/) reference. responses: "200": description: Only for documentation purpose security: [] x-internal: true /3ds/cres/{requestorId}: post: tags: - 3ds summary: cres description: | Uploads the CRes returned by the ACS at the end of an EMV 3DS 2.x challenge. The gateway asks for a challenge by returning `threeDSAuth.threeDSAuthStep = CREQ` with `creq` (base64url-encoded) and `acsUrl`. Post the `creq` to the ACS in an iframe; when the cardholder finishes, the ACS posts the `CRes` to the `cresUrl` you supplied. Forward it here with `orderSystemId` — both fields are required. Send the value exactly as received, with no re-encoding. The response is a `StatusResponse` with the state after authentication, and it may still be non-final — a successful challenge means the cardholder was authenticated, not that the issuer approved the payment. operationId: submitCRes requestBody: content: application/json: schema: $ref: '#/components/schemas/CResRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /3ds/method/{requestorId}: post: tags: - 3ds summary: method description: | Reports the result of the 3DS Method back to the gateway. The 3DS Method is the invisible iframe step that runs before authentication and lets the issuer fingerprint the browser. The gateway asks for it by returning `threeDSAuth.threeDSAuthStep = THREEDS_METHOD` with `threeDSMethodUrl` and `threeDSMethodTransactionId`. Load that URL in a hidden iframe, wait for it to finish, then call this endpoint with `orderSystemId`, `browser`, `threeDSServerTransID`, `cresUrl` (where the ACS should deliver the CRes), and `threeDSCompInd` — `Y` if the method completed, `N` if it did not, `U` if it could not run. All five are required. A method that fails is not an error: report `N` or `U` and the flow continues, usually with a challenge. What breaks authentication is not reporting at all — the issuer waits, then times out. operationId: submitThreeDSMethod requestBody: content: application/json: schema: $ref: '#/components/schemas/ThreeDSMethodRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /3ds/pares/{requestorId}: post: tags: - 3ds summary: pares description: | Uploads the PaRes returned by the issuer in a 3-D Secure 1.0.2 flow. The gateway asks for it by returning `threeDSAuth.threeDSAuthStep = PAREQ` with `paReq` and `acsUrl`. Post the customer to the ACS, and the ACS posts the `PaRes` back to your return URL. Forward it here with `orderSystemId` — both fields are required. Send the value exactly as received, with no re-encoding: it is signed, and any change invalidates it. The response is a `StatusResponse` with the state after authentication. It may still be non-final; take the outcome from `/payments/status` or the webhook. operationId: submitPaRes requestBody: content: application/json: schema: $ref: '#/components/schemas/PaResRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /balance/_Overview: head: tags: - balance summary: Overview description: | Current balances of a merchant. Three figures matter and they are not the same: `realBalance` is everything on the balance, `totalShortTermHold` and `totalRollingReserve` are the parts you cannot touch yet, and `liveBalance` is what is actually available after pending outgoing operations (`totalProcessingAmount`) are deducted. Balances are read-only here — they move as a result of payments and settlements, not through this API. responses: "200": description: Only for documentation purpose security: [] x-internal: true /balance/by-manager/{username}: post: tags: - balance summary: by-manager description: | Returns a named balance from the manager's side, together with the merchant it belongs to (`merchantLogin`, `externalMerchantId`). The body names the balance (`balanceName`), the same as `by-merchant`. Note that this response uses different field names for the same figures than `by-merchant` does: `amount` for the full balance, `onlineBalanceLiveAmount` for the available part, `totalShortTermHoldAmount`, `totalRollingReserveAmount` and `amountBufferHold`. Map them explicitly rather than reusing your `by-merchant` parser. operationId: getManagerBalance requestBody: content: application/json: schema: $ref: '#/components/schemas/BalanceNamedRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/BalanceManagerResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: username in: path description: Merchant Login Name required: true schema: type: string example: merchant1 /balance/by-merchant-all/{username}: post: tags: - balance summary: by-merchant-all description: | Returns every balance of the merchant at once, as `merchantBalances`. Unlike `by-merchant`, this call takes no request body — the merchant login in the path is enough. Each entry has the same shape as the `by-merchant` response: `balanceName`, `balanceCurrency`, `realBalance`, `liveBalance`, `totalShortTermHold`, `totalRollingReserve` and `totalProcessingAmount`. Use this when you do not know the balance names in advance, or when you need a complete picture in one request instead of one call per balance. operationId: getMerchantBalances responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/BalanceMerchantAllResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: username in: path description: Merchant Login Name required: true schema: type: string example: merchant1 /balance/by-merchant/{username}: post: tags: - balance summary: by-merchant description: | Returns one named balance of a merchant. The path parameter is the merchant login; the body names the balance (`balanceName`). `realBalance` is everything on the balance. `totalShortTermHold` and `totalRollingReserve` are the parts held back — by date bumping and by the rate plan respectively — and `totalProcessingAmount` is the amount reserved for outgoing operations that have no final status yet. `liveBalance` is what remains available. To get every balance in one request without knowing the names, use `by-merchant-all`. operationId: getMerchantBalance requestBody: content: application/json: schema: $ref: '#/components/schemas/BalanceNamedRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/BalanceMerchantResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: username in: path description: Merchant Login Name required: true schema: type: string example: merchant1 /card-info/_Overview: head: tags: - card-info summary: Overview description: | Card lookups that do not move money. `get-card-info` resolves the issuing bank, its country and currency from a card number — use it to route a payment, to show the customer which bank they are about to pay with, or to block card types you do not accept before creating an order. `get-card-history` returns deposit and withdrawal history scores for a card. It is a risk signal, not a decision: combine it with your own rules. Neither call creates an order or charges anything. responses: "200": description: Only for documentation purpose security: [] x-internal: true /card-info/get-card-history/{requestorId}: post: tags: - card-info summary: get-card-history description: | Returns deposit and withdrawal history scores for a card, as a risk signal for an order you are about to create. Identify the card in one of two ways, and say which one you used in `cardHistorySourceType`: * `FULL_CARD_NUMBER` — send `cardNumber`, leave `cardFirstDigits` and `cardLastDigits` empty. * `FIRST_6_LAST_4` — send `cardFirstDigits` (6) and `cardLastDigits` (4), leave `cardNumber` empty. `expireMonth` and `expireYear` are always required, as is your `orderMerchantId`. The response is symmetric for deposits and withdrawals: whether any were found, over how many days, a score between 0 and 1, whether several sources were involved, and for deposits a `depositsHighRoller` flag. Scores are advisory. The gateway does not decline a payment because of them — the decision, and its threshold, are yours. operationId: getCardHistory requestBody: content: application/json: schema: $ref: '#/components/schemas/CardHistoryRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/CardHistoryResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /card-info/get-card-info/{clientId}: post: tags: - card-info summary: get-card-info description: | Resolves the issuer of a card from its number (BIN lookup). Note the path parameter: this endpoint takes your **client id**, not a requestor id. Send the full card number in `cardNumber`. The response tells you whether the card was found (`result`), and for a found card returns `cardIssuerName`, `cardIssuerCountryCode` (ISO 3166) and `cardCurrencyCode` (ISO 4217). `result` values: * `FOUND` — issuer data is in the response. * `NOT_FOUND_01`, `NOT_FOUND_02` — the BIN is not in the database. Treat both as "unknown issuer" and fall back to your default routing; do not decline on this alone. The card number is used for the lookup only — nothing is stored as an order, and no authorization is performed. operationId: getCardInfo requestBody: content: application/json: schema: $ref: '#/components/schemas/CardInfoRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/CardInfoResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: clientId in: path description: Client ID of your application required: true schema: type: string example: "1" /exchange-rate/_Overview: head: tags: - exchange-rate summary: Overview description: | Currency rates as a specific provider quotes them. The rates are informational: they let you show a customer an expected amount before a cross-currency payment. The rate actually applied to a transaction is fixed at processing time by the provider, and can differ from what this endpoint returned a moment earlier. responses: "200": description: Only for documentation purpose security: [] x-internal: true /exchange-rate/get-exchange-rate/{requestorId}: post: tags: - exchange-rate summary: get-exchange-rate description: | Returns one provider's rate for a currency pair. All three fields are required: `exchangeProvider`, plus `exchangeCurrencyCodeFrom` and `exchangeCurrencyCodeTo` as three-letter ISO 4217 codes. Two rates come back, both from the provider's point of view: `exchangeLowRate` is the rate at which the provider buys, `exchangeHighRate` the rate at which it sells. Which one applies to you depends on the direction of your payment. Do not cache the result for long, and do not use it to settle anything — see the note on the section page. operationId: getExchangeRate requestBody: content: application/json: schema: $ref: '#/components/schemas/ExchangeRateRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/ExchangeRateResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /payments/_Overview: head: tags: - payments summary: Overview description: | ## Payments Card payments: one-step purchases (`sale`), two-step authorization and capture (`auth` + `capture`), reversals, card-to-card transfers, and zero-amount account verification. Two integration styles run through the same endpoints. The `*-form` variants hand the customer to a payment form hosted by the gateway, so card data never touches your servers; the others take card data directly, which puts your systems in PCI DSS scope. See [Choosing an integration method](https://help.frhyp.com/manual/guides/choosing-integration-method/). Every call returns a `StatusResponse` and an HTTP `200` means only that the request was accepted. The payment result is `orderState`, and it may still be non-final when you get the response. responses: "200": description: Only for documentation purpose security: [] x-internal: true /payments/account-verification/{requestorId}: post: tags: - payments summary: account-verification description: | Zero-amount verification: checks that a card is valid and active without charging it. The request has the same shape as `sale` — `order` and `browser` are required, and `paymentMethod` selects how the card is supplied. No money moves and nothing is blocked on the card. Use it to validate a card before storing it for recurring payments, or at sign-up where you need a usable card on file but nothing to charge yet. Register the card with `/recurring/register-cards` afterwards to get a reusable `cardId`. Verification can require 3-D Secure exactly like a payment: the response may carry `threeDSAuth` with `outputHtml` or `outputRedirectToUrl`, and the result is final only once `orderState` is final. operationId: verifyAccount requestBody: content: application/json: schema: $ref: '#/components/schemas/AccountVerificationRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /payments/auth-form/{requestorId}: post: tags: - payments summary: auth-form description: | Payment Form integration is relevant for merchants who are not able to accept customer. card details (merchant’s website must complete PCI DSS certification).. In case of Payment Form integration merchant is released of accepting payment details. and all this stuff is completely implemented on the gateway side.. In addition, merchant may customize the look and feel of the Payment Form.. Merchant must send the template to their Manager for approval before it could be used. operationId: createAuthForm requestBody: content: application/json: schema: $ref: '#/components/schemas/SaleFormStartRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /payments/auth/{requestorId}: post: tags: - payments summary: auth description: | ## Authorization Merchant Site initiates a Pre-auth transaction by sending corresponding HTTPS POST request to the specified URL The System processes the transaction and sends corresponding response (depending on 3DS/non-3DS processing type). Upon successful completion of a preauth transaction the bank blocks the specified amount in the credit card account and does not allow the cardholder to use this blocked money. It is important to know that the block remains for a definite period of time depending on whether this is a debit or a credit card (usually the maximum block period is 7 days for debit cards and 28 days for credit cards). Merchant sends Capture transaction in order to deduct the locked amount from credit card. System processes capture transaction and returns corresponding response. In this case the money is actually transferred from the bank-issuer account to the bank-acquirer account, which means the end of the transaction. operationId: createAuth requestBody: content: application/json: schema: $ref: '#/components/schemas/AuthRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /payments/capture/{requestorId}: post: tags: - payments summary: capture description: | Charges an amount that a previous `auth` has blocked on the card. Identify the order by `orderSystemId` or by your own `orderMerchantId`. Omit `captureAmount` to capture the full authorized amount, or send a smaller one for a partial capture — you cannot capture more than was authorized. Capture before the authorization expires. The block typically lasts around 7 days for debit cards and 28 for credit cards, but the exact window is the issuer's, not the gateway's. After it lapses the money is released to the cardholder and the capture will be declined. The response is a `StatusResponse`; as always, `orderState` is the answer, not the HTTP status. operationId: captureAuth requestBody: content: application/json: schema: $ref: '#/components/schemas/CaptureRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /payments/reversal/{requestorId}: post: tags: - payments summary: reversal description: | Reverses a transaction — a void before the funds settle, a refund afterwards. The gateway picks the right one; you do not choose. `orderSystemId` and `reversalReason` are required. Omit `reversalAmount` for a full reversal, or send a smaller amount for a partial one. Several partial reversals are possible as long as their sum does not exceed the captured amount. `reversalReason` is free text and ends up in the transaction report, so write something a person reconciling the report will understand. A refund is not instant for the cardholder: the gateway state goes final long before the money appears on the statement, which usually takes several business days. operationId: reverseTransaction requestBody: content: application/json: schema: $ref: '#/components/schemas/ReversalRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /payments/sale-form/{requestorId}: post: tags: - payments summary: sale-form description: | One-step purchase through the payment form hosted by the gateway. Your server never sees card data, which keeps it out of PCI DSS scope. You send the order, the customer, and the browser context; the gateway returns where to send the customer next — `outputRedirectToUrl` to redirect, or `outputHtml` to render as is, without modification. `order`, `customer` and `browser` are required. Put your return addresses in `urls` — that is where the customer comes back after paying or cancelling. The customer's return to your site is **not** the payment result: they may close the tab on the way back. Take the outcome from the [webhook](https://help.frhyp.com/manual/reference/webhook/) or from `/payments/status`, never from the redirect alone. The look of the form can be customised, but the template has to be approved by your account manager before it can be used. operationId: createSaleForm requestBody: content: application/json: schema: $ref: '#/components/schemas/SaleFormStartRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /payments/sale/{requestorId}: post: tags: - payments summary: sale description: | One-step purchase: authorization and capture in a single request. The money moves without any further call from you. Use `sale` when you ship or deliver immediately. If there is a gap between the order and the delivery, use `auth` and `capture` instead — an authorization can be released, a completed sale can only be reversed. Choose how the card reaches the gateway with `paymentMethod`: raw card data (`CARD`), a previously registered card (`CARD_ID`), an Apple Pay or Google Pay token, open banking, a QR code, or a BLIK code. Sending raw card data puts your servers in PCI DSS scope — `sale-form` avoids that. The response is a `StatusResponse`. A `200` means the request was accepted, not that the payment succeeded: read `orderState`. `PROCESSING` and `CHAIN_STEP` are not final — keep polling `/payments/status` or wait for the webhook. If 3-D Secure is required, the response carries `threeDSAuth` together with `outputHtml` or `outputRedirectToUrl`. Send your own `orderMerchantId` with every request. It is how you find the order again if the response never reaches you. operationId: createSale requestBody: content: application/json: schema: $ref: '#/components/schemas/SaleRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /payments/status/{requestorId}: post: tags: - payments summary: status description: | For more details, refer to the [Status](https://help.frhyp.com/manual/reference/status/) reference. Returns the current state of an order. This is the authoritative read — the state here always wins over what you saw in the response to `sale`, `auth` or `capture`. Identify the order by `orderSystemId`, by your own `orderMerchantId`, or by `byCorrelationId` from an earlier response. For a multi-currency requestor, add `orderCurrencyCode`. `orderState` is final for `APPROVED`, `DECLINED`, `ERROR` and `FILTERED`. For `PROCESSING`, `UNKNOWN` and `CHAIN_STEP` keep polling — a few seconds apart, not in a tight loop — or wait for the [webhook](https://help.frhyp.com/manual/reference/webhook/), which carries this same object and saves you the polling. `transactions` lists the individual transactions of the order, so an authorization and its capture are both visible here. operationId: getOrderStatus requestBody: content: application/json: schema: $ref: '#/components/schemas/StatusRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /payments/transfer/{requestorId}: post: tags: - payments summary: transfer description: | For more details, refer to the [Transfer](https://help.frhyp.com/manual/reference/transfer/) reference. ## Authorization `transfer` is the only endpoint that is **not** authorized with a bearer token. Each request is signed with your RSA private key and carries an OAuth 1.0a `Authorization` header extended with `oauth_body_hash` ([draft-eaton-oauth-bodyhash-00](https://datatracker.ietf.org/doc/id/draft-eaton-oauth-bodyhash-00.html)). Before the first call, your **public** key is registered for your requestor together with a consumer key. The private key never leaves your side. As with bearer authorization, the credentials are bound to the requestor id **and** to the API host, and any IP allowlist configured for the requestor applies here too. ### Signing algorithm The signature is `SHA256withRSA`, and this is fixed: `oauth_signature_method` must say `RSA-SHA256`. **1. Hash the body.** Take the raw request body exactly as it will be sent — the same bytes, no re-serialization, no whitespace changes: ``` oauth_body_hash = base64( sha256( ) ) ``` **2. Collect the OAuth parameters.** All six are required; a missing one is a `400`, not a `401`. | Parameter | Value | |---|---| | `oauth_body_hash` | from step 1 | | `oauth_consumer_key` | the consumer key issued with your requestor | | `oauth_nonce` | a unique random string per request | | `oauth_signature_method` | `RSA-SHA256` | | `oauth_timestamp` | current Unix time in **seconds** | | `oauth_version` | `1.0` | **3. Build the parameter string** ([RFC 5849 §3.4.1.3](https://tools.ietf.org/html/rfc5849#section-3.4.1.3)). Sort the parameters by name, percent-encode each **value** per RFC 3986 — unreserved characters are `A-Z a-z 0-9 - . _ ~`, a space is `%20`, `*` is `%2A` — and join them with `&`: ``` oauth_body_hash=hp%2BTgzX1VxEJRIBTjwJMXNBCziyj9Dlujn%2B7KJtqC7s%3D&oauth_consumer_key=consumerKey-1&oauth_nonce=kDc0elvhn4S&oauth_signature_method=RSA-SHA256&oauth_timestamp=1678339009&oauth_version=1.0 ``` Do not add query parameters to the URL. If you do, they have to be folded into this string as well, which is easy to get wrong. **4. Build the signature base string** from three parts joined by `&` — the uppercase HTTP method, the percent-encoded base URI, and the percent-encoded parameter string: ``` POST&https%3A%2F%2Ftest.frhyp.com%2Fapi%2Fpayments%2Ftransfer%2F1&oauth_body_hash%3Dhp%252BTgzX1…%26oauth_consumer_key%3DconsumerKey-1%26… ``` The **base URI** follows [RFC 5849 §3.4.1.2](https://tools.ietf.org/html/rfc5849#section-3.4.1.2): lowercase scheme and authority, the default port omitted, path as sent, **no query string and no fragment**. It is the URL you actually call — the base URL from `servers` above plus the path: ``` https://test.frhyp.com/api/payments/transfer/1 ``` **5. Sign.** `SHA256withRSA` over the UTF-8 bytes of the signature base string, base64-encoded: ``` oauth_signature = base64( rsaSha256( utf8(), ) ) ``` **6. Build the header.** The six parameters plus `oauth_signature`, each value in double quotes, separated by commas. Percent-encoding the values is recommended; raw base64 is also accepted. ``` Authorization: OAuth oauth_consumer_key="consumerKey-1",oauth_nonce="kDc0elvhn4S",oauth_signature_method="RSA-SHA256",oauth_timestamp="1678339009",oauth_version="1.0",oauth_body_hash="hp%2BTgzX1VxEJRIBTjwJMXNBCziyj9Dlujn%2B7KJtqC7s%3D",oauth_signature="PxCYhXN8wiuIM5O589oSLyOrDCXiJO8c…" ``` ### Debugging a 401 The signature error tells you exactly what the gateway signed. The `context` of a `-13` error contains `baseUrl`, `paramString` and `signatureBaseString` as the **server** computed them — diff them against yours and the mismatch is usually visible in the first line. Look at `baseUrl` first. It is built from the URL as the gateway received it, so a proxy in front of you that changes scheme, host or port makes your signature and the gateway's disagree even though your code is correct. ### Errors | HTTP | errorCode | Meaning | |---|---|---| | 400 | `-6` | no `Authorization` header | | 400 | `-7` | header does not start with `OAuth ` | | 400 | `-18` | a required `oauth_*` parameter is missing; `invalidParams` names it | | 401 | `-19` | body hash mismatch — `context` has `expected-sha256` and `actual-sha256` | | 401 | `-7` | consumer key not known for this requestor and host | | 401 | `-10` / `-11` / `-12` / `-36` | no public key registered, or it cannot be read | | 401 | `-13` | signature does not verify — `context` has `baseUrl`, `paramString`, `signatureBaseString` | | 401 | `-18` | `oauth_signature` is not valid base64 | | 401 | `-20` | source address is not in the allowlist | The most common causes, in order: base URI mismatch, body re-serialized after hashing, and values not percent-encoded in the parameter string. ### Reference implementation `TransferSignatureBuilder` in the `standin-remote-client` library builds this header in a few lines. In any other language the steps above are plain OAuth 1.0a with `RSA-SHA256` plus the `oauth_body_hash` extension, so most OAuth 1.0a libraries can produce the header once you add `oauth_body_hash` as an extra parameter before signing. operationId: createTransfer requestBody: content: application/json: schema: $ref: '#/components/schemas/TransferRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/StatusResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - oauth_body_hash: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /recurring/_Overview: head: tags: - recurring summary: Overview description: | Card registration for repeat payments. Once an order has been approved, register its card to get a `cardId`. Later payments then reference that `cardId` with `paymentMethod: CARD_ID` instead of card data, which keeps card numbers out of your systems for subsequent charges. The stored identifier is scoped to your requestor. It is not a payment instrument on its own: it only works through this API, for this requestor. responses: "200": description: Only for documentation purpose security: [] x-internal: true /recurring/register-cards/{requestorId}: post: tags: - recurring summary: register-cards description: | Registers the card (or cards) used in an existing order and returns identifiers for reuse. Identify the order with both `orderSystemId` and `orderMerchantId` — both are required. The response returns `cardId` for the payer's card and, for transfers, `receiverCardId` for the recipient's card. Store the ones you need; pass a stored `cardId` in a later `sale` or `auth` request with `paymentMethod: CARD_ID`, adding `cardIdCvv2` when the scheme requires it. Register the card after the order reaches a final approved state. Registering a card from a declined order gives you an identifier that will not be usable. operationId: registerCards requestBody: content: application/json: schema: $ref: '#/components/schemas/RegisterCardsRequest' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/RegisterCardsResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: requestorId in: path description: Requestor ID required: true schema: type: integer example: "1" /report/_Overview: head: tags: - report summary: Overview description: | Transaction reports for reconciliation and bookkeeping. The report returns one row per **transaction**, not per order: a single order that was authorized and then captured produces several rows, linked by `orderSystemId`. This is the endpoint to reconcile against your own ledger and against the acquirer statement. For the state of one specific order, use `/payments/status` instead — it is cheaper and answers immediately. responses: "200": description: Only for documentation purpose security: [] x-internal: true /report/transaction/{username}: post: tags: - report summary: transaction description: | Returns transaction rows for a period. The path parameter is your **merchant login**, not a requestor id. Choose the period with `periodFrom` and `periodTo` (`YYYY-MM-dd HH:mm:ss`) and say which date they refer to in `periodType`: * `SYSTEM_DATE` — when the transaction was created in the gateway. Use this to reconcile against your own records. * `ACQUIRER_DATE` — the acquirer reconciliation date. Use this to reconcile against a bank statement, where the same transaction may fall on a different day. `utcOffsetHours` shifts the period into your local time; the default is UTC. `reportFormat` selects the output: `JSON` (default shape of this API), `CSV`, `CSV_UNDERSCORE`, `JSON_EACH_ROW` or `PRETTY_JSON_EACH_ROW`. Each row carries the order identifiers, transaction type and status, the amounts (`transactionAmount`, `captureAmount`, `reversalAmount`, `transactionCommission`), the processing-currency equivalents (`outcome*`), the card and issuer data, the acquirer references (`transactionRrn`, `transactionArn`) and the routing that was used (provider, bank terminal, channel, blueprint). Amounts are strings in major units with a dot, the same as everywhere else in this API: `"10.5"` is ten dollars fifty. Ask for the period you need and no more. A wide period over a busy merchant is a large response, and the report is rate limited. operationId: getTransactionReport requestBody: content: application/json: schema: $ref: '#/components/schemas/TransactionReportRequest' responses: "200": description: Success response content: application/json: schema: type: array items: $ref: '#/components/schemas/TransactionReportRow' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] parameters: - name: username in: path description: Merchant Login Name required: true schema: type: string example: merchant1 /webhook/_Overview: head: tags: - webhook summary: Overview description: | The callback the gateway sends to **you** when an order changes state. This is the recommended way to learn a payment's outcome: it removes the polling loop around `/payments/status`, and it is the only way to hear about changes that happen long after the original request, such as a chargeback. The body is the same `StatusResponse` object that `/payments/status` returns, so one handler can serve both. The endpoint documented here describes that payload — you implement it on your side and register the URL for your requestor. responses: "200": description: Only for documentation purpose security: [] x-internal: true /webhook/webhook: post: tags: - webhook summary: webhook description: | For more details, refer to the [Webhook](https://help.frhyp.com/manual/reference/webhook/) reference. operationId: receiveWebhook requestBody: content: application/json: schema: $ref: '#/components/schemas/StatusResponse' responses: "200": description: Success response content: application/json: schema: $ref: '#/components/schemas/VoidResponse' "400": description: BadRequest content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/BadRequestError' "401": description: Unauthorized content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/UnauthorizedError' "500": description: InternalSystemError content: application/json; charset=utf-8: schema: $ref: '#/components/schemas/InternalSystemError' security: - bearerAuth: [] components: schemas: CardHistoryResponse: required: - depositsDaysUsed - depositsFound - depositsHighRoller - depositsMultipleSources - depositsScore - orderMerchantId - orderSystemId - withdrawalsDaysUsed - withdrawalsFound - withdrawalsMultipleSources - withdrawalsScore type: object properties: correlationId: type: string description: Serial number assigned to the specific response example: 656454a2-3fff-4663-abdf-b30180136678 depositsFound: type: boolean description: Deposits found example: true depositsDaysUsed: type: integer description: Deposits days used format: int32 example: 302 depositsScore: type: number description: Deposits score example: 0.9 depositsMultipleSources: type: boolean description: Deposits multiple sources example: true depositsHighRoller: type: boolean description: Deposits high roller example: true withdrawalsFound: type: boolean description: Withdrawals found example: true withdrawalsDaysUsed: type: integer description: Withdrawals days used format: int32 example: 302 withdrawalsScore: type: number description: Withdrawals score example: 0.9 withdrawalsMultipleSources: type: boolean description: Withdrawals multiple sources example: true orderSystemId: type: integer description: System Order ID format: int64 example: 12121212 orderMerchantId: type: string description: Merchant Order ID example: 02618145-2e65-46ac-a08f-00bda7acad27 CardHistoryRequest: required: - cardHistorySourceType - expireMonth - expireYear - orderMerchantId type: object properties: orderMerchantId: type: string description: Merchant Order ID example: 02618145-2e65-46ac-a08f-00bda7acad27 cardHistorySourceType: maxLength: 19 minLength: 13 type: string description: |- Card source. * `FULL_CARD_NUMBER` – all digits in card number. Field `cardNumber` should be present. Example: `cardNumber` = `4444444444443333` * `FIRST_6_LAST_4` – First 6 and last 4 digits of card number. Fields `cardFirstDigits` and `cardLastDigits` should be present. Example: `cardFirstDigits` = `444444` and `cardLastDigits` = `3333` example: FIRST_6_LAST_4 enum: - FULL_CARD_NUMBER - FIRST_6_LAST_4 cardNumber: maxLength: 19 minLength: 13 type: string description: |- Card number. **Note:** if cardNumber is presented than cardHistorySourceType = FULL_CARD_NUMBER but cardFirstDigits and cardLastDigits should be empty example: "4444444444443333" expireMonth: maxLength: 2 minLength: 1 type: string description: Card expiration month example: "12" expireYear: maxLength: 4 minLength: 2 type: string description: Card expiration year example: "2029" cardFirstDigits: maxLength: 6 minLength: 6 type: string description: |- Card first digits. * If cardFirstDigits is presented * than `cardLastDigits` and `cardHistorySourceType = 'FIRST_6_LAST_4'` should be presented * but `cardNumber` should be absent example: "444444" cardLastDigits: maxLength: 4 minLength: 4 type: string description: |- Card last digits. * If cardLastDigits is presented * than `cardFirstDigits` and `cardHistorySourceType = 'FIRST_6_LAST_4'` should be presented * but `cardNumber` should be absent example: "3333" CardInfoResponse: type: object properties: result: type: string description: Card search result example: FOUND enum: - FOUND - NOT_FOUND_01 - NOT_FOUND_02 correlationId: type: string description: Serial number assigned to the specific response example: 656454a2-3fff-4663-abdf-b30180136678 cardIssuerName: type: string description: Bank name by customer card BIN example: Gringotts Wizarding Bank cardIssuerCountryCode: type: string description: Indicates the country of the issuer according to ISO 3166 example: US cardCurrencyCode: type: string description: ISO 4217 Currency code example: USD CardInfoRequest: required: - cardNumber type: object properties: cardNumber: maxLength: 19 minLength: 13 type: string description: Card number example: "4444444444443333" ExchangeRateResponse: type: object properties: exchangeLowRate: type: string description: Provider's buy rate exchangeHighRate: type: string description: Provider's sale rate ExchangeRateRequest: required: - exchangeCurrencyCodeFrom - exchangeCurrencyCodeTo - exchangeProvider type: object properties: exchangeProvider: type: string description: Input your exchange provider exchangeCurrencyCodeFrom: type: string description: "Input currency code that you need to exchange (for example:\ \ USD, EUR, RUB)" exchangeCurrencyCodeTo: type: string description: "Input currency code that you need to get (for example: USD,\ \ EUR, RUB)" BalanceManagerResponse: type: object properties: name: type: string description: Balance name example: BalanceTest1 currency: type: string description: Currency used for selected balance example: USD amount: type: number description: Current balance including STH and Rolling reserve example: 0.0 onlineBalanceLiveAmount: type: number description: Current balance calculated from configuration excluding STH and Rolling reserve. Live = current - STH - RR example: 0.0 totalShortTermHoldAmount: type: number description: Current amount of hold based on Date bumping function example: 0.0 totalRollingReserveAmount: type: number description: Current amount calculated from rate plan hold example: 0.0 amountBufferHold: type: number description: Calculated amount for OUT operations without final status example: 0.0 merchantLogin: type: string description: Merchant login example: merchant-1 externalMerchantId: type: string description: External merchant identifier example: "123123" BalanceNamedRequest: required: - balanceName type: object properties: balanceName: type: string description: Your balance name BalanceMerchantResponse: type: object properties: balanceName: type: string description: Balance name example: BalanceTest1 balanceCurrency: type: string description: Balance currency example: USD realBalance: type: number description: Current balance including totalShortTermHold and Rolling reserve example: 0.0 liveBalance: type: number description: |- Current balance calculated from configuration excluding totalShortTermHold and totalRollingReserve `LiveBalance = realBalance - totalProcessingAmount` example: 0.0 totalShortTermHold: type: number description: Current amount of hold based on Date bumping function example: 0.0 totalRollingReserve: type: number description: Current amount calculated from rate plan hold example: 0.0 totalProcessingAmount: type: number description: Calculated amount for OUT operations without final status example: 0.0 BalanceMerchantAllResponse: type: object properties: merchantBalances: type: array items: $ref: '#/components/schemas/BalanceMerchantResponse' VoidRequest: type: object OrderOutputAttribute: required: - name - value type: object properties: name: maxLength: 64 type: string description: Order attribute name example: avsCheckCode value: maxLength: 64 type: string description: Order attribute value example: "01" StatusResponse: required: - orderAmount - orderCurrencyCode - orderMerchantId - orderState - orderSystemId type: object properties: correlationId: type: string description: Serial number assigned to the specific response example: 656454a2-3fff-4663-abdf-b30180136678 orderSystemId: type: integer description: System Order ID format: int64 example: 12121212 orderMerchantId: type: string description: Merchant Order ID example: 02618145-2e65-46ac-a08f-00bda7acad27 orderState: type: string description: "Order status\n* `APPROVED` – Transaction is approved, final\ \ status\n* `DECLINED` – Transaction is declined, final status* \n* `ERROR`\ \ – Transaction is declined but something went wrong, please inform your\ \ account manager, final status\n* `FILTERED` – Transaction is declined\ \ by fraud internal or external control systems, final status\n* `PROCESSING`\ \ – Transaction is being processed, you should continue polling, non final\ \ status\n* `UNKNOWN` – The status of transaction is unknown, please inform\ \ your account manager, non final status\n* `CHAIN_STEP` – Transaction\ \ is declined in a cascading chain, non final status" example: APPROVED enum: - APPROVED - DECLINED - ERROR - FILTERED - PROCESSING - UNKNOWN - CHAIN_STEP transactionType: type: string description: "Transaction type (sale, preauthorize, capture, reversal)" example: sale enum: - SALE - PREAUTHORIZE - CANCEL - CAPTURE - REVERSAL - TRANSFER - ACCOUNT_VERIFICATION - CHARGEBACK - FRAUD - RETRIEVAL - PAYOUT - SCORING - VOID - CHARGEBACK_REVERSAL - PREARBITRATION - ARBITRATION - PAYOUT_CANCEL orderAmount: maxLength: 10 type: string description: "Amount.The amount has to be specified in the highest units\ \ with . delimiter. For instance, 10.5 for USD means 10 US Dollars and\ \ 50 Cents" example: "10.5" orderCurrencyCode: maxLength: 3 minLength: 3 type: string description: "Currency the transaction is charged in (three-letter currency\ \ code). Sample values are: USD for US Dollar, EUR for European Euro" example: USD cardFirstDigits: type: string description: First six digits of customer credit card number example: "654321" cardLastDigits: type: string description: Last four digits of customer credit card number example: "1234" cardType: type: string description: "Type of customer credit card (VISA, MASTERCARD, etc)" example: VISA cardHolderName: type: string description: Cardholder name example: MR JOHN cardExpiryMonth: type: integer description: Card expiration month format: int32 example: 12 cardExpiryYear: type: integer description: Card expiration year format: int32 example: 2025 cardHashId: type: integer description: Unique card identifier to use for loyalty programs or fraud checks format: int64 example: 2025 cardIssuerName: type: string description: Bank name by customer card BIN example: Gringotts Wizarding Bank cardIssuerCountryCode: type: string description: Indicates the country of the issuer according to ISO 3166 example: US orderUpstreamRrn: type: string description: The Authorization Retrieval Reference Number (RRN) is a unique identifier assigned by an acquirer to an authorization example: R12345678910 orderUpstreamId: type: string description: Acquirer transaction identifier example: "123456789" orderUpstreamAuthorizationCode: type: string description: A five or six number generated by the issuing bank to validate a credit card whenever it is approved for the sale of a good or service example: "012345" orderUpstreamDescriptor: type: string description: Bank identifier of the payment recipient example: BL TS errorCode: type: integer description: "The error code is case status in declined, error, filtered" format: int32 example: 1234 errorMessage: type: string description: "If status in declined, error, filtered this parameter contains\ \ the reason for decline" example: Do not honor outputRedirectToUrl: type: string description: |- For 3DS authorization the merchant can redirect the customer to URL provided in this parameter instead of rendering the page provided in html parameter. This parameter is returned only if the html parameter is returned. Merchant should use GET HTTP method to redirect. example: https://somebank.com/redirect/1234 outputHtml: type: string description: HTML code of 3DS authorization form. The system returns the following response parameters when it gets 3DS authorization form from the Issuer Bank. It contains auth form HTML code which must be passed through without any changes to the client’s browser. This parameter exists and has value only when the redirection HTML is already available. For 3DS HTML has value after some short time after the processing has been started threeDSAuth: $ref: '#/components/schemas/ThreeDSAuth' balancingStep: type: integer description: Balancing step format: int32 receiverCardFirstDigits: type: string description: "Receiver: First six digits of customer credit card number" example: "654321" receiverCardLastDigits: type: string description: "Receiver: Last four digits of customer credit card number" example: "1234" receiverCardType: type: string description: "Receiver: Type of customer credit card (VISA, MASTERCARD,\ \ etc)" example: VISA receiverCardHashId: type: integer description: "Receiver: Unique card identifier to use for loyalty programs\ \ or fraud checks" format: int64 example: 2025 receiverCardIssuerName: type: string description: "Receiver: Bank name by customer card BIN" example: Gringotts Wizarding Bank receiverCardIssuerCountryCode: type: string description: "Receiver: Indicates the country of the issuer according to\ \ ISO 3166" example: US statusCreatedTimestamp: type: integer description: "When this status message created. Time in milliseconds since\ \ the UNIX epoch (January 1, 1970 00:00:00 UTC)." format: int64 example: 1685486257959 transactions: type: array description: Transaction list items: $ref: '#/components/schemas/TransactionInfo' cardPaymentNetworkProductCode: type: string description: Card payment network product code example: TPL cardPaymentNetworkProductName: type: string description: Card payment network product name example: TCC—Mastercard Consumer—Immediate Debit cardPaymentNetworkTypeCode: type: string description: Card payment network type code example: Debit cardPaymentNetworkTypeName: type: string description: Card payment network type name example: MASTERCARD Debit receiverCardPaymentNetworkProductCode: type: string description: Receiver card payment network product code example: F receiverCardPaymentNetworkProductName: type: string description: Receiver card payment network product name example: Visa Classic receiverCardPaymentNetworkTypeCode: type: string description: Receiver card payment network type code example: Debit receiverCardPaymentNetworkTypeName: type: string description: Receiver card payment network type name example: VISA Debit qrCodeType: type: string description: QR-code type enum: - QR_CODE_1 - QR_CODE_2 qrCodePayload: type: string description: QR-code payload. Generally this is an url qrCodeDataImageUrl: type: string description: QR-code data image url if enabled on your requestor threeDSOutput: $ref: '#/components/schemas/ThreeDSOutputInfo' orderOutputAttributes: type: array description: "Order attribute name. Possible names:\n* `avsCheckCode` –\ \ Address Verification Service (AVS) check result. Verifies the billing\ \ address of the credit card provided by the customer against the address\ \ on file at the credit card company.\n * `X` / `Y` / `D` / `M` / `F`\ \ – **Match**. Street address and ZIP code both match.\n * `A` / `B`\ \ – **Partial Match**. Street address matches, but ZIP code does not match.\n\ \ * `W` / `Z` / `P` – **Partial Match**. Street address does not match,\ \ but ZIP code matches.\n * `N` / `I` / `C` – **No Match**. Street\ \ address and ZIP code do not match.\n * `G` / `S` – **Not Supported**.\ \ Issuing bank does not support AVS.\n * `U` – **System Unavailable**.\ \ Address information unavailable. Returned if non-US. AVS is not available\ \ or the AVS in a U.S. bank is not functioning properly.\n * `R` –\ \ **System Unavailable**. Retry - Issuer's System Unavailable or Timed\ \ Out.\n* `cvv2CheckCode` – CVV2 (Card Verification Value) check result.\ \ Verifies that the card verification number that appears on the back\ \ of a credit card matches the credit card number provided by the customer.\n\ \ * `M` – CVV2 Match\n * `N` – CVV2 No Match\n * `P` – Not Processed\n\ \ * `U` – Issuer is not certified and/or has not provided Visa the\ \ encryption keys\n * `S` – CVV2 processor is unavailable\n* `featureConvertToAft`.\ \ Result of convert to AFT in request. Possible values:\n * `CONVERT_TO_AFT`\ \ – sale/auth was converted to AFT\n * `NONE` – option was requested\ \ but cannot be converted to AFT\n * absent – no any option sent in\ \ sale/auth request\n* `sepaTransferType` - SEPA transfer type. Possible\ \ values:\n * `SEPA_CREDIT_TRANSFER` – SEPA Credit Transfer (SCT) –\ \ A one-time transfer of euros between bank accounts within the SEPA zone.\ \ It uses IBAN (and sometimes BIC) to transfer funds securely and is typically\ \ processed within one business day.\n\n * `SEPA_INSTANT_CREDIT_TRANSFER`\ \ – SEPA Instant Credit Transfer (SCT Inst) – Enables real-time euro transfers\ \ within seconds, 24/7, including holidays, with a standard limit of around\ \ €100,000. It is designed for urgent payments requiring immediate settlement.\n\ \ * `SEPA_DIRECT_DEBIT_CORE` – SEPA Core Direct Debit (consumer use)\ \ \n * `SEPA_DIRECT_DEBIT_B2B` – SEPA B2B Direct Debit (business use)" items: $ref: '#/components/schemas/OrderOutputAttribute' merchantId: type: integer description: Merchant identifier format: int64 merchantName: type: string description: Merchant name orderUpstreamDebitArn: type: string description: A Debit Acquirer Reference Numbers (ARNs) are unique 23-digit numbers linked to online Visa and Mastercard debit card transactions between a merchant's bank (the acquiring bank) and a cardholder's bank (the issuing bank) example: "123456789012345678901234" orderUpstreamCreditArn: type: string description: A Credit Acquirer Reference Number (ARN) is a unique identifier assigned to each credit card transaction example: "98765432109876543210987" ibanAccountNumber: maxLength: 34 minLength: 10 type: string description: Beneficiary's account number example: GB22MIDL12345612345678 ThreeDSAuth: required: - threeDSAuthStep type: object properties: threeDSAuthStep: type: string description: 3DS flow step example: CREQ enum: - PAREQ - PARES_PROCESSING - CREQ - CRES_PROCESSING - THREEDS_METHOD - AREQ_PROCESSING paReq: maxLength: 10240 type: string description: |- The PaReq message initiates Cardholder interaction and can be used to carry authentication data from the Cardholder. * Appears on the `PAREQ` step creq: maxLength: 4096 type: string description: |- The CReq message initiates Cardholder interaction in a Challenge Flow and can be used to carry authentication data from the Cardholder. * Base64url encoded. * Appears on the `CREQ` step example: eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6ImNlNmM2MzE5LTdkNmEtNDZiZS1iMmFlLTU2ZDU0YzZiMmNjMiIsImFjc1RyYW5zSUQiOiIxYzY2OGYwZi0xZTNjLTQzM2EtOWQ1ZS1lMGRhZDZjM2Y4MjUiLCJjaGFsbGVuZ2VXaW5kb3dTaXplIjoiMDIiLCJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMy4wIn0 acsUrl: maxLength: 2048 type: string description: |- Fully qualified URL of the ACS to be used for the challenge. * Fully qualified URL. * Appears on the ThreeDSAuthStep.CREQ or ThreeDSAuthStep.PAREQ example: https://server.acsdomainname.com threeDSMethodTransactionId: maxLength: 36 type: string description: |- Contains the 3DS Server Transaction ID used during the previous execution of the 3DS method. * Appears on the `THREEDS_METHOD` step threeDSMethodUrl: maxLength: 4096 type: string description: |- Transaction ID. * Appears on the `THREEDS_METHOD` step description: Please see **3DS Overview** for more info ThreeDSOutputInfo: type: object properties: protocolVersion: maxLength: 5 minLength: 5 type: string description: |- Protocol version identifier. This is the Protocol Version Number of the specification utilised by the system creating this message. The Protocol Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Protocol Version Number does not change during a 3DS transaction. Possible values are: * 1.0.2 * 2.1.0 * 2.2.0 * 2.3.0 transactionXId: maxLength: 36 minLength: 19 type: string description: |- Transaction Identifier. xid for 1.0.2 or dsTransID for 2.1.0/2.2.0 acsTransId: maxLength: 36 minLength: 19 type: string description: ACS Transaction Identifier dsTransId: maxLength: 36 minLength: 19 type: string description: DS Transaction Identifier threeDSServerTransId: maxLength: 36 minLength: 19 type: string description: 3DS Server Transaction Identifier eci: maxLength: 2 minLength: 2 type: string description: |- ECI. Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. authenticationValue: maxLength: 28 minLength: 19 type: string description: |- Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result flowType: maxLength: 2 minLength: 2 type: string description: |- Flow type: Frictionless, Challenge or Exemption for EMV 3DS 2.x if available * Frictionless Flow does not require further Cardholder interaction to achieve a successful authentication and complete the 3-D Secure authentication process * Challenge Flow – The process where the ACS is in communication with the 3DS Client to obtain additional information through Cardholder interaction * Exemption applied by the ACS to authenticate the transaction without requesting a challenge enum: - FRICTIONLESS - CHALLENGE - EXEMPTION transactionStatus: maxLength: 1 minLength: 1 type: string description: |- Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification enum: - "Y" - "N" - U - A - C - D - R transactionStatusReason: type: string description: |- Provides information on why the Transaction Status field has the specified value. Length: 2 characters Possible values with description: * 01 = Card authentication failed * 02 = Unknown device * 03 = Unsupported device * 04 = Exceeds authentication frequency limit * 05 = Expired card * 06 = Invalid card number * 07 = Invalid transaction * 08 = No card record * 09 = Security failure * 10 = Stolen card * 11 = Suspected fraud * 12 = Transaction not permitted to Cardholder * 13 = Cardholder not enrolled in service * 14 = Transaction timed out at the ACS * 15 = Low confidence * 16 = Medium confidence * 17 = High confidence * 18 = Very high confidence * 19 = Exceeds ACS maximum challenges * 20 = Non-Payment transaction not supported * 21 = 3RI transaction not supported * 22 = ACS technical issue * 23 = Decoupled Authentication required by ACS but not requested by 3DS Requestor * 24 = 3DS Requestor Decoupled Max Expiry Time exceeded * 25 = Decoupled Authentication was provided insufficient time to authenticate Cardholder. ACS will not make attempt * 26 = Authentication attempted but not performed by the Cardholder * 27 = Preferred Authentication Method not supported * 28 = Validation of content security policy failed * 29 = Authentication attempted but not completed by the Cardholder. Fall back to Decoupled Authentication * 30 = Authentication completed successfully but additional authentication of the Cardholder required. Reinitiate as Decoupled Authentication * 31–79 = Reserved for EMVCo future use (values invalid until defined by EMVCo) * 80–99 = Reserved for DS use TransactionInfo: type: object properties: type: type: string description: "Transaction type (SALE, PREAUTHORIZE, CAPTURE, REVERSAL)" example: SALE enum: - SALE - PREAUTHORIZE - CANCEL - CAPTURE - REVERSAL - TRANSFER - ACCOUNT_VERIFICATION - CHARGEBACK - FRAUD - RETRIEVAL - PAYOUT - SCORING - VOID - CHARGEBACK_REVERSAL - PREARBITRATION - ARBITRATION - PAYOUT_CANCEL status: type: string description: "Transaction status (APPROVED, DECLINED, FILTERED)" example: APPROVED enum: - APPROVED - DECLINED - FILTERED amount: maxLength: 10 type: string description: "Amount.The amount has to be specified in the highest units\ \ with . delimiter. For instance, 10.5 for USD means 10 US Dollars and\ \ 50 Cents" example: "10.5" createdSystemTimestamp: type: string description: Transaction created date and time in the system. Format is `YYYY-MM-dd HH:mm:ss Z` example: 2023-12-21 12:55:54 +0000 createdBankTimestamp: type: string description: Acquirer reconciliation date and time in the system. Format is `YYYY-MM-dd HH:mm:ss Z` example: 2023-12-21 12:55:54 +0000 AccountVerificationRequest: required: - browser - order type: object properties: order: $ref: '#/components/schemas/OrderInfo' browser: $ref: '#/components/schemas/BrowserInfo' customer: $ref: '#/components/schemas/CustomerInfo' card: $ref: '#/components/schemas/CardInfo' cardId: type: integer description: Card identifier for subsequent recurrent format: int64 example: 12345 cardIdCvv2: maxLength: 4 minLength: 3 type: string description: CVV/CVC for subsequent recurrent example: "012" threeDSResultInfo: $ref: '#/components/schemas/ThreeDSResultInfo' urls: $ref: '#/components/schemas/UrlsInfo' messageExtensions: type: array description: Data necessary to support requirements not otherwise defined in the message are carried in a Message Extension items: $ref: '#/components/schemas/MessageExtension' paymentMethod: type: string description: Payment method enum: - CARD - CARD_ID - QR_CODE_1 - QR_CODE_2 - CARD_PROVIDER_FORM - GOOGLE_PAY_TOKEN - APPLE_PAY_TOKEN - OPEN_BANKING - BLIK_CODE feature: $ref: '#/components/schemas/AuthFeatureSupplier' googlePayToken: type: string description: GooglePay Token. JSON.stringify(paymentResponse) example: "{\\\\\"signature\\\\\":\\\\\"MEYCIQD0/CAHzJHhcH+3g8iQWfsiPN16Q3LQEAmZydY64wSBhQIhANlAwic6fWnZ2WOSmqpR7FU5o3jfOyqDLK6h65465666543ys\\\ \\\",\\\\\"intermediateSigningKey\\\\\":{\\\\\"signedKey\\\\\":\\\\\"\ {\\\\\\\\\\\\\"keyVa..." applePayToken: type: string description: ApplePay Token. JSON.stringify(event.payment.token) example: "{\\\"paymentData\\\":{\\\"data\\\":\\\"dvKmMHpogc/dmVtTyqNN ...\ \ b5vlerWL8=\\\",\\\"signature\\\":\\\"MIAGCSq ... o7MALywDDAAAAAAAAA==\\\ \",\\\"header\\\":{\\\"publicKeyHash\\\":\\\"vPhCD8VZijln1 ... XTlLS2kbwvtF44Qc=\\\ \",\\\"ephemeralPublicKey\\\":\\\"MFkwEwYHKoZIzj0CAQYI ... 34QClQdmA5fxV8VkQ==\\\ \",\\\"transactionId\\\":\\\"697620c044f97cadfdd ... a07f5a5823c8146265177c0\\\ \"},\\\"version\\\":\\\"EC_v1\\\"},\\\"paymentMethod\\\":{\\\"displayName\\\ \":\\\"MasterCard 8836\\\",\\\"network\\\":\\\"MasterCard\\\",\\\"type\\\ \":\\\"debit\\\"},\\\"transactionIdentifier\\\":\\\"697620c044f97cadfdd38d\ \ ... 5a5823c8146265177c0\\\"}" AddressInfo: required: - city - countryCode - line1 - zipCode type: object properties: countryCode: maxLength: 2 minLength: 2 type: string description: Customer's country(two-letter country code). example: US stateCode: maxLength: 3 minLength: 2 type: string description: "Customer's country(two-letter country code). Customer's state.\ \ Mandatory for USA, Canada and Australia" example: CA zipCode: maxLength: 10 minLength: 3 type: string description: Customer's ZIP code example: "12345" city: maxLength: 50 minLength: 3 type: string description: Customer's city example: Boston line1: maxLength: 50 minLength: 3 type: string description: Customer's address line 1 example: "Street Name, 1" line2: maxLength: 50 minLength: 3 type: string description: Customer's address line 2 description: Address AuthFeatureSupplier: type: object properties: testSleepBeforeCallSeconds: maximum: 35 minimum: 1 type: integer description: Seconds before call format: int32 testSleepAfterCallSeconds: maximum: 35 minimum: 1 type: integer description: Seconds before call format: int32 redirectUrlCreation: type: string description: |- When redirect url should be created * `CREATE_IN_RESPONSE` – The redirect url is always created even if an acquirer does not provide it yet * `DO_NOT_CREATE_IN_RESPONSE` – default. We generate the redirect url in the /status response when we got it from an acquirer enum: - CREATE_IN_RESPONSE - DO_NOT_CREATE_IN_RESPONSE cardOnFileStore: type: string description: |- Card-on-file transaction feature. * `STORE_FOR_FUTURE_USE` – You intend to reuse the payment credentials in subsequent payments * `ALREADY_STORED` – For payment that use stored card details enum: - STORE_FOR_FUTURE_USE - ALREADY_STORED convertToAft: type: string description: |- Convert to AFT. * `CONVERT_TO_AFT` – Convert sale or auth operation to AFT on acquirer side * `NONE` – (default) Do not convert enum: - CONVERT_TO_AFT - NONE description: Sale Features BrowserInfo: required: - acceptLanguage - ipAddress - javascriptEnabled - screenHeight - screenWidth - timeZone - userAgent type: object properties: ipAddress: maxLength: 45 minLength: 7 type: string description: "Customer's IP address, included for fraud screening purposes" example: 1.2.3.4 acceptHeader: maxLength: 2048 minLength: 10 type: string description: "Exact content of the HTTP accept headers as sent to the 3DS\ \ Requestor from the Cardholder’s browser. \nYou get get this value from\ \ http request Header 'Accept'" example: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.9" colorDepth: maximum: 48 minimum: 2 type: integer description: |- Value representing the bit depth of the colour palette for displaying images, in bits per pixel. You get get this value from javascript: `screen.colorDepth` format: int32 example: 24 javaEnabled: type: boolean description: |- Boolean that represents the ability of the cardholder browser to execute Java. You get get this value from javascript: `navigator.javaEnabled()` example: false javascriptEnabled: type: boolean description: Boolean that represents the ability of the cardholder browser to execute JavaScript example: true acceptLanguage: maxLength: 8 minLength: 1 type: string description: |- Value representing the browser language as defined in IETF BCP47 You get get this value from javascript: `navigator.language` example: en-GB screenWidth: maximum: 999999 minimum: 1 type: integer description: |- Total width of the cardholder’s screen in pixels You get get this value from javascript: `screen.width` format: int32 example: 412 screenHeight: maximum: 999999 minimum: 1 type: integer description: |- Total height of the Cardholder’s screen in pixels You get get this value from javascript: `screen.height` format: int32 example: 846 timeZone: maximum: 99999 minimum: -99999 type: integer description: |- Time-zone offset in minutes between UTC and the Cardholder browser local time. Note that the offset is positive if the local time zone is behind UTC and negative if it is ahead You get get this value from javascript: `new Date().getTimezoneOffset()` format: int32 example: 0 userAgent: maxLength: 2048 minLength: 10 type: string description: Exact content of the HTTP user-agent header example: "Mozilla/5.0 (Linux; Android 10; SM-G965F Build/QP1A.190711.020;\ \ wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/106.0.5249.126\ \ Mobile Safari/537.36 [FB_IAB/FB4A;FBAV/391.1.0.37.104;]" CardInfo: type: object properties: cardNumber: maxLength: 19 minLength: 13 type: string description: | | Test card | 3DS Version | Emv Flow | Description | |--------------------|-------------|--------------|-----------------------------------| | `5555444433331111` | Non-3DS | | Use cvv 123 for approved and cvv 555 for declined | | `4444444411111111` | 1.0.2 | | PaReq | | `4444444444444422` | 2.x (EMV) | Frictionless | Approved | | `4444444444444455` | 2.x (EMV) | Frictionless | Declined | | `4444444444443333` | 2.x (EMV) | Challenge | Card has 3DS Method | | `4444444444446666` | 2.x (EMV) | Challenge | 3DS Method has 15 seconds timeout | | `4444444499999999` | 2.x (EMV) | Challenge | No 3DS Method | cvv2: maxLength: 4 minLength: 3 type: string description: CVV/CVC expireMonth: maxLength: 2 minLength: 2 type: string description: Card expiration month expireYear: maxLength: 4 minLength: 2 type: string description: Card expiration year cardPrintedName: maxLength: 25 minLength: 2 type: string description: Name on card CustomerInfo: type: object properties: firstname: maxLength: 50 minLength: 1 type: string description: Customer's firstname example: Firstname lastname: maxLength: 50 minLength: 1 type: string description: Customer's lastname example: Lastname address: $ref: '#/components/schemas/AddressInfo' identityDocument: $ref: '#/components/schemas/IdentityDocumentInfo' resident: type: boolean citizenship: type: string middleName: type: string ssn: type: string birthPlace: type: string birthBirthday: maxLength: 10 minLength: 10 type: string description: Customer's birthday. Format is yyyy.MM.dd example: 2025.01.31 customerPhone: maxLength: 15 minLength: 3 type: string description: "Customer's full international phone number, including country\ \ code" example: +11234323232323 customerEmail: maxLength: 50 minLength: 3 type: string description: Customer's email address example: email@noanymail.com taxId: maxLength: 30 minLength: 5 type: string description: Customer's Tax ID example: ATU12345678 customerIdentifier: maxLength: 64 minLength: 1 type: string description: Customer's ID example: "1234567" IdentityDocumentInfo: type: object properties: documentId: type: string type: type: string series: type: string number: type: string issuerName: type: string issuerDate: type: string departmentCode: type: string documentNumber: type: string documentSeries: type: string MessageExtension: type: object properties: name: type: string description: The name of the extension data set as defined by the extension owner keyValues: type: object additionalProperties: type: string description: The data carried in the extension. It represents map with key and value description: The data carried in the extension. It represents map with key and value description: Data necessary to support requirements not otherwise defined in the message are carried in a Message Extension OrderInfo: required: - orderAmount - orderCurrencyCode - orderDescription - orderMerchantId type: object properties: orderMerchantId: maxLength: 128 type: string description: Merchant order id example: "1234556789123422" orderDescription: maxLength: 65536 type: string description: Order description example: Description 1 orderPurpose: maxLength: 128 type: string description: "Destination to where the payment goes. It is useful for the\ \ merchants who let their clients to transfer money from a credit card\ \ to some type of client’s account, e.g. game or mobile phone account.\ \ Sample values are: +123456789; hello@mail.com etc. This value will be\ \ used by fraud monitoring system" orderAmount: maxLength: 10 type: string description: "Amount to be charged. The amount has to be specified in the\ \ highest units with . delimiter. For instance, 10.5 for USD means 10\ \ US Dollars and 50 Cents" example: "10.5" orderCurrencyCode: maxLength: 3 minLength: 3 type: string description: "Currency the transaction is charged in (three-letter currency\ \ code). Sample values are: USD for US Dollar EUR for European Euro" example: USD description: Order info ThreeDSResultInfo: required: - authenticationValue - eci type: object properties: authenticationType: maxLength: 2 minLength: 2 type: string description: "Authentication Type. \nIndicates the type of authentication\ \ method the Issuer will use to challenge the Cardholder, whether in the\ \ ARes message or what was used by the ACS when in the RReq message. \n\ 01 - Static, 02 – Dynamic, 03 – OOB" authenticationValue: maxLength: 28 minLength: 19 type: string description: |- Authentication Value. Payment System-specific value provided by the ACS or the DS using an algorithm defined by Payment System. Authentication Value may be used to provide proof of authentication. A 20-byte value that has been Base64 encoded, giving a 28-byte result transactionId: maxLength: 36 minLength: 19 type: string description: |- Transaction Identifier. xid for 1.0.2 or dsTransID for 2.1.0/2.2.0 transactionStatus: maxLength: 1 minLength: 1 type: string description: |- Transaction Status. Indicates whether a transaction qualifies as an authenticated transaction or account verification enum: - "Y" - "N" - U - A - C - D - R protocolVersion: maxLength: 5 minLength: 5 type: string description: |- Protocol version identifier. This shall be the Protocol Version Number of the specification utilised by the system creating this message. The Protocol Version Number is set by the 3DS Server which originates the protocol with the AReq message. The Protocol Version Number does not change during a 3DS transaction. Possible values are: * 1.0.2 * 2.1.0 * 2.2.0 eci: maxLength: 2 minLength: 2 type: string description: |- ECI. Payment System-specific value provided by the ACS or DS to indicate the results of the attempt to authenticate the Cardholder. description: 3D Authentication result if you are using own 3DS Server UrlsInfo: type: object properties: resultUrl: maxLength: 1024 minLength: 3 type: string description: "Upon completion of the transaction or if the user remains\ \ on the waiting page for an extended period, the cardholder will be redirected\ \ to this resultUrl URL. It's important to understand that redirection\ \ may occur not only after transaction approval or decline but also in\ \ exceptional cases when the transaction is still processing." example: https://merchant.com/result/1234 cresUrl: maxLength: 256 minLength: 3 type: string description: Fully qualified URL of merchant system that will receive the CRes message or Error Message example: https://merchant.com/cres/1234 webhookUrl: maxLength: 1024 minLength: 3 type: string description: |- The URL to which the transaction result will be sent via a StatusResponse message. Merchants can utilize this URL for custom processing of transaction completion, such as collecting sales data in the merchant's database. Please note that we will only send a webhook to this URL if the transaction is in its final status (approved, declined, etc). example: https://merchant.com/webhook/1234 redirectWebhookUrl: maxLength: 1024 minLength: 3 type: string description: "The URL where the 3DS parameters or redirect URL will be sent\ \ via StatusResponse message. Merchants may utilize this URL to obtain\ \ the redirect URL, thus avoiding the need for continuous polling of the\ \ status. The Time-to-Live (TTL) for this request is set to 60 seconds." example: https://merchant.com/redirect-webhook/1234 description: URLs AuthRequest: required: - browser - order type: object properties: order: $ref: '#/components/schemas/OrderInfo' browser: $ref: '#/components/schemas/BrowserInfo' customer: $ref: '#/components/schemas/CustomerInfo' card: $ref: '#/components/schemas/CardInfo' cardId: type: integer description: Card ID if paymentMethod = CARD_ID format: int64 cardIdCvv2: type: string description: Card ID CVV if paymentMethod = CARD_ID threeDSResultInfo: $ref: '#/components/schemas/ThreeDSResultInfo' urls: $ref: '#/components/schemas/UrlsInfo' messageExtensions: type: array description: Data necessary to support requirements not otherwise defined in the message are carried in a Message Extension items: $ref: '#/components/schemas/MessageExtension' feature: $ref: '#/components/schemas/AuthFeatureSupplier' paymentMethod: type: string description: Payment method enum: - CARD - CARD_ID - QR_CODE_1 - QR_CODE_2 - CARD_PROVIDER_FORM - GOOGLE_PAY_TOKEN - APPLE_PAY_TOKEN - OPEN_BANKING - BLIK_CODE googlePayToken: type: string description: GooglePay Token. JSON.stringify(paymentResponse) example: "{\\\\\"signature\\\\\":\\\\\"MEYCIQD0/CAHzJHhcH+3g8iQWfsiPN16Q3LQEAmZydY64wSBhQIhANlAwic6fWnZ2WOSmqpR7FU5o3jfOyqDLK6h65465666543ys\\\ \\\",\\\\\"intermediateSigningKey\\\\\":{\\\\\"signedKey\\\\\":\\\\\"\ {\\\\\\\\\\\\\"keyVa..." applePayToken: type: string description: ApplePay Token. JSON.stringify(event.payment.token) example: "{\\\"paymentData\\\":{\\\"data\\\":\\\"dvKmMHpogc/dmVtTyqNN ...\ \ b5vlerWL8=\\\",\\\"signature\\\":\\\"MIAGCSq ... o7MALywDDAAAAAAAAA==\\\ \",\\\"header\\\":{\\\"publicKeyHash\\\":\\\"vPhCD8VZijln1 ... XTlLS2kbwvtF44Qc=\\\ \",\\\"ephemeralPublicKey\\\":\\\"MFkwEwYHKoZIzj0CAQYI ... 34QClQdmA5fxV8VkQ==\\\ \",\\\"transactionId\\\":\\\"697620c044f97cadfdd ... a07f5a5823c8146265177c0\\\ \"},\\\"version\\\":\\\"EC_v1\\\"},\\\"paymentMethod\\\":{\\\"displayName\\\ \":\\\"MasterCard 8836\\\",\\\"network\\\":\\\"MasterCard\\\",\\\"type\\\ \":\\\"debit\\\"},\\\"transactionIdentifier\\\":\\\"697620c044f97cadfdd38d\ \ ... 5a5823c8146265177c0\\\"}" SaleFormStartRequest: required: - browser - customer - order type: object properties: order: $ref: '#/components/schemas/OrderInfo' browser: $ref: '#/components/schemas/BrowserInfo' customer: $ref: '#/components/schemas/CustomerInfo' urls: $ref: '#/components/schemas/UrlsInfo' CaptureRequest: type: object properties: orderSystemId: type: integer description: System Order ID format: int64 example: 12121323 orderMerchantId: type: string description: Merchant Order ID example: 02618145-2e65-46ac-a08f-00bda7acad27 captureAmount: maxLength: 10 type: string description: "Amount to be captured. The amount has to be specified in the\ \ highest units with . delimiter. For instance, 10.5 for USD means 10\ \ US Dollars and 50 Cents" example: "10.5" captureCurrencyCode: maxLength: 3 minLength: 3 type: string description: "Currency the transaction is reversed in (three-letter currency\ \ code). Sample values are: USD for US Dollar EUR for European Euro" example: USD StatusRequest: type: object properties: orderSystemId: type: integer description: System Order ID format: int64 example: 12121323 orderMerchantId: type: string description: Merchant Order ID example: 02618145-2e65-46ac-a08f-00bda7acad27 byCorrelationId: type: string description: "Correlation ID assigned to the specific response. \nIf this\ \ field exist in status request, status response return for this specific\ \ request. \nInclude this parameter to get the status request with the\ \ particular transaction stage (can be used in specific cases). \nTo get\ \ the latest transaction status, don’t include this parameter in status\ \ request" example: 656454a2-3fff-4663-abdf-b30180136678 orderCurrencyCode: maxLength: 3 minLength: 3 type: string description: |- Currency the transaction is charged in (three-letter currency code). Sample values are: USD for US Dollar, EUR for European Euro Note: we use currency only for multi currency requestor example: USD ReversalRequest: required: - orderSystemId - reversalReason type: object properties: orderSystemId: type: integer description: System Order ID format: int64 example: 12121323 orderMerchantId: type: string description: Merchant Order ID example: 02618145-2e65-46ac-a08f-00bda7acad27 reversalAmount: maxLength: 10 type: string description: "Amount to be reversed. The amount has to be specified in the\ \ highest units with . delimiter. For instance, 10.5 for USD means 10\ \ US Dollars and 50 Cents" example: "10.5" reversalReason: maxLength: 256 type: string description: Reversal description example: Description 1 reversalCurrencyCode: maxLength: 3 minLength: 3 type: string description: "Currency the transaction is reversed in (three-letter currency\ \ code). Sample values are: USD for US Dollar EUR for European Euro" example: USD IBANInfo: required: - accountNumber type: object properties: country: maxLength: 2 minLength: 2 type: string description: The two-letter ISO country code of the beneficiary's bank example: PL accountNumber: maxLength: 34 minLength: 10 type: string description: Beneficiary's account number example: GB22MIDL12345612345678 bankNumber: maxLength: 11 minLength: 8 type: string description: Beneficiary's bank SWIFT/BIC or routing number example: BUKBGB220KP SaleFeatureSupplier: type: object properties: testSleepBeforeCallSeconds: maximum: 35 minimum: 1 type: integer description: Seconds before call format: int32 testSleepAfterCallSeconds: maximum: 35 minimum: 1 type: integer description: Seconds before call format: int32 redirectUrlCreation: type: string description: |- When redirect url should be created * `CREATE_IN_RESPONSE` – The redirect url is always created even if an acquirer does not provide it yet * `DO_NOT_CREATE_IN_RESPONSE` – default. We generate the redirect url in the /status response when we got it from an acquirer enum: - CREATE_IN_RESPONSE - DO_NOT_CREATE_IN_RESPONSE cardOnFileStore: type: string description: |- Card-on-file transaction feature. * `STORE_FOR_FUTURE_USE` – You intend to reuse the payment credentials in subsequent payments * `ALREADY_STORED` – For payment that use stored card details enum: - STORE_FOR_FUTURE_USE - ALREADY_STORED convertToAft: type: string description: |- Convert to AFT. * `CONVERT_TO_AFT` – Convert sale or auth operation to AFT on acquirer side * `NONE` – (default) Do not convert enum: - CONVERT_TO_AFT - NONE SaleRequest: required: - browser - order type: object properties: order: $ref: '#/components/schemas/OrderInfo' browser: $ref: '#/components/schemas/BrowserInfo' customer: $ref: '#/components/schemas/CustomerInfo' card: $ref: '#/components/schemas/CardInfo' cardId: type: integer description: Card identifier for subsequent recurrent if paymentMethod = CARD_ID format: int64 example: 12345 cardIdCvv2: maxLength: 4 minLength: 3 type: string description: CVV/CVC for subsequent recurrent. If paymentMethod = CARD_ID example: "012" threeDSResultInfo: $ref: '#/components/schemas/ThreeDSResultInfo' urls: $ref: '#/components/schemas/UrlsInfo' messageExtensions: type: array description: Data necessary to support requirements not otherwise defined in the message are carried in a Message Extension items: $ref: '#/components/schemas/MessageExtension' feature: $ref: '#/components/schemas/SaleFeatureSupplier' paymentMethod: type: string description: Payment method enum: - CARD - CARD_ID - QR_CODE_1 - QR_CODE_2 - CARD_PROVIDER_FORM - GOOGLE_PAY_TOKEN - APPLE_PAY_TOKEN - OPEN_BANKING - BLIK_CODE googlePayToken: type: string description: GooglePay Token. JSON.stringify(paymentResponse). If paymentMethod = GOOGLE_PAY_TOKEN. example: "{\\\\\"signature\\\\\":\\\\\"MEYCIQD0/CAHzJHhcH+3g8iQWfsiPN16Q3LQEAmZydY64wSBhQIhANlAwic6fWnZ2WOSmqpR7FU5o3jfOyqDLK6h65465666543ys\\\ \\\",\\\\\"intermediateSigningKey\\\\\":{\\\\\"signedKey\\\\\":\\\\\"\ {\\\\\\\\\\\\\"keyVa..." applePayToken: type: string description: ApplePay Token. JSON.stringify(event.payment.token). If paymentMethod = APPLE_PAY_TOKEN. example: "{\\\"paymentData\\\":{\\\"data\\\":\\\"dvKmMHpogc/dmVtTyqNN ...\ \ b5vlerWL8=\\\",\\\"signature\\\":\\\"MIAGCSq ... o7MALywDDAAAAAAAAA==\\\ \",\\\"header\\\":{\\\"publicKeyHash\\\":\\\"vPhCD8VZijln1 ... XTlLS2kbwvtF44Qc=\\\ \",\\\"ephemeralPublicKey\\\":\\\"MFkwEwYHKoZIzj0CAQYI ... 34QClQdmA5fxV8VkQ==\\\ \",\\\"transactionId\\\":\\\"697620c044f97cadfdd ... a07f5a5823c8146265177c0\\\ \"},\\\"version\\\":\\\"EC_v1\\\"},\\\"paymentMethod\\\":{\\\"displayName\\\ \":\\\"MasterCard 8836\\\",\\\"network\\\":\\\"MasterCard\\\",\\\"type\\\ \":\\\"debit\\\"},\\\"transactionIdentifier\\\":\\\"697620c044f97cadfdd38d\ \ ... 5a5823c8146265177c0\\\"}" blikCode: type: string description: BLIK code if paymentMethod = BLIK_CODE iban: $ref: '#/components/schemas/IBANInfo' ReceiverCardInfo: type: object properties: cardNumber: maxLength: 19 minLength: 13 type: string description: | | Test card | Description | |--------------------|-----------------------------------| | `4444444444444422` | Approved | | `4444444444444455` | Declined | | `4444444444443333` | Always Processing | | `4444444444446666` | Error | | `4444444499999999` | Unknown | expireMonth: maxLength: 2 minLength: 2 type: string description: Card expiration month expireYear: maxLength: 4 minLength: 2 type: string description: Card expiration year cardPrintedName: maxLength: 25 minLength: 2 type: string description: Name on card TransferFeature: type: object properties: redirectUrlCreation: type: string description: |- When redirect url should be created * `CREATE_IN_RESPONSE` – The redirect url is always created even if an acquirer does not provide it yet * `DO_NOT_CREATE_IN_RESPONSE` – default. We generate the redirect url in the /status response when we got it from an acquirer enum: - CREATE_IN_RESPONSE - DO_NOT_CREATE_IN_RESPONSE testSleepBeforeCallSeconds: maximum: 35 minimum: 1 type: integer description: Seconds before call format: int32 testSleepAfterCallSeconds: maximum: 35 minimum: 1 type: integer description: Seconds before call format: int32 TransferRequest: required: - order - transferType type: object properties: order: $ref: '#/components/schemas/OrderInfo' browser: $ref: '#/components/schemas/BrowserInfo' transferType: type: string description: Transfer type enum: - CARD_TO_CARD - CARD_ID_TO_CARD - CARD_ID_TO_CARD_ID - CARD_TO_CARD_ID - CARD_TO_ACCOUNT - CARD_ID_TO_ACCOUNT - ACCOUNT_TO_CARD - ACCOUNT_TO_CARD_ID - ACCOUNT_TO_IBAN sender: $ref: '#/components/schemas/CustomerInfo' senderCard: $ref: '#/components/schemas/CardInfo' senderCardId: type: integer format: int64 senderCardIdCvv2: type: string senderIban: $ref: '#/components/schemas/IBANInfo' receiver: $ref: '#/components/schemas/CustomerInfo' receiverCard: $ref: '#/components/schemas/ReceiverCardInfo' receiverCardId: type: integer format: int64 receiverIban: $ref: '#/components/schemas/IBANInfo' urls: $ref: '#/components/schemas/UrlsInfo' messageExtensions: type: array description: Data necessary to support requirements not otherwise defined in the message are carried in a Message Extension items: $ref: '#/components/schemas/MessageExtension' feature: $ref: '#/components/schemas/TransferFeature' RegisterCardsResponse: type: object properties: orderSystemId: type: integer description: System Order ID format: int64 example: 12121323 cardId: type: integer description: Card Identifier format: int64 example: 12121323 receiverCardId: type: integer description: Receiver's Card Identifier format: int64 example: 12121323 correlationId: type: string description: Serial number assigned to the specific response example: 656454a2-3fff-4663-abdf-b30180136678 RegisterCardsRequest: required: - orderMerchantId - orderSystemId type: object properties: orderSystemId: type: integer description: System Order ID format: int64 example: 12121323 orderMerchantId: maxLength: 128 type: string description: Merchant order id example: "1234556789123422" TransactionReportRow: required: - captureAmount - orderDescription - reversalAmount - transactionAmount - transactionCommission - transactionCurrencyCode type: object properties: bankTerminalBillingDescriptor: type: string description: A billing descriptor refers to how a company's name appears on a credit card statement example: Company name bankTerminalId: type: integer description: Bank Terminal ID in the system format: int64 example: 1234 bankTerminalName: type: string description: Bank Terminal Name example: Company browserIpAddress: type: string captureAmount: maxLength: 10 type: string description: "Capture Amount. The amount has to be specified in the highest\ \ units with . delimiter. For instance, 10.5 for USD means 10 US Dollars\ \ and 50 Cents" example: "10.5" cardBankName: type: string cardCountryCode: type: string description: Card country ISO 3166-1 alpha-2 code. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 example: US cardCountryName: type: string description: Card country name example: United States of America cardExpiry: type: string description: Card expiration date. Format `yyyyMM` example: "202304" cardHolderName: type: string description: Cardholder name example: MR JOHN cardNumber: type: string description: Formatted card number example: 444455**** **** 1111 cardReceiverBankName: type: string cardReceiverCountryCode: type: string description: Receiver's card country ISO 3166-1 alpha-2 code. See https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2 example: US cardReceiverCountryName: type: string description: Receiver's country name example: United States of America cardReceiverExpiry: type: string description: Receiver's card expiration date. Format `yyyyMM` example: "202304" cardReceiverNumber: type: string description: Formatted receiver's card number example: 444455**** **** 1111 cardReceiverType: type: string description: Receiver's Card Type example: VISA cardType: type: string description: Card Type example: VISA createdBankTimestamp: type: string description: Acquirer reconciliation date and time in the system. Format is `YYYY-MM-dd HH:mm:ss` example: 2023-12-21 12:55:54 createdSystemDate: type: string description: Transaction created date in the system. Format is `YYYY-MM-dd` example: 2023-12-21 createdSystemTimestamp: type: string description: Transaction created date and time in the system. Format is `YYYY-MM-dd HH:mm:ss` example: 2023-12-21 12:55:54 customerAddressCity: type: string customerAddressCountryName: type: string customerAddressLine1: type: string customerAddressStateName: type: string customerAddressZipCode: type: string customerEmail: type: string errorCode: type: integer description: "The error code is case status in declined, error, filtered" format: int32 example: 1234 errorMessage: type: string description: "If status in declined, error, filtered this parameter contains\ \ the reason for decline" example: Do not honor firstname: type: string description: First name example: John lastname: type: string description: Last name example: Doe managerId: type: integer description: Manager Identifier format: int64 example: 1234 managerName: type: string description: Manager Name example: manager1 merchantName: type: string description: Merchant name example: Merchant 1 orderDescription: maxLength: 65536 type: string description: Order description example: Description 1 orderMerchantId: type: string description: Merchant Order ID example: 02618145-2e65-46ac-a08f-00bda7acad27 orderProviderId: type: string description: Provider Order ID example: 4150-889f-7df52fdcf441 orderSystemId: type: integer description: System Order ID format: int64 example: 12121212 outcomeCaptureAmount: type: string description: Capture amount in currency for processing example: "10.0" outcomeFee: type: string description: Fee in currency for processing example: "10.0" outcomeRateCurrency: type: string description: Currency rate for processing example: USD outcomeReversalAmount: type: string description: Reversal amount in currency for processing example: "10.0" outcomeTransactionAmount: type: string description: Amount in currency for processing example: "10.0" outcomeTransactionCurrency: type: string description: Currency for processing example: USD providerCommission: type: string description: Provider Commission example: "10.0" providerCurrencyRate: type: string description: Provider currency rate example: "10.0" providerId: type: integer description: Provider ID in the system format: int64 example: 12 providerName: type: string description: Provider Name example: Acquirer 2 requestorId: type: integer description: Requestor ID format: int64 example: 123 reversalAmount: maxLength: 10 type: string description: "Reversal Amount. The amount has to be specified in the highest\ \ units with . delimiter. For instance, 10.5 for USD means 10 US Dollars\ \ and 50 Cents" example: "10.5" transactionAmount: maxLength: 10 type: string description: "Transaction Amount. The amount has to be specified in the\ \ highest units with . delimiter. For instance, 10.5 for USD means 10\ \ US Dollars and 50 Cents" example: "10.5" transactionArn: type: string transactionCommission: maxLength: 10 type: string description: "Transaction CommissionThe amount has to be specified in the\ \ highest units with . delimiter. For instance, 10.5 for USD means 10\ \ US Dollars and 50 Cents" example: "10.5" transactionCurrencyCode: maxLength: 3 minLength: 3 type: string description: "Currency the transaction is charged in (three-letter currency\ \ code). Sample values are: USD for US Dollar, EUR for European Euro" example: USD transactionRrn: type: string transactionStatus: type: string description: | Transaction status * `APPROVED` – Approved * `DECLINED` – Declined * `FILTERED` – Filtered * `ORDER_PROCESSING` – No any transaction yet. Order is in processing state. Only if exported from Order List * `ORDER_UNKNOWN` – No any transaction yet. Order is in unknown state. Only if exported from Order List * `ORDER_ERROR` – No any transaction yet. Order has an error. Only if exported from Order List example: APPROVED enum: - APPROVED - DECLINED - FILTERED - ORDER_PROCESSING - ORDER_ERROR - ORDER_UNKNOWN transactionSystemId: type: integer description: System Transaction ID (not order id) format: int64 example: 12121212 transactionType: type: string description: "Transaction type (sale, capture, reversal, etc)" example: sale enum: - SALE - PREAUTHORIZE - CANCEL - CAPTURE - REVERSAL - TRANSFER - ACCOUNT_VERIFICATION - CHARGEBACK - FRAUD - RETRIEVAL - PAYOUT - SCORING - VOID - CHARGEBACK_REVERSAL - PREARBITRATION - ARBITRATION - PAYOUT_CANCEL merchantId: type: integer description: Unique merchant Identifier in the system format: int64 example: 123 cardPaymentNetworkProductCode: type: string description: Card payment network product code example: TPL cardPaymentNetworkProductName: type: string description: Card payment network product name example: TCC—Mastercard Consumer—Immediate Debit cardPaymentNetworkTypeCode: type: string description: Card payment network type code example: Debit cardPaymentNetworkTypeName: type: string description: Card payment network type name example: MASTERCARD Debit cardReceiverPaymentNetworkProductCode: type: string description: Receiver card payment network product code example: F cardReceiverPaymentNetworkProductName: type: string description: Receiver card payment network product name example: Visa Classic cardReceiverPaymentNetworkTypeCode: type: string description: Receiver card payment network type code example: Debit cardReceiverPaymentNetworkTypeName: type: string description: Receiver card payment network type name example: VISA Debit requestorName: type: string description: Requestor Name example: Requestor 1 providerTerminalIdentifier: type: string description: Provider Terminal Identifier (TID) example: "00012345" createdSystemInitialTimestamp: type: string description: "Initial transaction created date and time in the system. Format\ \ is `YYYY-MM-dd HH:mm:ss`.For example, this field hold auth transaction\ \ created date for capture" example: 2023-12-21 12:55:54 orderCreatedSystemTimestamp: type: string description: Order created date. Format is `YYYY-MM-dd HH:mm:ss`. example: 2023-12-21 12:55:54 orderChangedSystemTimestamp: type: string description: Order status changed date. Format is `YYYY-MM-dd HH:mm:ss`. example: 2023-12-21 12:55:54 channelId: type: integer description: Channel ID in the system. format: int64 example: 1234 channelName: type: string description: Channel Name for provider payments example: East west payments transactionChannelId: type: integer description: Channel ID in the transaction. format: int64 example: 1234 transactionChannelName: type: string description: Channel Name for transaction example: East west payments transactionProviderId: type: integer description: Provider ID in transaction format: int64 example: 12 transactionProviderName: type: string description: Provider Name in transaction example: Acquirer 2 channelLegalEntity: type: string description: Channel is legal entity. example: "Y" payerIban: type: string description: Payer iban number example: CS00TG2233440055066366 fenigeTokenUuid: type: string description: Fenige token uuid fenigeMerchantUuid: type: string description: Fenige merchant token uuid geographicScope: type: string description: Geographic scope sourceUrl: type: string description: Source url example: www.google.com/paymentUrl/0199136382297327 sourceRef: type: string description: Source ref example: www.google.com/reference/0199136382297327 blueprintId: type: integer description: Blueprint ID in transaction format: int64 example: 99 blueprintName: type: string description: Blueprint Name in transaction example: Some blueprint 2 receiverFirstName: type: string description: Receiver first name example: John receiverLastName: type: string description: Receiver last name example: Doe cardGlobalWhitelistStatus: type: string description: | Card global whitelist status * `SOURCE` – Only the source card is whitelisted. * `DESTINATION` – Only the destination card is whitelisted. * `BOTH` – Both cards (source and destination) are whitelisted. * `NONE` – Neither card is in the whitelist. example: SOURCE bankTerminalExternalWhitelistCheckStatus: type: string description: | Bank Terminal external whitelist check status * `SOURCE` – Whitelist validation is enabled only for the source card. * `DESTINATION` – Whitelist validation is enabled only for the destination card. * `BOTH` – Whitelist validation is enabled for both cards (source and destination). * `NONE` – Whitelist validation is disabled for both cards (source and destination). example: SOURCE providerExternalWhitelistCheckStatus: type: string description: | Provider external whitelist check status * `SOURCE` – Whitelist validation is enabled only for the source card. * `DESTINATION` – Whitelist validation is enabled only for the destination card. * `BOTH` – Whitelist validation is enabled for both cards (source and destination). * `NONE` – Whitelist validation is disabled for both cards (source and destination). example: SOURCE TransactionReportRequest: type: object properties: periodFrom: type: string description: From date and time. Format is `YYYY-MM-dd HH:mm:ss` example: 2023-12-21 12:55:54 periodTo: type: string description: To date and time. Format is `YYYY-MM-dd HH:mm:ss` example: 2023-12-21 12:55:54 periodType: type: string description: | Period type: * `SYSTEM_DATE` – Transaction creation date in the system * `ACQUIRER_DATE` – Acquirer reconciliation data example: SYSTEM_DATE enum: - SYSTEM_DATE - ACQUIRER_DATE reportFormat: type: string description: "Format:\n\n* `CSV` – Comma Separated Values format and \ \ `CSV_UNDERSCORE` – Comma Separated Values format with column name with\ \ '_' (underscore symbol)\n * See RFC at https://tools.ietf.org/html/rfc4180\n\ \ * When formatting, rows are enclosed in double quotes. \n * A double\ \ quote inside a string is output as two double quotes in a row. \n *\ \ There are no other rules for escaping characters\n * Numbers are output\ \ without quotes\n * Values are separated by a delimiter character, which\ \ is , by default\n * Rows are separated using the Unix line feed (LF)\n\ * `JSON_EACH_ROW` – Outputs each row as a separated, newline-delimited\ \ JSON Object\n* `PRETTY_JSON_EACH_ROW` – Differs from JSON_EACH_ROW only\ \ in that JSON is pretty formatted with new line delimiters and 2 space\ \ indents\n* `JSON` – Outputs data in JSON format. Note that the output\ \ json could be more than 1GB so your parser can throw an out of memory\ \ exception. Prefer use of `JSON_EACH_ROW`." example: CSV enum: - CSV - CSV_UNDERSCORE - JSON_EACH_ROW - PRETTY_JSON_EACH_ROW - JSON utcOffsetHours: maximum: 12 minimum: -12 type: integer description: UTC offset in hours. Default is 0. format: int32 example: 0 CResRequest: required: - cres - orderSystemId type: object properties: orderSystemId: type: integer description: System Order ID format: int64 example: 12121212 cres: maxLength: 4096 type: string description: The CRes message is the ACS response to the CReq message. It indicates the result of the Cardholder authentication ThreeDSMethodRequest: required: - browser - cresUrl - orderSystemId - threeDSCompInd - threeDSServerTransID type: object properties: orderSystemId: type: integer description: System Order ID format: int64 example: 12121212 browser: $ref: '#/components/schemas/BrowserInfo' threeDSCompInd: maxLength: 1 type: string description: 3DS Method Completion. Indicates whether the 3DS Method was successfully completed example: "Y" enum: - "Y" - "N" - U threeDSServerTransID: maxLength: 36 type: string description: DS Server Transaction ID. Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction example: 1089d1ea-563c-4bc0-8db0-f60d2a925f3a cresUrl: maxLength: 256 minLength: 3 type: string description: Fully qualified URL of merchant system that will receive the CRes message or Error Message example: https://merchant.com/cres/1234 PaResRequest: required: - orderSystemId - pares type: object properties: orderSystemId: type: integer description: System Order ID format: int64 example: 12121212 pares: maxLength: 10240 type: string description: Payer Authentication Response message is returned by the ACS with the result of cardholder payment authentication VoidResponse: type: object BadRequestError: type: object properties: errorCorrelationId: type: string description: Unique number assigned by the system to identify error example: cc54bdd4-a57a-4683-8510-d1250218a813 errorCode: type: integer description: The error code format: int32 example: 1234 errorMessage: type: string description: Description of the error example: No Authorization header invalidParams: type: array description: List of bad input parameters items: $ref: '#/components/schemas/InvalidParam' httpReasonCode: type: integer format: int32 InvalidParam: type: object properties: name: type: string description: Field name reason: type: string description: Reason for error UnauthorizedError: type: object properties: errorCorrelationId: type: string description: Unique number assigned by the system to identify error example: cc54bdd4-a57a-4683-8510-d1250218a813 errorMessage: type: string description: Description of the error example: Internal error errorCode: type: integer description: The error code format: int32 example: 1234 hint: type: string description: Hint for this error example: Please check you bearer token context: type: object additionalProperties: type: string description: Error context description: Error context httpReasonCode: type: integer format: int32 InternalSystemError: type: object properties: errorCorrelationId: type: string description: Unique number assigned by the system to identify error example: cc54bdd4-a57a-4683-8510-d1250218a813 errorCode: type: integer description: The error code format: int32 example: 1234 errorMessage: type: string description: Description of the error example: Internal error httpReasonCode: type: integer format: int32 securitySchemes: bearerAuth: type: http description: "Opaque access token issued with your requestor in the console.\ \ It is valid only for the combination of the requestor id (or merchant login)\ \ in the path, the API host the request arrives at, and the token value itself.\ \ If an IP allowlist is configured for the requestor, the source address must\ \ match it as well. This is a server-side credential: never expose it in client-side\ \ code, a mobile app, or a URL." scheme: bearer oauth_body_hash: type: http description: "OAuth 1.0a with RSA-SHA256 and the oauth_body_hash extension (https://datatracker.ietf.org/doc/id/draft-eaton-oauth-bodyhash-00.html).\ \ The request is signed with the merchant private key; the matching public\ \ key is registered for the requestor together with a consumer key. Required\ \ parameters: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature_method=RSA-SHA256,\ \ oauth_version=1.0, oauth_body_hash, oauth_signature. The full algorithm,\ \ the base URI rules and the error codes are in the Transfer reference: /manual/reference/transfer/" scheme: OAuth