Accept Zip payments/
Set up

Set up

DocsLimited

Last updated: Oct 29th, 1:38am

You can use the steps in this section to ensure that your accounts and environment are set up to accept Zip payments.

Set up sandbox account

  1. Sign up for a PayPal developer account. On successful signup, PayPal automatically creates your sandbox environment. The sandbox environment mimics real-world transactions and includes a business account by default. You can create additional business accounts as needed.
  2. Set up the sandbox environment:
    1. Go to your PayPal developer account sandbox and toggle to Sandbox.
    2. Go to Apps & Credentials and select Create App.
    3. Enter your app name, set the Type to Merchant, choose the sandbox business account, and select Create App. The app details page will be displayed.
    4. Configure a webhook listener for the app and subscribe to events:
      • In the app details page, go to Sandbox Webhooks.
      • Select Add Webhook.
      • Enter a Webhook URL (your server endpoint for PayPal notifications), select the events to subscribe to, and select Save.
      The webhook listener is now configured, and a Webhook ID is displayed. Store the ID for verification in your app code. For more information, see Use webhooks.
  3. Retrieve sandbox app credentials: To integrate and test Zip payments, you need the following sandbox credentials:
    • Client ID: App identifier for authentication.
    • Client Secret: App credential for authorization.
  4. To retrieve the sandbox credentials:
    • Go to your PayPal developer account and switch to Sandbox.
    • Go to Apps & Credentials > API Credentials > REST API apps.
    • Copy the Client ID and Client Secret listed next to your app name and save them.
  5. Retrieve sandbox account credentials: To test your Zip integration end-to-end, run your app, simulate a checkout flow, log in to your personal PayPal account to approve the Zip payment, and confirm that money is received in your business PayPal account. You need sandbox login credentials for both accounts. For information on accessing or resetting these credentials, see Get sandbox account credentials.
  6. Set up the development environment.

Set up production business account

  1. Log in to the PayPal Developer Dashboard and switch to the Live environment.
  2. Go to Apps & Credentials and create a new app or select an existing app.
  3. In the app's Features tab, ensure Accept payments is enabled.
    • Configure a webhook listener for the app and subscribe to events:
      • On the app details page, go to Live Webhooks.
      • Select Add Webhook.
      • Enter your Webhook URL (the server endpoint where notifications from PayPal are sent), select the events the app wants to subscribe to, and select Save.
      • [Recommended] Subscribe to the following events:
        • CHECKOUT.ORDER.COMPLETED: Successful Zip payment
        • PAYMENT.CAPTURE.DENIED: Failed capture
      • Click Save. A Webhook ID will be generated.
      The webhook listener is successfully configured, and a Webhook ID is displayed. You can store the ID and use it in your app code to verify the source sending messages to your listener. For more information on webhooks, see Use webhooks.
  4. Copy your Client ID and Secret for the live app.
  5. Enable Zip for the production account.

Onboard Afterpay payments

You can enable Zip using one of the following methods:

Enable Zip from your PayPal dashboard

If you have an eligible PayPal business account, you can enable Zip directly from your dashboard:

  1. Log in to your PayPal business account.
  2. Go to Account Settings > Products & Services > Payment Methods.
  3. Find Zip and select Get Started.
  4. Follow the on-screen prompts to complete onboarding and activate Zip payments on your accounts.

Once enabled, go to Payment Options to manage your Zip settings or continue integration.


Request approval to enable Zip

If you don't see Zip in your dashboard, contact your PayPal account manager to enable Zip payments for your business account. Zip payments are activated after PayPal verifies eligibility and completes a compliance review.

Partner information - Onboard merchants

As a partner, you can onboard your merchants to accept Zip as a payment method. You can also build the onboarding process into your software.

Use a valid access token and send a POST request to /v2/customer/partner-referrals with all required request parameters to generate a sign-up link that directs your merchants to PayPal onboarding. Ensure to include your merchant's information in the API call to pre-fill the PayPal sign-up flow.

  1. Sample request
  2. Sample response
1curl -v -X POST https://api-m.sandbox.paypal.com/v2/customer/partner-referrals \
2  -H "Content-Type: application/json" \
3  -H "Authorization: Bearer <Access-Token>" \
4  -H "PayPal-Partner-Attribution-Id: <BN-CODE>" \
5  -d '{
6    "email": "zip+AU3@gmail.com",
7    "preferred_language_code": "en-AU",
8    "tracking_id": "1758136735206",
9    "partner_config_override": {
10        "partner_logo_url": "https://www.paypalobjects.com/webstatic/mktg/logo/pp_cc_mark_111x69.jpg",
11        "return_url": "https://testenterprises.com/merchantonboarded",
12        "return_url_description": "the url to return the merchant after the paypal onboarding process.",
13        "action_renewal_url": "https://testenterprises.com/renew-exprired-url",
14        "show_add_credit_card": true
15    },
16    "individual_owners": [
17        {
18            "names": [
19                {
20                    "prefix": "Mr.",
21                    "given_name": "Jamie",
22                    "surname": "Sun",
23                    "middle_name": "Lark",
24                    "suffix": "Jr.",
25                    "full_name": "Jamie Lark Sun Jr.",
26                    "type": "LEGAL"
27                }
28            ],
29            "citizenship": "AU",
30            "addresses": [
31                {
32                        "address_line_1": "573 Hay St",
33                        "address_line_2": "",
34                        "admin_area_2": "Perth",
35                        "admin_area_1": "Western Australia",
36                        "postal_code": "6000",
37                    "type": "HOME",
38                    "country_code":"AU"
39                }
40            ],
41            "type": "PRIMARY"
42        }
43    ],
44    "business_entity": {
45        "business_type": {
46            "type": "INDIVIDUAL",
47            "subtype": "ASSO_TYPE_INCORPORATED"
48        },
49        "business_industry": {
50            "category": "1004",
51            "mcc_code": "8111",
52            "subcategory": "8931"
53        },
54        "business_incorporation": {
55            "incorporation_country_code": "AU",
56            "incorporation_date": "1986-12-29"
57        },
58        "names": [
59            {
60                "business_name": "Test Enterprise",
61                "type": "LEGAL_NAME"
62            }
63        ],
64        "emails": [
65            {
66                "type": "CUSTOMER_SERVICE",
67                "email": "customerservice@example.com"
68            }
69        ],
70        "website": "https://mystore.testenterprises.com",
71        "addresses": [
72            {
73                       "address_line_1": "573 Hay St",
74                        "address_line_2": "",
75                        "admin_area_2": "Perth",
76                        "admin_area_1": "Western Australia",
77                        "postal_code": "6000",
78                "country_code": "AU",
79                "type": "WORK"
80            }
81        ],
82        "phones": [
83            {
84                "country_code": "1",
85                "national_number": "9177270835",
86                "extension_number": "1234",
87                "type": "CUSTOMER_SERVICE"
88            }
89        ],
90        "beneficial_owners": {
91            "individual_beneficial_owners": [
92                {
93                    "names": [
94                        {
95                            "prefix": "Mr.",
96                            "given_name": "Jaimie",
97                            "surname": "Sun",
98                            "middle_name": "Lark",
99                            "suffix": "Jr.",
100                            "full_name": "Jaimie Lark Sun Jr.",
101                            "type": "LEGAL"
102                        }
103                    ],
104                    "citizenship": "AU",
105                    "addresses": [
106                        {
107                        "address_line_1": "573 Hay St",
108                        "address_line_2": "",
109                        "admin_area_2": "Perth",
110                        "admin_area_1": "Western Australia",
111                        "postal_code": "6000",
112                        "type": "HOME",
113                        "country_code": "AU"
114                        }
115                    ],
116                    "phones": [
117                        {
118                            "country_code": "1",
119                            "national_number": "9177270835",
120                            "extension_number": "1234",
121                            "type": "MOBILE"
122                        }
123                    ],
124                    "birth_details": {
125                        "date_of_birth": "1955-12-29"
126                    },
127                    "percentage_of_ownership": "50"
128                }
129            ],
130            "business_beneficial_owners": [
131                {
132                    "business_type": {
133                        "type": "INDIVIDUAL",
134                        "subtype": "ASSO_TYPE_INCORPORATED"
135                    },
136                    "business_industry": {
137                        "category": "1004",
138                        "mcc_code": "2025",
139                        "subcategory": "8931"
140                    },
141                    "business_incorporation": {
142                        "incorporation_country_code": "AU",
143                        "incorporation_date": "1986-12-29"
144                    },
145                    "names": [
146                        {
147                            "business_name": "Test Enterprise",
148                            "type": "LEGAL_NAME"
149                        }
150                    ],
151                    "emails": [
152                        {
153                            "type": "CUSTOMER_SERVICE",
154                            "email": "customerservice@example.com"
155                        }
156                    ],
157                    "website": "https://mystore.testenterprises.com",
158                    "addresses": [
159                        {
160                       "address_line_1": "573 Hay St",
161                        "address_line_2": "",
162                        "admin_area_2": "Perth",
163                        "admin_area_1": "Western Australia",
164                        "postal_code": "6000",
165                            "country_code": "AU",
166                            "type": "WORK"
167                        }
168                    ],
169                    "phones": [
170                        {
171                            "country_code": "1",
172                            "national_number": "9177270835",
173                            "extension_number": "1234",
174                            "type": "CUSTOMER_SERVICE"
175                        }
176                    ],
177                    "percentage_of_ownership": "50"
178                }
179            ]
180        },
181        "office_bearers": [
182            {
183                "names": [
184                    {
185                        "prefix": "Mr.",
186                        "given_name": "Jamie",
187                        "surname": "Sun",
188                        "middle_name": "Lark",
189                        "suffix": "Jr.",
190                        "full_name": "Jamie Lark Sun Jr.",
191                        "type": "LEGAL"
192                    }
193                ],
194                "citizenship": "AU",
195                "addresses": [
196                    {
197                        "address_line_1": "79 Sheppard Ave",
198                        "address_line_2": "Apt 123",
199                        "admin_area_2": "Toronto",
200                        "admin_area_1": "Ontario",
201                        "postal_code": "M1S 1T4",
202                        "country_code": "AU",
203                        "type": "HOME"
204                    }
205                ],
206                "phones": [
207                    {
208                        "country_code": "1",
209                        "national_number": "4168374117",
210                        "extension_number": "1234",
211                        "type": "MOBILE"
212                    }
213                ],
214                "birth_details": {
215                    "date_of_birth": "1955-12-29"
216                },
217                "role": "DIRECTOR"
218            }
219        ],
220        "annual_sales_volume_range": {
221            "minimum_amount": {
222                "currency_code": "AUD",
223                "value": "10000"
224            },
225            "maximum_amount": {
226                "currency_code": "AUD",
227                "value": "50000"
228            }
229        },
230        "average_monthly_volume_range": {
231            "minimum_amount": {
232                "currency_code": "AUD",
233                "value": "1000"
234            },
235            "maximum_amount": {
236                "currency_code": "AUD",
237                "value": "50000"
238            }
239        },
240        "purpose_code": "P0104"
241    },
242    "operations": [
243        {
244            "operation": "API_INTEGRATION",
245            "api_integration_preference": {
246                "rest_api_integration": {
247                    "integration_method": "PAYPAL",
248                    "integration_type": "THIRD_PARTY",
249                    "third_party_details": {
250                        "features": [
251                            "PAYMENT",
252                            "REFUND"
253                        ]
254                    }
255                }
256            }
257        }
258    ],
259    "products": [
260        "ZIP"
261    ],
262    "legal_consents": [
263        {
264            "type": "SHARE_DATA_CONSENT",
265            "granted": true
266        }
267    ]
268}'

Request and response parameters

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

Parameter name Description
tracking_id
string		 Partner's unique identifier for this merchant. Use this ID to track the status of your merchant as they complete onboarding.
business_entity
Required, object		 Merchant's business details, including type, industry classification, incorporation information, and addresses.
business_entity.business_type
Required, object		 Business structure classification with type and subtype for legal entity identification.
business_entity.business_industry
Required, object		 Industry classification details including category, MCC code, and subcategory for business categorization.
business_entity.business_incorporation
Required, object		 Incorporation information including country code and date of incorporation.
business_entity.names
Required, array		 Business legal name registration for official identification.
business_entity.addresses
Required, array		 Business location details for verification and compliance.
business_entity.annual_sales_volume_range
Required, object		 Expected annual transaction volume range in local currency for risk assessment.
business_entity.average_monthly_volume_range
Required, object		 Expected monthly transaction volume range in local currency for account configuration.
business_entity.purpose_code
Required, string		 Business purpose classification code for regulatory compliance.
operations
Required, array		 API integration preferences and configuration for technical setup.
products
Required, array		 PayPal products to enable for the merchant. For Zip payments, set to ZIP.
legal_consents
Required, array		 Consents received from the merchant. If SHARE_DATA_CONSENT is not granted, PayPal does not store the customer data.

Partner specific information

If you are a platform, pass the build notation (BN) code of the partner in the PayPal-Partner-Attribution-Id header for server-side calls to the Orders API. PayPal uses this information for reporting and tracking purposes. To find your BN code, see Code and Credential Reference.

Onboard merchants using URLs

URL onboarding is a process where merchants are redirected to a specific PayPal sign-up URL to complete their onboarding. Use URL onboarding only if you have previously onboarded merchants with this method or have a specific use case for it.

The URL contains parameters that pre-fill merchant information and configures the onboarding flow for required products. Merchants must complete all required fields and have a PayPal business account to finish onboarding. Casual merchants are not supported.

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