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

List captures

Request

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/capture?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(metadata-cursor)

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

dataArray of objects

The Capture object contains all the necessary information for executing a fund capture action. It defines how and where the funds should be routed upon capturing a transaction. This object is essential for finalizing transactions and ensuring the correct allocation of funds.

Response
application/json
{
  "metadata": {
    "next_cursor": "lL_j7ilk7rc",
    "count": 10
  },
  "data": [
    { … }
  ]
}

Captures a Single Auth, Frequent and Frequent Auth

Request

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

Bodyapplication/jsonrequired

Created

transaction_keystring<= 50 characters

Your internal key identifying this capture

Example: "key example"
capture_datestring(date)

The date when the action should be executed. This field specifies the exact day for capturing the transaction, formatted as "YYYY-MM-DD" (e.g., "2024-06-30"). It is optional and defaults to the current date if not specified.

Example: "2022-11-11"
accountobject

For multi-account clients.

splitsArray of objects

Used in split payments.

force_3dsboolean

Whether or not you want to force the 3DS authentication on Credit Cards (used only on Frequent capture without authorisation).

Default false
descriptivestring<= 255 characters

This will appear in the bank statement/mbway application.

Example: "descriptive example"
valuenumber(double)>= 0.5

Value will be rounded to 2 decimals.

Example: 20.55
mbway_sdkobjectDeprecated
curl -i -X POST \
  'https://api.test.easypay.pt/2.0/capture/{id}' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_key": "key example",
    "capture_date": "2022-11-11",
    "account": {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
    },
    "splits": [
      {
        "split_key": "example key",
        "split_descriptive": "string",
        "value": 10.56,
        "account": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        },
        "margin_value": 0.01,
        "margin_account": {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08"
        }
      }
    ],
    "mbway_sdk": {
      "purchase_token": "string",
      "initial_timestamp": "string",
      "merchant_operation_id": "string",
      "payload": "string"
    },
    "force_3ds": false,
    "descriptive": "descriptive example",
    "value": 20.55
  }'

Responses

Created

Bodyapplication/json
statusstring
Example: "ok"
messageArray of strings
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: "677dbec9-ec19-4a78-9e08-3d2901c7a32b"
Response
application/json
{
  "status": "ok",
  "message": [
    "Your request was successfully created"
  ],
  "id": "677dbec9-ec19-4a78-9e08-3d2901c7a32b"
}

Shows capture details

Request

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

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

Responses

OK

Bodyapplication/json
transaction_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.

capture_datestring

The date when the action should be executed. This field specifies the exact day for capturing the transaction, formatted as "YYYY-MM-DD" (e.g., "2024-06-30"). It is optional and defaults to the current date if not specified.

Example: "2025-07-10"
accountobject

An object within the capture request that specifies the details of the account to which the funds should be routed, different from the initially requested account. This ensures that the captured funds are directed to the correct destination as per the specific routing requirements.

descriptivestring

A text field that describes the transaction as it will appear on the end user's account statement. This is typically used to provide clear, recognizable information about the payment, such as "Payment of Invoice Nº 1982652" or "Ticket for Queen".

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"). The value must be greater than or equal to 0.5.

Example: 38.98
statusany

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

  • delayed: The capture attempt is scheduled for a future date and does not require further user interaction due to prior consent (e.g., authorization or frequent).
  • 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: The capture is pending user completion.
  • success: The capture has been completed successfully.
  • failed: The capture could not be completed due to an error or issue.
  • refunded: The capture has been refunded.

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

Enum"delayed""waiting""success""pending""failed""refunded"
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: "c6056234-a3f9-42de-b944-3ed793fcb6bb"
payment_typeany

Specifies the type of payment processed. Possible values include:

  • Single: A one-time payment transaction.
  • Frequent: A payment that occurs regularly but is not part of a subscription (e.g., recurring manual payments).
  • Subscription: A recurring payment that is part of a subscription plan, automatically processed at regular intervals. This field helps to categorize and manage different payment methods based on their frequency and nature.
Enum"single""frequent""subscription"
payment_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.

force_3dsboolean

A boolean field indicating whether to enforce 3D Secure (3DS) authentication for the transaction. If set to true, 3DS authentication will be required, adding an additional layer of security by verifying the cardholder's identity during the transaction process. If set to false, 3DS authentication will not be enforced. This field helps enhance security and reduce fraud in online payments.

refundsobject

The Refund object contains information required to process a refund. For payment methods that do not support direct refunds, additional fields are required to facilitate a fallback to a bank transfer. This ensures that the customer receives their refund even when the original payment method does not facilitate refunds.

splitsArray of objects
errorobject

Represents the reason why an operation failed. It includes a human-readable message describing the issue, which can help diagnose and resolve the failure.

Response
application/json
{
  "transaction_key": "string",
  "capture_date": "2025-07-10",
  "account": {
    "id": "c0151524-79e6-437a-a549-2ddd7c95e245"
  },
  "descriptive": "string",
  "value": 38.98,
  "status": "delayed",
  "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
  "payment_type": "single",
  "payment_id": "d43b87f9-9e28-4802-8eaa-6ee91a40ea71",
  "force_3ds": true,
  "refunds": {
    "id": "c0151524-79e6-437a-a549-2ddd7c95e245",
    "status": "waiting",
    "transaction_key": "example key",
    "value": 0.1,
    "iban": "string",
    "email": "string",
    "phone": "string",
    "account_holder": "string"
  },
  "splits": [
    { … }
  ],
  "error": {
    "message": "string"
  }
}

Updates the split of a capture

Request

Security
accountId and apiKey
Path
capture-uuidstring(uuid)required

Capture Identification

capture-split-uuidstring(uuid)required

Capture Split Identification

Bodyapplication/json

Payment configuration object to generate a payment

clearing_datestring(date)

The new date for the split to be cleared.
This field must be in the future and no longer than 2 years from today.

Example: "2006-01-02"
curl -i -X PATCH \
  'https://api.test.easypay.pt/2.0/capture/{capture-uuid}/splits/{capture-split-uuid}' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "clearing_date": "2006-01-02"
  }'

Responses

OK

Bodyapplication/json
statusstring
Example: "ok"
messageArray of strings
Example: ["Your request was successfully created"]
Response
application/json
{
  "status": "ok",
  "message": [
    "Your request was successfully created"
  ]
}

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