> ## 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.

# MODO

> Connect MODO to Payrails to accept MODO wallet payments in Argentina, covering your credentials, processor code and installments.

<Note>
  **Who should use this guide**

  This guide is intended for merchants who:

  * Use **Payrails** as a payment orchestrator
  * Use **MODO** to accept wallet payments in Argentina
  * Have an active MODO merchant account
</Note>

***

## Create a MODO integration in Payrails

1. Log in to the **Payrails** portal.
2. Go to **Settings** → **Integrations**.
3. Select **Add instance** to create a new integration configuration.
4. Select the **workspaces** where this integration should be available.

<Note>
  **About workspaces**

  Workspaces determine where this integration is available. They let you isolate provider setups by region or business line, or share the same configuration across multiple workspaces.
</Note>

***

## Step 1: Choose the integration type

* Select **Payment**.
* Continue to the next step.

***

## Step 2: Choose the provider

* Select **Modo**.
* Continue to the next step.

<img src="https://mintcdn.com/payrails-42074109/EGCtsK-I7fgATNbU/images/docs/modo-image-01.png?fit=max&auto=format&n=EGCtsK-I7fgATNbU&q=85&s=267ab97d529f4738687941534cfb6820" alt="A screenshot showing MODO selected as the provider." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/modo-image-01.png" />

***

## Step 3: Configure your MODO integration

<Tip>
  **What you'll need from MODO**

  Before you begin, make sure you have your MODO username, password and processor code. MODO provides them when it sets up your account.
</Tip>

***

### Integration instance name

> An integration instance is a specific payment provider setup in Payrails. You can create multiple instances for different regions, currencies, or business needs. Choose a clear, consistent name, as it is used in routing.

**In Payrails**

* Enter an **Instance name** for your integration, for example `merchant_modo`.

<img src="https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max&auto=format&n=145W1v58K5wnDMNC&q=85&s=470be58979509680650b0cbf8b5eecc4" alt="A screenshot showing the integration instance name field." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/orchestration/integrations/shared/integration-instance-name.png" />

***

### Payment methods

**In Payrails**

* Select **Modo**.

<img src="https://mintcdn.com/payrails-42074109/EGCtsK-I7fgATNbU/images/docs/modo-image-02.png?fit=max&auto=format&n=EGCtsK-I7fgATNbU&q=85&s=337fcf394384037e09959ba12de6f18f" alt="A screenshot showing the MODO payment method selection." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/modo-image-02.png" />

***

### Credentials

**In Payrails**

| Field | Value |
| :- | :- |
| **Username** | Your MODO username |
| **Password** | Your MODO password |

Payrails sends requests to the MODO pre-production environment in test mode and to the live environment in live mode, so use the credentials for the matching environment.

<img src="https://mintcdn.com/payrails-42074109/EGCtsK-I7fgATNbU/images/docs/modo-image-03.png?fit=max&auto=format&n=EGCtsK-I7fgATNbU&q=85&s=7eb8cfe6527f6a22ef62b366ea5d4686" alt="A screenshot showing the MODO credential fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/modo-image-03.png" />

***

### Account details

**In Payrails**

| Field | Value |
| :- | :- |
| **Processor Code** | Your MODO processor code: the identifier of the payment gateway configuration for your payments |
| **Commercial Condition (CC) Code** | Optional. Refer to [Configure MODO settings](#configure-modo-settings). |

<img src="https://mintcdn.com/payrails-42074109/EGCtsK-I7fgATNbU/images/docs/modo-image-04.png?fit=max&auto=format&n=EGCtsK-I7fgATNbU&q=85&s=c783a8135ed0e78aa5171f050beda421" alt="A screenshot showing the MODO account details fields." className="mx-auto block rounded-lg object-cover border border-gray-200" width="80%" data-path="images/docs/modo-image-04.png" />

***

### Webhooks or notifications

Payrails sends its notification URL to MODO with every payment, so you don't need to set one up with MODO. Payrails verifies each notification with the signing keys MODO publishes and also checks the payment status with MODO until it reaches a final state.

***

## Request fields for MODO

Send these fields in the [authorize request](/reference/authorizeaction), in addition to the standard authorize fields. **Required** fields must be present for the payment to succeed. Payrails sends **Optional** fields to MODO when you include them. For more about meta fields, refer to [Meta fields](/docs/orchestration/meta-fields).

| Field | Status | Description |
| :- | :- | :- |
| `amount` | Required | Use ARS. MODO charges the order total. |
| `meta.order` | Required | Include `lines` or `total`. Payrails sends `total` as the amount, or adds up the lines, shipping, tax and discount. The order must match `amount`. |
| `meta.customer.name`, `meta.customer.lastName` | Required | Sent as the customer's full name. |
| `meta.customer.email` | Required | Sent as the customer email. |
| `merchantReference` | Optional | Sent as the external intention ID. Use a new value for every payment. |
| `meta.order.description` | Optional | Sent as the payment description. Payrails builds one from the lines when you don't send it. |
| `meta.order.lines[].description`, `quantity` | Optional | Sent as the items. |
| `meta.order.deliveryAddress`, `meta.order.billingAddress` | Optional | Sent as the shipping and invoice addresses. |
| `meta.customer.identityCardNumber` | Optional | Sent as the customer identification. |
| `meta.customer.birthDate` | Optional | Sent as the customer's date of birth. |
| `meta.customer.phone.number` | Optional | Sent as the customer phone. |
| `meta.customer.reference` | Optional | Sent as the customer ID. |

MODO payments are captured straight away, so use instant capture in your workflow.

***

## Configure MODO settings

Some MODO integration settings change how Payrails processes your payments. The portal shows the same description when you hover over each setting.

| Setting | What it does |
| :- | :- |
| **Commercial Condition (CC) Code** | The installment combinations MODO offers your customer at checkout, for example `3CSI` or `3CSI-6CSI-12CCI`. Payrails sends it to MODO unchanged. When it's empty, MODO offers a single payment (`1CSI`). |

***

## Enable the integration

**In Payrails**

* Select **Save account** to enable the integration.
* Confirm the integration shows as **Enabled**.

Your **MODO** integration is now ready to process payments.

***

## Next steps

1. Run a test payment in ARS in the MODO pre-production environment, and pay it with the MODO app.
2. Verify that:
   * Your customer sees the MODO QR code or app link.
   * The payment status updates correctly in Payrails.
3. Once verified in test mode, repeat the setup in live mode.

→ Continue to: [Test a payment](/docs/orchestration/payment-acceptance/test-payments)


## Related topics

- [Integrations](/docs/orchestration/integrations.md)
- [Create a new Ruleset](/reference/createruleset.md)
- [Update a Ruleset](/reference/updateruleset.md)


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