Skip to main content

Zip Destination

Nexla's bi-directional connectors allow data to flow both to and from any location, making it simple to create a FlexFlow data flow that sends data to a Zip location.
zip_api.png

Zip

Create a Zip Destination​

  1. Click the + icon on the Nexset that will be sent to the Zip destination, and select the Send to Destination option from the menu.

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

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

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

Configure Using a Template​

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

  • To configure this destination using a template, select the endpoint to which data will be sent from the Endpoint pulldown menu. Then, click on the template in the list below to expand it, and follow the instructions to configure additional endpoint settings.

    Create Charge

    Creates or captures a charge on an existing, approved checkout session. Use this endpoint to complete a payment after a customer has successfully completed the Zip checkout flow. This is the final step to confirm a purchase and transfer funds.

    • This endpoint requires no additional parameter configuration beyond selecting it from the Endpoint pulldown menu. The request body containing charge details (such as the checkout token and capture flag) is taken from the Nexset data being sent to this destination.

    • The Nexset data sent to this endpoint should include the following fields:

      • checkoutId or token — The identifier of the approved Zip checkout session to charge.
      • capture — Set to true to immediately capture funds, or false to authorize only (ring-fence funds for later capture).

    A charge must be created within the validity window of the checkout session — if the checkout expires before a charge is created, a new checkout session must be initiated. For full request body details, refer to the Zip developer documentation.

    Capture Charge

    Captures an existing authorized charge, completing the payment and transferring funds from the customer to the merchant. Use this endpoint when a charge was previously created with capture: false (authorization only) and you are now ready to finalize the transaction — for example, when fulfilling a delayed shipment or confirming a booking.

    • Enter the unique identifier of the authorized charge to capture in the Charge ID field. This is the charge ID returned by Zip when the original charge was created.
    • The request body sent to this endpoint can include an optional amount to perform a partial capture. If no amount is specified, the full authorized amount will be captured.

    Capturing a charge is a one-time action — once captured, a charge cannot be un-captured. To cancel an authorized charge without capturing, use the Void Charge endpoint instead.

    Refund Charge

    Refunds an existing captured charge, returning funds to the customer. Use this endpoint to process customer refunds for completed Zip transactions — for example, for returned goods, cancelled orders, or service credits. Both full and partial refunds are supported.

    • Enter the unique identifier of the charge to refund in the Charge ID field. This is the charge ID of the previously captured transaction.

    • The Nexset data sent to this endpoint should include the refund details:

      • amount — The amount to refund, in the transaction currency. Omit this field or set it to the full charge amount for a complete refund.
      • reason — An optional description of the reason for the refund.

    Refunds processed via the Zip API are typically reflected in the customer's account within a few business days. Zip applies a negative transaction to the settlement reconciliation for the refunded amount.

    Void Charge

    Voids (cancels) an existing authorized charge before it has been captured. Use this endpoint to release ring-fenced funds back to the customer when an order needs to be cancelled after authorization but before payment capture — for example, when an item is out of stock or a booking is cancelled.

    • Enter the unique identifier of the authorized charge to void in the Charge ID field. Only charges that have been authorized but not yet captured can be voided.
    • No additional request body parameters are required for a void operation.

    A void can only be performed on an authorized charge that has not yet been captured. If a charge has already been captured and you need to return funds to the customer, use the Refund Charge endpoint instead.

    Create Checkout

    Creates a new Zip checkout session for a merchant. Use this endpoint to initiate the Zip payment flow for a customer — the checkout session captures order details and returns a redirect URL or token that the customer uses to complete their Zip payment. This is the first step in the Zip charge lifecycle.

    • This endpoint requires no additional parameter configuration beyond selecting it from the Endpoint pulldown menu. All checkout details — including order amount, currency, items, and consumer information — are provided in the Nexset data sent as the request body.

    • The Nexset data sent to this endpoint should include the core checkout fields:

      • amount — The total order amount.
      • currency — The ISO 4217 currency code (e.g., AUD, USD).
      • order — Order details including reference, items, and shipping information.
      • consumer — Customer details including name and email address.
      • config.redirect_uri — The URL Zip will redirect the customer to after completing the checkout.

    The response from this endpoint includes a uri field containing the Zip-hosted checkout URL that you should redirect the customer to. After the customer completes the checkout, use the Create Charge endpoint to finalize the payment.

    Accept Dispute and Close

    Closes a dispute by accepting the loss, finalizing the dispute resolution without contesting the chargeback. Use this endpoint when you choose not to submit evidence for a dispute and want to accept the outcome — for example, when the customer's claim is valid, or when the cost of contesting is not justified.

    • This endpoint requires no additional parameter configuration beyond selecting it from the Endpoint pulldown menu. The dispute identifier and any required closure details are provided in the Nexset data sent as the request body.
    • Once accepted and closed, a dispute cannot be re-opened. The associated chargeback amount will be deducted from your next settlement.

    Accepting a dispute is irreversible. If you wish to contest a dispute instead, use the Submit Dispute Evidence endpoint before the evidence submission deadline. For more information, see the Zip dispute close documentation.

    Submit Dispute Evidence

    Submits evidence to contest a dispute. Use this endpoint when you want to challenge a chargeback by providing supporting documentation such as proof of delivery, refund policies, or records showing the transaction was legitimate. Evidence submissions are final and cannot be modified after submission.

    • This endpoint requires no additional parameter configuration beyond selecting it from the Endpoint pulldown menu. All evidence details are provided in the Nexset data sent as the request body.

    • The Nexset data sent to this endpoint should include the dispute identifier and the relevant evidence. Types of evidence that Zip accepts include:

      • Refund policy — Documentation of your store's refund or return policy.
      • Cancellation policy — Documentation of your cancellation policy if applicable.
      • Proof of delivery — Shipping tracking records or delivery confirmation.
      • Duplicate charge documentation — Evidence that the disputed transaction is not a duplicate.

    :::warning Important Evidence submissions are final and cannot be modified or withdrawn after submission. Ensure all evidence is accurate and complete before sending. For details on accepted evidence formats, refer to the Zip submit evidence documentation. :::

Configure Manually​

Zip destinations can be manually configured to send data to any valid Zip API endpoint.

Using manual configuration, you can also configure Nexla to automatically send the response received from the Zip API after each call to a new Nexla webhook data source.

API Method​

  1. To manually configure this destination, 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. Most Zip write operations use POST for creating resources, capturing charges, or submitting evidence.

Data Format​

  1. Select the format in which the Nexset data will be sent to the Zip API from the Content Format pulldown menu. Nexla will automatically convert the data to the selected format for each API call. The Zip API accepts JSON format for all request bodies.

API Endpoint URL​

  1. Enter the URL of the Zip API endpoint to which you want to send the Nexset data in the URL field. For operations that target a specific resource (such as capturing or voiding a charge), include the resource ID in the URL path.

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

    • To create a checkout: https://merchant-api.zip.co/global/v1/checkouts
    • To capture a specific charge: https://merchant-api.zip.co/global/v1/charges/{charge_id}/capture
    • To submit dispute evidence: https://merchant-api.zip.co/merchant-disputes/submit-evidence

Request Headers​

Optional

  • If Nexla should include any additional request headers in API calls to this destination, 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 is required for all Zip API calls and must be specified here when using manual configuration.

Exclude Attributes from the Call​

Optional

  • If any record attributes in the Nexset should be omitted when sending data to this Zip destination, select the attributes from the Exclude Attributes pulldown menu.

  • Any number of attributes can be selected for exclusion, and all excluded attributes will be shown in the field. To remove an attribute from the list, click the X icon next to the attribute name.

Record Batching​

Optional

  1. If records should be sent to this destination in batched API calls, check the box next to Would you like to batch your records together? to enable record batching.

  2. Enter the maximum number of records that should be batched together in a single API call in the Batch Size field. By default, this value is set to 100.

  3. Select the algorithm that will be used to group records into batches from the Grouping Algorithm pulldown menu. The sample request shown in the panel on the right will be updated to reflect the current batching settings.

Most Zip API endpoints accept one operation per request. Record batching is generally not applicable for individual charge, checkout, or dispute operations, but may be useful for custom bulk workflows. Verify the target endpoint's batch support before enabling this option.

Response Webhook​

Optional

Nexla can automatically send the response received from the Zip API after each call to a new Nexla webhook data source. This option allows you to keep track of the status of each API call and any additional information returned after each call — such as the newly created charge ID, checkout URL, or dispute status update.

  • To enable this option, check the box next to Would you like to process the API response as a Nexla Webhook source?.

Sample Request Payload​

Sample request payloads containing a portion of the Nexset data that will be sent to the Zip API endpoint based on the current settings are shown in the Sample Payload panel on the right. These samples can be referenced to ensure that the destination and request settings are correctly configured.

  • Click on a sample request payload to expand it and view the complete payload content.
  • Sample payloads are automatically updated with each setting change, making it easy to verify that changes achieve the desired effect.

Endpoint Testing (Manual Configuration)​

After all endpoint settings have been configured, Nexla can send a test payload to the Zip API to ensure that the destination is configured correctly.

  1. To send a test payload, select the Test button at the top of the Sample Payload panel, and click on a listed sample payload to expand it.

  2. If any modifications to the sample payload are needed, make the necessary changes directly within the sample window.

  3. Click the Send Test Data button at the top of a sample payload to send the test payload to the Zip API using the current settings.

Save & Activate the Destination​

  • Once all endpoint settings have been configured, click the Done button in the upper right corner of the screen to save and create the destination. To begin sending data to the configured Zip endpoint, open the destination resource menu, and select Activate.

    The Nexset data will not be sent to the Zip API until the destination is activated. Destinations can be activated immediately or at a later time, providing full control over data movement.