RS PAY · MERCHANT API · V1

Payments that move
at your speed.

A focused API for dependable pay-ins and payouts. Create transactions, host checkout, and reconcile final outcomes from one reliable platform.

Start integrating →Explore API reference ↓

Production APIhttps://rspay.co/api/v1

LIVE REQUEST200

GET /payIn/generate-payin

payment initialized

hosted checkout ready

webhook delivery armed

Built for the complete transaction lifecycle.

01 · QUICK START

From first request to first payment.

Use hosted checkout when RS Pay should receive the customer in the browser. Use direct server-to-server creation only when your server already has the customer's IP and needs payment details immediately.

Get credentials

Request your merchant code and private API key from the RS Pay 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.

Hosted checkout

Set checkout=true when you will redirect the customer to payInUrl. Do not send clientIp: the hosted checkout request contains the customer's IP. RS Pay creates the record first and starts provider payment only after the customer opens checkout.

Hosted checkout

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

Direct server-to-server

Omit checkout when your server needs RS Pay to create payment immediately. In this flow, clientIp is required because no hosted customer request is available to determine it.

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

RS Pay 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://rspay.co/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 RS Pay has a result. Respond quickly with a 2xx status and process events idempotently.

1RS Pay 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, RS Pay 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

Use checkout=true when redirecting a customer to the RS Pay hosted checkout. It creates an INITIATED pay-in first, then assigns a bank and starts the provider payment only after the customer opens checkout; clientIp is optional because RS Pay uses that customer request's IP. Omit checkout for direct server-to-server creation: payment starts immediately and clientIp is required because it must be supplied by your server.

GETTry it →

https://rspay.co/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

checkout · boolean · optional · use true for hosted checkout

clientIp · IPv4 or IPv6 · required for S2S · optional only with checkout=true

merchant_order_id · string · required

notifyUrl · URL · HTTPS

returnUrl · URL · HTTPS

customer_email · string · optional

customer_phone · string · optional

customer_first_name · string · optional

customer_last_name · string · optional

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.rspay.co/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": "RS Pay Merchant",
    "amount": "505.00",
    "transactionId": "IND96d1859a5c6b4"
  }
}

Pay-in callback

When the transaction state changes, RS Pay 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.
Use checkout=true only for hosted checkout; the provider payment starts when the customer opens payInUrl.
Without checkout=true, this is an S2S request and clientIp is required.
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 RS Pay support.

✓ Credentials stored server-side

✓ HTTPS callbacks deployed

✓ Duplicate events handled

✓ Status reconciliation scheduled

Payments that moveat your speed.

From first request to first payment.

Get credentials

Create a pay-in

Redirect securely

Hosted checkout

Direct server-to-server

One private key. Every request.

Merchant API key

Keep secrets on the server.

One production endpoint.

Errors you can act on.

Listen for the final state.

We send a POST to your notifyUrl.

Pay-in callback · SUCCESS

Payout callback · APPROVED

Make retries safe.

Designed for steady traffic.

Initialize a pay-in

Request

Response

Launch with confidence.

Payments that move
at your speed.