Lidio

Who should use this guideThis guide is intended for merchants who:

Use Payrails as a payment orchestrator
Use Lidio for card processing in Türkiye
Have an active Lidio merchant account

Create a Lidio integration in Payrails

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

About workspacesWorkspaces 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.

Step 1: Choose the integration type

Select Payment.
Continue to the next step.

Step 2: Choose the provider

Select Lidio.
Continue to the next step.

A screenshot showing Lidio selected as the provider.

Step 3: Configure your Lidio integration

What you’ll need from LidioBefore you begin, make sure you have your Lidio merchant code, API key and API password. Lidio provides them when it sets up your account.

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

A screenshot showing the integration instance name field.

Account details

In Payrails

Field	Value
Merchant Code for Lidio	Your Lidio merchant code

A screenshot showing the Lidio account details fields.

Credentials

In Payrails

Field	Value
API key	Your Lidio API key: the value Lidio gives you for the `Authorization` header, without the `MxS2S` prefix
API Password	Your Lidio API password. Payrails uses it to verify notifications from Lidio.

Payrails sends requests to the Lidio test environment in test mode and to the live environment in live mode, so use the credentials for the matching environment.

A screenshot showing the Lidio credential fields.

Payment methods

In Payrails

Select Card.

A screenshot showing the Lidio payment method selection.

Webhooks or notifications

Payrails sends its notification URL to Lidio with every payment, so you don’t need to set one up in the Lidio dashboard. Payrails verifies each notification with your API password.

Request fields for Lidio

Send these fields in the authorize request for card payments, in addition to the standard authorize fields. Required fields must be present for the payment to succeed. Payrails sends Optional fields to Lidio when you include them. For more about meta fields, refer to Meta fields.

Field	Status	Description
`amount`	Required	Sent to Lidio as the total amount and currency.
`merchantReference`	Required	Sent as the order ID: letters and numbers only, up to 20 characters.
`meta.customer.name`	Required	Sent as the customer name.
`meta.customer.email`	Required	Sent as the customer email.
`meta.customer.reference`	Required	Sent as the customer ID.
`meta.customer.phone.number`	Required	Sent as the customer phone.
`meta.order.billingAddress`	Required	Sent as the invoice address. Include `country.name`, `city`, `area` and `postalCode`.
`meta.order.deliveryAddress`	Required	Sent as the delivery address. Include `country.name`, `city`, `area` and `postalCode`.
`meta.order.lines`	Optional	Sent as the basket items, with `name`, `quantity` and `unitPrice`. The lines must add up to `amount`.
`meta.risk.threeDSMode`	Optional	`Force` runs 3D Secure.

Enable the integration

In Payrails

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

Your Lidio integration is now ready to process payments.

Next steps

Run a test card payment in TRY in the Lidio test environment.
Verify that:
- The payment appears in Lidio.
- The payment status updates correctly in Payrails.
Once verified in test mode, repeat the setup in live mode.

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a Lidio integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider