> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blockradar.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Stablecoin Checkout

> Create and manage checkout payment links for seamless stablecoin payments

<Note>
  In a nutshell<br />
  Blockradar Checkout lets you accept stablecoin payments via shareable links—no customer accounts or complex integrations required. Create a link, share it, and receive payments directly to your wallet.
</Note>

<iframe className="w-full h-[500px]" height="315" src="https://www.youtube.com/embed/nHCakfoSPWw?si=zar81as8HDK-HMrB" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen />

## Prerequisites

Before creating payment links, ensure you have:

<Steps>
  <Step title="API Key">
    Get your API key from the [Blockradar Dashboard](https://dashboard.blockradar.co). Navigate to **Developers** to generate one.
  </Step>

  <Step title="Master Wallet Created">
    Create a master wallet via the [Create Wallet API](/en/api-reference/wallets/create-wallet) or dashboard. Payment links are tied to a wallet.
  </Step>

  <Step title="Checkout Plan Active">
    Ensure the Checkout feature is enabled on your account. Contact [support@blockradar.co](mailto:support@blockradar.co) if you need to activate it.
  </Step>

  <Step title="Webhook Configured (Optional)">
    Set up webhooks to receive real-time payment notifications. See [Webhooks](/en/essentials/webhooks) for setup details.
  </Step>
</Steps>

## Introduction

Payment links are shareable URLs that allow anyone to send stablecoin payments to your wallet. They're perfect for:

* **E-commerce**: Send to customers for product purchases
* **Invoicing**: Include in invoices for services rendered
* **Donations**: Share on social media or websites
* **Marketplace payments**: Facilitate peer-to-peer transactions
* **Subscription billing**: Recurring payment collection

## How Payment Links Work

<CardGroup cols={2}>
  <Card title="Creation" icon="plus">
    Create a payment link with specific parameters like amount, name,
    description, and payment limits.
  </Card>

  <Card title="Sharing" icon="share">
    Share the generated URL with your customers through email, messaging, or
    embed it on your website.
  </Card>

  <Card title="Payment" icon="credit-card">
    Customers click the link, enter their payment details, and complete the
    transaction.
  </Card>

  <Card title="Confirmation" icon="check">
    You receive webhook notifications and can track payment status in real-time.
  </Card>
</CardGroup>

## Payment Link Features

* **Customizable Parameters**: Set amount, description, payment limits, and metadata
* **Shareable URLs**: Generate unique payment links for each transaction
* **Customer Pre-filling**: Pre-populate customer details via URL query parameters
* **Real-time Tracking**: Monitor payment status and receive webhook notifications
* **Multi-network Support**: Accept payments across different blockchain networks
* **Auto-sweep Integration**: Funds automatically consolidated to master wallet

### **Multi-Asset Support**

* **USDT, USDC, DAI, BUSD** across multiple blockchains
* **Ethereum, BSC, Polygon, Base, Arbitrum, Optimism, Tron, Solana, Celo**
* Automatic conversion and routing for optimal user experience

### **Flexible Configuration**

* **Fixed amounts** for specific products/services
* **Variable amounts** for donations or custom payments
* **Payment limits** to ensure timely payments
* **Custom metadata** for tracking and analytics
* **Webhook notifications** for real-time updates

### **Security & Compliance**

* **AML screening** on all incoming payments
* **Address validation** and verification
* **Fraud detection** and prevention
* **Regulatory compliance** across jurisdictions

## Payment Flow

### **1. Payment Link Creation**

When you create a payment link, Blockradar returns a unique payment URL:

```json theme={null}
{
  "id": "pl_123456789",
  "name": "Product Purchase",
  "url": "https://pay.blockradar.co/payment-link-10012",
  "amount": "100.00",
  "currency": "USD",
  "active": true
}
```

### **2. Customer Pre-filling with Query Parameters**

You can enhance the payment URL with query parameters to automatically pre-fill customer details on the payment page:

```
https://pay.blockradar.co/payment-link-10012?name=Customer&email=customer@example.com&reference=ORDER123&amount=99.99&redirectUrl=https://yoursite.com/payment-success
```

**Supported Optional Query Parameters:**

* `name` - Customer's name (appears on payment page)
* `email` - Customer's email address
* `reference` - Custom reference that will be included in transaction responses
* `amount` - Pre-fill the payment amount (overrides link's default amount if set)
* `redirectUrl` - URL to redirect to after payment completion

### **3. Post-Payment Redirect**

When a `redirectUrl` is provided, customers will be automatically redirected to your specified URL after payment processing is complete. The redirect URL will include the following query parameters:

**Redirect Query Parameters:**

* `status` - Payment status (`success`, `failed`, `pending`)
* `tx_reference` - Transaction reference ID
* `reference` - Your custom reference (if provided)
* `slug` - Payment link identifier

**Example Redirect URL:**

```
https://yoursite.com/payment-success?status=success&tx_reference=tx_abc123&reference=ORDER123&slug=payment-link-10012
```

<Note>
  The redirect only occurs after payment processing is complete. If no
  `redirectUrl` is provided, customers will see the default payment completion
  page.
</Note>

### **4. Amount Configuration**

Payment links support two amount modes:

**Fixed Amount (Pre-set)**

* When you specify an `amount` during creation, customers cannot modify the payment amount
* Ideal for specific products or services with set pricing
* Example: Product purchase for exactly \$99.99

**Variable Amount (Customer Input)**

* When no `amount` is specified, customers can enter their own payment amount
* Perfect for donations, tips, or flexible pricing scenarios
* Customers see an amount input field on the payment page

### **4. Payment Processing**

Customers visit the payment link, review pre-filled details, and complete the transaction using their preferred stablecoin.

### **5. Transaction Response**

The `reference` parameter from the URL will be included in the transaction response and webhook payloads, allowing you to link payments back to your internal systems.

## Try It Out

Experience Blockradar payment links firsthand with our live demo:

**🔗 Demo Payment Link**: [https://pay.blockradar.co/demo](https://pay.blockradar.co/demo)

This demo showcases:

* **Payment Flow**: Complete customer experience from link to completion
* **UI/UX**: Modern, intuitive payment interface
* **Stablecoin Options**: Multiple payment methods and networks
* **Real-time Updates**: Live transaction status and confirmations

<Note>
  The demo payment link is for testing purposes only. No real transactions will
  be processed.
</Note>

## Creating Payment Links

### **Basic Payment Link**

Create a simple payment link for a fixed amount:

```json theme={null}
{
  "name": "Product Purchase",
  "description": "Payment for Laptop Pro 2024",
  "amount": "100.00",
  "redirectUrl": "https://store.example.com/thank-you",
  "successMessage": "Thank you for your purchase!",
  "metadata": "{\"product_id\": \"prod_123\", \"order_id\": \"ord_456\"}"
}
```

### **Variable Amount Payment Link**

Allow customers to choose their payment amount:

```json theme={null}
{
  "name": "Donation Campaign",
  "description": "Support our disaster relief efforts",
  "redirectUrl": "https://charity.example.com/thank-you",
  "successMessage": "Thank you for your generous donation!",
  "metadata": "{\"campaign\": \"disaster_relief_2024\"}"
}
```

### **Payment Link with File Upload**

Include a file (e.g., invoice, product image) with your payment link using form-data:

**Form Data Fields:**

* `name`: Service Invoice
* `description`: Web development services - January 2024
* `amount`: 1500.00
* `redirectUrl`: [https://company.example.com/payment-success](https://company.example.com/payment-success)
* `successMessage`: Payment received! We'll start working on your project.
* `metadata`: invoice\_id: INV-2024-001, service: web\_development
* `file`: \[cover.png] (file upload)

<Note>
  When including file uploads, use form-data instead of JSON. The file will be
  stored and accessible via the payment link.
</Note>

## Payment Link Parameters

### **Required Parameters**

| Parameter | Type              | Description                  |
| --------- | ----------------- | ---------------------------- |
| `name`    | string (max: 250) | The name of the payment link |

### **Optional Parameters**

| Parameter         | Type                 | Description                                                                                       |
| ----------------- | -------------------- | ------------------------------------------------------------------------------------------------- |
| `description`     | string (max: 250)    | A description of the payment link                                                                 |
| `slug`            | string (max: 250)    | A unique identifier (URL-friendly). Must match regex: `^[a-zA-Z0-9-]+$`                           |
| `amount`          | string               | The amount for the payment link. Must be a valid string number > 0                                |
| `redirectUrl`     | string (URL)         | The URL to redirect the user after payment. Must include http\:// or https\://                    |
| `successMessage`  | string (max: 500)    | Message shown when the payment succeeds                                                           |
| `inactiveMessage` | string (max: 500)    | Message shown when the payment link is inactive                                                   |
| `metadata`        | object (JSON string) | Custom metadata as key-value pairs (string or number). Must be sent as a JSON string in form-data |
| `paymentLimit`    | number (min: 1)      | Maximum number of payments allowed for this link                                                  |
| `file`            | file                 | An optional file upload (e.g., image or document) attached to the payment link                    |

## Payment Flow

### **Customer Experience**

1. **Click Payment Link**

   * Customer receives and clicks the payment link
   * Link opens to a secure payment page

2. **Select Payment Method**

   * Choose from available stablecoins
   * Select preferred blockchain network
   * Enter payment amount (if variable)

3. **Complete Payment**

   * Customer confirms transaction details
   * Payment is processed on the blockchain
   * Real-time confirmation and status updates

4. **Success Confirmation**
   * Payment confirmation page
   * Optional redirect to your website
   * Receipt and transaction details

### **Merchant Experience**

1. **Real-time Notifications**

   * Webhook events for payment status
   * Email notifications (if configured)
   * Dashboard updates

2. **Payment Tracking**
   * Transaction history and status
   * Payment analytics and reporting
   * Integration with your systems

## Address Lifecycle

<Warning>
  Payment addresses generated for checkout links have a limited lifecycle:

  * **After successful payment**: The address is immediately deactivated and cannot receive additional payments
  * **After 24 hours of inactivity**: If no payment is made to an address within 24 hours, it is automatically deactivated

  Each new payment session generates a fresh address. This ensures security and prevents address reuse.
</Warning>

## Webhook Events

Payment links trigger the following webhook events when payments are received:

| Event             | Description                               |
| ----------------- | ----------------------------------------- |
| `deposit.success` | Payment was received via the payment link |
| `deposit.failed`  | Payment attempt failed                    |

### **Webhook Payload Example**

```json theme={null}
{
  "event": "deposit.success",
  "data": {
    "id": "0d7a0b98-943c-48d0-8baa-216c29956050",
    "reference": "bjXPk7d00",
    "senderAddress": "0x451dEFC27B45808078e875556AF06bCFdC697BA4",
    "recipientAddress": "0x9D8dF15628B737CAf63a92Abd8E8bb304210eA94",
    "tokenAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "amount": "1",
    "amountPaid": "1",
    "amountUSD": "1",
    "rateUSD": "1",
    "fee": null,
    "feeHash": null,
    "currency": "USD",
    "toCurrency": null,
    "blockNumber": 34771099,
    "blockHash": "0xa9dc060dbe649676a15ae1faee725851fe1ecf2401b200e60fff33fc0ff41e84",
    "hash": "0x9f01af8f517afb3fd3ee17f36dabee03a4d6514885473115815de86c28ea7dfb",
    "confirmations": 6,
    "confirmed": true,
    "gasPrice": "7026436",
    "gasUsed": "62159",
    "gasFee": "0.000000436756235324",
    "status": "SUCCESS",
    "type": "DEPOSIT",
    "note": null,
    "amlScreening": {
      "provider": "ofac, fbi, tether, circle",
      "status": "success",
      "message": "Address is not sanctioned"
    },
    "assetSwept": true,
    "assetSweptAt": "2025-08-27T21:53:22.300Z",
    "assetSweptGasFee": "0.000000489848406004",
    "assetSweptHash": "0xe85efcf15ff8eaa2429aea32515347d65ff8098f22dac567611c258441bde809",
    "assetSweptSenderAddress": "0x9D8dF15628B737CAf63a92Abd8E8bb304210eA94",
    "assetSweptRecipientAddress": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43",
    "assetSweptAmount": "1",
    "reason": "Funds swept successfully",
    "network": "mainnet",
    "chainId": 8453,
    "metadata": {},
    "toAmount": null,
    "signedTransaction": null,
    "rate": null,
    "createdAt": "2025-08-27T21:52:19.839Z",
    "updatedAt": "2025-08-27T21:53:22.303Z",
    "asset": {
      "id": "3a18a31a-86ad-44a0-9b9c-cdb69d535c64",
      "name": "USD Coin",
      "symbol": "USDC",
      "decimals": 6,
      "address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "standard": null,
      "currency": "USD",
      "isActive": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800083/crypto-assets/usd-coin-usdc-logo_fs9mhv.png",
      "network": "mainnet",
      "isNative": false,
      "createdAt": "2024-06-08T12:59:11.303Z",
      "updatedAt": "2025-06-03T11:34:36.288Z"
    },
    "address": {
      "id": "824d8ff9-1ee4-43d1-bec0-c77f25699cd6",
      "address": "0x9D8dF15628B737CAf63a92Abd8E8bb304210eA94",
      "name": null,
      "isActive": true,
      "type": "INTERNAL",
      "derivationPath": "m/44'/60'/0'/0/503",
      "metadata": null,
      "configurations": {
        "aml": {
          "status": "success",
          "message": "Address is not sanctioned",
          "provider": "ofac, fbi, tether, circle"
        }
      },
      "network": "mainnet",
      "createdAt": "2025-08-27T21:52:19.839Z",
      "updatedAt": "2025-08-27T21:52:19.839Z"
    },
    "blockchain": {
      "id": "28a730d3-211b-40f7-bb8f-dd589dcc738e",
      "name": "base",
      "symbol": "eth",
      "slug": "base",
      "derivationPath": "m/44'/60'/0'/0",
      "isEvmCompatible": true,
      "isL2": true,
      "logoUrl": "https://res.cloudinary.com/blockradar/image/upload/v1716800080/crypto-assets/Base_Network_Logo_vqyh7r.png",
      "isActive": true,
      "tokenStandard": null,
      "createdAt": "2024-06-07T11:09:56.586Z",
      "updatedAt": "2025-11-26T15:26:21.825Z"
    },
    "wallet": {
      "id": "6b741fbc-8a9c-48a1-92b0-ae7b52de8b9e",
      "name": "Base Mainnet Wallet",
      "description": "This is base mainnet wallet",
      "address": "0xb55c054D8eE75224E1033e6eC775B4F62D942b43",
      "derivationPath": "m/44'/60'/0'/0/0",
      "isActive": true,
      "status": "ACTIVE",
      "network": "mainnet",
      "configurations": {
        "withdrawal": {
          "gasless": {
            "isActive": true
          }
        },
        "autoSweeping": {
          "isActive": true
        }
      },
      "createdAt": "2024-06-15T02:53:23.409Z",
      "updatedAt": "2025-08-18T23:26:13.469Z",
      "business": {
        "id": "a109729b-3b97-4fb3-a90a-769a0cbf6a25",
        "name": "Blockradar",
        "sector": "infrastructure",
        "userId": "831b739e-ed85-499a-b273-8a1a5b41b7a0",
        "status": "ACTIVE",
        "pipedriveOrganizationId": "308",
        "createdAt": "2023-04-28T17:40:18.541Z",
        "updatedAt": "2025-06-19T23:51:01.019Z"
      }
    },
    "beneficiary": null,
    "paymentLink": {
      "id": "dd8eb830-0971-4f61-97bc-b1ad352e1c48",
      "name": "Blockradar Checkout Demo",
      "description": "Blockradar payment links simplify stablecoin transactions into a clean, intuitive experience. This demo shows how users can pay securely using stablecoins with just a few clicks, fast, transparent, and onchain.",
      "slug": "demo",
      "amount": null,
      "currency": "USD",
      "imageUrl": "https://res.cloudinary.com/blockradar/image/upload/v1752049884/payment-links/ndlbgyb5wg70bpr3p1uu.png",
      "redirectUrl": null,
      "successMessage": null,
      "active": true,
      "inactiveMessage": null,
      "network": "mainnet",
      "type": "payment",
      "createdChannel": "dashboard",
      "metadata": {},
      "configurations": {},
      "createdAt": "2024-06-20T05:38:13.863Z",
      "updatedAt": "2025-07-09T08:31:25.328Z"
    },
    "toAsset": null,
    "toBlockchain": null,
    "toWallet": null
  }
}
```

### **Key Webhook Data Fields**

The webhook payload includes comprehensive information about the payment:

| Field          | Description                                                              |
| -------------- | ------------------------------------------------------------------------ |
| `reference`    | Custom reference from URL query parameters (e.g., ORDER123, customer ID) |
| `paymentLink`  | Complete payment link details including name, description, and metadata  |
| `asset`        | Asset information (USDC, USDT, etc.) with network details                |
| `blockchain`   | Network information (Base, Ethereum, etc.)                               |
| `wallet`       | Master wallet details and configurations                                 |
| `address`      | Customer address that received the payment                               |
| `amlScreening` | Anti-money laundering screening results                                  |
| `assetSwept`   | Auto-sweep status and details                                            |
| `metadata`     | Custom data from the payment link                                        |

<Note>
  The `reference` field in webhook payloads corresponds to the `reference` query
  parameter you include in the payment URL. This allows you to track payments
  back to specific orders, customers, or internal references in your system.
</Note>

## Best Practices

### **Security**

* **Use HTTPS** for all payment link sharing
* **Monitor webhook events** for suspicious activity
* **Implement rate limiting** on your webhook endpoints

### **User Experience**

* **Clear descriptions** of what the payment is for
* **Mobile-optimized** payment pages
* **Multiple payment options** when possible

### **Integration**

* **Store payment link IDs** for tracking
* **Use metadata** to link payments to your systems
* **Implement webhook retry logic** for reliability
* **Test webhooks** in sandbox environment first

## Use Cases & Examples

### **E-commerce Store**

```json theme={null}
{
  "name": "Laptop Pro 2024",
  "description": "High-performance laptop with latest specifications",
  "amount": "299.99",
  "redirectUrl": "https://store.example.com/thank-you",
  "successMessage": "Thank you for your purchase! Your order has been confirmed.",
  "metadata": "{\"product_id\": \"laptop_pro_2024\", \"category\": \"electronics\", \"customer_email\": \"customer@example.com\"}",
  "paymentLimit": 1
}
```

### **Service Invoice**

```json theme={null}
{
  "name": "Web Development Services",
  "description": "Professional web development services - January 2024",
  "amount": "1500.00",
  "redirectUrl": "https://company.example.com/payment-success",
  "successMessage": "Payment received! We'll start working on your project immediately.",
  "metadata": "{\"invoice_id\": \"INV-2024-001\", \"service\": \"web_development\", \"client_id\": \"client_789\"}",
  "paymentLimit": 1
}
```

### **Donation Campaign**

```json theme={null}
{
  "name": "Disaster Relief 2024",
  "description": "Support our disaster relief efforts in affected regions",
  "amount": "10.00",
  "redirectUrl": "https://charity.example.com/thank-you",
  "successMessage": "Thank you for your generous donation! Every contribution makes a difference.",
  "metadata": "{\"campaign\": \"disaster_relief_2024\", \"organization\": \"charity_foundation\", \"tax_deductible\": true}",
  "paymentLimit": 1000
}
```

### **Subscription Service**

```json theme={null}
{
  "name": "Premium Plan Monthly",
  "description": "Monthly subscription to our premium service",
  "amount": "29.99",
  "redirectUrl": "https://service.example.com/welcome",
  "successMessage": "Welcome to Premium! Your subscription is now active.",
  "metadata": "{\"plan\": \"premium_monthly\", \"billing_cycle\": \"monthly\", \"features\": \"unlimited_access\"}",
  "paymentLimit": 100
}
```

<Note>
  These examples use the correct Blockradar payment links API parameters. The
  `metadata` field must be sent as a JSON string in form-data, and `file`
  uploads are supported for additional content.
</Note>

## Testing & Development

### **Sandbox Environment**

* Use testnet networks for development
* Test webhook delivery and handling
* Verify payment flows end-to-end
* Test edge cases and error scenarios

### **Webhook Testing**

* Use tools like [webhook.site](https://webhook.site) for testing
* Verify signature validation
* Test retry mechanisms
* Monitor webhook delivery rates

## Checkout Plan

**Blockradar Checkout** is a programmable stablecoin payment layer for accepting onchain payments via links, embedded QR codes, and WalletConnect. Funds settle directly to your non-custodial wallets with built-in support for swap, bridge, and treasury routing.

### **Pricing**

<Card title="0.75% per transaction" icon="percent">
  Simple, transparent pricing with no monthly subscription costs.
</Card>

### **Supported Stablecoins**

* **USDC, USDT, cNGN, IDRX, EUROC**, and more

### **Multi-Chain Support**

* **Ethereum, Polygon, Base, Solana, Tron, Celo**, and more

### **Treasury Management**

* **Swap and Bridge**: Convert and move assets across chains
* **Auto-settlement**: Automatically settle to your preferred currency
* **Circle Gateway**: Access Circle's cross-chain transfer protocol
* **Auto-sweeping**: Consolidate funds to your master wallet

<Note>
  This plan does not include Wallet-as-a-Service (WaaS) features or the
  provisioning of dedicated wallets for your end users.
</Note>

## Fetching Payment Link Transactions

You can retrieve all transactions associated with a specific payment link using the dedicated transactions endpoint. This is useful for:

* **Payment Tracking**: Monitor all payments received through a specific link
* **Reconciliation**: Match payments to orders or invoices
* **Reporting**: Generate reports for specific payment links

### **Query Parameters**

| Parameter | Type   | Description                                                   |
| --------- | ------ | ------------------------------------------------------------- |
| `page`    | number | Page number for pagination (default: 1)                       |
| `limit`   | number | Number of results per page (default: 10)                      |
| `status`  | string | Filter by transaction status (e.g., SUCCESS, PENDING, FAILED) |
| `type`    | string | Filter by transaction type (e.g., DEPOSIT)                    |
| `order`   | string | Sort order (ASC or DESC)                                      |

### **Example Response**

```json theme={null}
{
  "status": true,
  "message": "Transactions fetched successfully",
  "data": [
    {
      "id": "0d7a0b98-943c-48d0-8baa-216c29956050",
      "reference": "bjXPk7d00",
      "amount": "100.00",
      "amountUSD": "100.00",
      "status": "SUCCESS",
      "type": "DEPOSIT",
      "createdAt": "2025-01-15T10:30:00.000Z",
      "asset": {
        "symbol": "USDC",
        "name": "USD Coin"
      },
      "blockchain": {
        "name": "base",
        "slug": "base"
      },
      "customer": {
        "email": "customer@example.com",
        "name": "John Doe"
      }
    }
  ],
  "meta": {
    "page": 1,
    "limit": 10,
    "total": 25,
    "totalPages": 3
  }
}
```

## Support & Resources

### **API Reference**

* [Create Payment Link](/en/api-reference/payment-links/create)
* [Get All Payment Links](/en/api-reference/payment-links/get-all)
* [Get Payment Link](/en/api-reference/payment-links/get-one)
* [Update Payment Link](/en/api-reference/payment-links/update)
* [Get Payment Link Transactions](/en/api-reference/payment-links/get-transactions)

### **Getting Help**

* **Email**: [support@blockradar.co](mailto:support@blockradar.co)
* **API Reference**: [Checkout](/en/api-reference/payment-links/create)

<Note>
  Checkout and payment links are a powerful way to accept stablecoin payments with minimal
  integration effort. Start with simple use cases and gradually add complexity
  as you become more familiar with the system.
</Note>