Creating payments
How to design a payment correctly, choose the right type, and understand the behavior of fixed, reusable, variable, and proxy payments.
Creating a payment in OpenPayment means designing the future behavior of checkout. The most important question is not "what amount should I charge?" but "what should this link be allowed to do over time?"
The payment definition is the source of truth
Before a payer ever opens checkout, OpenPayment stores a payment definition. That definition controls:
- who receives settlement
- which Base network is used
- whether the amount is fixed or editable
- whether the link can be reused
- whether payment unlocks a protected resource
If you choose the wrong payment type here, every later stage behaves incorrectly. That is why creation is the most important step in the lifecycle.
If you want to try the flow directly in the hosted product, start from the Create page.
Fields you are actually choosing
Every public interface for creating payments is built around the same business inputs.
| Field | What it controls |
|---|---|
| Type | Reuse, amount behavior, and whether a protected resource exists |
| Price | Fixed amount or suggested amount |
| Recipient wallet | Where USDC is settled |
| Network | Base Mainnet or Base Sepolia |
| Description | What the payer sees as context |
| Resource URL | The protected HTTPS endpoint for PROXY |
Today, the standard OpenPayment creation flow is USDC on Base. You choose the network; the rest of the token configuration is handled for you by the product.
How to choose the right payment type
| Type | Amount behavior | Reusable | Protected resource | Choose it when |
|---|---|---|---|---|
SINGLE_USE | Fixed | No | No | One payment should complete the request permanently |
MULTI_USE | Fixed | Yes | No | The same fixed-price link should be usable repeatedly |
VARIABLE | Suggested at creation, payer can override | Yes | No | Each payer may pay a different amount |
PROXY | Fixed | Yes | Yes | Payment should immediately unlock a server-side JSON/text response |
Type-by-type guidance
SINGLE_USE
Use SINGLE_USE when the link corresponds to one business event and should stop accepting payment after the first success.
Good fits:
- a single invoice
- one service engagement
- one fixed-price order
- a one-time reservation fee
Avoid it when:
- the same URL should be reused for future customers
- you need recurring or campaign-based collection
MULTI_USE
Use MULTI_USE when many payers should be able to use the same fixed-price link over time.
Good fits:
- a standard product link
- a recurring membership payment collected manually each cycle
- a repeated access fee
- a public "buy now" link for a fixed offer
The amount is fixed at creation and cannot be edited at checkout.
VARIABLE
Use VARIABLE when you want a reusable link but the final amount should be entered by the payer.
Good fits:
- tips
- donations
- pay-what-you-want products
- flexible invoice settlement
The configured price still matters because it acts as the default or suggested amount shown in checkout. The payer can increase or decrease it before paying.
PROXY
Use PROXY when payment should not only transfer funds but also unlock a protected resource immediately after settlement.
Good fits:
- paid API responses
- gated JSON or text reports
- protected lookups
- premium content returned from a private endpoint
Operationally, PROXY behaves like a reusable fixed-price payment plus a protected server-side fetch after payment.
Choosing by use case
If your use case looks like one of these, the choice is usually straightforward:
| Use case | Recommended type | Why |
|---|---|---|
| Customer pays an invoice once | SINGLE_USE | Prevents accidental reuse |
| Public checkout link for a fixed offer | MULTI_USE | One price, many payers |
| Tips, donations, creator support | VARIABLE | Payer chooses amount |
| Paid API call or gated report | PROXY | Payment and access control stay in one flow |
Amount semantics
The amount field does not mean the same thing for every type:
| Type | Meaning of the configured amount |
|---|---|
SINGLE_USE | The exact amount the payer must settle |
MULTI_USE | The exact amount required on every use |
VARIABLE | The suggested default shown before the payer edits it |
PROXY | The exact amount charged before the protected response is fetched |
This is why VARIABLE should not be used when the merchant must collect an exact amount.
Designing a good PROXY payment
Because PROXY is the most specialized payment type, it deserves extra care.
A strong PROXY design usually has these properties:
- the protected resource is available over HTTPS
- the resource returns JSON or text
- the resource responds quickly
- the resource accepts optional flat query parameters when context is needed
- the business logic treats payment success and resource success as related but separate outcomes
Use PROXY when the protected resource is the product.
What creation returns
Every creation interface returns the same two public artifacts:
paymentId- a shareable payment URL
Use the paymentId for internal tracking and support. Use the URL wherever a payer should enter checkout.
A practical creation checklist
Before generating a link, confirm:
- the recipient wallet is correct
- the network matches the environment you want
- the type matches the real business lifecycle
- the amount behavior is intentional
- for
PROXY, the protected resource is actually the thing you want to gate
If those five choices are correct, the rest of the OpenPayment flow tends to work predictably.