REST API reference

Payments API

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

Payments (resource group)

PayPal provides various payment related operations using 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 an approved PayPal payment

POST /v1/payments/payment/payment_id/execute

Execute (complete) a PayPal payment that has been approved by the payer. Optionally update transaction information when executing the payment by passing in one or more transactions.

Look up a payment resource

GET /v1/payments/payment/payment_id

Get details about payments that have not completed, such as payments that are created and approved, or if a payment has failed.

Update a payment resource

PATCH /v1/payments/payment/payment_id

Partially update the payment resource for the given identifier. Please note that it is not possible to use patch after execute has been called.

List payment resources

GET /v1/payments/payment

List payments that were created by the create payment call and are in any state, such as created, approved, and failed. The payments returned are the payments made to the merchant who makes the call.

Sale Transactions (resource group)

To get details about completed payments (sale transaction) 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.

Look up a sale

GET /v1/payments/sale/sale_id

Get details about a sale transaction.

Refund a sale

POST /v1/payments/sale/sale_id/refund

Refund 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).

Look up a refund

GET /v1/payments/refund/refund_id

Get details about a specific refund. To get a list of your refunds, you can first get a list of payments. Within the list, you can see the state of the sale object as refunded and a refund object with the state of completed.

Authorizations (resource group)

Use the /authorization resource and related sub-resources to act on a previously created authorization. Options include retrieving, capturing, voiding, and reauthorizing authorizations.

Look up an authorization

GET /v1/payments/authorization/authorization_id

Get details about authorizations.

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

Void a previously authorized payment.

Reauthorize a payment

POST /v1/payments/authorization/authorization_id/reauthorize

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

Captures (resource group)

The /capture resource and sub-resources allow you to look up and refund captured payments.

Look up a captured payment

GET /v1/payments/capture/capture_id

Get details about a captured payment.

Refund a captured payment

POST /v1/payments/capture/capture_id/refund

Refund a captured payment. Provide the captureId in the URI and an amount object. For partial refunds, you can include a lower amount object.

Orders (resource group)

Use the /orders resource to take action on a payment with the intent of order. Actions include authorize, capture, void, and look up orders. 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.

Retrieve an order

GET /v1/payments/orders/order_id

Specify an order_id to get details about an order.

Authorize an order

POST /v1/payments/orders/order_id/authorize

Capture an order

POST /v1/payments/orders/order_id/capture

Capture 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

Void an existing order.

Billing Plans API

PayPal offers merchants a /billing-plans resource for providing billing plans to users for recurring payments.

Create a plan

POST /v1/payments/billing-plans

Create an empty billing plan and add a trial period and/or regular billing. Alternatively, you can create a fully loaded plan that includes both a trial period and regular billing.

Update a plan

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

Update the information for an existing billing plan. The state of a plan must be active before a billing agreement is created.

Retrieve a plan

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

Get details about a specific billing plan.

List plans

GET /v1/payments/billing-plans

Get a list of all billing plans based on their current state and optional query string parameters.

Billing Agreements API

After the billing plan is created, the /billing-agreements resource provides billing agreements so that users can agree to be billed for the plans.

Create an agreement

POST /v1/payments/billing-agreements

Create a billing agreement for the buyer. The response for this call includes these HATEOAS links: an approval_url link and an execute link. Each returned link includes the token for the agreement.

Execute an agreement

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

Execute an agreement after the buyer approves it.

Update an agreement

PATCH /v1/payments/billing-agreements/agreement_id

Retrieve an agreement

GET /v1/payments/billing-agreements/agreement_id

Suspend an agreement

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

Reactivate an agreement

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

Cancel an agreement

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

Search for transactions

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

Search for the transactions within a billing agreement.

Set outstanding agreement amounts

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

Set the outstanding amount of an agreement.

Bill outstanding agreement amounts

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

Bill the outstanding amount of an agreement.

Payouts API

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

The Payout APIs are 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 Payouts, you must request access through your account page. Alternatively, contact your Account Manager or PayPal Customer Support. You must have a PayPal business account.

As in the case of other REST APIs, the Payouts APIs use ISO 8601 as the date format.

Create batch or single payout

POST /v1/payments/payouts

Make payouts to multiple PayPal accounts or to a single PayPal account.

Get the status of a batch payout

GET /v1/payments/payouts/payout_batch_id

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

Get the status of a payout item

GET /v1/payments/payouts-item/payout_item_id

Get data about a payout item, including the status, without retrieving an entire batch. Get the status of an individual payout item in a batch in order to review the current status of a previously-unclaimed, or pending, payout item.

Cancel an unclaimed payout item

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

Cancel an existing, unclaimed transaction. If an unclaimed item is not claimed within 30 days, the funds will be automatically returned to the sender. This call can be used to cancel the unclaimed item prior to the automatic 30-day return.

Vault API

Merchants can use the Vault API to store sensitive details like credit card-related details with PayPal instead of on their own server.

After you store a credit card, you can pass the credit card ID instead of credit card details to complete a payment.

For information, see store a credit card.

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

Store a credit card

POST /v1/vault/credit-cards

Stores credit card details with PayPal.

Delete a stored credit card

DELETE /v1/vault/credit-cards/credit_card_id

Deletes details of a stored credit card. Include the credit card ID in the request URI.

Shows stored credit card details

GET /v1/vault/credit-cards/credit_card_id

Shows details for a stored credit card. Include the credit card id in the request URI.

List stored credit cards

GET /v1/vault/credit-cards

Lists stored credit cards.

Update stored credit card

PATCH /v1/vault/credit-cards/credit_card_id

Updates a stored credit card, by ID.

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 service to create, send, and manage invoices. Also use the Invoicing service to track payments.

When you send an invoice, PayPal emails the specified customer with a link to the invoice on PayPal's website.

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

Invoices (resource group)

Invoices are objects that you use to track payments.

Create an invoice

POST /v1/invoicing/invoices

Creates an invoice in a draft state. After you create an invoice that includes an items array, you can send the invoice.

Send an invoice

POST /v1/invoicing/invoices/invoice_id/send

Sends an invoice, by ID, to the payer. To send an invoice, you must include an items array.

Update an invoice

PUT /v1/invoicing/invoices/invoice_id

Updates an invoice, by ID.

Show invoice details

GET /v1/invoicing/invoices/invoice_id

Shows details for an invoice, by ID.

List merchant invoices

GET /v1/invoicing/invoices

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

Generate next invoice number

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

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

Search for invoices

POST /v1/invoicing/search

Returns invoices that match the specified search criteria.

Send an invoice reminder

POST /v1/invoicing/invoices/invoice_id/remind

Sends a reminder that a payment is due for an existing invoice.

Cancel an invoice

POST /v1/invoicing/invoices/invoice_id/cancel

Cancels an invoice and, optionally, notifies the payer about the cancellation.

Delete an invoice

DELETE /v1/invoicing/invoices/invoice_id

Deletes a draft invoice. Note that this call works for invoices in the draft state only.

Get a QR code

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

Gets a QR code for an invoice, by ID. The QR code is a PNG image in base-64 encoded format that corresponds to the invoice ID. A QR code for an invoice can be added to a paper or PDF invoice. When a customer uses their mobile device to scan the QR code, the customer is redirected to the PayPal mobile payment flow, where they can pay online with PayPal or a credit card.

Record a payment

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

Records a payment and marks an invoice as paid.

Record a refund

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

Records a refund and marks an invoice as refunded.

Templates (resource group)

Templates are objects that store customized invoice details. You can use templates to quickly create invoices that are populated with predefined data. To create templates, go to Template Settings.

Show template details

GET /v1/invoicing/templates/template_id

Shows details for a template, by ID.

List templates

GET /v1/invoicing/templates

Lists all templates that the user created. Includes the user's emails, addresses, and phone numbers from the user profile.

Payment Experience API

Use the /web-profiles resource to create seamless payment experience profiles. See the payment experience overview for further information about using the /payment resource to create the PayPal payment and pass the experience_profile_id.

Create a web experience profile

POST /v1/payment-experience/web-profiles

Create a web experience profile

Retrieve a web experience profile

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

Retrieve the details of a particular web experience profile by passing the ID of the profile to the request URI.

List web experience profiles

GET /v1/payment-experience/web-profiles

Get a list of all profiles that exist for a given merchant (or subject).

Update a web experience profile

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

Update an experience profile.

Partially update a web experience profile

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

Delete a web experience profile

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

Notifications API

The notifications namespace contains resource collections for webhooks.

Webhooks (resource group)

  • Use /webhooks-event-types for listing webhook event types.
  • Use /webhooks for creating, listing, updating, and deleting webhooks.
  • Use /webhooks-events for searching and resending webhook events.

Create a webhook

POST /v1/notifications/webhooks

Create a webhook. The maximum number of webhooks you can register is 10.

Get a webhook

GET /v1/notifications/webhooks/webhook_id

Retrieve a webhook by using the webhook_id as an identifier.

List all webhooks

GET /v1/notifications/webhooks

List all the webhooks.

Update a webhook

PATCH /v1/notifications/webhooks/webhook_id

Update a webhook; supports the replace operation only.

Delete a webhook

DELETE /v1/notifications/webhooks/webhook_id

Retrieve a webhook event

GET /v1/notifications/webhooks-events/event_id

Search webhook events

GET /v1/notifications/webhooks-events

Search for all webhook events.

Resend a webhook event

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

Specify a received webhook event-id to resend the event notification.

Get a reference list of webhook event types

GET /v1/notifications/webhooks-event-types

Retrieve the list of event types that are available to any webhook for subscription. For further information about supported event types, refer to the webhooks overview.

List subscribed webhook event types

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

Retrieve the list of events types that are subscribed to a webhook.

Simulate a webhook event

POST /v1/notifications/simulate-event

Simulate a webhook event using a sample payload. Also use the Webhooks Simulator interface to send static mock event data to the URLs that you have configured to accept webhooks. For more information about simulation capabilities, see the webhooks overview.