Orqestria Download
← Back to Web app developers

Skill · Version 1.0.0

PayPal and Braintree integration

Connects server-controlled orders, captures and subscription events to a coherent payment and dispute lifecycle.

paypal-braintree-integration

Team members using this skill

See how it helps

When is it useful?

Use when implementing PayPal checkout or Braintree recurring billing.

What does it help you do?

  • Separates server order creation, buyer approval and server capture.
  • Maps subscription events to actual entitlements and billing states.
  • Verifies webhooks and tracks refunds or disputes explicitly.

Try asking this

Implement PayPal checkout in a sandbox and handle buyer approval followed by an uncertain capture response. After buyer approval, lose the capture response and query its status. Grant the purchase only from verified capture evidence, without issuing a second capture blindly.

Detailed documentation

Read the skill’s original instructions, examples and checks in their authored language.

Details…Show less

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.

Included files 1

  • SKILL.md