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": []
}

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

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.