---
name: bsv-payments
description: "Design or implement sending and receiving BSV between people: paying a handle or a contact, the review screen, handing the payment over as BEEF, receiving it with internalizeAction, requests and QR codes, and the plain-address fallback with its wrong-network defences. Use when asked to 'send BSV', 'pay a handle', 'receive a payment', 'build the review screen', 'show a QR code', 'accept a Paymail', 'paste an address', or anything about moving BSV from one person to another."
---

> Start from [bitcoinsv-design](../bitcoinsv-design/SKILL.md). Shared states, labels, errors, amounts and fees: [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

# Send and receive BSV payments

**Scope:** Person-to-person payments: choosing who, the review screen, the handover, receiving, requests, and plain addresses.

**Does NOT cover:**

- The mechanics of createAction and states: see [bsv-actions](../bsv-actions/SKILL.md)
- Charging per use: see [bsv-micropayments](../bsv-micropayments/SKILL.md)
- Formatting amounts: see [bsv-amounts-and-copy](../bsv-amounts-and-copy/SKILL.md)

**Cross-references:** [bsv-actions](../bsv-actions/SKILL.md), [bsv-amounts-and-copy](../bsv-amounts-and-copy/SKILL.md), [bsv-wallet-connection](../bsv-wallet-connection/SKILL.md), [shared patterns](../bitcoinsv-design/references/shared-patterns.md).

The recommended flow is peer to peer (BRC-29): the sender's wallet finds the recipient, derives a one-time key from both parties' keys (BRC-42), builds and signs the payment, and hands it to the recipient as BEEF (BRC-62), which carries the proofs needed to check it. The recipient's wallet verifies it against block headers and replies accepted or rejected. For the user this collapses to: pick who, enter how much, confirm, and see **Paid** within seconds. The review screen's job is catching the wrong recipient, which is the mistake people actually make.

## ALWAYS

- Resolve the handle and show the profile name and avatar before the confirm button. Paying "Anna Keller" is checkable; paying anna@example.com is only spellable. See Paying by handle. _([costs money](https://www.bitcoinsv.design/guide/rule/fba6444cf1/))_
- Warn on every pasted address that money sent to an address on another network is very hard to recover, and offer the user's contacts or a handle instead. _([costs money](https://www.bitcoinsv.design/guide/rule/2433fe3c54/))_
- Tell the user once when their wallet is retrying for them: "Your wallet will keep trying to send this. You don't need to pay again." _([costs money](https://www.bitcoinsv.design/guide/rule/2a72388be3/))_
- Show on the review screen the same sats amount the wallet's prompt will show, and if the rate moves before Anna presses the button, update the figure on this screen first rather than letting the wallet show a different number. _([costs money](https://www.bitcoinsv.design/guide/rule/cef01aa4a6/))_
- Say when the key behind a saved contact has changed since last time, and make the user acknowledge it. A silently rotated key is how a handle gets hijacked. _([costs money](https://www.bitcoinsv.design/guide/rule/f47f34353f/))_
- Make the handle the default and the address the fallback. Every payment that uses a handle is a payment that cannot go to the wrong network. _([costs money](https://www.bitcoinsv.design/guide/rule/98fc09f14d/))_

## NEVER

- Let a typed handle go straight to a confirm screen with no resolution step. The resolution is the check. _([costs money](https://www.bitcoinsv.design/guide/rule/44c3c56764/))_
- Offer "Try again" on a payment until you know the first attempt did not go out. _([costs money](https://www.bitcoinsv.design/guide/rule/24ccdc3485/))_
- Add a booking fee or any other charge after the review screen. If the product charges one, it is part of the price shown here. _([costs money](https://www.bitcoinsv.design/guide/rule/9d65fbb29c/))_
- Use "bitcoin address" as the field label. That is the word that cannot distinguish the networks, on the screen where the distinction is the whole point. _([costs money](https://www.bitcoinsv.design/guide/rule/e92e4f5284/))_
- Ask for a spending allowance "to make the next purchase faster". A site people pay a few times a year should ask each time. _([costs trust](https://www.bitcoinsv.design/guide/rule/6d94573c75/))_
- Keep a fee picker because the design system already has one. It asks the user a question with no wrong answer, which teaches them that your questions are decorative. _([costs trust](https://www.bitcoinsv.design/guide/rule/5d31c5cfd7/))_

## Patterns

_Design guidance in each pattern comes from the guide page it cites. Method names, arguments and code are implementation notes checked against `@bsv/sdk` 4.0.0._

### 1. Pay a handle or a contact

**When:** The user picks who to pay.

**How:**

1. Offer, in order of safety: saved contacts, scanning a code, a request somebody sent, and typing a handle last. Autocomplete from contacts before accepting free text.
2. Resolve a typed handle and show the profile name and avatar before the confirm button. The resolution is the check.
3. If a saved contact's identity key has changed since last time, say so and make the user acknowledge it before paying.
4. Build the payment with `createAction` (see bsv-actions), then hand the resulting `tx` (AtomicBEEF) to the recipient over the transport they advertise: their payment endpoint, a message box, or Paymail.
5. Show **Paid**, with the recipient's name, when their wallet replies accepted. Offer to save a new recipient as a contact.

**Error states:**

- **The handle does not resolve:** Name the part that failed: no such handle, the domain is unreachable, or the certificate did not check out. Not "Couldn't find that".
- **The recipient cannot take a peer-to-peer payment:** Say the payment can still go, with weaker confirmation, rather than silently downgrading to a plain address.
- **`WERR_INSUFFICIENT_FUNDS`:** Say the shortfall from `moreSatoshisNeeded`: "You need 1,200 more sats."

_Source: [Sending](https://www.bitcoinsv.design/guide/daily-spending-wallet/sending/)_

### 2. Build the review screen

**When:** Between choosing and confirming, every time.

**How:**

1. Make the recipient the largest thing on the screen: profile name and avatar, with the handle smaller beneath.
2. Show the amount in the user's unit with local currency, an optional note the recipient will see, and one confirm action.
3. Leave out a fee picker, a priority choice, a protocol selector, an expiry countdown and an "advanced" disclosure. Put the fee in the details afterwards.
4. Require the device's own authentication above the threshold the user set.

_Source: [Sending](https://www.bitcoinsv.design/guide/daily-spending-wallet/sending/)_

### 3. Receive a peer-to-peer payment

**When:** A payment arrives as BEEF with the sender's remittance details.

**How:**

1. Call `internalizeAction` with the AtomicBEEF and, for each output that pays the user, `protocol: 'wallet payment'` and the `paymentRemittance` the sender supplied (`derivationPrefix`, `derivationSuffix`, `senderIdentityKey`).
2. The wallet verifies it against block headers. On success, show **Received** at once with the sender's name and any note, and reply accepted.
3. If it cannot be verified, reject it with a plain explanation rather than showing it as pending.
4. Never show a confirmation counter on an everyday incoming payment; it was verified on arrival.

```ts
import { WalletClient, type AtomicBEEF } from "@bsv/sdk";

const wallet = new WalletClient("auto", "example.com");
declare const tx: AtomicBEEF;
declare const derivationPrefix: string, derivationSuffix: string;
declare const senderIdentityKey: string;

await wallet.internalizeAction({
  tx,
  description: "Payment from Maya",
  outputs: [
    {
      outputIndex: 0,
      protocol: "wallet payment",
      paymentRemittance: { derivationPrefix, derivationSuffix, senderIdentityKey },
    },
  ],
});
```

_Source: [Payments](https://www.bitcoinsv.design/guide/how-it-works/payments/)_

### 4. Ask to be paid

**When:** The user wants somebody to pay them.

**How:**

1. Share a handle, with a QR code as the in-person version of the same thing. Never lead a receive screen with an address.
2. Let a request carry an amount and a note, prefilled where you can. Keep anything personal out of the note by default; it is shared with the payer.
3. Do not generate and show a new address per request. A fresh key is derived per payment automatically.

_Source: [Requesting](https://www.bitcoinsv.design/guide/daily-spending-wallet/requesting/)_

### 5. Fall back to a plain address safely

**When:** The recipient only has an address: an older wallet, an exchange, an old invoice.

**How:**

1. A BSV address and an address on another chain can share a format and pass each other's validation. No check can tell them apart, so design is the only defence.
2. Label the field **BSV address**, never "bitcoin address", and warn on every paste rather than trying to detect a bad one.
3. Put the network on the confirmation beside the recipient, in the same weight as the amount, and say before the button that a payment to the wrong network cannot be recovered.
4. Offer a test payment to a first-time address above a threshold. It costs less than 1p.
5. Keep sending to a plain address possible in every consumer wallet. It is the user's way out if everything else fails.

_Source: [Wrong-network payments](https://www.bitcoinsv.design/guide/patterns/wrong-network-payments/)_

## All the rules

`references/rules.md`: 100 rules from 10 pages, 34 of them costly, most costly first.
Every rule in the guide, most costly first: https://www.bitcoinsv.design/api/rules.json

## Implementation resources

- **[@bsv/sdk](https://bsv-blockchain.github.io/ts-sdk/)**: The TypeScript SDK: `WalletClient` for every BRC-100 call, `AuthFetch` for HTTP 402, transactions, scripts and BEEF. Source at github.com/bsv-blockchain/ts-sdk.
- **[Wallet Toolbox](https://github.com/bsv-blockchain/wallet-toolbox)**: The wallet side of the interface: storage, signing and `WalletPermissionsManager`. Start here if you are building a wallet rather than an app.
- **[BRCs](https://github.com/bsv-blockchain/BRCs)**: Every proposal the skills cite, by number.

---

_Generated from https://www.bitcoinsv.design/, Open BSV License Version 6. Rules are extracted from the guide's pages and cannot be out of date about what it says; the patterns may still need updating._