ZiniPay Sandbox

Create invoices & verify status

This documentation covers the essential Create Invoice and Verify Invoice endpoints for merchant and partner developers. Follow the instructions to test transactions securely.

PDF Version

Base URL

https://api.zinipay.com

Create Endpoint

POST /v1/payment/create

Verify Endpoint

POST /v1/payment/verify

Preferred Auth

zini-api-key

Overview

ZiniPay exposes two external APIs for sandbox testing: Create Invoice and Verify Invoice.

How to get your API key

Login to your sandbox dashboard.
Navigate to the Main Menu.
Select Brands.
Copy your Brand Key / API Key.

Example full URL

https://api.zinipay.com/v1/payment/create

Authentication

Every request must include your API key to authenticate securely.

Method	Value	Notes
`Preferred header`	`zini-api-key: YOUR_API_KEY`	Recommended
`Also supported header`	`zinipay-api-key: YOUR_API_KEY`	Supported
`Query parameter`	`?apikey=YOUR_API_KEY`	Supported

Endpoints

Name	Method	Path	Purpose
`Create Invoice`	`POST`	/v1/payment/create	Create a hosted invoice and return payment_url.
`Verify Invoice`	`POST`	/v1/payment/verify	Verify invoice payment status.

Common rules

Set Content-Type to application/json.
Every request must include an API key.
Only active brands are allowed.
redirect_url domain must match the brand website domain.
amount must be greater than 0.
metadata must be valid JSON and stay within 1 KB.

Create Invoice

Create a hosted invoice and receive the secure payment URL to redirect your customers.

POSThttps://api.zinipay.com/v1/payment/create

Required headers

Content-Type: application/json
zini-api-key: YOUR_API_KEY

Request fields

Field	Type	Required	Description
`cus_name`	`string`	No	Customer name.
`cus_email`	`string`	No	Customer email.
`amount`	`number`	Yes	Invoice amount, must be greater than 0.
`metadata`	`object`	No	JSON metadata up to 1 KB.
`redirect_url`	`string`	Yes	Success redirect URL.
`cancel_url`	`string`	No	Cancel redirect URL.
`val_id`	`string`	No	Merchant reference.
`webhook_url`	`string`	No	Webhook callback URL.

Request examples

curl -X POST "https://api.zinipay.com/v1/payment/create" \
  -H "Content-Type: application/json" \
  -H "zini-api-key: YOUR_API_KEY" \
  -d '{
    "cus_name": "John Doe",
    "cus_email": "[email protected]",
    "amount": 1200,
    "metadata": {
      "order_id": "ORD-1001",
      "customer_id": "CUS-9001"
    },
    "redirect_url": "https://merchant.com/payment/success",
    "cancel_url": "https://merchant.com/payment/cancel",
    "val_id": "INV-REF-1001",
    "webhook_url": "https://merchant.com/api/zinipay/webhook"
  }'

Success response

{
  "status": true,
  "message": "Invoice created successfully.",
  "payment_url": "https://secure.zinipay.com/payment/INVOICE_ID",
  "val_id": "INV-REF-1001"
}

Verify Invoice

Verify the latest payment status directly from your backend before processing the order.

POSThttps://api.zinipay.com/v1/payment/verify

Request fields

Field	Type	Required	Description
`invoice_id`	`string`	Yes	Invoice reference to verify.

Request examples

curl -X POST "https://api.zinipay.com/v1/payment/verify" \
  -H "Content-Type: application/json" \
  -H "zini-api-key: YOUR_API_KEY" \
  -d '{
    "invoice_id": "INV-REF-1001"
  }'

Success response

{
  "cus_name": "John Doe",
  "cus_email": "[email protected]",
  "amount": 1200,
  "invoice_id": "INVOICE_ID",
  "val_id": "INV-REF-1001",
  "payment_method": "bkash",
  "transaction_id": "TXN123456789",
  "status": "COMPLETED"
}

Status values

PENDINGCOMPLETEDFAILED

Recommendation

Always verify the invoice from your backend using this endpoint before fulfilling any order, delivering digital services, or sending a "Received Payment" notification.

Webhook Callback Flow

If webhook_url is sent during invoice creation, ZiniPay will automatically call it after a successful payment update.

Webhook payload

JSON Body / Query

{
  "invoice_id": "INVOICE_ID",
  "status": "true",
  "val_id": "INV-REF-1001"
}

Query parameter style

https://merchant.com/api/zinipay/webhook?invoice_id=INVOICE_ID&status=true&val_id=INV-REF-1001

Recommended merchant flow

1Create order
2Generate val_id
3Create invoice
4Redirect user
5Receive callback
6Verify invoice
7If completed, mark paid
8If pending, retry
9If failed, cancel order

Production Checklist

Before deploying to your live environment, verify these final steps to ensure a smooth transition.

API key stored in environment variables

HTTPS enabled

Redirect domain matched

Backend verification added

Logging enabled

Webhook secured

Need the original PDF?

Download the full API documentation for offline use and sharing.

Download PDF

Advanced APIBeta

Transaction Verification API

Need backend-side payment verification with masked sender data, credit deduction, and irreversible confirmation? Use our advanced two-step transaction verification flow.

Two-step verify + confirmDouble-spend protectionMasked sender on verifyAtomic credit deduction

Endpoint Group

/api/trx/*

Best For

Merchant backend verification and secure payment confirmation

Open transaction docs