Home › API Docs
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.

Production environment

API endpoints

ItemValue
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.

1

Sign in

Open your merchant account.

2

Open Brands

Go to Merchant Dashboard → Brands.

3

Create / select brand

Set the real website domain for that brand.

4

Copy Brand Key

Use it only from your server-side integration.

Supported authentication methods

MethodValueUse
API-KEY headerAPI-KEY: YOUR_BRAND_KEYRecommended.
api_key parameter?api_key=YOUR_BRAND_KEYSupported 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.

POSThttps://pay.sofolx.com/api

Request fields

FieldTypeRequiredLive behaviour
amountnumberRequiredMust be numeric, greater than 0 and not over 1,000,000 BDT.
success_urlURLRequiredCustomer return URL for pending/completed flow. Domain must match the Brand website domain.
cancel_urlURLRequiredCustomer return URL for cancelled/failed flow. Domain must match the Brand website domain.
cus_namestringOptionalCustomer name. Live API supplies a default if omitted.
cus_emailstringOptionalCustomer email. Live API supplies a default if omitted.
cus_phonestringOptionalCustomer phone number.
webhook_urlURLOptionalBackend callback URL. When supplied, domain must match the Brand website domain.
metadataJSON objectOptionalMerchant 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.

POSThttps://pay.sofolx.com/api/verify
FieldTypeRequiredDescription
transaction_idstringRequiredThe 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

FieldReturned value
cus_nameCustomer name stored on the payment.
cus_emailCustomer email stored on the payment.
amountPayment amount.
transaction_idSofolX transaction reference.
metadataMerchant metadata stored at creation.
payment_methodDetected/processed payment method when available.
statusPENDING, 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.

1

Create order

2

Create payment

3

Redirect customer

4

Payment processed

5

Webhook received

6

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.

PENDINGWaiting or still processing.
COMPLETEDPayment confirmed.
CANCELEDCustomer/payment flow cancelled.
FAILEDPayment flow failed.
ERRORUnexpected/unknown status mapping.

Common API errors

HTTPCodeMeaning
401INVALID_API_KEYMissing or invalid Brand Key.
403PLAN_EXPIRED / PLAN_REQUIRED / BRAND_INACTIVEBrand/account does not currently have access.
404TRANSACTION_NOT_FOUNDThe transaction does not belong to the Brand or cannot be found.
422REQUIRED_FIELD_MISSINGRequired verify field is missing.
422INVALID_PARAMETERSCreate 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