Cross-Border Payment API Integration Guide for India Collections

A cross-border payment API integration for India collections is the connection between your checkout and a Payment Aggregator - Cross Border (PA-CB), a company the Reserve Bank of India (RBI) authorises to collect from Indian customers for overseas merchants.

Your customers pay in rupees by card or UPI, while you are settled abroad in your own currency.

An integration guide for India collections comes down to eight steps: choose a route, complete compliance onboarding, submit KYC and KYB documents, set up authentication and your API calls, confirm each payment by webhook, plan for the rate at settlement, test in test mode, and go live with live keys.

These steps are for collecting from Indian customers; paying suppliers or contractors abroad needs a different integration.

In India, cross-border collections typically run through an RBI-authorised PA-CB under the 15 September 2025 Master Direction (RBI/DPSS/2025-26/141), covering aggregators and the banks that serve them.

RBI authorises Xflow as a PA-CB, and that RBI PA-CB authorisation is final as of February 2026, the fully approved stage past in-principle.

India collections means Indian customers paying you through a regulated Indian aggregator; for sending money out, see this comparison of international money transfer APIs.

1. Your customer pays in rupees - By card, UPI (India's instant bank-to-bank method), netbanking or a recurring mandate. With us, cards include RuPay as well as Visa and Mastercard, and recurring payments run on UPI AutoPay, card mandates or e-NACH.
2. The aggregator collects through its bank - The PA-CB takes the rupees through an AD Category-1 bank, the authorised dealer class RBI permits to handle foreign exchange.
3. The rupees convert and land abroad - The exchange happens at settlement, and payouts reach your overseas bank account in the currency you choose. We settle on T+2 (2 business days).
4. Your API calls and webhooks sit on top - You create the payer, the invoice and the checkout through the API, then confirm each payment by webhook, not the browser redirect.

In order, from route to first live payment:

1. Choose a route - hosted checkout, direct processing or an orchestrator.
2. Complete compliance onboarding - agree your company details and purpose codes with your aggregator.
3. Submit KYC, KYB and payment documents - company, payer and invoice details go to your aggregator.
4. Set up authentication and your API calls - keys, payer, invoice and checkout.
5. Confirm each payment by webhook - your ledger follows the event, not the redirect.
6. Plan for the rate at settlement - the final rate arrives with the payout.
7. Test in test mode - no real funds move while you try success and failure.
8. Go live - switch to live keys once your account is activated and tests pass.

Choose between hosted checkout, direct API and an orchestrator

A payment gateway API takes the card or UPI payment, while a PA-CB also holds the authorisation to collect for overseas merchants and settle abroad. Whichever cross-border payments API you start from, the options for India collections look like this:

Our route

- For direct merchants, we run the hosted checkout route. If you're a payment service provider collecting for your own merchants, we have a separate integration path for you.

Complete compliance onboarding before you accept live payments

Complete compliance onboarding with your aggregator before you plan a live date.

In India that aggregator is a PA-CB, which RBI's Master Direction on Regulation of Payment Aggregators defines as an aggregator for cross-border current account payments that FEMA, India's foreign exchange law, does not prohibit.

The aggregator and its AD Category-1 bank carry most of the RBI duties, so your part is supplying accurate company details and agreeing the RBI purpose codes your payments will use.

Have three things ready: those purpose codes, the overseas bank account you want paid into, and details of the people who own and run your business.

Start onboarding in parallel with your build, because your first live payment depends on it.

Onboarding with us

- Our team works with you through onboarding, including choosing your purpose codes.

Each payment you collect carries one, and your approved codes show on your own account in the API. If you're a payment service provider onboarding your merchants with us, activation fails until their purpose codes, payout address and business person details are in place.

Our PA-CB licence post explains what our authorisation covers.

KYC and KYB checks, and the documents you provide

Prepare for Know Your Customer (KYC) and Know Your Business (KYB) checks, and ask your aggregator for its document checklist before you apply.

RBI expects the aggregator to carry out customer due diligence on you and to monitor your activity against your business profile (Master Direction, paragraph 13). Prepare payer and invoice details for every payment too.

What we ask you for

- Request the exact checklist for your account. We run sanctions screening on each Indian payer, and you supply:

• Payer details - Each Indian payer needs a type (business or individual) and a postal code. Their legal name must match the Bill To name on the invoice.
• PAN, if screening returns a hit - We may ask for the payer's Permanent Account Number after a sanctions hit, and the payer can supply it during checkout.
• The invoice - You upload a copy of each invoice, and the amount, purpose code and transaction type go with it.
• Shipping proof for goods - You submit a shipping document within 10 business days after the Receivable is reconciled.

Authentication, request setup and the payment API integration calls in order

Authenticate every request with a secret key kept on your server, call only over HTTPS, and keep test and live credentials apart.

Then build the calls in the order the money flows: identify the payer, record the invoice, create the checkout, open it, and read the result.

Our keys and API calls

- We issue test and live secret keys, and the key you use decides the mode. Authentication is HTTP Basic with the key as the username and no password, and a Bearer header also works.

Our API reference lists every resource, and the calls run in this order:

1. Create and activate the payer - Create a Partner, the Indian customer, then submit it for screening.
2. Upload the invoice and create a Receivable - A Receivable holds the amount, purpose code and transaction type. Confirm it before checkout, or update it after payment.
3. Create a Checkout - It's INR only, takes one Receivable, and its session lasts 30 minutes, then expires, so start a new session after expiry.
4. Open the hosted checkout - Load our script and allow its two domains in your Content Security Policy.

Our integration guide shows each step in full.

Webhooks and idempotency keys for confirming payments without double-counting

Confirm each payment by webhook and API status, because the browser redirect can be missed or closed before it loads. Make your handling safe to repeat.

An idempotency key is a unique value that stops a retried request creating the same thing twice, so store each event and payment ID you process and ignore repeats.

The webhook events we send

- Events cover payer status changes, Receivable status changes and the exchange rate being created. Save the secret we use to generate webhook signatures when you create each endpoint, because live mode returns it only in the create response.

After the redirect, poll the checkout's latest payment status.

FX quote versus the rate you receive at settlement

An FX quote is a rate offered before money moves. Check whether your provider quotes a rate before checkout or sets it at settlement, because that decides what you can show customers and how you report revenue.

When we set your rate

- Your customer pays in INR, and we set the exchange rate at settlement and attach it to your payout after the bank confirms the wire. A webhook tells you when the rate exists.

Sandbox and test mode before you connect to live payments

Test every flow in a sandbox before real money moves. Cover each of these:

• Checkout creation and rendering - The hosted checkout loads on every page and device you support.
• A successful and a failed payment - Your pages, your redirect and your ledger react correctly to both.
• An expired session - A customer who comes back after the checkout session ends gets a fresh one, not an error.
• Webhooks out of order or twice - The webhook can land before the redirect, and the same event can arrive again, so your ledger records each payment once.
• A payer screening hit - Your flow copes when a payer is asked for extra details before paying.

Our test mode

- It's our sandbox, and it works like live mode, except no actual payment is processed and no real funds move. On the hosted checkout you pick a successful or a failed payment and watch how your integration reacts.

Switch to live keys once your account is activated and tests pass

Go live once your aggregator has activated your account and your test payments pass. Then:

• Swap in your live secret keys - The key decides the mode, so the same calls now move real money.
• Recreate your webhook endpoints in live mode - Each live endpoint gets a new secret, so save it the moment you create it.
• Allow the checkout domains on your live site - Your production Content Security Policy needs the same two domains you allowed in test.
• Run one real payment end to end - Follow it from checkout to your ledger, including the webhook.
• Match the first payout to its invoices - Check the amount and the exchange rate against your records.

Test data doesn't carry over, so create your live payers and receivables again in live mode. Keep alerts on failed webhook deliveries for the first weeks, when a missed event is most likely to go unnoticed.

Plan for failed requests before launch, because any step between your server and the payment schemes can time out or refuse a call. Sort each error by what it needs:

• Server errors (500, 502, 503, 504) - Retry after a short wait, wait longer each time, and stop after a few tries.
• Request errors (400, 404) - Don't retry unchanged; fix the data you sent, such as a missing field or a wrong ID.
• Key and permission errors (401, 403) - Check you're using the right secret key for test or live mode.
• Conflicts (409) - Another request is changing the same object, so wait and try again.

Log every request and response against your own payment reference, so a failed payment is quick to trace.

Our error codes

- Our error codes tell you what went wrong and how to fix it, for example an invalid API key or a missing purpose code.

If you get an "object busy" conflict, send requests for that object one at a time or slow them down. If your webhook endpoint was down, you can fetch missed events through our Events API for up to 30 days.

• Local payment methods - Customers pay in rupees the way they already do in India.
• Settlement in your own currency - Money lands in your overseas bank account.
• India compliance largely carried for you - You supply KYC and invoice data; the aggregator does the rest.
• One integration instead of building your own India setup - No Indian entity and no per-method integrations.

What you get with us

:

• Indian payment methods in INR - Visa, Mastercard and RuPay cards, UPI, UPI AutoPay, card mandates, e-NACH and netbanking.
• Payouts in your currency - USD, GBP, EUR, CAD, AUD and more.
• Final PA-CB authorisation - We hold it from RBI, and our AD Category-1 banking partner handles the regulatory requirements.
• No Indian entity - Xflow states no Indian entity is required: no company registration, no local bank account and no India payments hire.

Get these in writing before you commit:

• Per-transaction limit - RBI caps a PA-CB payment at Rs 25 lakh (Rs 2,500,000) per transaction (Master Direction, paragraph 11.d), so check your largest invoice against it.
• Settlement timeline - RBI requires the merchant agreement to state the settlement timeline (Master Direction, Table 1), so get it written down.
• Refunds and chargebacks - RBI's rule is that credits for reversed transactions and refunds go back through the escrow account unless the merchant manages the refund directly and the payer has been told so in the contract (Master Direction, paragraph 18(h)). Get ownership of refunds and chargebacks, and the timing, in writing.
• Supporting documents - RBI expects the aggregator to provide the documents and information the payer's own AD bank needs for its records, where applicable (Master Direction, paragraph 11.h), so check which documents your aggregator needs from you and by when.

We settle on T+2 (2 business days). Once the payment schemes pay the funds to us, each paid Receivable is reconciled into a payout, and the payout grows as more payments reconcile.

Our banking partner then sends it to your overseas bank account in your chosen currency.

You can read these from the API:

• The INR amount behind a payout - Fetch the payment linked to the payout to see the rupees collected.
• The exchange rate - Read it from the same linked payment once the wire is confirmed.
• Which invoices fed a payout - Each payout links back through its transfers to the payments and Receivables inside it, so finance can match every payout line to an invoice.
• Your fees - Your fee plan shows a collection fee for each payment method and a payout fee for each payout, as set in your agreement with us.

For the wider job of matching payouts to invoices, see payment reconciliation.

We run Xflow Import for companies collecting from India and settling abroad.

Ask us for the onboarding checklist and test access, then tell us your expected volumes. You can also accept payments from India without an Indian entity.