GuidesAPI Reference
Guides

Lightweight Second Chance Widget

Zip Second Chance Widget

Our No SDK Javascript Second Chance Widget helps merchants recover lost sales by offering customers who were declined for other payment methods the ability to Pay in 4 using Zip.

This component provides a seamless way to integrate the widget into your checkout flow.

This widget should be embedded in an element on your site.

Sandbox: https://components.sand.us.zip.co/2nd-chance

Production: https://components.us.zip.co/2nd-chance

The following query parameters should be provided in the query string to configure the widget for your e-commerce store:

query_paramtypeexample_valuerequireddescription
merchant-idGUID60d597c2-bb43-4156-86e9-c4d17d968e3dYesYour unique Zip merchant identifier
amountdecimal199.95YesThe maximum amount that can be authorized
merchantReferencestringorder-abc-123YesUnique identifier for order reconciliation
signaturestringdXzp4K+68kCwSjBn...Ht8w==YesHMAC-SHA256 signature for request authentication
backgroundColorstringwhiteNoBackground color: white, black, or grey (default: white)
hideBorderbooleanfalseNoHide widget border: true or false (default: false)
borderStylestringsharpNoBorder style: sharp or curved (default: sharp)

About signature

The signature parameter is required for API checkout to work properly. It must be calculated on your backend server using HMAC-SHA256 with your Zip client secret. This ensures the security and authenticity of the checkout request. For detailed instructions on how to calculate the signature, please refer to Zip API JavaScript SDK - Calculating the Signature

Example URLs

# Basic implementation - Default styling
https://components.us.zip.co/2nd-chance?merchantId=60d597c2-bb43-4156-86e9-c4d17d968e3d&amount=100.00&merchantReference=order-123&signature=YOUR_CALCULATED_SIGNATURE

# With custom styling
https://components.us.zip.co/2nd-chance?merchantId=60d597c2-bb43-4156-86e9-c4d17d968e3d&amount=250.00&merchantReference=order-456&signature=YOUR_CALCULATED_SIGNATURE&backgroundColor=black&borderStyle=curved

# Full configuration - All parameters are present
https://components.us.zip.co/2nd-chance?merchantId=60d597c2-bb43-4156-86e9-c4d17d968e3d&amount=199.99&merchantReference=order-abc-123&signature=YOUR_CALCULATED_SIGNATURE&backgroundColor=white&hideBorder=false&borderStyle=sharp

Example Implementation

<!-- Embed the widget -->
<iframe 
  id="zip-second-chance"
  src="https://components.sand.us.zip.co/2nd-chance?merchantId=60d597c2-bb43-4156-86e9-c4d17d968e3d&amount=199.95&merchantReference=order-123&backgroundColor=white&hideBorder=false&borderStyle=sharp&signature=YOUR_CALCULATED_SIGNATURE"
  width="400" 
  height="200"
  frameborder="0"
  style="border: none;">
</iframe>

<script>
  // Listen for events from the widget
  window.addEventListener('message', function(event) {
		const message = event.data;
    // Verify origin for security
    if (event.origin !== 'https://components.sand.us.zip.co') return;
    
    switch(message.type) {
      case 'ZIP_SECOND_CHANCE_COMPLETE':
        console.log('Checkout completed:', message.data.result);
        // Handle successful checkout
        // Redirect to success page or update UI
        break;
        
      case 'ZIP_SECOND_CHANCE_CLOSE':
        console.log('Widget closed:', message.data.message);
        // Handle widget close without completion
        break;
        
      case 'ZIP_SECOND_CHANCE_ERROR':
      case 'ZIP_SECOND_CHANCE_SDK_ERROR':
        console.error('Error occurred:', message.data);
        // Handle errors appropriately
        break;
    }
  });
</script>

Event Types

The widget communicates with the parent page through PostMessage events (Channel Messaging API). Here are the event types you'll receive

ZIP_SECOND_CHANCE_COMPLETE

Fired when the customer completes the checkout process.

{
  type: 'ZIP_SECOND_CHANCE_COMPLETE',
  data: {
    result: {
      // Contains checkout completion details
      orderId: 'zip-order-123',
      success: true,
      // ... additional result data
    },
    timestamp: '2024-01-15T10:30:00.000Z'
  }
}

ZIP_SECOND_CHANCE_CLOSE

Fired when the customer closes the widget without completing the checkout..

{
  type: 'ZIP_SECOND_CHANCE_CLOSE',
  data: {
    message: 'User closed widget',
    timestamp: '2024-01-15T10:30:00.000Z'
  }
}

ZIP_SECOND_CHANCE_ERROR

Fired when an error occurs during checkout initiation (e.g., missing required parameters).

{
  type: 'ZIP_SECOND_CHANCE_ERROR',
  data: {
    error: 'Zip SDK not available or openCheckout method not found',
    timestamp: '2024-01-15T10:30:00.000Z'
  }
}

ZIP_SECOND_CHANCE_SDK_ERROR

Fired when the Zip SDK encounters an error during the checkout process.

{
  type: 'ZIP_SECOND_CHANCE_SDK_ERROR',
  data: {
    message: {
      // SDK error details
    },
    timestamp: '2024-01-15T10:30:00.000Z'
  }
}

Visual Customization

The widget supports various styling options through query parameters:

Backgrounds

The default background color is white. However, there is also the option to update the background color to either black or grey.

Black Background Example

Grey Background Example

Border Styles

The default widget will have a thin black border, however there is the option to remove the border.

With Border Example

Without Border Example


Adjust Border Style

The default border style is one with sharp edges, but there is the option to have curved edges as well.

Sharp Edge Border Example

Round Edge Border Example


📘

Need help?

If you would like information about advanced customization or have any questions, please email our Merchant & Partner Solutions team.

Updated about 3 hours ago