Integration Guide

Add stablecoin checkout to your website.

Include one script, configure your wallet, and start accepting payments. No backend integration required.

3-step setupNo backend requiredWebhook supportLive demo

Prerequisites

Set up your wallet to receive payments.

One-time setup. Your wallet address establishes the settlement endpoint for all USDC transactions.

Quick start

Three steps to accepting payments.

No backend integration required. Add the script, configure your wallet, and create payment buttons.

Include the script

Add this line just before the closing </body> tag.

<script src="https://app.instantescrow.nz/conduit-checkout.js"></script>

Initialize with your wallet

Configure the checkout with your merchant wallet address.

<script>
  ConduitCheckout.init({
    // REQUIRED: Your wallet address to receive payments
    sellerAddress: '0xYourWalletAddressHere',

    // REQUIRED: Base URL of checkout page
    baseUrl: 'https://app.instantescrow.nz',

    // RECOMMENDED: Auto-send verified payment to your backend
    webhookUrl: 'https://yoursite.com/api/conduit-webhook',
    webhookSecret: 'your-secret-key',  // For HMAC signature verification

    // Optional: Default token ('USDC' or 'USDT')
    tokenSymbol: 'USDC',

    // Optional: Days until auto-release (default: 7)
    expiryDays: 7,

    // Optional: Display mode ('popup' or 'redirect')
    mode: 'popup',

    // Success callback (webhook already sent!)
    onSuccess: function(data) {
      console.log('Payment verified!', data);
      alert('Thank you! Order #' + data.orderId + ' confirmed!');
    },

    // Error callback
    onError: function(error) {
      console.error('Payment failed:', error);
      alert('Payment failed: ' + error);
    },

    // Cancel callback
    onCancel: function() {
      console.log('Payment cancelled');
    }
  });
</script>

Add payment buttons

Create buttons that open the checkout.

<button onclick="ConduitCheckout.open({
  amount: '50.00',
  description: 'Premium Product'
})">
  Pay $50 with USDC
</button>

Display modes

Choose how checkout appears.

Popup window

Opens in a centered popup. Best for minimal disruption to the shopping experience.

Examples

Common integration patterns.

Basic product payment

Simple checkout for a single product with order tracking.

<button onclick="ConduitCheckout.open({
  amount: '29.99',
  description: 'Premium Widget - Blue',
  orderId: 'ORDER-12345'
})">
  Buy Now - $29.99
</button>

Reference

Configuration options.

`ConduitCheckout.init(options)`

Option	Type	Required	Default	Description
sellerAddress	string	Yes	-	Your wallet address to receive payments
baseUrl	string	Yes	-	Base URL of checkout page
webhookUrl	string	No	-	Webhook URL for payment verification
webhookSecret	string	No	-	HMAC secret for webhook signatures
tokenSymbol	string	No	'USDC'	'USDC' or 'USDT'
expiryDays	number	No	7	Days until auto-release to seller
mode	string	No	'popup'	'popup' or 'redirect'
onSuccess	function	No	-	Callback when payment completes
onError	function	No	-	Callback when payment fails
onCancel	function	No	-	Callback when user cancels

`ConduitCheckout.open(params)`

Parameter	Type	Required	Description
amount	string/number	Yes	Payment amount (e.g., '50.00')
description	string	Yes	Payment description (max 160 chars)
orderId	string	No	Your internal order/transaction ID
email	string	No	Customer email address
tokenSymbol	string	No	Override default token for this payment
expiryDays	number	No	Override default expiry
webhookUrl	string	No	Override webhook URL for this payment
metadata	object	No	Custom metadata to include

Backend integration

Webhook-based order fulfillment.

Receive server-to-server notifications when payments complete. The SDK sends verified payment data to your webhook automatically.

Configure SDK with webhook

The SDK handles verification and webhook delivery automatically. No manual fetch() calls needed.

ConduitCheckout.init({
  sellerAddress: '0xYourWalletAddress',
  baseUrl: 'https://app.instantescrow.nz',

  // Webhook config
  webhookUrl: 'https://yoursite.com/api/conduit-webhook',
  webhookSecret: 'your-secret-key',  // Store securely!

  onSuccess: function(verifiedData) {
    // Webhook already sent! Just show UI confirmation
    console.log('Payment verified!', verifiedData);
    window.location.href = '/thank-you?order=' + verifiedData.orderId;
  },

  onError: function(error) {
    alert('Payment failed: ' + error);
  }
});

Create webhook endpoint

One endpoint handles verification, order processing, and fulfillment.

const crypto = require('crypto');

// POST /api/conduit-webhook
app.post('/api/conduit-webhook', async (req, res) => {
  try {
    // 1. VERIFY HMAC SIGNATURE (prevents spoofing)
    const signature = req.headers['x-conduit-signature'];
    const payload = JSON.stringify(req.body);

    const expectedSig = crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(payload)
      .digest('hex');

    if (signature !== expectedSig) {
      return res.status(401).json({ error: 'Invalid signature' });
    }

    // 2. EXTRACT VERIFIED DATA
    const {
      contractId,
      chainAddress,
      amount,
      currencySymbol,
      state,
      verified,
      verifiedAt,
      orderId,
      email,
      metadata
    } = req.body;

    console.log('Payment verified:', contractId, amount, currencySymbol);

    // 3. PROCESS PAYMENT IN YOUR SYSTEM
    await db.orders.update({
      where: { id: orderId },
      data: {
        status: 'PAID',
        paymentContractId: contractId,
        paymentChainAddress: chainAddress,
        paymentAmount: amount,
        paidAt: new Date(verifiedAt)
      }
    });

    // 4. FULFILL ORDER
    await fulfillment.ship(orderId);
    await email.sendConfirmation(email, orderId);

    // 5. RESPOND SUCCESS
    res.json({ received: true });

  } catch (error) {
    console.error('Webhook error:', error);
    res.status(500).json({ error: 'Internal server error' });
  }
});

Webhook payload

{
  "transaction_hash": "0x1234...",
  "contract_address": "0x5678...",
  "contract_id": "abc123",
  "order_id": "1234",
  "expected_amount": 50.00,
  "expected_recipient": "0x9abc...",
  "merchant_wallet": "0xdef0..."
}

Verification

What verified data means.

Field	Meaning
verified: true	Backend confirmed payment exists in blockchain
state: "ACTIVE"	Funds are locked in escrow contract
seller: "0x..."	Matches your wallet (verified by SDK)
amount: 50.0	Matches expected amount (verified by SDK)
chainAddress	Blockchain contract address (permanent record)

Once you receive verified data, it is safe to fulfil the order. The SDK has confirmed everything on-chain.

Platform

Built-in protection for every transaction.

Buyer protection

Funds held in escrow smart contract
Time-delayed release (default 7 days)
Dispute mechanism
Admin arbitration

No gas fees

Platform covers all blockchain fees
Users pay 1% platform fee
Minimum payment: $1.001
Fee included in payment amount

Client-side security

Users sign with own wallet
No custody of user funds
HTTPS required
Open-source smart contracts

Multi-token support

USDC (default)
USDT (optional)
Base network (Ethereum L2)
Low transaction costs

End-to-end flow

Customer clicks pay

Opens checkout popup or redirect.

Wallet connects & pays

Customer signs the transaction.

SDK verifies on-chain

Automatic blockchain verification.

Webhook sent to backend

Your server receives verified data.

Order fulfilled

Ship goods, deliver product, send receipt.

FAQ

Frequently asked questions.

What tokens are supported?

Currently USDC on the Base network (Ethereum Layer 2).

What are the fees?

1% platform fee per transaction. No setup costs, no monthly fees. Minimum payment is $1.001. Gas fees are covered by the platform.

How long until I receive funds?

Funds are automatically released after the expiry period (default 7 days) unless the buyer raises a dispute. You can customize the expiry period per payment.

Can buyers get refunds?

Buyers can raise a dispute within the protection period. Our admin team reviews disputes and can release funds to either party based on the evidence.

Do I need a crypto wallet?

Yes, you need a wallet address to receive payments. We recommend MetaMask, Coinbase Wallet, or any Web3-compatible wallet. Buyers can use email + social login (we create embedded wallets for them).

Is this secure?

Yes. Payments are secured by immutable smart contracts on the Base blockchain. Users sign transactions with their own wallets. All transactions are auditable on-chain. HTTPS is required for all integrations.

What about chargebacks?

Cryptocurrency transactions are irreversible — there are no chargebacks like with credit cards. The escrow system provides buyer protection through the dispute mechanism during the protection period.

Ready to integrate?

Try the interactive demo or start integrating directly into your site.

View Live Demo Merchant Overview

How it works FAQ Shopify integration Source code info@conduit-ucpi.com