REST API reference
Billing Agreements API
After you create and activate a billing plan, you can use the /billing-agreements resource to create billing agreements. A buyer must approve an agreement before you can execute it. For more information, see Billing agreements.
Create agreement
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.
Execute agreement
payment_token/Executes an agreement after the buyer approves it.
Show agreement details
agreement_idShows details for an agreement, by ID.
Suspend agreement
agreement_id/Suspends an agreement, by ID.
Reactivate agreement
agreement_id/Reactivates an agreement, by ID.
Cancel agreement
agreement_id/Cancels an agreement, by ID.
List transactions for billing agreement
agreement_id/Lists transactions for a billing agreement.
Set outstanding agreement amounts
agreement_id/Sets the outstanding amount of an agreement, by ID.
Bill outstanding agreement amounts
agreement_id/Bills the outstanding amount of an agreement, by ID.
Billing Plans API
To create a billing agreement, you must use the Billing Plans API to create and activate a billing plan. You do this one time. A billing plan defines the number of payments, the frequency of payments, and other payment details. After you update the state of a plan to ACTIVE to activate the plan, you can create a billing agreement that you base off that plan. You use a billing agreement to create subscriptions for customers. A subscription is a recurring payment for a customer.
Billing Plans (resource group)
Use the /billing-plans resource to:
Create plan
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.
Notes:
- A billing plan supports a maximum of two payment definitions.
- By default, the state of a new billing plan is
CREATED. Before you can create a billing agreement from a plan, you must activate the plan. To activate a plan, update the plan state toACTIVE.
Update plan
plan-idReplaces 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.
List plans
Lists billing plans. To filter the billing plans that are returned in the response, specify one or more optional query and pagination parameters.
Identity API
Log In with PayPal (formerly PayPal Access) is a commerce identity solution that enables your customers to sign in to your web site quickly and securely using their PayPal login credentials. Log In with PayPal utilizes the latest security standards, and you don't have to worry about storing user data on your system.
For more information, learn about Log In with PayPal.
Grant token from authorization code
Grant an access token from a previously obtained authorization code.
Grant token from refresh token
Grant a new access token, using a refresh token.
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, 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.
Create 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 items array.
Note: The merchant specified in an invoice must have a PayPal account in good standing.
Generate QR code
invoice_id/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
[email protected]as the recipient email address in thebilling_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 protected]as the recipient email address, the invoice is not emailed.
List merchant invoices
Lists invoices that belong to the merchant who makes the call.
Generate invoice number
Generates the next invoice number that is available to the user.
Delete draft invoice
invoice_idDeletes a draft invoice, by ID. Note that this call works for invoices in the draft state only. For invoices that have already been sent, you can cancel the invoice. After you delete a draft invoice, you can no longer use it or show its details. However, you can reuse its invoice number.
Send invoice
invoice_id/Sends an invoice, by ID, to a customer.
Note: After you send an invoice, you cannot resend it.
Optionally, set the
notify_merchant query parameter to also send the merchant an invoice update notification. Default is true.
Send invoice reminder
invoice_id/Sends a reminder to the payer that a payment is due for an invoice, by ID.
Cancel sent invoice
invoice_id/Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and Cc: emails.
Mark invoice as paid
invoice_id/Marks an invoice, by ID, as paid.
Mark invoice as refunded
invoice_id/Marks an invoice, by ID, as refunded.
Delete external payment
invoice_id/transaction_idDeletes an external payment transaction, by ID, from an invoice, by ID.
Delete external refund
invoice_id/transaction_idDeletes an external refund transaction, by ID, from an invoice, by ID.
Templates (resource group)
You can create a template for an invoice, which enables you to create invoices with predefined data.
Note: You can also use the Template Settings dashboard to create a template for an invoice.
You can use the /invoicing/templates resource to create, list, show details for, update, and delete templates.
Create template
Creates an invoice template. When you create an invoice from a template, the invoice is populated with the predefined data that the source template contains.
Note: Use the Template Settings dashboard instead of the API to create an invoice template.
List templates
Lists all merchant-created templates. The list shows the emails, addresses, and phone numbers from the merchant profile.
Update template
template_idUpdates a template, by ID. In the JSON request body, pass a complete template object. The update method does not support partial updates.
Limits Resolutions API
Use the Limits Resolutions API to list the tasks that a user must complete to verify his or her identity so that PayPal can remove account limitations.
Also, use this API to show details for a task by ID, upload and verify identity documents, and evaluate a task based on data provided for the task.
Certain factors, such as risk or compliance regulatory checks, can limit a user account or privileges. For example, a user might be restricted to sending only $500 USD or less, pending identity verification.
To list all tasks that a user must complete to verify his or her identity, call GET v1/identity/limits-resolutions/.
To show details for a task, call GET v1/identity/limits-resolutions/<task_id>, where task_id is the ID of the task for which you want to show details. The response shows task information, including which document is required and the current state of the task. If the required document is an identity document and document verification is required, the call returns the verification results.
Identity verification methods include:
-
Data verification. Clients must supply information such as name, address, date of birth, and, optionally, social security number information. The API checks the regulatory databases and vendors to verify the information.
-
Document verification. The client must supply profile information such as name, address, and date of birth information. The client must also supply a document that contains the information that matches the profile information. The API checks the authenticity of the document and matches the profile data to the data that is extracted from the document. If the data matches, the verification succeeds. Otherwise, the verification fails.
Limits Resolutions (resource group)
Use the /limits-resolutions resource to list tasks, show details for a task, evaluate a task, and upload and verify a document.
List identity verification tasks
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.
Show task details
task_idBased on the security context details, shows details for an identity verification task, by ID.
Upload and verify document
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.
Evaluate task
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.
Payment Experience API
Use the /web-profiles resource to create seamless payment experience profiles. For information about how to create a PayPal payment with a web experience profile, see the Payment Experience overview.
Web profiles (resource group)
Use the /web-profiles resource to create, show details for, list all, update, partially update, and delete web experience profiles.
Create web experience profile
Creates a web experience profile.
Show web experience profile details
profile-idShows details for a web experience profile, by ID.
List web experience profiles
Lists web experience profiles for a merchant.
Update web experience profile
profile-idUpdates a web experience profile, by ID.
Partially update web experience profile
profile-idPartially updates a web experience profile, by ID.
Delete web experience profile
profile-idDeletes a web experience profile, by ID.
Payments API
The payments namespace contains resource collections for payment, sale, refund, authorization, and capture.
Payments (resource group)
PayPal provides various payment-related operations through the /payment resource and related sub-resources. Use payment for direct credit card payments and PayPal account payments. You can also use sub-resources to get payment-related details.
Create a payment
Depending on the payment_method and the funding_instrument, you can use the payment resource for direct credit card payments, stored credit card payments, or PayPal account payments.
Execute approved PayPal payment
payment_id/Executes a PayPal payment that the payer has approved. Optionally pass in one or more transactions to update transaction information when you execute the payment.
Show payment details
payment_idShows details for a payment, by ID, that is yet completed. For example, a payment that was created, approved, or failed.
Update payment
payment_idPartially updates a payment, by ID. You cannot update a payment after the payment is executed.
List payments
Lists payments that were created by the create payment call and are in any state. The list shows the payments that are made to the merchant who makes the call.
Sale transactions (resource group)
To show details for completed payments (sale transactions) created by a payment request or to refund a direct sale transaction, PayPal provides the /sale resource and related sub-resources. You can find the sale transactions in the payment resource within related_resources.
Refund sale
sale_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)
Use the /refund resource to show details for a refund on direct and captured payments.
For more information about refunding payments, see refund a sale and refund a completed payment (sale).
Show refund details
refund_idShows details for a refund, by ID.
To list your refunds, list payments. Refunds in the list have a sale object with a state of refunded and a refund object with a state of completed.
Authorizations (resource group)
Use the /authorization resource and related sub-resources to act on a previously created authorization. You can show details for, capture, void, and reauthorize an authorization.
Shows authorization details
authorization_idShows details for an authorization, by ID.
Capture an authorization
authorization_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 authorize.
Void an authorization
authorization_id/Voids a previously authorized payment.
Reauthorize payment
authorization_id/Reauthorizes a PayPal account payment. We recommend that you reauthorize a payment after the initial three-day honor period to ensure that funds are still available.
Captures (resource group)
The /capture resource and sub-resources enable you to show details for and refund captured payments.
Show captured payment details
capture_idShows details for a captured payment, by ID.
Refund captured payment
capture_id/Refunds a captured payment, by ID. Include an amount object in the JSON request body.
Orders (resource group)
Use the /orders resource to take action on a payment with the intent of order. Actions include authorize, capture, void, and show details for an order. Also see create and process an order for further information about using the /payment resource to create and execute an order.
It is not possible to refund an order directly. Instead, you must refund a completed payment of the order. Refer to the following how-to guides for integration information:
For operation information as well as request and response details, see Refund a captured payment.
Capture order
order_id/Captures a payment on an order. To use this call, an original payment call must specify an intent of 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.
For more information about the Payouts API, see Payouts.
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.
Note: Before you can use the Payouts API, learn how to make your first call.
Payouts (resource group)
Use the /payouts resource to create payouts and show batch payout details.
Show batch payout details
payout_batch_idPeriodically 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.
Show payout item details
payout_item_idShows the details for a payout item. Review the current status of a previously unclaimed, or pending, payout item.
Cancel unclaimed payout item
payout_item_id/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 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
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 external_customer_id.
Delete a stored credit card
credit_card_idDeletes details of a stored credit card. Include the credit card ID in the request URI.
Show stored credit card details
credit_card_idShows details for a credit card, by ID.
Update stored credit card
credit_card_idUpdates a stored 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
Subscribes your webhook listener to events. A successful call returns a webhook object, which includes the webhook ID for later use.
Update webhook
webhook_idUpdates a webhook, by ID. Supports only the replace operation.
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
event_idShows details for an event notification, by ID.
List event notifications
Lists webhook event notifications. Specify one or more optional query parameters to filter the response.
Resend event notification
event_id/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
Lists events to which an app can subscribe. For a list of webhook events, see webhook events.
List event subscriptions for a webhook
webhook_id/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.
Simulate 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)
Use the /verify-webhook-signature resource to verify a webhook signature.
Verify webhook signature
Verifies a webhook signature.