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, please contact PayPal.
When you enable in-person pickup, you can capture the transaction on your platform even though buyers and sellers meet offline to complete the purchase. Enabling this feature prevents platform leakage while giving your sellers the flexibility to meet their buyers in person.
Know before you code
- You must be an approved partner to use this integration.
- You must complete seller onboarding before you use this integration. During seller 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
The flow for enabling in-person pickup is:
- You create an order when a buyer selects PayPal as a payment method on your platform.
- You authorize the order when the buyer reserves the item. Authorization puts the money on hold.
- You capture the authorization when the buyer and seller meet in person and the buyer completes the purchase on your platform. Capture moves the money from the buyer to the seller.
Note: This feature does not support seller protection because the buyer can verify items before purchasing.
Step 1: Change the approval intent to authorize
The default approval intent of the PayPal 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 PayPal JavaScript SDK script tag as seen in the following example.
<script
src="https://www.paypal.com/sdk/js?client-id=YOUR_CLIENT_ID&intent=authorize">
</script>
Step 2. Create an order
Before you authorize funds, you must create an order with the intent
field set to AUTHORIZE
. To create an order, copy the following code and modify it.
- 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": "seller@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}'
Modify the code
After you copy the sample request, modify the following:
- Use the
purchase_units/payee
object to specify the end receiver of the funds. - Shipping type must be set to
PICKUP_IN_PERSON
.
Step 3. Authorize an order
After your buyer approves the order, you call authorize order to authorize the buyer's funds.
- cURL
- Node
1curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize2-H 'PayPal-Partner-Attribution-Id:'<BN-Code>'3-H 'Authorization: Bearer <Access-Token>'4-H 'Content-Type: application/json'5-d '{}'
An authorization places a hold on the funds and is valid for 29 days. After a successful authorization, PayPal recommends that you capture the funds within the three-day honor period. Success of the capture is subject to risk and availability of funds on the authorized funding instrument. Within the 29-day authorization period, you can issue multiple re-authorizations after the honor period expires. A re-authorization generates a new Authorization ID and restarts the honor period and any subsequent capture should be performed on the new Authorization ID. If you do a re-authorization on the 27th day of the authorization, you get only two days of honor period. You can capture less than the original authorization, full authorization amount, or even more than the authorization amount (up to 115% of the original authorization or $75 USD more, whichever is less).
Note: Orders cannot be authorized until the status of the order is set to
APPROVED
. The order status is set toAPPROVED
when the buyer successfully completes the checkout flow.
Step 4. Capture an authorization
When you are ready to capture the funds you authorized, call /v2/payments/authorizations/{authorization_id}/capture. You can retrieve 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.
curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/5O190127TN364715T/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer <Access-Token>" \
-d '{
"payment_instruction": {
"disbursement_mode": "INSTANT",
"platform_fees": [
{
"amount": {
"currency_code": "USD",
"value": "2.00"
}
}
]
}
}'
- Use the
payment_instruction/platform_fees
array to specify any fees you want to collect on this transaction.