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

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.

  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 "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 is APPROVED when the payer successfully completes checkout.

  1. cURL
  2. Node
1curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/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.

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 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/disbursement_mode field to specify when funds should be disbursed to the merchant. You can delay disbursement by passing DELAYED, or disburse funds immediately with INSTANT. 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/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 }'