Tender Types

Tender types identify the payment methods that can be enabled for a partner, merchant, location, terminal, or individual payment.

Use tender types when you need to:

• configure which payment methods are available

• limit a payment to one or more specific tenders

• understand which tender a customer used

• build reporting, filtering, or fulfillment logic by tender

• design customer experiences that match payment timing

Tender type values are API values. They are case-sensitive and must be passed exactly as documented.

Tender type basics

A tender type represents a payment rail or payment method. Examples include Bitcoin on-chain, Bitcoin Lightning, USDC networks, PayPal, Venmo, Klarna, Alipay, WeChat Pay, and Cash App.

Tender types can appear in different parts of the integration:

Context	How tender types are used
Partner configuration	Defines which tenders may be available under the partner.
Merchant configuration	Defines which tenders the merchant may accept.
Location configuration	Defines which tenders are available for a physical or virtual location.
Terminal configuration	Defines which tenders are available at a terminal.
Payment creation	Optionally limits a specific payment to selected tenders.
Payment status and reporting	Identifies the tender actually used for a payment.

Passing a tender type at payment creation does not enroll a merchant into that tender. The tender must already be enabled for the relevant partner, merchant, location, and terminal context.

Public tender type values

This page lists the tender types integrators should use when configuring or limiting customer-facing payment experiences.

Some tender type values may exist in the API for internal, legacy, or processor-specific use. Those values are not listed here unless they should be used in public integrations.

API value	Display label	Category	Notes
bitcoin	BTC (on-chain) / Bitcoin on-chain	Crypto	Bitcoin on-chain payment. Can take several minutes or longer to complete.
bitcoin_Lightning	Bitcoin Lightning	Crypto	BTC over Lightning. Separate from BTC (on-chain) and generally faster.
ethereum	Ethereum	Crypto	Ethereum-based crypto tender.
usdC_Polygon	USDC on Polygon	Crypto	USDC tender on Polygon.
usdC_Ethereum	USDC on Ethereum	Crypto	USDC tender on Ethereum.
usdcBase	USDC on Base	Crypto	USDC tender on Base.
usdcSolana	USDC on Solana	Crypto	USDC tender on Solana.
paypal	PayPal	Wallet app / alternative payment	PayPal tender.
venmo	Venmo	Wallet app / alternative payment	Venmo tender.
cashApp	Cash App	Wallet app / alternative payment	Cash App tender.
alipay	Alipay	Wallet app / alternative payment	Alipay tender.
weChatPay	WeChat Pay	Wallet app / alternative payment	WeChat Pay tender.
klarna	Klarna	Buy now, pay later	Klarna tender.

API values versus display labels

Tender type API values are not always the same as the customer-facing or merchant-facing labels.

For example:

Display label	API value
BTC (on-chain) / Bitcoin on-chain	bitcoin
Bitcoin Lightning	bitcoin_Lightning
USDC on Base	usdcBase
USDC on Solana	usdcSolana
WeChat Pay	weChatPay
Cash App	cashApp

Do not send display labels in API requests.

Do not send:

{
  "tenderTypes": ["BTC (on-chain)"]
}

Use:

{
  "tenderTypes": ["bitcoin"]
}

BTC (on-chain) naming

BTC (on-chain) is the customer- and merchant-friendly label for Bitcoin on-chain payments.

In the API, BTC (on-chain) is represented by:

bitcoin

Do not send BTC (on-chain), btcClassic, bitcoinClassic, or any other label as the tender type.

Use:

{
  "tenderTypes": ["bitcoin"]
}

Do not confuse BTC (on-chain) with Bitcoin Lightning.

Customer-facing name	API tender type	Meaning
BTC (on-chain) / Bitcoin on-chain	bitcoin	Standard Bitcoin network payment.
Bitcoin Lightning	bitcoin_Lightning	Lightning rail for BTC payments.

Bitcoin versus Bitcoin Lightning

bitcoin and bitcoin_Lightning both involve BTC, but they should not be treated as the same tender experience.

Tender type	Customer experience	Integrator guidance
bitcoin	Bitcoin on-chain transfer. May require network confirmation and can remain processing for several minutes or longer.	Design for asynchronous completion. Fulfill only on completed.
bitcoin_Lightning	Lightning payment flow. Typically faster and more suitable for customer-facing waiting flows.	Usually reasonable to keep the customer in the payment flow until final result. Fulfill only on completed.

Use bitcoin when the merchant wants to accept BTC (on-chain).

Use bitcoin_Lightning when the merchant wants to accept BTC over Lightning.

BTC (on-chain) timing guidance

BTC (on-chain) should be treated as a longer-running tender.

When a customer pays with BTC (on-chain), the payment may move to processing after Bead detects the transaction. That means the transaction is underway, but the payment is not final.

For BTC (on-chain):

• processing means payment detected, not completed

• completed is the fulfillment trigger

• the customer should not always be expected to keep the payment page open until final completion

• merchants should not release goods, ship orders, grant digital access, or mark invoices as paid until the payment reaches completed

• webhooks or payment status checks should be used to confirm final completion

BTC (on-chain) is often a good fit for:

• ecommerce orders with later shipment

• invoices

• service payments before pickup

• deposits

• high-ticket purchases

• high-touch retail environments

BTC (on-chain) is usually not a good fit for:

• fast in-person checkout

• low-ticket high-throughput retail

• instant digital downloads

• immediate account access

• any flow where fulfillment must happen immediately

Tender selection at payment creation

When creating a payment, use the optional tenderTypes array to limit the hosted payment experience to one or more tenders.

Example: limit payment to BTC (on-chain)

{
  "terminalId": "TERM-123",
  "merchantId": "MERCH-456",
  "requestedAmount": 2500.00,
  "reference": "ORDER-4821",
  "description": "Deposit payment",
  "tenderTypes": ["bitcoin"],
  "webhookUrls": [
    "https://example.com/webhooks/bead/payment"
  ]
}

Use this for Bitcoin on-chain / BTC (on-chain) payments.

Because BTC (on-chain) may take longer to complete, make sure the integration can:

• show the customer that payment has been detected

• keep the order or invoice pending while status is processing

• listen for webhooks or poll payment status

• fulfill only after completed

Example: offer BTC (on-chain) and Bitcoin Lightning

{
  "terminalId": "TERM-123",
  "merchantId": "MERCH-456",
  "requestedAmount": 100.00,
  "reference": "ORDER-9127",
  "description": "Customer payment",
  "tenderTypes": ["bitcoin", "bitcoin_Lightning"],
  "webhookUrls": [
    "https://example.com/webhooks/bead/payment"
  ]
}

Use this when the merchant supports both BTC rails and wants the customer to choose.

Example: limit payment to USDC on Base

{
  "terminalId": "TERM-123",
  "merchantId": "MERCH-456",
  "requestedAmount": 25.00,
  "reference": "ORDER-2201",
  "description": "Online order",
  "tenderTypes": ["usdcBase"],
  "webhookUrls": [
    "https://example.com/webhooks/bead/payment"
  ]
}

Use the exact tender value for the desired USDC network.

Example: offer wallet app tenders

{
  "terminalId": "TERM-123",
  "merchantId": "MERCH-456",
  "requestedAmount": 75.00,
  "reference": "ORDER-3891",
  "description": "Retail payment",
  "tenderTypes": ["paypal", "venmo", "cashApp"],
  "webhookUrls": [
    "https://example.com/webhooks/bead/payment"
  ]
}

Use this when the merchant wants to offer selected wallet app or alternative payment tenders.

Tender type returned on payments

A payment may be created with one or more allowed tender types, but the customer may choose one tender during the hosted payment experience.

When reading payment status, reporting, or webhook payloads, use the returned tender type to understand which tender was actually used.

For example:

Returned tender type	Meaning
bitcoin	Customer used BTC (on-chain) / Bitcoin on-chain.
bitcoin_Lightning	Customer used Bitcoin Lightning.
usdcBase	Customer used USDC on Base.
usdcSolana	Customer used USDC on Solana.
paypal	Customer used PayPal.
venmo	Customer used Venmo.
cashApp	Customer used Cash App.

Use the returned tender type together with statusCode to decide fulfillment behavior.

Tender-specific status handling

Different tenders can have different customer wait expectations.

Tender group	processing guidance	Fulfillment guidance
BTC (on-chain) / bitcoin	Payment detected and underway, but final completion may take several minutes or longer.	Fulfill only after completed.
Bitcoin Lightning / bitcoin_Lightning	Usually shorter customer-facing window.	Fulfill only after completed.
USDC tenders	May briefly process while transfer and confirmation complete.	Fulfill only after completed.
Wallet app and alternative payment tenders	Timing depends on the rail.	Fulfill only after completed.
Buy now, pay later tenders	Timing depends on the provider flow.	Fulfill only after completed.

Regardless of tender, do not treat processing as final payment success.

Choosing tenders by payment environment

Tender selection should match the merchant’s business model and customer experience.

Environment	Recommended tender strategy
Fast physical checkout	Prefer near-real-time tenders. Avoid BTC (on-chain) by default.
High-touch physical retail	BTC (on-chain) may be appropriate for high-ticket purchases if staff can explain the wait.
Ecommerce with later shipment	BTC (on-chain) can be appropriate because fulfillment naturally happens later.
Digital goods with instant delivery	Avoid BTC (on-chain) unless access can remain pending until completion.
Invoices	BTC (on-chain) is often appropriate because reconciliation can happen asynchronously.
Service pickup payments	BTC (on-chain) can work well when the customer pays before pickup.
Deposits and reservations	BTC (on-chain) can be appropriate if the merchant waits for completion before committing fulfillment.

Use the Choosing Tender Types by Payment Environment guide for more detailed recommendations.

Recommended integrator behavior for BTC (on-chain)

When tenderType is bitcoin:

1. Treat the payment as BTC (on-chain) / Bitcoin on-chain.

2. Show the customer BTC-specific timing guidance.

3. If the payment reaches processing, tell the customer the transaction has been detected.

4. Move the customer to an order, invoice, receipt, or status screen.

5. Keep the order or invoice pending.

6. Use Payment Webhooks or payment status checks to detect final status.

7. Fulfill only after completed.

Recommended customer-facing 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.

Common mistakes

Using the display label instead of the API value

Do not pass:

{
  "tenderTypes": ["BTC (on-chain)"]
}

Use:

{
  "tenderTypes": ["bitcoin"]
}

Treating Bitcoin and Bitcoin Lightning as interchangeable

Do not assume bitcoin and bitcoin_Lightning are the same customer experience.

bitcoin is BTC (on-chain) / Bitcoin on-chain.

bitcoin_Lightning is Bitcoin Lightning.

Fulfilling on processing

Do not release goods, grant digital access, ship an order, or mark an invoice as paid when the payment is only processing.

This is especially important for BTC (on-chain).

Use completed as the successful final payment state.

Enabling BTC (on-chain) everywhere by default

BTC (on-chain) can be valuable, but it should be enabled where delayed confirmation makes sense.

Avoid enabling it by default in fast checkout or instant-delivery environments unless the merchant has a clear pending-payment workflow.

Assuming enum-valid means enabled

A tender type may be a valid API value, but that does not mean it is enabled for a given merchant, location, terminal, or payment flow.

Before passing a tender in tenderTypes, confirm it is enabled in the relevant configuration context.

Operational guidance

Before enabling a tender, confirm that the merchant can operationally support it.

For each tender, ask:

• Can the customer wait for this tender to complete?

• Can the merchant delay fulfillment if needed?

• Can staff explain the payment state?

• Can the integration track final status asynchronously?

• Can the order, invoice, or account remain pending?

• Are webhooks configured?

• Is fulfillment gated on completed?

For BTC (on-chain), all of these questions matter. If the answer is no, use faster tenders instead.

Related pages

• Create Payment

• Payment Statuses

• Payment Webhooks

• Crypto Wallet Flow and Amounts

• Why do BTC (on-chain) payments take longer?

• Choosing Tender Types by Payment Environment