Razorpay

The Razorpay app makes Razorpay the payment gateway for credit cards in your Swell store. Shoppers pay in Razorpay's window in Swell's hosted checkout, and Razorpay saves their card. The app captures payments when Swell takes them, charges the saved card for subscription renewals and later charges, and refunds payments from the order.

Card details stay with Razorpay. Swell keeps Razorpay's token for the card with its brand, last four digits and expiry date. Before the app takes any money, it checks the Razorpay payment against the Swell payment's amount, currency and card method, and it never takes the money twice for one Swell payment, even when a request is retried.

Install Razorpay from the Swell App Store, and set it up in your test environment before the live one.

When a shopper chooses to pay by card, the checkout shows You will enter your card details in a secure Razorpay window. When they click Complete order, the app creates a Razorpay order for the cart's total and opens the Razorpay window, with the shopper's name, email address and phone number filled in. The window offers cards only. If a card is declined, the shopper can try again in the same window. If they close it, the order isn't placed, with the error Payment cancelled or the reason the last attempt failed.

When the shopper pays, Razorpay authorizes the payment and saves the card for later charges. The app checks the payment's signature with your Key secret, and the order is placed with the authorized payment and the saved card: Razorpay's token, the card brand, the last four digits and the expiry date. The Razorpay payment is set to manual capture, so Swell decides when it's captured.

The first time a customer pays, the app creates a Razorpay customer with their name, email address and phone number, and keeps it on their Swell account. Their later checkouts and charges use the same Razorpay customer, even if their phone number changes.

Swell decides when a payment is captured, with Charge automatically and Require payment authorization under Settings > Orders:

To capture an authorized payment, open the order and click Charge order. Keep the amount at the authorized amount and click the Charge button. The app captures the Razorpay payment after checking that it's a card payment for the same amount and currency, and that no other Swell payment has used it.

Razorpay keeps an authorization from the checkout for 5 days. After that, the capture fails with The authorization is no longer valid; charge the saved card with a new payment. Click Charge order again to charge the saved card. To take a different amount than the authorization, enter it in Charge order: the app charges the saved card with a new payment, and Razorpay releases the authorization when it expires.

When Razorpay doesn't answer a capture, or answers with a server error, the capture fails, and the app doesn't charge the saved card instead, because the capture may still go through. Check the payment in the Razorpay Dashboard before you charge the order again: a new Charge order charges the saved card.

The app charges the shopper's saved card with a new Razorpay payment when a charge has no usable authorization, such as a subscription renewal, a Charge order after the authorization expired, or a different amount. The shopper doesn't need to be present.

Razorpay takes several seconds to charge a saved card, so the payment shows Pending in the order's Transactions, and a workflow finishes it, usually within seconds. It then shows Paid, or Error with the reason. The runs are listed under Apps > Razorpay > Workflows. Every 30 minutes, the app also finishes saved card charges that are still pending, for example after a workflow failed.

A saved card can be charged up to ₹10,000 at a time, or 10,000 in another currency with two decimals. The customer's account needs an email address, and a phone number unless the app already created their Razorpay customer.

In live mode, Razorpay charges a saved Indian card only after it notifies the cardholder, about 36 hours later. Until then, the payment stays Pending. The app checks it every 6 hours, for up to 8 days, and records it as Paid once Razorpay has charged the card. If the card still isn't charged after 8 days, the payment fails with Saved card payment … was not finalized: Payment is still pending (status: created) after 8 days. In test mode, saved cards are charged without the wait.

To refund a payment, open the order and click Refund order. Choose the payment, enter the Refund amount and an optional Reason, and click the Refund button. The app refunds the amount to the card through Razorpay. You can refund a payment in full or in parts, up to the amount paid. Refunds made in the Razorpay Dashboard aren't sent to Swell.

The app supports subscriptions, so the card payment method is offered at checkout for carts with subscription products. The first payment is taken at checkout. Renewals are charged on the saved card with no checkout, when Swell charges the subscription. With Charge automatically on under Settings > Subscriptions, that's when the renewal is due.

Each renewal payment shows Pending until its workflow finishes it, which on a live Indian card takes about 36 hours.

Every Razorpay order the app creates for a saved card charge carries the Swell payment's ID as its receipt. When a charge is retried, the app finds the earlier Razorpay payment by that receipt and finishes it instead of charging the card again. A new saved card payment is created at most once. If Razorpay's answer is lost, the app waits a minute and looks for the payment before it records anything.

A Razorpay payment the app captures is marked with its Swell payment, and the app never uses it for another one. If the app finds a Razorpay payment that was captured but not by the app, for example in the Razorpay Dashboard, it stops with Payment already captured but not recorded; contact support rather than charging again.

Settings are in Settings > Payments: under Credit cards, click Edit settings while Razorpay is the payment gateway. The same settings are in Apps > Razorpay > Settings. They're saved separately for each environment.

Errors at checkout are shown to the shopper. A charge or refund that fails shows Error in the order's Transactions, with the reason when you point at it. The app also logs its errors. In the Swell dashboard, the logs are under Developer > Console > Logs, and saved card charges are under Apps > Razorpay > Workflows.

Razorpay is not configured means no Key ID is saved in this environment, and Razorpay keys are not configured that the Key ID or the Key secret is missing. Enter both under Settings > Payments and save. Razorpay checkout could not be loaded means the shopper's browser couldn't load Razorpay's checkout script from checkout.razorpay.com. The shopper can click Complete order again.

Razorpay needs the shopper's email address and phone number to save the card. Under Settings > Checkout > Form fields, set Phone number to Required. The same messages ending in to charge the saved card mean the customer's account is missing them. Add them to the account, then charge the order again.

Razorpay authorized the payment without saving the card, so the order isn't placed, and Razorpay releases the authorization after 5 days. Check that recurring card payments are enabled on your Razorpay account. Razorpay decides which cards can be saved, so the shopper can also try another card.

Razorpay's signature on the payment didn't match your Key secret, so the order isn't placed and the payment is left uncaptured. The shopper can pay again.

Razorpay refused the request, and the rest of the message is Razorpay's reason. Check the keys, that test keys are used in the test environment and live keys in the live one, and that recurring card payments are enabled on your Razorpay account.

A saved card charge shows Pending until its workflow finishes, usually within seconds. On a live Indian card it waits for Razorpay to notify the cardholder, about 36 hours. Open Apps > Razorpay > Workflows to see the run and its steps. If a run failed, the app finishes the charge within 30 minutes. If Razorpay has no payment for it by then, the payment fails with The saved card charge did not complete, and nothing was charged.

The authorization expired or was released before it was captured, for example after 5 days. Click Charge order again to charge the saved card.

The Razorpay payment was captured, but not by this Swell payment, for example in the Razorpay Dashboard. The app doesn't charge the card again. Check the payment in the Razorpay Dashboard, and email support@swell.is.

A saved card payment exists in Razorpay but couldn't be completed, and its money may be on hold or taken. The message names the Razorpay payment and the reason. Look it up in the Razorpay Dashboard before you charge the order again. Saved card payment … is still pending (status: created); contact support means a charge was retried while Razorpay was still waiting to charge the card.

No Razorpay payment to refund means the Swell payment has no Razorpay payment ID. Other reasons start with Razorpay: and come from Razorpay.

Uninstalling the app removes its functions, its workflow and its settings, including your API keys, and removes Razorpay from the Payment gateway options. Uninstalling applies to the environment you are in, so remove the app from the test and live environments separately.

Before you uninstall, choose another payment gateway for Credit cards under Settings > Payments. Uninstalling doesn't change the card method's gateway, and while it's still Razorpay, card payments stop working: Charge order and subscription renewals fail with an error that the payment app isn't installed.

Wait until no saved card charge shows Pending. After the app is removed, nothing finishes them: the Swell payment stays pending, and the Razorpay payment isn't captured.

Cards saved through the app are Razorpay tokens and can only be charged through Razorpay. Subscriptions paid with a saved card need a new card from the customer to renew on another gateway. Customers, saved cards, payments and refunds stay in your Razorpay account. The app isn't notified when it's uninstalled, so if you no longer need the API keys, regenerate them in the Razorpay Dashboard under Account & Settings > API Keys.

The app is the gateway of Swell's card method through a payment extension with subscriptions: true, so the gateway ID is app_<app id>_card. Its settings are key_id, which is public, and key_secret, in the card settings. The Razorpay customer is kept on the account under $app.razorpay as customer_id and contact, the phone it was created with.

The checkout component, components/Razorpay.tsx, is an @swell/apps-sdk component on the card extension and the checkout.payment.methods target. On submit it loads https://checkout.razorpay.com/v1/checkout.js, calls createIntent with the cart's capture_total in the currency's smallest unit, opens the window with recurring: '1' and a card-only display block, and passes the signed response to getIntent. It returns billing.card with the token, last4, brand, exp_month and exp_year, and billing.intent.razorpay.id.

The app calls the Razorpay API at https://api.razorpay.com/v1 with Basic auth: POST /customers with fail_existing: '0', POST /orders, GET /orders?receipt=…, GET /orders/{id}/payments, GET /payments/{id} with expand[]=token, POST /payments/create/recurring, PATCH /payments/{id} for notes, POST /payments/{id}/capture and POST /payments/{id}/refund. Errors are thrown as Razorpay: <description>. The checkout order has method: card, token.max_amount: 1000000 with frequency: as_presented, and manual capture with manual_expiry_period: 7200. Amounts are converted to the smallest unit in lib/amount.ts, with zero-decimal and three-decimal currencies.

get_intent checks the HMAC-SHA256 hex signature of order_id|payment_id with the key secret in constant time. card-charge takes the Razorpay payment from transaction_id or intent.razorpay.id, and uses it only when it's a card payment with the Swell payment's amount and currency, authorized, and not marked with another Swell payment in notes.swell_payment_id. After a capture it writes that note. A captured payment without the note fails closed. A capture that gets a network error, a 408, a 429 or a 5xx while the payment is still authorized fails the charge. Only another 4xx refusal falls back to the saved card.

A saved card charge reads the customer, looks up earlier attempts and creates an order with payment_capture: false, receipt set to the Swell payment ID, in parallel. An earlier payment is finished in the hook. Otherwise the hook starts card-charge-finish with identifiers only and answers async: true, because creating a recurring payment takes Razorpay longer than the hook can wait. While a Swell payment is async without success, a new charge of it answers async: true and creates nothing. A capture of a Swell payment that already has its result never starts a saved card charge.

The workflow's steps are check pending, charge saved card (never retried), wait for Razorpay and find by receipt after an unknown outcome, read payment and wait for debit 1 to wait for debit 32 at 6-hour intervals, capture, record and late capture. Each step that calls Razorpay reads the keys itself and doesn't return them. Step names are the step cache keys, so they mustn't change while runs sleep. The sweep reads the gateway from /settings/payments, reads up to 10 async, pending, non-void card payments of that gateway, newest first, works on 5 at a time and starts none after 6 seconds.

Swell builds and maintains the Razorpay app. For help with the app, email support@swell.is. For questions about your Razorpay account, API keys or recurring payments, contact Razorpay.