Extend an authorization

Extend the validity of an existing authorization when fulfillment takes longer than the initial authorization period. In the United States, authorizations are valid for 3 days, and up to 29 days in other regions. Reauthorization allows the merchant to keep funds available without requiring the buyer to re-approve payment.

Common scenarios include:

• Custom or made-to-order items with extended production times
• Backorders with delayed inventory availability
• International shipments with longer fulfillment windows
• Pre-orders for unreleased products
• Fulfillment delays due to operational or external factors
• High-value orders requiring additional verification before shipping

This integration uses the Payments API v2 to reauthorize an existing authorization and generate a new authorization with a refreshed expiration date.

Prerequisites

• Complete the quick start PayPal integration.
• An existing authorization ID that is past the initial honor period (3+ days old).
• A server environment capable of securely calling PayPal REST APIs.

Integrate server side

Add the following endpoint to your existing server file from the quick start integration.

# Reauthorize for the same amount
curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION_ID/reauthorize \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{}'

# Reauthorize for a higher amount (up to 115% of original)
curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION_ID/reauthorize \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "amount": {
      "currency_code": "USD",
      "value": "115.00"
    }
  }'

# Get reauthorization status
curl -X GET https://api-m.sandbox.paypal.com/v2/payments/authorizations/NEW_AUTHORIZATION_ID \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

Test endpoint

# Reauthorize for the same amount
curl -X POST http://localhost:3000/api/paypal/reauthorize-payment \
  -H "Content-Type: application/json" \
  -d '{"authorizationID": "5AB67890CD123456E"}'

# Expected success response:
# {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"100.00"},"expirationTime":"2024-02-05T10:23:23Z"}

# Reauthorize for a higher amount (up to 115% of original)
curl -X POST http://localhost:3000/api/paypal/reauthorize-payment \
  -H "Content-Type: application/json" \
  -d '{
    "authorizationID": "5AB67890CD123456E",
    "amount": {
      "currency_code": "USD",
      "value": "115.00"
    }
  }'

# Expected success response:
# {"status":"REAUTHORIZED","newAuthorizationId":"8CD12345EF678901A","amount":{"currency_code":"USD","value":"115.00"},"expirationTime":"2024-02-05T10:23:23Z"}

Best practices

• Reauthorize within the valid window: Reauthorization is allowed only between days 4-29 after the original authorization, depending on region.
• Reauthorize only once: Each authorization can be reauthorized a single time. If more time is required, create a new order.
• Monitor authorization expiration: Track expiration dates and trigger reauthorization before the authorization lapses.
• Respect amount limits: You can reauthorize for up to 115% of the original amount in most regions. Regional limits may vary.
• Handle failures gracefully: If reauthorization fails, void the original authorization and request a new payment from the customer.

Important details

• Authorization validity periods: Authorizations are valid for 3 days in the US and up to 29 days in most other regions. After expiration, funds are automatically released to the customer.
• Reauthorization timing window: You can only reauthorize between days 4-29 after the initial authorization. Attempts before day 3 or after day 29 will fail.
• Single reauthorization limit: Each authorization can be reauthorized only once. If you need more time after reauthorization, void the authorization and create a new order.
• No customer interaction required: Reauthorization happens server-side without customer approval. However, consider notifying customers as a courtesy when extending payment holds.
• Handling reauthorization failures: If reauthorization fails, void the original authorization and request new payment from the customer. Common failures include insufficient funds, authorization already captured or voided, or attempting outside the valid window.

Test your integration

Run the following standard tests on your integration.

Go-live checklist

• Test reauthorization in sandbox using the time machine.
• Verify handling of amount limits (up to 115%).
• Test error handling for all reauthorization error cases.
• Implement authorization expiration monitoring.
• Switch to production API credentials.