Skip to content
Sign in
Menu

Understand payment receipts

Read the PAYMENT-RESPONSE header and confirm a payment on-chain.

  • Tutorial
On this page

What you'll achieve

You can tell whether a call's payment settled and find its transaction on Solana.

Prerequisites

  • A paid call's response headers.

1. Decode the receipt

TypeScript
const header = response.headers.get("PAYMENT-RESPONSE")
const receipt = header ? JSON.parse(Buffer.from(header, "base64").toString("utf8")) : undefined
JSONIllustrative values
{
  "success": true,
  "transaction": "<Solana transaction signature>",
  "network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
  "payer": "<the paying wallet>"
}

2. Interpret it

ReceiptMeaning
success: trueSettled: confirmed on Solana. You paid.
success: false, errorReason: "settlement_pending"You got the answer; confirmation is still in progress. It usually settles shortly.
success: false, errorReason: "settlement_failed"Settlement failed; the answer was withheld and you weren't charged.
No receiptUsually no payment was taken (an error before settlement). After settlement_unavailable, payment_core_unavailable or a dropped connection, the payment may still settle: check your wallet before paying again.

3. Check on-chain

Look up transaction in a Solana explorer for the receipt's network. The transfer goes from your USDC account to the API's vault, with the quote id as its memo.

Expected result

A record of each call's transaction, which you can match against your wallet's history.

Common mistakes

MistakeFix
Treating success: false as a failed callCheck errorReason: settlement_pending came with a real answer.
Looking for the payment in the provider's walletPayments land in the API's vault and are paid out to providers later.