easypay

Easypay Payments API (2.0)

Download OpenAPI specification:Download

Easypay Documentation: tec@easypay.pt License: MIT

Terms conditions and legal terms
Privacy Policy

Overview

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.

URLs

The API endpoints are available through the following domains:

  • For test environment:
      https://api.test.easypay.pt/
  • For production environment:
      https://api.prod.easypay.pt/

Authentication

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.

Errors

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 expected
  • 4xx 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.

Authentication Error

This error can have multiple potential causes. Here are some examples:

  • Missing/Invalid AccountId and/or ApiKey Headers
  • Your account has been blocked
  • You don't enough permissions to the action requested

Invalid Content Type Error

This error can only have one cause, you provided an invalid/unsupported content type header.

Invalid JSON Error

This error happens when you provide a bad formated JSON payload.

Invalid Params Error

This error indicates the information provided was incorrect of insufficient (for example, a required parameter was omitted).

Internal Error

This error indicates that an unexpected error ocurred on our servers.

Idempotency

Safe Retries in Easypay API: The Role and Implementation of Idempotency Keys

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".

Generating Idempotency Keys

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.

How it works

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:

  • Too Many Requests (HTTP status code 429)
  • Bad Gateway (HTTP status code 502)
  • Service Unavailable (HTTP status code 503)

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:

  1. If no response was received at all, resend the request.
  2. If the response has one of the following status codes, resend the request:
    • Conflict (HTTP status code 409), may indicate the original request was still in transit
    • Too Many Requests (HTTP status code 429)
    • Bad Gateway (HTTP status code 502)
    • Service Unavailable (HTTP status code 503)
  3. If the response has status code 500 (Internal Server Error), resend the request as long as it's not a POST request.
  4. Otherwise, don't repeat the request and handle the error.

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 Concepts

Payment Methods

Payment methods are defined according to two different categories:

  • Pull / Push: The merchant requests the funds from the customer, or the customer sends the funds directly to the merchant.
  • Synchronous / Asynchronous: The charge happens immediately, or only after a period of time.

Pull or Push

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.

Credit / Debit Card

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

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™

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

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

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:

  • An entity number
  • A reference number
  • The amount to pay To pay, the customer introduces these details in an ATM or in their homebanking system.

This payment method has some edge cases that you should be aware of, such as the ones below:

  • The customer can pay a different amount than the requested;
  • Multibanco refunds are not currently supported by the vendor. If refunds are needed, you can offer them via SEPA Transfer.

Direct Debit

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

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.

Payment Types

Single

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

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.

Subscription

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.

Authorisations and Captures

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

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.

Capture

A capture is the actual transfer of funds from the buyer to the merchant.

Sale

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).

Multi-captures

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 Payment

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.

Multibanco Reference


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.


MBWay


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 operations
  917654321 - Failed for all operations
  913456789 - Declined for all operations
  919876543 - Pending for all operations

Visa & Mastercard


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 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 operations
  2222222222222222 - Proceed with 3DS authentication
  1111111111111111 - Failed for all operations
  1234123412341234 - Declined for all operations

SEPA Direct Debit


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 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


Virtual IBAN


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.

Lists single payments

Full report with all the single payments from your Account

SecurityaccountId and apiKey
Request
query Parameters
page
integer
Default: 1

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).

Example: page=1
records_per_page
integer
Default: 20

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).

Example: records_per_page=20
type
string

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).

Enum: "sale" "authorisation"
Example: type=sale
expiration_time
string

Filter records by expiration datetime interval. Format: interval(YYYY-MM-DD HH:MM,YYYY-MM-DD HH:MM)

Example: expiration_time=interval(2006-01-02 15:04,2006-01-02 15:04)
method
string

Filter by payment method used in the transaction.

Enum: "cc" "vi" "dd" "mb" "mbw" "ap" "gp" "sc" "uf"
Example: method=mb
customer
string

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.

Example: customer=01J32EDWGNX94XMWP8PWB23KBK
id
string <uuid>

Filter by the unique identifier for the resource. Typically formatted as a UUID (Universally Unique Identifier).

Example: id=bb3e7e60-20f3-4208-9b21-64c635a51f42
key
string

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.

Example: key=01J32EESEC1Z543P7J3PKSF1Q9
value
number <double>

Filter records by the exact transaction amount.

Example: value=10.32
created_at
string

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).

Example: created_at=interval(2006-01-02 15:04,2006-01-02 15:04)
Responses
200

Success

403

Forbidden

404

Not found response

412

Pre condition failed

500

Unprocessable Entity

get/single
Request samples 
Response samples 
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}
Create single payment
Creates a Single Payment


SecurityaccountId and apiKey 
Request 
Request Body schema: application/json
required
Configuration object to generate a single payment


type
string (OperationType) 
Specifies the 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).


 Enum: "sale" "authorisation"  
object (CreateCapture) 
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.


 
expiration_time
string
 Deprecated 
The last possible time to make the payment. Applicable in Multibanco payments. This field is deprecated, use multibanco.expiration_time instead.


 
currency
string (Currency) 
The currency code in ISO 4217 format (e.g., "EUR" for Euro). This field specifies the type of currency used in financial operation.


 Value: "EUR"  
value
required
number <double>  (Value)   >= 0.5 
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.


 
method
required
string (SinglePaymentMethods) 
Enumerates the possible values for the payment method used in the transaction. This field helps to identify the selected payment method. Possible values include:


    

  • "CC": Credit Card
    • 

  • "VI": Digital IBAN
    • 

  • "DD": Direct Debit
    • 

  • "MB": Multibanco
    • 

  • "MBW": MBWay
    • 

  • "AP": Apple Pay
    • 

  • "GP": Google Pay
    • 



Each value corresponds to a specific payment method.


 Enum: "cc" "vi" "dd" "mb" "mbw" "ap" "gp"  
key
string (Key)   <= 255 characters 
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.


 
object (Customer) 
The Customer object contains detailed information about the customer involved in the transaction.


 
object
An object that holds the details specific to a Multibanco transaction.


 
object (CreateSddMandate) 
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.


 
Responses 
201
Single created with success response


400
Bad Request


403
Forbidden


412
Pre condition failed


500
Unprocessable Entity


post/single
Request samples 
application/json
{
  • "customer": {
    },
  • "key": "merchant identification key Example",
  • "value": 15.5,
  • "method": "mb",
  • "capture": {
    }
}
Response samples 
application/json
{
  • "status": "ok",
  • "message": [
    ],
  • "id": "ed7f8dac-0ea2-4846-8433-f5f8b0e70ed7",
  • "method": {
    },
  • "customer": {
    },
  • "capture": {
    }
}
Shows single payment details
Retrive a single payment details


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
200
Success


403
Forbidden


404
Not found response


500
Unprocessable Entity


get/single/{id}
Request samples 
Response samples 
application/json
{
  • "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
  • "created_at": "string",
  • "capture": [
    ],
  • "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
  • "descriptive": "Payment of Invoice Nº 1982652",
  • "value": 15.32,
  • "expiration_time": "string",
  • "currency": "EUR",
  • "customer": {
    },
  • "method": {
    },
  • "paid_at": "string"
}
Deletes single payment
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:


    

  • MBWay and Credit Cards: Voids all authorizations.
    • 

  • Multibanco: Cancels the Multibanco Reference.
    • 

  • Direct Debit: Cancels the Direct Debit if the request is made before the cutoff hour(18:00 Europe/Lisbon).
    • 



This operation ensures that all associated authorizations and references are properly handled and terminated according to the specified payment method.


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
204
No content


400
Bad Request


403
Forbidden


404
Not found response


500
Unprocessable Entity


delete/single/{id}
Request samples 
Response samples 
application/json
{
  • "status": "error",
  • "message": [
    ]
}
Update a single Payment
Apply partial modifications to a single payment resource.


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Request Body schema: application/json
expiration_time
string
 Deprecated 
 
currency
string (Currency) 
The currency code in ISO 4217 format (e.g., "EUR" for Euro). This field specifies the type of currency used in financial operation.


 Value: "EUR"  
object (UpdatableCustomer) 
The Customer object contains detailed information about the customer involved in the transaction.


 
key
string (Key)   <= 255 characters 
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.


 
object (UpdatableSddMandate) 
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.


 
Responses 
200
Success


400
Bad Request


403
Forbidden


404
Not found response


500
Unprocessable Entity


patch/single/{id}
Request samples 
application/json
{
  • "expiration_time": "string",
  • "currency": "EUR",
  • "customer": {
    },
  • "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
  • "sdd_mandate": {
    }
}
Response samples 
application/json
{}
Frequent Payment
Payments used on frequent services with amounts and periodicity changes 
 
 
      
 
 
Multibanco Reference
 
 
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.
 
   
 
 
MBWay
 
 
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 operations
   917654321 - Declined for all operations
   919876543 - Pending for all operations
 
   
 
 
Visa & Mastercard
 
 
When 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.
 
   
 
 
SEPA Direct Debit
 
 
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.
 
   
 
 
 
 


Lists frequent payments
Full report with all the frequent payments from your Account Id


SecurityaccountId and apiKey 
Request 
query Parameters
page
number
Page Number


 
records_per_page
number
 Default:  20
Limit records per page (Max: 100)


 
expiration_time
string
Filter by expiration time interval (max 30 days)


 
method
string
Filter by method


 
customer
string
Filter by customer key


 
id
string
Filter by id


 
key
string
Filter by frequent key


 
created_at
string
Filter by created datetime interval (max 30 days)


 
Responses 
200
Success


403
Forbidden


429
Too Many Requests


500
Internal Error


get/frequent
Request samples 
Response samples 
{
  • "meta": {
    },
  • "data": [
    ]
}
Create frequent payment
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


SecurityaccountId and apiKey 
Request 
Request Body schema: application/json
expiration_time
string
 
currency
string
 Default:  "EUR"
 Enum: "EUR" "BRL"  
required
object (Customer) 
The Customer object contains detailed information about the customer involved in the transaction.


 
key
string  <= 50 characters 
The merchant's key for identifying the payment.


 
min_value
required
number <double>   >= 0.01 
 
max_value
required
number <double>   >= 0.01 
 
unlimited_payments
boolean
 Default:  true
Transactions will be unlimited, max or min value will be refreshed on each payment.


 
method
required
string
 Enum: "mb" "cc" "dd" "mbw" "vi"  
object (SddMandate) 
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.


 
object
Configuration of the Multibanco payment


 
Responses 
201
Success


400
Bad Request


403
Forbidden


412
Pre condition failed


429
Too Many Requests


500
Internal Error


post/frequent
Request samples 
application/json
{
  • "expiration_time": "2038-12-12 16:05",
  • "currency": "EUR",
  • "customer": {
    },
  • "key": "Key Example",
  • "max_value": 25.5,
  • "min_value": 10,
  • "unlimited_payments": true,
  • "method": "dd",
  • "sdd_mandate": {
    }
}
Response samples 
{}
Shows frequent payment details
Retrieve a Frequent Payment details


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


get/frequent/{id}
Request samples 
Response samples 
{
  • "id": "ac1913a3-fd78-4822-8394-0a14f4169247",
  • "key": "Default Key",
  • "expiration_time": "2022-12-12T16:05:00Z",
  • "customer": {
    },
  • "method": {},
  • "currency": "EUR",
  • "max_value": 20,
  • "min_value": 2,
  • "unlimited_payments": false,
  • "created_at": "2022-11-23 13:16:58"
}
Deletes frequent payment
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.


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
204
No content


400
Bad Request


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


delete/frequent/{id}
Request samples 
Response samples 
{
  • "status": "error",
  • "message": [
    ]
}
Updates frequent payment details
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Request Body schema: application/json
required
Frequent Payment object to edit existing one


status
string
 Enum: "active" "deleted"  
expiration_time
string <Y-m-d H:i> 
 
currency
string (Currency) 
The currency code in ISO 4217 format (e.g., "EUR" for Euro). This field specifies the type of currency used in financial operation.


 Value: "EUR"  
object (Customer) 
The Customer object contains detailed information about the customer involved in the transaction.


 
key
string  <= 50 characters 
The merchant's key for identifying the payment.


 
max_value
number <double>   >= 0.01 
 
min_value
number <double>   >= 0.01 
 
unlimited_payments
boolean
 Default:  true
Transactions will be unlimited, max or min value will be refreshed on each payment.


 
object (SddMandate) 
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.


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


patch/frequent/{id}
Request samples 
application/json
{
  • "status": "active",
  • "expiration_time": "2017-12-12 16:05",
  • "currency": "EUR",
  • "customer": {
    },
  • "key": "Key Example",
  • "max_value": 25.5,
  • "min_value": 10,
  • "unlimited_payments": true,
  • "sdd_mandate": {
    }
}
Response samples 
{
  • "method": {
    },
  • "status": "ok",
  • "message": [
    ]
}
Request Authorisation
Create a new authorisation on a given Frequent Payment


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Request Body schema: application/json
required
Payment configuration object to generate a payment


object (Mbway_sdk) 
 
transaction_key
string  <= 255 characters 
Your internal key identifying this authorisation.


 
force_3ds
boolean
 Default:  false
Whether or not you want to force the 3DS authentication.


 
descriptive
required
string  <= 255 characters 
This will appear in the bank statement/mbway application.


 
value
required
number <double>   >= 0.5 
Value will be rounded to 2 decimals.


 
Responses 
201
Success


400
Bad Request


403
Forbidden


404
Not Found


412
Precondition Failed


429
Too Many Requests


500
Internal Error


post/frequent/authorisation/{id}
Request samples 
application/json
{
  • "transaction_key": "string",
  • "descriptive": "Descriptive Example",
  • "value": 17.5
}
Response samples 
{
  • "id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50",
  • "status": "ok",
  • "message": [
    ]
}
Subscription Payment
List subscription payments
Full report with all the subscriptions payments from your Account Id


SecurityaccountId and apiKey 
Request 
query Parameters
page
number
Page Number


 
records_per_page
number
 Default:  20
Limit records per page (Max: 100)


 
expiration_time
string
Filter by expiration time interval (max 30 days)


 
method
string
Filter by method


 
customer
string
Filter by customer key


 
id
string
Filter by id


 
key
string
Filter by subscription key


 
created_at
string
Filter by created datetime interval (max 30 days)


 
Responses 
200
Success


403
Forbidden


429
Too Many Requests


500
Internal Error


get/subscription
Request samples 
Response samples 
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}
Create subscription payment
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.


SecurityaccountId and apiKey 
Request 
Request Body schema: application/json
required
Payment configuration object to generate a payment


frequent_id
string <uuid> 
Only required to create a subscription from active Frequent Payment


 
object
 
expiration_time
string <Y-m-d H:i> 
Required only when no max_captures is set.
The last possible time to make the payment.


 
currency
string (Currency) 
The currency code in ISO 4217 format (e.g., "EUR" for Euro). This field specifies the type of currency used in financial operation.


 Value: "EUR"  
object
 
key
string  <= 50 characters 
The merchant's key for identifying the payment.


 
value
required
number <double>   >= 0.5 
The payment value.
Will be rounded to 2 decimals.


 
frequency
required
string
 Enum: "1D" "1W" "2W" "1M" "2M" "3M" "4M" "6M" "1Y" "2Y" "3Y"  
max_captures
integer
Required when no expiration_time is set.
Number of payments.


 
start_time
required
string <Y-m-d H:i> 
Defining the start of billing cycles.


 
failover
boolean
 Default:  false
After all retries failed, the payment cycle can have another try with another single method.


 
capture_now
boolean
 Default:  false
Whether to schedule an immediate capture and schedule the second one for start_time.


 
retries
integer
 Default:  0
Number of retries in each payment cycle.

The chosen frequency will define the max number of possible retries.


 
method
required
string
The payment methods.


 Enum: "cc" "dd"  
object (SddMandate) 
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.


 
Responses 
201
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


500
Internal Error


post/subscription
Request samples 
application/json
{
  • "expiration_time": "2022-12-04 12:00",
  • "max_captures": 2,
  • "start_time": "2022-12-04 12:00",
  • "value": 17.55,
  • "frequency": "1D",
  • "method": "cc"
}
Response samples 
application/json
{}
Shows subscription payment details
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


get/subscription/{id}
Request samples 
Response samples 
application/json
{
  • "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": {
    },
  • "method": {
    },
  • "currency": "EUR",
  • "value": 17.5,
  • "created_at": "2022-11-22 15:29:54"
}
Deletes subscription payment
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
204
No content


400
Bad Request


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


delete/subscription/{id}
Request samples 
Response samples 
{
  • "status": "error",
  • "message": [
    ]
}
Updates subscription payment details
Retrieves the subscription payment details.


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Request Body schema: application/json
required
Subscription Payment object to edit existing one


status
string
The Payment Status.


 Enum: "active" "inactive"  
object
 
expiration_time
string <Y-m-d H:i> 
Required only when no max_captures is set.
The last possible time to make the payment.


 
currency
string (Currency) 
The currency code in ISO 4217 format (e.g., "EUR" for Euro). This field specifies the type of currency used in financial operation.


 Value: "EUR"  
object
 
key
string  <= 50 characters 
The merchant's key for identifying the payment.


 
value
number <double>   >= 0.5 
The payment value.
Will be rounded to 2 decimals.


 
frequency
string
 Enum: "1D" "1W" "2W" "1M" "2M" "3M" "4M" "6M" "1Y" "2Y" "3Y"  
max_captures
integer
Required when no expiration_time is set.
Number of payments.


 
start_time
string <Y-m-d H:i> 
Defining the start of billing cycles.


 
failover
boolean
 Default:  false
After all retries failed, the payment cycle can have another try with another single method.


 
retries
integer
 Default:  0
Number of retries in each payment cycle.

The chosen frequency will define the max number of possible retries.


 
object (SddMandate) 
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.


 
Responses 
200
Success


400
Bad Request


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


patch/subscription/{id}
Request samples 
application/json
{
  • "status": "active",
  • "capture": {
    },
  • "expiration_time": "2017-12-12 16:05",
  • "currency": "EUR",
  • "customer": {
    },
  • "key": "Example Key",
  • "value": 12.55,
  • "frequency": "1W",
  • "max_captures": 0,
  • "start_time": "2017-12-12 16:05",
  • "failover": false,
  • "retries": 0,
  • "sdd_mandate": {
    }
}
Response samples 
application/json
{
  • "status": "ok",
  • "message": [
    ],
  • "id": "63f3f5a0-1543-4ed7-9b44-7f0f802ff476",
  • "method": {
    },
  • "customer": {
    }
}
Payment Generic Operations
These operations can be used on all our payment types: single, frequent and subscription


List captures
SecurityaccountId and apiKey 
Request 
query Parameters
cursor
string
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
number
The limit parameter is used for pagination. It specifies the maximum number of entries to return in a single page of results. Max 100. 


 
created_at
string
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).


 
 Example:  created_at=interval(2006-01-02 15:04,2006-01-02 15:04)
updated_at
string
Filter records by update datetime interval. Maximum range of 30 days. Format: interval(YYYY-MM-DD HH:MM,YYYY-MM-DD HH:MM)


 
 Example:  updated_at=interval(2006-01-02 15:04,2006-01-02 15:04)
Responses 
200
Example response


401
Bad Request


403
Forbidden


404
Not found response


412
Pre condition failed


500
Unprocessable Entity


get/capture
Request samples 
Response samples 
application/json
{
  • "metadata": {
    },
  • "data": [
    ]
}
Shows capture details
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
200
Example response


401
Bad Request


403
Forbidden


404
Not found response


500
Unprocessable Entity


get/capture/{id}
Request samples 
Response samples 
application/json
{
  • "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
  • "status": "delayed",
  • "descriptive": "Payment of Invoice Nº 1982652",
  • "transaction_key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
  • "capture_date": "2019-08-24",
  • "account": {
    },
  • "splits": [
    ],
  • "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",
  • "error": {
    },
  • "refunds": [
    ]
}
Captures a Single Auth, Frequent and Frequent Auth
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Request Body schema: application/json
required
Payment configuration object to generate a payment


transaction_key
string  <= 50 characters 
Your internal key identifying this capture.


 
capture_date
string <date> 
 
object
For multi-account clients.


 
Array of objects
Used in split payments.


 
object (Mbway_sdk) 
 
force_3ds
boolean
 Default:  false
Whether or not you want to force the 3DS authentication on Credit Cards (used only on Frequent capture without authorisation).


 
descriptive
string  <= 255 characters 
This will appear in the bank statement/mbway application.


 
value
required
number <double>   >= 0.5 
Value will be rounded to 2 decimals.


 
currency
string (Currency) 
The currency code in ISO 4217 format (e.g., "EUR" for Euro). This field specifies the type of currency used in financial operation.


 Value: "EUR"  
Responses 
201
Success


400
Bad Request


403
Forbidden


412
Precondition Failed


422
Unprocessable Entity


428
Precondition Required


429
Too Many Requests


500
Internal Error


post/capture/{id}
Request samples 
application/json
{
  • "transaction_key": "key example",
  • "capture_date": "2022-11-11",
  • "account": {
    },
  • "splits": [
    ],
  • "mbway_sdk": {
    },
  • "force_3ds": false,
  • "descriptive": "string",
  • "value": 20.55
}
Response samples 
{
  • "status": "ok",
  • "message": [
    ],
  • "id": "522b83f3-cd98-48ee-8e40-9a94d6b79eb1"
}
Updates the split of a capture
SecurityaccountId and apiKey 
Request 
path Parameters
capture-uuid
required
string <uuid> 
Capture Identification


 
capture-split-uuid
required
string <uuid> 
Capture Split Identification


 
Request Body schema: application/json
Payment configuration object to generate a payment


clearing_date
string <date> 
The new date for the split to be cleared.

This field must be in the future and no longer than 2 years from today.


 
Responses 
201
Success


400
Bad Request


403
Forbidden


412
Precondition Failed


428
Precondition Required


429
Too Many Requests


500
Internal Error


patch/capture/{capture-uuid}/splits/{capture-split-uuid}
Request samples 
application/json
{
  • "clearing_date": "2006-01-02"
}
Response samples 
{
  • "status": "ok",
  • "message": [
    ]
}
Shows authorisation details
Retrieves the details of an authorisation


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


get/authorisation/{id}
Request samples 
Response samples 
{
  • "id": "ef7d7bc6-6c1a-4193-a33e-d9e7bba29727",
  • "status": "success",
  • "message": "Operação concluída com sucesso",
  • "key": "Example Key",
  • "customer": {
    },
  • "method": {},
  • "currency": "EUR",
  • "value": 20,
  • "value_captured": 20,
  • "transactions": [
    ]
}
Shows void details
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


get/void/{id}
Request samples 
Response samples 
application/json
{
  • "status": "success",
  • "id": "9ef96025-47e3-4007-b1a4-b6915099668b",
  • "transaction_key": "example_key",
  • "descriptive": "Descriptive Example",
  • "authorisation": {
    }
}
Voids a Single Auth or Frequent Auth
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Request Body schema: application/json
required
Void details


descriptive
required
string  <= 255 characters 
This will appear in the bank statement/mbway application.


 
transaction_key
string  <= 50 characters 
Your internal key identifying this void.


 
Responses 
201
Success


400
Bad Request


403
Forbidden


412
Precondition Failed


429
Too Many Requests


500
Internal Error


post/void/{id}
Request samples 
application/json
{
  • "descriptive": "descriptive_example",
  • "transaction_key": "key_example"
}
Response samples 
{
  • "status": "ok",
  • "message": [
    ],
  • "id": "9ef96025-47e3-4007-b1a4-b6915099668b"
}
List Refunds
Cursor based endpoint to retrieve all account refunds.


SecurityaccountId and apiKey 
Request 
query Parameters
cursor
string
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
number
The limit parameter is used for pagination. It specifies the maximum number of entries to return in a single page of results. Max 100. 


 
created_at
string
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).


 
 Example:  created_at=interval(2006-01-02 15:04,2006-01-02 15:04)
updated_at
string
Filter records by update datetime interval. Maximum range of 30 days. Format: interval(YYYY-MM-DD HH:MM,YYYY-MM-DD HH:MM)


 
 Example:  updated_at=interval(2006-01-02 15:04,2006-01-02 15:04)
Responses 
200
The ListRefunds endpoint retrieves a paginated list of refund transactions processed within the system.


get/refund
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}
Shows refund details
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


get/refund/{id}
Request samples 
Response samples 
{
  • "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": {
    }
}
Refunds a Single Transaction or Frequent Transaction
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
The capture uuid associated with Single or Frequent Transaction


 
Request Body schema: application/json
required
Refund details


transaction_key
string  <= 50 characters 
Your internal key identifying this refund


 
iban
string  <= 34 characters 
Optional - Iban from the bank account


 
email
string  <= 50 characters 
Optional - Email from the bank account holder


 
phone
string  <= 20 characters 
Optional - Phone from the bank account holder


 
account_holder
string  <= 100 characters 
Optional - Bank account holder name


 
value
required
number <double>   > 0 
Value will be rounded to 2 decimals


 
object
 
Responses 
201
Success


400
Bad Request


403
Forbidden


412
Precondition Failed


422
Unprocessable Entity


429
Too Many Requests


500
Internal Error


post/refund/{id}
Request samples 
application/json
{
  • "transaction_key": "string",
  • "value": 17.5
}
Response samples 
{
  • "status": "ok",
  • "message": [
    ],
  • "id": "5e2fee01-71e8-47e1-896a-3e2153222afd"
}
List chargebacks
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.


SecurityaccountId and apiKey 
Request 
query Parameters
cursor
string
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
number
The limit parameter is used for pagination. It specifies the maximum number of entries to return in a single page of results. Max 100. 


 
created_at
string
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).


 
 Example:  created_at=interval(2006-01-02 15:04,2006-01-02 15:04)
Responses 
200
Success


403
Forbidden


412
Pre condition failed


500
Unprocessable Entity


get/chargeback
Request samples 
Response samples 
application/json
{
  • "data": [
    ],
  • "metadata": {
    }
}
Notifications / Webhooks
What are notifications and why they are useful
Easypay use notifications (webhooks) for event notifications.


Notifications are POST API calls (JSON encoded) that let your application know an event has happened.


This is a server-to-server service that sends near real-time notifications, informing about a payment status change.


Notifications are particularly useful for asynchronous events like:


    

  • when a customer pays a MB reference.
    • 

  • a frequent payment succeeds/fails.
    • 

  • subscription succeeds/fails, among other useful events.
    • 

  • a checkout single sale payment succeeds/fails.
    • 



With notifications your system can automate custom actions in response to the transitions that happen in a payment flow.


Supported Notification types
Easypay supports 3 notification types:


    

  • Generic notification: a notification informing about all state transitions of some payment resource.
    • 

  • Authorisation notification: a notification informing about some payment transitioning to authorization status. Available for single and frequent payments.
    • 

  • Transaction notification: a notification informing about some payment transitioning to capture status. Available for single and frequent payments.
    • 



As an example, if you subscribe to Generic and Authorisation notifications, we will inform you about the payment status transition to authorized in two different formats and you will receive two notifications for the same event.


What varies in these two notifications, for the same event, is the contract of the notification message.


Generic Notification
All transitions that happen in a payment flow are notified via generic notification.


The notification flow follows the following diagram:


Recommended flow


    

  1. A change of payment state is notified to the configured generic notification endpoint.
    2. 

  2. The integrator system that received a generic notification, queries Easypay API's. This is a recommended to ensure that the received notification was issued by Easypay.
    3. 

  3. The integrator system performs its internal application logic regarding the payment state transition, according to API response.
    4. 



The generic notification message contains the following fields:


{
  "id": "5eca7446-14e9-47bb-aabb-5ee237159b8b",
  "key": "dcf9ab3fd95ca3d5607853f36d46f161c8715858",
  "type": "capture",
  "status": "success",
  "messages": ["Your request was successfully captured"],
  "date": "2022-08-10 14:56:54"
}



Payload Attributes






Name
Type
Description





type
string
the type of payment status change.




status
string
the status of the given payment status change.




messages
string
messages associated with this payment status change.




date
string
the expiration associated with this single or frequent payment. Follows the format  If none was given, defaults to empty.he merchant identification key provided on a single or frequent payment request.





In a generic notification, the fields id and key will change according to the payment type and operation.


The following table describes the possible combinations:






Payment Type
Name
Type
Description





Single Authorisation
id 
 key		
string  
 string		
the id of the single payment.
 the field key given to create single request payload.		




Single Capture
id 
 key		
string  
 string		
the id of the single payment.
the field transaction_key given to capturing single payload.		




Single Sale
id 
 key		
string  
 string		
the id of the single payment. 
the field transaction_key, inside of object capture, given to create single request payload.		




Frequent Create
id 
key		
string  
 string		
the id of the frequent payment.
the field key given to create frequent request payload.		




Frequent Authorization
id 
key		
string  
 string		
the id of the frequent payment.
the field transaction_key given to authorisation frequent request payload.		




Frequent Capture
id 
key		
string  
 string		
the id of the capture operation. 
the field transaction_key given to capture frequent request payload.		




Refund Single/Frequent Capture
id 
key		
string 
 string		
the id of the refund.
the field transaction_key given to refund capture request payload.		




Void Single/Frequent Authorisation
id 
key		
string 
 string		
the id of the void.
the field transaction_key given to void authorisation request payload.		




Subcription Create
id 
key		
string 
 string		
the id of the subscription.
the field key given to create subscription request payload.		




Subcription Capture
id 
key		
string 
 string		
the id of the subscription.
the field transaction_key inside of object capture, given to create subscription request payload.		




Chargeback Single
id 
key		
string 
 string		
the id of the single.
the field transaction_key given to create frequent request payload.		




Chargeback Frequent
id 
key		
string 
 string		
the id of the capture operation.
the field transaction_key given to capture frequent request payload.		




Outpayment
id 
key		
string 
 string		
the id of the outpayment operation.
the field key given to create outpayment request payload.		





Authorisation Notification Message structure


The delivered authorisation notification message contains the following fields:


{
  "id": "1bbc14c3-8ca8-492c-887d-1ca86400e4fa",
  "value": 1,
  "currency": "EUR",
  "key": "the merchant key",
  "expiration_time": "2022-01-01 10:20",
  "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"
  },
  "method": "mb",
  "account": {
    "id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50"
  },
  "authorisation": {
    "id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50"
  }
}



Attributes






Name
Type
Description





id
string
the uuid of a single or frequent payment




value
double
the amount requested on single/frequent creation. Rounded to 2 decimals.




key
string
the merchant identification key provided on a single or frequent payment request




expiration_time
string
the expiration associated with this single or frequent payment. Follows the format  If none was given, defaults to empty.




customer
object
the customer associated at single or frequent payment request




method
string
the choosen payment method associated with single or frequent payment




account
object
the account from which this notification was originated




authorization
object
the authorization details.





Transaction Notification Message structure
The transaction notification message contains the following fields:


{
  "id": "87615356-0a88-42bd-8abb-aab3e90128de",
  "value": "40",
  "currency": "EUR",
  "key": "the merchant key",
  "expiration_time": "2023-08-07 20:00",
  "method": "MBW",
  "customer": {
    "id": "2eb64a7f-90a7-4dc6-959b-1d9aba44910c",
    "phone": "910410419"
  },
  "account": {
    "id": "0b8de6e7-89c8-4d76-93e8-019bc058f27d"
  },
  "transaction": {
    "id": "eb23923b-3529-4b71-b54e-1e707a8d55c4",
    "key": "transaction_key_of_this_capture",
    "type": "capture",
    "date": "2022-08-10T12:45:50Z",
    "values": {
      "requested": "40",
      "paid": "40",
      "fixed_fee": "0",
      "variable_fee": "0",
      "tax": "0",
      "transfer": "0"
    }
  }
}



Attributes






Name
Type
Description





id
string
the uuid of a single or frequent payment




value
double
the amount requested on single/frequent creation. Rounded to 2 decimals.




currency
string
the currency of requested amount requested on single/frequent creation.




key
string
the merchant identification key provided on a single or frequent payment request.




expiration_time
string
the expiration associated with this single or frequent payment. Follows the format  If none was given, defaults to empty.




method
string
the choosen payment method associated with single or frequent payment.




customer
object
the customer associated at single or frequent payment request.




account
object
the account from which this notification was originated.




transaction
object
the details of this transaction.





Configuring Notifications
On Easypay backoffice, navigate to Web Services > Configuration API 2.0.


Select the payment account you want to receive notifications.


Select Notifications.


To receive generic notifications, place your system url on Generic - URL .


To receive authorisation notifications, place your system url on Authorisation - URL.


To receive capture notifications, place your system url on Payment - URL.


Following Notification via Backoffice
On Easypay backoffice, navigate to Web Services > Notifications API 2.0.


There, you can select the payment account whose notifications you are interested in.


Generic NotificationWebhook 
We will send you this json in our notifications


SecurityBasicAuth 
Request 
Request Body schema: application/json
required
Notification Payload


id
string <uuid> 
ID of the related notified resource


 
key
string
Merchant identification key


 
type
string
 Enum: "authorisation" "capture" "frequent_create" "void" "refund" "chargeback" "subscription_create" "subscription_capture" "out_payment"  
status
string
 Enum: "failed" "success"  
messages
Array of strings
 
date
string
 
Responses 
200
Return a 200 status to indicate that the data was received successfully


Request samples 
application/json
{
  • "id": "1bbc14c3-8ca8-492c-887d-1ca86400e4fa",
  • "key": "Example Key",
  • "type": "capture",
  • "status": "success",
  • "messages": [
    ],
  • "date": "2022-01-01 10:20:30"
}
Authorisation NotificationWebhook 
We will send you this json in our notification


SecurityBasicAuth 
Request 
Request Body schema: application/json
required
Notification Payload


object
 
object
 
Responses 
200
Return a 200 status to indicate that the data was received successfully


Request samples 
application/json
{
  • "account": {
    },
  • "authorisation": {
    }
}
Transaction NotificationWebhook 
We will send you this json in our notification


SecurityBasicAuth 
Request 
Request Body schema: application/json
required
Notification Payload


object
 
Responses 
200
Return a 200 status to indicate that the data was received successfully


Request samples 
application/json
{
  • "account": {
    }
}
Reports
Report Ledger
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.


By 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.


SecurityaccountId and apiKey 
Request 
query Parameters
cursor
string
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
number
 Default:  100
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.


 
created_at
string
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).


 
 Example:  created_at=interval(2006-01-02 15:04,2006-01-02 15:04)
transaction_type
string
Filter by LedgerTransactionType


 Enum: "CP" "RF" "RV" "FEE" "SP" "MAN" "TB" "OT" "CB" "OP"  
 Example:  transaction_type=CP
transfer_batch
string
Filter by LedgerTransferBatch


 
 Example:  transfer_batch=584
Responses 
200
403
Forbidden


412
Precondition Failed


500
Internal Error


get/report/ledger
Request samples 
Response samples 
{
  • "metadata": {
    },
  • "data": [
    ]
}
Report Transactions
List your transactions


SecurityaccountId and apiKey 
Request 
query Parameters
start_date
string <Y-m-d H:i> 
Filter from this date (inclusive). The date and time must be provided in UTC, using the format Y-m-d H:i.


 
end_date
string <Y-m-d H:i> 
 Filter until this date (inclusive). The date and time must be provided in UTC, using the format Y-m-d H:i.


 
page
number
Page Number


 
records_per_page
number
 Default:  20
Limit records per page (Max: 2500)


 
Responses 
200
Success


403
Forbidden


412
Precondition Failed


500
Internal Error


get/report/transactions
Request samples 
curl -XGET -H "AccountId: 5fe2e102-dfee-4880-bd87-1d9a6ec6fdd2" -H "ApiKey: b0ea270d-9f50-4bbc-af58-44fed3df4b2b" \
-G --data-urlencode "start_date=2019-01-07 15:10" --data-urlencode "end_date=2019-02-05 15:14" --data-urlencode "page=1" --data-urlencode "records_per_page=10" \
https://api.prod.easypay.pt/2.0/report/transactions

Response samples 
{
  • "meta": {
    },
  • "data": [
    ]
}
Out Payment
These operations will allow our clients to transfer their funds from Easypay Accounts to a Sepa Bank Account.


Lists out payments
Full report with all the out payments from your Account Id


SecurityaccountId and apiKey 
Request 
query Parameters
page
number
Page Number


 
records_per_page
number
 Default:  20
Limit records per page (Max: 100)


 
type
string
Filter by type


 
method
string
Filter by method


 
id
string
Filter by id


 
key
string
Filter by out payment key


 
value
number <double> 
Filter by value


 
Responses 
200
Success


403
Forbidden


429
Too Many Requests


500
Internal Error


get/out_payment
Request samples 
Response samples 
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}
Create out payment
Get your strong authentication RSA private key from Easypay Backoffice on menu:
Web Services->Configuration API 2.0->Keys.


SecurityaccountId and apiKey and signatureAuth 
Request 
Request Body schema: application/json
required
object (Customer-Create-Or-Update) 
 
key
string  <= 50 characters 
Merchant identification key


 
value
required
number <double>   >= 0.5 
Value will be rounded to 2 decimals


 
type
string
 Default:  "normal"
Optional - only applicable to method transfer


 Enum: "normal" "instant"  
schedule_at
string <date-time> 
Schedule date to execute the payment


 
descriptive
string  <= 140 characters ^[a-zA-Z0-9 .,/+*$%]+$
 
object (Account) 
 
required
object (Out-Account) 
 
method
required
string
 Default:  "transfer"
 
timestamp
required
string
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


 
Responses 
201
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


500
Internal Error


post/out_payment
Request samples 
application/json
{
  • "customer": {
    },
  • "key": "Example Key",
  • "value": 0.5,
  • "type": "normal",
  • "schedule_at": "2019-08-24T14:15:22Z",
  • "descriptive": "Descriptive Example",
  • "account": {
    },
  • "out_account": {
    },
  • "method": "transfer",
  • "timestamp": "1696642539"
}
Response samples 
application/json
{
  • "status": "ok",
  • "message": [
    ],
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "method": {
    },
  • "customer": {
    },
  • "out_account": {
    }
}
Shows out payment details
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


get/out_payment/{id}
Request samples 
Response samples 
application/json
{
  • "id": "760d105e-950d-4b41-8017-cad840ca3baa",
  • "status": "success",
  • "type": "normal",
  • "method": "transfer",
  • "descriptive": "descriptive",
  • "customer": {
    },
  • "account": {
    },
  • "out_account": {
    },
  • "key": "Example Key",
  • "value": 1,
  • "schedule_at": "2022-11-25 10:30:11",
  • "transactions": [
    ],
  • "created_at": "2022-11-25 10:30:14"
}
Deletes out payment
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.


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
204
No content


400
Bad Request


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


delete/out_payment/{id}
Request samples 
Response samples 
{
  • "status": "error",
  • "message": [
    ]
}
Config
Account URL configuration for notifications and credit card transactions


Get Account Config
SecurityaccountId and apiKey 
Responses 
200
Success


403
Forbidden


429
Too Many Requests


500
Internal Error


get/config
Request samples 
Response samples 
application/json
{}
Patch Account Config
SecurityaccountId and apiKey 
Request 
Request Body schema: application/json
required
Payment configuration object to generate a payment


generic
string
 Default:  "https://www.easypay.pt/generic"
URL for generic notification


 
authorisation
string
 Default:  "https://www.easypay.pt/authorisation"
URL for authorisation notification


 
transaction
string
 Default:  "https://www.easypay.pt/transaction"
URL for transaction notification


 
visa_fwd
string
 Default:  "https://www.easypay.pt/visa_fwd"
URL for redirect clients on credit card forward


 
visa_detail
string
 Default:  "https://www.easypay.pt/visa_detail"
URL for credit card payment detail


 
Responses 
200
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


500
Internal Error


patch/config
Request samples 
application/json
No sample
Response samples 
application/json
{}
Checkout
Overview
Checkout is easypay's integrated solution for collecting payments in any website.


It requires no extensive programming knowledge by including a pre-built payment form directly in your website. Checkout is responsible for:


    

  • Collecting user information.
    • 

  • Allowing payment method selection.
    • 

  • Collecting payment information.
    • 

  • Invoking payment APIs.
    • 

  • Displaying payment feedback.
    • 



Checkout


Supported payment methods
Currently, the supported payment methods are:



To know how to choose from the available methods and integrate them with Checkout, read the integration guide.


Supported payment types
Both single and frequent payments, as well as subscriptions are accepted by Checkout.


Integration methods
All Checkout interactions begin by making a server-to-server request to create a Checkout session. The request will return a Checkout manifest, which is then used to configure and display a Checkout form created exclusively for that payment interaction.


You can then display a Checkout form in your page by invoking our Checkout SDK. The SDK can be included from a CDN, via HTML <script> tag, or you can use it as an NPM dependency in your project and import it in JavaScript/TypeScript.


This two-step approach makes Checkout the easiest way to integrate easypay payments in your custom website.


Demo
You can explore a live integration of Checkout to see what exactly is included in the solution, as well as trying out each payment flow.


The source code for the application, as well as instructions for running it locally, is available at the public repository.


Guide
Requirements


Before using Checkout, you will need an easypay payment account.


An example app that demonstrates the steps described in this guide is available at https://github.com/Easypay/checkout-demo .


Creating a checkout session


To create a Checkout session, you are required to send a server-to-server POST request to the /checkout endpoint. The created session will have an expiration time of 30 minutes at most, after which the users won't be able to pay that specific Checkout anymore.


Like all API requests, this request is authenticated as described in Authentication, which means you must include the AccountId and ApiKey headers.


An example payload is:


{
  "type": ["single"],
  "payment": {
    "methods": ["cc", "mb", "mbw", "dd", "vi"],
    "type": "sale",
    "capture": {
      "descriptive": "Purchase in MyStore"
    },
    "currency": "EUR",
    "expiration_time": null
  },
  "order": {
    "items": [
      {
        "description": "T-shirt",
        "quantity": 1,
        "key": "t-shirt",
        "value": 12.5
      },
      {
        "description": "Gloves",
        "quantity": 1,
        "key": "gloves",
        "value": 7
      }
    ],
    "key": "order-123",
    "value": 19.5
  }
}



You can check all the possible parameters in the Checkout reference.


The service will return something like:


{
  "id": "57cc19e9-f393-4cfa-9516-8807763b5096",
  "session": "8zoaBOC0Mj5Mg_YAbdRCqYGI66Zc2DttAWeyVcedzhuT3r2IE8aS7l7H-sQOyppgawIv-wO48H_oKDHMzvMf1TeIJwo3Xu7HO7Tmj7y1iblt8t9JlEzyNdf5HurTvCeszC8PdRS4mbaPBCMCQ7g4xkG0qUuOEhiee5OB49MJJQ-Mo9vEnC_R4hzRBi-HSIMviTNDcCm5NiMnn__nWZxpfAmh6pYUg_eznqTGNbheYLu7ku_mBn7HvAdJQcgsmk6eeD-Z9S8SsK-ONHpbJQz1LNZsUkIIiWpNxPMrzD5Je0r2veawzAaIQmCeN8hYncHDfl5YZ7PP28MFVtEjMGOxsOsqxL4wmDOLPO5s6aWMq7Dxns-OGgf0r7dmaka4Y2mXovLVtNxsGgsNbBav8K86f5DceCDmPKBzYh-X5i1nx07LuqYKoJmA8NfyVP5tb-R3Y9dtwbPzcHc_AyQVKlsM0HtW3JXAdqoIBfsDgUqwASeuqQHEyIITKlcRvDIzWFaxTgXmmJauj6et7mo1GEM4L1gDkA1IXOd3n4HU2GvfPw==",
  "config": null
}



This return object is referred to as a Checkout manifest, and will be needed in the steps below.


Integrating in your page


Script tag


Include the easypay Checkout SDK in your page:


<script src="https://cdn.easypay.pt/checkout/2.6.2/"></script>



Prepare an empty element in your page where you'd like the Checkout form to be and give it the easypay-checkout id:


<div id="easypay-checkout"></div>



Make sure to trigger the server-to-server call described above and get the contents of the manifest:


const manifest = await yourFunctionToGetTheManifest()



Then, use the globally available easypayCheckout variable to initialize the SDK and display the form:


easypayCheckout.startCheckout(manifest)



And the Checkout should be running smoothly.


Testing




NPM import


Instead of directly including the JavaScript library from the CDN, you can import it as an NPM module:


npm install --save @easypaypt/checkout-sdk



And use it like any other importable dependency:


import { startCheckout } from '@easypaypt/checkout-sdk'

startCheckout(manifest)



All the other steps are the same as for the CDN.


Customizing element id


If you'd like to have the Checkout form displayed in an element with another id, for instance:


<div id="checkout-form"></div>



You can pass the id in the options parameter of the Checkout initialization:


startCheckout(manifest, {id: 'checkout-form',
})



Removing Checkout contents


When starting a Checkout form, you can store the return value to later manage it (particularly by removing it from the page at a later date).


const checkoutInstance = startCheckout(manifest)



When you no longer wish to display the Checkout contents, call the unmount() method on the return object:


checkoutInstance.unmount()



Reacting to successful payment interactions


Even before the Checkout process is completed (by the user pressing the End button or closing the popup), the Checkout SDK is able to notify you of a successful payment interaction.


This doesn't necessarily mean that the funds were transferred, but that no more user interaction with the Checkout is needed.


For instance, for a Credit Card payment, this means that the user successfully authorized the operation, and for Multibanco payments this means the user has requested the entity and reference values to pay later.


function mySuccessHandler(checkoutSuccessInfo) {// There was a successful payment interaction// You can react to details in checkoutSuccessInfo
}

const checkoutInstance = startCheckout(manifest, {onSuccess: mySuccessHandler,
})



Your callback function can receive a parameter with additional details about the outcome of the payment process. The full reference of the details is available on the reference page.


Reacting to Checkout UI close


It will often be useful to know when users finish the Checkout process, so you can hide the Checkout contents and display a thank you message.
The SDK includes a callback parameter that you can pass to get notified when the Checkout process is closed. In inline mode, this always means that the user finished a payment interaction, but in popup mode the user can choose to close the Checkout popup without finishing a payment interaction.


let successfulPaymentInteraction = false

function mySuccessHandler(checkoutSuccessInfo) {successfulPaymentInteraction = true
}

function myCloseHandler() {if (successfulPaymentInteraction) {
    checkoutInstance.unmount()
    document.write('Your order was received. Thank you.')
}
}

const checkoutInstance = startCheckout(manifest, {onSuccess: mySuccessHandler, onClose: myCloseHandler,
})



Saving frequent payment information


Processing a frequent payment means you have to save tokenized payment details to later use them to actually transfer funds.


To create a frequent payment Checkout session, your initial POST request to /checkout will have to include the type property set to ['frequent'].


After the user selects a payment method and fills in their details (if any), the SDK will call the success handler with the result information. It is at this point that you should send the payment.id field to your server.


function saveTokenizedPayment(checkoutSuccessInfo) {sendTokenToServer(checkoutSuccessInfo.payment.id)
}

const checkoutInstance = startCheckout(manifest, {onSuccess: saveTokenizedPayment,
})



From then on, you can use the payment ID to send server-to-server requests capturing funds.


Each capture is created by sending a POST request to the /capture/<payment id> endpoint. The request must be authenticated with the AccountId and ApiKey headers as usual.
The payload has to include at least the descriptive and value for the capture. Learn more in the service reference.


{
  "descriptive": "Purchase in MyStore",
  "value": 20
}



On success, the service will return something similar to:


{
  "status": "ok",
  "message": ["Your request was successfully created"],
  "id": "c68d8d1a-4c95-4a87-b9b5-031057b3a68e"
}



You can use the resulting capture id to get information about the specific capture by issuing an authenticated GET request to /capture/<capture id>. Learn more in the service reference.


It will reply with the capture details:


{
  "account": {
    "id": "1a398de4-d318-48fc-a9fd-230f863dc0e1"
  },
  "capture_date": "2022-08-02",
  "descriptive": "Purchase in MyStore",
  "force_3ds":false,
  "id": "c68d8d1a-4c95-4a87-b9b5-031057b3a68e",
  "payment_id": "76ab3c32-7883-459f-a0ef-5fe0541e0ec7",
  "payment_type": "frequent",
  "status": "success",
  "transaction_key": "",
  "value": 20
}



Note: for frequent Multibanco Reference payments, no capture request is necessary. It's the customer's responsibility to make new payments to the same reference.


If you wish to be notified each time a payment is successful, follow our Notifications documentation.


Accepting subscriptions


For periodical payments with a set frequency, you can accept subscription payments in Checkout.


To do so, you will need to specify a payment type of ["subscription"].


You will also need to define:


    

  • A payment.start_time, that determines when the subscription payments start. The start time must be in the future.
    • 

  • A payment.frequency that sets the periodicity of the payments (weekly, monthly, etc). Available values are:
    • 

  • "1D" (daily)
    • 

  • "1W" (weekly)
    • 

  • "2W" (biweekly)
    • 

  • "1M" (monthly)
    • 

  • "2M" (bimonthly)
    • 

  • "3M" (trimonthly)
    • 

  • "4M" (quadmonthly)
    • 

  • "6M" (semiannually)
    • 

  • "1Y" (annually)
    • 

  • "2Y" (biannually)
    • 

  • "3Y" (triannually)
    • 

  • Either a payment.expiration_time or a payment.max_captures, so that the subscription has an end eventually.
    • 



Check the reference for additional details and all the available properties.


An example request payload would therefore be:


{
  "type": ["subscription"],
  "payment": {
    "methods": ["cc", "dd"],
    "type": "sale",
    "capture": {
      "descriptive": "Purchase in MyStore"
    },
    "start_time": "2023-01-01 00:00",
    "frequency": "1M",
    "expiration_time": "2030-12-31 23:59"
  },
  "order": {
    "items": [
      {
        "description": "My streaming service",
        "quantity": 1,
        "key": "streaming-service",
        "value": 12.5
      }
    ],
    "key": "order-123",
    "value": 12.5
  }
}



After typing their details, the customer would then see a confirmation dialog for the subscription:


Subscription


Pressing the proceed button allows to continue on with the payment method selection and the remaining interaction is the same as for single and frequent payments.


Reacting to Checkout errors


The Checkout process is resilient to most forms of errors and allows the customer to retry multiple times with different payment methods until the payment is completed.
However, there are cases where the Checkout form is unable to recover on its own, such as an expired Checkout session, an attempt to pay a Checkout that was already paid or a Checkout that was canceled.


You can be notified of such cases by passing the callback parameter onError:


function myErrorHandler(error) {checkoutInstance.unmount()switch (error.code) {
    case 'checkout-expired':// In this case a new Checkout session must be createdconst manifest = await yourFunctionToGetTheManifest()checkoutInstance = startCheckout(manifest, {
        onError: myErrorHandler
})
    break
case 'already-paid':
    document.write('Your order was already paid. Thank you.')
    break
case 'checkout-canceled':
    document.write('Your checkout was canceled.')
    break
default:
    document.write('Unable to process payment, please try again.')
}
}

const checkoutInstance = startCheckout(manifest, {onError: myErrorHandler
})



The list of possible errors is further documented in the reference


How to use popup module


If you want to integrate Checkout and display it in a popup this is what you need to do:


    

  1. Import easypay's Checkout SDK into you project:
    2. 




    

  1. Add a button with an id to your page:
    2. 



<button id="checkout">Open Popup</button>



function initEasypayCheckoutSDK(manifest) {checkoutInstance = easypayCheckout.startCheckout(manifest, {
    id: 'checkout',
    display: 'popup',
})
}



Result:

Checkout Popup Mode


Changing Checkout's appearance


Checkout supports a robust styling API that allows integrators to change its appearance in order to better blend it in their website.


The list of customizations include:


    

  • An optional company logo to display in the header
    • 

  • The colors used in:
    • 

  • The background
    • 

  • Highlights (the more colorful sections of the page, originally blue)
    • 

  • Buttons
    • 

  • Input borders and backgrounds
    • 

  • Whether to use floating labels in the inputs
    • 

  • Whether to use box-shadow in the buttons
    • 

  • The font family used to render the text
    • 

  • The overall text size
    • 



With a combination of some of these options, it's possible to change the Checkout entirely, fitting it in your website with ease.


Example:


const checkoutInstance = easypayCheckout.startCheckout(manifest, {logoUrl: 'www.example.com/mylogo.png', accentColor: 'orange', buttonBackgroundColor: '#111', buttonBoxShadow: false, buttonBorderRadius: 5, inputBorderRadius: 5, inputBorderColor: '#000', inputBackgroundColor: '#ffe7c4', backgroundColor: '#eee', fontFamily: 'https://fonts.gstatic.com/s/raleway/v28/1Ptxg8zYS_SKggPN4iEgvnHyvveLxVvaorCIPrEVIT9d0c8.woff2',
})



Outcome:


Checkout


To see every individual option in detail, check the reference.


SDK
startCheckout(manifest, [options])


Parameters:


    

  • manifest: The return object from the checkout service.
    • 

  • options: An optional object containing any of the following properties:
    


    
Option
Type
Required
Default
Description

    
    

    
id
string
no
'easypay-checkout'
The id of the HTML element where the Checkout form should be included.

    

    
onSuccess
function
no
() => {}
Callback function to be called when the Checkout is finished successfully.

    

    
onError
function
no
() => {}
Callback function to be called on (unrecoverable) errors.

    

    
onPaymentError
function
no
() => {}
Callback function to be called on (recoverable) payment errors.

    

    
onClose
function
no
undefined
Callback function to be called when the Checkout interaction is closed.

    

    
testing
boolean
no
false
Whether to use the testing API (true) or the production one (false).

    

    
display(1)
string
no
'inline'
The display style of the element that hosts the Checkout.

    

    
hideDetails
boolean
no
false
Whether to hide the details form or not. An expandable summary will be shown with the details, instead.

    

    
language(2)
string
no
undefined
The language in which to display the Checkout.

    

    
logoUrl
string
no
undefined
The merchant logo url to display in the Checkout.

    

    
backgroundColor
string
no
'#ffffff'
The color used as the background of the Checkout page.

    

    
accentColor
string
no
'#0d71f9'
The color used in highlights, as well as default buttons and input borders.

    

    
errorColor
string
no
'#ff151f'
The color used for errors.

    

    
inputBackgroundColor
string
no
'transparent'
The color used for the input backgrounds.

    

    
inputBorderColor
string
no
accentColor
The color for input borders.

    

    
inputBorderRadius
number
no
50
The border radius for inputs, in px.

    

    
inputFloatingLabel
boolean
no
true
Whether inputs should use floating labels.

    

    
buttonBackgroundColor
string
no
accentColor
The color used for the button backgrounds.

    

    
buttonBorderRadius
number
no
50
The border radius for buttons, in px.

    

    
buttonBoxShadow
boolean
no
true
Whether the buttons should have box-shadow.

    

    
fontFamily
string
no
'Overpass'
The font used for the text.

    

    
baseFontSize
number
no
10
The value in px for the font size of the root element (1rem).

    

    

    Options
    
(1) display available values: inline (default) or popup.
(2) language available values: en or pt_PT. If left undefined, a default language will be selected according to the customer's browser language.
    • 



Return:


    

  • A CheckoutInstance object, containing the following method:
      

    • unmount(): Removes all Checkout form content and event listener.
      • 

    

    • 






Success handler:


onSuccess(checkoutInfo)


Receives an object with the following properties:






Property
Type
Description





id
string
The id of the Checkout session.




type
string
The payment type for this Checkout ('single', 'frequent' or 'subscription').




payment
Object
Detailed information about the payment.





Properties of the payment Object:


Note: Some properties only appear with certain payment methods.






Property
Method
Type
Description





id
All
string
The payment's id.




method (1)
All
string
The payment method chosen by the customer.




status (2)
All
Object
The status of the payment.




value
All
number
The order value, rounded to two decimal places. Not used in frequent payments.




cardType
Credit Card
string
The credit card type ('VISA' or 'MasterCard').




lastFour
Credit Card
string
The last four digits of the credit card.




cardCountryCode
Credit Card
string
The country code of the credit card.




expirationDate (3)
Credit Card / Multibanco
string
The expiration date of the card (Credit Card) or the payment (Multibanco).




entity
Multibanco
string
The Multibanco entity.




reference
Multibanco
string
The Multibanco reference.




sddMandate (4)
Direct Debit
Object
SEPA Direct Debit mandate.




iban
Virtual IBAN
string
The created IBAN.





(1) Possible method values are the same as in the Checkout creation.


(2) Possible payment status values:


Expand


    

  • 'authorised'
    • 

  • 'deleted'
    • 

  • 'enrolled'
    • 

  • 'error'
    • 

  • 'failed'
    • 

  • 'paid'
    • 

  • 'pending'
    • 

  • 'success'
    • 

  • 'tokenized' (To be used later in frequent payments.)
    • 

  • 'voided'



(3) Format of the expiration varies between Credit Card ('MM/YY' format) and Multibanco ('Y-m-d H:i').


(4) Properties of the sddMandate Object:


Expand






Property
Type
Description





accountHolder
string
Name of the account holder.




billingEntity
string
The billing entity for the payments.




countryCode
string
Country code of the bank account.




email
string
The customer's e-mail address.




iban
string
The IBAN.




id
string
The mandate's id.




maxNumDebits
string
The maximum number of debits allowed for this Direct Debit.




name
string
The customer's name. May be different from the account holder's name.




phone
string
The customer's phone number.




referenceAdc
string
The authorization reference.











Error handler:


onError(error)


Receives an object with the following property:






Property
Type
Description





code
string 
The type of error that occurred. See the table below for possible values.





The error code has the following possible values and recommended solutions:






Value
Cause
Recommended solution





checkout-expired
The Checkout session has expired.
Create a new Checkout session with the server-to-server call and use the newly returned Manifest to instantiate a new Checkout form.




already-paid
The Checkout was already paid.
Refresh the order information and confirm that it was paid. Give feedback to the user accordingly.




checkout-canceled
The Checkout was canceled.
Create a new Checkout session with the server-to-server call and use the newly returned Manifest to instantiate a new Checkout form.




generic-error
An unspecified error occurred.
Since the root cause is unclear, you can try creating a new session or signal an error to the user.








Payment error handler:


onPaymentError(error)


Signals the occurrence of a recoverable error during a payment attempt. These errors are informative and for logging/analysis purposes, as the user is allowed (and encouraged) to try the payment again with the same or other payment method.


Receives an object with the following properties:






Property
Type
Description





code
string
The type of error that occurred. See the table below for possible values.




paymentMethod
string
The payment method for which the error happened.




checkout
object
On payment-failure errors, the Checkout object containing the payment information that had already been created. Has the same properties as the onSuccess checkoutInfo object.





The error code has the following possible values and recommended solutions:






Value
Cause
Recommended solution





generic-error
There was an error before the payment process had started.
Allow the user to try again. If problem persists, report it to easypay.




payment-failure
There was an error after the payment process had started.
Allow the user to try again. If problem persists, use the attached checkout object to get details about the payment intent.





Examples of each appearance property



const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  logoUrl: 'www.example.com/mylogo.png'
})



Outcome:


Checkout


Changing the background color


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  backgroundColor: '#222222'
})



The text colors are automatically adjusted to shades of black or white depending on the background color, in order to achieve the best contrast possible.


Outcome:


Checkout


Changing the accent color


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  accentColor: '#ffa861'
})



The text colors (over the accent, such as in buttons) are automatically adjusted to black or white, in order to achieve the best contrast possible.


Outcome:


Checkout


Changing the error color


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  errorColor: '#d18800'
})



Outcome:


Checkout


Changing the input background color


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  inputBackgroundColor: '#001f3d'
})



Outcome:


Checkout


Changing the input border color


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  inputBorderColor: '#000000'
})



Outcome:


Checkout


Changing the input border radius


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  inputBorderRadius: 0
})



Outcome:


Checkout


Using non-floating labels


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  inputFloatingLabel: false
})



Outcome:


Checkout


Changing button background color


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  buttonBackgroundColor: '#000000'
})



The button text color is automatically adjusted to black or white, in order to achieve the best contrast possible.


Outcome:


Checkout


Changing button border radius


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  buttonBorderRadius: 0
})



Outcome:


Checkout


Disabling button box-shadow


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  buttonBoxShadow: false
})



Outcome:


Checkout


Changing font family


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  fontFamily: 'cursive'
})



The fontFamily property can have three types of values:


    

  • Generic family name (e.g. 'sans-serif', 'serif', 'cursive')
    • 

  • Web safe font (e.g. 'arial', 'verdana')
    • 

  • Web font URL (e.g. 'https://fonts.gstatic.com/s/overpass/v12/qFda35WCmI96Ajtm83upeyoaX6QPnlo6_PPbM5qKl8Kuo8AzesE.woff2', must include the protocol http/https)
    • 



Outcome:


Checkout


Changing base font size


const checkoutInstance = easypayCheckout.startCheckout(manifest, {
  baseFontSize: 8
})



Changes the value in px for the font size of the root element (1rem). The default value is 10, so any value below will reduce the font size, while a value above will increase it.


Besides changing the size of the text (while keeping the proportions), this setting changes most of the layout dimensions, effectively increasing or decreasing the scale.


Outcome:


Checkout


Shows checkout details
SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
200
Success


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


get/checkout/{id}
Request samples 
Response samples 
application/json
{
  • "status": "failed",
  • "message": [
    ],
  • "checkout": {
    },
  • "payment": {
    },
  • "value": 0
}
Cancels a checkout
This cancels the Checkout and deletes the payment associated with it if possible.


SecurityaccountId and apiKey 
Request 
path Parameters
id
required
string <uuid> 
Resource Identification


 
Responses 
204
No content


400
Bad Request


401
Unauthorized


403
Forbidden


404
Resource Not Found


429
Too Many Requests


500
Internal Error


delete/checkout/{id}
Request samples 
Response samples 
{
  • "status": "error",
  • "message": [
    ]
}
Create Checkout
Creates a Checkout Session.


SecurityaccountId and apiKey 
Request 
Request Body schema: application/json
required
Checkout request details


type
required
Array of strings
Only the first value in the Array is considered (e.g. ['single', 'frequent'] would be equivalent to ['single']).


Items Enum: "single" "frequent" "subscription"  
required
object
Describing the payment configuration.


 
object
Order represent the order/cart being paid. Order is required if type is one single or subscription.


 
required
object
The customer details.


 
Responses 
201
Success


400
Bad Request


403
Forbidden


429
Too Many Requests


500
Internal Error


post/checkout
Request samples 
application/json
{
  • "type": [
    ],
  • "payment": {
    },
  • "order": {
    },
  • "customer": {
    }
}
Response samples 
application/json
{
  • "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
}