Void an authorized payment

Cancel an authorized payment before capturing it to release the customer's held funds. Voiding an authorized payment saves processing fees compared to refunding a captured payment. Common scenarios include:

• Customer cancels an order before shipment
• Item is out of stock after authorization
• Order fails fraud verification
• Customer requests cancellation during fulfillment

Add the void endpoint to cancel authorizations. This integration uses the Payments API v2 and requires an authorized payment that hasn't been captured yet.

What's the difference between authorization and capture?

Prerequisites

• Complete the quick start PayPal integration.
• Implement an authorization and capture flow that doesn't use immediate capture.
• Have an authorization ID from an order creation. Store authorization IDs in your database when creating orders. You'll need them to void the authorization.
• Optional for production:
  • Automated void triggers for inventory and fraud checks
  • Customer notifications on voided payments
  • Void reason tracking for analytics

Integrate server side

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

# Void an authorization
curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION_ID/void \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -d '{}'

Test endpoint

# Test voiding an authorization (replace with actual authorization ID)
curl -X POST http://localhost:3000/api/authorizations/8AA831015G517922L/void \
  -H "Content-Type: application/json"

# Expected success response:
# {"id":"8AA831015G517922L","status":"VOIDED"}

# Test voiding already captured authorization (should fail)
curl -X POST http://localhost:3000/api/authorizations/CAPTURED_AUTH_ID/void \
  -H "Content-Type: application/json"

# Expected error response:
# {"error":"Cannot void - already captured. Use refund instead."}

Best practices

• Void promptly: Cancel authorizations immediately when an order won't be fulfilled to release customer funds. Don't let an authorization expire.
• Void before capture: Always void instead of refund when possible. Voiding can save up to 3% in processing fees.
• Automate cancellations: Trigger voids automatically for out-of-stock scenarios or fraud detection.
• Handle timing: Authorizations expire after 3 days (standard) or 29 days (honor period).

Important details

• Void vs. refund: Void cancels an authorization before capture. Refund returns money after a payment has been captured. Voiding saves processing fees.
• Finding authorization IDs: You need the authorization ID to void, not the order ID. The authorization ID is returned when you create an order with AUTHORIZE intent. Store this value in your database immediately.
• All-or-nothing operation: You cannot partially void an authorization. Voids cancel the entire authorized amount.
• Voided authorizations cannot be captured: Once voided, an authorization is permanently cancelled and cannot be captured. Attempting to capture will fail with an error.
• Fund release time: In sandbox mode, funds release immediately. In production, funds can take up to 24 hours depending on the customer's bank.

Test your integration

• Create test authorizations with AUTHORIZE intent.
• Test at different intervals: immediately after authorization, after 1 day, and after 3 days.
• Verify funds are released in the sandbox buyer account after voiding.

Standard testing

Negative testing

For 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

• Test void flow in sandbox with real authorization IDs.
• Implement void reason tracking.
• Set up customer cancellation notifications.
• Train support team on void vs refund scenarios.
• Configure automatic void triggers, such as out of inventory or a fraudulent transaction.
• Monitor void success rates.
• Test with real $1 authorization and void it.

Post-launch monitoring

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