Authorize and Capture Payments Integration Guide

DOCS

Last updated: Sept 19th, 6:50pm

Use the Payments API to authorize a payment that you can capture later. For example, you might have a delayed shipment for which you do not want to collect funds right away.

Overview

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.

Within a 29-day authorization period, you can issue multiple reauthorizations after the initial three-day honor period expires.

Day	Action	Authorization period	Honor period
1	Authorization-1	Begins 29-day authorization period	Days 1 through 3
4	Reauthorization-1 on Authorization-1	Within 29-day authorization period	Days 4 through 7
8	Reauthorization-2 on Authorization-1	Within 29-day authorization period	Days 8 through 11

For any payment type, you can capture less than or the full original authorized amount. You can also capture up to 115% of or $75 USD more than the original authorized amount, whichever is less.

You can also complete partial captures during a single authorization period. For PayPal payment authorizations, you must enable this feature on your PayPal account.

Note:

Customers and merchants cannot close accounts that have authorized but not yet captured payments.

You can also authorize payments for orders, which confirms the availability of funds but does not place the funds on hold.

Integration steps


1.	Required	Set up your development environment.
2.	Required	Authorize the payment.
3.	Required only   for   PayPal   payments	Get buyer approval and execute the payment authorization.
4.	Required	Capture the authorized payment.

Set up your development environment

Before you can integrate Payments, you must set up your development environment. After you get a token that lets you access protected REST API resources, you create sandbox accounts to test your web and mobile apps. For details, see Get started.

Then, return to this page to integrate Payments.

Authorize the payment

To authorize a payment to be captured later, create a payment and set the intent to authorize. You can authorize PayPal payments.

This example creates an authorization for a PayPal payment:

1curl -v https://api-m.sandbox.paypal.com/v1/payments/payment \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>" \
4  -d '{
5  "intent": "authorize",
6  "payer":
7  {
8    "payment_method": "paypal"
9  },
10  "transactions": [
11  {
12    "amount":
13    {
14      "total": "30.11",
15      "currency": "USD",
16      "details":
17      {
18        "subtotal": "30.00",
19        "tax": "0.07",
20        "shipping": "0.03",
21        "handling_fee": "1.00",
22        "shipping_discount": "-1.00",
23        "insurance": "0.01"
24      }
25    },
26    "description": "This is the payment transaction description.",
27    "custom": "EBAY_EMS_90048630024435",
28    "invoice_number": "48787589673",
29    "payment_options":
30    {
31      "allowed_payment_method": "INSTANT_FUNDING_SOURCE"
32    },
33    "soft_descriptor": "ECHI5786786",
34    "item_list":
35    {
36      "items": [
37      {
38        "name": "hat",
39        "description": "Brown color hat",
40        "quantity": "5",
41        "price": "3",
42        "tax": "0.01",
43        "sku": "1",
44        "currency": "USD"
45      },
46      {
47        "name": "handbag",
48        "description": "Black color hand bag",
49        "quantity": "1",
50        "price": "15",
51        "tax": "0.02",
52        "sku": "product34",
53        "currency": "USD"
54      }],
55      "shipping_address":
56      {
57        "recipient_name": "Hello World",
58        "line1": "4thFloor",
59        "line2": "unit#34",
60        "city": "SAn Jose",
61        "country_code": "US",
62        "postal_code": "95131",
63        "phone": "011862212345678",
64        "state": "CA"
65      }
66    }
67  }],
68  "note_to_payer": "Contact us for any questions on your order.",
69  "redirect_urls":
70  {
71    "return_url": "https://example.com/return",
72    "cancel_url": "https://example.com/cancel"
73  }
74}'

If the request succeeds, the response includes the payment details. The response also includes:

id. The PayPal-generated ID for the authorization.

state. The state of the authorization, which is either created or failed.

create_time. The date and time when the payment authorization was created.

links. The approval_url and execute links that you use to get buyer approval and execute the payment authorization. After you successfully execute the payment authorization, PayPal responds with a capture link that you use to capture the payment.

1{
2  "id": "PAY-1BP41925BA069714SK6SKIAY",
3  "intent": "authorize",
4  "state": "created",
5  "payer":
6  {
7    "payment_method": "paypal"
8  },
9  "transactions": [
10  {
11    "amount":
12    {
13      "total": "30.11",
14      "currency": "USD",
15      "details":
16      {
17        "subtotal": "30.00",
18        "tax": "0.07",
19        "shipping": "0.03",
20        "insurance": "0.01",
21        "handling_fee": "1.00",
22        "shipping_discount": "-1.00"
23      }
24    },
25    "description": "This is the payment transaction description.",
26    "custom": "EBAY_EMS_90048630024435",
27    "invoice_number": "48787589673",
28    "soft_descriptor": "ECHI5786786",
29    "payment_options":
30    {
31      "allowed_payment_method": "INSTANT_FUNDING_SOURCE",
32      "recurring_flag": false
33    },
34    "item_list":
35    {
36      "items": [
37      {
38        "name": "hat",
39        "sku": "1",
40        "description": "Brown color hat",
41        "price": "3.00",
42        "currency": "USD",
43        "tax": "0.01",
44        "quantity": 5
45      },
46      {
47        "name": "handbag",
48        "sku": "product34",
49        "description": "Black color hand bag",
50        "price": "15.00",
51        "currency": "USD",
52        "tax": "0.02",
53        "quantity": 1
54      }],
55      "shipping_address":
56      {
57        "recipient_name": "Hello World",
58        "line1": "4thFloor",
59        "line2": "unit#34",
60        "city": "SAn Jose",
61        "state": "CA",
62        "postal_code": "95131",
63        "country_code": "US",
64        "phone": "011862212345678"
65      }
66    },
67    "related_resources": []
68  }],
69  "note_to_payer": "Contact us for any questions on your order.",
70  "create_time": "2016-08-05T14:34:42Z",
71  "links": [
72  {
73    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-1BP41925BA069714SK6SKIAY",
74    "rel": "self",
75    "method": "GET"
76  },
77  {
78    "href": "https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_express-checkout&token=EC-511429312Y0182227",
79    "rel": "approval_url",
80    "method": "REDIRECT"
81  },
82  {
83    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-1BP41925BA069714SK6SKIAY/execute",
84    "rel": "execute",
85    "method": "POST"
86  }]
87}

Next, capture an authorized payment.

Test buyer approval in sandbox

To test buyer approval in sandbox:

Navigate to the approval_url given in the HATEOAS links provided in your create order call.

When the checkout flow popup appears, log in using the buyer account created for you when you created your sandbox account.

Make the payment.

Log into PayPal sandbox with your buyer account. You will see the funds transfer from the buyer side.

Log into PayPal sandbox with your facilitator account (also automatically created when you created a sandbox account) and you will see the funds transfer to you from the buyer.

Capture an authorized payment

To capture an authorized payment, include the authorization ID in the URI of the call.

Include the amount that you want to capture in the amount object in the JSON request body. For a partial capture, you can provide a lower amount.

Optionally, set is_final_capture to true to prevent future captures.

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/payments/authorization/9T287484DP554682S/capture \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>" \
4  -d '{
5  "amount": {
6    "currency": "USD",
7    "total": "4.54"
8  },
9  "is_final_capture": true
10}'

The response shows details for the captured payment including links that enable you to complete actions against the captured payment:

1{
2  "id": "6BA17599X0950293U",
3  "create_time": "2017-05-06T22:32:24Z",
4  "update_time": "2017-05-06T22:32:25Z",
5  "amount": {
6    "total": "4.54",
7    "currency": "USD"
8  },
9  "is_final_capture": true,
10  "state": "completed",
11  "parent_payment": "PAY-44664305570317015KGEC5DI",
12  "links": [{
13    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/6BA17599X0950293U",
14    "rel": "self",
15    "method": "GET"
16  }, {
17    "href": "https://api-m.sandbox.paypal.com/v1/payments/capture/6BA17599X0950293U/refund",
18    "rel": "refund",
19    "method": "POST"
20  }, {
21    "href": "https://api-m.sandbox.paypal.com/v1/payments/authorization/5RA45624N3531924N",
22    "rel": "authorization",
23    "method": "GET"
24  }, {
25    "href": "https://api-m.sandbox.paypal.com/v1/payments/payment/PAY-44664305570317015KGEC5DI",
26    "rel": "parent_payment",
27    "method": "GET"
28  }]
29}

You can complete these authorization-related tasks:

Show authorization details

Re-authorize a payment

Void an authorization

Refund a captured payment

Or, learn how to create orders.

Additional information

The REST APIs and HATEOAS

Payments API Reference

Capture payments later

How PayPal uses OAuth 2.0

REST API errors

PayPal REST API Country and Currency Support