{ "openapi": "3.1.0", "info": { "title": "e-Payouts API", "version": "2.0.0", "description": "e-Payouts REST API for merchants: create payments (hosted paymentbox), query their status, available methods, balance and refunds. JSON over HTTPS; authentication exclusively through HMAC-SHA256 signed headers. Amounts always travel as text with two decimals and a dot (\"49.90\"), and dates in UTC (ISO 8601)." }, "servers": [ { "url": "http://api2.e-payouts.local", "description": "Production" } ], "security": [ { "KeyId": [], "Timestamp": [], "Nonce": [], "Signature": [] } ], "tags": [ { "name": "account", "x-displayName": "Account", "description": "Test your credentials, check your balance and see your modules and their payment methods." }, { "name": "payments", "x-displayName": "Payments", "description": "Create payments (get the paymentbox link) and query their status." }, { "name": "refunds", "x-displayName": "Refunds and chargebacks", "description": "Request a refund for a payment and list refunds and chargebacks." }, { "name": "legacy", "x-displayName": "v1 compatibility", "description": "Same parameters and responses as api.e-payouts.com (v1), with the new authentication. To migrate without rewriting the integration. Only available when the v1 integration is enabled for your account." }, { "name": "public", "x-displayName": "No authentication", "description": "Service status." } ], "paths": { "/health": { "get": { "tags": [ "public" ], "operationId": "health", "security": [], "summary": "Service status", "description": "Tells whether the API is up. It needs no signature: use it for monitoring (for example, a periodic check from your server).", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "status": { "type": "string", "const": "ok", "description": "Always \"ok\" when the API answers." } } } } }, "example": { "data": { "status": "ok" } } } } } } } }, "/v2/ping": { "get": { "tags": [ "account" ], "operationId": "ping", "summary": "Test credentials", "description": "Checks that your Key ID, secret and signature are right, without doing anything else. It returns the name of the merchant that owns the key and the server time: if signing fails with timestamp_out_of_range, compare server_time with your server clock. It is the recommended first call when integrating.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "object", "properties": { "object": { "const": "ping" }, "merchant": { "type": "string", "description": "Name of the merchant that owns the key." }, "uid": { "type": [ "integer", "null" ], "description": "Your v1 merchant id, if the account comes from v1; otherwise null." }, "server_time": { "type": "string", "format": "date-time", "description": "Server time (UTC)." } } } } }, "example": { "data": { "object": "ping", "merchant": "My Store Ltd", "uid": 73, "server_time": "2026-09-30T15:04:05Z" } } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/balance": { "get": { "tags": [ "account" ], "operationId": "getBalance", "summary": "Balance per currency", "description": "Returns your balance in each currency you hold: what is available to withdraw, what is pending (paid payments waiting for their availability date) and what is held (guarantee reserves). It is the same balance you see in your merchant panel.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } } }, "example": { "data": [ { "object": "balance", "currency": "EUR", "available": "1250.40", "pending": "486.15", "reserved": "62.30", "updated_at": "2026-09-30T14:35:10Z" } ] } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/modules": { "get": { "tags": [ "account" ], "operationId": "listModules", "summary": "List modules", "description": "Returns every module in your account with its site. A module is a payment integration (a store or a form): every payment is created for a module, which defines the enabled methods, the notification URL and whether it is live or in test mode (sandbox). Use it to get the module id you need to create payments.", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Module" } } } }, "example": { "data": [ { "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10", "object": "module", "mid": 55, "name": "Main store", "mode": "live", "status": "enabled", "price": null, "currency": null, "site": { "name": "tienda.example.com", "url": "https://tienda.example.com", "status": "enabled" } } ] } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/modules/{module}": { "get": { "tags": [ "account" ], "operationId": "getModule", "summary": "Get a module", "description": "Returns one module of your account: name, mode (live or sandbox), status, default price if any, and its site. Use it, for example, to check before charging that the module and its site are enabled.", "parameters": [ { "name": "module", "in": "path", "required": true, "description": "Module id (UUID) or v1 mid.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Module" } } }, "example": { "data": { "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10", "object": "module", "mid": 55, "name": "Main store", "mode": "live", "status": "enabled", "price": null, "currency": null, "site": { "name": "tienda.example.com", "url": "https://tienda.example.com", "status": "enabled" } } } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or belongs to another merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/modules/{module}/methods": { "get": { "tags": [ "account" ], "operationId": "listMethods", "summary": "Available methods", "description": "Returns the payment methods the paymentbox would offer the customer for that module, amount and country, with the code your integration uses, each one's minimum and maximum and the estimated commission. Use it to show the methods in your own store or to preselect one when creating the payment (method field). amount and currency are required unless the module has a fixed price.", "parameters": [ { "name": "module", "in": "path", "required": true, "description": "Module id (UUID) or v1 mid.", "schema": { "type": "string" } }, { "name": "amount", "in": "query", "required": false, "description": "Amount, dot as decimal separator.", "schema": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ] } }, { "name": "currency", "in": "query", "required": false, "description": "Currency of the amount (ISO 4217).", "schema": { "type": "string", "pattern": "^[A-Z]{3}$", "default": "EUR" } }, { "name": "country", "in": "query", "required": false, "description": "Customer country (ISO 3166-1 alpha-2). Some methods are only offered in certain countries.", "schema": { "type": "string", "pattern": "^[A-Za-z]{2}$" } }, { "name": "lang", "in": "query", "required": false, "description": "Language of each method name (the one the customer sees at checkout). Without it, your account language.", "schema": { "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt" ] } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Method" } }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ], "description": "Amount used for the calculation (the module fixed price, if any)." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency of the amount." }, "sandbox": { "type": "boolean", "description": "true when the module is in test mode." } } }, "example": { "data": [ { "object": "method", "code": "safetypay", "name": "SafetyPay", "min": "10.00", "max": "2000.00", "commission": { "amount": "8.74", "currency": "EUR" }, "requires_phone": false }, { "object": "method", "code": "multibanco", "name": "Multibanco", "min": "5.00", "max": "1000.00", "commission": { "amount": "3.17", "currency": "EUR" }, "requires_phone": false }, { "object": "method", "code": "mbway", "name": "MB WAY", "min": "5.00", "max": "1000.00", "commission": { "amount": "3.17", "currency": "EUR" }, "requires_phone": true } ], "amount": "49.90", "currency": "EUR", "sandbox": false } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "IP not allowed or merchant disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or belongs to another merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed: see error.fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/payments": { "post": { "tags": [ "payments" ], "operationId": "createPayment", "summary": "Create a payment", "description": "Prepares a charge and returns checkout_url, the paymentbox address where the customer chooses the method and pays: redirect them there (or open it in an iframe). No payment exists yet: it is created when the customer chooses the method and pays. The result arrives by webhook at the module's notification URL, with the same ucode. The link expires in 60 minutes.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional (8 to 64 characters [A-Za-z0-9_-]). Lets you retry without duplicates: repeating the call with the same key and body within 24 h returns the original response (with the header Idempotent-Replayed: true) instead of creating another resource. Use a new key for each different operation.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePayment" }, "example": { "module": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10", "amount": "49.90", "currency": "EUR", "ucode": "PEDIDO-1042", "locale": "es", "customer": { "name": "Ana García", "email": "ana@example.com", "country": "ES" } } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Checkout" } } }, "example": { "data": { "object": "checkout", "checkout_url": "http://paymentbox2.e-payouts.local/pagar?t=Xk3v9QpL2mZ7wR4tY8bN1cF6hJ0sD5aG", "expires_at": "2026-09-30T16:04:05Z", "sandbox": false, "module": { "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10", "mid": 55 }, "amount": "49.90", "currency": "EUR", "ucode": "PEDIDO-1042", "method": null, "methods": [ "sofort", "safetypay", "ppal", "16cards", "multibanco", "mbway" ] } } } } }, "400": { "description": "Invalid parameter or malformed JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "IP not allowed or merchant disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or belongs to another merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The current state does not allow the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "415": { "description": "Wrong Content-Type.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed: see error.fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "payments" ], "operationId": "listPayments", "summary": "List payments", "description": "Searches the payments of your account and returns them newest first. Use it to reconcile: for example, find the payment for an order (ucode), review a day's completed payments or recover the status if a webhook was lost. Filters can be combined. It returns up to limit payments per page: if has_more is true, request the next one passing next_cursor as cursor. Test payments (sandbox) are listed separately, with sandbox=true.", "parameters": [ { "name": "ucode", "in": "query", "required": false, "description": "Only payments with that order code.", "schema": { "type": "string" } }, { "name": "module", "in": "query", "required": false, "description": "Only those of that module: id (UUID) or mid.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Only those in that status.", "schema": { "type": "string", "enum": [ "created", "pending", "completed", "failed", "cancelled", "refunded", "charged_back" ] } }, { "name": "created_from", "in": "query", "required": false, "description": "Created from this date (UTC), inclusive: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ.", "schema": { "type": "string", "examples": [ "2026-09-01" ] } }, { "name": "created_to", "in": "query", "required": false, "description": "Created before this date (UTC), exclusive.", "schema": { "type": "string", "examples": [ "2026-10-01T00:00:00Z" ] } }, { "name": "sandbox", "in": "query", "required": false, "description": "true = list test payments from sandbox-mode modules instead of real ones.", "schema": { "type": "boolean", "default": false } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (1 to 100).", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "To get the next page: next_cursor from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "has_more": { "type": "boolean", "description": "true when there are more results after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it as cursor to get the next page; null on the last page." } } }, "example": { "data": [ { "code": "8a2c4e6f-1b3d-4f5a-9c7e-0d2f4a6b8c1e", "object": "payment", "sandbox": false, "status": "pending", "ucode": "PEDIDO-1043", "method": "multibanco", "effective_method": "multibanco", "amount": "12.00", "currency": "USD", "charged": { "amount": "10.65", "currency": "EUR", "exchange_rate": "0.8877599005" }, "module": { "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10", "mid": 55 }, "customer": { "name": "João Silva", "email": "joao@example.com", "country": "PT" }, "commission": { "amount": "0.82", "currency": "EUR" }, "net_amount": null, "settlement": { "amount": "11.93", "currency": "USD", "exchange_rate": "1.120629575" }, "completed_at": null, "created_at": "2026-09-30T14:35:10Z" }, { "code": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b", "object": "payment", "sandbox": false, "status": "completed", "ucode": "PEDIDO-1042", "method": "sofort", "effective_method": "sofort", "amount": "49.90", "currency": "EUR", "charged": null, "module": { "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10", "mid": 55 }, "customer": { "name": "Ana García", "email": "ana@example.com", "country": "ES" }, "commission": { "amount": "2.15", "currency": "EUR" }, "net_amount": "47.75", "settlement": { "amount": "49.90", "currency": "EUR", "exchange_rate": null }, "completed_at": "2026-09-18T14:35:02Z", "created_at": "2026-09-18T14:33:22Z" } ], "has_more": true, "next_cursor": "MTAyNA" } } } }, "400": { "description": "Invalid parameter or malformed JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or belongs to another merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/payments/{code}": { "get": { "tags": [ "payments" ], "operationId": "getPayment", "summary": "Get a payment", "description": "Returns the current status and details of a payment: method, amounts, commission, net and settlement. Use it to confirm a webhook before delivering the order (fetch the payment by id and check status and amount) or to show the status in your system. It works for real and test payments; test payments do not include commission, net_amount, settlement or completed_at.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Payment code (UUID, the payment's code field).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Payment" } } }, "example": { "data": { "code": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b", "object": "payment", "sandbox": false, "status": "completed", "ucode": "PEDIDO-1042", "method": "sofort", "effective_method": "sofort", "amount": "49.90", "currency": "EUR", "charged": null, "module": { "id": "7c1e4a52-5d0b-4f7e-9a1d-3b8f2c6d9e10", "mid": 55 }, "customer": { "name": "Ana García", "email": "ana@example.com", "country": "ES" }, "commission": { "amount": "2.15", "currency": "EUR" }, "net_amount": "47.75", "settlement": { "amount": "49.90", "currency": "EUR", "exchange_rate": null }, "completed_at": "2026-09-18T14:35:02Z", "created_at": "2026-09-18T14:33:22Z" } } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or belongs to another merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/payments/{code}/refunds": { "post": { "tags": [ "refunds" ], "operationId": "requestRefund", "summary": "Request a refund", "description": "Requests the full refund of a completed payment. It stays in created status until e-Payouts processes it; only one live refund per payment. It can only be requested within the window set by e-Payouts since the payment was completed (currently 2 months); after that it answers 409 refund_window_expired and must be requested through a ticket in your merchant panel. Test payments are not refunded.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Payment code (UUID, the payment's code field).", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional (8 to 64 characters [A-Za-z0-9_-]). Lets you retry without duplicates: repeating the call with the same key and body within 24 h returns the original response (with the header Idempotent-Replayed: true) instead of creating another resource. Use a new key for each different operation.", "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "reason": { "type": "string", "maxLength": 255, "description": "Reason (optional), for your records and e-Payouts'." } } }, "example": { "reason": "The customer cancelled the order" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/Adjustment" } } }, "example": { "data": { "id": "c4d5e6f7-0a1b-4c2d-8e3f-4a5b6c7d8e9f", "object": "refund", "status": "created", "amount": "49.90", "currency": "EUR", "reason": "The customer cancelled the order", "payment": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b", "created_at": "2026-09-20T09:12:44Z", "resolved_at": null } } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or belongs to another merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The current state does not allow the operation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Validation failed: see error.fields.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/payments/{code}/adjustments": { "get": { "tags": [ "refunds" ], "operationId": "listPaymentAdjustments", "summary": "Refunds and chargebacks of a payment", "description": "Returns the refunds and chargebacks of a payment, newest first, with their status. Use it to follow a refund you requested or to see whether the customer disputed the charge with their bank.", "parameters": [ { "name": "code", "in": "path", "required": true, "description": "Payment code (UUID, the payment's code field).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (1 to 100).", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "To get the next page: next_cursor from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Adjustment" } }, "has_more": { "type": "boolean", "description": "true when there are more results after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it as cursor to get the next page; null on the last page." } } }, "example": { "data": [ { "id": "c4d5e6f7-0a1b-4c2d-8e3f-4a5b6c7d8e9f", "object": "refund", "status": "created", "amount": "49.90", "currency": "EUR", "reason": "The customer cancelled the order", "payment": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b", "created_at": "2026-09-20T09:12:44Z", "resolved_at": null } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Invalid parameter or malformed JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or belongs to another merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v2/adjustments": { "get": { "tags": [ "refunds" ], "operationId": "listAdjustments", "summary": "List refunds and chargebacks", "description": "Returns the refunds and chargebacks of your whole account, newest first. Use it to reconcile the amounts deducted from your balance. It can be filtered by type, status or payment, and it is paginated like payments.", "parameters": [ { "name": "type", "in": "query", "required": false, "description": "refund = refunds; chargeback = chargebacks.", "schema": { "type": "string", "enum": [ "refund", "chargeback" ] } }, { "name": "status", "in": "query", "required": false, "description": "Only those in that status.", "schema": { "type": "string", "enum": [ "created", "processing", "completed", "rejected" ] } }, { "name": "payment", "in": "query", "required": false, "description": "Only those of that payment (UUID id).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Results per page (1 to 100).", "schema": { "type": "integer", "default": 20, "minimum": 1, "maximum": 100 } }, { "name": "cursor", "in": "query", "required": false, "description": "To get the next page: next_cursor from the previous response.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "has_more", "next_cursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Adjustment" } }, "has_more": { "type": "boolean", "description": "true when there are more results after this page." }, "next_cursor": { "type": [ "string", "null" ], "description": "Pass it as cursor to get the next page; null on the last page." } } }, "example": { "data": [ { "id": "c4d5e6f7-0a1b-4c2d-8e3f-4a5b6c7d8e9f", "object": "refund", "status": "created", "amount": "49.90", "currency": "EUR", "reason": "The customer cancelled the order", "payment": "3f6b2d10-9a4c-4e21-8b7f-5c0d1e2f3a4b", "created_at": "2026-09-20T09:12:44Z", "resolved_at": null }, { "id": "d1e2f3a4-5b6c-4d7e-8f9a-0b1c2d3e4f5a", "object": "chargeback", "status": "completed", "amount": "30.00", "currency": "EUR", "reason": null, "payment": "9b8a7c6d-5e4f-4a3b-8c2d-1e0f9a8b7c6d", "created_at": "2026-09-10T16:40:00Z", "resolved_at": "2026-09-12T10:05:31Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Invalid parameter or malformed JSON.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, invalid, expired or reused signature.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found or belongs to another merchant.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Rate limit exceeded (see Retry-After).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Maintenance or API disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/createCode": { "post": { "tags": [ "legacy" ], "operationId": "legacyCreateCode", "summary": "createCode (v1): create payment", "description": "The same as POST /v2/payments with v1 parameters: it returns the paymentbox link where you must send the customer. With direct present, instead of answering JSON it redirects (302) straight to that link. Note: unlike the other v1 routes, the response has no message or data.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "uid", "mid" ], "properties": { "uid": { "type": "string", "description": "v1 merchant id (your account)." }, "mid": { "type": "string", "description": "v1 module id (mid)." }, "price": { "type": "string", "description": "Amount (your account currency). Required if the module has no default price; if its price is fixed, that one is charged." }, "type": { "type": "string", "description": "Method code to preselect it (optional)." }, "cc": { "type": "string", "description": "Customer country (2 letters)." }, "email": { "type": "string", "description": "Customer email." }, "name": { "type": "string", "description": "Customer first name." }, "lastname": { "type": "string", "description": "Customer last name." }, "ucode": { "type": "string", "description": "Your order code." }, "direct": { "type": "string", "description": "If present (any value), redirects (302) to the paymentbox." } } }, "example": { "uid": "73", "mid": "55", "price": "49.90", "cc": "es", "email": "ana@example.com", "name": "Ana", "lastname": "García", "ucode": "PEDIDO-1042" } } } }, "responses": { "200": { "description": "Always HTTP 200. On success error = 0 with the link; otherwise error holds the v1 error number (see Errors).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "integer", "description": "0 = success." }, "code": { "type": "string", "description": "Payment session code (the last part of url)." }, "url": { "type": "string", "format": "uri", "description": "Paymentbox link where you send the customer." }, "expires_at": { "type": "string", "format": "date-time", "description": "Link expiry (UTC)." } } }, "example": { "error": 0, "code": "Xk3v9QpL2mZ7wR4tY8bN1cF6hJ0sD5aG", "url": "http://paymentbox2.e-payouts.local/pagar?t=Xk3v9QpL2mZ7wR4tY8bN1cF6hJ0sD5aG", "expires_at": "2026-09-30T16:04:05Z" } } } }, "302": { "description": "With direct: redirect to the paymentbox (Location header)." } } } }, "/v1/getData": { "post": { "tags": [ "legacy" ], "operationId": "legacyGetData", "summary": "getData (v1): site, module and methods", "description": "Returns the site and module status and the methods available for a country, with their minimum and maximum, and the address to create payments. Equivalent to GET /v2/modules/{module}/methods in the v1 format.", "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "required": [ "uid", "mid", "cc" ], "properties": { "uid": { "type": "string", "description": "v1 merchant id (your account)." }, "mid": { "type": "string", "description": "v1 module id (mid)." }, "cc": { "type": "string", "description": "Customer country (2 letters)." }, "price": { "type": "string", "description": "Amount; required if the module has no fixed price." } } }, "example": { "uid": "73", "mid": "55", "cc": "pt", "price": "49.90" } } } }, "responses": { "200": { "description": "Always HTTP 200. On success error = 0 and the result in data; otherwise error holds the v1 error number (see Errors).", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "integer", "description": "0 = success." }, "message": { "type": "string", "description": "Fixed v1 text." }, "data": { "type": "object", "properties": { "error": { "type": "integer", "description": "Always 0 (repeated inside data, as in v1)." }, "sites": { "type": "object", "description": "Status and URL of the module's site." }, "modules": { "type": "object", "description": "Price, status, currency, allowed IPs (api_ip, comma separated) and methods per country (price, pmin, pmax, name)." }, "gateway": { "type": "object", "description": "createCode URL." } } } } }, "example": { "error": 0, "message": "API response -> successful request.", "data": { "error": 0, "sites": { "status": "enabled", "url": "https://tienda.example.com" }, "modules": { "price": null, "status": "enabled", "currency": "EUR", "country": "pt", "api_ip": "", "methods": { "pt": [ { "method": "multibanco", "country": "pt", "price": "49.90", "pmin": "5.00", "pmax": "1000.00", "name": "Multibanco" }, { "method": "mbway", "country": "pt", "price": "49.90", "pmin": "5.00", "pmax": "1000.00", "name": "MB WAY" } ] } }, "gateway": { "url": "http://api2.e-payouts.local/v1/createCode" } } } } } } } } } }, "components": { "securitySchemes": { "KeyId": { "type": "apiKey", "in": "header", "name": "X-Api-Key-Id", "description": "Public Key ID (your merchant panel → API)." }, "Timestamp": { "type": "apiKey", "in": "header", "name": "X-Api-Timestamp", "description": "Unix seconds; ±300 s accepted." }, "Nonce": { "type": "apiKey", "in": "header", "name": "X-Api-Nonce", "description": "Random and unique per call, 16 to 64 characters [A-Za-z0-9_-]." }, "Signature": { "type": "apiKey", "in": "header", "name": "X-Api-Signature", "description": "hex(HMAC-SHA256(\"....\", secret))" } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "request_id" ], "properties": { "code": { "type": "string", "examples": [ "validation_failed" ], "description": "Stable error code, for your program (see Errors)." }, "message": { "type": "string", "description": "Human-readable explanation; it may change." }, "fields": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Validation errors only: what failed in each field." }, "request_id": { "type": "string", "description": "Quote it when contacting support." } } } } }, "CreatePayment": { "type": "object", "required": [ "module" ], "additionalProperties": false, "properties": { "module": { "type": "string", "description": "Module id (UUID) or v1 mid." }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ], "description": "Required if the module has no default price. If the module price is fixed, omit it or send that value; otherwise it replaces the default price." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Defaults to your account currency. If different, the payment is converted to your account currency." }, "ucode": { "type": "string", "pattern": "^[A-Za-z0-9._:/#-]{1,64}$", "description": "Your order code; it comes back in the webhook and the redirect." }, "method": { "type": "string", "description": "Preselect a method (see /methods). If unavailable: 422 method_unavailable." }, "locale": { "type": "string", "enum": [ "en", "es", "fr", "de", "it", "pt" ], "default": "es", "description": "Paymentbox language." }, "customer": { "type": "object", "additionalProperties": false, "description": "Customer data to prefill the paymentbox form (optional).", "properties": { "name": { "type": "string", "maxLength": 190, "description": "Full name." }, "email": { "type": "string", "format": "email", "description": "The receipt is sent there." }, "country": { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "Country (ISO 3166-1 alpha-2); decides which methods are offered. Without it, the paymentbox detects it from the customer IP and lets them change it." }, "phone": { "type": "string", "description": "Portuguese mobile (+351 9XXXXXXXX) for MB WAY. If you also send method, name and email, the customer goes straight to the provider, except for MB WAY: there they see the screen prefilled and confirm with one click." } } } } }, "Checkout": { "type": "object", "properties": { "object": { "const": "checkout" }, "checkout_url": { "type": "string", "format": "uri", "description": "Paymentbox link: send the customer there." }, "expires_at": { "type": "string", "format": "date-time", "description": "Link expiry (UTC)." }, "sandbox": { "type": "boolean", "description": "true when the module is in test mode (no real money is charged)." }, "module": { "$ref": "#/components/schemas/ModuleRef" }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ], "description": "Amount to charge." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency of the amount." }, "ucode": { "type": [ "string", "null" ], "description": "Your order code, if you sent one." }, "method": { "type": [ "string", "null" ], "description": "Preselected method, if you asked for one." }, "methods": { "type": "array", "items": { "type": "string" }, "description": "Codes of the methods the customer will see." } } }, "ModuleRef": { "type": "object", "description": "Module it belongs to.", "properties": { "id": { "type": "string", "description": "Module id (UUID)." }, "mid": { "type": [ "integer", "null" ], "description": "v1 mid, if the module comes from v1." } } }, "Payment": { "type": "object", "properties": { "code": { "type": "string", "description": "Payment code (UUID)." }, "object": { "const": "payment" }, "sandbox": { "type": "boolean", "description": "true = test payment (no money moved)." }, "status": { "type": "string", "enum": [ "created", "pending", "completed", "failed", "cancelled", "refunded", "charged_back" ], "description": "Only completed means paid. pending = waiting for the customer to finish (e.g. unpaid Multibanco reference)." }, "ucode": { "type": [ "string", "null" ], "description": "Your order code." }, "method": { "type": "string", "description": "Code of the method the customer chose." }, "effective_method": { "type": "string", "description": "Method that actually charged the payment. Differs from method only when that method is routed (e.g. method ppal, effective_method 16cards)." }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ], "description": "Amount you asked to charge." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency of amount." }, "charged": { "type": [ "object", "null" ], "description": "Only when the chosen method does not accept the payment currency (e.g. MB WAY and Multibanco charge in EUR): what the customer was charged and the rate used (market + margin). amount and currency are still what you requested. Otherwise null.", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ] }, "currency": { "type": "string" }, "exchange_rate": { "type": "string" } } }, "module": { "$ref": "#/components/schemas/ModuleRef" }, "customer": { "type": "object", "description": "Data the customer left (each may be null).", "properties": { "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] } } }, "commission": { "type": "object", "description": "e-Payouts commission. Real payments only.", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ] }, "currency": { "type": "string" } } }, "net_amount": { "type": [ "string", "null" ], "description": "Amount minus commission, in the currency of amount (real payments only; null when charged in another currency: see settlement)." }, "settlement": { "type": [ "object", "null" ], "description": "What is credited to your balance: amount in your account currency and applied rate (margin included; null when there was no conversion). Real payments only.", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ] }, "currency": { "type": "string", "enum": [ "EUR", "USD" ] }, "exchange_rate": { "type": [ "string", "null" ] } } }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it was paid; null if not yet. Real payments only." }, "created_at": { "type": "string", "format": "date-time", "description": "When the payment was created (UTC)." } } }, "Adjustment": { "type": "object", "properties": { "id": { "type": "string", "description": "Refund or chargeback id (UUID)." }, "object": { "type": "string", "enum": [ "refund", "chargeback" ], "description": "refund = refund; chargeback = chargeback (the customer disputed the charge with their bank)." }, "status": { "type": "string", "enum": [ "created", "processing", "completed", "rejected" ], "description": "created = requested; processing = in progress; completed = done; rejected = rejected." }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ], "description": "Amount refunded or disputed." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Currency of amount." }, "reason": { "type": [ "string", "null" ], "description": "Reason, if any." }, "payment": { "type": "string", "description": "Payment id (UUID)." }, "created_at": { "type": "string", "format": "date-time", "description": "When it was created (UTC)." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When it finished (completed or rejected); null while in progress." } } }, "Module": { "type": "object", "properties": { "id": { "type": "string", "description": "Module id (UUID): the one you send as module when creating payments." }, "object": { "const": "module" }, "mid": { "type": [ "integer", "null" ], "description": "v1 mid, if the module comes from v1." }, "name": { "type": "string", "description": "Name you gave it." }, "mode": { "type": "string", "enum": [ "live", "sandbox" ], "description": "live = charges for real; sandbox = test with simulator." }, "status": { "type": "string", "enum": [ "created", "enabled", "disabled", "off" ], "description": "Only enabled can charge." }, "price": { "type": [ "string", "null" ], "description": "Default price, if any." }, "currency": { "type": [ "string", "null" ], "description": "Price currency, if any." }, "site": { "type": "object", "description": "Site it belongs to.", "properties": { "name": { "type": "string" }, "url": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "enabled", "disabled", "locked", "off" ], "description": "Only enabled can charge." } } } } }, "Method": { "type": "object", "properties": { "object": { "const": "method" }, "code": { "type": "string", "description": "The code your integration uses (routing applied); the one you send as method." }, "name": { "type": "string", "description": "Display name." }, "min": { "type": [ "string", "null" ], "description": "Minimum amount; null = no minimum." }, "max": { "type": [ "string", "null" ], "description": "Maximum amount; null = no maximum." }, "commission": { "type": "object", "description": "Estimated commission for that amount.", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ] }, "currency": { "type": "string" } } }, "requires_phone": { "type": "boolean", "description": "true when the customer must give a phone number (MB WAY)." } } }, "Balance": { "type": "object", "properties": { "object": { "const": "balance" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "Balance currency." }, "available": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ], "description": "Available to withdraw." }, "pending": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ], "description": "Pending: paid payments still waiting for their availability date." }, "reserved": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "examples": [ "25.00" ], "description": "Held: guarantee reserves, until their release date." }, "updated_at": { "type": "string", "format": "date-time", "description": "Last movement (UTC)." } } } } } }