{ "openapi": "3.1.0", "info": { "title": "Payments API v2", "version": "2.0.0-draft.1", "summary": "Payins and payouts. One create endpoint per method, everything else shared.", "description": "Enums grow without a new version: statuses, `status_details.code`, `next_action.type`, event types, `method_type`, error codes. Treat an unknown status as not final, an unknown `status_details.code` as `provider_declined`, an unknown `next_action.type` as a reason to stop and ask, an unknown event type as a reason to re-read the transaction, an unknown error code by its HTTP status.\n", "x-extensible-enums": true }, "servers": [ { "url": "https://payments-api.mrcr.io", "description": "Sandbox (not serving traffic yet)" }, { "url": "https://payments-api.mercuryo.io", "description": "Production (not serving traffic yet)" } ], "security": [ { "bearerAuth": [] } ], "x-test-amounts": { "description": "Sandbox, sandbox keys only. The cents of `amount.value` select the outcome; `applies_to` lists the methods. Any other cents — the success path of the method.", "values": { "51": { "status": "failed", "code": "provider_declined", "applies_to": "all" }, "52": { "status": "failed", "code": "risk_rejected", "applies_to": "all" }, "53": { "status": "failed", "code": "limit_exceeded", "applies_to": "payout_card" }, "54": { "status": "failed", "code": "card_not_supported", "applies_to": "payin_card, payin_apple_pay, payin_google_pay, payout_card" }, "55": { "status": "failed", "code": "method_unavailable", "applies_to": "all" }, "56": { "status": "failed", "code": "internal_error", "applies_to": "all" }, "57": { "status": "requires_action", "then": "completed", "applies_to": "payin_google_pay" }, "58": { "status": "requires_action", "then": "failed", "code": "provider_declined or canceled_by_payer (BLIK)", "applies_to": "payin_google_pay, payin_blik" }, "60": { "status": "failed", "code": "invalid_recipient_details", "applies_to": "payout_card" }, "61": { "status": "processing", "then": "completed", "after_seconds": 60, "applies_to": "payin_card, payin_apple_pay, payin_google_pay, payout_card" } } }, "x-test-fixtures": { "description": "Sandbox, sandbox keys only.", "card_number": "Any Luhn-valid number, any future expiry, any CVC.", "blik_code": "Any six digits.", "apple_pay_payment_token": "test_apple_pay_token_visa — or a real token from Apple Pay in its sandbox environment.", "google_pay_payment_token": "test_google_pay_token_visa — or a real token from Google Pay in its TEST environment.", "apple_pay_session": "`createApplePaySession` returns a stub session for any `validation_url` on `apple-pay-gateway-cert.apple.com`." }, "x-tagGroups": [ { "name": "Payins", "tags": [ "Card", "Apple Pay", "Google Pay", "BLIK", "Hosted payment form" ] }, { "name": "Payouts", "tags": [ "Card payout" ] }, { "name": "Common", "tags": [ "Transactions", "Balances" ] }, { "name": "Testing", "tags": [ "Testing" ] } ], "paths": { "/v2/pay-sessions": { "post": { "operationId": "createPaySession", "summary": "Create a pay session", "description": "Card only. Returns a pay session with the link to the form in `url`. The payer enters the card on the form; a `payin_card` payin with the session's `merchant_reference` is created then and follows the [card payin](/v2/guides/payins/card) statuses and webhooks. One payin per session.\n", "tags": [ "Hosted payment form" ], "x-shop-type": "payin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaySessionRequest" }, "examples": { "card": { "$ref": "#/components/examples/CreatePaySessionRequest" } } } } }, "responses": { "201": { "description": "Recorded. Send the payer to `url`.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaySessionResponse" }, "examples": { "created": { "$ref": "#/components/examples/PaySessionCreated" } } } } }, "400": { "description": "The request is malformed. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/payins/card": { "post": { "operationId": "createCardPayin", "summary": "Create a card payin", "description": "`card` or `card_token`, exactly one.\n\nThe create returns `requires_action` with the payment page in `next_action.redirect.url`; the page runs 3DS when the issuer asks for it. Then `processing` → `completed` or `failed`. If the shop holds card payins: `processing` → `authorized`, then `capture` → `processing` → `completed`, or `void` → `processing` → `failed` with `canceled_by_merchant`.\n", "tags": [ "Card" ], "x-shop-type": "payin", "x-status-transitions": [ [ "created", "requires_action" ], [ "requires_action", "processing" ], [ "processing", "authorized" ], [ "authorized", "processing" ], [ "processing", "completed" ], [ "completed", "refunded" ], [ "created", "failed" ], [ "processing", "failed" ], [ "requires_action", "failed" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardPayinRequest" }, "examples": { "card_number": { "$ref": "#/components/examples/CreateCardPayinRequestNumber" }, "card_token": { "$ref": "#/components/examples/CreateCardPayinRequestToken" } } } } }, "responses": { "201": { "description": "Recorded. Read `status`.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinResponse" }, "examples": { "requires_action": { "$ref": "#/components/examples/CardPayinRequiresAction" } } } } }, "400": { "description": "The request is malformed. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/payins/apple-pay": { "post": { "operationId": "createApplePayPayin", "summary": "Create an Apple Pay payin", "description": "Call `createApplePaySession` first. Refund: full or partial.\n\nStatuses: `created` → `processing` → `completed` or `failed`.\n", "tags": [ "Apple Pay" ], "x-shop-type": "payin", "x-status-transitions": [ [ "created", "processing" ], [ "processing", "completed" ], [ "completed", "refunded" ], [ "created", "failed" ], [ "processing", "failed" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApplePayPayinRequest" }, "examples": { "apple_pay": { "$ref": "#/components/examples/CreateApplePayPayinRequest" } } } } }, "responses": { "201": { "description": "Recorded. Read `status`.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinResponse" }, "examples": { "created": { "$ref": "#/components/examples/ApplePayPayinCreated" } } } } }, "400": { "description": "The request is malformed. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/payins/apple-pay/sessions": { "post": { "operationId": "createApplePaySession", "summary": "Create an Apple Pay session", "description": "Apple Pay merchant validation. Creates no transaction.\n", "tags": [ "Apple Pay" ], "x-shop-type": "payin", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApplePaySessionRequest" }, "examples": { "session": { "value": { "apple_pay": { "validation_url": "https://apple-pay-gateway.apple.com/paymentservices/startSession", "domain": "shop.example.com" } } } } } } }, "responses": { "200": { "description": "Session for Apple Pay.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApplePaySessionResponse" } } } }, "400": { "description": "The request is malformed. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/payins/google-pay": { "post": { "operationId": "createGooglePayPayin", "summary": "Create a Google Pay payin", "description": "Refund: full or partial.\n\nStatuses: `created` → `processing` → `completed`. 3DS adds `requires_action` with `redirect`.\n", "tags": [ "Google Pay" ], "x-shop-type": "payin", "x-status-transitions": [ [ "created", "processing" ], [ "processing", "requires_action" ], [ "requires_action", "processing" ], [ "processing", "completed" ], [ "completed", "refunded" ], [ "created", "failed" ], [ "processing", "failed" ], [ "requires_action", "failed" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGooglePayPayinRequest" }, "examples": { "google_pay": { "$ref": "#/components/examples/CreateGooglePayPayinRequest" } } } } }, "responses": { "201": { "description": "Recorded. Read `status`.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinResponse" }, "examples": { "created": { "$ref": "#/components/examples/GooglePayPayinCreated" } } } } }, "400": { "description": "The request is malformed. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/payins/blik": { "post": { "operationId": "createBlikPayin", "summary": "Create a BLIK payin", "description": "PLN only. Refund: not supported yet.\n\nStatuses: `created` → `processing` → `requires_action` → `completed` or `failed`. `next_action.type` is `await_confirmation` or `redirect`, set for the shop.\n", "tags": [ "BLIK" ], "x-shop-type": "payin", "x-status-transitions": [ [ "created", "processing" ], [ "processing", "requires_action" ], [ "requires_action", "completed" ], [ "created", "failed" ], [ "processing", "failed" ], [ "requires_action", "failed" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateBlikPayinRequest" }, "examples": { "blik": { "$ref": "#/components/examples/CreateBlikPayinRequest" } } } } }, "responses": { "201": { "description": "Recorded. Read `status`.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinResponse" }, "examples": { "requires_action": { "$ref": "#/components/examples/BlikPayinRequiresAction" } } } } }, "400": { "description": "The request is malformed. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/payins/{payin_id}/capture": { "post": { "operationId": "capturePayin", "summary": "Capture a held payin", "description": "Card only, status `authorized`. Without a body — the full amount.\n", "tags": [ "Card" ], "x-shop-type": "payin", "parameters": [ { "$ref": "#/components/parameters/PayinId" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CapturePayinRequest" } } } }, "responses": { "200": { "description": "Capture accepted. Read `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinResponse" }, "examples": { "processing": { "$ref": "#/components/examples/CardPayinCapturing" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`action_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Described in the contract, not working yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payins/{payin_id}/void": { "post": { "operationId": "voidPayin", "summary": "Void a held payin", "description": "Card only, status `authorized`. Result: `failed` with `canceled_by_merchant`.\n", "tags": [ "Card" ], "x-shop-type": "payin", "parameters": [ { "$ref": "#/components/parameters/PayinId" } ], "responses": { "200": { "description": "Void accepted. Read `status`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayinResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`action_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/payins/{payin_id}/refunds": { "post": { "operationId": "createRefund", "summary": "Refund a payin", "description": "Payin must be `completed` or `refunded`. Without `amount` — the whole refundable remainder. A completed refund moves the payin to `refunded` and adds to its `refunded_amount`. BLIK: not supported yet.\n", "tags": [ "Card", "Apple Pay", "Google Pay", "BLIK" ], "x-availability-by-method": { "payin_card": "available", "payin_apple_pay": "available", "payin_google_pay": "available", "payin_blik": "not_supported_yet" }, "x-shop-type": "payin", "x-status-transitions": [ [ "created", "processing" ], [ "processing", "completed" ], [ "created", "failed" ], [ "processing", "failed" ] ], "parameters": [ { "$ref": "#/components/parameters/PayinId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateRefundRequest" }, "examples": { "partial": { "value": { "merchant_reference": "refund-10001", "amount": { "value": "20.00", "currency": "EUR" }, "description": "Order canceled by the payer" } } } } } }, "responses": { "201": { "description": "Recorded. Read `status`.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundResponse" }, "examples": { "created": { "$ref": "#/components/examples/RefundCreated" } } } } }, "400": { "description": "The request is malformed. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`action_not_allowed` or `merchant_reference_conflict`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" }, "501": { "description": "Described in the contract, not working yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/payouts/card": { "post": { "operationId": "createCardPayout", "summary": "Create a card payout", "description": "Statuses: `created` → `processing` → `completed` or `failed`.\n", "tags": [ "Card payout" ], "x-shop-type": "payout", "x-status-transitions": [ [ "created", "processing" ], [ "processing", "completed" ], [ "created", "failed" ], [ "processing", "failed" ] ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCardPayoutRequest" }, "examples": { "payout_card": { "$ref": "#/components/examples/CreateCardPayoutRequest" } } } } }, "responses": { "201": { "description": "Recorded. Read `status`.", "headers": { "Idempotent-Replayed": { "$ref": "#/components/headers/IdempotentReplayed" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PayoutResponse" }, "examples": { "created": { "$ref": "#/components/examples/PayoutCreated" } } } } }, "400": { "description": "The request is malformed. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "403": { "$ref": "#/components/responses/Forbidden" }, "409": { "$ref": "#/components/responses/Conflict" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/transactions": { "get": { "operationId": "listTransactions", "summary": "List transactions", "description": "Transactions of the key's shop: payins and refunds for a payin shop, payouts for a payout shop. Pages are keyset cursors: a transaction is never skipped or repeated within one window; a transaction changed during paging leaves the `updated_from`–`updated_to` window and appears in the next one.\nFor a scheduled sync, and to find a transaction by `merchant_reference` when its id is unknown.\n", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/ObjectQuery" }, { "$ref": "#/components/parameters/MethodTypeQuery" }, { "$ref": "#/components/parameters/StatusQuery" }, { "$ref": "#/components/parameters/MerchantReferenceQuery" }, { "$ref": "#/components/parameters/PayinIdQuery" }, { "$ref": "#/components/parameters/CreatedFromQuery" }, { "$ref": "#/components/parameters/CreatedToQuery" }, { "$ref": "#/components/parameters/UpdatedFromQuery" }, { "$ref": "#/components/parameters/UpdatedToQuery" }, { "$ref": "#/components/parameters/OrderQuery" }, { "$ref": "#/components/parameters/LimitQuery" }, { "$ref": "#/components/parameters/StartingAfterQuery" }, { "$ref": "#/components/parameters/EndingBeforeQuery" } ], "responses": { "200": { "description": "A page of transactions, newest first.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionList" }, "examples": { "page": { "$ref": "#/components/examples/TransactionListPage" } } } } }, "400": { "description": "The request is malformed. Nothing was created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/transactions/{transaction_id}": { "get": { "operationId": "retrieveTransaction", "summary": "Retrieve a transaction", "description": "A payin, refund or payout of the key's shop by id. The type is in `object`.\nStatus changes come by webhook, and a verified webhook carries the full transaction; this is the fallback — if no webhook has come for a minute, you can start polling it until the status is final. Polling instead of webhooks loads the API and gets `429 rate_limited`.\n", "tags": [ "Transactions" ], "parameters": [ { "$ref": "#/components/parameters/TransactionId" } ], "responses": { "200": { "description": "The transaction.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" }, "examples": { "payin_completed": { "$ref": "#/components/examples/CardPayinCompleted" }, "payin_failed": { "$ref": "#/components/examples/CardPayinFailed" }, "refund_processing": { "$ref": "#/components/examples/RefundProcessing" }, "payout_failed": { "$ref": "#/components/examples/PayoutFailed" } } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/balances": { "get": { "operationId": "listBalances", "summary": "List shop balances", "description": "Balance of the payout shop, in the shop currency. Payouts are paid from it.", "tags": [ "Balances" ], "x-shop-type": "payout", "responses": { "200": { "description": "The shop balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BalanceList" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "429": { "$ref": "#/components/responses/RateLimited" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/test/transactions/{transaction_id}/advance": { "post": { "operationId": "advanceTestTransaction", "summary": "Move a test transaction to the next status", "description": "Sandbox, sandbox keys only. Moves a non-final test transaction along its method's `x-status-transitions` and sends the webhooks a real transition sends. Not supported yet.\n", "tags": [ "Testing" ], "x-availability": "not_supported_yet", "parameters": [ { "$ref": "#/components/parameters/TransactionId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvanceTestTransactionRequest" }, "examples": { "decline": { "value": { "status": "failed", "status_details": { "code": "provider_declined" } } } } } } }, "responses": { "200": { "description": "Moved. The transaction in its new status.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionResponse" } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "description": "`action_not_allowed` — the transition is not in `x-status-transitions` of the method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "501": { "description": "Described in the contract, not working yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2/test/webhooks": { "post": { "operationId": "sendTestWebhook", "summary": "Send a test event to the shop webhook URL", "description": "Sandbox, sandbox keys only. Sends an event of `type` with a sample transaction of the key's shop, signed like a real one. Not supported yet.\n", "tags": [ "Testing" ], "x-availability": "not_supported_yet", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "type" ], "properties": { "type": { "$ref": "#/components/schemas/EventType" } } } } } }, "responses": { "202": { "description": "Queued for delivery.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "required": [ "event_id" ], "properties": { "event_id": { "type": "string", "example": "8d4b2a0c-5e9f-4a6d-9c1b-3f0e6a9d2cf8" } } } } } } } }, "401": { "$ref": "#/components/responses/AuthenticationFailed" }, "501": { "description": "Described in the contract, not working yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": { "event": { "post": { "operationId": "receiveEvent", "summary": "Transaction status changed", "description": "One header, `Webhook-Signature: t=,v1=`. `v1` is the hex HMAC-SHA256 of `.` with the shop's signing secret; during a secret rotation the header carries two `v1` values. Reject a `t` more than 5 minutes from your clock. Pick the secret by `shop_id` in the body; trust nothing in the body until the signature matches. Answer `2xx` within 30 s, otherwise up to 15 redeliveries over about 2 days — 16 attempts in total; the pause before redelivery N is N⁴ + 3 s. Deduplicate on `id`.\n", "x-signature-tolerance-seconds": 300, "x-retry-policy": { "timeout_seconds": 30, "max_redeliveries": 15, "total_attempts": 16, "delay_seconds": "n^4 + 3", "window_hours": 50 }, "parameters": [ { "in": "header", "name": "Webhook-Signature", "required": true, "description": "`t` — Unix time of this delivery attempt, in seconds. `v1` — the signature; two `v1` during a secret rotation.", "schema": { "type": "string", "pattern": "^t=[0-9]+,v1=[0-9a-f]{64}(,v1=[0-9a-f]{64})?$", "example": "t=1790672400,v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "payin_completed": { "$ref": "#/components/examples/PayinCompletedEvent" } } } } }, "responses": { "200": { "description": "Acknowledged. Any `2xx` stops redelivery." }, "500": { "description": "Any non-`2xx` or a timeout schedules a redelivery." } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Key of one shop: `__`. Sandbox keys start with `psbox_` and work only on the sandbox host; production keys start with `plive_` and work only on the production host." } }, "headers": { "IdempotentReplayed": { "description": "`true` when the response is an earlier transaction returned for a repeated `merchant_reference` with the same body.", "schema": { "type": "boolean" } } }, "parameters": { "PayinId": { "in": "path", "name": "payin_id", "required": true, "schema": { "type": "string", "format": "uuid", "example": "0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70" } }, "TransactionId": { "in": "path", "name": "transaction_id", "required": true, "description": "Id of a payin, refund or payout.", "schema": { "type": "string", "format": "uuid", "example": "0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70" } }, "MerchantReferenceQuery": { "in": "query", "name": "merchant_reference", "schema": { "type": "string", "maxLength": 100 } }, "ObjectQuery": { "in": "query", "name": "object", "schema": { "type": "string", "enum": [ "payin", "refund", "payout" ] } }, "StatusQuery": { "in": "query", "name": "status", "description": "Any value of `PayinStatus`, `RefundStatus` or `PayoutStatus`.", "schema": { "type": "string" } }, "MethodTypeQuery": { "in": "query", "name": "method_type", "schema": { "$ref": "#/components/schemas/MethodType" } }, "PayinIdQuery": { "in": "query", "name": "payin_id", "description": "Refunds of this payin.", "schema": { "type": "string" } }, "OrderQuery": { "in": "query", "name": "order", "description": "`created_desc` — newest first, for browsing. `updated_asc` — oldest change first, ties broken by `id`; use it with `updated_from` to sync.", "schema": { "type": "string", "enum": [ "created_desc", "updated_asc" ], "default": "created_desc" } }, "CreatedFromQuery": { "in": "query", "name": "created_from", "description": "Inclusive.", "schema": { "type": "string", "format": "date-time" } }, "CreatedToQuery": { "in": "query", "name": "created_to", "description": "Exclusive.", "schema": { "type": "string", "format": "date-time" } }, "UpdatedFromQuery": { "in": "query", "name": "updated_from", "description": "Inclusive. Changed at or after this time. Use it with `order=updated_asc` to sync statuses — `created_from` misses later changes.", "schema": { "type": "string", "format": "date-time" } }, "UpdatedToQuery": { "in": "query", "name": "updated_to", "description": "Exclusive. Set it to the time the sync started so the window does not move while you page.", "schema": { "type": "string", "format": "date-time" } }, "LimitQuery": { "in": "query", "name": "limit", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, "StartingAfterQuery": { "in": "query", "name": "starting_after", "description": "Id of the last item on the previous page.", "schema": { "type": "string" } }, "EndingBeforeQuery": { "in": "query", "name": "ending_before", "description": "Id of the first item on the current page. Returns the page before it.", "schema": { "type": "string" } } }, "responses": { "AuthenticationFailed": { "description": "Missing, malformed or revoked key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Forbidden": { "description": "`method_not_enabled` — the method is not enabled for the shop, or the key is of the other shop type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "NotFound": { "description": "No such transaction in this shop.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Conflict": { "description": "`merchant_reference_conflict` or `action_not_allowed`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "RateLimited": { "description": "Too many requests. Retry after `Retry-After` seconds.", "headers": { "Retry-After": { "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "InternalError": { "description": "Failure on our side. Retryable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "Money": { "type": "object", "required": [ "value", "currency" ], "additionalProperties": false, "properties": { "value": { "type": "string", "pattern": "^[0-9]+(\\.[0-9]{1,2})?$", "description": "Major units, at most two decimals, at least `0.01`. Never a number.", "example": "100.50" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "example": "EUR" } } }, "MerchantReference": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Your id for the transaction, unique per merchant across payins, refunds, payouts and pay sessions. It is also the idempotency key of the create — the same reference with the same body returns the existing transaction, with a different body `409 merchant_reference_conflict`. Never expires.", "example": "order-10001" }, "Address": { "type": "object", "properties": { "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2.", "example": "US" }, "state": { "type": "string", "pattern": "^[A-Z]{2,3}$", "description": "ISO 3166-2 subdivision code without the country prefix, 2–3 letters. Required for payers and recipients in the US, Canada and Australia.", "example": "CA" }, "city": { "type": "string", "pattern": ".*[^0-9].*", "description": "Not digits only.", "example": "San Francisco" }, "postal_code": { "type": "string", "example": "94105" }, "line1": { "type": "string", "description": "Street and house number.", "example": "1 Market Street" }, "line2": { "type": "string", "description": "Apartment, suite, floor.", "example": "Suite 300" } } }, "Payer": { "type": "object", "description": "The person who pays.", "properties": { "first_name": { "type": "string", "example": "Jane" }, "last_name": { "type": "string", "example": "Doe" }, "email": { "type": "string", "format": "email", "example": "jane@example.com" }, "ip_address": { "type": "string", "description": "IPv4 or IPv6.", "example": "203.0.113.10" } } }, "PayerWithAddress": { "allOf": [ { "$ref": "#/components/schemas/Payer" }, { "type": "object", "required": [ "email", "ip_address", "address" ], "properties": { "address": { "description": "Billing address. `country`, `line1`, `city` and `postal_code` are required.", "allOf": [ { "$ref": "#/components/schemas/Address" }, { "required": [ "country", "line1", "city", "postal_code" ] } ] } } } ] }, "PayoutSender": { "type": "object", "properties": { "birth_date": { "type": "string", "format": "date", "example": "1990-01-15" }, "ip_address": { "type": "string", "description": "IPv4 or IPv6.", "example": "203.0.113.10" } } }, "PayoutRecipient": { "type": "object", "properties": { "first_name": { "type": "string", "description": "First and middle names. If `first_name` or `last_name` is omitted, both are taken from `card.cardholder_name`.", "example": "John" }, "last_name": { "type": "string", "example": "Smith" }, "email": { "type": "string", "format": "email", "example": "john@example.com" }, "phone": { "type": "string", "example": "+14155550123" }, "birth_date": { "type": "string", "format": "date", "example": "1985-03-20" }, "nationality": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "ISO 3166-1 alpha-2.", "example": "US" }, "address": { "$ref": "#/components/schemas/Address" } } }, "Purpose": { "type": "object", "description": "What the payout is for.", "properties": { "details_url": { "type": "string", "format": "uri", "pattern": "^https?://", "maxLength": 255, "description": "A page with the payment details on your side, `http://` or `https://`.", "example": "https://shop.example.com/payouts/payout-10001" }, "digital_asset_type": { "type": "string", "enum": [ "cbdc", "stablecoin", "native_token", "nft", "other" ], "x-enumDescriptions": { "cbdc": "Central bank digital currency or a tokenized deposit.", "stablecoin": "A fiat-backed stablecoin.", "native_token": "A blockchain native token or coin.", "nft": "A non-fungible token.", "other": "Unknown or other." }, "description": "The digital asset the payout is for — card networks classify such payouts. Omitted, or not accepted by the provider of the payout — the provider's default for the card brand is used, `other` if there is none.", "example": "stablecoin" } } }, "SubMerchant": { "type": "object", "description": "Your client the payout is made for, when you pay out on behalf of other businesses.", "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9]{1,15}$", "description": "Your id for the client. Omitted — the id of your merchant account is used.", "example": "client42" }, "country": { "type": "string", "pattern": "^[A-Z]{2}$", "description": "Country of the client, ISO 3166-1 alpha-2. Omitted or unknown — the country of your shop is used.", "example": "PT" } } }, "ReturnUrls": { "type": "object", "description": "Where the payment page sends the payer after the final status, `https://` only. Coming back is not a result — wait for the final status.", "properties": { "success": { "type": "string", "format": "uri", "pattern": "^https://" }, "failure": { "type": "string", "format": "uri", "pattern": "^https://" } } }, "ReturnUrlsRequired": { "allOf": [ { "$ref": "#/components/schemas/ReturnUrls" }, { "required": [ "success", "failure" ] } ] }, "PayinStatus": { "type": "string", "enum": [ "created", "processing", "requires_action", "authorized", "completed", "failed", "refunded" ], "x-terminal-values": [ "completed", "failed", "refunded" ], "x-enumDescriptions": { "created": "Recorded, processing not started. Not final.", "processing": "Checks or provider in progress. Not final.", "requires_action": "The payer has a step to take — read `next_action`. Not final.", "authorized": "Amount on hold (card, two-step). Call `capture` or `void`. Not final.", "completed": "Charged. Final; the only change after it is `refunded`.", "failed": "Not charged — read `status_details.code`. Covers declines, a voided hold (`canceled_by_merchant`), a payer who rejected (`canceled_by_payer`). Final.", "refunded": "Charged, then refunded in part or in full — read `refunded_amount`. Set by the first completed refund and kept by later ones. Final." } }, "RefundStatus": { "type": "string", "enum": [ "created", "processing", "completed", "failed" ], "x-terminal-values": [ "completed", "failed" ], "x-enumDescriptions": { "created": "Recorded. Not final.", "processing": "At the provider. Not final.", "completed": "Returned to the payer. Final.", "failed": "Not returned — read `status_details.code`. Final." } }, "PayoutStatus": { "type": "string", "enum": [ "created", "processing", "completed", "failed" ], "x-terminal-values": [ "completed", "failed" ], "x-enumDescriptions": { "created": "Recorded. Not final.", "processing": "Checks or provider in progress. Not final.", "completed": "Credited to the recipient. Final.", "failed": "Not credited — read `status_details.code`. The blocked amount is returned to the balance. Final." } }, "StatusDetails": { "type": "object", "required": [ "code" ], "description": "Why a transaction ended `failed`.", "properties": { "code": { "type": "string", "enum": [ "card_not_supported", "invalid_payment_token", "method_unavailable", "risk_rejected", "limit_exceeded", "provider_declined", "invalid_recipient_details", "insufficient_funds", "canceled_by_payer", "canceled_by_merchant", "internal_error" ], "x-enumDescriptions": { "card_not_supported": "The card is not accepted — type, country or issuer.", "invalid_payment_token": "The Apple Pay or Google Pay token could not be decrypted.", "method_unavailable": "The method is not available for this transaction right now.", "risk_rejected": "Rejected by antifraud.", "limit_exceeded": "A cumulative limit — daily, monthly, or per payer — was exceeded.", "provider_declined": "The provider or the bank declined.", "invalid_recipient_details": "The recipient's bank rejected the payout details.", "insufficient_funds": "The shop balance did not cover the payout.", "canceled_by_payer": "The payer canceled or did not confirm.", "canceled_by_merchant": "The merchant voided the hold.", "internal_error": "Failure on our side; the transaction did not complete." } }, "message": { "type": "string", "description": "Human-readable. Not stable — do not parse." } } }, "NextAction": { "type": "object", "description": "What the payer has to do while the payin is `requires_action`. Guide — /v2/guides/common/payer-actions.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "redirect", "await_confirmation" ], "x-enumDescriptions": { "redirect": "Send the payer to `redirect.url` as a full page or a new window, never in an iframe.", "await_confirmation": "The payer confirms the payment outside your page — in the banking app or another channel of their bank. There is nothing to open; wait for the final status." } }, "redirect": { "type": "object", "description": "Set when `type` is `redirect`. `url` is the Mercuryo payment page of the payin; after the final status it sends the payer to `return_urls`.", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri" } } }, "expires_at": { "type": "string", "format": "date-time", "description": "When the provider stops waiting for the payer; after it the payin ends `failed`. Set when the provider gives a deadline." } } }, "MethodType": { "type": "string", "description": "The flow of the transaction, end to end — the method and the direction.", "enum": [ "payin_card", "payin_apple_pay", "payin_google_pay", "payin_blik", "refund", "payout_card" ] }, "PayinMethodType": { "type": "string", "enum": [ "payin_card", "payin_apple_pay", "payin_google_pay", "payin_blik" ] }, "CreatePaySessionRequest": { "type": "object", "description": "`card_token` pays with a saved card: the form shows its last four digits instead of the card fields.", "required": [ "merchant_reference", "amount", "description", "expires_at", "payer" ], "properties": { "merchant_reference": { "$ref": "#/components/schemas/MerchantReference" }, "amount": { "$ref": "#/components/schemas/Money" }, "description": { "type": "string", "maxLength": 255, "description": "Shown to the payer on the form." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the form stops accepting the payment. In the future, with a time zone offset.", "example": "2026-09-29T10:40:00Z" }, "payer": { "allOf": [ { "$ref": "#/components/schemas/Payer" }, { "type": "object", "required": [ "email", "address" ], "properties": { "first_name": { "description": "If `first_name` or `last_name` is omitted, both are taken from the cardholder name the payer types on the form." }, "ip_address": { "description": "If omitted, the IP the payer submits the form from." }, "address": { "description": "Billing address. `country`, `line1`, `city` and `postal_code` are required.", "allOf": [ { "$ref": "#/components/schemas/Address" }, { "required": [ "country", "line1", "city", "postal_code" ] } ] } } } ] }, "card_token": { "type": "string", "description": "`card.token` of an earlier `completed` payin of this shop." }, "save_card": { "type": "boolean", "default": false, "description": "Return `card.token` for repeat payins when the payin is `completed`. Works if the shop allows saving cards." }, "return_urls": { "$ref": "#/components/schemas/ReturnUrls" } } }, "PaySession": { "type": "object", "required": [ "id", "object", "merchant_reference", "amount", "url", "expires_at", "payin_id", "created_at" ], "properties": { "id": { "type": "string", "description": "Session id. It is also the last part of `url`." }, "object": { "const": "pay_session" }, "merchant_reference": { "$ref": "#/components/schemas/MerchantReference" }, "amount": { "$ref": "#/components/schemas/Money" }, "url": { "type": "string", "format": "uri", "description": "The payment form. Open it for the payer as a full page, or in an iframe on a domain allowed for the shop." }, "expires_at": { "type": "string", "format": "date-time", "description": "UTC. When the form stops accepting the payment." }, "payin_id": { "description": "The payin created when the payer submitted the form. `null` until then; `null` after `expires_at` means the session expired unpaid.", "oneOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "type": "string", "format": "date-time" } } }, "PaySessionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/PaySession" } } }, "CardInput": { "type": "object", "required": [ "number", "exp_month", "exp_year", "cvc", "cardholder_name" ], "additionalProperties": false, "properties": { "number": { "type": "string", "pattern": "^[0-9]{12,19}$", "description": "Passes the Luhn check." }, "exp_month": { "type": "string", "pattern": "^(0?[1-9]|1[0-2])$", "example": "12" }, "exp_year": { "type": "string", "pattern": "^[0-9]{2}$", "description": "Two digits.", "example": "30" }, "cvc": { "type": "string", "pattern": "^[0-9]{3,4}$", "description": "Never stored." }, "cardholder_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z ]*$", "description": "Latin letters and spaces, as printed on the card." } } }, "CreateCardPayinRequest": { "type": "object", "description": "Exactly one of `card` and `card_token`.", "required": [ "merchant_reference", "amount", "payer" ], "oneOf": [ { "title": "Card fields", "required": [ "card" ] }, { "title": "Saved card", "required": [ "card_token" ] } ], "properties": { "merchant_reference": { "$ref": "#/components/schemas/MerchantReference" }, "amount": { "$ref": "#/components/schemas/Money" }, "payer": { "description": "`first_name` and `last_name` are required with `card_token`; with `card` they can be omitted — they are taken from `card.cardholder_name`.", "allOf": [ { "$ref": "#/components/schemas/PayerWithAddress" } ] }, "description": { "type": "string", "maxLength": 255 }, "card": { "$ref": "#/components/schemas/CardInput" }, "card_token": { "type": "string", "description": "`card.token` of an earlier `completed` payin of this shop created with `save_card: true`.", "example": "3f9c2a7e5b1d4c8a9e0f6b2d7c4a1e8f3b5d9c2a6e0f4b8d1c7a3e9f5b2d6c0a" }, "save_card": { "type": "boolean", "default": false, "description": "Return `card.token` for repeat payins when the payin is `completed`. Works if the shop allows saving cards." }, "return_urls": { "$ref": "#/components/schemas/ReturnUrls" } } }, "CreateApplePayPayinRequest": { "type": "object", "required": [ "merchant_reference", "amount", "payer", "apple_pay" ], "properties": { "merchant_reference": { "$ref": "#/components/schemas/MerchantReference", "pattern": "^[A-Za-z0-9_-]{1,100}$" }, "amount": { "$ref": "#/components/schemas/Money" }, "payer": { "allOf": [ { "$ref": "#/components/schemas/PayerWithAddress" }, { "required": [ "first_name", "last_name" ] } ] }, "apple_pay": { "type": "object", "required": [ "payment_token" ], "properties": { "payment_token": { "type": "string", "format": "byte", "description": "Base64 of the `token.paymentData` JSON from Apple Pay JS." } } } } }, "CreateGooglePayPayinRequest": { "type": "object", "required": [ "merchant_reference", "amount", "payer", "google_pay", "return_urls" ], "properties": { "merchant_reference": { "$ref": "#/components/schemas/MerchantReference", "pattern": "^[A-Za-z0-9_-]{1,100}$" }, "amount": { "$ref": "#/components/schemas/Money" }, "payer": { "allOf": [ { "$ref": "#/components/schemas/PayerWithAddress" }, { "required": [ "first_name", "last_name" ] } ] }, "google_pay": { "type": "object", "required": [ "payment_token" ], "properties": { "payment_token": { "type": "string", "format": "byte", "description": "Base64 of `paymentMethodData.tokenizationData.token` from the Google Pay API. Protocol `ECv2`." } } }, "return_urls": { "$ref": "#/components/schemas/ReturnUrlsRequired" } } }, "CreateBlikPayinRequest": { "type": "object", "required": [ "merchant_reference", "amount", "payer", "blik" ], "properties": { "merchant_reference": { "$ref": "#/components/schemas/MerchantReference", "pattern": "^[A-Za-z0-9_-]{1,100}$" }, "amount": { "description": "PLN only.", "allOf": [ { "$ref": "#/components/schemas/Money" }, { "properties": { "currency": { "const": "PLN" } } } ] }, "payer": { "allOf": [ { "$ref": "#/components/schemas/Payer" }, { "type": "object", "required": [ "first_name", "last_name", "email", "ip_address" ], "properties": { "first_name": { "pattern": "^[A-Za-zÀ-ÿ .'-]{2,255}$" }, "last_name": { "pattern": "^[A-Za-zÀ-ÿ .'-]{2,255}$" }, "phone": { "type": "string", "example": "+48500100200" } } } ] }, "blik": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "The BLIK code from the payer's banking app." } } } } }, "CreateApplePaySessionRequest": { "type": "object", "required": [ "apple_pay" ], "properties": { "apple_pay": { "type": "object", "required": [ "validation_url", "domain" ], "properties": { "validation_url": { "type": "string", "format": "uri", "pattern": "^https://(cn-)?apple-pay-gateway[^/]*\\.apple\\.com/", "description": "`validationURL` from the `onvalidatemerchant` event of Apple Pay JS." }, "domain": { "type": "string", "description": "Merchant domain where the Apple Pay payment is initiated. Must be registered for the shop." } } } } }, "ApplePaySession": { "type": "object", "required": [ "apple_pay" ], "properties": { "apple_pay": { "type": "object", "required": [ "session" ], "properties": { "session": { "type": "object", "description": "Apple Pay merchant session. Pass it to Apple Pay unchanged." } } } } }, "TransactionBase": { "type": "object", "description": "Fields every transaction has — payin, refund and payout. `object` and `method_type` tell which fields come on top; the fields of the payment instrument are in an object named after it — `card`, `apple_pay` or `google_pay`.", "required": [ "id", "merchant_reference", "status_details", "amount", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Transaction id. The type of the transaction is in `object`." }, "merchant_reference": { "$ref": "#/components/schemas/MerchantReference" }, "status_details": { "description": "Why the transaction ended `failed`. `null` in every other status.", "oneOf": [ { "$ref": "#/components/schemas/StatusDetails" }, { "type": "null" } ] }, "amount": { "$ref": "#/components/schemas/Money" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "Payin": { "allOf": [ { "$ref": "#/components/schemas/TransactionBase" }, { "type": "object", "required": [ "object", "method_type", "status", "refunded_amount" ], "properties": { "object": { "const": "payin" }, "method_type": { "$ref": "#/components/schemas/PayinMethodType" }, "status": { "$ref": "#/components/schemas/PayinStatus" }, "refunded_amount": { "$ref": "#/components/schemas/Money" }, "next_action": { "oneOf": [ { "$ref": "#/components/schemas/NextAction" }, { "type": "null" } ] }, "capture_method": { "description": "Set only when `method_type` is `payin_card`. `manual` — the shop holds card payins at `authorized` until `capture` or `void`.", "type": "string", "enum": [ "automatic", "manual" ] }, "card": { "description": "Set only when `method_type` is `payin_card`.", "type": "object", "properties": { "brand": { "type": "string", "example": "visa" }, "last4": { "type": "string", "pattern": "^[0-9]{4}$" }, "token": { "type": "string", "description": "Set on a `completed` payin created with `save_card: true`. Pass it as `card_token`." } } }, "apple_pay": { "description": "Set only when `method_type` is `payin_apple_pay`, after the token is decrypted.", "type": "object", "properties": { "brand": { "type": "string", "example": "visa" }, "last4": { "type": "string", "pattern": "^[0-9]{4}$", "description": "Last four digits of the device card number." } } }, "google_pay": { "description": "Set only when `method_type` is `payin_google_pay`, after the token is decrypted.", "type": "object", "properties": { "brand": { "type": "string", "example": "visa" }, "last4": { "type": "string", "pattern": "^[0-9]{4}$" } } } } } ] }, "CapturePayinRequest": { "type": "object", "properties": { "amount": { "description": "Up to the held amount. Omitted — the full amount. Partial capture: not supported yet, returns `501 not_supported_yet`.", "x-availability": "not_supported_yet", "allOf": [ { "$ref": "#/components/schemas/Money" } ] } } }, "CreateRefundRequest": { "type": "object", "required": [ "merchant_reference" ], "properties": { "merchant_reference": { "$ref": "#/components/schemas/MerchantReference", "pattern": "^[A-Za-z0-9_-]{1,100}$" }, "amount": { "description": "Up to the refundable remainder — the payin amount minus refunds that are not `failed`. Omitted — the whole remainder.", "allOf": [ { "$ref": "#/components/schemas/Money" } ] }, "description": { "type": "string", "maxLength": 255, "description": "Why you refund. Free text." } } }, "Refund": { "allOf": [ { "$ref": "#/components/schemas/TransactionBase" }, { "type": "object", "required": [ "object", "method_type", "payin_id", "status" ], "properties": { "object": { "const": "refund" }, "method_type": { "const": "refund" }, "payin_id": { "type": "string", "description": "The payin this refund returns money from." }, "status": { "$ref": "#/components/schemas/RefundStatus" } } } ] }, "CreateCardPayoutRequest": { "type": "object", "required": [ "merchant_reference", "amount", "card" ], "properties": { "merchant_reference": { "$ref": "#/components/schemas/MerchantReference" }, "amount": { "$ref": "#/components/schemas/Money" }, "card": { "type": "object", "required": [ "number", "cardholder_name" ], "additionalProperties": false, "properties": { "number": { "type": "string", "pattern": "^[0-9]{12,19}$", "description": "Passes the Luhn check." }, "cardholder_name": { "type": "string", "pattern": "^[A-Za-z][A-Za-z ]*$", "description": "Latin letters and spaces, as printed on the card." } } }, "recipient": { "description": "The person who receives the payout.", "allOf": [ { "$ref": "#/components/schemas/PayoutRecipient" } ] }, "sender": { "description": "The person on whose behalf you send the payout.", "allOf": [ { "$ref": "#/components/schemas/PayoutSender" } ] }, "purpose": { "$ref": "#/components/schemas/Purpose" }, "sub_merchant": { "$ref": "#/components/schemas/SubMerchant" } } }, "Payout": { "allOf": [ { "$ref": "#/components/schemas/TransactionBase" }, { "type": "object", "required": [ "object", "method_type", "status" ], "properties": { "object": { "const": "payout" }, "method_type": { "type": "string", "enum": [ "payout_card" ] }, "status": { "$ref": "#/components/schemas/PayoutStatus" }, "rrn": { "type": "string", "description": "Retrieval reference number of the payout in the card network, when the provider returns it. Lets the recipient's bank find the payment.", "example": "627314523901" }, "card": { "description": "Set when `method_type` is `payout_card`.", "type": "object", "properties": { "brand": { "type": "string", "example": "visa" }, "last4": { "type": "string", "pattern": "^[0-9]{4}$" } } } } } ] }, "Transaction": { "description": "A payin, refund or payout. The type is in `object`.", "oneOf": [ { "$ref": "#/components/schemas/Payin" }, { "$ref": "#/components/schemas/Refund" }, { "$ref": "#/components/schemas/Payout" } ], "discriminator": { "propertyName": "object", "mapping": { "payin": "#/components/schemas/Payin", "refund": "#/components/schemas/Refund", "payout": "#/components/schemas/Payout" } } }, "TransactionList": { "type": "object", "required": [ "data", "has_more" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "has_more": { "type": "boolean" } } }, "Balance": { "type": "object", "required": [ "currency", "available" ], "properties": { "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "available": { "$ref": "#/components/schemas/Money" } } }, "BalanceList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } } }, "PayinResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payin" } } }, "RefundResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Refund" } } }, "PayoutResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payout" } } }, "TransactionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Transaction" } } }, "ApplePaySessionResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/ApplePaySession" } } }, "AdvanceTestTransactionRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Target status, one transition away in `x-status-transitions`." }, "status_details": { "$ref": "#/components/schemas/StatusDetails" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "$ref": "#/components/schemas/Error" } } }, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "validation_failed", "authentication_failed", "method_not_enabled", "resource_not_found", "merchant_reference_conflict", "action_not_allowed", "rate_limited", "internal_error", "not_supported_yet" ], "description": "Stable machine-readable cause. Branch on this, never on `message`.", "x-enumDescriptions": { "validation_failed": "400. A field is missing or malformed — including an amount with more than two decimals and a currency other than the shop currency; `details[]` names the field. Fix the request.", "authentication_failed": "401. The key is missing, malformed or revoked, or sent to the other environment's host.", "method_not_enabled": "403. The method is not enabled for the shop, or the key is of the other shop type — a payin shop key on a payout endpoint, or the reverse.", "resource_not_found": "404. No such transaction in this shop.", "merchant_reference_conflict": "409. `merchant_reference` is already used with a different body. Resend the original body to get the existing transaction, or use a new reference.", "action_not_allowed": "409. The action is not available for this method or status.", "rate_limited": "429. Too many requests. Retry after `Retry-After` seconds.", "internal_error": "500. Failure on our side. Retry the identical request.", "not_supported_yet": "501. Described in the contract, not working yet." } }, "message": { "type": "string", "description": "Human-readable. Not stable — do not parse." }, "details": { "type": "array", "description": "Set for `validation_failed` — one item per field.", "items": { "type": "object", "required": [ "field", "message" ], "properties": { "field": { "type": "string" }, "message": { "type": "string" } } } } }, "x-retryable-codes": [ "rate_limited", "internal_error" ] }, "EventType": { "type": "string", "enum": [ "payin.requires_action", "payin.authorized", "payin.completed", "payin.failed", "payin.refunded", "payin.capture_failed", "payin.void_failed", "refund.completed", "refund.failed", "payout.completed", "payout.failed" ] }, "Event": { "type": "object", "required": [ "id", "type", "shop_id", "created_at", "data" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Event id. The same on every redelivery — deduplicate on it." }, "shop_id": { "type": "integer", "description": "The id of the shop the event belongs to. Pick the shop's signing secret by it." }, "type": { "$ref": "#/components/schemas/EventType" }, "created_at": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "object" ], "properties": { "object": { "description": "The transaction as returned by `retrieveTransaction`.", "allOf": [ { "$ref": "#/components/schemas/Transaction" } ] } } } } } }, "examples": { "CreateCardPayinRequestNumber": { "summary": "Card fields", "value": { "merchant_reference": "order-10001", "amount": { "value": "100.50", "currency": "EUR" }, "payer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "ip_address": "203.0.113.10", "address": { "country": "US", "state": "CA", "city": "San Francisco", "postal_code": "94105", "line1": "1 Market Street" } }, "card": { "number": "4111111111111111", "exp_month": "12", "exp_year": "30", "cvc": "123", "cardholder_name": "JANE DOE" }, "save_card": true, "return_urls": { "success": "https://shop.example.com/pay/success", "failure": "https://shop.example.com/pay/failure" } } }, "CreateCardPayinRequestToken": { "summary": "Card token", "value": { "merchant_reference": "order-10002", "amount": { "value": "40.00", "currency": "EUR" }, "payer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "ip_address": "203.0.113.10", "address": { "country": "US", "state": "CA", "city": "San Francisco", "postal_code": "94105", "line1": "1 Market Street" } }, "card_token": "3f9c2a7e5b1d4c8a9e0f6b2d7c4a1e8f3b5d9c2a6e0f4b8d1c7a3e9f5b2d6c0a", "return_urls": { "success": "https://shop.example.com/pay/success", "failure": "https://shop.example.com/pay/failure" } } }, "CardPayinRequiresAction": { "summary": "Payment page", "value": { "data": { "id": "0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70", "object": "payin", "merchant_reference": "order-10001", "method_type": "payin_card", "status": "requires_action", "status_details": null, "amount": { "value": "100.50", "currency": "EUR" }, "refunded_amount": { "value": "0.00", "currency": "EUR" }, "next_action": { "type": "redirect", "expires_at": "2026-09-29T09:30:00Z", "redirect": { "url": "https://pay-in.mrcr.io/order/0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70" } }, "capture_method": "automatic", "card": { "brand": "visa", "last4": "1111" }, "created_at": "2026-09-29T09:00:00Z", "updated_at": "2026-09-29T09:00:01Z" } } }, "CardPayinCompleted": { "summary": "Completed", "value": { "data": { "id": "0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70", "object": "payin", "merchant_reference": "order-10001", "method_type": "payin_card", "status": "completed", "status_details": null, "amount": { "value": "100.50", "currency": "EUR" }, "refunded_amount": { "value": "0.00", "currency": "EUR" }, "next_action": null, "capture_method": "automatic", "card": { "brand": "visa", "last4": "1111", "token": "3f9c2a7e5b1d4c8a9e0f6b2d7c4a1e8f3b5d9c2a6e0f4b8d1c7a3e9f5b2d6c0a" }, "created_at": "2026-09-29T09:00:00Z", "updated_at": "2026-09-29T09:00:20Z" } } }, "CardPayinFailed": { "summary": "Failed — declined by the provider", "value": { "data": { "id": "1c7a5f3b-8d2e-4f9c-8b4a-6e3d9f2c5b81", "object": "payin", "merchant_reference": "order-10003", "method_type": "payin_card", "status": "failed", "status_details": { "code": "provider_declined", "message": "Declined by issuer" }, "amount": { "value": "100.50", "currency": "EUR" }, "refunded_amount": { "value": "0.00", "currency": "EUR" }, "next_action": null, "capture_method": "automatic", "card": { "brand": "visa", "last4": "0002" }, "created_at": "2026-09-29T09:05:00Z", "updated_at": "2026-09-29T09:05:04Z" } } }, "CardPayinCapturing": { "summary": "Capture accepted", "value": { "data": { "id": "2d8b6a4c-9e3f-4a0d-9c5b-7f4e0a3d6c92", "object": "payin", "merchant_reference": "order-10004", "method_type": "payin_card", "status": "processing", "status_details": null, "amount": { "value": "250.00", "currency": "EUR" }, "refunded_amount": { "value": "0.00", "currency": "EUR" }, "next_action": null, "capture_method": "manual", "card": { "brand": "visa", "last4": "1111" }, "created_at": "2026-09-29T08:00:00Z", "updated_at": "2026-09-29T10:00:00Z" } } }, "CreateApplePayPayinRequest": { "summary": "Apple Pay", "value": { "merchant_reference": "order-20001", "amount": { "value": "59.90", "currency": "EUR" }, "payer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "ip_address": "203.0.113.10", "address": { "country": "US", "state": "CA", "city": "San Francisco", "postal_code": "94105", "line1": "1 Market Street" } }, "apple_pay": { "payment_token": "eyJ2ZXJzaW9uIjoiRUNfdjEiLCJkYXRhIjoi4oCmIiwic2lnbmF0dXJlIjoi4oCmIiwiaGVhZGVyIjp7ImVwaGVtZXJhbFB1YmxpY0tleSI6IuKApiIsInB1YmxpY0tleUhhc2giOiLigKYiLCJ0cmFuc2FjdGlvbklkIjoi4oCmIn19" } } }, "ApplePayPayinCreated": { "summary": "Created", "value": { "data": { "id": "3e9c7b5d-0f4a-4b1e-8d6c-8a5f1b4e7da3", "object": "payin", "merchant_reference": "order-20001", "method_type": "payin_apple_pay", "status": "created", "status_details": null, "amount": { "value": "59.90", "currency": "EUR" }, "refunded_amount": { "value": "0.00", "currency": "EUR" }, "next_action": null, "apple_pay": { "last4": "1234" }, "created_at": "2026-09-29T09:10:00Z", "updated_at": "2026-09-29T09:10:00Z" } } }, "CreateGooglePayPayinRequest": { "summary": "Google Pay", "value": { "merchant_reference": "order-30001", "amount": { "value": "59.90", "currency": "EUR" }, "payer": { "first_name": "Jane", "last_name": "Doe", "email": "jane@example.com", "ip_address": "203.0.113.10", "address": { "country": "US", "state": "CA", "city": "San Francisco", "postal_code": "94105", "line1": "1 Market Street" } }, "google_pay": { "payment_token": "eyJzaWduYXR1cmUiOiLigKYiLCJpbnRlcm1lZGlhdGVTaWduaW5nS2V5Ijp7InNpZ25lZEtleSI6IuKApiIsInNpZ25hdHVyZXMiOlsi4oCmIl19LCJwcm90b2NvbFZlcnNpb24iOiJFQ3YyIiwic2lnbmVkTWVzc2FnZSI6IuKApiJ9" }, "return_urls": { "success": "https://shop.example.com/pay/success", "failure": "https://shop.example.com/pay/failure" } } }, "GooglePayPayinCreated": { "summary": "Created", "value": { "data": { "id": "4f0d8c6e-1a5b-4c2f-9e7d-9b6a2c5f8eb4", "object": "payin", "merchant_reference": "order-30001", "method_type": "payin_google_pay", "status": "created", "status_details": null, "amount": { "value": "59.90", "currency": "EUR" }, "refunded_amount": { "value": "0.00", "currency": "EUR" }, "next_action": null, "created_at": "2026-09-29T09:20:00Z", "updated_at": "2026-09-29T09:20:00Z" } } }, "GooglePayPayinRequiresAction": { "summary": "Redirect required", "value": { "data": { "id": "4f0d8c6e-1a5b-4c2f-9e7d-9b6a2c5f8eb4", "object": "payin", "merchant_reference": "order-30001", "method_type": "payin_google_pay", "status": "requires_action", "status_details": null, "amount": { "value": "59.90", "currency": "EUR" }, "refunded_amount": { "value": "0.00", "currency": "EUR" }, "next_action": { "type": "redirect", "expires_at": "2026-09-29T09:30:00Z", "redirect": { "url": "https://pay-in.mrcr.io/order/4f0d8c6e-1a5b-4c2f-9e7d-9b6a2c5f8eb4" } }, "google_pay": { "last4": "4321" }, "created_at": "2026-09-29T09:20:00Z", "updated_at": "2026-09-29T09:20:01Z" } } }, "CreateBlikPayinRequest": { "summary": "BLIK", "value": { "merchant_reference": "order-40001", "amount": { "value": "120.00", "currency": "PLN" }, "payer": { "first_name": "Jan", "last_name": "Kowalski", "email": "jan@example.com", "ip_address": "203.0.113.20" }, "blik": { "code": "777123" } } }, "BlikPayinRequiresAction": { "summary": "Waiting for confirmation in the banking app", "value": { "data": { "id": "5a1e9d7f-2b6c-4d3a-8f8e-0c7b3d6a9fc5", "object": "payin", "merchant_reference": "order-40001", "method_type": "payin_blik", "status": "requires_action", "status_details": null, "amount": { "value": "120.00", "currency": "PLN" }, "refunded_amount": { "value": "0.00", "currency": "PLN" }, "next_action": { "type": "await_confirmation" }, "created_at": "2026-09-29T09:30:00Z", "updated_at": "2026-09-29T09:30:02Z" } } }, "CreatePaySessionRequest": { "summary": "Card on the payment form", "value": { "merchant_reference": "order-50001", "amount": { "value": "75.00", "currency": "EUR" }, "description": "Order 50001", "expires_at": "2026-09-29T10:40:00Z", "payer": { "email": "jane@example.com", "address": { "country": "US", "state": "CA", "city": "San Francisco", "postal_code": "94105", "line1": "1 Market Street" } }, "return_urls": { "success": "https://shop.example.com/pay/success", "failure": "https://shop.example.com/pay/failure" } } }, "PaySessionCreated": { "summary": "Created", "value": { "data": { "id": "9c1e7a2f4b8d3c6e0a5f1b9d7e3c2a8f4b6d0e1c9a7f3b5d2e8c4a6f0b1d3e5c", "object": "pay_session", "merchant_reference": "order-50001", "amount": { "value": "75.00", "currency": "EUR" }, "url": "https://pay-in.mrcr.io/pay/9c1e7a2f4b8d3c6e0a5f1b9d7e3c2a8f4b6d0e1c9a7f3b5d2e8c4a6f0b1d3e5c", "expires_at": "2026-09-29T10:40:00Z", "payin_id": null, "created_at": "2026-09-29T09:40:00Z" } } }, "TransactionListPage": { "summary": "One page, payin shop", "value": { "data": [ { "id": "0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70", "object": "payin", "merchant_reference": "order-10001", "method_type": "payin_card", "status": "completed", "status_details": null, "amount": { "value": "100.50", "currency": "EUR" }, "refunded_amount": { "value": "0.00", "currency": "EUR" }, "next_action": null, "capture_method": "automatic", "card": { "brand": "visa", "last4": "1111" }, "created_at": "2026-09-29T09:00:00Z", "updated_at": "2026-09-29T09:00:20Z" }, { "id": "7c3a1f9b-4d8e-4f5c-8b0a-2e9d5f8c1be7", "object": "refund", "method_type": "refund", "payin_id": "3e9c7b5d-0f4a-4b1e-8d6c-8a5f1b4e7da3", "merchant_reference": "refund-10001", "status": "processing", "status_details": null, "amount": { "value": "20.00", "currency": "EUR" }, "created_at": "2026-09-29T11:00:00Z", "updated_at": "2026-09-29T11:00:00Z" } ], "has_more": false } }, "RefundCreated": { "summary": "Created", "value": { "data": { "id": "7c3a1f9b-4d8e-4f5c-8b0a-2e9d5f8c1be7", "object": "refund", "method_type": "refund", "payin_id": "3e9c7b5d-0f4a-4b1e-8d6c-8a5f1b4e7da3", "merchant_reference": "refund-10001", "status": "created", "status_details": null, "amount": { "value": "20.00", "currency": "EUR" }, "created_at": "2026-09-29T11:00:00Z", "updated_at": "2026-09-29T11:00:00Z" } } }, "RefundProcessing": { "summary": "Processing", "value": { "data": { "id": "7c3a1f9b-4d8e-4f5c-8b0a-2e9d5f8c1be7", "object": "refund", "method_type": "refund", "payin_id": "3e9c7b5d-0f4a-4b1e-8d6c-8a5f1b4e7da3", "merchant_reference": "refund-10001", "status": "processing", "status_details": null, "amount": { "value": "20.00", "currency": "EUR" }, "created_at": "2026-09-29T11:00:00Z", "updated_at": "2026-09-29T11:00:00Z" } } }, "CreateCardPayoutRequest": { "summary": "Card payout", "value": { "merchant_reference": "payout-10001", "amount": { "value": "300.00", "currency": "EUR" }, "card": { "number": "4111111111111111", "cardholder_name": "JOHN SMITH" }, "recipient": { "first_name": "John", "last_name": "Smith", "phone": "+14155550123", "address": { "country": "US", "state": "CA", "city": "San Francisco", "postal_code": "94105", "line1": "1 Market Street" } } } }, "PayoutCreated": { "summary": "Created", "value": { "data": { "id": "6b2f0e8a-3c7d-4e4b-9a9f-1d8c4e7b0ad6", "object": "payout", "merchant_reference": "payout-10001", "method_type": "payout_card", "status": "created", "status_details": null, "amount": { "value": "300.00", "currency": "EUR" }, "card": { "brand": "visa", "last4": "1111" }, "created_at": "2026-09-29T12:00:00Z", "updated_at": "2026-09-29T12:00:00Z" } } }, "PayoutFailed": { "summary": "Failed — recipient details rejected", "value": { "data": { "id": "6b2f0e8a-3c7d-4e4b-9a9f-1d8c4e7b0ad6", "object": "payout", "merchant_reference": "payout-10001", "method_type": "payout_card", "status": "failed", "status_details": { "code": "invalid_recipient_details", "message": "Card number rejected by the receiving bank" }, "amount": { "value": "300.00", "currency": "EUR" }, "card": { "brand": "visa", "last4": "1111" }, "created_at": "2026-09-29T12:00:00Z", "updated_at": "2026-09-29T12:00:09Z" } } }, "PayinCompletedEvent": { "summary": "payin.completed", "value": { "id": "8d4b2a0c-5e9f-4a6d-9c1b-3f0e6a9d2cf8", "type": "payin.completed", "shop_id": 1024, "created_at": "2026-09-29T09:00:20Z", "data": { "object": { "id": "0b6f4e2a-7c1d-4e8b-9a3f-5d2c8e1b4a70", "object": "payin", "merchant_reference": "order-10001", "method_type": "payin_card", "status": "completed", "status_details": null, "amount": { "value": "100.50", "currency": "EUR" }, "refunded_amount": { "value": "0.00", "currency": "EUR" }, "next_action": null, "capture_method": "automatic", "card": { "brand": "visa", "last4": "1111" }, "created_at": "2026-09-29T09:00:00Z", "updated_at": "2026-09-29T09:00:20Z" } } } } } }, "x-ext-urls": {} }