Skip to content
/
Create single payment

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

Lists single payments

Request

Full report with all the single payments from your Account

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
typestring

Filter by type of financial operation being performed. Possible values are "Sale" (a complete transaction where funds are immediately captured) or "Authorisation" (a temporary hold on funds pending a future capture).

Enum"sale""authorisation"
Example: type=sale
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
valuenumber(double)

Filter records by the exact transaction amount.

Example: value=10.32
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/single?page=1&records_per_page=20&type=sale&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&value=10.32&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)

Metadata object containing pagination and result information for list responses.

dataArray of objects(single)
Response
application/json
{
  "meta": {
    "page": { … },
    "records": { … },
    "links": { … }
  },
  "data": [
    { … }
  ]
}

Create single payment

Request

Creates a Single Payment

Security
accountId and apiKey
Bodyapplication/jsonrequired

Configuration object to generate a single payment

typestring

Specifies the type of financial operation being performed.

TYPEDESCRIPTION
salea complete transaction where funds are immediately captured.
authorisationa temporary hold on funds pending a future capture.
Enum"sale""authorisation"
captureobject(create-capture)

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. Object required when the operation type is Sale.

currencystring

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

Example: "EUR"
valuenumber(double)[ 0.5 .. 999999.99 ]required

The monetary amount for the transaction. This field specifies the value of the payment in the designated currency. It must be a positive decimal number representing the exact amount to be processed.

Example: 17.5
methodstringrequired

Enumerates the possible values for the payment method used in the transaction. This field helps to identify the selected payment method. Possible values include:

METHODDESCRIPTION
CCCredit Card
VIDigital IBAN
DDDirect Debit
MBMultibanco
MBWMBWay
GPGoogle Pay*
APApple Pay*
SWSamsung Wallet*

*payment only available through checkout yet

Enum"CC""VI""DD""MB""MBW""GP""AP""SW"
keystring<= 50 characters

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: "Payment of Invoice Nº 1982652"
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.

multibancoobject

An object that holds the details specific to a Multibanco transaction.

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.

notificationobject(notification)

Notification settings for payment methods.

expiration_timestringDeprecated

The last possible time to make the payment. Applicable in Multibanco payments. This field is deprecated, use multibanco.expiration_time instead.

Example: "2017-12-12 16:05"
curl -i -X POST \
  https://api.test.easypay.pt/2.0/single \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "customer": {
      "name": "Customer Example",
      "email": "customer@example.com",
      "phone": "911234567",
      "phone_indicative": "+351",
      "key": "customer Key Example",
      "language": "EN"
    },
    "key": "merchant identification key Example",
    "value": 15.5,
    "method": "MB",
    "capture": {
      "descriptive": "transaction descriptive Example",
      "transaction_key": "transaction key Example"
    },
    "notification": {
      "customer_method_instructions_email": true
    }
  }'

Responses

Created

Bodyapplication/json
statusstring(response-status)

Indicates the overall status of the API response. 'ok' means the request was successful, 'error' indicates there was a problem.

Enum"ok""error"
messageArray of strings(response-message)

An array of messages providing details about the response status. These messages give additional context about the operation result.

idstring(uuid)
Example: "c6056234-a3f9-42de-b944-3ed793fcb6bb"
methodobject(method-on-post-response)

Method information returned in POST responses after creating a payment

customerobject
captureobject
multibancoobject(response-multibanco)

An object that holds the details specific to a Multibanco transaction response.

notificationobject(notification)

Notification settings for payment methods.

Response
application/json
{
  "status": "ok",
  "message": [
    "Your request was successfully created"
  ],
  "id": "ed7f8dac-0ea2-4846-8433-f5f8b0e70ed7",
  "method": {
    "type": "dd",
    "status": "pending",
    "entity": "21098",
    "reference": "503564027",
    "sdd_mandate": { … }
  },
  "customer": {
    "id": "2544ce48-ccec-465e-9722-d42ccf0aa640"
  },
  "capture": {
    "id": "c6101a8b-b8c6-44a7-b128-bef8888e14d7"
  }
}

Shows single payment details

Request

Retrieve a single payment details

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

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

Responses

OK

Bodyapplication/json
idstring
Example: "c6056234-a3f9-42de-b944-3ed793fcb6bb"
created_atstring
capturesArray of objects(single-capture-full)
keystring
Example: "Payment of Invoice Nº 1982652"
descriptivestring(descriptive)<= 255 characters

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)(value)[ 0.5 .. 999999.99 ]

The monetary amount for the transaction. This field specifies the value of the payment in the designated currency. It must be a positive decimal number representing the exact amount to be processed.

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

methodobject(single-detail-method-response)
paid_atstring
transactionsArray of objects(payment-transactions)
payment_statusstring(single-payment-status)

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

"pending": The payment is awaiting processing. "paid": The payment has been completed successfully. "authorised": The payment has been authorized but not yet captured. "error": An error occurred during the payment process. "deleted": The payment has been deleted. "failed": The payment attempt failed. "active": The payment is currently active. "voided": The payment has been voided.

Enum"pending""paid""authorised""error""deleted""failed""active"
multibancoobject(response-multibanco)

An object that holds the details specific to a Multibanco transaction response.

notificationobject(notification)

Notification settings for payment methods.

Response
application/json
{
  "id": "c6056234-a3f9-42de-b944-3ed793fcb6bb",
  "created_at": "string",
  "captures": [
    { … }
  ],
  "key": "Payment of Invoice Nº 1982652",
  "descriptive": "Payment of Invoice Nº 1982652",
  "value": 17.5,
  "expiration_time": "string",
  "currency": "EUR",
  "customer": {
    "id": "649e88cf-0b78-4c36-8f99-33f5ebb812a1",
    "name": "John Doe",
    "email": "john.doe@example.com",
    "phone": "911234567",
    "phone_indicative": "+351",
    "fiscal_number": "PT123456789",
    "key": "customer Key Example",
    "language": "PT"
  },
  "method": {
    "type": "CC",
    "status": "active",
    "sdd_mandate": { … },
    "card_type": "VISA",
    "last_four": "1234",
    "expiration_date": "string",
    "url": "https://cc.easypay.pt/v3/public/card-details/cec55ab6-bda3-4ab3-af22-04d2ad2c046a",
    "alias": "string",
    "entity": "11683",
    "reference": "665876931",
    "iban": "PT50002700000001234567833"
  },
  "paid_at": "string",
  "transactions": [
    { … }
  ],
  "payment_status": "paid",
  "multibanco": {
    "expiration_time": "2025-09-28T12:41:08Z",
    "start_time": "2025-08-26T12:41:09Z",
    "product": "SPG"
  },
  "notification": {
    "customer_method_instructions_email": true
  }
}

Deletes single payment

Request

This endpoint allows for the deletion of a single payment identified by its unique ID. The DELETE operation performs the following actions based on the payment method:

  • MBWay and Credit Cards: Voids all authorizations.
  • Multibanco: Cancels the Multibanco Reference.
  • Direct Debit: Cancels the Direct Debit if the request is made before the cutoff hour(18:00 Europe/Lisbon).

This operation ensures that all associated authorizations and references are properly handled and terminated according to the specified payment method.

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

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

Responses

No Content

Response
No content

Update a single Payment

Request

Apply partial modifications to a single payment resource.

Security
accountId and apiKey
Path
idstring(uuid)required

Resource Identification

Bodyapplication/json
currencystring

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

Example: "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(key)<= 255 characters

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.

sdd_mandateobject(updatable-sdd-mandate)

The SDD Mandate object contains the necessary fields to update a SEPA Direct Debit mandate. All fields are optional for update operations.

expiration_timestringDeprecated
curl -i -X PATCH \
  'https://api.test.easypay.pt/2.0/single/{id}' \
  -H 'AccountId: 2b0f63e2-9fb5-4e52-aca0-b4bf0339bbe6' \
  -H 'ApiKey: eae4aa59-8e5b-4ec2-887d-b02768481a92' \
  -H 'Content-Type: application/json' \
  -d '{
    "expiration_time": "string",
    "currency": "EUR",
    "customer": {
      "name": "Jonh Doe",
      "email": "customer@example.com",
      "phone": "962496235",
      "phone_indicative": "351",
      "fiscal_number": "PT277712580",
      "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
      "language": "PT"
    },
    "key": "01J1PKR2RPHJNJQGFWGDYXY0KM",
    "sdd_mandate": {
      "iban": "PT50002700000001234567833",
      "key": "Sdd mandate Key Example",
      "name": "John Doe",
      "email": "john.doe@example.com",
      "phone": "911234567",
      "account_holder": "John Doe"
    }
  }'

Responses

OK

Bodyapplication/json
idstring(identifier)
messageArray of strings(response-message)

An array of messages providing details about the response status. These messages give additional context about the operation result.

statusstring(response-status)

Indicates the overall status of the API response. 'ok' means the request was successful, 'error' indicates there was a problem.

Enum"ok""error"
methodobject(single-edit-method-response)
customerobject
Response
application/json
{
  "status": "ok",
  "message": [
    "Your request was successfully created"
  ],
  "id": "d4851c0a-66e2-4b34-9587-1e453ddcc650",
  "method": {
    "type": "CC",
    "status": "pending",
    "url": "https://cc.easypay.pt/v3/public/card-details/d4851c0a-66e2-4b34-9587-1e453ddcc650"
  },
  "customer": {
    "id": "156de567-b17d-4591-a154-442c873b76c7"
  }
}

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

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