Can I view payments with a Payment API key?

Yes. If you have a terminal-scoped Payment API key that can create a payment, you can also use that same key to retrieve payment history using the Payments endpoint filtered by terminalId.

This is the simplest way to confirm that payments are being created and to review recent transactions during early sandbox testing, without needing integrator admin credentials.

What this is for

Common use cases:

• Confirm a payment attempt was received and recorded by Bead

• Poll for new payments after launching a hosted payment page

• Show a basic “recent payments” list in a sandbox demo UI

• Diagnose “did the request reach Bead” without relying on network logs

Credentials required

You need:

• A Payment API key (terminal scoped)

• A terminalId associated with that key

You do not need:

• Integrator admin credentials

• Access to integrator reporting endpoints (for example, /merchants/{id}/payments or /terminals/{id}/payments)

Endpoint

GET /Payments?terminalId={terminalId}&page={page}&pageSize={pageSize}

This article focuses on terminalId only to keep the quick start narrow and consistent with the most common sandbox setup.

Example request (curl)

Copy and paste, then replace the placeholders with your values.

curl -X 'GET' \
  'https://api.test.devs.beadpay.io/Payments?terminalId=<TERMINAL_ID>&page=0&pageSize=50' \
  -H 'accept: application/json' \
  -H 'X-Api-Key: <PAYMENT_API_KEY>'

Placeholder notes:

• <TERMINAL_ID> looks like a hex string similar to: 69a09eb79f5a9af290440fdd

• <PAYMENT_API_KEY> is your terminal-scoped Payment API key value

Example response

The exact fields may vary by payment type and environment, but you should expect:

• A list of payments (or an envelope containing a list)

• Identifiers you can correlate to your payment creation flow (paymentId, trackingId, terminalId)

• Status fields showing where the payment is in its lifecycle

Example shape (illustrative):

{
  "page": 0,
  "pageSize": 50,
  "total": 2,
  "items": [
    {
      "paymentId": "<PAYMENT_ID>",
      "terminalId": "<TERMINAL_ID>",
      "amount": 12.34,
      "currency": "USD",
      "status": "approved",
      "createdAt": "2026-02-27T12:34:56Z",
      "network": "base",
      "asset": "USDC",
      "trackingId": "<TRACKING_ID>"
    }
  ]
}

If your API returns a raw array instead of an envelope, the same guidance applies. You can still paginate using page and pageSize.

Pagination guidance

Use these parameters:

• page: zero-based page index (0 is the first page)

• pageSize: number of records per page (typical values are 25, 50, 100)

Examples:

• First page, 50 results:

  • page=0&pageSize=50

• Second page, 50 results:

  • page=1&pageSize=50

For deeper guidance on pagination and sorting, see: https://developers.bead.xyz/reporting/payment-history-concepts/pagination-and-sorting

Recommended quick check workflow

1. Create a payment using your terminal Payment API key.

2. Call GET /Payments?terminalId=... to confirm the payment record exists.

3. If you have a hosted payment page flow, use this list to confirm the transaction started.

4. If you are watching for a final outcome, use your payment tracking flow for status changes and use payment history as a supporting view.

Common questions

Can I use merchantId instead?

This page focuses on terminalId to keep the early developer path simple. If you have merchant-level identifiers and access, the Payments endpoint may support additional filters.

Why do I see older payments from other tests?

If multiple testers reuse the same terminalId, you will see each other’s payments. Use a unique terminal per tester if you want isolated history.

How fresh is the data?

In sandbox, payment records should appear quickly after creation. If you do not see a payment immediately, wait a few seconds and retry.

Troubleshooting

401 Unauthorized or 403 Forbidden

Most common causes:

• The X-Api-Key header is missing or invalid

• You are using the wrong key type (not a terminal Payment API key)

• The key is not authorized for the terminalId provided

How to fix:

• Confirm you are using the terminal-scoped Payment API key you were issued for sandbox

• Confirm the terminalId matches the scope of that key

• Confirm you are calling the sandbox base URL:

  • https://api.test.devs.beadpay.io

400 Bad Request

Most common causes:

• terminalId format is invalid

• page or pageSize are missing or not integers

How to fix:

• Start from the sample curl and replace only <TERMINAL_ID> and <PAYMENT_API_KEY>

• Ensure page and pageSize are numeric values

Empty results but you know you made a payment

Most common causes:

• You used a different terminal for payment creation than the one you are querying

• You are querying the wrong environment base URL

How to fix:

• Confirm the terminalId used to create the payment matches the terminalId in the query

• Confirm you are using the test environment URL shown above

Related pages

• Test crypto transactions

• How to test Klarna payments

• Pagination and sorting (payment history concepts)