# Multibanco for Unified Payments API

Multibanco payments follow a two-step process:

1. [Request a Multibanco payment](#Request_a_payment).
2. [Redirect the customer](#Redirect_the_customer).

---

## Request a payment

Call the [Request a payment](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint to create a Multibanco payment:

> **Information**
>
> Your base URL's `{prefix}` value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see [API endpoints](https://www.checkout.com/docs/developer-resources/api/api-endpoints.md).

**Production**

`POST` `https://{prefix}.api.checkout.com/payments`

**Sandbox**

`POST` `https://{prefix}.api.sandbox.checkout.com/payments`

### Request example

```json
{
  "amount": 100,
  "currency": "EUR",
  "source": {
    "type": "multibanco",
    "payment_country": "PT",
    "account_holder_name": "John Smith",
    "billing_descriptor": "test payment"
  }
}
```

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:

### Request example

```json
{
  "amount": 100,
  "currency": "EUR",
  "source": {
    "type": "multibanco",
    "payment_country": "PT",
    "account_holder_name": "John Smith",
    "billing_descriptor": "test payment"
  },
  "expire_on": "2019-09-10T10:11:12Z"
}
```

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

### Response example

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

```json
{
  "id": "pay_cdv64cky2neeljlss37yjpofzu",
  "status": "Pending",
  "customer": {
    "id": "cus_ezuq5ju3ln4udgaz6joebp3p44"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_cdv64cky2neeljlss37yjpofzu"
    },
    "multibanco:static-reference-page": {
      "href": "https://r.girogate.de/ti/simmultibanco?tx=512308296&rs=y5XBJFK6UF0R7gcn4lcQlbtc5wD2ppQ1&cs=058d2f4cecebaf97933ac9fb465a517ab84395eca459900105526a823460a90a"
    }
  }
}
```

---

## Redirect the customer

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.

---

## Get details about a payment

To retrieve details about the payment, call the [Get payment details](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentsList) endpoint, and provide the `{id}` path parameter using the `payment_id` value you received in the `Create a payment` response.

**Live**

`GET` `https://{prefix}.api.checkout.com/payments/{id}`

**Sandbox**

`GET` `https://{prefix}.api.sandbox.checkout.com/payments/{id}`

### Response example

```json
{
  "id": "pay_cdv64cky2neeljlss37yjpofzu",
  "requested_on": "2024-09-25T06:05:22Z",
  "source": {
    "type": "multibanco",
    "service_supplier_id": "11854",
    "payment_reference": "999999919"
  },
  "amount": 100,
  "currency": "EUR",
  "payment_type": "Regular",
  "status": "Captured",
  "approved": true,
  "risk": {
    "flagged": false
  },
  "customer": {
    "id": "cus_ezuq5ju3ln4udgaz6joebp3p44"
  },
  "actions": [
    {
      "id": "act_n7qvjkcqgvlutongpq7vxshauy",
      "type": "Capture",
      "response_code": "10000",
      "response_summary": "Approved"
    }
  ],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_cdv64cky2neeljlss37yjpofzu"
    },
    "actions": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_cdv64cky2neeljlss37yjpofzu/actions"
    },
    "refund": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_cdv64cky2neeljlss37yjpofzu/refunds"
    }
  }
}
```

---

## Refund a payment

Multibanco supports both partial and full refunds.

You can process a full refund using the [Dashboard](https://dashboard.checkout.com) or by using the [Refund API](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment).

---

## Testing Multibanco

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

1.  Create a Multibanco transaction following the steps on this page, and open the redirect link in the response to Multibanco's website.
2.  Select _Multibanco_.
3.  Select _Pay now_. You will be redirected to the Multibanco Simulator.
4.  Leave the _Pin_ field blank and select _Make Payment_.
5.  Select _Back to where you came from_ to be redirected to your predefined success URL.