Accept Zip payments/
Accept Zip payments/
Create order

Create order

DocsLimited

Last updated: Oct 24th, 4:58am

Create an order to begin the Zip payment process.

Automatic capture occurs immediately after buyer approval, streamlining the payment process by eliminating the need for manual intervention to complete the transaction.

Automatic flow

Include payment source details directly in the create order request for a streamlined integration.

Use a valid access token and send a POST request to /v2/checkout/orders with request body parameters including intent set to CAPTURE, purchase_units with amount and currency (USD or AUD only), invoice_id (mandatory for Zip), payment_source with Zip details, and processing_instruction set to ORDER_COMPLETE_ON_PAYMENT_APPROVAL.

  1. Sample request
  2. Sample response
1curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <ACCESS_TOKEN>" \
4  -H "PayPal-Request-Id: <UNIQUE_REQUEST_ID>" \
5  -d '{
6  "intent": "CAPTURE",
7  "processing_instruction": "ORDER_COMPLETE_ON_PAYMENT_APPROVAL",
8  "payment_source": {
9    "zip": {
10      "name": {
11        "given_name": "Jim",
12        "surname": "Carrey"
13      },
14      "country_code": "US",
15      "phone": {
16        "country_code": "1",
17        "national_number": "4085551234"
18      },
19      "billing_address": {
20        "address_line_1": "2211 N 1st St.",
21        "admin_area_1": "CA",
22        "admin_area_2": "San Jose",
23        "postal_code": "95131",
24        "country_code": "US"
25      },
26      "experience_context": {
27        "return_url": "https://www.example.com/returnUrl",
28        "cancel_url": "https://www.example.com/cancelUrl"
29      }
30    }
31  },
32  "purchase_units": [
33    {
34      "reference_id": "default",
35      "amount": {
36        "breakdown": {
37            "item_total": {
38                "currency_code": "USD",
39                "value": "34.10"
40            },
41            "tax_total": {
42                "currency_code": "USD",
43                "value": "2.00"
44            }
45        },
46        "currency_code": "USD",
47        "value": "36.10"
48      },
49      "payee": {
50        "merchant_id": "M683SLY6MTM78",
51        "email_address": "destaccount1@hotmail.com"
52      },
53      "custom_id": "Custom-1234",
54      "invoice_id": "Invoice-1760356117",
55      "shipping": {
56        "name": {
57          "full_name": "John Doe"
58        },
59        "address": {
60          "address_line_1": "2211 N 1st St.",
61          "admin_area_1": "CA",
62          "admin_area_2": "San Jose",
63          "postal_code": "95131",
64          "country_code": "US"
65        }
66      },
67      "items": [
68        {
69          "name": "Shirt",
70          "quantity": "1",
71          "supplementary_data": [],
72          "postback_data": [],
73          "unit_amount": {
74            "currency_code": "USD",
75            "value": "12.05"
76          },
77          "tax": {
78            "currency_code": "USD",
79            "value": "1.00"
80          }
81        },
82        {
83          "name": "Trouser",
84          "quantity": "1",
85          "supplementary_data": [],
86          "postback_data": [],
87          "unit_amount": {
88            "currency_code": "USD",
89            "value": "22.05"
90          },
91          "tax": {
92            "currency_code": "USD",
93            "value": "1.00"
94          }
95        }
96      ]
97    }
98  ]
99}'

The response includes the payer-action link to redirect the buyer to Zip.

On successful order creation, complete the Zip payment with these steps:

  1. Review order response: PayPal returns order ID with PAYER_ACTION_REQUIRED status and payer-action link
  2. Redirect your buyer: Send the buyer to the payer-action URL to complete payment on Zip's platform
  3. Monitor payment status: Buyer approves payment and order status automatically changes to COMPLETED
  4. Payment captured: The payment is automatically captured upon buyer approval (no additional capture call needed for Zip)
  5. Notify the buyer: Display order confirmation and send receipt or tracking information to complete the purchase experience.

Request and response parameters

Select a tab to view either the required request parameters or the expected response parameters for partner referrals.

Request parameters

Parameter name Description
intent
Required, string		 Indicates whether payment is captured immediately or authorized for later capture.
processing_instruction
Required, string		 Specifies how the order is processed. Must be set to ORDER_COMPLETE_ON_PAYMENT_APPROVAL for automatic capture.
payment_source
Required, object		 Payment method for the order. Must contain a zip object.
payment_source.zip
Required, object		 Details of the Zip payment method.
payment_source.zip.name
Required, object		 Name of the buyer.
payment_source.zip.name.given_name
Required, string		 First name of the buyer.
payment_source.zip.name.surname
Required, string		 Last name of the buyer.
payment_source.zip.country_code
Required, string		 Country where Zip payment will be processed. Valid values: US (United States) or AU (Australia).
payment_source.zip.phone
Required, object		 Phone number of the buyer.
payment_source.zip.phone.country_code
Required, string		 Country calling code. Valid values: 1 for US, 61 for AU.
payment_source.zip.phone.national_number
Required, string		 National phone number without country code.
payment_source.zip.billing_address
object		 Optional billing address for enhanced fraud screening. When provided, all sub-fields are required.
payment_source.zip.billing_address.address_line_1
Required, string		 Street address of the buyer.
payment_source.zip.billing_address.admin_area_1
Required, string		 State or province code. Valid values: US states (For example, CA, TX) or Australian states.
payment_source.zip.billing_address.admin_area_2
Required, string		 City name of the billing address.
payment_source.zip.billing_address.postal_code
Required, string		 Postal or ZIP code of the billing address.
payment_source.zip.billing_address.country_code
Required, string		 Country code for billing address. Valid values: US or AU.
payment_source.zip.experience_context
Required, object		 Configuration for the buyer's checkout experience.
payment_source.zip.experience_context.return_url
Required, string		 URL to redirect the buyer after payment approval.
payment_source.zip.experience_context.cancel_url
Required, string		 URL to redirect the buyer for cancelled or failed payment.
purchase_units
Required, array		 Array containing purchase details for the order.
purchase_units[].reference_id
string		 Reference ID for the purchase unit. Defaults to default.
purchase_units[].amount
Required, object		 Total amount and currency for the purchase.
purchase_units[].amount.currency_code
Required, string		 Three-character currency code for Zip payments. Valid values: USD (US Dollar) or AUD (Australian Dollar).
purchase_units[].amount.value
Required, string		 Total amount value.
purchase_units[].amount.breakdown
object		 Breakdown of the total amount by category.
purchase_units[].invoice_id
Required, string		 Merchant's invoice number.
purchase_units[].custom_id
string		 Custom identifier for merchant tracking.
purchase_units[].payee
object		 Recipient of the payment.
purchase_units[].shipping
Recommended, object		 Shipping information for the order.
purchase_units[].items
Recommended, array		 Array of line item details for the purchase.
ReferencePayPal.comPrivacyCookiesSupportLegalContact

If you accept cookies, we’ll use them to improve and customize your experience and enable our partners to show you personalized PayPal ads when you visit other sites. Manage cookies and learn more