PayPal and Braintree integration

PayPal & Braintree Integration

PayPal and Braintree flows require strict separation between client-side approval and server-side authorization/capture. Never treat a client-side onApprove callback alone as a completed payment.

1. PayPal Orders v2 (One-Time Checkout)

Follow the authoritative two-step server-orchestrated flow:

1. Create Order on Server (POST /v2/checkout/orders):
   • Client requests checkout for a server-known item/plan.
   • Server computes amount (currency_code + string value formatted to the currency's exact decimal support, e.g., "29.99" for USD/EUR, or integer string "5000" for HUF and JPY — PayPal rejects decimals for HUF!), sets intent: "CAPTURE", attaches custom_id / invoice_id (for deduplication), and returns the PayPal orderID.
2. Buyer Approves in PayPal JS SDK:
   • The buyer approves the order in the PayPal button modal/redirect, triggering client onApprove({ orderID }).
3. Capture Order on Server (POST /v2/checkout/orders/{id}/capture):
   • Client calls your backend with orderID; your backend calls PayPal's capture endpoint with a PayPal-Request-Id idempotency header.
   • Inspect purchase_units[0].payments.captures[0].status:
     • COMPLETED: payment settled; record capture ID and grant entitlement.
     • PENDING: review status_details.reason (e.g., ECHECK, regulatory review); keep local payment processing until webhook confirms completion.
     • DECLINED / FAILED (or INSTRUMENT_DECLINED error): return recoverable error so the client SDK can call actions.restart() to pick another funding source.

2. PayPal Subscriptions & Braintree Recurring Billing

• PayPal Subscriptions (/v1/billing/subscriptions):
  • Link Product -> Billing Plan -> Subscription (custom_id set to your internal tenant/user ID).
  • Track lifecycle via webhooks: BILLING.SUBSCRIPTION.ACTIVATED, PAYMENT.SALE.COMPLETED (actual recurring payment settlement), BILLING.SUBSCRIPTION.PAYMENT.FAILED, BILLING.SUBSCRIPTION.SUSPENDED and BILLING.SUBSCRIPTION.CANCELLED.
  • Note that BILLING.SUBSCRIPTION.CREATED or client approval does not mean the first payment settled — verify subscription status and PAYMENT.SALE.COMPLETED.
• Braintree (Hosted Fields / Drop-in):
  • Generate clientToken on the server; client exchanges payment details for a single-use paymentMethodNonce.
  • Pass paymentMethodNonce and 3DS verification data to gateway.transaction.sale() or gateway.subscription.create() on the server.
  • Distinguish authorized vs. submitted_for_settlement vs. settled vs. settlement_declined.

3. Webhook Verification & Dispute Lifecycle

• PayPal Webhook Verification: verify incoming webhooks by calling POST /v1/notifications/verify-webhook-signature (passing transmission_id, transmission_time, cert_url, auth_algo, transmission_sig, webhook_id and the raw event) or cryptographic certificate verification, and deduplicate by event.id.
• Braintree Webhook Parsing: use gateway.webhookNotification.parse(bt_signature, bt_payload) and deduplicate by notification timestamp + kind + subject ID.
• Refunds & Disputes: handle PAYMENT.CAPTURE.REFUNDED, PAYMENT.CAPTURE.REVERSED and CUSTOMER.DISPUTE.CREATED / RESOLVED to freeze or adjust entitlements and record audit ledger entries.