Accounts are the basic organizations that use Coinsub services. They can be individuals, businesses, or non-profit organizations. They can have one or more users associated with them, and they can be connected to other accounts.

Creating an account through the API will connect that account with your account, enabling you to call the API as that account in the future. This allows a platform account the ability to onboard users, and configure products, and payment agreements for their users.

Coinsub Merchant Wallets are secure, non-custodial wallets powered by DFNS’s battle-tested wallet infrastructure. Designed with robust key management and WebAuthn-based authentication, these wallets ensure enterprise-grade security without exposing private keys or relying on vulnerable seed phrases. With Merchant Wallets, Coinsub merchants don’t need to connect external wallets or manage third-party integrations. Everything is built-in—making on-chain payments, managing funds, and receiving crypto subscriptions frictionless and secure, straight from your Coinsub dashboard.

To get started with a merchant platform wallet of your own, sign up at test.coinsub.io (development environment) or app.coinsub.io (production).

This comprehensive guide provides detailed information about integrating Coinsub payment processing into your application. Coinsub offers four distinct integration methods designed to accommodate different technical requirements and use cases, from simple no-code solutions to advanced API integrations with full customization capabilities.

Which Integration Option Should You Use?

Choosing the right integration depends on your technical resources, business model, and how much control you want over the checkout experience.

🔹 Standard Checkout Link – Best for Non-Technical Merchants

Who it's for:

• Individual creators
• Small merchants or service providers
• Teams with no dev resources

Why use it:

• Zero development required
• Shareable across any platform (email, social, website)
• Fastest way to start accepting stablecoin payments

🔸 Button Embed – Best for Low-Code Teams

Who it's for:

• Marketing teams with light dev help
• Shopify, WordPress, or Webflow users
• Sites that need a call-to-action button with minimal backend setup

Why use it:

• Simple HTML embed
• Button styling via data-color
• Redirects to secure hosted checkout

🔸 Modal iFrame – Best for Custom Frontends That Want In-Site UX

Who it's for:

• Sites with web developers
• Businesses that care about seamless branding and user experience
• Publishers, SaaS sites, or gated content platforms

Why use it:

• Fully embedded experience
• Controlled modal styling
• Checkout stays within your UI context

🔸 Headless API – Best for Crypto-Native Platforms & Advanced Teams

Who it's for:

• Web3 apps, dApps, DeFi platforms
• Teams already managing wallets or signing flows
• Platforms needing custom onboarding, wallet UX, or nonstandard product logic

Why use it:

• Full control over the payment process
• You manage wallet interaction and signing
• Suitable for integrations with other on-chain or backend systems

Webhooks allow real-time communication between systems.

Webhooks are used to synchronize disparate systems by publishing automated messages with predefined payloads that can be interpreted by integrated systems. They allow real-time communication between applications, enabling instant updates and data sharing without the need for continuous polling.

Our platform webhooks provide notifications when specific actions occur on your account, such as when a customer subscribes to a product, purchases a one-off product, makes a payment, or cancels a subscription. By setting up webhooks, you can automate processes and keep your systems in sync with our platform in real-time.

1. Sign into the platform
2. Navigate to Merchant Settings
   • From the dashboard, select the Settings menu located on the sidebar, then merchant settings
3. Input Webhook URL
   • Input your webhook URL and other merchant details in the settings.

If you are looking to control the webhook URLs configuration for your other connected merchant accounts, you can do so

The webhook is triggered during the following actions:

• When a customer subscribes to a product.
• When a customer purchases a one-off product.
• When a customer makes a payment.
• When a customer cancels a subscription.
• When you execute a wallet send transaction from your account

We send five different event types:

• Recurrence Signup
• Payment
• Failed Payment
• Subscription Cancellation
• Wallet Transfer

Recurrence Signup

When a customer agrees to make recurring payments, the webhook sends the following data. Note that other than the first_payment_id, there is no information about the first payment made. Payment information is sent as a separate payment event.

 
{
  "type": "recurrence_signup",
  "merchant_id": "mrch_10d3ed3c-2471-4573-ac66-ec7e3b414e80",
  "origin_id": "161",
  "origin": "subscriptions",
  "name": "asdasd",
  "amount": 0.0985,
  "agreement_id": "agre_115608f9-662c-4ae4-aa6f-3928f99df15b",
  "frequency": "Every",
  "interval": "Day",
  "duration": "Until Cancelled",
  "start_date": "2025-08-18T08:37:59.858585Z",
  "next_process_date": "2025-08-19T08:38:00Z",
  "first_payment_id": "paym_6f7a1c13-706c-4df3-a566-6a8ced58ccfc",
  "user": {
    "first_name": "Test",
    "last_name": "Test",
    "email": "test@gmail.com",
    "subscriber_id": "1d5faea9-306c-488d-b2f9-b00b2e8cd414"
  },
  "metadata": {
    "some": "metadata"
  }
}

Fields:

• type: "recurrence_signup" (Type of action being executed).
• merchant_id: Unique identifier for the merchant.
• origin_id: Unique identifier for the recurrence signup's origin.
• origin: Source of the payment. Values: “purchase_sessions” or “subscriptions”.
• name: Name of the recurring payments.
• amount: The amount received each time a recurring payment is made.
• agreement_id: The id of the agreement that can be used to retrieve agreement details.
• frequency: How often the customer is billed. Values: “Every”, “Every Other”, “Every Third”, “Every Fourth”, “Every Fifth”, “Every Sixth”, or “Every Seventh”.
• interval: The time period for the billing cycle. Values: “Day”, “Week”, “Month”, or “Year".
• duration: The number of billing cycles. Either a number (e.g., “1”, “525600”, etc.) or “Until Cancelled”. There is no limit to the number. Data type: string.
• start_date: Date the user agreed to the recurring payments.
• next_process_date: The next date customer will be billed.
• first_payment_id: The payment_id of the first payment made for this billing agreement.
• user: Information about the customer.
  • first_name: The customer's first name.
  • last_name: The customer's last name.
  • email: The customer's email.
  • subscriber_id: A unique identifier for the customer.
• metadata: Miscellaneous information (if any) about payment. Data type: object.

Payment

When a customer makes a successful payment, the webhook sends the following data:

 
{
  "type": "payment",
  "merchant_id": "mrch_10d3ed3c-2471-4573-ac66-ec7e3b414e80",
  "origin_id": "161",
  "origin": "subscriptions",
  "name": "asdasd",
  "currency": "USDC",
  "amount": 0.1,
  "metadata": null,
  "payment_date": "2025-08-18T08:37:59.229191Z",
  "status": "completed",
  "transaction_details": {
    "transaction_id": 343,
    "transaction_hash": "0x15c4308c3f55e7ef13d062e0784ec30181a400a2ac92bfac849443c486d33963",
    "chain_id": 84532
  },
  "user": {
    "first_name": "asd",
    "last_name": "asd",
    "email": "asd@gmail.com",
    "subscriber_id": "1d5faea9-306c-488d-b2f9-b00b2e8cd414"
  },
  "payment_id": "paym_6f7a1c13-706c-4df3-a566-6a8ced58ccfc"
}

Fields:

• type: "payment" (Type of action being executed)
• merchant_id: Unique identifier for the merchant.
• origin_id: Unique identifier for the payment's origin.
• origin: Source of the payment. Values: “purchase_sessions” or “subscriptions”.
• name: Name of the purchase item.
• currency: Symbol for the currency used to make the payment (e.g., “USDC”, “USDT”).
• amount: The amount the customer paid, excluding fees.
• metadata: Miscellaneous information (if any) about the payment. Data type: object.
• status: Status of the payment, i.e., “completed.” Data type: string.
• payment_id: The id of the payment object. Can be used to get full transaction details of a payment.
• transaction_details: Information about the transaction. Data type: object.
  • transaction_id: ID for the transaction.
  • transaction_hash: Blockchain transaction hash.
  • chain_id: Chain ID for the network in which the payment was made.
• user: Information about the customer. Data type: object.
  • first_name: The customer's first name.
  • last_name: The customer's last name.
  • email: The customer's email.
  • subscriber_id: A unique identifier for the customer.

Failed Payment

When a customer makes a payment attempt and fails, the webhook sends the following data:

 
{
  "type": "payment",
  "merchant_id": "mrch_92313b-1291-43c5-941d-9349d82fc33e",
  "origin_id": "8",
  "origin": "subscriptions",
  "name": "Willy Wonka's Wonka Bar",
  "currency": "USDC",
  "amount": 1,
  "metadata": {
    "some": "metadata"
  },
  "payment_date": "2025-05-28T17:20:03.766627-07:00",
  "status": "completed",
  "transaction_details": {
    "transaction_id": 29,
    "transaction_hash": "0x20887c4a415fdf19486364c02c550107da5c79147891e2264f1ef281383599fd",
    "chain_id": 80002
  },
  "user": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john_doe@company.net",
    "subscriber_id": "22b5ff13-e846-40cc-80fa-9e0261f8fd42"
  },
}
}

• type: "failed_payment" (Type of action being executed)
• merchant_id: Unique identifier for the merchant.
• origin_id: Unique identifier for the payment's origin.
• origin: Source of the payment. Values: “purchase_sessions” or “subscriptions”.
• name: Name of the purchased item.
• currency: Symbol for the currency used to make the payment (e.g., “USDC”, “USDT”).
• amount: The amount the customer paid, excluding fees.
• metadata: Miscellaneous information (if any) about the payment. Data type: object.
• status: Status of the payment, i.e., “failed.”
• transaction_details: Information about the transaction. Data type: object.
  • transaction_id: Unique identifier for the transaction.
  • transaction_hash: Blockchain transaction hash. Values: a hex value, or empty string.
  • chain_id: Chain ID for the network in which the payment was made.
• user: Information about the customer. Data type: object.
  • first_name: The customer's first name.
  • last_name: The customer's last name.
  • email: The customer's email.
  • subscriber_id: A unique identifier for the customer.

Subscription Cancellation

When a subscriber cancels a subscription, the webhook sends the following data:

 
{
  "type": "cancellation",
  "merchant_id": "mrch_92313b-1291-43c5-941d-9349d82fc33e",
  "origin": "purchase_sessions",
  "name": "Willy Wonka's Candy Subscription Package",
  "amount": 1,
  "metadata": {
    "some": "metadata"
  },
  "agreement_id": "agre_78e289d9-bbb0-4930-be9a-2edd6822e1ff",
  "frequency": "Every",
  "interval": "Minute",
  "duration": "Until Cancelled",
  "start_date": "2025-05-28T16:22:49.47113-07:00",
  "cancellation_date": "2025-05-28T16:49:16.502493-07:00",
  "active_until": "2025-05-28T16:49:25.398975Z",
  "user": {
    "first_name": "John",
    "last_name": "Doe",
    "email": "john_doe@company.net",
    "subscriber_id": "22b5ff13-e846-40cc-80fa-9e0261f8fd42"
  }
}

Fields:

• type: "cancellation" (Type of action being executed).
• merchant_id: Unique identifier for the merchant.
• origin: Source of the payment. Values: “purchase_sessions” or “subscriptions”.
• name: Name of the purchase item.
• amount: The amount paid with each billing cycle.
• metadata: Miscellaneous information (if any) about the payment. Data type: object.
• agreement_id: Unique identifier for the original agreement created at sign-up.
• frequency: How often the customer is billed. Values: “Every”, “Every Other”, “Every Third”, “Every Fourth”, “Every Fifth”, “Every Sixth”, or “Every Seventh”.
• interval: The time period for the billing cycle. Values: “Day”, “Week”, “Month”, or “Year".
• duration: The number of billing cycles. Either a number (e.g., “1”, “525600”, etc.) or “Until Cancelled”. There is no limit to the number. Data type: string.
• start_date: Date the user agreed to the recurring payments.
• cancellation_date: Date the user cancelled the agreement for recurring payments.
• active_until: Date the last billing cycle will end.
• user: Information about the customer. Data type: object.
  • first_name: The customer's first name.
  • last_name: The customer's last name.
  • email: The customer's email.
  • subscriber_id: A unique identifier for the customer.

Wallet Transfers

When you execute a wallet to wallet transfer from your merchant wallet, the following payload is sent to the webhook

 
{
  "type": "transfer",
  "merchant_id": "mrch_053daf5f-7de6-491e-8096-5c8a8612f334",
  "amount_in_usd": "0.985000",
  "hash": "0x0924b6a3cc49d2ba216452358271533bc8190826b6cae395747be86b91a6ea98",
  "transfer_id": "7",
  "wallet_id": "wa-tffvk-1nj19-1qqbt0j5ieophqg",
  "network": "PolygonAmoy",
  "from_address": "0xd0cbe3ab3a241f6c4d5f2c0e2bfe37ec03fe7f04",
  "to_address": "0x1C337aBF69aB1DC1F9388e97bBd4AAD57059D8Eb",
  "status": "success",
  "status_confirmed_at": "2025-08-15T11:43:19.641041+02:00"
}

Fields:

• type: "transfer" (Type of action being executed). Indicates that this payload is for a wallet-to-wallet transfer.
• merchant_id: Unique identifier for the merchant initiating the transfer.
• amount_in_usd: Amount being transferred, denominated in USD. Data type: string.
• hash: Unique transaction hash on the blockchain, used to verify and track the transfer.
• transfer_id: Unique identifier for this specific transfer within the platform's system.
• wallet_id: Unique identifier for the wallet within the platform's system that initiated the transfer.
• network: Blockchain network on which the transfer occurs. Example: “Polygon”.
• from_address: Blockchain address of the sender wallet.
• to_ddress: Blockchain address of the receiver wallet.
• status: Status of the transfer. Common values: "success", "pending", "failed".
• status_confirmed_at: Timestamp when the transfer status was confirmed. Format: ISO 8601 with timezone.

Retry Mechanism

If the webhook fails to deliver the data, it will retry up to 5 times, with each retry occurring every 5-10 minutes.

The Crypto Interest & Engagement Button allows you to measure customer interest in paying with cryptocurrency before launch. By integrating this button, you can collect customer interactions, emails, and waitlist sign-ups—all without processing any payments immediately.

How It Works

1. Customer clicks “Pay with Crypto” The button records the interaction in our database.
2. Modal opens A pop-up asks the customer if they want to receive updates via email.
3. Customer enters email They are added to your “waitlist” for crypto payments.
4. You get data Track interest, cart sizes, and popular products.

Step 1 – Get Your Merchant ID

1. Log in to your CoinSub Dashboard.
2. Go to Settings → API Keys.
3. Copy your Merchant ID.

Step 2 – Add the Script to Your Website

Place the following script anywhere in your HTML:

<script
        src="https:÷test.coinsub.io/djs/crypto-interest-button.js"
        data-merchant-id="YOUR_MERCHANT_ID_HERE"
        data-button-text="Subscribe with Crypto ⚡"
        data-background-color="rgb(30,30,30)"
        data-button-color="rgb(0, 200, 200)"
        data-button-text-color="rgb(255, 255, 255)"
        data-logo-mode="dark"
        data-cart-size="100"
        data-merchant-industry="Fashion"
        data-product-metadata='{"product_name": "Skirt", "price": 99.99, "category": "clothing"}'
      ></script> 

Step 3 – Customize Button (Optional)

The button can be fully customized using the data-* attributes. Here’s what each field does. You can customize the look of your buttons to match your website’s style. You can find real code examples here.

Step 4 – Collect Data & Analyze

For the APIs you can use to collect data about user engagement/interest use the following set of APIs. This feature is currently restricted to the test environment.