Skip to content
/
Shows frequent payment de...

Easypay Payments API (2.0)

Terms conditions and legal terms
Privacy Policy

Download OpenAPI description
openapi.json
openapi.yaml
Overview
Easypay Documentation
correio@easypay.pt
License
MIT
Languages
Servers
Sandbox
https://api.test.easypay.pt/2.0
Production
https://api.prod.easypay.pt/2.0

Single Payment

Create and manage one-time payment transactions

Operations

Frequent Payment

Tokenize payment details for variable on-demand charges

Operations

Lists frequent payments

Request

Full report with all the frequent payments from your Account Id

Security
accountId and apiKey
Query
pageinteger

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

Default 1
Example: page=1
records_per_pageinteger

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

Default 20
Example: records_per_page=20
expiration_timestring

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

Filter by payment method used in the transaction.

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

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
idstring(uuid)

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

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

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
created_atstring

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)
curl -i -X GET \
  'https://api.test.easypay.pt/2.0/frequent?page=1&records_per_page=20&expiration_time=interval%282006-01-02+15%3A04%2C2006-01-02+15%3A04%29&method=mb&customer=01J32EDWGNX94XMWP8PWB23KBK&id=bb3e7e60-20f3-4208-9b21-64c635a51f42&key=01J32EESEC1Z543P7J3PKSF1Q9&created_at=interval%282006-01-02+15%3A04%2C2006-01-02+15%3A04%29' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92'

Responses

OK

Bodyapplication/json
metaobject(meta)required

Metadata object containing pagination and result information for list responses.

meta.​pageobject

Pagination details

Example: 1
meta.​recordsobject

Record details

Example: 20
meta.​linksobject

Navigation links for pagination

dataArray of objects(frequent)required
data[].​idstring(uuid)(Identifier)required

A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.

Example: "c6056234-a3f9-42de-b944-3ed793fcb6bb"
data[].​keystring

A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.

Example: "Default Key"
data[].​expiration_timestring

Expiration date and time for the frequent payment in ISO 8601 format

Example: "2024-07-01T15:15:00Z"
data[].​customerobject(customer)

The Customer object contains the necessary details about the customer involved in the transaction. This includes identification information, contact details, and preferences. All fields are optional unless specified otherwise.

data[].​methodobject(frequent-method-response)

Method details for frequent payment responses

data[].​currencystring

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"
Example: "EUR"
data[].​max_valuenumberrequired

Maximum value allowed for transactions

Example: 20.55
data[].​min_valuenumberrequired

Minimum value allowed for transactions

Example: 2.55
data[].​unlimited_paymentsboolean

Whether transactions are unlimited, max or min value will be refreshed on each payment

Example: false
data[].​created_atstringrequired

Date when payment was created.

Example: "2017-12-12 16:05:02"
Response
application/json
{
  "meta": {
    "page": { … },
    "records": { … },
    "links": { … }
  },
  "data": [
    { … },
    { … }
  ]
}

Create frequent payment

Request

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

Security
accountId and apiKey
Bodyapplication/json
expiration_timestring

Expiration date and time for the payment in YYYY-MM-DD HH:mm format

Example: "2038-12-12 16:05"
currencystring

Currency code for the payment

Default "EUR"
Enum"EUR""BRL"
Example: "EUR"
customerobject(customer)required

The Customer object contains the necessary details about the customer involved in the transaction. This includes identification information, contact details, and preferences. All fields are optional unless specified otherwise.

customer.​idstring(uuid)

Unique identifier for the customer. When provided, it links the transaction to an existing customer record.

Example: "649e88cf-0b78-4c36-8f99-33f5ebb812a1"
customer.​namestring<= 255 characters

Full name of the customer. This is typically displayed on receipts and statements.

Example: "John Doe"
customer.​emailstring(email)<= 70 characters

Customer's email address. Used for sending receipts, notifications, and payment confirmations.

Example: "john.doe@example.com"
customer.​phonestring<= 15 characters

The contact phone number of the customer, excluding the country code indicator (e.g., "+351"). This field is used for communication purposes. If the payment method is MBWAY, the phone_number is required and is used to send the MBWAY push notification.

Example: "911234567"
customer.​phone_indicativestring<= 5 characters

The country code indicator for the customer's phone number (e.g., "351" for Portugal). This field is used in conjunction with the phone number to ensure proper international dialing and communication.

Example: "+351"
customer.​fiscal_numberstring<= 20 characters

Customer's tax identification number or fiscal number. Format may vary by country.

Example: "PT123456789"
customer.​keystring<= 255 characters

A customizable text field for users to input their own identifier for the customer. This can be any string that helps the user uniquely identify the customer in their own system.

Example: "customer Key Example"
customer.​languagestring= 2 characters

Preferred language for customer communications. Uses ISO 639-1 language codes.

Enum"PT""EN""ES"
Example: "PT"
keystring<= 50 characters

The merchant's key for identifying the payment.

Example: "Key Example"
min_valuenumber(double)>= 0.01

Minimum value allowed for transactions

Example: 10
max_valuenumber(double)>= 0.01

Maximum value allowed for transactions

Example: 25.5
unlimited_paymentsboolean

Transactions will be unlimited, max or min value will be refreshed on each payment.

Default true
methodstringrequired

Payment method type

Enum"mb""cc""dd""mbw""vi"
Example: "dd"
sdd_mandateobject(sdd-mandate)

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.

multibancoobject

Configuration of the Multibanco payment

curl -i -X POST \
  https://api.test.easypay.pt/2.0/frequent \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "expiration_time": "2038-12-12 16:05",
    "currency": "EUR",
    "customer": {
      "name": "Customer Example",
      "email": "customer@example.com",
      "phone": "911234567",
      "phone_indicative": "351",
      "fiscal_number": "PT123456789",
      "key": "Key Example",
      "language": "PT"
    },
    "key": "Key Example",
    "max_value": 25.5,
    "min_value": 10,
    "unlimited_payments": true,
    "method": "dd",
    "sdd_mandate": {
      "iban": "PT50002700000001234567833",
      "key": "Key Example",
      "name": "Name Example",
      "email": "customer@example.com",
      "phone": "911234567",
      "account_holder": "Acount Name Example",
      "country_code": "PT",
      "max_num_debits": "12"
    }
  }'

Responses

Created

Bodyapplication/json
statusstring

Status of the request

Example: "ok"
messageArray of strings

Array of status messages

Example: ["Your request was successfully created"]
idstring(uuid)

Unique identifier for the created frequent payment

Example: "86401037-1c8d-4cf3-9172-d0a29b17b9fd"
methodobject

Payment method details

customerobject

Customer information

Response
application/json
{
  "status": "ok",
  "message": [
    "Your request was successfully created"
  ],
  "id": "cd90455e-4ab3-42cf-a91c-cfc6e3afa65a",
  "method": {
    "type": "cc",
    "status": "waiting",
    "url": "https://cc.test.easypay.pt/start/cd90455e-4ab3-42cf-a91c-cfc6e3afa65a"
  },
  "customer": {
    "id": "68d07e52-3e04-493f-aaeb-bffe7ddb81ee"
  }
}

Shows frequent payment details

Request

Retrieve a Frequent Payment details

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

curl -i -X GET \
  'https://api.test.easypay.pt/2.0/frequent/{id}' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92'

Responses

OK

Bodyapplication/json
idstring(uuid)(Identifier)required

A unique identifier for the resource. While typically formatted as a UUID (Universally Unique Identifier), it can also be in other formats as defined by the user. This field ensures the resource can be distinctly recognized and referenced.

Example: "c6056234-a3f9-42de-b944-3ed793fcb6bb"
keystring

A customizable text field for users to input their own identifier for the resource. This can be any string that helps the user uniquely identify or reference the resource in their own system.

Example: "Default Key"
expiration_timestring

Expiration date and time for the frequent payment in ISO 8601 format

Example: "2024-07-01T15:15:00Z"
customerobject(customer)

The Customer object contains the necessary details about the customer involved in the transaction. This includes identification information, contact details, and preferences. All fields are optional unless specified otherwise.

methodobject(frequent-method-response)

Method details for frequent payment responses

currencystring

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"
Example: "EUR"
max_valuenumberrequired

Maximum value allowed for transactions

Example: 20.55
min_valuenumberrequired

Minimum value allowed for transactions

Example: 2.55
unlimited_paymentsboolean

Whether transactions are unlimited, max or min value will be refreshed on each payment

Example: false
created_atstringrequired

Date when payment was created.

Example: "2017-12-12 16:05:02"
transactionsArray of objects

Array of payment transactions associated with this frequent payment

Response
application/json
{
  "id": "ac1913a3-fd78-4822-8394-0a14f4169247",
  "key": "Default Key",
  "expiration_time": "2022-12-12T16:05:00Z",
  "customer": {
    "id": "fdc4bc82-8e45-4597-b46d-51d3285cf935",
    "name": "Robert Stuart",
    "email": "email@example.com",
    "phone": "911234567",
    "key": "Customer key",
    "language": "PT"
  },
  "method": {
    "type": "cc",
    "status": "active",
    "url": "https://cc.test.easypay.pt/start/ac1913a3-fd78-4822-8394-0a14f4169247",
    "last_four": "0000",
    "card_type": "VISA",
    "expiration_date": "04/25"
  },
  "currency": "EUR",
  "max_value": 20,
  "min_value": 2,
  "unlimited_payments": false,
  "created_at": "2022-11-23 13:16:58"
}

Deletes frequent payment

Request

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.

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

curl -i -X DELETE \
  'https://api.test.easypay.pt/2.0/frequent/{id}' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92'

Responses

No Content

Response
No content

Updates frequent payment details

Request

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

Bodyapplication/jsonrequired

Frequent Payment object to edit existing one

statusstring

Status of the frequent payment

Enum"active""deleted"
Example: "active"
expiration_timestring(Y-m-d H:i)

Expiration date and time for the payment

Example: "2017-12-12 16:05"
currencystring(currency)

ISO 4217 currency code. If not specified, the default currency is set to EUR.

Value"EUR"
customerobject(customer)

The Customer object contains the necessary details about the customer involved in the transaction. This includes identification information, contact details, and preferences. All fields are optional unless specified otherwise.

keystring<= 50 characters

The merchant's key for identifying the payment.

Example: "Key Example"
max_valuenumber(double)>= 0.01

Maximum value allowed for transactions

Example: 25.5
min_valuenumber(double)>= 0.01

Minimum value allowed for transactions

Example: 10
unlimited_paymentsboolean

Transactions will be unlimited, max or min value will be refreshed on each payment.

Default true
sdd_mandateobject(sdd-mandate)

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.

curl -i -X PATCH \
  'https://api.test.easypay.pt/2.0/frequent/{id}' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "status": "active",
    "expiration_time": "2038-12-12 16:05",
    "currency": "EUR",
    "customer": {
      "id": "22ea3cc9-424b-489a-91b7-8955f643dc93",
      "name": "Customer Example",
      "email": "customer@example.com",
      "phone": "911234567",
      "phone_indicative": "+351",
      "fiscal_number": "PT123456789",
      "key": "Key Example",
      "language": "PT"
    },
    "key": "Example Key",
    "max_value": 20,
    "min_value": 2,
    "unlimited_payments": false,
    "sdd_mandate": {
      "id": "12345678901",
      "iban": "PT50002700000001234567833",
      "key": "Key Example",
      "name": "Name Example",
      "email": "customer@example.com",
      "phone": "911234567",
      "account_holder": "Acount Name Example",
      "country_code": "PT",
      "max_num_debits": "12"
    }
  }'

Responses

OK

Body
statusstring

Status of the request

Example: "ok"
messageArray of strings

Array of status messages

Example: ["Your request was successfully created"]
idstring(uuid)

Unique identifier for the frequent payment

Example: "86401037-1c8d-4cf3-9172-d0a29b17b9fd"
methodobject

Payment method details

customerobject

Customer information

Response
{
  "method": {
    "type": "dd",
    "sdd_mandate": { … }
  },
  "status": "ok",
  "message": [
    "Your request was successfully created"
  ]
}

Request Authorisation

Request

Create a new authorisation on a given Frequent Payment

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

Bodyapplication/jsonrequired

Payment configuration object to generate a payment

transaction_keystring<= 255 characters

Your internal key identifying this authorisation.

Example: "transaction_key_123"
force_3dsboolean

Whether or not you want to force the 3DS authentication.

Default false
descriptivestring<= 255 charactersrequired

This will appear in the bank statement/mbway application.

Example: "Descriptive Example"
valuenumber(double)>= 0.5required

Value will be rounded to 2 decimals.

Example: 10.5
mbway_sdkobjectDeprecated

MBway SDK configuration for payment processing

curl -i -X POST \
  'https://api.test.easypay.pt/2.0/frequent/authorisation/{id}' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_key": "string",
    "descriptive": "Descriptive Example",
    "value": 17.5
  }'

Responses

Created

Bodyapplication/json
idstring(uuid)

Unique identifier for the authorization

Example: "4c67e74b-a256-4e0a-965d-97bf5d01bd50"
statusstring

Status of the request

Example: "ok"
messageArray of strings

Array of status messages

Example: ["Your request was successfully created"]
Response
application/json
{
  "id": "4c67e74b-a256-4e0a-965d-97bf5d01bd50",
  "status": "ok",
  "message": [
    "Your request was successfully created"
  ]
}

Subscription Payment

Set up and manage automated recurring payments

Operations

Captures

Operations for managing payment captures

Operations

Authorisations

Operations for managing payment authorisations

Operations

Voids

Operations for managing payment voids

Operations

Refunds

Operations for managing payment refunds

Operations

Chargebacks

Operations for managing chargebacks

Operations

Notifications / Webhooks

Configure and manage webhook notifications for payment events

Webhooks

Reports

Access transaction and ledger reports

Operations

Out Payment

Transfer funds from Easypay accounts to SEPA bank accounts

Operations

Config

Configure account URLs for notifications and credit card transactions

Operations

Checkout

Embedded payment form solution for websites

Operations

System

System health check endpoints

Operations
© 2026 easypay - Bank of Portugal N.º 8706