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.
Production environment
API endpoints
| Item | Value |
|---|---|
| Main website | https://sofolx.com |
| Gateway base URL | https://pay.sofolx.com |
| Create | POST /api |
| Verify | POST /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 in
Open your merchant account.
Open Brands
Go to Merchant Dashboard → Brands.
Create / select brand
Set the real website domain for that brand.
Copy Brand Key
Use 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 private
Store 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.
https://pay.sofolx.com/apiRequest 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
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": "[email protected]", "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"} }' Success response
{ "status": 1, "message": "Payment Link", "payment_url": "https://pay.sofolx.com/api/execute/PAYMENT_SESSION_ID"} Domain validation
The 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.
https://pay.sofolx.com/api/verify| Field | Type | Required | Description |
|---|---|---|---|
transaction_id | string | Required | The SofolX transaction reference returned by the payment flow. |
cURL
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"}' 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 behaviour
Treat 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.
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. |
Production Checklist
Complete these checks before enabling SofolX on a production merchant website.
- Store the Brand Key only on the merchant backend.
- Save the correct merchant website domain under Brands.
- Use HTTPS success, cancel and webhook URLs.
- Redirect customers only to the returned payment_url.
- Verify every transaction before fulfilment.
- Handle duplicate webhook calls idempotently.
Apps & Integrations
Download and integration links are managed from SofolX Admin → Apps/Plugin and reflected on the live page.
SofolX Android App
Merchant device application link.
WordPress Plugin
WordPress/WooCommerce integration.
cPanel Integration
cPanel integration package.
Shopify Integration
Merchant Shopify integration area inside SofolX.
Support
Main: https://sofolx.com • Gateway: https://pay.sofolx.com
[email protected] • +966531270392