PayPal · Holds, captures, payouts

Every Handshake deal runs on PayPal's own payment primitives. The buyer's money is reserved, not sent; the seller sees it's real; and only the right amount ever moves, after the item arrives.

Try it live

One real sandbox deal, start to finish

Nintendo Switch OLED · asking $230

Buyer's offer held by PayPal
Orders v2 · AUTHORIZE
$215.00
Agents agree on
Only this can ever be charged
$210.00
Captured after delivery
Payments v2 · final_capture
$210.00
Released to the buyer
Never charged
$5.00
PayPal fee
From the capture
−$5.93
Paid to the seller
Payouts v1
$204.07

The deal lifecycle

Paying a stranger usually means trusting them first. Handshake puts PayPal in the middle of every step, so neither side has to.

  1. 01

    Reserve, don't send

    The buyer approves a PayPal order with intent AUTHORIZE. The money is held on their account and nothing moves to anyone.

    Orders v2
  2. 02

    Know where it ships

    The authorization returns the buyer's PayPal-verified address. The seller's label is checked against it, since PayPal Seller Protection generally needs the item shipped there.

    Shipping address
  3. 03

    Keep it reserved

    PayPal guarantees a hold for three days. If the item is still in transit, a Render Workflow reauthorizes it so the funds stay reserved until delivery.

    Reauthorize
  4. 04

    Charge only what's fair

    On delivery, Handshake captures the deal price, or less after a damage refund, with final_capture. PayPal releases whatever is left.

    Partial capture
  5. 05

    Prove it shipped

    Tracking is attached to the PayPal capture, which PayPal recommends for physical goods and uses when resolving disputes. Protection eligibility is PayPal's call.

    Order tracking
  6. 06

    Pay the seller

    The seller's share goes out through PayPal Payouts, after PayPal's fee, straight to their PayPal account.

    Payouts v1
  7. 07

    Hand over a receipt

    Once PayPal captures, the buyer gets an official PayPal invoice, marked paid: the item and what was promised, the agreed price, any refund as its own line, the tracking and the capture.

    Invoicing v2
  8. 08

    Or release it all

    Seller never ships, or the agents can't agree? The hold is voided and the buyer is never charged.

    Void

Built for real money

Idempotent by default

Every PayPal request carries its own PayPal-Request-Id, so a retry or a double click can never charge twice.

Bound to one browser

Checkout is pinned to the browser that started it with a private cookie. A stranger holding an order id can't finish someone else's payment.

Amounts set in code

The AI never decides how much money moves. Capture amounts come from the agreed price and code-capped refund rules.

Proof

$223.55

paid to a seller after PayPal's $6.45 fee on a $230 deal: hold, ship, capture, track, payout.

Full deal

$5

of a $215 backed offer released automatically when the agents agreed on $210.

Partial capture

100%

of a hold returned when the agents couldn't agree, voided before anyone was charged.

Void

What we call

Log in with PayPal

POST /v1/oauth2/token · GET /v1/identity/oauth2/userinfo

Sellers sign in on PayPal's own page. Handshake gets their verified status and payer id, never a password.

Create order

POST /v2/checkout/orders

intent AUTHORIZE at the deal price, or at the buyer's max for a backed offer.

Authorize

POST /v2/checkout/orders/{id}/authorize

Turns the buyer's approval into a hold and returns their PayPal-verified shipping address.

Capture

POST /v2/payments/authorizations/{id}/capture

Captures the agreed amount, or less after a refund, with final_capture so the rest is released.

Reauthorize

POST /v2/payments/authorizations/{id}/reauthorize

Renews the hold after PayPal's 3-day honor period, run on schedule by a Render Workflow.

Void

POST /v2/payments/authorizations/{id}/void

Releases the whole hold on cancel, when the agents can't agree, or when the seller misses the shipping deadline.

Add tracking

POST /v2/checkout/orders/{id}/track

Attaches the carrier and tracking number to the capture, as PayPal recommends for physical goods.

Payouts

POST /v1/payments/payouts

Sends the seller their net amount after PayPal's fee, into their own PayPal account by payer id.

Invoicing

POST /v2/invoicing/invoices · /{id}/send · /{id}/payments

After the capture, the buyer's receipt: a PayPal invoice for the deal, marked paid, never emailed to anyone. It never moves money.

JS SDK Buttons

intent=authorize

PayPal's own checkout window, plus the sandbox test card for judges without a login.

Docs & source

Check a deal Sell with Handshake