Batch API How To
DOCS
Last updated: Sept 24th, 4:52pm
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.
Create, partially update, and show details for a payment
Sample request
1curl -X POST \2 https://api-m.sandbox.paypal.com/v1/apis/batch \3 -H "Authorization: Bearer <Access-Token>" \4 -H "content-type: application/json" \5 -d '{6 "process_in_sequence": true,7 "operations": [8 {9 "method": "POST",10 "path": "v1/payments/payment",11 "headers": [12 {13 "name": "Authorization",14 "value": "BASIC cHNzLXRnaWYtY2xpZW50OnNlY3JldA=="15 },16 {17 "name": "Accept",18 "value": "application/json"19 }],20 "bulk_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",21 "body": {22 "intent": "sale",23 "payer": {24 "payment_method": "paypal"25 },26 "transactions": [27 {28 "amount": {29 "total": "30.11",30 "currency": "USD",31 "details": {32 "subtotal": "30.00",33 "tax": "0.07",34 "shipping": "0.03",35 "handling_fee": "1.00",36 "shipping_discount": "-1.00",37 "insurance": "0.01"38 }39 },40 "description": "The payment transaction description.",41 "custom": "EBAY_EMS_90048630024435",42 "invoice_number": "48787589673",43 "payment_options": {44 "allowed_payment_method": "INSTANT_FUNDING_SOURCE"45 },46 "soft_descriptor": "ECHI5786786",47 "item_list": {48 "items": [49 {50 "name": "hat",51 "description": "Brown hat.",52 "quantity": "5",53 "price": "3",54 "tax": "0.01",55 "sku": "1",56 "currency": "USD"57 },58 {59 "name": "handbag",60 "description": "Black handbag.",61 "quantity": "1",62 "price": "15",63 "tax": "0.02",64 "sku": "product34",65 "currency": "USD"66 }],67 "shipping_address": {68 "recipient_name": "Brian Robinson",69 "line1": "4th Floor",70 "line2": "Unit #34",71 "city": "San Jose",72 "country_code": "US",73 "postal_code": "95131",74 "phone": "011862212345678",75 "state": "CA"76 }77 }78 }],79 "note_to_payer": "Contact us for any questions on your order.",80 "redirect_urls": {81 "return_url": "https://example.com/return",82 "cancel_url": "https://example.com/cancel"83 }84 }85 },86 {87 "method": "PATCH",88 "path": "v1/payments/payment/{bulk_id:f81d4fae-7dec-11d0-a765-00a0c91e6bf6}",89 "headers": [90 {91 "name": "Authorization",92 "value": "BASIC cHNzLXRnaWYtY2xpZW50OnNlY3JldA=="93 },94 {95 "name": "Accept",96 "value": "application/json"97 }],98 "bulk_id": "f91d4fae-7dec-11d0-a765-00a0c91e6bf6",99 "body": [100 {101 "op": "add",102 "path": "/transactions/0/item_list/shipping_address",103 "value": {104 "recipient_name": "Anna Gruneberg",105 "line1": "Kathwarinenhof 1",106 "city": "Flensburg",107 "postal_code": "24939",108 "country_code": "DE"109 }110 }]111 },112 {113 "method": "GET",114 "path": "v1/payments/payment/{bulk_id:f81d4fae-7dec-11d0-a765-00a0c91e6bf6}",115 "headers": [116 {117 "name": "Authorization",118 "value": "BASIC cHNzLXRnaWYtY2xpZW50OnNlY3JldA=="119 },120 {121 "name": "Accept",122 "value": "application/json"123 }],124 "bulk_id": "b81d4fae-7dec-11d0-a765-00a0c91e6bf6",125 "body": {}126 }]127}'
Sample response
1{2 "operations": [3 {4 "method": "POST",5 "bulk_id": "f81d4fae-7dec-11d0-a765-00a0c91e6bf6",6 "path": "v1/payments/payment",7 "headers": [8 {9 "name": "Content-Length",10 "value": "1548"11 },12 {13 "name": "Content-Type",14 "value": "application/json;charset=UTF-8"15 },16 {17 "name": "paypal-debug-id",18 "value": "daabcb47406bd"19 },20 {21 "name": "Date",22 "value": "Fri, 17 Aug 2018 23:57:55 GMT"23 }],24 "body": {25 "id": "PAY-7RB82972EF486783CLN3WCBA",26 "intent": "sale",27 "state": "created",28 "payer": {29 "payment_method": "paypal"30 },31 "transactions": [32 {33 "amount": {34 "total": "30.11",35 "currency": "USD",36 "details": {37 "subtotal": "30.00",38 "tax": "0.07",39 "shipping": "0.03",40 "insurance": "0.01",41 "handling_fee": "1.00",42 "shipping_discount": "-1.00"43 }44 },45 "description": "The payment transaction description.",46 "custom": "EBAY_EMS_90048630024435",47 "invoice_number": "48787589673",48 "soft_descriptor": "ECHI5786786",49 "payment_options": {50 "allowed_payment_method": "INSTANT_FUNDING_SOURCE",51 "recurring_flag": false,52 "skip_fmf": false53 },54 "item_list": {55 "items": [56 {57 "name": "hat",58 "sku": "1",59 "description": "Brown hat.",60 "price": "3.00",61 "currency": "USD",62 "tax": "0.01",63 "quantity": 564 },65 {66 "name": "handbag",67 "sku": "product34",68 "description": "Black handbag.",69 "price": "15.00",70 "currency": "USD",71 "tax": "0.02",72 "quantity": 173 }],74 "shipping_address": {75 "recipient_name": "Brian Robinson",76 "line1": "4th Floor",77 "line2": "Unit #34",78 "city": "San Jose",79 "state": "CA",80 "postal_code": "95131",81 "country_code": "US",82 "phone": "011862212345678"83 }84 },85 "related_resources": []86 }],87 "note_to_payer": "Contact us for any questions on your order.",88 "create_time": "2018-08-17T23:57:55Z",89 "links": [90 {91 "href": "https://www.${stage_domain}:11888/v1/payments/payment/PAY-7RB82972EF486783CLN3WCBA",92 "rel": "self",93 "method": "GET"94 },95 {96 "href": "https://www.${stage_domain}/cgi-bin/webscr?cmd=_express-checkout&token=EC-7W003348WG176631E",97 "rel": "approval_url",98 "method": "REDIRECT"99 },100 {101 "href": "https://www.${stage_domain}:11888/v1/payments/payment/PAY-7RB82972EF486783CLN3WCBA/execute",102 "rel": "execute",103 "method": "POST"104 }]105 },106 "status": {107 "code": "201"108 }109 },110 {111 "method": "PATCH",112 "bulk_id": "f91d4fae-7dec-11d0-a765-00a0c91e6bf6",113 "path": "v1/payments/payment/PAY-7RB82972EF486783CLN3WCBA",114 "headers": [115 {116 "name": "Content-Length",117 "value": "1727"118 },119 {120 "name": "Content-Type",121 "value": "application/json;charset=UTF-8"122 },123 {124 "name": "paypal-debug-id",125 "value": "daabcb47406bd"126 },127 {128 "name": "Date",129 "value": "Fri, 17 Aug 2018 23:57:56 GMT"130 }],131 "body": {132 "id": "PAY-7RB82972EF486783CLN3WCBA",133 "intent": "sale",134 "state": "created",135 "cart": "7W003348WG176631E",136 "payer": {137 "payment_method": "paypal",138 "payer_info": {}139 },140 "transactions": [141 {142 "amount": {143 "total": "30.11",144 "currency": "USD",145 "details": {146 "subtotal": "30.00",147 "tax": "0.07",148 "shipping": "0.03",149 "insurance": "0.01",150 "handling_fee": "1.00",151 "shipping_discount": "-1.00"152 }153 },154 "payee": {155 "merchant_id": "WDMEWZ63SR74G",156 "email": "[email protected]"157 },158 "description": "The payment transaction description.",159 "custom": "EBAY_EMS_90048630024435",160 "invoice_number": "48787589673",161 "soft_descriptor": "ECHI5786786",162 "item_list": {163 "items": [164 {165 "name": "hat",166 "sku": "1",167 "description": "Brown hat.",168 "price": "3.00",169 "currency": "USD",170 "tax": "0.01",171 "quantity": 5172 },173 {174 "name": "handbag",175 "sku": "product34",176 "description": "Black handbag.",177 "price": "15.00",178 "currency": "USD",179 "tax": "0.02",180 "quantity": 1181 }],182 "shipping_address": {183 "recipient_name": "Anna Gruneberg",184 "line1": "Kathwarinenhof 1",185 "city": "Flensburg",186 "postal_code": "24939",187 "country_code": "DE"188 },189 "shipping_phone_number": "011862212345678"190 },191 "related_resources": []192 }],193 "note_to_payer": "Contact us for any questions on your order.",194 "redirect_urls": {195 "return_url": "https://example.com/return?paymentId=PAY-7RB82972EF486783CLN3WCBA",196 "cancel_url": "https://example.com/cancel"197 },198 "create_time": "2018-08-17T23:57:55Z",199 "update_time": "2018-08-17T23:57:56Z",200 "links": [201 {202 "href": "https://www.${stage_domain}:11888/v1/payments/payment/PAY-7RB82972EF486783CLN3WCBA",203 "rel": "self",204 "method": "GET"205 },206 {207 "href": "https://www.${stage_domain}:11888/v1/payments/payment/PAY-7RB82972EF486783CLN3WCBA/execute",208 "rel": "execute",209 "method": "POST"210 },211 {212 "href": "https://www.${stage_domain}/cgi-bin/webscr?cmd=_express-checkout&token=EC-7W003348WG176631E",213 "rel": "approval_url",214 "method": "REDIRECT"215 }]216 },217 "status": {218 "code": "200"219 }220 },221 {222 "method": "GET",223 "bulk_id": "b81d4fae-7dec-11d0-a765-00a0c91e6bf6",224 "path": "v1/payments/payment/PAY-7RB82972EF486783CLN3WCBA",225 "headers": [226 {227 "name": "Content-Length",228 "value": "1727"229 },230 {231 "name": "Content-Type",232 "value": "application/json;charset=UTF-8"233 },234 {235 "name": "paypal-debug-id",236 "value": "daabcb47406bd"237 },238 {239 "name": "Date",240 "value": "Fri, 17 Aug 2018 23:57:56 GMT"241 }],242 "body": {243 "id": "PAY-7RB82972EF486783CLN3WCBA",244 "intent": "sale",245 "state": "created",246 "cart": "7W003348WG176631E",247 "payer": {248 "payment_method": "paypal",249 "payer_info": {}250 },251 "transactions": [252 {253 "amount": {254 "total": "30.11",255 "currency": "USD",256 "details": {257 "subtotal": "30.00",258 "tax": "0.07",259 "shipping": "0.03",260 "insurance": "0.01",261 "handling_fee": "1.00",262 "shipping_discount": "-1.00"263 }264 },265 "payee": {266 "merchant_id": "WDMEWZ63SR74G",267 "email": "[email protected]"268 },269 "description": "The payment transaction description.",270 "custom": "EBAY_EMS_90048630024435",271 "invoice_number": "48787589673",272 "soft_descriptor": "ECHI5786786",273 "item_list": {274 "items": [275 {276 "name": "hat",277 "sku": "1",278 "description": "Brown hat.",279 "price": "3.00",280 "currency": "USD",281 "tax": "0.01",282 "quantity": 5283 },284 {285 "name": "handbag",286 "sku": "product34",287 "description": "Black handbag.",288 "price": "15.00",289 "currency": "USD",290 "tax": "0.02",291 "quantity": 1292 }],293 "shipping_address": {294 "recipient_name": "Anna Gruneberg",295 "line1": "Kathwarinenhof 1",296 "city": "Flensburg",297 "postal_code": "24939",298 "country_code": "DE"299 },300 "shipping_phone_number": "011862212345678"301 },302 "related_resources": []303 }],304 "note_to_payer": "Contact us for any questions on your order.",305 "redirect_urls": {306 "return_url": "https://example.com/return?paymentId=PAY-7RB82972EF486783CLN3WCBA",307 "cancel_url": "https://example.com/cancel"308 },309 "create_time": "2018-08-17T23:57:56Z",310 "update_time": "2018-08-17T23:57:57Z",311 "links": [312 {313 "href": "https://www.${stage_domain}:11888/v1/payments/payment/PAY-7RB82972EF486783CLN3WCBA",314 "rel": "self",315 "method": "GET"316 },317 {318 "href": "https://www.${stage_domain}:11888/v1/payments/payment/PAY-7RB82972EF486783CLN3WCBA/execute",319 "rel": "execute",320 "method": "POST"321 },322 {323 "href": "https://www.${stage_domain}/cgi-bin/webscr?cmd=_express-checkout&token=EC-7W003348WG176631E",324 "rel": "approval_url",325 "method": "REDIRECT"326 }]327 },328 "status": {329 "code": "200"330 }331 }]332}
Create, partially update, and show details for an order
Sample 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": true,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": "PATCH",38 "path": "v2/checkout/orders/{bulk_id:f81d4fae-7dec-11d0-a765-00a0c91e6bf6}",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 {51 "op": "replace",52 "path": "/purchase_units/@reference_id=='\''123'\''/amount",53 "value": {54 "currency_code": "USD",55 "value": "95.00"56 }57 }]58 },59 {60 "method": "GET",61 "path": "v2/checkout/orders/{bulk_id:f81d4fae-7dec-11d0-a765-00a0c91e6bf6}",62 "headers": [63 {64 "name": "Authorization",65 "value": "BASIC cHNzLXRnaWYtY2xpZW50OnNlY3JldA=="66 },67 {68 "name": "Accept",69 "value": "application/json"70 }],71 "bulk_id": "b81d4fae-7dec-11d0-a765-00a0c91e6bf6",72 "body": {}73 }]74}'
Sample 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": "f6ceb74747ddc"19 },20 {21 "name": "Date",22 "value": "Thu, 16 Aug 2018 23:31:38 GMT"23 }],24 "body": {25 "id": "6JB80285LY756971Y",26 "links": [27 {28 "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6JB80285LY756971Y",29 "rel": "self",30 "method": "GET"31 },32 {33 "href": "https://api-m.sandbox.paypal.com/checkoutnow?token=6JB80285LY756971Y",34 "rel": "approve",35 "method": "GET"36 },37 {38 "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6JB80285LY756971Y/capture",39 "rel": "capture",40 "method": "POST"41 }],42 "status": "CREATED"43 },44 "status": {45 "code": "201"46 }47 },48 {49 "method": "PATCH",50 "bulk_id": "f91d4fae-7dec-11d0-a765-00a0c91e6bf6",51 "path": "v2/checkout/orders/6JB80285LY756971Y",52 "headers": [53 {54 "name": "paypal-debug-id",55 "value": "f6ceb74747ddc"56 },57 {58 "name": "Date",59 "value": "Thu, 16 Aug 2018 23:31:38 GMT"60 }],61 "status": {62 "code": "204"63 }64 },65 {66 "method": "GET",67 "bulk_id": "b81d4fae-7dec-11d0-a765-00a0c91e6bf6",68 "path": "v2/checkout/orders/6JB80285LY756971Y",69 "headers": [70 {71 "name": "Content-Length",72 "value": "757"73 },74 {75 "name": "Content-Type",76 "value": "application/json"77 },78 {79 "name": "paypal-debug-id",80 "value": "f6ceb74747ddc"81 },82 {83 "name": "Date",84 "value": "Thu, 16 Aug 2018 23:31:38 GMT"85 }],86 "body": {87 "id": "6JB80285LY756971Y",88 "intent": "CAPTURE",89 "gross_amount": {90 "currency_code": "USD",91 "value": "95.00"92 },93 "purchase_units": [94 {95 "reference_id": "123",96 "amount": {97 "currency_code": "USD",98 "value": "95.00"99 },100 "payee": {101 "email_address": "[email protected]"102 }103 }],104 "create_time": "2018-08-16T23:31:37Z",105 "links": [106 {107 "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6JB80285LY756971Y",108 "rel": "self",109 "method": "GET"110 },111 {112 "href": "https://api-m.sandbox.paypal.com/checkoutnow?token=6JB80285LY756971Y",113 "rel": "approve",114 "method": "GET"115 },116 {117 "href": "https://api-m.sandbox.paypal.com/v2/checkout/orders/6JB80285LY756971Y/capture",118 "rel": "capture",119 "method": "POST"120 }],121 "status": "CREATED"122 },123 "status": {124 "code": "200"125 }126 }]127}