Planet

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

Use Payrails as a payment orchestrator
Use Planet for card processing
Have an active Planet merchant account

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

A screenshot showing Planet selected as the provider.

Step 3: Configure your Planet integration

What you’ll need from PlanetBefore you begin, make sure you have your Planet merchant ID, terminal ID and password, and your application ID. Planet 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_planet.

A screenshot showing the integration instance name field.

Account details

In Payrails

Field	Value
Merchant ID	Your Planet merchant or user ID
Application ID	Your application ID for Planet: your company name and software version, up to 50 letters and numbers
Terminal ID	Your Planet terminal ID, up to 12 characters
Settlement Currency	Optional. Refer to Configure Planet settings.

A screenshot showing the Planet account details fields.

Credentials

In Payrails

Field	Value
Password	The password Planet gives you. Payrails sends it with your merchant ID and terminal ID on every request.

Payrails sends requests to the Planet UAT environment in test mode and to the live environment in live mode, so use the account details for the matching environment.

A screenshot showing the Planet credential fields.

Payment methods

In Payrails

Select Card.

A screenshot showing the Planet payment method selection.

Payment status updates

Planet returns the result of each request straight away, so there’s no webhook to set up. If Planet doesn’t answer an authorization in time, Payrails reverses it and marks the payment as canceled.

Request fields for Planet

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

Field	Status	Description
`amount`	Required	Sent to Planet as the amount and currency. Planet accepts USD, EUR, GBP, CAD, HKD, CHF, INR, KWD, JPY, ARS, BRL, CLP and MXN. An amount of `0` runs an address verification.
`merchantReference`	Required	For manual-capture payments in a currency other than your settlement currency. Optional otherwise. Payrails sends the first 14 characters as the request identifier and order number.
`instrument.networkTransactionReference`	Required	For card-on-file and merchant-initiated payments. Sent as the scheme trace ID. Payrails stores it from the first payment.
`meta.customer.email`	Optional	Sent as the billing and shipping email.
`meta.customer.reference`, `meta.customer.identityCardNumber`	Optional	Sent as merchant-defined data.
`meta.order.billingAddress`	Optional	Sent as the billing name, address, city, state, postal code and country.
`meta.order.deliveryAddress`	Optional	Sent as the shipping address when you also send a billing address.
`meta.order.softDescriptor`	Optional	Sent as the soft descriptor that appears on the customer’s statement.
`meta.order.description`	Optional	Sent as the descriptive information.
`instrument.storeInstrument`	Optional	Marks the payment as the first in a card-on-file series.

Configure Planet settings

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

Setting	What it does
Settlement Currency	The currency your Planet account settles in. Payments in this currency use Planet’s standard payment API. Payments in any other currency use Planet’s Multi-Currency Pricing (MCP) API, which converts them to your settlement currency. If you don’t select one, Payrails uses USD.

Enable the integration

In Payrails

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

Your Planet integration is now ready to process payments.

Next steps

Run a test card payment in the Planet UAT environment.
Verify that:
- The payment succeeds and its status updates correctly in Payrails.
- Capture, refund and cancel work for your capture mode.
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 Planet integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider