Verify Razorpay Payment

POST

checkout

{id}

razorpay

verify

Verify a Razorpay checkout payment and settle the invoice

curl --request POST \
  --url https://billing.example.com/checkout/{id}/razorpay/verify \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "razorpay_order_id": "<string>",
  "razorpay_payment_id": "<string>",
  "razorpay_signature": "<string>"
}
'

import requests

url = "https://billing.example.com/checkout/{id}/razorpay/verify"

payload = {
    "razorpay_order_id": "<string>",
    "razorpay_payment_id": "<string>",
    "razorpay_signature": "<string>"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    razorpay_order_id: '<string>',
    razorpay_payment_id: '<string>',
    razorpay_signature: '<string>'
  })
};

fetch('https://billing.example.com/checkout/{id}/razorpay/verify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/checkout/{id}/razorpay/verify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'razorpay_order_id' => '<string>',
    'razorpay_payment_id' => '<string>',
    'razorpay_signature' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/checkout/{id}/razorpay/verify"

	payload := strings.NewReader("{\n  \"razorpay_order_id\": \"<string>\",\n  \"razorpay_payment_id\": \"<string>\",\n  \"razorpay_signature\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billing.example.com/checkout/{id}/razorpay/verify")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"razorpay_order_id\": \"<string>\",\n  \"razorpay_payment_id\": \"<string>\",\n  \"razorpay_signature\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/checkout/{id}/razorpay/verify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"razorpay_order_id\": \"<string>\",\n  \"razorpay_payment_id\": \"<string>\",\n  \"razorpay_signature\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "status": "paid",
    "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoice_number": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

Public endpoint called by the hosted checkout’s Razorpay success handler with the fields Checkout.js returns.

Verification is two-step and never client-trusted:

Signature — the HMAC-SHA256 of order_id|payment_id is checked against the key secret, proving a genuine Razorpay payment.
Binding — the order is fetched from Razorpay and its notes.invoice_id must match this invoice, so a genuine payment for a different invoice can’t be replayed here.

Settlement then goes through the same idempotent ledger path as the payment.captured webhook (the authoritative backstop) — replays report paid without double-posting.

Request Body

Parameter	Type	Required
`razorpay_order_id`	string	Yes
`razorpay_payment_id`	string	Yes
`razorpay_signature`	string	Yes

Example

curl -X POST https://api.recurso.dev/checkout/8b7a9358-.../razorpay/verify \
  -H "Content-Type: application/json" \
  -d '{
    "razorpay_order_id": "order_TBf3HG...",
    "razorpay_payment_id": "pay_TBf4Jk...",
    "razorpay_signature": "9c1f..."
  }'

{
  "data": {
    "status": "paid",
    "invoice_id": "8b7a9358-...",
    "invoice_number": "INV-..."
  }
}

Errors

Status	Code	When	Fix
400	`validation_failed`	`id` is not a valid invoice UUID, or `razorpay_order_id`/`razorpay_payment_id`/`razorpay_signature` are missing.	Send all three fields from the Razorpay checkout callback.
400	`validation_failed`	Signature verification failed (`payment verification failed`).	Pass the untouched values from Razorpay’s handler callback — any mutation invalidates the signature.
400	`validation_failed`	The payment’s order does not belong to this invoice (`payment does not belong to this invoice`).	Verify against the same invoice that created the Razorpay order.
404	`not_found`	No invoice with that ID exists.	Verify the checkout URL.
502	`internal_error`	Razorpay could not confirm the payment when queried (`could not confirm the payment`).	Retry; webhooks will also reconcile the payment once Razorpay settles it.
503	`internal_error`	Razorpay checkout is not configured on this deployment.	The merchant must connect Razorpay credentials first.

See Errors for the error envelope and the full code taxonomy.

Authorizations

Authorization

string

header

required

Path Parameters

string<uuid>

required

Body

application/json

razorpay_order_id

string

required

razorpay_payment_id

string

required

razorpay_signature

string

required

Response

Invoice settled (idempotent — already-paid invoices report paid).

data

object

Show child attributes

Verify a Razorpay checkout payment and settle the invoice

curl --request POST \
  --url https://billing.example.com/checkout/{id}/razorpay/verify \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "razorpay_order_id": "<string>",
  "razorpay_payment_id": "<string>",
  "razorpay_signature": "<string>"
}
'

import requests

url = "https://billing.example.com/checkout/{id}/razorpay/verify"

payload = {
    "razorpay_order_id": "<string>",
    "razorpay_payment_id": "<string>",
    "razorpay_signature": "<string>"
}
headers = {
    "Authorization": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    razorpay_order_id: '<string>',
    razorpay_payment_id: '<string>',
    razorpay_signature: '<string>'
  })
};

fetch('https://billing.example.com/checkout/{id}/razorpay/verify', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://billing.example.com/checkout/{id}/razorpay/verify",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'razorpay_order_id' => '<string>',
    'razorpay_payment_id' => '<string>',
    'razorpay_signature' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://billing.example.com/checkout/{id}/razorpay/verify"

	payload := strings.NewReader("{\n  \"razorpay_order_id\": \"<string>\",\n  \"razorpay_payment_id\": \"<string>\",\n  \"razorpay_signature\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://billing.example.com/checkout/{id}/razorpay/verify")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"razorpay_order_id\": \"<string>\",\n  \"razorpay_payment_id\": \"<string>\",\n  \"razorpay_signature\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://billing.example.com/checkout/{id}/razorpay/verify")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"razorpay_order_id\": \"<string>\",\n  \"razorpay_payment_id\": \"<string>\",\n  \"razorpay_signature\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "status": "paid",
    "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoice_number": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "<string>"
  }
}

Getting Started

Core

Billing & Invoicing

Revenue & Finance

Growth & Recovery

Compliance (India)

Platform

Customer Portal API

Verify Razorpay Payment

Request Body

Example

Errors

Authorizations

Path Parameters

Body

Response

​Request Body

​Example

​Errors

Authorizations

Path Parameters

Body

Response

Request Body

Example

Errors