Ecommpay

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

Use Payrails as a payment orchestrator
Use Ecommpay for card and wallet processing
Have an active Ecommpay project

Create a Ecommpay 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 Ecommpay.
Continue to the next step.

A screenshot showing Ecommpay selected as the provider.

Step 3: Configure your Ecommpay integration

What you’ll need from EcommpayBefore you begin, make sure you have your Ecommpay project ID and secret key. Ecommpay gives you a test project first and sends the live secret key when your account goes live.

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

A screenshot showing the integration instance name field.

Account details

In Payrails

Field	Value
Project ID	Your Ecommpay project ID
Enable polling for authorize operations	Optional. Refer to Configure Ecommpay settings.

A screenshot showing the Ecommpay account details fields.

Credentials

In Payrails

Field	Value
Secret Key	Your Ecommpay project secret key. Payrails signs every request with it and verifies notifications from Ecommpay.

Payments go to the test or live project that your project ID and secret key belong to, so use the ones that match the mode of your Payrails integration.

A screenshot showing the Ecommpay credential fields.

Payment methods

In Payrails

Select Card, Apple Pay, Google Pay or any combination.

A screenshot showing the Ecommpay payment method selection.

Webhooks or notifications

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

Request fields for Ecommpay

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 Ecommpay when you include them. For more about meta fields, refer to Meta fields.

Field	Status	Description
`amount`	Required	Sent to Ecommpay in minor units, with the currency. An amount of `0` runs an account verification.
`meta.customer.email`	Required	Sent as the customer email.
`meta.clientContext.ipAddress`	Required	Sent as the customer IP.
`meta.clientContext.screenWidth`, `screenHeight`	Required	Customer-initiated payments only. Sent as the screen resolution.
`instrument.holderName`	Optional	Sent as the card holder.
`merchantReference`	Optional	Sent in the merchant data.
`meta.customer.name`, `lastName`, `phone`, `country`, `birthDate`, `identityCardNumber`	Optional	Sent as the customer details.
`meta.order.billingAddress`, `meta.order.deliveryAddress`	Optional	Sent as the billing and shipping addresses.
`meta.risk.threeDSMode`	Optional	`Skip` sends the payment without 3D Secure.

Configure Ecommpay settings

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

Setting	What it does
Enable polling for authorize operations	Ecommpay processes payments asynchronously. By default, Payrails gets the payment result and any 3D Secure challenge from Ecommpay’s notifications. When you turn this on, Payrails also checks the payment status with Ecommpay for up to one hour after the authorize request, and takes the 3D Secure challenge from those checks. Notifications still update the payment status.

Enable the integration

In Payrails

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

Your Ecommpay integration is now ready to process payments.

Next steps

Run a test card payment on your Ecommpay test project.
Verify that:
- The payment appears in the Ecommpay dashboard.
- The payment status updates correctly in Payrails.
Once verified in test mode, repeat the setup with your live project.

→ Continue to: Test a payment

Getting Started

Payment Orchestration

Token Vault

Analytics & Reporting

Fraud Management

Chargebacks

Monitoring

Resources

Use Cases

Create a Ecommpay integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider