Payment

Coinsub API

Introduction

Authentication

Generating API Keys

Subscription Products

Retrieve all Subscription Products

Retrieve Subscriptions For Subscriber

Retrieve Subscriptions For Subscriber and Product Id

Retrieve the Subscription Status of a Product with a Subscriber’s Metadata

Accounts & API Keys

Create an account

Update an account

Retrieve an account

List all connected accounts

Create API Key for connected account

Retrieve API Keys for connected account

Disable API Key for connected account

Delete an account

Merchant Wallet

Wallet Credentials

Wallet Transfers

Wallet Information

Agreements

Cancel an Agreement

Retrieve an agreement

Retrieve all agreements

Payments

Retrieve a payment

Retrieve all payments

Purchase Sessions

Create A Purchase Session

Retrieve Purchase Session Status

Delete Purchase Session 

Purchase Messages

Request Purchase Message to Sign

Submit Signed Purchase Message

Permit Messages

Submit Signed Permit Message

Webhooks

How to Use the Webhooks

Webhook Triggers

Webhook Payloads

Custom Checkout Integration

Creating a Custom Form

Example Use Case

Checkout Button

Basic Integration

Customizing the Button

Theneo Demo TechCrunch

Coinsub Developer Documentation

Production

Development

Sandbox

<h2 class="slate-h2 " ><strong class="slate-bold">Advanced API Structure for Seamless Integration</strong></h2><p class="slate-p " >To enable third-party platforms to integrate Coinsub’s capabilities, we&apos;ve meticulously designed a comprehensive and flexible API structure. Our API facilitates easy integration, providing developers with the tools to incorporate blockchain payment solutions into their applications.</p><h3 class="slate-h3 " ><strong class="slate-bold">Core API Components</strong></h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Secure Authentication</strong>: Utilizing API keys we ensure secure and authorized access to our services.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Blockchain Interaction</strong>: Developers can easily select networks, manage tokens, and authorize transactions, offering unparalleled flexibility across blockchains.</div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Dynamic Payment Processing</strong>: Our API supports the creation and management of various payment types, including one-time invoices, recurring subscriptions, and usage-based billing, with built-in support for handling overdue payments.</div></li></ul><p class="slate-p " ></p><p class="slate-p " >

</p><p class="slate-p " ></p><p class="slate-p " ></p>

Advanced API Structure for Seamless Integration

To enable third-party platforms to integrate Coinsub’s capabilities, we've meticulously designed a comprehensive and flexible API structure. Our API facilitates easy integration, providing developers with the tools to incorporate blockchain payment solutions into their applications.

<p class="slate-p " >At <strong class="slate-bold">Coinsub</strong>, a <strong class="slate-bold">product</strong> is a digital offer created by a merchant that users can purchase in exchange for access to a service, benefit, or digital experience. While many products are traditional subscriptions, they can also represent <strong class="slate-bold">one-time access</strong> or <strong class="slate-bold">single-purchase offerings</strong>.</p><div class="slate-hr"><hr contenteditable="false" class="slate-HrElement-hr"/></div><h3 class="slate-h3 " >Core Aspects of a Coinsub Product:</h3><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Merchant-Defined</strong>:
 Each product is owned and managed by a specific merchant, who determines its pricing, duration, and usage. </div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Descriptive Name</strong>:
 Every product has a clear and user-friendly title that communicates what the offering is. </div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Flexible Pricing Model</strong>:
 Products are priced in U.S. dollars, but payment may be made using crypto. The pricing supports both <strong class="slate-bold">recurring subscriptions</strong> and <strong class="slate-bold">one-time purchases</strong>. </div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Blockchain Integration</strong>:
 Payments are directed to a dedicated blockchain address, enabling secure, on-chain transactions. </div></li><li class="slate-li " ><div style="position:relative"><strong class="slate-bold">Lifecycle Status</strong>:
 Products can be marked as active (available for purchase), inactive (temporarily paused), or discontinued (retired), giving merchants control over their offerings. </div></li></ul><p class="slate-p " ></p>

 is a digital offer created by a merchant that users can purchase in exchange for access to a service, benefit, or digital experience. While many products are traditional subscriptions, they can also represent 

<p class="slate-p " >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. </p><p class="slate-p slate-indent-0" style="0px">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. </p><p class="slate-p " ></p>

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. 

<p class="slate-p " >Coinsub Merchant Wallets are secure, non-custodial wallets powered by <a href="https://www.dfns.co/" target="_self">DFNS’s</a> 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.</p><p class="slate-p " >To get started with a merchant platform wallet of your own, sign up at <a href="https://test.coinsub.io" target="">test.coinsub.io</a> (development environment) or <a href="https://app.coinsub.io" target="">app.coinsub.io</a> (production).</p><p class="slate-p " >Signing up on the platform will get you a merchant wallet and setup your initial default passkey. If you&apos;re interested you can take a look at a short video below. </p><p class="slate-p " ></p><div class="iframe-embed"><iframe
                        title="embed"
                        frameBorder="0"
                        allowFullScreen=""
                        src="https://www.youtube.com/embed/fMUpygfdrrY"
                        id="fMUpygfdrrY"
                        provider="youtube"
                        class="slate-MediaEmbedElement-iframe"
                        width="100%"
                    ></iframe></div><p class="slate-p " ></p><p class="slate-p " ></p>

Coinsub Merchant Wallets are secure, non-custodial wallets powered by 

 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 

Signing up on the platform will get you a merchant wallet and setup your initial default passkey. If you're interested you can take a look at a short video below. 

<p class="slate-p " >Payment agreements generate recurring payments through Coinsub&apos;s payment network based on the pre-defined agreements signed by the customer. The customer is required to agree to any changes to a payment agreement. </p><p class="slate-p " ></p><p class="slate-p " ></p>

Payment agreements generate recurring payments through Coinsub's payment network based on the pre-defined agreements signed by the customer. The customer is required to agree to any changes to a payment agreement. 

<p class="slate-p " >Payments in this system represent transactions that merchants receive from their customers. Each payment record contains important information about a transaction, such as:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">The amount paid</div></li><li class="slate-li " ><div style="position:relative">The currency used (like USDC)</div></li><li class="slate-li " ><div style="position:relative">When the payment was made</div></li><li class="slate-li " ><div style="position:relative">The status of the payment</div></li><li class="slate-li " ><div style="position:relative">Details about the customer</div></li><li class="slate-li " ><div style="position:relative">Information about what was purchased</div></li><li class="slate-li " ><div style="position:relative">Whether it was a one-time purchase or part of a subscription</div></li></ul><p class="slate-p " >Merchants can use this service to:</p><ul class="slate-ul " ><li class="slate-li " ><div style="position:relative">View their complete payment history</div></li><li class="slate-li " ><div style="position:relative">Look up specific payment details</div></li><li class="slate-li " ><div style="position:relative">Monitor transaction statuses</div></li><li class="slate-li " ><div style="position:relative">Keep records of customer purchases</div></li></ul><p class="slate-p " >This helps merchants keep track of their business transactions and maintain a clear record of all payments they&apos;ve received through the platform.</p><p class="slate-p " ></p>

Payments in this system represent transactions that merchants receive from their customers. Each payment record contains important information about a transaction, such as:

This helps merchants keep track of their business transactions and maintain a clear record of all payments they've received through the platform.

<p class="slate-p " >A crypto payment system purchase session is a digital payment request, enabling users to specify and request a cryptocurrency amount from another party. 

Upon creation, the system generates a unique URL for the session, including details on the payment amount (if specified) and any additional instructions or metadata. This URL can be shared via email, messaging, QR code, or other methods, directing the payer to a secure payment interface to complete the transaction using their crypto wallet. This approach ensures precise payment amounts and offers a clear, trackable way to request and receive crypto payments, making it ideal for businesses, freelancers, and anyone needing a straightforward method for crypto transactions.
Purchase sessions securely transmit user information to Coinsub upon initialization using a secure backchannel. Sessions can also be set to expire after a certain period, allowing for expirable quotes and adding a layer of security to the payment process.

</p><p class="slate-p " ></p><p class="slate-p " ></p>

A crypto payment system purchase session is a digital payment request, enabling users to specify and request a cryptocurrency amount from another party. 

Upon creation, the system generates a unique URL for the session, including details on the payment amount (if specified) and any additional instructions or metadata. This URL can be shared via email, messaging, QR code, or other methods, directing the payer to a secure payment interface to complete the transaction using their crypto wallet. This approach ensures precise payment amounts and offers a clear, trackable way to request and receive crypto payments, making it ideal for businesses, freelancers, and anyone needing a straightforward method for crypto transactions.
Purchase sessions securely transmit user information to Coinsub upon initialization using a secure backchannel. Sessions can also be set to expire after a certain period, allowing for expirable quotes and adding a layer of security to the payment process.



<p class="slate-p " ></p><p class="slate-p " >Purchase messages are designed for integrators who want to build and control their own checkout experience. Instead of redirecting customers to a hosted checkout page, integrators request a raw payload from Coinsub, which contains all necessary transaction details.</p><p class="slate-p " >The integrator then signs this payload on the client or server side using their private key, following the <a href="https://eips.ethereum.org/EIPS/eip-712" target="_blank">EIP-712</a> structured data signing standard. Once signed, the integrator submits the message back to Coinsub’s API to finalize the transaction.</p><p class="slate-p " >This approach gives developers full flexibility over the user interface and transaction flow, while still leveraging Coinsub’s backend for transaction processing, validation, and reconciliation.</p><div class="slate-div"><p class="slate-p " >A short demo on how to sign a message using EIP-712 is available here: <a href="https://codesandbox.io/p/sandbox/eip712-forked-2scgy6" target="_blank">CodeSandbox EIP-712 Demo</a></p></div><p class="slate-p " ></p>

Purchase messages are designed for integrators who want to build and control their own checkout experience. Instead of redirecting customers to a hosted checkout page, integrators request a raw payload from Coinsub, which contains all necessary transaction details.

The integrator then signs this payload on the client or server side using their private key, following the 

 structured data signing standard. Once signed, the integrator submits the message back to Coinsub’s API to finalize the transaction.

This approach gives developers full flexibility over the user interface and transaction flow, while still leveraging Coinsub’s backend for transaction processing, validation, and reconciliation.

<p class="slate-p " >Permit messages enable gasless token approvals by allowing users to sign an off-chain message that authorizes Coinsub’s smart contract to spend their tokens. Instead of requiring an on-chain approval transaction—which costs gas—users can simply sign a structured message with their wallet. This reduces friction at checkout and makes the payment process faster and more cost-effective.</p><p class="slate-p " >When you submit a signed purchase session, Coinsub checks whether the user has already approved token spending. If so, the payment is processed immediately. If not, the response will include a permit message in typed data format. You can present this message to the user for signing. Once signed, submit it to Coinsub to complete the approval and proceed with the transaction—all without requiring an additional on-chain approval step.</p><p class="slate-p " ></p>

Permit messages enable gasless token approvals by allowing users to sign an off-chain message that authorizes Coinsub’s smart contract to spend their tokens. Instead of requiring an on-chain approval transaction—which costs gas—users can simply sign a structured message with their wallet. This reduces friction at checkout and makes the payment process faster and more cost-effective.

When you submit a signed purchase session, Coinsub checks whether the user has already approved token spending. If so, the payment is processed immediately. If not, the response will include a permit message in typed data format. You can present this message to the user for signing. Once signed, submit it to Coinsub to complete the approval and proceed with the transaction—all without requiring an additional on-chain approval step.

<p class="slate-p " >Webhooks allow real-time communication between systems.</p><p class="slate-p " >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.</p><p class="slate-p " >CoinSub 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 CoinSub in real-time.</p><p class="slate-p " ></p>

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.

CoinSub 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 CoinSub in real-time.

<p class="slate-p " >If you prefer to create a custom implementation for integrating Coinsub subscription payments without using the provided widget, you can directly create a form that posts to the Coinsub server. Below is a guide on how to achieve this.</p><p class="slate-p " ></p>

If you prefer to create a custom implementation for integrating Coinsub subscription payments without using the provided widget, you can directly create a form that posts to the Coinsub server. Below is a guide on how to achieve this.

<p class="slate-p " >The Checkout Button section guides users on integrating a customizable button into their website for subscription payments. Users can enhance the button&apos;s appearance and functionality by using various data attributes. This section empowers users to seamlessly enable subscription payments through the Checkout Button widget.</p><h1 class="slate-h1 " >Integrating Checkout Button</h1><p class="slate-p " >This guide will walk you through the process of integrating checkout button into your website to enable subscription payments using our widget. You can customize the button&apos;s appearance and behavior using various data attributes.</p><p class="slate-p " ></p><div style="text-align:center"><img src="https://d24lr4zqs1tgqh.cloudfront.net/4859436e-dcc3-4c30-b6da-0b6ba3e32edc.jpg" style="
              width:330px;
	            height:242px;
	            aspect-ratio:330 / 242"
         /></div><p class="slate-p " ></p>

The Checkout Button section guides users on integrating a customizable button into their website for subscription payments. Users can enhance the button's appearance and functionality by using various data attributes. This section empowers users to seamlessly enable subscription payments through the Checkout Button widget.

This guide will walk you through the process of integrating checkout button into your website to enable subscription payments using our widget. You can customize the button's appearance and behavior using various data attributes.

Sections