Payment Gateway API Documentation Bangladesh

LIVE API

SofolX API Docs

sofolx.com is the official SofolX platform. Use this guide to create hosted payment sessions, redirect customers to SofolX checkout, verify transactions from your server, and handle callbacks securely.

Brand Keys

Overview Create Payment Verify Payment Webhook Flow Production Apps & Plugins

Production environment

API endpoints

Main websitehttps://sofolx.com

Gateway base URLhttps://pay.sofolx.com

CreatePOST /api

VerifyPOST /api/verify

Authentication

Every API call is authenticated with the merchant Brand Key created inside the SofolX dashboard. The secret key is never embedded into this public documentation.

Sign inOpen your merchant account.

Open BrandsGo to Merchant Dashboard → Brands.

Create / select brandSet the real website domain for that brand.

Copy Brand KeyUse it only from your server-side integration.

Supported authentication methods

Method	Value	Use
`API-KEY` header	`API-KEY: YOUR_BRAND_KEY`	Recommended.
`api_key` parameter	`?api_key=YOUR_BRAND_KEY`	Supported by the live API.

Keep your Brand Key privateStore it on your backend or in environment variables. Public examples use YOUR_BRAND_KEY as a placeholder.

Create Payment

Create a hosted SofolX payment session and receive a payment_url that you redirect the customer to.

POSThttps://pay.sofolx.com/api

Request fields

Field	Type	Required	Live behaviour
`amount`	number	Required	Must be numeric, greater than 0 and not over 1,000,000 BDT.
`success_url`	URL	Required	Customer return URL for pending/completed flow. Domain must match the Brand website domain.
`cancel_url`	URL	Required	Customer return URL for cancelled/failed flow. Domain must match the Brand website domain.
`cus_name`	string	Optional	Customer name. Live API supplies a default if omitted.
`cus_email`	string	Optional	Customer email. Live API supplies a default if omitted.
`cus_phone`	string	Optional	Customer phone number.
`webhook_url`	URL	Optional	Backend callback URL. When supplied, domain must match the Brand website domain.
`metadata`	JSON object	Optional	Merchant metadata stored with the temporary payment session.

curl -X POST "https://pay.sofolx.com/api" \ -H "Content-Type: application/json" \ -H "API-KEY: YOUR_BRAND_KEY" \ -d '{ "amount": 500, "cus_name": "John Doe", "cus_email": "john@example.com", "cus_phone": "01700000000", "success_url": "https://merchant.example/payment/success", "cancel_url": "https://merchant.example/payment/cancel", "webhook_url": "https://merchant.example/api/sofolx/webhook", "metadata": {"order_id":"ORD-1001"} }'

$payload = [ 'amount' => 500, 'cus_name' => 'John Doe', 'cus_email' => 'john@example.com', 'success_url' => 'https://merchant.example/payment/success', 'cancel_url' => 'https://merchant.example/payment/cancel', 'webhook_url' => 'https://merchant.example/api/sofolx/webhook', 'metadata' => (object)['order_id' => 'ORD-1001'],];$ch = curl_init('https://pay.sofolx.com/api');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'API-KEY: YOUR_BRAND_KEY'], CURLOPT_POSTFIELDS => json_encode($payload),]);$response = curl_exec($ch);

const response = await fetch('https://pay.sofolx.com/api', { method: 'POST', headers: { 'Content-Type': 'application/json', 'API-KEY': 'YOUR_BRAND_KEY' }, body: JSON.stringify({ amount: 500, cus_name: 'John Doe', cus_email: 'john@example.com', success_url: 'https://merchant.example/payment/success', cancel_url: 'https://merchant.example/payment/cancel', webhook_url: 'https://merchant.example/api/sofolx/webhook', metadata: {order_id: 'ORD-1001'} })});const data = await response.json();

Success response

JSON

{ "status": 1, "message": "Payment Link", "payment_url": "https://pay.sofolx.com/api/execute/PAYMENT_SESSION_ID"}

Domain validationThe gateway validates success_url, cancel_url and any supplied webhook_url against the website domain saved on the Brand.

Verify Payment

Verify the SofolX transaction from your backend before updating your order or service.

POSThttps://pay.sofolx.com/api/verify

Field	Type	Required	Description
`transaction_id`	string	Required	The SofolX transaction reference returned by the payment flow.

curl -X POST "https://pay.sofolx.com/api/verify" \ -H "Content-Type: application/json" \ -H "API-KEY: YOUR_BRAND_KEY" \ -d '{"transaction_id":"TRANSACTION_ID"}'

$ch = curl_init('https://pay.sofolx.com/api/verify');curl_setopt_array($ch, [ CURLOPT_POST => true, CURLOPT_RETURNTRANSFER => true, CURLOPT_HTTPHEADER => ['Content-Type: application/json', 'API-KEY: YOUR_BRAND_KEY'], CURLOPT_POSTFIELDS => json_encode(['transaction_id' => 'TRANSACTION_ID']),]);$response = curl_exec($ch);

const response = await fetch('https://pay.sofolx.com/api/verify', { method: 'POST', headers: {'Content-Type':'application/json','API-KEY':'YOUR_BRAND_KEY'}, body: JSON.stringify({transaction_id: 'TRANSACTION_ID'})});const result = await response.json();

Verify response fields

Field	Returned value
`cus_name`	Customer name stored on the payment.
`cus_email`	Customer email stored on the payment.
`amount`	Payment amount.
`transaction_id`	SofolX transaction reference.
`metadata`	Merchant metadata stored at creation.
`payment_method`	Detected/processed payment method when available.
`status`	`PENDING`, `COMPLETED`, `CANCELED`, `FAILED` or `ERROR`.

Webhook & Redirect Flow

When the live payment flow is processed, SofolX sends the merchant callback fields below and also appends matching status information to the customer redirect URL.

Webhook payload

{ "paymentMethod": "bkash", "transactionId": "TRANSACTION_ID", "paymentAmount": 500, "paymentFee": 0, "status": "completed"}

Customer redirect query fields

The gateway adds paymentMethod, transactionId, paymentAmount, paymentFee and status to the configured success/cancel URL.

Create order

Create payment

Redirect customer

Payment processed

Webhook received

Verify API

Recommended merchant behaviourTreat the webhook/redirect as a signal, then call https://pay.sofolx.com/api/verify from your backend and act on the returned status.

Errors & Status

Use these statuses and error codes when handling API responses from the gateway.

PENDING

Waiting or still processing.

COMPLETED

Payment confirmed.

CANCELED

Customer/payment flow cancelled.

FAILED

Payment flow failed.

ERROR

Unexpected/unknown status mapping.

Common API errors

HTTP	Code	Meaning
401	`INVALID_API_KEY`	Missing or invalid Brand Key.
403	`PLAN_EXPIRED / PLAN_REQUIRED / BRAND_INACTIVE`	Brand/account does not currently have access.
404	`TRANSACTION_NOT_FOUND`	The transaction does not belong to the Brand or cannot be found.
422	`REQUIRED_FIELD_MISSING`	Required verify field is missing.
422	`INVALID_PARAMETERS`	Create request contains invalid or missing parameters.