API requests
DocsCurrentLast updated: March 16th 2023, @ 11:23:55 am
To make a REST API request, you combine the HTTP GET
, POST
, PUT
, PATCH
,
or DELETE
method, the URL to the API service, the URI to a resource to query,
submit data to, update, or delete, and one or more
HTTP request headers.
The URL to the API service is either:
- Sandbox.
https://api-m.sandbox.paypal.com
- Live.
https://api-m.paypal.com
Optionally, you can include query parameters on GET
calls
to filter, limit the size of, and sort the data in the responses.
Most GET
, POST
, PUT
, and PATCH
calls require a JSON request body.
This sample request lists invoices:
1curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true -H "Content-Type: application/json" -H "Authorization: Bearer <Access-Token>"
Query parameters
For most REST GET
calls, you can include one or more query parameters on the request URI to filter, limit the size of, and sort the data in an API response. For filter parameters, see the individual GET
calls.
To limit, or page, and sort the data that is returned in some API responses, use these, or similar, query parameters:
Note: Not all pagination parameters are available for all APIs.
Parameter | Type | Description |
---|---|---|
count | integer | The number of items to list in the response. |
end_time | integer | The end date and time for the range to show in the response, in Internet date and time format. For example, end_time=2016-03-06T11:00:00Z . |
page | integer | The page number indicating which set of items will be returned in the response. So, the combination of page=1 and page_size=20 returns the first 20 items. The combination of page=2 and page_size=20 returns items 21 through 40. |
page_size | integer | The number of items to return in the response. |
total_count_required | boolean | Indicates whether to show the total count in the response. |
sort_by | string | Sorts the payments in the response by a specified value, such as the create time or update time. |
sort_order | string | Sorts the items in the response in ascending or descending order. |
start_id | string | The ID of the starting resource in the response. When results are paged, you can use the next_id value as the start_id to continue with the next set of results. |
start_index | integer | The start index of the payments to list. Typically, you use the start_index to jump to a specific position in the resource history based on its cart. For example, to start at the second item in a list of results, specify ?start_index=2 . |
start_time | string | The start date and time for the range to show in the response, in Internet date and time format. For example, start_time=2016-03-06T11:00:00Z . |
For example, the Invoicing API returns details for four invoices beginning with the third invoice and includes the total count of invoices in the response:
1curl -v -X GET https://api-m.sandbox.paypal.com/v1/invoicing/invoices?page=3&page_size=4&total_count_required=true -H "Content-Type: application/json" -H "Authorization: Bearer <Access-Token>"
HTTP request headers
The commonly used HTTP request headers are:
Accept | |
The response format, which is required for operations with a response body. The syntax is: Accept: application/format Where | |
Authorization | |
Required to get an access token or make API calls:
| |
Content-Type | |
The request format, which is required for operations with a request body. The syntax is: Content-Type: application/format Where | |
PayPal-Auth-Assertion | |
An API client-provided JSON Web Token (JWT) assertion that identifies the merchant. To use this header, you must get consent to act on behalf of a merchant. You might want to use a JWT if you act on behalf of multiple merchants at the same time, because it is difficult and expensive to generate and manage multiple access tokens. Instead of managing multiple access tokens, you can use this header to provide a JWT assertion that identifies the merchant when you call the API. Constructing the JWT While you can use either a signed or unsigned (unsecured) JWT, PayPal recommends using the unsigned JWT for simplicity because the information you pass with the JWT is not sensitive data. A JWT consists of three parts:
Example:
To pass the JWT easily in HTTP environments, use Base64 to encode all three parts of the JWT separately, then concatenate them with a period ( ew0KICAiYWxnIjogIm5vbmUiDQp9.ew0KICAiaXNzIjogImNsaWVudF9pZCIsDQogICJwYXllcl9pZCI6ICJtZXJjaGFudF9wYXllcl9pZCINCn0=. Refer to Issue a Refund in the PayPal Commerce Platform documentation for an example of using the | |
PayPal-Client-Metadata-Id | |
Optional. Verifies that the payment originates from a valid, user-consented device and application. Reduces fraud and decreases declines. Transactions that do not include a client metadata ID are not eligible for PayPal Seller Protection. | |
PayPal-Partner-Attribution-Id | |
Identifies the caller as a PayPal partner. To receive revenue attribution, specify a unique build notation (BN) code. BN codes provide tracking on all transactions that originate or are associated with a particular partner. To find your BN code, see Code and Credential Reference. | |
PayPal-Request-Id | |
Optional. Contains a unique user-generated ID that the server stores for a period of time. Use this header to enforce idempotency on REST API For example, a user calls refund captured payment with the If the initial call fails with the HTTP Note: Not all APIs support this header. To determine whether your API supports it and for information about how long the server stores the ID, see the reference for your API. |