PayPal

PayPal REST API

Get an OAuth token, create and capture or authorize orders, refund captures, send invoices and verify webhooks in Sandbox.

PaymentsGuided#checkout#orders#refunds#invoicing#webhooks#oauth2

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

PayPal's REST APIs let a merchant take PayPal (and card) payments, refund them, bill customers with invoices and receive webhooks about all of it. This guided collection covers the server-side calls most integrations need: an OAuth 2.0 access token, Orders v2 (create, approve, capture or authorize), Payments v2 (capture an authorization, void, refund), Invoicing v2 and Webhooks (subscribe, simulate, verify a signature). It points at the Sandbox so nothing real is charged.

Get credentials

  1. Log in (or sign up) at https://developer.paypal.com/dashboard/ with a PayPal account.
  2. Open Apps & Credentials, make sure you are in Sandbox mode, and use the Default Application or Create App.
  3. Copy the app's Client ID and Secret into clientId and clientSecret.
  4. Under Testing Tools > Sandbox Accounts you already have a sandbox personal (buyer) and business (seller) account; use View/Edit Account to see the buyer's email and password. You log in with the buyer account when you approve an order. Live credentials come from the same page in Live mode once your business account is approved.

Docs: https://developer.paypal.com/api/rest/ and https://developer.paypal.com/api/rest/authentication/

Authentication

OAuth 2.0 client credentials. 1. Start here > Get an access token posts grant_type=client_credentials to /v1/oauth2/token with HTTP Basic auth (client ID as username, secret as password) and saves the returned access_token. Every other request sends Authorization: Bearer {{accessToken}} (set on the collection). Tokens last for the expires_in seconds in the response; when you get 401, run the token request again.

Base URLs

EnvironmentBase URL
Sandboxhttps://api-m.sandbox.paypal.com
Livehttps://api-m.paypal.com

Sandbox and live use different client IDs and secrets.

Variables and run order

Fill clientId and clientSecret, then run 1. Start here. In 2. Orders: pay now, create the order, open the saved approveUrl in a browser and log in as the sandbox buyer, then run the capture (it saves captureId). 3. Authorize, then capture repeats this with intent: AUTHORIZE. 4. Refunds uses captureId. 5. Invoicing sends an invoice to buyerEmail (set it to your sandbox buyer's email). 6. Webhooks needs a public HTTPS webhookUrl you control.

Create and capture calls send a PayPal-Request-Id (a fresh UUID from a pre-request script) so a retried request is not processed twice.

Limits and pricing

Sandbox is free. Live fees depend on country and payment type: https://www.paypal.com/us/business/paypal-business-fees. PayPal applies rate limiting and returns HTTP 429 RATE_LIMIT_REACHED when you exceed it; back off and retry. See https://developer.paypal.com/api/rest/reference/rate-limiting/

Common errors

Errors are JSON with name, message, debug_id and a details[] array whose issue is the precise code. Quote debug_id to PayPal support.

IssueMeaningWhat to do
401 invalid_tokenAccess token missing or expiredRun Get an access token again.
ORDER_NOT_APPROVED (422)Capture or authorize before the buyer approvedOpen approveUrl, approve, retry.
PAYER_ACTION_REQUIRED (422)Buyer must go back to PayPalRedirect to the payer-action link.
INSTRUMENT_DECLINED (422)Funding source declinedSend the buyer back to choose another method.
DUPLICATE_INVOICE_ID (422)invoice_id used beforeUse a unique invoice_id.
PERMISSION_DENIED (403)App lacks the feature or resource belongs to another accountEnable the feature for the app, check IDs.

Links

  • REST API overview: https://developer.paypal.com/api/rest/
  • Orders v2: https://developer.paypal.com/docs/api/orders/v2/
  • Payments v2: https://developer.paypal.com/docs/api/payments/v2/
  • Invoicing v2: https://developer.paypal.com/docs/api/invoicing/v2/
  • Webhooks: https://developer.paypal.com/api/rest/webhooks/rest/ and event names https://developer.paypal.com/api/rest/webhooks/event-names/
  • Orders errors: https://developer.paypal.com/api/rest/reference/orders/v2/errors/
  • OpenAPI specs: https://github.com/paypal/paypal-rest-api-specifications

Endpoints 24

1. Start here

  • POSTGet an access token/v1/oauth2/tokenPosts grant_type=client_credentials with HTTP Basic auth (client ID and secret) and returns an access_token plus expires_in (seconds) and the granted scope.…

2. Orders: pay now

  • POSTCreate an order (capture)/v2/checkout/ordersCreates an order for 10.00 USD that will be captured straight after the buyer approves (intent: CAPTURE). What comes back: the order with status:…
  • GETShow order details/v2/checkout/orders/{{orderId}}Reads the order by orderId. Use it to check status: CREATED or PAYER_ACTION_REQUIRED before approval, APPROVED once the buyer has approved, COMPLETED after…
  • PATCHUpdate the order amount/v2/checkout/orders/{{orderId}}Changes an order that is still CREATED or APPROVED (never COMPLETED) with a JSON Patch array. Paths address a purchase unit by its reference_id, here default.…
  • POSTCapture the order/v2/checkout/orders/{{orderId}}/captureTakes the money for an approved order. The body can be empty. On success status is COMPLETED and purchase_units[0].payments.captures[0] holds the capture,…

3. Authorize, then capture

  • POSTCreate an order (authorize)/v2/checkout/ordersSame as the capture order but with intent: AUTHORIZE, so approval only places a hold on the buyer's funds. Saves authOrderId and approveUrl; open the link and…
  • POSTAuthorize the order/v2/checkout/orders/{{authOrderId}}/authorizeTurns the approved order into an authorization (a hold). The authorization id in purchase_units[0].payments.authorizations[0] is saved to authorizationId,…
  • GETShow authorization details/v2/payments/authorizations/{{authorizationId}}Reads the authorization by authorizationId: status (CREATED, CAPTURED, PARTIALLY_CAPTURED, VOIDED, EXPIRED and others), amount and expiration_time. Check it…
  • POSTCapture the authorization/v2/payments/authorizations/{{authorizationId}}/captureCaptures held funds. Leave out amount to capture the full authorization, or send a smaller one; final_capture: true releases whatever is left. invoice_id and…
  • POSTVoid the authorization/v2/payments/authorizations/{{authorizationId}}/voidCancels an authorization that has not been fully captured and releases the hold on the buyer's funds. Run it instead of the capture above when an order is…

4. Refunds

  • POSTRefund a capture/v2/payments/captures/{{captureId}}/refundRefunds a captured payment saved in captureId. Send amount for a partial refund or an empty body for a full one; note_to_payer appears in the buyer's…
  • GETShow refund details/v2/payments/refunds/{{refundId}}Reads a refund by refundId to follow up a PENDING refund or show refund history. Contains the amount, status, any status_details.reason, and the seller…
  • GETShow capture details/v2/payments/captures/{{captureId}}Reads a capture by captureId: amount, status (becomes PARTIALLY_REFUNDED or REFUNDED after refunds), the seller receivable breakdown with PayPal's fee and net…

5. Invoicing v2

  • POSTGenerate the next invoice number/v2/invoicing/generate-next-invoice-numberAsks PayPal for the next invoice number in your account's sequence, so new invoices do not clash with old ones. The number is saved to invoiceNumber and used…
  • POSTCreate a draft invoice/v2/invoicing/invoicesCreates an invoice in DRAFT status. detail (currency, number, payment term such as NET_10) is required; add invoicer, primary_recipients[].billing_info and…
  • POSTSend the invoice/v2/invoicing/invoices/{{invoiceId}}/sendSends the draft to its recipients by email and moves it to SENT (or SCHEDULED when the invoice date is in the future). Optional subject, note,…
  • GETShow invoice details/v2/invoicing/invoices/{{invoiceId}}Reads the invoice by invoiceId: status (DRAFT, SENT, PAID, PARTIALLY_PAID, CANCELLED and others), totals, due_amount, recorded payments and refunds, and the…
  • GETList invoices/v2/invoicing/invoicesLists the account's invoices, newest first, with paging by page and page_size; total_required=true adds total_items and total_pages. For filters by status,…
  • POSTSend a payment reminder/v2/invoicing/invoices/{{invoiceId}}/remindEmails a reminder for a sent, unpaid invoice. Takes the same optional subject and note fields as sending. Returns 204 with no body.
  • POSTCancel the invoice/v2/invoicing/invoices/{{invoiceId}}/cancelCancels a sent invoice so it can no longer be paid and optionally emails the recipient. Use delete instead for drafts that were never sent. Returns 204 with…

6. Webhooks

  • POSTCreate a webhook/v1/notifications/webhooksSubscribes your HTTPS webhookUrl to the listed event_types for this app. The response id is saved to webhookId; you need it to verify signatures. Common…
  • GETList webhooks/v1/notifications/webhooksLists the webhooks subscribed for this app with their URLs and event types. Useful to find an existing webhookId instead of creating a duplicate.
  • POSTSimulate a webhook event/v1/notifications/simulate-eventSends a mock event of event_type to the webhook (webhook_id) or to any url, with a sample resource for that event, so you can test your listener. Mock events…
  • POSTVerify a webhook signature/v1/notifications/verify-webhook-signatureAsks PayPal whether a webhook you received is genuine. Copy the PAYPAL-AUTH-ALGO, PAYPAL-CERT-URL, PAYPAL-TRANSMISSION-ID, PAYPAL-TRANSMISSION-SIG and…

API details

Base URL
https://api-m.sandbox.paypal.com
https://api-m.paypal.com
Authentication
OAuth 2.0 (client credentials flow)
Operations
24 operations on 24 pathsPOST 16GET 7PATCH 1
Main resources
1. Start here 12. Orders: pay now 43. Authorize, then capture 54. Refunds 35. Invoicing v2 76. Webhooks 4
Description format
Swastik Codes guided collection, API version checked against the docs on 2026-11-18

How to test the PayPal REST API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the PayPal REST API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses OAuth 2.0 (client credentials flow). Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “Get an access token” (POST /v1/oauth2/token), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the PayPal REST API?

Get an OAuth token, create and capture or authorize orders, refund captures, send invoices and verify webhooks in Sandbox. It is listed under Payments and has 24 endpoints.

Who publishes the PayPal REST API?

It is listed from PayPal's public API description (an OpenAPI document), not published by PayPal on Swastik Codes. Anyone who controls paypal.com can claim the profile by adding a DNS TXT record.

What is the base URL of the PayPal REST API?

Its description lists 2 base URLs: https://api-m.sandbox.paypal.com, https://api-m.paypal.com. The first is the usual one; the others are typically sandbox or regional servers.

How do I authenticate with the PayPal REST API?

With OAuth 2.0 (client credentials flow).

How many endpoints does the PayPal REST API have?

24 operations on 24 paths (16 POST, 7 GET, 1 PATCH). The largest groups are 1. Start here, 2. Orders: pay now, 3. Authorize, then capture, 4. Refunds.

Is forking the PayPal REST API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.