Meo Wallet

Meo Wallet

Structures

In this section you find the reference for the structures used by the MEO Wallet API calls.

These structures are used across all methods and define the name, type, input or output, requirements and description for each field.

Callback

Field Type In/Out Mandatory Description
amount float O Y amount received
create_date date O Y transaction date in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format
currency string O Y amount currency in ISO 4217
event string O Y transaction event being notified
ext_customerid string O Y merchant customer reference
ext_invoiceid string O Y merchant reference for this payment
ext_email string O Y merchant store email
mb_entity string O N MB entity
mb_ref string O N MB reference generated for this payment
method string O Y payment method used on the transaction
modified_date date O Y transaction modified date in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format
operation_id string O Y operation ID the callback referers to
operation_status string O Y status of the transaction after this event
user integer O Y user which performed operation
error string O N optional error description
type string O N for checkout authorizations: ‘AUTH’, ‘CAPTURE’ or ‘RELEASE’
for SEPA direct debits: ‘PAYMENT’ or ‘REFUND_REVERSAL’
checkout_id string O N returned in checkout authorizations
mandate_id string O N mandate id used for SEPA direct debits
mandate_status string O N mandate status for SEPA direct debits: ‘CREATED’, ‘ACTIVE’, ‘PENDING’ or ‘DELETED’
dd_status_code string O N SEPA transaction status
parent_operation_id string O N the id of the original operation being refunded for SEPA direct debits, in case type is ‘REFUND_REVERSAL’

Checkout

Field Type In/Out Mandatory Description
exclude String array I N list of payment methods to be excluded (“MB”, “CC”)
id string O Y checkout identifier
payment Payment object IO N payment resulting from this checkout
authorization Authorization object IO N authorization resulting from this checkout
subscription Subscription object IO N subscription resulting from this checkout
required_fields RequiredFields I N flags to control the required fields on the checkout page
url_cancel url I Y URL where the user will be redirected after a failed checkout
url_confirm url I Y URL where the user will be redirected after a successful checkout
default_method string I N payment method that will be selected by default on the Checkout page

RequiredFields

Field Type In/Out Mandatory Description
email bool I N if true this checkout will request the customer email
name bool I N if true this checkout will request the customer name
phone bool I N if true this checkout will request phone number
shipping bool I N if true this checkout will request shipping address

CreditCard

Field Type In/Out Mandatory Description
expired boolean O Y card is no longer valid
last4 string O Y last four digits of the card number
token string O Y UID representing the card in MEO Wallet - for reference only
type string O Y card brand
valdate string O Y card expiration date as MM/YYYY

Error

Field Type Description
code integer Error code
link string Link to know more about the error
message string Short description
reason string Reason for humans
tid string error guid - always include this when contacting support

For more information on errors see error handling.

MB

Field Type In/Out Mandatory Description
entity string O Y MB entity
ref string O Y MB reference

Merchant

Field Type In/Out Mandatory Description
email string O Y merchant email
id integer O Y internal merchant id
name string O Y merchant comercial name

Operation

The Operation structure describes monetary operations on your account. Currently it can describe one of seven different operation types, indicated by the type field. The table describes the possible fields and indicates on which types (Payment, Walletfunds, Usertransfer, Refund, Auth, Capture, RELease) they are present.

Note: Capture behaves like a Payment. Authorization and RELease are used to retain or release money related with an authorization.

Field Type In/Out Mandatory A/C/P/REL W U R Description
amount float I Y Y Y Y Y payment amount
amount_net float O Y Y Y Y Y amount after fees
card CreditCard O N Y Y N Y credit card data used in this transaction (if applicable)
client Client Data IO N Y N N N inputs the client and shipping data known by the merchant and outputs it augmented with the data collected from user
currency string I Y Y Y Y Y amount currency in ISO 4217
date date O Y Y Y Y Y transaction create date in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format
destination User O N N N Y N user receiving a transfer
ext_customerid string I N Y N N Y merchant customer reference (max 45 chars)
ext_employee string I N Y N N Y employee name (max 45 chars)
ext_invoiceid string I N Y N N Y merchant reference for this payment (max 45 chars)
ext_email string I N Y N N Y Customer email (max 100 chars)
fee float O Y Y Y Y Y transaction fee
id string O Y Y Y Y Y operation identifier
ipaddress string IO N Y N N Y customer IP address (can be set as «In» parameter in the payment API)
items PaymentItem Array I N Y N N Y items to be displayed on the checkout process
mb MB O N Y Y N Y Multibanco reference used in this transaction (if applicable)
merchant Merchant O N Y N N Y transaction recipient
method string IO Y Y Y Y Y payment method used for this transaction - see below
modified_date date O Y Y Y Y Y transaction modified date in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format
notes string O N Y Y Y Y notes
origin User O N N N Y N originating user for transfers
parent string O N N N N Y parent operation ID for chained transactions like refunds
refundable boolean O Y Y Y Y Y is this operation refundable?
status string O Y Y Y Y Y transaction status - see below
store integer I N Y N N N store ID (from the merchant backoffice)
type string IO Y Y Y Y Y transaction type - see below
mbway MBWayPayment IO N Y N N N Mandatory if payment method = MBWAY
callback string IO N Y N N N Used in MBWAY payments
expires date IO N Y N N N expiration date of the payment in ISO 8601 YYYY-MM-DDThh:mm:ssTZD format. If this field is not provided your payment will be valid for 1000 minutes
instant boolean IO N Y N N N Useful if you have the MB method available in your checkout page. Set this field to true to create an instant reference. You must use this field with the expires field described above (minimum duration = 1 hour)
request_id string IO N Y N N Y UUID used to track the request

The status field may be one of the following

Status Description
COMPLETED Operation is completed with success
FAIL Operation has failed, user canceled it or there aren’t funds available
NEW Operation as not been started yet
PENDING Operation is pending of some external event (such as user action)

The type field may be one of the following

Type Description
PAYMENT A payment results from a checkout process. It includes the information originally passed on checkout creation and the payment information resulting from the user actions.
REFUND A refund of a refundable operation, links to original operation
USERTRANSFER A transfer of funds between MEO Wallet users
WALLETFUNDS A transfer of funds from outside MEO Wallet into a user’s wallet
AUTH An authorization given to a configured amount to be captured or released later
CAPTURE A capture results from a checkout authorization process. It includes the information originally passed on checkout creation and the authorization information resulting from the user actions
RELEASE Cancels a previously authorized amount. If amount is omited, cancels the original amount defined at the authorization checkout process

The method field may be one of the following

Method Description
CC Credit Card
MB Multibanco
MBWAY MB WAY
PAYPAL PayPal
WALLET MEO Wallet balance
GPAY Google Pay - used only as input flag to exclude or define Google Pay as default method in the checkout
APAY Apple Pay - used only as input flag to exclude or define Apple Pay as default method in the checkout

The dd_status_code field can take the following values

Code Description
0000 Payment or Reversal Success
1999 Error due to generic data provided through API
1989 Error due to bank account details provided through API
1979 Error due to bank account details (Name) provided through API
1969 Error due to bank account details (IBAN) provided through API
2999 Error due to Debtors bank
3999 Unrecoverable error due to an external event (usually performed by the debtor) or temporary error. May se solved by retrying the payment operation with the same payment data
4999 Unrecoverable error that requires executing more complex/time consuming procedure and hence cannot be solved by retrying the payment operation with the same data
5999 Refund Success
5989 Refund or Reversal Failed

PaymentItem

A PaymentItem describes a line item on an invoice. It can be provided to produce a more helpful MEO Wallet checkout page or for later API lookup.

Field Type In/Out Mandatory Description Validations
amount float I N amount to charge min=0.001,max=99999.990
descr string I N item description maxlen=255
name string I Y item name maxlen=500
qt integer I Y quantity min=1, max=2147483648
ref string I N item inventory reference maxlen=100

RefundRequest

Field Type In/Out Mandatory Description Validations
amount float I N amount to refund min=0.01
ext_customerid string I N Merchant customer ID (for reference) maxlen=255
ext_email string I N Customer email (for reference) maxlen=255
ext_invoiceid string I N Merchant transaction reference maxlen=255
notes string I N Merchant notes maxlen=255

Client Data

Field Type In/Out Mandatory Description Validations
address address object IO N described below maxlen=255
email string IO N ex. foo@bar.com maxlen=250
name string IO N payer supplied name maxlen=100
nif string O N buyers fiscal number maxlen=255
phone string IO N in E.164 format ex. 351961234567 Msisdn

Address

Field Type In/Out Mandatory Description Validations
address string IO N street address including door number minlen=2, maxlen=255
city string IO N ex. Lisboa maxlen=100
country string IO N “PT” iso-3166-alpha2
postalcode string IO N Postal code (ex. 1000-100) maxlen=15

User

Describes a MEO Wallet current or future user.

Field Type In/Out Mandatory Description
email string O Y  
name string O N  

MBWayPayment

A MBWayPayment object describes the structure which contains details to be provided for a MB WAY payment. At this moment, MEO Wallet only supports payments providing customer mobile phone number.

Field Type In/Out Mandatory Description
phone string IO Y Portuguese mobile numbers: don’t send country calling code

ReferenceRequest

Describes the request for creating a MB reference for recurring payments

Field Type In/Out Mandatory Description Validations  
currency string I N amount currency ISO 4217  
expires string I N date ISO 8601 YYYY-MM-DDThh:mm:ssTZD format  
ext_customerid string I N Merchant customer ID (for reference) maxlen=45  
ext_email string I N Customer email (for reference) maxlen=100  
ext_invoiceid string I N Merchant transaction reference maxlen=45  
max_amount float I Y maximum payable amount min=0.2  
min_amount float I Y minimim payment amount min=0.2  
op_type string I N transaction type see below  

The op_type field may be one of the following:

Type Description
PAYMENT Reference that can be paid multiple times

DeleteReferenceRequest

Describes the request for deleting a recurring payment MB reference.

Field Type In/Out Mandatory Description
entity string I Y MB entity
reference string I Y MB reference

CaptureRequest

Field Type In/Out Mandatory Description Validations
amount float I N amount to capture min=0.2
ext_customerid string I N Merchant customer ID (for reference maxlen=45
ext_email string I N Customer email (for reference) maxlen=100
ext_invoiceid string I N Merchant transaction reference maxlen=45
ext_employee string I N employee name (max 45 chars) maxlen=45
notes string I N Merchant notes maxlen=255

ReleaseRequest

Field Type In/Out Mandatory Description  
amount float I N amount to capture min=0.2
ext_customerid string I N Merchant customer ID (for reference maxlen=45
ext_email string I N Customer email (for reference) maxlen=100
ext_invoiceid string I N Merchant transaction reference maxlen=45
ext_employee string I N employee name (max 45 chars) maxlen=45
notes string I N Merchant notes maxlen=255