REST API reference

Billing Agreements API

You use billing plans and billing agreements to create an agreement for a recurring credit card, bank card, or PayPal payment for goods or services.

To create an agreement, you reference an active billing plan from which the agreement inherits information. You also supply customer and payment information and, optionally, can override the referenced plan's merchant preferences and shipping fee and tax information.

For more information, see Billing Plans and Agreements.

Billing agreements (resource group)

Use the /billing-agreements resource to create an agreement, update an agreement, show agreement details, and cancel agreements. You can also set or bill the balance for an agreement. You can re-activate an agreement, suspend an agreement, list agreement transactions, and execute agreements.

Create agreement

POST /v1/payments/billing-agreements

Creates a billing agreement. In the JSON request body, include an agreement object with the name, description, start date, ID of the plan on which to base the agreement, and customer and shipping address information. A successful request returns the HTTP 201 Created status code and a JSON response body that shows billing agreement details.

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. A successful request returns the HTTP 200 OK status code with no JSON response body.

Show agreement details

GET /v1/payments/billing-agreements/agreement_id

Shows details for a billing agreement, by ID. A successful request returns the HTTP 200 OK status code and a JSON response body that shows billing agreement details.

Bill agreement balance

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

Bills the balance for an agreement, by ID. In the JSON request body, include an optional note that describes the reason for the billing action and the agreement amount and currency. A successful request returns the HTTP 204 No Content status code with no JSON response body.

Cancel agreement

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

Cancels a billing agreement, by ID. In the JSON request body, include an agreement_state_descriptor object with an optional note that describes the reason for the cancellation and the agreement amount and currency. A successful request returns the HTTP 204 No Content status code with no JSON response body.

Re-activate agreement

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

Re-activates a suspended billing agreement, by ID. In the JSON request body, include an agreement_state_descriptor object with with a note that describes the reason for the re-activation and the agreement amount and currency. A successful request returns the HTTP 204 No Content status code with no JSON response body.

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, specify the balance currency type and value. A successful request returns the HTTP 204 No Content status code with no JSON response body.

Suspend agreement

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

Suspends a billing agreement, by ID. A successful request returns the HTTP 204 No Content status code with no JSON response body.

List agreement transactions

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

Lists transactions for an agreement, by ID. To filter the transactions that appear in the response, specify the optional start and end date query parameters. A successful request returns the HTTP 200 OK status code and a JSON response body that lists transactions with details.

Execute agreement

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

Executes a billing agreement, by ID, after customer approval. A successful request returns the HTTP 200 OK status code and a JSON response body that shows billing agreement details.

Billing Plans API

You use billing plans and billing agreements to create an agreement for a recurring credit card, bank card, or PayPal payment for goods or services.

A billing plan includes payment definitions and other details. A plan must include at least one regular payment definition and, optionally, a trial payment definition. Each definition determines how often and for how long a customer is charged.

A plan can specify a type, which indicates whether the payment definitions in the plan have a fixed or infinite number of payment cycles. The plan also defines merchant preferences including how much it costs to set up the agreement, the URLs where a customer can approve or can cancel the agreement, and the action if the customer's initial payment fails.

By default, a plan is not active when you create it. To activate it, you update its state to ACTIVE.

For more information, see Billing Plans and Agreements.

Billing Plans (resource group)

Use the /billing-plans resource to create, update, show details for, and list plans.

Create plan

POST /v1/payments/billing-plans

Creates a billing plan. In the JSON request body, include the plan details. A plan must include at least one regular payment definition and, optionally, a trial payment definition. Each payment definition specifies a billing period, which determines how often and for how long the customer is charged. A plan can specify a fixed or infinite number of payment cycles. A payment definition can optionally specify shipping fee and tax amounts.

A successful request returns the HTTP 201 Created status code and a JSON response body that shows plan details. The default state of a new plan is CREATED. Before you can create an agreement from a plan, you must activate the plan by updating its state to ACTIVE.

Update plan

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

Updates 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.

A successful request returns the HTTP 200 OK status code with no JSON response body.

Show plan details

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

Shows details for a billing plan, by ID.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows plan details.

List plans

GET /v1/payments/billing-plans

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

A successful request returns the HTTP 200 OK status code and a JSON response body that lists plans with details.

Customer Disputes API

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

PayPal merchants, partners, and external developers can use the PayPal Customer Disputes API to list disputes, provide evidence, accept claims, show dispute details, and appeal disputes.

Occasionally, something goes wrong with a customer's order. To dispute a charge, a customer can file a case with PayPal or ask his or her bank or credit card company to reverse a charge. A charge reversal is also known as a chargeback. For more information, see Disputes, claims, chargebacks, and bank reversals.

Note: Merchants cannot create disputes but can only respond to customer-created disputes.

When a customer disputes your charge, you can provide evidence to show that the charge is legitimate. To provide new evidence or appeal a dispute, you submit a proof of delivery or proof of refund document or notes, which can include logs.

For details, see Customer Disputes and the Marketplace Disputes Integration Guide.

Disputes (resource group)

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

Use the /customer/disputes/ resource to list all or a filtered set of disputes, provide evidence, accept a claim, show dispute details, and appeal disputes.

List disputes

GET /v1/customer/disputes

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

Provide evidence

POST /v1/customer/disputes/dispute_id/provide-evidence

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

Accept claim

POST /v1/customer/disputes/dispute_id/accept-claim

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

Show dispute details

GET /v1/customer/disputes/dispute_id

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

Appeal dispute

POST /v1/customer/disputes/dispute_id/appeal

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

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.

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)

Use the /invoicing/invoices resource to create, update, and send invoices and invoice reminders. You can also generate invoice QR codes and invoice numbers, search for, list, and show invoice details, and delete draft invoices and cancel sent invoices. You can mark invoices as fully or partially paid, or as refunded and delete an external payment or refund from an invoice.

Create draft 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.

A successful request returns the HTTP 201 Created status code and a JSON response body that shows invoice details.

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.
A successful request returns the HTTP 202 Accepted status code with no JSON response body.

Update invoice

PUT /v1/invoicing/invoices/invoice_id

Fully updates an invoice, by ID. In the JSON request body, include a complete invoice object. This call does not support partial updates.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows invoice details.

Send invoice reminder

POST /v1/invoicing/invoices/invoice_id/remind

Sends a reminder to the payer about an invoice, by ID. In the JSON request body, include a notification object that defines the subject of the reminder and other details.
A successful request returns the HTTP 202 Accepted status code with no JSON response body.

Delete draft invoice

DELETE /v1/invoicing/invoices/invoice_id

Deletes a draft invoice, by ID. Deletes 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.
A successful request returns the HTTP 204 No Content status code with no JSON response body.

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.
A successful request returns the HTTP 204 No Content status code with no JSON response body.

Mark invoice as paid

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

Marks the status of an invoice, by ID, as paid. Include a payment detail object that defines the payment method and other details in the JSON request body.
A successful request returns the HTTP 200 OK status code with no JSON response body.

Mark invoice as refunded

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

Marks the status of an invoice, by ID, as refunded. In the JSON request body, include a payment detail object that defines the payment method and other details.
A successful request returns the HTTP 200 OK status code with no JSON response body.

List merchant invoices

GET /v1/invoicing/invoices

Lists merchant invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.
A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices with details.

Search for invoices

POST /v1/invoicing/search

Lists invoices that match search criteria. In the JSON request body, include a search object that specifies the search criteria.
A successful request returns the HTTP 200 OK status code and a JSON response body that lists the invoices that match the search criteria.

Show invoice details

GET /v1/invoicing/invoices/invoice_id

Shows details for an invoice, by ID.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows invoice details.

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.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows the QR code as a PNG image.

Generate invoice number

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

Generates the next invoice number that is available to the merchant.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows the next invoice number.

Templates (resource group)

You can create a template for an invoice, which enables you to create invoices with predefined data. You can use the /invoicing/templates resource to create, list, show details for, update, and delete templates.

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

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.

Update template

PUT /v1/invoicing/templates/template_id

Updates a template, by ID. In the JSON request body, specify a complete template object. The update method does not support partial updates.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows template details.

List templates

GET /v1/invoicing/templates

Lists all merchant-created templates. The list shows the emails, addresses, and phone numbers from the merchant profile.
A successful request returns the HTTP 200 OK status code and a JSON response body that lists invoices.

Show template details

GET /v1/invoicing/templates/template_id

Shows details for a template, by ID.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows template details.

Delete template

DELETE /v1/invoicing/templates/template_id

Deletes a template, by ID.
A successful request returns the HTTP 204 No Content status code with no JSON response body.

Merchant Onboarding API

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

This API enables a marketplace to add PayPal merchant accounts. It supports the Connected path and Managed path marketplace models.

In the Connected path, you host a button on your website that takes sellers to PayPal to create and configure a PayPal account. The Onboarding API enables you to collect seller data and pass it to the account creation and setup forms, reducing the burden on sellers to during the signup and setup process.

Call these methods for the Connected path:

In the Managed path, you create and configure reference accounts that enable you to make payments to sellers on your platform. The Onboarding API enables you to create reference accounts without involving your sellers.

Call these methods for the Managed path:

Partner referrals (resource group)

Enables you to create and get information about shared customer data.

Create partner referral

POST /v1/customer/partner-referrals

Creates a partner referrals resource that was previously shared by the API caller. The resource contains the client's personal, business, and financial data.
A successful request returns the HTTP 201 Created status code and a JSON response body that contains a HATEOAS link that enables you to get the referral and an action_url that you use to redirect the customer in a browser to complete the signup process. The partner_referral_id token is appended to the URL.

Show partner referral data

GET /v1/customer/partner-referrals/partner_referral_id

Shows details for partner referral data, by ID, that is shared by the API caller.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the specified partner referral data.

Merchant integration (resource group)

Enables you to get information about a merchant-partner integration.

Show account tracking details

GET /v1/customer/partners/partner_id/merchant-integrations

Shows tracking information for the merchant integration that the partner onboarded. Specify the partner ID in the URI.
A successful request returns the HTTP 201 Created status code and a JSON response body that shows tracking information.

Show merchant status

GET /v1/customer/partners/partner_id/merchant-integrations/merchant_id

Shows the status for a merchant, by ID, who was onboarded by a partner, by ID.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows status details.

Merchant accounts (resource group)

Enables you to create, update, and repopulate merchant accounts.

Create merchant account

POST /v1/customer/partners/merchant-accounts

Creates a merchant account.
A successful request returns the HTTP 201 Created status code and a JSON response body that shows merchant account details.

Updates merchant account

PATCH /v1/customer/partners/merchant-accounts/merchant_payer_id

Updates an account for a merchant, by ID.
A successful request returns the HTTP 204 No Content status code with no JSON response body.

Replace merchant account

POST /v1/customer/partners/merchant-accounts/merchant_payer_id

Submits merchant information to re-populate an account for a merchant, by ID.
A successful request returns the HTTP 201 Created status code and a JSON response body that shows merchant account details.

Orders API

Important: PayPal for Marketplaces is a limited-release solution at this time. It is available to select partners for approved use cases. For more information, reach out to your PayPal account manager or contact us.

Use the Orders API to create, view, and pay for orders and to disburse funds based on order approval. For details, see the Orders Integration Guide.

Orders (resource group)

Use the /checkout/orders resource to create, cancel, and show details for orders.

Create order

POST /v1/checkout/orders

Creates an order.
First, to set the transaction context and enable the server to perform risk and compliance analysis of the transaction, call /v1/risk/transaction-contexts to generate a tracking ID. Save and include this ID in the Paypal-Client-Metadata-Id request header in your call to /v1/checkout/orders.
A successful request returns the HTTP 200 OK status code and a JSON response body that shows order details.

Cancel order

DELETE /v1/checkout/orders/order_id

Cancels an order, by ID, and deletes the order resource.

Show order details

GET /v1/checkout/orders/order_id

Shows details for an order, by ID.

Orders payment actions (resource group)

Use the /orders resource with the /pay action to pay for an order.

When you create an order, the response includes an approval URL. Redirect the customer to this URL to approve the order.

Pay for order

POST /v1/checkout/orders/order_id/pay

Pays for an approved order 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.

Web profiles (resource group)

Use the /payment-experience/web-profiles resource to create, show details for, list, update, partially update, and delete web experience 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

Use the Payments REST API to easily and securely accept online and mobile payments. The payments namespace contains resource collections for payments, sales, refunds, authorizations, captures, and orders.

You can enable customers to make PayPal and credit card payments with only a few clicks, depending on the country. You can accept an immediate payment or authorize a payment and capture it later. You can show details for completed payments, refunds, and authorizations. You can make full or partial refunds. You also can void or re-authorize authorizations.

For more information, see the Payments overview.

Payments (resource group)

Use the /payment resource to create a sale, an authorized payment, or an order. A sale is a direct credit card payment, stored credit card payment, or PayPal payment. An authorized payment places funds on hold to be captured later. An order is a purchase that a customer has approved but for which the funds are not placed on hold. You can also use this resource to execute approved PayPal payments and show details for, update, and list payments. For more information, see also Payments.

Create payment

POST /v1/payments/payment

Creates a sale, an authorized payment to be captured later, or an order.

To create a sale, authorization, or order, include the payment details in the JSON request body. Set the intent to sale, authorize, or order. Include payer, transaction details, and, for PayPal payments only, redirect URLs. The combination of the payment_method and funding_instrument determines the type of payment that is created.

For more information, see Payments REST API.

Notes:
  • Some countries restrict direct credit card payment and related features.

  • Authorizations are guaranteed for up to three days, though you can attempt to capture an authorization for up to 29 days. After the three-day honor period authorization expires, you can reauthorize the payment.

Execute approved PayPal payment

POST /v1/payments/payment/payment_id/execute

Executes a PayPal payment that the customer has approved. Optionally update one or more transactions when you execute the payment.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the executed payment.

Important: This call works only after a customer has approved the payment. For more information, learn about PayPal payments.

Show payment details

GET /v1/payments/payment/payment_id

Shows details for a payment, by ID, that has yet to complete. For example, shows details for a payment that was created, approved, or failed.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows payment details.

Update payment

PATCH /v1/payments/payment/payment_id

Partially updates a payment, by ID. Update the amount, shipping address, invoice ID, and custom data. You cannot update a payment after the payment executes.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows payment details.

List payments

GET /v1/payments/payment

Lists payments that were created by the create payment call and that are in any state. The list shows the payments that are made to the merchant who makes the call. To filter the payments that appear in the response, you can specify one or more optional query and pagination parameters. See Filtering and pagination.

A successful request returns the HTTP 200 OK status code and a JSON response body that lists payments with payment details.

Sales (resource group)

A sale is a completed payment. Use the /sale resource to show sale details and refund a sale. For more information, see also Refund payments.

Show sale details

GET /v1/payments/sale/sale_id

Shows details for a sale, by ID. Returns only sales that were created through the REST API.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows sale details.

Refund sale

POST /v1/payments/sale/sale_id/refund

Refunds a sale, by ID. For a full refund, include an empty payload in the JSON request body. For a partial refund, include an amount object in the JSON request body.

A successful request returns the HTTP 201 Created status code and a JSON response body that shows details for the refunded sale.

Refunds (resource group)

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

Show refund details

GET /v1/payments/refund/refund_id

Shows details for a refund, by ID.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows refund details.

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.

Show authorization details

GET /v1/payments/authorization/authorization_id

Shows details for an authorization, by ID.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows authorization details.

Capture authorization

POST /v1/payments/authorization/authorization_id/capture

Captures and processes an authorization, by ID. To use this call, the original payment call must specify an intent of authorize.

A successful request returns the HTTP 201 Created status code and a JSON response body that shows details for the captured authorization.

Void an authorization

POST /v1/payments/authorization/authorization_id/void

Voids, or cancels, an authorization, by ID. You cannot void a fully captured authorization.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the voided authorization.

Re-authorize payment

POST /v1/payments/authorization/authorization_id/reauthorize

Re-authorizes a PayPal account payment, by authorization ID. To ensure that funds are still available, re-authorize a payment after the initial three-day honor period. Supports only the amount request parameter. Re-authorize a payment only once from four to 29 days after three-day honor period for the original authorization expires. If 30 days have passed from the original authorization, you must create a new authorization instead. A re-authorized payment itself has a new three-day honor period. You can re-authorize a transaction once for up to 115% of the originally authorized amount, not to exceed an increase of $75 USD.

A successful request returns the HTTP 201 Created status code and a JSON response body that shows details for the re-authorized authorization.

Captures (resource group)

Use the /capture resource and sub-resources 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.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the captured payment.

Refund captured payment

POST /v1/payments/capture/capture_id/refund

Refunds a captured payment, by ID. In the JSON request body, include an amount object.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the captured payment.

Orders (resource group)

Use the /orders resource to authorize, capture, void, and show details for an order.

Note: You cannot refund an order directly. Instead, you must refund a completed payment for an order. For integration information, see Orders and refund a payment.

For more information, see also Orders.

Show order details

GET /v1/payments/orders/order_id

Shows details for an order, by ID.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the voided authorization.

Authorize order

POST /v1/payments/orders/order_id/authorize

Authorizes an order, by ID. In the JSON request body, include an amount object.

A successful request returns the HTTP 201 Created status code and a JSON response body that shows details for the authorized order.

Capture order

POST /v1/payments/orders/order_id/capture

Captures a payment for an order, by ID. To use this call, the original payment call must specify an order intent. In the JSON request body, include the payment amount and indicate whether this capture is the final capture for the authorization.

A successful request returns the HTTP 201 Created status code and a JSON response body that shows details for the captured order.

Void an order

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

Voids, or cancels, an order, by ID. You cannot void an order if the payment has already been partially or fully captured.

A successful request returns the HTTP 200 OK status code and a JSON response body that shows details for the voided order.

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.

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.

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.

  • Some countries restrict direct credit card payments and related features.

Credit cards (resource group)

Use the /credit-cards resource to store a credit card in the vault, delete, show details for, list, and update vaulted cards.

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 request returns the HTTP 201 Created status code and a JSON response body with a webhook object that 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.