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/crypto

2. Present the hosted payment page URL (paymentUrls[0]) in a browser tab or iframe

3. Poll status using GET /Payments/tracking/{trackingId} until the payment reaches a final state

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

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/crypto

Required headers:

• X-Api-Key: {apiKey}

• Content-Type: application/json

Minimal request body (recommended for POCs):

{
  "merchantId": "{merchantId}",
  "terminalId": "{terminalId}",
  "requestedAmount": 1,
  "paymentUrlType": "web",
  "reference": "POC-ORDER-001",
  "customer": {
    "firstName": "Test",
    "lastName": "User",
    "email": "[email protected]",
    "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)

• trackingId (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 trackingId

Endpoint:

• GET /Payments/tracking/{trackingId}

Headers:

• X-Api-Key: {apiKey}

• Accept: application/json

Example curl (Sandbox):

curl -s -X GET "https://api.test.devs.beadpay.io/Payments/tracking/{trackingId}" \
  -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 in a terminal state such as:

  • completed

  • expired

  • cancelled

  • invalid

  • underpaid

  • overpaid

POC UI flow (recommended)

Build a single page with three states:

1. Amount entry

• Amount input that accepts decimals

• Primary button: Pay with crypto

1. In progress

• Show the hosted payment page (iframe or new tab link)

• Show live status (statusCode) while polling

1. Complete

• Show a completion view when a terminal state is reached

• Display:

  • final statusCode

  • requested amount

  • trackingId

• 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.

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/apidocs/v1/api.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 a terminal state, show a Payment Complete screen:

   • Replace the iframe view with a completion view

   • Display the final status (completed, expired, cancelled, invalid, underpaid, overpaid)

   • Display the amount requested

   • Display the trackingId

   • 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/crypto

   • Header: X-Api-Key: {apiKey}

   • Header: Content-Type: application/json

   • JSON body includes:

     • merchantId: {merchantId}

     • terminalId: {terminalId}

     • requestedAmount: <amount from UI>

     • paymentUrlType: "web"

     • reference: "POC-ORDER-<unique>"

     • customer object exactly as shown below

2. Use this customer object in the request body:

   • firstName: "Test"

   • lastName: "User"

   • email: "[email protected]"

   • address: "123 Main St"

   • address2: ""

   • city: "Boston"

   • state: "MA"

   • postalCode: "02110"

   • countryCode: "US"

3. From the create payment response, extract:

   • paymentUrls[0] as paymentUrl

   • trackingId

4. Poll for status using:

   • GET https://api.test.devs.beadpay.io/Payments/tracking/{trackingId}

   • Header: X-Api-Key: {apiKey}

   • Poll every 2 seconds

   • Only log when status changes

   • Stop polling when statusCode reaches a terminal state: completed, expired, cancelled, invalid, underpaid, overpaid

Deliverables:

• One backend endpoint (or function/route) that:

  • accepts requestedAmount

  • calls POST /Payments/crypto

  • returns paymentUrl, trackingId, and echoed requestedAmount

• One backend endpoint (or function/route) that:

  • accepts trackingId

  • calls GET /Payments/tracking/{trackingId}

  • 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 (final status + trackingId + 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.