REST API reference
Billing agreements (resource group)
/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.
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.
Updates details of a billing agreement, by ID. Details include the description, shipping address, start date, and so on.
Shows details for a billing agreement, by ID.
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.
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.
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.
Sets the balance for an agreement, by ID. In the JSON request body, specify the balance currency type and value.
Suspends a billing agreement, by ID.
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.
Executes a billing agreement, by ID, after customer approval.
Billing Plans (resource group)
/billing-plans resource to create, update, show details for, and list 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. The default state of a new plan is
CREATED. You must activate the plan by updating the plan
ACTIVE before you can create an agreement from the plan.
Replaces 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.
Shows details for a billing plan, by ID.
Lists billing plans. To filter the plans that appear in the response, specify one or more optional query and pagination parameters.
Invoices (resource group)
/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.
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 merchant invoices. To filter the invoices that appear in the response, you can specify one or more optional query parameters.
Lists invoices that match search criteria. In the JSON request body, include a
search object that specifies the search criteria.
Shows details for an invoice, by ID.
Fully updates an invoice, by ID. In the JSON request body, include a complete
invoice object. This call does not support partial updates.
Generates the next invoice number that is available to the merchant.
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.
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.
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.
Cancels a sent invoice, by ID, and, optionally, sends a notification about the cancellation to the payer, merchant, and CC: emails.
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.
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.
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.
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, specify a complete
template object. The update method does not support partial updates.
Deletes a template, by ID.
Web profiles (resource group)
/payment-experience/web-profiles resource to create, show details for, list, update, partially update, and delete web experience profiles.
Creates a web experience profile. In the JSON request body, specify the profile name and details.
Shows details for a web experience profile, by ID.
Lists all web experience profiles for a merchant or subject.
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-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.
Deletes a web experience profile, by ID.
Payments (resource group)
/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.
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
order. Include payer, transaction details, and, for PayPal payments only, redirect URLs. The combination of the
funding_instrument determines the type of payment that is created.
For more information, see Payments REST API.
Executes a PayPal payment that the customer has approved. Optionally update one or more transactions when you execute the payment.
Important: This call works only after a customer has approved the payment. For more information, learn about PayPal payments.
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.
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.
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.
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.
Shows details for a sale, by ID. Returns only sales that were created through the REST API.
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.
Refunds (resource group)
/refund resource to show details for a refund on direct and captured payments.
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.
Captures and processes an authorization, by ID. To use this call, the original payment call must specify an intent of
Voids, or cancels, an authorization, by ID. You cannot void a fully captured authorization.
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.
Captures (resource group)
/capture resource and sub-resources to show details for and refund captured payments.
Orders (resource group)
Shows details for an order, by ID.
Authorizes an order, by ID. In the JSON request body, include an
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.
Voids, or cancels, an order, by ID. You cannot void an order if the payment has already been partially or fully captured.
Payouts (resource group)
/payouts resource to create payouts and show batch payout details.
Payout item (resource group)
/payouts-item resource to show details for a payout item an cancel an unclaimed payout item.
Note: (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.
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.
Credit cards (resource group)
/credit-cards resource to store a credit card in the vault, delete, show details for, list, and update vaulted 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.
Lists vaulted credit cards. To filter the cards in the response, specify one or more optional query parameters.
Shows details for a vaulted credit card, by ID.
Updates information for a vaulted credit card, by ID. In the JSON request body, specify the values to update.
Deletes a vaulted 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. 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.
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)
/verify-webhook-signature resource to verify a webhook signature.