Skip to main content
Handle payments for orders that customers purchase online and pick up at a physical store location. This pattern authorizes payment at checkout and captures funds after verifying pickup. This ensures payment is secured and collected only when the customer receives their items. Common scenarios include:
  • Retail stores offering same-day pickup
  • Grocery orders for curbside pickup
  • Restaurant orders for takeout
  • Click-and-collect services
Before you begin, you’ll need to complete the quick start PayPal integration.

​
Integrate server side

Add the following endpoints to your existing server file from the quick start integration. 
# Create BOPIS order (authorization)
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": "75.00"
      },
      "custom_id": "PICKUP-PICK789",
      "description": "Pickup at Store #123"
    }]
  }'

# Authorize the order
curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER_ID/authorize \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

# Capture payment at pickup
curl -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTH_ID/capture \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ACCESS_TOKEN"

​
Test endpoints

  1. Create an authorization.
Endpoint: /v2/checkout/orders/{id}/authorize
# 1. Create BOPIS order (authorization)
curl -X POST http://localhost:3000/api/orders/bopis \
  -H "Content-Type: application/json" \
  -d '{"amount": "75.00", "pickupLocation": "Store #123", "pickupCode": "PICK789"}'
  1. Capture payment at pickup.
Endpoint: /v2/payments/authorizations/{authorization_id}/capture
# 2. Complete pickup (capture payment)
curl -X POST http://localhost:3000/api/orders/bopis/ORDER_ID/pickup \
  -H "Content-Type: application/json" \
  -d '{"authorizationId": "AUTH_ID", "pickupCode": "PICK789"}'

​
Best practices

  • Set clear pickup timeframes: Communicate pickup windows. Typical holds: 7 days for retail, 24 hours for restaurants or groceries. Balance customer convenience with inventory management. Automatically void expired authorizations.
  • Implement pickup verification: Require order number and pickup code. Capture payment only after verifying the customer.
  • Handle partial pickups: If part of the order is collected, capture the partial amount and void the remainder.
  • Train store staff: Ensure staff know when to trigger capture and how to handle pickup exceptions.
  • Monitor unclaimed orders: Track unclaimed orders and void authorizations promptly to release funds.

​
Important details

  • Capture only after pickup verification: Do not capture payment before verifying the customer has received their items. This protects both you and the customer from fraud.
  • Add items at pickup: If customers want to add items at pickup, process additional items as a separate transaction at the store.
  • Handle partial pickups: If only part of an order is available, capture only the amount for available items and void the remaining authorization.
  • Notification timing: Email customers when orders are ready for pickup, but only capture payment after pickup. The authorization secures payment while the order waits.
  • Identity verification methods: Verify customer identity through order number, pickup code, photo ID, or app confirmation before capturing. Works the same for in-store, curbside, or drive-up pickup.

​
Test your integration

Before testing pickup flows, authorize an order to obtain an authorization ID.

​
Standard testing

Test scenarioSetupExpected result
Successful pickupCreate order and verify with correct codeAuthorization succeeds and capture completes on pickup.
Invalid pickup codeUse incorrect pickup codeReturns 401 error: invalid pickup code.
Abandoned orderDo not pick up within timeframeAuthorization is voided automatically.
Partial pickupAuthorize $100, pick up $60Capture $60 and void remaining $40.

​
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.
Test scenarioError codeExpected result
Expired authorizationAUTHORIZATION_EXPIREDError: authorization expired and order canceled.
Already picked upAUTHORIZATION_ALREADY_CAPTUREDError: authorization already captured.

​
Go-live checklist

  • Integrate store pickup system with payment capture.
  • Test pickup verification at all store locations.
  • Configure automatic voids for unclaimed orders.
  • Train store staff on capture process.
  • Test with a real $1 order and pickup.

​
Post-launch monitoring

These values are suggested monitoring thresholds for your integration, not performance guarantees from PayPal.
MetricTargetAction if below target
Authorization success rate95%Investigate authorization failures.
Capture success at pickup90%Check for expired authorizations or staff process gaps.
Authorization expiration rate<15%Monitor for abnormal increases.
Void success rate (abandoned)98%Investigate void failures.
API response time<2 secondsCheck PayPal API status.