Multibanco

EPA Integration option

Payment

Payment flow

1. The customer selects Multibanco as a payment method on the merchant's website.
2. The merchant sends a payment request to PaySage.io.
3. PaySage.io sends a response containing the multibanco object with account_number and account_code parameters.
4. The merchant displays account_number (Reference) and account_code (Entity) values to the customer as well as the instructions on how to complete the payment.
5. The customer uses the displayed values to complete the payment in an ATM or an application.
6. If the payment is successful, PaySage.io sends a webhook notification to the merchant with successful status.
7. If the payment isn't made within 3 hours after the payment response is sent, PaySage.io sends a webhook notification to the merchant with expired status.
8. If the transaction is made after more than 3 hours after the payment response is sent, PaySage.io sends another webhook notification to the merchant with successful status.

Request

Send a payment request with the following additional parameters:

Parameter	Type	Description
request	object
return_url * required	string	URL to return the customer to when the transaction is completed.
method	object	A section of the payment method.
type * required	string	multibanco
customer	object	A section of the customer details.
first_name * required	string	The customer's first name.
last_name * required	string	The customer's last name.
email * required	string	The customer's email address.
phone * required	string (9)	The customer's phone number without the country code.

Request example

{
    "request":{
        "amount":100,
        "currency":"EUR",
        "description":"description",
        "return_url": "https://your_return_url.com",
        "test": true,
        "method":{
            "type": "multibanco"
        },
        "customer":{
            "first_name": "John",
            "last_name": "Doe",
            "email": "john@example.com",
            "phone":"123456789"       
        }
    }
}

Response

The response will additionally contain the multibanco object with account_number and account_code parameters.

Parameter	Type	Description
multibanco	object
account_number * required	string	Identifier of the bank account, to which the payment is made. The value to be inserted into the Reference field in the ATM/application.
account_code * required	string	Identifier of the entity to which the payment is made. The value to be inserted into the Entity field in the ATM/application.

Response example

{
    "transaction": {
        "uid": "faaec396-641a-489b-941e-00d53e66f995",
        "type": "payment",
        "status": "pending",
        "amount": 100,
        "currency": "EUR",
        "description": "description",
        "created_at": "2023-11-15T06:51:55Z",
        "updated_at": "2023-11-15T06:51:57Z",
        "method_type": "multibanco",
        "receipt_url": "https://backoffice.paysage.io/customer/transactions/faaec396-641a-489b-941e-00d53e66f995/f65401e3dd21b16c5c48d93d0efe81fc1b9e88ca8875e2d50a6f4fbde1c08159",
        "payment": {
            "status": "pending",
            "gateway_id": 3403,
            "ref_id": "101323322",
            "message": "0 | OK",
            "bank_code": 0
        },
        "multibanco": {
            "account_number": "101323322",
            "account_code": "82142"
        },
        "customer": {
            "email": null,
            "ip": null
        },
        "manually_corrected_at": null,
        "message": "0 | OK",
        "test": true,
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },        
        "gateway": {
            "iframe": false
        }
    }
}

TW2 Integration option

Payment flow

1. Customer initiates Multibanco payment on the merchant's website.
2. Merchant sends the payment request to PaySage.io
3. PaySage.io returns a response with the form object with parameters to build a form to complete the payment.
4. The merchant redirects the customer to the form.
5. The customer completes the payment.
6. PaySage.io sends a webhook notification to the merchant.

Payment

Request

Send a payment request with the following additional parameters:

Parameter	Type	Description
request	object
amount * required	bigInteger	Transaction amount in minimal currency units, for example, 5000 (50 euros).
return_url * required	string	URL to return the customer to when the transaction is completed.
method	object	A section of the payment method.
type * required	string	multibanco_redirect
ip	string	The customer's IP address.
customer	object	A section of additional information about the customer.
country	string (2)	The customer's country in the ISO 3166-1 Alpha-2 format. For example, PT.
phone	string	The customer's phone number.
email	string	The customer's email address.
first_name	string	The customer's first name.
last_name	string	The customer's last name.
city	string (120)	The customer's billing city.
zip	string (40)	The customer's billing ZIP or postal code.
state	string	The customer's two-letter billing state only if the billing address country is US, CA or IN.
address	string (510)	The customer's billing address.

Request example

{
    "request": {
        "amount": 101,
        "currency": "EUR",
        "description": "test",
        "test": false,
        "tracking_id": "your_uniq_number21212",
        "return_url": "https://your-success.url",
        "method": {
            "type": "multibanco_redirect"
        }
    }
}

Response

Build an HTML form based on the parameters in the form object. Redirect the customer to the form to finalize the payment.

Response example

{
    "transaction": {
        "uid": "c0ed1ea7-743b-4b31-8b5d-822bbf8eae46",
        "type": "payment",
        "status": "pending",
        "amount": 100,
        "currency": "EUR",
        "description": "test",
        "created_at": "2025-04-08T10:54:36Z",
        "updated_at": "2025-04-08T10:54:36Z",
        "method_type": "multibanco_redirect",
        "receipt_url": "https://backoffice.paysage.io/customer/transactions/c0ed1ea7-743b-4b31-8b5d-822bbf8eae46/1b02219693e9975c5b03978435cd1ed46d7fc0b0d12de0380d83df6e02381ca3",
        "payment": {
            "status": "pending",
            "gateway_id": 5236,
            "message": "Transaction was initialized."
        },
        "multibanco_redirect": {
            "type": "multibanco_redirect"
        },
        "customer": {
            "email": null,
            "ip": null
        },
        "manually_corrected_at": null,
        "version": 0,
        "message": "Transaction was initialized.",
        "tracking_id": "your_uniq_number21212",
        "test": false,
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },            
        "gateway": {
            "iframe": false
        },
        "form": {
            "action": "link-to-payment-url",
            "method": "POST",
            "fields": [
                {
                    "name": "memberId",
                    "value": "14363",
                    "type": "hidden"
                },
                {
                    "name": "terminalid",
                    "value": "8162",
                    "type": "hidden"
                },
                {
                    "name": "partnerId",
                    "value": "39",
                    "type": "hidden"
                },
                {
                    "name": "checksum",
                    "value": "56426a4923e7cd9a816b078cfd0aa2d0",
                    "type": "hidden"
                },
                {
                    "name": "merchantTransactionId",
                    "value": "c0ed1ea7-743b-4b31-8b5d-822bbf8eae46",
                    "type": "hidden"
                },
                {
                    "name": "amount",
                    "value": "1.00",
                    "type": "hidden"
                },
                {
                    "name": "currency",
                    "value": "EUR",
                    "type": "hidden"
                },
                {
                    "name": "paymentBrand",
                    "value": "MULTIBANCO",
                    "type": "hidden"
                },
                {
                    "name": "paymentMode",
                    "value": "EW",
                    "type": "hidden"
                },
                {
                    "name": "orderDescription",
                    "value": "test",
                    "type": "hidden"
                },
                {
                    "name": "country",
                    "value": "PT",
                    "type": "hidden"
                },
                {
                    "name": "merchantRedirectUrl",
                    "value": "https://api.paysage.io/beyag/transactions/returns/88c70e7191aa823ac0588a279d22ef5722fc26712f6eac23ab76b53a65019c48/c0ed1ea7-743b-4b31-8b5d-822bbf8eae46",
                    "type": "hidden"
                },
                {
                    "name": "notificationUrl",
                    "value": "https://api.paysage.io/beyag/transactions/notifications/88c70e7191aa823ac0588a279d22ef5722fc26712f6eac23ab76b53a65019c48/c0ed1ea7-743b-4b31-8b5d-822bbf8eae46",
                    "type": "hidden"
                },
                {
                    "name": "totype",
                    "value": "TransactWorld",
                    "type": "hidden"
                }
            ]
        }
    }
}