REST API reference

Creates a billing agreement. In the JSON request body, pass an agreement object with the name, description, start date, ID of the billing plan on which to base the agreement, payer, and shipping address.

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 an outstanding amount for an agreement, by ID. In the JSON request body, pass an agreement_state_descriptor object with the reason for the agreement state change and the agreement amount and currency.

Cancels a billing agreement, by ID. In the JSON request body, pass an agreement_state_descriptor object with the reason for the agreement state change and the agreement amount and currency.

Reactivates a suspended billing agreement, by ID. In the JSON request body, pass an agreement_state_descriptor object with the reason for the agreement state change and the agreement amount and currency.

Sets the balance for an agreement, by ID. In the JSON request body, pass a common_currency object with the balance currency type and value.

Suspends a billing agreement, by ID.

Lists transactions for a billing agreement, by ID. In the URI, specify the start and end dates of the range of transactions to list.

Executes a billing agreement, by ID, after buyer approval.

Creates a billing plan. In the JSON request body, include the plan details. 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, its type must be REGULAR. If you include two payment definitions in the request, one payment definition type must be TRIAL and the other type must be REGULAR. A payment definition can contain, but does not require, a list of charge models that add shipping and tax information.

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 to ACTIVE.

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 billing plans that are returned in the response, specify one or more optional query and pagination parameters.

Grant an access token from a previously obtained authorization code.

Grant a new access token, using a refresh token.

Retrieve user profile attributes.

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.

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:

1. Create an invoice. Specify [email protected] as the recipient email address in the billing_info object. Use a customer email address only if you want to email the invoice.
   
2. 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.
   

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.

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.

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.

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.

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.

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.

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.

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.

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.

Shows 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.

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 authorize.

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.

Shows details for a captured payment, by ID.

Refunds a captured payment, by ID. Include an amount object in the JSON request body.

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 intent of order.

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.

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

Subscribes your webhook listener to events. A successful call returns a webhook object, which includes the webhook ID for later use.

Shows details for a webhook, by ID.

Lists all webhooks.

Updates a webhook, by ID. Supports only the replace operation.

Deletes a webhook, by ID.

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.

Lists events to which an app can subscribe. For a list of webhook events, see webhook events.

Lists the event subscriptions for a webhook, by ID.

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.

Verifies a webhook signature.