MERCHANT API · V1

Payments infrastructure
without the busywork.

Build reliable pay-ins and payouts with one clean API. APA Paisa hosts the payment experience, handles verification, and sends you the events that matter.

Start integrating →Explore API reference ↓

Production APIhttps://app.apapaisa.com/api/v1

01 · QUICK START

From first request to first payment.

Keep your private key on your server, create a pay-in, then redirect your customer to the hosted payment URL. Every transaction can be reconciled through status checks and webhooks.

Get credentials

Request your merchant code and private API key from the APA Paisa team.

Create a pay-in

Call the initialize endpoint with a unique order ID and amount.

Redirect securely

Send the customer to payInUrl and wait for the callback.

Node.js

const response = await fetch("https://app.apapaisa.com/api/v1/payIn/generate-payin?code=YOUR_MERCHANT_CODE&ot=y&amount=505&user_id=23131", {
  headers: { "x-api-key": process.env.APA_PAISA_PRIVATE_KEY }
});
const { data } = await response.json();
redirectCustomer(data.payInUrl);

02 · AUTHENTICATION

One private key. Every request.

Authenticate server-to-server calls with your merchant private key in the x-api-key header. Never expose this key in browser code or commit it to source control.

⌘

Merchant API key

Issued per merchant and scoped to production access.

x-api-key: YOUR_MERCHANT_PRIVATE_KEY

03 · API KEYS

Keep secrets on the server.

Use environment variables or your secret manager to store credentials. Rotate keys if they are ever exposed.

✦

Credential safety

APA Paisa support can issue a replacement key and revoke the old one. Treat the private key like a password.

04 · ENVIRONMENT

One production endpoint.

This merchant portal documents the live API only. All requests use the same stable base URL.

ProductionLive transactions

https://app.apapaisa.com/api/v1v1

05 · ERRORS

Errors you can act on.

Validation failures return a structured error. Handle the response code first, then use the message to correct the request.

400Invalid request, missing field, or incorrect data type

404Merchant, API key, or resource not found

461Amount exceeds your assigned pay-in limits

500Unexpected server error — retry safely

06 · WEBHOOKS

Listen for the final state.

Provide an HTTPS notifyUrl when creating a transaction. Your endpoint receives a callback when APA Paisa has a result. Respond quickly with a 2xx status and process events idempotently.

1APA Paisa posts an eventto your notifyUrl

→

2Verify the order IDand reconcile the amount

→

3Return 200 OKthen update your system

06A · WEBHOOK PAYLOADS

We send a POST to your notifyUrl.

When a hosted payment or payout reaches a new state, APA Paisa sends a JSON POST request to the HTTPS URL you provided during initialization. Your endpoint should accept application/json, verify the merchant order ID and amount, persist the event, and return a 2xx response.

POSTnotifyUrl

Header: Content-Type: application/json

Pay-in status values include SUCCESS, PENDING, DROPPED, DUPLICATE, DISPUTE, FAILED, BANK_MISMATCH, and IMG_PENDING.

POSTnotifyUrl

Payout status values include INITIATED, APPROVED, REJECTED, REVERSED, and PENDING.

Pay-in callback · SUCCESS

application/json

{
  "status": "SUCCESS",
  "merchantOrderId": "279cebf7-52ba-4309-b56d-1807c906d667",
  "amount": 1200,
  "payinId": "81f20af5-2bd0-4ba1-93ac-717aa2241fd7",
  "req_amount": 1200,
  "utr_id": "5342343423"
}

Payout callback · APPROVED

application/json

{
  "status": "APPROVED",
  "merchantOrderId": "79334b7a-f6bc-4131-92f3-5046ff5ef011",
  "amount": 5770,
  "payoutId": "f01cad58-ec14-46e5-84c4-efde465b60db",
  "utr_id": "23423423421"
}

↻

Handle callbacks safely

Return 2xx after the event is durably accepted. Treat callbacks as repeatable: use the transaction ID, payinId or payoutId, and status to make processing idempotent. If a callback is missed, use the corresponding status endpoint.

07 · RELIABILITY

Make retries safe.

Use a unique merchant_order_id for each transaction. Persist the returned pay-in or payout ID and use status endpoints when a network timeout leaves the result unknown.

08 · RATE LIMITS

Designed for steady traffic.

Keep requests measured and retry transient 5xx responses with exponential backoff. Contact support before a large launch or traffic spike.

API REFERENCE

Initialize a pay-in

Create a hosted payment link and receive the pay-in identifiers needed to track the transaction.

GETTry it →

https://app.apapaisa.com/api/v1/payIn/generate-payin

Request

All requests require the x-api-key header.

Query parameters

code · string · required

ot · string · required · use y

amount · integer · required

user_id · string · required

merchant_order_id · string · required

notifyUrl · URL · HTTPS

returnUrl · URL · HTTPS

Response

A successful response includes a transaction ID and current status.

200 · application/json

{
  "message": "PayIn is generated & url is sent successfully",
  "statusCode": 200,
  "data": {
    "expirationDate": "2025-05-05T15:36:12.434Z",
    "payInUrl": "https://pay.apapaisa.com/transaction/…",
    "payinId": "0b6a4d30-3689-44e4-9d12-1d47d19db400",
    "merchantOrderId": "ORDER-123",
    "status": "INITIATED",
    "intentUrl": "upi://pay?pa=merchant@upi&am=505.00&cu=INR",
    "paymentId": "27031146017",
    "paymentUrl": "https://anypaymenturl/tnxid",
    "merchantVpa": "merchant@upi",
    "merchantName": "APA Paisa Merchant",
    "amount": "505.00",
    "transactionId": "IND96d1859a5c6b4"
  }
}

Pay-in callback

When the transaction state changes, APA Paisa sends this JSON payload as a POST request to the HTTPS notifyUrl in your request.

POST notifyUrl

Callback payload · application/json

{
  "status": "SUCCESS",
  "merchantOrderId": "279cebf7-52ba-4309-b56d-1807c906d667",
  "amount": 1200,
  "payinId": "81f20af5-2bd0-4ba1-93ac-717aa2241fd7",
  "req_amount": 1200,
  "utr_id": "5342343423"
}

Your endpoint must accept POST requests, persist the payload idempotently, and return a 2xx response.

Notes

The pay-in link is valid for 10 minutes.
Persist the payinId until the transaction reaches a final state.
If intentUrl is empty or missing, redirect the customer to paymentUrl.
Use the HTTPS notifyUrl callback to reconcile the final result.

09 · GOING LIVE

Launch with confidence.

Before launch, verify callback handling, persist transaction IDs, test all terminal statuses, and confirm your account limits with APA Paisa support.

✓ Credentials stored server-side

✓ HTTPS callbacks deployed

✓ Duplicate events handled

✓ Status reconciliation scheduled