Zip Data Source

The Zip connector enables you to ingest payment, checkout, dispute, and settlement data from your Zip merchant account into Nexla for analysis, reporting, and downstream processing. Follow the instructions below to create a new data flow that ingests data from a Zip source in Nexla.

Zip

Create a New Data Flow

1. To create a new data flow, navigate to the Integrate section, and click the New Data Flow button. Then, select the desired flow type from the list, and click the Create button.

2. Select the Zip connector tile from the list of available connectors. Then, select the credential that will be used to connect to the Zip instance, and click Next; or, create a new Zip credential for use in this flow.

3. In Nexla, Zip data sources can be created using pre-built endpoint templates, which expedite source setup for common Zip API endpoints. Each template is designed specifically for the corresponding Zip endpoint, making source configuration easy and efficient.
   • To configure this source using a template, follow the instructions in Configure Using a Template.

   Zip sources can also be configured manually, allowing you to ingest data from Zip endpoints not included in the pre-built templates or apply further customizations to exactly suit your needs.
   • To configure this source manually, follow the instructions in Configure Manually.

Configure Using a Template

Nexla provides pre-built templates that can be used to rapidly configure data sources to ingest data from common Zip API endpoints. Each template is designed specifically for the corresponding Zip endpoint, making data source setup easy and efficient.

Endpoint Settings

• Select the endpoint from which this source will fetch data from the Endpoint pulldown menu. Available endpoint templates are listed in the expandable boxes below. Click on an endpoint to see more information about it and how to configure your data source for this endpoint.

Get Charge

Retrieves the details of a single charge by its unique identifier. Use this endpoint when you need to look up the status, amount, or metadata of a specific Zip charge — for example, to verify whether a payment was successfully captured or to audit a particular transaction.

• Enter the unique identifier of the charge you want to retrieve in the Charge ID field. Charge IDs are returned by Zip when a charge is created and can also be found in your Zip Merchant Dashboard under the Orders or Transactions section.

• This endpoint retrieves a single charge record. The response includes charge status, amount, currency, associated checkout ID, and timestamps.

The Charge ID is a required field for this endpoint. For retrieving a list of multiple charges with filtering options, use the List Charges endpoint instead.

List Charges

Retrieves a paginated list of charges associated with your merchant account. Use this endpoint for bulk data exports, reconciliation, reporting, or auditing charge activity across your Zip integration. Results are returned in pages of up to 50 records.

• Optionally, enter a Merchant ID to filter charges to a specific merchant sub-account. Leave this field blank to retrieve charges for your primary merchant account.

• Optionally, enter a From Date (in yyyy-MM-dd format) to filter charges created on or after this date. For example, enter 2025-01-01 to retrieve charges from January 1, 2025 onward.

• Optionally, enter a To Date (in yyyy-MM-dd format) to filter charges created on or before this date. Use this in combination with From Date to define a specific date range.

• Optionally, enter a Status value to filter charges by their current state. Common Zip charge statuses include:

  • authorised — Funds have been ring-fenced but not yet captured.
  • captured — Payment has been fully captured and funds transferred.
  • cancelled — The charge was voided before capture.
  • refunded — The charge has been partially or fully refunded.

All filter parameters are optional. When no filters are applied, this endpoint returns all charges for your account in reverse chronological order. Nexla automatically handles pagination to retrieve all matching records.

Get Checkout

Retrieves the details of a specific checkout session by its unique identifier. Use this endpoint to inspect the status and configuration of a checkout — for example, to verify whether a customer completed a checkout flow or to retrieve the checkout data needed to initiate a charge.

• Enter the unique identifier of the checkout session you want to retrieve in the Checkout ID field. Checkout IDs are returned by Zip when a checkout is created via the Create Checkout endpoint.
• The response includes checkout status, order details, consumer information, and any associated charge data. A checkout session must be completed by the customer before a charge can be created against it.

Checkout sessions in Zip have a limited validity window. Once a checkout session expires, a new one must be created. Refer to the Zip developer documentation for current session expiry details.

Get Dispute

Retrieves the full details of a single dispute record by its unique identifier. Use this endpoint to check the status and evidence of a specific chargeback or customer dispute — for example, to confirm whether a dispute is still open or has been resolved.

• Enter the unique identifier of the dispute you want to retrieve in the Dispute ID field. Dispute IDs are assigned by Zip when a dispute is raised and can be found in your Merchant Dashboard or via the Search Merchant Disputes endpoint.
• The response includes the dispute status, associated charge, reason code, evidence submitted, and relevant dates. Dispute statuses include states such as Open, Under Review, and Closed.

For searching disputes across a date range or filtering by status, use the Search Merchant Disputes endpoint instead.

Search Merchant Disputes

Searches for disputes associated with your merchant account within a specified date range. Use this endpoint for bulk dispute reporting, reconciliation workflows, or to monitor dispute trends over a given period. Results are paginated with up to 10 records per page.

• Optionally, enter a Merchant ID to scope the search to a specific merchant sub-account. Leave blank to search across your primary merchant account.

• Optionally, enter a Start Date to define the beginning of the search date range. Dates should be in yyyy-MM-dd format (for example, 2025-01-01).

• Optionally, enter an End Date to define the end of the search date range. Use this together with Start Date to narrow results to a specific period.

• Optionally, enter a Status to filter disputes by their current state. Common Zip dispute statuses include:

  • Open — The dispute has been raised and is awaiting merchant response.
  • Under Review — Evidence has been submitted and the dispute is being reviewed.
  • Closed — The dispute has been resolved.

All filter parameters are optional. Nexla automatically handles pagination to retrieve all matching dispute records across multiple pages. For complete details, refer to the Zip disputes search documentation.

Get Settlement Invoices

Retrieves a paginated list of settlement invoices for reconciliation purposes. Use this endpoint to retrieve the invoices that Zip issues when it pays out merchant funds, which is essential for accounting, financial reporting, and payment reconciliation workflows. Results are returned in pages of up to 50 records.

• This endpoint does not require any additional configuration parameters beyond selecting it from the Endpoint pulldown menu.
• The response includes invoice identifiers, settlement amounts, associated transaction periods, and payout dates. Each invoice corresponds to a settlement batch from Zip to your merchant account.

Settlement invoices represent funds that Zip has paid out to your bank account. Use this endpoint alongside Get Settlement Transactions to perform a complete settlement reconciliation. For additional details, see the Zip settlements invoices documentation.

Get Settlement Transactions

Retrieves a paginated list of individual transactions included in settlement reports. Use this endpoint to obtain the line-item transaction data that makes up each settlement batch — essential for detailed financial reconciliation, revenue recognition, and auditing. Results are returned in pages of up to 50 records.

• This endpoint does not require any additional configuration parameters beyond selecting it from the Endpoint pulldown menu.
• The response includes transaction-level details such as transaction IDs, charge references, transaction types (sale, refund, dispute), amounts, and settlement dates.

Use this endpoint alongside Get Settlement Invoices for complete settlement reconciliation — invoices provide the summary-level payout data, while settlement transactions provide the underlying line items. For additional details, see the Zip settlements report documentation.

Endpoint Testing

Once the selected endpoint template has been configured, Nexla can retrieve a sample of the data that will be fetched according to the current settings. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Configure Manually

Zip data sources can be manually configured to ingest data from any valid Zip API endpoint. Manual configuration provides maximum flexibility for accessing endpoints not covered by pre-built templates or when you need custom API configurations.

With manual configuration, you can also create more complex Zip sources, such as sources that use chained API calls to fetch data from multiple endpoints or sources that require custom authentication headers or request parameters.

API Method

1. To manually configure this source, select the Advanced tab at the top of the configuration screen.

2. Select the API method that will be used for calls to the Zip API from the Method pulldown menu. The most common methods are:

   • GET: For retrieving data from the API (charges, checkouts, disputes, settlements)
   • POST: For triggering actions or querying endpoints that accept request bodies (such as dispute searches)

API Endpoint URL

3. Enter the URL of the Zip API endpoint from which this source will fetch data in the Set API URL field. This should be the complete URL including the protocol (https://) and any required path parameters.

   Zip API endpoint URLs follow this pattern: https://merchant-api.zip.co/global/v1/{resource} for production or https://sand.merchant-api.com/global/v1/{resource} for sandbox. For example:

   • To retrieve all charges: https://merchant-api.zip.co/global/v1/charges
   • To retrieve a specific checkout: https://merchant-api.zip.co/global/v1/checkouts/{checkout_id}

Ensure the API endpoint URL is correct and accessible with your current credentials. You can test the endpoint using the Test button after configuring the URL.

Date/Time Macros (API URL)

Optional

Optionally, the API URL can be customized using macros—all macros added to the API URL will be converted into values when Nexla executes the API call. Macros are dynamic placeholders that allow you to create flexible API endpoints that can adapt to different time periods or data requirements.

Macros are particularly useful for Zip endpoints that accept date range query parameters such as from and to for filtering charges or disputes by date.

1. To add a macro, type { at the appropriate position in the API URL (within the Set API URL field), and select the desired macro from the dropdown list.

   • {now} – The current datetime
   • {now-1} – The datetime one time unit before the current datetime
   • {now+1} – The datetime one time unit after the current datetime
   • custom – Datetime macros can reference any number of time units before or after the current datetime—for example, enter (now-4) to indicate the datetime four time units before the current datetime

2. Select the format that will be applied to datetime macros from the Date Format for Date/Time Macro pulldown menu. This format will be applied to the base datetime value of the macro—i.e., the value of {now} in {now-1}. For Zip date filter parameters, use yyyy-MM-dd format.

3. Select the datetime unit that will be used to perform mathematical operations in the included macro(s) from the Time Unit for Operations pulldown menu—for example, for the macro {now-1}, when Day is selected, {now-1} will be converted to the datetime one day before the current datetime.

Lookup-Based Macros (API URL)

Optional

Column values from existing lookups can also be included as macros in the API URL. Lookup-based macros allow you to reference data from previously configured data sources or lookups, enabling dynamic API endpoints that can adapt based on existing data.

Lookup-based macros are useful when you need to create Zip API endpoints that reference specific charge IDs, checkout IDs, or other identifiers retrieved from other data sources in your Nexla environment.

1. To include a lookup column value macro, select the relevant lookup from the Add Lookups to Supported Macros pulldown menu.

2. Type { at the appropriate position in the API URL, and select the lookup column-based macro from the dropdown list. Lookup-based macros are automatically populated into the macro list when a lookup is selected in the Add Lookups to Supported Macros pulldown menu.

Path to Data

Optional

If only a subset of the data returned by the Zip API endpoint is needed, you can designate the part of the response that should be included in the Nexsets produced from this source. This is particularly useful when Zip API responses contain metadata, pagination information, or wrapper objects alongside the actual data records.

For example, the Zip List Charges endpoint returns a JSON object with a data array containing the charge records, along with pagination metadata. By specifying $.data[*] as the path to data, Nexla treats each element of the array as a separate record.

Path to Data is essential when Zip API responses have nested structures. Without specifying the correct path, Nexla might not properly parse and organize your data into usable records.

• To specify which data should be treated as relevant in responses from this source, enter the path to the relevant data in the Set Path to Data in Response field.

  • For responses in JSON format, enter the JSON path that points to the object or array that should be treated as relevant data. JSON paths use dot notation (e.g., $.data[*] to access an array of records within a data object, or $.invoices[*] for settlement invoice arrays).
  Path to Data Example:

  For the Zip List Charges endpoint, the response wraps charge records in a data array. Enter $.data[*] as the path to data so that Nexla treats each charge object as a separate record.

Autogenerate Path Suggestions

Nexla can also autogenerate data path suggestions based on the response from the API endpoint. These suggested paths can be used as-is or modified to exactly suit your needs.

• To use this feature, click the Test button next to the Set API URL field to fetch a sample response from the API endpoint. Suggested data paths generated based on the content & format of the response will be displayed in the Suggestions box below the Set Path to Data in Response field.

• Click on a suggestion to automatically populate the Set Path to Data in Response field with the corresponding path. The populated path can be modified directly within the field if further customization is needed.

  

Metadata

If metadata is included in the Zip API response but is located outside of the defined path to relevant data, you can configure Nexla to include this data as common metadata in each record. For example, Zip paginated responses often include total counts and page information alongside the data array.

Metadata paths are particularly useful for preserving Zip API response context like request IDs, pagination totals, or summary statistics that apply to all records in the response.

• To specify the location of metadata that should be included with each record, enter the path to the relevant metadata in the Path to Metadata in Response field.

  • For responses in JSON format, enter the JSON path to the object or array that contains the metadata.

Request Headers

Optional

• If Nexla should include any additional request headers in API calls to this source, enter the headers & corresponding values as comma-separated pairs in the Request Headers field (e.g., header1:value1,header2:value2).

  The Zip API requires a QP-Territory header to specify the region for the API call. Enter this header as: QP-Territory:AU (or the appropriate territory code for your Zip region).

  You do not need to include the Authorization header — Nexla automatically adds this from your configured credential. The QP-Territory header, however, is required for all Zip API calls and must be specified here when using manual configuration.

Endpoint Testing

After configuring all settings for the selected endpoint, Nexla can retrieve a sample of the data that will be fetched according to the current configuration. This allows users to verify that the source is configured correctly before saving.

• To test the current endpoint configuration, click the Test button to the right of the endpoint selection menu. Sample data will be fetched & displayed in the Endpoint Test Result panel on the right.

• If the sample data is not as expected, review the selected endpoint and associated settings, and make any necessary adjustments. Then, click the Test button again, and check the sample data to ensure that the correct information is displayed.

Save & Activate the Source

1. Once all of the relevant steps in the above sections have been completed, click the Create button in the upper right corner of the screen to save and create the new Zip data source. Nexla will now begin ingesting data from the configured endpoint and will organize any data that it finds into one or more Nexsets.