Integrate Magic Checkout on iOS App
Steps to integrate Magic Checkout on your iOS app using the Razorpay iOS Standard SDK.
Follow these steps to integrate the Razorpay Magic Checkout on your iOS application.
- Create a Razorpay account.
- Generate from the Dashboard. To go live with the integration and start accepting real payments, generate Live Mode API Keys and replace them in the integration.
Follow the steps given below:
Raise a request with your Razorpay SPOC to get this feature enabled on your account. Once this feature is enabled, the customer address saving and coupon features are enabled.
Follow the steps given below to create promotions and shipping info API endpoints:
Watch Out!
Ensure that the URLs are publicly accessible, require no authentication and are hosted on your server.
- Log in to the Dashboard and navigate to Magic Checkout.
- In the Platform Setup, select Custom E-Commerce Platform from the drop-down list and click Next.
- In the Setup & Settings section, click Checkout Settings.
- In the Coupon Settings section, enter the following:
- URL for get promotions: The API URL should return a list of promotions applicable to the specified order_id and customer. Magic Checkout uses this endpoint to fetch these promotions from your server and display them to your customers in the checkout modal.
- URL for apply promotions: The API URL validates the promotion code applied by the customer and should return the discount amount. Magic Checkout uses this endpoint to apply promotions via your server.
- Click Save settings.
- Navigate to Shipping Setup.
- Select API as the Shipping Service type from the drop-down list.
- Enter the URL for shipping info. The API URL should return shipping serviceability, COD serviceability, shipping fees and COD fees for a given list of customer addresses. Magic Checkout uses this endpoint to retrieve shipping information from your server.
- Click Save Settings.
You can import the Razorpay iOS Standard SDK library using any of these ways:
Refer to our
(bitcode enabled) pod.
To initialise Razorpay iOS Standard SDK, you need the following:
-
API keys. You can generate this from the
.Watch Out!
API keys should not be hardcoded in the app. Must be sent from your backend as app-related metadata fetch.
-
A delegate that implements
RazorpayPaymentCompletionProtocolorRazorpayPaymentCompletionProtocolWithData.
Watch Out!
- For Swift version 5.1+, ensure that you declare
var razorpay: RazorpayCheckout!. - For versions lower than 5.1, use
var razorpay: Razorpay!. - Alternatively, you can use the following alias and retain the variable as Razorpay.
typealias Razorpay = RazorpayCheckout
import Razorpayclass ViewController: UIViewController, RazorpayPaymentCompletionProtocol {// typealias Razorpay = RazorpayCheckoutvar razorpay: RazorpayCheckout!override func viewDidLoad() {super.viewDidLoad()razorpay = RazorpayCheckout.initWithKey(razorpayTestKey, andDelegate: self)}override func viewWillAppear(_ animated: Bool) {super.viewWillAppear(animated)self.showPaymentForm()}}
You can create an order using the following API and send the additional information required for Magic Checkout. Pass the order_id received in response to the checkout code.
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \-X POST https://api.razorpay.com/v1/orders \-H "content-type: application/json" \-d '{"amount": 50000,"currency": "INR","receipt": "receipt#1","notes": {},"line_items_total": 50000,"line_items": [{"sku": "1g234","variant_id": "12r34","other_product_codes": {"upc": "12r34","ean": "123r4","unspsc": "123s4"},"price": 50000,"offer_price": 50000,"tax_amount": 0,"quantity": 1,"name": "TEST","description": "TEST","weight": 1700,"dimensions": {"length": 1700,"width": 1700,"height": 1700},"image_url": "url","product_url": "url","notes": {}}]}'
{"id": "order_EKwxwAgItmmXdp","entity": "order","amount": 50000,"amount_paid": 0,"amount_due": 50000,"currency": "INR","receipt": "receipt#1","offer_id": null,"status": "created","attempts": 0,"notes": [],"created_at": 1582628071,"line_items_total": 50000}
amount
mandatory
integer The transaction amount, expressed in the currency subunit, such as paise (in case of INR). For example, for an actual amount of ₹299.35, the value of this field should be 29935.
currency
mandatory
string The currency in which the transaction should be made. See the
INR. Length must be of 3 characters.receipt
mandatory
string Your receipt id for this order should be passed here. Maximum length of 40 characters.
notes
optional
object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty".
line_items_total
mandatory
integer Total of offer_price for all line items added to the cart, in paise. For example, if a shoe worth ₹8,000 and a shirt worth ₹10,000 are added, the line_item_total will be 1800000. This amount is post-tax.
Watch Out!
To ensure the order is considered as a Magic Checkout order, you must pass this parameter. Otherwise, it will default to Standard Checkout order, and customers will view the Standard Checkout UI instead of Magic Checkout. Know more about
.line_items
mandatory
array This will have the details about the specific items added to the cart.
sku
mandatory
string Unique product id defined by you. It can be alphanumeric.
variant_id
mandatory
string Unique variant id defined by you. It can be alphanumeric.
other_product_codes
optional
object Array to collect different codes that can identify the item type.
upc
optional
string Universal Product Code (UPC; redundantly: UPC code) is a barcode symbology used worldwide to track trade items in stores. UPC consists of 12 numeric digits that are uniquely assigned to each trade item.
ean
optional
string European Article Numbers (EAN) is a type of barcode that encodes an article number. Contains 8 (EAN-8) or 13 (EAN-13) numerical digits.
unspsc
optional
string The United Nations Standard Products and Services Code (UNSPSC) is a taxonomy of products and services used in ecommerce. It is a four-level hierarchy coded as an eight-digit number, with an optional fifth level adding two more digits.
price
mandatory
integer Price of the product in paise.
offer_price
mandatory
integer Final price charged to the customer in paise, after applying any adjustments, such as product discounts.
Handy Tips
If no discount is applied, price and offer_price will be the same.
tax_amount
mandatory
integer The tax levied on the product.
quantity
mandatory
integer Number of units added in the cart.
name
mandatory
string Name of the product.
description
mandatory
string Description of the product.
weight
optional
integer Weight of the product in grams.
dimensions
optional
object The dimensions of the product.
length
optional
string The length of the product in centimeters.
width
optional
string The width of the product in centimeters.
height
optional
string The height of the product in centimeters.
image_url
optional
string The URL of the product image. This parameter is mandatory if you want to display product images on our iframe.
product_url
optional
string URL of the product's listing page.
notes
optional
object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty".
id
string The unique identifier of the order.
amount
integer Payment amount in the smallest currency sub-unit. For example, if the amount to be charged is $299.00, then pass 29900 in this field.
partial_payment
boolean Indicates whether the customer can make a partial payment. Possible values:
true: The customer can make partial payments.false(default): The customer cannot make partial payments.
amount_paid
integer The amount paid against the order.
amount_due
integer The amount pending against the order.
currency
string ISO code for the currency in which you want to accept the payment. The default length is 3 characters.
receipt
string Receipt number that corresponds to this order. Can have a maximum length of 40 characters and has to be unique.
status
string The status of the order. Possible values:
created: When you create an order it is in thecreatedstate. It stays in this state till a payment is attempted on it.attempted: An order moves fromcreatedtoattemptedstate when a payment is first attempted on it. It remains in theattemptedstate till one payment associated with that order is captured.paid: After the successful capture of the payment, the order moves to thepaidstate. No further payment requests are permitted once the order moves to thepaidstate. The order stays in thepaidstate even if the payment associated with the order is refunded.
attempts
integer The number of payment attempts, successful and failed, that have been made against this order.
notes
json object Key-value pair that can be used to store additional information about the entity. Maximum 15 key-value pairs, 256 characters (maximum) each. For example, "note_key": "Beam me up Scotty”.
created_at
integer Indicates the Unix timestamp when this order was created.
line_items_total
integer Total of offer_price for all line items added to the cart, in paise.
The error response parameters are available in the
.This API should return shipping serviceability, COD serviceability, shipping fees and COD fees for a given list of customer addresses.
{"order_id": "SomeReceiptValue", // This is the receipt field set in the Razorpay order"razorpay_order_id": "EKwxwAgItmmXdp", // This is the RZP order created without the `order_` prefix"email": "gaurav.kumar@example.com", // Email field will be set if the customer enters an email"contact": "+919900000000", // Customer phone number with country code"addresses": [{"id": "0","zipcode": "560060","state_code": "KA","country": "IN"}]}
order_id
mandatory
string Unique identifier of the order created
razorpay_order_id
mandatory
string Unique identifier for the order returned by Checkout.
mandatory
string Customer's email address.
contact
mandatory
string Customer's phone number.
addresses
mandatory
array Customer's address details.
id
mandatory
string Unique identifier of the customer's address.
zipcode
mandatory
string Customer's ZIP code.
state_code
optional
string The code of the state where the customer resides.
country
mandatory
string Country where the customer resides. The length cannot exceed 2 characters.
addresses
mandatory
array Customer's address details.
id
mandatory
string Unique identifier of the customer's address.
zipcode
mandatory
string Customer's ZIP code.
country
mandatory
string Country where the customer resides. The length cannot exceed 2 characters.
shipping_methods
mandatory
array Details regarding the shipping methods.
id
mandatory
string Unique identifier of the shipping method.
description
integer Brief description of the shipping method.
name
mandatory
string Name of the shipping method.
serviceable
mandatory
boolean Indicates whether you deliver orders to the zipcode entered by the customer. This is based on the ZIP codes you have added in the serviceability setting on the Razorpay Dashboard. Possible values:
true: Orders can be delivered to the added ZIP codes.false: Orders cannot be delivered to the added ZIP codes.
shipping_fee
mandatory
integer Shipping charge applicable to be paid by the customer.
cod
mandatory
boolean Indicates whether you support cash on delivery on this order.
true: COD payment method is supported.false: COD payment method is not supported.
cod_fee
mandatory
integer Additional amount charged by for you COD. This is based on the amount you have added to the COD setting on the Razorpay Dashboard.
Handy Tips
If the cod field is false, set the cod_fee field to 0.
This API should return the list of promotions applicable for the given order_id and customer.
{"order_id": "SomeReceiptValue", // this is the receipt field set in Razorpay order"contact": "+919000090000","email": "gaurav.kumar@example.com"}'
order_id
mandatory
string Unique identifier of the order created
contact
optional
string Customer's phone number.
optional
string Customer's email address.
promotions
mandatory
array Details of the promotions created.
code
mandatory
string Unique identifier of the promotion.
summary
mandatory
string Summary about the promotion. For example, 10% off on total cart value.
description
optional
string Brief description of the promotion. For example, 10% on total cart value upto ₹300.
This API should validate the promotion code applied by the customer and return the discount amount.
{"order_id": "SomeReceiptValue", // this is the receipt field set in Razorpay order"contact": "+919000090000","email": "gaurav.kumar@example.com","code": "500OFF"}'
order_id
mandatory
string Unique identifier of the order created
contact
optional
string Customer's phone number.
optional
string Customer's email address.
code
mandatory
string Promotion code used to avail discount on checkout.
promotion
mandatory
object Used to pass all offer or discount-related information, including promotion code discount, method discount and so on.
reference_id
mandatory
string Identifier of the offer you create.
code
optional
string Promotion code used to avail discount on checkout.
type
optional
string Type of offer. Possible values:
coupon: A discount applied by customers during checkout. For example, customers can use a coupon likeDiwali Sale 500 Offto get ₹500 off the total cart value.offer: A promotion you create for your customers. For example, you create an offerBuy 4 t-shirts and get 2 free. In this case, when customers add 4 t-shirts to their cart, the 2 additional t-shirts will be automatically added for free.
value
optional
integer The offer value that needs to be applied in paise. For example, if you want to offer a discount of ₹500, enter 50000.
value_type
optional
string The type of value like:
fixed_amount: A fixed amount discount value in the currency of the order. For example, ₹500.percentage: A percentage discount value. For example, 10%.BXGY: Buy X and Get Y. For example, if you buy 2 t-shirts, you a get a cap for free or at a discounted value.
Handy Tips
Regardless of the value_type, the amount specified in the value parameter is applied as-is. For example, if value_type is percentage and the value is 5000, 5000 is considered in currency subunits (paise).
description
optional
string Description of the promotion applied. For example, New Year Sale Offer.
Call RazorpayCheckout.checkIntegration(withMerchantKey: <merchant_key>) to check the health of integration. This will also let you know if the SDK version is outdated. The opinionated alerting is displayed only when it is running on simulators.
Add the following code to your ViewController or wherever you want to initialise payments:
internal func showPaymentForm(){let options: [String:Any] = ["key": "YOUR_KEY_ID","amount": "100", //This is in currency subunits. 100 = 100 paise= INR 1."currency": "INR",//We support more that 92 international currencies."description": "purchase description","order_id": "order_DBJOWzybf0sJbb","image": "https://url-to-image.jpg","name": "business or product name","prefill": ["contact": "9797979797","email": "gaurav.kumar@example.com"],"one_click_checkout": true, //magic checkout"show_coupons": true, //magic checkout"theme": ["color": "#F37254"]]razorpay.open(options)}
Optional Parameter - displayController
When the optional parameter- displayController, is specified, the Razorpay controller is pushed onto this controller's navigation controller if present or presented on this controller if absent.
razorpay.open(options, displayController: self)
key
mandatory
string API key id generated from the Dashboard.
amount
mandatory
integer The amount to be paid by the customer in currency subunits. For example, if the amount is $500.00, enter 50000.
currency
mandatory
string The currency in which the payment should be made by the customer. Length must be of 3 characters.
name
mandatory
string Your Business/Enterprise name shown on the Checkout form. For example, Acme Corp.
description
optional
string Description of the purchase item shown on the Checkout form. It should start with an alphanumeric character.
image
optional
string Link to an image (usually your business logo) shown on the Checkout form. Can also be a base64 string if you are not loading the image from a network.
order_id
mandatory
string Order id generated via
prefill
object You can prefill the following details at Checkout.
Boost Conversions and Minimise Drop-offs
- Autofill customer contact details, especially phone number to ease form completion. Include customer’s phone number in the
contactparameter of the JSON request'sprefillobject. Format: +(country code)(phone number). Example: "contact": "+919000090000". - This is not applicable if you do not collect customer contact details on your website before checkout, have Shopify stores or use any of the no-code apps.
name
optional
string Cardholder's name to be prefilled if customer is to make card payments on Checkout. For example, Gaurav Kumar.
optional
string Email address of the customer.
contact
optional
string Phone number of the customer. The expected format of the phone number is + {country code}{phone number}. If the country code is not specified, 91 will be used as the default value. This is particularly important while prefilling contact of customers with phone numbers issued outside India. Examples:
- +14155552671 (a valid non-Indian number)
- +919977665544 (a valid Indian number).
If 9977665544 is entered,+91is added to it as +919977665544.
method
optional
string Pre-selection of the payment method for the customer. Will only work if contact and email are also prefilled. Possible values:
cardnetbankingwalletupicod
notes
optional
object Set of key-value pairs that can be used to store additional information about the payment. It can hold a maximum of 15 key-value pairs, each 256 characters long (maximum).
one_click_checkout
mandatory
boolean Specifies whether to initiate Magic Checkout or Standard Checkout. Possible values:
true: Initiates Magic Checkout.false(default): Initiates Standard Checkout.
show_coupons
optional
boolean Determines whether to show the coupons to customer on the checkout. Possible values:
true(default): Enables the Coupon feature.false: Disables the Coupon feature.
theme
object Thematic options to modify the appearance of Checkout.
color
optional
string Enter your brand colour's HEX code to alter the text, payment method icons and CTA (call-to-action) button colour of the Checkout form.
backdrop_color
optional
string Enter a HEX code to change the Checkout's backdrop colour.
modal
object Options to handle the Checkout modal.
backdropclose
optional
boolean Indicates whether clicking the translucent blank space outside the Checkout form should close the form. Possible values:
true: Closes the form when your customer clicks outside the checkout form.false(default): Does not close the form when customer clicks outside the checkout form.
escape
optional
boolean Indicates whether pressing the escape key should close the Checkout form. Possible values:
true(default): Closes the form when the customer presses the escape key.false: Does not close the form when the customer presses the escape key.
handleback
optional
boolean Determines whether Checkout must behave similar to the browser when back button is pressed. Possible values:
true(default): Checkout behaves similarly to the browser. That is, when the browser's back button is pressed, the Checkout also simulates a back press. This happens as long as the Checkout modal is open.false: Checkout does not simulate a back press when browser's back button is pressed.
confirm_close
optional
boolean Determines whether a confirmation dialog box should be shown if customers attempts to close Checkout. Possible values:
true: Confirmation dialog box is shown.false(default): Confirmation dialog box is not shown.
ondismiss
optional
function Used to track the status of Checkout. You can pass a modal object with ondismiss: function()\{\} as options. This function is called when the modal is closed by the user. If retry is false, the ondismiss function is triggered when checkout closes, even after a failure.
animation
optional
boolean Shows an animation before loading of Checkout. Possible values:
true(default): Animation appears.false: Animation does not appear.
callback_url
optional
string Customers will be redirected to this URL on successful payment. Ensure that the domain of the Callback URL is allowlisted.
redirect
optional
boolean Determines whether to post a response to the event handler post payment completion or redirect to Callback URL. callback_url must be passed while using this parameter. Possible values:
true: Customer is redirected to the specified callback URL in case of payment failure.false(default): Customer is shown the Checkout popup to retry the payment with the suggested next best option.
customer_id
optional
string Unique identifier of customer. Used for:
- .
- Static bank account details on Checkout in case of .
remember_customer
optional
boolean Determines whether to allow saving of cards. Can also be configured via the
true: Enables card saving feature.false(default): Disables card saving feature.
timeout
optional
integer Sets a timeout on Checkout, in seconds. After the specified time limit, the customer will not be able to use Checkout.
Watch Out!
Some browsers may pause JavaScript timers when the user switches tabs, especially in power saver mode. This can cause the checkout session to stay active beyond the set timeout duration.
readonly
object Marks fields as read-only.
contact
optional
boolean Used to set the contact field as read-only. Possible values:
true: Customer will not be able to edit this field.false(default): Customer will be able to edit this field.
optional
boolean Used to set the email field as read-only. Possible values:
true: Customer will not be able to edit this field.false(default): Customer will be able to edit this field.
name
optional
boolean Used to set the name field as read-only. Possible values:
true: Customer will not be able to edit this field.false(default): Customer will be able to edit this field.
hidden
object Hides the contact details.
contact
optional
boolean Used to set the contact field as optional. Possible values:
true: Customer will not be able to view this field.false(default): Customer will be able to view this field.
optional
boolean Used to set the email field as optional. Possible values:
true: Customer will not be able to view this field.false(default): Customer will be able to view this field.
send_sms_hash
optional
boolean Used to auto-read OTP for cards and netbanking pages. Applicable from Android SDK version 1.5.9 and above. Possible values:
true: OTP is auto-read.false(default): OTP is not auto-read.
allow_rotation
optional
boolean Used to rotate payment page as per screen orientation. Applicable from Android SDK version 1.6.4 and above. Possible values:
true: Payment page can be rotated.false(default): Payment page cannot be rotated.
retry
optional
object Parameters that enable retry of payment on the checkout.
enabled
boolean Determines whether the customers can retry payments on the checkout. Possible values:
true(default): Enables customers to retry payments.false: Disables customers from retrying the payment.
max_count
integer The number of times the customer can retry the payment. We recommend you to set this to 4. Having a larger number here can cause loops to occur.
Watch Out!
Web Integration does not support the max_count parameter. It is applicable only in Android and iOS SDKs.
config
optional
object Parameters that enable configuration of checkout display language.
display
object Child parameter that enables configuration of checkout display language.
language
string The language in which checkout should be displayed. Possible values:
-
en: English -
ben: Bengali -
hi: Hindi -
mar: Marathi -
guj: Gujarati -
tam: Tamil -
tel: TeluguYou must pass these parameters in Checkout to initiate the payment.
Watch Out!
To support theme colour in the progress bar, please pass HEX colour values only.
Provide your customers with a better payment experience by enabling UPI Intent on your app's Checkout form. In the UPI Intent flow:
- Customer selects UPI as the payment method in your iOS app. A list of UPI apps supporting the intent flow is displayed. For example, PhonePe, Google Pay and Paytm.
- Customer selects the preferred app. The UPI app opens with pre-populated payment details.
- Customer enters their UPI PIN to complete their transactions.
- Once the payment is successful, the customer is redirected to your app or website.
To enable this in your iOS integration, you must make the following changes in your app's info.plist file.
<key>LSApplicationQueriesSchemes</key><array><string>tez</string><string>phonepe</string><string>paytmmp</string><string>credpay</string><string>mobikwik</string><string>in.fampay.app</string><string>bhim</string><string>amazonpay</string><string>navi</string><string>kiwi</string><string>payzapp</string><string>jupiter</string><string>omnicard</string><string>icici</string><string>popclubapp</string><string>sbiyono</string><string>myjio</string><string>slice-upi</string><string>bobupi</string><string>shriramone</string><string>indusmobile</string><string>whatsapp</string></array>
Know more about
.After completing payment, you can handle success or error events by implementing onPaymentSuccess and onPaymentError methods of the RazorpayPaymentCompletionProtocol.
Alternatively, you can implement onPaymentSuccess and onPaymentError methods of RazorpayPaymentCompletionProtocolWithData.
extension CheckoutViewController : RazorpayPaymentCompletionProtocol {func onPaymentError(_ code: Int32, description str: String) {print("error: ", code, str)self.presentAlert(withTitle: "Alert", message: str)}func onPaymentSuccess(_ payment_id: String) {print("success: ", payment_id)self.presentAlert(withTitle: "Success", message: "Payment Succeeded")}}
extension CheckoutViewController: RazorpayPaymentCompletionProtocolWithData {func onPaymentError(_ code: Int32, description str: String, andData response: [AnyHashable : Any]?) {print("error: ", code)self.presentAlert(withTitle: "Alert", message: str)}func onPaymentSuccess(_ payment_id: String, andData response: [AnyHashable : Any]?) {print("success: ", payment_id)self.presentAlert(withTitle: "Success", message: "Payment Succeeded")}}
After completing the payment, add necessary actions based on success or error events.
Failure Codes:
- 0: Network error
- 1: Initialization failure / Unexpected behaviour
- 2: Payment cancelled by the user
Success handler receives payment_id that you can use later for capturing the payment.
A successful payment returns the following fields to the Checkout form.
- You need to store these fields in your server.
- You can confirm the authenticity of these details by verifying the signature in the next step.
razorpay_payment_id
string Unique identifier for the payment returned by Checkout only for successful payments.
razorpay_order_id
string Unique identifier for the order returned by Checkout.
razorpay_signature
string Signature returned by the Checkout. This is used to verify the payment.
This is a mandatory step to confirm the authenticity of the details returned to the Checkout form for successful payments.
-
Create a signature in your server using the following attributes:
order_id: Retrieve theorder_idfrom your server. Do not use therazorpay_order_idreturned by Checkout.razorpay_payment_id: Returned by Checkout.key_secret: Available in your server. Thekey_secretthat was generated from the .
-
Use the SHA256 algorithm, the
razorpay_payment_idand theorder_idto construct a HMAC hex digest as shown below:generated_signature = hmac_sha256(order_id + "|" + razorpay_payment_id, secret);if (generated_signature == razorpay_signature) {payment is successful} -
If the signature you generate on your server matches the
razorpay_signaturereturned to you by the Checkout form, the payment received is from an authentic source.
Given below is the sample code for payment signature verification:
RazorpayClient razorpay = new RazorpayClient("[YOUR_KEY_ID]", "[YOUR_KEY_SECRET]");String secret = "EnLs21M47BllR3X8PSFtjtbd";JSONObject options = new JSONObject();options.put("razorpay_order_id", "order_IEIaMR65cu6nz3");options.put("razorpay_payment_id", "pay_IH4NVgf4Dreq1l");options.put("razorpay_signature", "0d4e745a1838664ad6c9c9902212a32d627d68e917290b0ad5f08ff4561bc50f");boolean status = Utils.verifyPaymentSignature(options, secret);
After you have completed the integration, you can
, make test payments, replace the test key with the live key and integrate with other .Handy Tips
On the Razorpay Dashboard, ensure that the payment status is captured. Refer to the payment capture settings page to know how to
To verify the payment status from the Razorpay Dashboard:
- Log in to the Razorpay Dashboard and navigate to Transactions → Payments.
- Check if a Payment Id has been generated and note the status. In case of a successful payment, the status is marked as Captured.
Based on the response, you can handle post-payment processing on your end.
Use the Fetch Orders API to retrieve order details, including customer information, address, shipping method and promotions of a particular order:
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]\-X GET https://api.razorpay.com/v1/orders/order_R1yDkxyIuKXXXX \
{"id": "order_R1yDkxyIuKXXXX","entity": "order","amount": 507000,"amount_paid": 0,"amount_due": 507000,"currency": "INR","receipt": "#30567","offers": ["offer_QXwkRH1bOvXXXX","offer_QXwoP07qnHXXXX","offer_QYrcJ29gBCXXXX","offer_QZDsVyMNzDXXXX","offer_QtfwFTZYkGXXXX","offer_Qtg3UsQyZaXXXX"],"status": "placed","attempts": 0,"notes": {"cart_id": "hWN2Am4BGnQrizKE3hzeQaXc?key=2b3cad31","storefront_id": "gid://shopify/Cart/hf5Q?key=14bbbce35b8","shopify_order_id": "6302119854247"},"created_at": 1756045901,"description": null,"checkout": null,"promotions": [{"code": "orderOff","type": "cart_value","value": 10000,"description": "order off","reference_id": "offer_ORnSr9d2eAXXXX"}],"cod_fee": 5000,"shipping_fee": 7000,"customer_details": {"contact": "+919100000000","email": "gaurav.kumar@example.com","shipping_address": {"city": "Bengaluru","contact": "+919100000000","country": "in","line1": "Houseno:24","line2": "Andree Road, Bheemanna Garden, Shanti Nagar","name": "Gaurav Kumar","state": "KARNATAKA","tag": "Home","type": "shipping_address","zipcode": "560001"},"billing_address": {"city": "Bengaluru","contact": "+919100000000","country": "in","line1": "Houseno:24","line2": "Andree Road, Bheemanna Garden, Shanti Nagar","name": "Gaurav Kumar","state": "KARNATAKA","tag": "Home","type": "shipping_address","zipcode": "560001"}},"line_items_total": 600000,"tax_details": {"total_tax": 4128,"taxes_included": true}}
Know more about the
Order Status
Check the order status for the following:
- Prepaid orders:
paid. - COD orders:
placed.
id
string Unique identifier of the order. For example, order_R1yDkxyIuKXXXX.
entity
string Type of entity. Value is order.
amount
integer Total order amount in the smallest currency unit (paise).
amount_paid
integer Amount paid towards the order in paise. For prepaid orders, this shows the actual amount paid. For COD orders, this is 0 until payment is collected.
amount_due
integer Outstanding amount due in paise. For prepaid orders, this shows any remaining balance. For COD orders, this equals the amount field until payment is collected.
currency
string The 3-letter ISO currency code. For example, INR.
receipt
string Receipt identifier for internal reference. For example, #30567.
offers
array Array of offer IDs applied to the order.
status
string Current status of the order. Possible values:
placed: Order placed but payment pending (COD orders).paid: Order placed and payment completed (prepaid orders).cancelled: Order cancelled.refunded: Order refunded.
attempts
integer Number of payment attempts made for this order. For example, 1.
notes
object Custom notes added to the order containing integration-specific data.
cart_id
string Shopping cart identifier.
storefront_id
string Storefront system identifier.
shopify_order_id
string Shopify order reference.
flits_cart_token
string Flits integration token (optional).
created_at
integer Unix timestamp indicating when the order was created. For example, 1756045901.
description
string|null Order description. Returns null if no description is provided.
checkout
string|null Checkout identifier. Returns null if not applicable.
promotions
array Array of promotion objects applied to the order.
code
string Promotion code used. For example, orderOff.
type
string Type of promotion. For example, cart_value.
value
integer Discount value in paise. For example, 10000 for ₹100.
description
string Human-readable promotion description.
reference_id
string Internal reference for the promotion.
cod_fee
integer Cash on Delivery charges in paise. For COD orders, this contains the fee amount (for example, 5000 for ₹50). For prepaid orders, this is 0.
shipping_fee
integer Shipping charges in paise. For example, 700 for ₹7.
customer_details
object Customer information.
contact
string Customer's phone number.
string Customer's email address.
shipping_address
object Complete shipping address information.
city
string City name.
contact
string Contact number for delivery.
country
string Country code. For example, in.
id
string Address identifier (optional).
line1
string Address line 1.
line2
string Address line 2.
name
string Recipient name.
state
string State name.
tag
string Address tag. For example, Home.
type
string Address type. Value is shipping_address.
zipcode
string Postal code.
billing_address
object Complete billing address information.
city
string City name.
contact
string Contact number for billing.
country
string Country code. For example, in.
id
string Address identifier (optional).
line1
string Address line 1.
line2
string Address line 2.
name
string Account holder name.
state
string State name.
tag
string Address tag. For example, Home.
type
string Address type. Value is billing_address.
zipcode
string Postal code.
line_items_total
integer Total value of line items in paise before adding shipping fees and COD fees, after applying promotions. For example, 60000 for ₹600.
tax_details
object Tax information.
total_tax
integer Total tax amount in paise. For example, 4128.
taxes_included
boolean Indicates whether taxes are included in the item prices. Possible values:
true: Taxes are included in item prices.false: Taxes are separate from item prices.
Use the Fetch Payments API to retrieve comprehensive payment details, including transaction status, payment method, customer information, settlement details, and the associated order information for a specific payment:
curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET]-X GET https://api.razorpay.com/v1/payments/pay_R1yFlWQar3XXXX
{"id": "pay_R1yFlWQar3XXXX","entity": "payment","amount": 55700,"currency": "INR","status": "pending","order_id": "order_R1yDkxyIuKXXXX","invoice_id": null,"international": false,"method": "cod","amount_refunded": 0,"refund_status": null,"captured": false,"description": null,"card_id": null,"bank": null,"wallet": null,"vpa": null,"email": "gaurav.kumar@example.com","contact": "+919100000000","notes": {"cart_id": "hWN2QaXc?key=2b3cad31","storefront_id": "gid://shopify/Cart/h?key=14bbf59ce35b8"},"fee": null,"tax": null,"error_code": null,"error_description": null,"error_source": null,"error_step": null,"error_reason": null,"acquirer_data": {},"created_at": 1756046099,"receiver_type": null}
Know more about the
.id
string Unique identifier of the payment. For example, pay_R1yFlWQar3XXXX.
entity
string Type of entity. Value is payment.
amount
integer Payment amount in the smallest currency unit (paise). For COD payments, this includes the COD fee (for example, 55700 for ₹557). For prepaid payments, this equals the captured amount (for example, 90630 for ₹906.30).
currency
string The 3-letter ISO currency code. For example, INR.
status
string Current status of the payment. Possible values:
pending: Payment pending collection (COD orders).captured: Payment successfully captured (prepaid orders).authorized: Payment authorized but not captured.failed: Payment attempt failed.
order_id
string Unique identifier of the associated order. For example, order_R1yDkxyIuKXXXX.
invoice_id
string|null Unique identifier of the associated invoice. Returns null if no invoice is linked.
international
boolean Indicates whether this is an international payment. Possible values:
true: International payment.false: Domestic payment.
method
string Payment method used. Possible values include:
codupicardnetbankingwallet
amount_refunded
integer Amount refunded in paise. For example, 0 indicates no refund has been processed.
refund_status
string|null Current refund status. Returns null if no refund is applicable. Possible values:
partial: Partial refund processed.full: Full refund processed.
captured
boolean Indicates whether the payment has been captured. Possible values:
true: Payment has been captured.false: Payment has not been captured.
description
string|null Payment description. Returns null if no description is provided.
card_id
string|null Unique identifier of the card used for payment. Returns null for non-card payments.
bank
string|null Bank identifier for netbanking payments. Returns null for other payment methods.
wallet
string|null Wallet provider identifier. Returns null for non-wallet payments.
vpa
string|null Virtual Payment Address for UPI payments. For example, gaurav.kumar@exampleupi. Returns null for non-UPI payments.
string Customer's email address.
contact
string Customer's phone number.
notes
object Custom notes added to the payment containing integration-specific data.
cart_id
string Shopping cart identifier.
storefront_id
string Storefront system identifier.
flits_cart_token
string Flits integration token (optional).
optimizer_provider_name
string Payment optimizer provider name (optional).
fee
integer|null Processing fee charged in paise. For example, 0 indicates no fee. Returns null for COD payments.
tax
integer|null Tax amount on processing fee in paise. For example, 0 indicates no tax. Returns null for COD payments.
error_code
string|null Error code if payment failed. Returns null for successful payments.
error_description
string|null Human-readable error description. Returns null for successful payments.
error_source
string|null Source of the error. Returns null for successful payments.
error_step
string|null Step at which error occurred. Returns null for successful payments.
error_reason
string|null Reason for the error. Returns null for successful payments.
acquirer_data
object Data from the payment acquirer.
rrn
string Retrieval Reference Number from the acquirer (optional).
upi_transaction_id
string UPI transaction identifier from the acquirer (optional).
created_at
integer Unix timestamp indicating when the payment was created. For example, 1756046099.
receiver_type
string|null Type of receiver for the payment. Returns null if not applicable.
upi
object UPI-specific payment details (only present for UPI payments).
vpa
string Virtual Payment Address used for the UPI payment.
After the integration is complete, a Pay button appears on your webpage/app.
Click the button and make a test transaction to ensure the integration is working as expected. You can start accepting actual payments from your customers once the test transaction is successful.
You can make test payments using one of the payment methods configured at the Checkout.
Watch Out!
This is a mock payment page that uses your test API keys, test card and payment details.
- Ensure you have entered only your in the Checkout code.
- No real money is deducted due to the usage of test API keys. This is a simulated transaction.
Following are all the payment modes that the customer can use to complete the payment on the Checkout. Some of them are available by default, while others may require approval from us. Raise a request from the Dashboard to enable such payment methods.
You can select any of the listed banks. After choosing a bank, Razorpay will redirect to a mock page where you can make the payment success or a failure. Since this is Test Mode, we will not redirect you to the bank login portals.
Check the list of
.You can enter one of the following UPI IDs:
success@razorpay: To make the payment successful.failure@razorpay: To fail the payment.
Check the list of
.Handy Tips
You can use Test Mode to test UPI payments, and Live Mode for UPI Intent and QR payments.
You can use one of the following test cards to test transactions for your integration in Test Mode.
- Use any valid expiration date in the future in the MM/YY format.
- Use any random CVV to create a successful payment.
Check the list of
.You can select any of the listed wallets. After choosing a wallet, Razorpay will redirect to a mock page where you can make the payment success or a failure. Since this is Test Mode, we will not redirect you to the wallet login portals.
Check the list of
.Check the go-live checklist for Razorpay Magic Checkout integration. Consider these steps before taking the integration live.
You can perform an end-to-end simulation of funds flow in the Test Mode. Once confident that the integration is working as expected, switch to the Live Mode and start accepting payments from customers.
Watch Out!
Ensure you are switching your test API keys with API keys generated in Live Mode.
To generate API Keys in Live Mode on your Razorpay Dashboard:
- Log in to the Razorpay Dashboard and switch to Live Mode on the menu.
- Navigate to Account & Settings → API Keys → Generate Key to generate the API Key for Live Mode.
- Download the keys and save them securely.
- Replace the Test API Key with the Live Key in the Checkout code and start accepting actual payments.
After payment is authorized, you need to capture it to settle the amount to your bank account as per the settlement schedule. Payments that are not captured are auto-refunded after a fixed time.
Watch Out
- You should deliver the products or services to your customers only after the payment is captured. Razorpay automatically refunds all the uncaptured payments.
- You can track the payment status using our or webhooks.
Authorized payments can be automatically captured. You can auto-capture all payments
on the Razorpay Dashboard. Know more about .Watch Out!
Payment capture settings work only if you have integrated with Orders API on your server side. Know more about the
.Ensure you have
in the live mode and configured the events for which you want to receive notifications.Is this integration guide useful?