API Requests
To make a REST API request, you combine the HTTPGET
, 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
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\2 -H "Content-Type: application/json" \3 -H "Authorization: Bearer ACCESS-TOKEN"
Query parameters
For most RESTGET
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\2 -H "Content-Type: application/json" \3 -H "Authorization: Bearer ACCESS-TOKEN"
HTTP request headers
The most commonly used HTTP request headers are:
Accept
The response format, which is required for operations with a response body. The syntax isAccept: application/format
, where format
is json
.Authorization
Authorization is required to get an access token or make API calls.
- Get an access token: When you create a sandbox or live REST API app, PayPal generates a set of OAuth 2.0 client ID and secret credentials for the sandbox or live environment. When you make a get an access token call, set the
Authorization
header to these credentials for the environment in which you're making the call. - Make REST API calls: Include the access token in the
Authorization
header with theBearer
authentication scheme:Authorization: Bearer Access-Token
.
Content-Type
The request format required for operations with a request body. The syntax is:Content-Type: application/format
where format
is json
.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.
Build the JWT
While you can use either a signed or an unsigned JWT, PayPal recommends using the unsigned JWT for simplicity because the information passed with the JWT is not sensitive data.
A JWT consists of 3 parts:
- Header: Identifies the algorithm that generated the signature. Because PayPal recommends an unsigned JWT, pass an
alg
ofnone
for the header. - Payload: Contains a set of claims about the entities involved in the API call. For the
PayPal-Auth-Assertion
header, the entity is usually the merchant. The payload must includeiss
to identify the third-party caller, and eitheremail
orpayer_id
to identify the merchant on whose behalf the call is made. Because a merchant's email address can change, PayPal recommends usingpayer_id
to specify a merchant. - Signature: Validates the token and consists of the encoded header, the encoded payload, a secret, and the algorithm. PayPal recommends passing an empty string for the signature. If you prefer a signed JWT for security reasons, you can sign it with your secret from your API credentials.
Example
- Header:
"alg": "none"
- Payload:
1{2 "iss": "client_id",3 "payer_id": "merchant_payer_id"4 }
- Signature: Use
""
for unsigned, or sign with your client secret.
To pass the JWT in HTTP environments, use Base64 to encode all three parts of the JWT separately, then concatenate them with a period. The following code shows the previous example after Base64 encoding and compact serialization (or concatenation):
1{2 ew0KICAiYWxnIjogIm5vbmUiDQp9.ew0KICAiaXNzIjogImNsaWVudF9pZCIsDQogICJwYXllcl9pZCI6ICJtZXJjaGFudF9wYXllcl9pZCINCn0=.3}
PayPal-Auth-Assertion
header in an API call.PayPal-Partner-Attribution-Id
Required for multiparty payments. 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-Mock-Response
Optional. Simulate an error. Pass an error code to test through themock_application_codes
header parameter. For example, "mock_application_codes": "DUPLICATE_INVOICE_ID"
. For more information, see:- Error codes: Payment API Error Messages and Orders API Error Messages.
- Negative testing: Simulate negative responses with request headers.
PayPal-Request-Id
Optional. See the API reference to verify the API supports this header.
PayPal-Request-Id
contains a unique user-generated ID that the server stores for a period of time. Use this header to enforce idempotency on REST API POST calls. You can make these calls any number of times without concern that the server creates or completes an action on a resource more than once. You can retry calls that fail with network timeouts or the HTTP 500 status code. You can retry calls for as long as the server stores the ID.
For example, a user calls refund captured payment with the PayPal-Request-Id
header that contains a unique user-provided ID. The user can make the call again with the same ID in the PayPal-Request-Id
header for up to 45 days.
If the initial call fails with the HTTP 500
status code but the server has already refunded the payment, the caller does not need to worry that the server will refund the payment again.