> 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/enumerations-and-schemas/tender-types.md). # 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: ```json { "tenderTypes": ["BTC (on-chain)"] } ``` Use: ```json { "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: ```json { "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) ```json { "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 ```json { "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 ```json { "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 ```json { "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: ```json { "tenderTypes": ["BTC (on-chain)"] } ``` Use: ```json { "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](/payments/create-payment.md) * [Payment Statuses](/payments/payment-statuses.md) * [Payment Webhooks](/payments/payment-webhooks.md) * [Crypto Wallet Flow and Amounts](/payments/crypto-wallet-flow-and-amounts.md) * [Why do BTC (on-chain) payments take longer?](/faqs-and-troubleshooting/payments-faqs/why-do-btc-on-chain-payments-take-longer.md) * [Choosing Tender Types by Payment Environment](/reference-guide/payment-flows/choosing-tender-types-by-payment-environment.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/reference-guide/enumerations-and-schemas/tender-types.md?ask=&goal= ``` `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.