Enable in-person pickup

DocsLast updated: June 15th 2023, @ 5:00:00 pm


Note: These instructions are available to US partners only. For all other countries, contact PayPal.

When you enable in-person pickup, you can capture the transaction on your platform even though payers and merchants meet offline to complete the purchase.

Know before you code

  • You must be an approved partner to use this integration.
  • You must complete merchant onboarding before you use this integration. During merchant onboarding, you must enable casual and business accounts to accept payment, and you must pass PPCP as the value of the products array.
  • You must have an access token.
  • This integration is a PCI Compliant - SAQ A solution for accepting credit card payments directly on your website.

How it works

  1. You create an order when a payer selects PayPal as a payment method on your platform.
  2. You authorize the order when the payer reserves the item, and put the money on hold.
  3. You capture the authorization when the payer and merchant meet in person and the payer completes the purchase on your platform. Capture moves the money from the payer to the merchant.

Note: This feature does not support seller protection because the payer can verify items before purchasing.

Step 1: Change approval intent to authorize

The default approval intent of the JavaScript SDK is to both authorize the transaction and capture funds immediately. To split authorize and capture into separate actions, add &intent=authorize to the JavaScript SDK script tag as follows:

1<script
2 src="https://www.paypal.com/sdk/js?client-id=CLIENT_ID&intent=authorize">
3</script>
4}

Step 2. Create an order

Before you authorize funds, create an order and:

  • Set the intent to AUTHORIZE.
  • Specify the end receiver of the funds using the purchase_units/payee object.
  • Set the shipping type to PICKUP_IN_PERSON.

Sample request

  1. cURL
  2. Node
1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders
2 -H 'Content-Type: application/json'
3 -H 'Authorization: Bearer ACCESS-TOKEN'
4 -H 'PayPal-Partner-Attribution-Id: BN-CODE'
5 -d '{
6 "intent": "AUTHORIZE",
7 "application_context" : {
8 "shipping_preference" : "SET_PROVIDED_ADDRESS"
9 },
10 "purchase_units": [
11 {
12 "amount": {
13 "currency_code": "USD",
14 "value": "10.00"
15 },
16 "payee": {
17 "email_address": "merchant@example.com"
18 },
19 "shipping" : {
20 "address": {
21 "address_line_1": "500 Hillside Street",
22 "address_line_2": "#100",
23 "admin_area_2": "San Jose",
24 "admin_area_1": "CA",
25 "postal_code": "95131",
26 "country_code": "US"
27 },
28 "type" : "PICKUP_IN_PERSON"
29 }
30 }
31 ]
32 }'

Step 3. Authorize order

After your payer approves the order, authorize the payer's funds.

Note: Orders can't be authorized until the status of the order is APPROVED. The order status is APPROVED when the payer successfully completes checkout.

Sample request

  1. cURL
  2. Node
1curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/AUTHORIZATION-ID/authorize
2 -H 'PayPal-Partner-Attribution-Id:'BN-CODE'
3 -H 'Authorization: Bearer ACCESS-TOKEN'
4 -H 'Content-Type: application/json'
5 -d '{}'

Authorization information

An authorization places a hold on the funds and is valid for 29 days. After a successful authorization, capture the funds within 3 days. Success of the capture is subject to risk and availability of funds on the authorized payment method.

If you don't capture funds within 3 days, you can issue multiple re-authorizations as long as the transaction is within the 29-day authorization period. A re-authorization generates a new authorization ID and restarts the 3-day timer. Capture funds on the new authorization ID.

If you re-authorize on the 27th day of the authorization period, you only have 2 days to capture payment.

You can capture less than the original authorization, the full authorization amount, or more than the authorization amount. If you capture more than the authorization amount, the limit is up to 115% of the original authorization or $75 USD, whichever is less.

Note: Orders can't be authorized until the status of the order is set to APPROVED. The order status is set to APPROVED when the payer successfully completes the checkout flow.

Step 4. Capture authorization

When you are ready to capture the funds you authorized, call /v2/payments/authorizations/AUTHORIZATION-ID/capture, and:

  • Use the authorization_id from the purchase_units/payments/authorizations/id field of the response from the previous step to authorize an order or from a show order details call.
  • Use the payment_instruction/platform_fees array to specify any fees you want to collect on this transaction.
1curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/AUTHORIZATION-ID/capture
2 -H "Content-Type: application/json"
3 -H "Authorization: Bearer ACCESS-TOKEN"
4 -d '{
5 "payment_instruction": {
6 "disbursement_mode": "INSTANT",
7 "platform_fees": [
8 {
9 "amount": {
10 "currency_code": "USD",
11 "value": "2.00"
12 }
13 }
14 ]
15 }
16 }'