Skip to main content

How to Use Bitcoin Payment Links and QR Codes

A Bitcoin payment link packages an on-chain Bitcoin address and, optionally, payment details such as an amount. The same request can be represented as a QR code so that you do not have to type the address manually.

Gem Wallet supports plain Bitcoin addresses and standard bitcoin: payment requests based on BIP-21 and BIP-321.

RequestExample formatWhat Gem Wallet uses
Plain addressbc1...Bitcoin recipient address
BIP-21 linkbitcoin:bc1...?amount=0.001Address and optional BTC amount
BIP-321 linkbitcoin:?bc=bc1...&amount=0.001On-chain address and optional BTC amount

A request can also contain label or memo metadata. Always rely on the recipient address and amount shown on Gem Wallet's confirmation screen when deciding whether to send.

note

The formats above are examples only. Do not send BTC to a shortened or placeholder address.

Scan a Bitcoin Payment QR Code​

Use a payment request that you already intend to pay. You can reproduce these steps safely and stop before selecting Confirm.

  1. Open Bitcoin in Gem Wallet.
  2. Select Send.
  3. Select the QR scanner on the recipient screen.
  4. Scan the payment QR code with the camera, or choose its saved image when that option is available.
  5. Review the recipient and amount decoded by Gem Wallet.

An address-only request opens the send flow so that you can enter the BTC amount. A complete request that includes a supported amount can advance to transaction review.

Before confirming, compare the complete Bitcoin address and requested amount with the invoice or instructions you received. Also review the selected wallet, network fee, and total debit.

caution

A QR code prevents typing mistakes, but it does not prove that the recipient is trustworthy. A malicious website, message, or replaced QR code can still provide an attacker's address.

Select a bitcoin: link on your device. If the operating system offers a choice of compatible apps, select Gem Wallet. The app validates the request and opens the applicable Bitcoin send screen.

If the request provides both a standard address after bitcoin: and a bc parameter, Gem Wallet uses the standard address. Parameter names and the bitcoin scheme are handled without case sensitivity.

Gem Wallet also removes surrounding whitespace and ignores a URL fragment after # before decoding the request. You should still verify the final recipient rather than relying on the original text.

Supported and Unsupported Payment Details​

Gem Wallet validates the Bitcoin address and converts a supported BTC amount without rounding excess decimal places.

The decoder supports:

  • A plain on-chain Bitcoin address.
  • An on-chain address in a BIP-21 or BIP-321 request.
  • An optional BTC amount.
  • Optional label and memo metadata.
  • An address in the BIP-321 bc parameter when no address follows bitcoin:.

Gem Wallet can ignore unsupported payment instructions, including Lightning, BOLT 12, and silent-payment fields, when the same request contains a usable on-chain Bitcoin address. It rejects a request that contains only unsupported instructions and no usable on-chain address.

A request containing an unsupported required parameter beginning with req- is rejected in full. This prevents the wallet from silently overlooking a condition that the requester marked as mandatory.

The Request Cannot Be Opened​

Check that the request includes a complete, valid Bitcoin address. A Lightning-only invoice, BOLT 12 offer, silent-payment-only request, or unrelated QR code cannot be used as a standard on-chain Bitcoin recipient in this flow.

If the link contains an unknown req- parameter, ask the recipient for a compatible on-chain Bitcoin address or a new payment request. Do not remove a required field and assume the payment will have the intended result.

The Amount Is Not Accepted​

Confirm that the amount is denominated in BTC and contains a valid decimal value. Gem Wallet rejects an amount with more precision than Bitcoin supports instead of rounding it to a different amount.

Ask the recipient for a corrected request, or scan an address-only QR code and enter the verified amount manually.

The Camera Cannot Scan the Code​

  • Allow Gem Wallet to use the device camera.
  • Improve the lighting and keep the entire QR code inside the scanner frame.
  • Clean the camera lens and increase the QR code's display brightness.
  • Save the QR code and select it as an image when the scanner provides that option.
  • Ask for the full Bitcoin address and compare it character by character before continuing.

Do not continue. Return to the invoice or recipient through a trusted channel and verify the complete address and BTC amount. Clipboard malware or a modified website can replace payment details.

Before You Confirm​

  • Confirm that the request is for on-chain Bitcoin, not another asset or network.
  • Compare the complete recipient address using a second trusted channel for important payments.
  • Verify the BTC amount and its displayed fiat estimate.
  • Review the Bitcoin network fee.
  • Send a small test amount before a large first-time payment when practical.

For general Bitcoin account information, see Bitcoin (BTC). If a submitted payment remains unconfirmed, follow Why Is My Crypto Transaction Pending?.