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
- You create an order when a payer selects PayPal as a payment method on your platform.
- You authorize the order when the payer reserves the item, and put the money on hold.
- 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<script2 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
toAUTHORIZE
. - Specify the end receiver of the funds using the
purchase_units/payee
object. - Set the shipping type to
PICKUP_IN_PERSON
.
Sample request
- cURL
- Node
1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders2 -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 isAPPROVED
when the payer successfully completes checkout.
Sample request
- cURL
- Node
1curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/AUTHORIZATION-ID/authorize2 -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 toAPPROVED
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 thepurchase_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/capture2 -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 }'