Authorize and capture
DocsLast updated: June 15th 2023, @ 5:00:00 pm
Authorize your payers' funds before you capture them. An authorization places a hold on the funds and is valid for 29 days.
Note: Authorize and capture is not supported with Managed Path Onboarding. Sellers also cannot accept alternative payment methods with authorize and capture.
Know before you code
- Complete merchant onboarding.
- Integrate Checkout.
1. Create order
Create an order with the intent
field set to AUTHORIZE
. Use the purchase_units/payee
object to specify the end receiver of the funds.
- 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 "purchase_units": [{8 "amount": {9 "currency_code": "USD",10 "value": "100.00"11 },12 "payee": {13 "email_address": "seller@example.com"14 }15 }]16 }'
2. Authorize order
After your payer approves the order, authorize the order.
Note: Orders can't be authorized until the status of the order is
APPROVED
. The order status isAPPROVED
when the payer successfully completes checkout.
- 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 '{}'
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.
3. Capture an authorization
When you are ready to capture funds, call /v2/payments/authorizations/AUTHORIZATION-ID/capture
and:
- Include the authorization ID. You can retrieve 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/disbursement_mode
field to specify when funds should be disbursed to the merchant. You can delay disbursement by passingDELAYED
, or disburse funds immediately withINSTANT
. For more information, refer to Delay disbursements and Immediate capture. - Use the
payment_instruction/platform_fees
array to specify 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 }'