Authorize and delay capture

Charge a customer after fulfilling their order, not immediately. Common use cases include:

• Reserve payment for pre-orders shipping in the future
• Charge after made-to-order items are produced
• Authorize hotels or rentals at booking, capture at check-in or check-out
• Confirm authenticity of high value items requiring verification before capturing payment

This integration uses the Orders API v2 to authorize and the Payments API v2 to capture later. To authorize first and capture later, change your integration to use intent: "AUTHORIZE". This reserves funds on the customer's payment method for up to 29 days.

The highest success rate is within the first 3 days (the honor period). After 3 days, you may use reauthorization to extend the hold.

What's the difference between authorization and capture?

Integrate server side

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

# Step 1: Create order with AUTHORIZE intent
curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{
    "intent": "AUTHORIZE",
    "purchase_units": [{
      "amount": {
        "currency_code": "USD",
        "value": "100.00"
      }
    }]
  }'

# Step 2: Capture the authorization later
curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION_ID/capture \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{}'

Test endpoints

# 1. Create authorization (returns orderId)
curl -X POST http://localhost:3000/api/orders \
  -H "Content-Type: application/json" \
  -d '{"amount": "100.00"}'

# Expected response:
# {"id":"5O190127TN364715T"}

# 2. Later, capture the authorization (use authorizationId from PayPal)
curl -X POST http://localhost:3000/api/orders/ORDER_ID/capture \
  -H "Content-Type: application/json" \
  -d '{"authorizationId": "AUTH_ID_FROM_PAYPAL"}'

# Expected response:
# {"status":"COMPLETED","captureId":"3C679366HH908993F"}

Best practices

• Capture within 3-day honor period: Authorization success rates are highest during the 3-day honor period. After the payment is authorized, ship within 3 days.
• Track authorization expiration: Store the date when the authorization was created in your database. Alert when approaching day 29 and have a process to handle expiring authorizations.
• Handle partial captures: You can capture any amount up to the authorized total. The remainder can be voided or left to expire. For multiple shipments, use multiple partial captures.
• Void uncaptured authorizations promptly: If you can't fulfill an order, void the authorization immediately to release customer funds.
• Communicate holds to customers: Inform customers that their payment is authorized, but not yet charged. Inform them when the actual charge will occur.
• Monitor authorization validity: Authorizations can be voided by the customer's bank or PayPal. Handle capture failures gracefully.

Important details

• Find authorization IDs: The authorization ID is in the order approval response at purchase_units[0].payments.authorizations[0].id. Store this value in your database immediately.
• Authorization expiration: You have up to 29 days to capture payment. Captures are most likely to succeed during the 3-day honor period. After 29 days, the authorization automatically expires, and you'll need to create a new order to charge the customer.
• Partial captures: You can capture any amount up to the authorized total.
• Extending authorizations: Use reauthorization between days 4-29 to extend an authorization. See Reauthorize an authorization.

Test your integration

Sandbox authorizations don't expire after 29 days. Test authorizations with negative testing instead.

Standard testing

Negative testing

1. Make sure to enable negative testing in your sandbox business account as described in the quick start prerequisites.
2. In the .env file, set ENABLE_NEGATIVE_TESTING=true and set NEGATIVE_TEST_TYPE to one of the error codes in the table.
3. Restart the server after changing the .env file: node server.js.

Go-live checklist

• Implement authorization tracking system.
• Integrate capture process with fulfillment workflow.
• Configure authorization expiration monitoring.
• Test customer communication about holds.
• Test with real $1 authorization and capture.

Post-launch monitoring

These values are suggested monitoring thresholds for your integration, not performance guarantees from PayPal.