Pine Labs

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

Use Payrails as a payment orchestrator
Use Pine Labs (Plural) to accept payments in India
Have an active Pine Labs merchant account with API access

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

A screenshot showing Pine Labs selected as the provider.

Step 3: Configure your Pine Labs integration

What you’ll need from Pine LabsBefore you begin, make sure you have your Pine Labs merchant ID, access code and secret key. Your Pine Labs account manager provides them.

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

A screenshot showing the integration instance name field.

Account details

In Payrails

Field	Value
Merchant ID	Your Pine Labs merchant ID. It’s a number.

A screenshot showing the Pine Labs account details fields.

Credentials

In Payrails

Field	Value
Access Token	Your Pine Labs access code
Secret Key	Your Pine Labs secret key, in hexadecimal. Payrails signs every request with it and uses it to verify Pine Labs’ notifications.

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

Payment methods

In Payrails

Select the payment methods to enable for this integration: Card, UPI, NetBanking or CashFree Wallets.

A screenshot showing the Pine Labs payment method selection.

Webhooks or notifications

Payrails uses provider webhooks or notifications to receive asynchronous payment status updates.

Create webhooks in the same mode (test or live) as your Payrails integration.

In Payrails

Copy the Notification URL shown under Account configuration at the top of the integration form.

In Pine Labs

Send the Payrails notification URL to your Pine Labs account manager, and ask them to send your payment and refund notifications to it.
Pine Labs signs each notification with your secret key, and Payrails verifies the signature.

Request fields for Pine Labs

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

Field	Status	Description
`amount`	Required	Sent to Pine Labs in paisa. Use INR.
`instrument.securityCode`	Required	Card payments only. The CVV your checkout collects, sent to Pine Labs with the card.
`instrument.holderName`	Required	Card payments only. Sent as the card holder name. You can send `meta.customer.name` and `meta.customer.lastName` instead.
`meta.customer.name`, `meta.customer.lastName`	Optional	Sent as the customer’s first and last name.
`meta.customer.email`	Optional	Sent as the customer’s email.
`meta.customer.phone`	Optional	Sent as the customer’s mobile number, country code first.
`meta.customer.reference`	Optional	Sent as the customer ID.
`meta.order.billingAddress`	Optional	Sent as the billing address: `street` and `doorNumber`, `city`, `state` and `country.code`.
`meta.order.deliveryAddress`	Optional	Sent as the shipping address, with the recipient’s `name`, `lastName` and `phone`.

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

Enable the integration

In Payrails

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

Your Pine Labs integration is now ready to process payments.

Next steps

Run a test payment in the Pine Labs UAT environment.
Verify that:
- The payment appears in Pine Labs.
- 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 Pine Labs integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider