Buy online, pick up in store

Documentation Index

Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt

Use this file to discover all available pages before exploring further.

• Retail stores offering same-day pickup
• Grocery orders for curbside pickup
• Restaurant orders for takeout
• Click-and-collect services

​

Integrate server side

# 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.

# 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"}'

2. Capture payment at pickup.

# 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

​

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

• 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