Payment APIs: Connecting the Money to Order Fulfillment

A payment API is the set of endpoints your software uses to ask a payment provider to do something with a card: hold money, take money, give money back, remember a card for next time. That definition is the same whether you run a SaaS product or a bakery.

What changes for a business that delivers is the sequence. In a shop, the money and the goods move at the same instant, so one API call does the job. When the goods leave hours later on a van, the money has to travel through four or five steps, and the payment API is what keeps those steps attached to a single order. Payment APIs for order fulfillment are, in practice, plumbing between a charge and a handoff.

This post is the technical layer. The decision about which provider to use in the first place is in the guide to choosing a payment gateway for delivery orders, and if you’re automating charges for customers who order on a schedule, recurring billing for delivery routes covers a different set of endpoints entirely.

The Bottom Line

• The core pattern for delivery is authorize at order, capture at handoff. Everything else is detail hung off those two calls.
• Capture has a deadline. The network maximum is around 144 hours, with Visa typically expecting capture inside seven days (Solidgate, retrieved September 2026). If your delivery window is longer than that, store the card instead of holding the authorization.
• Tie the payment to an order object, not to a bare amount. Square’s Orders API, for example, exposes a PayOrder endpoint precisely so the charge and the line items stay one record (Square Developer, retrieved September 2026).
• Webhooks, not polling. A delivery business needs to know about a failed capture before the van leaves, which means the provider tells you rather than you asking every ten minutes.
• Use idempotency keys on every write. Bad signal at a back door means retries, and retries without a key mean double charges.

The Four Calls a Delivery Order Actually Needs

Strip away the vocabulary differences between providers and the fulfillment sequence is short.

• Authorize. At checkout, you ask the bank to approve and reserve an amount. The customer sees a pending charge. You have not been paid.
• Adjust. Between checkout and the door, the real total moves. A substitution, a case that weighed 14 pounds instead of 15, a tip. Depending on the provider you either increment the existing authorization or capture a different final amount.
• Capture. At handoff, or when the order is marked delivered, you take the money. This is the call that should fire off a fulfillment event rather than a clock.
• Refund or void. If the delivery fails, you void an uncaptured authorization, which costs nothing. If you already captured, you refund, which at most providers costs you the original processing fee. That difference is the whole argument for capturing late.

A fifth call sits alongside these for anyone taking repeat orders: store the payment method and get back a token you can charge later. That one matters when your delivery date is further out than the authorization window allows.

Tokenization is also why you should resist any urge to keep card numbers yourself. The token is meaningless to anyone who steals it, and card data you never hold is card data you never have to protect. It’s a live research question how long today’s encryption stays comfortable, and the payments industry watches work on quantum computing simulators for exactly that reason, but the practical version for a delivery business is unchanged and unglamorous: let the provider hold the card.

Why Authorize-Then-Capture Beats Charging at Checkout

Charging the full amount at checkout is one line of code fewer, and it’s the default in most storefront plugins. It’s also the source of most of the payment mess in a delivery operation.

Every correction becomes a refund. Refunds are slow for the customer, they usually cost you the processing fee anyway, and they turn one clean transaction into two lines on a statement, which is where “I was charged twice” support tickets come from.

The delayed-capture pattern fixes all three, at the price of a deadline. Solidgate puts the network maximum at 144 hours and recommends settling inside 120 (Solidgate, retrieved September 2026). Practical reading: it works fine for next-day and same-week delivery, and it does not work for a caterer booking an event in six weeks.

For anything beyond that window, the pattern changes. You store the card on file at checkout, capture a deposit immediately if you take one, and charge the stored token on the delivery day. The payment API handles both patterns; the mistake is using the short-window one for a long-window business and discovering it when captures start declining.

Tie the Payment to an Order, Not to an Amount

The single design decision that saves the most work later is refusing to let a payment exist as a floating dollar figure.

Most modern payment APIs support this directly. Square splits it into a Payments API and an Orders API, where the Orders API records line items, calculates totals, tracks progress through fulfillment, and exposes PayOrder so the charge attaches to that record (Square Developer, retrieved September 2026). Other providers do the same thing with metadata fields on the payment intent.

Either way, the rule is: every authorization carries your order ID, and every capture references the same one.

What that buys you:

• A card taken at the door lands against the order automatically, instead of being a $64.20 swipe somebody matches to a paper list that evening.
• Your payout reconciles. One bank deposit covering forty orders minus fees can be broken back down without human guesswork.
• Disputes are defensible. When a customer claims an order never arrived, the payment record points at the order record, which points at the proof of delivery.
• Partial captures make sense. A capture of $58.90 against an authorization of $64.20 reads as a short pick, not as a mystery.

Webhooks: Finding Out Before the Van Leaves

Polling an API on a timer is fine for a report. It’s wrong for fulfillment, because the events you care about are the ones that should stop a box going out.

The webhooks worth subscribing to:

• Payment authorized and payment failed, so an order with a declined card never reaches the pick list.
• Capture succeeded and capture failed. A failed capture after an expired authorization is the quiet one that costs real money, because the goods have usually already gone.
• Refund created, so your order system and your books agree without anyone retyping.
• Dispute opened, which starts a clock you don’t control and usually needs proof of delivery attached within days.

Two implementation notes that are boring and load-bearing. Verify the webhook signature, because an unauthenticated endpoint that marks orders paid is exactly as bad as it sounds. And make your handler idempotent, because providers retry deliveries and you will receive the same event twice.

One more event class is worth a decision rather than a default: fraud screening. Most gateways include basic rules, and specialist risk platforms such as Sift’s fintech and finance tooling score a transaction before you authorize it. For local delivery the exposure is modest, since the goods go to a real address on a real route, so start with your provider’s built-in rules and only add a layer if card-testing or first-order fraud actually shows up in your data.

Handling Retries, Bad Signal and Double Charges

Payment code that works in an office fails at a back door with one bar of signal.

Idempotency keys are the fix, and they’re supported by every serious provider. You generate a unique key per logical operation and send it with the request. If the driver’s phone retries because the response never arrived, the provider recognizes the key and returns the original result rather than charging again.

The rule to enforce in your own code: the key belongs to the operation, not to the retry. Capturing order 4417 uses the same key on attempt one and attempt four. A fresh key on each attempt is the same as having no key at all.

Offline queuing is the related question, and it’s worth asking your provider directly rather than assuming. Some in-person SDKs queue a transaction locally and submit it when signal returns, with a ceiling on the amount. Others simply fail. Knowing which you have decides whether “take the card at the door” is a real option on rural routes.

What to Build First

Nobody needs the whole surface area on day one. A sensible order of work:

• Authorization at checkout, with your order ID attached. This alone stops bad cards from reaching the pick list.
• Capture triggered by your delivery-completed event rather than by a schedule.
• The failed-capture webhook, wired to something a human will actually see.
• Stored payment methods, once you have customers ordering further out than the authorization window.
• Partial capture and authorization increments, once substitutions or tips are frequent enough to be annoying.

If your provider can’t do the first two cleanly, that’s a gateway problem rather than an integration problem, and it’s worth re-reading the three factors that decide the gateway choice before writing more code against it.

Buy the Integration or Build It?

Most businesses under a few hundred orders a week should not be writing directly against a payment API at all.

Native connections between a storefront, a POS and a gateway already do the authorize-and-capture dance, and a connector tool can move the events between systems that don’t know each other. The API is the fallback for the gap that nothing covers, which in a delivery business is usually the link between “delivered” and “captured”.

One exception pushes people to the API sooner than volume alone would: paying suppliers abroad. A wholesaler importing produce or a florist buying stems overseas is running money in the other direction, and the endpoints for that sit with cross-border payment platforms rather than with the gateway taking your customers’ cards. Keep the two flows separate in your head and in your books; conflating them is how foreign exchange costs end up invisible.

Build against the API when three things are true: the sequence you need doesn’t exist as a native option, the volume justifies maintaining it, and somebody will still be around to fix it when the provider deprecates a version. Otherwise the cheapest payment API is the one your existing tools are already calling on your behalf.