Batch API Integration

DOCS

Last updated: Sept 24th, 4:24pm

Important: The PayPal Batch API is available as a limited-release API to select merchants and partners. Use this API to make batch requests to the /v2/checkout/orders, v1/payments/payment, and /v2/payments endpoints.

You can make both non-dependent and dependent batch requests to PayPal's server:

Non-dependent batch requests do not support dependencies between batch operations.

Dependent batch requests support dependencies between two operations.

Set up your development environment

Before you can integrate Batch, 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 Batch.

Non-dependent batch requests

The simplest way to process REST API operations in a batch request is to make a non-dependent batch request. The batch request contains multiple independent API operations. Each operation has its own headers, path, method, and request body.

The PayPal batch server returns the response of the batch request as a single-wrapped response only after receiving responses for individual independent operations.

This example batch request captures two individual authorized payments by running a POST on v2/checkout/orders with each operation having a unique bulk ID:

Example non-dependent request

1curl -X POST \
2  https://api-m.sandbox.paypal.com/v1/apis/batch \
3  -H "Content-Type: application/json" \
4  -H "Authorization: Bearer <Access-Token>" \
5  -d '{
6  "operations": [
7  {
8    "method": "POST",
9    "path": "v2/checkout/orders",
10    "headers": [
11    {
12      "name": "Authorization",
13      "value": "BASIC cHNzLXRnaWYtY2xpZW50OnNlY3JldA=="
14    },
15    {
16      "name": "Accept",
17      "value": "application/json"
18    }],
19    "bulk_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
20    "body": {
21      "intent": "CAPTURE",
22      "application_context": {
23        "return_url": "https://example.com/return",
24        "cancel_url": "https://example.com/cancel"
25      },
26      "purchase_units": [
27      {
28        "reference_id": "123",
29        "amount": {
30          "currency_code": "USD",
31          "value": "12.00"
32        }
33      }]
34    }
35  },
36  {
37    "method": "POST",
38    "path": "v2/checkout/orders",
39    "headers": [
40    {
41      "name": "Authorization",
42      "value": "BASIC cHNzLXRnaWYtY2xpZW50OnNlY3JldA=="
43    },
44    {
45      "name": "Accept",
46      "value": "application/json"
47    }],
48    "bulk_id": "f91d4fae-7dec-11d0-a765-00a0c91e6bf6",
49    "body": {
50      "intent": "CAPTURE",
51      "application_context": {
52        "return_url": "https://example.com/return",
53        "cancel_url": "https://example.com/cancel"
54      },
55      "purchase_units": [
56      {
57        "reference_id": "123",
58        "amount": {
59          "currency_code": "USD",
60          "value": "12.00"
61        }
62      }]
63    }
64  }]
65}'

After PayPal processes the batch request, it returns the response with status codes for each operation in the batch request.

Example non-dependent response

1{
2  "operations": [
3  {
4    "method": "POST",
5    "bulk_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
6    "path": "v2/checkout/orders",
7    "headers": [
8    {
9      "name": "Content-Length",
10      "value": "501"
11    },
12    {
13      "name": "Content-Type",
14      "value": "application/json"
15    },
16    {
17      "name": "paypal-debug-id",
18      "value": "76820def796b3"
19    },
20    {
21      "name": "Date",
22      "value": "Thu, 16 Aug 2018 20:40:13 GMT"
23    }],
24    "body": {
25      "id": "5BY1070253943650R",
26      "links": [
27      {
28        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5BY1070253943650R",
29        "rel": "self",
30        "method": "GET"
31      },
32      {
33        "href": "https://api-m.sandbox.paypal.com/checkoutnow?token=5BY1070253943650R",
34        "rel": "approve",
35        "method": "GET"
36      },
37      {
38        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5BY1070253943650R/capture",
39        "rel": "capture",
40        "method": "POST"
41      }],
42      "status": "CREATED"
43    },
44    "status": {
45      "code": "201"
46    }
47  },
48  {
49    "method": "POST",
50    "bulk_id": "x81d4fae-7dec-11d0-a765-00a0c91e6bf6",
51    "path": "v2/checkout/orders",
52    "headers": [
53    {
54      "name": "Content-Length",
55      "value": "501"
56    },
57    {
58      "name": "Content-Type",
59      "value": "application/json"
60    },
61    {
62      "name": "paypal-debug-id",
63      "value": "76820def796b3"
64    },
65    {
66      "name": "Date",
67      "value": "Thu, 16 Aug 2018 20:40:15 GMT"
68    }],
69    "body": {
70      "id": "8J656500H3487814U",
71      "links": [
72      {
73        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/8J656500H3487814U",
74        "rel": "self",
75        "method": "GET"
76      },
77      {
78        "href": "https://api-m.sandbox.paypal.com/checkoutnow?token=8J656500H3487814U",
79        "rel": "approve",
80        "method": "GET"
81      },
82      {
83        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/8J656500H3487814U/capture",
84        "rel": "capture",
85        "method": "POST"
86      }],
87      "status": "CREATED"
88    },
89    "status": {
90      "code": "201"
91    }
92  }]
93}

Dependent batch requests

Dependent batch requests contain multiple API operations that are dependent on each other. For example, the output of one operation might be passed as input to another operation in the batch request.

Request

This example dependent batch request creates and authorizes the order within a single batch request.

1curl -v -X POST https://api-m.sandbox.paypal.com/v1/apis/batch \
2  -H "Authorization: Bearer <Access-Token>" \
3  -H "content-type: application/json" \
4  -d '{
5  "process_in_sequence": false,
6  "operations": [
7  {
8    "method": "POST",
9    "path": "v2/checkout/orders",
10    "headers": [
11    {
12      "name": "Authorization",
13      "value": "BASIC cHNzLXRnaWYtY2xpZW50OnNlY3JldA=="
14    },
15    {
16      "name": "Accept",
17      "value": "application/json"
18    }],
19    "bulk_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
20    "body": {
21      "intent": "CAPTURE",
22      "application_context": {
23        "return_url": "https://example.com/return",
24        "cancel_url": "https://example.com/cancel"
25      },
26      "purchase_units": [
27      {
28        "reference_id": "123",
29        "amount": {
30          "currency_code": "USD",
31          "value": "12.00"
32        }
33      }]
34    }
35  },
36  {
37    "method": "POST",
38    "path": "v2/checkout/orders/{bulk_id:f81d4fae-7dec-11d0-a765-00a0c91e6bf6}/capture",
39    "bulk_id": "499a50fc-4437-11e8-842f-0ed5f89f718b",
40    "headers": [
41    {
42      "name": "Authorization",
43      "value": "Basic cHNzLXRnaWYtY2xpZW50OnNlY3JldA=="
44    }],
45    "body": {
46      "payment_source": {
47        "token": {
48          "type": "BILLING_AGREEMENT",
49          "id": "B-61T235868M773844X"
50        }
51      }
52    }
53  }]
54}'

In the previous example, after the parent POST operation succeeds, it creates a new order. However, if the parent POST operation fails, the child operation that authorizes the created order does not execute.

The parent and child operations each have unique bulk IDs. Use these bulk IDs to define the dependency between the parent and child operations.

A child operation specifies its parent operation's bulk ID in its path.

Response

1{
2  "operations": [
3  {
4    "method": "POST",
5    "bulk_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",
6    "path": "v2/checkout/orders",
7    "headers": [
8    {
9      "name": "Content-Length",
10      "value": "501"
11    },
12    {
13      "name": "Content-Type",
14      "value": "application/json"
15    },
16    {
17      "name": "paypal-debug-id",
18      "value": "51e1005b4380f"
19    },
20    {
21      "name": "Date",
22      "value": "Thu, 16 Aug 2018 20:36:41 GMT"
23    }],
24    "body": {
25      "id": "5RX73713XN478811H",
26      "links": [
27      {
28        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5RX73713XN478811H",
29        "rel": "self",
30        "method": "GET"
31      },
32      {
33        "href": "https://api-m.sandbox.paypal.com/checkoutnow?token=5RX73713XN478811H",
34        "rel": "approve",
35        "method": "GET"
36      },
37      {
38        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5RX73713XN478811H/capture",
39        "rel": "capture",
40        "method": "POST"
41      }],
42      "status": "CREATED"
43    },
44    "status": {
45      "code": "201"
46    }
47  },
48  {
49    "method": "POST",
50    "bulk_id": "499a50fc-4437-11e8-842f-0ed5f89f718b",
51    "path": "v2/checkout/orders/5RX73713XN478811H/capture",
52    "headers": [
53    {
54      "name": "Content-Length",
55      "value": "447"
56    },
57    {
58      "name": "Content-Type",
59      "value": "application/json"
60    },
61    {
62      "name": "paypal-debug-id",
63      "value": "51e1005b4380f"
64    },
65    {
66      "name": "Date",
67      "value": "Thu, 16 Aug 2018 20:36:47 GMT"
68    }],
69    "body": {
70      "id": "5UR40004BE990964A",
71      "purchase_units": [
72      {
73        "reference_id": "123",
74        "payments": {
75          "captures": [
76          {
77            "id": "4GA51238M87633122",
78            "status": "COMPLETED",
79            "amount": {
80              "currency_code": "USD",
81              "value": "12.00"
82            },
83            "final_capture": true,
84            "seller_protection": {
85              "status": "ELIGIBLE",
86              "dispute_categories": ["ITEM_NOT_RECEIVED", "UNAUTHORIZED_TRANSACTION"]
87            },
88            "seller_receivable_breakdown": {
89              "gross_amount": {
90                "currency_code": "USD",
91                "value": "12.00"
92              },
93              "paypal_fee": {
94                "currency_code": "USD",
95                "value": "0.65"
96              },
97              "net_amount": {
98                "currency_code": "USD",
99                "value": "11.35"
100              }
101            },
102            "links": [
103            {
104              "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/4GA51238M87633122",
105              "rel": "self",
106              "method": "GET"
107            },
108            {
109              "href": "https://api-m.sandbox.paypal.com/v2/payments/captures/4GA51238M87633122/refund",
110              "rel": "refund",
111              "method": "POST"
112            }],
113            "create_time": "2018-07-31T06:34:07Z",
114            "update_time": "2018-07-31T06:34:07Z"
115          }]
116        }
117      }],
118      "payer": {
119        "name": {
120          "given_name": "Daphne",
121          "surname": "Anthony"
122        },
123        "email_address": "payer@example.com",
124        "payer_id": "GRPGMSW8EDQBJ",
125        "address": {
126          "address_line_1": "030268 Dodd Street",
127          "address_line_2": "6445723 E Roosevelt",
128          "admin_area_2": "Klamath Falls",
129          "admin_area_1": "OR",
130          "postal_code": "97601",
131          "country_code": "US"
132        }
133      },
134      "links": [
135      {
136        "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/5UR40004BE990964A",
137        "rel": "self",
138        "method": "GET"
139      }],
140      "status": "COMPLETED"
141    },
142    "status": {
143      "code": "201"
144    }
145  }]
146}

The response includes the outputs for both the parent and dependent operations.