REST API reference

Billing Agreements API

After you create and activate a billing plan, you can use the /payments/billing-agreements resource to create billing agreements. For PayPal payments, a buyer must approve an agreement before you can execute it. For more information, see Billing agreements.

Create agreement

POST /v1/payments/billing-agreements

Creates a billing agreement. In the JSON request body, pass an agreement object with the name, description, start date, ID of the billing plan on which to base the agreement, payer, and shipping address.

Update agreement

PATCH /v1/payments/billing-agreements/agreement_id

Updates details of a billing agreement, by ID. Details include the description, shipping address, start date, and so on.

Show agreement details

GET /v1/payments/billing-agreements/agreement_id

Shows details for a billing agreement, by ID.

Bill outstanding agreement amounts

POST /v1/payments/billing-agreements/agreement_id/bill-balance

Bills an outstanding amount for an agreement, by ID. In the JSON request body, pass an agreement_state_descriptor object with the reason for the agreement state change and the agreement amount and currency.

Cancel agreement

POST /v1/payments/billing-agreements/agreement_id/cancel

Cancels a billing agreement, by ID. In the JSON request body, pass an agreement_state_descriptor object with the reason for the agreement state change and the agreement amount and currency.

Re-activate agreement

POST /v1/payments/billing-agreements/agreement_id/re-activate

Reactivates a suspended billing agreement, by ID. In the JSON request body, pass an agreement_state_descriptor object with the reason for the agreement state change and the agreement amount and currency.

Set agreement balance

POST /v1/payments/billing-agreements/agreement_id/set-balance

Sets the balance for an agreement, by ID. In the JSON request body, pass a common_currency object with the balance currency type and value.

Suspend agreement

POST /v1/payments/billing-agreements/agreement_id/suspend

Suspends a billing agreement, by ID.

List agreement transactions

GET /v1/payments/billing-agreements/agreement_id/transactions

Lists transactions for a billing agreement, by ID. In the URI, specify the start and end dates of the range of transactions to list.

Execute agreement

POST /v1/payments/billing-agreements/payment_token/agreement-execute

Executes a billing agreement, by ID, after buyer approval.

Billing Plans API

To create a billing agreement, you must use the Billing Plans API to create and activate a billing plan. You do this one time. A billing plan defines the number of payments, the frequency of payments, and other payment details. After you update the state of a plan to ACTIVE to activate the plan, you can create a billing agreement that you base off that plan. You use a billing agreement to create subscriptions for customers. A subscription is a recurring payment for a customer.

Billing Plans (resource group)

Use the /billing-plans resource to:

Create plan

POST /v1/payments/billing-plans

Creates a billing plan. In the JSON request body, include the plan details. A valid billing plan consists of at least one payment definition and one merchant preference. If you include only one payment definition in the request, its type must be REGULAR. If you include two payment definitions in the request, one payment definition type must be TRIAL and the other type must be REGULAR. A payment definition can contain, but does not require, a list of charge models that add shipping and tax information.

Notes:
  • A billing plan supports a maximum of two payment definitions.
  • By default, the state of a new billing plan is CREATED. Before you can create a billing agreement from a plan, you must activate the plan. To activate a plan, update the plan state to ACTIVE.

Update plan

PATCH /v1/payments/billing-plans/plan-id

Replaces fields in a billing plan, by ID. In the JSON request body, include a patch object that specifies the operation to perform, one or more fields to update, and a new value for each updated field.

Show plan details

GET /v1/payments/billing-plans/plan-id

Shows details for a billing plan, by ID.

List plans

GET /v1/payments/billing-plans

Lists billing plans. To filter the billing plans that are returned in the response, specify one or more optional query and pagination parameters.

Identity API

Log In with PayPal (formerly PayPal Access) is a commerce identity solution that enables your customers to sign in to your web site quickly and securely using their PayPal login credentials. Log In with PayPal utilizes the latest security standards, and you don't have to worry about storing user data on your system.

For more information, learn about Log In with PayPal.

Grant token from authorization code

POST /v1/identity/tokenservice

Grant an access token from a previously obtained authorization code.

Grant token from refresh token

POST /v1/identity/tokenservice

Grant a new access token, using a refresh token.

Get user information

GET /v1/identity/openidconnect/userinfo

Retrieve user profile attributes.

Invoicing API

Use the Invoicing API to create draft invoices, send invoices, and manage invoices. You use invoices to track payments.

When you send an invoice, the invoice moves from draft to payable state and PayPal emails a link to the invoice on the PayPal website to the customer.

Customers with a PayPal account can log in and pay with PayPal. Alternatively, customers can pay with a check, debit card, or credit card.

For more information, see Invoicing overview.

Invoices (resource group)

Create invoice

POST /v1/invoicing/invoices

Creates a draft invoice. Optionally create an invoice template. Then, when you create an invoice from a template, the invoice is populated with the predefined data that the source template contains. To move the invoice from a draft to payable state, you must send the invoice. In the JSON request body, include invoice details including merchant information. The invoice object must include an items array.

Note: The merchant specified in an invoice must have a PayPal account in good standing.

Generate QR code

GET /v1/invoicing/invoices/invoice_id/qr-code

Generates a QR code for an invoice, by ID.

The QR code is a PNG image in Base64-encoded format that corresponds to the invoice ID. Generate a QR code for an invoice and add it to a paper or PDF invoice. When a customer uses their mobile device to scan the QR code, he or she is redirected to the PayPal mobile payment flow where he or she can pay online with PayPal or a credit card.

Before you get a QR code, you must:

  1. Create an invoice. Specify qrinvoice@paypal.com as the recipient email address in the billing_info object. Use a customer email address only if you want to email the invoice.
  2. Send an invoice to move the invoice from a draft to payable state. If you specify qrinvoice@paypal.com as the recipient email address, the invoice is not emailed.

List merchant invoices

GET /v1/invoicing/invoices

Lists invoices that belong to the merchant who makes the call.

Search for invoices

POST /v1/invoicing/search

Lists invoices that match search criteria.

Show invoice details

GET /v1/invoicing/invoices/invoice_id

Shows details for an invoice, by ID.

Update invoice

PUT /v1/invoicing/invoices/invoice_id

Updates an invoice, by ID.

Generate invoice number

POST /v1/invoicing/invoices/next-invoice-number

Generates the next invoice number that is available to the user.

Delete draft invoice

DELETE /v1/invoicing/invoices/invoice_id

Deletes a draft invoice, by ID. Note that this call works for invoices in the draft state only. For invoices that have already been sent, you can cancel the invoice. After you delete a draft invoice, you can no longer use it or show its details. However, you can reuse its invoice number.

Send invoice

POST /v1/invoicing/invoices/invoice_id/send

Sends an invoice, by ID, to a customer.

Note: After you send an invoice, you cannot resend it.

Optionally, set the notify_merchant query parameter to also send the merchant an invoice update notification. Default is true.

Send invoice reminder

POST /v1/invoicing/invoices/invoice_id/remind

Sends a reminder to the payer that a payment is due for an invoice, by ID.

Cancel sent invoice

POST /v1/invoicing/invoices/invoice_id/cancel

Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and Cc: emails.

Mark invoice as paid

POST /v1/invoicing/invoices/invoice_id/record-payment

Marks an invoice, by ID, as paid.

Mark invoice as refunded

POST /v1/invoicing/invoices/invoice_id/record-refund

Marks an invoice, by ID, as refunded.

Delete external payment

DELETE /v1/invoicing/invoices/invoice_id/payment-records/transaction_id

Deletes an external payment transaction, by ID, from an invoice, by ID.

Delete external refund

DELETE /v1/invoicing/invoices/invoice_id/refund-records/transaction_id

Deletes an external refund transaction, by ID, from an invoice, by ID.

Templates (resource group)

You can create a template for an invoice, which enables you to create invoices with predefined data.

Note: You can also use the Template Settings dashboard to create a template for an invoice.

You can use the /invoicing/templates resource to create, list, show details for, update, and delete templates.

Create template

POST /v1/invoicing/templates

Creates an invoice template. When you create an invoice from a template, the invoice is populated with the predefined data that the source template contains.

Note: Use the Template Settings dashboard instead of the API to create an invoice template.

List templates

GET /v1/invoicing/templates

Lists all merchant-created templates. The list shows the emails, addresses, and phone numbers from the merchant profile.

Show template details

GET /v1/invoicing/templates/template_id

Shows details for a template, by ID.

Update template

PUT /v1/invoicing/templates/template_id

Updates a template, by ID. In the JSON request body, pass a complete template object. The update method does not support partial updates.

Delete template

DELETE /v1/invoicing/templates/template_id

Deletes a template, by ID.

Payment Experience API

Use the Payment Experience API to create seamless payment experience profiles. For information about how to create a PayPal payment with a web experience profile, see Payment Experience web profiles.

Create web experience profile

POST /v1/payment-experience/web-profiles

Creates a web experience profile. In the JSON request body, specify the profile name and details.

Show web experience profile details

GET /v1/payment-experience/web-profiles/profile-id

Shows details for a web experience profile, by ID.

List web experience profiles

GET /v1/payment-experience/web-profiles

Lists all web experience profiles for a merchant or subject.

Update web experience profile

PUT /v1/payment-experience/web-profiles/profile-id

Updates a web experience profile, by ID. In the JSON request body, specify the profile details. If your request omits any profile parameters, any previously set values for those parameters are removed.

Partially update web experience profile

PATCH /v1/payment-experience/web-profiles/profile-id

Partially-updates a web experience profile, by ID. In the JSON request body, specify a patch object, the path of the profile location to update, and, if needed, a new value to complete the operation.

Delete web experience profile

DELETE /v1/payment-experience/web-profiles/profile-id

Deletes a web experience profile, by ID.

Payments API

The payments namespace contains resource collections for payment, sale, refund, authorization, and capture.

Payments (resource group)

PayPal provides various payment-related operations through the /payment resource and related sub-resources. Use payment for direct credit card payments and PayPal account payments. You can also use sub-resources to get payment-related details.

Create a payment

POST /v1/payments/payment

Depending on the payment_method and the funding_instrument, you can use the payment resource for direct credit card payments, stored credit card payments, or PayPal account payments.

Execute approved PayPal payment

POST /v1/payments/payment/payment_id/execute

Executes a PayPal payment that the payer has approved. Optionally pass in one or more transactions to update transaction information when you execute the payment.

Show payment details

GET /v1/payments/payment/payment_id

Shows details for a payment, by ID, that is yet completed. For example, a payment that was created, approved, or failed.

Update payment

PATCH /v1/payments/payment/payment_id

Partially updates a payment, by ID. You cannot update a payment after the payment is executed.

List payments

GET /v1/payments/payment

Lists payments that were created by the create payment call and are in any state. The list shows the payments that are made to the merchant who makes the call.

Sale transactions (resource group)

To show details for completed payments (sale transactions) created by a payment request or to refund a direct sale transaction, PayPal provides the /sale resource and related sub-resources. You can find the sale transactions in the payment resource within related_resources.

Show sale details

GET /v1/payments/sale/sale_id

Shows details for a sale transaction, by ID.

Refund sale

POST /v1/payments/sale/sale_id/refund

Refunds a completed payment. Provide the sale_id in the URI and an empty JSON payload for a full refund. For partial refunds, you can include an amount.

Refunds (resource group)

Use the /refund resource to show details for a refund on direct and captured payments.

For more information about refunding payments, see refund a sale and refund a completed payment (sale).

Show refund details

GET /v1/payments/refund/refund_id

Shows details for a refund, by ID. To list your refunds, list payments. Refunds in the list have a sale object with a state of refunded and a refund object with a state of completed.

Authorizations (resource group)

Use the /authorization resource and related sub-resources to act on a previously created authorization. You can show details for, capture, void, and reauthorize an authorization.

Shows authorization details

GET /v1/payments/authorization/authorization_id

Shows details for an authorization, by ID.

Capture an authorization

POST /v1/payments/authorization/authorization_id/capture

Use this resource to capture and process a previously created authorization. To use this resource, the original payment call must have the intent set to authorize.

Void an authorization

POST /v1/payments/authorization/authorization_id/void

Voids a previously authorized payment.

Reauthorize payment

POST /v1/payments/authorization/authorization_id/reauthorize

Reauthorizes a PayPal account payment. We recommend that you reauthorize a payment after the initial three-day honor period to ensure that funds are still available.

Captures (resource group)

The /capture resource and sub-resources enable you to show details for and refund captured payments.

Show captured payment details

GET /v1/payments/capture/capture_id

Shows details for a captured payment, by ID.

Refund captured payment

POST /v1/payments/capture/capture_id/refund

Refunds a captured payment, by ID. Include an amount object in the JSON request body.

Orders (resource group)

Use the /orders resource to take action on a payment with the intent of order. Actions include authorize, capture, void, and show details for an order. Also see create and process an order for further information about using the /payment resource to create and execute an order.

It is not possible to refund an order directly. Instead, you must refund a completed payment of the order. Refer to the following how-to guides for integration information:

For operation information as well as request and response details, see Refund a captured payment.

Show order details

GET /v1/payments/orders/order_id

Shows details for an order, by ID.

Authorize order

POST /v1/payments/orders/order_id/authorize

Authorizes an order, by ID.

Capture order

POST /v1/payments/orders/order_id/capture

Captures a payment on an order. To use this call, an original payment call must specify an intent of order.

Void an order

POST /v1/payments/orders/order_id/do-void

Voids an order, by ID.

Payouts API

Use the Payouts API to make PayPal payments to multiple PayPal accounts in a single API call. You can specify the recipients by using their PayPal email addresses, phone numbers, or encrypted PayPal account numbers.

The Payouts API is a fast, convenient way to send commissions, rebates, rewards, and general disbursements. Payouts appear as Mass Payments in the sender's PayPal account and are provided with the Mass Payment reports.

Important: To use the Payouts API, request access through My Account. Alternatively, contact your account manager or PayPal Customer Support. You must have a PayPal business account.

The Payouts API uses the ISO 8601 date and time format.

For more information about the Payouts API, see Payouts.

Note: (Deprecation notice)

Synchronous mode will soon be deprecated and is no longer available for new integrations but continues to be supported for existing integrations. A synchronous mode payout immediately returns the results of the payout.

Payouts (resource group)

Use the /payouts resource to create payouts and show batch payout details.

Create payouts

POST /v1/payments/payouts

Make payouts to one or more PayPal accounts.

Show batch payout details

GET /v1/payments/payouts/payout_batch_id

Periodically shows the latest status of a batch payout along with the transaction status and other data for individual items.

Payout item (resource group)

Use the /payouts-item resource to show details for a payout item an cancel an unclaimed payout item.

Note: (Deprecation notice)

Synchronous mode will soon be deprecated and is no longer available for new integrations but continues to be supported for existing integrations. A synchronous mode payout immediately returns the results of the payout.

Show payout item details

GET /v1/payments/payouts-item/payout_item_id

Shows the details for a payout item. Review the current status of a previously unclaimed, or pending, payout item.

Cancel unclaimed payout item

POST /v1/payments/payouts-item/payout_item_id/cancel

Cancels an unclaimed transaction. If no one claims the unclaimed item within 30 days, the funds are automatically returned to the sender. Cancel the unclaimed item before the automatic 30-day refund.

Vault API

Merchants can use the Vault API to securely store customer credit cards in the PayPal vault rather than on your server. When you use the API to store a customer credit card, the API returns the ID of the vaulted card. To take a payment with the vaulted card, you specify the ID of the vaulted card instead of credit card details. For information, see the Vault overview.

Notes:
  • PayPal does not validate credit card information that you store in the vault.

  • Direct credit card payment and related features are restricted in some countries.

Store credit card

POST /v1/vault/credit-cards

Stores credit card details in the PayPal vault. To use the vaulted card to make a payment, specify the ID of the vaulted card as the credit_card_id in a credit_card_token object. If you include a payer_id when you store the credit card, you must include that ID as the external_customer_id in the credit_card_token object. Also use the ID of the vaulted credit card to show details for, update, or delete the vaulted card.

List vaulted credit cards

GET /v1/vault/credit-cards

Lists vaulted credit cards. To filter the cards in the response, specify one or more optional query parameters.

Show vaulted credit card details

GET /v1/vault/credit-cards/credit_card_id

Shows details for a vaulted credit card, by ID.

Update vaulted credit card

PATCH /v1/vault/credit-cards/credit_card_id

Updates information for a vaulted credit card, by ID. In the JSON request body, specify the values to update.

Delete vaulted credit card

DELETE /v1/vault/credit-cards/credit_card_id

Deletes a vaulted credit card, by ID.

Webhooks API

The PayPal REST APIs use webhooks for event notification. Webhooks are HTTP callbacks that receive notification messages for events.

After you configure a webhook listener for your app, you can create a webhook, which subscribes the webhook listener for your app to events.

The notifications namespace contains resource collections for webhooks.

Webhooks (resource group)

Use the /webhooks resource to create, show details for, list all, update, and delete webhooks.

Create webhook

POST /v1/notifications/webhooks

Subscribes your webhook listener to events. A successful call returns a webhook object, which includes the webhook ID for later use.

Show webhook details

GET /v1/notifications/webhooks/webhook_id

Shows details for a webhook, by ID.

List all webhooks

GET /v1/notifications/webhooks

Lists all webhooks.

Update webhook

PATCH /v1/notifications/webhooks/webhook_id

Updates a webhook, by ID. Supports only the replace operation.

Delete webhook

DELETE /v1/notifications/webhooks/webhook_id

Deletes a webhook, by ID.

Webhook event notifications (resource group)

Use the /webhooks-events resource to show event notification details, list event notifications, and resend the notification for an event.

Show event notification details

GET /v1/notifications/webhooks-events/event_id

Shows details for an event notification, by ID.

List event notifications

GET /v1/notifications/webhooks-events

Lists webhook event notifications. Specify one or more optional query parameters to filter the response.

Resend event notification

POST /v1/notifications/webhooks-events/event_id/resend

Resends an event notification, by event ID.

Webhook events (resource group)

Use the /webhooks-event-types resource to list events to which webhooks can subscribe and the /webhooks/<webhook_id>/event-types resource to list event subscriptions for a webhook.

List available events

GET /v1/notifications/webhooks-event-types

Lists events to which an app can subscribe. For a list of webhook events, see webhook events.

List event subscriptions for a webhook

GET /v1/notifications/webhooks/webhook_id/event-types

Lists the event subscriptions for a webhook, by ID.

Simulate webhook event (resource group)

Use the /simulate-event resource to use a sample payload to simulate a webhook event. The events that this call generates only serve to validate the connection to the listener URL and to show how webhook events look.

Note: You can also use the Webhooks simulator to simulate webhook events.

Simulate webhook event

POST /v1/notifications/simulate-event

Simulates a webhook event. To simulate an event, you specify a sample payload in the request to send mock event data to the URL that you configured to listen for notification messages. The mock events serve to validate the connection to the listener URL and to show how webhook events look.

Verify webhook signature (resource group)

Use the /verify-webhook-signature resource to verify a webhook signature.

Verify webhook signature

POST /v1/notifications/verify-webhook-signature

Verifies a webhook signature.