Instant Capture

APICURRENT

Last updated: Sept 19th, 3:24am

With the Payments v2 API, you can instantly capture a payment or get authorization from your customer and capture it at a later time. You can use instant capture in scenarios such as in-store purchase where the goods or services are immediately made available to the customer. You can use instant capture by setting the intent to CAPTURE when initiating an order.

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-426655440010" -d '{
2    "intent": "CAPTURE",
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            ],
17            "amount": {
18                "currency_code": "USD",
19                "value": "100.00",
20                "breakdown": {
21                    "item_total": {
22                        "currency_code": "USD",
23                        "value": "200.00"
24                    }
25                }
26            }
27        }
28    ],
29    "application_context": {
30        "return_url": "https://example.com",
31        "cancel_url": "https://example.com/cancel"
32    }
33}'

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.

Sample 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. The status indicates the order was CREATED. The links object provides the URL to take your customer through the approval flow, after which they 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.

1{
2    "id": "87G58317YM3771105",
3    "intent": "CAPTURE",
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-18T16:37:01Z",
36    "links": [
37        {
38            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/87G58317YM3771105",
39            "rel": "self",
40            "method": "GET"
41        },
42        {
43            "href": "https://www.sandbox.paypal.com/checkoutnow?token=87G58317YM3771105",
44            "rel": "approve",
45            "method": "GET"
46        },
47        {
48            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/87G58317YM3771105",
49            "rel": "update",
50            "method": "PATCH"
51        },
52        {
53            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/87G58317YM3771105/capture",
54            "rel": "capture",
55            "method": "POST"
56        }
57    ]
58}

2. Get payment approval

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

3. Capture payment

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

Sample API request

1curl -v -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/87G58317YM3771105/capture -H "Content-Type: application/json" -H "Authorization: Bearer Access-Token" -H "PayPal-Request-Id: 123e4567-e89b-12d3-a456-426655440011" -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 capture id within the payments object in the response, which may be used in subsequent requests. The order and the payment status is updated to COMPLETED to indicate the payment is captured and the order completed. The payment_source object provides details of the payer's PayPal account and vault information, if applicable.

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.

1{
2    "id": "87G58317YM3771105",
3    "intent": "CAPTURE",
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 Snow"
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                "captures": [
81                    {
82                        "id": "32G741949K374372X",
83                        "status": "COMPLETED",
84                        "amount": {
85                            "currency_code": "USD",
86                            "value": "200.00"
87                        },
88                        "final_capture": true,
89                        "seller_protection": {
90                            "status": "ELIGIBLE",
91                            "dispute_categories": [
92                                "ITEM_NOT_RECEIVED",
93                                "UNAUTHORIZED_TRANSACTION"
94                            ]
95                        },
96                        "seller_receivable_breakdown": {
97                            "gross_amount": {
98                                "currency_code": "USD",
99                                "value": "200.00"
100                            },
101                            "paypal_fee": {
102                                "currency_code": "USD",
103                                "value": "7.47"
104                            },
105                            "net_amount": {
106                                "currency_code": "USD",
107                                "value": "192.53"
108                            }
109                        },
110                        "links": [
111                            {
112                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/32G741949K374372X",
113                                "rel": "self",
114                                "method": "GET"
115                            },
116                            {
117                                "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/32G741949K374372X/refund",
118                                "rel": "refund",
119                                "method": "POST"
120                            },
121                            {
122                                "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/87G58317YM3771105",
123                                "rel": "up",
124                                "method": "GET"
125                            }
126                        ],
127                        "create_time": "2022-08-18T17:06:24Z",
128                        "update_time": "2022-08-18T17:06:24Z"
129                    }
130                ]
131            }
132        }
133    ],
134    "payer": {
135        "name": {
136            "given_name": "John",
137            "surname": "Snow"
138        },
139        "email_address": "john.snow@personal.example.com",
140        "payer_id": "F3JFJAMKRPAEC",
141        "address": {
142            "country_code": "US"
143        }
144    },
145    "create_time": "2022-08-18T16:37:01Z",
146    "update_time": "2022-08-18T17:06:24Z",
147    "links": [
148        {
149            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/87G58317YM3771105",
150            "rel": "self",
151            "method": "GET"
152        }
153    ]
154}

4. Search captured payment details

To look up 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/32G741949K374372X -H "Content-Type: application/json" -H "Authorization: Bearer Access-Token"

Modify the code

Set the Access Token to the one you used when you created 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.

1{
2    "id": "32G741949K374372X",
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    },
29    "status": "COMPLETED",
30    "supplementary_data": {
31        "related_ids": {
32            "order_id": "87G58317YM3771105"
33        }
34    },
35    "create_time": "2022-08-18T17:06:24Z",
36    "update_time": "2022-08-18T17:06:24Z",
37    "links": [
38        {
39            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/32G741949K374372X",
40            "rel": "self",
41            "method": "GET"
42        },
43        {
44            "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/32G741949K374372X/refund",
45            "rel": "refund",
46            "method": "POST"
47        },
48        {
49            "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/87G58317YM3771105",
50            "rel": "up",
51            "method": "GET"
52        }
53    ]
54}

Next Steps

Refund payments

Testing

Test and go live with this integration.

Complete production onboarding to be eligible to process cards with your live PayPal account.

Remember to swap the credentials and API URL from sandbox to production when going live with your integration.

Additional Information

REST APIs and HATEOAS

Payments v2 API

Orders v2 API

REST API Responses

PayPal REST API Country and Currency Support