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
const header = response.headers.get("PAYMENT-RESPONSE")
const receipt = header ? JSON.parse(Buffer.from(header, "base64").toString("utf8")) : undefined{
"success": true,
"transaction": "<Solana transaction signature>",
"network": "solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1",
"payer": "<the paying wallet>"
}2. Interpret it
| Receipt | Meaning |
|---|---|
success: true | Settled: 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 receipt | Usually 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
| Mistake | Fix |
|---|---|
Treating success: false as a failed call | Check errorReason: settlement_pending came with a real answer. |
| Looking for the payment in the provider's wallet | Payments land in the API's vault and are paid out to providers later. |