--- updatedAt: 2026-09-04T11:22:09.000Z agentTools: projectIndex: https://docs.us.zip.co/llms.txt --- # API Javascript SDK Implementation The JavaScript SDK is a client-side initiated version of our [Gateway API](https://docs.us.zip.co/docs/custom-integration-guide#gateway-api) integration. It removes the need for a full-page redirect by managing the in-context rendering of the Zip checkout flow in a modal, the same way our Virtual Checkout solution does currently. Zip takes care of the initial authorization API call through the openCheckout method, which is used with a custom DOM element, and will launch checkout in a popup window (or iframe depending on provided parameters). Read more below. Zip communicates the results via a Webhook to a predefined endpoint on the merchant side, additionally to return the result on the client-side. Each consecutive operation, such as void, capture, refund, or other, must be completed on the server side. Please refer to [our API documentation](https://docs.us.zip.co/docs/custom-integration-guide). # Flow Diagrams *** Depending on how the capture model works for an order, there may be no need to make additional calls to our API to complete an order. **Auto capture**\ This will enable minimal server-side integration, and the order will be completed after the consumer has completed the Zip checkout flow. This also means that the installment plan will start right away and the order will be captured immediately upon order placement. This is recommended for instant orders or digital goods. ![](https://files.readme.io/162bfcd-API_Js_lib2x_1.png "API Js lib@2x (1).png")
**Delayed capture**\ This use-case is targeted for payment with a delay between the initial authorization and the order capture. This can also be used if the order requires multiple captures on the same authorization. The installment plan will start on the initial authorization, not on the capture. [Please refer to our API documentation](https://docs.us.zip.co/docs/custom-integration-guide#capture-an-order). ![](https://files.readme.io/e2e2336-API_Js_lib2x_2.png "API Js lib@2x (2).png") # Implementation Guide *** ## Client-side The client-side integration requires the following: 1. A reference to our CDN-hosted JavaScript library [see example](https://docs.us.zip.co/docs/api-javascript-sdk#section-javascript-reference) . 2. A signature that is computed server-side [see example](https://docs.us.zip.co/docs/api-javascript-sdk#calculating-the-signature--code-examples) 3. An HTML element to attach the click event that will trigger the openCheckout function. This element can be a custom HTML element, the Zip payment widget, or the Zip second chance widget. 4. JavaScript to attach one or more callback functions to customize the payment flow and handle checkout completion, including any potential errors. > 📘 Using a Zip widget to initiate checkout > > Set the attribute `integrationType='api'`. Without this attribute, the payment flow defaults to a **Virtual Checkout**, and the `window.quadpay.apiCheckout` methods will not be available

Javascript Reference

There are two environments available, and you'll receive unique credentials for each: * **Sandbox (Test) - US:** `https://cdn.sand.us.zip.co/v1/zip.js` * **Production - US:** `https://cdn.us.zip.co/v1/zip.js` Adding the sandbox script will automatically integrate with our sandbox services for testing. Importing the production script will result in real transactions. The script can be loaded by adding a tag like: ```html ``` The script can be added anywhere in the body or head area and loaded asynchronously. If loaded asynchronously, be sure to wait for its load to complete before invoking any operations against the library.

Start Checkout

Start the Zip checkout by calling `openCheckout`, typically in response to events like `click` or `keyDown` on a DOM element. Zip provides a Branded button asset by using: ```html ``` #### Open Checkout Function The openCheckout function is attached to a DOM element and initiates the Zip checkout flow with the [requestBody](https://docs.us.zip.co/docs/api-javascript-sdk#requestbody) and [signature](https://docs.us.zip.co/docs/api-javascript-sdk#calculating-the-signature--code-examples) input. An example is below: ```javascript const zipButton = document.getElementById('ZipButton') zipButton.addEventListener('click', () => { window.quadpay.apiCheckout.openCheckout(requestBody, signature) }) ``` ```jsx React const handleClick = () => { window.quadpay.apiCheckout.openCheckout(requestBody, signature) } const handleKeyDown = () => { if (event.key === 'Enter') { window.quadpay.apiCheckout.openCheckout(requestBody, signature) } } handleKeyDown(event)} > ``` > 🚧 Potential Pitfall! > > Be sure that the call to `openCheckout(requestBody, signature)` exists in the same context as the `onClick` handler. Calling `openCheckout()` in a callback or Promise might prevent the pop-up from appearing on some browsers. ### SDK Methods These methods handle events by passing them to their assigned callback functions, which may be called asynchronously. #### onComplete The `onComplete` method runs when a customer completes the Zip checkout. It receives the [Zip Response](https://docs.us.zip.co/docs/api-javascript-sdk#zip-response). In the [Express flow](https://docs.us.zip.co/docs/express-checkout), the `shippingAddress`([Address](https://docs.us.zip.co/docs/api-javascript-sdk#address)) object will also be sent. ```javascript /** * @param {Object} result - The result object * @param {Object} result.customer - The Customer object * @param {Object} result.object - The Zip order object * @param {Object} [result.shippingAddress] - Address object (only on Express Checkout) */ window.quadpay.apiCheckout.onComplete((result) => { // your code goes here }); ``` #### onClose `onClose` is an optional method that runs when a customer closes the Zip checkout window or their session times out. It receives a string describing why the checkout was closed. ```javascript /** * @param {string} message - A message explaining why checkout was closed */ window.quadpay.apiCheckout.onClose((message) => { // your code goes here }) ``` #### onError `onError` is an optional method that runs if the [requestBody](https://docs.us.zip.co/docs/api-javascript-sdk#requestbody) passed to `startCheckout()` fails validation. It receives an array of strings describing which attributes failed validation. ```javascript /** * @param {string[]} errors - An array of error messages */ window.quadpay.apiCheckout.onError((errors) => { // your code goes here }) ``` ## Server-side To enable secure communication between the SDK and our server, all operations are secured with an HMAC-SHA256 one-way hash that is performed using a shared secret key. **The key is provided by Zip and will differ depending on the environment used.** The Signatures are generated based on the requests **to sign the entire Zip requestBody object.** **JSON RequestBody example:** ```json { "merchantId": "[Insert merchant Id]", "merchantReference": "your-unique-order-id", "order": {}, // Order object reference can be found below "callbackUrl": "your-url-for-callbacks", "capture": "true" } ``` [block:parameters] { "data": { "h-0": "Properties", "h-1": "Type", "h-2": "Optional/Required", "h-3": "Description", "0-0": "merchantId", "0-1": "GUID", "0-2": "Required", "0-3": "Your identifier provided by Zip", "1-0": "merchantReference", "1-1": "String", "1-2": "Required", "1-3": "A unique order ID from the merchant", "2-0": "order ([see model](https://docs.us.zip.co/docs/api-javascript-sdk#object-models))", "2-1": "Order object", "2-2": "Required", "2-3": "A custom object representing the order. Example below.", "3-0": "callbackUrl", "3-1": "String", "3-2": "Optional", "3-3": "A URL that will receive the webhook request about the result of this operation. \nIf capture is set to true, a callbackUrl is required to verify the order details.", "4-0": "capture", "4-1": "Boolean", "4-2": "Required (default true)", "4-3": "Indicated is the order will be auto-captured or additional operations for capture will be completed to capture." }, "cols": 4, "rows": 5, "align": [ "left", "left", "left", "left" ] } [/block] ### Calculating the Signature — Code Examples Implementing this is language specific. Here are examples that can generate these hashes for you: ```csharp /// Takes the secret key and the JSON in string format public string Compute(string secretKey, string json) { var bytes = Encoding.UTF8.GetBytes(json); return this.Compute(secretKey, bytes); } /// If your entire request body is passed in as bytes (e.g. POST JSON request), this will give you the correct hash public string Compute(string secretKey, byte[] bytes) { using (var hmacsha256 = new HMACSHA256(Encoding.UTF8.GetBytes(secretKey))) { var hash = hmacsha256.ComputeHash(bytes); return Convert.ToBase64String(hash); } } ``` ```php $signature = base64_encode(hash_hmac('sha256', $data, $secret, true)); ``` ```javascript Node.js import crypto from 'crypto' const data = JSON.stringify(requestBody); const key = 'your_api_key_here'; const signature = crypto .createHmac('sha256', key) .update(data) .digest('base64'); ``` ```python import hmac import hashlib import base64 import json request_body = {"key": "value"} # Replace with actual data data = json.dumps(request_body) key = 'your_api_key_here' signature = base64.b64encode( hmac.new(key.encode(), data.encode(), hashlib.sha256).digest() ).decode() print(signature) ``` ```go Go package main import ( "crypto/hmac" "crypto/sha256" "encoding/base64" "encoding/json" "fmt" ) func main() { requestBody := map[string]interface{}{"key": "value"} // Replace with actual data data, _ := json.Marshal(requestBody) key := "your_api_key_here" h := hmac.New(sha256.New, []byte(key)) h.Write(data) signature := base64.StdEncoding.EncodeToString(h.Sum(nil)) } ``` ```ruby require 'openssl' require 'base64' require 'json' request_body = { key: 'value' } # Replace with actual data data = request_body.to_json key = 'your_api_key_here' digest = OpenSSL::HMAC.digest('sha256', key, data) signature = Base64.strict_encode64(digest) ```
### Webhooks Zip provides an async webhook message for events when a consumer completes the Zip checkout flow and when API calls are completed. **Webhook message format**\ [Authorization (at user completion of Zip checkout)](https://docs.us.zip.co/docs/custom-integration-guide#authorize-an-order)
## Example code ```javascript // retrieve server-side computed signature const signature = await fetch('/calculate-signature') // format order object const order = { amount: 123.45, curency: 'USD', shippingAmount: 10, taxAmount: 13.45, email: 'name@email.com', firstName: 'John', lastName: 'Doe', phoneNumber: '+15555555555', billingAddress: { line1: '123 street', address2: '', city: 'New York', state: 'NY', postalCode: '10001', country: 'US' }, lineItems: [ { name: 'Item Name', description: 'Item description', quantity: 1, price: 123.45, sku: '12345678', }, ] } // format Zip checkout request body const requestBody = { merchantId: '[Insert merchant Id]', merchantReference: 'merchant-order-id', // Unique order id from Merchant order, callbackUrl: 'http://merchant-url', capture: true, checkoutFlow: 'standard' } // initiate checkout method window.quadpay.apiCheckout.openCheckout(requestBody, signature) // runs when Zip checkout completes window.quadpay.apiCheckout.onComplete((result) => { // your code goes here }) // runs when Zip checkout popup is closed or session times out window.quadpay.apiCheckout.onClose((message) => { // your code goes here }) // runs when requestBody validation fails in openCheckout() window.quadpay.apiCheckout.onError((errors) => { // your code goes here }) ``` # Functions *** ### focusCheckout This method allows you to programmatically bring focus to the pop-up window once checkout has been opened. ```javascript window.quadpay.apiCheckout.focusCheckout() ``` ### closeCheckout This method force-closes the Zip checkout window and ends the user's Zip session. ```javascript window.quadpay.apiCheckout.closeCheckout() ``` # Object Models *** ## Order [block:html] { "html": "\n\n\n \n \n API Documentation\n \n\n\n
\n
\n
\n
\n currency (required) · string
\n
\n The currency code the order is in\n
\n
\n
\n amount (required) · number
\n
\n The amount of the order. It should include all fees, taxes, shipping, and discount codes calculated in its value.\n
\n
\n
\n firstName · string
\n
\n Customer's first name.\n
\n
\n
\n lastName · string
\n
\n Customer's last name.\n
\n
\n
\n email · string
\n
\n Customer's email address\n
\n
\n
\n phone · string
\n
\n Customer's 11-digit phone number\n
\n
\n
\n shippingAddress · Address
\n
\n Customer's shipping address information in the form of an Address object \n
\n Show properties\n
\n
    \n
  • line1: (required) Primary billing address information
    • \n
  • line2: Secondary billing address information
    • \n
  • city: (required) City of customer's billing address
    • \n
  • state: (required) State of customer's billing address in ISO 3166-2: US format
    • \n
  • country: (required) Country of customer's billing address in ISO3166-2 (two letter country code)
    • \n
  • postalCode: (required) 5 digit state postal/zip code
    • \n
\n
\n
\n
\n
\n
\n billingAddress · Address
\n
\n Customer's billing address information in the form of an Address object \n
\n Show properties\n
\n
    \n
  • line1: (required) Primary shipping address information
    • \n
  • line2: Secondary shipping address information
    • \n
  • city: (required) City of customer's shipping address
    • \n
  • state: (required) State of customer's shipping address in ISO 3166-2: US format
    • \n
  • country: (required) Country of customer's shipping address in ISO3166-2 (two letter country code)
    • \n
  • postalCode: (required) 5 digit state postal/zip code
    • \n
\n
\n
\n
\n
\n
\n taxAmount · number
\n
\n The tax amount of the order.\n
\n
\n
\n shippingAmount · number
\n
\n The shipping amount of the order.\n
\n
\n
\n lineItems · array of LineItem
\n
\n The amount of the order. It should include all fees, taxes, shipping, and discount codes calculated in its value.\n
\n Show properties\n
\n
    \n
  • name: The name of the item
    • \n
  • description: The description of the item (max character length 100)
    • \n
  • quantity: The quantity of the item in the order
    • \n
  • price: The price of 1 item
    • \n
  • sku: The Stock Keeping Unit number
    • \n
  • isPreOrder: Whether the item is a pre-order item
    • \n
  • releaseDate: The anticipated shipment date of the item
    • \n
\n
\n
\n
\n
\n
\n description · string
\n
\n The description of the order\n
\n
\n
\n{\n amount: 25.50,\n currency: \"USD\",\n firstName: \"John\",\n lastName: \"Doe\",\n email: \"johndoe@mail.com\",\n phone: \"123-456-7889\",\n shippingAddress: {\n line1: \"101 Test Street\",\n line2: \"Unit 101\",\n city: \"New York City\",\n state: \"NY\",\n country: \"USA\",\n postalCode: \"10001\"\n },\n billingAddress: {\n line1: \"101 Test Street\",\n line2: \"Unit 101\",\n city: \"New York City\",\n state: \"NY\",\n country: \"USA\",\n postalCode: \"10001\"\n },\n taxAmount: 0.00,\n shippingAmount: 10.00,\n lineItems: [\n {\n name: \"T-Shirt\",\n description: \"Item description\",\n quantity: 1,\n price: 25.50,\n sku: \"SKU123\",\n isPreOrder: false,\n releaseDate: null\n }\n ],\n description: \"Order description\"\n}\n
\n
\n\n\n" } [/block] ## Address [block:html] { "html": "\n\n\n \n \n API Documentation\n \n\n\n
\n
\n
\n
\n line1 (required) · string
\n
\n Primary address information\n
\n
\n
\n line2 · string
\n
\n Secondary address information\n
\n
\n
\n city (required) · string
\n
\n City of address\n
\n
\n
\n state (required) · string
\n
\n State of address in ISO3166-2 (US) format\n
\n
\n
\n country (required) · string
\n
\n Country of address in ISO3166-2 (two letter country code)\n
\n
\n
\n postalCode (required) · string
\n
\n 5 digit state postal code\n
\n
\n
\n{\n line1: \"101 Test Street\",\n line2: \"Unit 101\",\n city: \"New York City\",\n state: \"NY\",\n country: \"USA\",\n postalCode: \"10001\"\n}\n
\n
\n\n\n" } [/block] ## LineItem [block:html] { "html": "\n\n\n \n \n API Documentation\n \n\n\n
\n
\n
\n
\n name · string
\n
\n The name of the item\n
\n
\n
\n description · string
\n
\n The description of the item (max character length 100)\n
\n
\n
\n quantity · number
\n
\n The quantity of the item in the order\n
\n
\n
\n price · number
\n
\n The price of one item\n
\n
\n
\n sku · string
\n
\n The Stock Keeping Unit number\n
\n
\n
\n isPreOrder · boolean
\n
\n Whether the item is a pre-order item\n
\n
\n
\n releaseDate · Date
\n
\n The anticipated shipment date of the item\n
\n
\n
\n{\n name: \"T-Shirt\",\n description: \"Item description\",\n quantity: 1,\n price: 25.50,\n sku: \"SKU123\",\n isPreOrder: false,\n releaseDate: null\n}\n
\n
\n\n\n" } [/block] ## requestBody [block:html] { "html": "\n\n\n \n \n API Documentation\n \n\n\n
\n
\n
\n
\n merchantId (required) · string
\n
\n The merchant ID provided by Zip\n
\n
\n
\n merchantReference (required) · string
\n
\n The order ID on the merchant's platform. \n
\n
\n
\n order (required) · Order
\n
\n The order object\n
\n
\n
\n callbackUrl (required) · string
\n
\n The URL that Zip will send event webhooks too. These webhooks are the result of API requests made to Zip. \n
\n
\n
\n capture [default: true] · boolean
\n
\n This boolean tells Zip whether the order should be treated as Auto or Delayed capture. \n
\n
\n
\n checkoutFlow (required) · \"standard\" | \"express\"
\n
\n This string tells Zip whether the transaction should be opened in our Standard or Express checkout flow\n
\n
\n
\n{\n merchantId: \"xxxx-xxxx-xxxx-xxxx\",\n merchantReference: \"123ABC\",\n order: {} as Order,\n callbackUrl: \"my-merchant.com/zip-callback\",\n capture: true,\n checkoutFlow: \"standard\"\n}\n
\n
\n\n\n" } [/block] ## Zip Checkout Response [block:html] { "html": "\n\n\n \n \n API Documentation\n \n\n\n
\n
\n
\n
\n customer · Customer
\n
\n The Customer object sent from Zip\n
\n Show properties\n
\n
    \n
  • address1: Primary shipping address information
    • \n
  • address2: Secondary shipping address information
    • \n
  • city: City of customer's shipping address
    • \n
  • country: Country of customer's shipping address in ISO3166-2 (two letter country code)
    • \n
  • email: Customer's email address
    • \n
  • fistName: Customer's first name
    • \n
  • lastName: Customer's last name
    • \n
  • phoneNumber: Customer's 10 digit phone number
    • \n
  • postalCode: 5 digit state postal/zip code
    • \n
  • state: State of customer's shipping address in ISO 3166-2: US format
    • \n
\n
\n
\n
\n
\n
\n order · OrderResponse
\n
\n The Order object sent from Zip\n
\n Show properties\n
\n
    \n
  • amount: The order amount
    • \n
  • currency: The currency code
    • \n
  • isSuccess: Whether Zip successfully captured the order
    • \n
  • isTest: Whether the order was captured in sandbox or production
    • \n
  • merchantId: Merchant's Zip ID
    • \n
  • merchantReference: Merchant's order ID
    • \n
  • orderId: Zip's order ID
    • \n
  • timestamp: Timestamp when order was processed
    • \n
\n
\n
\n
\n
\n
\n shippingAddress (If Express checkout) · Address
\n
\n The shipping Address sent from Zip\n
\n Show properties\n
\n
    \n
  • line1: Primary shipping address information
    • \n
  • line2: Secondary shipping address information
    • \n
  • city: City of customer's shipping address
    • \n
  • state: State of customer's shipping address in ISO 3166-2: US format
    • \n
  • postalCode: 5 digit state postal/zip code
    • \n
  • country: Country of customer's shipping address in ISO3166-2 (two letter country code)
    • \n
\n
\n
\n
\n
\n
\n success · boolean
\n
\n Signifies whether Zip successfully processed the order\n
\n
\n
\n{\n customer: {\n address1: \"101 N Test Street\",\n address2: undefined,\n city: \"New York City\",\n country: \"US\",\n email: \"johndoe@gmail.com\",\n firstName: \"John\"\n lastName: \"Doe\"\n phoneNumber: \"(123)123-1234\" \n postalCode: \"12345\" \n state: \"NY \n }\n order: {\n amount: 149.99,\n currency: \"USD\",\n isSuccess: true,\n isTest: false,\n merchantId: 1234-1234-1234-1234,\n merchantReference: \"XYZ123\"\n orderId: \"XYZABC-123-5432\"\n timestamp: 2024-05-25T12:30:00 \n }\n shippingAddress: {\n line1: \"101 N Test Street\",\n line2: \"Unit 101\",\n city: \"New York City\",\n state: \"NY \n postalCode: \"12345\" \n country: \"US\" \n },\n success: true\n}\n
\n
\n\n\n" } [/block]