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.