Glossary

The PayPal APIs are HTTP-based RESTful APIs that use OAuth 2.0 for authorization. API request and response bodies are formatted in JSON.

This glossary defines commonly used terms for the PayPal REST APIs.

A

access token

The credentials that the PayPal authorization server issues to a client in exchange for the OAuth 2.0 client ID and secret credentials. This token proves the client's identity and lets them make REST API calls to access protected resources.

API request

The combination of an HTTP method, the API service URL, a URI to the resource, optional query parameters for filtering and pagination, HTTP request headers including the Authorization header with the access token, and, if required, a JSON-formatted request body.

API version

The API version, which you append to the endpoint. For example, the version in this endpoint is v1:

https://api.paypal.com/v1
authorization

When you create a REST API app, PayPal generates a set of OAuth 2.0 client ID and secret credentials for the sandbox and live environments. In exchange for these credentials, the PayPal authorization server issues an access token that you use for authorization when you make REST API requests.

authorization and capture

A feature that enables you to authorize a payment, or place a customer's funds on hold, that you can capture, or obtain payment for, later. For example, you might have a delayed shipment for which you do not want to collect funds right away.

Authorization and capture includes an authorization period and honor period.

To complete authorization and capture, use the Payments API.

authorization period

An authorization places a hold on the funds and is valid for 29 days. After a successful authorization, PayPal recommends that you capture the funds within the three-day honor period. Success of the capture is subject to risk and availability of funds on the authorized funding instrument. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires. A re-authorization generates a new Authorization ID and restarts the honor period, and any subsequent capture should be performed on the new Authorization ID. If you do a re-authorization on the 27th day of the authorization, you get only two days of honor period.

B

bearer token

A type of access token that lets you complete an action on behalf of a resource owner.

C

capture

Obtain payment for a previously authorized payment.

connected path

The partner model where the PayPal seller rather than the partner assumes financial liability.

  • Sellers must have PayPal business accounts.
  • PayPal signup is completed in a secure window on the platform site.
  • If a seller already has an account with the partner, the signup form can be populated with the partner’s existing account data.
  • Sellers grant the partner permissions to process PayPal transactions on their behalf.
cURL

A command-line tool that lets you send HTTP requests and receive responses.

customer

An individual or company that purchases goods or services on a PayPal Commerce Platform venue. Also called a buyer, consumer, or sender.

D

disbursement

The release of funds by PayPal to a seller's bank account.

If the seller selects instant disbursement, they receive funds as soon as a sale is complete.

If the seller selects delayed disbursement, funds are not released until the partner triggers disbursement.

E

endpoint

The URL through which you access an API. For example:

https://api.paypal.com/

F

filtering

The use of query parameters to filter the items that are returned in an API response.

H

HATEOAS

A constraint of the REST application architecture, Hypermedia as the Engine of Application State dictates that each API response include an array of contextual links, if available, that gives you more information about and lets you construct an API flow that is relative to that request.

hold

The retention of funds by PayPal on a partner’s behalf. A partner can opt to either place an automatic hold on all PayPal payments made on the platform or notify PayPal when they want to initiate holds.

honor period

A three-day period from day one to day three of the authorization period.

After a successful authorization or reauthorization, PayPal honors authorized funds for three days. However, PayPal cannot ensure that 100% of the funds will be available. A day is defined as the start of the calendar day when the authorization or reauthorization was made, from 00:00 to 23:50 Pacific Time.

You can only reauthorize a payment after the honor period concludes.

I

idempotency

You can make idempotent calls any number of times without concern that the server creates or completes an action on a resource more than once. You can retry idempotent calls that fail with network timeouts or the HTTP 500 status code for as long as the server stores the ID.

Internet date and time format

The ISO 8601-compliant format that API requests and responses use for date and time values.

L

loss account

Used by managed path solutions to reverse movement of funds. When a customer disputes a charge for fraud or non-delivery of goods, PayPal reverses the transaction and refunds the customer from the loss account. Loss accounts are required because managed path partners assume full financial liability for their merchants.

M

managed path

The partner model where the partner assumes financial liability.

  • Sellers are not required to have PayPal accounts.
  • The partner controls the sellers’ experience and has full responsibility and liability for sellers.
  • Seller accounts are linked with the partner in a parent-child relationship, where the partner manages those accounts on the sellers’ behalf.
  • Funds from the seller accounts roll up to the partner’s account at the end of each day. The partner disburses funds to the sellers outside of PayPal.

N

namespace

A logical grouping of application, data, and its metadata. For example:

https://api.paypal.com/v1/payments/

O

OAuth 2.0

The industry-standard authorization protocol. Focuses on client developer simplicity and provides authorization flows for web, desktop, and mobile apps, and Internet of things (IoT) devices.

See OAuth 2.0.

P

pagination

The use of query parameters to limit the size of and sort the data in an API response.

partner

A company that sells software or other technical services that enable sellers to process e-commerce transactions. A partner can also be a marketplace operator or owner. Partners earn revenue by selling their software and capabilities, and receive compensation from PayPal for enabling and influencing PayPal-branded payments.

partner fee

The commission paid to a partner by the seller on processed transactions.

path

A predefined configuration of PayPal Commerce Platform features and functions that determine how sellers are onboarded and whether shopping carts can include goods from more than one seller.

payer ID

The unique PayPal account identification number.

PayPal processing fee

The fee paid to PayPal by the seller to process transactions. Usually 2.9% plus $0.30.

progressive onboarding

The method for onboarding connected path sellers who do not already have a PayPal account. Enables customers to use PayPal to pay across your platform. Sellers do not go through PayPal setup until they receive their first order. After a customer buys something with PayPal, the seller receives an email from PayPal and is guided through the setup process.

purchase unit

A single seller’s portion of an order. If a customer orders multiple items from one seller, you can put them in a single purchase unit. However, if a customer orders items from multiple sellers, you must create separate purchase units for each seller. PayPal treats each purchase unit as a single transaction.

Q

query parameter

A type of parameter that you include on the request URI to filter and sort the items that are returned in an API response and limit the size of the data returned in that response.

R

reference account

A PayPal general ledger entry that the partner creates on behalf of a seller to track transactions for managed path integrations. The seller cannot access this account.

resource

A named thing in a namespace, such as a payment transaction, against which you call REST methods.

For example:

https://api.paypal.com/v1/payments/payment/
https://api.paypal.com/v1/payments/payment payment_id
resource collection

A REST resource against which you call the REST GET method to list resources.

For example, you can complete a GET operation against this resource collection to list payments:

https://api.paypal.com/v1/payments/payment/
REST API app

Associates a set of OAuth 2.0 client ID and secret credentials with a PayPal account and a set of scopes and configurations. You can create multiple apps for the same PayPal account.

S

seller

An individual or company that sells goods or services on a platform venue. A seller can also be an individual or organization that conducts fund-raising activities through the platform. Also called a merchant, receiver, or vendor.

U

upfront onboarding

A method for setting up sellers to accept PayPal orders using the connected path model. With upfront onboarding, you post a PayPal signup link on your website for your sellers and PayPal handles the rest. The signup flow uses an in-context experience to keep your sellers on your website and minimizes the number of pages to navigate. You can pre-fill some form fields for the seller based on content the seller has already provided you. Unlike the URL onboarding experience, this method leverages APIs and provides a streamlined experience for the seller.

URL onboarding

A method for setting up sellers to accept PayPal orders by using the connected path model. This option does not enable you to pre-fill any information that you collect from your sellers but it is faster for you to set up than the upfront onboarding method. With this onboarding experience, you use a URL with static parameters to direct the seller to PayPal.

W

webhook

An HTTP callback that receives notification messages for an event.

Feedback