DocsGuidesPayments

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#

  1. POST /api/payments/paypal/orders with { "obligation_id": "ob_rent" }.
  2. The server reads amount and currency from the stored obligation — never from the request — and creates an Orders v2 order.
  3. The response is 201 with payment, approve_url and mode (sandbox or live). Send the browser to approve_url; PayPal appends ?token=<order>&PayerID=<payer> to the return URL you configured (/obligations?paypal=return by default).
  4. POST /api/payments/paypal/capture with { "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 proof PayPal capture <id>.
bash
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.

  1. POST /api/trust/escrows with { obligation_id, provider_id, amount, payee_paypal_email }. The escrow starts as draft and records the fee split. A missing payee email returns payee_required.
  2. POST /api/trust/escrows/:id/hold creates a PayPal Orders v2 order with intent=AUTHORIZE and returns an approve_url. The escrow becomes hold_pending.
  3. 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 becomes authorized; nothing has moved yet.
  4. POST /api/trust/escrows/:id/release with { "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.
  5. POST /api/trust/escrows/:id/void releases 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.

  1. POST /api/seller/payouts moves every available earning into processing and records a payout.
  2. POST /api/payments/paypal/payouts with { "payout_id": "po_..." } calls Payouts v1 and records the batch id.
  3. GET /api/payments/paypal/payouts/:batch polls the batch. SUCCESS marks 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:

json
{
  "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.