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

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

List Refunds

Request

Cursor based endpoint to retrieve all account refunds.

Security
accountId and apiKey
Query
cursorstring

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.

limitnumber

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_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)
updated_atstring

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)
curl -i -X GET \
  'https://api.test.easypay.pt/2.0/refund?cursor=string&limit=0&created_at=interval%282006-01-02+15%3A04%2C2006-01-02+15%3A04%29&updated_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
metadataobject

An object containing additional information about the response. It includes details that help manage and navigate the retrieved data.

dataArray of objects
Response
application/json
{
  "metadata": {
    "next_cursor": "string",
    "count": 5
  },
  "data": [
    { … }
  ]
}

Refunds a Single Transaction or Frequent Transaction

Request

Each method has a specific time window during which a refund can be issued. Once this period expires, refunds can no longer be processed via the API for that payment.

Refund Deadlines by Payment Method

Payment MethodMaximum Refund Time
MBWay12 months
Visa & Mastercard12 months
Apple Pay12 months
Google Pay12 months
Samsung Pay12 months
MB SPG references120 days
Other MB referencesNo limit
Direct Debit180 days
Security
accountId and apiKey
Path
idstring(uuid)required

The capture uuid associated with Single or Frequent Transaction

Bodyapplication/jsonrequired

Request body for creating a refund

transaction_keystring<= 50 characters

Your internal key identifying this refund

ibanstring<= 34 characters

Optional - Iban from the bank account

emailstring<= 50 characters

Optional - Email from the bank account holder

phonestring<= 20 characters

Optional - Phone from the bank account holder

account_holderstring<= 40 characters

Optional - Bank account holder name

valuenumber(double)>= 0.01required
revertobject

Reverts refers to the process of reversing a previously made split payment. This means that the amounts that were divided and allocated to different recipients or accounts are returned to the original payer or redistributed as per the new instructions.

curl -i -X POST \
  'https://api.test.easypay.pt/2.0/refund/{id}' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_key": "string",
    "iban": "string",
    "email": "string",
    "phone": "string",
    "account_holder": "string",
    "value": 0.01,
    "revert": {
      "mode": "partial",
      "splits": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      ]
    }
  }'

Responses

Created

Bodyapplication/json
statusstring
Example: "ok"
messagestring
Example: "Your request was successfully created"
idstring(uuid)

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: "25997c28-1902-4f6d-842e-c6050e7d5421"
Response
application/json
{
  "status": "ok",
  "message": "Your request was successfully created",
  "id": "25997c28-1902-4f6d-842e-c6050e7d5421"
}

Shows refund details

Request

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

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

Responses

OK

Bodyapplication/json
idstring(uuid)

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.

statusany

Indicates the current status of the refund. Possible values include:

  • waiting: The payment instruction has been given, but the chosen payment method requires confirmation from an external entity before the status of the operation is finalized.
  • pending: This is the initial state, and it means that the refund is queued.
  • success: The refund has been completed successfully.
  • failed: The refund could not be completed due to an error or issue.

This field provides a clear indication of the current state of the refund, helping users understand its progress and outcome.

Enum"success""pending""failed""waiting"
transaction_keystring

Your internal key identifying this refund.

valuenumber(double)

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

Example: 15.98
account_holderstring

Bank account holder name.

emailstring

The email address of the account holder. This field is used for communication purposes, including sending notifications about the refund stat.

Example: "customer@example.pt"
phonestring

The contact phone number of the account holder, including the country code indicator (e.g., "+351"). This field is used for communication purposes, such as contacting the account holder for verification

Example: "+351912345678"
ibanstring

The International Bank Account Number of the account to which the refund will be sent. This field is used to uniquely identify the recipient's bank account across international borders.

Example: "PT50007950088428437201551"
captureobject

Object with all the details about the capture.

Response
application/json
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "status": "success",
  "transaction_key": "string",
  "value": 15.98,
  "account_holder": "string",
  "email": "customer@example.pt",
  "phone": "+351912345678",
  "iban": "PT50007950088428437201551",
  "capture": {
    "transaction_key": "string",
    "capture_date": "2019-08-24T14:15:22Z",
    "account": { … },
    "status": "delayed",
    "payment_type": "string",
    "payment_id": "d43b87f9-9e28-4802-8eaa-6ee91a40ea71",
    "id": "string",
    "descriptive": "string",
    "value": 10.86,
    "force_3ds": false
  }
}

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