Tamara Integration

Overview

Tamara is a buy now pay later service available in the United Arab Emirates, Kuwait, and Saudi Arabia. This guide covers the complete technical integration process for accepting Tamara payments through the Onerway payment gateway, from prerequisites to production deployment.

Technical Characteristics:

Payment flow: Redirect-based (buy now pay later service)
Supported countries: AE (United Arab Emirates), KW (Kuwait), SA (Saudi Arabia)
Supported currencies: AED (UAE Dirham), KWD (Kuwaiti Dinar), SAR (Saudi Riyal)
Settlement currency: USD (US Dollar)
Transaction amount: Single transaction range 0.1-10000 SAR (or equivalent in other supported currencies)
Transaction type: Real-time
Integration method: REST API

Supported Features:

One-time payments
Buy now pay later service
Physical goods transactions (logistics upload required for settlement)
Virtual goods transactions (no logistics required)

Not Supported:

Subscription payments

Settlement Process Requirements

Tamara has special settlement requirements based on product type:

Physical Goods Transactions: After successful payment, you must upload signed delivery information to trigger fund settlement
Virtual Goods Transactions: No logistics information needed; settlement processes automatically after payment success
Order Status Requirement: Physical goods orders must reach success status before uploading logistics information
Upload Timing: For physical goods, must upload within 30 days after package delivery

For detailed logistics upload process, see Logistics Information Upload.

Technical Prerequisites

Ensure your system meets these requirements before starting integration:

Infrastructure Requirements

HTTPS-enabled endpoints (TLS 1.2 or higher)
Public-accessible webhook endpoint for receiving notifications
Ability to generate and verify SHA256 signatures
UTF-8 character encoding support

Integration Requirements

Onerway merchant account with Tamara enabled
API credentials (merchant number and secret key)
Sandbox environment access for testing
Support for HTTP redirects (302/303 status codes)

Optional Enhancements

Arabic language support for improved user experience
Mobile app deep linking support
Right-to-left (RTL) UI layout

Technical Configuration

Step 1: API Credentials Setup

Obtain the following credentials from Onerway:

merchantNo: Your unique merchant identifier
secretKey: Used for request/response signature generation
API endpoint URLs (sandbox and production)

Step 2: Webhook Configuration

Configure your webhook endpoint to receive payment notifications:

Endpoint URL: Must be publicly accessible via HTTPS
Supported methods: POST
Content-Type: application/json
Response requirement: Return HTTP 200 with JSON body containing transactionId

Example webhook configuration:

Webhook URL: https://your-domain.com/api/webhooks/onerway
Method: POST
Timeout: 30 seconds
Retry: 3 attempts (30-minute intervals)

Step 3: Return URL Configuration

Set up URLs for customer redirects after payment:

returnUrl: Where customers are redirected after payment (success or failure)
Query parameters will include: transactionId, status, merchantTxnId

Transaction Status Polling

After receiving the redirect to returnUrl, merchants can actively poll the transaction status by calling the Transaction Query API to verify the final payment status, rather than relying solely on the redirect parameters.

Integration Flow

The Tamara integration follows a redirect-based payment flow:

Payment Flow Diagram

Flow Steps Explained

Phase 1: Payment Initiation

Customer selects Tamara as payment method
Merchant sends payment request to Onerway API
Onerway creates payment session with Tamara
Onerway returns redirect URL

Phase 2: Customer Authentication

Merchant redirects customer to Tamara payment page
Customer selects installment plan for authentication
Customer confirms payment in Tamara
Tamara redirects back to merchant

Phase 3: Payment Confirmation

Tamara notifies Onerway of result
Onerway sends webhook to merchant
Merchant acknowledges webhook
Merchant displays result to customer

Phase 4: Settlement Confirmation (Physical Goods)

Merchant uploads logistics information after package delivery
Onerway verifies logistics information validity
Settlement process automatically triggered

Virtual Goods

Virtual goods transactions do not require Phase 4; settlement processes automatically after payment success.

Important

Always rely on webhook notifications for final payment status
The redirect back to your site may not accurately reflect the payment outcome
Physical goods: Logistics information must be uploaded after successful payment to trigger settlement, see Logistics Information Upload
Virtual goods: Settlement processes automatically after payment success, no additional action needed

Tamara Special Requirements

Tamara payment requires the following configuration and parameters:

lpmsInfo Configuration

Set the lpmsInfo parameter to identify Tamara:

json

"lpmsInfo": "{\"lpmsType\":\"tamara\"}"

Required Parameters

The following parameters are required for Tamara payment:

merchantCustId

Unique customer identifier in merchant system.

txnOrderMsg

Must include the following fields:

customerPlatform - Merchant platform identifier
- Web: Domain name (e.g., merchant.example.com)
- App: Application name (e.g., Merchant iOS App)
products - Product information
- type: Product type (physical or virtual), affects settlement process
- productAvatarUrl: Product image URL

View Products for complete field definitions

billingInformation

Required for both physical and virtual goods:

firstName, lastName, phone, email

View TransactionAddress for complete field definitions

shippingInformation

Required for both physical and virtual goods:

firstName, lastName, phone
country, city, address, postalCode

View TransactionAddress for complete field definitions

Different Scenarios

Physical GoodsVirtual Goods

json

{
  "merchantCustId": "customer_12345", // Required
  "lpmsInfo": "{\"lpmsType\":\"tamara\"}", // Tamara identifier
  "billingInformation": "{\"firstName\":\"Ahmad\",\"lastName\":\"Al-Salem\",\"phone\":\"966501234567\",\"email\":\"customer@example.com\"}", // firstName, lastName, phone, email always required
  "shippingInformation": "{\"firstName\":\"Ahmad\",\"lastName\":\"Al-Salem\",\"phone\":\"966501234567\",\"country\":\"SA\",\"city\":\"Riyadh\",\"address\":\"King Fahd Road\",\"postalCode\":\"12345\"}", // Complete shipping info always required
  "txnOrderMsg": "{\"customerPlatform\":\"merchant.example.com\",\"products\":\"[{\\\"type\\\":\\\"physical\\\",\\\"productAvatarUrl\\\":\\\"https://cdn.example.com/product.jpg\\\"}]\"}" // type=physical, productAvatarUrl required
}

json

{
  "merchantCustId": "customer_12345", // Required
  "lpmsInfo": "{\"lpmsType\":\"tamara\"}", // Tamara identifier
  "billingInformation": "{\"firstName\":\"Ahmad\",\"lastName\":\"Al-Salem\",\"phone\":\"966501234567\",\"email\":\"customer@example.com\"}", // phone, email also required for virtual goods
  "shippingInformation": "{\"firstName\":\"Ahmad\",\"lastName\":\"Al-Salem\",\"phone\":\"966501234567\",\"country\":\"SA\",\"city\":\"Riyadh\",\"address\":\"King Fahd Road\",\"postalCode\":\"12345\"}", // Complete shipping info required even for virtual goods
  "txnOrderMsg": "{\"customerPlatform\":\"merchant.example.com\",\"products\":\"[{\\\"type\\\":\\\"virtual\\\",\\\"productAvatarUrl\\\":\\\"https://cdn.example.com/product.jpg\\\"}]\"}" // type=virtual, productAvatarUrl required
}

Product Type Affects Settlement

physical (Physical Goods): Logistics information must be uploaded after successful payment to trigger settlement
virtual (Virtual Goods): Settlement processes automatically after payment success

Important: Regardless of product type, Tamara requires complete customer information (both billingInformation and shippingInformation).

View StoreProductTypeEnum for type enumeration values

API Request Parameters

POST

Key Parameters

For Tamara integration, you must set:

productType: LPMS
lpmsInfo: JSON string containing lpmsType set to tamara
orderCurrency: AED, KWD, or SAR
orderAmount: Single transaction range 0.1-10000 SAR (or equivalent in other supported currencies)

Standard Request Parameters

For complete standard LPMS parameters, please refer to Local Payment Methods documentation.

Parameter	Type	Length	Required	Signed	Description
billingInformation	String	/	Yes	Yes	Transaction billing information in JSON string format. See TransactionAddress for complete structure.
lpmsInfo	String	/	Conditional	Yes	Local payment method information in JSON string format. See LpmsInfo for complete structure.
merchantNo	String	20	Yes	Yes	Merchant number assigned by `Onerway` upon registration, obtained from the `Onerway` merchant dashboard.
merchantTxnId	String	64	Yes	Yes	Unique transaction identifier for each customer payment, generated by the merchant system.
merchantTxnOriginalId	String	128	No	Yes	Master transaction ID generated by merchant for grouping related transactions.
merchantTxnTime	String	/	No	Yes	Transaction timestamp when the merchant initiated the transaction.
merchantTxnTimeZone	String	64	No	Yes	Transaction timezone offset for the merchant transaction time.
mpiInfo	String	/	Conditional	Yes	3DS verification result information in JSON string format. See MpiInfo for complete structure.
orderAmount	String	19	Yes	Yes	Transaction amount in the specified currency, formatted as a decimal string.
orderCurrency	String	8	Yes	Yes	Three-letter currency code according to ISO 4217 standard for the transaction amount.
osType	String	16	Conditional	Yes	Operating system type for mobile and app-based transactions. See OsTypeEnum for available options.
paymentMode	String	16	No	Yes	Payment mode indicating the platform or environment for the transaction. See PaymentModeEnum for all available options.
productType	String	16	Yes	Yes	Payment method category that determines which payment options are available to customers. See ProductTypeEnum for all available options.
risk3dsStrategy	String	16	Conditional	Yes	3DS risk control strategy for fraud prevention. See Risk3dsStrategyEnum for available options.
shippingInformation	String	/	Yes	Yes	Transaction shipping information in JSON string format. See TransactionAddress for complete structure.
sign	String	/	Yes	No	Digital signature string for request verification and security. Please refer to Signature for signature generation method.
subProductType	String	16	Yes	Yes	Specific implementation method within the selected product type, defining how the payment is processed. See SubProductTypeEnum for all available options.
subscription	String	/	Conditional	Yes	Subscription configuration in JSON format including frequency, billing cycle, and subscription type (managed / self-managed).
txnOrderMsg	String	/	Yes	Yes	Transaction business information in JSON string format. See TxnOrderMsg for complete structure.
txnType	String	16	Yes	Yes	Transaction type that defines the payment operation to be performed. See TxnTypeEnum for all available options and detailed usage scenarios.

lpmsInfo Parameter Details

lpmsInfo is a JSON string for Tamara payment configuration:

Parameter	Type	Required	Description
lpmsType	String	Yes	Fixed value `tamara`

Response

The API returns a JSON response with standard Onerway response fields. For Tamara transactions, pay special attention to the status and actionType fields to determine the next action required.

Name	Type	Description
respCode	String	Response code from `Onerway`
respMsg	String	Response message from `Onerway`
data	Object	Response data. Refer to object data

data

The data object in the response contains detailed transaction information:

Name	Type	Description
transactionId	String	Transaction ID created by `Onerway`
responseTime	String	Response timestamp Format: `yyyy-MM-dd HH:mm:ss`
txnTime	String	Transaction initiation time Format: `yyyy-MM-dd HH:mm:ss`
txnTimeZone	String	Transaction timezone Format: `+/-HH:mm`
orderAmount	String	Order amount
orderCurrency	String	Order currency Refer to ISO 4217 currency codes
txnAmount	String	Settlement amount
txnCurrency	String	Settlement currency Refer to ISO 4217 currency codes
status	String	Transaction status Refer to TxnStatusEnum
redirectUrl	String	Payment redirect URL
contractId	String	Subscription contract ID
tokenId	String	Payment token
eci	String	Electronic Commerce Indicator
periodValue	String	Installment periods
codeForm	String	Code form See CodeFormEnum
presentContext	String	Presentation context
actionType	String	Required action See ActionTypeEnum
subscriptionManageUrl	String	Subscription management URL
sign	String	Response signature Refer to the Signature documentation

Response Handling

Tamara transactions typically return status=R with actionType=RedirectURL. You must redirect the customer to complete payment on the Tamara payment page.

API Usage Examples

Standard Payment Request

RequestResponse - RedirectAsync Notification

json

{
  "merchantNo": "800209", // Merchant number from Onerway
  "merchantCustId": "1763979160000", // Unique customer identifier
  "merchantTxnId": "1763979160000", // Unique transaction ID
  "merchantTxnTime": "2025-11-24 18:12:40", // Transaction time
  "orderAmount": "250.00", // Order amount (0.1-10000 SAR)
  "orderCurrency": "SAR", // Supports SAR, AED, KWD
  "productType": "LPMS", // Local payment method
  "subProductType": "DIRECT",
  "lpmsInfo": "{\"lpmsType\":\"tamara\"}", // Tamara configuration
  "billingInformation": "{\"firstName\":\"xxx\",\"lastName\":\"xxx\",\"phone\":\"966501234567\",\"email\":\"abel.wang@onerway.com\",\"postalCode\":\"35802\",\"address\":\"test\",\"country\":\"SA\",\"province\":\"AS\",\"city\":\"city\",\"street\":\"Amsterdam Ave\",\"number\":10}", // Complete billing info (always required)
  "shippingInformation": "{\"firstName\":\"xxx\",\"lastName\":\"xxx\",\"phone\":\"966501234567\",\"email\":\"abel.wang@onerway.com\",\"postalCode\":\"35802\",\"address\":\"test\",\"country\":\"SA\",\"province\":\"AS\",\"city\":\"city\",\"street\":\"Amsterdam Ave\",\"number\":10}", // Complete shipping info (always required)
  "txnOrderMsg": "{\"returnUrl\":\"https://merchant.com/return\",\"notifyUrl\":\"https://www.merchant-store-website.com/\",\"appId\":\"1727880846378401792\",\"customerPlatform\":\"merchant.example.com\",\"products\":\"[{\\\"name\\\":\\\"iPhone 15\\\",\\\"price\\\":\\\"250.00\\\",\\\"num\\\":\\\"1\\\",\\\"currency\\\":\\\"SAR\\\",\\\"type\\\":\\\"physical\\\",\\\"productAvatarUrl\\\":\\\"https://cdn.merchant.com/iphone15.jpg\\\"}]\"}", // Tamara required fields
  "txnType": "SALE",
  "sign": "1d307518fd390f91945887eaa681d65f1e317dedfece5f537fc2a4b4c538bfca" // Request signature
}

json

{
  "respCode": "20000", // Success code
  "respMsg": "Success",
  "data": {
    "transactionId": "1992899161619828736", // Onerway transaction ID
    "responseTime": "2025-11-24 18:12:41",
    "txnTime": "2025-11-24 18:12:41",
    "txnTimeZone": "+08:00",
    "orderAmount": "250.00",
    "orderCurrency": "SAR",
    "txnAmount": null,
    "txnCurrency": null,
    "status": "R", // Redirect required
    "redirectUrl": "https://cashier-dev.gccpay.cn/en-US/order/ORD251124131241558257507", // Tamara payment page URL
    "contractId": null,
    "tokenId": null,
    "eci": null,
    "periodValue": null,
    "codeForm": null,
    "presentContext": null,
    "actionType": "RedirectURL", // Action type: Redirect
    "subscriptionManageUrl": null,
    "sign": "39dc0cd41a050f297a9300e46e980f66edbd3bb740b0c09d3e404c5a40d48946"
  }
}

json

{
  "notifyType": "TXN",
  "transactionId": "1992899161619828736", // Onerway transaction ID
  "txnType": "SALE",
  "merchantNo": "800209",
  "merchantTxnId": "1763979160000",
  "responseTime": "2025-11-24 18:16:16",
  "txnTime": "2025-11-24 18:12:41",
  "txnTimeZone": "+08:00",
  "orderAmount": "250.00",
  "orderCurrency": "SAR",
  "status": "S", // Success status
  "reason": "{\"respCode\":\"20000\",\"respMsg\":\"Success\"}",
  "sign": "a12a1a4d704b0f8e2b1c1b23b504d6f064a704a7b4627f999f852d2e08a8ed45", // Verify signature
  "paymentMethod": "tamara", // Payment method
  "walletTypeName": "tamara", // Wallet type name
  "channelRequestId": "8002091992899163351810049"
}

Technical Integration Checklist

Before deploying to production:

API Integration

Payment request API implemented and tested
Request signature generation working correctly
Error response handling implemented
Redirect flow implemented (handle status=R)
Supported countries and currencies validation implemented (AE/AED, KW/KWD, SA/SAR)
Transaction amount limit validation implemented (0.1-10000 SAR or equivalent)

Tamara Special Requirements

Product information includes type field (physical or virtual)
Product information includes productAvatarUrl field (HTTPS image URL)
txnOrderMsg includes customerPlatform field (domain for web, app name for app)
Regardless of product type, billingInformation includes complete info (firstName, lastName, phone, email)
Regardless of product type, shippingInformation includes complete info (firstName, lastName, phone, country, city, address, postalCode)
Physical goods: Logistics information upload API implemented
Physical goods: Package delivery status verification implemented
Physical goods: Order final status checking implemented
Physical goods: Logistics upload timing control implemented (within 30 days)

Webhook Implementation

Webhook endpoint publicly accessible via HTTPS
Webhook signature verification implemented
Idempotent webhook processing implemented
Webhook acknowledgment returns HTTP 200 with transactionId
Asynchronous processing for webhook payload

Security

TLS 1.2 or higher enabled
API credentials stored securely
Signature verification tested
No sensitive data logged in plain text

Testing Validation

Successful payment scenario tested
Failed payment scenario tested
Timeout scenario tested
Webhook delivery tested
Duplicate transaction prevention tested
Redirect flow tested on mobile devices
Supported countries and currencies testing completed

Monitoring & Operations

API request/response logging implemented
Error monitoring and alerting configured
Transaction status tracking implemented
Webhook retry mechanism implemented

Technical Support

For technical integration assistance, contact Onerway technical support with your merchantNo and specific technical questions.

Android SDK

Local Payment Methods

Apple Pay

Payment Flow

Google Pay

Tamara Integration ​

Overview ​

Technical Prerequisites ​

Infrastructure Requirements ​

Integration Requirements ​

Optional Enhancements ​

Technical Configuration ​

Step 1: API Credentials Setup ​

Step 2: Webhook Configuration ​

Step 3: Return URL Configuration ​

Integration Flow ​

Payment Flow Diagram ​

Flow Steps Explained ​

Phase 1: Payment Initiation ​

Phase 2: Customer Authentication ​

Phase 3: Payment Confirmation ​

Phase 4: Settlement Confirmation (Physical Goods) ​

Tamara Special Requirements ​

lpmsInfo Configuration ​

Required Parameters ​

merchantCustId ​

txnOrderMsg ​

billingInformation ​

shippingInformation ​

Different Scenarios ​

API Request Parameters ​

Standard Request Parameters ​

lpmsInfo Parameter Details ​

Response ​

data ​

API Usage Examples ​

Standard Payment Request ​

Technical Integration Checklist ​

API Integration ​

Tamara Special Requirements ​

Webhook Implementation ​

Security ​

Testing Validation ​

Monitoring & Operations ​

Tamara Integration

Overview

Technical Prerequisites

Infrastructure Requirements

Integration Requirements

Optional Enhancements

Technical Configuration

Step 1: API Credentials Setup

Step 2: Webhook Configuration

Step 3: Return URL Configuration

Integration Flow

Payment Flow Diagram

Flow Steps Explained

Phase 1: Payment Initiation

Phase 2: Customer Authentication

Phase 3: Payment Confirmation

Phase 4: Settlement Confirmation (Physical Goods)

Tamara Special Requirements

lpmsInfo Configuration

Required Parameters

merchantCustId

txnOrderMsg

billingInformation

shippingInformation

Different Scenarios

API Request Parameters

Standard Request Parameters

lpmsInfo Parameter Details

Response

data

API Usage Examples

Standard Payment Request

Technical Integration Checklist

API Integration

Tamara Special Requirements

Webhook Implementation

Security

Testing Validation

Monitoring & Operations