PayPal Developer API Features
Catalog of PayPal REST capabilities, mapped to opshell.dev revenue shapes.
✅ marks features already covered by paypal-sandbox/paypal-test.mjs. Per-feature
test status is tracked in the Feature Test Matrix.
Sandbox scope
Everything below is testable against https://api-m.sandbox.paypal.com using
Sandbox app credentials. Features marked approval-gated may still be
disabled for the account and should be verified before design depends on them.
Authentication
| Feature | Endpoint | Testable | Notes |
|---|---|---|---|
| OAuth2 token (client credentials) | POST /v1/oauth2/token | ✅ | Prerequisite for every call |
| Token introspection | POST /v1/oauth2/token/introspect | Yes | Debugging |
| Userinfo (OIDC) | GET /v1/identity/oauth2/userinfo | Yes | For Log in with PayPal |
Checkout & payments
| Feature | Endpoint | Testable | Revenue shape |
|---|---|---|---|
| Create order | POST /v2/checkout/orders | ✅ | Digital packs |
| Get order | GET /v2/checkout/orders/{id} | Yes | All |
| Capture order | POST /v2/checkout/orders/{id}/capture | Yes | Digital packs |
| Authorize order | POST /v2/checkout/orders/{id}/authorize | Yes | Services |
| Void authorization | POST /v2/payments/authorizations/{id}/void | Yes | Services |
| Capture authorized payment | POST /v2/payments/authorizations/{id}/capture | Yes | Services |
| Refund capture | POST /v2/payments/captures/{id}/refund | Yes | All |
| Get capture / refund details | GET /v2/payments/captures/{id} | Yes | Reporting |
| PayPal JS SDK buttons | sdk.js (browser) | Yes | All |
| Advanced card payments (unbranded) | Payments v2 | Approval-gated | Card-only checkout |
| Venmo / Pay Later | JS SDK | Region-gated | Venmo is US-only |
Catalog & subscriptions (memberships)
| Feature | Endpoint | Testable | Notes |
|---|---|---|---|
| Create product | POST /v1/catalogs/products | ✅ | Container for plans |
| List / get / update product | GET /v1/catalogs/products | Yes | |
| Create plan | POST /v1/billing/plans | ✅ | USD only per plan |
| List / get / update / deactivate plan | GET /v1/billing/plans | Yes | |
| Create subscription | POST /v1/billing/subscriptions | Yes | Needs buyer approval |
| Get / list subscriptions | GET /v1/billing/subscriptions | Yes | |
| Cancel subscription | POST /v1/billing/subscriptions/{id}/cancel | Yes | Access revocation |
| Suspend / activate subscription | POST /v1/billing/subscriptions/{id}/suspend | Yes | Non-payment handling |
| Capture authorized subscription payment | Subscriptions v1 | Yes | |
| List subscription transactions | GET /v1/billing/subscriptions/{id}/transactions | Yes | Reconciliation |
| Free trials & setup fees | Plan overrides | Yes | Membership onboarding |
| Revise plan (price/quantity) | Subscriptions v1 | Yes | Upgrades |
Invoicing (services)
| Feature | Endpoint | Testable | Notes |
|---|---|---|---|
| Create draft invoice | POST /v2/invoicing/invoices | ✅ | |
| List / get / search invoices | GET /v2/invoicing/invoices | Yes | |
| Send / send reminder | /v2/invoicing/invoices/{id}/send | Yes | |
| Cancel invoice | /v2/invoicing/invoices/{id}/cancel | Yes | |
| Record payment (out-of-band) | /v2/invoicing/invoices/{id}/payments | Yes | Bank/wire clients |
| Refund invoice | Invoicing v2 | Yes | |
| Generate QR code | /v2/invoicing/invoices/{id}/generate-qr-code | Yes | |
| Generate next invoice number | /v2/invoicing/generate-next-invoice-number | Yes |
Invoicing not authorized
On 2026-09-13 the Sandbox app opshell returned NOT_AUTHORIZED when creating
a draft invoice. Enable Invoicing for the app/account before depending on it.
Status is tracked in the Feature Test Matrix.
Money movement & reporting
| Feature | Endpoint | Testable | Notes |
|---|---|---|---|
| Balances | GET /v1/reporting/balances | Yes | Balance display |
| Transaction search | GET /v1/reporting/transactions | Yes | Reconciliation |
| Single payout | POST /v1/payments/payouts | Approval-gated | Payout to sellers |
| Batch payout | POST /v1/payments/payouts | Approval-gated | Bulk payouts |
Webhooks, disputes, wallet
| Feature | Endpoint | Testable | Notes |
|---|---|---|---|
| Create / list / delete webhook | /v1/notifications/webhooks | Yes | Fulfillment trigger |
| Verify webhook signature | POST /v1/notifications/verify-webhook-signature | Yes | Security |
| List event types | GET /v1/notifications/webhooks-event-types | Yes | Event discovery |
| Webhook simulator | Developer Dashboard | Yes | Fire events without a real payment |
| List / get disputes | /v1/customer/disputes | Yes | Chargeback handling |
| Accept claim / provide evidence | /v1/customer/disputes/{id}/... | Yes | |
| Vault — store payment method | /v1/vault/... | Approval-gated | Saved cards / subscriptions |
Sandbox-only testing tools
| Tool | Purpose |
|---|---|
| Test business + personal accounts | Simulate a real buyer with Sandbox login |
| Magic amounts / negative testing | Force declines and error states |
| Sandbox credit cards | Card-only checkout flows |
| Webhook simulator | Trigger PAYMENT.CAPTURE.COMPLETED, BILLING.SUBSCRIPTION.*, etc. |
| API Explorer / Postman | Ad-hoc request testing |
Capability risks to verify before design locks
- Payouts and Vault — frequently approval-gated; may be unavailable for ID.
- Live receiving in Indonesia — Sandbox passes even when live is restricted; test separately with live credentials and a small real transaction.
- Venmo / Pay Later / advanced cards — geo- or approval-gated.
- One currency per plan — USD chosen; a second plan is required for any other currency.