Idempotency

APICurrent

Last updated: Aug 15th, 8:01am

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.

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.

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.

      Support, docs, and resources

      We use cookies to improve your experience on our site. May we use marketing cookies to show you personalized ads? Manage all cookies