# Easypay Payments API

<a href='https://www.easypay.pt/en/legal-terms-and-conditions/' class='item'>Terms conditions and legal terms</a><br><a href='https://www.easypay.pt/en/privacy-and-data-protection-policy/' class='item'>Privacy Policy</a>

Version: 2.0
License: MIT

## Servers

Sandbox
```
https://api.test.easypay.pt/2.0
```

Production
```
https://api.prod.easypay.pt/2.0
```

## Security

### accountId

This is the identification for the Easypay Client Account

Type: apiKey
In: header
Name: AccountId

### apiKey

This is the counter key for the used Account Id

Type: apiKey
In: header
Name: ApiKey

### signatureAuth

RSA signature Base64 generated with algorithm SHA256 using a account strong authentication private Key on the raw body or id.

Type: apiKey
In: header
Name: Signature

### BasicAuth

Type: http
Scheme: basic

## Download OpenAPI description

[Easypay Payments API](https://docs.easypay.pt/_bundle/@l10n/pt/openapi.yaml)

## Single Payment

Create and manage one-time payment transactions

### Lists single payments

 - [GET /single](https://docs.easypay.pt/pt/openapi/single-payment/single-get.md): Full report with all the single payments from your Account

Required scope: single:read

### Create single payment

 - [POST /single](https://docs.easypay.pt/pt/openapi/single-payment/single-post.md): Creates a Single Payment

Required scope: single:create

### Shows single payment details

 - [GET /single/{id}](https://docs.easypay.pt/pt/openapi/single-payment/single-id-get.md): Retrieve a single payment details

Required scope: single:read

### Deletes single payment

 - [DELETE /single/{id}](https://docs.easypay.pt/pt/openapi/single-payment/single-delete.md): 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.

Required scope: single:delete

### Update a single Payment

 - [PATCH /single/{id}](https://docs.easypay.pt/pt/openapi/single-payment/single-update.md): Apply partial modifications to a single payment resource.

Required scope: single:update

## Frequent Payment

Tokenize payment details for variable on-demand charges

### Lists frequent payments

 - [GET /frequent](https://docs.easypay.pt/pt/openapi/frequent-payment/frequent-get.md): Full report with all the frequent payments from your Account Id

Required scope: frequent:read

### Create frequent payment

 - [POST /frequent](https://docs.easypay.pt/pt/openapi/frequent-payment/post_frequent.md): 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


Required scope: frequent:create

### Shows frequent payment details

 - [GET /frequent/{id}](https://docs.easypay.pt/pt/openapi/frequent-payment/frequent-id-get.md): Retrieve a Frequent Payment details

Required scope: frequent:read

### Deletes frequent payment

 - [DELETE /frequent/{id}](https://docs.easypay.pt/pt/openapi/frequent-payment/delete_frequent_id.md): 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.

Required scope: frequent:delete

### Updates frequent payment details

 - [PATCH /frequent/{id}](https://docs.easypay.pt/pt/openapi/frequent-payment/patch_frequent_id.md): Required scope: frequent:update

### Request Authorisation

 - [POST /frequent/authorisation/{id}](https://docs.easypay.pt/pt/openapi/frequent-payment/frequent-authorisation.md): Create a new authorisation on a given Frequent Payment

Required scope: frequent:create

## Subscription Payment

Set up and manage automated recurring payments

### List subscription payments

 - [GET /subscription](https://docs.easypay.pt/pt/openapi/subscription-payment/get_subscription.md): Full report with all the subscriptions payments from your Account Id

Required scope: subscription:read

### Create subscription payment

 - [POST /subscription](https://docs.easypay.pt/pt/openapi/subscription-payment/post_subscription.md): Creates a Subscription.

Required scope: subscription:create

### Shows subscription payment details

 - [GET /subscription/{id}](https://docs.easypay.pt/pt/openapi/subscription-payment/get_subscription_id.md): Retrieves the subscription payment details

Required scope: subscription:read

### Deletes subscription payment

 - [DELETE /subscription/{id}](https://docs.easypay.pt/pt/openapi/subscription-payment/delete_subscription_id.md): Deletes the subscription

Required scope: subscription:delete

### Updates subscription payment details

 - [PATCH /subscription/{id}](https://docs.easypay.pt/pt/openapi/subscription-payment/patch_subscription_id.md): Updates the subscription payment details

Required scope: subscription:update

## Captures

Operations for managing payment captures

### List captures

 - [GET /capture](https://docs.easypay.pt/pt/openapi/captures/paths/~1capture/get.md): Required scope: capture:read

### Captures a Single Auth, Frequent and Frequent Auth

 - [POST /capture/{id}](https://docs.easypay.pt/pt/openapi/captures/paths/~1capture~1%7Bid%7D/post.md): Required scope: capture:create

### Shows capture details

 - [GET /capture/{id}](https://docs.easypay.pt/pt/openapi/captures/paths/~1capture~1%7Bid%7D/get.md): Required scope: capture:read

### Updates the split of a capture

 - [PATCH /capture/{capture-uuid}/splits/{capture-split-uuid}](https://docs.easypay.pt/pt/openapi/captures/patch_capture_capture_uuid_splits_capture_split_uuid.md): Required scope: capture:update

## Authorisations

Operations for managing payment authorisations

### Shows authorisation details

 - [GET /authorisation/{id}](https://docs.easypay.pt/pt/openapi/authorisations/get_authorisation_id.md): Retrieves the details of an authorisation

Required scope: authorisation:read

## Voids

Operations for managing payment voids

### Shows void details

 - [GET /void/{id}](https://docs.easypay.pt/pt/openapi/voids/get_void_id.md): Required scope: void:read

### Voids a Single Auth or Frequent Auth

 - [POST /void/{id}](https://docs.easypay.pt/pt/openapi/voids/post_void_id.md): Required scope: void:create

## Refunds

Operations for managing payment refunds

### List Refunds

 - [GET /refund](https://docs.easypay.pt/pt/openapi/refunds/list-refund.md): Cursor based endpoint to retrieve all account refunds.

Required scope: refund:read

### Refunds a Single Transaction or Frequent Transaction

 - [POST /refund/{id}](https://docs.easypay.pt/pt/openapi/refunds/paths/~1refund~1%7Bid%7D/post.md): 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 Method         | Maximum Refund Time |
|------------------------|---------------------|
| MBWay                  | 12 months           |
| Visa & Mastercard      | 12 months           |
| Apple Pay              | 12 months           |
| Google Pay             | 12 months           |
| Samsung Pay            | 12 months           |
| MB SPG references      | 120 days            |
| Other MB references    | No limit            |
| Direct Debit           | 180 days            |


Required scope: refund:create

### Shows refund details

 - [GET /refund/{id}](https://docs.easypay.pt/pt/openapi/refunds/paths/~1refund~1%7Bid%7D/get.md): Required scope: refund:read

## Chargebacks

Operations for managing chargebacks

### List chargebacks

 - [GET /chargeback](https://docs.easypay.pt/pt/openapi/chargebacks/list-chargeback.md): This endpoint retrieves a list of chargebacks associated with your account. A Chargeback is a mandatory transaction reversal initiated by the consumer's card issuer or bank, usually due to a dispute over a transaction. When a chargeback occurs, the costumer effectively reverses the transaction, resulting in a debit of the disputed amount from the merchant's account. This endpoint allows you to view details of chargebacks, including the reason for the dispute, transaction amount, and status, providing insights into consumer disputes and their impact on your financials.

Required scope: chargeback:read

### Shows chargeback details

 - [GET /chargeback/{id}](https://docs.easypay.pt/pt/openapi/chargebacks/get-chargeback-details.md): This endpoint retrieves the details of a specific chargeback by its unique identifier. A Chargeback is a mandatory transaction reversal initiated by the consumer's card issuer or bank, usually due to a dispute over a transaction.

Required scope: chargeback:read

## Notifications / Webhooks

Configure and manage webhook notifications for payment events

### Generic Notification

 - [POST yourGenericNotificationEndpoint](https://docs.easypay.pt/pt/openapi/notifications-webhooks/paths/yourgenericnotificationendpoint/post.md): We will send you this json in our notifications

### Authorisation Notification

 - [POST yourAuthorisationNotificationEndpoint](https://docs.easypay.pt/pt/openapi/notifications-webhooks/paths/yourauthorisationnotificationendpoint/post.md): We will send you this json in our notification

### Transaction Notification

 - [POST yourNotificationEndpoint](https://docs.easypay.pt/pt/openapi/notifications-webhooks/paths/yournotificationendpoint/post.md): We will send you this json in our notification

## Reports

Access transaction and ledger reports

### Report Ledger

 - [GET /report/ledger](https://docs.easypay.pt/pt/openapi/reports/get_report_ledger.md): The /reports/ledger endpoint provides access to detailed reports of ledger entries within the Easypay reconciliation system. This endpoint retrieves comprehensive financial data for each transaction recorded in the ledger, including captures, refunds, fees, and other financial operations, and it was designed to help users generate precise and relevant financial reports, aiding in effective account reconciliation and financial management.

By using this endpoint, clients can obtain an itemized list of all ledger entries, including relevant financial details such as transaction amounts, fees, taxes, and net transferred amounts. The data returned by this endpoint is ideal for accounting, auditing, and financial analysis purposes, as it ensures transparency and accuracy in financial reporting.

Required scope: report:read

### Report Transactions

 - [GET /report/transactions](https://docs.easypay.pt/pt/openapi/reports/get_report_transactions.md): List your transactions

Required scope: report:read

## Settlements

View settlement details and history

### List settlements

 - [GET /settlement](https://docs.easypay.pt/pt/openapi/settlements/get-settlement.md): Retrieve a list of settlements.

Required scope: settlement:read

### Retrieve a settlement

 - [GET /settlement/{id}](https://docs.easypay.pt/pt/openapi/settlements/get-settlement-id.md): Retrieve a specific settlement by its ID.

Required scope: settlement:read

## Out Payment

Transfer funds from Easypay accounts to SEPA bank accounts

### Lists out payments

 - [GET /out_payment](https://docs.easypay.pt/pt/openapi/out-payment/get_out_payment.md): Full report with all the out payments from your Account Id

Required scope: out_payment:read

### Create out payment

 - [POST /out_payment](https://docs.easypay.pt/pt/openapi/out-payment/post_out_payment.md): Get your strong authentication RSA private key from Easypay Backoffice on menu:Web Services->Configuration API 2.0->Keys.

Required scope: out_payment:create

### Shows out payment details

 - [GET /out_payment/{id}](https://docs.easypay.pt/pt/openapi/out-payment/get_out_payment_id.md): Required scope: out_payment:read

### Deletes out payment

 - [DELETE /out_payment/{id}](https://docs.easypay.pt/pt/openapi/out-payment/delete_out_payment_id.md): If the payment is not processed, it will be cancelled.  Get your strong authentication RSA private key from Easypay Backoffice on menu:  Web Services->Configuration API 2.0->Keys.

Required scope: out_payment:delete

## Config

Configure account URLs for notifications and credit card transactions

### Get Account Config

 - [GET /config](https://docs.easypay.pt/pt/openapi/config/get_config.md): Required scope: config:read

### Patch Account Config

 - [PATCH /config](https://docs.easypay.pt/pt/openapi/config/patch_config.md): This endpoint is useful for setting up the correct URLs for event notifications.
For more details, see Notifications-Webhooks.

Required scope: config:update

## Checkout

Embedded payment form solution for websites

### Shows checkout details

 - [GET /checkout/{id}](https://docs.easypay.pt/pt/openapi/checkout/get_checkout_id.md): Required scope: checkout:read

### Cancels a checkout

 - [DELETE /checkout/{id}](https://docs.easypay.pt/pt/openapi/checkout/delete_checkout_id.md): This cancels the Checkout and deletes the payment associated with it if possible.

Required scope: checkout:delete

### Create Checkout

 - [POST /checkout](https://docs.easypay.pt/pt/openapi/checkout/checkout-post.md): Creates a Checkout Session.

Required scope: checkout:create

## Pay By Link

Generate and manage shareable payment links

### Create a payment link

 - [POST /link](https://docs.easypay.pt/pt/openapi/pay-by-link/post-link.md): Generates a link that takes customers straight to a secure and ready-to-pay checkout.

Required scope: link:create

### List all payment links

 - [GET /link](https://docs.easypay.pt/pt/openapi/pay-by-link/get-link.md): List all the payment links.

Required scope: link:read

### List payment link details

 - [GET /link/{id}](https://docs.easypay.pt/pt/openapi/pay-by-link/get-link-id.md): Lists a payment link with all the details identified by its unique ID.

Required scope: link:read

### Delete Link

 - [DELETE /link/{id}](https://docs.easypay.pt/pt/openapi/pay-by-link/delete-link-id.md): Deletes a payment link identified by its unique ID. Once deleted, the link becomes invalid and can no longer be used. This action is irreversible.

Required scope: link:delete

### Update Link

 - [PATCH /link/{id}](https://docs.easypay.pt/pt/openapi/pay-by-link/patch-link.md): Updates a payment link identified by its unique ID.

Required scope: link:update

## Terminals (coming soon)

Manage terminals (POS devices)

### List terminals

 - [GET /terminal](https://docs.easypay.pt/pt/openapi/terminals-(coming-soon)/get_terminal.md): List all terminals (POS devices) from your account.

Required scope: terminal:read

### Create terminal

 - [POST /terminal](https://docs.easypay.pt/pt/openapi/terminals-(coming-soon)/post_terminal.md): Creates a new terminal (POS device).

Required scope: terminal:create

### Show terminal details

 - [GET /terminal/{id}](https://docs.easypay.pt/pt/openapi/terminals-(coming-soon)/get_terminal_id.md): Retrieves the terminal details.

Required scope: terminal:read

### Delete terminal

 - [DELETE /terminal/{id}](https://docs.easypay.pt/pt/openapi/terminals-(coming-soon)/delete_terminal_id.md): Deletes the terminal.

Required scope: terminal:delete

### Update terminal

 - [PATCH /terminal/{id}](https://docs.easypay.pt/pt/openapi/terminals-(coming-soon)/patch_terminal_id.md): Updates the terminal details.

Required scope: terminal:update

## System

System health check endpoints

### Check connectivity and authentication

 - [GET /system/ping](https://docs.easypay.pt/pt/openapi/system/ping.md): This endpoint allows you to verify connectivity to the API and validate your authentication credentials.
A successful response indicates that the API is reachable and your credentials are valid.


Required scope: system:read