API idempotency

DOCS

Last updated: Aug 15th, 6:08am

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 HTTP 5xx status codes for as long as the server stores the ID. Idempotency enables you to correlate request payloads with response payloads, eliminate duplicate requests, and retry failed requests or requests with unclear responses.

To enforce idempotency on REST API POST calls, use the PayPal-Request-Id request header, which contains a unique user-generated ID that the server stores for a period of time.

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.

If you are using a REST SDK, idempotency and the PayPal-Request-Id header are abstracted for you.

For example, when you include a previously specified PayPal-Request-Id header in a request, PayPal returns the latest status of the previous request that used that same header. Conversely, when you omit the PayPal-Request-Id header from a request, PayPal duplicates the request.

Note: When you send two simultaneous API requests with same PayPal-Request-Id header, PayPal processes the first request and might fail the second request.

Example

A capture authorized payment request that includes a PayPal-Request-Id header times out but the server captures the payment.

You retry the original request with the same PayPal-Request-Id header:

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/0VF52814937998046/capture \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer Access-Token" \
4  -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440010" \
5  -d '{
6  "amount": {
7    "value": "10.99",
8    "currency_code": "USD"
9  },
10  "invoice_id": "INVOICE-123",
11  "final_capture": true
12}'

If this request succeeds, PayPal returns the latest status of the request, which is the HTTP 201 Created status code and a JSON response body that shows captured payment details. The server does not capture the payment again because the capture succeeded in the first call.

1{
2  "id": "2GG279541U471931P",
3  "status": "COMPLETED",
4  "links": [
5    {
6      "rel": "self",
7      "method": "GET",
8      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P"
9    },
10    {
11      "rel": "refund",
12      "method": "POST",
13      "href": "https://api-m.paypal.com/v2/payments/captures/2GG279541U471931P/refund"
14    },
15    {
16      "rel": "up",
17      "method": "GET",
18      "href": "https://api-m.paypal.com/v2/payments/authorizations/0VF52814937998046"
19    }
20  ]
21}

Usage notes

The PayPal-Request-Id header value must be unique for both each request and an API call type. For example, authorize payment and capture authorized payment.
PayPal recommends that you use the UUID standard for the PayPal-Request-Id header value because it meets the 38 single-byte character limit.
PayPal provides the status of a request at the current time and not the status of the original request.