Verify Checkout Payment

GET

checkout

{id}

success

Verify a checkout payment and report settlement status

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

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

fetch('https://billing.example.com/checkout/{id}/success', 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}/success",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  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}/success"

	req, _ := http.NewRequest("GET", 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}/success")

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

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

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

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

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

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

Public endpoint called by the hosted checkout after stripe.confirmPayment — and hit automatically on redirect-method returns, since Stripe appends ?payment_intent= to the return URL.

This endpoint never settles on trust. With payment_intent present it verifies, directly with Stripe, that the intent succeeded and that its metadata invoice_id matches this invoice — so a succeeded intent for one invoice can never be replayed to pay another. Only then is the invoice marked paid through the ledger path (idempotent with the payment webhook).

Query Parameters

Parameter	Type	Description
`payment_intent`	string	Stripe PaymentIntent id (`pi_*`) to verify. Omit to just read the invoice’s current status.

Response statuses

`status`	Meaning
`paid`	Verified and settled (or already settled by the webhook).
`processing`	Genuinely in flight — e.g. ACH/SEPA settling over days, or a pending `requires_action`. The webhook settles it later.
`failed`	The attempt was declined or abandoned (`requires_payment_method` / `canceled`). The customer should retry.
`open` / `past_due`	No verifiable payment supplied; current invoice status reported unchanged.

Example

curl "https://api.recurso.dev/checkout/9b2f6c1e-.../success?payment_intent=pi_3TrZw5..."

{
  "data": {
    "status": "paid",
    "invoice_id": "9b2f6c1e-...",
    "invoice_number": "INV-..."
  }
}

Errors

Status	Code	When	Fix
400	`validation_failed`	`id` is not a valid invoice UUID.	Use the invoice UUID from the checkout link.
400	`validation_failed`	The `payment_intent`/payment reference in the query does not belong to this invoice.	Pass the payment reference returned by this invoice’s pay step.
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 could not be loaded, or settling the invoice after a confirmed payment failed.	Retry — settlement is safe to re-request; webhooks will also reconcile the payment.

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

Authorizations

Authorization

string

header

required

Path Parameters

string<uuid>

required

Query Parameters

payment_intent

string

Stripe PaymentIntent id (pi_*) to verify — also appended automatically by Stripe on redirect-method returns.

Response

Settlement status for this invoice.

data

object

Show child attributes

Verify a checkout payment and report settlement status

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

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

fetch('https://billing.example.com/checkout/{id}/success', 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}/success",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  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}/success"

	req, _ := http.NewRequest("GET", 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}/success")

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

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

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

{
  "data": {
    "status": "paid",
    "payment_status": "<string>",
    "invoice_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "invoice_number": "<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 Checkout Payment

Query Parameters

Response statuses

Example

Errors

Authorizations

Path Parameters

Query Parameters

Response

​Query Parameters

​Response statuses

​Example

​Errors

Authorizations

Path Parameters

Query Parameters

Response

Query Parameters

Response statuses

Example

Errors