Overview
The Coinsnap Pay Link API allows merchants to add Bitcoin payments to their own eCommerce application, even if a direct Bitcoin integration into the normal checkout is not possible or not practical.
Instead of integrating Bitcoin as a live payment method directly into the shop checkout, the merchant creates a unique Pay Link for each order or invoice. This link contains all relevant payment details in advance, such as the order ID or invoice number, amount, currency, and optional customer information.
The Pay Link can then be shown to the customer after checkout, included in an order confirmation email, attached to an invoice PDF, or displayed in a customer account area.
When the customer opens the Pay Link, Coinsnap shows a hosted payment page with the order details already prefilled. If the customer chooses to proceed with Bitcoin payment, Coinsnap generates a fresh Bitcoin payment invoice using the current exchange rate. The customer can then pay via Bitcoin or Lightning.
This approach is especially useful for:
- custom eCommerce applications without a standard Coinsnap plugin
- shop systems where direct checkout integration would be too complex
- invoice-based payment flows
- marketplaces, B2B ordering systems, and service platforms
- situations where Bitcoin should be offered as an additional payment option next to bank transfer
How the payment flow works
Before starting the technical integration, it is important to understand the difference between the Pay Link and the Bitcoin payment invoice.
A Pay Link is the merchant-facing payment request for one specific order or invoice.
A Bitcoin payment invoice is the technical payment request that Coinsnap generates only when the customer actually starts the Bitcoin payment process.
This means:
- Your eCommerce system creates one Pay Link for one order.
- The customer opens the Pay Link.
- Coinsnap displays the hosted payment page.
- The customer clicks to pay with Bitcoin.
- Coinsnap creates a Bitcoin payment invoice based on the current exchange rate.
- The customer pays the invoice.
- If the invoice expires unpaid, the same Pay Link can be opened again later to generate a new Bitcoin payment invoice for the same order.
So the Pay Link remains tied to the same order, while the actual Bitcoin invoice may be recreated if a previous payment attempt expired.
Step 1: Decide where the Pay Link should be used in your eCommerce flow
The first step is to decide at which point in your application the Pay Link should be created and shown to the customer.
Typical options are:
Option A: After order confirmation
The customer places the order first. After the order is created, your system generates a Coinsnap Pay Link and shows it on the confirmation page.
This is useful when Bitcoin is offered as an alternative payment method after checkout.
Option B: In the order confirmation email
Your system generates the Pay Link after the order is created and includes it in the email sent to the customer.
This is useful when the customer may want to pay later.
Option C: In the customer account area
The order is created as unpaid in your system. The customer can later log in and click “Pay with Bitcoin” from the order overview.
Option D: Attached to an invoice
If your business sends invoices, the Pay Link can be added to the invoice email or PDF, similar to how bank transfer instructions are normally shown.
For many merchants, this is the easiest way to understand the purpose of the Pay Link:
Instead of printing IBAN, bank name, payment reference, and amount on the invoice, you provide a Bitcoin payment link that already includes all payment data.
Step 2: Create the order in your own eCommerce system first
Before you call the Coinsnap API, your own system should already create the order or invoice internally.
This is important because the Pay Link should always belong to a specific business transaction.
At minimum, you should already have:
- your own internal order ID or invoice number
- the order amount
- the currency
- optionally the customer name or email
- optionally a description for the payment
- optionally a success URL where the customer should return after payment
Example:
- Order ID: ORD-2026-1045
- Customer: John Smith
- Amount: 149.00
- Currency: EUR
This order ID becomes the key reference between your eCommerce system and Coinsnap.
Step 3: Create a Pay Link via the Coinsnap API
Once the order exists in your own system, your application sends a request to Coinsnap to create a Pay Link.
Endpoint:
POST /api/v1/stores/{storeId}/payment-requestsThe request should contain the core payment data for that order.
Typical fields include:
- amount
- title
- currency
- orderId
- description
- redirectUrl
- customerEmail
- discount
- internalNote
- expiryDate
Example request:
{
"amount": 149.00,
"title": "John Smith",
"currency": "EUR",
"orderId": "ORD-2026-1045",
"description": "Order ORD-2026-1045",
"redirectUrl": "https://yourshop.com/payment-success",
"customerEmail": "john@example.com",
"discount": 5,
"internalNote": "Custom webshop order"
}What these fields mean
amount The fiat amount the customer should pay.
title A customer-facing label, usually the customer name, company name, or order label.
currency The currency of the original order, for example EUR or USD.
orderId Your own reference, such as the order number or invoice number.
description A short human-readable explanation shown to the customer.
redirectUrl The URL where the customer should be sent after successful payment.
customerEmail An optional pre-filled customer email address.
discount Optional Bitcoin discount, if you want to reward Bitcoin payments.
internalNote Optional note visible only to the merchant.
Step 4: Store the returned Pay Link in your own system
When Coinsnap successfully creates the Pay Link, the API returns a response like this:
{
"id": "3JUseUusmduemKeJkv3H",
"url": "https://pay-link.coinsnap.io/payment-requests/3JUseUusmduemKeJkv3H?type=individual"
}You should store both values in your own database:
- the Coinsnap Pay Link ID
- the Pay Link URL
You should also store them together with your own order record.
Step 5: Show the Pay Link to the customer
After the Pay Link has been created, your application can present it in different ways.
On a confirmation page
Pay this order with Bitcoin
In an email
Click here to pay your invoice with Bitcoin
In a PDF invoice
You can insert the link as clickable text or as a QR code.
In the customer account
You can display the payment button only while the order is still unpaid.
Step 6: What the customer experiences
When the customer opens the Pay Link, they do not immediately see a Bitcoin QR code.
Instead, they first see a hosted Coinsnap payment page with the prefilled order details.
- who the payment is for
- what amount is due
- which currency applies
- which order or invoice the payment belongs to
When the customer clicks Pay with Bitcoin, Coinsnap then creates the actual Bitcoin payment invoice.
- the fiat amount is converted into Bitcoin
- the current exchange rate is applied
- the customer receives the QR code and payment details
- the Bitcoin invoice is valid only for a limited time
If the customer pays within the validity period, the order can be marked as paid.
If the customer does not pay in time, the Bitcoin invoice expires. The customer can later reopen the same Pay Link and start again.
Step 7: Check the status of the Pay Link
GET /api/v1/stores/{storeId}/payment-requests/{id}GET /api/v1/stores/{storeId}/payment-requestsStep 8: Mark the order correctly in your own eCommerce system
- Order created → status: pending payment
- Pay Link created → status: awaiting bitcoin payment
- Bitcoin payment completed → status: paid
- Order fulfilled → status: completed
Step 9: Use Pay Links where checkout integration is not possible
- custom-built order systems
- older enterprise software
- ERP-driven ordering portals
- B2B systems with invoice-based payment
- special workflows where the total is confirmed manually before payment
Step 10: Recommended implementation logic
- One Pay Link per order or invoice
- Always store your own reference ID
- Keep your own order system as the master
- Treat the Pay Link as customer-facing
- Treat the Bitcoin invoice as technical
- Keep the payment process simple
Example end-to-end flow
- Customer places an order in your eCommerce application.
- Your system creates order ORD-2026-1045.
- Your application calls the Coinsnap Pay Link API.
- Coinsnap returns a unique Pay Link.
- Your system stores the Pay Link and attaches it to the order.
- The customer receives the order confirmation email with the Bitcoin payment link.
- The customer opens the link.
- Coinsnap shows the hosted payment page with order details.
- The customer clicks to pay with Bitcoin.
- Coinsnap creates a fresh Bitcoin payment invoice using the current exchange rate.
- The customer pays.
- Your application updates the order to paid.
Why this is useful for non-technical merchants
A non-technical merchant can think of the Coinsnap Pay Link like this:
It is similar to adding a payment button to an invoice.
Instead of telling the customer:
- please transfer EUR 149.00
- to this bank account
- with this payment reference
the merchant simply sends:
- here is your Bitcoin payment link
The customer clicks the link and pays with Bitcoin.
All important payment details are already included.
This reduces friction, avoids input mistakes, and makes Bitcoin usable even in business workflows that were originally designed for bank transfers.
Summary
The Coinsnap Pay Link API is a practical way to add Bitcoin payments to a custom eCommerce application without requiring a full checkout integration.
The merchant creates one unique Pay Link for each order or invoice. The customer opens that link and starts the payment. Coinsnap then creates the actual Bitcoin payment invoice using the current exchange rate.
This makes Pay Links ideal for:
- custom eCommerce systems
- invoice-based payment flows
- order confirmation emails
- customer account payment pages
- accounting and ERP-driven payment requests
In short:
Your eCommerce system manages the order.
Coinsnap manages the Bitcoin payment flow.
The Pay Link connects both.
Simply print on the invoice
Send flexibly
One link for all customers
Self-hosted form (HTML version):
