Category: Developer Guide

Technical documentation for integrating Bitcoin & Lightning payments. APIs, plugins, and developer guides for Coinsnap and BTCPay.

How to integrate Coinsnap Pay Links into a custom eCommerce application

Posted on by Jens Leinert

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:

  1. Your eCommerce system creates one Pay Link for one order.
  2. The customer opens the Pay Link.
  3. Coinsnap displays the hosted payment page.
  4. The customer clicks to pay with Bitcoin.
  5. Coinsnap creates a Bitcoin payment invoice based on the current exchange rate.
  6. The customer pays the invoice.
  7. 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-requests

The 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-requests

Step 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

  1. Customer places an order in your eCommerce application.
  2. Your system creates order ORD-2026-1045.
  3. Your application calls the Coinsnap Pay Link API.
  4. Coinsnap returns a unique Pay Link.
  5. Your system stores the Pay Link and attaches it to the order.
  6. The customer receives the order confirmation email with the Bitcoin payment link.
  7. The customer opens the link.
  8. Coinsnap shows the hosted payment page with order details.
  9. The customer clicks to pay with Bitcoin.
  10. Coinsnap creates a fresh Bitcoin payment invoice using the current exchange rate.
  11. The customer pays.
  12. 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.

Coinsnap Payment Link API

Posted on by Jens Leinert

Coinsnap Payment Link API

The Coinsnap Payment Link API allows external systems such as accounting software, invoicing software, ERP systems, or custom applications to generate a Bitcoin payment link for an existing invoice.

A payment link can then be:

  • added to an invoice PDF
  • included in an email
  • displayed in a customer portal
  • embedded in a web application

This allows customers to pay an existing invoice in Bitcoin via Coinsnap.

Use Case

Typical flow:

  1. An external system creates an invoice
  2. The invoice data is sent to Coinsnap
  3. Coinsnap creates a payment link
  4. The payment link is shown to the customer
  5. The customer pays the invoice in Bitcoin
  6. Coinsnap processes the payment
  7. The external system can later reconcile the payment using the invoice number and Coinsnap transaction data

Endpoint

POST /payment-links

Request Body

invoice_number string yes Invoice number from the external system. This is the main reference used for reconciliation.

amount string or number yes Invoice amount in fiat currency.

currency string yes Fiat currency of the invoice, for example EUR or USD.

recipient string yes Name of the merchant or invoice issuer.

customer_email string no Customer email address. Useful for tracking or customer communication.

description string no Human-readable description of the invoice or payment purpose.

redirect_url string no URL to redirect the customer to after successful payment.

discount object no Optional Bitcoin discount configuration.

expiry_date string no Expiration date and time of the payment link in ISO 8601 format.

Discount Object

If a Bitcoin discount should be applied, include the discount object.

Example discount object

{
"type": "percentage",
"value": 5
}

or

{
"type": "absolute",
"value": 10.00
}

Example Request

{
"invoice_number": "RE-2026-00123",
"amount": "100.00",
"currency": "EUR",
"recipient": "Mustermann GmbH",
"customer_email": "customer@example.com",
"description": "Invoice RE-2026-00123",
"redirect_url": "https://merchant.example.com/payment-success",
"discount": {
"type": "percentage",
"value": 5
},
"expiry_date": "2026-12-31T23:59:59Z"
}

Example Response

{
"payment_link": "https://pay.coinsnap.io/payment-requests/4XimFJCJDDTa9f1LWRmHYybauZ1q?type=individual"
}

Response Fields

invoice_number This is the invoice number from the external system, not from Coinsnap.

It is used to:

  • identify the invoice in the merchant system
  • match a payment later in the accounting or invoicing software
  • reconcile Coinsnap payment data with the original invoice

coinsnap_invoice_id This is the Coinsnap-generated technical ID for the payment request.

It is used to:

  • identify the payment request inside Coinsnap
  • reference the payment via API
  • match Coinsnap events and webhooks

amount and currency These define the invoice total that the customer should pay.

recipient This is the merchant name or invoice issuer shown in the payment context.

redirect_url If provided, the customer will be redirected to this URL after payment.

payment_link string Hosted Coinsnap payment page URL

coinsnap_invoice_id string Unique Coinsnap invoice ID for this payment request

expiry_date

If provided, the payment link will no longer be valid after this date.

Validation Rules

External developers should ensure that:

  • invoice_number is unique in their own system
  • amount is greater than zero
  • currency is a supported fiat currency
  • expiry_date, if provided, is a valid ISO 8601 datetime
  • discount.value is greater than zero
  • discount.type is either percentage or absolute

Integration Notes

  • Coinsnap does not create the invoice itself
  • The external application remains the source of truth for invoice creation and invoice numbering
  • Coinsnap only provides the payment link and processes the Bitcoin payment
  • The invoice_number should be stored by the external system for later reconciliation

Example: cURL

curl -X POST "https://api.coinsnap.io/payment-links" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"invoice_number": "RE-2026-00123",
"amount": "100.00",
"currency": "EUR",
"recipient": "Mustermann GmbH",
"customer_email": "customer@example.com",
"description": "Invoice RE-2026-00123",
"redirect_url": "https://merchant.example.com/payment-success",
"discount": {
"type": "percentage",
"value": 5
},
"expiry_date": "2026-12-31T23:59:59Z"
}'

Example: JavaScript

const response = await fetch("https://api.coinsnap.io/payment-links", {
method: "POST",
headers: {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
},
body: JSON.stringify({
invoice_number: "RE-2026-00123",
amount: "100.00",
currency: "EUR",
recipient: "Mustermann GmbH",
customer_email: "customer@example.com",
description: "Invoice RE-2026-00123",
redirect_url: "https://merchant.example.com/payment-success",
discount: {
type: "percentage",
value: 5
},
expiry_date: "2026-12-31T23:59:59Z"
})
});

const data = await response.json();
console.log(data.payment_link);
console.log(data.coinsnap_invoice_id);

Example: PHP

<?php

$payload = [
"invoice_number" => "RE-2026-00123",
"amount" => "100.00",
"currency" => "EUR",
"recipient" => "Mustermann GmbH",
"customer_email" => "customer@example.com",
"description" => "Invoice RE-2026-00123",
"redirect_url" => "https://merchant.example.com/payment-success",
"discount" => [
"type" => "percentage",
"value" => 5
],
"expiry_date" => "2026-12-31T23:59:59Z"
];

$ch = curl_init("https://api.coinsnap.io/payment-links");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
"Authorization: Bearer YOUR_API_KEY",
"Content-Type: application/json"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($payload));

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);

echo $data["payment_link"] . PHP_EOL;
echo $data["coinsnap_invoice_id"] . PHP_EOL;

Example: Python

import requests

url = "https://api.coinsnap.io/payment-links"
headers = {
"Authorization": "Bearer YOUR_API_KEY",
"Content-Type": "application/json"
}

payload = {
"invoice_number": "RE-2026-00123",
"amount": "100.00",
"currency": "EUR",
"recipient": "Mustermann GmbH",
"customer_email": "customer@example.com",
"description": "Invoice RE-2026-00123",
"redirect_url": "https://merchant.example.com/payment-success",
"discount": {
"type": "percentage",
"value": 5
},
"expiry_date": "2026-12-31T23:59:59Z"
}

response = requests.post(url, headers=headers, json=payload)
data = response.json()

print(data["payment_link"])
print(data["coinsnap_invoice_id"])

Example: Minimal Request

{
"invoice_number": "RE-2026-00123",
"amount": "100.00",
"currency": "EUR",
"recipient": "Mustermann GmbH"
}

Minimal Response

{
"payment_link": "https://pay.coinsnap.io/payment-requests/4XimFJCJDDTa9f1LWRmHYybauZ1q?type=individual",
"coinsnap_invoice_id": "cs_inv_123456"
}

Recommended Best Practices

  • Always pass the original invoice_number
  • Store the returned coinsnap_invoice_id
  • Use a meaningful description
  • Use expiry_date for time-limited invoices
  • Use redirect_url for a better payment flow
  • Use discount only when the Bitcoin discount should be visible and applied at payment time

Typical Use Cases

  • Accounting / Invoicing software Generate a Bitcoin payment option for an existing invoice.
  • ERP / CRM systems Add Bitcoin as an alternative payment method.
  • Merchant portals Create payment links dynamically for unpaid invoices.
  • Email invoice workflows Embed the payment link in invoice emails.