> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payrails.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code.
> Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it.
> Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code.
> Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation.
> Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent.
> Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format.
> Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code.

# MB WAY via Checkout.com

> Set up MB WAY payments through Checkout.com in Payrails, including the direct flow that keeps the customer in your checkout.

<picture noZoom>
  ![MB WAY logo](https://assets.payrails.io/img/logos/mbway/logo.svg)
</picture>

<picture noZoom>
  ![Checkout.com logo](https://assets.payrails.io/img/logos/checkout/logo-full-bleed.svg)
</picture>

Accept [MB WAY](https://docs.payrails.com/docs/integrations/payment-methods/mb-way) payments from customers in Portugal with Checkout.com as the payment service provider (PSP). The customer approves each payment in the MB WAY app, and Checkout.com sends the result to Payrails as a webhook notification.

## Supported workflows

<table>
  <thead>
    <tr><th>Workflow</th><th>Supported</th></tr>
  </thead>

  <tbody>
    <tr><td>Payrails SDK</td><td>✔</td></tr>
    <tr><td>Payrails API</td><td>✔</td></tr>
    <tr><td>[Delayed / Manual Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✖</td></tr>
    <tr><td>[Instant Capture](https://docs.payrails.com/docs/orchestration/payment-acceptance/capture-and-cancel-modes.md#capture-mode)</td><td>✔</td></tr>
    <tr><td>[Cancel / Void](https://docs.payrails.com/docs/orchestration/payment-acceptance/cancel-a-payment.md)</td><td>✖</td></tr>
    <tr><td>[Refund / Reverse](https://docs.payrails.com/docs/orchestration/payment-acceptance/refund-a-payment.md)</td><td>✔</td></tr>
    <tr><td>[Save Instruments](https://docs.payrails.com/docs/resources/manage-instruments.md)</td><td>✖</td></tr>
    <tr><td>[Merchant Initiated Transaction (MIT)](https://docs.payrails.com/docs/resources/payments/authorization-flags.md)</td><td>✖</td></tr>
  </tbody>
</table>

## Before you begin

Complete these steps before you send your first MB WAY payment through Checkout.com:

1. Set up a Checkout.com integration in your workspace. Follow the [Checkout.com integration setup guide](https://docs.payrails.com/docs/integrations/payment-providers/checkout-com.md) if you don't have one yet.
2. Ask Checkout.com support to enable MB WAY on your Checkout.com account.
3. In the Payrails Portal, go to **Settings → Integrations**, open your Checkout.com integration, select **MB WAY** under **Payment methods**, and save.
4. Optional: turn on **Direct** under MB WAY in the same integration to use the direct flow. Leave it off to use the payment setup flow.
5. Add MB WAY as a [payment option](https://docs.payrails.com/docs/integrations/payment-methods/set-up-payment-methods.md) in your workflow.

### Choose a flow

Payrails processes MB WAY through Checkout.com in one of two flows, set by the **Direct** option on your integration:

* **Payment setup flow (default):** Payrails uses the Checkout.com Payment Setup API. If Checkout.com returns a redirect to a Checkout.com-hosted page, Payrails passes it on. Otherwise, the payment stays pending until the customer approves it in the app.
* **Direct flow:** Payrails uses the Checkout.com payments API. The customer stays on your checkout and approves in the app, and the response includes a wait action instead of a redirect. The Payrails SDK collects the phone number through payer fields when the amount is in EUR or isn't known yet.

## Request fields for Checkout.com

Send these fields in the authorize request, in addition to the standard [authorize fields](https://docs.payrails.com/reference/authorizeaction.md). **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to the PSP when you include them.

Send the phone number either as payer fields or in `meta.customer.phone`. Payrails uses the payer fields when they carry a phone number.

| Field | Status | Description |
| - | - | - |
| `paymentComposition[].paymentInstrumentData.payerFields.phoneCountryCode` | Required | Needed with payer fields. The dialing code of the customer's phone, digits only, for example `351`. |
| `paymentComposition[].paymentInstrumentData.payerFields.phoneNumber` | Required | Needed with payer fields. The customer's mobile number without the dialing code. Six to nine digits. |
| `meta.customer.phone.number` | Required | Needed without payer fields. The customer's mobile number without the dialing code. |
| `meta.customer.phone.countryCode` | Required | Needed without payer fields. The dialing code of the customer's phone, for example `351`. |
| `meta.customer.name`, `meta.customer.lastName` | Optional | Sent to Checkout.com as the customer name. |
| `meta.customer.email` | Optional | Sent to Checkout.com as the customer email. |

## Authorize an MB WAY payment

Call [authorize a payment](https://docs.payrails.com/reference/authorizeaction.md) with `mbWay` as the `paymentMethodCode`.

```json Authorize request theme={null}
{
  "amount": {
    "value": "25.00",
    "currency": "EUR"
  },
  "paymentComposition": [
    {
      "integrationType": "api",
      "paymentMethodCode": "mbWay",
      "amount": {
        "value": "25.00",
        "currency": "EUR"
      },
      "paymentInstrumentData": {
        "payerFields": {
          "phoneCountryCode": "351",
          "phoneNumber": "912345678"
        }
      }
    }
  ],
  "meta": {
    "customer": {
      "email": "ines.costa@example.com",
      "name": "Inês",
      "lastName": "Costa"
    }
  },
  "returnInfo": {
    "success": "https://example.com/success",
    "error": "https://example.com/error"
  }
}
```

The payment stays pending until the customer approves it in the MB WAY app. Confirm the result through [webhook notifications](https://docs.payrails.com/docs/orchestration/payment-acceptance/receive-notifications.md) or the execution status before you fulfill the order.

## How Checkout.com handles MB WAY

* Payrails checks the phone number before it calls Checkout.com, and sends it to Checkout.com on the customer.
* In the direct flow, the wait action gives the client a 15-minute window to poll for the result.
* Checkout.com sends the final result as a webhook notification after the customer approves or declines in the app.
* Each MB WAY payment is a new customer-initiated payment.


## Related topics

- [MB WAY](https://docs.payrails.com/docs/integrations/payment-methods/mb-way.md)
- [Przelewy24 via Checkout.com](https://docs.payrails.com/docs/integrations/payment-methods/przelewy24/checkout-com.md)
- [Bancontact via Checkout.com](https://docs.payrails.com/docs/integrations/payment-methods/bancontact/checkout-com.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.