> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/payments/payment-statuses.md).

# Payment Statuses

Integrators can retrieve the current status of a payment at any time using the `paymentId` returned when the payment is created. Use this endpoint to verify completion, support customer issues, and keep internal records accurate.

Payment status checks complement webhooks, Reporting, and Settlement. Webhooks notify you when something changes, this endpoint lets you query on demand, and Reporting and Settlement provide historical and settlement views across many payments.

{% hint style="warning" %}
**`overpaid` and `underpaid` are final statuses.** An `overpaid` payment is a paid payment: fulfill the order. The requested amount settles to the merchant and only the excess is returned to the payer. An `underpaid` payment is not paid: do not fulfill, and offer the customer a new payment. Reclaim progress is reported in `refundLifecycleStatus` and does not change `statusCode`. See "Final statuses" below.
{% endhint %}

{% hint style="info" %}
**Note for testing:** After a reclaim completes, some paths can still return `partiallyRefunded` or `fullyRefunded` in `statusCode`. This is being removed in an upcoming update. Do not build logic around these values. Treat the payment as final, and keep your fulfillment decision from the first outcome. `statusCode` will stay `overpaid` or `underpaid`, and reclaim progress is reported in `refundLifecycleStatus`.
{% endhint %}

**Overview**

Use the payment status endpoint when you want to:

* retrieve near real time payment status with a simple GET request
* confirm the outcome of a payment, such as `completed`, `overpaid`, `underpaid`, `expired`, `abandoned`, or `invalid`
* confirm that a reclaim return has completed, shown by `refundLifecycleStatus` set to `completed`
* identify the tender type actually used to pay, such as `bitcoin_Lightning`, `usdcSolana`, `paypal`, `venmo`, or `klarna`
* troubleshoot or support a single payment without pulling a full history

For ongoing monitoring and reconciliation, prefer webhooks plus Reporting and Settlement instead of frequent polling.

**Requesting payment status**

Payment status is retrieved by `paymentId`.

**Endpoint**

`GET /Payments/{paymentId}/tracking`

**Path parameters**

| Name        | Type   | Required | Description                                                |
| ----------- | ------ | -------- | ---------------------------------------------------------- |
| `paymentId` | string | Yes      | Payment identifier returned by the Create Payment response |

> `trackingId` is a legacy identifier that is deprecated but still supported for backwards compatibility. The legacy endpoint `GET /Payments/tracking/{trackingId}` continues to work, but its response does not include the reclaim fields (`refundLifecycleStatus`, `refundInitiatedAt`, `refundCompletedAt`, `refundFailureReason`). New integrations should use `paymentId` and `GET /Payments/{paymentId}/tracking`.

**Required headers**

Payments endpoints use header based authentication with a terminal API key.

| Header      | Value              |
| ----------- | ------------------ |
| `X-Api-Key` | `{apiKey}`         |
| `Accept`    | `application/json` |

Notes:

* the API key is the secret credential
* the masked API key is not usable
* send the full API key value in the `X-Api-Key` header on every Payments request

**Authentication methods for Payment Statuses**

**Using `X-Api-Key`**

Use `X-Api-Key` for new Payments integrations.

```http
GET /Payments/{paymentId}/tracking
X-Api-Key: {apiKey}
Accept: application/json
```

**Using OAuth for legacy Payments integrations**

If you are using an existing integration that authenticates Payments through OAuth password grant, send the access token as:

```http
GET /Payments/{paymentId}/tracking
Authorization: Bearer {access_token}
Accept: application/json
```

New integrations should use the `X-Api-Key` method.

**Example request**

```bash
curl "https://api.test.devs.beadpay.io/Payments/{paymentId}/tracking" \
  -H "X-Api-Key: {apiKey}" \
  -H "Accept: application/json"
```

**Example response**

The tracking endpoint returns the same payload shape as a payment webhook. It includes the reclaim fields (`refundLifecycleStatus`, `refundInitiatedAt`, `refundCompletedAt`, `refundFailureReason`). It does not include settlement or batch identity (`settlementId`, `batchId`, `batchPeriod`, `batchStatus`). See "Settlement and batch identity" below for where to get those.

The example below shows an `overpaid` payment whose payer has been emailed reclaim instructions for the excess. `tenderType` identifies the tender actually used to pay.

```json
{
  "paymentId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "trackingId": "c10b29e3c8104e0f8dc139c20d9eeb6c",
  "paymentCode": "PAY-9X7K2M",
  "statusCode": "overpaid",
  "tenderType": "usdcBase",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 100,
        "currency": { "id": 16, "code": "USDC_BASE", "name": "USDC Base", "symbol": "USDC" }
      },
      "inRequestedCurrency": {
        "amount": 100,
        "currency": { "id": 1, "code": "USD", "name": "USD", "symbol": "$" }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 105,
        "currency": { "id": 16, "code": "USDC_BASE", "name": "USDC Base", "symbol": "USDC" }
      }
    }
  },
  "reference": "ORDER123",
  "description": null,
  "receivedTime": "2026-10-06T13:55:02.114Z",
  "terminalId": "65f0b274f9a4c9a3f8d4b2a1",
  "merchantId": "664c5e3b0517b0a8a6321c9a",
  "errorMessage": null,
  "originalSenderAddress": "0x8f3c...a91d",
  "conversions": [],
  "refundLifecycleStatus": "emailSent",
  "refundInitiatedAt": "2026-10-06T13:57:20.207Z",
  "refundCompletedAt": null,
  "refundFailureReason": null
}
```

**Settlement and batch identity**

This endpoint is for payment status only. For settlement and batch identity on a payment, use the Reporting payment history endpoints instead:

| Endpoint                       | Settlement/batch fields returned                            |
| ------------------------------ | ----------------------------------------------------------- |
| `GET /Partners/{id}/payments`  | `settlementId`, `batchId`, `batchPeriod`, `batchStatus`     |
| `GET /Merchants/{id}/payments` | `settlementId`, `batchId`, `batchPeriod`, `batchStatus`     |
| `GET /Terminals/{id}/payments` | `batchId`, `settlementId`, `batchStatus` (no `batchPeriod`) |

These fields populate as the payment moves through batching and settlement, so expect them to be null until a payment has been batched (and, for `settlementId`, until the batch has rolled into a settlement). `completed` and `overpaid` payments are batched. See [Reporting](https://developers.bead.xyz/reporting.md) for these endpoints and [Settlement](https://developers.bead.xyz/settlement.md) for how settlement and batch records work.

**Using `tenderType`**

Use the returned `tenderType` to identify the tender actually used for the payment.

This is especially important when the payment flow presents multiple tender options. For example, an integrator may create one hosted payment session that allows several eligible tenders. When the customer completes the payment with Bitcoin Lightning, the status response returns:

```json
{
  "statusCode": "completed",
  "tenderType": "bitcoin_Lightning"
}
```

Recommended handling:

* store `tenderType` with your order, invoice, or payment record
* use `tenderType` for support, analytics, and tender-level reporting
* use the returned value as the actual tender paid, not only the tender options offered when the payment was created
* expect `tenderType` to be populated for paid payments
* for early or unresolved states, such as `created`, `tenderType` may not yet identify a completed tender

**BTC Classic and `tenderType`**

BTC Classic refers to Bitcoin on-chain payments. In API responses, use the returned `tenderType` value to identify the tender actually used for the payment.

For Bitcoin on-chain payments, the tender type is `bitcoin`. Do not treat `bitcoin_Lightning` as BTC Classic; Bitcoin Lightning is a separate, faster BTC payment rail.

If your payment flow allows multiple tenders, wait for the returned `tenderType` when available. If your integration already knows that the customer selected BTC Classic, you can use that local checkout context for customer messaging, but still use `statusCode` as the source of truth for fulfillment.

Recommended handling:

* use `tenderType: "bitcoin"` for BTC Classic / Bitcoin on-chain handling
* use `tenderType: "bitcoin_Lightning"` for Bitcoin Lightning handling
* do not assume all BTC payments have the same customer wait time
* use `completed` or `overpaid`, not `processing`, as the fulfillment trigger

**Status values**

Statuses are returned in the `statusCode` field and use the `PaymentStatus` enum.

`partiallyRefunded` and `fullyRefunded` are reserved values. Reclaim progress and completion are reported in `refundLifecycleStatus`, not in `statusCode`. See "Reclaim progress and completion" below.

**How crypto amount mismatch happens**

In most wallet based crypto payments, the customer scans the QR code to set the destination and then manually enters the amount to send in their wallet app. If the customer mistypes the amount, the payment can end as:

* `overpaid` when more than the requested amount is sent. The payment is paid. The requested amount settles to the merchant, and the excess is returned to the payer through Bead's reclaim process.
* `underpaid` when less than the requested amount is sent. The payment is not paid. Nothing settles to the merchant, and the full amount sent is returned to the payer through reclaim.

A very small overpayment, within a per tender tolerance set by Bead, is classified as `completed` instead of `overpaid`, and no reclaim is offered for the excess.

**Status codes**

| Status code         | Description                                                                                                                                                                                                                                                                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `created`           | Payment record created, waiting for customer funds. The actual paid tender may not yet be known.                                                                                                                                                                                                                                                                  |
| `processing`        | Funds detected and conversion or settlement processing is in progress. The payment is underway, but its outcome is not known yet. For most tenders, this state may be brief. For BTC Classic / Bitcoin on-chain payments, this state may last several minutes or longer while the Bitcoin network confirms the transaction. Do not fulfill based on `processing`. |
| `completed`         | Customer sent the requested amount. `tenderType` identifies the tender actually used. Crypto, if any, has been converted and credited. Paid: fulfill the order. Final status.                                                                                                                                                                                     |
| `overpaid`          | Customer sent more than requested. Paid: fulfill the order. The requested amount settles to the merchant. The excess is returned to the payer through reclaim. Final status.                                                                                                                                                                                      |
| `underpaid`         | Customer sent less than requested. Not paid: do not fulfill. Treat it like a declined payment and offer the customer a new payment. The amount sent is returned to the payer through reclaim. Final status.                                                                                                                                                       |
| `expired`           | A payment attempt was started, but no funds were received before the payment window expired. Any funds sent later remain unconverted and must be reclaimed. Final status.                                                                                                                                                                                         |
| `abandoned`         | The payment was created, but the customer never started a payment attempt, so no quote, deposit address, or checkout was ever issued. Bead closes these payments automatically 24 hours after the payment was created. Final status. See "Abandoned payments" below.                                                                                              |
| `invalid`           | Irregular event such as multiple transactions, unsupported asset, compliance block, or extreme market movement. Funds remain unconverted and must be reclaimed. Final status.                                                                                                                                                                                     |
| `cancelled`         | Customer or merchant cancelled the payment. Any funds remain unconverted and may be reclaimed. Final status.                                                                                                                                                                                                                                                      |
| `partiallyRefunded` | Reserved. Not returned.                                                                                                                                                                                                                                                                                                                                           |
| `fullyRefunded`     | Reserved. Not returned.                                                                                                                                                                                                                                                                                                                                           |

**Abandoned payments**

A payment is `abandoned` when it was created but the customer never began paying. For example, your system created a payment and the customer never opened the hosted payment page, or opened it and left without choosing a tender or starting a checkout. No funds were requested or expected, so there is nothing to reclaim.

How this differs from `expired`:

* `abandoned`: no payment attempt was recorded for the payment. Nothing was quoted or issued to the customer.
* `expired`: a payment attempt was started (for example a crypto quote, deposit address, or hosted checkout was issued) but was not completed before its window closed.

Because a payment may sit in `created` for up to 24 hours before Bead closes it, `created` is not a permanent state for payments that are never paid. Expect these payments to move to `abandoned` once 24 hours have passed since the payment was created.

**Automatic closures and webhooks**

> **Webhook behavior:** Bead closes unpaid payments automatically 24 hours after the payment was created, as `abandoned` or `expired`. Bead sends a payment webhook for each automatic closure, the same as for any other status change. Both statuses are also available from `GET /Payments/{paymentId}/tracking`. See [Payment Webhooks](https://developers.bead.xyz/payments/payment-webhooks.md).

**Reclaim progress and completion**

When a payment ends as `overpaid`, `underpaid`, `expired`, `invalid`, or `cancelled`, Bead returns crypto to the payer through the reclaim process. For `overpaid`, only the excess is returned. For the other statuses, the full amount received is returned. The progress of that return is on the payment record:

| Field                   | Meaning                                                                                                                                                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `refundLifecycleStatus` | One of `notStarted`, `emailSent`, `customerClaimed`, `processing`, `completed`, `failed`, `rejected`, `cancelled`. A value of `null` means the same as `notStarted`. `cancelled` means Bead closed the reclaim before the payer started a claim, and nothing is returned. |
| `refundInitiatedAt`     | The first time Bead emailed the payer reclaim instructions or the payer started a claim, whichever came first.                                                                                                                                                            |
| `refundCompletedAt`     | When Bead confirmed the return to the payer.                                                                                                                                                                                                                              |
| `refundFailureReason`   | Populated when a return attempt failed.                                                                                                                                                                                                                                   |

When the return completes, `refundLifecycleStatus` becomes `completed` and `refundCompletedAt` is set. `statusCode` does not change: an `overpaid` payment stays `overpaid`, and an `underpaid` payment stays `underpaid`.

These fields are returned by `GET /Payments/{paymentId}/tracking`, `GET /Payments/{paymentId}`, payment webhooks, and the merchant and partner payment history endpoints. They are always present on those responses and are `null` until a reclaim starts.

> **Webhook behavior:** Bead sends a payment webhook each time `refundLifecycleStatus` changes, including the change to `completed`. The `statusCode` in these webhooks is the payment's final status, unchanged. The webhook goes to the terminal webhook URL and to any `webhookUrls` set on the payment, using the same payload as other payment webhooks.

See [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md) for lifecycle values, webhook handling, and example responses.

**Final statuses**

`created` and `processing` are pending. Every other status is final: once a payment reaches it, `statusCode` does not change.

| Status       | Outcome  | Fulfillment    | Reclaim possible          |
| ------------ | -------- | -------------- | ------------------------- |
| `created`    | Pending  | Wait           | No                        |
| `processing` | Pending  | Wait           | No                        |
| `completed`  | Paid     | Fulfill        | No                        |
| `overpaid`   | Paid     | Fulfill        | Yes, the excess only      |
| `underpaid`  | Not paid | Do not fulfill | Yes, the full amount sent |
| `expired`    | Not paid | Do not fulfill | Yes, if funds arrived     |
| `invalid`    | Not paid | Do not fulfill | Yes, if funds arrived     |
| `cancelled`  | Not paid | Do not fulfill | Yes, if funds arrived     |
| `abandoned`  | Not paid | Do not fulfill | No                        |

Rules for your webhook consumer:

* Act on the first final status you receive for a `paymentId`. A payment never returns to `created` or `processing`.
* Expect later webhooks while a reclaim progresses. They carry the same final `statusCode` with an updated `refundLifecycleStatus`. Update your reclaim records, but do not reverse the fulfillment decision.
* A return may never happen. If the payer never claims, or the amount is below the minimum that can be returned, `refundLifecycleStatus` does not reach `completed`.

**Integrator handling guidance**

Use these rules when mapping payment statuses to your internal order or invoice state.

**`processing`**

Treat as payment detected, but not complete.

A `processing` status means Bead has detected funds and the payment is underway. It does not mean the payment is paid.

Do not fulfill the order, release goods, grant digital access, ship an item, or mark an invoice as paid based only on `processing`.

For most tender types, `processing` may be short enough that the customer can remain in the payment flow until the outcome is returned.

For BTC Classic / Bitcoin on-chain payments, `processing` can last several minutes or longer. In those flows, the recommended customer experience is to acknowledge that the payment has been detected, let the customer move on, and use webhooks or this endpoint to confirm the outcome.

Recommended BTC Classic handling:

* show the customer that the BTC payment has been detected
* explain that Bitcoin on-chain confirmation can take several minutes
* move the customer to an order, invoice, receipt, or status screen
* keep the internal order or invoice in a pending payment state
* use Payment Webhooks or this endpoint to detect the outcome
* fulfill only after the payment reaches `completed` or `overpaid`

Example customer message:

```
Your BTC payment has been detected and is now processing.

Bitcoin on-chain payments can take several minutes to confirm. You do not need to keep this page open. The merchant will confirm when the payment is complete.
```

**`completed`**

* Treat as a paid payment.
* Store the returned `tenderType` as the tender actually paid.
* Proceed with fulfillment after you have confirmed the outcome via webhooks or this endpoint.
* Use `paymentId`, `statusCode`, `tenderType`, `reference`, and `receivedTime` to support order lookup and customer support workflows.

**`overpaid`**

* Treat as a paid payment and fulfill the order.
* The requested amount settles to the merchant like a `completed` payment.
* The excess is returned to the payer through Bead's reclaim process. Bead emails the payer reclaim instructions when an email is on file.
* Do not ask the customer to pay again.
* Expect later webhooks as the return of the excess progresses, with `statusCode` still `overpaid` and `refundLifecycleStatus` updated. Keep the order fulfilled.

**`underpaid`**

* Treat as a declined payment. Nothing was processed for the order.
* Do not fulfill the order.
* Offer the customer a new payment, using your normal retry or tender selection flow. The original payment session cannot be topped up.
* The amount sent is returned to the payer through Bead's reclaim process.
* Expect later webhooks as the return progresses, with `statusCode` still `underpaid` and `refundLifecycleStatus` updated.

**`expired`, `abandoned`, `invalid`, `cancelled`**

* Treat as not paid.
* Do not fulfill the order.
* If funds were sent (not applicable to `abandoned`), they remain unconverted and are handled through reclaim.
* For `abandoned`, no funds were requested. If the customer still wants to pay, create a new payment.

For how these states behave in full flows, see the Payment Scenarios pages, which walk through overpaid, underpaid, and reclaim flows in more detail.

**Reclaiming crypto**

When a payment ends in one of the following states:

* `overpaid` (the excess only)
* `underpaid`
* `expired`
* `invalid`
* `cancelled`

crypto associated with that payment is returned to the payer through Bead's reclaim process.

**Email capture behavior**

Bead uses an email based reclaim flow to return crypto.

* if an email address is included in the original payment request, common in digital and `virtual` terminal flows, Bead will email instructions to the payer when reclaim is required
* if an email address is not included in the request, common in `physical` or terminal based flows, the hosted payment page will prompt the customer to enter an email address when one of these outcomes occurs, then Bead emails the reclaim instructions

Your integration does not need to implement the reclaim process directly, but you should:

* display clear messaging in your UI when these statuses occur
* add internal flags or notes so support and finance teams can recognize reclaim scenarios
* avoid automatically retrying or recreating payments without clear customer intention
* create a new payment session when the customer is ready to attempt payment again after a not paid outcome

**Error responses**

**Common error responses**

| Code  | Condition                                                                                                                                                                                |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401` | Missing or invalid API key. Confirm the `X-Api-Key` header is present and the key is valid for this environment.                                                                         |
| `403` | Authenticated, but not permitted to view this payment in the current context. Confirm you are using the correct API key for the terminal and merchant relationship tied to this payment. |
| `404` | No payment exists for this `paymentId`, or it is not visible in the current context.                                                                                                     |

Log the response body and headers for debugging, but avoid exposing raw error text directly to end users.

**Best practices**

Recommended patterns when using the payment status endpoint:

**Prefer webhooks for real time changes**

Configure Payment Webhooks so your system receives status updates automatically, including reclaim progress and the automatic `abandoned` and `expired` closures. Use this endpoint for ad hoc checks and support workflows, not as your primary real time mechanism.

Webhooks are especially important for longer-running payment flows such as BTC Classic / Bitcoin on-chain. In those flows, the customer may leave the payment page after the payment reaches `processing`, while the merchant still needs to know the outcome.

Recommended pattern:

* use the hosted payment page or status endpoint to show the customer the current payment state
* use webhooks to update the merchant order, invoice, or fulfillment workflow
* use this endpoint for customer support, reconciliation checks, or manual refresh actions
* avoid relying on the customer keeping a browser tab open until the outcome is known

**Use `paymentId` as the primary lookup key**

Save the `paymentId` from the Create Payment response alongside your order or invoice. Use it to correlate status checks, webhooks, and Reporting records. `trackingId` is a legacy identifier that is deprecated but still supported for backwards compatibility; new integrations should use `paymentId`.

**Store the actual paid `tenderType`**

Save the returned `tenderType` once the payment has an outcome. This lets your system distinguish between the tenders offered during checkout and the tender actually used to pay.

For example, if a hosted payment flow allowed multiple tenders but the customer paid with Bitcoin Lightning, the completed payment status returns `tenderType: "bitcoin_Lightning"`.

**Map status codes to internal order states**

Translate every status into an internal state that your business and support team understand. `completed` and `overpaid` are paid. `underpaid`, `expired`, `abandoned`, `invalid`, and `cancelled` are not paid. Track reclaim progress separately, using `refundLifecycleStatus`.

**Use a pending state for BTC Classic processing**

For BTC Classic / Bitcoin on-chain payments, map `processing` to an internal pending state such as:

* payment detected
* pending confirmation
* awaiting BTC confirmation
* payment processing

Do not map BTC Classic `processing` to paid, approved, fulfilled, or complete.

Recommended mapping:

| Bead status  | Outcome  | Internal state                                 | Fulfillment behavior    |
| ------------ | -------- | ---------------------------------------------- | ----------------------- |
| `created`    | Pending  | Awaiting payment                               | Do not fulfill yet      |
| `processing` | Pending  | Payment detected / pending confirmation        | Do not fulfill yet      |
| `completed`  | Paid     | Paid                                           | Fulfillment may proceed |
| `overpaid`   | Paid     | Paid, excess returned to payer through reclaim | Fulfillment may proceed |
| `underpaid`  | Not paid | Payment declined / retry with a new payment    | Do not fulfill          |
| `expired`    | Not paid | Payment expired                                | Do not fulfill          |
| `abandoned`  | Not paid | Payment not started / closed                   | Do not fulfill          |
| `invalid`    | Not paid | Payment invalid / review required              | Do not fulfill          |
| `cancelled`  | Not paid | Payment cancelled                              | Do not fulfill          |

**Avoid tight polling loops**

If you must poll, use reasonable intervals and a backoff strategy. For anything beyond small scale, move to webhooks together with Reporting and Settlement.

**Combine with Reporting and Settlement for reconciliation**

Use this endpoint for single payment checks. For daily reconciliation and accounting, rely on the Reporting payment history endpoints and the Settlement APIs to see payments, batches, and payment settlement lines together.

**Next steps**

* Configure [Payment Webhooks](https://developers.bead.xyz/payments/payment-webhooks.md) for real time payment events.
* Review [Tender Types](https://developers.bead.xyz/reference-guide/enumerations-and-schemas/tender-types.md) for the list of valid `tenderType` values.
* Review [Tracking Reclaim Status](https://developers.bead.xyz/reference-guide/payment-scenarios/tracking-reclaim-status.md) for how to follow a reclaim return through to completion.
* Review [Why do BTC (on-chain) payments take longer?](https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/why-do-btc-on-chain-payments-take-longer.md) for more detail on Bitcoin on-chain confirmation timing and customer messaging.
* Review [Choosing Tender Types by Payment Environment](https://developers.bead.xyz/reference-guide/payment-flows/choosing-tender-types-by-payment-environment.md) for guidance on when BTC Classic is appropriate for physical, digital, invoice, and delayed-fulfillment flows.
* Review [Payment Scenarios](https://developers.bead.xyz/reference-guide/payment-scenarios.md) for practical examples of handling overpaid, underpaid, and reclaim outcomes.
* Review [Why is my payment still Created or In Progress?](https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/why-is-my-payment-still-created-or-in-progress.md) for what to expect when a payment is started but not finished.
* Review [Why is my Klarna payment still processing?](https://developers.bead.xyz/faqs-and-troubleshooting/payments-faqs/why-is-my-klarna-payment-still-processing.md) for how Klarna payments move through `processing`.
* Use [Reporting](https://developers.bead.xyz/reporting.md) and [Settlement](https://developers.bead.xyz/settlement.md) to build dashboards and reconciliation jobs that operate over many payments at once.

**Legacy authentication**

Some existing Payments integrations authenticate using OAuth password grant and send an access token as:

```http
Authorization: Bearer {access_token}
```

New integrations should use the terminal API key method described above. If you are on the legacy model, see [Authentication](https://developers.bead.xyz/authentication.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/payments/payment-statuses.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
