Authorize & Capture

APICURRENT

Last updated: Sept 19th, 3:23am

With Payments v2, you can get authorization from your customer and capture the payment later. You can authorize and capture by setting the intent to AUTHORIZE when initiating an order. Some key use cases of this approach are:

Orders that require some processing, like shipping an order, before the customer receives the goods or services purchased.

Transactions that require a hold charge before the merchant can procure and ship the product. You can do a full capture of the authorized amount or multiple partial captures

Situations where you need to charge a customer an additional amount, such as charging for room damages after a customer checks out of a room. Check with your account manager if this is a setting allowed in your country. See PSD2 overcapture requirements for more details.

Know before you code

The Payments API must be used with the Orders v2 API.

See the Orders v2 API reference documentation to learn more about Orders.

See the Payments v2 API reference documentation to learn more about Payments.

Complete the steps in Get Started to setup your developer environment.

Use Postman to explore and test PayPal APIs.

If you are a partner acting on behalf of merchants on your platform, you'll need to include the PayPal-Auth-Assertion header in your API request. You can generate the value according to the following pseudocode. See REST Requests for more information. You'll need to be an approved partner and complete seller onboarding.

1<base64-encoding <span class="hljs-keyword">of</span>-({<span class="hljs-string">"alg"</span>:<span class="hljs-string">"none"</span>})>.<base64-encoding-<span class="hljs-keyword">of</span>-({<span class="hljs-string">"iss"</span>:<span class="hljs-string">"<var>client_id</var>"</span>,<span class="hljs-string">"payer_id"</span>:<span class="hljs-string">"<var>payer_id</var>"</span>})>.

1. Create an order

After you collect the order details from the customer, call the "Create Order" API at /v2/checkout/orders.

Sample API request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ -H "Content-Type: application/json" -H "Authorization: Bearer Access-Token" -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440012" -d '{
2    "intent": "AUTHORIZE",
3    "purchase_units": [
4        {
5            "items": [
6                {
7                    "name": "Red Sweater",
8                    "description": "Cashmere solid red sweater",
9                    "quantity": "1",
10                    "unit_amount": {
11                        "currency_code": "USD",
12                        "value": "200.00"
13                    }
14                }
15            ],
16            "amount": {
17                "currency_code": "USD",
18                "value": "200.00",
19                "breakdown": {
20                    "item_total": {
21                        "currency_code": "USD",
22                        "value": "200.00"
23                    }
24                }
25            }
26        }
27    ],
28    "application_context": {
29        "return_url": "https://example.com",
30        "cancel_url": "https://example.com/cancel"
31    }
32}'

Modify the code

Set the Access Token to one obtained from your Developer Dashboard.

Change PayPal-Request-Id to a unique value, such as GUID, for each order to ensure idempotency.

Update return_url and cancel_url as appropriate.

Update the order items purchase_units array to one or more items based on the order details.

API response

You will get an HTTP 201 Created response. Note the order id in the response body, which will be used in subsequent requests. status indicates the order was CREATED. The links object provides the URL to take your customer through the approval flow, after which the customer will be redirected to the URL provided in the request.

Note: If you did not receive the response, making the same API call without changing anything will result in an HTTP 200 OK with details of the created order.

Sample API response

1{
2    "id": "6YN33669Y5103870B",
3    "intent": "AUTHORIZE",
4    "status": "CREATED",
5    "purchase_units": [
6        {
7            "reference_id": "default",
8            "amount": {
9                "currency_code": "USD",
10                "value": "200.00",
11                "breakdown": {
12                    "item_total": {
13                        "currency_code": "USD",
14                        "value": "200.00"
15                    }
16                }
17            },
18            "payee": {
19                "email_address": "john.snow@example.com",
20                "merchant_id": "8RKYD8PNW5TM4"
21            },
22            "items": [
23                {
24                    "name": "Red Sweater",
25                    "unit_amount": {
26                        "currency_code": "USD",
27                        "value": "200.00"
28                    },
29                    "quantity": "1",
30                    "description": "Cashmere solid red sweater"
31                }
32            ]
33        }
34    ],
35    "create_time": "2022-08-18T17:22:54Z",
36    "links": [
37        {
38            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6YN33669Y5103870B",
39            "rel": "self",
40            "method": "GET"
41        },
42        {
43            "href": "https://www.sandbox.paypal.com/checkoutnow?token=6YN33669Y5103870B",
44            "rel": "approve",
45            "method": "GET"
46        },
47        {
48            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6YN33669Y5103870B",
49            "rel": "update",
50            "method": "PATCH"
51        },
52        {
53            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6YN33669Y5103870B/authorize",
54            "rel": "authorize",
55            "method": "POST"
56        }
57    ]
58}

2. Get payment approval

Now that the order is created, your customer must approve the payment before you can capture it. Upon approval, they will be redirected to the return URL specified in the order creation details.

3. Authorize payment for the order

To authorize the approved payment, call the "Authorize Payment for Order" API at /v2/checkout/orders/{id}/authorize.

Sample API request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/6YN33669Y5103870B/authorize -H "Content-Type: application/json" -H "Authorization: Bearer Access-Token" -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440013" -d '{}'

Modify the code

Set the Access Token to the one you used when you created the order.

Change PayPal-Request-Id to a unique value, such as GUID, for each order to ensure idempotency.

Update path parameter id to the id obtained in the response for order creation.

API response

You will get an HTTP 201 Created response. Note the authorization id within the payments object in the response, which may be used in subsequent requests. Order status will now be updated to COMPLETED, but the payment status will be set to CREATED to indicate the authorization has been created but not yet captured. The payment_source object provides details of the payer's PayPal account and vault information, if applicable.

A couple of important things to note:

An authorization is valid for 29 days after the date of its creation.

Once a payment is authorized, to ensure money is available, it must be captured within the 3 days honor period. If payment is not captured, a reauthorization is necessary.

Note: If you did not receive the response, making the same API call without changing anything will result in an HTTP 200 OK with details of the authorized order.

Sample API response

1{
2    "id": "6YN33669Y5103870B",
3    "intent": "AUTHORIZE",
4    "status": "COMPLETED",
5    "payment_source": {
6        "paypal": {
7            "email_address": "john.snoww@example.com",
8            "account_id": "F3JFJAMKRPAEC",
9            "name": {
10                "given_name": "John",
11                "surname": "Snoww"
12            },
13            "address": {
14                "country_code": "US"
15            }
16        }
17    },
18    "purchase_units": [
19        {
20            "reference_id": "default",
21            "amount": {
22                "currency_code": "USD",
23                "value": "200.00",
24                "breakdown": {
25                    "item_total": {
26                        "currency_code": "USD",
27                        "value": "200.00"
28                    },
29                    "shipping": {
30                        "currency_code": "USD",
31                        "value": "0.00"
32                    },
33                    "handling": {
34                        "currency_code": "USD",
35                        "value": "0.00"
36                    },
37                    "insurance": {
38                        "currency_code": "USD",
39                        "value": "0.00"
40                    },
41                    "shipping_discount": {
42                        "currency_code": "USD",
43                        "value": "0.00"
44                    }
45                }
46            },
47            "payee": {
48                "email_address": "john.snow@example.com",
49                "merchant_id": "8RKYD8PNW5TM4"
50            },
51            "description": "Red Sweater",
52            "items": [
53                {
54                    "name": "Red Sweater",
55                    "unit_amount": {
56                        "currency_code": "USD",
57                        "value": "200.00"
58                    },
59                    "tax": {
60                        "currency_code": "USD",
61                        "value": "0.00"
62                    },
63                    "quantity": "1",
64                    "description": "Cashmere solid red sweater"
65                }
66            ],
67            "shipping": {
68                "name": {
69                    "full_name": "John Snoww"
70                },
71                "address": {
72                    "address_line_1": "1 Main St",
73                    "admin_area_2": "San Jose",
74                    "admin_area_1": "CA",
75                    "postal_code": "95131",
76                    "country_code": "US"
77                }
78            },
79            "payments": {
80                "authorizations": [
81                    {
82                        "status": "CREATED",
83                        "id": "12P54155LA952100L",
84                        "amount": {
85                            "currency_code": "USD",
86                            "value": "200.00"
87                        },
88                        "seller_protection": {
89                            "status": "ELIGIBLE",
90                            "dispute_categories": [
91                                "ITEM_NOT_RECEIVED",
92                                "UNAUTHORIZED_TRANSACTION"
93                            ]
94                        },
95                        "expiration_time": "2022-09-16T17:27:36Z",
96                        "links": [
97                            {
98                                "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/12P54155LA952100L",
99                                "rel": "self",
100                                "method": "GET"
101                            },
102                            {
103                                "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/12P54155LA952100L/capture",
104                                "rel": "capture",
105                                "method": "POST"
106                            },
107                            {
108                                "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/12P54155LA952100L/void",
109                                "rel": "void",
110                                "method": "POST"
111                            },
112                            {
113                                "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/12P54155LA952100L/reauthorize",
114                                "rel": "reauthorize",
115                                "method": "POST"
116                            },
117                            {
118                                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6YN33669Y5103870B",
119                                "rel": "up",
120                                "method": "GET"
121                            }
122                        ],
123                        "create_time": "2022-08-18T17:27:36Z",
124                        "update_time": "2022-08-18T17:27:36Z"
125                    }
126                ]
127            }
128        }
129    ],
130    "payer": {
131        "name": {
132            "given_name": "John",
133            "surname": "Snow"
134        },
135        "email_address": "john.snoww@example.com",
136        "payer_id": "F3JFJAMKRPAEC",
137        "address": {
138            "country_code": "US"
139        }
140    },
141    "create_time": "2022-08-18T17:22:54Z",
142    "update_time": "2022-08-18T17:27:36Z",
143    "links": [
144        {
145            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6YN33669Y5103870B",
146            "rel": "self",
147            "method": "GET"
148        }
149    ]
150}

4. Capture authorized payment

You can either capture the full payment or a partial payment.

Capture the Full Amount

To capture the authorized payment, call the "Capture Authorized Payment" API at /v2/payments/authorizations/{authorization_id}/capture.

Sample API request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/12P54155LA952100L/capture -H "Content-Type: application/json" -H "Authorization: Bearer Access-Token" -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440014" -d '{
2    "amount": {
3        "value": "200",
4        "currency_code": "USD"
5    },
6    "invoice_id": "1660844025",
7    "final_capture": true,
8    "note_to_payer": "If the ordered color is not available, we will substitute with a different color free of charge.",
9    "soft_descriptor": "Bobs sweaters"
10}'

Modify the code

Set the Access Token to the one you used when you authorized the order.

Change PayPal-Request-Id to a unique value, such as GUID, for each order to ensure idempotency.

Update authorization_id to the id obtained from a successful authorization call.

To fully capture a payment, include the appropriate value in the request body and set final_capture to true.

API response

You will get an HTTP 201 Created response. Note the capture id in the response body, which may be used in subsequent requests. Payment status will now be updated to COMPLETED to indicate the payment has been captured.

Note: If you did not receive the response, making the same API call without changing anything will result in an HTTP 200 OK with details of the captured order.

Sample API response

1{
2    "id": "9BS68399VH1254114",
3    "amount": {
4        "currency_code": "USD",
5        "value": "200.00"
6    },
7    "final_capture": true,
8    "seller_protection": {
9        "status": "ELIGIBLE",
10        "dispute_categories": [
11            "ITEM_NOT_RECEIVED",
12            "UNAUTHORIZED_TRANSACTION"
13        ]
14    },
15    "seller_receivable_breakdown": {
16        "gross_amount": {
17            "currency_code": "USD",
18            "value": "200.00"
19        },
20        "paypal_fee": {
21            "currency_code": "USD",
22            "value": "7.47"
23        },
24        "net_amount": {
25            "currency_code": "USD",
26            "value": "192.53"
27        },
28        "exchange_rate": {}
29    },
30    "invoice_id": "1660844025",
31    "status": "COMPLETED",
32    "create_time": "2022-08-18T17:33:46Z",
33    "update_time": "2022-08-18T17:33:46Z",
34    "links": [
35        {
36            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9BS68399VH1254114",
37            "rel": "self",
38            "method": "GET"
39        },
40        {
41            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9BS68399VH1254114/refund",
42            "rel": "refund",
43            "method": "POST"
44        },
45        {
46            "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/12P54155LA952100L",
47            "rel": "up",
48            "method": "GET"
49        }
50    ]
51}

Capture partial payment

To capture the authorized payment, call the "Capture Authorized Payment" API at /v2/payments/authorizations/{authorization_id}/capture.

Sample API request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/payments/authorizations/12P54155LA952100L/capture -H "Content-Type: application/json" -H "Authorization: Bearer Access-Token" -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440015" -d '{
2    "amount": {
3        "value": "100",
4        "currency_code": "USD"
5    },
6    "invoice_id": "1660844025",
7    "final_capture": false,
8    "note_to_payer": "If the ordered color is not available, we will substitute with a different color free of charge.",
9    "soft_descriptor": "Bobs sweaters"
10}'

Modify the code

Set the Access Token to the one you used when you authorized the order.

Change PayPal-Request-Id to a unique value, such as GUID, for each order to ensure idempotency.

Update authorization_id to the id obtained from a successful authorization call.

To partially capture a payment, include the appropriate value in the request body and set final_capture to false.

Note When you make your final capture, ensure the value is set to an amount yet to be captured and update final_capture to true to end the flow.

API response

You will get an HTTP 201 Created response. Note the capture id in the response body, which may be used in subsequent requests. Payment status will now be updated to PARTIALLY_CAPTURED to indicate additional captures are possible for this authorization.

Note: If you did not receive the response, making the same API call without changing anything will result in an HTTP 200 OK with details of the captured order.

Sample API response

1{
2    "id": "9BS68399VH1254114",
3    "amount": {
4        "currency_code": "USD",
5        "value": "100.00"
6    },
7    "final_capture": false,
8    "seller_protection": {
9        "status": "ELIGIBLE",
10        "dispute_categories": [
11            "ITEM_NOT_RECEIVED",
12            "UNAUTHORIZED_TRANSACTION"
13        ]
14    },
15    "seller_receivable_breakdown": {
16        "gross_amount": {
17            "currency_code": "USD",
18            "value": "100.00"
19        },
20        "paypal_fee": {
21            "currency_code": "USD",
22            "value": "3.98"
23        },
24        "net_amount": {
25            "currency_code": "USD",
26            "value": "96.02"
27        },
28        "exchange_rate": {}
29    },
30    "invoice_id": "1660844025",
31    "status": "COMPLETED",
32    "create_time": "2022-08-18T17:33:46Z",
33    "update_time": "2022-08-18T17:33:46Z",
34    "links": [
35        {
36            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9BS68399VH1254114",
37            "rel": "self",
38            "method": "GET"
39        },
40        {
41            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9BS68399VH1254114/refund",
42            "rel": "refund",
43            "method": "POST"
44        },
45        {
46            "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/12P54155LA952100L",
47            "rel": "up",
48            "method": "GET"
49        }
50    ]
51}

5. Search captured payment details

To lookup captured payment details, call the "Show Captured Payment Details" API at /v2/payments/captures/{capture_id}.

Sample API request

1curl -v -X GET https://api-m.sandbox.paypal.com/v2/payments/captures/9BS68399VH1254114 -H "Content-Type: application/json" -H "Authorization: Bearer Access-Token"

Modify the code

Set the Access Token to the one you used when you captured the order.

Update capture-id to the id obtained in the response for payment capture.

API response

You will get an HTTP 200 OK response with details about the captured payment and order id information.

Sample API response

1{
2    "id": "9BS68399VH1254114",
3    "amount": {
4        "currency_code": "USD",
5        "value": "200.00"
6    },
7    "final_capture": true,
8    "seller_protection": {
9        "status": "ELIGIBLE",
10        "dispute_categories": [
11            "ITEM_NOT_RECEIVED",
12            "UNAUTHORIZED_TRANSACTION"
13        ]
14    },
15    "disbursement_mode": "INSTANT",
16    "seller_receivable_breakdown": {
17        "gross_amount": {
18            "currency_code": "USD",
19            "value": "200.00"
20        },
21        "paypal_fee": {
22            "currency_code": "USD",
23            "value": "7.47"
24        },
25        "net_amount": {
26            "currency_code": "USD",
27            "value": "192.53"
28        }
29    },
30    "invoice_id": "1660844025",
31    "status": "COMPLETED",
32    "supplementary_data": {
33        "related_ids": {
34            "order_id": "6YN33669Y5103870B",
35            "authorization_id": "12P54155LA952100L"
36        }
37    },
38    "create_time": "2022-08-18T17:33:46Z",
39    "update_time": "2022-08-18T17:33:46Z",
40    "links": [
41        {
42            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9BS68399VH1254114",
43            "rel": "self",
44            "method": "GET"
45        },
46        {
47            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/9BS68399VH1254114/refund",
48            "rel": "refund",
49            "method": "POST"
50        },
51        {
52            "href": "https://api-m.sandbox.paypal.com/v2/payments/authorizations/12P54155LA952100L",
53            "rel": "up",
54            "method": "GET"
55        }
56    ]
57}