API ReferenceIntegrationsKnowledge Base

Checkout and API Integration

You can accept payments from customers on behalf of your sub-merchants by integrating with the Razorpay Payment Gateway.

Follow these steps to complete the integration:

  1. Create an order
  2. Integrate with Razorpay Checkout
  3. Verify payment signature

API Authentication🔗

We use Basic Auth for authorizing Partner requests. Use the Partner credentials as described in the Dashboard Guide. Watch this video to see how to access your Partner credentials.

partner credentials

Handy Tips:
These credentials are mode-specific. In addition to the API Key ID and Secret, provide the sub-merchant identification in the API requests.

Step 1 - Create an Order🔗

Orders help in binding multiple payment attempts to a single order_id. You can integrate the Orders API in your server-side to create orders. Use the endpoint given below to create an order: /orders

Request Parameters🔗

In the POST requests, provide the sub-merchant identification as a request parameter. Following is the list of request parameters to be used with the Create Order API to create an Order.

account_id mandatory
string Unique identifier of the sub-merchant account. For example, acc_Ef7ArAsdU5t0XL.

Here is a sample request and response using a few of these parameters.

Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \ -X POST https://api.razorpay.com/v1/orders \ -H "Content-Type: application/json" \ -d '{ "amount": 10000, "currency": "INR", "receipt": "1", "account_id": "acc_Ef7ArAsdU5t0XL" }'
Copy{ "id": "order_Ef80WJDPBmAeNt", "entity": "order", "amount": 10000, "amount_paid": 0, "amount_due": 10000, "currency": "INR", "receipt": "1", "offer_id": null, "status": "created", "attempts": 0, "notes": [], "created_at": 1587033758 }

Step 2 - Integrate with Razorpay Checkout🔗

You can create a payment by integrating with Razorpay Checkout. Ensure that the order_id generated in the previous step is passed as part of the Checkout code.

Copy-paste the form parameters as data attributes in your HTML code:

Copy <button id="rzp-button1">Pay</button> <script src="https://checkout.razorpay.com/v1/checkout.js"></script> <script> var options = { "key": "YOUR_KEY_ID", // Enter the Key ID generated from the Dashboard "amount": "50000", // Amount is in currency subunits. Default currency is INR. Hence, 50000 refers to 50000 paise "currency": "INR", "name": "Acme Corp", "description": "Test Transaction", "image": "https://example.com/your_logo", "order_id": "order_Ef80WJDPBmAeNt", //Pass the `id` obtained in the previous step "account_id": "acc_Ef7ArAsdU5t0XL", "handler": function (response){ alert(response.razorpay_payment_id); alert(response.razorpay_order_id); alert(response.razorpay_signature) } }; var rzp1 = new Razorpay(options); document.getElementById('rzp-button1').onclick = function(e){ rzp1.open(); e.preventDefault(); } </script>

This creates a Pay button on the website, which the customer can use to invoke Checkout and complete the payment.

Step 3 - Verify Payment Signature🔗

This is a mandatory step that allows you to confirm the authenticity of the details returned to the Checkout form for successful payments.

To verify the razorpay_signature returned to you by the Checkout form:

  1. Create a signature in your server using the following attributes:

    • order_id - Retrieve the order_id from your server. Do not use the razorpay_order_id returned by Checkout.
    • razorpay_payment_id - Returned by Checkout.
    • key_secret - Available in your server.
      The key_secret that was generated from the Razorpay Dashboard.
  2. Use the SHA256 algorithm, the razorpay_payment_id and the order_id to construct a HMAC hex digest as shown below:

    Copygenerated_signature = hmac_sha256(order_id + "|" + razorpay_payment_id, secret); if (generated_signature == razorpay_signature) { payment is successful }
  3. If the signature you generate on your server matches the razorpay_signature returned to you by the Checkout form, the payment received is from an authentic source.

Generate Signature on Your Server🔗

The links to the Razorpay SDKs for the supported platforms are given below:

Platform

Link

Java

https://github.com/razorpay/razorpay-java

PHP

https://github.com/razorpay/razorpay-php

Ruby

https://github.com/razorpay/razorpay-ruby

Python

https://github.com/razorpay/razorpay-python

.Net

https://github.com/razorpay/razorpay-dot-net

Copy/** * This class defines common routines for generating * authentication signatures for Razorpay Webhook requests. */ public class Signature { private static final String HMAC_SHA256_ALGORITHM = "HmacSHA256"; /** * Computes RFC 2104-compliant HMAC signature. * * @param data * The data to be signed. * @param key * The signing key. * @return * The Base64-encoded RFC 2104-compliant HMAC signature. * @throws * java.security.SignatureException when signature generation fails */ public static String calculateRFC2104HMAC(String data, String secret) throws java.security.SignatureException { String result; try { // get an hmac_sha256 key from the raw secret bytes SecretKeySpec signingKey = new SecretKeySpec(secret.getBytes(), HMAC_SHA256_ALGORITHM); // get an hmac_sha256 Mac instance and initialize with the signing key Mac mac = Mac.getInstance(HMAC_SHA256_ALGORITHM); mac.init(signingKey); // compute the hmac on input data bytes byte[] rawHmac = mac.doFinal(data.getBytes()); // base64-encode the hmac result = DatatypeConverter.printHexBinary(rawHmac).toLowerCase(); } catch (Exception e) { throw new SignatureException("Failed to generate HMAC : " + e.getMessage()); } return result; } }
Copyuse Razorpay\Api\Api; $api = new Api($key_id, $key_secret); $attributes = array('razorpay_signature' => '23233', 'razorpay_payment_id' => '332' , 'razorpay_order_id' => '12122'); $order = $api->utility->verifyPaymentSignature($attributes)
Copyrequire 'razorpay' Razorpay.setup('key_id', 'key_secret') payment_response = { 'razorpay_order_id': '12122', 'razorpay_payment_id': '332', 'razorpay_signature': '23233' } Razorpay::Utility.verify_payment_signature(payment_response)
Copyimport razorpay client = razorpay.Client(auth = ('[key_id]', '[key_secret]')) params_dict = { 'razorpay_order_id': '12122', 'razorpay_payment_id': '332', 'razorpay_signature': '23233' } client.utility.verify_payment_signature(params_dict)
Copy Dictionary<string, string> attributes = new Dictionary<string, string>(); attributes.Add("razorpay_payment_id", paymentId); attributes.Add("razorpay_order_id", Request.Form["razorpay_order_id"]); attributes.Add("razorpay_signature", Request.Form["razorpay_signature"]); Utils.verifyPaymentSignature(attributes);

Post Signature Verification🔗

After verifying the signature, fetch the order in your system that corresponds to the razorpay_order_id in your database. Mark it as successful and process the order.

Next Steps🔗

You can view customers' payments on the sub-merchant's Razorpay Dashboard. You can also retrieve the status of the payments by polling our APIs.

Following APIs are used to fetch payments. Pass the sub-merchant account identifier as a header while retrieving details using GET requests.

Fetch Payments of Sub-Merchants🔗

You can fetch the details of the sub-merchant payments using the endpoint given below. Ensure that you pass the sub-merchant account identifier as a header.

/payments
Copycurl -X GET 'https://api.razorpay.com/v1/payments \ -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] //partner credentials -h 'x-razorpay-account: acc_AQGtV93g7sDCwB'
Copy{ "id": "pay_EfXir8l3TPO9zw", "entity": "payment", "amount": 10000, "currency": "INR", "status": "authorized", "order_id": "order_EfXfUWQzL1YyI4", "invoice_id": null, "international": false, "method": "wallet", "amount_refunded": 0, "refund_status": null, "captured": false, "description": "Test transaction", "card_id": null, "bank": null, "wallet": "freecharge", "vpa": null, "email": "gaurav.kumar@example.com", "contact": "+919988776644", "notes": [], "fee": null, "tax": null, "error_code": null, "error_description": null, "created_at": 1587124317 }

Fetch Payments Based on Orders🔗

The following endpoint retrieves payments corresponding to an Order:

/orders/:id/payments
Copycurl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] -X GET https://api.razorpay.com/v1/orders/order_Ef80WJDPBmAeNt/payments -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] //partner credentials -h 'x-razorpay-account: acc_AQGtV93g7sDCwB'
Copy{ "count": 1, "entity": "collection", "items": [ { "id": "pay_EfXir8l3TPO9zw", "entity": "payment", "amount": 10000, "currency": "INR", "status": "authorized", "order_id": "order_EfXfUWQzL1YyI4", "method": "wallet", "amount_refunded": 0, "refund_status": null, "captured": false, "description": "Test transaction", "card_id": null, "bank": null, "wallet": "freecharge", "vpa": null, "email": "gaurav.kumar@example.com", "contact": "+919988776644", "fee": null, "tax": null, "error_code": null, "error_description": null, "notes": [], "created_at": 1587124317 }, ] }

Path Parameter🔗

id mandatory
string Unique identifier of the order you want to fetch payment details for.
×