Developer · API v1

API Document Guide

Complete documentation to integrate FIREPAY Gateway deposits, withdrawals, statements, and webhooks for Bangladesh currency (BDT).

Version v1Format JSONWallets: 4Base {API_HOST}/v1

Confidential — for integrating merchant developers · Last updated July 2026

Technical API payloads, field names, and code samples remain in English for integration accuracy.

Overview

FIREPAY Gateway lets your platform accept mobile-wallet deposits and send withdrawals to customer wallet numbers in Bangladesh (BDT).

Deposits

Your server creates a deposit via API → customer is redirected to a hosted payment page → customer cashes out to an agent wallet and submits their TrxID → FIREPAY automatically verifies and approves the deposit

Withdrawals

Your server creates a withdrawal via API (status pending) → admin releases to an agent (processing) → agent approves or rejects → every status change is sent to your webhook

Statements

Your server requests a date-range summary (Opening, Deposit, Withdraw, Fee, Settlement, Adjustment, Closing) — scoped to your API key only

Integration

Server-to-server REST API authenticated with an API key

Concern	How it works
Deposits	Your server creates a deposit via API → customer is redirected to a hosted payment page → customer cashes out to an agent wallet and submits their TrxID → FIREPAY automatically verifies and approves the deposit
Withdrawals	Your server creates a withdrawal via API (status pending) → admin releases to an agent (processing) → agent approves or rejects → every status change is sent to your webhook
Statements	Your server requests a date-range summary (Opening, Deposit, Withdraw, Fee, Settlement, Adjustment, Closing) — scoped to your API key only
Integration	Server-to-server REST API authenticated with an API key

Base URLs

Your FIREPAY administrator provides the production API_HOST and PAYMENT_HOST for your environment. Do not hardcode hosts from public materials.

Production

Commercial API

https://{API_HOST}/v1

Payment page

https://{PAYMENT_HOST}

Local dev

Commercial API

http://localhost:3001/v1

Payment page

http://localhost:5173

Environment	Commercial API	Payment page
Production	https://{API_HOST}/v1	https://{PAYMENT_HOST}
Local dev	http://localhost:3001/v1	http://localhost:5173

All commercial endpoints are prefixed with /v1. Payment pages are served at /deposit/{deposit_id}?token=... on the payment base URL.

Fees

amount

Gross wallet move (what the player paid or received)

fee_percent

Platform fee percent for this client

fee_amount

FIREPAY's share

client_amount

What settles to you (amount − fee_amount)

Field	Meaning
amount	Gross wallet move (what the player paid or received)
fee_percent	Platform fee percent for this client
fee_amount	FIREPAY's share
client_amount	What settles to you (amount − fee_amount)

Authentication

Every commercial API request must include a valid client API key.

Obtaining an API key

Ask your FIREPAY administrator for:

API key
Default webhook URL

Keys are created in the backoffice Clients page. The full API key is shown once at creation — store it securely on your server. Clients do not generate their own keys.

Key format: fp_{prefix}_{secret} (example: fp_a1b2c3d4_xK9mN2pQ7rS4tU8vW1yZ3)

Request headers

Authorization

Bearer fp_xxxxxxxx

X-API-Key

Alternative to Authorization — pass the raw key

Content-Type

application/json

Header	Value
Authorization	Bearer fp_xxxxxxxx
X-API-Key	Alternative to Authorization — pass the raw key
Content-Type	application/json

create-deposit.sh

SHELL

1curl -X POST "https://{API_HOST}/v1/deposits" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  -H "Content-Type: application/json" \
4  -d '{
5    "amount": 500,
6    "wallet": "bkash",
7    "order_id": "ORD-1001",
8    "return_url": "https://yoursite.com/payment/return"
9  }'

Security

Never expose API keys in client-side code, mobile apps, or public repositories. Call FIREPAY only from your backend.

Response format

Success

success.json

JSON

1{
2  "success": true,
3  "data": { }
4}

HTTP status 200 for reads, 201 for creates.

Error

error.json

JSON

1{
2  "success": false,
3  "error": {
4    "code": "VALIDATION_ERROR",
5    "message": "order_id and return_url are required"
6  }
7}

IDs & order references

Understanding these values prevents broken reconciliation after payment.

order_id (request)

Who creates it

You

Example

ORD-1001

Use for

Your unique order reference (must be unique per client)

external_order_id

Who creates it

FIREPAY (echo)

Example

ORD-1001

Use for

Same as your request order_id — match webhooks & return URL to this

order_id (response)

Who creates it

FIREPAY

Example

K7M9P2Q4R5

Use for

Internal FIREPAY order number (10 chars)

deposit_id

Who creates it

FIREPAY

Example

DPABCD1234

Use for

Public deposit ID — DP + 8 characters

withdrawal_id

Who creates it

FIREPAY

Example

WDXYZ98765

Use for

Public withdrawal ID — WD + 8 characters

Field	Who creates it	Example	Use for
order_id (request)	You	ORD-1001	Your unique order reference (must be unique per client)
external_order_id	FIREPAY (echo)	ORD-1001	Same as your request order_id — match webhooks & return URL to this
order_id (response)	FIREPAY	K7M9P2Q4R5	Internal FIREPAY order number (10 chars)
deposit_id	FIREPAY	DPABCD1234	Public deposit ID — DP + 8 characters
withdrawal_id	FIREPAY	WDXYZ98765	Public withdrawal ID — WD + 8 characters

Rules for integrators

Return URL query param order_id is always your original reference (external_order_id).
In JSON responses and webhooks, prefer external_order_id when matching your shop order.
Credit the player only after webhook / GET confirmation — never from the browser redirect alone.

Quick start

Create deposit — POST /v1/deposits with amount, wallet, unique order_id, and return_url.
Redirect customer — Send the user to payment_url from the response.
Customer pays — They cash out to the agent wallet number shown on the page and submit their TrxID.
Auto verification — FIREPAY automatically verifies the payment and updates the deposit status.
Confirm on your server — Trust webhooks (and/or poll GET /v1/deposits/:depositId). Return URL is a UX redirect only — always verify server-side before crediting the player.

sequence.txt

TEXT

1Your server                FIREPAY                 Customer
2     |                          |                       |
3     |-- POST /v1/deposits ---->|                       |
4     |<-- payment_url ----------|                       |
5     |                          |                       |
6     |-- redirect customer ---------------------------->|
7     |                          |<-- cash out + TrxID --|
8     |                          |-- verify + approve ---|
9     |<-- webhook deposit.approved                      |
10     |                          |-- redirect return_url >|

Deposit flow

End-to-end deposit lifecycle between your merchant system and FIREPAY.

Merchant submits deposit — POST /v1/deposits
FIREPAY validates the request
FIREPAY returns payment_url + agent_number with status pending
Merchant processes the response
Merchant redirects the customer to payment_url
Hosted page: customer pays + submits TrxID → Cash Out → automatic verification
FIREPAY approves / rejects / expires
Webhook callback → merchant credits if approved
return_url is UX only — process result server-side

Critical

Never credit from return_url alone — wait for deposit.approved webhook or GET status.

Wallets API

GET/v1/wallets

API key required

Returns branding for bKash / Nagad / Rocket / Upay plus the global deposit countdown minutes.

wallets.response.json

JSON

1{
2  "success": true,
3  "data": {
4    "deposit_expiry_minutes": 15,
5    "wallets": [
6      {
7        "wallet": "bkash",
8        "header_color": "#E2136E",
9        "accent_color": "#E2136E",
10        "logo_path": "uploads/wallet-logos/bkash.png",
11        "logo_url": "https://{CDN_HOST}/uploads/wallet-logos/bkash.png"
12      },
13      {
14        "wallet": "nagad",
15        "header_color": "#F6921E",
16        "accent_color": "#F6921E",
17        "logo_url": "https://{CDN_HOST}/uploads/wallet-logos/nagad.png"
18      },
19      {
20        "wallet": "rocket",
21        "header_color": "#6B2D8B",
22        "accent_color": "#00A651",
23        "logo_url": "https://{CDN_HOST}/uploads/wallet-logos/rocket.png"
24      },
25      {
26        "wallet": "upay",
27        "header_color": "#E31837",
28        "accent_color": "#E31837",
29        "logo_url": "https://{CDN_HOST}/uploads/wallet-logos/upay.png"
30      }
31    ]
32  }
33}

Deposits API

Create deposit

POST/v1/deposits

API key required

amount

Type

number

Required

Yes

Description

Deposit amount in BDT (e.g. 500 or 500.00)

wallet

Type

string

Required

Yes

Description

bkash | nagad | rocket | upay

order_id

Type

string

Required

Yes

Description

Your unique order reference (unique per client)

return_url

Type

string

Required

Yes

Description

HTTPS URL — redirect customer after payment

callback_url

Type

string

Required

Description

Override webhook URL for this deposit only

Field	Type	Required	Description
amount	number	Yes	Deposit amount in BDT (e.g. 500 or 500.00)
wallet	string	Yes	bkash \| nagad \| rocket \| upay
order_id	string	Yes	Your unique order reference (unique per client)
return_url	string	Yes	HTTPS URL — redirect customer after payment
callback_url	string	No	Override webhook URL for this deposit only

create-deposit.response.json

JSON

1{
2  "success": true,
3  "data": {
4    "deposit_id": "DPABCD1234",
5    "order_id": "K7M9P2Q4R5",
6    "external_order_id": "ORD-1001",
7    "status": "pending",
8    "amount": 500,
9    "fee_percent": 5,
10    "fee_amount": 25,
11    "client_amount": 475,
12    "wallet": "bkash",
13    "wallet_label": "bKash",
14    "wallet_logo_url": "https://{CDN_HOST}/uploads/wallet-logos/bkash.png",
15    "wallet_header_color": "#E2136E",
16    "wallet_accent_color": "#E2136E",
17    "agent_number": "01623072275",
18    "payment_url": "https://{PAYMENT_HOST}/deposit/DPABCD1234?token=...",
19    "expires_at": "2026-07-14T15:30:00.000Z",
20    "deposit_expiry_minutes": 15
21  }
22}

deposit_id

Public FIREPAY deposit ID (DP + 8 chars)

order_id

Internal FIREPAY order number

external_order_id

Your original order_id from the request

agent_number

Wallet number the customer must cash out to

payment_url

Hosted payment page — redirect the customer here

expires_at

Deposit session expiry (default 15 minutes, configurable)

client_amount

Amount that settles to you after fee

Field	Description
deposit_id	Public FIREPAY deposit ID (DP + 8 chars)
order_id	Internal FIREPAY order number
external_order_id	Your original order_id from the request
agent_number	Wallet number the customer must cash out to
payment_url	Hosted payment page — redirect the customer here
expires_at	Deposit session expiry (default 15 minutes, configurable)
client_amount	Amount that settles to you after fee

Get deposit status

GET/v1/deposits/:depositId

API key required

Poll this if the customer closes the browser before redirect, or to confirm webhook data.

get-deposit.response.json

JSON

1{
2  "success": true,
3  "data": {
4    "deposit_id": "DPABCD1234",
5    "order_id": "K7M9P2Q4R5",
6    "external_order_id": "ORD-1001",
7    "status": "approved",
8    "amount": 500,
9    "fee_percent": 5,
10    "fee_amount": 25,
11    "client_amount": 475,
12    "wallet": "bkash",
13    "wallet_label": "bKash",
14    "agent_number": "01623072275",
15    "customer_trx_id": "DFC78W6RL3",
16    "return_url": "https://yoursite.com/payment/return",
17    "expires_at": "2026-07-14T15:30:00.000Z",
18    "approved_at": "2026-07-14T15:12:00.000Z",
19    "created_at": "2026-07-14T15:00:00.000Z"
20  }
21}

Submit TrxID (server-side, optional)

POST/v1/deposits/:depositId/submit-trx

Not required (uses page token)

Rate limit: 10 requests per minute per IP. Normally the customer submits TrxID on the hosted payment page. This endpoint is available if you build a custom payment UI.

trx_id

Type

string

Required

Yes

Description

Customer transaction ID from their wallet app

token

Type

string

Required

Yes

Description

Page token from payment_url

Field	Type	Required	Description
trx_id	string	Yes	Customer transaction ID from their wallet app
token	string	Yes	Page token from payment_url

submit-trx.response.json

JSON

1{
2  "success": true,
3  "data": {
4    "deposit_id": "DPABCD1234",
5    "status": "awaiting_sms",
6    "message": "Transaction ID submitted. Awaiting confirmation.",
7    "verification_expires_at": "2026-07-14T15:15:00.000Z"
8  }
9}

If payment is already verified, status may be approved immediately with a return_url in the response (including your original order_id as the query param).

Hosted payment page

Redirect the customer to payment_url. The page is wallet-branded (bKash / Nagad / Rocket / Upay) and shows the assigned agent cash-out number.

Customer sees amount, agent wallet number, and deposit timer

Customer sends money from their wallet app (Cash Out / Send Money)

Customer enters TrxID and taps Submit

If deposit timer hits 00:00 → redirect with status=expired

Verification wait while payment is confirmed

On approval → status=approved; verify timeout → status=rejected

Step	Description
1	Customer sees amount, agent wallet number, and deposit timer
2	Customer sends money from their wallet app (Cash Out / Send Money)
3	Customer enters TrxID and taps Submit
4	If deposit timer hits 00:00 → redirect with status=expired
5	Verification wait while payment is confirmed
6	On approval → status=approved; verify timeout → status=rejected

Return URL query parameters

FIREPAY appends these parameters when redirecting the customer:

status

Example

approved

Description

approved | review | fraud | rejected | expired

deposit_id

Example

DPABCD1234

Description

FIREPAY deposit ID

order_id

Example

ORD-1001

Description

Your original order_id (external_order_id)

Parameter	Example	Description
status	approved	approved \| review \| fraud \| rejected \| expired
deposit_id	DPABCD1234	FIREPAY deposit ID
order_id	ORD-1001	Your original order_id (external_order_id)

return-url.example.txt

TEXT

1https://yoursite.com/payment/return?status=approved&deposit_id=DPABCD1234&order_id=ORD-1001

Do not credit from return URL

Do not credit the player from the return URL alone. Wait for deposit.approved webhook or confirm with GET /v1/deposits/:depositId.

Withdrawal flow

Create → pending (backoffice hold) → admin processing → agent result → webhooks.

Merchant submits withdrawal — POST /v1/withdrawals
FIREPAY validates the request
Status pending — held in backoffice; webhook: withdrawal.pending
Merchant processes the response
Admin sets processing (agent assigned); webhook: withdrawal.processing
Agent/admin approved / rejected — callback result
Merchant completes or refunds

Optional: poll GET /v1/withdrawals/:id if webhook is delayed.

Withdrawals API

Request a payout to a customer mobile-wallet number. Flow: create → status pending (held in backoffice, no agent yet) → admin sets processing (agent assigned) → agent approves or rejects. FIREPAY notifies your webhook on every status change.

Create withdrawal

POST/v1/withdrawals

API key required

amount

Type

number

Required

Yes

Description

Withdrawal amount in BDT

wallet

Type

string

Required

Yes

Description

bkash | nagad | rocket | upay

customer_phone

Type

string

Required

Yes

Description

Recipient wallet number (BD mobile, e.g. 017XXXXXXXX)

order_id

Type

string

Required

Yes

Description

Your unique withdrawal reference (unique per client)

callback_url

Type

string

Required

Description

Override webhook URL for this withdrawal only

Field	Type	Required	Description
amount	number	Yes	Withdrawal amount in BDT
wallet	string	Yes	bkash \| nagad \| rocket \| upay
customer_phone	string	Yes	Recipient wallet number (BD mobile, e.g. 017XXXXXXXX)
order_id	string	Yes	Your unique withdrawal reference (unique per client)
callback_url	string	No	Override webhook URL for this withdrawal only

create-withdrawal.response.json

JSON

1{
2  "success": true,
3  "data": {
4    "withdrawal_id": "WDXYZ98765",
5    "order_id": "N4P6Q8R0S1",
6    "external_order_id": "WDR-9001",
7    "status": "pending",
8    "amount": 1000,
9    "fee_percent": 2,
10    "fee_amount": 20,
11    "client_amount": 980,
12    "wallet": "bkash",
13    "wallet_label": "bKash",
14    "customer_phone": "01712345678",
15    "assigned_agent_id": null,
16    "auto_withdraw": false,
17    "created_at": "2026-07-14T15:00:00.000Z"
18  }
19}

On create, FIREPAY also sends withdrawal.pending to your webhook. Withdrawals do not auto-expire while pending or processing.

Get withdrawal status

GET/v1/withdrawals/:withdrawalId

API key required

get-withdrawal.response.json

JSON

1{
2  "success": true,
3  "data": {
4    "withdrawal_id": "WDXYZ98765",
5    "order_id": "N4P6Q8R0S1",
6    "external_order_id": "WDR-9001",
7    "status": "approved",
8    "amount": 1000,
9    "fee_percent": 2,
10    "fee_amount": 20,
11    "client_amount": 980,
12    "wallet": "bkash",
13    "wallet_label": "bKash",
14    "customer_phone": "01712345678",
15    "agent_trx_id": "8XJ2K9LM",
16    "reject_remarks": null,
17    "expires_at": null,
18    "approved_at": "2026-07-14T15:08:00.000Z",
19    "rejected_at": null,
20    "created_at": "2026-07-14T15:00:00.000Z"
21  }
22}

Statements API

Fetch your Client Summary totals for a date range (same numbers as the FIREPAY Report → Client Summary page).

Security & timezone

Results are always limited to the client that owns the API key. You cannot request another client's data. Calendar days use Asia/Dhaka.

Get statement summary

GET/v1/statements/summary

API key required

from_date

Type

string

Required

Yes

Description

Start date YYYY-MM-DD (inclusive)

to_date

Type

string

Required

Yes

Description

End date YYYY-MM-DD (inclusive)

Parameter	Type	Required	Description
from_date	string	Yes	Start date YYYY-MM-DD (inclusive)
to_date	string	Yes	End date YYYY-MM-DD (inclusive)

statements.response.json

JSON

1{
2  "success": true,
3  "data": {
4    "from_date": "2026-07-28",
5    "to_date": "2026-07-28",
6    "timezone": "Asia/Dhaka",
7    "currency": "BDT",
8    "opening": 3338.8,
9    "deposit": 0,
10    "withdraw": 1100,
11    "fee": 9.9,
12    "settlement": 0,
13    "adjustment": 0,
14    "closing": 2248.7
15  }
16}

opening

Opening balance at the start of from_date

deposit

Approved deposits in the period (gross)

withdraw

Approved withdrawals in the period (gross)

fee

Total fees in the period (deposit + withdraw)

settlement

Client settlements / top-ups net in the period

adjustment

Client adjustments net in the period

closing

Closing balance at the end of to_date

Field	Meaning
opening	Opening balance at the start of from_date
deposit	Approved deposits in the period (gross)
withdraw	Approved withdrawals in the period (gross)
fee	Total fees in the period (deposit + withdraw)
settlement	Client settlements / top-ups net in the period
adjustment	Client adjustments net in the period
closing	Closing balance at the end of to_date

statements.sh

SHELL

1curl -G "https://{API_HOST}/v1/statements/summary" \
2  -H "Authorization: Bearer YOUR_API_KEY" \
3  --data-urlencode "from_date=2026-07-28" \
4  --data-urlencode "to_date=2026-07-28"

Webhooks

Ask your administrator to set a default webhook URL on your client account (backoffice → Clients → Edit client). FIREPAY sends POST requests with JSON event payloads for both deposits and withdrawals.

Delivery

Method

POST

Content-Type

application/json

User-Agent

FIREPAY-Webhook/1.0

Timeout

10 seconds

Retries

Up to 3

Setting	Default
Method	POST
Content-Type	application/json
User-Agent	FIREPAY-Webhook/1.0
Timeout	10 seconds
Retries	Up to 3

Respond with HTTP 200 quickly. Handle events idempotently (same deposit_id / withdrawal_id may be delivered more than once).

Per-transaction override

Pass optional callback_url when creating a deposit or withdrawal to override the client default webhook URL for that transaction only.

Events

deposit.approved

When fired

Payment confirmed

Action on your side

Credit the player

deposit.review

When fired

Held for review (e.g. balance chain)

Action on your side

Do not credit yet

deposit.fraud

When fired

Fraud signal

Action on your side

Do not credit

deposit.rejected

When fired

Rejected (verify timeout / admin)

Action on your side

Do not credit / mark failed

withdrawal.pending

When fired

Withdrawal created (held in backoffice)

Action on your side

Record as pending on your side

withdrawal.processing

When fired

Admin released to an agent

Action on your side

Update status — payout in progress

withdrawal.approved

When fired

Agent (or admin) completed payout

Action on your side

Complete withdrawal on your side

withdrawal.rejected

When fired

Agent (or admin) rejected the withdrawal

Action on your side

Mark failed / refund flow

withdrawal.expired

When fired

Marked expired by admin (rare)

Action on your side

Mark failed / refund flow

Event	When fired	Action on your side
deposit.approved	Payment confirmed	Credit the player
deposit.review	Held for review (e.g. balance chain)	Do not credit yet
deposit.fraud	Fraud signal	Do not credit
deposit.rejected	Rejected (verify timeout / admin)	Do not credit / mark failed
withdrawal.pending	Withdrawal created (held in backoffice)	Record as pending on your side
withdrawal.processing	Admin released to an agent	Update status — payout in progress
withdrawal.approved	Agent (or admin) completed payout	Complete withdrawal on your side
withdrawal.rejected	Agent (or admin) rejected the withdrawal	Mark failed / refund flow
withdrawal.expired	Marked expired by admin (rare)	Mark failed / refund flow

Payload structure

webhook.envelope.json

JSON

1{
2  "event": "deposit.approved",
3  "timestamp": "2026-07-14T15:12:00.000Z",
4  "data": { }
5}

webhook.deposit.approved.json

JSON

1{
2  "event": "deposit.approved",
3  "timestamp": "2026-07-14T15:12:00.000Z",
4  "data": {
5    "deposit_id": "DPABCD1234",
6    "order_id": "K7M9P2Q4R5",
7    "external_order_id": "ORD-1001",
8    "amount": 500,
9    "fee_percent": 5,
10    "fee_amount": 25,
11    "client_amount": 475,
12    "wallet": "bkash",
13    "trx_id": "DFC78W6RL3",
14    "approved_at": "2026-07-14T15:12:00.000Z"
15  }
16}

webhook.deposit.review.json

JSON

1{
2  "event": "deposit.review",
3  "timestamp": "2026-07-14T15:12:00.000Z",
4  "data": {
5    "deposit_id": "DPABCD1234",
6    "order_id": "K7M9P2Q4R5",
7    "external_order_id": "ORD-1001",
8    "amount": 500,
9    "fee_percent": 5,
10    "fee_amount": 25,
11    "client_amount": 475,
12    "wallet": "nagad",
13    "trx_id": "75NRHGZ1",
14    "status": "review",
15    "reason": "Balance chain mismatch — manual review required",
16    "at": "2026-07-14T15:12:00.000Z"
17  }
18}

webhook.deposit.rejected.json

JSON

1{
2  "event": "deposit.rejected",
3  "timestamp": "2026-07-14T15:18:00.000Z",
4  "data": {
5    "deposit_id": "DPABCD1234",
6    "order_id": "K7M9P2Q4R5",
7    "external_order_id": "ORD-1001",
8    "amount": 500,
9    "fee_percent": 5,
10    "fee_amount": 25,
11    "client_amount": 475,
12    "wallet": "bkash",
13    "trx_id": "DFC78W6RL3",
14    "remarks": null,
15    "rejected_at": "2026-07-14T15:18:00.000Z"
16  }
17}

webhook.withdrawal.pending.json

JSON

1{
2  "event": "withdrawal.pending",
3  "timestamp": "2026-07-14T15:00:00.000Z",
4  "data": {
5    "withdrawal_id": "WDXYZ98765",
6    "order_id": "N4P6Q8R0S1",
7    "external_order_id": "WDR-9001",
8    "amount": 1000,
9    "fee_percent": 2,
10    "fee_amount": 20,
11    "client_amount": 980,
12    "wallet": "bkash",
13    "customer_phone": "01712345678",
14    "status": "pending",
15    "created_at": "2026-07-14T15:00:00.000Z"
16  }
17}

webhook.withdrawal.processing.json

JSON

1{
2  "event": "withdrawal.processing",
3  "timestamp": "2026-07-14T15:05:00.000Z",
4  "data": {
5    "withdrawal_id": "WDXYZ98765",
6    "order_id": "N4P6Q8R0S1",
7    "external_order_id": "WDR-9001",
8    "amount": 1000,
9    "fee_percent": 2,
10    "fee_amount": 20,
11    "client_amount": 980,
12    "wallet": "bkash",
13    "customer_phone": "01712345678",
14    "status": "processing",
15    "at": "2026-07-14T15:05:00.000Z"
16  }
17}

webhook.withdrawal.approved.json

JSON

1{
2  "event": "withdrawal.approved",
3  "timestamp": "2026-07-14T15:08:00.000Z",
4  "data": {
5    "withdrawal_id": "WDXYZ98765",
6    "order_id": "N4P6Q8R0S1",
7    "external_order_id": "WDR-9001",
8    "amount": 1000,
9    "fee_percent": 2,
10    "fee_amount": 20,
11    "client_amount": 980,
12    "wallet": "bkash",
13    "customer_phone": "01712345678",
14    "status": "approved",
15    "trx_id": "8XJ2K9LM",
16    "approved_at": "2026-07-14T15:08:00.000Z"
17  }
18}

webhook.withdrawal.rejected.json

JSON

1{
2  "event": "withdrawal.rejected",
3  "timestamp": "2026-07-14T15:18:00.000Z",
4  "data": {
5    "withdrawal_id": "WDXYZ98765",
6    "order_id": "N4P6Q8R0S1",
7    "external_order_id": "WDR-9001",
8    "amount": 1000,
9    "fee_percent": 2,
10    "fee_amount": 20,
11    "client_amount": 980,
12    "wallet": "bkash",
13    "customer_phone": "01712345678",
14    "status": "rejected",
15    "remarks": "Invalid account number",
16    "rejected_at": "2026-07-14T15:18:00.000Z"
17  }
18}

webhook.withdrawal.expired.json

JSON

1{
2  "event": "withdrawal.expired",
3  "timestamp": "2026-07-14T16:00:00.000Z",
4  "data": {
5    "withdrawal_id": "WDXYZ98765",
6    "order_id": "N4P6Q8R0S1",
7    "external_order_id": "WDR-9001",
8    "amount": 1000,
9    "fee_percent": 2,
10    "fee_amount": 20,
11    "client_amount": 980,
12    "wallet": "bkash",
13    "customer_phone": "01712345678",
14    "status": "expired",
15    "expired_at": "2026-07-14T16:00:00.000Z"
16  }
17}

Status reference

Deposit statuses

pending

Created; customer has not submitted TrxID yet

awaiting_trx

Intermediate / transitional state

awaiting_sms

TrxID submitted; awaiting payment confirmation

approved

Payment confirmed — credit the customer

review

Held for manual review — do not credit yet

fraud

Fraud signal — do not credit

rejected

Verification failed, timed out, or admin rejected

expired

Deposit session timed out

Status	Description
pending	Created; customer has not submitted TrxID yet
awaiting_trx	Intermediate / transitional state
awaiting_sms	TrxID submitted; awaiting payment confirmation
approved	Payment confirmed — credit the customer
review	Held for manual review — do not credit yet
fraud	Fraud signal — do not credit
rejected	Verification failed, timed out, or admin rejected
expired	Deposit session timed out

Withdrawal statuses

pending

Created; held in backoffice until admin releases (webhook: withdrawal.pending)

processing

Assigned to an agent for payout (webhook: withdrawal.processing)

approved

Agent/admin completed payout — complete on your side (webhook: withdrawal.approved)

rejected

Agent/admin rejected (see reject_remarks / webhook remarks)

expired

Marked expired by admin (rare; no auto-expiry on pending/processing)

Status	Description
pending	Created; held in backoffice until admin releases (webhook: withdrawal.pending)
processing	Assigned to an agent for payout (webhook: withdrawal.processing)
approved	Agent/admin completed payout — complete on your side (webhook: withdrawal.approved)
rejected	Agent/admin rejected (see reject_remarks / webhook remarks)
expired	Marked expired by admin (rare; no auto-expiry on pending/processing)

Error codes

401

Code

UNAUTHORIZED

Description

Missing or invalid API key

403

Code

CLIENT_INACTIVE

Description

Client account disabled

403

Code

FORBIDDEN

Description

Invalid payment page token

400

Code

VALIDATION_ERROR

Description

Missing or invalid request fields

400

Code

INVALID_AMOUNT

Description

Amount must be positive

400

Code

INVALID_WALLET

Description

Wallet must be bkash, nagad, rocket, or upay

400

Code

INVALID_PHONE

Description

customer_phone is not a valid BD mobile

400

Code

INVALID_TRX_ID

Description

Transaction ID format invalid

409

Code

DUPLICATE_ORDER

Description

order_id already used for this client

409

Code

DUPLICATE_TRX_ID

Description

TrxID already used for this wallet

409

Code

ALREADY_PROCESSED

Description

Withdrawal already approved or rejected

404

Code

NOT_FOUND

Description

Deposit or withdrawal not found

410

Code

EXPIRED

Description

Deposit or withdrawal window expired

HTTP	Code	Description
401	UNAUTHORIZED	Missing or invalid API key
403	CLIENT_INACTIVE	Client account disabled
403	FORBIDDEN	Invalid payment page token
400	VALIDATION_ERROR	Missing or invalid request fields
400	INVALID_AMOUNT	Amount must be positive
400	INVALID_WALLET	Wallet must be bkash, nagad, rocket, or upay
400	INVALID_PHONE	customer_phone is not a valid BD mobile
400	INVALID_TRX_ID	Transaction ID format invalid
409	DUPLICATE_ORDER	order_id already used for this client
409	DUPLICATE_TRX_ID	TrxID already used for this wallet
409	ALREADY_PROCESSED	Withdrawal already approved or rejected
404	NOT_FOUND	Deposit or withdrawal not found
410	EXPIRED	Deposit or withdrawal window expired

Code examples

Node.js — create deposit, redirect, and verify

deposit.js

1const API_KEY = process.env.FIREPAY_API_KEY;
2const BASE = process.env.FIREPAY_API_BASE; // https://{API_HOST}/v1
3 
4async function createDeposit({ amount, wallet, orderId, returnUrl }) {
5  const res = await fetch(`${BASE}/deposits`, {
6    method: 'POST',
7    headers: {
8      Authorization: `Bearer ${API_KEY}`,
9      'Content-Type': 'application/json',
10    },
11    body: JSON.stringify({
12      amount,
13      wallet,
14      order_id: orderId,
15      return_url: returnUrl,
16    }),
17  });
18  const json = await res.json();
19  if (!json.success) throw new Error(json.error?.message);
20  return json.data; // payment_url, deposit_id, external_order_id
21}
22 
23async function getDeposit(depositId) {
24  const res = await fetch(`${BASE}/deposits/${depositId}`, {
25    headers: { Authorization: `Bearer ${API_KEY}` },
26  });
27  const json = await res.json();
28  if (!json.success) throw new Error(json.error?.message);
29  return json.data;
30}
31 
32// Checkout:
33app.post('/checkout/deposit', async (req, res) => {
34  const deposit = await createDeposit({
35    amount: req.body.amount,
36    wallet: 'bkash',
37    orderId: `ORD-${Date.now()}`,
38    returnUrl: 'https://yoursite.com/payment/return',
39  });
40  res.redirect(deposit.payment_url);
41});
42 
43// After redirect — verify server-side:
44app.get('/payment/return', async (req, res) => {
45  const deposit = await getDeposit(req.query.deposit_id);
46  if (
47    deposit.status === 'approved' &&
48    deposit.external_order_id === req.query.order_id
49  ) {
50    // creditPlayer(deposit.external_order_id, deposit.amount);
51  }
52  res.send('OK');
53});

Node.js — create withdrawal

withdrawal.js

1async function createWithdrawal({ amount, wallet, customerPhone, orderId, callbackUrl }) {
2  const res = await fetch(`${BASE}/withdrawals`, {
3    method: 'POST',
4    headers: {
5      Authorization: `Bearer ${API_KEY}`,
6      'Content-Type': 'application/json',
7    },
8    body: JSON.stringify({
9      amount,
10      wallet,
11      customer_phone: customerPhone,
12      order_id: orderId,
13      ...(callbackUrl ? { callback_url: callbackUrl } : {}),
14    }),
15  });
16  const json = await res.json();
17  if (!json.success) throw new Error(json.error?.message);
18  return json.data;
19}

PHP — create deposit

create-deposit.php

PHP

1<?php
2$apiKey = getenv('FIREPAY_API_KEY');
3$payload = [
4  'amount' => 500,
5  'wallet' => 'bkash',
6  'order_id' => 'ORD-' . time(),
7  'return_url' => 'https://yoursite.com/payment/return',
8];
9$ch = curl_init('https://{API_HOST}/v1/deposits');
10curl_setopt_array($ch, [
11  CURLOPT_POST => true,
12  CURLOPT_HTTPHEADER => [
13    'Authorization: Bearer ' . $apiKey,
14    'Content-Type: application/json',
15  ],
16  CURLOPT_POSTFIELDS => json_encode($payload),
17  CURLOPT_RETURNTRANSFER => true,
18]);
19$response = json_decode(curl_exec($ch), true);
20curl_close($ch);
21if (!$response['success']) {
22  throw new Exception($response['error']['message'] ?? 'API error');
23}
24header('Location: ' . $response['data']['payment_url']);
25exit;

Python — poll deposit status

get_deposit.py

PYTHON

1import os
2import requests
3 
4API_KEY = os.environ["FIREPAY_API_KEY"]
5BASE = os.environ["FIREPAY_API_BASE"]  # https://{API_HOST}/v1
6HEADERS = {"Authorization": f"Bearer {API_KEY}"}
7 
8def get_deposit(deposit_id: str) -> dict:
9    r = requests.get(f"{BASE}/deposits/{deposit_id}", headers=HEADERS, timeout=30)
10    r.raise_for_status()
11    data = r.json()
12    if not data.get("success"):
13        raise RuntimeError(data.get("error", {}).get("message"))
14    return data["data"]
15 
16# Match your order with external_order_id
17# d = get_deposit("DPABCD1234")
18# if d["status"] == "approved" and d["external_order_id"] == "ORD-1001":
19#     credit_player(...)

Production checklist

Use HTTPS for all API calls and webhook endpoints
Store API keys server-side only
Configure a webhook URL with your FIREPAY administrator (or use callback_url)
Use a unique order_id per deposit and withdrawal
Match shop orders using external_order_id
Credit only on deposit.approved (webhook and/or confirmed GET)
Poll GET /v1/deposits/:id if the customer closes the browser before redirect
Handle all withdrawal webhook events (pending, processing, approved, rejected)
Handle webhook events idempotently (retries)
Use GET /v1/statements/summary for your Opening / Deposit / Withdraw / Fee / Settlement / Adjustment / Closing totals
Request API key + webhook URL from your FIREPAY administrator before go-live