Download OpenAPI specification:Download
The easypay API is a collection of web services that allow you to receive payments from customers, be notified of those payments, refund them if necessary, among others.
The API endpoints are available through the following domains:
https://api.test.easypay.pt/
https://api.prod.easypay.pt/
To create credentials for your account you can follow this guide.
Server-to-server requests to easypay APIs must be authenticated via Account ID and API Key. To do so, include the following HTTP headers in your API requests:
AccountId: <YOUR_ACCOUNT_ID>
ApiKey: <YOUR_API_KEY>
When these headers are missing or incorrect, a 403
HTTP status code is returned.
For your convenience, during tests you can use the following ID/Key pair:
AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6
ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92
These will only work for testing purposes and won't work in production.
Easypay uses HTTP response status codes to indicate the success or failure of your API requests. If your request fails, Easypay returns an error using the appropriate status code.
In general, there are three status code ranges you can expect:
2xx
success status codes confirm that your request worked as expected4xx
error status codes indicate an error because of the information provided (for example, a required parameter was omitted).5xx
error status codes are rare and indicate an error with Easypay’s servers.Some 4xx
errors that could be handled programmatically (for example, a card is declined) include an error code (a short string with a brief explanation) as a value for code
.
Below is a list of possible error codes that can be returned, along with additional information about how to resolve them. For your convenience, these types of errors also include the doc_url
attribute with a direct link to the specific error code it corresponds to.
This error can have multiple potential causes. Here are some examples:
This error can only have one cause, you provided an invalid/unsupported content type header.
This error happens when you provide a bad formated JSON payload.
This error indicates the information provided was incorrect of insufficient (for example, a required parameter was omitted).
This error indicates that an unexpected error ocurred on our servers.
Easypay API incorporates idempotency that enables the safe re-submission of requests, eliminating the risk of unintentionally duplicating operations.
This helps to circumvent unintentional replication due to failures and retries.
For instance, in an event of a timeout error, you can securely resend the same API payment call several times, assured that the payment detail will be debited only once.
To execute an idempotent request, simply include an additional Idempotency-Key
header within the request parameters.
curl -L -X POST 'https://api.test.easypay.pt/2.0/checkout' \
-H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
-H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
-H 'Idempotency-Key: 435e08a0-e5a9-4216-acb5-44d6b96de612' \
-H 'Content-Type: application/json' \
--data-raw '{ "type": [ "single" ] ... }'
You can check if a request is a replay by checking if the Idempotency-Replay
Header is present in the response and if it has the value "true"
.
Although the technique of creating unique keys is your choice, remember random string with sufficient entropy to prevent overlaps is advisable.
Easypay recommends the use of UUID V4 or ULID as Idempotency Key.
The maximum length for idempotency key is 50 characters.
Two requests with the same Idempotency-Key but different AccountId headers will be treated as different requests.
Easypay manages idempotency by storing the initial status code and response body for the initial request with a specific idempotency key.
The Idempotency layer compares the request body of the incoming request with that of the original request.
If they differ, the system triggers an error to prevent inadvertent misuse.
Repeated requests bearing the same key yield identical outcomes. The only exception pertains to transient errors, which we have identified as the following:
The previously mentioned error codes are safe to retry.
To help the client applications decide whether to retry calls, the API's responses include an X-Easypay-Should-Retry
header with value "true"
or "false"
.
Note that this header does not take into account the number of tries already made, so clients should keep track and only send a limited number of equal requests (e.g. 3).
If and when the header is not present, clients can use the following strategy to determine what to do:
POST
request.Idempotency Keys are automatically purged from the system once they've been in existence for 24 hours, and a fresh request is initiated if a key is reused after its original has been deleted.
Only results from API endpoints that have started execution are stored.
If your request fails authentication, it will not be governed by idempotency rules.
Idempotency keys are acceptable in all POST/PATCH requests.
It is unnecessary and should be avoided to supply idempotency keys in GET and DELETE requests, as these types of requests are inherently idempotent by nature.
Payment methods are defined according to two different categories:
Each method of payment is categorized as either pull or push, depending on how funds are transferred from the customer’s payment method.
In a method with a pull behaviour, the customer needs only to accept the payment request from the merchant. Credit card payments and MB WAY are examples of the described behaviour. On the credit card, the customer accepts the payment by providing his credit card details, while on MB WAY they accept by interacting with the push notification on the smartphone.
In a method with a push behaviour, the customer takes the initiative of sending the funds to the merchant. Virtual IBAN or Multibanco are examples of such behaviour. On the Virtual IBAN, the customer should go to their bank account and create a SEPA transfer to the provided IBAN. On Multibanco, the customer should go to an ATM and create a payment to the entity and reference provided.
A Credit / Debit card is a payment card issued to users (cardholders) to enable the cardholder to pay a merchant for a good or service. This is a synchronous pull payment method. This means that the payment happens immediately. Credit / Debit cards also support authorizations where you can hold an amount for later capture.
Apple Pay is a mobile payment and digital wallet service by Apple Inc. that allows users to make payments in iOS apps, and on the web using Safari. It is supported on the iPhone, Apple Watch, iPad, and Mac. Apple Pay is a synchronous pull payment method. This means that the payment happens immediately when the customer authorizes it using their Apple device. The merchant requests the payment, and the customer approves it on their device, which sends the payment to the merchant. Apple Pay does not require the customer to create any additional accounts or fill out an extensive form for each purchase. It utilizes the cards already on file in a user’s Apple Wallet. Apple Pay uses a method called tokenization to secure card information. Tokenization replaces the card number with a unique alphanumeric identifier, referred to as a token. The token is used for communication between the merchant, the bank, and Apple Pay, ensuring the actual card number is never shared with the merchant or transmitted with the payment.
Please note that Apple Pay is not available in all regions and is subject to the terms and conditions of the card issuer.
Google Pay is a mobile payment method that enables customers to pay using credit or debit cards stored in their Google Account. It is a synchronous pull payment method, meaning payments are processed immediately upon customer authorization. Google Pay primarily uses a tokenized solution for enhanced security, which most issuers accept as compliant with Strong Customer Authentication (SCA), eliminating the need for 3D-Secure (3DS) in many cases.
Fallback for Non-Tokenized Transactions: If a transaction isn’t tokenized or the issuer requires additional authentication, the system will automatically trigger the 3DS flow to ensure payment success.
Compatibility and Requirements: Google Pay is fully compatible with existing features like recurring payments and can be integrated seamlessly into websites and apps. It requires serving the payment page over HTTPS with a TLS domain-validated certificate for secure transactions.
Usage: This payment method supports transactions for physical goods, donations, subscriptions, and more. The integration process involves enabling Google Pay in your payment methods settings, with minimal code implementation required when using certain payment platforms.
Regions and Limitations: Google Pay's availability depends on the user's region. All merchants must adhere to the Google Pay APIs Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service.
MB WAY is a Portuguese local method. To use MB WAY, the customer must have a Portuguese Banking account as well as a smartphone Bank/MB WAY app installed. This is a synchronous pull payment method. The Merchant will issue a payment request that will trigger a push notification on the customer application. MB WAY also supports authorizations where you can hold an amount for later capture.
Multibanco is a Portuguese local method. This is an asynchronous push payment method. The Merchant creates a payment request that will generate the Multibanco order details. The details include:
This payment method has some edge cases that you should be aware of, such as the ones below:
Direct Debit is an asynchronous pull payment method in which a merchant withdraws funds from the customer's bank account. To do so, the customer must accept a SEPA Direct Debit (SDD) Mandate, which can be valid for multiple payments (therefore supporting single, frequent and subscription payments). To create the SDD Mandate, the merchant must supply the customer's name and IBAN.
Depending on the customer's bank, confirmations of Direct Debit payments may take up to 14 days. Direct Debit is not recommended for single payments due to the risk of fraudulent customers issuing chargebacks.
Virtual IBAN is an asynchronous push payment method that follows the same principles of SEPA Bank Transfers: the merchant provides the customer with an IBAN and transfer amount that they should introduce in an ATM or homebanking system to specify the bank account to which funds are to be transferred.
In comparison with regular SEPA Transfers, Virtual IBAN has the benefit of protecting your bank account details by providing you with a virtual bank account number that supports single, frequent and subscription payments.
Although transfers to a single-use Virtual IBAN after the first payment are initially accepted by the customer's bank (and thus funds are temporarily withdrawn), they are automatically refunded by the IBAN issuer bank.
Universo Flex is a Portuguese local synchronous pull payment method similar to Credit Card, allowing the merchant to accept payments in 3 to 24 installments without having to be a credit intermediary.
Santander Consumer Finance is a Portuguese local asynchronous pull payment method where the customer applies for a loan to acquire the good or service in installments. The merchant does not need to be a credit intermediary.
Single payments are one-time transactions that will let your customers pay an amount of money to you. Examples may include a purchase of a good or service, or a donation. Every payment method supported by easypay allows single payments.
You can accept single payments entirely through our Checkout solution or by calling our Payments API.
Frequent payments are repeatable transactions of varying sums without the client having to enter their payment details again. The original details can be obtained (tokenized) through our Checkout solution, but each payment will have to be charged via the Payments API.
It 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.
Supported methods for frequent payments are: Credit Card, MB WAY, Multibanco, Direct Debit, and Virtual IBAN.
Subscriptions are periodic payments of the same amount of money, configured through Checkout or our Payments API.
Subscriptions support a number of different frequencies, ranging from daily to once every three years. Their last payment can be determined by the end date of the subscription, as well as the total number of payments captured. They also support a configurable number of retries for each capture in case of failure, as well as falling back to another (single) payment method if the recurring one is not successful.
Supported methods for subscriptions are: Credit Card and Direct Debit.
Certain payment methods like credit card and MB WAY go through two distinct phases: authorisation and capture. Our integrations allow you to move through them separately (issuing a card authorisation first and later capturing the funds) or in a single step referred to in our APIs as sale
(authorisation followed by capture).
Authorisation is the first step of the process and involves guaranteeing that the buyer has sufficient funds or credit available to make the payment. If so, the funds are put on hold: the customer cannot use them to pay for other goods or services, but they're not yet transferred to the merchant's account. If the merchant fails to capture the funds in the following days, the hold is lifted.
Authorisations are useful to make sure customers have the means to purchase your product/service before actually charging them. You can issue the authorisation at the moment an order is placed and only actually transfer the funds when you ship the items or provide the service. Another interesting use case of authorisations is multi-captures.
A capture is the actual transfer of funds from the buyer to the merchant.
In many of our integrations, specifying sale
as the type of operation will automatically perform an authorisation and a capture, immediatelly transferring the funds from the customer to the merchant in a single step (if successful).
It is also possible to issue an authorisation for a value that will later be split among different captures. One example is a store supporting split payments for orders of multiple vendors. The full amount of the order is authorised but the different captures can be issued at different times, after each vendor confirms or ships the goods.
Single payments are one-time transactions that will let your customers pay an amount of money to you.
Examples may include a purchase of a good or service, or a donation.
Every payment method supported by easypay allows single payments.
When calling the API 2.0 in single, our system returns an entity and reference in the response JSON. When the payment is made by the customer, our system sends a Generic Notification with the Single ID. Upon receipt, your system should call the Single Details endpoint with the Single ID reported as successful in order to confirm it.
Upon successfully calling API 2.0 on a Single with type sale, our system will communicate to the end customer's MBWAY App. After the event of the customer accepting/declining the payment, our system sends a Generic Notification with the Single ID and a status (success or failed). Upon receipt of success, your system should call Single Details endpoint with the Single ID reported as successful in order to confirm it.
Only for Test Environment, we have these possible cases on phone:
911234567 - Authorized for all operationsBy successfully calling the API 2.0 in a Single with type sale, our system returns a URL in the response JSON for the client to be forwarded to our credit card gateway. The end customer must enter the card data. Our system validates the card in the VISA / MASTERCARD and sends a Generic Notification with the Single ID and a status (success or failed). Upon receipt of a success, your system should call the Single Details endpoint with the Single ID reported as successful in order to confirm it.
For Visa forward and Visa details configurations follow this link
Only for Test Environment, we have these possible credit card numbers:
0000000000000000 - Authorized for all operationsBy successfully calling the API 2.0 in a Single with type sale, our system returns a URL in the response JSON for the client to be forwarded to our credit card gateway. The end customer must enter the card data. Our system validates the card in the VISA / MASTERCARD and sends a Generic Notification with the Single ID and a status (success or failed). Upon receipt of a success, your system should call the Single Details endpoint with the Single ID reported as successful in order to confirm it.
Only for Test Environment, all valid iban will return success but this one: PT50000201231234567890154
When calling the API 2.0 in single, our system returns an IBAN in the response JSON. When the payment is made by the customer, our system sends a Generic Notification with the Single ID. Upon receipt, your system should call the Single Details endpoint with the Single ID reported as successful in order to confirm it.
By successfully calling the API 2.0 in a Single, our system returns a URL in the response JSON for the client to be forwarded to. The end customer must fullfill the journey in the Santander Consumer page. After the journey is completed with success, our system sends a Generic Notification with the Single ID. Upon receipt, your system should call the Single Details endpoint with the Single ID reported as successful in order to confirm it.
By successfully calling the API 2.0 in a Single with type sale, our system returns a URL in the response JSON for the client to be forwarded to. The end customer must fullfill the journey in the Universo Flex page. After the journey is completed with success or failure, our system sends a Generic Notification with the Single ID. Upon receipt, your system should call the Single Details endpoint with the Single ID reported as successful in order to confirm it.
For Visa forward and Visa details configurations follow this link
Full report with all the single payments from your Account
Success
Forbidden
Not found response
Pre condition failed
Unprocessable Entity
{- "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": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "descriptive": "Payment of Invoice Nº 1982652",
- "expiration_time": "2024-06-30 21:38:31",
- "customer": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "name": "Jonh Doe",
- "email": "user@example.com",
- "phone": "962496235",
- "phone_indicative": "351",
- "fiscal_number": "PT277712580",
- "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "language": "PT"
}, - "method": {
- "type": "string",
- "status": "string",
- "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"
}, - "card_type": "VISA",
- "last_four": "1234",
- "expiration_date": "string",
- "alias": "string",
- "entity": "11683",
- "reference": "665876931",
- "iban": "PT50000747199140461443823"
}, - "currency": "EUR",
- "value": 15.32,
- "created_at": "2024-06-30 21:38:31",
- "payment_status": "paid"
}
]
}
Creates a Single Payment
Configuration object to generate a single payment
Single created with success response
Bad Request
Forbidden
Pre condition failed
Unprocessable Entity
{- "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",
- "capture": {
- "descriptive": "transaction descriptive Example",
- "transaction_key": "transaction key Example"
}
}
{- "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"
}
}
Retrive a single payment details
Success
Forbidden
Not found response
Unprocessable Entity
{- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "created_at": "string",
- "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "capture": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "status": "delayed",
- "descriptive": "Payment of Invoice Nº 1982652",
- "transaction_key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "capture_date": "2019-08-24",
- "account": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb"
}, - "splits": [
- {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "split_key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "split_descriptive": "Payment of Invoice Nº 1982652",
- "account": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb"
}, - "value": 15.32,
- "clearing_date": "2019-08-24",
- "clearing_period": "7D",
- "margin_account": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb"
}, - "margin_value": 0,
- "status": "waiting",
- "reverts": [
- {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "value": 15.32,
- "margin_value": 0
}
]
}
]
}, - "descriptive": "Payment of Invoice Nº 1982652",
- "value": 15.32,
- "expiration_time": "string",
- "currency": "EUR",
- "customer": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "name": "Jonh Doe",
- "email": "user@example.com",
- "phone": "962496235",
- "phone_indicative": "351",
- "fiscal_number": "PT277712580",
- "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "language": "PT"
}, - "method": {
- "type": "string",
- "status": "string",
- "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"
}, - "card_type": "VISA",
- "last_four": "1234",
- "expiration_date": "string",
- "alias": "string",
- "entity": "11683",
- "reference": "665876931",
- "iban": "PT50000747199140461443823"
}, - "paid_at": "string"
}
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:
This operation ensures that all associated authorizations and references are properly handled and terminated according to the specified payment method.
No content
Bad Request
Forbidden
Not found response
Unprocessable Entity
{- "status": "error",
- "message": [
- "The field value is required"
]
}
Apply partial modifications to a single payment resource.
Success
Bad Request
Forbidden
Not found response
Unprocessable Entity
{- "expiration_time": "string",
- "currency": "EUR",
- "customer": {
- "name": "Jonh Doe",
- "email": "user@example.com",
- "phone": "962496235",
- "phone_indicative": "351",
- "fiscal_number": "PT277712580",
- "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "language": "PT"
}, - "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "sdd_mandate": {
- "iban": "PT50000747199140461443823",
- "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "name": "string",
- "email": "string",
- "phone": "string",
- "account_holder": "string",
- "country_code": "string",
- "max_num_debits": "string",
- "billing_entity": "PT16103627"
}
}
{- "status": "ok",
- "message": [
- "Your request was successfully created"
], - "id": "d4851c0a-66e2-4b34-9587-1e453ddcc650",
- "method": {
- "type": "CC",
- "status": "pending",
}, - "customer": {
- "id": "156de567-b17d-4591-a154-442c873b76c7"
}
}
Payments used on frequent services with amounts and periodicity changes
After one Frequent MB request our system will return an entity and a reference in the JSON response. The customer can always pay between the min and max values several times before the expiration date or when the method Deletes Frequent is called with success. If the parameter unlimited_payments is active transactions will be unlimited, entity and reference is reseted on our provider 3 times a day, otherwise the total value of payments can’t exceed the max defined. For each payment made with this entity and reference, our system sends a Generic Notification with the Frequent ID.
After successfully calling the API 2.0 on a Frequent MBW you can capture funds through the Frequent ID on a Capture call, our system will communicate to the end customer's MBWAY App. If the final customer accepts / rejects payment, the system sends a Generic Notification with the Capture ID and a status (success or failed). Upon successful receipt, the system should call the Frequent Details endpoint with the Frequent ID reported as successful in order to confirm it.
Only for Test Environment, we have these possible cases on phone:
911234567 - Authorized for all operationsWhen calling the API 2.0 successfully on a Frequent CC, the system returns a URL in JSON for the client to be forwarded to our credit card gateway. The end customer must enter the card data. The system validates the card in the VISA / MASTERCARD and notifies Generic Notification with the Frequent ID and a status (success or failed). Upon successful receipt, the system should call the Frequent Details endpoint with the Frequent ID reported as successful. From a successful communication, you can capture funds using the Frequent ID in a Capture call. The system will capture the funds from the card and sends a Generic Notification with the Capture ID and a status (success or failed). Upon successful receipt, the system should call the Frequent Details endpoint with the Frequent ID reported as successful.
For Visa forward and Visa details configurations follow this link.
When calling API 2.0 successfully on a Frequent DD, the system returns in JSON including the SEPA Direct Debit Mandate ID and an additional entity/reference for additional payments. From now on funds can be captured through the Frequent ID using the Capture endpoint, these funds can take up to 48 business hours to obtain a SEPA direct debit response. When responding, the system notifies with Generic Notification with the Capture ID and a status (success or failed). Upon successful receipt, the system should call the Frequent Details endpoint with the Frequent ID reported as successful.
Full report with all the frequent payments from your Account Id
Success
Forbidden
Too Many Requests
Internal Error
{- "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",
}, - "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"
}
]
}
Frequent payments are repeatable transactions of varying sums without the client having to enter their payment details again.
It 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.
Supported methods for frequent payments are: Credit Card, MB WAY, Multibanco, Direct Debit and Virtual IBAN
Success
Bad Request
Forbidden
Pre condition failed
Too Many Requests
Internal Error
{- "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": {
- "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"
}
}
{- "status": "ok",
- "message": [
- "Your request was successfully created"
], - "id": "cd90455e-4ab3-42cf-a91c-cfc6e3afa65a",
- "method": {
- "type": "cc",
- "status": "waiting",
}, - "customer": {
- "id": "68d07e52-3e04-493f-aaeb-bffe7ddb81ee"
}
}
Retrieve a Frequent Payment details
Success
Unauthorized
Forbidden
Resource Not Found
Too Many Requests
Internal Error
{- "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",
- "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"
}
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.
No content
Bad Request
Unauthorized
Forbidden
Resource Not Found
Too Many Requests
Internal Error
{- "status": "error",
- "message": [
- "Custom error message"
]
}
Frequent Payment object to edit existing one
Success
Bad Request
Unauthorized
Forbidden
Resource Not Found
Too Many Requests
Internal Error
{- "status": "active",
- "expiration_time": "2017-12-12 16:05",
- "currency": "EUR",
- "customer": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "name": "Jonh Doe",
- "email": "user@example.com",
- "phone": "962496235",
- "phone_indicative": "351",
- "fiscal_number": "PT277712580",
- "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "language": "PT"
}, - "key": "Key Example",
- "max_value": 25.5,
- "min_value": 10,
- "unlimited_payments": true,
- "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"
}
}
{- "method": {
- "type": "dd",
- "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",
- "reference_adc": "987654321123"
}
}, - "status": "ok",
- "message": [
- "Your request was successfully created"
]
}
Full report with all the subscriptions payments from your Account Id
Success
Forbidden
Too Many Requests
Internal Error
{- "meta": {
- "page": {
- "current": 1,
- "total": 827
}, - "records": {
- "total": 1654,
- "per_page": 2
}, - "links": {
- "first": "?page=1",
- "prev": "",
- "next": "?page=2",
- "last": "?page=827"
}
}, - "data": [
- {
- "id": "7a3b9c3b-8bc8-4aa9-b67b-43b7a8e0377f",
- "key": "Default Key",
- "expiration_time": "2022-12-04T12:00:00Z",
- "start_time": "2022-12-04T12:00:00Z",
- "frequency": "1Y",
- "retries": 2,
- "max_captures": 2,
- "failover": false,
- "capture_now": false,
- "customer": {
- "id": "93a0b7e4-d0ae-4da2-bdcf-c9a735e44a9a",
- "name": "***",
- "email": "cus***@example.com",
- "phone": "***",
- "fiscal_number": "***",
- "key": "Customer Key",
- "language": "PT"
}, - "method": {
- "type": "DD",
- "status": "active",
- "sdd_mandate": {
- "id": "50124440050",
- "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",
- "value": 17.5,
- "created_at": "2022-11-22 15:29:54"
}, - {
- "id": "2e41fc8e-76ee-4533-a296-809c7bfbc811",
- "key": "",
- "expiration_time": "",
- "start_time": "2022-12-04T12:00:00Z",
- "frequency": "1Y",
- "retries": 0,
- "max_captures": 2,
- "failover": false,
- "capture_now": false,
- "customer": {
- "id": "33058cb5-ca1e-4314-b4ae-c6a86b218157",
- "language": ""
}, - "method": {
- "type": "CC",
- "status": "deleted",
}, - "currency": "EUR",
- "value": 17.5,
- "created_at": "2022-11-22 15:19:51"
}
]
}
Subscriptions are periodic payments of the same amount of money, configured through Checkout or our Payments API.
Subscriptions support a number of different frequencies, ranging from daily to once every three years. Their last payment can be determined by the end date of the subscription, as well as the total number of payments captured.
They also support a configurable number of retries for each capture in case of failure, as well as falling back to another (single) payment method if the recurring one is not successful.
Supported methods for subscriptions are: Credit Card and Direct Debit.
Payment configuration object to generate a payment
Success
Bad Request
Forbidden
Too Many Requests
Internal Error
{- "expiration_time": "2022-12-04 12:00",
- "max_captures": 2,
- "start_time": "2022-12-04 12:00",
- "value": 17.55,
- "frequency": "1D",
- "method": "cc"
}
{- "status": "ok",
- "message": [
- "Your request was successfully created"
], - "id": "b3dd33b8-ace7-4239-89ef-c9bdf4fdb14b",
- "method": {
- "type": "CC",
- "status": "waiting",
}, - "customer": {
- "id": "f80e90fb-9cc5-40c2-832f-0497a2092f82"
}
}
Success
Unauthorized
Forbidden
Resource Not Found
Too Many Requests
Internal Error
{- "id": "7a3b9c3b-8bc8-4aa9-b67b-43b7a8e0377f",
- "key": "Default Key",
- "expiration_time": "2022-12-04T12:00:00Z",
- "start_time": "2022-12-04T12:00:00Z",
- "frequency": "1Y",
- "retries": 2,
- "max_captures": 2,
- "failover": false,
- "capture_now": false,
- "customer": {
- "id": "93a0b7e4-d0ae-4da2-bdcf-c9a735e44a9a",
- "email": "customer@example.com",
- "key": "Customer Key",
- "language": "PT"
}, - "method": {
- "type": "DD",
- "status": "active",
- "sdd_mandate": {
- "id": "50124440050",
- "billing_entity": "PT16103627",
- "iban": "PT50002700XXXXXXXXXXX7833",
- "key": "Sdd Mandate key",
- "name": "Frequent Payment DD",
- "email": "customer@example.com",
- "phone": "911234567",
- "account_holder": "Account Name Example",
- "country_code": "PT",
- "max_num_debits": "0"
}
}, - "currency": "EUR",
- "value": 17.5,
- "created_at": "2022-11-22 15:29:54"
}
No content
Bad Request
Unauthorized
Forbidden
Resource Not Found
Too Many Requests
Internal Error
{- "status": "error",
- "message": [
- "Custom error message"
]
}
Retrieves the subscription payment details.
Subscription Payment object to edit existing one
Success
Bad Request
Unauthorized
Forbidden
Resource Not Found
Too Many Requests
Internal Error
{- "status": "active",
- "capture": {
- "transaction_key": "string",
- "account": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}, - "descriptive": "string"
}, - "expiration_time": "2017-12-12 16:05",
- "currency": "EUR",
- "customer": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "name": "string",
- "email": "string",
- "phone": "string",
- "phone_indicative": "+351",
- "fiscal_number": "PT123456789",
- "key": "Example Key",
- "language": "PT"
}, - "key": "Example Key",
- "value": 12.55,
- "frequency": "1W",
- "max_captures": 0,
- "start_time": "2017-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"
}
}
{- "status": "ok",
- "message": [
- "Your request was successfully created"
], - "id": "63f3f5a0-1543-4ed7-9b44-7f0f802ff476",
- "method": {
- "type": "dd",
- "status": "inactive"
}, - "customer": {
- "id": "d927731a-8684-4aa9-bc50-f691d666c117"
}
}
These operations can be used on all our payment types: single, frequent and subscription
Example response
Bad Request
Forbidden
Not found response
Pre condition failed
Unprocessable Entity
{- "metadata": {
- "next_cursor": "lL_j7ilk7rc",
- "count": 10
}, - "data": [
- {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "status": "delayed",
- "descriptive": "Payment of Invoice Nº 1982652",
- "transaction_key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "capture_date": "2019-08-24",
- "account": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb"
}, - "splits": [
- {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "split_key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "split_descriptive": "Payment of Invoice Nº 1982652",
- "account": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb"
}, - "value": 15.32,
- "clearing_date": "2019-08-24",
- "clearing_period": "7D",
- "margin_account": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb"
}, - "margin_value": 0,
- "status": "waiting",
- "reverts": [
- {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "value": 15.32,
- "margin_value": 0
}
]
}
], - "payment_id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "payment_type": "single",
- "value": 15.32,
- "force_3ds": true,
- "created_at": "2006-01-02 15:04",
- "updated_at": "2006-01-02 15:04"
}
]
}
Example response
Bad Request
Forbidden
Not found response
Unprocessable Entity
{- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "status": "delayed",
- "descriptive": "Payment of Invoice Nº 1982652",
- "transaction_key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "capture_date": "2019-08-24",
- "account": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb"
}, - "splits": [
- {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "split_key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "split_descriptive": "Payment of Invoice Nº 1982652",
- "account": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb"
}, - "value": 15.32,
- "clearing_date": "2019-08-24",
- "clearing_period": "7D",
- "margin_account": {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb"
}, - "margin_value": 0,
- "status": "waiting",
- "reverts": [
- {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "value": 15.32,
- "margin_value": 0
}
]
}
], - "payment_id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "payment_type": "single",
- "value": 15.32,
- "force_3ds": true,
- "created_at": "2006-01-02 15:04",
- "updated_at": "2006-01-02 15:04",
- "refunds": [
- {
- "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
- "status": "success",
- "transaction_key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
- "value": 15.32,
- "iban": "string",
- "email": "string",
- "phone": "string",
- "account_holder": "string"
}
]
}
Payment configuration object to generate a payment
Success
Bad Request
Forbidden
Precondition Failed
Unprocessable Entity
Precondition Required
Too Many Requests
Internal Error
{- "transaction_key": "key example",
- "capture_date": "2022-11-11",
- "account": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}, - "splits": [
- {
- "split_key": "example key",
- "split_descriptive": "string",
- "value": 0.01,
- "account": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}, - "margin_value": 0.01,
- "margin_account": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
}
}
], - "mbway_sdk": {
- "purchase_token": "626E6AA2224D017917D839D4D39296B49441A1D10DA7E8DB6E7E1A4356DDE75429531BEB32190C6D736FA12C7A116CA5F3FCAEE72570406F51371A0CB6E14B6B",
- "initial_timestamp": "2018-01-01 23:59:59",
- "merchant_operation_id": "TESTACCOUNT5436",
- "payload": "{'purchase_token':'EDEB342D3588DDDEEE3E070476E72A6B222E3456C1C825D3E89A734005CE81F69986045424984F55B3233CBFD090A8A564071BBB493F34C4849C964','initial_timestamp':'2018-09-20T10:46:08+01:00','merchant_operation_id':'TESTACCOUNT5436','payload':{'amount':1000,'currencyCode':'9782'}}"
}, - "force_3ds": false,
- "descriptive": "string",
- "value": 20.55
}
{- "status": "ok",
- "message": [
- "Your request was successfully created"
], - "id": "522b83f3-cd98-48ee-8e40-9a94d6b79eb1"
}
Payment configuration object to generate a payment
Success
Bad Request
Forbidden
Precondition Failed
Precondition Required
Too Many Requests
Internal Error
{- "clearing_date": "2006-01-02"
}
{- "status": "ok",
- "message": [
- "Your request was successfully created"
]
}
Success
Unauthorized
Forbidden
Resource Not Found
Too Many Requests
Internal Error
{- "status": "success",
- "id": "9ef96025-47e3-4007-b1a4-b6915099668b",
- "transaction_key": "example_key",
- "descriptive": "Descriptive Example",
- "authorisation": {
- "id": "848cb022-bc78-44e0-9b97-5d7b810a637a",
- "status": "success",
- "message": "Sucesso: Operação concluída com sucesso.",
- "key": "Robertos Key",
- "customer": {
- "id": "aaaa3891-a0f1-4589-a417-56ca595815e0",
- "name": "Alucard",
- "email": "roberto@example.com",
- "phone": "911234567",
- "language": "PT"
}, - "method": {
- "type": "MBW",
- "status": "active"
}, - "currency": "EUR",
- "value": 200
}
}
Void details
Success
Bad Request
Forbidden
Precondition Failed
Too Many Requests
Internal Error
{- "descriptive": "descriptive_example",
- "transaction_key": "key_example"
}
{- "status": "ok",
- "message": [
- "Your request was successfully created"
], - "id": "9ef96025-47e3-4007-b1a4-b6915099668b"
}
Cursor based endpoint to retrieve all account refunds.
The ListRefunds endpoint retrieves a paginated list of refund transactions processed within the system.
{- "data": [
- {
- "id": "03ec73bc-4b70-49ab-9f3a-1f0c0119d7bf",
- "status": "success",
- "transaction_key": "internal key identifying this refund",
- "value": 10,
- "account_holder": "Account Name Example",
- "email": "customer@example.com",
- "phone": "911234567",
- "iban": "PT50002700000001234567833",
- "created_at": "2024-09-19 09:05:42",
- "updated_at": "2024-09-19 09:06:42",
- "capture": {
- "id": "f2387117-0d06-4929-b78a-3c9b8d37cd44",
- "payment_id": "f2387117-0d06-4929-b78a-3c9b8d37cd44",
- "payment_type": "frequent"
}
}, - {
- "id": "aa3f2a0f-4013-4b7e-aad1-a4c443a2affc",
- "status": "success",
- "transaction_key": "internal key identifying this refund",
- "value": 10,
- "account_holder": "Account Name Example",
- "email": "customer@example.com",
- "phone": "911234567",
- "iban": "PT50002700000001234567833",
- "created_at": "2024-09-19 08:59:42",
- "updated_at": "2024-09-19 09:00:02",
- "capture": {
- "id": "92abad40-fc76-4054-9020-a991a0ee5588",
- "payment_id": "92abad40-fc76-4054-9020-a991a0ee5588",
- "payment_type": "frequent"
}
}
], - "metadata": {
- "next_cursor": "Yxk8mepPg2eMyJNj",
- "count": 2
}
}
Success
Unauthorized
Forbidden
Resource Not Found
Too Many Requests
Internal Error
{- "id": "4db3d9ab-f4c0-41a6-a80e-6cbbdd1508f4",
- "status": "success",
- "transaction_key": "internal key identifying this refund",
- "value": 50,
- "account_holder": "Account Name Example",
- "email": "customer@example.com",
- "phone": "911234567",
- "iban": "PT50002700000001234567833",
- "capture": {
- "transaction_key": "string",
- "capture_date": "string",
- "account": {
- "id": "22ea3cc9-424b-489a-91b7-8955f643dc93"
}, - "status": "success",
- "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"
}
}
], - "payment_type": "single",
- "payment_id": "bfd3518d-fe73-4fb8-b8e6-0ce38cd3ced8",
- "id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50",
- "descriptive": "Descriptive Example",
- "value": 17.5
}
}
Refund details
Success
Bad Request
Forbidden
Precondition Failed
Unprocessable Entity
Too Many Requests
Internal Error
{- "transaction_key": "string",
- "value": 17.5
}
{- "status": "ok",
- "message": [
- "Your request was successfully created"
], - "id": "5e2fee01-71e8-47e1-896a-3e2153222afd"
}
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.
Success
Forbidden
Pre condition failed
Unprocessable Entity