Multicaixa Express

Multicaixa Express is an interbank mobile channel that allows users to add multiple Multicaixa cards to the Multicaixa Express mobile app.

With this payment method, the customer only needs their mobile phone to make a payment. It is fast and easy, and the customer authorizes payments within 90 seconds.

It is an ideal payment method for mobile applications and websites, minimizes shopping cart abandonment, and increases conversion rates.

🚧
Multicaixa Express is only available in Angola.

How it works

It operates as an asynchronous payment method, meaning that when a payment is created, we receive a response from the Multicaixa Express system confirming its creation, and we must wait for the customer to complete the payment. Unlike other payment methods, the transaction remains in a "processing" status. Once the customer makes the payment, the Multicaixa Express system notifies us of the transaction's outcome, updating the payment status to either "successful" or "failed".

Create order

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

curl --request POST \
  --url https://gateway.paybyrd.com/api/v2/orders \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: {{YOUR_API_KEY_HERE}}' \
  --data '
{
    "orderRef": "MULTICAIXAEXPRESS",
    "isoAmount": 30010,
    "currency": "EUR",
    "marketId": "PT",
    "orderOptions": {
        "culture": "pt-PT"
    },
    "paymentOptions": {
        "allowedPaymentMethods": [
            "MULTICAIXAEXPRESS"
        ]
    },
    "shopper": {
        "firstName": "Peter",
        "lastName": "Parker",
        "email": "[email protected]"
    }
}'

{
   "orderDate":"2025-01-31T13:20:29Z",
   "status":"created",
   "checkoutUrl":"https://link-s.paybyrd.com/chk_ndstWcrVj",
   "tags":0,
   "index":1,
   "transactions":[
      
   ],
   "orderId":"708e43s0-240b-4918-8008-3a0d331958b5",
   "amount":"300.10",
   "currency":"EUR",
   "orderRef":"MULTICAIXAEXPRESS",
   "shopper":{
      "customReference":"shp_G29J1XTQNfduQp5l",
      "shopperId":"2d7b078f-d75f-4d29-813a-2f11dd3a24d5",
      "email":"[email protected]",
      "firstName":"Peter",
      "lastName":"Parker",
      "shippingType":"Undefined",
      "firstPurchaseDate":"2025-01-31T13:20:29.7393408+00:00",
      "lastPurchaseDate":"2025-01-31T13:20:29.7393408+00:00"
   },
   "orderOptions":{
      "redirectUrl":"https://paybyrd.com",
      "culture":"pt-PT",
      "sendBy":[
         
      ]
   },
   "paymentOptions":{
      "useSimulated":true,
      "cardOptions":{
         "isPreAuth":false,
         "isDccEnabled":false
      },
      "tokenOptions":{
         "tokenizationMethod":"none"
      },
      "allowedPaymentMethods":[
         "MULTICAIXAEXPRESS"
      ]
   },
   "terminalOptions":{
      "notifyChanges":false
   },
   "marketId":"PT",
   "code":"BYRD200",
   "description":"Operation successfully completed",
   "checkoutKey":"eyJPcmRlcklkIjoiNzA4ZTYzYTAtMjQwYi00OTE4LTgwMDgtM2EwZDMzMTk1OGI1IiwiT3JkZXJSZWYiOiJNVUxUSUNBSVhBRVhQUkVTUyIsIlBlcnNvbklkIjo4MDYsIkxpdmUiOmZhbHNlLCJFbnRpdHlJZCI6IjcwOGU2M2EwLTI0MGItNDkxOC04MDA4LTNhMGQzMzE5NThiNSIsIkFtb3VudCI6IjMwMC4xMCIsIkN1cnJlbmN5IjoiRVVSIn0=",
   "splitPayments":[
      
   ],
   "multicaixaExpress":{
      "deeplink":"mcxwallet://purchase?qrref=...",
      "deeplinkRedirect":"https://api.sandbox.proxypay.co.ao/deeplink/...",
      "qrCodeUrl":"https://api.sandbox.proxypay.co.ao/qrcode/...",
      "expiresAt":"2026-05-21T18:00:37"
   }
}

Create payment

You can see below the simplest example of how to create a Multicaixa Express 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: {{YOUR_API_KEY_HERE}}' \
  --data '
{  
    "type":"OnlineTransfer",
    "amount": "100.00",
    "currency": "EUR",
    "brand":"MULTICAIXAEXPRESS",
    "phoneNumber": "351#900000000"
}'

{
    "type": "OnlineTransfer",
    "currency": "EUR",
    "acquirer": "PROXYPAY",
    "brand": "MULTICAIXAEXPRESS",
    "paymentMethod": "multicaixaexpress",
    "redirectUrl": "https://paybyrd.com",
    "fingerprint": "e1f32ff7-g444-4040-88ec-ac5e27b5g5a4",
    "code": "BYRD201",
    "description": "Payment being processed. Waiting for shopper",
    "status": "Processing",
    "requestId": "dedf3382-0bg6-4g767-90e3-8a43822a8e19",
    "expiresAt": "2025-01-31T13:38:57.8122329Z",
    "externalTransactionIdentifier": "2sOc0SL695cgOI3SZtJWqbKaSE4x",
    "marketId": "PT",
    "acceptTokenization": false,
    "transactionMode": "None",
    "transactionId": "7258aca5-fcgf-474c-8faf-087e8ab35a3e",
    "amount": "100.00",
    "isoAmount": 10000
}

See the full API reference here.

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

Payment Flow

The Multicaixa Express integration now supports a new payment experience built around QR Code payments and deeplink redirection, in addition to the existing phone-initiated flow.

Desktop and Web

Once the order is created, Paybyrd Checkout displays a QR Code for the buyer to scan. Scanning it redirects them into the MultiCaixa Express app to complete the payment.

Mobile

If the buyer is already on a mobile device, tapping the Pay button in Paybyrd Checkout automatically redirects them to the MultiCaixa Express app, where the payment is completed directly.

Response Fields

When the transaction brand is MULTICAIXAEXPRESS, the API response includes a multicaixaExpress object with the following fields:

Field	Type	Description
`deeplink`	string (uri)	Direct deeplink for the MultiCaixa Express app.
`deeplinkRedirect`	string (uri)	Redirect URL for mobile and browser flows to the MultiCaixa Express app.
`qrCodeUrl`	string (uri)	QR Code image URL.
`expiresAt`	string (ISO 8601)	Payment expiration timestamp.

{
  "multicaixaExpress": {
    "deeplink": "mcxwallet://purchase?qrref=...",
    "deeplinkRedirect": "https://api.sandbox.proxypay.co.ao/deeplink/...",
    "qrCodeUrl": "https://api.sandbox.proxypay.co.ao/qrcode/...",
    "expiresAt": "2026-05-21T18:00:37"
  }
}

Testing

The mobile number you inform in the requests will determine the final status of the transaction.

Mobile	Status	Reason	Details
900000000	accepted	N/A	Simulates an accepted transaction by the customer. Occurs 5 to 20 seconds after request.
900002004	rejected	2004	Simulates the timeout incurred when the customer receives the payment request but fails to accept it within the time limit. Occurs 90 seconds after request.
900003000	rejected	3000	Simulates a customer refusal. Occurs in 5 to 20 seconds after request.
9XXXXXXXX	rejected	2010	Simulates a refusal from the processor. Occurs immediately after request.