Initiate Checkout Payment

POST

checkout

{id}

pay

Initiate payment for an invoice

curl --request POST \
  --url https://billing.example.com/checkout/{id}/pay \
  --header 'Authorization: <api-key>'

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

fetch('https://billing.example.com/checkout/{id}/pay', 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}/pay",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

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

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'

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

{
  "data": {
    "order_id": "<string>",
    "amount": 123,
    "currency": "<string>",
    "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoice_number": "<string>",
    "gateway": "stripe",
    "client_secret": "<string>",
    "publishable_key": "<string>",
    "razorpay_key_id": "<string>"
  }
}

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

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

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

This is a public, rate-limited endpoint used by the hosted checkout page. No authentication is required.

Creates a payment order on the currency-routed gateway. The response tells the client which flow to drive:

gateway: "stripe" — mount the Stripe Payment Element with client_secret and publishable_key, confirm client-side, then verify via GET /checkout/{id}/success.
gateway: "razorpay" — open the Razorpay Checkout.js modal with order_id and razorpay_key_id, then verify via POST /checkout/{id}/razorpay/verify.

Settlement is never client-trusted: both verify endpoints confirm the payment with the gateway and bind it to this invoice before marking anything paid, and the gateway webhooks remain the authoritative backstop.

Path Parameters

Parameter	Type	Description
`id`	string (UUID)	The invoice ID

Example Request

curl -X POST https://api.recurso.dev/checkout/9b2f6c1e-.../pay

Response (Stripe-routed currency)

{
  "data": {
    "order_id": "pi_3TrZw5...",
    "amount": 2900,
    "currency": "USD",
    "invoice_id": "9b2f6c1e-...",
    "invoice_number": "INV-...",
    "gateway": "stripe",
    "client_secret": "pi_3TrZw5..._secret_...",
    "publishable_key": "pk_test_...",
    "razorpay_key_id": ""
  }
}

Response (INR / Razorpay-routed)

{
  "data": {
    "order_id": "order_TBf3HG...",
    "amount": 58882,
    "currency": "INR",
    "invoice_id": "8b7a9358-...",
    "invoice_number": "INV-...",
    "gateway": "razorpay",
    "client_secret": "",
    "publishable_key": "",
    "razorpay_key_id": "rzp_test_..."
  }
}

Already-paid invoices return 400. A 503 means the deployment is missing the gateway’s browser-side key (STRIPE_PUBLISHABLE_KEY or RAZORPAY_KEY_ID) — fix the configuration rather than retrying.

Errors

Status	Code	When	Fix
400	`validation_failed`	`id` is not a valid invoice UUID.	Use the invoice UUID from the checkout link.
400	`invoice_already_paid`	The invoice is already paid.	Nothing to collect — show the success state instead.
404	`not_found`	No invoice with that ID exists.	Verify the checkout URL.
429	`rate_limited`	This public endpoint has its own rate limit.	Back off and retry after the limit window.
500	`internal_error`	The invoice lookup failed, or the gateway rejected payment-order creation.	Retry; the merchant should check their gateway connection if it persists.
503	`internal_error`	Checkout is not fully configured for the invoice currency (missing Stripe publishable key or Razorpay key ID).	The merchant must finish their gateway configuration (dashboard → Gateway Connections).

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

Authorizations

Authorization

string

header

required

Path Parameters

string<uuid>

required

Response

Gateway order created.

data

object

Show child attributes

Initiate payment for an invoice

curl --request POST \
  --url https://billing.example.com/checkout/{id}/pay \
  --header 'Authorization: <api-key>'

const options = {method: 'POST', headers: {Authorization: '<api-key>'}};

fetch('https://billing.example.com/checkout/{id}/pay', 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}/pay",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "Authorization: <api-key>"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

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

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

	req.Header.Add("Authorization", "<api-key>")

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

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

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

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

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'

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

{
  "data": {
    "order_id": "<string>",
    "amount": 123,
    "currency": "<string>",
    "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoice_number": "<string>",
    "gateway": "stripe",
    "client_secret": "<string>",
    "publishable_key": "<string>",
    "razorpay_key_id": "<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

Initiate Checkout Payment

Path Parameters

Example Request

Response (Stripe-routed currency)

Response (INR / Razorpay-routed)

Errors

Authorizations

Path Parameters

Response

​Path Parameters

​Example Request

​Response (Stripe-routed currency)

​Response (INR / Razorpay-routed)

​Errors

Authorizations

Path Parameters

Response

Path Parameters

Example Request

Response (Stripe-routed currency)

Response (INR / Razorpay-routed)

Errors