Skip to content

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

Subscription Payment

Set up and manage automated recurring payments

Operations

List subscription payments

Request

Full report with all the subscriptions payments from your Account Id

Security
accountId and apiKey
Query
pagenumber

Page Number

records_per_pagenumber

Limit records per page (Max: 100)

Default 20
expiration_timestring

Filter by expiration time interval (max 30 days)

methodstring

Filter by method

customerstring

Filter by customer key

idstring

Filter by id

keystring

Filter by subscription key

created_atstring

Filter by created datetime interval (max 30 days)

statusstring

Filter by Subscription Status

Example: status=active
valuestring

Filter by Subscription Value

Example: value=10.55
curl -i -X GET \
  'https://api.test.easypay.pt/2.0/subscription?page=0&records_per_page=20&expiration_time=string&method=string&customer=string&id=string&key=string&created_at=string&status=active&value=10.55' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92'

Responses

OK

Bodyapplication/json
dataArray of objects(subscription-response-on-list)
metaobject(meta)

Metadata object containing pagination and result information for list responses.

Response
application/json
{
  "data": [
    { … }
  ],
  "meta": {
    "page": { … },
    "records": { … },
    "links": { … }
  }
}

Create subscription payment

Request

Creates a Subscription.

Security
accountId and apiKey
Bodyapplication/jsonrequired

Payment configuration object to generate a payment

frequent_idstring(uuid)

Only required to create a subscription from an active Frequent Payment.
Some properties like customer and sdd_mandate are inherited by the subscriptions.
So it's not necessary to send them in the request creation.

Example: "9234ef0f-b666-41cc-8ad2-5b54c1a84150"
captureobject
expiration_timestring(Y-m-d H:i)

The last possible time to make the payment.
Required only when max_captures and/or unlimited_payments are NOT set.

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

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

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: "Example Key"
valuenumber(double)>= 0.5required

The payment value.
Will be rounded to 2 decimals.

Example: 12.55
frequencystring(frequency)required

Defining the frequency that the cycles are charged.

Enum"1D""1W""2W""1M""2M""3M""4M""6M""1Y""2Y"
max_capturesinteger

Defining the total of cycles that will be charged.
Required only when expiration_time and/or unlimited_payments are NOT set.

unlimited_paymentsboolean

When this property is set, unlimited cycles will be charged until the subscription is inactivated or deleted.

Default false
start_timestring(Y-m-d H:i)required

Defining the start of billing cycles.

Example: "2027-01-11 16:05"
failoverboolean

After all retries failed, the payment cycle can have another try with another single method.

Default false
capture_nowboolean

Whether to schedule an immediate capture and schedule the second one for start_time.

Default false
retriesinteger

Number of tries for every cycle of payments.
The maximum number of retries that can occur will be determined by the frequency that is selected.
If a capture is unsuccessful for any reason, it will attempt to charge once more until the allotted number of attempts is reached.

Default 0
methodstringrequired

The payment methods.

Enum"cc""dd"
Example: "cc"
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 POST \
  https://api.test.easypay.pt/2.0/subscription \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "expiration_time": "2022-12-04 12:00",
    "max_captures": 2,
    "start_time": "2022-12-04 12:00",
    "value": 17.55,
    "frequency": "1D",
    "method": "cc"
  }'

Responses

Created

Bodyapplication/json
idstring(uuid)
Example: "458b2fc4-3092-4de3-abd4-fe1600c09420"
statusstring
Example: "ok"
keystring
Example: "payment 02536985"
expiration_timestring(date-time)
Example: "2099-01-15 00:00"
start_timestring(date-time)
Example: "2027-01-15 00:00"
frequencyany
Enum"1D""1W""2W""1M""2M""3M""4M""6M""1Y""2Y"
retriesinteger
Example: 2
max_capturesinteger
Example: 12
failoverboolean
Default false
capture_nowboolean
unlimited_paymentsboolean
customerobject(customer-response-on-detail)

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

methodobject(subscription-method-response-on-detail)
transactionsArray of objects(payment-transactions)
currencystring(currency)

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

Value"EUR"
valuenumber(double)
Example: 10.55
created_atstring(date-time)
Example: "2025-08-05 13:44:29"
Response
application/json
{
  "status": "ok",
  "message": {
    "id": "458b2fc4-3092-4de3-abd4-fe1600c09420",
    "key": "subscription 02536985",
    "expiration_time": "2099-01-15 00:00",
    "start_time": "2027-01-15 00:00",
    "frequency": "1M",
    "retries": 2,
    "max_captures": 12,
    "failover": false,
    "capture_now": true,
    "unlimited_payments": false,
    "customer": { … },
    "method": { … },
    "transactions": [],
    "currency": "EUR",
    "value": 10.55,
    "created_at": "2025-08-05 13:44:29"
  }
}

Shows subscription payment details

Request

Retrieves the subscription payment details

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

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

Responses

OK

Bodyapplication/json
idstring(uuid)
Example: "458b2fc4-3092-4de3-abd4-fe1600c09420"
statusstring
Example: "ok"
keystring
Example: "payment 02536985"
expiration_timestring(date-time)
Example: "2099-01-15 00:00"
start_timestring(date-time)
Example: "2027-01-15 00:00"
frequencyany
Enum"1D""1W""2W""1M""2M""3M""4M""6M""1Y""2Y"
retriesinteger
Example: 2
max_capturesinteger
Example: 12
failoverboolean
Default false
capture_nowboolean
unlimited_paymentsboolean
customerobject(customer-response-on-detail)

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

methodobject(subscription-method-response-on-detail)
transactionsArray of objects(payment-transactions)
currencystring(currency)

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

Value"EUR"
valuenumber(double)
Example: 10.55
created_atstring(date-time)
Example: "2025-08-05 13:44:29"
Response
application/json
{
  "id": "458b2fc4-3092-4de3-abd4-fe1600c09420",
  "key": "subscription 02536985",
  "expiration_time": "2099-01-15 00:00",
  "start_time": "2027-01-15 00:00",
  "frequency": "1M",
  "retries": 2,
  "max_captures": 12,
  "failover": false,
  "capture_now": true,
  "unlimited_payments": false,
  "customer": {
    "id": "e66c4f80-3dc6-11eb-b378-0242ac130002",
    "name": "João Silva",
    "email": "joao.silva@test.com",
    "phone": "+351911234567",
    "fiscal_number": "123456789",
    "key": "customer_key_123",
    "phone_indicators": { … }
  },
  "method": {
    "type": "CC",
    "status": "active",
    "url": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a",
    "last_four": "2222",
    "card_type": "VISA",
    "expiration_date": "07/29"
  },
  "transactions": [
    { … }
  ],
  "currency": "EUR",
  "value": 10.55,
  "created_at": "2025-08-05 13:44:29"
}

Deletes subscription payment

Request

Deletes the subscription

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

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

Responses

No Content

Response
No content

Updates subscription payment details

Request

Updates the subscription payment details

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

Bodyapplication/jsonrequired

Subscription Payment object to edit existing one

statusstring

The Subscription Status.
When sets to inactive the next pending cycles will be deleted.
When sets to active a new billing cycle will be schedule accordingly the new frequency and start_time.
Those properties are required to active a subscription.

Enum"active""inactive"
Example: "active"
captureobject
expiration_timestring(Y-m-d H:i)
Example: "2039-12-12 16:05"
currencystring(currency)

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

Value"EUR"
customerobject(updatable-customer)

The Customer object contains detailed information about the customer involved in the transaction. Used for update operations where all fields are optional.

keystring<= 50 characters

The merchant's key for identifying the payment.

Example: "Example Key"
valuenumber(double)>= 0.5

The payment value.
Will be rounded to 2 decimals.

Example: 12.55
frequencystring(frequency)

Defining the frequency that the cycles are charged.

Enum"1D""1W""2W""1M""2M""3M""4M""6M""1Y""2Y"
max_capturesinteger

Defining the total of cycles that will be charged.
When this property is set, unlimited_payments will be inactivated.

unlimited_paymentsboolean

When this property is set, unlimited cycles will be charged until the subscription is inactivated or deleted.

start_timestring(Y-m-d H:i)

Defining the start of billing cycles.

Example: "2025-12-12 16:05"
failoverboolean

After all retries failed, the payment cycle can have another try with another single method.

Default false
retriesinteger

Number of retries in each payment cycle.
The chosen frequency will define the max number of possible retries.

Default 0
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/subscription/{id}' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "capture": {
      "transaction_key": "Transaction Key",
      "descriptive": "subscription"
    },
    "retries": 2,
    "customer": {
      "email": "john.doe@example.com",
      "key": "Customer Key",
      "language": "PT"
    },
    "key": "Payment Key Key",
    "max_captures": 12,
    "start_time": "2025-08-06 11:07",
    "expiration_time": "2099-08-06 11:07",
    "value": 10.99,
    "frequency": "1M",
    "method": "dd",
    "sdd_mandate": {
      "iban": "PT50002700000001234567833",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "911234567",
      "account_holder": "John Doe",
      "key": "SDD Mandate key",
      "max_num_debits": "12"
    }
  }'

Responses

OK

Bodyapplication/json
statusstring
Example: "ok"
messageobject(subscription-response-on-detail)

Subscription object that returns after a success request.

Response
application/json
{
  "status": "ok",
  "message": {
    "id": "458b2fc4-3092-4de3-abd4-fe1600c09420",
    "key": "subscription 02536985",
    "expiration_time": "2099-01-15 00:00",
    "start_time": "2027-01-15 00:00",
    "frequency": "1M",
    "retries": 2,
    "max_captures": 12,
    "failover": false,
    "capture_now": true,
    "unlimited_payments": false,
    "customer": { … },
    "method": { … },
    "transactions": [ … ],
    "currency": "EUR",
    "value": 10.55,
    "created_at": "2025-08-05 13:44:29"
  }
}

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