Single Integration API

1.1 Handle Payment Success and Error Events

Once a customer completes the payment, a POST request is made to the callback_url provided in the payment request. The data contained in this request will depend on whether the payment was a success or a failure.

Success Callback

If the payment made by the customer is successful, the following fields are sent:

razorpay_payment_id
razorpay_order_id
razorpay_signature

{
  "razorpay_payment_id": "pay_29QQoUBi66xm2f",
  "razorpay_order_id": "order_9A33XWu170gUtm",
  "razorpay_signature": "9ef4dffbfd84f1318f6739a3ce19f9d85851857ae648f114332d8401e0949a3d"
}

Failure Callback

If the payment has failed, the callback will contain details of the error. Refer to

Errors

for details.

Given below is a sample error code you will receive when the order fails.

{
   "error": {
   "code": "BAD_REQUEST_ERROR",
   "description": "The amount must be atleast INR 1.00",
   "source": "business",
   "step": "order_create",
   "reason": "input_validation_failed",
   "metadata": {},
   "field": "amount"
    }
}

Given below is a sample error code you will receive when the payment fails.

Watch Out!

You can use the order id present in the metadata for additional payment attempts on the order without creating a new one.

{
   "error": {
   "code": "BAD_REQUEST_ERROR",
   "description": "Authentication failed due to incorrect OTP",
   "field": null,
   "source": "customer",
   "step": "payment_authentication",
   "reason": "invalid_otp",
   "metadata": {
       "order_id": "order_EKwxwAgItmmXdp"
    }
  }
}

The following error occurs when the order was processed, payment was created in Razorpay but failed at gateway level.

{
   "error": {
   "code": "GATEWAY_ERROR",
   "description": "Authentication failed due to incorrect OTP",
   "field": null,
   "source": "customer",
   "step": "payment_authentication",
   "reason": "gateway failure",
   "metadata": {
   "order_id": "order_EKwxwAgItmmXdp",
   "payment_id": "pay_TKwxwAgItmmXdp"
    }
  }
}

1.2 Retry/Re-Attempt Request

Use the following sample code example to make a retry request using Order id and Receipt in the request.

curl -u [YOUR_KEY_ID]:[YOUR_KEY_SECRET] \
-X POST https://api.razorpay.com/v1/orders \
-H "Content-Type: application/json" \
-d{
 "id": "order_EKwxwAgItmmXdp",
 "payment": {
   "amount": 100,
   "currency": "",
   "method": "card",
   "card": {
     "number": "4842 7930 0208 6571",
     "name": " Nur Aisyah",
     "expiry_month": "11",
     "expiry_year": "30",
     "cvv": "100"
   },
   "notes": {
     "key1": "value3",
     "key2": "value2"
   }
 }
}

{
  "id": "order_EKwxwAgItmmXdp",
  "status": "attempted",
  "receipt": "receipt#1",
  "notes": {
    "key1": "value3",
    "key2": "value2"
  },
  "created_at": 1582628071,
  "amount": 50000,
  "amount_paid": 0,
  "amount_due": 50000,
  "currency": "",
  "offer_id": null,
  "attempts": 1,
  "transfers": [],
  "payment_workflow": {
    "id": "pay_FVmAstJWfsD3SO",
    "next": [
      {
        "action": "redirect",
        "url": "https://api.razorpay.com/v1/payments/pay_FVmAstJWfsD3SO/authorize"
      },
      {
        "action": "otp_generate",
        "url": "https://api.razorpay.com/v1/payments/pay_FVmAstJWfsD3SO/otp_generate?track_id=FVmAtLUe9XZSGM&key_id=<YOUR_KEY_ID>"
      }
    ]
  }
 }

1.3 Verify Payment Signature

Signature verification is a mandatory step to ensure that the callback is sent by Razorpay. The razorpay_signature contained in the callback can be regenerated by your system and verified as follows.

Create a string to be hashed using the razorpay_payment_id contained in the callback and the Order ID generated in the first step, separated by a |. Hash this string using SHA256 and your API Secret.

generated_signature = hmac_sha256(order_id + "|" + razorpay_payment_id, secret);

if (generated_signature == razorpay_signature) {
    payment is successful
}

Generate Signature on your Server

/**
* 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;
    }
}

1.4 Integrate Payments Rainy Day Kit

Use Payments Rainy Day kit to overcome payments exceptions such as:

1.5 Verify Payment Status

Handy Tips

On the Razorpay Curlec Dashboard, ensure that the payment status is captured. Refer to the payment capture settings page to know how to

capture payments automatically

You can track the payment status in three ways:

To verify the payment status from the Razorpay Curlec Dashboard:

Log in to the Razorpay Curlec 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.

Next Steps

Step 2: Test Integration