REST API reference feedback

Payments

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

revealhide operation descriptions

Payments

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.

You can authorize payments to be captured later or create an order.

When creating a payment, set the intent (sale, authorize, or order), and specify the actual transactions details like amount, recipients, and items.

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

Execute an approved PayPal payment

POST /v1/payments/payment/payment_id/execute

Use this call to execute (complete) a PayPal payment that has been approved by the payer. You can optionally update transaction information when executing the payment by passing in one or more transactions.

Important: This call only works after a buyer has approved the payment using the provided PayPal approval URL. For more information, learn how to accept a PayPal payment.

Look up a payment resource

GET /v1/payments/payment/payment_id

Use this call to 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

Use this call to 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

Use this call to get a list of payments in any state (created, approved, failed, etc.). The payments returned are the payments made to the merchant making the call.

Sale Transactions

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

Use this call to get details about a sale transaction.

Note: This call returns only the sales that were created via the REST API.

Refund a sale

POST /v1/payments/sale/sale_id/refund

Use this call to 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

Use the /refund resource to look up details of a specific refund on direct and captured payments.

See Refund a sale in the API reference and Refund a completed payment (sale) for more information about refunding payments.

Look up a refund

GET /v1/payments/refund/refund_id

Use this call to 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

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

Use this call to 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

Use this call to void a previously authorized payment.

Note: A fully captured authorization cannot be voided.

Reauthorize a payment

POST /v1/payments/authorization/authorization_id/reauthorize

Use this call to 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.

You can reauthorize a payment only once 4 to 29 days after 3-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 reauthorized payment itself has a new 3-day honor period. You can reauthorize a transaction once for up to 115% of the originally authorized amount, not to exceed an increase of $75 USD.

Note: You can only reauthorize PayPal account payments.

Captures

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

Use this call to get details about a captured payment.

Refund a captured payment

POST /v1/payments/capture/capture_id/refund

Use this call to 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

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

Use this call to authorize an order.

Capture an order

POST /v1/payments/orders/order_id/capture

Use this call to 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

Use this call to void an existing order.

Note: An order cannot be voided if payment has already been partially or fully captured.

Billing Plans

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

revealhide operation descriptions

Create a plan

POST /v1/payments/billing-plans

You can 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.

Note: By default, a created billing plan is in a CREATED state. A user cannot subscribe to the billing plan unless it has been set to the ACTIVE state. Use this call to create a billing plan. The request sample shows the plan being created with a regular billing period.

Update a plan

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

You can 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

Use this call to get details about a specific billing plan.

List plans

GET /v1/payments/billing-plans

Use this call to get a list of all billing plans based on their current state and optional query string parameters.

Billing Agreements

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

revealhide operation descriptions

Create an agreement

POST /v1/payments/billing-agreements

Use this call to 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.

For PayPal payments:

  • After successfully creating the agreement, direct the user to the approval_url on the PayPal site so that the user can approve the agreement.
  • Call the execute link to execute the billing agreement.

Note: Billing agreements for credit card payments execute automatically when created. There is no need for the user to approve the agreement or to execute the agreement.

Execute an agreement

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

Use this call to execute an agreement after the buyer approves it.

Note: This request is only necessary for PayPal payments. Billing agreements for credit card payments execute automatically at the time of creation and so this request is not necessary for credit card payments.

Update an agreement

PATCH /v1/payments/billing-agreements/agreement_id

Use this call to update an agreement.

Retrieve an agreement

GET /v1/payments/billing-agreements/agreement_id

Use this call to retrieve an agreement.

Suspend an agreement

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

Use this call to suspend an agreement.

Reactivate an agreement

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

Use this call to reactivate an agreement.

Cancel an agreement

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

Use this call to cancel an agreement.

Search for transactions

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

Use this call to search for the transactions within a billing agreement.

Set outstanding agreement amounts

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

Use this call to set the outstanding amount of an agreement.

Bill outstanding agreement amounts

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

Use this call to bill the outstanding amount of an agreement.

Payouts

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.

revealhide operation descriptions

Create a Batch or Single Payout

POST /v1/payments/payouts

You can make payouts to multiple PayPal accounts or to a single PayPal account.

By default, a payout API call is asynchronous, which means you retrieve the results of the payout at a later time. See Create a batch payout.

If you are submitting a single payout, you can make a synchronous payout call, which immediately returns the results of the payout. In a synchronous payout call, the response is similar to a batch payout status response. To make a synchronous payout, specify sync_mode=true in the URL: /v1/payments/payouts?sync_mode=true

The asynchronous payout mode (sync_mode=false, which is the default) enables a maximum of 500 individual payouts to be specified in one API call. Exceeding 500 payouts in one call returns an HTTP response message with status code 400 (Bad Request).

PayPal prevents duplicate batches from being processed. If you specify a sender_batch_id that was used in the last 30 days, the batch request is rejected with an error message: Batch with given sender_batch_id already exists. The error response includes a HATEOAS link to the original batch payout with the same sender_batch_id.

Note: Payouts does not currently support BN Codes. In a future release of Payouts, BN Codes optionally can be provided in the PayPal-Partner-Attribution-Id header of the request. For information about the PayPal-Partner-Attribution-Id header, see Authentication & Headers. To learn more or to request a BN Code, contact your Partner Manager or visit the following location: PayPal Partner Portal.

Get the status of a batch payout

GET /v1/payments/payouts/payout_batch_id

This call can be used to periodically to get the latest status of a batch, along with the transaction status and other data for individual items.

This call also returns the payout item IDs for the individual items, e.g. for use when you get the status of an individual payout item.

The following table contains the supported values for the retrieved batch status:

StatusDescription
PENDINGThe batch is waiting to be processed.
PROCESSINGThe batch is being processed.
DENIEDNo batch items will be processed.
SUCCESSThe batch has been successfully processed. Note that some batch items may not have been completely processed, e.g. because they are unclaimed, or because they are on hold, or for another reason.

The following table contains the supported values for the retrieved item transaction status:

StatusDescription
SUCCESSThe item has been successfully processed.
DENIEDThe item has been denied payment.
PENDINGThe item is awaiting payment.
PROCESSINThe item is being processed.
FAILEDProcessing failed for the item.
UNCLAIMEDThe item is unclaimed. If the item is not claimed within 30 days, the funds will be returned to the sender.
RETURNEDThe item is returned. The funds are returned if the recipient hasn’t claimed them in 30 days.
ONHOLDThe item is on hold.
BLOCKEDThe item is blocked.
CANCELLEDIt is not possible for the `CANCELLED` state to occur if the sender is solely using the API to send Payouts. This status is an edge-case if a sender uses both the MassPay web upload and the Payouts API, cancels the web upload, and then uses the API to find the batch/items. In this case, `CANCELLED` status is possible.

Get the status of a payout item

GET /v1/payments/payouts-item/payout_item_id

Use this call to get data about a payout item, including the status, without retrieving an entire batch. You can 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.

For a table with the supported status values, see the transaction status table in the following section: Get the status of a batch payout.

Cancel an unclaimed payout item

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

Use this call to 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

PayPal offers merchants a /vault API to store sensitive details like credit card related details.

You can currently use the /vault API to store credit card details with PayPal instead of storing them on your own server. After storing a credit card, you can then pass the credit card id instead of the related credit card details to complete a payment.

For more information, learn about using the /vault API to store a credit card.

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

revealhide operation descriptions

Store a credit card

POST /v1/vault/credit-cards

Use this call to store credit card details with PayPal. To use the stored card, you can then use the returned id as the credit_card_id within a credit_card_token. We also recommend including an external_customer_id.

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

Delete a stored credit card

DELETE /v1/vault/credit-cards/credit_card_id

Use this call to delete details of a credit card. Simply include the credit card id in the request URI.

Note: Even if you delete a credit card, some limited information about that credit card is provided when you look up a sale.

Look up a stored credit card

GET /v1/vault/credit-cards/credit_card_id

Use this call to look up details of a credit card. Simply include the credit card id in the request URI.

List credit card resources

GET /v1/vault/credit-cards

Use this call to retrieve a list of credit card resources.

Update a stored credit card

PATCH /v1/vault/credit-cards/credit_card_id

Use this call to modify a credit card.

Identity

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.

revealhide operation descriptions

Grant token from authorization code

POST /v1/identity/openidconnect/tokenservice

Use this call to grant a new access token, using the previously obtained authorization code.

Grant token from refresh token

POST /v1/identity/openidconnect/tokenservice

Use this call to grant a new access token, using a refresh token.

Get user information

GET /v1/identity/openidconnect/userinfo

Use this call to retrieve user profile attributes.

Invoicing

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.

revealhide operation descriptions

Invoices

Invoices are objects used 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.

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

Send an Invoice

POST /v1/invoicing/invoices/invoice_id/send

Sends the specified invoice to the payer. An invoice cannot be sent unless it includes an items array.

Note: Once you've sent an invoice, it cannot be re-sent.

Update an invoice

PUT /v1/invoicing/invoices/invoice_id

Makes the specified changes to the specified invoice.

Retrieve an invoice

GET /v1/invoicing/invoices/invoice_id

Returns the specified invoice.

Get invoices of a merchant

GET /v1/invoicing/invoices

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

Search for invoices

POST /v1/invoicing/search

Returns invoices that match the specified 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 of 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.

For invoices that have already been sent, you can cancel the invoice. See Cancel an invoice for instructions.

Once you've deleted a draft invoice, it can no longer be used and cannot be retrieved. However, you can reuse its invoice number.

Retrieve a QR code

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

Specify an invoice ID to get a QR code (image) 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.

Before getting a QR code, you create an invoice. It is recommended that you specify qrinvoice@paypal.com as the recipient email address in the billing_info object. (Use a customer email address only if you want the invoice to be emailed.)

After you create the invoice, you must send it. This step is necessary to move the invoice from a draft state to a payable state. As stated above, if you specify qrinvoice@paypal.com as the recipient email address, the invoice will not be emailed.

Record a payment

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

Use this call to mark an invoice as paid.

Record a refund

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

Use this call to mark an invoice as refunded.

Payment Experience

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.

revealhide operation descriptions

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

Use this call to update an experience profile.

Partially update a web experience profile

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

Use this call to partially update a web experience profile.

Delete a web experience profile

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

Use this call to delete a web experience profile.

Notifications

The notifications namespace contains resource collections for webhooks.

revealhide operation descriptions

Webhooks

  • 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

Use this call to 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

Use this call to list all the webhooks.

Update a webhook

PATCH /v1/notifications/webhooks/webhook_id

Use this call to update a webhook; supports the replace operation only.

Delete a webhook

DELETE /v1/notifications/webhooks/webhook_id

Use this call to delete a webhook.

Retrieve a webhook event

GET /v1/notifications/webhooks-events/event_id

Use this call to retrieve a webhook event.

Search webhook events

GET /v1/notifications/webhooks-events

Use this call to 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

Use this call to 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

Use this call to 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. You can 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.

Note: The mock event data sent by the simulator cannot be manipulated using other API operations such as resending or retrieving a webhook.

scroll to top