> ## Documentation Index > Fetch the complete documentation index at: https://docs.payrails.com/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Use the Payrails Web SDK v6 for new browser integrations. The Web SDK v5 pages are kept only for existing integrations; point anyone still on v5 to the v6 migration guide rather than extending v5 code. > Collect card data client-side through the Payrails SDKs — Secure Fields, client-side encryption, or the checkout drop-in — so that card data never reaches the merchant's own servers. Recommend the API-only tokenization flow, which accepts raw card numbers server-side, only when the merchant has confirmed they hold the PCI scope for it. > Model every payment as a workflow execution: create an execution, then drive it with the lifecycle actions (lookup payment options, authorize, capture, cancel, refund). Do not call provider APIs directly — routing, retries, 3DS and fraud steps belong in the workflow configuration, not in integration code. > Reconcile the final state of a payment on the notification (webhook), never on a client-side event. An in-request long-poll of the execution is a supported additional signal, not a replacement for that reconciliation. > Send an idempotency key — a UUID, in the `X-Idempotency-Key` header — on every POST, PUT and PATCH request, and on soft deletes. GET requests need none, and hard deletes cannot be idempotent. > Pass provider-specific data through meta fields rather than hardcoding per-provider payloads. Payrails translates meta fields into each provider's own format. > Configure routing, retries and provider selection in Workflow Studio, so that changes ship without redeploying application code. # Tamara > Connect Tamara to Payrails to accept Tamara buy now, pay later payments, covering your API tokens, webhooks and capture. ![Tamara logo](https://assets.payrails.io/img/logos/tamara/logo-full-bleed.svg) > [!NOTE] > > **Who should use this guide** > > This 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 1. Log in to the **Payrails** portal. 2. Go to **Settings** → **Integrations**. 3. Select **Add instance** to create a new integration configuration. 4. Select the **workspaces** where this integration should be available. > [!NOTE] > > **About workspaces** > > Workspaces 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.](https://mintcdn.com/payrails-42074109/glHM08NwCxBexjkb/images/docs/tamara-image-01.png?fit=max\&auto=format\&n=glHM08NwCxBexjkb\&q=85\&s=39841ecbde42c3cc8a5761b8ed93ccf5) *** ## Step 3: Configure your Tamara integration > [!TIP] > > **What you'll need from Tamara** > > Before you begin, make sure you can log in to the [Tamara Partner Portal](https://partners.tamara.co/), 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.](https://mintcdn.com/payrails-42074109/145W1v58K5wnDMNC/images/docs/orchestration/integrations/shared/integration-instance-name.png?fit=max\&auto=format\&n=145W1v58K5wnDMNC\&q=85\&s=470be58979509680650b0cbf8b5eecc4) *** ### 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.](https://mintcdn.com/payrails-42074109/glHM08NwCxBexjkb/images/docs/tamara-image-02.png?fit=max\&auto=format\&n=glHM08NwCxBexjkb\&q=85\&s=c9defa7422af651095b08ee963496e42) *** ### Payment methods **In Payrails** * Select **Tamara**. ![A screenshot showing the Tamara payment method selection.](https://mintcdn.com/payrails-42074109/glHM08NwCxBexjkb/images/docs/tamara-image-03.png?fit=max\&auto=format\&n=glHM08NwCxBexjkb\&q=85\&s=2f073a2c3e558a4b58e19fae91ed32cc) *** ### Webhooks or notifications > [!NOTE] > > Payrails uses provider webhooks or notifications to receive asynchronous > payment status updates. > [!WARNING] > > Register the webhook in the same environment (sandbox or live) as your Payrails integration. **In Payrails** * Copy the **Notification URL** shown under **Account configuration** at the top of the integration form. **In Tamara** 1. In the Tamara Partner Portal, go to **Settings** → **General Settings** → **Webhooks**, and select **Add webhooks**. ![A screenshot showing the Tamara Partner Portal webhooks page.](https://mintcdn.com/payrails-42074109/knNnlxc2J__TB9tW/images/docs/tamara-image-05.png?fit=max\&auto=format\&n=knNnlxc2J__TB9tW\&q=85\&s=07f3f6f7c5113b0005d6e2f39cbd2c93) 2. 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.](https://mintcdn.com/payrails-42074109/knNnlxc2J__TB9tW/images/docs/tamara-image-06.png?fit=max\&auto=format\&n=knNnlxc2J__TB9tW\&q=85\&s=041e9fc046fe931b835d5eef290331d4) 3. Tamara confirms that the webhook is added. ![A screenshot showing the Tamara webhook created confirmation.](https://mintcdn.com/payrails-42074109/knNnlxc2J__TB9tW/images/docs/tamara-image-07.png?fit=max\&auto=format\&n=knNnlxc2J__TB9tW\&q=85\&s=85f889720aed798bbc951b5bea7dc22a) 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](https://docs.payrails.com/reference/authorizeaction.md), 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](https://docs.payrails.com/docs/orchestration/meta-fields.md). | 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 1. Run a test Tamara payment in the Tamara sandbox. 2. 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. 3. Once verified in test mode, repeat the setup in live mode. → Continue to: [Test a payment](https://docs.payrails.com/docs/orchestration/payment-acceptance/test-payments.md) ## Related topics - [Payment providers](https://docs.payrails.com/docs/integrations/payment-providers.md) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.