{ "openapi": "3.1.0", "info": { "title": "Easypay Payments API", "description": "Terms conditions and legal terms
Privacy Policy", "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" }, "contact": { "name": "Easypay Documentation", "email": "correio@easypay.pt" }, "version": "2.0", "x-logo": { "url": "https://easypay-cdn-delivery.s3.eu-central-1.amazonaws.com/logo.png", "altText": "easypay" }, "summary": "" }, "servers": [ { "url": "https://api.test.easypay.pt/2.0", "description": "Sandbox" }, { "url": "https://api.prod.easypay.pt/2.0", "description": "Production" } ], "security": [ { "accountId": [], "apiKey": [] } ], "tags": [ { "name": "Single Payment", "description": "Create and manage one-time payment transactions" }, { "name": "Frequent Payment", "description": "Tokenize payment details for variable on-demand charges" }, { "name": "Subscription Payment", "description": "Set up and manage automated recurring payments" }, { "name": "Captures", "description": "Operations for managing payment captures" }, { "name": "Authorisations", "description": "Operations for managing payment authorisations" }, { "name": "Voids", "description": "A **void** cancels a payment authorisation **before it is captured**. The acquirer releases the amount that was held on the customer's card, so no money ever moves — as if the transaction had never happened.\n\nUse a void to undo an authorisation that has not yet been captured. To return money that has **already** been captured, use a **Refund** instead.\n\nVoids are supported for **single** and **frequent** payment authorisations.\n" }, { "name": "Refunds", "description": "Operations for managing payment refunds" }, { "name": "Chargebacks", "description": "Operations for managing chargebacks" }, { "name": "Notifications / Webhooks", "description": "Configure and manage webhook notifications for payment events" }, { "name": "Reports", "description": "Access transaction and ledger reports" }, { "name": "Settlements", "description": "View settlement details and history" }, { "name": "Out Payment", "description": "Transfer funds from Easypay accounts to SEPA bank accounts" }, { "name": "Config", "description": "Configure account URLs for notifications and credit card transactions" }, { "name": "Checkout", "description": "Embedded payment form solution for websites" }, { "name": "Pay By Link", "description": "Generate and manage shareable payment links" }, { "name": "Customer", "description": "Retrieve customer details and reward credit history" }, { "name": "Terminals", "description": "Manage terminals (POS devices)" }, { "name": "System", "description": "System health check endpoints" } ], "webhooks": { "yourGenericNotificationEndpoint": { "post": { "security": [ { "BasicAuth": [] } ], "tags": [ "Notifications / Webhooks" ], "summary": "Generic Notification", "description": "We will send you this json in our notifications", "requestBody": { "description": "Notification Payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification-generic" } } } }, "responses": { "200": { "description": "Indicates that the data was received successfully", "headers": { "X-Easypay-Code": { "description": "A user defined code", "schema": { "type": "string" } } } } } } }, "yourAuthorisationNotificationEndpoint": { "post": { "security": [ { "BasicAuth": [] } ], "tags": [ "Notifications / Webhooks" ], "summary": "Authorisation Notification", "description": "We will send you this json in our notification", "requestBody": { "description": "Notification Payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification-authorisation" } } } }, "responses": { "200": { "description": "Indicates that the data was received successfully", "headers": { "X-Easypay-Code": { "description": "A user defined code", "schema": { "type": "string" } } } } } } }, "yourNotificationEndpoint": { "post": { "security": [ { "BasicAuth": [] } ], "tags": [ "Notifications / Webhooks" ], "summary": "Transaction Notification", "description": "We will send you this json in our notification", "requestBody": { "description": "Notification Payload", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/notification-capture" } } } }, "responses": { "200": { "description": "Indicates that the data was received successfully", "headers": { "X-Easypay-Code": { "description": "A user defined code", "schema": { "type": "string" } } } } } } } }, "paths": { "/single": { "get": { "x-required-permissions": [ "single:read" ], "tags": [ "Single Payment" ], "summary": "Lists single payments", "description": "Full report with all the single payments from your Account\n\n**Required scope:** single:read\n\n", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/RecordsPerPage" }, { "$ref": "#/components/parameters/Type" }, { "$ref": "#/components/parameters/ExpirationTime" }, { "$ref": "#/components/parameters/Method" }, { "$ref": "#/components/parameters/CustomerKey" }, { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Key" }, { "$ref": "#/components/parameters/Value" }, { "$ref": "#/components/parameters/CreatedAt" } ], "responses": { "200": { "$ref": "#/components/responses/list-single" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "500": { "$ref": "#/components/responses/internal-error" } }, "security": [ { "accountId": [], "apiKey": [] } ], "operationId": "single-get" }, "post": { "x-required-permissions": [ "single:create" ], "tags": [ "Single Payment" ], "summary": "Create single payment", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/create-single-payment" }, "responses": { "201": { "$ref": "#/components/responses/create-single-payment" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "409": { "$ref": "#/components/responses/conflict" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "single-post", "description": "Creates a Single Payment\n\n**Required scope:** single:create\n\n" } }, "/single/{id}": { "get": { "x-required-permissions": [ "single:read" ], "tags": [ "Single Payment" ], "summary": "Shows single payment details", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-single-details" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "single-id-get", "description": "Retrieve a single payment details\n\n**Required scope:** single:read\n\n" }, "delete": { "x-required-permissions": [ "single:delete" ], "tags": [ "Single Payment" ], "summary": "Deletes single payment", "description": "This endpoint allows for the deletion of a single payment identified by its unique ID. The DELETE operation performs the following actions based on the payment method:\n\n - MB WAY and Credit Cards: Voids all authorizations.\n - Multibanco: Cancels the Multibanco Reference.\n - Direct Debit: Cancels the Direct Debit if the request is made before the cutoff hour(18:00 Europe/Lisbon).\n\nThis operation ensures that all associated authorizations and references are properly handled and terminated according to the specified payment method.\n\n**Required scope:** single:delete\n\n", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "$ref": "#/components/responses/no-content" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "single-delete" }, "patch": { "x-required-permissions": [ "single:update" ], "operationId": "single-update", "tags": [ "Single Payment" ], "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/update-single" }, "responses": { "200": { "$ref": "#/components/responses/single-update" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "Apply partial modifications to a single payment resource.\n\n**Required scope:** single:update\n\n", "summary": "Update a single Payment" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "name": "id", "in": "path", "required": true } ] }, "/frequent": { "get": { "x-required-permissions": [ "frequent:read" ], "tags": [ "Frequent Payment" ], "summary": "Lists frequent payments", "description": "Full report with all the frequent payments from your Account Id\n\n**Required scope:** frequent:read\n\n", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/RecordsPerPage" }, { "$ref": "#/components/parameters/ExpirationTime" }, { "$ref": "#/components/parameters/Method" }, { "$ref": "#/components/parameters/CustomerKey" }, { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Key" }, { "$ref": "#/components/parameters/CreatedAt" } ], "responses": { "200": { "$ref": "#/components/responses/list-frequent" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "frequent-get" }, "post": { "x-required-permissions": [ "frequent:create" ], "tags": [ "Frequent Payment" ], "summary": "Create frequent payment", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/create-frequent-payment" }, "responses": { "201": { "$ref": "#/components/responses/create-frequent-payment" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "Frequent payments are repeatable transactions of varying sums without the client having to enter their payment details again.\n\nIt is possible to limit the transferred sums by choosing minimum or maximum values, either to the total sum of the transactions or each individual transaction.\n\nSupported methods for frequent payments are: Credit Card, MB WAY, Multibanco, Direct Debit and Virtual IBAN\n\n\n**Required scope:** frequent:create\n\n", "operationId": "post_frequent" } }, "/frequent/{id}": { "get": { "x-required-permissions": [ "frequent:read" ], "tags": [ "Frequent Payment" ], "summary": "Shows frequent payment details", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-frequent-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "frequent-id-get", "description": "Retrieve a Frequent Payment details\n\n**Required scope:** frequent:read\n\n" }, "delete": { "x-required-permissions": [ "frequent:delete" ], "tags": [ "Frequent Payment" ], "summary": "Deletes frequent payment", "description": "3 times a day (10am, 3pm and 10pm) our system will attempt to close your deleted MB payments.
All CC and MBW authorisations will be deleted, releasing the funds.
All MBW operations waiting for user interaction will be cancelled.
Before 6pm all Sepa Direct Debits waiting for file processing will be cancelled.\n\n**Required scope:** frequent:delete\n\n", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "$ref": "#/components/responses/no-content" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "delete_frequent_id" }, "patch": { "x-required-permissions": [ "frequent:update" ], "tags": [ "Frequent Payment" ], "summary": "Updates frequent payment details", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/update-frequent" }, "responses": { "200": { "$ref": "#/components/responses/frequent-update" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "patch_frequent_id", "description": "**Required scope:** frequent:update\n\n" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "name": "id", "in": "path", "required": true } ] }, "/frequent/authorisation/{id}": { "post": { "x-required-permissions": [ "frequent:create" ], "tags": [ "Frequent Payment" ], "summary": "Request Authorisation", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/frequent-authorisation" }, "responses": { "201": { "$ref": "#/components/responses/frequent-authorisation" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "Create a new authorisation on a given Frequent Payment\n\n**Required scope:** frequent:create\n\n", "operationId": "frequent-authorisation" }, "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "name": "id", "in": "path", "required": true } ] }, "/config": { "get": { "x-required-permissions": [ "config:read" ], "tags": [ "Config" ], "summary": "Get Account Config", "parameters": [], "responses": { "200": { "$ref": "#/components/responses/get-config" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_config", "description": "**Required scope:** config:read\n\n" }, "patch": { "x-required-permissions": [ "config:update" ], "tags": [ "Config" ], "summary": "Patch Account Config", "description": "This endpoint is useful for setting up the correct URLs for event notifications.\nFor more details, see [Notifications-Webhooks.](https://docs.easypay.pt/#tag/Notifications-Webhooks)\n\n**Required scope:** config:update\n\n", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/patch-config" }, "responses": { "200": { "$ref": "#/components/responses/patch-config" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "x-codegen-request-body-name": "body", "operationId": "patch_config" } }, "/capture": { "get": { "x-required-permissions": [ "capture:read" ], "tags": [ "Captures" ], "summary": "List captures", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/CreatedAt" }, { "$ref": "#/components/parameters/UpdatedAt" } ], "responses": { "200": { "$ref": "#/components/responses/list-capture" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "**Required scope:** capture:read\n\n" } }, "/capture/{id}": { "post": { "x-required-permissions": [ "capture:create" ], "tags": [ "Captures" ], "summary": "Captures a Single Auth, Frequent and Frequent Auth", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/create-capture" }, "responses": { "201": { "$ref": "#/components/responses/create-capture" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "422": { "$ref": "#/components/responses/unprocessable-entity" }, "428": { "$ref": "#/components/responses/pre-condition-required" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "**Required scope:** capture:create\n\n" }, "get": { "x-required-permissions": [ "capture:read" ], "tags": [ "Captures" ], "summary": "Shows capture details", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-capture-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "**Required scope:** capture:read\n\n" }, "delete": { "operationId": "capture-delete", "x-required-permissions": [ "capture:delete" ], "x-badges": [ { "name": "Soon", "color": "orange" } ], "tags": [ "Captures" ], "summary": "Cancels a capture", "description": "**This endpoint is rolling out shortly.** The shape below is stable, but calls against it will not succeed until the feature ships.\n\nCancels a capture before it is processed.\n\nOnly captures still in **delayed**, **waiting** or **pending** can be cancelled, and only\nfor these payment methods:\n\n- **Multibanco:** `SPG` and `FILE` references. `SPG` cancels in real time. `FILE` can\n take up to 24 hours, so the reference may still be paid in that window. `CHECKDIGIT`\n references cannot be cancelled.\n- **Direct Debit:** until the instruction is sent to the customer's bank.\n- **Credit Card, Apple Pay, Google Pay and Samsung Wallet:** until the customer provides\n their payment details on the payment page or checkout.\n\nOnce a capture has succeeded, the money has already moved, so issue a **Refund** instead.\n\n\n**Required scope:** capture:delete\n\n", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "$ref": "#/components/responses/no-content" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "422": { "$ref": "#/components/responses/unprocessable-entity" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } } }, "/capture/{capture-uuid}/splits/{capture-split-uuid}": { "patch": { "x-required-permissions": [ "capture:update" ], "tags": [ "Captures" ], "summary": "Updates the split of a capture", "parameters": [ { "name": "capture-uuid", "in": "path", "description": "Capture Identification", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "capture-split-uuid", "in": "path", "description": "Capture Split Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/update-capture-split" }, "responses": { "201": { "$ref": "#/components/responses/update-capture-split" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "428": { "$ref": "#/components/responses/pre-condition-required" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "patch_capture_capture_uuid_splits_capture_split_uuid", "description": "**Required scope:** capture:update\n\n" } }, "/authorisation/{id}": { "get": { "x-required-permissions": [ "authorisation:read" ], "tags": [ "Authorisations" ], "summary": "Shows authorisation details", "description": "Retrieves the details of an authorisation\n\n**Required scope:** authorisation:read\n\n", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-authorisation-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_authorisation_id" } }, "/checkout/{id}": { "get": { "x-required-permissions": [ "checkout:read" ], "tags": [ "Checkout" ], "summary": "Shows checkout details", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/checkout-get-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "security": [ { "accountId": [], "apiKey": [] } ], "operationId": "get_checkout_id", "description": "**Required scope:** checkout:read\n\n" }, "delete": { "x-required-permissions": [ "checkout:delete" ], "tags": [ "Checkout" ], "summary": "Cancels a checkout", "description": "This cancels the Checkout and deletes the payment associated with it if possible.\n\n**Required scope:** checkout:delete\n\n", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "$ref": "#/components/responses/no-content" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "security": [ { "accountId": [], "apiKey": [] } ], "operationId": "delete_checkout_id" } }, "/checkout": { "post": { "x-required-permissions": [ "checkout:create" ], "tags": [ "Checkout" ], "summary": "Create Checkout", "description": "Creates a Checkout Session.\n\n**Required scope:** checkout:create\n\n", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/create-checkout" }, "responses": { "201": { "$ref": "#/components/responses/create-checkout" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "checkout-post", "security": [ { "accountId": [], "apiKey": [] } ] } }, "/subscription": { "get": { "x-required-permissions": [ "subscription:read" ], "tags": [ "Subscription Payment" ], "summary": "List subscription payments", "description": "Full report with all the subscriptions payments from your Account Id\n\n**Required scope:** subscription:read\n\n", "parameters": [ { "name": "page", "in": "query", "description": "Page Number", "schema": { "type": "number" } }, { "name": "records_per_page", "in": "query", "description": "Limit records per page (Max: 100)", "schema": { "type": "number", "default": 20 } }, { "name": "expiration_time", "in": "query", "description": "Filter by expiration time interval (max 30 days)", "schema": { "type": "string" } }, { "name": "method", "in": "query", "description": "Filter by method", "schema": { "type": "string" } }, { "name": "customer", "in": "query", "description": "Filter by customer key", "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Filter by id", "schema": { "type": "string" } }, { "name": "key", "in": "query", "description": "Filter by subscription key", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "description": "Filter by created datetime interval (max 30 days)", "schema": { "type": "string" } }, { "schema": { "type": "string", "example": "active" }, "in": "query", "name": "status", "description": "Filter by Subscription Status" }, { "schema": { "type": "string", "example": "10.55" }, "in": "query", "name": "value", "description": "Filter by Subscription Value" } ], "responses": { "200": { "$ref": "#/components/responses/list-subscription" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_subscription" }, "post": { "x-required-permissions": [ "subscription:create" ], "tags": [ "Subscription Payment" ], "summary": "Create subscription payment", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/create-subscription" }, "responses": { "201": { "$ref": "#/components/responses/create-subscription" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "Creates a Subscription.\n\n**Required scope:** subscription:create\n\n", "operationId": "post_subscription" } }, "/subscription/{id}": { "get": { "x-required-permissions": [ "subscription:read" ], "tags": [ "Subscription Payment" ], "summary": "Shows subscription payment details", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-subscription-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "Retrieves the subscription payment details\n\n**Required scope:** subscription:read\n\n", "operationId": "get_subscription_id" }, "delete": { "x-required-permissions": [ "subscription:delete" ], "tags": [ "Subscription Payment" ], "summary": "Deletes subscription payment", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "$ref": "#/components/responses/no-content" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "Deletes the subscription\n\n**Required scope:** subscription:delete\n\n", "operationId": "delete_subscription_id" }, "patch": { "x-required-permissions": [ "subscription:update" ], "tags": [ "Subscription Payment" ], "summary": "Updates subscription payment details", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/update-subscription" }, "responses": { "200": { "$ref": "#/components/responses/update-subscription" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "x-codegen-request-body-name": "body", "description": "Updates the subscription payment details\n\n**Required scope:** subscription:update\n\n", "operationId": "patch_subscription_id" } }, "/subscription/{id}/cycle": { "get": { "x-required-permissions": [ "subscription:read" ], "tags": [ "Subscription Payment" ], "summary": "List cycles on a subscription", "description": "Returns the cycles attached to a subscription, ordered from newest to oldest. Use `status[]` to narrow the result set — values are case-insensitive. Pagination is cursor-based: pass the previous response's `metadata.next_cursor` back as `cursor`. An empty `next_cursor` means there are no further pages.\n\n\n**Required scope:** subscription:read\n\n", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the subscription whose cycles you want to list.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of cycles to return. Defaults to `50`, capped at `100`.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50, "example": 10 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque cursor from the previous response's `metadata.next_cursor`. Omit on the first call.", "schema": { "type": "string", "example": "lL_j7ilk7rc" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by one or more statuses. Repeat the parameter for multiple values (e.g. `status[]=pending&status[]=failed`). Case-insensitive.", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "PENDING", "PROCESSING", "WAITING", "SUCCESS", "FAILED", "RETRY", "FAILOVER", "DELETED" ] }, "example": [ "PENDING", "FAILED" ] } } ], "responses": { "200": { "$ref": "#/components/responses/list-cycles" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_subscription_id_cycles" }, "post": { "x-required-permissions": [ "subscription:create" ], "tags": [ "Subscription Payment" ], "summary": "Create a one-off cycle on a subscription", "description": "Triggers an extra capture against an active subscription's saved payment method — useful for billing ad-hoc items like setup fees, add-ons, or upgrades without touching the recurring schedule. The regular cycles keep running unchanged.\n\nSend `capture_at` to schedule the capture for later, or omit it to capture right away. The subscription must be active; a one-off cycle on an inactive subscription is rejected with a `409 Conflict`.\n\n\n**Required scope:** subscription:create\n\n", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the subscription to add the cycle to.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/create-one-time-charge" }, "responses": { "201": { "$ref": "#/components/responses/create-one-time-charge" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "409": { "$ref": "#/components/responses/conflict" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "x-codegen-request-body-name": "body", "operationId": "post_subscription_id_cycles" } }, "/subscription/{id}/cycle/{cycle_id}": { "get": { "x-required-permissions": [ "subscription:read" ], "tags": [ "Subscription Payment" ], "summary": "Retrieve a cycle on a subscription", "description": "Returns a single cycle that belongs to the given subscription. A cycle that doesn't exist — or that belongs to a different account — returns `404 Not Found`.\n\n\n**Required scope:** subscription:read\n\n", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the subscription the cycle belongs to.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cycle_id", "in": "path", "description": "UUID of the cycle to retrieve.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-cycle" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_subscription_id_cycle_id" }, "patch": { "x-required-permissions": [ "subscription:update" ], "tags": [ "Subscription Payment" ], "summary": "Update a cycle on a subscription", "description": "Overrides the charge amount for a single cycle without touching the subscription's recurring schedule or default value. Only `RENEWABLE` cycles in `PENDING` status can be patched — anything else (one-off charges, already-processed cycles, deleted cycles) returns `409 Conflict`.\n\n\n**Required scope:** subscription:update\n\n", "parameters": [ { "name": "id", "in": "path", "description": "UUID of the subscription the cycle belongs to.", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cycle_id", "in": "path", "description": "UUID of the cycle to update.", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/update-cycle" }, "responses": { "200": { "$ref": "#/components/responses/update-cycle" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "409": { "$ref": "#/components/responses/conflict" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "x-codegen-request-body-name": "body", "operationId": "patch_subscription_id_cycle_id" } }, "/void/{id}": { "get": { "x-required-permissions": [ "void:read" ], "tags": [ "Voids" ], "summary": "Get a void", "description": "Returns the details and current status of a void, including the authorisation it cancelled. Use this to track a void's outcome after creation, since processing is asynchronous.\n\n\n**Required scope:** void:read\n\n", "parameters": [ { "name": "id", "in": "path", "description": "The **void's unique identifier** (the `id` returned when the void was created).", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-void-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_void_id" }, "post": { "x-required-permissions": [ "void:create" ], "tags": [ "Voids" ], "summary": "Create a void", "description": "Cancels a payment authorisation before it is captured, releasing the amount held on the card. Works for **single** and **frequent** authorisations.\n\n\n**Required scope:** void:create\n\n", "parameters": [ { "name": "id", "in": "path", "description": "The **token of the operation to cancel** — the single or frequent payment authorisation token.\n", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/create-void" }, "responses": { "201": { "$ref": "#/components/responses/create-void" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "post_void_id" } }, "/report/ledger": { "get": { "x-required-permissions": [ "report:read" ], "tags": [ "Reports" ], "summary": "Report Ledger", "description": "The /reports/ledger endpoint provides access to detailed reports of ledger entries within the Easypay reconciliation system. This endpoint retrieves comprehensive financial data for each transaction recorded in the ledger, including captures, refunds, fees, and other financial operations, and it was designed to help users generate precise and relevant financial reports, aiding in effective account reconciliation and financial management.\n\nBy using this endpoint, clients can obtain an itemized list of all ledger entries, including relevant financial details such as transaction amounts, fees, taxes, and net transferred amounts. The data returned by this endpoint is ideal for accounting, auditing, and financial analysis purposes, as it ensures transparency and accuracy in financial reporting.\n\n**Required scope:** report:read\n\n", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "name": "limit", "in": "query", "schema": { "type": "number", "default": 100 }, "description": "The maximum number of records to return in a single response. This value determines how many items are included in each page of the results. The default value is 100, and the maximum allowable limit is 100. If not specified, the default limit will be used. Adjust the limit to control the size of the response and manage the data load for each request." }, { "$ref": "#/components/parameters/CreatedAt" }, { "name": "transaction_type", "in": "query", "schema": { "type": "string", "enum": [ "CP", "RF", "RV", "FEE", "SP", "MAN", "TB", "OT", "CB", "OP", "TF", "RW", "RR", "RX" ] }, "example": "CP", "description": "**LedgerTransactionType** is a string enum that represents various types of financial transactions recorded in a ledger. Each transaction type is abbreviated with a code and corresponds to a specific financial operation.\n\nThe following are the possible values and their descriptions:\n\n• **CP** (Capture): Represents the capture of funds, typically after a payment authorization. This transaction finalizes a payment and moves the funds from the payer's account to the payee's account.\n\n• **RF** (Refund): Represents a refund transaction where previously captured funds are returned to the payer's account. This transaction often occurs when a customer returns goods or services.\n\n• **RV** (Revert): Indicates a revert transaction that undoes a previously made transaction, often used to correct errors or reverse transactions.\n\n• **SP** (Split Payment): Represents a split payment transaction, where a payment is divided among multiple recipients or for different purposes within the same transaction.\n\n• **FEE** (Fee): Represents a fee transaction, which is a charge applied for a specific service or transaction. This could include service fees, processing fees, or other types of charges.\n\n• **MAN** (Manual Movement): Represents a manual movement of funds, typically entered manually by an administrator or accountant to adjust balances or correct errors.\n\n• **TB** (Bank Transfer): Represents a bank transfer transaction, where funds are moved between different bank accounts. This can be a transfer within the same bank or across different banks.\n\n• **OT** (Out Transfer): Indicates an out transfer transaction, where funds are transferred out of the current ledger or account to another external account or ledger.\n\n• **CB** (Chargeback): Represents a chargeback transaction, typically initiated by the payer's bank to reverse a disputed or fraudulent transaction. This transaction withdraws the funds from the payee's account and returns them to the payer.\n\n• **OP** (Out Payment): Represents an out payment transaction, where funds are paid out from the ledger to an external party or account. This transaction is usually used to settle debts or make external payments.\n\n• **TF** (Transfer Funds): Represents a movement of funds from an Easypay account to a bank account.\n\n• **RW** (Reward): Represents a reward earned by a customer, funded from the account balance. The entry links to the capture that earned the reward through the `details` object.\n\n• **RR** (Reward Redemption): Represents reward credits a customer redeemed against a purchase. The entry links to the capture the credits were redeemed on through the `details` object.\n\n• **RX** (Reward Expiry): Represents the payout of a customer's unused reward credits when they expire. These entries are not linked to any operation, so `details` is not populated.\n\nSee the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for how reward movements work." }, { "name": "transfer_batch", "in": "query", "schema": { "type": "string" }, "example": "584", "description": "Filter by **LedgerTransferBatch**" } ], "responses": { "200": { "$ref": "#/components/responses/report-ledger-response" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_report_ledger" }, "parameters": [] }, "/report/transactions": { "get": { "x-required-permissions": [ "report:read" ], "x-badges": [ { "name": "End of Life", "color": "red" } ], "tags": [ "Reports" ], "deprecated": true, "summary": "Report Transactions", "description": "**This endpoint is end of life and will be removed on 2026-07-31.** Use `/report/ledger` instead.\n\nList your transactions\n\n\n**Required scope:** report:read\n\n", "parameters": [ { "name": "start_date", "in": "query", "description": "Filter from this date (inclusive). The date and time must be provided in UTC, using the format Y-m-d H:i.", "schema": { "type": "string", "format": "Y-m-d H:i" } }, { "name": "end_date", "in": "query", "description": " Filter until this date (inclusive). The date and time must be provided in UTC, using the format Y-m-d H:i.", "schema": { "type": "string", "format": "Y-m-d H:i" } }, { "name": "page", "in": "query", "description": "Page Number", "schema": { "type": "number" } }, { "name": "records_per_page", "in": "query", "description": "Limit records per page (Max: 2500)", "schema": { "type": "number", "default": 20 } } ], "responses": { "200": { "$ref": "#/components/responses/report-transactions-response" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_report_transactions" } }, "/settlement": { "get": { "x-required-permissions": [ "settlement:read" ], "summary": "List settlements", "description": "Returns your settlements, newest first. Each settlement groups the transactions paid out together in a single bank transfer.\n\nNarrow the results with `status[]`, `created_at`, and `updated_at`. Pagination is cursor-based: pass the previous response's `metadata.next_cursor` back as `cursor`. An empty `next_cursor` means there are no further pages.\n\n\n**Required scope:** settlement:read\n\n", "operationId": "get-settlement", "tags": [ "Settlements" ], "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/CreatedAt" }, { "$ref": "#/components/parameters/UpdatedAt" }, { "name": "status[]", "in": "query", "required": false, "description": "Filter by one or more statuses. Repeat the parameter for multiple values (e.g. `status[]=IN_TRANSIT&status[]=SUCCEEDED`). Case-insensitive.", "explode": true, "schema": { "type": "array", "items": { "type": "string", "enum": [ "IN_TRANSIT", "SUCCEEDED", "FAILED" ] }, "example": [ "SUCCEEDED", "FAILED" ] } } ], "responses": { "200": { "$ref": "#/components/responses/settlements" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } } }, "/settlement/{id}": { "get": { "x-required-permissions": [ "settlement:read" ], "summary": "Retrieve a settlement", "description": "Retrieve a single settlement by its ID.\n\n**Required scope:** settlement:read\n\n", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The unique identifier of the settlement to retrieve.", "schema": { "type": "string", "format": "uuid" } } ], "operationId": "get-settlement-id", "tags": [ "Settlements" ], "responses": { "200": { "$ref": "#/components/responses/settlement" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } } }, "/out_payment": { "get": { "x-required-permissions": [ "out_payment:read" ], "tags": [ "Out Payment" ], "summary": "Lists out payments", "description": "Full report with all the out payments from your Account Id\n\n**Required scope:** out_payment:read\n\n", "parameters": [ { "$ref": "#/components/parameters/PageQuery" }, { "$ref": "#/components/parameters/RecordsPerPage" }, { "$ref": "#/components/parameters/OutPaymentMethod" }, { "$ref": "#/components/parameters/OutPaymentType" }, { "$ref": "#/components/parameters/Id" }, { "$ref": "#/components/parameters/Key" }, { "$ref": "#/components/parameters/Value" }, { "$ref": "#/components/parameters/CreatedAt" } ], "responses": { "200": { "$ref": "#/components/responses/list-out-payments" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_out_payment" }, "post": { "x-required-permissions": [ "out_payment:create" ], "tags": [ "Out Payment" ], "summary": "Create out payment", "description": "Get your strong authentication RSA private key from Easypay Backoffice on menu:
Web Services->Configuration API 2.0->Keys.\n\n**Required scope:** out_payment:create\n\n", "security": [ { "accountId": [], "apiKey": [], "signatureAuth": [] } ], "requestBody": { "$ref": "#/components/requestBodies/create-out-payment" }, "responses": { "201": { "$ref": "#/components/responses/create-out-payment" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "x-code-samples": [ { "lang": "PHP", "source": "$body = [\n \"key\" => \"Key Example\",\n \"method\" => \"transfer\",\n \"type\"\t=> \"normal\",\n \"value\"\t=> floatval(17.50),\n \"schedule_at\" =>\"2018-12-31 12:00\",\n \"customer\" => [\n \"name\" => \"Customer Example\",\n \"email\" => \"customer@example.com\",\n \"key\" => \"Key Example\",\n \"phone_indicative\" => \"+351\",\n \"phone\" => \"911234567\",\n \"fiscal_number\" =>\"PT123456789\",\n ],\n \"out_account\" => [\n \"name\" => \"Name Example\",\n \"email\" => \"sdd_email@example.com\",\n \"account_holder\" => \"Account Holder Example\",\n \"key\" => \"SDD Key Example\",\n \"iban\" => \"PT50002700000001234567833\",\n \"phone\" => \"911234567\",\n \"max_num_debits\" =>\"12\",\n ],\n \"timestamp\" => (string)time()\n];\n\n$private = << \"https://api.prod.easypay.pt/2.0/out_payment\",\n CURLOPT_RETURNTRANSFER => true,\n CURLOPT_POST => 1,\n CURLOPT_TIMEOUT => 60,\n CURLOPT_POSTFIELDS => $encoded_body,\n CURLOPT_HTTPHEADER => $headers,\n];\n\n$curl = curl_init();\ncurl_setopt_array($curl, $curlOpts);\n$response_body = curl_exec($curl);\ncurl_close($curl);\n$response = json_decode($response_body, true);\n" } ], "operationId": "post_out_payment" } }, "/out_payment/{id}": { "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "x-required-permissions": [ "out_payment:read" ], "tags": [ "Out Payment" ], "summary": "Shows out payment details", "responses": { "200": { "$ref": "#/components/responses/get-out-payment-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get_out_payment_id", "description": "**Required scope:** out_payment:read\n\n" }, "delete": { "x-required-permissions": [ "out_payment:delete" ], "tags": [ "Out Payment" ], "summary": "Deletes out payment", "description": "If the payment is not processed, it will be cancelled.
Get your strong authentication RSA private key from Easypay Backoffice on menu:
Web Services->Configuration API 2.0->Keys.\n\n**Required scope:** out_payment:delete\n\n", "responses": { "204": { "$ref": "#/components/responses/no-content" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "delete_out_payment_id" } }, "/refund": { "get": { "x-required-permissions": [ "refund:read" ], "summary": "List Refunds", "tags": [ "Refunds" ], "responses": { "200": { "$ref": "#/components/responses/list-refund" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "list-refund", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/CreatedAt" }, { "$ref": "#/components/parameters/UpdatedAt" } ], "description": "Cursor based endpoint to retrieve all account refunds.\n\n**Required scope:** refund:read\n\n" } }, "/refund/{id}": { "post": { "x-required-permissions": [ "refund:create" ], "tags": [ "Refunds" ], "summary": "Refunds a Single Transaction or Frequent Transaction", "description": "Each method has a specific time window during which a refund can be issued. Once this period expires, refunds can no longer be processed via the API for that payment.\n\n### Refund Deadlines by Payment Method\n\n| Payment Method | Maximum Refund Time |\n|------------------------|---------------------|\n| MB WAY | 12 months |\n| Visa & Mastercard | 12 months |\n| Apple Pay | 12 months |\n| Google Pay | 12 months |\n| Samsung Pay | 12 months |\n| MB SPG references | 120 days |\n| Other MB references | No limit |\n| Direct Debit | 180 days |\n\n\n**Required scope:** refund:create\n\n", "parameters": [ { "name": "id", "in": "path", "description": "The capture uuid associated with Single or Frequent Transaction", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/create-refund" }, "responses": { "201": { "$ref": "#/components/responses/create-refund" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "422": { "$ref": "#/components/responses/unprocessable-entity" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } }, "get": { "x-required-permissions": [ "refund:read" ], "tags": [ "Refunds" ], "summary": "Shows refund details", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-refund-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "description": "**Required scope:** refund:read\n\n" } }, "/chargeback": { "get": { "x-required-permissions": [ "chargeback:read" ], "summary": "List chargebacks", "tags": [ "Chargebacks" ], "description": "This endpoint retrieves a list of chargebacks associated with your account. A Chargeback is a mandatory transaction reversal initiated by the consumer's card issuer or bank, usually due to a dispute over a transaction. When a chargeback occurs, the costumer effectively reverses the transaction, resulting in a debit of the disputed amount from the merchant's account. This endpoint allows you to view details of chargebacks, including the reason for the dispute, transaction amount, and status, providing insights into consumer disputes and their impact on your financials.\n\n**Required scope:** chargeback:read\n\n", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/CreatedAt" }, { "name": "capture.id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Filter chargebacks by capture UUID. Returns only chargebacks associated with the specified capture.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" } ], "responses": { "200": { "$ref": "#/components/responses/list-chargeback" }, "403": { "$ref": "#/components/responses/forbidden" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "list-chargeback" } }, "/chargeback/{id}": { "get": { "x-required-permissions": [ "chargeback:read" ], "tags": [ "Chargebacks" ], "summary": "Shows chargeback details", "description": "This endpoint retrieves the details of a specific chargeback by its unique identifier. A Chargeback is a mandatory transaction reversal initiated by the consumer's card issuer or bank, usually due to a dispute over a transaction.\n\n**Required scope:** chargeback:read\n\n", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-chargeback-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "412": { "$ref": "#/components/responses/pre-condition-failed" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } }, "operationId": "get-chargeback-details" } }, "/link": { "post": { "x-required-permissions": [ "link:create" ], "tags": [ "Pay By Link" ], "summary": "Create a payment link", "operationId": "post-link", "security": [ { "accountId": [], "apiKey": [] } ], "requestBody": { "$ref": "#/components/requestBodies/create-link" }, "responses": { "201": { "$ref": "#/components/responses/create-link" }, "400": { "$ref": "#/components/responses/link-bad-request" }, "403": { "$ref": "#/components/responses/link-forbidden" }, "500": { "$ref": "#/components/responses/internal-server-error" }, "501": { "$ref": "#/components/responses/not-implemented" } }, "description": "Generates a link that takes customers straight to a secure and ready-to-pay checkout.\n\n**Required scope:** link:create\n\n" }, "get": { "x-required-permissions": [ "link:read" ], "tags": [ "Pay By Link" ], "summary": "List all payment links", "operationId": "get-link", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "in": "query", "name": "id", "description": "UUID from a created Pay By Link.", "schema": { "type": "string", "format": "uuid" } }, { "schema": { "type": "string", "pattern": "^interval\\(([-+]?[0-9]+)?(?:\\.[0-9]+)?,([-+]?[0-9]+)?(?:\\.[0-9]+)?\\)$", "example": "interval(10.00,50.00)" }, "in": "query", "name": "amount", "description": "Filter Pay By Links by amount, as the range interval(min,max). Leave either bound empty to make the range open-ended, as in interval(10.00,) for everything from €10 up." }, { "schema": { "type": "string" }, "in": "query", "name": "customer_name", "description": "Filter Pay By Links by customer name." }, { "schema": { "type": "string", "format": "email" }, "in": "query", "name": "email", "description": "Filter Pay By Links by customer email." }, { "schema": { "type": "string", "pattern": "^\\+[1-9]\\d{1,14}$", "example": "+351911234567" }, "in": "query", "name": "phone_number", "description": "Filter Pay By Links by customer phone number, in the E.164 pattern." }, { "schema": { "type": "string", "example": "interval(2025-01-01T00:00:00Z,2025-01-31T23:59:59Z)" }, "in": "query", "name": "created_at", "description": "Filter Pay By Links by creation date. Takes either a single RFC3339 timestamp or the range interval(from,to)." }, { "schema": { "type": "string", "example": "interval(2025-01-01T00:00:00Z,2025-01-31T23:59:59Z)" }, "in": "query", "name": "modified_at", "description": "Filter Pay By Links by modification date. Takes either a single RFC3339 timestamp or the range interval(from,to)." }, { "schema": { "type": "string", "example": "interval(2025-01-01T00:00:00Z,2025-01-31T23:59:59Z)" }, "in": "query", "name": "expiration_time", "description": "Filter Pay By Links by expiration date. Takes either a single RFC3339 timestamp or the range interval(from,to)." }, { "schema": { "$ref": "#/components/schemas/payment-methods-response" }, "in": "query", "name": "payment_method[]", "description": "Filter Pay By Links by payment methods." }, { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/status-response" } }, "in": "query", "name": "status[]", "description": "Filter Pay By Links by payment status." } ], "responses": { "200": { "$ref": "#/components/responses/list-link" }, "400": { "$ref": "#/components/responses/link-bad-request" }, "403": { "$ref": "#/components/responses/link-forbidden" }, "409": { "$ref": "#/components/responses/link-conflict" }, "500": { "$ref": "#/components/responses/internal-server-error" } }, "security": [ { "accountId": [], "apiKey": [] } ], "description": "List all the payment links. Results come back a page at a time, with limit capped at 100. Ask for more than that and you get a 409, ask for less than 1 and you get a 400.\n\n**Required scope:** link:read\n\n" } }, "/link/{id}": { "parameters": [ { "schema": { "type": "string", "format": "uuid" }, "name": "id", "in": "path", "required": true, "description": "Unique identifier of the payment link." } ], "get": { "x-required-permissions": [ "link:read" ], "summary": "List payment link details", "tags": [ "Pay By Link" ], "security": [ { "accountId": [], "apiKey": [] } ], "responses": { "200": { "$ref": "#/components/responses/get-link-details" }, "400": { "$ref": "#/components/responses/link-bad-request" }, "403": { "$ref": "#/components/responses/link-forbidden" }, "404": { "$ref": "#/components/responses/link-not-found" }, "500": { "$ref": "#/components/responses/internal-server-error" } }, "operationId": "get-link-id", "description": "Lists a payment link with all the details identified by its unique ID.\n\n**Required scope:** link:read\n\n" }, "delete": { "x-required-permissions": [ "link:delete" ], "summary": "Delete Link", "tags": [ "Pay By Link" ], "security": [ { "accountId": [], "apiKey": [] } ], "responses": { "204": { "$ref": "#/components/responses/no-content" }, "400": { "$ref": "#/components/responses/link-bad-request" }, "403": { "$ref": "#/components/responses/link-forbidden" }, "404": { "$ref": "#/components/responses/link-not-found" }, "409": { "$ref": "#/components/responses/link-conflict" }, "500": { "$ref": "#/components/responses/internal-server-error" } }, "operationId": "delete-link-id", "description": "Deletes a payment link identified by its unique ID. The link moves to the CANCELLED status, which makes it invalid and unusable from then on. This action is irreversible, and a link that is already cancelled or finalized answers with a 409.\n\n**Required scope:** link:delete\n\n" }, "patch": { "x-required-permissions": [ "link:update" ], "tags": [ "Pay By Link" ], "summary": "Update Link", "operationId": "patch-link", "security": [ { "accountId": [], "apiKey": [] } ], "responses": { "200": { "$ref": "#/components/responses/update-link" }, "400": { "$ref": "#/components/responses/link-bad-request" }, "403": { "$ref": "#/components/responses/link-forbidden" }, "404": { "$ref": "#/components/responses/link-not-found" }, "409": { "$ref": "#/components/responses/link-conflict" }, "500": { "$ref": "#/components/responses/internal-server-error" } }, "requestBody": { "$ref": "#/components/requestBodies/update-link" }, "description": "Updates the expiration time of a payment link identified by its unique ID. Pushing the expiration of an already expired link back into the future makes it active again. A link that is cancelled or finalized answers with a 409. The updated link comes back wrapped in a data object.\n\n**Required scope:** link:update\n\n" } }, "/customer/{id}": { "get": { "x-required-permissions": [ "customer:read" ], "tags": [ "Customer" ], "summary": "Show customer details", "description": "Retrieves the customer details, including reward balances.\n\n**Required scope:** customer:read\n\n", "operationId": "get_customer_id", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-customer-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } } }, "/customer/{id}/rewards": { "get": { "x-required-permissions": [ "customer:read" ], "tags": [ "Customer" ], "summary": "List customer reward ledger entries", "description": "Lists reward ledger entries for a customer. Each entry is a single movement — a reward earned (`type: REWARD`), a redemption against a reward (`type: REDEMPTION`), an unused reward swept at its expiry date (`type: REWARD_EXPIRATION`), a reward taken back after the earning capture was refunded or charged back (`type: REWARD_REVERSAL`), or a redemption given back as fresh credit after a refund or chargeback (`type: REWARD_RESTORATION`). Supports filtering by account, type, expiry date, and creation date. Results are sorted by creation date descending (newest first). See the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for the full flow.\n\n**Required scope:** customer:read\n\n", "operationId": "get_customer_id_rewards", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "account_id[]", "in": "query", "required": false, "description": "Filter by reward account identifier. Repeat the parameter to filter by multiple accounts.", "schema": { "type": "string", "format": "uuid", "example": "458b2fc4-3092-4de3-abd4-fe1600c09420" } }, { "name": "type[]", "in": "query", "required": false, "description": "Filter by ledger entry type. Repeat the parameter to filter by multiple types. Note that `REWARD` only matches earned rewards — credits given back after a refund or chargeback are matched by `REWARD_RESTORATION`.", "schema": { "type": "string", "enum": [ "REWARD", "REDEMPTION", "REWARD_EXPIRATION", "REWARD_REVERSAL", "REWARD_RESTORATION" ], "example": "REWARD" } }, { "name": "expiration_date", "in": "query", "required": false, "description": "Filter by expiry date. Accepts a single date `YYYY-MM-DD` (matches that whole day) or an interval `interval(YYYY-MM-DD,YYYY-MM-DD)`. Maximum interval span is 1 year.", "schema": { "type": "string", "example": "interval(2026-01-01,2027-12-31)" } }, { "name": "created_at", "in": "query", "required": false, "description": "Filter by creation datetime in UTC. Accepts a single datetime `YYYY-MM-DD HH:MM` (matches that whole minute) or an interval `interval(YYYY-MM-DD HH:MM,YYYY-MM-DD HH:MM)`. Maximum interval span is 1 year.", "schema": { "type": "string", "example": "interval(2026-01-01 00:00,2026-01-31 23:59)" } } ], "responses": { "200": { "$ref": "#/components/responses/list-customer-rewards" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } } }, "/terminal": { "get": { "x-required-permissions": [ "terminal:read" ], "tags": [ "Terminals" ], "summary": "List terminals", "description": "List all terminals (POS devices) from your account.\n\n**Required scope:** terminal:read\n\n", "operationId": "get_terminal", "parameters": [ { "$ref": "#/components/parameters/Cursor" }, { "$ref": "#/components/parameters/Limit" }, { "name": "name", "in": "query", "description": "Filter by terminal name", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by terminal status", "schema": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] } }, { "name": "model", "in": "query", "description": "Filter by terminal model", "schema": { "type": "string" } } ], "responses": { "200": { "$ref": "#/components/responses/list-terminal" }, "403": { "$ref": "#/components/responses/forbidden" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } }, "post": { "x-required-permissions": [ "terminal:create" ], "tags": [ "Terminals" ], "summary": "Create terminal", "description": "Creates a new terminal (POS device).\n\n**Required scope:** terminal:create\n\n", "operationId": "post_terminal", "parameters": [], "requestBody": { "$ref": "#/components/requestBodies/create-terminal" }, "responses": { "201": { "$ref": "#/components/responses/create-terminal" }, "400": { "$ref": "#/components/responses/bad-request" }, "403": { "$ref": "#/components/responses/forbidden" }, "409": { "$ref": "#/components/responses/conflict" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } } }, "/terminal/{id}": { "get": { "x-required-permissions": [ "terminal:read" ], "tags": [ "Terminals" ], "summary": "Show terminal details", "description": "Retrieves the terminal details.\n\n**Required scope:** terminal:read\n\n", "operationId": "get_terminal_id", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "$ref": "#/components/responses/get-terminal-details" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } }, "delete": { "x-required-permissions": [ "terminal:delete" ], "tags": [ "Terminals" ], "summary": "Delete terminal", "description": "Deletes the terminal.\n\n**Required scope:** terminal:delete\n\n", "operationId": "delete_terminal_id", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "204": { "$ref": "#/components/responses/no-content" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } }, "patch": { "x-required-permissions": [ "terminal:update" ], "tags": [ "Terminals" ], "summary": "Update terminal", "description": "Updates the terminal details.\n\n**Required scope:** terminal:update\n\n", "operationId": "patch_terminal_id", "parameters": [ { "name": "id", "in": "path", "description": "Resource Identification", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "$ref": "#/components/requestBodies/update-terminal" }, "responses": { "200": { "$ref": "#/components/responses/update-terminal" }, "400": { "$ref": "#/components/responses/bad-request" }, "401": { "$ref": "#/components/responses/unauthorized" }, "403": { "$ref": "#/components/responses/forbidden" }, "404": { "$ref": "#/components/responses/not-found" }, "409": { "$ref": "#/components/responses/conflict" }, "429": { "$ref": "#/components/responses/too-many-requests" }, "500": { "$ref": "#/components/responses/internal-error" } } } }, "/system/ping": { "get": { "x-required-permissions": [ "system:read" ], "tags": [ "System" ], "summary": "Check connectivity and authentication", "description": "This endpoint allows you to verify connectivity to the API and validate your authentication credentials.\nA successful response indicates that the API is reachable and your credentials are valid.\n\n\n**Required scope:** system:read\n\n", "responses": { "200": { "$ref": "#/components/responses/ping" }, "403": { "$ref": "#/components/responses/forbidden" }, "500": { "$ref": "#/components/responses/internal-error" } }, "security": [ { "accountId": [], "apiKey": [] } ], "operationId": "ping" } } }, "components": { "securitySchemes": { "accountId": { "type": "apiKey", "description": "This is the identification for the Easypay Client Account", "name": "AccountId", "in": "header" }, "apiKey": { "type": "apiKey", "description": "This is the counter key for the used Account Id", "name": "ApiKey", "in": "header" }, "signatureAuth": { "type": "apiKey", "in": "header", "name": "Signature", "description": "RSA signature Base64 generated with algorithm SHA256 using a account strong authentication private Key on the raw body or id." }, "BasicAuth": { "type": "http", "scheme": "basic" } }, "parameters": { "PageQuery": { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "default": 1, "example": 1 }, "description": "Specifies the page number of the results to retrieve. This parameter is used for paginating through a collection of records, allowing the client to navigate to different pages of the dataset. The value must be a positive integer (e.g., \"1\" for the first page)." }, "RecordsPerPage": { "name": "records_per_page", "in": "query", "required": false, "schema": { "type": "integer", "default": 20, "example": 20 }, "description": "Specifies the number of records to retrieve per page. This parameter is used for controlling the size of each page in a paginated collection of records. The value must be a positive integer, determining how many records are displayed on each page (e.g., \"20\" for 20 records per page)." }, "Type": { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "sale", "authorisation" ], "example": "sale" }, "description": "Filter by type of financial operation being performed. Possible values are \"Sale\" (a complete transaction where funds are immediately captured) or \"Authorisation\" (a temporary hold on funds pending a future capture)." }, "ExpirationTime": { "name": "expiration_time", "in": "query", "required": false, "schema": { "type": "string", "example": "interval(2006-01-02 15:04,2006-01-02 15:04)" }, "description": "Filter records by expiration datetime interval. Format: interval(YYYY-MM-DD HH:MM,YYYY-MM-DD HH:MM)" }, "Method": { "name": "method", "in": "query", "required": false, "schema": { "type": "string", "example": "MB", "enum": [ "CC", "VI", "DD", "MB", "MBW", "AP", "GP" ] }, "description": "Filter by payment method used in the transaction." }, "CustomerKey": { "name": "customer", "in": "query", "required": false, "schema": { "type": "string", "example": "01J32EDWGNX94XMWP8PWB23KBK" }, "description": "A user-defined identifier used to filter the customers. This parameter allows the client to specify a key to retrieve records or transactions that match the provided key. The value is a string and may not be unique, as it is determined by the user." }, "Id": { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "format": "uuid", "example": "bb3e7e60-20f3-4208-9b21-64c635a51f42" }, "description": "Filter by the unique identifier for the resource. Typically formatted as a UUID (Universally Unique Identifier)." }, "Key": { "name": "key", "in": "query", "required": false, "schema": { "type": "string", "example": "01J32EESEC1Z543P7J3PKSF1Q9" }, "description": "A user-defined identifier used to filter the results. This parameter allows the client to specify a key to retrieve records or transactions that match the provided key. The value is a string and may not be unique, as it is determined by the user." }, "Value": { "name": "value", "in": "query", "schema": { "type": "number", "format": "double", "example": 10.32 }, "description": "Filter records by the exact transaction amount." }, "CreatedAt": { "name": "created_at", "in": "query", "required": false, "schema": { "type": "string", "example": "interval(2006-01-02 15:04,2006-01-02 15:04)" }, "description": "Filter records by creation datetime interval in UTC. Maximum allowed range is 30 days. Format: interval(YYYY-MM-DD HH:MM,YYYY-MM-DD HH:MM)." }, "Cursor": { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "The cursor parameter is used for pagination. It specifies the pointer to the start of the next set of results in a sequence of paginated data. Typically, this is a unique identifier of the last item from the previous response. If not provided, the API fetches the first page of results." }, "Limit": { "name": "limit", "in": "query", "required": false, "schema": { "type": "number" }, "description": "The limit parameter is used for pagination. It specifies the maximum number of entries to return in a single page of results. Max 100. " }, "UpdatedAt": { "name": "updated_at", "in": "query", "required": false, "schema": { "type": "string", "example": "interval(2006-01-02 15:04,2006-01-02 15:04)" }, "description": "Filter records by update datetime interval. Maximum range of 30 days. Format: interval(YYYY-MM-DD HH:MM,YYYY-MM-DD HH:MM)" }, "OutPaymentMethod": { "name": "method", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "transfer", "mb" ] }, "description": "Filter by method used in the transaction." }, "OutPaymentType": { "name": "type", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "normal", "instant" ] }, "description": "Filter by type of out payment." } }, "schemas": { "meta": { "title": "Meta", "type": "object", "description": "Metadata object containing pagination and result information for list responses.", "properties": { "page": { "type": "object", "description": "Pagination details", "properties": { "current": { "type": "integer", "description": "Current page number" }, "total": { "type": "integer", "description": "Total number of pages" } }, "example": 1 }, "records": { "type": "object", "description": "Record details", "properties": { "per_page": { "type": "integer", "description": "Number of records per page" }, "total": { "type": "integer", "description": "Total number of records" } }, "example": 20 }, "links": { "type": "object", "description": "Navigation links for pagination", "properties": { "first": { "type": "string", "description": "Link to the first page", "example": "?page=1" }, "prev": { "type": "string", "description": "Link to the previous page", "example": "" }, "next": { "type": "string", "description": "Link to the next page", "example": "?page=2" }, "last": { "type": "string", "description": "Link to the last page", "example": "?page=826" } } } } }, "identifier": { "type": "string", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "customer-response-on-list": { "type": "object", "description": "Customer information as returned in list responses (may contain masked/partial data for privacy)", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] }, "name": { "type": "string", "description": "Customer name (may be partially masked for privacy)", "example": "Jos*** Gom***" }, "email": { "type": "string", "description": "Customer email (may be partially masked for privacy)", "example": "cus***@example.com" }, "phone": { "type": "string", "description": "Customer phone (may be partially masked for privacy)", "example": "911***567" }, "phone_indicative": { "type": "string", "description": "Phone country code", "example": "+351" }, "fiscal_number": { "type": "string", "description": "Fiscal number (may be partially masked for privacy)", "example": "PT123***89" }, "key": { "type": "string", "description": "Customer key", "example": "Key Example" }, "language": { "type": "string", "description": "Customer preferred language", "example": "PT" } } }, "sdd-mandate-response-on-list": { "type": "object", "description": "SDD Mandate information as returned in list responses (contains masked data for privacy)", "properties": { "id": { "type": "string", "description": "Mandate ID", "example": "50389142122" }, "iban": { "type": "string", "description": "IBAN (partially hidden for data security reasons)", "example": "PT500027**XX7833" }, "key": { "type": "string", "description": "Mandate key", "example": "SDD Mandate key" }, "name": { "type": "string", "description": "Account holder name (partially hidden for data security reasons)", "example": "Fre*** DD***" }, "email": { "type": "string", "description": "Account holder email (partially hidden for data security reasons)", "example": "Cam***@yahoo.com" }, "phone": { "type": "string", "description": "Account holder phone (partially hidden for data security reasons)", "example": "911***567" }, "account_holder": { "type": "string", "description": "Account holder name (partially hidden for data security reasons)", "example": "Acc*** Exa***" }, "country_code": { "type": "string", "description": "Country code", "example": "PT" }, "max_num_debits": { "type": "string", "description": "Maximum number of debits allowed", "example": "12" }, "billing_entity": { "type": "string", "description": "Billing entity identifier", "example": "PT16103627" } } }, "response-mbway": { "title": "ResponseMbway", "type": "object", "description": "An object that holds the details specific to an MB WAY payment.", "properties": { "phone": { "type": "string", "description": "The phone number charged for the MB WAY payment, in full E.164 format (leading `+` and country code).", "example": "+351911234567" } } }, "single-all-method-response": { "title": "SingleAllMethodResponse", "type": "object", "properties": { "type": { "enum": [ "CC", "DD", "VI", "MBW", "MB", "AP", "GP", "SW", "IPP" ] }, "status": { "enum": [ "active", "deleted", "pending" ] }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate-response-on-list" }, "mbway": { "allOf": [ { "$ref": "#/components/schemas/response-mbway" } ], "description": "Present when `method.type` is `MBW` and `mbway.phone` was supplied when creating the payment." }, "card_type": { "type": "string", "description": "Indicates the type of credit card used for the payment (e.g., \"Visa\", \"MasterCard\"). This field is only applicable for credit card transactions.", "enum": [ "VISA", "MasterCard" ] }, "last_four": { "type": "string", "description": "The last four digits of the credit card number used for the payment. This field is only applicable for credit card transactions.", "example": "1234" }, "expiration_date": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The URL where the merchant should redirect the user to complete Credit Card Payments. This field is only applicable and available for credit card payment transactions.", "example": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a" }, "alias": { "deprecated": true, "type": "string", "description": "A unique identifier for the user within the MB WAY system, used to identify the user in the MB WAY SDK. This field is only applicable and available for MB WAY transactions." }, "entity": { "type": "string", "description": "The identifier for the Multibanco entity to which the payment should be routed. This field specifies the entity code required for processing the payment through the Multibanco network, ensuring that the payment is directed to the correct recipient.", "minLength": 5, "maxLength": 5, "example": "11683" }, "reference": { "type": "string", "minLength": 9, "maxLength": 9, "example": "665876931", "description": "The unique payment reference number issued for the specific Multibanco entity. This field is used by the end user to make a payment at an ATM or through home banking. It ensures that the payment is correctly attributed to the intended transaction and recipient." }, "iban": { "type": "string", "description": "International Bank Account Number (IBAN) in standard format", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]+$", "example": "PT50002700000001234567833" } } }, "response-multibanco": { "title": "ResponseMultibanco", "type": "object", "description": "An object that holds the details specific to a Multibanco transaction response.", "properties": { "expiration_time": { "type": [ "string", "null" ], "format": "date-time", "description": "When the Multibanco reference expires", "example": "2025-09-28T12:41:08Z" }, "start_time": { "type": "string", "format": "date-time", "description": "When the Multibanco reference becomes valid", "example": "2025-08-26T12:41:09Z" }, "product": { "type": "string", "enum": [ "SPG", "CHECKDIGIT", "FILE" ], "description": "The Multibanco product type used" } } }, "response-terminal": { "title": "ResponseTerminal", "type": "object", "description": "An object that holds the details specific to an IPP terminal response.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the terminal.", "example": "458b2fc4-3092-4de3-abd4-fe1600c09420" } } }, "notification": { "title": "Notification", "description": "Notification settings for payment methods.", "type": "object", "properties": { "customer_method_instructions_email": { "type": "boolean", "description": "Specifies whether an email containing the payment instructions (e.g., Multibanco reference or Virtual IBAN details) should be sent to the customer's email address when the selected payment method is Multibanco or Virtual IBAN.", "example": true } } }, "single": { "type": "object", "x-examples": { "Example 1": { "id": "f5d7148b-aab5-47c6-8cfa-557b0d58ef7b", "type": "sale", "key": "Example Key", "expiration_time": "2024-07-01T21:38:00Z", "customer": { "id": "649e88cf-0b78-4c36-8f99-33f5ebb812a1", "name": "Jos*** Gom***", "email": "cus***@example.com", "phone": "911***567", "fiscal_number": "***", "language": "" }, "method": { "type": "MBW", "status": "active" }, "currency": "EUR", "value": 200, "created_at": "2024-06-30 21:38:31", "payment_status": "pending" } }, "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "type": { "type": "string", "enum": [ "sale", "authorisation" ], "description": "Specifies the type of financial operation being performed. \n\nTYPE | DESCRIPTION |\n---------|----------|\n sale | a complete transaction where funds are immediately captured. |\n authorisation | a temporary hold on funds pending a future capture. |" }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.", "example": "Payment of Invoice Nº 1982652" }, "descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\".", "maxLength": 255, "example": "Payment of Invoice Nº 1982652" }, "expiration_time": { "type": "string", "example": "2024-06-30 21:38:31" }, "customer": { "$ref": "#/components/schemas/customer-response-on-list" }, "method": { "$ref": "#/components/schemas/single-all-method-response" }, "currency": { "type": "string", "description": "ISO 4217 currency code. If not specified, the default currency is set to EUR.", "example": "EUR" }, "value": { "type": "number", "format": "double", "description": "The monetary amount for the transaction. This field specifies the value of the payment in the designated currency. It must be a positive decimal number representing the exact amount to be processed.", "example": 17.5, "minimum": 0.5, "maximum": 999999.99 }, "created_at": { "type": "string", "example": "2024-06-30 21:38:31" }, "payment_status": { "type": "string", "enum": [ "pending", "paid", "authorised", "error", "deleted", "failed", "active" ], "description": "\n| Status | Description |\n|--------|-------------|\n| `pending` | The payment is awaiting processing. |\n| `paid` | The payment has been completed successfully. |\n| `authorised` | The payment has been authorized but not yet captured. |\n| `error` | An error occurred during the payment process. |\n| `deleted` | The payment has been deleted. |\n| `failed` | The payment attempt failed. |\n| `active` | The payment is currently active. |\n| `voided` | The payment has been voided. |\n" }, "multibanco": { "$ref": "#/components/schemas/response-multibanco" }, "terminal": { "allOf": [ { "$ref": "#/components/schemas/response-terminal" } ], "description": "Present when `method.type` is `IPP`." }, "notification": { "$ref": "#/components/schemas/notification" } } }, "error-response-4xx": { "title": "ErrorResponse4xx", "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "array", "items": { "type": "string" }, "description": "An array of human-readable messages included in the response. These messages provide detailed information about the success of the operation or explain the reasons for any failure. This field is always present in the response to ensure clarity and transparency regarding the outcome of the API request." } }, "required": [ "status", "message" ] }, "capture-account": { "title": "CaptureAccount", "type": "object", "description": "An object within the capture request that specifies the details of the account to which the funds should be routed, different from the initially requested account. This ensures that the captured funds are directed to the correct destination as per the specific routing requirements.", "properties": { "id": { "type": "string", "description": "The unique identifier of the account where the captured funds will be routed. This ID corresponds to an existing account in the system and is used to specify the destination for the capture transaction." } }, "required": [ "id" ] }, "capture-split-create": { "type": "object", "description": "Represents a split configuration for dividing transaction funds across multiple accounts. This is useful for marketplace or multi-vendor scenarios where transaction proceeds need to be distributed.", "required": [ "value" ], "properties": { "split_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the split.", "maxLength": 50, "example": "Payment of Invoice Nº 1982652" }, "split_descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\".", "maxLength": 255, "example": "Payment of Invoice Nº 1982652" }, "account": { "type": "object", "description": "The account to receive the split funds", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] } }, "required": [ "id" ] }, "value": { "type": "number", "format": "double", "example": 17.5, "minimum": 0.5, "maximum": 999999.99, "description": "The monetary amount for the transaction. This field specifies the value of the payment in the designated currency. It must be a positive decimal number representing the exact amount to be processed." }, "clearing_period": { "type": "string", "description": "The clearing period must follow the format 1Y, 10W or 30D. Y for Years, W for weeks, D for days. Minimum is 7 days, maximum is 1 year.", "example": "30D" }, "margin_account": { "type": "object", "description": "The account to which the margin value should be routed. This field specifies the destination account for the margin portion of the funds, ensuring that the correct recipient receives the designated margin value.", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] } }, "required": [ "id" ] }, "margin_value": { "type": "number", "format": "double", "description": "The margin amount to be deducted from this split", "example": 0.25 }, "reward": { "type": "object", "description": "Reward credits to generate from this split. The credits are associated with the customer provided at the top level of the payment request and can only be redeemed by that customer. Reward funds expire after the specified period. Only available on the payment methods `CC`, `MBW`, `AP`, `GP`, `SW`, and `IPP`. See the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for the full flow.", "required": [ "account", "value" ], "properties": { "account": { "type": "object", "description": "The account to which the reward credits should be routed.", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] } }, "required": [ "id" ] }, "value": { "type": "number", "format": "double", "description": "The reward amount to be generated from this split.", "example": 1 }, "expiration_date": { "type": "string", "format": "date", "description": "The date until which the reward credits are valid. Defaults to 12 months from the transaction date if not specified.", "example": "2027-04-02" } } } } }, "reward-redemption": { "type": "object", "description": "Apply accumulated reward credits to reduce the payment value. Supports full or partial redemption of available reward balance. Only available on the payment methods `CC`, `MBW`, `AP`, `GP`, `SW`, and `IPP`. See the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for the full flow.", "required": [ "account", "value" ], "properties": { "account": { "type": "object", "description": "The reward account to debit credits from.", "required": [ "id" ], "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] } } }, "value": { "type": "number", "format": "double", "description": "The reward amount to apply. Must not exceed the available reward balance or the payment value.", "example": 2.5, "minimum": 0.01, "maximum": 999999.99 } } }, "create-capture": { "title": "CreateCapture", "type": "object", "description": "The Capture object contains all the necessary information for executing a fund capture action. It defines how and where the funds should be routed upon capturing a transaction. This object is essential for finalizing transactions and ensuring the correct allocation of funds. Object required when the operation type is Sale.", "required": [ "descriptive" ], "properties": { "descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\".", "maxLength": 255, "example": "Payment of Invoice Nº 1982652" }, "transaction_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.", "maxLength": 50, "example": "231d0464-6382-4e39-9a1f-af82ea166868" }, "account": { "$ref": "#/components/schemas/capture-account" }, "capture_date": { "type": "string", "format": "date", "description": "The date when the action should be executed. This field specifies the exact day for capturing the transaction, formatted as \"YYYY-MM-DD\" (e.g., \"2024-06-30\"). It is optional and defaults to the current date if not specified.", "example": "2024-06-30" }, "splits": { "type": "array", "description": "An array of split objects defining how funds should be divided among multiple accounts. Each split specifies an account, an amount, and optional margin details. This is useful for marketplace or multi-vendor scenarios where transaction proceeds need to be distributed across different parties.", "items": { "$ref": "#/components/schemas/capture-split-create" } }, "reward_redemption": { "$ref": "#/components/schemas/reward-redemption" } } }, "customer": { "title": "Customer", "type": "object", "description": "The Customer object contains the necessary details about the customer involved in the transaction. This includes identification information, contact details, and preferences. All fields are optional unless specified otherwise.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer. When provided, it links the transaction to an existing customer record.", "example": "649e88cf-0b78-4c36-8f99-33f5ebb812a1" }, "name": { "type": "string", "description": "Full name of the customer. This is typically displayed on receipts and statements.", "maxLength": 255, "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Customer's email address. Used for sending receipts, notifications, and payment confirmations.", "maxLength": 70, "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "The contact phone number of the customer, excluding the country code indicator (e.g., \"+351\"). This field is used for communication purposes. If the payment method is MB WAY, the phone_number is required and is used to send the MB WAY push notification.", "maxLength": 15, "example": "911234567" }, "phone_indicative": { "type": "string", "description": "The country code indicator for the customer's phone number (e.g., \"351\" for Portugal). This field is used in conjunction with the phone number to ensure proper international dialing and communication.", "maxLength": 5, "example": "+351" }, "fiscal_number": { "type": "string", "description": "Customer's tax identification number or fiscal number. Format may vary by country.", "maxLength": 20, "example": "PT123456789" }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the customer. This can be any string that helps the user uniquely identify the customer in their own system.", "maxLength": 255, "example": "customer Key Example" }, "language": { "type": "string", "description": "Preferred language for customer communications. Uses ISO 639-1 language codes.", "maxLength": 2, "minLength": 2, "enum": [ "PT", "EN", "ES" ], "example": "PT" } } }, "sdd-mandate": { "title": "SddMandate", "type": "object", "description": "The SDD Mandate object contains the necessary fields to create a SEPA Direct Debit mandate. This object ensures that all required information is provided to authorize and process SEPA Direct Debit transactions. Object required when method is Direct Debit.", "required": [ "iban", "name", "email", "phone", "account_holder" ], "properties": { "iban": { "type": "string", "description": "The International Bank Account Number (IBAN) of the debtor's account. This field is used to uniquely identify the debtor's bank account across international borders, ensuring accurate and efficient processing of SEPA Direct Debit transactions. The IBAN is a standardized format that includes the country code, check digits, bank code, and account number.", "maxLength": 34, "example": "PT50002700000001234567833" }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the SDD mandate.", "maxLength": 255, "example": "Sdd mandate Key Example" }, "name": { "type": "string", "description": "Full name of the account holder as it appears on the bank account.", "maxLength": 100, "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Email address of the account holder for mandate-related communications.", "maxLength": 50, "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "Phone number of the account holder without country code.", "maxLength": 20, "example": "911234567" }, "account_holder": { "type": "string", "description": "The name of the person or entity that holds the bank account. This field is used to identify the owner of the bank account involved in the transaction, ensuring that the correct account is credited or debited.", "maxLength": 100, "example": "John Doe" }, "country_code": { "type": "string", "description": "ISO 3166-1 alpha-2 country code of the customer's country.", "pattern": "^[A-Z]{2}$", "example": "PT" }, "max_num_debits": { "type": "string", "description": "Maximum number of debits allowed under this mandate.", "example": "12" }, "billing_entity": { "type": "string", "description": "The entity responsible for billing in the context of the SEPA Direct Debit (SDD) mandate.", "example": "PT16103627" } } }, "response-status": { "title": "ResponseStatus", "type": "string", "enum": [ "ok", "error" ], "example": "ok", "description": "Indicates the overall status of the API response. 'ok' means the request was successful, 'error' indicates there was a problem." }, "response-message": { "title": "ResponseMessage", "type": "array", "items": { "type": "string" }, "example": [ "Your request was successfully created" ], "description": "An array of messages providing details about the response status. These messages give additional context about the operation result." }, "iban": { "title": "IBAN", "type": "string", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]+$", "description": "International Bank Account Number (IBAN) in standard format", "example": "PT50002700000001234567833" }, "sdd-mandate-response-on-detail": { "type": "object", "description": "SDD Mandate information as returned in detail responses", "properties": { "id": { "type": "string", "description": "Mandate ID", "example": "50389142122" }, "iban": { "$ref": "#/components/schemas/iban" }, "key": { "type": "string", "description": "Mandate key", "example": "Sdd mandate Key Example" }, "name": { "type": "string", "description": "Account holder name", "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Account holder email", "example": "john.doe@easypay.pt" }, "phone": { "type": "string", "description": "Account holder phone", "example": "911345678" }, "account_holder": { "type": "string", "description": "Account holder name as registered with bank", "example": "John Doe" }, "country_code": { "type": "string", "description": "Country code", "example": "PT" }, "max_num_debits": { "type": "string", "description": "Maximum number of debits allowed", "example": "12" }, "billing_entity": { "type": "string", "description": "Billing entity identifier", "example": "PT16103627" }, "reference_adc": { "type": "string", "example": "987654321123" } } }, "method-on-post-response": { "type": "object", "description": "Method information returned in POST responses after creating a payment", "properties": { "type": { "type": "string", "description": "The payment method type", "enum": [ "MB", "CC", "DD", "MBW", "VI", "AP", "GP", "SW" ] }, "status": { "type": "string", "description": "The current status of the payment method", "enum": [ "waiting", "pending", "active", "deleted", "success" ] }, "entity": { "type": "string", "description": "Multibanco entity (for Multibanco payments)", "example": "59126" }, "reference": { "type": "string", "description": "Multibanco reference (for Multibanco payments)", "example": "810000618" }, "expiration_date": { "type": "string", "description": "Expiration date of the payment method formatted as MM/DD", "example": "11/28" }, "url": { "type": "string", "description": "Payment URL (for certain payment methods)", "format": "uri" }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate-response-on-detail" }, "mbway": { "allOf": [ { "$ref": "#/components/schemas/response-mbway" } ], "description": "Present when `method.type` is `MBW` and `mbway.phone` was supplied when creating the payment." } } }, "split-reverts": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb", "description": "The unique identifier for the split associated with the capture." }, "value": { "type": "number", "format": "double", "example": 17.5, "minimum": 0.5, "maximum": 999999.99, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"100.00\"). The value must be greater than or equal to 0.5." }, "margin_value": { "type": "number", "format": "double", "example": 0.25, "description": "The monetary amount designated as the margin in a split payment. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"10.00\"). The value must be less than the total value of the split. This specifies the portion of the funds that should be routed to the margin account." } } }, "capture-split-response": { "type": "object", "description": "Represents a split configuration for dividing transaction funds across multiple accounts. This is useful for marketplace or multi-vendor scenarios where transaction proceeds need to be distributed.", "required": [ "id", "value", "status" ], "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] }, "status": { "type": "string", "description": "The current state of this split. `waiting` while the split is queued for processing, `success` once the funds have been routed, `failed` if processing errored, `reverted` once the split has been reverted after a refund or chargeback.", "enum": [ "waiting", "success", "failed", "reverted" ], "example": "success" }, "split_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the split.", "maxLength": 50, "example": "Payment of Invoice Nº 1982652" }, "split_descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\".", "maxLength": 255, "example": "Payment of Invoice Nº 1982652" }, "account": { "type": "object", "description": "The account to receive the split funds", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] } }, "required": [ "id" ] }, "value": { "type": "number", "format": "double", "example": 17.5, "minimum": 0.5, "maximum": 999999.99, "description": "The monetary amount for the transaction. This field specifies the value of the payment in the designated currency. It must be a positive decimal number representing the exact amount to be processed." }, "clearing_date": { "type": "string", "format": "date", "description": "The clearing date refers to the specific date when a financial transaction is finalized and the funds are transferred from one account to another. This is the point at which the payment is officially completed and the amount is debited from the payer’s account and credited to the payee’s account.", "example": "2024-06-30" }, "margin_account": { "type": "object", "description": "The account to which the margin value should be routed. This field specifies the destination account for the margin portion of the funds, ensuring that the correct recipient receives the designated margin value.", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] } }, "required": [ "id" ] }, "margin_value": { "type": "number", "format": "double", "description": "The margin amount to be deducted from this split", "example": 0.25 }, "reward": { "type": "object", "description": "Reward credits generated from this split. The credits are associated with the customer provided at the top level of the payment request and can only be redeemed by that customer. Reward funds expire after the specified period.", "required": [ "account", "value", "expiration_date" ], "properties": { "account": { "type": "object", "description": "The account to which the reward credits are routed.", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] } }, "required": [ "id" ] }, "value": { "type": "number", "format": "double", "description": "The reward amount generated from this split.", "example": 1 }, "expiration_date": { "type": "string", "format": "date", "description": "The date until which the reward credits are valid.", "example": "2027-04-02" } } }, "reverts": { "$ref": "#/components/schemas/split-reverts" } } }, "single-capture-full": { "title": "SingleCaptureFull", "type": "object", "description": "The Capture object contains all the necessary information for executing a fund capture action. It defines how and where the funds should be routed upon capturing a transaction. This object is essential for finalizing transactions and ensuring the correct allocation of funds.", "required": [ "id", "status", "descriptive" ], "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] }, "status": { "type": "string", "enum": [ "delayed", "waiting", "success", "pending", "failed", "refunded" ], "description": "Represents the current state of a payment capture operation. This field provides clear visibility into the capture's progress and outcome:\n\n- **delayed**: The capture has been scheduled for a later time.\n- **waiting**: The capture is queued for processing.\n- **success**: The capture has been completed successfully.\n- **pending**: The capture is currently being processed.\n- **failed**: The capture could not be completed due to an error or issue.\n- **refunded**: The capture has been refunded.\n\nThis field provides a clear indication of the current state of the capture, helping users understand its progress and outcome." }, "descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\".", "maxLength": 255, "example": "Payment of Invoice Nº 1982652" }, "transaction_key": { "type": "string", "example": "Payment of Invoice Nº 1982652" }, "capture_date": { "type": "string", "format": "date", "description": "The date when the action should be executed. This field specifies the exact day for capturing the transaction, formatted as \"YYYY-MM-DD\" (e.g., \"2024-06-30\"). It is optional and defaults to the current date if not specified.", "example": "2024-06-30" }, "account": { "$ref": "#/components/schemas/capture-account" }, "splits": { "type": "array", "items": { "$ref": "#/components/schemas/capture-split-response" } }, "reward_redemption": { "type": "object", "description": "Reward credits redeemed in this payment.", "properties": { "account": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] } }, "required": [ "id" ] }, "value": { "type": "number", "format": "double", "description": "The redeemed reward amount.", "example": 5 } } } } }, "descriptive": { "title": "Descriptive", "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\".", "maxLength": 255, "example": "Payment of Invoice Nº 1982652" }, "value": { "title": "Value", "type": "number", "format": "double", "example": 17.5, "minimum": 0.5, "maximum": 999999.99, "description": "The monetary amount for the transaction. This field specifies the value of the payment in the designated currency. It must be a positive decimal number representing the exact amount to be processed." }, "currency": { "title": "Currency", "description": "ISO 4217 currency code. If not specified, the default currency is set to EUR.", "type": "string", "enum": [ "EUR" ], "example": "EUR" }, "single-detail-method-response": { "title": "SingleDetailMethodResponse", "type": "object", "properties": { "type": { "enum": [ "CC", "DD", "VI", "MBW", "MB", "AP", "GP", "SW", "IPP" ] }, "status": { "enum": [ "active", "deleted", "pending" ] }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate-response-on-detail" }, "mbway": { "allOf": [ { "$ref": "#/components/schemas/response-mbway" } ], "description": "Present when `method.type` is `MBW` and `mbway.phone` was supplied when creating the payment." }, "card_type": { "type": "string", "description": "Indicates the type of credit card used for the payment (e.g., \"Visa\", \"MasterCard\"). This field is only applicable for credit card transactions.", "enum": [ "VISA", "MasterCard" ] }, "last_four": { "type": "string", "description": "The last four digits of the credit card number used for the payment. This field is only applicable for credit card transactions.", "example": "1234" }, "expiration_date": { "type": "string" }, "url": { "type": "string", "format": "uri", "description": "The URL where the merchant should redirect the user to complete Credit Card Payments. This field is only applicable and available for credit card payment transactions.", "example": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a" }, "alias": { "deprecated": true, "type": "string", "description": "A unique identifier for the user within the MB WAY system, used to identify the user in the MB WAY SDK. This field is only applicable and available for MB WAY transactions." }, "entity": { "type": "string", "description": "The identifier for the Multibanco entity to which the payment should be routed. This field specifies the entity code required for processing the payment through the Multibanco network, ensuring that the payment is directed to the correct recipient.", "minLength": 5, "maxLength": 5, "example": "11683" }, "reference": { "type": "string", "minLength": 9, "maxLength": 9, "example": "665876931", "description": "The unique payment reference number issued for the specific Multibanco entity. This field is used by the end user to make a payment at an ATM or through home banking. It ensures that the payment is correctly attributed to the intended transaction and recipient." }, "iban": { "$ref": "#/components/schemas/iban" } } }, "payment-transactions": { "type": "object", "description": "Transaction details for a payment, including values and transfer information", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the transaction", "example": "4fb3ac57-c7fe-4157-aeb7-4362ae24deec" }, "key": { "type": "string", "description": "Merchant identification key", "example": "Merchant identification key" }, "created_at": { "type": "string", "format": "date-time", "description": "When the transaction was created", "example": "2025-05-30T17:21:46Z" }, "date": { "type": "string", "format": "date-time", "description": "Transaction date", "example": "2025-05-30T17:21:47Z" }, "values": { "type": "object", "description": "Transaction value breakdown", "properties": { "requested": { "type": "number", "format": "double", "description": "Requested amount", "example": 12.55 }, "paid": { "type": "number", "format": "double", "description": "Amount actually paid", "example": 12.55 }, "fixed_fee": { "type": "number", "format": "double", "description": "Fixed fee charged", "example": 0.07 }, "variable_fee": { "type": "number", "format": "double", "description": "Variable fee charged", "example": 0.09 }, "tax": { "type": "number", "format": "double", "description": "Tax amount", "example": 0.04 }, "transfer": { "type": "number", "format": "double", "description": "Amount transferred to merchant", "example": 12.35 } } }, "transfer_date": { "type": "string", "format": "date-time", "description": "When the transfer occurred", "example": "2025-06-02T00:00:00Z" }, "transfer_batch": { "type": "string", "description": "Transfer batch identifier" }, "method": { "type": "string", "description": "Payment method used", "example": "mbw" }, "document_number": { "type": "string", "description": "Document number for the transaction", "example": "MARCEL0208220628294020250530172147" }, "descriptive": { "type": "string", "description": "Transaction description", "example": "Descriptive Josefa" } } }, "single-payment-status": { "title": "SinglePaymentStatus", "type": "string", "enum": [ "pending", "paid", "authorised", "error", "deleted", "failed", "active" ], "description": "Indicates the current status of the payment. Possible values include:\n\n \"pending\": The payment is awaiting processing.\n \"paid\": The payment has been completed successfully.\n \"authorised\": The payment has been authorized but not yet captured.\n \"error\": An error occurred during the payment process.\n \"deleted\": The payment has been deleted.\n \"failed\": The payment attempt failed.\n \"active\": The payment is currently active.\n \"voided\": The payment has been voided.", "example": "paid" }, "key": { "title": "Key", "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.", "example": "01J1PKR2RPHJNJQGFWGDYXY0KM", "maxLength": 255 }, "updatable-customer": { "type": "object", "description": "The Customer object contains detailed information about the customer involved in the transaction. Used for update operations where all fields are optional.", "properties": { "name": { "type": "string", "maxLength": 255, "description": "The full name of the customer. This field is used to identify the customer and personalize interactions.", "example": "Jonh Doe" }, "email": { "type": "string", "format": "email", "description": "The email address of the customer. Used for communication purposes, including sending transaction confirmations and receipts.", "maxLength": 70, "example": "customer@example.com" }, "phone": { "type": "string", "description": "The contact phone number of the customer, excluding the country code indicator. Used for communication purposes.", "maxLength": 15, "example": "962496235" }, "phone_indicative": { "type": "string", "description": "The country code indicator for the customer's phone number (e.g., \"351\" for Portugal).", "maxLength": 5, "example": "351", "default": 351 }, "fiscal_number": { "type": "string", "description": "The customer's fiscal number (prefixed by the country code).", "maxLength": 20, "example": "PT277712580" }, "key": { "$ref": "#/components/schemas/key" }, "language": { "type": "string", "default": "PT", "example": "PT", "minLength": 2, "maxLength": 2, "description": "The language preference of the customer, specified in the ISO 639-1 Alpha-2 format (e.g., \"EN\" for English, \"PT\" for Portuguese)." } } }, "updatable-sdd-mandate": { "description": "The SDD Mandate object contains the necessary fields to update a SEPA Direct Debit mandate. All fields are optional for update operations.", "type": "object", "properties": { "iban": { "type": "string", "description": "The International Bank Account Number (IBAN) of the debtor's account. This field is used to uniquely identify the debtor's bank account across international borders, ensuring accurate and efficient processing of SEPA Direct Debit transactions. The IBAN is a standardized format that includes the country code, check digits, bank code, and account number.", "maxLength": 34, "example": "PT50002700000001234567833" }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the SDD mandate.", "maxLength": 255, "example": "Sdd mandate Key Example" }, "name": { "type": "string", "description": "Full name of the account holder as it appears on the bank account.", "maxLength": 100, "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Email address of the account holder for mandate-related communications.", "maxLength": 50, "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "Phone number of the account holder without country code.", "maxLength": 20, "example": "911234567" }, "account_holder": { "type": "string", "description": "The name of the person or entity that holds the bank account. This field is used to identify the owner of the bank account involved in the transaction, ensuring that the correct account is credited or debited.", "maxLength": 100, "example": "John Doe" } } }, "single-edit-method-response": { "title": "SingleEditMethodResponse", "type": "object", "properties": { "type": { "enum": [ "CC", "DD", "VI", "MBW", "MB", "AP", "GP", "SW" ] }, "status": { "enum": [ "active", "deleted", "pending" ] }, "entity": { "type": "string", "description": "The identifier for the Multibanco entity to which the payment should be routed. This field specifies the entity code required for processing the payment through the Multibanco network, ensuring that the payment is directed to the correct recipient.", "example": "11683" }, "reference": { "type": "string", "example": "665876931", "description": "The unique payment reference number issued for the specific Multibanco entity. This field is used by the end user to make a payment at an ATM or through home banking. It ensures that the payment is correctly attributed to the intended transaction and recipient." }, "url": { "type": "string", "format": "uri", "description": "The URL where the merchant should redirect the user to complete Credit Card Payments. This field is only applicable and available for credit card payment transactions.", "example": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a" } } }, "frequent-method-response": { "title": "Frequent Payment Method Response", "description": "Method details for frequent payment responses", "type": "object", "properties": { "type": { "type": "string", "enum": [ "CC", "DD", "MBW", "MB", "VI" ], "description": "Payment method type", "example": "MBW" }, "status": { "type": "string", "enum": [ "active", "inactive", "waiting", "pending", "deleted", "success" ], "description": "Current status of the payment method", "example": "active" }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate" }, "card_type": { "type": "string", "description": "Indicates the type of credit card used for the payment (e.g., \"Visa\", \"MasterCard\"). This field is only applicable for credit card transactions.", "enum": [ "VISA", "MasterCard" ], "example": "VISA" }, "last_four": { "type": "string", "description": "The last four digits of the credit card number used for the payment. This field is only applicable for credit card transactions.", "example": "0000" }, "expiration_date": { "type": "string", "description": "Credit card expiration date in MM/YY format", "example": "04/25" }, "url": { "type": "string", "format": "uri", "description": "The URL where the merchant should redirect the user to complete Credit Card Payments. This field is only applicable and available for credit card payment transactions.", "example": "https://cc.test.easypay.pt/start/ac1913a3-fd78-4822-8394-0a14f4169247" }, "alias": { "type": "string", "description": "A unique identifier for the user within the MB WAY system, used to identify the user in the MB WAY SDK. This field is only applicable and available for MB WAY transactions.", "example": "79cb81f626924c71926cdb36a03a0590", "deprecated": true }, "entity": { "type": "string", "description": "The identifier for the Multibanco entity to which the payment should be routed. This field specifies the entity code required for processing the payment through the Multibanco network, ensuring that the payment is directed to the correct recipient.", "minLength": 5, "maxLength": 5, "example": "11683" }, "reference": { "type": "string", "minLength": 9, "maxLength": 9, "example": "665876931", "description": "The unique payment reference number issued for the specific Multibanco entity. This field is used by the end user to make a payment at an ATM or through home banking. It ensures that the payment is correctly attributed to the intended transaction and recipient." }, "iban": { "type": "string", "description": "International Bank Account Number (IBAN) in standard format", "pattern": "^[A-Z]{2}[0-9]{2}[A-Z0-9]+$", "example": "PT50002700000001234567833" } } }, "frequent": { "title": "Frequent", "type": "object", "examples": [ { "id": "ef66f227-2318-4079-8793-ce0fbf651d5c", "key": "Default Key", "expiration_time": "2024-07-01T15:15:00Z", "customer": { "id": "df0eac33-a487-4338-96cb-5dea17bdb469", "name": "Cus*** Exa***", "email": "cus***@example.com", "phone": "911***567", "phone_indicative": "351", "fiscal_number": "PT123***89", "key": "Key Example", "language": "PT" }, "method": { "type": "MBW", "status": "active", "alias": "79cb81f626924c71926cdb36a03a0590" }, "currency": "EUR", "max_value": 20, "min_value": 2, "unlimited_payments": false, "created_at": "2024-06-30 15:15:05" }, { "id": "545eaf84-2644-4bc1-83d5-a1a6845b85d2", "key": "Default Key", "expiration_time": "2024-07-01T15:15:00Z", "customer": { "id": "74fdaf37-e045-4d01-a3aa-71eb198bf3db", "name": "Cus*** Exa***", "email": "cus***@example.com", "phone": "911***567", "phone_indicative": "351", "fiscal_number": "PT123***89", "key": "Key Example", "language": "PT" }, "method": { "type": "DD", "status": "active", "sdd_mandate": { "id": "50355335333", "billing_entity": "PT16103627", "iban": "PT500027**XX7833", "key": "Sdd Mandate key", "name": "Fre*** DD***", "email": "cus***@example.com", "phone": "911***567", "account_holder": "Acc*** Exa***", "country_code": "PT", "max_num_debits": "0" } }, "currency": "EUR", "max_value": 10, "min_value": 2, "unlimited_payments": false, "created_at": "2024-06-30 15:15:06" } ], "required": [ "id", "max_value", "min_value", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "title": "Identifier", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.", "example": "Default Key" }, "expiration_time": { "type": "string", "description": "Expiration date and time for the frequent payment in ISO 8601 format", "example": "2024-07-01T15:15:00Z" }, "customer": { "$ref": "#/components/schemas/customer" }, "method": { "$ref": "#/components/schemas/frequent-method-response" }, "currency": { "type": "string", "enum": [ "EUR" ], "description": "The currency code in ISO 4217 format (e.g., \"EUR\" for Euro). This field specifies the type of currency used in financial operation.", "example": "EUR" }, "max_value": { "type": "number", "description": "Maximum value allowed for transactions", "example": 20.55 }, "min_value": { "type": "number", "description": "Minimum value allowed for transactions", "example": 2.55 }, "unlimited_payments": { "type": "boolean", "description": "Whether transactions are unlimited, max or min value will be refreshed on each payment", "example": false }, "created_at": { "type": "string", "description": "Date when payment was created.", "example": "2017-12-12 16:05:02" } } }, "frequent-with-transactions": { "title": "Frequent Payment with Transactions", "description": "Frequent payment schema that includes transaction history", "allOf": [ { "$ref": "#/components/schemas/frequent" }, { "type": "object", "properties": { "transactions": { "type": "array", "description": "Array of payment transactions associated with this frequent payment", "items": { "type": "object", "description": "Transaction details for a payment, including values and transfer information", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the transaction", "example": "4fb3ac57-c7fe-4157-aeb7-4362ae24deec" }, "key": { "type": "string", "description": "Merchant identification key", "example": "Merchant identification key" }, "created_at": { "type": "string", "format": "date-time", "description": "When the transaction was created", "example": "2025-05-30T17:21:46Z" }, "date": { "type": "string", "format": "date-time", "description": "Transaction date", "example": "2025-05-30T17:21:47Z" }, "values": { "type": "object", "description": "Transaction value breakdown", "properties": { "requested": { "type": "number", "format": "double", "description": "Requested amount", "example": 12.55 }, "paid": { "type": "number", "format": "double", "description": "Amount actually paid", "example": 12.55 }, "fixed_fee": { "type": "number", "format": "double", "description": "Fixed fee charged", "example": 0.07 }, "variable_fee": { "type": "number", "format": "double", "description": "Variable fee charged", "example": 0.09 }, "tax": { "type": "number", "format": "double", "description": "Tax amount", "example": 0.04 }, "transfer": { "type": "number", "format": "double", "description": "Amount transferred to merchant", "example": 12.35 } } }, "transfer_date": { "type": "string", "format": "date-time", "description": "When the transfer occurred", "example": "2025-06-02T00:00:00Z" }, "transfer_batch": { "type": "string", "description": "Transfer batch identifier" }, "method": { "type": "string", "description": "The payment method used to identify the payment in legacy.", "example": "MBW", "deprecated": true }, "document_number": { "type": "string", "description": "Document number for the transaction", "example": "MARCEL0208220628294020250530172147" }, "descriptive": { "type": "string", "description": "Transaction description", "example": "Descriptive Josefa" } } } } } } ] }, "config-details": { "type": "object", "x-examples": { "Default Config": { "generic": "https://www.easypay.pt/generic", "authorisation": "https://www.easypay.pt/authorisation", "transaction": "https://www.easypay.pt/transaction", "visa_fwd": "https://www.easypay.pt/visa_fwd", "visa_detail": "https://www.easypay.pt/visa_detail", "account": "b2080452-bad1-4455-8ae7-9f5ea552a274", "client_id": "EASYP030002", "payment_methods": [ "MB" ] } }, "properties": { "generic": { "type": "string", "description": "URL for generic notification." }, "authorisation": { "type": "string", "description": "URL for authorisation notification." }, "transaction": { "type": "string", "description": "URL for transaction notification." }, "visa_fwd": { "type": "string", "description": "URL for redirect clients on credit card forward." }, "visa_detail": { "type": "string", "description": "URL for credit card payment detail." }, "account": { "type": "string", "format": "uuid", "description": "The UUID of the related account.", "example": "b2080452-bad1-4455-8ae7-9f5ea552a274" }, "client_id": { "type": "string", "description": "The id of the related client.", "example": "EASYP030002" }, "payment_methods": { "type": "array", "description": "The available payments for the related account.", "items": { "type": "string" } } } }, "metadata-cursor": { "title": "Metadata", "type": "object", "required": [ "next_cursor", "count" ], "description": "An object containing additional information about the response. It includes details that help manage and navigate the retrieved data.", "properties": { "next_cursor": { "type": "string", "example": "lL_j7ilk7rc", "description": "Provides the cursor for the next set of records. This value should be used as the cursor parameter in subsequent requests to continue paginating through the data. If the cursor is an empty string or null, it indicates that there are no more results. To retrieve all available results, continue making subsequent requests until next_cursor is empty or null." }, "count": { "type": "number", "example": 10, "description": "The total number of records in the current response. This field indicates the number of items returned in the current set of results." } } }, "capture-get-list-response": { "title": "CaptureGetListResponse", "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/metadata-cursor" }, "data": { "type": "array", "description": "The Capture object contains all the necessary information for executing a fund capture action. It defines how and where the funds should be routed upon capturing a transaction. This object is essential for finalizing transactions and ensuring the correct allocation of funds.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "status": { "description": "Indicates the current status of the capture. Possible values include:\n- delayed: The capture attempt is scheduled for a future date and does not require further user interaction due to prior consent (e.g., authorization or frequent).\n- waiting: The payment instruction has been given, but the chosen payment method requires confirmation from an external entity before the status of the operation is finalized.\n- pending: The capture is pending user completion.\n- success: The capture has been completed successfully.\n- failed: The capture could not be completed due to an error or issue.\n- refunded: The capture has been refunded.\n\nThis field provides a clear indication of the current state of the capture, helping users understand its progress and outcome.\n", "enum": [ "delayed", "waiting", "success", "pending", "failed", "refunded" ] }, "descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\"." }, "transaction_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system." }, "capture_date": { "type": "string", "format": "date", "description": "The date when the action should be executed. This field specifies the exact day for capturing the transaction, formatted as \"YYYY-MM-DD\" (e.g., \"2024-06-30\"). It is optional and defaults to the current date if not specified." }, "account": { "type": "object", "description": "An object within the capture request that specifies the details of the account to which the funds should be routed, different from the initially requested account. This ensures that the captured funds are directed to the correct destination as per the specific routing requirements.", "properties": { "id": { "type": "string", "format": "uuid", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "splits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "split_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system." }, "split_descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\"" }, "account": { "type": "object", "description": "The account to which the funds should be routed. This field is used to specify the destination account for the split payment, ensuring that the correct recipient receives their designated portion of the funds.", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced. " } } }, "value": { "type": "number", "format": "double", "example": 10.49, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"100.00\"). The value must be greater than or equal to 0.5" }, "clearing_date": { "type": "string", "format": "date", "description": "The clearing date refers to the specific date when a financial transaction is finalized and the funds are transferred from one account to another. This is the point at which the payment is officially completed and the amount is debited from the payer's account and credited to the payee's account." }, "clearing_period": { "type": "string", "description": "The clearing period must follow the format 1Y, 10W or 30D. Y for Years, W for weeks, D for days. Minimum is 7 days, maximum is 1 year." }, "margin_account": { "type": "object", "description": "The account to which the margin value should be routed. This field specifies the destination account for the margin portion of the funds, ensuring that the correct recipient receives the designated margin value. ", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced. ", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" } } }, "margin_value": { "type": "number", "description": "The monetary amount designated as the margin in a split payment. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"10.00\"). The value must be less than the total value of the split. This specifies the portion of the funds that should be routed to the margin account. ", "format": "double", "example": 12.6 }, "status": { "enum": [ "waiting", "success", "failed", "reverted" ], "description": "The status of the Split. `waiting` while the split is queued for processing, `success` once the funds have been routed, `failed` if processing errored, `reverted` once the split has been reverted after a refund or chargeback." }, "reverts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced. ", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "value": { "type": "number", "format": "double", "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"100.00\"). The value must be greater than or equal to 0.5. " }, "margin_value": { "type": "string", "description": "The monetary amount designated as the margin in a split payment. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"10.00\"). The value must be less than the total value of the split. This specifies the portion of the funds that should be routed to the margin account." } } } } } } }, "payment_id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced. ", "format": "uuid" }, "payment_type": { "description": "Specifies the type of payment processed. Possible values include:\n- Single: A one-time payment transaction.\n- Frequent: A payment that occurs regularly but is not part of a subscription (e.g., recurring manual payments).\n- Subscription: A recurring payment that is part of a subscription plan, automatically processed at regular intervals. This field helps to categorize and manage different payment methods based on their frequency and nature.\n", "enum": [ "single", "frequent", "subscription" ] }, "value": { "type": "number", "format": "double", "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"100.00\"). The value must be greater than or equal to 0.5. ", "example": 15.32 }, "force_3ds": { "type": "boolean", "description": "A boolean field indicating whether to enforce 3D Secure (3DS) authentication for the transaction. If set to true, 3DS authentication will be required, adding an additional layer of security by verifying the cardholder's identity during the transaction process. If set to false, 3DS authentication will not be enforced. This field helps enhance security and reduce fraud in online payments. " }, "created_at": { "type": "string", "format": "date", "description": "The timestamp indicating when the resource was created. It is formatted as \"YYYY-MM-DD HH:MM\". " }, "updated_at": { "type": "string", "format": "date", "description": "The timestamp indicating when the resource was created. It is formatted as \"YYYY-MM-DD HH:MM\". " }, "error": { "type": "object", "description": "Represents the reason why an operation failed. It includes a human-readable message describing the issue, which can help diagnose and resolve the failure. ", "properties": { "message": { "type": "string", "description": "A human-readable description of the error. " } } } } } } } }, "capture-get-by-id-response": { "title": "CaptureGetByIdResponse", "type": "object", "properties": { "transaction_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system." }, "capture_date": { "type": "string", "example": "2025-07-10", "description": "The date when the action should be executed. This field specifies the exact day for capturing the transaction, formatted as \"YYYY-MM-DD\" (e.g., \"2024-06-30\"). It is optional and defaults to the current date if not specified." }, "account": { "type": "object", "description": "An object within the capture request that specifies the details of the account to which the funds should be routed, different from the initially requested account. This ensures that the captured funds are directed to the correct destination as per the specific routing requirements.", "properties": { "id": { "type": "string", "format": "uuid", "example": "c0151524-79e6-437a-a549-2ddd7c95e245", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\". " }, "value": { "type": "number", "format": "double", "example": 38.98, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"100.00\"). The value must be greater than or equal to 0.5. " }, "status": { "description": "Indicates the current status of the capture. Possible values include:\n- delayed: The capture attempt is scheduled for a future date and does not require further user interaction due to prior consent (e.g., authorization or frequent).\n- waiting: The payment instruction has been given, but the chosen payment method requires confirmation from an external entity before the status of the operation is finalized.\n- pending: The capture is pending user completion.\n- success: The capture has been completed successfully.\n- failed: The capture could not be completed due to an error or issue.\n- refunded: The capture has been refunded.\n\nThis field provides a clear indication of the current state of the capture, helping users understand its progress and outcome.\n", "enum": [ "delayed", "waiting", "success", "pending", "failed", "refunded" ] }, "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "payment_type": { "description": "Specifies the type of payment processed. Possible values include:\n- Single: A one-time payment transaction.\n- Frequent: A payment that occurs regularly but is not part of a subscription (e.g., recurring manual payments).\n- Subscription: A recurring payment that is part of a subscription plan, automatically processed at regular intervals. This field helps to categorize and manage different payment methods based on their frequency and nature.\n", "enum": [ "single", "frequent", "subscription" ] }, "payment_id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced. " }, "force_3ds": { "type": "boolean", "description": "A boolean field indicating whether to enforce 3D Secure (3DS) authentication for the transaction. If set to true, 3DS authentication will be required, adding an additional layer of security by verifying the cardholder's identity during the transaction process. If set to false, 3DS authentication will not be enforced. This field helps enhance security and reduce fraud in online payments. " }, "refunds": { "type": "array", "description": "The refunds issued against this capture. Each Refund object contains information about a processed refund. For payment methods that do not support direct refunds, additional fields are present to facilitate a fallback to a bank transfer.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "format": "uuid", "example": "c0151524-79e6-437a-a549-2ddd7c95e245" }, "status": { "description": "Indicates the current status of the refund. Possible values include:\n- waiting: The payment instruction has been given, but the chosen payment method requires confirmation from an external entity before the status of the operation is finalized.\n- pending: This is the initial state, and it means that the refund is queued.\n- success: The refund has been completed successfully.\n- failed: The refund could not be completed due to an error or issue. This field provides a clear indication of the current state of the refund, helping users understand its progress and outcome.\n", "enum": [ "waiting", "pending", "success", "failed" ] }, "transaction_key": { "type": "string", "description": "Your internal key identifying this refund.", "example": "example key" }, "value": { "type": "number", "format": "double", "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"100.00\"). The value must be greater than or equal to 0.5." }, "iban": { "type": "string", "description": "(Required for fallback): The International Bank Account Number of the account to which the refund will be sent. This field is used to uniquely identify the recipient's bank account across international borders." }, "email": { "type": "string", "description": "(Required for fallback): The email address of the account holder. This field is used for communication purposes, including sending notifications about the refund stat." }, "phone": { "type": "string", "description": "(Required for fallback): The contact phone number of the account holder, including the country code indicator (e.g., \"+351\"). This field is used for communication purposes, such as contacting the account holder for verification." }, "account_holder": { "type": "string", "description": "Bank account holder name." } } } }, "splits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "format": "uuid", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "split_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.", "example": "Example Key" }, "split_descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\"", "example": "Descriptive Example" }, "account": { "type": "object", "description": "The account to which the funds should be routed. This field is used to specify the destination account for the split payment, ensuring that the correct recipient receives their designated portion of the funds.", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced. " } } }, "value": { "type": "number", "format": "double", "example": 10.89, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"100.00\"). The value must be greater than or equal to 0.5" }, "clearing_date": { "type": "string", "format": "date", "description": "The clearing date refers to the specific date when a financial transaction is finalized and the funds are transferred from one account to another. This is the point at which the payment is officially completed and the amount is debited from the payer's account and credited to the payee's account." }, "clearing_period": { "type": "string", "description": "The clearing period must follow the format 1Y, 10W or 30D. Y for Years, W for weeks, D for days. Minimum is 7 days, maximum is 1 year." }, "margin_account": { "type": "object", "description": "The account to which the margin value should be routed. This field specifies the destination account for the margin portion of the funds, ensuring that the correct recipient receives the designated margin value. ", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced. " } } }, "margin_value": { "type": "number", "format": "double", "description": "The monetary amount designated as the margin in a split payment. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"10.00\"). The value must be less than the total value of the split. This specifies the portion of the funds that should be routed to the margin account. ", "example": 10 }, "status": { "description": "The status of the Split. `waiting` while the split is queued for processing, `success` once the funds have been routed, `failed` if processing errored, `reverted` once the split has been reverted after a refund or chargeback.", "enum": [ "waiting", "success", "failed", "reverted" ] }, "reward": { "type": "object", "description": "Reward credits generated from this split. The credits are associated with the customer provided at the top level of the payment request and can only be redeemed by that customer. Present only when the split carries a reward.", "properties": { "account": { "type": "object", "description": "The account to which the reward credits are routed.", "properties": { "id": { "type": "string", "format": "uuid", "example": "c0151524-79e6-437a-a549-2ddd7c95e245", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "value": { "type": "number", "format": "double", "description": "The reward amount generated from this split.", "example": 1 }, "expiration_date": { "type": "string", "format": "date", "description": "The date until which the reward credits are valid. Present only when the reward has an expiration date.", "example": "2027-04-02" } } }, "reverts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced. ", "format": "uuid" }, "value": { "type": "number", "format": "double", "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"100.00\"). The value must be greater than or equal to 0.5. " }, "margin_value": { "type": "number", "description": "The monetary amount designated as the margin in a split payment. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"10.00\"). The value must be less than the total value of the split. This specifies the portion of the funds that should be routed to the margin account.", "format": "double" } } } } } } }, "reward_redemption": { "type": "object", "description": "Reward credits redeemed in this capture. Present only when the capture redeemed reward credits. See the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for the full flow.", "properties": { "account": { "type": "object", "description": "The reward account the credits were debited from.", "properties": { "id": { "type": "string", "format": "uuid", "example": "c0151524-79e6-437a-a549-2ddd7c95e245", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "value": { "type": "number", "format": "double", "description": "The redeemed reward amount.", "example": 2.5 } } }, "error": { "type": "object", "description": "Represents the reason why an operation failed. It includes a human-readable message describing the issue, which can help diagnose and resolve the failure. ", "properties": { "message": { "type": "string", "description": "Represents the reason why an operation failed. It includes a human-readable message describing the issue, which can help diagnose and resolve the failure. " } } } } }, "capture-post-request": { "title": "CapturePostRequest", "type": "object", "properties": { "transaction_key": { "type": "string", "description": "Your internal key identifying this capture", "maxLength": 50, "example": "key example" }, "capture_date": { "type": "string", "format": "date", "example": "2022-11-11", "description": "The date when the action should be executed. This field specifies the exact day for capturing the transaction, formatted as \"YYYY-MM-DD\" (e.g., \"2024-06-30\"). It is optional and defaults to the current date if not specified." }, "account": { "type": "object", "description": "For multi-account clients.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The uuid of the account." } } }, "splits": { "type": "array", "description": "Used in split payments.", "items": { "$ref": "#/components/schemas/capture-split-create" } }, "reward_redemption": { "$ref": "#/components/schemas/reward-redemption" }, "force_3ds": { "type": "boolean", "description": "Whether or not you want to force the 3DS authentication on Credit Cards (used only on Frequent capture without authorisation).", "default": false }, "descriptive": { "type": "string", "description": "This will appear in the bank statement/MB WAY application.", "maxLength": 255, "example": "descriptive example" }, "value": { "type": "number", "minimum": 0.5, "description": "Value will be rounded to 2 decimals.", "example": 20.55, "format": "double" } } }, "capture-post-response": { "title": "CapturePostResponse", "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "array", "items": { "type": "string", "example": "Your request was successfully created" } }, "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "677dbec9-ec19-4a78-9e08-3d2901c7a32b" } } }, "status-details": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "array", "items": { "type": "string", "example": "Your request was successfully created" } } } }, "authorisation-get-by-id-response": { "title": "AuthorisationGetDetailsResponse", "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "status": { "type": "string", "enum": [ "waiting", "pending", "failed", "canceled", "deleted", "success" ], "description": "Indicates the current status of the authorisation. Possible values include:\n- **waiting:** The payment instruction has been given, but the chosen payment method requires confirmation from an external entity before the status of the operation is finalized.\n- **pending:** This is the initial state, and it means that the authorisation is queued.\n- **success:** The authorisation has been completed successfully.\n- **failed:** The authorisation could not be completed due to an error or issue.\nThis field provides a clear indication of the current state of the authorisation, helping users understand its progress and outcome.\n" }, "message": { "type": "string", "description": "A string human-readable message included in the response." }, "key": { "type": "string", "description": "This can be any string that helps the user uniquely identify or reference the resource in their own system." }, "customer": { "$ref": "#/components/schemas/customer" }, "method": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "MB", "CC", "DD", "MBW" ], "description": "Specifies the payment method type used for the authorisation. Possible values include:\n- **MB:** Multibanco\n- **CC:** Credit Card\n- **DD:** Direct Debit\n- **MBW:** MB WAY\n- This field helps to identify the payment method chosen by the customer for the transaction.\n" }, "status": { "enum": [ "waiting", "pending", "active", "failed", "canceled", "deleted" ] }, "url": { "type": "string", "description": "The URL where the merchant should redirect the user to complete Credit Card Payments. This field is only applicable and available for credit card payment transactions.", "example": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a", "format": "uri" }, "last_four": { "type": "string", "description": "The last four digits of the credit card number used for the payment. This field is only applicable for credit card transactions.", "example": "1354" }, "card_type": { "enum": [ "VISA", "Mastercard" ], "description": "Indicates the type of credit card used for the payment (e.g., \"Visa\", \"MasterCard\"). This field is only applicable for credit card transactions." }, "expiration_date": { "type": "string", "format": "date-time", "description": "The timestamp indicating when the resource will expire. It is formatted as \"YYYY-MM-DD HH:MM" } } }, "currency": { "type": "string", "description": "The currency code in ISO 4217 format (e.g., \"EUR\" for Euro). This field specifies the type of currency used in financial operation", "example": "EUR" }, "value": { "type": "number", "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places.", "example": 125.89, "format": "double" }, "value_captured": { "type": "number", "description": "The monetary amount requested for the capture transaction. This field is formatted as a double, and will be rounded to two decimal places.", "format": "double", "example": 10.87 }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/payment-transactions" } } } }, "checkout-get-details-response": { "type": "object", "x-examples": { "example-1": { "status": "success", "message": [ "checkout is not finished yet" ], "checkout": { "id": "ced0ff93-d64f-47fc-b29e-4e5481cb38ec", "status": "pending" }, "payment": { "id": "df9d691d-f7fe-4ce4-8205-323888a769f3", "status": "success", "methods": [ "MB", "CC", "MBW", "VI", "UF" ], "expiration_time": "2022-12-12T16:05:00Z", "currency": "EUR", "key": "Example Key", "max_value": 20, "min_value": 2, "frequency": "1W", "max_captures": 10, "start_time": "2022-12-05T12:05:00Z", "failover": true, "capture_now": true, "retries": 2 }, "value": 17.5 } }, "properties": { "status": { "type": "string", "enum": [ "failed", "success" ] }, "message": { "type": "array", "items": { "type": "string" } }, "checkout": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "canceled", "complete" ] } } }, "payment": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "waiting", "pending", "active", "deleted" ] }, "methods": { "type": "array", "items": { "type": "string", "enum": [ "MB", "CC", "MBW", "DD", "VI", "AP", "GP", "SW" ] } }, "type": { "enum": [ "single", "frequent", "subscription" ] }, "expiration_time": { "type": "string" }, "currency": { "type": "string" }, "key": { "type": "string" }, "max_value": { "type": "integer" }, "min_value": { "type": "integer" }, "unlimited_payments": { "type": "boolean" }, "frequency": { "type": "string" }, "max_captures": { "type": "integer" }, "start_time": { "type": "string" }, "failover": { "type": "boolean" }, "capture_now": { "type": "boolean" }, "retries": { "type": "integer" }, "notification": { "$ref": "#/components/schemas/notification" } } }, "value": { "type": "number" } } }, "checkout-payment-types-request": { "title": "CheckoutPaymentTypesRequest", "type": "string", "enum": [ "single", "frequent", "subscription" ] }, "checkout-payment-methods-request": { "title": "Checkout Payment Methods", "type": "array", "description": "All the payment methods available to create a checkout payment.", "items": { "type": "string", "enum": [ "MB", "MBW", "DD", "CC", "VI", "AP", "GP", "SW" ], "example": "MBW" } }, "checkout-capture-object-request": { "title": "CheckoutCaptureObjectRequest", "type": "object", "properties": { "transaction_key": { "type": "string", "description": "The internal key used to identify this transaction in the merchant's database.", "maxLength": 50 }, "capture_date": { "type": "string", "format": "date", "example": "2026-05-15", "description": "The date on which the capture is performed." }, "account": { "type": "object", "description": "This object is used for multi-account clients.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The uuid of the account." } } }, "splits": { "$ref": "#/components/schemas/capture-split-create", "description": "This object is only used in split payments." }, "descriptive": { "type": "string", "maxLength": 255, "description": "Required if the payment method is 'MBW'." } } }, "checkout-payment-object-request": { "title": "CheckoutPaymentObjectRequest", "type": "object", "properties": { "methods": { "$ref": "#/components/schemas/checkout-payment-methods-request", "description": "Payment Method | Single Payment | Frequent Payment | Subscription Payment |\n---------|----------|---------|----------|\n CC (Credit Card) | x | x | x |\n DD (Direct Debit) | x | x | x |\n MBW (MB WAY) | x | x | - |\n MB (Multibanco) | x | x | - |\n VI (Virtual IBAN) | x | x | - |\n SW (Samsung Wallet) | x | x | x |\n AP (Apple Pay) | x | x | x |\n GP (Google Pay) | x | x | x |\n" }, "type": { "description": "Specifies the type of financial operation being performed.
**This property is used only for Single Payments.** \n\nTYPE | DESCRIPTION |\n---------|----------|\n sale | a complete transaction where funds are immediately captured. |\n authorisation | a temporary hold on funds pending a future capture. |\n", "example": "sale", "enum": [ "sale", "authorisation" ] }, "capture": { "$ref": "#/components/schemas/checkout-capture-object-request", "description": "Required only if the payment type is sale." }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate" }, "expiration_time": { "type": "string", "description": "The last possible time to make the payment. Applicable in Multibanco payments.\n\nNote: If the expiration time is less than the default checkout session expiration (which is 30 minutes),\nthe user won't be able to interact with the Checkout after that time.\n", "format": "date", "example": "2027-12-12 16:05" }, "currency": { "type": "string", "default": "EUR", "description": "The currency code in ISO 4217 format (e.g., \"EUR\" for Euro). This field specifies the type of currency used in financial operation." }, "key": { "type": "string", "description": "The merchant's key for identifying the payment.", "maxLength": 50 }, "max_value": { "type": "number", "format": "double", "minimum": 0.5, "description": "Additional property for frequent payments." }, "min_value": { "type": "number", "format": "double", "minimum": 0.5, "description": "Additional property for frequent payments." }, "unlimited_payments": { "type": "boolean", "description": "Additional property for frequent payments." }, "frequency": { "enum": [ "1D", "1W", "2W", "1M", "2M", "3M", "4M", "6M", "1Y", "2Y", "3Y" ], "description": "Additional property for subscription payments." }, "max_captures": { "type": "integer", "description": "Additional property for subscription payments.\n\nDefines a maximum number of captures, is required when no expiration_time is set.\n" }, "start_time": { "type": "string", "format": "date", "description": "Additional property for subscription payments.\nDefines the start of the billing cycles.\n" }, "failover": { "type": "boolean", "description": "Additional property for subscription payments.\n\nAfter all retries failed, the payment cycle can have another try with another single method.\n" }, "capture_now": { "type": "boolean", "description": "Additional property for subscription payments.\n\nWhether to schedule an immediate capture and schedule the second one for start_time.\n" }, "retries": { "type": "number", "description": "Additional property for subscription payments.\n\nNumber of retries in each payment cycle.
\nThe chosen frequency will define the max number of possible retries.\n", "default": 0 }, "multibanco": { "type": "object", "description": "An object that holds the details specific to a Multibanco transaction. **This property is used only for Single Payments.**", "required": [ "expiration_time" ], "properties": { "expiration_time": { "type": "string", "description": "The end timestamp indicating the deadline by which the Multibanco Reference must be paid. It defines the final time within which the payment must be completed. The format follows RFC3339 (e.g., \"2024-06-30T21:38:31Z\")." }, "start_time": { "type": "string", "description": "The starting timestamp indicating when the Multibanco Reference becomes valid for payment. It defines the initial time from which the payment can be made. The format follows RFC3339 (e.g., \"2024-06-30T21:38:31Z\"). This field is optional and defaults to the current timestamp if not specified, or if the sent value is in the past." }, "multibanco": { "type": "object", "description": "An object that holds the details specific to a Multibanco transaction.", "required": [ "expiration_time" ], "properties": { "expiration_time": { "type": "string", "format": "date-time", "description": "The end timestamp indicating the deadline by which the Multibanco Reference must be paid. It defines the final time within which the payment must be completed. The format follows RFC3339 (e.g., \"2024-06-30T21:38:31Z\")." }, "start_time": { "type": "string", "format": "date-time", "description": "The starting timestamp indicating when the Multibanco Reference becomes valid for payment. It defines the initial time from which the payment can be made. The format follows RFC3339 (e.g., \"2024-06-30T21:38:31Z\"). This field is optional and defaults to the current timestamp if not specified, or if the sent value is in the past." }, "product": { "type": "string", "enum": [ "FILE", "SPG", "CHECKDIGIT" ], "default": "CHECKDIGIT", "description": "This field is used to select the desired product. Below, the supported features for each product are listed. The default value is CHECKDIGIT. Additional costs may apply depending on the selected product.\n\n**Product Features:**\n\n| Product Type | Immediate Issuance | Expiration Date | Start Date |\n|--------------|-------------------|-----------------|------------|\n| CHECKDIGIT | ✓ | ✓ | ✗ |\n| SPG | ✗ | ✓ | ✓ |\n| FILE | ✗ | ✓ | ✓ |\n\n**Descriptions:**\n- **CHECKDIGIT**: Standard Multibanco references with immediate issuance\n- **SPG**: Special purpose group references with scheduling capabilities\n- **FILE**: File-based references for batch processing" } } } } }, "notification": { "$ref": "#/components/schemas/notification" } } }, "checkout-order-response": { "title": "CheckoutOrderResponse", "type": "object", "required": [ "value" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "description", "value" ], "properties": { "description": { "type": "string", "maxLength": 100, "description": "Brief description of the item.", "example": "Description Example" }, "quantity": { "type": "number", "example": 2, "description": "Quantity of this item being paid." }, "key": { "type": "string", "maxLength": 50, "description": "The merchant's key to identify the item", "example": "Key Example" }, "value": { "type": "number", "format": "double", "example": 10.55, "minimum": 0.5, "description": "The price being paid for the specific item(s), rounded to 2 decimals." } } } }, "key": { "type": "string", "description": "The merchant's key to identify the order.", "maxLength": 50, "example": "Example Key" }, "value": { "type": "number", "format": "double", "example": 50.78, "description": "The price being paid for the entire order, rounded to 2 decimals", "minimum": 0.5 } } }, "checkout-customer-request": { "title": "Customer", "type": "object", "description": "The Customer object contains detailed information about the customer required to create a Checkout payment.", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "name": { "type": "string", "example": "Jonh Doe", "description": "The full name of the customer. This field is used to identify the customer and personalize interactions. It typically includes the customer's first name and last name.", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "example@easypay.pt", "maxLength": 70, "description": "The email address of the customer. This field is used for communication purposes, including sending transaction confirmations, receipts, and other notifications related to the customer's activities." }, "phone": { "type": "string", "example": "911234567", "description": "The contact phone number of the customer has the E.164 pattern. This number will be used to make the payment if the method is MB WAY.", "maxLength": 15 }, "phone_indicative": { "type": "string", "maxLength": 5, "description": "The phone country code.", "example": "+351" }, "language": { "type": "string", "description": "The language preference of the customer, specified in the ISO 639-1 Alpha-2 format (e.g., \"EN\" for English, \"PT\" for Portuguese). This field is used to indicate the customer's preferred language for communication and documentation.", "minLength": 2, "maxLength": 2, "example": "EN" }, "fiscal_number": { "type": "string", "maxLength": 20, "description": "The customer's fiscal number (prefixed by the country code).", "example": "PT268826145" }, "key": { "type": "string", "maxLength": 255, "description": "The merchant's key to identify the customer.", "example": "Key Example" } } }, "checkout-request": { "type": "object", "x-examples": { "example-1": { "type": [ "single", "frequent", "subscription" ], "payment": { "methods": [ "MB", "CC", "MBW", "VI", "UF", "SC", "DD", "AP" ], "type": "sale", "capture": { "transaction_key": "string", "capture_date": "string", "account": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93" }, "splits": [ { "split_key": "string", "split_descriptive": "Descriptive Example", "value": 1, "account": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93" }, "margin_value": 0.1, "margin_account": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93" } } ], "descriptive": "Descriptive Example" }, "expiration_time": "2017-12-12 16:05", "currency": "EUR", "key": "Example Key", "max_value": 20, "min_value": 2, "unlimited_payments": false, "frequency": "1D", "max_captures": 10, "start_time": "2017-12-12 16:05", "failover": true, "capture_now": true, "retries": 2, "notification": { "customer_method_instructions_email": true } }, "order": { "items": [ { "description": "Item in Shopping Cart", "quantity": 2, "key": "Example Key", "value": 17.5 } ], "key": "Example Key", "value": 17.5 }, "customer": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93", "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "fiscal_number": "PT123456789", "key": "Key Example" } } }, "required": [ "type", "payment" ], "properties": { "type": { "type": "array", "items": { "$ref": "#/components/schemas/checkout-payment-types-request" }, "minItems": 1, "description": "Only the first value in the Array is considered (e.g. ['single', 'frequent'] would be equivalent to ['single'])." }, "payment": { "$ref": "#/components/schemas/checkout-payment-object-request", "description": "Describing the payment configuration." }, "order": { "$ref": "#/components/schemas/checkout-order-response", "description": "Order represent the order/cart being paid. Order is required if type is one single or subscription." }, "customer": { "$ref": "#/components/schemas/checkout-customer-request", "description": "The customer details." } } }, "checkout-post-response": { "title": "CheckoutPostResponse", "type": "object", "description": "The response body when the checkout is created successfully.", "properties": { "id": { "type": "string", "description": "UUID of the checkout.", "format": "uuid", "example": "5db36b83-0664-4bc4-a760-7040ac3726f0" }, "session": { "type": "string", "description": "Session token to be used by the rest of the Checkout process.", "example": "PX2duB7zMRISp6WrKdkOHLcvhIj-7-yUXMYHDQf5k7L5b5mA3D_m5TCdsYT-mCOaALGw4k95I_gjYQS-tcsxAAjTqU4G0UM5sd2o5wdGTGOOuoZVv0CwmiBwhUY9j4Dq4MDryEEPXtqMHEYi7PJz7dakeBemaWFg9GCEvdE6BM_uDBjZLBIS--_uFjRWpKm5enhwTkGvF3iTXuNrsRAxrW8YTsPUGJZumz2s-xSwa6XVaqRqO9uTvuHWy9TrEs1eCTeiWpqwZaj8_aNry5Tc44Epvvw4-4yebDaMQ1gJIHyJDzkLQ9mv4lNPjOFFtJPHihzgIybJdxzE1f6oBnjudMJa0LHsyzkHt29_j4FNRwSyU0Sti2vtW9SEAJ9D8pqrhvMg7zDQkvYLxjNJrME8EVqlGA_il0hc75wigX3hRdoVokF7u0-0ac0HYltG2zYEgE2lxqzPaG_lSbidSBAIoFWhY5rij3TyQHg6lPhHF6jYhn0ytvsBRauIdlZnJau18KzcOH4fcwN8d59SuhffuSyD_Mtd7trlzz6lWM9AeoY=" }, "config": { "nullable": true } } }, "subscription-method-response-on-list": { "title": "SubscriptionMethodResponseOnList", "type": "object", "properties": { "type": { "enum": [ "CC", "DD" ] }, "status": { "enum": [ "active", "inactive", "waiting" ] }, "url": { "type": "string", "format": "uri", "example": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a" }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate-response-on-list" } } }, "subscription-response-on-list": { "type": "object", "description": "Subscription object that returns after a success request.", "properties": { "id": { "type": "string", "format": "uuid", "example": "458b2fc4-3092-4de3-abd4-fe1600c09420" }, "key": { "type": "string", "example": "payment 02536985" }, "expiration_time": { "type": "string", "format": "date-time", "example": "2099-01-15 00:00" }, "start_time": { "type": "string", "example": "2027-01-15 00:00", "format": "date-time" }, "frequency": { "enum": [ "1D", "1W", "2W", "1M", "2M", "3M", "4M", "6M", "1Y", "2Y", "3Y" ] }, "retries": { "type": "integer", "example": 2 }, "max_captures": { "type": "integer", "example": 12 }, "failover": { "type": "boolean", "default": false }, "capture_now": { "type": "boolean" }, "unlimited_payments": { "type": "boolean" }, "customer": { "$ref": "#/components/schemas/customer-response-on-list" }, "method": { "$ref": "#/components/schemas/subscription-method-response-on-list" }, "currency": { "type": "string", "description": "The currency code in ISO 4217 format (e.g., \"EUR\" for Euro). This field specifies the type of currency used in financial operation." }, "value": { "type": "number", "format": "double", "example": 10.55 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-08-05 13:44:29" } } }, "frequency": { "title": "Frequency", "x-stoplight": { "id": "yvzrcsvdf10ek" }, "type": "string", "enum": [ "1D", "1W", "2W", "1M", "2M", "3M", "4M", "6M", "1Y", "2Y", "3Y" ], "description": "Defining the frequency that the cycles are charged." }, "customer-response-on-detail": { "type": "object", "x-stoplight": { "id": "ro8t50k4mow57" }, "description": "The Customer object contains detailed information about the customer involved in the transaction.", "properties": { "id": { "type": "string", "format": "uuid", "example": "1b4ca1cf-9a1a-415b-97bf-342c6ddcf9c1" }, "name": { "type": "string", "example": "Joey Price" }, "email": { "type": "string", "format": "email", "example": "john.doe@yahoo.com" }, "phone": { "type": "string", "example": "911234567" }, "phone_indicative": { "type": "string", "example": "+351" }, "fiscal_number": { "type": "string", "example": "PT921839198892623010" }, "key": { "type": "string", "example": "subscription 01234589" }, "language": { "type": "string", "example": "PT" } } }, "subscription-method-response-on-detail": { "title": "SubscriptionMethodResponseOnDetail", "type": "object", "properties": { "type": { "enum": [ "CC", "DD" ] }, "status": { "enum": [ "active", "inactive", "waiting" ] }, "url": { "type": "string", "format": "uri", "example": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a" }, "last_four": { "type": "string", "example": "2222" }, "card_type": { "type": "string", "example": "VISA" }, "expiration_date": { "type": "string", "example": "07/29" }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate-response-on-detail" } } }, "subscription-response-on-detail": { "type": "object", "description": "Subscription object that returns after a success request.", "properties": { "id": { "type": "string", "format": "uuid", "example": "458b2fc4-3092-4de3-abd4-fe1600c09420" }, "status": { "type": "string", "example": "ok" }, "key": { "type": "string", "example": "payment 02536985" }, "expiration_time": { "type": "string", "format": "date-time", "example": "2099-01-15 00:00" }, "start_time": { "type": "string", "example": "2027-01-15 00:00", "format": "date-time" }, "frequency": { "enum": [ "1D", "1W", "2W", "1M", "2M", "3M", "4M", "6M", "1Y", "2Y", "3Y" ] }, "retries": { "type": "integer", "example": 2 }, "max_captures": { "type": "integer", "example": 12 }, "failover": { "type": "boolean", "default": false }, "capture_now": { "type": "boolean" }, "unlimited_payments": { "type": "boolean" }, "customer": { "$ref": "#/components/schemas/customer-response-on-detail" }, "method": { "$ref": "#/components/schemas/subscription-method-response-on-detail" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/payment-transactions" } }, "currency": { "$ref": "#/components/schemas/currency" }, "value": { "type": "number", "format": "double", "example": 10.55 }, "created_at": { "type": "string", "format": "date-time", "example": "2025-08-05 13:44:29" } } }, "cycle": { "title": "Cycle", "type": "object", "required": [ "id", "type", "status", "value", "capture_at" ], "properties": { "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "description": "The cycle's unique identifier." }, "type": { "type": "string", "enum": [ "RENEWABLE", "ONE_TIME_CHARGE", "CAPTURE_NOW" ], "example": "RENEWABLE", "description": "How the cycle was created:\n * `RENEWABLE` — part of the recurring schedule.\n * `ONE_TIME_CHARGE` — an ad-hoc capture added on top of the schedule.\n * `CAPTURE_NOW` — an immediate one-off capture.\n" }, "status": { "type": "string", "enum": [ "PENDING", "PROCESSING", "WAITING", "SUCCESS", "FAILED", "RETRY", "FAILOVER", "DELETED" ], "example": "PENDING", "description": "The current state of the cycle:\n * `PENDING` — queued, waiting for its scheduled time.\n * `PROCESSING` — capture is being executed right now.\n * `WAITING` — waiting on an external dependency (e.g. customer action).\n * `SUCCESS` — captured successfully.\n * `FAILED` — capture failed and will not be retried.\n * `RETRY` — capture failed but is queued for another attempt.\n * `FAILOVER` — switched to the failover method after the primary failed.\n * `DELETED` — cancelled before being captured.\n" }, "value": { "type": "number", "format": "double", "minimum": 0, "example": 10.5, "description": "The amount captured, in euros." }, "capture_at": { "type": "string", "format": "date-time", "example": "2026-05-22T09:00:00Z", "description": "When the capture is scheduled to run, in UTC (RFC 3339)." }, "description": { "type": "string", "maxLength": 255, "example": "monthly charge", "description": "Free-form text shown on the bank statement or in the MB WAY app. Omitted when not set." }, "key": { "type": "string", "maxLength": 50, "example": "my-key", "description": "Your internal identifier for the cycle. Omitted when not set." } } }, "one-time-charge-response-on-post": { "title": "OneTimeChargeResponseOnPost", "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "array", "items": { "type": "string" }, "example": [ "Your request was successfully created" ] }, "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "description": "The UUID of the newly created cycle." } }, "required": [ "status", "message", "id" ] }, "update-cycle-response-on-patch": { "title": "UpdateCycleResponseOnPatch", "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "array", "items": { "type": "string" }, "example": [ "Your request was successfully updated" ] }, "id": { "type": "string", "format": "uuid", "example": "550e8400-e29b-41d4-a716-446655440000", "description": "The UUID of the updated cycle (same as the `cycle_id` path parameter)." } }, "required": [ "status", "message", "id" ] }, "void-get-by-id-response": { "title": "VoidGetDetailsResponse", "type": "object", "properties": { "status": { "enum": [ "pending", "processing", "success", "failed" ], "description": "Indicates the current status of the void:\n- **pending**: Initial state — the void has been created and queued.\n- **processing**: The void is being processed by the acquirer.\n- **success**: The void completed successfully (the authorisation was released).\n- **failed**: The void could not be completed due to an error or issue.\n" }, "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "transaction_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system." }, "descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\"." }, "authorisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "status": { "enum": [ "waiting", "pending", "failed", "canceled", "deleted", "success" ], "description": "- **waiting**: The authorisation instruction has been given, but the chosen payment method requires confirmation from an external entity before the status of the operation is finalized.\n- **pending**: This is the initial state, and it means that the authorisation is queued.\n- **failed**: The authorisation could not be completed due to an error or issue.\n- **canceled**: The authorisation has been canceled.\n- **deleted**: The authorisation has been deleted.\n- **success**: The authorisation has been created successfully.\n" }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system." }, "customer": { "$ref": "#/components/schemas/customer" }, "method": { "type": "object", "properties": { "type": { "enum": [ "CC", "MBW", "AP", "GP", "SW" ], "description": "Specifies the type of payment method being used for the transaction. \n\nTYPE | DESCRIPTION |\n---------|----------|\n CC | Credit Card |\n MBW | Multibanco |\n AP | Apple Pay |\n GP | Google Pay |\n SW | Samsung Wallet |" }, "status": { "enum": [ "active", "inactive" ] } } }, "currency": { "type": "string", "enum": [ "EUR" ] }, "value": { "type": "number", "format": "double", "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places.", "example": 15.78 } } } } }, "void-post-request": { "title": "VoidPostRequest", "type": "object", "required": [ "descriptive" ], "properties": { "descriptive": { "type": "string", "description": "Free-text reason for the void. Required, up to 255 characters. This will appear in the bank statement / MB WAY application.\n", "maxLength": 255, "example": "Cancelling the duplicated authorisation" }, "transaction_key": { "type": "string", "description": "Optional. Your own internal key identifying this void, up to 50 characters. Echoed back on the void details.\n", "maxLength": 50, "example": "order-1982652-void" } }, "example": { "descriptive": "Cancelling the duplicated authorisation", "transaction_key": "order-1982652-void" } }, "void-post-response": { "title": "PostVoidResponse", "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "array", "description": "An array of human-readable messages included in the response. These messages provide detailed information about the success of the operation or explain the reasons for any failure. This field is always present in the response to ensure clarity and transparency regarding the outcome of the API request.", "items": { "type": "string", "example": "Your request was successfully created" } }, "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "8010e7d5-9985-4ae3-b1bf-6b70019439c7" } } }, "money": { "title": "Money", "type": "object", "description": "The money type is a data structure used to represent a monetary value in a specific currency. It includes both the amount and the currency type to accurately define the value of money in various contexts, such as financial transactions, pricing, and accounting.", "properties": { "amount": { "type": "string", "description": "Represents the numerical value of the money. The amount should be a string formatted to include up to two decimal places to accurately represent cents or subunits of currency. For example, \"123.45\" represents one hundred twenty-three units and forty-five subunits of the currency." }, "currency": { "type": "string", "description": "Indicates the type of currency associated with the amount. This should follow standard currency codes (ISO 4217), such as \"USD\" for US Dollar, \"EUR\" for Euro, or \"JPY\" for Japanese Yen, to specify which currency the amount is denominated in." } }, "examples": [ { "amount": 0.12, "currency": "EUR" } ] }, "transaction-fee": { "title": "Fee", "type": "object", "properties": { "fixed_amount": { "$ref": "#/components/schemas/money" }, "variable_amount": { "$ref": "#/components/schemas/money" }, "vat_amount": { "$ref": "#/components/schemas/money" } }, "description": "An object that represents a set of amounts in different categories such as fixed, variable, and VAT, each with an associated currency. The structure includes:\n - **fixed_amount**: Represents a fixed fee applied to the transaction.\n - **variable_amount**: Represents a variable fee, usually dependent on the transaction amount.\n - **vat_amount**: Represents the value-added tax (VAT) applied to the fees.\n All amounts are represented in a specific currency." }, "financial-transaction-details": { "title": "FinancialTransactionDetails", "type": "object", "description": "An object containing detailed financial information related to the transaction. Provides a breakdown of various components of the transaction, such as fees , requested and payed amounts.", "properties": { "requested_amount": { "$ref": "#/components/schemas/money" }, "payed_amount": { "$ref": "#/components/schemas/money" }, "fees": { "type": "array", "items": { "$ref": "#/components/schemas/transaction-fee" }, "description": "An array of fee objects, where each fee represents a specific charge or cost associated with a transaction. Each fee includes details such as the amount and currency, and may represent different types of fees like fixed, variable, or VAT." } } }, "ledger-entry-details": { "type": "object", "x-examples": { "Example 1": { "operation_id": "7bca9e29-21a3-4e23-a1f5-50bb605e2360", "operation_key": "Merchant identification key", "method": "CC", "payment_id": "502b0844-13a8-4788-b775-5e4cc8194a50", "payment_type": "single", "payment_key": "Merchant identification key" } }, "description": "An object containing detailed information about a specific operation and payment. This includes unique identifiers, the method used for the payment, and the type of payment.", "properties": { "operation_id": { "type": "string", "example": "502b0844-13a8-4788-b775-5e4cc8194a50", "description": "A unique identifier for the operation, represented as a UUID." }, "operation_key": { "type": "string", "description": "A merchant-specific identification key for the operation." }, "method": { "type": "string", "description": "The payment method used for the transaction (e.g., CC for credit card).", "example": "CC" }, "payment_id": { "type": "string", "description": "A unique identifier for the payment, represented as a UUID.", "example": "235934c2-467d-44fa-9e81-9cbd9d1a6f61" }, "payment_type": { "type": "string", "description": "The type of payment, such as 'single' for a one-time payment.", "example": "single" }, "payment_key": { "type": "string", "description": " A merchant-specific identification key for the payment." } } }, "ledger-entry": { "title": "LedgerEntry", "type": "object", "description": "The **LedgerEntry** object represents a single entry in the financial ledger of Easypay reconciliation system. It captures detailed information about a specific financial transaction, including its type, category, and associated monetary details. This object serves as a comprehensive record of all activities impacting an account's balance, providing an audit trail for both debits and credits.\n\nEach **LedgerEntry** includes metadata such as unique identifiers and timestamps to track when the entry was created and when the transaction occurred. It also encompasses financial breakdowns like fees, taxes, and transferred amounts, all contextualized with currency information. Additionally, the object can link to specific operations or payment methods, detailing the source and nature of each transaction.\n", "examples": [ { "id": "38c65c65-6b66-42e8-b3db-3a3361ef23e4", "created_at": "2024-10-02 09:39", "transaction_timestamp": "2024-10-02 09:39", "transaction_type": "CP", "amount_details": { "requested_amount": { "amount": 8, "currency": "EUR" }, "payed_amount": { "amount": 8, "currency": "EUR" }, "fees": [ { "fixed_amount": { "amount": 0.25, "currency": "EUR" }, "variable_amount": { "amount": 0.28, "currency": "EUR" }, "vat_amount": { "amount": 0.12, "currency": "EUR" } } ] }, "transfer_batch_date": "2024-10-11", "transfer_batch": "781", "descriptive": "Descriptive Josefa", "details": { "operation_id": "7bca9e29-21a3-4e23-a1f5-50bb605e2360", "operation_key": "Merchant identification key", "method": "CC", "payment_id": "502b0844-13a8-4788-b775-5e4cc8194a50", "payment_type": "single", "payment_key": "Merchant identification key" }, "amount": { "amount": 7.35, "currency": "EUR" } } ], "properties": { "id": { "type": "string", "example": "\"38c65c65-6b66-42e8-b3db-3a3361ef23e4\"", "description": "A unique identifier for the ledger entry, represented as a UUID. This ID is used to uniquely track and reference individual entries within the ledger system." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp indicating when the resource was created. It is formatted as ISO 8601.", "example": "2019-08-24T14:15:22Z" }, "transaction_timestamp": { "type": "string", "description": "The exact timestamp of when the associated transaction occurred. It is formatted as \"YYYY-MM-DD HH:MM\".", "examples": [ "2024-09-23 11:03" ] }, "transaction_type": { "type": "string", "enum": [ "CP", "RF", "RV", "FEE", "SP", "MAN", "TB", "OT", "CB", "OP", "TF", "RW", "RR", "RX" ], "example": "CP", "description": "**LedgerTransactionType** is a string enum that represents various types of financial transactions recorded in a ledger. Each transaction type is abbreviated with a code and corresponds to a specific financial operation.\n\nThe following are the possible values and their descriptions:\n\n• **CP** (Capture): Represents the capture of funds, typically after a payment authorization. This transaction finalizes a payment and moves the funds from the payer's account to the payee's account.\n\n• **RF** (Refund): Represents a refund transaction where previously captured funds are returned to the payer's account. This transaction often occurs when a customer returns goods or services.\n\n• **RV** (Revert): Indicates a revert transaction that undoes a previously made transaction, often used to correct errors or reverse transactions.\n\n• **SP** (Split Payment): Represents a split payment transaction, where a payment is divided among multiple recipients or for different purposes within the same transaction.\n\n• **FEE** (Fee): Represents a fee transaction, which is a charge applied for a specific service or transaction. This could include service fees, processing fees, or other types of charges.\n\n• **MAN** (Manual Movement): Represents a manual movement of funds, typically entered manually by an administrator or accountant to adjust balances or correct errors.\n\n• **TB** (Bank Transfer): Represents a bank transfer transaction, where funds are moved between different bank accounts. This can be a transfer within the same bank or across different banks.\n\n• **OT** (Out Transfer): Indicates an out transfer transaction, where funds are transferred out of the current ledger or account to another external account or ledger.\n\n• **CB** (Chargeback): Represents a chargeback transaction, typically initiated by the payer's bank to reverse a disputed or fraudulent transaction. This transaction withdraws the funds from the payee's account and returns them to the payer.\n\n• **OP** (Out Payment): Represents an out payment transaction, where funds are paid out from the ledger to an external party or account. This transaction is usually used to settle debts or make external payments.\n\n• **TF** (Transfer Funds): Represents a movement of funds from an Easypay account to a bank account.\n\n• **RW** (Reward): Represents a reward earned by a customer, funded from the account balance. The entry links to the capture that earned the reward through the `details` object.\n\n• **RR** (Reward Redemption): Represents reward credits a customer redeemed against a purchase. The entry links to the capture the credits were redeemed on through the `details` object.\n\n• **RX** (Reward Expiry): Represents the payout of a customer's unused reward credits when they expire. These entries are not linked to any operation, so `details` is not populated.\n\nSee the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for how reward movements work." }, "amount_details": { "$ref": "#/components/schemas/financial-transaction-details" }, "transfer_batch_date": { "type": "string", "examples": [ "2024-10-11" ], "description": "The date when the transfer batch is scheduled or processed. The date is represented in ISO 8601 format (YYYY-MM-DD), indicating the year, month, and day." }, "transfer_batch": { "type": "string", "example": "\"584\"", "description": "A unique identifier for the transfer batch, typically represented as a string. This value is used to track and reference a specific batch of transfers within the system." }, "descriptive": { "type": "string", "description": "A brief, user-friendly description of the ledger entry. This is used to provide additional context or notes that describe the nature of the transaction in plain language." }, "details": { "$ref": "#/components/schemas/ledger-entry-details" }, "amount": { "$ref": "#/components/schemas/money" } } }, "metadata-page": { "type": "object", "x-examples": { "example-1": { "page": { "current": 1, "total": 8 }, "records": { "total": 20, "per_page": 20 }, "links": { "first": "?page=1", "prev": "", "next": "?page=2", "last": "?page=8" } } }, "description": "The Pagination object contains detailed information about the pagination of a collection of records.\n\nThis object is used to provide navigation and context for paginated results, allowing users to easily move between pages and understand the scope of the dataset.", "properties": { "page": { "type": "object", "required": [ "current", "total" ], "description": "An object containing information about the pagination of pages within the collection.", "properties": { "current": { "type": "integer", "description": "The current page number being viewed." }, "total": { "type": "integer", "description": "The total number of pages available in the collection." } } }, "records": { "type": "object", "description": "An object containing information about the records within the collection.", "required": [ "total", "per_page" ], "properties": { "total": { "type": "integer", "description": "The total number of records available in the collection." }, "per_page": { "type": "integer", "description": "The number of records displayed per page." } } }, "links": { "type": "object", "description": "An object containing URLs for navigation between different pages of the collection.", "properties": { "first": { "type": "string", "description": "The URL to the first page of the collection." }, "prev": { "type": "string", "description": "The URL to the previous page of the collection. This field is an empty string if there is no previous page." }, "next": { "type": "string", "description": "The URL to the next page of the collection. This field is an empty string if there is no next page." }, "last": { "type": "string", "description": "The URL to the last page of the collection." } } } }, "required": [ "page", "records" ] }, "transaction-report-data": { "type": "object", "x-examples": { "example-1": { "id": "b41921f1-a255-41bc-9e92-9a28d266d378", "key": "Merchant identification key", "date": "2022-11-16T16:45:19Z", "values": { "requested": 44, "paid": 44, "fixed_fee": 0.25, "variable_fee": 0.66, "tax": 1.5, "transfer": 42.88 }, "transfer_date": "2022-11-21T00:00:00Z", "transfer_batch": "", "method": "DD", "document_number": "MARCEL0208220452011220221116164519", "payment_type": "single", "payment_id": "2a9112fe-6510-4366-b55e-24a3ae188d67", "payment_account": { "id": "76f190b9-2b8a-4bd0-9490-411241a9dc81" }, "payment_key": "Merchant identification key", "payment_transaction_key": "Merchant identification key", "descriptive": "Descriptive Josefa" } }, "properties": { "id": { "type": "string", "format": "uuid" }, "key": { "type": "string", "description": "Any value that will help the merchant manage the transaction on his database." }, "date": { "type": "string", "format": "date-time", "description": "The date on which the provider reported the payment as having occurred." }, "values": { "type": "object", "properties": { "requested": { "type": "integer" }, "paid": { "type": "integer" }, "fixed_fee": { "type": "number" }, "variable_fee": { "type": "number" }, "tax": { "type": "number" }, "transfer": { "type": "number" } } }, "transfer_date": { "type": "string", "format": "date" }, "transfer_batch": { "type": "string", "description": "The batch where this transaction has transfered." }, "method": { "type": "string", "description": "The payment method." }, "document_number": { "type": "string", "description": "Unique document number used for Easypay Invoice." }, "payment_type": { "type": "string", "enum": [ "single", "frequent", "subscription" ], "example": "single" }, "payment_id": { "type": "string", "format": "uuid" }, "payment_account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "payment_key": { "type": "string" }, "payment_transaction_key": { "type": "string", "description": "Capture transaction key." }, "descriptive": { "type": "string", "description": "Any descriptive information that will help the merchant manage the transaction on his database." }, "created_at": { "type": "string", "format": "date-time", "description": "The timestamp indicating when the payment record was added to the system." } } }, "settlement": { "title": "Settlement", "type": "object", "required": [ "id", "created_at", "updated_at", "name", "description", "status", "total_amount", "number_of_items", "destination" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the settlement.", "example": "f6a7b8c9-d0e1-2345-fabc-456789012306" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the settlement was created. Always present.", "example": "2026-02-05T09:30:00Z" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the settlement was last updated, or `null` when it has never been updated.", "example": "2025-10-01T00:00:00Z" }, "name": { "type": "string", "description": "Human-readable name of the settlement (its batch reference).", "example": "1006" }, "description": { "type": "string", "description": "Human-readable description of the settlement.", "example": "EASYPAY-1977225-42185-161-998590696" }, "status": { "type": "string", "enum": [ "IN_TRANSIT", "SUCCEEDED", "FAILED" ], "description": "Current status of the settlement.", "example": "IN_TRANSIT" }, "total_amount": { "$ref": "#/components/schemas/money", "description": "Total amount of the settlement" }, "number_of_items": { "type": "integer", "description": "Number of transactions included in the settlement.", "example": 2 }, "destination": { "type": "object", "description": "Where the settled funds are sent.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "IBAN" ], "description": "Type of destination.", "example": "IBAN" }, "details": { "type": "object", "description": "Details specific to the destination type.", "properties": { "iban": { "type": "string", "description": "Destination IBAN. Omitted when empty.", "example": "PT50007974951304464003280" } } } } } } }, "out-payment-transactions": { "type": "object", "description": "An array of transactions, where each one represents a specific charge or cost associated with a transaction. Includes details such as the amount and transfer, and its related fees.", "properties": { "id": { "type": "string", "description": "A unique identifier for the entry, represented as a UUID. This ID is used to uniquely track and reference individual entries within the ledger system.", "example": "4fb3ac57-c7fe-4157-aeb7-4362ae24deec", "format": "uuid" }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.", "example": "01J1PKR2RPHJNJQGFWGDYXY0KM" }, "created_at": { "type": "string", "description": "The timestamp indicating when the resource was created. It is formatted as ISO 8601.", "format": "date-time", "example": "2025-05-30T17:21:47Z" }, "date": { "type": "string", "description": "The timestamp indicating when the resource was updated. It is formatted as ISO 8601.", "example": "2025-05-30T17:21:46Z", "format": "date-time" }, "values": { "type": "object", "properties": { "requested": { "type": "number", "description": "The amount requested, rounded by two decimapl plates.", "format": "double", "example": 12.55 }, "paid": { "type": "number", "format": "double", "example": 12.55, "description": "The amount paid, rounded by two decimal plates." }, "fixed_fee": { "type": "number", "description": "The fixed fee amount applied to this transaction.", "format": "double", "example": 0.07 }, "variable_fee": { "type": "number", "description": "The variable fee amount applied to this transaction.", "example": 0.09 }, "tax": { "type": "number", "description": "The vat amount applied to this transaction.", "format": "double", "example": 0.04 }, "transfer": { "type": "number", "format": "double", "example": 12.35, "description": "The net value to be transferred." } } }, "transfer_date": { "type": "string", "format": "date-time", "example": "2025-06-02T00:00:00Z", "description": "The estimation when the funds will be transfered. It is formatted as ISO 8601." }, "transfer_batch": { "type": "string", "description": "A unique identifier for the transfer batch, typically represented as a string. This value is used to track and reference a specific batch of transfers within the system.", "example": "584" }, "method": { "type": "string", "description": "Method used for the transaction.", "example": "transfer" }, "document_number": { "type": "string", "example": "MARCEL0208220628294020250530172147", "description": "Unique document number used for Easypay Invoice." }, "descriptive": { "type": "string", "example": "blue t-shirts", "description": "This is used to provide additional context or notes that describe the nature of the transaction in plain language." } } }, "out-payment-response": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "status": { "type": "string", "enum": [ "success", "pending", "deleted", "delayed" ], "description": "Status of the out payment." }, "type": { "type": "string", "description": "Type of out payment.", "enum": [ "normal", "instant" ] }, "method": { "type": "string", "enum": [ "transfer", "mb" ], "description": "Method used for the out payment." }, "customer": { "type": "object", "description": "Customer associated with the out payment.", "properties": { "id": { "type": "string", "description": "Unique identifier for the customer." } } }, "account": { "type": "object", "description": "Easypay account from which the funds are transferred.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the Easypay account." } } }, "out_account": { "type": "object", "description": "Destination SEPA bank account for the out payment.", "properties": { "id": { "type": "string", "description": "Unique identifier for the destination account.", "format": "uuid" } } }, "key": { "type": "string", "description": "Merchant reference key for the out payment." }, "value": { "type": "number", "format": "double", "description": "Amount to be transferred." }, "schedule_at": { "type": "string", "description": "Scheduled date and time for the out payment (YYYY-MM-DD HH:MM:SS).", "example": "2022-09-15 20:28:58" }, "transactions": { "$ref": "#/components/schemas/out-payment-transactions", "description": "Transaction related to the out payment." }, "created_at": { "type": "string", "description": "Date and time when the out payment was created.", "example": "2022-09-15 20:28:58" }, "timestamp": { "type": "string", "description": "Timestamp of the last update or event for this out payment.", "example": "1749054192" } } }, "account": { "title": "Account", "type": "object", "properties": { "id": { "type": "string", "format": "uuid" } } }, "out-account": { "type": "object", "properties": { "account_holder": { "type": "string", "description": "Bank account holder name", "maxLength": 100 }, "iban": { "type": "string", "maxLength": 34, "description": "Only IBANS from SEPA zones are supported" }, "email": { "type": "string", "maxLength": 50 }, "phone": { "type": "string", "maxLength": 20 }, "key": { "type": "string", "maxLength": 255, "description": "Custom string controlled by our clients" }, "country_code": { "type": "string", "description": "Bank account country code", "deprecated": true } }, "required": [ "account_holder", "iban", "email", "phone" ] }, "refund-get-list-response": { "title": "RefundListSuccessResponse", "type": "object", "properties": { "metadata": { "type": "object", "description": "An object containing additional information about the response. It includes details that help manage and navigate the retrieved data.", "properties": { "next_cursor": { "type": "string", "description": "Provides the cursor for the next set of records. This value should be used as the cursor parameter in subsequent requests to continue paginating through the data. If the cursor is an empty string or null, it indicates that there are no more results. To retrieve all available results, continue making subsequent requests until next_cursor is empty or null." }, "count": { "type": "number", "description": "The total number of records in the current response. This field indicates the number of items returned in the current set of results.", "example": 5 } } }, "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "status": { "description": "Indicates the current status of the refund. Possible values include:\n- **waiting:** The payment instruction has been given, but the chosen payment method requires confirmation from an external entity before the status of the operation is finalized.\n- **pending:** This is the initial state, and it means that the refund is queued.\n- **success:** The refund has been completed successfully.\n- **failed:** The refund could not be completed due to an error or issue.\n\nThis field provides a clear indication of the current state of the refund, helping users understand its progress and outcome.\n", "enum": [ "success", "pending", "failed", "waiting" ] }, "transaction_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system." }, "value": { "type": "number", "format": "float", "example": 10.89, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places." }, "iban": { "type": "string", "description": "The International Bank Account Number of the account to which the refund will be sent. This field is used to uniquely identify the recipient's bank account across international borders.", "example": "PT50007950088428437201551" }, "email": { "type": "string", "description": "The email address of the account holder. This field is used for communication purposes, including sending notifications about the refund stat.", "example": "customer@example.pt" }, "phone": { "type": "string", "description": "The contact phone number of the account holder, including the country code indicator (e.g., \"+351\"). This field is used for communication purposes, such as contacting the account holder for verification.", "example": "+351912345678" }, "account_holder": { "type": "string", "description": "The name of the person or entity that holds the bank account. This field ensures that the refund is directed to the correct recipient." }, "capture": { "type": "object", "description": "The targeted Capture details.", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "payment_id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "payment_type": { "type": "string", "description": "Specifies the type of payment processed. Possible values include: - **Single:** A one-time payment transaction. - **Frequent:** A payment that occurs regularly but is not part of a subscription (e.g., recurring manual payments). - **Subscription:** A recurring payment that is part of a subscription plan, automatically processed at regular intervals. This field helps to categorize and manage different payment methods based on their frequency and nature." } } }, "create_at": { "type": "string", "format": "date-time", "description": "The timestamp indicating when the resource was created. It is formatted as \"YYYY-MM-DD HH:MM\"", "example": "2025-12-02 16:00:00" }, "update_at": { "type": "string", "format": "date-time", "description": "The timestamp indicating when the resource was updated. It is formatted as \"YYYY-MM-DD HH:MM\".", "example": "2025-12-02 16:00:00" } } } } } }, "refund-get-by-id-response": { "title": "RefundDetailsSuccessResponse", "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "status": { "enum": [ "success", "pending", "failed", "waiting" ], "description": "Indicates the current status of the refund. Possible values include:\n- **waiting:** The payment instruction has been given, but the chosen payment method requires confirmation from an external entity before the status of the operation is finalized.\n- **pending:** This is the initial state, and it means that the refund is queued.\n- **success:** The refund has been completed successfully.\n- **failed:** The refund could not be completed due to an error or issue.\n\nThis field provides a clear indication of the current state of the refund, helping users understand its progress and outcome.\n" }, "transaction_key": { "type": "string", "description": "Your internal key identifying this refund." }, "value": { "type": "number", "format": "double", "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places (e.g., \"100.00\").", "example": 15.98 }, "account_holder": { "type": "string", "description": "Bank account holder name." }, "email": { "type": "string", "description": "The email address of the account holder. This field is used for communication purposes, including sending notifications about the refund stat.", "example": "customer@example.pt" }, "phone": { "type": "string", "description": "The contact phone number of the account holder, including the country code indicator (e.g., \"+351\"). This field is used for communication purposes, such as contacting the account holder for verification", "example": "+351912345678" }, "iban": { "type": "string", "description": "The International Bank Account Number of the account to which the refund will be sent. This field is used to uniquely identify the recipient's bank account across international borders.", "example": "PT50007950088428437201551" }, "reward_redemption_reversal": { "type": "object", "description": "The reversal of the capture's reward redemption performed by this refund — the cashback restored to the customer's reward balance instead of being refunded to the payment method (the `revert.reward_redemption_reversal` the refund was created with). Present only when the refunded capture had redeemed reward credits and this refund restored them. This amount is wallet credit and is not part of the refund `value` paid out to the payment method. The restored credit appears on the customer's reward ledger as a `REWARD_RESTORATION` entry on `GET /customer/{id}/rewards`. See the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for the full flow.", "properties": { "value": { "type": "number", "format": "double", "description": "The reward amount this refund restored to the customer's reward balance.", "example": 2.5 }, "value_remaining": { "type": "number", "format": "double", "description": "The capture's redemption still un-reversed — the redeemed amount minus everything already restored to the customer's reward balance (the reversals of the capture's non-failed refunds and any chargeback restorations). Zero once the redemption is fully restored.", "example": 0 } } }, "capture": { "type": "object", "description": "Object with all the details about the capture.", "properties": { "transaction_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system." }, "capture_date": { "type": "string", "format": "date-time", "description": "The date when the action should be executed. This field specifies the exact day for capturing the transaction, formatted as \"YYYY-MM-DD\" (e.g., \"2024-06-30\"). It is optional and defaults to the current date if not specified." }, "account": { "type": "object", "description": "An object within the capture request that specifies the details of the account to which the funds should be routed, different from the initially requested account. This ensures that the captured funds are directed to the correct destination as per the specific routing requirements.", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "status": { "enum": [ "delayed", "waiting", "pending", "success", "failed", "refunded" ], "description": "Indicates the current status of the capture. Possible values include:\n- **delayed:** The capture attempt is scheduled for a future date and does not require further user interaction due to prior consent (e.g., authorization or frequent).\n- **waiting:** The payment instruction has been given, but the chosen payment method requires confirmation from an external entity before the status of the operation is finalized.\n- **pending:** The capture is pending user completion.\n- **success:** The capture has been completed successfully.\n- **failed:** The capture could not be completed due to an error or issue.\n- **refunded:** The capture has been refunded.\n\nThis field provides a clear indication of the current state of the capture, helping users understand its progress and outcome.\n" }, "splits": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the split. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "split_key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system." }, "split_descriptive": { "type": "string", "description": "A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as \"Payment of Invoice Nº 1982652\" or \"Ticket for Queen\"." }, "account": { "type": "object", "description": "The account to which the funds should be routed. This field is used to specify the destination account for the split payment, ensuring that the correct recipient receives their designated portion of the funds.", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "value": { "type": "number", "format": "double", "example": 8.65, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places. The value must be greater than or equal to 0.5." }, "clearing_date": { "type": "string", "format": "date", "description": "The clearing date refers to the specific date when a financial transaction is finalized and the funds are transferred from one account to another. This is the point at which the payment is officially completed and the amount is debited from the payer's account and credited to the payee's account." }, "clearing_period": { "type": "string", "description": "The clearing period must follow the format 1Y, 10W or 30D. Y for Years, W for weeks, D for days. Minimum is 7 days, maximum is 1 year.", "example": "1W" }, "margin_account": { "type": "object", "description": "The account to which the margin value should be routed. This field specifies the destination account for the margin portion of the funds, ensuring that the correct recipient receives the designated margin value.", "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "margin_value": { "type": "number", "format": "double", "description": "The monetary amount designated as the margin in a split payment. This field is formatted as a double, and will be rounded to two decimal places. The value must be less than the total value of the split. This specifies the portion of the funds that should be routed to the margin account.", "example": 1.25 }, "status": { "enum": [ "waiting", "success", "failed", "reverted" ], "description": "The current status of the Split. `waiting` while the split is queued for processing, `success` once the funds have been routed, `failed` if processing errored, `reverted` once the split has been reverted after a refund or chargeback." }, "reward": { "type": "object", "description": "Reward credits generated from this split. The credits are associated with the customer provided at the top level of the payment request and can only be redeemed by that customer. Present only when the split carries a reward.", "properties": { "account": { "type": "object", "description": "The account to which the reward credits are routed.", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "value": { "type": "number", "format": "double", "description": "The reward amount generated from this split.", "example": 1 }, "expiration_date": { "type": "string", "format": "date", "description": "The date until which the reward credits are valid. Present only when the reward has an expiration date.", "example": "2027-04-02" } } }, "reverts": { "type": "array", "description": "Object with all the information about the revert.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "value": { "type": "number", "format": "double", "example": 12.87, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places. The value must be greater than or equal to 0.5." }, "margin_value": { "type": "number", "format": "double", "description": "The monetary amount designated as the margin in a split payment. This field is formatted as a double, and will be rounded to two decimal places. The value must be less than the total value of the split. This specifies the portion of the funds that should be routed to the margin account.", "example": 1.25 } } } } } } }, "payment_type": { "type": "string", "description": "Specifies the type of payment processed. Possible values include:\n- **Single:** A one-time payment transaction.\n- **Frequent:** A payment that occurs regularly but is not part of a subscription (e.g., recurring manual payments).\n- **Subscription:** A recurring payment that is part of a subscription plan, automatically processed at regular intervals. This field helps to categorize and manage different payment methods based on their frequency and nature.\n" }, "payment_id": { "type": "string", "format": "uuid", "description": "A unique identifier for the payment. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "descriptive": { "type": "string", "description": "Description about the capture." }, "value": { "type": "number", "format": "float", "example": 10.86, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places. The value must be greater than or equal to 0.5." }, "force_3ds": { "type": "boolean", "description": "Whether or not you want to force the 3DS authentication.", "default": false }, "reward_redemption": { "type": "object", "description": "Reward credits redeemed in the original capture. Present only when the capture redeemed reward credits. See the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for the full flow.", "properties": { "account": { "type": "object", "description": "The reward account the credits were debited from.", "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "value": { "type": "number", "format": "double", "description": "The redeemed reward amount.", "example": 2.5 } } } } } } }, "refund-post-request": { "title": "RefundPostRequestBody", "type": "object", "required": [ "value" ], "properties": { "transaction_key": { "type": "string", "maxLength": 50, "description": "Your internal key identifying this refund" }, "iban": { "type": "string", "maxLength": 34, "description": "Optional - Iban from the bank account" }, "email": { "type": "string", "maxLength": 50, "description": "Optional - Email from the bank account holder" }, "phone": { "type": "string", "maxLength": 20, "description": "Optional - Phone from the bank account holder" }, "account_holder": { "type": "string", "maxLength": 40, "description": "Optional - Bank account holder name" }, "value": { "type": "number", "format": "double", "minimum": 0.01, "example": 17.5, "description": "The amount to refund. When `revert` is present, this is the gross amount from the payer's perspective — the amount refunded to the payment method plus any redeemed reward credits being restored." }, "revert": { "type": "object", "description": "Reverts refers to the process of reversing a previously made split payment. This means that the amounts that were divided and allocated to different recipients or accounts are returned to the original payer or redistributed as per the new instructions.", "properties": { "mode": { "description": "- **TOTAL:** All associated splits and their margins will be reverted - **PARTIAL:** Only the selected splits and their margins will be reverted", "enum": [ "partial", "total" ] }, "reward_redemption_reversal": { "type": "number", "format": "double", "example": 2.5, "description": "The portion of the refund value to restore to the customer's reward balance instead of refunding it to the payment method — the payment method receives the refund value minus this amount. Only valid when the capture redeemed reward credits, and it can exceed neither the refund value nor the redemption not yet restored by previous refunds. On a TOTAL revert it must equal the remaining redemption, and defaults to it when omitted; on captures fully paid with reward credits it defaults to the refund value. Otherwise, omitting the field restores nothing. The restored credit lands on the customer's reward ledger as a `REWARD_RESTORATION` entry on `GET /customer/{id}/rewards`. See the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for the full flow." }, "splits": { "type": "array", "description": "Array of splits to revert. Required only if the mode is PARTIAL.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The uuid of split." } } } } } } } }, "refund-post-response": { "title": "RefundPostSuccessResponse", "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "string", "example": "Your request was successfully created" }, "id": { "type": "string", "format": "uuid", "example": "25997c28-1902-4f6d-842e-c6050e7d5421", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." } } }, "chargeback-list-response": { "title": "Chargeback", "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "created_at": { "type": "string", "description": "The timestamp indicating when the resource was created. It is formatted as \"YYYY-MM-DD HH:MM\".", "example": "2006-01-02 15:04" }, "message": { "type": "string", "description": "The message field provides a human-readable explanation of the chargeback reason code, making it easier to understand the cause of the dispute without needing to interpret technical codes. This message clarifies the issue, such as incorrect account information, insufficient funds, or unauthorized transactions, and helps merchants quickly identify the nature of the problem.", "example": "MD06 - Refund Request by End Customer" }, "code": { "type": "string", "description": "The code field provides the specific SEPA or Visa/Masterd code associated with the chargeback. This code identifies the reason for the chargeback, offering insight into why the transaction was disputed by the consumer's bank or card issuer.\nSEPA reasons:\n - **AC01**: Incorrect Account Number\n - **AC04**: Closed Account Number\n - **AC06**: Blocked Account\n - **AC13**: Invalid Debitor Account Type\n - **AG01**: Transaction Forbidden\n - **AG02**: Invalid Bank Operation Code\n - **AM04**: Insufficient Funds\n - **AM05**: Duplication\n - **BE05**: Unrecognised Initiating Party\n - **CNOR**: Creditor Bank is Not Registered\n - **DNOR**: Debitor Bank is Not Registered\n - **ED05**: Settlement Failed\n - **FF01**: Invalid File Format\n - **MD01**: No Mandate\n - **MD02**: Missing Mandatory Mandate Information\n - **MD06**: Refund Request by End Customer\n - **MD07**: End Customer Deceased\n - **MS02**: Not Specified Reason Customer Generated\n - **MS03**: Not Specified Reason Agent Generated\n - **RC01**: Bank Identifier Incorrect\n - **RR01**: Missing Debitor Account Or Identification\n - **RR02**: Missing Debitor Name Or Address\n - **RR03**: Missing Creditor Name or Address\n - **RR04**: Regulatory Reason\n - **SL01**: Specific Service Offered By Debitor Agent\nVisa Reasons:\n - **10.1**: EMV Liability Shift Counterfeit Fraud\n - **10.2**: EMV Liability Shift Non-Counterfeit Fraud\n - **10.3**: Other Fraud, Card-Present Environment\n - **10.4**: Other Fraud, Card-Absent Environment\n - **10.5**: Visa Fraud Monitoring Program\n - **11.1**: Card Recovery Bulletin\n - **11.2**: Declined Authorization\n - **11.3**: No Authorization\n - **12.1**: Late Presentment\n - **12.2**: Incorrect Transaction Code\n - **12.3**: Incorrect Currency\n - **12.4**: Incorrect Account Number\n - **12.5**: Incorrect Amount\n - **12.6**: Duplicate Processing / Paid By Other Means\n - **12.7**: Invalid Data\n - **13.1**: Merchandise / Services Not Received\n - **13.2**: Cancelled Recurring Transaction\n - **13.3**: Not As Described Or Defective Merchandise / Services\n - **13.4**: Counterfeit Merchandise\n - **13.5**: Misrepresentation\n - **13.6**: Credit Not Processed\n - **13.7**: Cancelled Merchandise / Services\n - **13.8**: Original Credit Transaction Not Accepted\n - **13.9**: Non-Receipt of Cash or Load Transaction Value\n\nMastercard reasons:\n - **4837**: No Cardholder Authorization\n - **4840**: Fraudulent Processing Of Transactions\n - **4849**: Questionable Merchant Activity - Global Merchant Audit Program (GMAP)\n - **4849**: Questionable Merchant Activity - Mastercard Rule 3.7 Violation for Coercion Claim\n - **4849**: Questionable Merchant Activity - Questionable Merchant Audit Program (QMAP)\n - **4863**: Cardholder Does Not Recognize, Potential Fraud\n - **4870**: EMV Chip Liability Shift\n - **4871**: Chip Liability Shift – Lost / Stolen / Never Received Fraud\n - **4807**: Warning Bulletin\n - **4808**: Authorization Chargeback - Cardholder-Activated Terminal (CAT) 3 Device\n - **4808**: Authorization Chargeback - Expired Chargeback Protection Period\n - **4808**: Authorization Chargeback - Multiple Authorization Requests\n - **4808**: Authorization Chargeback - Required Authorization Not Obtained\n - **4812**: Account Number Not On File\n - **4853**: Cardholder Dispute - Credit Posted as a Purchase\n - **4853**: Cardholder Dispute - Digital Goods Purchase of $25 or Less\n - **4853**: Cardholder Dispute - Goods or Services Not as Described or Defective\n - **4853**: Cardholder Dispute - Goods or Services Not Provided\n - **4853**: Cardholder Dispute - Issuer Dispute of a Recurring Transaction\n - **4853**: Cardholder Dispute - Timeshares\n - **4853**: Cardholder Dispute - \"No Show\" Hotel Charge\n - **4853**: Cardholder Dispute - Transaction Did Not Complete\n - **4853**: Cardholder Dispute - Addendum Dispute\n - **4853**: Cardholder Dispute - Cardholder Dispute of a Recurring Transaction\n - **4853**: Cardholder Dispute - Counterfeit Goods\n - **4853**: Cardholder Dispute - Credit Not Processed\n - **4855**: Goods or Services Not Provided\n - **4859**: Addendum, No-Show, or ATM Dispute (Europe)\n - **4859**: Addendum, No-Show, or ATM Dispute (Non-European Bank)\n - **4860**: Credit Not Processed\n - **4831**: Incorrect Transaction Amount\n - **4834**: POI Error - Charges for Loss, Theft, or Damages\n - **4834**: POI Error - Late Presentment\n - **4834**: POI Error - Merchant Credit Correcting Error, Cardholder Currency Exchange Loss\n - **4834**: POI Error - Transaction Amount Differs\n - **4834**: POI Error - Currency Conversion (Dynamic Currency Conversion)\n - **4834**: POI Error - Unreasonable Amount (Europe)\n - **4834**: POI Error - ATM Disputes\n - **4834**: POI Error - Cardholder Debited More than Once\n - **4841**: Canceled Recurring or Digital Goods Transactions\n - **4842**: Late Presentment (Europe)\n - **4842**: Late Presentment (Non-European Banks)\n - **4846**: Correct Transaction Currency Code Not Provided / Currency Errors (Non-European Bank)\n - **4846**: Correct Transaction Currency Code Not Provided / Currency Error (Europe)", "example": "MD06" }, "amount": { "type": "number", "format": "double", "minimum": 0.5, "example": 12.87, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places. The value must be greater than or equal to 0.5." }, "capture": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "payment_id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "payment_type": { "type": "string", "enum": [ "single", "frequent", "subscription" ], "description": "Specifies the type of payment processed. Possible values include:\n\n- Single: A one-time payment transaction.\n- Frequent: A payment that occurs regularly but is not part of a subscription (e.g., recurring manual payments).\n- Subscription: A recurring payment that is part of a subscription plan, automatically processed at regular intervals.\n\nThis field helps to categorize and manage different payment methods based on their frequency and nature." } } } } } }, "metadata": { "$ref": "#/components/schemas/metadata-cursor" } } }, "chargeback-get-by-id-response": { "title": "ChargebackDetailsSuccessResponse", "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "created_at": { "type": "string", "description": "The timestamp indicating when the resource was created. It is formatted as \"YYYY-MM-DD HH:MM\".", "example": "2006-01-02 15:04" }, "message": { "type": "string", "description": "The message field provides a human-readable explanation of the chargeback reason code, making it easier to understand the cause of the dispute without needing to interpret technical codes. This message clarifies the issue, such as incorrect account information, insufficient funds, or unauthorized transactions, and helps merchants quickly identify the nature of the problem.", "example": "MD06 - Refund Request by End Customer" }, "code": { "type": "string", "description": "The code field provides the specific SEPA or Visa/Masterd code associated with the chargeback. This code identifies the reason for the chargeback, offering insight into why the transaction was disputed by the consumer's bank or card issuer.\nSEPA reasons:\n - **AC01**: Incorrect Account Number\n - **AC04**: Closed Account Number\n - **AC06**: Blocked Account\n - **AC13**: Invalid Debitor Account Type\n - **AG01**: Transaction Forbidden\n - **AG02**: Invalid Bank Operation Code\n - **AM04**: Insufficient Funds\n - **AM05**: Duplication\n - **BE05**: Unrecognised Initiating Party\n - **CNOR**: Creditor Bank is Not Registered\n - **DNOR**: Debitor Bank is Not Registered\n - **ED05**: Settlement Failed\n - **FF01**: Invalid File Format\n - **MD01**: No Mandate\n - **MD02**: Missing Mandatory Mandate Information\n - **MD06**: Refund Request by End Customer\n - **MD07**: End Customer Deceased\n - **MS02**: Not Specified Reason Customer Generated\n - **MS03**: Not Specified Reason Agent Generated\n - **RC01**: Bank Identifier Incorrect\n - **RR01**: Missing Debitor Account Or Identification\n - **RR02**: Missing Debitor Name Or Address\n - **RR03**: Missing Creditor Name or Address\n - **RR04**: Regulatory Reason\n - **SL01**: Specific Service Offered By Debitor Agent\nVisa Reasons:\n - **10.1**: EMV Liability Shift Counterfeit Fraud\n - **10.2**: EMV Liability Shift Non-Counterfeit Fraud\n - **10.3**: Other Fraud, Card-Present Environment\n - **10.4**: Other Fraud, Card-Absent Environment\n - **10.5**: Visa Fraud Monitoring Program\n - **11.1**: Card Recovery Bulletin\n - **11.2**: Declined Authorization\n - **11.3**: No Authorization\n - **12.1**: Late Presentment\n - **12.2**: Incorrect Transaction Code\n - **12.3**: Incorrect Currency\n - **12.4**: Incorrect Account Number\n - **12.5**: Incorrect Amount\n - **12.6**: Duplicate Processing / Paid By Other Means\n - **12.7**: Invalid Data\n - **13.1**: Merchandise / Services Not Received\n - **13.2**: Cancelled Recurring Transaction\n - **13.3**: Not As Described Or Defective Merchandise / Services\n - **13.4**: Counterfeit Merchandise\n - **13.5**: Misrepresentation\n - **13.6**: Credit Not Processed\n - **13.7**: Cancelled Merchandise / Services\n - **13.8**: Original Credit Transaction Not Accepted\n - **13.9**: Non-Receipt of Cash or Load Transaction Value\n\nMastercard reasons:\n - **4837**: No Cardholder Authorization\n - **4840**: Fraudulent Processing Of Transactions\n - **4849**: Questionable Merchant Activity - Global Merchant Audit Program (GMAP)\n - **4849**: Questionable Merchant Activity - Mastercard Rule 3.7 Violation for Coercion Claim\n - **4849**: Questionable Merchant Activity - Questionable Merchant Audit Program (QMAP)\n - **4863**: Cardholder Does Not Recognize, Potential Fraud\n - **4870**: EMV Chip Liability Shift\n - **4871**: Chip Liability Shift – Lost / Stolen / Never Received Fraud\n - **4807**: Warning Bulletin\n - **4808**: Authorization Chargeback - Cardholder-Activated Terminal (CAT) 3 Device\n - **4808**: Authorization Chargeback - Expired Chargeback Protection Period\n - **4808**: Authorization Chargeback - Multiple Authorization Requests\n - **4808**: Authorization Chargeback - Required Authorization Not Obtained\n - **4812**: Account Number Not On File\n - **4853**: Cardholder Dispute - Credit Posted as a Purchase\n - **4853**: Cardholder Dispute - Digital Goods Purchase of $25 or Less\n - **4853**: Cardholder Dispute - Goods or Services Not as Described or Defective\n - **4853**: Cardholder Dispute - Goods or Services Not Provided\n - **4853**: Cardholder Dispute - Issuer Dispute of a Recurring Transaction\n - **4853**: Cardholder Dispute - Timeshares\n - **4853**: Cardholder Dispute - \"No Show\" Hotel Charge\n - **4853**: Cardholder Dispute - Transaction Did Not Complete\n - **4853**: Cardholder Dispute - Addendum Dispute\n - **4853**: Cardholder Dispute - Cardholder Dispute of a Recurring Transaction\n - **4853**: Cardholder Dispute - Counterfeit Goods\n - **4853**: Cardholder Dispute - Credit Not Processed\n - **4855**: Goods or Services Not Provided\n - **4859**: Addendum, No-Show, or ATM Dispute (Europe)\n - **4859**: Addendum, No-Show, or ATM Dispute (Non-European Bank)\n - **4860**: Credit Not Processed\n - **4831**: Incorrect Transaction Amount\n - **4834**: POI Error - Charges for Loss, Theft, or Damages\n - **4834**: POI Error - Late Presentment\n - **4834**: POI Error - Merchant Credit Correcting Error, Cardholder Currency Exchange Loss\n - **4834**: POI Error - Transaction Amount Differs\n - **4834**: POI Error - Currency Conversion (Dynamic Currency Conversion)\n - **4834**: POI Error - Unreasonable Amount (Europe)\n - **4834**: POI Error - ATM Disputes\n - **4834**: POI Error - Cardholder Debited More than Once\n - **4841**: Canceled Recurring or Digital Goods Transactions\n - **4842**: Late Presentment (Europe)\n - **4842**: Late Presentment (Non-European Banks)\n - **4846**: Correct Transaction Currency Code Not Provided / Currency Errors (Non-European Bank)\n - **4846**: Correct Transaction Currency Code Not Provided / Currency Error (Europe)", "example": "MD06" }, "amount": { "type": "number", "format": "double", "minimum": 0.5, "example": 12.87, "description": "The monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places. The value must be greater than or equal to 0.5." }, "capture": { "type": "object", "properties": { "id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "payment_id": { "type": "string", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "payment_type": { "type": "string", "enum": [ "SINGLE", "FREQUENT", "SUBSCRIPTION" ], "description": "Specifies the type of payment processed. Possible values include:\n\n- Single: A one-time payment transaction.\n- Frequent: A payment that occurs regularly but is not part of a subscription (e.g., recurring manual payments).\n- Subscription: A recurring payment that is part of a subscription plan, automatically processed at regular intervals.\n\nThis field helps to categorize and manage different payment methods based on their frequency and nature." } } } } }, "payment-methods-response": { "title": "PBL-Payment-Methods", "type": "array", "description": "All the payment methods available to create a pay-by-link payment.", "items": { "type": "string", "enum": [ "MB", "MBW", "DD", "CC", "VI", "AP", "GP", "SW" ], "example": "MBW" } }, "status-response": { "title": "Status", "type": "string", "description": "The current state of the payment link. A link starts out ACTIVE, turns EXPIRED once its expiration time passes, becomes FINALIZED after it has been paid, and moves to CANCELLED when you delete it.", "enum": [ "ACTIVE", "EXPIRED", "FINALIZED", "CANCELLED" ] }, "payment-types-response": { "title": "PayByLinkPaymentTypes", "type": "string", "enum": [ "SINGLE", "FREQUENT", "SUBSCRIPTION" ], "description": "" }, "customer-response": { "title": "Customer", "type": "object", "description": "The Customer object contains detailed information about the customer required to create a pay-by-link.", "required": [ "name" ], "properties": { "name": { "type": "string", "example": "Jonh Doe", "description": "The full name of the customer. This field is used to identify the customer and personalize interactions. It typically includes the customer's first name and last name." }, "email": { "type": "string", "format": "email", "example": "example@easypay.pt", "description": "The email address of the customer. This field is used for communication purposes, including sending transaction confirmations, receipts, and other notifications related to the customer's activities. Omitted when the link was created without a customer email." }, "phone": { "type": "string", "example": "+351911234567", "description": "The contact phone number of the customer, in the E.164 pattern and including the country code indicator (e.g., \"+351\"). This field is used for communication purposes. If the payment method is MB WAY, the phone is required and is used to send the MB WAY push notification. Omitted when the link was created without a customer phone." } } }, "communication-channels-response": { "title": "Communication-Channels", "type": "array", "description": "The communication channels the final customer link was forwarded to. Always present, and empty when the link was created without any channel.", "items": { "type": "string", "enum": [ "SMS", "EMAIL" ], "example": "SMS" } }, "capture-response": { "title": "Capture", "type": "object", "properties": { "descriptive": { "type": "string", "description": "A customizable text field for users to input some descriptive associated with this capture operation." }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system." } } }, "single-response": { "title": "Single", "type": "object", "description": "Single object with all the fields necessary after creating a Pay-by-Link request.", "required": [ "requested_amount" ], "properties": { "requested_amount": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "description": "String representing the monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places.", "example": "10.45" } } }, "frequent-response": { "type": "object", "description": "Frequent object with all the fields necessary after creating a Pay-by-Link request.", "required": [ "minimum_amount", "maximum_amount", "unlimited_payments" ], "properties": { "minimum_amount": { "type": "string", "description": "Minimum value available to create a Pay-by-link request.", "example": "5" }, "maximum_amount": { "type": "string", "description": "Maximum value available to create a Pay-by-link request.", "example": "10" }, "unlimited_payments": { "type": "boolean", "description": "Determines whether payments can be unlimited." } } }, "subscription-response": { "type": "object", "description": "Subscription object with all the fields necessary after creating a Pay-by-Link request.", "required": [ "frequency", "maximum_captures", "start_time", "capture_now", "retries", "failover" ], "properties": { "frequency": { "type": "string", "enum": [ "1D", "1W", "2W", "1M", "2M", "3M", "4M", "6M", "1Y", "2Y", "3Y" ], "description": "Determines how often the subscription payment is made." }, "maximum_captures": { "type": "integer", "example": 100, "description": "The maximum number of captures for this subscription." }, "start_time": { "type": "string", "format": "date", "description": "The start date of the billing cycles for this subscription.", "example": "2025-01-15" }, "capture_now": { "type": "boolean", "description": "Whether an immediate capture was performed. If this value is true, an immediate capture was performed and the second capture will be on the date in the start_time field." }, "retries": { "type": "integer", "description": "Number of retries in each payment cycle." }, "failover": { "type": "boolean", "default": false, "description": "After all retries failed, the payment cycle can have another try with another single method." } } }, "link-response-object": { "title": "Link", "type": "object", "required": [ "id", "created_at", "expiration_time", "type", "communication_channels", "customer", "payment", "url", "image", "status" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.", "readOnly": true }, "created_at": { "type": "string", "description": "String with the date on which this Pay By Link was created.", "example": "2025-06-16T13:32:32Z", "format": "date-time", "readOnly": true }, "modified_at": { "type": "string", "description": "String with the date on which this Pay By Link was modified. Omitted while the link has never been modified.", "example": "2025-06-16T13:32:32Z", "format": "date-time", "readOnly": true }, "expiration_time": { "type": "string", "format": "date-time", "description": "The last possible time to make the payment.", "example": "2026-06-10T09:27:55Z" }, "type": { "$ref": "#/components/schemas/payment-types-response", "description": "Specifies the type of payment being performed. Possible values are \"Single\" (One-time transactions that will let your customers pay an amount of money to you), \"Frequent\" (Are repeatable transactions of varying sums without the client having to enter their payment details again), and \"Subscription\" (periodic payments of the same amount of money, configured through Checkout or our Payments API)." }, "customer": { "$ref": "#/components/schemas/customer-response" }, "communication_channels": { "$ref": "#/components/schemas/communication-channels-response" }, "payment": { "type": "object", "description": "Payment object with the payment methods, capture object and payment type object. Only the payment type you asked for is present.", "required": [ "methods" ], "properties": { "id": { "type": "string", "description": "Identifier of the payment behind this link. Omitted until the payment has been created." }, "methods": { "$ref": "#/components/schemas/payment-methods-response" }, "capture": { "$ref": "#/components/schemas/capture-response" }, "single": { "$ref": "#/components/schemas/single-response" }, "frequent": { "$ref": "#/components/schemas/frequent-response" }, "subscription": { "$ref": "#/components/schemas/subscription-response" } } }, "url": { "type": "string", "format": "uri", "example": "https://easypay.pt/s/XStDvnMKZaN", "description": "Link that redirects to the Easypay checkout payment page." }, "image": { "type": "string", "format": "uri", "example": "https://cdn.easypay.pt/images/qr/XStDvnMKZaN", "description": "Link that redirects to a QR code to access the payment checkout page." }, "status": { "$ref": "#/components/schemas/status-response", "description": "All the payment status after creating a pay-by-link payment." } } }, "invalid-params-response": { "title": "PayByLinkInvalidParamsResponse", "type": "object", "required": [ "name", "reason" ], "properties": { "name": { "type": "string", "description": "Name of the payload field that contains an error.", "example": "expiration_time" }, "reason": { "type": "string", "description": "Reason why this payload field contains an error.", "example": "expiration_time should be formatted as RFC 3339 and in the future" } } }, "bad-request-response": { "title": "PayByLinkBadRequestResponse", "type": "object", "required": [ "type", "title", "detail", "status" ], "properties": { "type": { "type": "string", "description": "Link that redirects to the API documentation.", "example": "https://docs.easypay.pt/docs/error-handling#invalid-params-error-400" }, "title": { "type": "string", "example": "Invalid payload provided", "description": "Brief title about the error." }, "detail": { "type": "string", "example": "Your request parameters didn't validate", "description": "Brief description about the error." }, "status": { "type": "number", "default": 400, "description": "API error code." }, "invalid_params": { "type": "array", "description": "One entry for each payload field that failed validation. Omitted when the request failed for a reason that isn't tied to a specific field.", "items": { "$ref": "#/components/schemas/invalid-params-response" } } } }, "forbidden-response": { "title": "PayByLinkForbiddenResponse", "type": "object", "required": [ "type", "title", "detail", "status" ], "properties": { "type": { "type": "string", "description": "Link that redirects to the API documentation.", "example": "https://docs.easypay.pt/docs/error-handling#authentication-error-403" }, "title": { "type": "string", "example": "Forbidden", "description": "Brief title about the error." }, "detail": { "type": "string", "example": "Authentication failed", "description": "Brief description about the error." }, "status": { "type": "number", "default": 403, "description": "API error code." } } }, "conflict-response": { "title": "PayByLinkConflictResponse", "type": "object", "required": [ "title", "detail", "status" ], "properties": { "title": { "type": "string", "example": "Conflict with the current state of the target resource", "description": "Brief title about the error." }, "detail": { "type": "string", "example": "conflict with the resource's current state", "description": "Brief description about the error." }, "status": { "type": "number", "default": 409, "description": "API error code." } } }, "internal-server-error-response": { "title": "PayByLinkInternalServerErrorResponse", "type": "object", "required": [ "type", "title", "detail", "status" ], "properties": { "type": { "type": "string", "description": "Link that redirects to the API documentation.", "example": "https://docs.easypay.pt/docs/error-handling#internal-error-500" }, "title": { "type": "string", "example": "An unexpected error has occurred", "description": "Brief title about the error." }, "detail": { "type": "string", "example": "An unexpected error has occurred, try again later if the error persists please contact correio@easypay.pt", "description": "Brief description about the error." }, "status": { "type": "number", "default": 500, "description": "API error code." } } }, "payment-types-request": { "title": "PayByLinkPaymentTypes", "type": "string", "enum": [ "SINGLE", "FREQUENT", "SUBSCRIPTION" ], "description": "" }, "customer-request": { "title": "Customer", "type": "object", "description": "The Customer object contains detailed information about the customer required to create a pay-by-link.", "required": [ "name", "language" ], "properties": { "name": { "type": "string", "example": "Jonh Doe", "description": "The full name of the customer. This field is used to identify the customer and personalize interactions. It typically includes the customer's first name and last name.", "maxLength": 255 }, "email": { "type": "string", "format": "email", "example": "example@easypay.pt", "maxLength": 70, "description": "The email address of the customer. This field is used for communication purposes, including sending transaction confirmations, receipts, and other notifications related to the customer's activities.\nAlso, this email will be used to send the payment link if the EMAIL channel was requested in the communication channels.\nOptional, but required when the EMAIL communication channel or the notification customer_method_instructions_email is requested. When omitted, it is collected from the customer on the checkout page." }, "phone": { "type": "string", "example": "+351911234567", "description": "The contact phone number of the customer, in the E.164 pattern. This number will be used to make the payment if the method is MB WAY and to send the payment link if the SMS channel was requested in the communication channels.\nOptional, but required when the SMS communication channel is requested. When omitted, it is collected from the customer on the checkout page.", "pattern": "^\\+[1-9]\\d{1,14}$", "maxLength": 16 }, "language": { "type": "string", "description": "The language preference of the customer, specified in the ISO 639-1 Alpha-2 format (e.g., \"EN\" for English, \"PT\" for Portuguese). This field is used to indicate the customer's preferred language for communication and documentation.", "enum": [ "PT", "EN", "ES" ], "minLength": 2, "maxLength": 2 } } }, "communication-channels-request": { "title": "Communication-Channels", "type": "array", "description": "The communication channels specifies where the final customer link should be forwarded. Optional, leave it out and we won't send the link anywhere, so it is up to you to hand it to your customer. Asking for EMAIL requires the customer email, and asking for SMS requires the customer phone.", "items": { "type": "string", "enum": [ "SMS", "EMAIL" ], "example": "SMS" } }, "payment-methods-request": { "title": "PBL-Payment-Methods", "type": "array", "description": "All the payment methods available to create a pay-by-link payment.", "minItems": 1, "items": { "type": "string", "enum": [ "MB", "MBW", "DD", "CC", "VI", "AP", "GP", "SW" ], "example": "MBW" } }, "capture-request": { "title": "Capture", "type": "object", "properties": { "descriptive": { "type": "string", "description": "A customizable text field for users to input some descriptive associated with this capture operation.", "maxLength": 255 }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.", "maxLength": 50 } }, "description": "Capture object with all the fields necessary to create a Pay-by-Link request" }, "single-request": { "title": "Single", "type": "object", "description": "Single object with all the fields necessary to create a Pay-by-Link request.", "required": [ "requested_amount" ], "properties": { "requested_amount": { "type": "string", "pattern": "^\\d+(\\.\\d{1,2})?$", "description": "String representing the monetary amount requested for the transaction. This field is formatted as a double, and will be rounded to two decimal places. The smallest amount you can ask for is €0.50.", "example": "10.45" } } }, "frequent-request": { "type": "object", "description": "This frequent object is not implemented yet. For now, we can only use Pay By Link with Single payments.", "required": [ "minimum_amount", "maximum_amount", "unlimited_payments" ], "properties": { "minimum_amount": { "type": "string", "description": "Minimum value available to create a Pay-by-link request." }, "maximum_amount": { "type": "string", "description": "Maximum value available to create a Pay-by-link request." }, "unlimited_payments": { "type": "boolean", "description": "Determines whether payments can be unlimited." } } }, "subscription-request": { "type": "object", "description": "This subscription object is not implemented yet. For now, we can only use Pay By Link with Single payments.", "required": [ "frequency", "start_time" ], "properties": { "frequency": { "type": "string", "enum": [ "1D", "1W", "2W", "1M", "2M", "3M", "4M", "6M", "1Y", "2Y", "3Y" ], "description": "Determines how often the subscription payment is made." }, "maximum_captures": { "type": "integer", "example": 100, "description": "Determines the maximum number of captures for this subscription.\n**It's only required when no expiration_time is set.**" }, "start_time": { "type": "string", "format": "date", "description": "Determines the start date of billing cycles for this subscription. This date must be always in the future.", "example": "2025-01-15" }, "capture_now": { "type": "boolean", "description": "Determines whether an immediate capture is performed. If this value is true, an immediate capture will be performed and the second capture will be on the date entered in the start_time field." }, "retries": { "type": "integer", "description": "Number of retries in each payment cycle.\nThe chosen frequency will define the max number of possible retries." }, "failover": { "type": "boolean", "default": false, "description": "After all retries failed, the payment cycle can have another try with another single method." }, "expiration_time": { "type": "string", "format": "date", "description": "The date the subscription expires, and it can't go past the year 2037.\n**Required if maximum_captures is not defined.**", "example": "2030-01-15" } } }, "notification-request": { "title": "Notification", "type": "object", "description": "Opt-in notification preferences for the link. When enabled, the customer receives an email with the payment instructions after choosing the method on the Pay by Link page. You can only set this when you create the link. It isn't returned with the link and you can't change it later.", "properties": { "customer_method_instructions_email": { "type": "boolean", "default": false, "description": "When true, sends the payment-instructions email to the customer. Requires the customer name, email and language to be present." } } }, "not-implemented-response": { "title": "PayByLinkNotImplementedResponse", "type": "object", "required": [ "title", "detail", "status" ], "properties": { "title": { "type": "string", "example": "The feature you tried to use is not implemented", "description": "Brief title about the error." }, "detail": { "type": "string", "example": "Subscriptions and Frequents are not yet available", "description": "Brief description about the error." }, "status": { "type": "number", "default": 501, "description": "API error code." } } }, "not-found-response": { "title": "PayByLinkNotFoundResponse", "type": "object", "required": [ "title", "detail", "status" ], "properties": { "title": { "type": "string", "example": "Not Found", "description": "Brief title about the error." }, "detail": { "type": "string", "example": "no link found with the provided id", "description": "Brief description about the error." }, "status": { "type": "number", "default": 404, "description": "API error code." } } }, "customer-detail": { "type": "object", "description": "The Customer object contains detailed information about the customer, including reward balances.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer.", "example": "649e88cf-0b78-4c36-8f99-33f5ebb812a1" }, "name": { "type": "string", "description": "Full name of the customer.", "maxLength": 255, "example": "John Doe" }, "email": { "type": "string", "format": "email", "description": "Customer's email address.", "maxLength": 70, "example": "john.doe@example.com" }, "phone": { "type": "string", "description": "The contact phone number of the customer, excluding the country code indicator.", "maxLength": 15, "example": "911234567" }, "phone_indicative": { "type": "string", "description": "The country code indicator for the customer's phone number.", "maxLength": 5, "example": "+351" }, "fiscal_number": { "type": "string", "description": "Customer's tax identification number or fiscal number.", "maxLength": 20, "example": "PT123456789" }, "key": { "type": "string", "description": "A customizable text field for users to input their own identifier for the customer.", "maxLength": 255, "example": "customer Key Example" }, "language": { "type": "string", "description": "Preferred language for customer communications. Uses ISO 639-1 language codes.", "maxLength": 2, "minLength": 2, "enum": [ "PT", "EN", "ES" ], "example": "PT" }, "reward_balances": { "type": "array", "description": "Reward balances across all reward accounts for this customer. Empty array if no reward accounts exist. See the [Rewards & Redemptions guide](/docs/guides/rewards-and-redemptions) for the full flow.", "items": { "type": "object", "properties": { "account_id": { "type": "string", "format": "uuid", "description": "The unique identifier of the reward account.", "example": "458b2fc4-3092-4de3-abd4-fe1600c09420" }, "available_balance": { "type": "number", "description": "The available reward balance for this account.", "example": 12.5 } } } } } }, "reward-ledger-entry": { "type": "object", "description": "A single movement on a customer's reward ledger. Each entry represents a reward earned (`type: REWARD`), a redemption against a reward (`type: REDEMPTION`), an unused reward swept at its expiry date (`type: REWARD_EXPIRATION`), a reward taken back after the earning capture was refunded or charged back (`type: REWARD_REVERSAL`), or a redemption given back as fresh credit after a refund or chargeback (`type: REWARD_RESTORATION`).", "required": [ "id", "account_id", "type", "amount", "created_at" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the ledger entry.", "example": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "account_id": { "type": "string", "format": "uuid", "description": "The reward account this entry belongs to.", "example": "458b2fc4-3092-4de3-abd4-fe1600c09420" }, "type": { "type": "string", "description": "The kind of movement. `REWARD` for credits earned; `REDEMPTION` for credits consumed; `REWARD_EXPIRATION` for unused credits removed from the balance at their expiry date; `REWARD_REVERSAL` for credits taken back when the capture that earned them was refunded or charged back; `REWARD_RESTORATION` for credits given back when a redemption is undone — either by a refund created with `revert.reward_redemption_reversal` or by a chargeback on the capture that redeemed them.", "enum": [ "REWARD", "REDEMPTION", "REWARD_EXPIRATION", "REWARD_REVERSAL", "REWARD_RESTORATION" ], "example": "REWARD" }, "amount": { "type": "number", "description": "The absolute value of the movement. Always positive; `type` signals direction.", "example": 10 }, "expiration_date": { "type": "string", "format": "date", "description": "The date after which the reward expires. Present when `type` is `REWARD`, `REWARD_EXPIRATION` or `REWARD_RESTORATION`.", "example": "2027-01-15" }, "capture": { "type": "object", "description": "The capture associated with this entry — the capture that granted the credit (`type: REWARD`, `type: REWARD_EXPIRATION` and `type: REWARD_REVERSAL`) or the capture that consumed it (`type: REDEMPTION` and `type: REWARD_RESTORATION`). Omitted when the entry is not linked to a capture (e.g. orphaned splits).", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier of the capture.", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" } } }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the movement occurred.", "example": "2026-01-15T10:30:00Z" } } }, "terminal": { "type": "object", "description": "Terminal (POS) object representing a payment terminal device.", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the terminal.", "example": "458b2fc4-3092-4de3-abd4-fe1600c09420" }, "serial_number": { "type": "string", "description": "The serial number of the terminal device. Unique per acquirer.", "example": "123-456-789" }, "name": { "type": "string", "description": "The name of the terminal. Must be unique.", "example": "Terminal Checkout 1" }, "status": { "type": "string", "enum": [ "ACTIVE", "INACTIVE", "DELETED" ], "description": "The current status of the terminal. Determined by the device state.", "example": "ACTIVE" }, "acquirer": { "type": "string", "enum": [ "VERIFONE" ], "description": "The acquirer associated with the terminal.", "example": "VERIFONE" }, "model": { "type": "string", "description": "The model of the terminal device. Inferred from the serial number.", "example": "V240m" }, "last_transaction_at": { "type": [ "string", "null" ], "format": "date-time", "description": "The date and time of the last transaction processed by the terminal. Null if no transactions have been processed.", "example": "2025-08-05T13:44:29Z" }, "created_at": { "type": "string", "format": "date-time", "description": "The date and time when the terminal was created.", "example": "2025-08-05T13:44:29Z" } } }, "notification-generic": { "type": "object", "properties": { "id": { "type": "string", "description": "ID of the related notified resource", "format": "uuid", "example": "1bbc14c3-8ca8-492c-887d-1ca86400e4fa" }, "key": { "type": "string", "description": "Merchant identification key", "example": "Example Key" }, "type": { "type": "string", "example": "capture", "enum": [ "authorisation", "capture", "frequent_create", "void", "refund", "chargeback", "subscription_create", "subscription_capture", "out_payment" ] }, "status": { "type": "string", "example": "success", "enum": [ "failed", "success" ] }, "messages": { "type": "array", "items": { "type": "string", "example": "Your request was successfully created" } }, "date": { "type": "string", "example": "2022-01-01 10:20:30" } } }, "notification-authorisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the notification", "example": "131d25c8-404d-4075-a264-67091620b0b3" }, "value": { "type": "string", "description": "The monetary amount", "example": "10.5" }, "currency": { "type": "string", "description": "ISO 4217 currency code", "example": "EUR" }, "key": { "type": "string", "description": "Merchant identification key", "example": "Example Key" }, "expiration_time": { "type": "string", "format": "date-time", "description": "The expiration time for the payment", "example": "2025-12-26T10:32:45Z" }, "method": { "type": "string", "description": "Payment method used", "example": "MBW" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "00ef522f-6a34-4d03-8448-834830cabb91" }, "name": { "type": "string", "example": "Josefa Gomes" }, "email": { "type": "string", "format": "email", "example": "customer@example.com" }, "phone": { "type": "string", "example": "921234567" }, "phone_indicative": { "type": "string", "example": "+351" }, "fiscal_number": { "type": "string", "example": "PT123456789" }, "key": { "type": "string", "example": "Customer Key" } } }, "account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "131d25c8-404d-4075-a264-67091620b066" } } }, "authorisation": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "131d25c8-404d-4075-a264-67091620b0b3" } } } } }, "notification-capture": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier for the notification", "example": "ad3a0bb3-15a0-462c-8049-4abeb2e11f11" }, "value": { "type": "string", "description": "The monetary amount", "example": "10.5" }, "currency": { "type": "string", "description": "ISO 4217 currency code", "example": "EUR" }, "key": { "type": "string", "description": "Merchant identification key", "example": "Example Key" }, "expiration_time": { "type": "string", "format": "date-time", "description": "The expiration time for the payment", "example": "2025-12-26T10:32:45Z" }, "method": { "type": "string", "description": "Payment method used", "example": "MBW" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "4a908674-3bfb-47e5-b518-052a5e14b8fb" }, "name": { "type": "string", "example": "Josefa Gomes" }, "email": { "type": "string", "format": "email", "example": "customer@example.com" }, "phone": { "type": "string", "example": "911234567" }, "phone_indicative": { "type": "string", "example": "+351" }, "fiscal_number": { "type": "string", "example": "PT123456789" }, "key": { "type": "string", "example": "Customer Key" } } }, "account": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3ab50128-567c-4624-9268-04c5899ffb66" } } }, "transaction": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "3ab50128-567c-4624-9268-04c5899ffb60" }, "key": { "type": "string", "example": "Transaction_key" }, "type": { "type": "string", "example": "capture" }, "date": { "type": "string", "format": "date-time", "example": "2025-12-26T10:32:45Z" }, "transfer_date": { "type": "string", "format": "date-time", "example": "2025-12-29T00:00:00Z" }, "document_number": { "type": "string", "example": "MARCEL0208220658120320251226103247" }, "values": { "type": "object", "properties": { "requested": { "type": "string", "example": "10.5" }, "paid": { "type": "string", "example": "10.5" }, "fixed_fee": { "type": "string", "example": "0.07" }, "variable_fee": { "type": "string", "example": "0.08" }, "tax": { "type": "string", "example": "0" }, "transfer": { "type": "string", "example": "10.5" } } } } } } } }, "responses": { "list-single": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/meta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/single" } } } }, "examples": { "List All": { "value": { "meta": { "page": { "current": 0, "total": 0 }, "records": { "total": 0, "per_page": 0 }, "links": { "first": "string", "prev": "string", "next": "string", "last": "string" } }, "data": [ { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb", "type": "sale", "key": "Payment of Invoice Nº 1982652", "descriptive": "Payment of Invoice Nº 1982652", "expiration_time": "2024-06-30 21:38:31", "customer": { "id": "1b4ca1cf-9a1a-415b-97bf-342c6ddcf9c1", "name": "Joe*** Pri***", "email": "Cam***@yahoo.com", "phone": "936***098", "phone_indicative": "+351", "fiscal_number": "PT921***10", "key": "subscription 01234589", "language": "PT" }, "method": { "type": "CC", "status": "active", "sdd_mandate": { "id": "50389142122", "iban": "PT500027**XX7833", "key": "SDD Mandate key", "name": "Fre*** DD***", "email": "Cam***@yahoo.com", "phone": "911***567", "account_holder": "Acc*** Exa***", "country_code": "PT", "max_num_debits": "12", "billing_entity": "PT16103627" }, "card_type": "VISA", "last_four": "1234", "expiration_date": "string", "url": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a", "alias": "string", "entity": "11683", "reference": "665876931", "iban": "PT50000747199140461443823" }, "currency": "EUR", "value": 15.32, "created_at": "2024-06-30 21:38:31", "payment_status": "paid", "multibanco": { "expiration_time": "2025-09-28T12:41:08Z", "start_time": "2025-08-26T12:41:09Z", "product": "SPG" } }, { "id": "2f1a5d8c-4b2f-4f3a-9e49-5d0f8b4f2d91", "type": "sale", "key": "IPP payment", "descriptive": "IPP payment", "expiration_time": "2024-07-01 12:00:00", "customer": { "id": "2a88e01f-53f6-4c2c-8cf9-9dd5bff1d7b4", "name": "Mar*** Sil***", "email": "mar***@example.com", "phone": "912***345", "phone_indicative": "+351", "fiscal_number": "PT123***45", "key": "store 123", "language": "PT" }, "method": { "type": "IPP", "status": "active" }, "currency": "EUR", "value": 45, "created_at": "2024-07-01 12:00:00", "payment_status": "paid", "terminal": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420" } } ] } } } } } }, "forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" }, "examples": { "Wrong credentials provided": { "value": { "status": "error", "message": [ "Authentication failed" ] } } } }, "application/xml": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "array", "items": { "type": "string" } } } } } } }, "not-found": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" }, "examples": { "Resource not found": { "value": { "status": "error", "message": [ "Resource not found" ] } } } } } }, "pre-condition-failed": { "description": "Pre condition failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" }, "examples": { "Domain constraint failed": { "value": { "status": "error", "message": [ "Min value can't be higher than max's" ] } } } } } }, "internal-error": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" }, "examples": { "Internal error": { "value": { "status": "error", "message": [ "Internal Error" ] } } } } } }, "create-single-payment": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "Example 1": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "7120ac93-7a55-4fa5-a1e4-d7f8d2dc8738", "method": { "type": "MBW", "status": "success" }, "customer": { "id": "6726cd0e-6503-46ec-90da-e01c3838a9e9" }, "capture": { "id": "85c3503d-882b-4b4a-bb83-081946b57e56" } } }, "properties": { "status": { "$ref": "#/components/schemas/response-status" }, "message": { "$ref": "#/components/schemas/response-message" }, "id": { "type": "string", "format": "uuid", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "method": { "$ref": "#/components/schemas/method-on-post-response" }, "customer": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" } } }, "capture": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "example": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "splits": { "type": "array", "items": { "$ref": "#/components/schemas/capture-split-response" } }, "reward_redemption": { "type": "object", "description": "Reward credits redeemed in this payment.", "properties": { "account": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] } }, "required": [ "id" ] }, "value": { "type": "number", "format": "double", "description": "The redeemed reward amount.", "example": 5 } } } } }, "multibanco": { "$ref": "#/components/schemas/response-multibanco" }, "notification": { "$ref": "#/components/schemas/notification" } } }, "examples": { "Created Direct Debit with success": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "ed7f8dac-0ea2-4846-8433-f5f8b0e70ed7", "method": { "type": "DD", "status": "pending", "entity": "21098", "reference": "503564027", "sdd_mandate": { "id": "50356402710", "billing_entity": "PT16103627", "iban": "PT50002700000001234567833", "key": "sdd mandate key", "name": "Name Example", "email": "customer@example.com", "phone": "912997715", "account_holder": "Account Name Example", "country_code": "PT", "max_num_debits": "1", "reference_adc": "50356402710" } }, "customer": { "id": "2544ce48-ccec-465e-9722-d42ccf0aa640" }, "capture": { "id": "c6101a8b-b8c6-44a7-b128-bef8888e14d7" } } }, "Created Digital IBAN with success": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "52a29de3-c337-4681-acc5-9e16a1bcbc76", "method": { "type": "VI", "status": "pending", "iban": "PT50123400009900032909922" }, "customer": { "id": "9d66ceba-8daf-4f9e-af59-747b0d196096" }, "capture": { "id": "833259eb-343d-4f4d-aac8-4797a7b2bfe6" } } }, "Created Multibanco with success": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "e95dec61-fa63-461a-8e5b-ea42c4755bac", "method": { "type": "MB", "status": "pending", "entity": "11683", "reference": "663000450", "expiration_date": "07/17" }, "customer": { "id": "fba21a72-70fc-4e15-92e0-bcc967dfb750" }, "capture": { "id": "2a2b6501-b3eb-4b88-8e43-beb3d348fef0" }, "multibanco": { "product": "CHECKDIGIT", "start_time": "2025-07-25T10:22:53Z", "expiration_time": "2025-08-24T10:22:52Z" } } }, "Created Credit Card with success": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "66d50369-1e80-4a6e-8346-ae7bc7e88355", "method": { "type": "CC", "status": "pending", "url": "https://cc.test.easypay.pt/v3/public/card-details/66d50369-1e80-4a6e-8346-ae7bc7e88355" }, "customer": { "id": "b929f784-3cd3-4a6d-b712-4e9f17e7fa2f" }, "capture": { "id": "15962a97-3c67-41bf-8db7-f8e0cddc16b5" } } }, "Created MB Way with success": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "1c21f592-e0a3-4da4-9bac-2c56069b807e", "method": { "type": "MBW", "status": "success" }, "customer": { "id": "e162c103-ce92-4a55-b39a-38f72a77d899" }, "capture": { "id": "ad0e3276-6ebc-48ee-bb27-9a2a39d8a986" } } }, "Created MB WAY with dedicated payer phone": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "7b8f4c2d-51e6-4a0b-9c3f-8e2d61a5f470", "method": { "type": "MBW", "status": "success", "mbway": { "phone": "+351922222222" } }, "customer": { "id": "e162c103-ce92-4a55-b39a-38f72a77d899" }, "capture": { "id": "ad0e3276-6ebc-48ee-bb27-9a2a39d8a986" } } }, "Created Sale with Reward Redemption": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "5bf6b4cf-2d31-4a8d-ae51-1e9f1f0ad7de", "method": { "type": "CC", "status": "pending", "url": "https://cc.test.easypay.pt/v3/public/card-details/5bf6b4cf-2d31-4a8d-ae51-1e9f1f0ad7de" }, "customer": { "id": "6726cd0e-6503-46ec-90da-e01c3838a9e9" }, "capture": { "id": "9c2a1f88-3b3a-4f0e-9f2f-6b6f1d5d2c11", "reward_redemption": { "account": { "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832" }, "value": 2.5 } } } }, "Created Sale with Splits and Rewards": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "1f7d9b22-1f55-4c84-9c0e-2ef3e4d3a812", "method": { "type": "CC", "status": "pending", "url": "https://cc.test.easypay.pt/v3/public/card-details/1f7d9b22-1f55-4c84-9c0e-2ef3e4d3a812" }, "customer": { "id": "6726cd0e-6503-46ec-90da-e01c3838a9e9" }, "capture": { "id": "73a51c29-9ae0-4f1a-8b34-2bb02c4e0a7d", "splits": [ { "id": "4a2c9e10-5f40-4f9a-9e3b-7d6f6c1d8c41", "split_key": "5d87a15c-dab6-441a-b9f6-ecd86171517e", "split_descriptive": "product", "account": { "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832" }, "margin_account": { "id": "b6f53027-0478-4728-9269-8bcc0f8088ea" }, "margin_value": 26.39, "reward": { "account": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "value": 5, "expiration_date": "2027-01-15" }, "value": 649.99, "status": "waiting" } ] } } }, "Created Sale with Splits": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "8b6db0e1-12c4-4f5d-b6c2-9a30bb1ef0de", "method": { "type": "CC", "status": "pending", "url": "https://cc.test.easypay.pt/v3/public/card-details/8b6db0e1-12c4-4f5d-b6c2-9a30bb1ef0de" }, "customer": { "id": "6726cd0e-6503-46ec-90da-e01c3838a9e9" }, "capture": { "id": "e2841fbd-7d36-4d1a-95a9-0e9a2c2f3a55", "splits": [ { "id": "0d3a4f87-1e22-4f6f-bf2e-9c5a3b8a6e10", "split_key": "5d87a15c-dab6-441a-b9f6-ecd86171517e", "split_descriptive": "product", "account": { "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832" }, "margin_account": { "id": "b6f53027-0478-4728-9269-8bcc0f8088ea" }, "margin_value": 26.39, "value": 649.99, "status": "waiting" } ] } } }, "Created Sale with Splits and Reward Redemption": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "3a92e5c8-4a17-4d2e-9c1f-5e1a6b7c8d90", "method": { "type": "CC", "status": "pending", "url": "https://cc.test.easypay.pt/v3/public/card-details/3a92e5c8-4a17-4d2e-9c1f-5e1a6b7c8d90" }, "customer": { "id": "6726cd0e-6503-46ec-90da-e01c3838a9e9" }, "capture": { "id": "7c3a1f4d-2b85-4f3a-a912-6e0f2d4b9c11", "splits": [ { "id": "9b1e3d4c-5a67-4f8e-9c2a-1d3e4f5a6b7c", "split_key": "5d87a15c-dab6-441a-b9f6-ecd86171517e", "split_descriptive": "Marketplace seller", "account": { "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832" }, "margin_account": { "id": "b6f53027-0478-4728-9269-8bcc0f8088ea" }, "margin_value": 5, "value": 70, "status": "waiting" }, { "id": "2c4d6e8f-1a3b-4c5d-7e9f-0a1b2c3d4e5f", "split_descriptive": "Platform share", "account": { "id": "c3d4e5f6-a1b2-7890-abcd-ef1234567890" }, "value": 20, "status": "waiting" } ], "reward_redemption": { "account": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "value": 10 } } } } } } } }, "bad-request": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" } } } }, "conflict": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" }, "examples": { "conflict": { "summary": "Resource conflict example", "value": { "status": "409", "message": "Conflict - Resource already exists or state conflict", "id": "00000000-0000-0000-0000-000000000000" } } } } } }, "get-single-details": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "allOf": [ { "$ref": "#/components/schemas/identifier" } ] }, "created_at": { "type": "string" }, "captures": { "type": "array", "items": { "$ref": "#/components/schemas/single-capture-full" } }, "key": { "type": "string", "example": "Payment of Invoice Nº 1982652" }, "descriptive": { "$ref": "#/components/schemas/descriptive" }, "value": { "$ref": "#/components/schemas/value" }, "expiration_time": { "type": "string" }, "currency": { "$ref": "#/components/schemas/currency" }, "customer": { "$ref": "#/components/schemas/customer" }, "method": { "$ref": "#/components/schemas/single-detail-method-response" }, "paid_at": { "type": "string" }, "transactions": { "type": "array", "items": { "$ref": "#/components/schemas/payment-transactions" } }, "payment_status": { "$ref": "#/components/schemas/single-payment-status" }, "multibanco": { "$ref": "#/components/schemas/response-multibanco" }, "terminal": { "$ref": "#/components/schemas/response-terminal", "description": "Present when `method.type` is `IPP`." }, "notification": { "$ref": "#/components/schemas/notification" } } }, "examples": { "IPP Payment": { "value": { "id": "2f1a5d8c-4b2f-4f3a-9e49-5d0f8b4f2d91", "created_at": "2024-07-01 12:00:00", "key": "IPP payment", "descriptive": "IPP payment", "value": 45, "expiration_time": "2024-07-01 12:00:00", "currency": "EUR", "customer": { "id": "2a88e01f-53f6-4c2c-8cf9-9dd5bff1d7b4", "name": "Mar*** Sil***", "email": "mar***@example.com", "phone": "912***345", "phone_indicative": "+351", "fiscal_number": "PT123***45", "key": "store 123", "language": "PT" }, "method": { "type": "IPP", "status": "active" }, "paid_at": "2024-07-01 12:05:00", "payment_status": "paid", "terminal": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420" } } }, "MB WAY with dedicated payer phone": { "value": { "id": "1c21f592-e0a3-4da4-9bac-2c56069b807e", "created_at": "2024-07-01 12:00:00", "key": "merchant identification key Example", "descriptive": "transaction descriptive Example", "value": 17.5, "currency": "EUR", "customer": { "id": "e162c103-ce92-4a55-b39a-38f72a77d899", "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351" }, "method": { "type": "MBW", "status": "active", "mbway": { "phone": "+351922222222" } }, "paid_at": "2024-07-01 12:05:00", "payment_status": "paid" } }, "Sale with Reward Redemption": { "value": { "id": "5bf6b4cf-2d31-4a8d-ae51-1e9f1f0ad7de", "created_at": "2024-07-01 12:00:00", "key": "merchant identification key Example", "descriptive": "transaction descriptive Example", "value": 50, "currency": "EUR", "customer": { "id": "6726cd0e-6503-46ec-90da-e01c3838a9e9", "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351" }, "method": { "type": "CC", "status": "active" }, "captures": [ { "id": "9c2a1f88-3b3a-4f0e-9f2f-6b6f1d5d2c11", "status": "success", "descriptive": "transaction descriptive Example", "transaction_key": "transaction key Example", "reward_redemption": { "account": { "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832" }, "value": 2.5 } } ], "paid_at": "2024-07-01 12:05:00", "payment_status": "paid" } } } } } }, "no-content": { "description": "No Content" }, "single-update": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/identifier" }, "message": { "$ref": "#/components/schemas/response-message" }, "status": { "$ref": "#/components/schemas/response-status" }, "method": { "$ref": "#/components/schemas/single-edit-method-response" }, "customer": { "type": "object", "properties": { "id": { "$ref": "#/components/schemas/identifier" } } } } }, "examples": { "Example 1": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "d4851c0a-66e2-4b34-9587-1e453ddcc650", "method": { "type": "CC", "status": "pending", "url": "https://cc.easypay.pt/v3/public/card-details/d4851c0a-66e2-4b34-9587-1e453ddcc650" }, "customer": { "id": "156de567-b17d-4591-a154-442c873b76c7" } } } } } } }, "list-frequent": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/meta" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/frequent" } } }, "required": [ "meta", "data" ] }, "examples": { "Response": { "value": { "meta": { "page": { "current": 1, "total": 2335 }, "records": { "total": 4669, "per_page": 2 }, "links": { "first": "?page=1", "prev": "", "next": "?page=2", "last": "?page=2335" } }, "data": [ { "id": "ab2f2eb6-3655-4951-98ae-36367d5f3727", "key": "Default Key", "expiration_time": "2022-12-12T16:05:00Z", "value": 10, "customer": { "id": "06300032-5cbd-4393-b73d-9f4c9875270a", "name": "***", "email": "ema***@example.com", "phone": "***", "fiscal_number": "***", "key": "Customer key", "language": "PT" }, "method": { "type": "CC", "status": "waiting", "url": "https://cc.test.easypay.pt/start/ab2f2eb6-3655-4951-98ae-36367d5f3727" }, "currency": "EUR", "max_value": 20.55, "min_value": 2.32, "unlimited_payments": false, "created_at": "2022-11-23 12:03:29" }, { "id": "f15cee45-d5a5-469d-8cb2-79a6dcba977f", "key": "Default Key", "expiration_time": "2022-12-12T16:05:00Z", "value": 10, "customer": { "id": "48307582-91bc-4e15-a9f6-84633fbdd2c7", "name": "***", "email": "ema***@example.com", "phone": "***", "fiscal_number": "***", "key": "Customer key", "language": "PT" }, "method": { "type": "DD", "status": "active", "sdd_mandate": { "id": "50124502381", "billing_entity": "PT16103627", "iban": "PT500027**XX7833", "key": "Sdd Mandate key", "name": "Fre*** DD***", "email": "cus***@example.com", "phone": "911***567", "account_holder": "Acc*** Exa***", "country_code": "PT", "max_num_debits": "0" } }, "currency": "EUR", "max_value": 20.55, "min_value": 2.32, "unlimited_payments": false, "created_at": "2022-11-23 11:56:35" } ] } } } } } }, "too-many-requests": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" }, "examples": { "Rate limit exceeded": { "value": { "status": "error", "message": [ "Rate limit exceeded" ] } } } } } }, "create-frequent-payment": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the request", "example": "ok" }, "message": { "type": "array", "items": { "type": "string", "example": "Your request was successfully created" }, "description": "Array of status messages" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the created frequent payment", "example": "86401037-1c8d-4cf3-9172-d0a29b17b9fd" }, "method": { "type": "object", "description": "Payment method details", "properties": { "type": { "type": "string", "enum": [ "MB", "CC", "DD", "MBW", "VI" ], "description": "Payment method type", "example": "CC" }, "status": { "type": "string", "enum": [ "waiting", "pending", "active", "deleted", "success" ], "description": "Current status of the payment method", "example": "waiting" }, "entity": { "type": "string", "description": "Entity identifier", "example": "59126" }, "reference": { "type": "string", "description": "Payment reference", "example": "810000618" }, "url": { "type": "string", "description": "Only returns if the payment is a Credit Card.", "example": "https://cc.test.easypay.pt/start/980d4826-8574-4782-8450-18db150b7c26" }, "iban": { "type": "string", "description": "Only returns if the payment method is Visa Direct.", "example": "PT50123400007000199799996" }, "alias": { "type": "string", "description": "Only returns if the payment method is MB WAY.", "example": "6ac1c9c50be844858afdbc74eb74acbc" }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate-response-on-detail" } } }, "customer": { "type": "object", "description": "Customer information", "properties": { "id": { "type": "string", "format": "uuid", "description": "Customer unique identifier", "example": "e7bb115b-3e59-441a-bdb4-60b0f066c2d0" } } } } }, "examples": { "Response from CC method": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "cd90455e-4ab3-42cf-a91c-cfc6e3afa65a", "method": { "type": "CC", "status": "waiting", "url": "https://cc.test.easypay.pt/v3/public/card-details/e388fe5a-5b9f-44b6-91b1-62e321a7dc4b" }, "customer": { "id": "68d07e52-3e04-493f-aaeb-bffe7ddb81ee" } } }, "Response from DD method": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "86401037-1c8d-4cf3-9172-d0a29b17b9fd", "method": { "type": "DD", "status": "active", "sdd_mandate": { "id": "50389142122", "iban": "PT50002700000001234567833", "key": "Key Example", "name": "John Doe", "email": "john.doe@example.com", "phone": "911345678", "account_holder": "John Doe", "country_code": "PT", "max_num_debits": "12", "billing_entity": "PT16103627", "reference_adc": "987654321123" } }, "customer": { "id": "e7bb115b-3e59-441a-bdb4-60b0f066c2d0" } } }, "Response from MB method": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "076d8c3f-a198-4e06-b44c-9ed1e9ba021a", "method": { "type": "MB", "status": "waiting", "entity": "21098", "reference": "504273872" }, "customer": { "id": "09a5c637-179b-4783-b6e7-849df5b4c341" } } }, "Response from VI method": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "0f5480ab-7c7b-4f27-ae1a-1c170e6c5a3e", "method": { "type": "VI", "status": "pending", "iban": "PT50123400007000199799996" }, "customer": { "id": "2752241c-ca5b-4144-9d65-e825c58feeb5" } } }, "Response from MBW method": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "fdf44408-3a39-4800-a9ef-521e648d69cc", "method": { "type": "MBW", "status": "success", "alias": "6ac1c9c50be844858afdbc74eb74acbc" }, "customer": { "id": "48b815dd-ce3e-489f-a378-09dc930bd3da" } } } } } } }, "get-frequent-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/frequent-with-transactions" }, "examples": { "Response": { "value": { "id": "ac1913a3-fd78-4822-8394-0a14f4169247", "key": "Default Key", "expiration_time": "2022-12-12T16:05:00Z", "customer": { "id": "fdc4bc82-8e45-4597-b46d-51d3285cf935", "name": "Robert Stuart", "email": "email@example.com", "phone": "911234567", "key": "Customer key", "language": "PT" }, "method": { "type": "CC", "status": "active", "url": "https://cc.test.easypay.pt/start/ac1913a3-fd78-4822-8394-0a14f4169247", "last_four": "0000", "card_type": "VISA", "expiration_date": "04/25" }, "currency": "EUR", "max_value": 20, "min_value": 2, "unlimited_payments": false, "created_at": "2022-11-23 13:16:58" } } } } } }, "unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" }, "examples": { "Wrong credentials provided": { "value": { "status": "error", "message": [ "Authentication failed" ] } } } } } }, "frequent-update": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "description": "Status of the request", "example": "ok" }, "message": { "type": "array", "items": { "type": "string", "example": "Your request was successfully created" }, "description": "Array of status messages" }, "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the frequent payment", "example": "86401037-1c8d-4cf3-9172-d0a29b17b9fd" }, "method": { "type": "object", "description": "Payment method details", "properties": { "type": { "type": "string", "enum": [ "MB", "CC", "DD", "MBW", "VI" ], "description": "Payment method type", "example": "CC" }, "status": { "type": "string", "enum": [ "waiting", "pending", "active", "deleted" ], "description": "Current status of the payment method", "example": "waiting" }, "url": { "type": "string", "description": "Only returns if the payment is a Credit Card.", "example": "https://cc.test.easypay.pt/start/86401037-1c8d-4cf3-9172-d0a29b17b9fd" }, "entity": { "type": "string", "description": "Entity identifier", "example": "59126" }, "reference": { "type": "string", "description": "Payment reference", "example": "810000618" }, "sdd_mandate": { "type": "object", "description": "SDD mandate details for direct debit payments", "properties": { "id": { "type": "string", "example": "12345678901" }, "iban": { "type": "string", "example": "PT50002700000001234567833" }, "key": { "type": "string", "example": "Key Example" }, "name": { "type": "string", "example": "Name Example" }, "email": { "type": "string", "example": "customer@example.com" }, "phone": { "type": "string", "example": "911234567" }, "account_holder": { "type": "string", "example": "Acount Name Example" }, "country_code": { "type": "string", "example": "PT" }, "max_num_debits": { "type": "string", "example": "12" }, "reference_adc": { "type": "string", "example": "987654321123" } } } } }, "customer": { "type": "object", "description": "Customer information", "properties": { "id": { "type": "string", "format": "uuid", "description": "Customer unique identifier", "example": "e7bb115b-3e59-441a-bdb4-60b0f066c2d0" } } } } }, "examples": { "Full Response": { "value": { "method": { "type": "DD", "sdd_mandate": { "id": "12345678901", "iban": "PT50002700000001234567833", "key": "Key Example", "name": "Name Example", "email": "customer@example.com", "phone": "911234567", "account_holder": "Account Name Example", "country_code": "PT", "max_num_debits": "12", "reference_adc": "987654321123" } }, "status": "ok", "message": [ "Your request was successfully created" ] } }, "Response from CC Method": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "86401037-1c8d-4cf3-9172-d0a29b17b9fd", "method": { "type": "CC", "status": "waiting", "entity": "59126", "reference": "810000618", "url": "https://cc.test.easypay.pt/start/86401037-1c8d-4cf3-9172-d0a29b17b9fd" }, "customer": { "id": "e7bb115b-3e59-441a-bdb4-60b0f066c2d0" } } } } }, "application/xml": {} } }, "frequent-authorisation": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the authorization", "example": "4c67e74b-a256-4e0a-965d-97bf5d01bd50" }, "status": { "type": "string", "description": "Status of the request", "example": "ok" }, "message": { "type": "array", "items": { "type": "string", "example": "Your request was successfully created" }, "description": "Array of status messages" } } }, "examples": { "Response": { "value": { "id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50", "status": "ok", "message": [ "Your request was successfully created" ] } } } } } }, "get-config": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/config-details" }, "examples": { "Response": { "value": { "generic": "https://www.easypay.pt/generic", "authorisation": "https://www.easypay.pt/authorisation", "transaction": "https://www.easypay.pt/transaction", "visa_fwd": "https://www.easypay.pt/visa_fwd", "visa_detail": "https://www.easypay.pt/visa_detail", "account": "b2080452-bad1-4455-8ae7-9f5ea552a274", "client_id": "EASYP030002", "payment_methods": [ "MB" ] } } } } } }, "patch-config": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/config-details" }, "examples": { "Response": { "value": { "generic": "https://www.easypay.pt/generic", "authorisation": "https://www.easypay.pt/authorisation", "transaction": "https://www.easypay.pt/transaction", "visa_fwd": "https://www.easypay.pt/visa_fwd", "visa_detail": "https://www.easypay.pt/visa_detail", "account": "b2080452-bad1-4455-8ae7-9f5ea552a274", "client_id": "EASYP030002", "payment_methods": [ "MB" ] } } } } } }, "list-capture": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture-get-list-response" } } } }, "get-capture-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture-get-by-id-response" } } } }, "create-capture": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture-post-response" } } } }, "unprocessable-entity": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" }, "examples": { "Rate limit exceeded": { "value": { "status": "error", "message": [ "Unprocessable Entity" ] } } } } } }, "pre-condition-required": { "description": "Pre condition required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/error-response-4xx" }, "examples": { "Domain constraint failed": { "value": { "status": "error", "message": [ "Min value is required" ] } } } } } }, "update-capture-split": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/status-details" } } } }, "get-authorisation-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/authorisation-get-by-id-response" } } } }, "checkout-get-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout-get-details-response" } } } }, "create-checkout": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout-post-response" }, "examples": { "Create Checkout with Success": { "value": { "id": "10d3a41a-c9c4-486e-8da7-9490e5f097b7", "session": "XkhRqoQtbBakUnjEJA4lYSCtboITWSb-ijxRMWKj7C9ormZ_4JubSB3qjy4XuORJFSrR0OsQ0ypE2Ws9Zl0N2REmR0CMNewH8ghyR1NBnPzDJ1AAuj9LvAhdv9SS-MXRh20_jmVz0MTcaD6E9WfHMiGSyej8eLMaE2hbSHn8DAO7kUSy8nzIIIUbR3pbpEpwxeO6fgHB3hdLGWrGUjeRq-Dq1Q_RF_ZWDPOGPwehXb3YRTatcjBG_2yoyGWWBaABOlkOx_uLaZIdrHMRXaDwLFDoN-eiu3BH1KKrut6pcE_Gc6laTf2AINBQIuSzKHLT4MFpTkrxdfPiD67w8aENm2HuzFc08I46KxdQG-2dSN522jZWDC2z4r4HFZ8LWVlDPuLbpui-WoWOJrJAnW3nPhyaKfUeu4KuU3BKYtJrtOoqs5ingkKWen0jm6AuFeZDeYRlRtj19S6d3P4q7Om3PVwil7c0K0brq31SmLHZdvsG_gHOPSZ6qrQy_95NZO0x934tBIUK91C1Bnm1Z9wA2Pp2hIeprOXMuZXkuanODro=", "config": null } } } } } }, "list-subscription": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/subscription-response-on-list" } }, "meta": { "$ref": "#/components/schemas/meta" } } }, "examples": { "Success": { "description": "Success", "value": { "data": [ { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "key": "subscription 02536985", "expiration_time": "2099-01-15 00:00", "start_time": "2027-01-15 00:00", "frequency": "1M", "retries": 2, "max_captures": 12, "failover": false, "capture_now": true, "unlimited_payments": false, "customer": { "id": "e66c4f80-3dc6-11eb-b378-0242ac130002", "name": "João Silva", "email": "joao.silva@test.com", "phone": "+351911234567", "fiscal_number": "123456789", "key": "customer_key_123" }, "method": { "type": "CC", "status": "active", "url": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a" }, "currency": "EUR", "value": 10.55, "created_at": "2025-08-05 13:44:29" } ], "meta": { "page": { "current": 2, "total": 500 }, "records": { "total": 60000, "per_page": 20 }, "links": { "first": "?page=1", "prev": "?page=2", "next": "?page=4", "last": "?page=5487" } } } } } } } }, "create-subscription": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription-response-on-detail" }, "examples": { "Response from CC method": { "description": "Success", "value": { "status": "ok", "message": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "key": "subscription 02536985", "expiration_time": "2099-01-15 00:00", "start_time": "2027-01-15 00:00", "frequency": "1M", "retries": 2, "max_captures": 12, "failover": false, "capture_now": true, "unlimited_payments": false, "customer": { "id": "e66c4f80-3dc6-11eb-b378-0242ac130002", "name": "João Silva", "email": "joao.silva@test.com", "phone": "+351911234567", "fiscal_number": "123456789", "key": "customer_key_123", "phone_indicators": { "country_calling_code": "+351", "national_destination_code": "91", "subscriber_number": "1234567" } }, "method": { "type": "CC", "status": "active", "url": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a", "last_four": "2222", "card_type": "VISA", "expiration_date": "07/29" }, "transactions": [], "currency": "EUR", "value": 10.55, "created_at": "2025-08-05 13:44:29" } } }, "Response from DD method": { "description": "Success", "value": { "status": "ok", "message": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "key": "subscription 02536985", "expiration_time": "2099-01-15 00:00", "start_time": "2027-01-15 00:00", "frequency": "1M", "retries": 2, "max_captures": 12, "failover": false, "capture_now": true, "unlimited_payments": false, "customer": { "id": "e66c4f80-3dc6-11eb-b378-0242ac130002", "name": "João Silva", "email": "joao.silva@test.com", "phone": "+351911234567", "fiscal_number": "123456789", "key": "customer_key_123", "phone_indicators": { "country_calling_code": "+351", "national_destination_code": "91", "subscriber_number": "1234567" } }, "method": { "type": "DD", "status": "active", "sdd_mandate": { "id": "50389142122", "billing_entity": "PT16103627", "iban": "PT50002700000001234567833", "key": "Key Example", "name": "John Doe", "email": "john.doe@example.com", "phone": "911345678", "account_holder": "John Doe", "country_code": "PT", "max_num_debits": "12", "reference_adc": "987654321123" } }, "transactions": [], "currency": "EUR", "value": 10.55, "created_at": "2025-08-05 13:44:29" } } } } } } }, "get-subscription-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subscription-response-on-detail" }, "examples": { "Success": { "description": "Success", "value": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "key": "subscription 02536985", "expiration_time": "2099-01-15 00:00", "start_time": "2027-01-15 00:00", "frequency": "1M", "retries": 2, "max_captures": 12, "failover": false, "capture_now": true, "unlimited_payments": false, "customer": { "id": "e66c4f80-3dc6-11eb-b378-0242ac130002", "name": "João Silva", "email": "joao.silva@test.com", "phone": "+351911234567", "fiscal_number": "123456789", "key": "customer_key_123", "phone_indicators": { "country_calling_code": "+351", "national_destination_code": "91", "subscriber_number": "1234567" } }, "method": { "type": "CC", "status": "active", "url": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a", "last_four": "2222", "card_type": "VISA", "expiration_date": "07/29" }, "transactions": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "key": "payment 123456", "status": "paid", "date": "2025-08-05 13:44:29", "currency": "EUR", "value": 10.55 } ], "currency": "EUR", "value": 10.55, "created_at": "2025-08-05 13:44:29" } } } } } }, "update-subscription": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "$ref": "#/components/schemas/subscription-response-on-detail" } } }, "examples": { "Success": { "description": "Success", "value": { "status": "ok", "message": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "key": "subscription 02536985", "expiration_time": "2099-01-15 00:00", "start_time": "2027-01-15 00:00", "frequency": "1M", "retries": 2, "max_captures": 12, "failover": false, "capture_now": true, "unlimited_payments": false, "customer": { "id": "e66c4f80-3dc6-11eb-b378-0242ac130002", "name": "João Silva", "email": "joao.silva@test.com", "phone": "+351911234567", "fiscal_number": "123456789", "key": "customer_key_123", "phone_indicators": { "country_calling_code": "+351", "national_destination_code": "91", "subscriber_number": "1234567" } }, "method": { "type": "CC", "status": "active", "url": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a", "last_four": "2222", "card_type": "VISA", "expiration_date": "07/29" }, "transactions": [ { "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6", "key": "payment 123456", "status": "paid", "date": "2025-08-05 13:44:29", "currency": "EUR", "value": 10.55 } ], "currency": "EUR", "value": 10.55, "created_at": "2025-08-05 13:44:29" } } } } } } }, "list-cycles": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "metadata" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/cycle" } }, "metadata": { "$ref": "#/components/schemas/metadata-cursor" } } }, "examples": { "First page": { "summary": "First page of cycles with a next cursor", "value": { "data": [ { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "RENEWABLE", "status": "SUCCESS", "value": 10.5, "capture_at": "2026-05-22T09:00:00Z" }, { "id": "2d3f4b8a-1c12-4e6f-9b7a-3f5d2e1c8a9b", "type": "ONE_TIME_CHARGE", "status": "PENDING", "value": 25, "capture_at": "2026-06-01T09:00:00Z", "description": "add-on charge", "key": "add-on-2026-06-01" } ], "metadata": { "next_cursor": "lL_j7ilk7rc", "count": 2 } } }, "Last page": { "summary": "Final page — empty next_cursor signals no further results", "value": { "data": [ { "id": "7a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "type": "RENEWABLE", "status": "SUCCESS", "value": 10.5, "capture_at": "2026-03-22T09:00:00Z" } ], "metadata": { "next_cursor": "", "count": 1 } } }, "No cycles": { "summary": "The subscription exists but has no cycles matching the filter", "value": { "data": [], "metadata": { "next_cursor": "", "count": 0 } } } } } } }, "create-one-time-charge": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/one-time-charge-response-on-post" }, "examples": { "One-time charge created": { "summary": "A new cycle has been queued on the subscription", "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "550e8400-e29b-41d4-a716-446655440000" } } } } } }, "get-cycle": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cycle" }, "examples": { "Pending one-off charge": { "summary": "A one-off cycle that has not been captured yet", "value": { "id": "550e8400-e29b-41d4-a716-446655440000", "type": "ONE_TIME_CHARGE", "status": "PENDING", "value": 10.5, "capture_at": "2026-05-22T09:00:00Z", "description": "monthly charge", "key": "my-key" } }, "Successful renewal": { "summary": "A regular renewal cycle that has been captured", "value": { "id": "2d3f4b8a-1c12-4e6f-9b7a-3f5d2e1c8a9b", "type": "RENEWABLE", "status": "SUCCESS", "value": 25, "capture_at": "2026-04-01T08:00:00Z" } } } } } }, "update-cycle": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update-cycle-response-on-patch" }, "examples": { "Cycle updated": { "summary": "The cycle's amount has been overridden", "value": { "status": "ok", "message": [ "Your request was successfully updated" ], "id": "550e8400-e29b-41d4-a716-446655440000" } } } } } }, "get-void-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/void-get-by-id-response" } } } }, "create-void": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/void-post-response" } } } }, "report-ledger-response": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/metadata-cursor" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ledger-entry" } } } }, "examples": { "Example 1": { "value": { "metadata": { "next_cursor": "lL_j7ilk7rc", "count": 10 }, "data": [ { "id": "dc0f1e47-4510-4058-8119-31b8f80b5a02", "created_at": "2019-08-24T14:15:22Z", "transaction_timestamp": "2019-08-24T14:15:22Z", "transaction_type": "CP", "amount_details": { "requested_amount": { "amount": "13.5", "currency": "EUR" }, "payed_amount": { "amount": "13.5", "currency": "EUR" }, "fixed_fee": { "amount": "0.07", "currency": "EUR" }, "variable_fee": { "amount": "0.1", "currency": "EUR" }, "tax_amount": { "amount": "0.04", "currency": "EUR" }, "transfered_amount": { "amount": "13.29", "currency": "EUR" } }, "transfer_batch_date": "2019-08-24", "transfer_batch": "string", "descriptive": "some descriptive", "details": { "operation_id": "79921588-12fb-44c8-87c2-207362a8e467", "operation_key": "transaction key associated with operation", "method": "MBW", "payment_id": "1717d252-7a25-43e9-a272-f1ae07a0f2d7", "payment_type": "single", "payment_key": "Merchant identification key associated with payment" } }, { "id": "5b8a2d1f-9c3e-4f6a-8b7d-2e4c6a8f0d13", "created_at": "2019-08-24T14:15:22Z", "transaction_timestamp": "2019-08-24T14:15:22Z", "transaction_type": "RW", "amount_details": { "requested_amount": { "amount": "0.68", "currency": "EUR" }, "payed_amount": { "amount": "0.68", "currency": "EUR" } }, "descriptive": "reward earned on capture", "details": { "operation_id": "79921588-12fb-44c8-87c2-207362a8e467", "operation_key": "transaction key associated with operation", "method": "MBW", "payment_id": "1717d252-7a25-43e9-a272-f1ae07a0f2d7", "payment_type": "single", "payment_key": "Merchant identification key associated with payment" } }, { "id": "9d4f7c2a-1e8b-4a5c-b3f6-7c9e1a3d5f28", "created_at": "2019-08-30T10:02:47Z", "transaction_timestamp": "2019-08-30T10:02:47Z", "transaction_type": "RR", "amount_details": { "requested_amount": { "amount": "1.50", "currency": "EUR" }, "payed_amount": { "amount": "1.50", "currency": "EUR" } }, "descriptive": "reward credits redeemed on capture", "details": { "operation_id": "3c1f9a6e-5d2b-48e7-a9c4-8b0d2f6e4a91", "operation_key": "transaction key associated with operation", "method": "CC", "payment_id": "84f0b3c7-2a9d-4e16-b5c8-1d7f3a9e6b42", "payment_type": "single", "payment_key": "Merchant identification key associated with payment" } }, { "id": "2f8e6b4d-9a1c-4e7f-8d3b-5c0a7e9f1b64", "created_at": "2019-09-15T00:05:00Z", "transaction_timestamp": "2019-09-15T00:05:00Z", "transaction_type": "RX", "amount_details": { "requested_amount": { "amount": "0.30", "currency": "EUR" }, "payed_amount": { "amount": "0.30", "currency": "EUR" } }, "descriptive": "expired reward credits paid out" } ] } } } }, "application/xml": { "schema": { "type": "object", "properties": {} } }, "multipart/form-data": { "schema": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/metadata-cursor" } } } }, "text/html": { "schema": { "type": "object", "properties": { "meta": { "type": "string" } } } } } }, "report-transactions-response": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/metadata-page" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/transaction-report-data" } } }, "required": [ "meta" ] }, "examples": { "Response": { "value": { "meta": { "page": { "current": 1, "total": 47 }, "records": { "total": 231, "per_page": 5 }, "links": { "first": "?page=1", "prev": "", "next": "?page=2", "last": "?page=47" } }, "data": [ { "id": "b41921f1-a255-41bc-9e92-9a28d266d378", "key": "Merchant identification key", "date": "2022-11-16T16:45:19Z", "created_at": "2022-11-16T16:45:19Z", "values": { "requested": 44, "paid": 44, "fixed_fee": 0.25, "variable_fee": 0.66, "tax": 1.5, "transfer": 42.88 }, "transfer_date": "2022-11-21T00:00:00Z", "transfer_batch": "", "method": "DD", "document_number": "MARCEL0208220452011220221116164519", "payment_type": "single", "payment_id": "2a9112fe-6510-4366-b55e-24a3ae188d67", "payment_account": { "id": "76f190b9-2b8a-4bd0-9490-411241a9dc81" }, "payment_key": "Merchant identification key", "payment_transaction_key": "Merchant identification key", "descriptive": "Descriptive Josefa" }, { "id": "b3fad7da-69bf-4320-b3ad-ccfaecaf8d16", "key": "Robertos Key", "date": "2022-11-16T11:46:58Z", "values": { "requested": 100, "paid": 100, "fixed_fee": 0, "variable_fee": 0, "tax": 0, "transfer": 100 }, "transfer_date": "2022-11-18T00:00:00Z", "transfer_batch": "", "method": "MBW", "document_number": "MARCEL0208220451979520221116114658", "payment_type": "single", "payment_id": "0cccc05d-1964-4648-a32b-fe7107746881", "payment_account": { "id": "76f190b9-2b8a-4bd0-9490-411241a9dc81" }, "payment_key": "Robertos Key", "payment_transaction_key": "", "descriptive": "Description of Roberto" }, { "id": "65196366-3afe-45b6-be79-0f1025c9e2d5", "key": "Merchant identification key", "date": "2022-11-15T10:06:19Z", "values": { "requested": 44, "paid": 44, "fixed_fee": 0.25, "variable_fee": 0.66, "tax": 1.5, "transfer": 42.88 }, "transfer_date": "2022-11-17T00:00:00Z", "transfer_batch": "", "method": "DD", "document_number": "MARCEL0208220451822420221115100619", "payment_type": "single", "payment_id": "8798e233-43c8-4a73-8e24-e440a083b157", "payment_account": { "id": "76f190b9-2b8a-4bd0-9490-411241a9dc81" }, "payment_key": "Merchant identification key", "payment_transaction_key": "Merchant identification key", "descriptive": "Descriptive Josefa" }, { "id": "a03c6452-ae7a-4495-993d-b6608d999edb", "key": "Merchant identification key", "date": "2022-11-15T10:06:19Z", "values": { "requested": 44, "paid": 44, "fixed_fee": 0.25, "variable_fee": 0.66, "tax": 1.5, "transfer": 42.88 }, "transfer_date": "2022-11-17T00:00:00Z", "transfer_batch": "", "method": "DD", "document_number": "MARCEL0208220451822320221115100619", "payment_type": "single", "payment_id": "b81d392b-b0d0-47ae-b76a-94ded2de404b", "payment_account": { "id": "76f190b9-2b8a-4bd0-9490-411241a9dc81" }, "payment_key": "Merchant identification key", "payment_transaction_key": "Merchant identification key", "descriptive": "Descriptive Josefa" }, { "id": "5b145b82-8ff1-4caf-bb5e-f72dccfff376", "key": "Merchant identification key", "date": "2022-11-15T10:06:19Z", "values": { "requested": 44, "paid": 44, "fixed_fee": 0.25, "variable_fee": 0.66, "tax": 1.5, "transfer": 42.88 }, "transfer_date": "2022-11-17T00:00:00Z", "transfer_batch": "", "method": "DD", "document_number": "MARCEL0208220451822220221115100619", "payment_type": "single", "payment_id": "e605e589-ccf8-4739-8fdb-8502a609bda4", "payment_account": { "id": "76f190b9-2b8a-4bd0-9490-411241a9dc81" }, "payment_key": "Merchant identification key", "payment_transaction_key": "Merchant identification key", "descriptive": "Descriptive Josefa" } ] } } } }, "application/xml": { "schema": { "type": "object", "properties": {} } }, "text/csv": { "schema": { "type": "object", "properties": {} } } } }, "settlements": { "description": "Successful response with a list of settlements", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "metadata" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/settlement" } }, "metadata": { "$ref": "#/components/schemas/metadata-cursor" } } }, "examples": { "First page": { "summary": "First page of settlements with a next cursor", "value": { "data": [ { "id": "f6a7b8c9-d0e1-2345-fabc-456789012306", "created_at": "2026-02-05T09:30:00Z", "updated_at": null, "name": "1006", "description": "EASYPAY-6-8895-1006-CIN002", "status": "IN_TRANSIT", "total_amount": { "currency": "EUR", "amount": "99.99" }, "number_of_items": 2, "destination": { "type": "IBAN", "details": { "iban": "PT50000201236666666666666" } } } ], "metadata": { "next_cursor": "lL_j7ilk7rc", "count": 1 } } }, "Last page": { "summary": "Final page — empty next_cursor signals no further results", "value": { "data": [ { "id": "e5f6a7b8-c9d0-1234-efab-345678901205", "created_at": "2026-02-01T11:00:00Z", "updated_at": null, "name": "1005", "description": "EASYPAY-5-8895-1005-CIN002", "status": "SUCCEEDED", "total_amount": { "currency": "EUR", "amount": "320.75" }, "number_of_items": 7, "destination": { "type": "IBAN", "details": { "iban": "PT50000201235555555555555" } } } ], "metadata": { "next_cursor": "", "count": 1 } } }, "No settlements": { "summary": "No settlements match the filter", "value": { "data": [], "metadata": { "next_cursor": "", "count": 0 } } } } } } }, "settlement": { "description": "Successful response with a settlement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/settlement" }, "examples": { "Settlement": { "summary": "A succeeded settlement", "value": { "id": "e5f6a7b8-c9d0-1234-efab-345678901205", "created_at": "2026-02-01T11:00:00Z", "updated_at": null, "name": "1005", "description": "EASYPAY-5-8895-1005-CIN002", "status": "SUCCEEDED", "total_amount": { "currency": "EUR", "amount": "320.75" }, "number_of_items": 7, "destination": { "type": "IBAN", "details": { "iban": "PT50000201235555555555555" } } } } } } } }, "list-out-payments": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "$ref": "#/components/schemas/metadata-page" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/out-payment-response" } } } }, "examples": { "Response": { "value": { "meta": { "page": { "current": 1, "total": 0 }, "records": { "total": 0, "per_page": 1 }, "links": { "first": "?page=1", "prev": "", "next": "?page=2", "last": "?page=0" } }, "data": [ { "id": "20efcd82-be96-4aa0-89a1-c6365633a72e", "status": "success", "type": "normal", "method": "transfer", "customer": { "id": "09dbe8e2-5703-401e-9adc-6317f67a4fd9" }, "account": { "id": "76f190b9-2b8a-4bd0-9490-411241a9dc81" }, "out_account": { "id": "bcd387ca-1835-4c95-9003-2da45f39e396" }, "key": "", "value": 50, "schedule_at": "2022-09-15 20:28:58", "transactions": [ { "id": "20efcd82-be96-4aa0-89a1-c6365633a72e", "key": "", "date": "2022-09-15T21:28:58Z", "values": { "requested": -50, "paid": -50, "fixed_fee": 1, "variable_fee": 0, "tax": 0.23, "transfer": -51.23 }, "transfer_date": "2022-09-15T00:00:00Z", "transfer_batch": "", "method": "transfer", "document_number": "MARCEL0208220435165820220915212858", "descriptive": "" } ], "created_at": "2022-09-15 20:28:58", "timestamp": "" }, { "id": "12f21a3c-52a6-4274-ad1e-5e774093f7dd", "status": "success", "type": "normal", "method": "transfer", "customer": { "id": "b586685e-4e56-472b-b469-9b365c62d223" }, "account": { "id": "76f190b9-2b8a-4bd0-9490-411241a9dc81" }, "out_account": { "id": "898d3a41-8013-4262-a432-0bd09e301dff" }, "key": "", "value": 50, "schedule_at": "2022-09-16 08:03:25", "transactions": [ { "id": "12f21a3c-52a6-4274-ad1e-5e774093f7dd", "key": "", "date": "2022-09-16T09:03:27Z", "values": { "requested": -50, "paid": -50, "fixed_fee": 1, "variable_fee": 0, "tax": 0.23, "transfer": -51.23 }, "transfer_date": "2022-09-16T00:00:00Z", "transfer_batch": "", "method": "transfer", "document_number": "MARCEL0208220435236620220916090327", "descriptive": "" } ], "created_at": "2022-09-16 08:03:27", "timestamp": "" } ] } } } } } }, "create-out-payment": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "ok" }, "message": { "type": "array", "items": { "type": "string", "example": "Your request was successfully created" } }, "id": { "type": "string", "format": "uuid", "description": "A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced." }, "method": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "normal", "instant" ] }, "status": { "type": "string", "example": "pending", "enum": [ "pending", "delayed", "success", "deleted" ] } } }, "customer": { "type": "object", "description": "Customer associated with the out payment.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the customer." } } }, "out_account": { "type": "object", "description": "Destination SEPA bank account for the out payment.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the destination account." } } } } }, "examples": { "Example 1": { "value": { "status": "ok", "message": [ "Your request was successfully created" ], "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb", "method": { "type": "transfer", "status": "pending" }, "customer": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "out_account": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" } } } } } } }, "get-out-payment-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/out-payment-response" }, "examples": { "Response": { "value": { "id": "760d105e-950d-4b41-8017-cad840ca3baa", "status": "success", "type": "normal", "method": "transfer", "descriptive": "descriptive", "customer": { "id": "7e47c256-4bea-41a8-b578-727d60004c7a" }, "account": { "id": "76f190b9-2b8a-4bd0-9490-411241a9dc81" }, "out_account": { "id": "343a8a78-8deb-4d4a-aa41-0a9140c95346" }, "key": "Example Key", "value": 1, "schedule_at": "2022-11-25 10:30:11", "transactions": [ { "id": "760d105e-950d-4b41-8017-cad840ca3baa", "key": "Example Key", "date": "2022-11-25T10:30:14Z", "values": { "requested": -1, "paid": -1, "fixed_fee": 1, "variable_fee": 0, "tax": 0.23, "transfer": -2.23 }, "transfer_date": "2022-11-25T00:00:00Z", "transfer_batch": "", "method": "transfer", "document_number": "MARCEL0208220453362220221125103014", "descriptive": "" } ], "created_at": "2022-11-25 10:30:14" } } } } } }, "list-refund": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund-get-list-response" } } } }, "get-refund-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund-get-by-id-response" } } } }, "create-refund": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund-post-response" } } } }, "list-chargeback": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chargeback-list-response" } } } }, "get-chargeback-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/chargeback-get-by-id-response" } } } }, "list-link": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "metadata", "data" ], "properties": { "metadata": { "$ref": "#/components/schemas/metadata-cursor" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/link-response-object" }, "readOnly": true } } } } } }, "link-bad-request": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/bad-request-response" }, "examples": { "Example 1": { "value": { "type": "https://docs.easypay.pt/docs/error-handling#invalid-params-error-400", "title": "Invalid payload provided", "detail": "Your request parameters didn't validate", "status": 400, "invalid_params": [ { "name": "expiration_time", "reason": "expiration_time should be formatted as RFC 3339 and in the future" } ] } } } } } }, "link-forbidden": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/forbidden-response" } } } }, "link-conflict": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/conflict-response" } } } }, "internal-server-error": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/internal-server-error-response" } } } }, "create-link": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/link-response-object" } } } }, "not-implemented": { "description": "Not Implemented", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/not-implemented-response" } } } }, "get-link-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/link-response-object" } } } }, "link-not-found": { "description": "Not Found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/not-found-response" } } } }, "update-link": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "$ref": "#/components/schemas/link-response-object" } } } } } }, "get-customer-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/customer-detail" }, "examples": { "Success": { "description": "Success", "value": { "id": "649e88cf-0b78-4c36-8f99-33f5ebb812a1", "name": "John Doe", "email": "john.doe@example.com", "phone": "911234567", "phone_indicative": "+351", "fiscal_number": "PT123456789", "key": "customer Key Example", "language": "PT", "reward_balances": [ { "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "available_balance": 12.5 }, { "account_id": "569c3ad5-4103-5ef4-cbe5-af2711d10531", "available_balance": 3 } ] } } } } } }, "list-customer-rewards": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "metadata", "data" ], "properties": { "metadata": { "$ref": "#/components/schemas/metadata-cursor" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/reward-ledger-entry" }, "readOnly": true } } }, "examples": { "Success": { "description": "Success", "value": { "metadata": { "next_cursor": "lL_j7ilk7rc", "count": 6 }, "data": [ { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890", "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "type": "REWARD", "amount": 10, "expiration_date": "2027-01-15", "capture": { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "created_at": "2026-01-15T10:30:00Z" }, { "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901", "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "type": "REDEMPTION", "amount": 1.5, "capture": { "id": "e8267345-c5a0-4fa9-d166-5af905bec8dd" }, "created_at": "2026-02-10T14:22:00Z" }, { "id": "c3d4e5f6-a7b8-9012-cdef-012345678902", "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "type": "REWARD", "amount": 5, "expiration_date": "2027-06-01", "created_at": "2026-02-15T09:00:00Z" }, { "id": "d4e5f6a7-b8c9-0123-def0-123456789013", "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "type": "REWARD_EXPIRATION", "amount": 8.5, "expiration_date": "2027-01-15", "capture": { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "created_at": "2027-01-16T03:00:00Z" }, { "id": "e5f6a7b8-c9d0-1234-ef01-234567890124", "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "type": "REWARD_REVERSAL", "amount": 5, "capture": { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "created_at": "2026-03-02T11:05:00Z" }, { "id": "f6a7b8c9-d0e1-2345-f012-345678901235", "account_id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "type": "REWARD_RESTORATION", "amount": 1.5, "expiration_date": "2027-01-15", "capture": { "id": "e8267345-c5a0-4fa9-d166-5af905bec8dd" }, "created_at": "2026-03-02T11:05:00Z" } ] } } } } } }, "list-terminal": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "metadata", "data" ], "properties": { "metadata": { "$ref": "#/components/schemas/metadata-cursor" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/terminal" }, "readOnly": true } } }, "examples": { "Success": { "description": "Success", "value": { "metadata": { "next_cursor": "lL_j7ilk7rc", "count": 2 }, "data": [ { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "serial_number": "123-456-789", "name": "Terminal Checkout 1", "status": "ACTIVE", "acquirer": "VERIFONE", "model": "V240m", "last_transaction_at": "2025-08-05T13:44:29Z", "created_at": "2025-08-01T10:00:00Z" }, { "id": "569c3ad5-4103-5ef4-cbe5-af2711d10531", "serial_number": "SN987654321", "name": "Terminal Bar 1", "status": "INACTIVE", "acquirer": "VERIFONE", "model": "V400m", "last_transaction_at": "2025-08-04T18:30:00Z", "created_at": "2025-08-02T14:00:00Z" } ] } } } } } }, "create-terminal": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/terminal" }, "examples": { "Success": { "description": "Success", "value": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "serial_number": "123-456-789", "name": "Terminal Checkout 1", "status": "ACTIVE", "acquirer": "VERIFONE", "model": "V240m", "last_transaction_at": null, "created_at": "2025-08-05T13:44:29Z" } } } } } }, "get-terminal-details": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/terminal" }, "examples": { "Success": { "description": "Success", "value": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "serial_number": "123-456-789", "name": "Terminal Checkout 1", "status": "ACTIVE", "acquirer": "VERIFONE", "model": "V240m", "last_transaction_at": "2025-08-05T13:44:29Z", "created_at": "2025-08-01T10:00:00Z" } } } } } }, "update-terminal": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/terminal" }, "examples": { "Success": { "description": "Success", "value": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420", "serial_number": "123-456-789", "name": "Terminal Checkout 2", "status": "ACTIVE", "acquirer": "VERIFONE", "model": "V240m", "last_transaction_at": "2025-08-05T13:44:29Z", "created_at": "2025-08-01T10:00:00Z" } } } } } }, "ping": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "environment": { "type": "string", "example": "sandbox" }, "time": { "type": "string", "format": "date-time", "example": "2026-01-01T12:00:00Z" } } } } } } }, "requestBodies": { "create-single-payment": { "description": "Configuration object to generate a single payment", "content": { "application/json": { "schema": { "type": "object", "required": [ "value", "method" ], "properties": { "type": { "type": "string", "enum": [ "sale", "authorisation" ], "description": "Specifies the type of financial operation being performed. \n\nTYPE | DESCRIPTION |\n---------|----------|\n sale | a complete transaction where funds are immediately captured. |\n authorisation | a temporary hold on funds pending a future capture. |" }, "capture": { "$ref": "#/components/schemas/create-capture" }, "expiration_time": { "type": "string", "description": "The last possible time to make the payment. Applicable in Multibanco payments. This field is deprecated, use multibanco.expiration_time instead.", "example": "2017-12-12 16:05", "deprecated": true }, "currency": { "description": "ISO 4217 currency code. If not specified, the default currency is set to EUR.", "type": "string", "example": "EUR" }, "value": { "type": "number", "format": "double", "example": 17.5, "minimum": 0.5, "maximum": 999999.99, "description": "The monetary amount for the transaction. This field specifies the value of the payment in the designated currency. It must be a positive decimal number representing the exact amount to be processed." }, "method": { "type": "string", "description": "Enumerates the possible values for the payment method used in the transaction. This field helps to identify the selected payment method. Possible values include:\n\nMETHOD | DESCRIPTION |\n---------|--------------------|\n CC | Credit Card |\n VI | Digital IBAN |\n DD | Direct Debit |\n MB | Multibanco |\n MBW | MB WAY |\n GP | Google Pay* |\n AP | Apple Pay* |\n SW | Samsung Wallet* |\n IPP | In-Person Payment |\n\n

*payment only available through checkout yet

", "enum": [ "CC", "VI", "DD", "MB", "MBW", "GP", "AP", "SW", "IPP" ], "examples": [ "CC" ] }, "terminal": { "type": "object", "description": "An object that holds the details specific to the terminal used in the transaction. Required when `method` is `IPP`.", "required": [ "id" ], "properties": { "id": { "type": "string", "format": "uuid", "description": "The unique identifier of the terminal.", "example": "458b2fc4-3092-4de3-abd4-fe1600c09420" } } }, "key": { "type": "string", "maxLength": 50, "description": "A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.", "example": "Payment of Invoice Nº 1982652" }, "customer": { "$ref": "#/components/schemas/customer" }, "multibanco": { "type": "object", "description": "An object that holds the details specific to a Multibanco transaction.", "required": [ "expiration_time" ], "properties": { "expiration_time": { "type": "string", "format": "date-time", "description": "The end timestamp indicating the deadline by which the Multibanco Reference must be paid. It defines the final time within which the payment must be completed. The format follows RFC3339 (e.g., \"2024-06-30T21:38:31Z\")." }, "start_time": { "type": "string", "format": "date-time", "description": "The starting timestamp indicating when the Multibanco Reference becomes valid for payment. It defines the initial time from which the payment can be made. The format follows RFC3339 (e.g., \"2024-06-30T21:38:31Z\"). This field is optional and defaults to the current timestamp if not specified, or if the sent value is in the past." }, "product": { "type": "string", "enum": [ "FILE", "SPG", "CHECKDIGIT" ], "default": "CHECKDIGIT", "description": "This field is used to select the desired product. Below, the supported features for each product are listed. The default value is CHECKDIGIT. Additional costs may apply depending on the selected product.\n\n**Product Features:**\n\n| Product Type | Immediate Issuance | Expiration Date | Start Date |\n|--------------|-------------------|-----------------|------------|\n| CHECKDIGIT | ✓ | ✓ | ✗ |\n| SPG | ✗ | ✓ | ✓ |\n| FILE | ✗ | ✓ | ✓ |\n\n**Descriptions:**\n- **CHECKDIGIT**: Standard Multibanco references with immediate issuance\n- **SPG**: Special purpose group references with scheduling capabilities\n- **FILE**: File-based references for batch processing" } } }, "mbway": { "type": "object", "description": "An object that holds the details specific to an MB WAY transaction. Only applicable when `method` is `MBW`; it is ignored for any other method.", "properties": { "phone": { "type": "string", "maxLength": 20, "description": "The phone number to charge for the MB WAY payment, in full E.164 format (leading `+` and country code). When present, this number is charged instead of the one built from `customer.phone_indicative` and `customer.phone`, and `customer.phone` becomes optional. `customer.phone` is left untouched.", "example": "+351911234567" } } }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate" }, "notification": { "$ref": "#/components/schemas/notification" } } }, "examples": { "Multibanco": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example", "language": "EN" }, "key": "merchant identification key Example", "value": 15.5, "method": "MB", "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "transaction key Example" }, "notification": { "customer_method_instructions_email": true } } }, "Multibanco with product SPG": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example", "language": "EN" }, "key": "merchant identification key Example", "value": 15.5, "method": "MB", "multibanco": { "product": "SPG", "start_time": "2026-03-23T17:52:13Z", "expiration_time": "2029-03-23T17:52:13Z" }, "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "transaction key Example" }, "notification": { "customer_method_instructions_email": true } } }, "Multibanco with product FILE": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example" }, "key": "merchant identification key Example", "value": 15.5, "method": "MB", "multibanco": { "product": "FILE", "start_time": "2026-03-23T17:52:13Z", "expiration_time": "2029-03-23T17:52:13Z" }, "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "transaction key Example" }, "notification": { "customer_method_instructions_email": true } } }, "Multibanco with product CHECKDIGIT": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example" }, "key": "merchant identification key Example", "value": 15.5, "method": "MB", "multibanco": { "product": "CHECKDIGIT", "expiration_time": "2029-03-23T17:52:13Z" }, "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "transaction key Example" }, "notification": { "customer_method_instructions_email": true } } }, "Direct Debit": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example" }, "key": "merchant identification key Example", "value": 17.5, "method": "dd", "sdd_mandate": { "iban": "PT50002700000001234567833", "key": "Sdd mandate Key Example", "name": "Customer name Example", "email": "customer@example.com", "phone": "911234567", "account_holder": "acount holder name Example" }, "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "transaction key Example" } } }, "CC Authorisation": { "value": { "currency": "EUR", "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351" }, "key": "Example Key", "value": 17.5, "type": "authorisation", "method": "cc" } }, "CC Sale": { "value": { "currency": "EUR", "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351" }, "key": "Example Key", "value": 17.5, "type": "sale", "method": "cc", "capture": { "descriptive": "string", "transaction_key": "string" } } }, "MB WAY Authorisation": { "value": { "currency": "EUR", "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351" }, "key": "Example Key", "value": 17.5, "type": "authorisation", "method": "mbw" } }, "MB WAY Sale": { "value": { "currency": "EUR", "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351" }, "key": "Example Key", "value": 17.5, "type": "sale", "method": "mbw", "capture": { "descriptive": "string", "transaction_key": "string" } } }, "MB WAY Sale with dedicated payer phone": { "value": { "currency": "EUR", "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351" }, "mbway": { "phone": "+351922222222" }, "key": "Example Key", "value": 17.5, "type": "sale", "method": "MBW", "capture": { "descriptive": "string", "transaction_key": "string" } } }, "Virtual IBAN": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example", "language": "EN" }, "key": "merchant identification key Example", "value": 0.5, "method": "vi", "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "transaction key Example" }, "notification": { "customer_method_instructions_email": true } } }, "Sale with Reward Redemption": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example" }, "key": "merchant identification key Example", "value": 50, "method": "CC", "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "transaction key Example", "reward_redemption": { "account": { "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832" }, "value": 2.5 } } } }, "Sale with Splits and Rewards": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example" }, "key": "merchant identification key Example", "value": 649.99, "method": "CC", "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "808254-9734", "splits": [ { "split_key": "5d87a15c-dab6-441a-b9f6-ecd86171517e", "split_descriptive": "product", "account": { "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832" }, "margin_account": { "id": "b6f53027-0478-4728-9269-8bcc0f8088ea" }, "margin_value": 26.39, "reward": { "account": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "value": 5 }, "value": 649.99 } ] } } }, "Sale with Splits": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example" }, "key": "merchant identification key Example", "value": 649.99, "method": "CC", "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "808254-9734", "splits": [ { "split_key": "5d87a15c-dab6-441a-b9f6-ecd86171517e", "split_descriptive": "product", "account": { "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832" }, "margin_account": { "id": "b6f53027-0478-4728-9269-8bcc0f8088ea" }, "margin_value": 26.39, "value": 649.99 } ] } } }, "Sale with Splits and Reward Redemption": { "value": { "customer": { "id": "6726cd0e-6503-46ec-90da-e01c3838a9e9", "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "key": "customer Key Example" }, "key": "merchant identification key Example", "value": 100, "method": "CC", "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "808254-9734", "reward_redemption": { "account": { "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" }, "value": 10 }, "splits": [ { "split_key": "5d87a15c-dab6-441a-b9f6-ecd86171517e", "split_descriptive": "Marketplace seller", "account": { "id": "7e697e0c-c2bf-422a-9535-ab0b750bb832" }, "margin_account": { "id": "b6f53027-0478-4728-9269-8bcc0f8088ea" }, "margin_value": 5, "value": 70 }, { "split_descriptive": "Platform share", "account": { "id": "c3d4e5f6-a1b2-7890-abcd-ef1234567890" }, "value": 20 } ] } } }, "IPP Sale": { "value": { "value": 17.5, "method": "IPP", "terminal": { "id": "458b2fc4-3092-4de3-abd4-fe1600c09420" }, "capture": { "descriptive": "transaction descriptive Example", "transaction_key": "transaction key Example" } } } } } }, "required": true }, "update-single": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expiration_time": { "type": "string", "deprecated": true }, "currency": { "description": "ISO 4217 currency code. If not specified, the default currency is set to EUR.", "type": "string", "example": "EUR" }, "customer": { "$ref": "#/components/schemas/updatable-customer" }, "key": { "$ref": "#/components/schemas/key" }, "sdd_mandate": { "$ref": "#/components/schemas/updatable-sdd-mandate" } } } } } }, "create-frequent-payment": { "content": { "application/json": { "schema": { "type": "object", "properties": { "expiration_time": { "type": "string", "description": "Expiration date and time for the payment in YYYY-MM-DD HH:mm format", "example": "2038-12-12 16:05" }, "currency": { "type": "string", "enum": [ "EUR", "BRL" ], "default": "EUR", "description": "Currency code for the payment", "example": "EUR" }, "customer": { "$ref": "#/components/schemas/customer" }, "key": { "type": "string", "description": "The merchant's key for identifying the payment.", "maxLength": 50, "example": "Key Example" }, "min_value": { "type": "number", "format": "double", "minimum": 0.01, "description": "Minimum value allowed for transactions", "example": 10 }, "max_value": { "type": "number", "format": "double", "minimum": 0.01, "description": "Maximum value allowed for transactions", "example": 25.5 }, "unlimited_payments": { "type": "boolean", "default": true, "description": "Transactions will be unlimited, max or min value will be refreshed on each payment." }, "method": { "type": "string", "enum": [ "MB", "CC", "DD", "MBW", "VI" ], "description": "Payment method type", "example": "DD" }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate" }, "multibanco": { "type": "object", "description": "Configuration of the Multibanco payment", "properties": { "reference": { "type": "string", "minLength": 9, "maxLength": 9, "pattern": "^[0-9]*$", "example": "505237431", "description": "This field controls which reference is going to be created. It's only available if you have an exclusive Multibanco entity." } }, "required": [ "reference" ] } }, "required": [ "customer", "method" ] }, "examples": { "Create a Frequent Payment DD": { "value": { "expiration_time": "2038-12-12 16:05", "currency": "EUR", "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "351", "fiscal_number": "PT123456789", "key": "Key Example", "language": "PT" }, "key": "Key Example", "max_value": 25.5, "min_value": 10, "unlimited_payments": true, "method": "DD", "sdd_mandate": { "iban": "PT50002700000001234567833", "key": "Key Example", "name": "Name Example", "email": "customer@example.com", "phone": "911234567", "account_holder": "Acount Name Example", "country_code": "PT", "max_num_debits": "12" } } }, "Create a Frequent Payment CC": { "value": { "expiration_time": "2038-12-12 16:05", "currency": "EUR", "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "351", "fiscal_number": "PT123456789", "key": "Key Example", "language": "PT" }, "key": "Key Example", "max_value": 999.99, "min_value": 10, "unlimited_payments": true, "method": "CC" } }, "Create a Frequent Payment MBW": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "351", "fiscal_number": "PT123456789", "key": "Key Example", "language": "PT" }, "key": "Key Example", "max_value": 999.99, "min_value": 1, "unlimited_payments": true, "method": "MBW" } }, "Create a Frequent Payment MB": { "value": { "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "351", "fiscal_number": "PT123456789", "key": "Key Example", "language": "PT" }, "key": "Key Example", "max_value": 999.99, "min_value": 10, "method": "MB" } }, "Create a Frequent Payment VI": { "value": { "key": "Key Example", "max_value": 999.99, "min_value": 10, "method": "VI" } } } } } }, "update-frequent": { "description": "Frequent Payment object to edit existing one", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active", "deleted" ], "description": "Status of the frequent payment", "example": "active" }, "expiration_time": { "type": "string", "format": "Y-m-d H:i", "description": "Expiration date and time for the payment", "example": "2017-12-12 16:05" }, "currency": { "$ref": "#/components/schemas/currency" }, "customer": { "$ref": "#/components/schemas/customer" }, "key": { "type": "string", "description": "The merchant's key for identifying the payment.", "maxLength": 50, "example": "Key Example" }, "max_value": { "type": "number", "format": "double", "minimum": 0.01, "description": "Maximum value allowed for transactions", "example": 25.5 }, "min_value": { "type": "number", "format": "double", "minimum": 0.01, "description": "Minimum value allowed for transactions", "example": 10 }, "unlimited_payments": { "type": "boolean", "default": true, "description": "Transactions will be unlimited, max or min value will be refreshed on each payment." }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate" } } }, "examples": { "Update frequent payment": { "value": { "status": "active", "expiration_time": "2038-12-12 16:05", "currency": "EUR", "customer": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93", "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "fiscal_number": "PT123456789", "key": "Key Example", "language": "PT" }, "key": "Example Key", "max_value": 20, "min_value": 2, "unlimited_payments": false, "sdd_mandate": { "id": "12345678901", "iban": "PT50002700000001234567833", "key": "Key Example", "name": "Name Example", "email": "customer@example.com", "phone": "911234567", "account_holder": "Account Name Example", "country_code": "PT", "max_num_debits": "12" } } } } } }, "required": true }, "frequent-authorisation": { "description": "Payment configuration object to generate a payment", "content": { "application/json": { "schema": { "type": "object", "properties": { "mbway_sdk": { "type": "object", "description": "MB WAY SDK configuration for payment processing", "deprecated": true, "properties": { "purchase_token": { "type": "string", "description": "Purchase token for MB WAY SDK" }, "initial_timestamp": { "type": "string", "description": "Initial timestamp for the transaction", "example": "2018-01-01 23:59:59" }, "merchant_operation_id": { "type": "string", "description": "unique-concatenation between client identifier and client operation id.", "maxLength": 20, "example": "TESTACCOUNT5436" }, "payload": { "type": "string", "description": "JSON payload for MB WAY SDK" } } }, "transaction_key": { "type": "string", "description": "Your internal key identifying this authorisation.", "maxLength": 255, "example": "transaction_key_123" }, "force_3ds": { "type": "boolean", "default": false, "description": "Whether or not you want to force the 3DS authentication." }, "descriptive": { "type": "string", "description": "This will appear in the bank statement/MB WAY application.", "maxLength": 255, "example": "Descriptive Example" }, "value": { "type": "number", "description": "Value will be rounded to 2 decimals.", "format": "double", "minimum": 0.5, "example": 10.5 } }, "required": [ "descriptive", "value" ] }, "examples": { "Create MB WAY Frequent Authorisation": { "value": { "transaction_key": "string", "descriptive": "Descriptive Example", "value": 17.5 } }, "Create CC Frequent Authorisation": { "value": { "transaction_key": "string", "descriptive": "Descriptive Example", "value": 17.5 } }, "Create CC Frequent Authorisation with 3DS authentication": { "value": { "transaction_key": "string", "descriptive": "Descriptive Example", "value": 17.5, "force_3ds": true } } } } }, "required": true }, "patch-config": { "description": "Configuration object to edit an account.", "content": { "application/json": { "schema": { "type": "object", "properties": { "generic": { "type": "string", "description": "URL for generic notification.", "maxLength": 255, "example": "https://www.easypay.pt/generic" }, "authorisation": { "type": "string", "description": "URL for authorisation notification.", "maxLength": 255, "example": "https://www.easypay.pt/authorisation" }, "transaction": { "type": "string", "description": "URL for transaction notification.", "maxLength": 255, "example": "https://www.easypay.pt/transaction" }, "visa_fwd": { "type": "string", "description": "URL for redirect clients on credit card forward.", "maxLength": 255, "example": "https://www.easypay.pt/visa_fwd" }, "visa_detail": { "type": "string", "description": "URL for credit card payment detail.", "maxLength": 255, "example": "https://www.easypay.pt/visa_detail" } } }, "examples": { "Example 1": { "value": { "generic": "https://www.easypay.pt/generic", "authorisation": "https://www.easypay.pt/authorisation", "transaction": "https://www.easypay.pt/transaction", "visa_fwd": "https://www.easypay.pt/visa_fwd", "visa_detail": "https://www.easypay.pt/visa_detail" } } } } }, "required": true }, "create-capture": { "description": "Created", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/capture-post-request" } } } }, "update-capture-split": { "description": "Payment configuration object to generate a payment", "content": { "application/json": { "schema": { "type": "object", "properties": { "clearing_date": { "type": "string", "format": "date", "description": "The new date for the split to be cleared.
This field must be in the future and no longer than 2 years from today.", "example": "2006-01-02" } } } } } }, "create-checkout": { "description": "Checkout request details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/checkout-request" }, "examples": { "Create Checkout": { "value": { "type": [ "single" ], "payment": { "methods": [ "MB", "CC", "MBW", "DD", "VI", "AP", "GP", "SW" ], "type": "sale", "capture": { "descriptive": "Descriptive Example" }, "expiration_time": "2025-06-12 11:24", "currency": "EUR", "key": "Example Key", "sdd_mandate": { "iban": "PT50002700000001234567833", "name": "Name Example", "email": "customer@example.com", "phone": "911234567", "account_holder": "Account Name Example" }, "max_value": 20, "min_value": 2, "unlimited_payments": false, "frequency": "1W", "max_captures": 10, "start_time": "2025-06-12 11:24", "failover": true, "capture_now": true, "retries": 2, "multibanco": { "product": "SPG", "start_time": "2025-07-25T10:22:53Z", "expiration_time": "2025-08-24T10:22:52Z" } }, "order": { "items": [ { "description": "Item in Shopping Cart", "quantity": 2, "key": "Example Key", "value": 17.5 } ], "key": "Example Key", "value": 17.5 }, "customer": { "name": "Customer Example", "email": "customer@example.com", "phone": "911234567" } } }, "Alternative Example": { "value": { "type": "single", "payment": { "methods": [ "MBW" ], "type": "sale", "capture": { "transaction_key": "string", "capture_date": "2026-05-15", "account": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "splits": { "split_key": "01J1PKR2RPHJNJQGFWGDYXY0KM", "split_descriptive": "Payment of Invoice Nº 1982652", "value": 15.32, "account": { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "margin_value": 0, "margin_account": { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb" }, "clearing_period": "7D" }, "descriptive": "Small description of the capture" }, "expiration_time": "2027-12-12 16:05", "currency": "EUR", "key": "string", "max_value": 0.5, "min_value": 0.5, "unlimited_payments": true, "frequency": "1D", "max_captures": 0, "start_time": "2019-08-24", "failover": true, "capture_now": true, "retries": 0, "multibanco": { "expiration_time": "string", "start_time": "string", "product": "CHECKDIGIT" } }, "order": { "items": [ { "description": "Description Example", "quantity": 2, "key": "Key Example", "value": 10.55 } ], "key": "Example Key", "value": 50.78 }, "customer": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "name": "John Doe", "email": "example@easypay.pt", "phone": "911234567", "phone_indicative": "+351", "language": "EN", "fiscal_number": "PT268826145", "key": "Key Example" } } } } } }, "required": true }, "create-subscription": { "description": "Payment configuration object to generate a payment", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "frequent_id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50", "capture": { "transaction_key": "string", "account": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93" }, "descriptive": "Descriptive Example" }, "expiration_time": "2017-12-12 16:05", "currency": "EUR", "customer": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93", "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "fiscal_number": "PT123456789", "key": "Key Example", "language": "PT" }, "key": "Example Key", "value": 17.5, "frequency": "1D", "max_captures": 10, "start_time": "2017-12-12 16:05", "failover": true, "capture_now": true, "retries": 2, "method": "CC", "sdd_mandate": { "id": "12345678901", "iban": "PT50002700000001234567833", "key": "Key Example", "name": "Name Example", "email": "customer@example.com", "phone": "911234567", "account_holder": "Acount Name Example", "country_code": "PT", "max_num_debits": "12" } } }, "required": [ "value", "frequency", "start_time", "method" ], "properties": { "frequent_id": { "description": "Only required to create a subscription \nfrom an active Frequent Payment.
\nSome properties like \n```customer``` and ```sdd_mandate``` \nare inherited by the subscriptions.
\nSo it's not necessary to send them in the request creation.", "type": "string", "format": "uuid", "example": "9234ef0f-b666-41cc-8ad2-5b54c1a84150" }, "capture": { "type": "object", "properties": { "transaction_key": { "type": "string", "description": "The internal key used to identify this transaction in the merchant's database.", "maxLength": 50 }, "account": { "type": "object", "description": "For multi-account clients.", "properties": { "id": { "type": "string", "description": "The uuid of the account.", "format": "uuid" } } }, "descriptive": { "type": "string", "description": "The description of the capture. Will be displayed in the bank statement or in the MB WAY application.", "maxLength": 255 } } }, "expiration_time": { "type": "string", "description": "The last possible time to make the payment.
\nRequired only when ```max_captures```\nand/or ```unlimited_payments```\nare **NOT** set.", "format": "Y-m-d H:i", "example": "2037-12-12 16:05" }, "currency": { "type": "string", "description": "The currency code in ISO 4217 format (e.g., \"EUR\" for Euro). This field specifies the type of currency used in financial operation." }, "customer": { "$ref": "#/components/schemas/customer" }, "key": { "type": "string", "description": "The merchant's key for identifying the payment.", "maxLength": 50, "example": "Example Key" }, "value": { "type": "number", "description": "The payment value.
Will be rounded to 2 decimals.", "format": "double", "minimum": 0.5, "example": 12.55 }, "frequency": { "$ref": "#/components/schemas/frequency" }, "max_captures": { "type": "integer", "description": "Defining the total of cycles that will be charged.
\nRequired only when ```expiration_time```\nand/or ```unlimited_payments```\nare **NOT** set." }, "unlimited_payments": { "type": "boolean", "default": false, "description": "When this property is set, unlimited cycles will be charged until the subscription is inactivated or deleted." }, "start_time": { "type": "string", "example": "2027-01-11 16:05", "description": "Defining the start of billing cycles.", "format": "Y-m-d H:i" }, "failover": { "type": "boolean", "default": false, "description": "After all retries failed, the payment cycle can have another try with another single method." }, "capture_now": { "type": "boolean", "description": "Whether to schedule an immediate capture and schedule the second one for start_time.", "default": false }, "retries": { "type": "integer", "default": 0, "description": "Number of tries for every cycle of payments.
\nThe maximum number of retries that can occur will be determined by the frequency that is selected.
\nIf a capture is unsuccessful for any reason, it will attempt to charge once more until the allotted number of attempts is reached." }, "method": { "type": "string", "example": "CC", "enum": [ "CC", "DD" ], "description": "The payment methods." }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate" } } }, "examples": { "Create a Subscription with a CC payment method": { "value": { "expiration_time": "2022-12-04 12:00", "max_captures": 2, "start_time": "2022-12-04 12:00", "value": 17.55, "frequency": "1D", "method": "CC" } }, "Create a Subscription with a DD payment method": { "value": { "max_captures": 2, "start_time": "2022-12-04 12:00", "value": 17.5, "frequency": "1Y", "method": "DD", "sdd_mandate": { "iban": "PT50002700000001234567833", "name": "Frequent Payment DD", "email": "customer@example.com", "phone": "911234567", "account_holder": "Account Name Example", "key": "Sdd Mandate key" } } }, "Full filled example": { "value": { "frequent_id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50", "capture": { "transaction_key": "string", "account": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93" }, "descriptive": "Descriptive Example" }, "expiration_time": "2017-12-12 16:05", "currency": "EUR", "customer": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93", "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "fiscal_number": "PT123456789", "key": "Key Example", "language": "PT" }, "key": "Example Key", "value": 17.5, "frequency": "1D", "max_captures": 10, "start_time": "2017-12-12 16:05", "failover": true, "capture_now": true, "retries": 2, "method": "CC", "sdd_mandate": { "id": "12345678901", "iban": "PT50002700000001234567833", "key": "Key Example", "name": "Name Example", "email": "customer@example.com", "phone": "911234567", "account_holder": "Acount Name Example", "country_code": "PT", "max_num_debits": "12" } } }, "Create a Subscription with a Frequent Payment": { "value": { "frequent_id": "8f952787-4110-40e5-b1ee-f8f041cb9881", "retries": 2, "capture_now": true, "key": "Payment Key Key", "max_captures": 999, "start_time": "2025-08-05 10:25", "expiration_time": "2099-12-25 23:25", "value": 10.99, "frequency": "1M", "method": "DD" } }, "Create a Subscription with unlimited payments": { "value": { "retries": 2, "capture_now": true, "key": "Payment Key Key", "start_time": "{{date}}", "unlimited_payments": true, "value": 10.99, "frequency": "1M", "method": "CC" } } } } }, "required": true }, "update-subscription": { "description": "Subscription Payment object to edit existing one", "content": { "application/json": { "schema": { "type": "object", "x-examples": { "example-1": { "status": "inactive", "expiration_time": "2017-12-12 16:05", "currency": "EUR", "customer": { "id": "22ea3cc9-424b-489a-91b7-8955f643dc93", "name": "Customer Example", "email": "customer@example.com", "phone": "911234567", "phone_indicative": "+351", "fiscal_number": "PT123456789", "key": "Key Example", "language": "PT" }, "key": "Example Key", "value": 17.5, "max_captures": 10, "failover": true, "retries": 2, "sdd_mandate": { "id": "12345678901", "iban": "PT50002700000001234567833", "key": "Key Example", "name": "Name Example", "email": "customer@example.com", "phone": "911234567", "account_holder": "Acount Name Example", "country_code": "PT", "max_num_debits": "12" } } }, "properties": { "status": { "type": "string", "description": "The Subscription Status.
\nWhen sets to ```inactive``` the next pending cycles will be deleted.
\nWhen sets to ```active``` a new billing cycle will be schedule \naccordingly the new ```frequency``` and ```start_time```.
\n**Those properties are required to active a subscription.**", "enum": [ "active", "inactive" ], "example": "active" }, "capture": { "type": "object", "properties": { "transaction_key": { "type": "string", "description": "The internal key used to identify this transaction in the merchant's database.", "maxLength": 50 }, "account": { "type": "object", "description": "For multi-account clients.", "properties": { "id": { "type": "string", "description": "The uuid of the account.", "format": "uuid" } } }, "descriptive": { "type": "string", "description": "The description of the capture. Will be displayed in the bank statement or in the MB WAY application.", "maxLength": 255 } } }, "expiration_time": { "type": "string", "format": "Y-m-d H:i", "example": "2039-12-12 16:05" }, "currency": { "$ref": "#/components/schemas/currency" }, "customer": { "$ref": "#/components/schemas/updatable-customer" }, "key": { "type": "string", "description": "The merchant's key for identifying the payment.", "maxLength": 50, "example": "Example Key" }, "value": { "type": "number", "description": "The payment value.
Will be rounded to 2 decimals.", "format": "double", "minimum": 0.5, "example": 12.55 }, "frequency": { "$ref": "#/components/schemas/frequency" }, "max_captures": { "type": "integer", "description": "Defining the total of cycles that will be charged.
\nWhen this property is set, ```unlimited_payments``` will be inactivated." }, "unlimited_payments": { "type": "boolean", "description": "When this property is set, unlimited cycles will be charged until the subscription is inactivated or deleted." }, "start_time": { "type": "string", "example": "2025-12-12 16:05", "description": "Defining the start of billing cycles.", "format": "Y-m-d H:i" }, "failover": { "type": "boolean", "default": false, "description": "After all retries failed, the payment cycle can have another try with another single method." }, "retries": { "type": "integer", "default": 0, "description": "Number of retries in each payment cycle.
\nThe chosen frequency will define the max number of possible retries." }, "sdd_mandate": { "$ref": "#/components/schemas/sdd-mandate" } } }, "examples": { "Full PATCH": { "value": { "capture": { "transaction_key": "Transaction Key", "descriptive": "subscription" }, "retries": 2, "customer": { "email": "john.doe@example.com", "key": "Customer Key", "language": "PT" }, "key": "Payment Key Key", "max_captures": 12, "start_time": "2025-08-06 11:07", "expiration_time": "2099-08-06 11:07", "value": 10.99, "frequency": "1M", "method": "DD", "sdd_mandate": { "iban": "PT50002700000001234567833", "name": "John Doe", "email": "john.doe@example.com", "phone": "911234567", "account_holder": "John Doe", "key": "SDD Mandate key", "max_num_debits": "12" } } }, "Example 1": { "value": { "status": "active", "capture": { "transaction_key": "string", "account": { "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08" }, "descriptive": "string" }, "expiration_time": "2039-12-12 16:05", "currency": "EUR", "customer": { "name": "Jonh Doe", "email": "user@example.com", "phone": "962496235", "phone_indicative": "351", "fiscal_number": "PT277712580", "key": "01J1PKR2RPHJNJQGFWGDYXY0KM", "language": "PT" }, "key": "Example Key", "value": 12.55, "frequency": "1D", "max_captures": 0, "unlimited_payments": true, "start_time": "2025-12-12 16:05", "failover": false, "retries": 0, "sdd_mandate": { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb", "iban": "PT50000747199140461443823", "key": "01J1PKR2RPHJNJQGFWGDYXY0KM", "name": "string", "email": "string", "phone": "string", "account_holder": "string", "country_code": "string", "max_num_debits": "string", "billing_entity": "PT16103627" } } } } } }, "required": true }, "create-one-time-charge": { "description": "Details of the one-off cycle to capture on an active subscription.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "number", "format": "double", "minimum": 0.5, "example": 10.5, "description": "Must have at most two decimal places." }, "capture_at": { "type": "string", "format": "Y-m-d H:i", "example": "2037-12-12 09:00", "description": "When to schedule the charge, in UTC. Must not be in the past. Omit to capture immediately." }, "description": { "type": "string", "maxLength": 255, "example": "extra subscription charge", "description": "Free-form text shown on the bank statement or in the MB WAY app." }, "key": { "type": "string", "maxLength": 50, "example": "one-time-charge-key", "description": "Your internal identifier for this charge. Useful for reconciliation on your side." } } }, "examples": { "Capture now": { "summary": "Charge the subscription immediately", "value": { "value": 10.5, "description": "extra subscription charge", "key": "one-time-charge-key" } }, "Schedule for later": { "summary": "Schedule the charge for a specific moment", "value": { "value": 25, "capture_at": "2037-12-12 09:00", "description": "Add-on charge", "key": "add-on-2037-12-12" } } } } } }, "update-cycle": { "description": "New amount to charge on this cycle.", "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "value" ], "properties": { "value": { "type": "number", "format": "double", "minimum": 0.01, "maximum": 999999.99, "example": 99.99, "description": "New amount for the cycle, in euros. Must have at most two decimal places." } } }, "examples": { "Update amount": { "summary": "Override the cycle's charge value", "value": { "value": 99.99 } } } } } }, "create-void": { "description": "Void details", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/void-post-request" } } } }, "create-out-payment": { "content": { "application/json": { "schema": { "type": "object", "required": [ "customer", "value", "out_account", "method", "timestamp" ], "properties": { "customer": { "$ref": "#/components/schemas/customer" }, "key": { "type": "string", "description": "Merchant identification key", "maxLength": 50 }, "value": { "type": "number", "minimum": 0.5, "format": "double", "description": "Value will be rounded to 2 decimals" }, "type": { "type": "string", "enum": [ "normal", "instant" ], "description": "Optional - only applicable to method transfer", "default": "normal" }, "schedule_at": { "type": "string", "description": "Scheduled date and time to execute the payment, in `YYYY-MM-DD HH:MM` format (UTC, no timezone suffix).", "example": "2026-04-24 16:25" }, "descriptive": { "type": "string", "pattern": "^[a-zA-Z0-9 .,/+*$%]+$", "maxLength": 140, "description": "Description for the out payment." }, "account": { "$ref": "#/components/schemas/account" }, "out_account": { "$ref": "#/components/schemas/out-account" }, "method": { "type": "string", "default": "transfer", "example": "transfer", "enum": [ "transfer", "mb" ] }, "timestamp": { "type": "string", "description": "Unix timestamp UTC, must be no more than 1 minute before or after real time, if not the strong authentication signature will not be valid" } } }, "examples": { "Create with new customer": { "value": { "customer": { "name": "Customer Example", "email": "user@example.com", "phone": "911234567", "phone_indicative": "+351", "fiscal_number": "PT123456789", "key": "Example Key", "language": "PT" }, "key": "Example Key", "value": 0.5, "type": "normal", "schedule_at": "2026-04-24 16:25", "descriptive": "Descriptive Example", "out_account": { "account_holder": "Acount Name Example", "iban": "PT50002700000001234567833", "email": "customer@example.com", "phone": "351911234567", "key": "Key Example", "country_code": "PT" }, "method": "transfer", "timestamp": "1696642539" } } } } } }, "create-refund": { "description": "Request body for creating a refund", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/refund-post-request" }, "examples": { "Refund": { "value": { "transaction_key": "transaction key Example", "value": 17.5 } }, "Refund with Total Revert": { "value": { "transaction_key": "transaction key Example", "value": 100, "revert": { "mode": "total" } } }, "Refund with Partial Revert": { "value": { "transaction_key": "transaction key Example", "value": 70, "revert": { "mode": "partial", "splits": [ { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb" } ] } } }, "Refund with Partial Revert and Reward Redemption Reversal": { "value": { "transaction_key": "transaction key Example", "value": 70, "revert": { "mode": "partial", "reward_redemption_reversal": 7, "splits": [ { "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb" } ] } } } } } } }, "create-link": { "content": { "application/json": { "schema": { "type": "object", "required": [ "expiration_time", "type", "customer", "payment" ], "properties": { "expiration_time": { "type": "string", "format": "date-time", "description": "RFC3339 formatted time for the link expiration date. It has to be in the future and can't go past the year 2037. For subscriptions, it also can't be later than the subscription's own expiration_time.", "example": "2026-06-10T09:27:55.339Z" }, "type": { "$ref": "#/components/schemas/payment-types-request", "description": "Specifies the type of payment being performed.\nPossible values are \"Single\" (One-time transactions that will let your customers pay an amount of money to you),\n\"Frequent\" (Are repeatable transactions of varying sums without the client having to enter their payment details again),\nand \"Subscription\" (periodic payments of the same amount of money, configured through Checkout or our Payments API)." }, "customer": { "$ref": "#/components/schemas/customer-request", "description": "The Customer object contains detailed information about the customer involved in the transaction." }, "communication_channels": { "$ref": "#/components/schemas/communication-channels-request" }, "payment": { "type": "object", "description": "Payment object with the payment method, capture object and payment type object (Single, Frequent, Subscription). Send exactly one of single, frequent or subscription, and make it match the type you asked for. Only single is available for now, frequent and subscription links answer with a 501.", "required": [ "methods" ], "properties": { "methods": { "$ref": "#/components/schemas/payment-methods-request" }, "capture": { "$ref": "#/components/schemas/capture-request" }, "single": { "$ref": "#/components/schemas/single-request" }, "frequent": { "$ref": "#/components/schemas/frequent-request" }, "subscription": { "$ref": "#/components/schemas/subscription-request" } } }, "notification": { "$ref": "#/components/schemas/notification-request" } } }, "examples": { "Create Single payment Pay-by-link with several payment methods and sms and email communication channel": { "value": { "type": "SINGLE", "expiration_time": "2033-12-29T23:59:59.999Z", "payment": { "single": { "requested_amount": "21.55" }, "methods": [ "CC", "MBW", "MB", "DD", "VI" ], "capture": { "descriptive": "string", "key": "string" } }, "customer": { "name": "pedro barros", "email": "barros@gmail.com", "phone": "+351911234567", "language": "PT" }, "communication_channels": [ "SMS", "EMAIL" ], "notification": { "customer_method_instructions_email": true } } }, "Create Single payment Pay-by-link with one payment method and no communication channel": { "value": { "type": "SINGLE", "expiration_time": "2033-12-29T23:59:59.999Z", "payment": { "single": { "requested_amount": "31.55" }, "methods": [ "MBW" ], "capture": { "descriptive": "string", "key": "string" } }, "customer": { "name": "pedro barros", "language": "PT" } } } } } } }, "update-link": { "content": { "application/json": { "schema": { "type": "object", "required": [ "expiration_time" ], "properties": { "expiration_time": { "type": "string", "format": "date-time", "description": "RFC3339 formatted time for the link expiration date" } } } } } }, "create-terminal": { "description": "Terminal object to create a new terminal", "content": { "application/json": { "schema": { "type": "object", "required": [ "serial_number", "name", "acquirer" ], "properties": { "serial_number": { "type": "string", "description": "The serial number of the terminal device. Unique per acquirer.", "maxLength": 255, "example": "123-456-789" }, "name": { "type": "string", "description": "The name of the terminal. Must be unique.", "maxLength": 255, "example": "Terminal Checkout 1" }, "acquirer": { "type": "string", "enum": [ "VERIFONE" ], "description": "The acquirer associated with the terminal.", "example": "VERIFONE" } } }, "examples": { "Create a Terminal": { "value": { "serial_number": "123-456-789", "name": "Terminal Checkout 1", "acquirer": "VERIFONE" } } } } }, "required": true }, "update-terminal": { "description": "Terminal object to update an existing terminal", "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "The name of the terminal. Must be unique.", "maxLength": 255, "example": "Terminal Checkout 2" } } }, "examples": { "Update Terminal name": { "value": { "name": "Terminal Checkout 2" } } } } }, "required": true } } } }