> 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-status-response-examples.md).

# Payment Status Response Examples

This page provides representative payment status payloads for common Bead payment outcomes.

The same status payload shape is used when you retrieve a payment status directly and when Bead sends a payment status webhook to your system.

Use these examples when mapping Bead payment outcomes to your internal order, invoice, or support states.

### Status payload references

Use the tracking endpoint when you need to check the current status of a specific payment on demand.

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

Bead also sends payment status webhook events to the configured webhook URL for the terminal or payment. Your webhook handler should process the request body using the same status payload structure shown in the examples below.

```http
POST {yourWebhookUrl}
Content-Type: application/json
```

### Payload shape

The status payload includes identifiers, the current payment state, amount information, and optional merchant-supplied metadata.

```json
{
  "paymentId": "string",
  "trackingId": "string",
  "paymentCode": "string",
  "statusCode": "created | processing | completed | underpaid | overpaid | expired | invalid | cancelled",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      },
      "inRequestedCurrency": {
        "amount": 0,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      }
    }
  },
  "reference": "string",
  "description": "string",
  "receivedTime": "2026-05-29T17:10:01Z",
  "terminalId": "string",
  "merchantId": "string",
  "errorMessage": null
}
```

### Field notes

| Field                                   | Description                                                                                                                       |
| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `paymentId`                             | Bead payment identifier. Use this value with `GET /Payments/{id}/tracking`.                                                       |
| `trackingId`                            | Tracking identifier returned when the payment was created. Store this with your internal order or invoice record for correlation. |
| `paymentCode`                           | Short payment code shown on the hosted payment page and in reporting.                                                             |
| `statusCode`                            | Current Bead payment status. Use this as the source of truth for payment state.                                                   |
| `amounts.requested.inRequestedCurrency` | Amount requested from the customer in the original requested currency.                                                            |
| `amounts.requested.inPaymentCurrency`   | Amount expected in the selected payment currency, when available.                                                                 |
| `amounts.paid.inPaymentCurrency`        | Amount actually received in the payment currency.                                                                                 |
| `reference`                             | Optional merchant-supplied reference from the original payment request.                                                           |
| `description`                           | Optional merchant-supplied description from the original payment request.                                                         |
| `receivedTime`                          | Timestamp associated with the status event or update.                                                                             |
| `terminalId`                            | Terminal associated with the payment.                                                                                             |
| `merchantId`                            | Merchant associated with the payment.                                                                                             |
| `errorMessage`                          | Additional error context when available. Usually `null` for normal lifecycle states.                                              |

### Status examples covered

| Status       | What the example shows                                              |
| ------------ | ------------------------------------------------------------------- |
| `created`    | Payment record created; no funds confirmed yet                      |
| `processing` | Payment is in progress; final outcome is not yet known              |
| `completed`  | Customer paid the requested amount                                  |
| `underpaid`  | Customer sent less than the requested amount                        |
| `overpaid`   | Customer sent more than the requested amount                        |
| `expired`    | Payment expired before completion                                   |
| `cancelled`  | Payment was cancelled before completion                             |
| `invalid`    | Irregular or unsupported payment event requiring exception handling |

Refund statuses are not shown on this page.

### Created

A `created` payment has been created, but the customer has not completed payment and no funds have been confirmed.

```json
{
  "paymentId": "pay_created_example",
  "trackingId": "trk_created_example",
  "paymentCode": "4DPJ2MEPAZHR",
  "statusCode": "created",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      },
      "inRequestedCurrency": {
        "amount": 1.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      }
    }
  },
  "reference": "abc123",
  "description": "test",
  "receivedTime": "2026-05-29T18:17:16Z",
  "terminalId": "term_created_example",
  "merchantId": "merch_created_example",
  "errorMessage": null
}
```

### Processing

A `processing` payment is still in progress. The customer or wallet flow may have started, but the final payment outcome is not yet known.

Do not treat `processing` as a successful final state.

```json
{
  "paymentId": "pay_processing_example",
  "trackingId": "trk_processing_example",
  "paymentCode": "6J2BNQBHEBHC",
  "statusCode": "processing",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 1.00,
        "currency": {
          "id": 101,
          "code": "CIT_USD_VENMO",
          "name": "Venmo",
          "symbol": "$"
        }
      },
      "inRequestedCurrency": {
        "amount": 1.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      }
    }
  },
  "reference": "abc123",
  "description": "test",
  "receivedTime": "2026-05-30T00:03:50Z",
  "terminalId": "term_processing_example",
  "merchantId": "merch_processing_example",
  "errorMessage": null
}
```

### Completed

A `completed` payment indicates that the customer paid the requested amount.

```json
{
  "paymentId": "pay_completed_example",
  "trackingId": "trk_completed_example",
  "paymentCode": "D8CU3N7A6CF4",
  "statusCode": "completed",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0.00000014,
        "currency": {
          "id": 201,
          "code": "BTC",
          "name": "Bitcoin Lightning",
          "symbol": "BTC"
        }
      },
      "inRequestedCurrency": {
        "amount": 0.01,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0.00000014,
        "currency": {
          "id": 201,
          "code": "BTC",
          "name": "Bitcoin Lightning",
          "symbol": "BTC"
        }
      }
    }
  },
  "reference": "POS-1780074506214",
  "description": "Leave a Penny",
  "receivedTime": "2026-05-29T17:10:01Z",
  "terminalId": "term_completed_example",
  "merchantId": "merch_completed_example",
  "errorMessage": null
}
```

### Underpaid

An `underpaid` payment means the customer sent less than the requested amount.

The `requested` and `paid` objects show the difference between the amount expected and the amount actually received.

```json
{
  "paymentId": "pay_underpaid_example",
  "trackingId": "trk_underpaid_example",
  "paymentCode": "KEYJWDJZR3TD",
  "statusCode": "underpaid",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0.00031198,
        "currency": {
          "id": 200,
          "code": "BTC",
          "name": "Bitcoin",
          "symbol": "BTC"
        }
      },
      "inRequestedCurrency": {
        "amount": 25.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0.00031197,
        "currency": {
          "id": 200,
          "code": "BTC",
          "name": "Bitcoin",
          "symbol": "BTC"
        }
      }
    }
  },
  "reference": "494810",
  "description": "Gift of College Payment for Transaction 494810",
  "receivedTime": "2026-05-08T23:50:45Z",
  "terminalId": "term_underpaid_example",
  "merchantId": "merch_underpaid_example",
  "errorMessage": null
}
```

### Overpaid

An `overpaid` payment means the customer sent more than the requested amount.

The `requested` and `paid` objects show the difference between the amount expected and the amount actually received.

```json
{
  "paymentId": "pay_overpaid_example",
  "trackingId": "trk_overpaid_example",
  "paymentCode": "EV5V2Z6V9TZH",
  "statusCode": "overpaid",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0.00000013655,
        "currency": {
          "id": 201,
          "code": "BTC",
          "name": "Bitcoin Lightning",
          "symbol": "BTC"
        }
      },
      "inRequestedCurrency": {
        "amount": 0.01,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0.00000014,
        "currency": {
          "id": 201,
          "code": "BTC",
          "name": "Bitcoin Lightning",
          "symbol": "BTC"
        }
      }
    }
  },
  "reference": "abc123",
  "description": "test",
  "receivedTime": "2026-04-10T19:14:13Z",
  "terminalId": "term_overpaid_example",
  "merchantId": "merch_overpaid_example",
  "errorMessage": null
}
```

### Expired

An `expired` payment means the payment window expired before the payment completed.

```json
{
  "paymentId": "pay_expired_example",
  "trackingId": "trk_expired_example",
  "paymentCode": "23DMFRZP52CY",
  "statusCode": "expired",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      },
      "inRequestedCurrency": {
        "amount": 0.01,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": null
      }
    }
  },
  "reference": "POS-1778177453583",
  "description": "Leave a Penny",
  "receivedTime": "2026-05-31T18:15:05Z",
  "terminalId": "term_expired_example",
  "merchantId": "merch_expired_example",
  "errorMessage": null
}
```

### Cancelled

A `cancelled` payment means the payment was cancelled before completion.

```json
{
  "paymentId": "pay_cancelled_example",
  "trackingId": "trk_cancelled_example",
  "paymentCode": "X7KM9JBZCQND",
  "statusCode": "cancelled",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 100.00,
        "currency": {
          "id": 301,
          "code": "USDC_BASE",
          "name": "USDC Base",
          "symbol": "USDC"
        }
      },
      "inRequestedCurrency": {
        "amount": 100.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0,
        "currency": {
          "id": 301,
          "code": "USDC_BASE",
          "name": "USDC Base",
          "symbol": "USDC"
        }
      }
    }
  },
  "reference": "6780e375-b9f8-41bf-9517-e275a7b75fd1",
  "description": "Area of Greatest Need",
  "receivedTime": "2026-05-29T17:24:07Z",
  "terminalId": "term_cancelled_example",
  "merchantId": "merch_cancelled_example",
  "errorMessage": null
}
```

### Invalid

An `invalid` payment indicates an irregular or unsupported payment event. Examples may include multiple transactions, unsupported assets, compliance blocks, extreme market movement, or other exception conditions.

The exact `errorMessage` may vary by cause.

```json
{
  "paymentId": "pay_invalid_example",
  "trackingId": "trk_invalid_example",
  "paymentCode": "INVALID12345",
  "statusCode": "invalid",
  "amounts": {
    "requested": {
      "inPaymentCurrency": {
        "amount": 0.00025,
        "currency": {
          "id": 200,
          "code": "BTC",
          "name": "Bitcoin",
          "symbol": "BTC"
        }
      },
      "inRequestedCurrency": {
        "amount": 20.00,
        "currency": {
          "id": 1,
          "code": "USD",
          "name": "US Dollar",
          "symbol": "$"
        }
      }
    },
    "paid": {
      "inPaymentCurrency": {
        "amount": 0.00025,
        "currency": {
          "id": 200,
          "code": "BTC",
          "name": "Bitcoin",
          "symbol": "BTC"
        }
      }
    }
  },
  "reference": "ORDER-INVALID-EXAMPLE",
  "description": "Example invalid payment",
  "receivedTime": "2026-05-29T17:30:00Z",
  "terminalId": "term_invalid_example",
  "merchantId": "merch_invalid_example",
  "errorMessage": "Payment could not be completed because the payment event was invalid."
}
```

### Implementation guidance

When mapping these payloads to your integration:

* Use `statusCode` as the primary state indicator.
* Store both `paymentId` and `trackingId` with your internal payment, invoice, or order record.
* Use `paymentId` when calling `GET /Payments/{id}/tracking`.
* Use `trackingId` to correlate Create Payment responses, webhook events, reporting records, and support workflows.
* Compare `amounts.requested` and `amounts.paid` when handling `underpaid` or `overpaid`.
* Treat `processing` as a non-final state.
* Treat `completed` as successful for the requested amount.
* Treat `underpaid`, `overpaid`, `expired`, `invalid`, and `cancelled` as not successful for fulfillment.
* Make webhook processing idempotent. You may receive the same event more than once.
* If a webhook event is missed, delayed, or received out of order, call `GET /Payments/{id}/tracking` to confirm the current state.

### Related pages

* [Payment Statuses](/payments/payment-statuses.md)
* [Payment Webhooks](/payments/payment-webhooks.md)
* [Payment Scenarios](/reference-guide/payment-scenarios.md)
* [Reclaiming Unconverted Crypto](/reference-guide/payment-scenarios/reclaiming-unconverted-crypto.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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/payments/payment-status-response-examples.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.