Authorize and Capture

Authorize and capture allows you to authorize your buyers' funds before you capture them. An authorization places a hold on the funds and is valid for 29 days.

Know before you code

  • You must be an approved partner to use this integration.
  • You must complete seller onboarding before you use this integration.
  • You must have an access token.
  • This integration is a PCI Compliant - SAQ A solution for accepting credit card payments directly on your website.

1. Change approval intent

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>

2. Create order

Before you authorize funds, you must create an order with the intent field set to AUTHORIZE.

curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <Access-Token>' \
  -H 'PayPal-Partner-Attribution-Id: <BN-Code>' \
  -d '{
  "intent": "AUTHORIZE",
  "purchase_units": [{
    "amount": {
      "currency_code": "USD",
      "value": "100.00"
    },
    "payee": {
      "email_address": "seller@example.com"
    }
  }]
 }'
 var express = require('express');
 var request = require('request');

 express()
     .post('/my-server/create-order', function(req, res) {
         request.post('https://api-m.sandbox.paypal.com/v2/checkout/orders', {
             headers: {
                 Content-Type: "application/json",
                 Authorization: "Bearer <Access-Token>",
                 PayPal-Partner-Attribution-Id: <BN-Code>
             },
             body: {
                 "intent": "AUTHORIZE",
                 "purchase_units": [{
                     "amount": {
                         "currency_code": "USD",
                         "value": "100.00"
                     },
                     "payee": {
                         "email_address": "seller@example.com"
                     }
                 }]
             },
             json: true
         }, function(err, response, body) {
             if (err) {
                 console.error(err);
                 return res.sendStatus(500);
             }

             res.json({
                 id: body.id
             });
         });
     });
  • Use the purchase_units/payee object to specify the end receiver of the funds.

3. Authorize order

After your buyer approves the order, you call authorize order to authorize the buyer's funds.

curl -v -k -X POST https://api-m.paypal.com/v2/checkout/orders/5O190127TN364715T/authorize \
 -H 'PayPal-Partner-Attribution-Id:'<BN-Code>' \
 -H 'Authorization: Bearer <Access-Token>' \
 -H 'Content-Type: application/json' \
 -d '{}'
var express = require('express');
var request = require('request');

express()
     .post('/my-server/handle-approve/:id', function(req, res) {
         var OrderID = req.params.id;
         request.post('https://api-m.sandbox.paypal.com/v2/checkout/orders/' + OrderID + '/authorize', {
             headers: {
                 Content-Type: "application/json",
                 Authorization: "Bearer <Access-Token>",
                 PayPal-Partner-Attribution-Id: <BN-Code>
             }
         }, function(err, response, body) {
             if (err) {
                 console.error(err);
                 return res.sendStatus(500);
             }

             res.json({
                 status: 'success'
             });
         });
     });

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 to APPROVED when the buyer successfully completes the checkout flow.

4. Capture 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/disbursement_mode field to specify when funds should be disbursed to the seller. To capture these funds and hold them before disbursing to the seller, see the Delay Disbursements guide.
  • Use the payment_instruction/platform_fees array to specify any fees you want to collect on this transaction.

See also