MB WAY

MB WAY is a digital solution created by SIBS to allow a simplified payment flow through your phone. According to SIBS, there are more than 3.4 million people using MB WAY right now and it is the biggest digital payment method in Portugal.

How it works

It works as an async payment method, which means: when you create a payment, we receive a response from SIBS that the payment was created and we should wait for the customer to pay. So, differently from other methods, our transaction stays with a processing status. As soon as the customer does the payment, SIBS system notifies of the execution of the transaction, and the payment is updated to success or failed.

Make a payment

You can see below the simplest example of how to create an MB WAY payment and the generated response:

curl --request POST \
  --url https://gateway.paybyrd.com/api/v2/payment \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \
  --data '
{  
  "type": "OnlineTransfer",
  "isoAmount": 1000,
  "currency": "EUR",
  "orderRef": "ABC123456",
  "brand": "MBWAY",
  "phoneCountryCode": "351",
  "phoneNumber": "969770085",
  "shopper": {
    "firstName": "John",
    "lastName": "Snow",
    "email": "[email protected]",
    "shippingAddress": "Rua da Igreja Velha",
    "shippingPostalCode": "4715-591",
    "shippingCity": "Braga",    
    "shippingCountry": "PRT",
    "billingAddress": "Rua da Igreja Velha",
    "billingPostalCode": "4715-591",
    "billingCity": "Braga",    
    "billingCountry": "PRT"
  }
}'

{
    "phoneCountryCode": "351",
    "phoneNumber": "969770085",
    "mbWay": {
        "phoneCountryCode": 31,
        "phoneNumber": "625413019",
        "entityCode": "53939"
    },
    "type": "OnlineTransfer",
    "currency": "EUR",
    "orderRef": "ABC123456",
    "brand": "MBWAY",
    "paymentMethod": "mbway",
    "shopper": {
        "email": "[email protected]",
        "firstName": "John",
        "lastName": "Snow",
        "shippingAddress": "Rua da Igreja Velha",
        "shippingPostalCode": "4715-591",
        "shippingCity": "Braga",
        "shippingCountry": "PRT",
        "billingAddress": "Rua da Igreja Velha",
        "billingPostalCode": "4715-591",
        "billingCity": "Braga",    
        "billingCountry": "PRT"
    },
    "code": "BYRD201",
    "description": "Payment being processed. Waiting for shopper",
    "status": "Processing",
    "requestId": "a325f758-edc1-4a4e-ba84-b630b0528217",
    "expiresAt": "2024-08-01T08:40:21.397267Z",
    "externalTransactionIdentifier": "s2NaTwRc28ujX3p8hpph",
    "acceptTokenization": false,
    "tokenType": "None",
    "transactionId": "81ebf619-e9e1-49ca-aa9d-5c8cf06a41c6",
    "amount": "10.00",
    "isoAmount": 1000
}

See the full API reference here.

Required Fields

Field	Description
Type	"OnlineTransfer"
IsoAmount	Total purchase amount in "ISO" format (https://en.wikipedia.org/wiki/ISO_4217).
Currency	Three letter "ISO" currency code (https://en.wikipedia.org/wiki/ISO_4217).
OrderRef	Merchant's order reference
Brand	"MBWAY"
phoneCountryCode	MBWay phone country code without symbols e.g. "351"
phoneNumber	MBWay phone number e.g. "969770085"

In order to know whether the transaction was accepted or not, you must check the code field. For successful scenarios, the expected code is BYRD201. You can find here the list of all possible codes

Notification

When the payment is finished by the user, Paybyrd will send a notification to the webhook URL defined in the Merchant's account configuration.

In your server, you will receive a request from Paybyrd with the transactionId which the status has changed. We expect a HTTP success status response from your server, which can be 200 OK, 201 CREATED, 202 ACCEPTED, otherwise Paybyrd will consider that your server was not able to handle the notification.

This is a sample payload of the hook sent by us:

{
    "webhookId": "1642449226",
    "contextType": "event:paymentStatusChanged",
    "transactionId": "81ebf619-e9e1-49ca-aa9d-5c8cf06a41c6"
}

Once the hook is received, you may query the transaction in order to obtain detailed information about its status.

Query payment result

You can find below an example of how to query a transaction and the response obtained:

curl --request GET \
  --url https://gateway.paybyrd.com/api/v2/transactions/{transactionId} \
  --header 'Accept: application/json'
  --header 'x-api-key: 5E37D19C-F99C-445F-8B77-1463EFC66C7B' \

{
    "referencedTransactions": [],
    "code":"BYRD200",
    "description":"Operation successfully completed",
    "currency": "EUR",
    "orderRef": "ABC123457",
    "acquirer": "SIBS",
    "brand": "MBWAY",
    "paymentMethod": "Wallet",
    "operationType": "Payment",
    "status":"Success",
    "fingerPrint": "23e13f9c-4527-4329-a2c2-0f098e759113",
    "createdDate": "2024-08-01T09:14:16Z",
    "transactionDate": "2024-08-01T09:14:16Z",
    "initiatedFrom": "Server",
    "subscriptionGuid": "9d16eaee-83f4-4452-8b2e-1a96121fb81c",
    "personId": 12,
    "expiresAt": "2024-08-01T08:40:21Z",
    "attempt": 0,
    "index": 1,
    "externalTransactionIdentifier": "s2sNZ6sgheEGDs4GyZTN",
    "externalCustomIdentifier": "973ade90794e4aa0b8e0c359249606e4",
    "acquirerResponseCode": "000",
    "mbWay": {
        "entityCode": "53939",
        "phoneCountryCode": 351,
        "phoneNumber": "969770085"
    },
    "acceptTokenization": false,
    "cardInfoComposition": {},
    "transactionId": "81ebf619-e9e1-49ca-aa9d-5c8cf06a41c6",
    "amount": "10.00",
    "isoAmount": 1000
}

{
    "referencedTransactions": [],
    "code":"BYRD205",
    "description":"Operation rejected",
    "currency": "EUR",
    "orderRef": "ABC123457",
    "acquirer": "SIBS",
    "brand": "MBWAY",
    "paymentMethod": "Wallet",
    "operationType": "Payment",
    "status":"Denied",
    "fingerPrint": "23e13f9c-4527-4329-a2c2-0f098e759113",
    "createdDate": "2024-08-01T09:14:16Z",
    "transactionDate": "2024-08-01T09:14:16Z",
    "initiatedFrom": "Server",
    "subscriptionGuid": "9d16eaee-83f4-4452-8b2e-1a96121fb81c",
    "personId": 12,
    "expiresAt": "2024-08-01T08:40:21Z",
    "attempt": 0,
    "index": 1,
    "externalTransactionIdentifier": "s2sNZ6sgheEGDs4GyZTN",
    "externalCustomIdentifier": "973ade90794e4aa0b8e0c359249606e4",
    "acquirerResponseCode": "000",
    "mbWay": {
        "entityCode": "53939",
        "phoneCountryCode": 351,
        "phoneNumber": "969770085"
    },
    "acceptTokenization": false,
    "cardInfoComposition": {},
    "transactionId": "81ebf619-e9e1-49ca-aa9d-5c8cf06a41c6",
    "amount": "10.00",
    "isoAmount": 1000
}

See the full API reference here.

The status indicates whether the transaction was successfully processed or not.