AI-Powered Financial InfrastructureGlobal PaymentsSecure & Trusted

Developers · API Reference

API Reference

The resources, request conventions and error handling behind every Paynancial integration — with working examples in PHP, JavaScript and cURL.

Request Sandbox Access Integration Guide

Base URL https://api.paynancial.com/v1
Basic auth with an API key
Amounts in paise

Overview

What the Paynancial API is.

The Paynancial API is a REST API over HTTPS for accepting payments, refunding them, sending payouts, creating payment links and running scheduled collections. Every request is authenticated with an API key and returns the resource it created or changed.

The same API is used by a developer's server, by Paynancial's SDKs and by AI agents acting for a business. Write endpoints accept an idempotency key so any caller can retry safely.

This reference covers the resources and parameters used in Paynancial's published examples. For endpoints, parameters or response fields not listed here, contact developer support.

Request conventions

How every request is made.

Request conventions
Convention	Detail
Base URL	`https://api.paynancial.com/v1`
Transport	HTTPS only.
Authentication	HTTP basic authentication with your API key as the username and an empty password (`-u YOUR_API_KEY:` in cURL). See Authentication.
Environments	A sandbox key runs requests in the sandbox; a live key moves real money. See Sandbox.
Amounts	Integers in the smallest currency unit — paise for INR.
Request body	Form-encoded fields, as in the cURL examples; the SDKs build the request for you.
Idempotency	`Idempotency-Key` header on write requests (the SDKs take an `idempotency_key` option).
Errors	A stable error code your code can branch on, alongside a readable message.

POST /payments

Payments

Create a payment to accept money from a customer.

Payments parameters
Parameter	Description
`amount`	Amount in the smallest currency unit (paise for INR) — 50000 is ₹500.00
`currency`	Currency code, e.g. INR
`receipt`	Your own reference for the order

A payment object; the examples read its id. Used by Payment Gateway.

POST /payments

$payment = $client->payments->create([
    'amount'   => 50000, // in paise
    'currency' => 'INR',
    'receipt'  => 'order_rcpt_101',
]);

echo $payment->id;

const payment = await client.payments.create({
  amount: 50000,
  currency: 'INR',
  receipt: 'order_rcpt_101',
});

console.log(payment.id);

curl https://api.paynancial.com/v1/payments \
  -u YOUR_API_KEY: \
  -d amount=50000 \
  -d currency=INR \
  -d receipt=order_rcpt_101

POST /refunds

Refunds

Refund all or part of an existing payment.

Refunds parameters
Parameter	Description
`payment_id`	The payment being refunded
`amount`	Amount to refund, in paise

A refund object. Used by Refunds.

POST /refunds

$refund = $client->refunds->create([
    'payment_id' => 'pay_9F3kd82',
    'amount'     => 20000,
]);

const refund = await client.refunds.create({
  payment_id: 'pay_9F3kd82',
  amount: 20000,
});

refund = client.refunds.create(
    payment_id='pay_9F3kd82',
    amount=20000,
)

curl https://api.paynancial.com/v1/refunds \
  -u YOUR_API_KEY: \
  -d payment_id=pay_9F3kd82 \
  -d amount=20000

POST /payouts

Payouts

Send money to a beneficiary's bank account or UPI ID.

Payouts parameters
Parameter	Description
`beneficiary_id`	The beneficiary receiving the funds
`amount`	Amount in paise — 250000 is ₹2,500.00
`mode`	Transfer mode; the published example uses `upi`. Bank transfer is also supported.

A payout object; the examples read its status. Used by Payouts.

POST /payouts

$payout = $client->payouts->create([
    'beneficiary_id' => 'bene_3Kd91',
    'amount'         => 250000, // in paise
    'mode'           => 'upi',
], [
    'idempotency_key' => 'payout-run-2026-08-29-0417',
]);

echo $payout->status;

curl https://api.paynancial.com/v1/payouts \
  -u YOUR_API_KEY: \
  -H "Idempotency-Key: payout-run-2026-08-29-0417" \
  -d beneficiary_id=bene_3Kd91 \
  -d amount=250000 \
  -d mode=upi

POST /payment_links

Payment Links

Create a shareable link a customer can pay without a checkout on your site.

Payment Links parameters
Parameter	Description
`title`	What the customer sees, e.g. an invoice number
`amount`	Amount in paise; omit it to let the customer enter the amount
`currency`	Currency code, e.g. INR

A payment link object; the examples read its short_url. Used by Payment Links.

POST /payment_links

$link = $client->paymentLinks->create([
    'title'    => 'Invoice #204',
    'amount'   => 500000, // in paise, or omit to let the customer enter it
    'currency' => 'INR',
]);

echo $link->short_url;

curl https://api.paynancial.com/v1/payment_links \
  -u YOUR_API_KEY: \
  -d title='Invoice #204' \
  -d amount=500000 \
  -d currency=INR

POST /collections

Collections

Collect recurring or scheduled payments from a customer.

Collections parameters
Parameter	Description
`customer_id`	The customer being charged
`amount`	Amount per collection, in paise
`schedule`	How often to collect; the published example uses `monthly`

A collection object; the examples read its id. Used by Payment Collection.

POST /collections

$collection = $client->collections->create([
    'customer_id' => 'cust_7Fk21',
    'amount'      => 150000, // in paise
    'schedule'    => 'monthly',
]);

echo $collection->id;

curl https://api.paynancial.com/v1/collections \
  -u YOUR_API_KEY: \
  -d customer_id=cust_7Fk21 \
  -d amount=150000 \
  -d schedule=monthly

POST /reports/transactions

Transaction reports

Generate a transaction report for a date range, for your finance team or accounting system.

Transaction reports parameters
Parameter	Description
`from`	Start date, e.g. 2026-08-01
`to`	End date, e.g. 2026-08-31
`format`	Report format; the published example uses `csv`

A report object; the examples read its download_url. Used by Payment Analytics.

POST /reports/transactions

$report = $client->reports->transactions([
    'from'   => '2026-08-01',
    'to'     => '2026-08-31',
    'format' => 'csv',
]);

echo $report->download_url;

curl https://api.paynancial.com/v1/reports/transactions \
  -u YOUR_API_KEY: \
  -d from=2026-08-01 \
  -d to=2026-08-31 \
  -d format=csv

Idempotency

Retry without paying twice.

Networks time out. When they do, you cannot tell whether the request reached Paynancial. Send an idempotency key with every write request, and a retry with the same key returns the original result rather than creating a second payment, refund or payout.

Use one unique key per intended action — for example your payout run ID.
Reuse the same key only when retrying that same action.
This matters most for automated callers and AI agents, which retry without asking a person first.

Payout with an idempotency key

$payout = $client->payouts->create([
    'beneficiary_id' => 'bene_3Kd91',
    'amount'         => 250000, // in paise
    'mode'           => 'upi',
], [
    'idempotency_key' => 'payout-run-2026-08-29-0417',
]);

echo $payout->status;

curl https://api.paynancial.com/v1/payouts \
  -u YOUR_API_KEY: \
  -H "Idempotency-Key: payout-run-2026-08-29-0417" \
  -d beneficiary_id=bene_3Kd91 \
  -d amount=250000 \
  -d mode=upi

Errors

Errors your code can act on.

Error responses carry a stable code and a readable message. Branch on the code, not the message. These are the codes shown in Paynancial's published examples:

Example error codes
Code	Meaning	What to do
`insufficient_funds`	The balance available is not enough for the requested payout or refund.	Do not retry automatically; top up or reduce the amount, then try again.
`invalid_method`	The payment method or mode in the request is not valid for this call.	Correct the request. Retrying the same request will fail the same way.
`rate_limited`	Too many requests in a short period.	Back off and retry later with the same idempotency key.

FAQ

API Reference questions.

What is the base URL of the Paynancial API?

All requests go to https://api.paynancial.com/v1 over HTTPS. Whether a request runs in the sandbox or moves real money depends on whether you authenticate with a sandbox key or a live key.

How are amounts expressed?

In the smallest unit of the currency. For Indian rupees that is paise, so 50000 means ₹500.00.

How do I avoid creating a duplicate payment or payout when I retry?

Send an idempotency key with every write request. If the same key is sent again, the API returns the original result instead of creating a second payment or payout.

Which endpoints are documented here?

Payments, refunds, payouts, payment links, collections and transaction reports, with the parameters used in Paynancial's published examples. For anything not covered on this page, contact developer support.

Test every call before it touches real money.

Request a sandbox key and run these examples end to end.

Request Sandbox Access Contact Developer Support