REST API reference
Creates 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.
Executes an agreement after the buyer approves it.
Updates an agreement, by ID.
Shows details for an agreement, by ID.
Suspends an agreement, by ID.
Reactivates an agreement, by ID.
Cancels an agreement, by ID.
Lists transactions for a billing agreement.
Sets the outstanding amount of an agreement, by ID.
Bills the outstanding amount of an agreement, by ID.
Billing Plans (resource group)
Creates a billing plan. Specify the plan details in the JSON request body. 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, the payment definition type must be
REGULAR. If you include two payment definitions in the request, one payment definition type must be
TRIAL and the other payment definition type must be
REGULAR. A payment definition can contain a list of charge models for adding shipping and tax information. However, charge models are not required when you create a billing plan.
- 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
Replaces fields in a billing plan. Specify the billing plan ID in the URI and include a patch object in the JSON request body that specifies the operation to perform, one or more fields to update, and a new value for each updated field.
Shows details for a billing plan, by ID.
Lists billing plans. To filter the billing plans that are returned in the response, specify one or more optional query and pagination parameters.
Grant a new access token, using a refresh token.
Invoices (resource group)
/invoicing/invoices resource to create, generate a QR code for, list, search for, show details for, update, send, and send a reminder for invoices.
You can also generate an invoice number, delete draft invoices, and cancel sent invoices.
To manage payments, you can mark an invoice as partially or fully paid or refunded and delete an external payment or an external refund from an invoice.
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
Note: The merchant specified in an invoice must have a PayPal account in good standing.
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:
- Create an invoice. Specify
firstname.lastname@example.org the recipient email address in the
billing_infoobject. Use a customer email address only if you want to email the invoice.
- Send an invoice to move the invoice from a draft to payable state. If you specify
email@example.com the recipient email address, the invoice is not emailed.
Lists invoices that belong to the merchant who makes the call.
Lists invoices that match search criteria.
Shows details for an invoice, by ID.
Updates an invoice, by ID.
Generates the next invoice number that is available to the user.
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.
Sends an invoice, by ID, to a customer.
Note: After you send an invoice, you cannot resend it.
Optionally, set the
notify_merchantquery parameter to also send the merchant an invoice update notification. Default is
Sends a reminder to the payer that a payment is due for an invoice, by ID.
Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and Cc: emails.
Marks an invoice, by ID, as paid.
Marks an invoice, by ID, as refunded.
Deletes an external payment transaction, by ID, from an invoice, by ID.
Deletes an external refund transaction, by ID, from an invoice, by ID.
Templates (resource group)
Note: You can also use the Template Settings dashboard to create a template for an invoice.
Lists all merchant-created templates. The list shows the emails, addresses, and phone numbers from the merchant profile.
Shows details for a template, by ID.
Updates a template, by ID. In the JSON request body, pass a complete
template object. The update method does not support partial updates.
Deletes a template, by ID.
Limits Resolutions (resource group)
Lists the identity verification tasks that a user must complete to verify his or her identity so that PayPal can remove account limitations. The list is based on the security context details that the API gets from security headers. The response includes HATEOAS links that enable you to get more details or submit the required evidence for a task.
Based on the security context details, shows details for an identity verification task, by ID.
Uploads and verifies an identity document. The call accepts the Multipart/Related content-type. In the JSON request body, include both the binary document and any metadata. Before the Limits Resolutions API uploads the file, it runs a malware scan to ensure that the file is not malware.
Shows task details, such as notes, to enable you to further evaluate the task. Also, lists tasks for an intent, such as a name change. Specify either a task ID or case ID in the JSON request body.
Note: Some tasks, such as
text_note, do not require that you upload any files.
Web profiles (resource group)
/web-profiles resource to create, show details for, list all, update, partially update, and delete web experience profiles.
Creates a web experience profile.
Shows details for a web experience profile, by ID.
Lists web experience profiles for a merchant.
Updates a web experience profile, by ID.
Partially updates a web experience profile, by ID.
Deletes a web experience profile, by ID.
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.
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.
Shows details for a payment, by ID, that is yet completed. For example, a payment that was created, approved, or failed.
Partially updates a payment, by ID. You cannot update a payment after the payment is executed.
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
Shows details for a sale transaction, by ID.
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)
Authorizations (resource group)
/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 details for an authorization, by ID.
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
Voids a previously authorized payment.
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)
/capture resource and sub-resources enable you to show details for and refund captured payments.
Shows details for a captured payment, by ID.
Refunds a captured payment, by ID. Include an
amount object in the JSON request body.
Orders (resource group)
/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.
Shows details for an order, by ID.
Authorizes an order, by ID.
Captures a payment on an order. To use this call, an original payment call must specify an
Voids an order, by ID.
Make payouts to one or more PayPal accounts.
Periodically shows the latest status of a batch payout along with the transaction status and other data for individual items.
Payout item (resource group)
/payouts-item resource to show details for a payout item an cancel an unclaimed payout item.
Shows the details for a payout item. Review the current status of a previously unclaimed, or pending, payout item.
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.
Stores credit card details with PayPal. To use the stored card, specify the returned ID as the
credit_card_id in a credit_card_token. Also, include an
Deletes details of a stored credit card. Include the credit card ID in the request URI.
Shows details for a credit card, by ID.
Lists stored credit cards.
Updates a stored credit card, by ID.
Webhooks (resource group)
/webhooks resource to create, show details for, list all, update, and delete webhooks.
Shows details for a webhook, by ID.
Lists all webhooks.
Updates a webhook, by ID. Supports only the
Deletes a webhook, by ID.
Webhook event notifications (resource group)
/webhooks-events resource to show event notification details, list event notifications, and resend the notification for an event.
Shows details for an event notification, by ID.
Lists webhook event notifications. Specify one or more optional query parameters to filter the response.
Resends an event notification, by event ID.
Webhook events (resource group)
/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.
Lists the event subscriptions for a webhook, by ID.
Simulate webhook event (resource group)
/simulate-event resource to use a sample payload to simulate a webhook event.
Simulates a webhook event by using a sample payload. Also use the Webhooks simulator to send mock event data to the URL that you configured to listen for notification messages. For more information about simulation, see Webhooks simulator.
Verify webhook signature (resource group)
/verify-webhook-signature resource to verify a webhook signature.