Payments: PayPal and escrow#
Money can move against an obligation in two ways, and they are deliberately separate. A PayPal payment settles an obligation in USD through the payer's own PayPal account. A PayPal escrow hold authorizes the amount up front and captures it only when proof is verified. Both attach to the same obligation and leave the same audit trail.
| Rail | Asset | Started by | Moves money |
|---|---|---|---|
| PayPal Orders | USD | A signed-in human, from the obligation | On capture |
| PayPal Payouts | USD | A signed-in human, from the seller desk | On payout confirmation |
| PayPal escrow hold | USD | A signed-in human, from the Trust page | On release, after verified proof |
Every route on this page is a session-cookie route. A machine key cannot start a payment, capture one, place a hold or send a payout. An agent that needs to move money has to do it through its execution connector, under the ceiling you gave it.
Paying an obligation with PayPal#
POST /api/payments/paypal/orderswith{ "obligation_id": "ob_rent" }.- The server reads amount and currency from the stored obligation — never from the request — and creates an Orders v2 order.
- The response is
201withpayment,approve_urlandmode(sandboxorlive). Send the browser toapprove_url; PayPal appends?token=<order>&PayerID=<payer>to the return URL you configured (/obligations?paypal=returnby default). POST /api/payments/paypal/capturewith{ "order_id": "..." }. The server captures the order, verifies the captured amount and currency against the stored row, records the capture id and completes the obligation with proofPayPal capture <id>.
curl -X POST "$REMINDIFY_URL/api/payments/paypal/orders" \
-H "cookie: remindify_session=..." \
-H "content-type: application/json" \
-d '{ "obligation_id": "ob_rent" }'Limits are deliberate: USD only, at most $10,000 per payment. A non-USD obligation returns currency_unsupported, and an amount of zero returns nothing_to_pay. Starting a new order supersedes any earlier uncaptured order for the same obligation, so a double click cannot leave two payable orders behind.
Capture is idempotent. Replaying the same order_id returns 200 with already_captured: true instead of charging again.
Escrow as an authorization hold#
Escrow does not move money when it opens. The payer approves a hold for up to 29 days (HOLD_DAYS=29), and the capture happens only on release, after the proof auditor has verified a receipt for the same obligation.
POST /api/trust/escrowswith{ obligation_id, provider_id, amount, payee_paypal_email }. The escrow starts asdraftand records the fee split. A missing payee email returnspayee_required.POST /api/trust/escrows/:id/holdcreates a PayPal Orders v2 order withintent=AUTHORIZEand returns anapprove_url. The escrow becomeshold_pending.- The payer approves in PayPal, which returns to
GET /api/trust/escrows/paypal/return?token=<order>. The server authorizes the order and records the authorization id and expiry. The escrow becomesauthorized; nothing has moved yet. POST /api/trust/escrows/:id/releasewith{ "proof_receipt_id": "rcpt_..." }. If the receipt is not already verified, the auditor runs first. On a verified receipt the server captures the authorization (POST /v2/payments/authorizations/{id}/capture) and sends a PayPal Payout to the payee email.POST /api/trust/escrows/:id/voidreleases an outstanding hold back to the payer. An escrow that was already captured cannot be voided; retry the payout instead.
The platform fee is deducted from the captured amount at release. With the default PAYPAL_PLATFORM_FEE_PERCENT=10, a $120 escrow captures $120, keeps $12 and pays the provider $108. The provider receives the net; there is no token and no custody.
If the capture succeeds but the payout fails, the escrow is parked as captured_awaiting_payout and the release returns payout_failed. It is not reported as settled, and the payout can be retried. A proof the auditor rejects returns proof_rejected and leaves the hold in place.
Sending a seller payout#
Sellers request a payout from cleared earnings in the seller desk, then send it to the PayPal email on file.
POST /api/seller/payoutsmoves everyavailableearning intoprocessingand records a payout.POST /api/payments/paypal/payoutswith{ "payout_id": "po_..." }calls Payouts v1 and records the batch id.GET /api/payments/paypal/payouts/:batchpolls the batch.SUCCESSmarks the payment paid and closes the payout; a returned or failed item marks it failed.
Without a PayPal email on the seller profile the route returns 409 paypal_email_required. The email is set in Seller desk → Storefront → Payout account.
Webhooks#
PayPal posts to /api/paypal/webhook. Events are applied only when PayPal confirms the signature for the configured PAYPAL_WEBHOOK_ID. Without that variable the endpoint acknowledges with 202 and applies nothing, so a forged call cannot complete an obligation or close a payout.
Handled events:
PAYMENT.CAPTURE.COMPLETED— marks the payment captured and completes the obligation.PAYMENT.CAPTURE.DENIED,PAYMENT.CAPTURE.REVERSED,CHECKOUT.ORDER.VOIDED— marks the payment failed.PAYMENT.PAYOUTS-ITEM.SUCCEEDED— marks the batch paid and closes the payout.- Any other
PAYMENT.PAYOUTS-ITEM.*— marks the batch failed.
Delivery is at-least-once, so handlers update by order id or batch id rather than appending.
Reading the ledger#
GET /api/payments returns every payment row in the workspace plus a summary:
{
"payments": [{ "kind": "obligation", "rail": "paypal", "status": "captured", "amount": 612, "currency": "USD", "order_id": "...", "capture_id": "..." }],
"summary": { "captured_count": 1, "captured_total": 612, "payouts_sent": 1, "failed": 0 },
"paypal": { "configured": true, "mode": "sandbox" }
}A payment row is one of created, captured, failed or superseded. state.payments inside GET /api/state carries the same rows for the signed-in app. Escrow holds and releases are on the Trust page and in GET /api/trust.
When to use which#
- PayPal Orders when the obligation should settle now and the proof is filed alongside the capture.
- PayPal escrow when the release condition has to be checked first: the payer authorizes a hold, the auditor verifies the receipt, and only then is the provider paid. See Proof and escrow.
- PayPal Payouts when a seller has cleared earnings and asks to be paid out.
What this does not do#
- No card checkout, subscriptions or stored payment methods. PayPal is the only payment provider.
- No refunds or disputes from inside Remindify. A failed or reversed capture is recorded; resolving it is a manual process.
- No multi-currency. Amounts are USD.
- No machine-key access. Payments are human actions, on purpose.
- No token. Settlement starts and ends inside PayPal.