Payment Engine API Documentation

Introduction

Payment Engine is a centralized payment gateway service that lets you process payments through SSLCommerz, bKash, and Stripe from a single REST API. Instead of integrating each gateway inside every project, you create a project in Payment Engine, configure one or more gateways, and use the API to initiate and track payments.

Authentication

All payment API requests are authenticated using Client Key and Secret Key pair. These keys are generated when you create a project.

Create Payment

Initiate a new payment by calling the create payment endpoint.

Request Body

Gateway Selection

You can use Payment Engine in two ways:

Supported values

• sslcommerz — redirects are finalized through Payment Engine callbacks (/success, /fail, /cancel).
• bkash — uses bKash callback (/bkash/callback) to finalize status.
• stripe — uses Stripe Checkout + webhook (/stripe/webhook) to finalize status.

Required Headers

Content-Type: application/json
x-client-key: ck_your_client_key_here
x-secret-key: sk_your_secret_key_here

Example Request

curl -X POST https://payment.progedify.com/api/v1/payment/create \
  -H "Content-Type: application/json" \
  -H "x-client-key: ck_a1b2c3d4e5f6g7h8i9j0" \
  -H "x-secret-key: sk_k1l2m3n4o5p6q7r8s9t0u1v2w3x4y5z6" \
  -d '{
    "gateway": "sslcommerz",
    "amount": 500,
    "currency": "BDT",
    "customerName": "John Doe",
    "customerEmail": "john@example.com",
    "customerPhone": "01700000000"
  }'

Example Response

Success (200)

{
  "success": true,
  "statusCode": 200,
  "message": "Payment initiated successfully",
  "data": {
    "transactionId": "txn_1709912345_a1b2c3d4e5f6",
    "gatewayUrl": "https://..."
  }
}

Redirect the user to gatewayUrl to complete the payment on the selected gateway.

Payment Flow

Redirect Flow

After payment, the user is redirected to the URLs configured in your project. Redirect query parameters vary by gateway.

SSLCommerz / bKash

Payment Engine finalizes the status and redirects with status (and sometimes amount):

https://your-app.com/payment/success?transactionId=txn_xxx&status=success&amount=500
https://your-app.com/payment/fail?transactionId=txn_xxx&status=failed
https://your-app.com/payment/cancel?transactionId=txn_xxx&status=cancelled

Stripe

Stripe redirect URLs include transactionId. Final payment status is confirmed via webhook + status query:

https://your-app.com/payment/success?transactionId=txn_xxx
https://your-app.com/payment/cancel?transactionId=txn_xxx

Stripe Webhook

Stripe payments are finalized through a webhook event. Configure Stripe to send events to:

https://payment.progedify.com/api/v1/payment/stripe/webhook

Query Payments

GET List Payments

GET /api/v1/payment/list
Headers: x-client-key, x-secret-key

GET Get Payment Status

GET /api/v1/payment/status/:transactionId
Headers: x-client-key, x-secret-key

Security Best Practices

• Never expose your Secret Key in client-side code.
• Always call the payment API from your backend server.
• Verify payment status from your backend using GET /api/v1/payment/status/:transactionId before fulfilling orders.
• Use HTTPS for all API communication.
• Store your keys in environment variables, never in source code.
• Rotate keys if you suspect a breach — create a new project and migrate.

Gateway Setup Guide (Step by Step)

This tutorial is designed for beginners. Follow each step and add your screenshot inside every placeholder box.

Prerequisites

Callback and Webhook URL Reference

Replace https://YOUR_SERVER_DOMAIN with your real public server URL.

Configure in Payment Engine Project

Step 1

Set Redirect URLs

Set these fields in project configuration: successUrl, failUrl, cancelUrl.

Step 2

Enable Gateways and Save Keys

Enable required gateways and add credentials for each one.

Example Payload

{
  "projectName": "My Shop",
  "successUrl": "https://merchant.example.com/payment/success",
  "failUrl": "https://merchant.example.com/payment/fail",
  "cancelUrl": "https://merchant.example.com/payment/cancel",
  "gateways": {
    "stripe": {
      "enabled": true,
      "secretKey": "sk_test_xxx",
      "webhookSecret": "whsec_xxx"
    },
    "sslcommerz": {
      "enabled": true,
      "storeId": "your_store_id",
      "storePass": "your_store_pass",
      "paymentApi": "https://sandbox.sslcommerz.com/gwprocess/v4/api.php",
      "validationApi": "https://sandbox.sslcommerz.com/validator/api/validationserverAPI.php"
    },
    "bkash": {
      "enabled": true,
      "appKey": "your_app_key",
      "appSecret": "your_app_secret",
      "username": "your_username",
      "password": "your_password",
      "callbackUrl": "https://pay.example.com/api/v1/payment/bkash/callback"
    },
    "crypto": {
      "enabled": true,
      "apiKey": "your_nowpayments_api_key",
      "ipnKey": "your_nowpayments_ipn_key",
      "apiUrl": "https://api.nowpayments.io/v1"
    }
  }
}

Troubleshooting