Feedback
Sign in./start

Site navigation

Theme

Learn

  • Roadmaps

Build

  • Projects
  • Developer Tools

Contribute

  • Open Source Projects
  • Issues
  • Reviews
  • First Contribution
  • BountiesSoon
  • Feedback

Prove

  • Builders

Ecosystem

  • Partners
  • Get Funded↗
  • HackathonsSoon
Sign in./start-building

Become an Open Source Builder. Learn. Build. Contribute. Prove.

Feedback welcome — open a GitHub issue.

Learn

RoadmapsStart Building

Build

ProjectsDeveloper Tools

Contribute

Open Source ProjectsIssuesReviewsFirst ContributionSupportFeedback

Prove

Builders Directory

Account

Sign in

Legal

PrivacyTermsCredits

© 2026 Pull // code MIT · curriculum CC BY-SA 4.0

PrivacyTermsCredits

lesson // bitcoin

Payment Processor API

Accept invoices, track confirmations, and handle payment webhooks.

advanced2 weeksproject // payment-processor

Public lesson — sign in to track progress on this roadmap.

./sign-in

On this page

Learning objectives

  • Create BIP-21 payment requests with unique addresses or amounts
  • Detect payments and confirmation thresholds
  • Emit signed webhooks to merchants

study // plan

Lessons are primers. Start with Step 1 (required reading) when present, then follow the numbered steps in the article. Depth comes from primary sources, labs, reflection, and evidence.

Research on Bitcoin Search

Step 1 // Required reading

Complete these before the numbered steps in the lesson body. Links are listed here once — not repeated below.

  • docsProject Spec: Payment Processor

    Pull project page — acceptance criteria and submit flow.

  • bipBIP-21 URI scheme

Reflection prompts

  1. Explain Payment Processor API to a teammate without jargon - what problem does it solve?
  2. What would break in production if you misunderstood Payment Processor API?
  3. Which BIP, book chapter, or Core doc is authoritative here, and what did you verify?

Lab // Project milestone evidence

Complete Steps 2–4. Ship invoice create → detect → confirm → webhook on regtest and capture demo evidence before marking complete.

evidence required

  • ·Link to public repo or branch
  • ·Demo of create invoice + paid/confirmed status (commands or screenshots)
  • ·Short note of one failure case (underpay, expiry, webhook retry)
  1. 01

    Worked mental model

    Re-read the diagrams in this lesson once out loud in plain language. If you cannot explain the flow to a friend without jargon, pause and revisit the Mastering Bitcoin / Mastering Lightning chapters linked in Resources. Chapter references are intentional, not decorative.

  2. 02

    Hands-on habit

    Every protocol idea should be paired with one local experiment. That habit turns reading into builder instinct.

    1. Reproduce the happy path on regtest (or Polar for Lightning)
    2. Break it on purpose (wrong fee, expired invoice, offline peer)
    3. Write down what error you saw and which layer produced it (wallet, node, mempool, peer)
  3. 03

    Glossary check

    Pick three terms from this lesson and define them in one sentence each without opening notes. Weak definitions mean the lesson is not finished yet.

  4. 04

    Resource order

    Use Resources in order: narrative book chapter first, then BIP/BOLT for precision, then implementation docs for commands. Jumping straight to RPC flags without the mental model creates brittle knowledge.

Merchants need idempotent invoices, confirmation policies, and reliable callbacks. This project is the on-chain cousin of a Lightning POS.

Complete Step 1 // Required reading in the study plan above, then continue here. This closes Projects.

Step 2 — Goal

API endpoints to:

  1. Create invoice (amount, expiry, address)
  2. Query invoice status
  3. Register webhook URL
  4. Mark paid after N confirmations

Return a BIP-21 URI with the invoice details.

Loading diagram…

Invoice creation, detection, confirmation, webhook.

Done when: You can explain idempotency for “create invoice” retries.

Step 3 — Milestones

PhaseShip
Milestone ACreate + get invoice with unique address / BIP-21
Milestone BDetect payment and confirmation threshold on regtest
Milestone CSigned webhook + under/over-payment policy documented

further reading

  • bookMastering Bitcoin

    Ch. 6: Transactions

  • articleBitcoin Optech

review // club

Chapter review picks

Practice on real Bitcoin OSS changes tied to this chapter. Read the diff, use the checklist, and optionally paste your review comment URL in your lab notes.

  • BTCPay Server payment flow GFI

    Study how BTCPay tracks invoices and note parallels to the payment processor project spec.

    gfi
    BIP-21confirmation tracking
    35 min·intermediateopen on GitHub

  • Mempool.space explorer GFI

    Compare mempool.space's fee views with what you'd build in the block explorer project.

    gfi
    UXfee visualization
    30 min·beginneropen on GitHub

  • BDK documentation pull requests

    Review a BDK docs PR and note whether examples would help a mini-wallet builder.

    pr review
    examplesAPI clarity
    35 min·beginneropen on GitHub
review checklist
  1. Does the change solve the stated problem?
  2. Are edge cases and rollout behavior covered?
  3. Are tests or test vectors included?
  4. Is the diff minimal and clearly explained?

More repos and GFIs on /discover and /issues.

build // next

Apply this chapter in a project

You have the concepts — ship something small to prove it. These Pull projects connect directly to what you just studied.

  • project // mini-wallet

    ./spec./submit

  • project // payment-processor

    ./spec./submit

discussion

Discussion

prevNode DashboardnextFinding Good First Issues

On this page

Press Shift + ? for keyboard shortcuts.

Press R to research on Bitcoin Search.

Under/over payment

Define policy for wrong amounts and late payments. Document it in the API.

Done when: Milestone B uses a stated confirmation policy (not “seen in mempool”).

Step 4 — Build & evidence (lab)

Implement against /projects/payment-processor. Capture repo link, happy-path demo, and one failure case.

Common mistakes

  • Reusing deposit addresses across invoices
  • Firing webhooks twice without idempotency keys
  • Treating 0-conf as settled for non-trivial amounts

Done when: Lab evidence is filed. Complete the chapter quiz when prompted.

Next lesson

OSS Discovery — find a good first issue in a Bitcoin repository.

No questions yet — be the first to ask.