Buy online, pick up in store

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

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"
      },
      "shipping": {
        "type": "PICKUP_IN_STORE",
        "address": {
          "address_line_1": "123 Orders St",
          "admin_area_2": "San Francisco",
          "admin_area_1": "CA",
          "postal_code": "94107",
          "country_code": "US"
        }
      },
      "custom_id": "YOUR-PICKUP-ORDER-ID",
      "description": "Pickup at Store 123"
    }]
  }'

# After buyer approval, 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

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

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

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