ZiniPay API Docs

Transaction Verification API

This API provides a secure two-step transaction verification flow with credit deduction, masked data return, and irreversible confirmation.

Base URL

https://api.zinipay.com/

Verify Endpoint

POST /verify

Confirm Endpoint

POST /confirm

Authentication

All transaction verification endpoints require your Brand or Service API key to be sent in the request headers.

Headers

{
  "zinipay-api-key": "your_brand_api_key_here"
}

Important

Send these requests from your backend only. Do not expose the API key in browser-side code, checkout pages, or mobile clients.

Base URL

https://api.zinipay.com/

API Flow Architecture

The verification process is designed as a two-step flow to protect against double spending, keep sender data masked during validation, and ensure atomic credit deduction.

Important Rules

Every request must include the Brand/Service API key in the zinipay-api-key header.
The flow is strictly two-step: verify first, then confirm using the returned id.
Verify deducts 1 credit atomically before masked transaction data is returned.
Confirm permanently consumes the transaction and it cannot be used again.

Recommended Flow

1Call POST /verify with transactionId and amount.
2Save the returned internal id from the verify response.
3Validate the masked transaction details on your backend.
4Call POST /confirm with transactionId, amount, and id.

Step 1: Verify

The client calls /verify with transactionId and amount. The system validates the transaction, deducts 1 verification credit atomically, and returns masked transaction data with the internal database id.

Step 2: Confirm

After validation, call /confirm with the same transactionId, amount, and returned id. This permanently marks the transaction as used and returns the full unmasked transaction data.

Verify Transaction

Pre-check transaction validity, ensure it is unused, and deduct 1 verification credit before proceeding to confirmation.

Endpoint

POSTPOST /verify

Request Body

JSON

{
  "transactionId": "TXN123456789",
  "amount": 500
}

Success Response

200 OK

{
  "statusCode": 200,
  "success": true,
  "message": "Transaction verified successfully.",
  "data": {
    "id": 1234,
    "trxID": "TXN123456789",
    "amount": 500,
    "sender": "017****5678",
    "status": "UNUSED",
    "provider": "bKash",
    "timestamp": "2026-05-20T10:30:00.000Z"
  }
}

Confirm Transaction

Irreversibly consume the verified transaction and mark it as used so it cannot be verified or confirmed again.

Endpoint

POSTPOST /confirm

Request Body

JSON

{
  "transactionId": "TXN123456789",
  "amount": 500,
  "id": 1234,
}

Success Response

200 OK

{
  "statusCode": 200,
  "success": true,
  "message": "Transaction confirmed and successfully consumed.",
  "data": {
    "id": 1234,
    "provider": "bKash",
    "message": "Payment received...",
    "transactionId": "TXN123456789",
    "senderNumber": "01712345678",
    "amount": 500,
    "timestamp": "2026-05-20T10:30:00.000Z",
    "status": false
  }
}

Common Error Responses

Verify Errors

Status	Message	Code
`400`	Transaction amount must be equal to the provided amount	-
`400`	Transaction is already used	-
`402`	Insufficient credits for transaction verification	`INSUFFICIENT_CREDITS`
`402`	Credits have expired	`CREDITS_EXPIRED`
`403`	Transaction verification API is not enabled for your service. Please enable it from the dashboard.	`FEATURE_DISABLED`
`404`	Transaction not found	-

Confirm Errors

Status	Message	Code
`400`	Provided ID does not match the transaction	-
`400`	Transaction is already used or does not exist	-
`403`	Device is not connected with the service	-
`500`	Internal Server Error	-

Example (Node.js)

JavaScript

import axios from "axios";

const headers = {
  "zinipay-api-key": process.env.ZINIPAY_API_KEY,
};

const verifyResult = await axios.post(
  "https://api.zinipay.com/api/trx/verify",
  {
    transactionId: "TXN123456789",
    amount: 500,
  },
  { headers }
);

const confirmResult = await axios.post(
  "https://api.zinipay.com/api/trx/confirm",
  {
    transactionId: "TXN123456789",
    amount: 500,
    id: verifyResult.data.data.id,
    invoiceId: "INV-98765",
  },
  { headers }
);