Multibanco for API only

Last updated: May 28, 2025

Multibanco payments follow a two-step process:

Call the Request a payment endpoint to create a Multibanco payment:

post

https://api.checkout.com/payments


1{
2  "amount": 100,
3  "currency": "EUR",
4  "source": {
5    "type": "multibanco",
6    "payment_country": "PT",
7    "account_holder_name": "John Smith",
8    "billing_descriptor": "test payment"
9  }
10}

By default, Multibanco payments expire after seven days. You can set the expiry date according to your business needs using the expire_on field in your payment request:


1{
2  "amount": 100,
3  "currency": "EUR",
4  "source": {
5    "type": "multibanco",
6    "payment_country": "PT",
7    "account_holder_name": "John Smith",
8    "billing_descriptor": "test payment"
9  },
10  "expire_on": "2019-09-10T10:11:12Z"
11}

Information

You set the expire_on field to 1 minute or up 7 days after the payment creation date.

If you receive a 202 Success response with a status field set to Pending, your request was successful.


1{
2  "id": "pay_cdv64cky2neeljlss37yjpofzu",
3  "status": "Pending",
4  "customer": {
5    "id": "cus_ezuq5ju3ln4udgaz6joebp3p44"
6  },
7  "_links": {
8    "self": {
9      "href": "https://api.sandbox.checkout.com/payments/pay_cdv64cky2neeljlss37yjpofzu"
10    },
11    "multibanco:static-reference-page": {
12      "href": "https://r.girogate.de/ti/simmultibanco?tx=512308296&rs=y5XBJFK6UF0R7gcn4lcQlbtc5wD2ppQ1&cs=058d2f4cecebaf97933ac9fb465a517ab84395eca459900105526a823460a90a"
13    }
14  }
15}

Redirect your customer to the multibanco:static-reference-page.url value in the response. The customer can then review and authorize the payment, before being transferred to your predefined success or failure URL.

After the payment expires, Checkout.com automatically voids it and sends a payment_expired webhook.

To retrieve details about the payment, call the Get payment details endpoint, and provide the {id} path parameter using the payment_id value you received in the Create a payment response.

get

https://api.checkout.com/payments/{id}


1{
2  "id": "pay_cdv64cky2neeljlss37yjpofzu",
3  "requested_on": "2024-09-25T06:05:22Z",
4  "source": {
5    "type": "multibanco",
6    "service_supplier_id": "11854",
7    "payment_reference": "999999919"
8  },
9  "amount": 100,
10  "currency": "EUR",
11  "payment_type": "Regular",
12  "status": "Captured",
13  "approved": true,
14  "risk": {
15    "flagged": false
16  },
17  "customer": {
18    "id": "cus_ezuq5ju3ln4udgaz6joebp3p44"
19  },
20  "actions": [
21    {
22      "id": "act_n7qvjkcqgvlutongpq7vxshauy",
23      "type": "Capture",
24      "response_code": "10000",
25      "response_summary": "Approved"
26    }
27  ],
28  "_links": {
29    "self": {
30      "href": "https://api.sandbox.checkout.com/payments/pay_cdv64cky2neeljlss37yjpofzu"
31    },
32    "actions": {
33      "href": "https://api.sandbox.checkout.com/payments/pay_cdv64cky2neeljlss37yjpofzu/actions"
34    },
35    "refund": {
36      "href": "https://api.sandbox.checkout.com/payments/pay_cdv64cky2neeljlss37yjpofzu/refunds"
37    }
38  }
39}

Multibanco supports both partial and full refunds.

You can process a full refund using the Dashboard or by using the Refund API.

Note

To start testing, contact your account manager or integrations engineer to activate Multibanco payments in the sandbox environment.

Create a Multibanco transaction following the steps on this page, and open the redirect link in the response to Multibanco's website.
Select Multibanco.
Select Pay now. You will be redirected to the Multibanco Simulator.
Leave the Pin field blank and select Make Payment.
Select Back to where you came from to be redirected to your predefined success URL.

Multibanco for API only

Request a payment

Request example

Request example

Information

Response example

Redirect the customer

Get details about a payment

Response example

Refund a payment

Testing Multibanco

Note