# MB WAY for Unified Payments API

To accept MB WAY payments, you must:

1. [Request a payment](#Request_a_payment).
2. The customer performs authentication in the MB WAY app using their MB WAY PIN or Touch ID.
3. Receive a `payment_captured` [webhook](#Webhooks) when the payment is completed successfully. Alternatively, you can confirm the `status` of the payment by [retrieving the payment details](#Get_details_about_a_payment) via the API.

## Request a payment

For the full API specification, see the [API reference](https://api-reference.checkout.com/tag/Payments/#operation/requestAPaymentOrPayout).

> **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": 1000,
  "currency": "EUR",
  "source": {
    "type": "mbway"
  },
  "reference": "ORD-5023-4E89",
  "customer": {
    "phone": {
      "country_code": "372",
      "number": "12345678"
    }
  }
}
```

### Response example

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

```json
{
  "id": "pay_7ehiotldrlvujfpiyeo42i2roe",
  "status": "Pending",
  "reference": "ORD-5023-4E89",
  "customer": {
    "id": "cus_urx7wggzcpzufjjynbn7t6l5mq",
    "email": "fyi4s2facqzuhiu4fetjp2bbxe@auto.cko",
    "phone": {
      "country_code": "372",
      "number": "12345678"
    }
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_7ehiotldrlvujfpiyeo42i2roe"
    }
  }
}
```

---

## Get details about a payment

You can retrieve details about an existing MB WAY payment with the following endpoint.

For the full API specification, see the [API reference](https://api-reference.checkout.com/tag/Payments/#operation/getPaymentDetails).

> **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**

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

**Sandbox**

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

### Response example

```json
{
  "id": "pay_7ehiotldrlvujfpiyeo42i2roe",
  "requested_on": "2023-08-17T07:58:32.0749106Z",
  "source": {
    "type": "mbway"
  },
  "amount": 1000,
  "currency": "EUR",
  "reference": "ORD-5023-4E89",
  "status": "Pending",
  "customer": {
      "id": "cus_urx7wggzcpzufjjynbn7t6l5mq",
      "email": "fyi4s2facqzuhiu4fetjp2bbxe@auto.cko",
      "phone": {
          "country_code": "372",
          "number": "12345678"
      }
  },
  "_links": {
      "self": {
          "href": "https://{prefix}.api.checkout.com/payments/pay_7ehiotldrlvujfpiyeo42i2roe"
      },
      "actions": {
          "href": "https://{prefix}.api.checkout.com/payments/pay_7ehiotldrlvujfpiyeo42i2roe/actions"
      }
  }
}
```

---

## Refund a payment

MB WAY supports full, partial, and multiple partial refunds.

You can refund a payment through the [Dashboard](https://dashboard.checkout.com) or using the [Refund API](https://api-reference.checkout.com/tag/Payments/#operation/refundAPayment).

> **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`

### Request example

```json
{
  "amount": 100
}
```

### Response example

```json
{
  "action_id": "act_jf7fv3vgiu7ezjfgzvvsqobxru",
  "_links": {
    "payment": {
      "href": "https://{prefix}.api.checkout.com/payments/pay_fsud3hyoqkxencjvb5cfv6yqoe"
    }
  }
}
```

---

## Perform a test payment

> **Note**
>
> To start testing, contact your account manager or [request support](https://dashboard.checkout.com/support/new?topic=case_account_management_and_access&issue=issue_account_changes) to enable MB WAY payments in the sandbox environment.

To test MB WAY, request a payment using:

- The `customer.phone.country_code` field  set to `777`
- The `customer.phone.number` field set to a value from the following table, depending on which outcome you want to simulate

| Response Code | Description | Phone Number |
| --- | --- | --- |
| `10000` | Payment approved. | `12345678` |
| `20000` | The request was declined, though subsequent attempts may be successful. | `12345001` |
| `20017` | Customer cancellation. | `12345002` |
| `20003` | Invalid merchant or service provider. | `12345003` |
| `20120` | Invalid customer/user. | `12345004` |
| `20019` | Transaction has expired. | `12345005` |

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

### Request example

**Successful payment flow**

```json
{
  "amount": 100,
  "currency": "EUR",
  "source": {
    "type": "mbway"
  },
  "reference": "ORD-5023-4E89",
  "customer": {
    "phone": {
      "country_code": "777",
      "number": "12345678"
    }
  }
}
```

**Declined payment flow**

```json
{
  "amount": 100,
  "currency": "EUR",
  "source": {
      "type": "mbway"
  },
  "reference": "ORD-5023-4E89",
  "customer": {
      "email": "fyi4s2facqzuhiu4fetjp2bbxe@auto.cko",
      "phone": {
          "country_code": "777",
          "number": "10008888"
      }
  },
  "_links": {
      "self": {
          "href": "https://{prefix}.api.checkout.com/payments/pay_7ehiotldrlvujfpiyeo42i2roe"
      }
  }
}
```