> 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/reference-guide/operational-guides/using-an-llm-or-agent-to-build-a-payments-poc.md).

# Using an LLM or Agent to Build a Payments POC

This page helps you quickly build a proof of concept (POC) integration using an LLM, coding agent, or IDE assistant. The fastest POC is:

1. Create a payment using `POST /Payments`
2. Present the hosted payment page URL (`paymentUrls[0]`) in a browser tab or iframe
3. Poll status using `GET /Payments/{paymentId}/tracking` until the payment reaches an outcome

This approach avoids webhook setup and is ideal for demos and early prototypes.

> `POST /Payments/crypto` is deprecated but still supported, and takes the same request body. Use `POST /Payments` for new work.

### What you need

To run the POC, you need these values from Bead:

* `apiKey` (terminal API key)
* `merchantId`
* `terminalId`

Sandbox defaults:

* Payments base URL: `https://api.test.devs.beadpay.io`
* Payments authentication header: `X-Api-Key: <apiKey>`
* There is no separate authentication URL for Payments when using API key authentication.

### POC flow

#### Step 1: Create a hosted payment page

Endpoint:

* `POST /Payments`

Required headers:

* `X-Api-Key: {apiKey}`
* `Content-Type: application/json`

Minimal request body (recommended for POCs). `refundEmail` and `customer` are required on virtual terminals:

```json
{
  "merchantId": "{merchantId}",
  "terminalId": "{terminalId}",
  "requestedAmount": 1,
  "reference": "POC-ORDER-001",
  "refundEmail": "test@example.com",
  "customer": {
    "firstName": "Test",
    "lastName": "User",
    "email": "test@example.com",
    "address": "123 Main St",
    "address2": "",
    "city": "Boston",
    "state": "MA",
    "postalCode": "02110",
    "countryCode": "US"
  }
}
```

Save these values from the response:

* `paymentUrls[0]` (hosted payment page URL)
* `paymentId` (used to check status)

#### Step 2: Present the hosted payment page

You can present the hosted payment page in one of these ways:

Option A: Open in a browser tab

* Redirect or open `paymentUrls[0]` directly in the user’s browser

Option B: Embed in an iframe (web apps)

* Render an iframe with `src=paymentUrls[0]`
* Use a full height container so QR codes and tender selection are visible
* If embedding is blocked, fall back to opening in a new tab

#### Step 3: Poll for status using paymentId

Endpoint:

* `GET /Payments/{paymentId}/tracking`

Headers:

* `X-Api-Key: {apiKey}`
* `Accept: application/json`

Example curl (Sandbox):

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

Recommended polling behavior:

* Start polling after you launch the hosted page
* Poll every 2 seconds for a POC demo
* Only log or display changes when status changes
* Stop polling when `statusCode` is no longer `created` or `processing`. The outcomes are:
  * Paid: `completed`, `overpaid`
  * Not paid: `underpaid`, `expired`, `cancelled`, `invalid`, `abandoned`

For `overpaid`, the payment is paid and the excess is returned to the payer later through Bead's reclaim process. For `underpaid`, the payment is not paid and the customer should start a new payment. See [Payment Statuses](https://developers.bead.xyz/payments/payment-statuses.md).

### POC UI flow (recommended)

Build a single page with three states:

1. Amount entry

* Amount input that accepts decimals
* Primary button: Pay with crypto

2. In progress

* Show the hosted payment page (iframe or new tab link)
* Show live status (`statusCode`) while polling

3. Complete

* Show a completion view when an outcome is reached
* Display:
  * the `statusCode` and whether the payment is paid
  * requested amount
  * `paymentId`
* Button: Start a new payment (resets to amount entry)

### Common troubleshooting

401 Unauthorized

* API key missing or invalid
* Header must be exactly `X-Api-Key`
* Ensure you are using the real `apiKey` value, not a masked value

403 Forbidden

* API key is valid but not permitted for the `merchantId` or `terminalId`
* Confirm all values are from the same environment and credential set

Environment mismatch

* Sandbox values only work with the Sandbox base URL
* Production values only work with the Production base URL

### Copy and paste prompt for an LLM or coding agent

Use the prompt below in ChatGPT, an IDE agent, or another coding assistant. It produces a minimal POC that creates a payment, presents the hosted page, polls for status, and shows a completion screen.

If your agent cannot open the OpenAPI URL in the prompt directly, download the spec yourself and attach the file to the conversation.

> Prompt
>
> You are a senior full stack engineer. Build a minimal proof of concept that integrates with Bead Payments using API key authentication only.
>
> Sandbox defaults:
>
> * Payments base URL: `https://api.test.devs.beadpay.io`
> * Payments auth header: `X-Api-Key: {apiKey}`
> * No separate authentication URL is used for Payments when using API key authentication.
>
> References (use if you need to confirm schemas and endpoints):
>
> * OpenAPI (authoritative): `https://api.test.devs.beadpay.io/openapi/v1.json`
> * Developer docs (supporting): `https://developers.bead.xyz/` If there is any conflict, follow the OpenAPI. For Payments authentication, do not use OAuth. Use `X-Api-Key` only.
>
> Inputs I will provide:
>
> * `{apiKey}` (terminal API key, full value)
> * `{merchantId}`
> * `{terminalId}`
>
> UI requirements:
>
> 1. Show a simple amount entry input:
>    * Label: Amount
>    * Accept decimals
>    * Validate amount is greater than 0
>    * Default to 1.00 on first load
> 2. Show a primary button:
>    * Label: Pay with crypto
> 3. When the user clicks Pay with crypto:
>    * Call the backend to create a payment with the entered amount
>    * Display the hosted payment page in an iframe (or open a new tab if iframe embedding is blocked)
>    * Display a status panel showing the current `statusCode`
> 4. When the payment reaches an outcome, show a Payment Complete screen:
>    * Replace the iframe view with a completion view
>    * Display the status and whether the payment is paid. Paid: `completed`, `overpaid`. Not paid: `underpaid`, `expired`, `cancelled`, `invalid`, `abandoned`
>    * For `overpaid`, show that the extra amount will be returned to the payer
>    * For `underpaid`, show that the payment did not go through and offer to start a new payment
>    * Display the amount requested
>    * Display the paymentId
>    * Provide a button to Start a new payment (resets UI back to amount entry)
>
> API requirements:
>
> 1. Create a hosted payment using:
>    * `POST https://api.test.devs.beadpay.io/Payments`
>    * Header: `X-Api-Key: {apiKey}`
>    * Header: `Content-Type: application/json`
>    * JSON body includes:
>      * `merchantId: {merchantId}`
>      * `terminalId: {terminalId}`
>      * `requestedAmount: <amount from UI>`
>      * `reference: "POC-ORDER-<unique>"`
>      * `refundEmail: "test@example.com"`
>      * `customer` object exactly as shown below
> 2. Use this customer object in the request body:
>    * `firstName: "Test"`
>    * `lastName: "User"`
>    * `email: "test@example.com"`
>    * `address: "123 Main St"`
>    * `address2: ""`
>    * `city: "Boston"`
>    * `state: "MA"`
>    * `postalCode: "02110"`
>    * `countryCode: "US"`
> 3. From the create payment response, extract:
>    * `paymentUrls[0]` as `paymentUrl`
>    * `paymentId`
> 4. Poll for status using:
>    * `GET https://api.test.devs.beadpay.io/Payments/{paymentId}/tracking`
>    * Header: `X-Api-Key: {apiKey}`
>    * Poll every 2 seconds
>    * Only log when status changes
>    * Stop polling when `statusCode` is no longer `created` or `processing`
>
> Deliverables:
>
> * One backend endpoint (or function/route) that:
>   * accepts `requestedAmount`
>   * calls `POST /Payments`
>   * returns `paymentUrl`, `paymentId`, and echoed `requestedAmount`
> * One backend endpoint (or function/route) that:
>   * accepts `paymentId`
>   * calls `GET /Payments/{paymentId}/tracking`
>   * returns the status JSON including `statusCode`
> * One UI page with three states:
>   1. Amount Entry state (input + Pay with crypto button)
>   2. In Progress state (iframe or new tab link + live status panel)
>   3. Payment Complete state (status + paid or not paid + paymentId + start over button)
>
> Constraints:
>
> * Use only API key auth for Payments (`X-Api-Key`). Do not include OAuth flows, tokens, or any authentication URL.
> * Do not include webhooks.
> * Do not include onboarding or entity management.
> * Treat `apiKey` as a secret and do not log it.
> * Keep the implementation small and readable.


---

# 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/reference-guide/operational-guides/using-an-llm-or-agent-to-build-a-payments-poc.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.
