> ## Documentation Index
> Fetch the complete documentation index at: https://razorpay.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# International Cards: How to Test Your Integration

> Test international card payments on S2S JSON and S2S Redirect in Test Mode across INR orders, non-INR orders and refunds, including settlement recon and failure scenarios.

Available in
🇮🇳 India

This page covers testing international card payments on **S2S JSON** (`POST /v1/payments/create/json`) and **S2S Redirect** (`POST /v1/payments/create/redirect`) across the three forex flows. If you have not yet, read [Forex Conversion](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/json/v2/build-integration/international-cards/forex-conversion.md) first. The scenarios below check the behaviour it describes.

> [!NOTE]
>
> **Before you start**
>
> Run the [Cards test page](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/cards.md) first. Authentication, declines, tokens and signature checks work the same way for international cards and are not repeated here. You need international payments enabled on your test account, and each non-INR currency you want to charge in enabled on that account.

## 1. Test Mode Coverage

> [!WARNING]
>
> **FX rates in test mode are dummy rates**
>
> The rates used to convert non-INR amounts into INR in test mode are dummy FX rates. They may not match actual mid-market rates and are subject to change. Do not hard-code or assert exact INR values in your tests.

### How live mode and test mode differ

| Behaviour | Live mode | Test mode |
| - | - | - |
| Razorpay FX rate (Flow 2) | Mid-market rate at the time of the transaction. | Dummy FX rates. Do not assert exact INR values. |
| Issuer conversion and markup | Applied by the cardholder's bank. Never visible to you or Razorpay. | Not simulated. The mock bank page has no billing currency. |
| Settlement | Real money settles to your bank. Each payment and refund appears as a line in the Settlement Recon API and in settlement reports. | No money moves, so there are no settled payment lines to fetch. You can still build and test the Settlement Recon API call itself. |
| Currencies | As enabled on your live account. | As enabled on your test account. A currency that is not enabled fails at order creation. |

### What you can test

| Area | What you can test | Available on test mode |
| - | - | - |
| Flow 1 payments | INR order paid with an international card | Available |
| Flow 2 payments | Non-INR orders in each currency you sell in | Available |
| Flow 3 refunds | Full and partial refunds in the presentment currency | Available |
| Settlement Recon API call | Request, pagination and error handling | Available |
| Settled amounts per transaction | `credit` on payment lines and `debit` on refund lines | Live only |
| Actual mid-market FX rates | The INR converted amount of a non-INR payment at the real rate | Live only |
| Issuer FX conversion, markup and charges | What the cardholder is debited or credited in their billing currency | Live only |

## 2. Test Kit

* Use any future expiry date and any 3-digit CVV.
* On the mock bank page, enter any OTP of 4–10 digits, or choose **Success**.
* For declines and other failures, use the failure cards on the [Cards test page](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/test-s2s/one-time/cards.md). They behave the same on non-INR orders.

### International test cards

| Use it to test | Card number | Notes |
| - | - | - |
| International card | `4012 8888 8888 1881` | Use for Flow 1, Flow 2 and refunds |
| International card with billing address | `5105 1051 0510 5100` | Asks for a billing address (AVS) |

### Amounts and currencies

`amount` is always in the smallest unit of the order's currency. Test at least one INR order and one order in every non-INR currency you will charge in. If you sell in zero- or three-decimal currencies, test those too.

| Currency type | Example | Price | Send `amount` |
| - | - | - | - |
| INR (Flow 1) | INR | ₹10,000.00 | `1000000` |
| Two-decimal (Flow 2) | USD, EUR, GBP | USD 100.00 | `10000` |
| Zero-decimal (Flow 2) | JPY | ¥1,000 | `1000` |
| Three-decimal (Flow 2) | KWD, BHD, OMR | KWD 10.500 | `10500` (last digit must be 0) |

## 3. Scenarios to Test Your Integration

* **Must-have (5):** the paths where money moves. All have to pass before you go live.
* **Other common scenarios (5):** things that happen in normal operation.
* **Error scenarios (4):** failures you trigger on purpose. Exact errors are in [Simulate failures](#6-simulate-failures).
* **Not available in test mode (4):** check these in a small live test.

Every scenario is self-contained. Each one creates its own order and payment, so you can run any scenario on its own, in any order. There are 18 scenarios in all: 14 you can run in test mode today and 4 you cannot. Any INR conversion in test mode uses dummy FX rates.

### 3.1 Must-have

<table>
  <thead><tr><th>Scenario ID</th><th>Flow</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th><th>Expected result</th></tr></thead>

  <tbody>
    <tr><td>**INTL-01**</td><td>Flow 1</td><td>INR order paid with an international card</td><td>`4012 8888 8888 1881`, order in INR</td><td>1. Create an order: `{"amount": 1000000, "currency": "INR", "receipt": "intl_01"}`.\
    2\. Create the payment with that `order_id` and the international card; complete authentication.\
    3\. Call `GET /v1/payments/{payment_id}`.</td><td>**Check:** `status: captured`, `international: true`, `currency: INR`, `amount: 1000000`.\
    **Webhooks:** `payment.authorized`, `payment.captured`, `order.paid`\
    **Your integration should:** store `payment_id`, `order_id` and `receipt` so the payment can be matched to its settlement recon line later.</td></tr>
    <tr><td>**INTL-02**</td><td>Flow 2</td><td>Non-INR order paid with an international card</td><td>`4012 8888 8888 1881`, order in USD</td><td>1. Create an order: `{"amount": 10000, "currency": "USD", "receipt": "intl_02"}`.\
    2\. Pay with the international card, using the same currency in the payment request.\
    3\. Call `GET /v1/payments/{payment_id}`.</td><td>**Check:** `status: captured`, `international: true`, `currency: USD`, `amount: 10000`.\
    **Webhooks:** `payment.authorized`, `payment.captured`, `order.paid`\
    **Your integration should:** keep the presented amount and currency for the customer and refunds. Take the INR converted and settled amounts from the Settlement Recon API, never from `amount` or your own FX rate.</td></tr>
    <tr><td>**INTL-03**</td><td>Flow 1, 2</td><td>Fetch settlement recon details and map them to payments</td><td>Your test API keys</td><td>1. Call `GET /v1/settlements/recon/combined?year=YYYY&month=MM&day=DD`.\
    2\. Call it again with `count` and `skip` to check pagination.\
    3\. Run your mapping logic: `type: payment` lines on `entity_id` or `order_id`, `type: refund` lines on `payment_id`.</td><td>**Check:** HTTP 200 with `entity: collection`. Your code handles a collection with no payment lines (test mode has no settlements) and pages until all lines are read.\
    **Webhooks:** None\
    **Your integration should:** record `credit` as the settled amount for each payment and `debit` for each refund, in INR paise. Settled values are verified live in INTL-X2.</td></tr>
    <tr><td>**INTL-04**</td><td>Flow 3</td><td>Full refund of an INR order</td><td>`4012 8888 8888 1881`, order in INR</td><td>1. Create an order: `{"amount": 1000000, "currency": "INR", "receipt": "intl_04"}`.\
    2\. Pay it with the international card and confirm it is captured.\
    3\. `POST /v1/payments/{payment_id}/refund` with `{"amount": 1000000, "speed": "normal"}`.\
    4\. Fetch the payment.</td><td>**Check:** Refund `currency: INR`, moves to `processed`. Payment shows `refund_status: full`, `amount_refunded: 1000000`.\
    **Webhooks:** `refund.created`, `refund.processed` (or `refund.failed`)\
    **Your integration should:** tell the customer the refund was issued in INR and their bank may convert it at a different rate.</td></tr>
    <tr><td>**INTL-05**</td><td>Flow 3</td><td>Full refund of a non-INR order</td><td>`4012 8888 8888 1881`, order in USD</td><td>1. Create an order: `{"amount": 10000, "currency": "USD", "receipt": "intl_05"}`.\
    2\. Pay it with the international card and confirm it is captured.\
    3\. `POST /v1/payments/{payment_id}/refund` with `{"amount": 10000, "speed": "normal"}`, that is USD 100.00 in cents, not an INR converted value.\
    4\. Fetch the payment.</td><td>**Check:** Refund `currency: USD`, `amount: 10000`, moves to `processed`. Payment shows `refund_status: full`.\
    **Webhooks:** `refund.created`, `refund.processed` (or `refund.failed`)\
    **Your integration should:** build refund amounts from the payment's `amount` and `currency` only.</td></tr>
  </tbody>
</table>

### 3.2 Other Common Scenarios

<table>
  <thead><tr><th>Scenario ID</th><th>Flow</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th><th>Expected result</th></tr></thead>

  <tbody>
    <tr><td>**INTL-06**</td><td>Flow 2</td><td>Non-INR orders in two different currencies</td><td>`4012 8888 8888 1881`, orders in USD and EUR (or GBP)</td><td>1. Create `{"amount": 10000, "currency": "USD"}` and `{"amount": 10000, "currency": "EUR"}`.\
    2\. Pay each with the international card.\
    3\. Fetch both payments.</td><td>**Check:** Both captured, each in its own presentment currency.\
    **Webhooks:** `payment.captured`, `order.paid`\
    **Your integration should:** have no hard-coded rates or currency lists. INR values for every currency come from the Settlement Recon API.</td></tr>
    <tr><td>**INTL-07**</td><td>Flow 3</td><td>Partial refunds in the presentment currency</td><td>`4012 8888 8888 1881`, order in USD</td><td>1. Create an order: `{"amount": 10000, "currency": "USD", "receipt": "intl_07"}` and pay it.\
    2\. Refund `3000` (USD 30.00) and fetch the payment.\
    3\. Refund `7000` (USD 70.00) and fetch again.</td><td>**Check:** After the first: `refund_status: partial`, `amount_refunded: 3000`. After the second: `full`, `10000`. Both refunds in USD.\
    **Webhooks:** `refund.created`, `refund.processed` for each\
    **Your integration should:** track the refundable balance in the presentment currency: `amount − amount_refunded`.</td></tr>
    <tr><td>**INTL-08**</td><td>Flow 2</td><td>Zero- and three-decimal currencies</td><td>`4012 8888 8888 1881`, orders in JPY, KWD (only if you sell in them)</td><td>1. Create `{"amount": 1000, "currency": "JPY"}` and `{"amount": 10500, "currency": "KWD"}`.\
    2\. Pay each and fetch the payment.</td><td>**Check:** Customer is charged ¥1,000 and KWD 10.500.\
    **Webhooks:** `payment.captured`, `order.paid`\
    **Your integration should:** convert prices using each currency's exponent, not by always multiplying by 100.</td></tr>
    <tr><td>**INTL-09**</td><td>Flow 2</td><td>Retry on the same non-INR order after a decline</td><td>`4100 2800 0005 0004` + **Failure**, then `4012 8888 8888 1881`</td><td>1. Create a USD order: `{"amount": 10000, "currency": "USD", "receipt": "intl_09"}`.\
    2\. Pay with the decline card and choose **Failure**.\
    3\. Pay the same order again with the international card.</td><td>**Check:** First payment failed with `card_declined`. Second captured. Order goes `attempted` → `paid`.\
    **Webhooks:** `payment.failed`, then `payment.captured`, `order.paid`\
    **Your integration should:** expect only the captured payment to appear in settlement recon. Do not wait for a line for the failed one.</td></tr>
    <tr><td>**INTL-10**</td><td>Flow 1, 2</td><td>International card that asks for a billing address</td><td>`5105 1051 0510 5100`, orders in INR and USD</td><td>1. Create an INR order and a USD order.\
    2\. Pay each with this card; collect and send the billing address when asked.\
    3\. Fetch both payments.</td><td>**Check:** Both succeed, each in its own presentment currency.\
    **Webhooks:** `payment.authorized`, `payment.captured`, `order.paid`\
    **Your integration should:** handle the billing address step without losing the order's currency.</td></tr>
  </tbody>
</table>

### 3.3 Error Scenarios

<table>
  <thead><tr><th>Scenario ID</th><th>Flow</th><th>Scenario</th><th>Trigger creds</th><th>Steps to follow</th><th>Expected result</th></tr></thead>

  <tbody>
    <tr><td>**INTL-E1**</td><td>All</td><td>International payments not enabled</td><td>`4012 8888 8888 1881` on an account without international enabled</td><td>1. Create an INR order.\
    2\. Pay with the international card.</td><td>**Check:** `international_transaction_not_allowed`. No payment captured.\
    **Webhooks:** `payment.failed` if the payment was created\
    **Your integration should:** show `error.description` and offer another payment method.</td></tr>
    <tr><td>**INTL-E2**</td><td>Flow 2</td><td>Currency not enabled or not valid</td><td>Order in a currency not enabled; `"currency": "XYZ"`</td><td>1. Create an order in each currency.</td><td>**Check:** HTTP 400 and no order created.\
    **Webhooks:** None\
    **Your integration should:** only offer currencies enabled on your account at checkout.</td></tr>
    <tr><td>**INTL-E3**</td><td>Flow 3</td><td>Refund more than the payment amount</td><td>`4012 8888 8888 1881`, order in USD</td><td>1. Create a USD order (`10000`) and pay it.\
    2\. Refund with an INR converted value in paise (for example `880000`), as if mixing up INR and USD.</td><td>**Check:** Refund rejected with HTTP 400. No refund created.\
    **Webhooks:** None\
    **Your integration should:** validate refund amounts against `amount − amount_refunded` in the presentment currency before calling the API.</td></tr>
    <tr><td>**INTL-E4**</td><td>Flow 3</td><td>Refund a payment that is already fully refunded</td><td>`4012 8888 8888 1881`, order in USD</td><td>1. Create a USD order (`10000`) and pay it.\
    2\. Refund `10000`.\
    3\. Refund it again.</td><td>**Check:** Second refund rejected with HTTP 400.\
    **Webhooks:** `refund.created`, `refund.processed` for the first refund only\
    **Your integration should:** block refunds once `refund_status` is `full`.</td></tr>
  </tbody>
</table>

### 3.4 Not Available in Test Mode

| Scenario ID | Flow | Scenario | How to check it | Steps to follow | Why it is not in test mode |
| - | - | - | - | - | - |
| **INTL-X1** | Flow 1, 2 | Issuer conversion, markup and charges on the cardholder's statement | A real international card | Make a small live payment and compare the statement amount with the presented amount. | Live only. Done by the issuing bank. |
| **INTL-X2** | Flow 1, 2, 3 | Settled amounts in the Settlement Recon API | Small live payments in INR and a non-INR currency, one refunded | After settlement, call the recon API for that date. Check each payment line has `credit = amount − fee` in INR, and the refund line has the INR debit (at the original transaction-time rate for a non-INR payment) and the right `payment_id`. | Live only. No settlements in test mode. |
| **INTL-X3** | Flow 3 | Refund credit on the cardholder's statement after reconversion | A small live payment with a real international card | Refund it and check the credit with the cardholder. | Live only. Done by the issuing bank. |
| **INTL-X4** | Flow 2 | Actual mid-market rate in the INR converted amount | A small live non-INR payment | Divide the INR amount on its recon line by the presented amount and compare with the mid-market rate at transaction time. | Live only. Test mode uses dummy FX rates that may not match mid-market rates and are subject to change. |

## 4. Webhooks: What Fires and What It Lets You Decide

| Event | FX-relevant fields | What to do |
| - | - | - |
| `payment.captured` | `id`, `order_id`, `amount`, `currency`, `international` | Fulfil, and store the IDs you will match against settlement recon lines. |
| `order.paid` | Order amount, currency, receipt, plus the payment entity | Mark the order paid. |
| `payment.failed` | `error.reason` | Keep the order open for a retry. Nothing will settle for this payment. |
| `refund.created` / `refund.processed` / `refund.failed` | Refund amount, currency (the payment's currency) | Update refund state and refundable balance in the presentment currency. |
| `settlement.processed` | Settlement `id`, `utr`, total amount | Call the Settlement Recon API for that settlement date to get the per-payment `credit` and per-refund `debit`. |

## 5. Common Integration Gaps to Avoid

| Gap | What goes wrong in production | What to do | Test with |
| - | - | - | - |
| Settled amount computed from the presented amount | For a USD 100 payment your books say 10,000 − fee, which is meaningless in INR. | Use `credit` from the payment's settlement recon line. | INTL-02, INTL-03, INTL-X2 |
| Own FX rate used | Your INR figures never match the settlement because your rate and timing differ from Razorpay's. | Take the INR converted amount from the recon line. Never recompute it. | INTL-06, INTL-X4 |
| Test-mode INR values hard-coded | Tests break when test-mode dummy rates change, and live values never match them. | Do not assert fixed INR numbers in tests. | INTL-06 |
| Recon pagination ignored | Busy settlement days have more lines than one call returns, so some payments look unsettled. | Page with `count` and `skip` until all lines are read. | INTL-03 |
| GST subtracted twice | Settled amount recorded short by the GST amount. | `credit` is already net of `fee`, which includes tax. | INTL-X2 |
| Refund built from an INR converted value | Refund rejected, or the wrong amount refunded. | Refund in the payment's `amount` and `currency`. | INTL-05, INTL-E3 |
| Every currency multiplied by 100 | JPY customers charged 100× the price. KWD amounts rejected. | Use each currency's exponent. | INTL-08 |
| Issuer markup treated as a Razorpay charge | Support tells customers Razorpay overcharged them. | Explain that the bank converts and marks up. See the [FAQs](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/json/v2/build-integration/international-cards/forex-conversion.md#faqs). | INTL-X1 |
| Promising refunds match the original debit | Customers complain that the refund in their currency is smaller. | Tell customers the bank reconverts at the refund-date rate. | INTL-X3 |

## 6. Simulate Failures

Branch on `error.reason`, never on the description text.

| ID | Trigger | `error.code` | `error.reason` | `error.description` | HTTP |
| - | - | - | - | - | - |
| INTL-E1 | International card when international payments are not enabled | `BAD_REQUEST_ERROR` | `international_transaction_not_allowed` | International cards are not supported. Please contact our support team for help | 400 |
| INTL-E2 | Order in a currency other than your account currency, without international payments enabled | `BAD_REQUEST_ERROR` | `input_validation_failed` | Order Currency is not supported | 400 |
| INTL-E2 | `"currency": "XYZ"` | `BAD_REQUEST_ERROR` | `invalid_currency` | Currency is not supported | 400 |
| INTL-E3 | Refund more than the payment amount (for example, an INR converted value on a USD payment) | `BAD_REQUEST_ERROR` | n/a | The total refund amount is greater than the refund payment amount | 400 |
| INTL-E4 | Refund a payment that is already fully refunded | `BAD_REQUEST_ERROR` | n/a | The payment has been fully refunded already | 400 |

[Back to Forex Conversion](https://razorpay.com/docs/payments/payment-gateway/s2s-integration/json/v2/build-integration/international-cards/forex-conversion.md)
