Easypay Payments API (2.0)

Download OpenAPI specification:Download

Easypay Documentation: tec@easypay.pt

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.

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.

Universo Flex

Universo Flex is a Portuguese local synchronous pull payment method similar to Credit Card, allowing the merchant to accept payments in 3 to 24 installments without having to be a credit intermediary.

Santander Consumer Finance

Santander Consumer Finance is a Portuguese local asynchronous pull payment method where the customer applies for a loan to acquire the good or service in installments. The merchant does not need to be a credit intermediary.

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

Payments used on a one time purchase

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


Boleto


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.


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.

Santander Consumer


By successfully calling the API 2.0 in a Single, our system returns a URL in the response JSON for the client to be forwarded to. The end customer must fullfill the journey in the Santander Consumer page. After the journey is completed with success, our system sends a Generic Notification with the Single ID. Upon receipt, your system should call the Single Details endpoint with the Single ID reported as successful in order to confirm it.

Universo Flex


By successfully calling the API 2.0 in a Single with type sale, our system returns a URL in the response JSON for the client to be forwarded to. The end customer must fullfill the journey in the Universo Flex page. After the journey is completed with success or failure, our system sends a Generic Notification with the Single ID. Upon receipt, your system should call the Single Details endpoint with the Single ID reported as successful in order to confirm it.

For Visa forward and Visa details configurations follow this link

Lists single payments

Full report with all the single payments from your Account

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

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

value
number <double>

Filter by value

created_at
string

Filter by created datetime interval (max 30 days)

Responses
200

OK

403

Forbidden

404

Not Found

429

Too Many Requests

500

Internal Error

get/single
Request samples
Response samples
application/json
{
  • "meta": {
    },
  • "data": [
    ]
}

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

SecurityaccountId and apiKey
Request
Request Body schema: application/json
required

Configuration object to generate a single payment

type
string
Default: "sale"

Optional - only applicable to method CC, MBW and UF

Enum: "sale" "authorisation"
object

Required if the payment type is sale.

expiration_time
string <Y-m-d H:i>

The last possible time to make the payment. Applicable in Multibanco payments.

currency
string
Default: "EUR"
Enum: "EUR" "BRL"
value
required
number <double> >= 0.5

Value will be rounded to 2 decimals

methods
required
Array of strings
Items Enum: "MB" "MBW" "DD" "CC" "SC" "UF" "VI"
key
string <= 50 characters

The merchant's key for identifying the payment.

object

The customer details.

Responses
201

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

500

Internal Error

post/single
Request samples
application/json
{
  • "customer": {
    },
  • "key": "merchant identification key Example",
  • "value": 15.5,
  • "method": "MB",
  • "capture": {
    }
}
Response samples
{
  • "id": "string",
  • "method": {
    },
  • "customer": {
    },
  • "status": "ok",
  • "message": [
    ],
  • "capture": {
    }
}

Shows single 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/single/{id}
Request samples
Response samples
{
  • "id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50",
  • "expiration_time": "2017-12-12 16:05",
  • "currency": "EUR",
  • "customer": {
    },
  • "key": "Example Key",
  • "value": 17.5,
  • "method": {
    },
  • "payment_status": "paid",
  • "paid_at": "2017-12-12 16:05:02",
  • "created_at": "2017-12-12 16:05:02"
}

Deletes single payment

This delete operation is not applicable for MB and BB method.
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/single/{id}
Request samples
Response samples
application/json
{ }

Updates single payment details

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

Resource Identification

Request Body schema: application/json
required

Single Payment object to edit existing one

id
string <uuid>
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

expiration_time
string <Y-m-d H:i>

Optional

currency
string
Default: "EUR"
Enum: "EUR" "BRL"
object
key
string <= 50 characters

Merchant identification key

method
required
string

It is not possible to edit after it's creation.

Enum: "mb" "cc" "mbw" "dd" "bb" "vi" "uf" "sc"
object
object (SddMandate)

Only required if 'method' is 'dd'

Responses
200

Success

304

Not Modified

400

Bad Request

401

Unauthorized

403

Forbidden

404

Resource Not Found

429

Too Many Requests

500

Internal Error

patch/single/{id}
Request samples
application/json
{
  • "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  • "descriptive": "Descriptive Example",
  • "value": 17.5,
  • "expiration_time": "2017-12-12 16:05",
  • "currency": "EUR",
  • "customer": {
    },
  • "key": "string",
  • "method": "mb",
  • "account": {
    },
  • "sdd_mandate": {
    }
}
Response samples
{
  • "id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50",
  • "expiration_time": "2017-12-12 16:05",
  • "currency": "EUR",
  • "customer": {
    },
  • "key": "Example Key",
  • "value": 17.5,
  • "method": {
    },
  • "payment_status": "paid",
  • "paid_at": "2017-12-12 16:05:02",
  • "created_at": "2017-12-12 16:05:02",
  • "status": "ok",
  • "message": [
    ]
}

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
required

Payment configuration object to generate a payment

expiration_time
string <Y-m-d H:i>
currency
string
Default: "EUR"
Enum: "EUR" "BRL"
object (Customer)
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.

method
string (Payment_Frequent_Method_Available)
Enum: "mb" "cc" "dd" "mbw" "vi"
object (SddMandate)

Only required if 'method' is 'dd'

Responses
201

Success

400

Bad Request

403

Forbidden

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.50",
  • "min_value": "10.00",
  • "unlimited_payments": true,
  • "method": "dd",
  • "sdd_mandate": {
    }
}
Response samples
{}

Shows 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
application/json
{ }

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
Default: "EUR"
Enum: "EUR" "BRL"
object (Customer)
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)

Only required if 'method' is 'dd'

Responses
200

Success

304

Not Modified

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,50",
  • "min_value": "10,00",
  • "unlimited_payments": true,
  • "sdd_mandate": {
    }
}
Response samples
{
  • "method": {
    },
  • "status": "ok",
  • "message": [
    ]
}

Request Authorisation

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
Default: "EUR"
Enum: "EUR" "BRL"
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)

Only required if 'method' is 'dd'

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
application/json
{ }

Updates 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
Enum: "EUR" "BRL"
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)

Only required if 'method' is 'dd'

Responses
200

Success

304

Not Modified

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

Shows capture 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/capture/{id}
Request samples
Response samples
{
  • "transaction_key": "key example",
  • "capture_date": "2022-11-28",
  • "account": {
    },
  • "descriptive": "Descriptive Example",
  • "value": 200,
  • "splits": [
    ],
  • "status": "waiting",
  • "id": "9595ab59-5f86-414c-8eda-5fc5e627fd2c",
  • "payment_type": "single",
  • "payment_id": "ead8a505-4f14-4ad2-b77b-b6dbf598977d",
  • "force_3ds": false
}

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 <Y-m-d>
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.

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

Shows authorisation 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/authorisation/{id}
Request samples
Response samples
{}

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

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

Responses
201

Success

400

Bad Request

403

Forbidden

412

Precondition Failed

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

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. 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. The integrator system performs its internal application logic regarding the payment state transition, according to API response.

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 Notification

SecurityaccountId and apiKey
Request
Request Body schema: application/json
required

We will send you this json in our notifications

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 <Y-m-d H:i:s>
Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

500

Internal Error

post/your-generic-notification-endpoint
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"
}
Response samples
application/json
{
  • "status": "ok",
  • "message": [
    ]
}

Authorisation Notification

SecurityaccountId and apiKey
Request
Request Body schema: application/json
required

We will send you this json in our notification

object
object
Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

500

Internal Error

post/your-authorisation-notification-endpoint
Request samples
application/json
{
  • "account": {
    },
  • "authorisation": {
    }
}
Response samples
application/json
{
  • "status": "ok",
  • "message": [
    ]
}

Transaction Notification

SecurityaccountId and apiKey
Request
Request Body schema: application/json
required

We will send you this json in our notification

object
Responses
200

Success

400

Bad Request

403

Forbidden

429

Too Many Requests

500

Internal Error

post/your-notification-endpoint
Request samples
application/json
{
  • "account": {
    }
}
Response samples
application/json
{
  • "status": "ok",
  • "message": [
    ]
}

Reports

Report Transactions

List your transactions

SecurityaccountId and apiKey
Request
query Parameters
start_date
string <Y-m-d H:i>

Filter from this date

end_date
string <Y-m-d H:i>

Filter until this date

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