Skip to content

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:
object
return_url
required
 string
URL to return the customer to when the transaction is completed.
object
A section of the payment method.
type
required
 string
multibanco
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.
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:

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.
object
A section of the payment method.
type
required
 string
multibanco_redirect
ip
 string
The customer's IP address.
object
A section of the customer details.
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"
                }
            ]
        }
    }
}

DC Integration option

Payment

Payment Flow

  1. The customer initiates the payment on the merchant's website.
  2. The merchant sends a payment request to PaySage.io.
  3. PaySage.io responds with a link to the payment page.
  4. The merchant redirects the customer to the payment page.
  5. The customer completes the payment.
  6. PaySage.io sends a webhook notification with the payment status to the merchant.

Info

This integration option supports only EUR currency.

Request

Send a payment request with the following additional data:
object
return_url
required
 string
URL to return the customer to when the transaction is completed.
object
A section of the payment method.
type
required
 string
multibanco_redirect
ip
 string
The customer's IP address.
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.
phone
 string
The customer's phone number.
email
 string
The customer's email address.
city
 string (120)
The customer's billing city.
zip
 string (40)
The customer's billing ZIP or postal code.
birth_date
 string
The customer's date of birth in the ISO 8601 format (YYYY-MM-DD).
address
 string (510)
The customer's billing address.
Request example 
{
    "request": {
        "amount": 500,
        "currency": "EUR",
        "description": "description",
        "test": true,
        "return_url": "https://return.com",
        "language": "en",
        "customer": {
            "first_name": "John",
            "last_name": "Doe"
        },
        "method": {
            "type": "multibanco_redirect"
        }
    }
}
Response

Redirect your customer to the URL received as the value of the form.action parameter.

Response example 
{
    "transaction": {
        "uid": "4b10733a-1327-45f0-b909-1ecd8bf6fefa",
        "type": "payment",
        "status": "pending",
        "amount": 500,
        "currency": "EUR",
        "description": "description",
        "created_at": "2025-09-17T12:10:55Z",
        "updated_at": "2025-09-17T12:10:56Z",
        "method_type": "multibanco_redirect",
        "receipt_url": "https://backoffice.paysage.io/customer/transactions/4b10733a-1327-45f0-b909-1ecd8bf6fefa/54cf8309584a098eab4f1c5eb2fae9ffab633d2445e07d438aa16e22d571fa0f?language=en",
        "payment": {
            "status": "pending",
            "gateway_id": 5220,
            "ref_id": "01505e9fb7884cd15b5d",
            "message": "Transaction was initialized."
        },
        "multibanco_redirect": {
            "type": "multibanco_redirect"
        },
        "customer": {
            "last_name": "Doe",
            "first_name": "John",
            "email": null,
            "ip": null
        },
        "manually_corrected_at": null,
        "version": 1,
        "message": "Transaction was initialized.",
        "test": true,
        "language": "en",
        "billing_address": {
            "last_name": "Doe",
            "first_name": "John"
        },
        "additional_data": {
            "payment_method": {
                "type": "alternative"
            }
        },
        "gateway": {
            "iframe": false
        },
        "form": {
            "action": "link_to_payment_page",
            "fields": [],
            "method": "GET"
        }
    }
}