Meo Wallet

Meo Wallet

SEPA DD API

With this API, you can create a debit authorization (mandate) and use this authorization to debit a given amount from the customer bank account.

Pre-requisites

Before using this API, you must create a merchant account here.

Then, create a API Key at the merchant backoffice. Go to the “O Meu Negócio” → “Chaves de API” submenu in the sidebar. This API key needs special permissions to create SEPA DD mandates and payments.

After creating this account and the API key, send the acccount e-mail to the Altice Pay team to be configured.

Authentication

To be able to create SEPA DD mandates and payments, you must provide an “Authorization” header. You can get more details in the Authentication section.

Services

Check description and examples below for each service. These examples use the sandbox environment endpoint.

Production endpoint: https://services.wallet.pt

Add Mandate

This service creates a debit authorization (mandate). The bank account to be debited is defined in the “debtor_dd_info” object. You can pass a request_id to track this request. Check the Idempotency page.

Request POST /api/v2/sepa/mandate
Query params none
Data params Mandate
Returns Mandate
Click here for an example 
curl --location --request POST 'https://services.sandbox.meowallet.pt/api/v2/sepa/mandate' \
--header 'Authorization: WalletPT <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "signature_date": "2023-02-28T00:00:00+0000",
   "contract_number": "1234567890",
   "debtor_dd_info": {
       "name": "PQR Magazines, Lda",
       "bic": "NOTPROVIDED",
       "iban": "PT50016001000038628000945",
       "ultimate_debtor_name": "PQR Import Export"
   }
}'
This request will return a response similar to this: 
{
    "signature_date": "2023-02-28",
    "mandate_id": "35238274752437",
    "status": "CREATED"
}

Get Mandate

This service returns mandate information given a mandate id.

Request GET /api/v2/sepa/mandate/:id
Query params id
Data params none
Returns Mandate
Click here for an example 
curl --location --request GET 'https://services.sandbox.meowallet.pt/api/v2/sepa/mandate/35238274752437' \
--header 'Authorization: WalletPT <api-key>' \
--header 'Content-Type: application/json' \
This request will return a response similar to this: 
{
    "signature_date": "2023-02-28",
    "mandate_id": "35238274752437",
    "status": "CREATED"
}

Payment with Mandate

This service creates a SEPA DD payment. You must indicate the “mandate_id” which you have created before. You can pass a request_id to track this request. Check the Idempotency page.

Request POST /api/v2/payment
Query params none
Data params Operation
Returns Operation
Click here for an example 
curl --location --request POST 'https://services.sandbox.meowallet.pt/api/v2/payment' \
--header 'Authorization: WalletPT <api-key>' \
--header 'Content-Type: application/json' \
--data-raw '{
{
    "method": "SEPA",
    "amount": 10,
    "date": "2023-01-02T12:15:13+0000",
    "currency": "EUR",
    "expires": "2023-03-27T20:15:00+0000",
    "mandate_id":35238274752437
  }
}'
In the example above, a payment of 10 EUR was created. The response will be similar to this one: 
{
    "currency": "EUR",
    "id": "d1241bba-b8ff-11ed-ae0a-a6f51ef36f7b",
    "type": "PAYMENT",
    "channel": "WEBSITE",
    "modified_date": "2023-03-02T13:40:38+0000",
    "collection_date": "2023-03-07T13:40:38",
    "refundable": false,
    "fee": -1,
    "amount": 10,
    "amount_net": 9,
    "merchant": {
        "id": "670064000",
        "name": "Test Wallet",
        "email": "sepatest@telecom.pt"
    },
    "date": "2023-03-02T13:40:38+0000",
    "method": "SEPA",
    "status": "PENDING"
}

The payment status remains PENDING until the bank sends the result. A callback will be sent with the status change.

Delete Mandate

This service deletes a mandate. You can’t delete mandates with pending payments.

Request DELETE /api/v2/sepa/mandate/:id
Query params id
Data params none
Returns Mandate
Click here for an example 
curl --location --request DELETE 'https://services.sandbox.meowallet.pt/api/v2/sepa/mandate/35238274752437' \
--header 'Authorization: WalletPT <api-key>' \
--header 'Content-Type: application/json' \
The response will be like this: 
{
    "signature_date": "2023-02-28",
    "mandate_id": "35238274752437",
    "status": "DELETED"
}

Structures

Mandate

Field Type In/Out Mandatory Description  
signature_date date IO Y Contract signature date (“now” OR transaction date in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format)  
contract_number string I Y Provider → Customer contract identifier  
debtor_dd_info DebtorDDInfo I Y Debtor info mandatory to process SEPA DD transaction  
mandate_id string O N Mandate ID  
status string O N Mandate status  
request_id string IO N UUID used to track the request  

Mandates can have these statuses:

Status Description
CREATED Mandate creation was successful in Wallet’s scope. At this point Creditor Bank still has no information about mandate creation.
PENDING First DD payment using previously created mandate was sent to Sponsor Bank
ACTIVE First DD payment using previously created mandate was successful
DELETED Mandate has been revoked, or it has been determined that it cannot be used to perform further payments

DebtorDDInfo

Field Type In/Out Mandatory Description  
name string I Y Debtor name  
bic string I Y Debtor BIC Code or “NOTPROVIDED”  
iban string I Y Debtor IBAN  
ultimate_debtor_name string I N NOTE: Ultimate debtor name field is mandatory if invoices are being paid by an individual other than the recipient of the service. For SEPA the Debtor is the owner of the bank account from where the funds will be withdrawn to pay the invoice and the Ultimate Debtor is the owner of the contract which the invoice refers to.  

Operation

This table describes the specific and mandatory fields for the SEPA DD payment API. For a full description of the optional fields, check the Structures documentation.

Field Type In/Out Mandatory Description
mandate_id string IO Y mandate_id returned by the create mandate service
amount float IO Y payment amount
date date I N charge date in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format
collection_date date O Y charge date in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format, adjusted to the next business day of the “date” field above. If “date” is omitted, the next business day of the request date will be returned.
method string IO Y payment method - SEPA