Tamara

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

Use Payrails as a payment orchestrator
Use Payrails to offer Tamara buy now, pay later
Have an active Tamara merchant account with access to the Tamara Partner Portal

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

A screenshot showing Tamara selected as the provider.

Step 3: Configure your Tamara integration

What you’ll need from TamaraBefore you begin, make sure you can log in to the Tamara Partner Portal, and have the API token, notification token and widget token Tamara issued for your merchant 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_tamara.

A screenshot showing the integration instance name field.

Credentials

In Tamara

Get the API token, notification token and widget token for your merchant account from the Tamara Partner Portal, or ask your Tamara account manager.

In Payrails

Field	Value
API Token	Your Tamara API token. Payrails uses it to call Tamara.
Notification Token	Your Tamara notification token. Payrails uses it to verify webhooks from Tamara.
Widget Token	Your Tamara widget token

Payrails sends requests to the Tamara sandbox in test mode and to the live environment in live mode, so use the tokens for the matching environment.

A screenshot showing the Tamara credential fields.

Payment methods

In Payrails

Select Tamara.

A screenshot showing the Tamara payment method selection.

Webhooks or notifications

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

In Payrails

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

In Tamara

In the Tamara Partner Portal, go to Settings → General Settings → Webhooks, and select Add webhooks.

A screenshot showing the Tamara Partner Portal webhooks page.

Enter the following, then select Create Webhook:
- Type: select Order.
- Events: select Approved, which Tamara requires, plus Authorised, Declined, Expired, Canceled, Captured and Refunded.
- URL: paste the Payrails notification URL.

A screenshot showing the Tamara create webhook form with order events and the notification URL.

Tamara confirms that the webhook is added.

A screenshot showing the Tamara webhook created confirmation.

Payrails verifies each webhook with your notification token. Payrails also checks the order status with Tamara until it reaches a final state.

Request fields for Tamara

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

Field	Status	Description
`amount`	Required	Sent to Tamara as the total amount and currency.
`meta.customer.country.code`	Required	Sent as the order country and the customer’s nationality.
`meta.order`	Required	Sent as the order details.
`meta.order.lines`	Required	Sent as the items. Include `id`, `name`, `quantity`, `total`, `unitPrice`, `totalTax`, `totalDiscount` and `product.type` on each line. Payrails also sends the lines when you capture or cancel.
`merchantReference`	Optional	Sent as the order reference ID.
`meta.customer.name`, `lastName`, `email`, `phone.number`	Optional	Sent as the customer’s first name, last name, email and phone.
`meta.customer.birthDate`	Optional	Sent as the customer’s date of birth for Tamara’s risk checks.
`meta.customer.createdAt`	Optional	RFC 3339 date-time. Sent as the account creation date for Tamara’s risk checks.
`meta.order.billingAddress`, `meta.order.deliveryAddress`	Optional	Sent as the billing and shipping addresses.
`meta.order.shipping`, `meta.order.totalTax`	Optional	Sent as the shipping and tax amounts. Payrails sends `0` when you don’t include them.
`meta.clientContext.language`	Optional	Sent as the checkout locale, for example `ar_SA` or `en_US`. Defaults to `en_US`.
`returnInfo.success`, `returnInfo.error`, `returnInfo.cancel`	Optional	The URLs Tamara returns your customer to.
`meta.shippingInfo`	Optional	A JSON string with the shipping details Payrails sends to Tamara when you capture the payment.

Tamara payments use manual capture, so build your workflow with manual capture. Payrails captures the payment when you send a capture. You can also turn on auto-capture for your account in Tamara.

Enable the integration

In Payrails

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

Your Tamara integration is now ready to process payments.

Next steps

Run a test Tamara payment in the Tamara sandbox.
Verify that:
- Your customer is redirected to Tamara and back to your site.
- The payment appears in the Tamara Partner Portal.
- 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 Tamara integration in Payrails

Step 1: Choose the integration type

Step 2: Choose the provider