# Bizum for Unified Payments API

To process Bizum payments, you must [request a payment](#Request_a_payment). Your customer will then confirm the payment using their online banking app.

---

## Request a payment

To send a payment request, call the [payments](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout) endpoint:

**Live**

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

**Sandbox**

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

### Request example

If you do not provide a customer ID or email address in the request, Checkout.com automatically creates a customer profile and returns the customer ID in the response.

```json
{
  "amount": 100,
  "currency": "EUR",
  "source": {
    "type": "bizum"
  },
  "reference": "ORD-5023-4E89",
  "customer": {
    "phone": {
      "country_code": "34",
      "number": "700000000"
    }
  },
  "processing_channel_id": "pc_3wuuqzzjbrzexbu4osjacmk7q4"
}
```

### Response example

If you receive a `202 Accepted` response with a payment `id` value and the `status` field set to `Pending`, your request was successful.

```json
{
  "id": "pay_7ehiotldrlvujfpiyeo42i2roe",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_urx7wggzcpzufjjynbn7t6l5mq",
    "phone": {
      "country_code": "34",
      "number": "700000000"
    }
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_7ehiotldrlvujfpiyeo42i2roe"
    }
  }
}
```

---

## Get details about a payment

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

**Live**

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

**Sandbox**

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

See [Get payment details](https://www.checkout.com/docs/payments/manage-payments/get-payment-details.md) for more information.

---

## Refund a payment

Bizum supports both partial and full refunds.

You can refund the payment through the [Dashboard](https://dashboard.checkout.com) or by calling the [Refund a payment](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment) endpoint setting the `{id}` query parameter using the `payment_id` value your received in the payment response:

> **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/{id}/refunds`

**Sandbox**

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

See [Refund a payment](https://www.checkout.com/docs/payments/manage-payments/refund-a-payment.md) for more information.

### Request example

```json
{
  "amount": 10
}
```

### Response example

```json
{
  "action_id": "act_f544khcfnyqudh3l73qwnnvfbi",
  "_links": {
    "payment": {
      "href": "https://{prefix}.api.sandbox.checkout.com/payments/pay_uexsi2rik7ceppidytigjmxshi"
    }
  }
}
```

---

## Cancel or void a payment

Once a payment is created, you can't void it. If you wish to void a payment in progress, wait for the `payment_captured` webhook, and then process a refund. Communicating this in advance to your end customer can help you avoid chargebacks.

If the customer cancels or fails to complete their payment, we send a `payment_expired` webhook.

---

## Test your integration

You can simulate an authorized or a declined payment in the sandbox environment to ensure your integration is set up correctly and behaving as expected. In your request:

- Set `customer.phone.country_code` to `34`
- Set `customer.phone.number` to `700000000`
- Set `amount` to a value between `1` and `1000` to simulate an authorized payment, or a value of `1001` or higher to simulate a declined payment

**Authorized payment**

```json
{
  "amount": 1,
  "currency": "EUR",
  "source": {
    "type": "bizum"
  },
  "customer": {
    "phone": {
      "country_code": "34",
      "number": "700000000"
    }
  }
}
```

**Declined payment**

```json
{
  "amount": 1001,
  "currency": "EUR",
  "source": {
    "type": "bizum"
  },
  "customer": {
    "phone": {
      "country_code": "34",
      "number": "700000000"
    }
  }
}
```

> **Information**
>
> In production, Bizum payments expire after four minutes if the customer does not confirm the payment in their online banking app. You cannot simulate this payment expiry flow in sandbox as the confirmation step is skipped.

---

## Response codes

When processing Bizum payments, you can receive the following response codes:

| Response code | Response text | Additional information |
| --- | --- | --- |
| `10000` | Approved |  |
| `20003` | Invalid merchant or service provider | The payment failed due to a technical issue. If the issue persists, contact us. |
| `20006` | Error / Invalid request parameters |  |
| `20051` | Insufficient funds | The payment failed because the customer does not have enough funds in their bank account. |
| `20068` | Response received too late / Timeout | The payment failed due to a technical issue. Try again after a few moments. If the issue persists, contact us. |
| `20068` | Internal error |  |
| `20083` | No accounts |  |
| `20103` | Card type / payment method not supported | The payment has been declined by your bank. |
| `20151` | Cardholder failed 3DS authentication |  |