# Introduction to Copperx Start accepting crypto payments instantly Copperx is a modern, non-custodial crypto payment gateway designed for developers and businesses. It allows you to: * Accept payments in a wide range of cryptocurrencies directly into your own wallet. * Maintain full control over your funds (Copperx **never** holds custody). * Automate recurring payments, invoices, taxes, and discounts. * Integrate easily with popular platforms like WooCommerce, Zapier, Stripe, and others. Use Copperx to build powerful crypto payment solutions for SaaS, eCommerce, services, donations, ticketing, and more. # How It Works * Want to accept Crypto payment via Payment link # Use Cases: How You Can Use Copperx Copperx offers flexible tools to meet a wide range of business and developer needs. Here’s how you can apply it: 1️⃣ **SaaS Subscriptions** * Automate **recurring crypto payments** for software-as-a-service products. * Manage renewals, upgrades, and cancellations seamlessly. * Use the Copperx API or dashboard for full subscription lifecycle control. *** 2️⃣ **eCommerce Stores** * Accept cryptocurrency at checkout using integrations like **WooCommerce** or custom-built flows. * Offer your customers multiple payment options across supported blockchains. *** 3️⃣ **Digital Services** * Get paid in crypto for **freelance work, agency services, or online consulting**. * Use Copperx checkout or invoicing tools to bill clients globally. *** 4️⃣ **Donations & NGOs** * Accept **transparent crypto donations** for nonprofits, charities, or fundraising campaigns. * Provide donors with clear, on-chain confirmation and reporting. *** 5️⃣ **Event Ticketing** * Sell tickets using **direct on-chain crypto payments**. * Automate confirmations and track payment status via webhooks. *** 6️⃣ **APIs for Developers** * Build **custom payment flows** tailored to your platform or app. * Use Copperx APIs to integrate crypto payments into mobile apps, marketplaces, or backend services. *** 7️⃣ **Invoicing** * Generate and send **crypto invoices** with defined due dates. * Automate reminders and track payment status using Copperx’s invoicing API. *** #### 📘 Summary Copperx is designed to support:\ ✔ Businesses (SaaS, eCommerce, services)\ ✔ Nonprofits (donations)\ ✔ Developers (API integrations)\ ✔ Event organizers (ticketing) By combining flexible tools, robust APIs, and a non-custodial design, Copperx makes it easy to integrate crypto payments into **almost any use case**. # Key Concepts & Terminology This section defines the essential terms used throughout Copperx’s platform and documentation. 1️⃣ **Non-Custodial** * Copperx does **not** hold or manage your funds. * All payments are sent directly to your connected wallets. * You maintain full custody, transparency, and control. *** 2️⃣ **Checkout** * A hosted payment page or API flow for **one-time crypto payments**. * Features: blockchain address generation, live payment tracking, and confirmation. * Use cases: eCommerce, service payments, custom flows. *** 3️⃣ **Invoicing** * Create and send **crypto invoices** to customers. * Features: due dates, itemized billing, automated reminders. * Use cases: B2B services, agency billing, crypto-based contracts. *** 4️⃣ **Subscription** * Set up **recurring crypto payments** on fixed schedules (monthly, annually, etc.). * Manage through Copperx’s API or dashboard. * Use cases: SaaS products, memberships, ongoing services. *** 5️⃣ **Webhook** * Real-time callbacks that notify your system about key events. * Example events: * Payment completed * Invoice overdue * Subscription renewed or canceled * Checkout session expired * Purpose: Automate backend actions like account upgrades or service provisioning. *** 6️⃣ **Test Mode** * A **sandbox** to simulate payments, subscriptions, and invoices. * Operates on testnets (e.g., Polygon Amoy, Ethereum Sepolia). * Requires test tokens (available from [Copperx faucet](https://dashboard.copperx.dev/faucet)). *** 7️⃣ **Supported Chains** * Blockchains Copperx integrates with for crypto payments. * Example [supported networks](https://copperx.io/payment-methods): * Ethereum * Polygon * Solana * BNB Smart Chain * Base * Arbitrum * Optimism * Tron * Tokens supported: USDC, DAI, ETH, BTC, POL (varies by chain). ### 📘 Summary Understanding these concepts helps you:\ ✔ Select the right payment model (checkout, invoice, or subscription)\ ✔ Implement webhook-driven automations\ ✔ Test safely in development mode\ ✔ Choose the appropriate blockchain and token for your integration # Setup an account To get started with the Copperx account: 1. **Registration:** Create an account at [Copperx Gateway](https://dashboard.copperx.io/) 2. **Onboarding Form:** Complete the onboarding form with accurate and detailed information about your business. This helps us understand your requirements better and tailor our services to suit your needs. 3. **Adding Payment Method:** [Go to Payment setting](/setup-and-configuration/setup-an-account/payment-configuration) # Payment Configuration To add payment settings in Copperx Gateway, follow these steps: {% hint style="info" %} Payment settings are mandatory to proceed with transactions. {% endhint %} * **Access Settings Page:** Navigate to the [Settings page](https://dashboard.copperx.io/settings/withdrawal) in your Copperx Gateway account. * **Add Preferred Payment Methods:** Once on the Settings page, you can add your preferred payment methods. These may include options such as Ethereum, Binance Smart Chain (BSC), Polygon, Solana, and more. * **Enable Stripe (Optional):** If you wish to accept payments via credit or debit cards, you can enable the Stripe integration. This allows you to accept card payments seamlessly. By configuring your payment settings, you ensure smooth and efficient transaction processing through Copperx Gateway.
**Managing Currency Preferences in Copperx Gateway** In addition to payment settings, Copperx Gateway offers advanced options for managing currency preferences. Here's how you can configure them: 1. **Default Network Selection:** Select your preferred blockchain network, which will take precedence during your checkout session. 2. **Default Currency Setting:** Set your preferred currency for transactions during the checkout session. 3. **Currency Conversion:** Enable currency conversion for flexible transaction handling. This feature allows you to seamlessly swap currencies, providing greater flexibility in transaction processing. By customizing your currency preferences, you optimize the checkout experience for both you and your customers on Copperx Gateway. # Business Details Streamlining Your Business Information To update your business information, follow these steps: 1. **Go to Business Settings Page:** Navigate to the [Business Settings](https://dashboard.copperx.io/settings/organization) page in your account dashboard. 2. **Update Business Details:** Here, you can set or modify the following information: * Business Name * Business Address * Support Email * Support Phone Number * Business Website * Company Identification Number (CIN) * Tax Number (Tax ID) * Support Website * Privacy Policy * Terms of Service
All of these settings will be visible in both the invoice and checkout sessions. # Apply your Branding Enhance Your Branding In the Copperx dashboard, navigate to the [branding settings](https://dashboard.copperx.io/settings/branding) page to personalize your brand experience. Set your **logo** and **brand colors** to reflect your unique identity. These customization options will seamlessly integrate your brand into the checkout page, providing a cohesive and memorable experience for your customers.

# Manage Promo Codes Boost Sales with Discounts Access the [promocode settings](https://dashboard.copperx.io/settings/promocodes) to create and manage promotional codes or discount coupons for your end users. Customers can apply these codes during the checkout session to receive discounts on their total amount. Customize your promotions to incentivize purchases and enhance customer satisfaction.
# Environments (Testnet vs Mainnet) Copperx offers both test and production environments so you can safely develop and test your integration before going live. **🔧 Test Environment** * **Dashboard URL:** `https://dashboard.copperx.dev` * **API Base URL:** `https://api.copperx.dev` * **Supported Network**: Eth Sepolia , Polygon Amoy, Solana Devnet, BNB Smart chain testnet, Base Sepolia, Arbitrum Sepolia, Optimism Sepolia, Tron Shasta * **Supported Tokens**: ETH, SOL, BNB, POL, DAI, USDT, USDC, USDC.e, USDT, and more * Use this environment for sandbox development and testing without real crypto transactions. **🚀 Production Environment** * **Dashboard URL:** `https://dashboard.copperx.io` * **API Base URL:** `https://api.copperx.io` * **Supported Network**: Ethereum, Polygon (PoS), Solana, BNB Chain, Base, Arbitrum, Optimism, Tron * **Supported Tokens**: ETH, SOL, BNB, POL, wETH, DAI, USDT, USDC, USDC.e, and more * Use this environment when you're ready to accept live payments. 📌 *Always separate your test and live API keys and endpoints to avoid unintentional transactions.* # How to Generate an API Key API Key is needed to interact with Copperx APIs. You can easily create, regenerate and delete API Keys from our powerful dashboard. To create an API Key for the Copperx API, you need to register for an account on the Copperx. Once registered, you can log in and generate an access token. 1. Go to the [Copperx Dashboard](https://dashboard.copperx.dev/developer/apikeys). 2. Login with your Copperx account. 3. Click **Developer** in the top menu and click on **API Keys**. 4. Press **Generate Key** button on top-right to generate a new API Key. 5. Give the name to your API Key and click **Generate Key**. You can different names to your API Keys, like `staging`, `production`, etc. 6. You will receive an API Secret Key. Do save this key at somewhere secure place as you can only see it once.
### Regenerate Key You can easily regenerate your API Key from Developer > API Keys. 1. Click **Developer** in the top menu and click on **API Keys**. 2. Hover over the key that you want to regenerate, and click on 3 dots **`⋮` > Regenerate**. 3. To confirm, click on **Regenerate Key**. 4. You will receive a regenerated API Secret Key. 📌 *Use separate keys for development and production environments.* # Accept One-Time Crypto Payments One-time payments let customers pay using crypto, similar to a standard checkout experience. **How it Works:** 1. Create a **Checkout Session** using the API. 2. Redirect the customer to the hosted checkout page (`url` from API response). 3. Copperx handles on-chain payment tracking. 4. Copperx redirects the customer to `successUrl` or `cancelUrl` based on payment completion. 5. Optionally, receive payment status updates through webhooks. \ **Example API Call:** ```bash curl --request POST \ --url https://api.copperx.dev/api/v1/checkout/sessions \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data-raw '{ "successUrl": "https://example.com/success", "cancelUrl": "https://example.com/cancel", "lineItems": { "data": [ { "priceData": { "currency": "usdc", "unitAmount": "100000000", "productData": { "name": "Pro Plan", "description": "One-time access" } } } ] } }' ``` **Best Practices:** * Validate the session’s status using API or webhooks. * Use test mode and Copperx’s faucet for testing. # Accept Crypto Subscriptions **🚀 How It Works** ✅ **Step 1: Create a Product** Every subscription plan is associated with a product. Create the product first using the following API request: ```bash curl --request POST \ --url https://api.copperx.dev/api/v1/products \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Pro Membership", "description": "Monthly plan for premium users", "isActive": true, "unitLabel": "month", "url": "https://example.com/product", "metadata": { "category": "SaaS" }, "visibility": 10, "defaultPriceData": { "currency": "usdc", "unitAmount": 50000000, "interval": "month", "intervalCount": 1, "type": "recurring" } }' ``` The response will include a unique `productId`. Save this for the next step. *** ✅ **Step 2: Create a Subscription Checkout Session** Using the created product’s ID, generate a checkout session to enable the user to subscribe: ```bash curl --request POST \ --url https://api.copperx.dev/api/v1/checkout/sessions \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data-raw '{ "mode": "subscription", "lineItems": { "data": [ { "priceData": { "currency": "usdc", "unitAmount": "50000000", "interval": "month", "productId": "{PRODUCT_ID}" } } ] }, "successUrl": "https://yourapp.com/success?session_id={CHECKOUT_SESSION_ID}", "cancelUrl": "https://yourapp.com/cancel" }' ``` The API response will provide a hosted **checkout session URL**. Redirect your user to this URL to complete the subscription. *** ✅ **Step 3: Automate Recurring Billing** Copperx’s smart contracts **automatically handle** the recurring charges based on the interval (`monthly`, `yearly`, etc.) and send blockchain-verified payment confirmations. *** ✅ **Step 4: Stay Updated with Webhooks** Copperx sends **webhook events** for key actions: * `customer.subscription.created` * `customer.subscription.started` * `customer.subscription.unpaid` Use these events to manage access and provide real-time updates to your users. # Create Invoices Issue invoices for services and track their payment status. **How it Works:** 1. Create an invoice with itemized details and due date. 2. Share the invoice URL with the customer. 3. Monitor invoice status (`paid`, `open`, `draft`, `void`, `uncollectable`). 4. Use webhooks for payment updates. **Example API Call:** ```bash curl --request POST \ --url https://api.copperx.dev/api/v1/invoices \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data-raw '{ "dueDate": "2025-06-01", "currency": "usdc", "lineItems": { "data": [ { "priceData": { "currency": "usdc", "unitAmount": "50000000", "productData": { "name": "Consulting Service" } } } ] } }' ``` # Create a Recurring Invoices Copperx allows you to create recurring invoices for subscriptions, memberships, and services that require periodic payments. ### 🔧 How It Works 1. **Create a Recurring Invoice**: Provide the relevant customer, amount, and recurrence details. 2. **Invoice Generation & Automation**: Copperx’s system automatically generates new invoices at the defined interval. 3. **Notifications & Webhooks**: Stay updated with webhooks for successful payments, failures, or other events. **✅ Step 1: Create a Customer** Before creating an invoice, you’ll need to create a customer: ```bash curl --request POST \ --url https://api.copperx.dev/api/v1/customers \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data-raw '{ "email": "customer@example.com", "name": "John Doe", "metadata": { "customerType": "SaaS" } }' ``` ✅ **Save the `customerId`** from the response. *** **✅ Step 2: Create a Product** Next, create the product to be billed: ```bash curl --request POST \ --url https://api.copperx.dev/api/v1/products \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data-raw '{ "name": "Pro Plan", "description": "Monthly subscription plan", "isActive": true, "unitLabel": "month", "metadata": { "category": "SaaS" }, "defaultPriceData": { "currency": "usdc", "unitAmount": 50000000, "interval": "month", "type": "recurring" } }' ``` ✅ **Save the `productId`** from the response. ✅ **Save the** `defaultPrice.id` as a `priceId` from the response. *** **✅ Step 3: Create a Recurring Invoice** Use the `customerId` and `productId` and `priceId` in the invoice creation request: ```bash curl --request POST \ --url https://api.copperx.dev/api/v1/invoices \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' \ --data-raw '{ "customerId": "{CUSTOMER_ID}", "description": "Monthly recurring invoice for Pro Plan", "dueDate": "2025-06-15T00:00:00Z", "invoiceType": "recurring", "collectionMethod": "charge_automatically", "lineItems": { "data": [ { "quantity": 1, "priceId": "{PRICE_ID}" "price": { "productId": "{PRODUCT_ID}", "unitAmount": "50000000", "currency": "usdc", "type": "recurring", "interval": "month" } } ] } }' ``` ✅ **Save the `invoiceId`** from the response. *** **✅ Step 4: Finalize the Invoice** Finalize the invoice to make it active and ready for payment collection: ```bash curl --request POST \ --url https://api.copperx.dev/api/v1/invoices/{INVOICE_ID}/finalize \ --header 'Authorization: Bearer {API_KEY}' \ --header 'Content-Type: application/json' ``` #### 🛠️ Best Practices ✅ **Validate Customer Details**: Make sure the customer information is accurate before generating invoices.\ ✅ **Use Webhooks**: Listen for events like `invoice.paid`, `customer.subscription.started`, and `invoice.marked_as_paid` to keep your system up to date.\ ✅ **Secure API Calls**: Always use HTTPS and a valid API key.\ ✅ **Clear Terms**: Clearly communicate the subscription and billing terms to customers. # Webhooks & Events Copperx uses webhooks to send real-time notifications to your server whenever important events occur in your account. This enables you to automate backend actions. #### ✅ What is a Webhook? A **webhook** is a POST request sent from Copperx to your server’s endpoint whenever a specific event occurs. It carries a JSON payload describing the event and its associated data. * **Why Use Webhooks?**\ Instead of continuously calling the API to check for payment status updates, Copperx sends real-time events to your backend. This reduces overhead and ensures your app stays in sync. * **Typical Flow:** 1. User completes a payment (e.g., Checkout Session). 2. Copperx sends a webhook event (`checkout_session.completed`) to your endpoint. 3. Your backend verifies the webhook and updates the user’s plan or access. *** #### 🔐 Webhook Security & Signature Verification For security, Copperx signs every webhook payload using an **HMAC-SHA256 signature**. * **Headers in the Webhook Request:** | Header | Description | | --------------------- | -------------------------------------------- | | `x-webhook-signature` | HMAC-SHA256 signature of the raw payload | | `x-webhook-token` | Your **webhook secret key** (from dashboard) | * **How to Verify the Signature:** 1. Retrieve the `x-webhook-signature` header from the request. 2. Compute your own HMAC-SHA256 hash of the raw request body using your **webhook secret key**. 3. Compare your hash with the `x-webhook-signature`. If they match, the webhook is valid. You can find your **webhook secret key** in the Copperx dashboard settings. *** #### 🔗 Common Webhook Events Below are the **most commonly used events** in Copperx’s payment flows: | Event | Description | | -------------------------------- | --------------------------------------------------- | | `checkout_session.completed` | User successfully completed the checkout. | | `checkout_session.expired` | Checkout session expired before payment completion. | | `checkout_session.canceled` | User canceled the checkout session. | | `invoice.paid` | An invoice was paid successfully. | | `invoice.finalized` | An invoice was finalized (ready to be paid). | | `invoice.payment_failed` | Payment for an invoice failed. | | `customer.subscription.created` | A new subscription was created. | | `customer.subscription.started` | Subscription started. | | `customer.subscription.deleted` | Subscription was canceled/deleted. | | `customer.subscription.past_due` | Subscription payment is past due. | | `customer.subscription.unpaid` | Subscription payment is unpaid. | | `payment_intent.succeeded` | PaymentIntent was successfully completed. | | `payment_intent.failed` | PaymentIntent failed. | *** #### 📨 Example Webhook Payload: Checkout Session Completed When a checkout session is completed, here’s an example of the JSON payload you will receive: ```json { "id": "00b6d1b6-93ce-4d6d-86b4-a7ab8fe14d87", "apiVersion": "2023-01-11", "created": 1748329965626, "object": "checkoutSession", "type": "checkout_session.completed", "data": { "object": { "id": "fe6b7b01-1c4b-4b35-a5a5-a23b0a089cc6", "createdAt": "2025-05-27T07:12:19.165Z", "updatedAt": "2025-05-27T07:12:45.582Z", "mode": "payment", "paymentMethodTypes": ["wallet"], "paymentSetting": { "allowedChains": [ { "chainId": 137 }, { "chainId": 8453 }, { "chainId": 42161 } ], "paymentMethodTypes": ["wallet"], "preferredChainId": 137, "allowSwap": true }, "currency": "usdc", "amountSubtotal": "10000000", "amountTotal": "10100000", "status": "complete", "paymentStatus": "paid", "paymentLinkId": "769a890b-5664-49f8-8f68-c9b688bcf60f", "url": "https://buy.copperx.tech/payment/checkout-session/fe6b7b01-1c4b-4b35-a5a5-a23b0a089cc6", "lineItems": { "object": "list", "data": [ { "description": null, "quantity": 1, "price": { "id": "ebc48921-0171-4f37-9070-2906d0da2f51", "currency": "usdc", "productId": "b1d2476f-b5cf-47d7-99ee-3d8123ae9ab5", "type": "one_time", "unitAmount": "10000000", "product": { "id": "b1d2476f-b5cf-47d7-99ee-3d8123ae9ab5", "name": "Demo test", "isActive": true }, "isActive": true }, "amountTotal": "10000000", "currency": "usdc" } ] }, "addresses": [/* ... multiple supported crypto assets and addresses ... */], "paymentIntent": { "id": "3b7bc615-a04d-49e1-98c4-8612f785484d", "amount": "10100000", "amountReceived": "10100000", "currency": "usdc", "status": "requires_payment_method", "paymentMethod": { "id": "88cbd77a-84f1-422a-8ac6-fa6f498142b1", "asset": { "id": "13056880-798b-4bd4-a555-c1c71de017fa", "name": "USDC.e", "chainId": 137, "address": "0x2791bca1f2de4661ed88a30c99a7a9449aa84174", "currency": "usdc" }, "type": "wallet", "accountAddress": "0xd2b59f3a9575a90a44e5627cda4ed98ecb5e5d20", "options": { "frontend": { "transactionHash": "0x54d164f9807060445614ece882603fd4b2a7858ac1394451cf1f07715a183def" }, "wallet": { "assetId": "13056880-798b-4bd4-a555-c1c71de017fa", "transactionHash": "0x54d164f9807060445614ece882603fd4b2a7858ac1394451cf1f07715a183def", "contractAddress": "0x146db67792092eaa92a51961946b50f89277a975" } } } }, "amountDetails": { "amountTotal": "10100000", "amountSubtotal": "10000000", "amountFee": "100000", "currency": "usdc", "feePercentage": 1 }, "amountNet": "10000000" } } } ``` *** #### 💡 How to Use This Event When you receive this event:\ ✅ Verify the **signature** (for security).\ ✅ Check the **paymentStatus** (`paid`).\ ✅ Activate the user’s plan, send a confirmation email, or update their account. #### ⚙️ Best Practices for Webhooks ✅ Always verify the signature to avoid spoofed requests.\ ✅ Respond quickly to webhook POST requests with a **`200` OK** to acknowledge receipt.\ ✅ Retry Behavior * **Max Attempts:** 10 * **Initial Delay:** 30 seconds * **Backoff Strategy:** Exponential (delay doubles with each retry) * **No Delay Cap:** Delay continues to double up to the 10th attempt * **Total Retry Window:** \~**4 hours 16 minutes** from initial delivery attempt *** ### 📊 Retry Schedule | Attempt | Delay (seconds) | Delay (minutes) | Cumulative Time | | ------- | --------------- | --------------- | --------------- | | 1st | 30 | 0.5 min | 0:00:30 | | 2nd | 60 | 1 min | 0:01:30 | | 3rd | 120 | 2 min | 0:03:30 | | 4th | 240 | 4 min | 0:07:30 | | 5th | 480 | 8 min | 0:15:30 | | 6th | 960 | 16 min | 0:31:30 | | 7th | 1920 | 32 min | 1:03:30 | | 8th | 3840 | 64 min | 2:07:30 | | 9th | 7680 | 128 min | 4:15:30 | | 10th | 15,360 | 256 min | 8:31:30\* | **Notes:** * A maximum of **10 retry attempts** will be made. * If all retries fail, the webhook delivery is marked as **unsuccessful**. ✅ Log webhook events for debugging and auditing.\ ✅ Use HTTPS for secure communication. # Error Handling & Troubleshooting | Status Code | Meaning | Common Cause | | ----------- | --------------------- | ------------------------ | | 400 | Bad Request | Invalid data in request | | 401 | Unauthorized | Invalid API Key | | 403 | Forbidden | Access denied | | 404 | Resource not found | Incorrect ID or endpoint | | 500 | Internal Server Error | Copperx service error | **Tips:** * Use test environment first. * Check API logs for request/response details. * Contact support if you face persistent issues. # Checkout Session API * [**Create Session**](https://copperx.readme.io/reference/sessionscontroller_create): `POST /api/v1/checkout/sessions` * [**Get Session**](https://copperx.readme.io/reference/sessionscontroller_findone): `GET /api/v1/checkout/sessions/{id}` * [**List of all Sessions**](https://copperx.readme.io/reference/sessionscontroller_findall): `GET /api/v1/checkout/sessions` * [**Auto Recover**](https://copperx.readme.io/reference/sessionscontroller_autorecovercheckoutsessionbyhash): `POST /api/v1/checkout/sessions/auto-recover-by-transaction-hash` * [**Complete Partial**](https://copperx.readme.io/reference/sessionscontroller_completepartialcheckoutsession): `POST /api/v1/checkout/sessions/{id}/complete-partial-checkout-session` For more details check [API Reference](https://copperx.readme.io/reference/sessionscontroller_create) # Invoice API * [**Create Invoice**](https://copperx.readme.io/reference/invoicecontroller_create): `POST /api/v1/invoices` * [**Get Invoice**](https://copperx.readme.io/reference/invoicecontroller_get): `GET /api/v1/invoices/{id}` * [**Finalize Invoice**](https://copperx.readme.io/reference/invoicecontroller_finalizeinvoice): `POST /api/v1/invoices/{id}/finalize` * [**Void Invoice**](https://copperx.readme.io/reference/invoicecontroller_voidinvoice): `POST /api/v1/invoices/{id}/void` * [**Mark as Paid**](https://copperx.readme.io/reference/invoicecontroller_payinvoice): `POST /api/v1/invoices/{id}/pay` For more details check [API Reference](https://copperx.readme.io/reference/invoicecontroller_create) # Webhook Events * [**Create Webhook**](https://copperx.readme.io/reference/webhookendpointcontroller_create): `POST /api/v1/webhook-endpoints` * [**Get All Webhooks**](https://copperx.readme.io/reference/webhookendpointcontroller_getall): `GET /api/v1/webhook-endpoints` * [**Update Webhook**](https://copperx.readme.io/reference/webhookendpointcontroller_update): `PUT /api/v1/webhook-endpoints/{id}` * [**Delete Webhook**](https://copperx.readme.io/reference/webhookendpointcontroller_delete): `DELETE /api/v1/webhook-endpoints/{id}` * [**Regenerate Secret**](https://copperx.readme.io/reference/webhookendpointcontroller_regenerate): `POST /api/v1/webhook-endpoints/{id}/regenerate` * [**Test Webhook**](https://copperx.readme.io/reference/webhookendpointcontroller_test): `POST /api/v1/webhook-endpoints/{id}/test` For more details check [API Reference](https://copperx.readme.io/reference/webhookendpointcontroller_getall) # Authentication & Security * All API requests require the `Authorization: Bearer {API_KEY}` header. * Manage API keys in the Copperx dashboard. # Payment Link Creating a Payment Link via Dashboard 1. **Navigate** to and click on the "[Create Payment Link](https://dashboard.copperx.io/payment-links/create)" button.
2. **Select Payment Link Type:** * Fixed Price: Choose this option to create a payment link for a product with a fixed price. You can either create a one-time product or select an existing one from your inventory. * Variable Price: Users can enter the desired amount. This option is suitable for donation purposes or when the price may vary. * Subscription: Create a payment link for monthly recurring payments, such as subscription services.
3. **Collect Customer Information:** * Enable various options such as name, email, phone number, billing and shipping address, and custom fields from the user side. This ensures that during the checkout session, users are prompted to provide necessary information.
4. **Advanced Options:** * Redirect URL: Set a specific URL where users will be redirected after a successful payment. This could be a thank you page or a confirmation page. * Success Message: Customize the message displayed to users upon successful payment completion. This message provides reassurance and confirms that the transaction was successful. * Discount Options: Allow for the inclusion of discount codes or promotional offers during the checkout process. This encourages users to make purchases by providing incentives such as discounts or special offers.
# Recurring Subscription Setting Up Recurring Subscriptions To set up recurring subscriptions for your services, follow these steps: 1. **Create a Product:** * Go to the Products section and open the [Product page](https://dashboard.copperx.io/products). * Click the "**Add Product**" button. * Choose "**Recurring**" as the pricing type. * Set the recurring interval according to your needs, such as monthly, quarterly, semi-annually, or annually. * After creating the product, proceed to the next step.
2. **Generate a Recurring Payment Link**: * In the [Payment links](https://dashboard.copperx.io/payment-links) page, click on [Create payment link](https://dashboard.copperx.io/payment-links/create). * Choose **Subscription** under "Choose link type" option. * You will then see the "Choose Plan" option, which displays all the recurring plans you created in step 1. * Once the payment link is configured, your recurring payment link is ready.
3. **Start the Recurring Subscription:** * After the payment is completed via the link, you can view the recurring subscription details on the [Subscription page](https://dashboard.copperx.io/billing/subscriptions) under Billing. # Recurring Invoice Creating a Recurring Invoice on Copperx 1. **Navigate to the Invoices Page** 1. Open your browser and go to [Copperx Dashboard](https://dashboard.copperx.io/invoices). 2. Log in to your account if you haven't already. 2. **Create a New Invoice** 1. Click on the [Create Invoice button](https://dashboard.copperx.io/invoices/create). 2. You will be redirected to the invoice creation page: Create Invoice. 3. **Select Customer** 1. Choose the customer you want to raise an invoice for. 2. If the customer is not listed, you can add a new customer by clicking on the **Add Customer** option. 4. **Configure Invoice Details** 1. **Invoice Number**: The system will auto-generate an invoice number, or you can manually enter one. 2. **Due In**: Select the due date (e.g., 7 days, 14 days, and so on). 3. **Receive Payments In**: Choose the preferred payment currency (e.g., USDC). 4. **Payment Collection**: Select "Recurring" to enable recurring invoices. 5. **Recurring Interval**: Choose the frequency of the recurring invoice (e.g., Monthly, Quarterly, Half yearly, Annually). 5. **Add Invoice Items** 1. Click on **Add Item**. 2. Enter the item details such as name, description, quantity, and price. 3. Repeat the process for multiple items if required. 6. **Choose Payment Methods** 1. Select the payment methods you want to accept (e.g., polygon, base, solana, ethereum ). 2. Multiple payment methods can be enabled for customer convenience. 7. **Additional Options** (Optional) 1. Enable Memo to add custom notes to the invoice. 2. Enable Footer to include additional terms or disclaimers. 8. **Save and Send Invoice** 1. Review all details to ensure accuracy. 2. Click on Save to store the invoice as a draft. 3. Click on Send Invoice to share it with the customer via email or a direct payment link. 9. **Manage Recurring Invoices** 1. Once sent, the recurring invoice will appear in your **Invoices** section. By following these steps, you can easily create and manage recurring invoices on Copperx, ensuring seamless automated payments for your services. # Crypto Invoice Crypto Invoice via Dashboard 1. **Navigate to Invoice Page:** Access the [Invoice page](https://dashboard.copperx.io/invoices) and initiate the process by clicking on the "[Create invoice](https://dashboard.copperx.io/invoices/create)" button.
2. **Add/Select Customer:** If the customer is new, add their details from the select box. Otherwise, choose an existing customer from the list. You can also add customer from [here](https://dashboard.copperx.io/customers).
3. **Invoice Details:** Provide essential information such as the choose network and token, set a due date, and other relevant details to tailor the invoice according to your needs.
4. **Items:** Add invoice items, including one-time items or create new ones as required. You have the flexibility to include multiple items and perform actions such as adding, editing, or deleting them as needed.
5. **Additional Options:** Customize the invoice further by adding a memo and footer. These additional options allow you to include personalized messages or additional information for your customers.
# WooCommerce This documentation explains the process of integrating WooCommerce with Copperx using the Copperx plugin. By integrating with Copperx, you can enable your store to accept various crypto payments. ## 1. Installing the Copperx Plugin * In your WordPress dashboard, Choose **`Plugins > Add New`**. * Search for "Copperx Payment Gateway for WooCommerce" and select the official plugin from Copperx. * Click **`Install Now`**. * Once installed, click **`Activate`** to use the plugin. ## **2. Creating a Copperx Account** * If you haven't already, sign up for a Copperx account. * Follow the onboarding process: * Add your business details. * Upload your company's logo and brand colors. * Configure wallet addresses for supported cryptocurrencies: Ethereum, Polygon, Solana, and BNB chain. ## **3. Linking to Copperx and Configuring the Plugin** * In the WordPress admin area, navigate to **`WooCommerce > Settings > Payments`**. * Locate "Copperx" in the list of available payment gateways. * Click on the **`Manage`** button alongside Copperx. * This will direct you to the plugin settings page for further configurations. ## **4. Adding the API Key** * In your Copperx dashboard, navigate to the **`Developer > API keys`** section. * Click on "Generate API Key" to produce a unique key that will link your WooCommerce store to your Copperx account. * Copy the generated API key. * Return to your WordPress plugin settings and paste the API key into the designated field. ## **5. Setting Up Webhooks** * In Copperx, navigate to the `**Developer > Webhooks**` * Under webhook configurations or similar, select **`Add endpoint`**, and insert the URL provided in your WooCommerce plugin settings page. * Ensure you copy and input any shared secret or additional authentication details as required in the plugin settings to ensure secure communication between Copperx and your WooCommerce store. ## **Testing Integration with Test Mode** Before fully integrating Copperx crypto payments into your WooCommerce store, utilizing the Test Mode is recommended to ensure smooth and accurate transactions. ### **Steps to Enable Test Mode:** **Important Note:** Ensure to use the Test Secret Key from [**dashboard.copperx.dev**](http://dashboard.copperx.dev/) for activating Test Mode. This specialized test mode not only ensures a secure and isolated environment for your test transactions but also allows you to view and verify all test payments distinctly from your live mode operations, maintaining a clean and safe separation. 1. **Access WooCommerce Dashboard**: * Navigate to **`Payments > Settings`**. 2. **Activate Copperx Test Mode**: * Find Copperx in the available payment gateways list. * Click on the **`Manage`** button to access its settings. * Activate the 'Test Mode' option from the settings. 3. **Retrieve Test Secret Key from Copperx**: * Navigate to **`Developer > Generate Key`** within your Copperx dev dashboard and copy the 'Test Secret Key'. * Return to the WooCommerce Copperx settings and paste the key into the designated field. **Note:** Always obtain the Test Secret Key from [**dashboard.copperx.dev**](http://dashboard.copperx.dev/) to ensure secure and accurate testing. 1. **Perform Test Transactions**: * Using the [Copperx faucet](https://dashboard.copperx.dev/faucet), acquire test tokens (e.g., USDC). * Initiate test transactions in your WooCommerce store using these tokens. 2. **Verify Transactions**: * After conducting test transactions, confirm that the funds reflect correctly in your test wallet. **Note**: Always ensure you switch off 'Test Mode' and use the live API key when you're ready to accept real crypto payments. *** **Further Resources**: * [How to generate an API Key](https://docs.copperx.io/how-to-generate-an-api-key) * [How to setup a Webhook](https://docs.copperx.io/webhook/how-to-setup-a-webhook) * [Accept your first payment](https://docs.copperx.io/examples/accept-your-first-payment) For any queries or assistance, the Copperx support team is available to guide you every step of the way. # Zapier This documentation explains the steps to create a Zap that will trigger an email to be sent to your customers as soon as their payment is completed using Copperx as the payment gateway. To create Zapier Automation: 1. Login to your [Zapier](https://zapier.com/) account and click on the **Create Zap** button from the Sidebar.
2. Now in the **Trigger**, search for the "Copperx" app and select **Checkout Session Completed** as the event and click **Continue**.
3. Next is to test the trigger, for that you need to copy the **webhook URL** and add it to the Copperx [webhooks settings](https://dashboard.copperx.io/developer/webhooks) as new webhook endpoint. (**Note :** you can test trigger by switching to Testnet and adding the copied URL to webhooks settings, but be sure to remove the URL from Testnet after the successful payment test.)
4. Next, select the email app you want to use as the **Action** app. For example, you could choose Gmail, Outlook, or any other email service and select "Send Email" as the event. Now, click **Continue** and log in to your email service.
5. Now, you need to fill the **Email** **To** field as the "Customer Email" from the given option data and fill other relevant fields such as email subject and body as per your business needs.
6. At this stage, you can test your Zap and **Publish** it.
Once you've completed these steps, you're ready to send customized emails to your customers through this automation. # Stripe To connect Stripe with Copperx for card payments, follow these steps: 1. **Create an Account with Copperx:** Sign up for an account with [Copperx](https://dashboard.copperx.io/) if you haven't already. You'll need to provide necessary details to register. 2. **Navigate to Payment Settings:** Once logged into your Copperx account, find the [payment settings](https://dashboard.copperx.io/settings/withdrawal) section. This is usually located within your account dashboard or settings menu. 3. **Click on "Add Stripe - Card Payments":** Within the payment settings, locate the option to add payment methods. Choose "Stripe - Card Payments" from the available options.
4. **Fill in Required Information:** After selecting Stripe as the payment method, a pop-up window will appear prompting you to enter necessary information. You'll need to provide your Publishable API key and Secret API key. You can obtain these keys from your Stripe account dashboard. Navigate to to find your Publishable and Secret API keys.
5. **Enter Publishable and Secret API Keys:** Copy and paste the Publishable API key and Secret API key from your Stripe account dashboard into the corresponding fields in the pop-up window within the Copperx platform.
6. **Save Changes:** After entering the API keys, ensure that you save the changes. This typically involves clicking a "Add" button within the pop-up window. 7. **Verify Integration:** Once the keys are successfully added, Copperx should be connected to Stripe for card payments. You can verify the integration by testing a checkout session or reviewing the payment settings to ensure that Stripe is listed as an active payment method.
Following these steps should allow you to successfully connect Stripe with Copperx for processing card payments via checkout sessions. Make sure to keep your API keys secure and never share them publicly. ### When using Checkout session API If you are using checkout session API to accept payments, then you need to do one extra step. By default stripe payment is disabled for checkout sessions created using API (Even if you connected your stripe account successfully). You need to set `paymentSetting.allowFiatPayment` to `true` to in request payload.\ \ \ `curl --request POST`\ `--url https://api.copperx.dev/api/v1/checkout/sessions`\ `--header 'accept: application/json'`\ `--header 'content-type: application/json'`\ `--data ' {` \ `"submitType": "pay",` \ `"lineItems": { .... },` \ `"paymentSetting": { ....` \ `"allowFiatPayment": true #SET THIS FIELD TRUE TO ACCEPT STRIPE PAYMENT` \ `}` \ `} '`\
# BigCommerce Coming Soon # Magento Coming soon # FAQ ### Introduction #### What is Copperx Payment Gateway? Copperx Payment Gateway allows businesses to accept crypto payments across multiple networks, including **Solana, Ethereum, Polygon, BNB Smart Chain, Tron, Optimism, and Arbitrum**. It supports: * Instant wallet withdrawals * Refund management * Tax and promo code support * Processing fee collection from payers * One-time and recurring payments You can also accept **credit and debit card payments** by connecting your Stripe account with Copperx for a single checkout experience. Copperx Payment Gateway is non-custodial, ensuring complete security by directly withdrawing payments to your wallet. *** #### Is the Copperx Payment Gateway non-custodial? Yes. Copperx does not hold or manage your funds at any point. Payments made by users are directly withdrawn to your wallet, ensuring complete security and control over your received funds. You have full ownership and access to your assets at all times. *** ### Accepting Crypto Payments #### What networks and tokens can I accept for crypto payment? You can view all supported networks and tokens on the [Copperx Payment Methods](https://copperx.io/payment-methods) page. *** #### Why is a gas fee charged for the Ethereum and Tron networks? Gas fees are required for processing transactions on the Ethereum and Tron networks. During busy network periods, the gas cost can be as high as: * **$25 per transaction** on Ethereum * **$10 per transaction** on Tron To reduce the burden on businesses for micropayments, Copperx offers the option to collect the payment processing gas cost from end customers. *** #### Where do I receive my payment? Is it instant? Each payment is credited directly to your wallet. Yes, payments are instant. *** #### Can I accept credit card and debit card payments? Yes. You can accept card payments in a single checkout by connecting your **Stripe account** with Copperx. Key details: * Card payments are processed by Stripe * Funds are deposited to the bank account connected to your Stripe account * Copperx does not charge any additional fees for this service # Clear Your Stuck Payments ⚠️ Already Paid but Your Session Hasn’t Updated?\ If you've completed your payment but your session still isn't active, use our recovery tool to manually verify and process your transaction. ### 🔁 How to Use the Recovery Tool 1. Visit 2. Select the network you used (e.g., Solana Mainnet). 3. Paste the transaction hash from your payment. 4. Click **"Reprocess"** to submit your request. We’ll review your transaction and respond based on its status. ### ✅ What Happens Next You’ll receive one of the following responses based on your payment’s status
ProblemExplanationAction Required with possible solution!
Partial PaymentCheckout session is incomplete.User action: It looks like the payment you submitted is incomplete.
Please complete the remaining amount to activate your session..
Complete PaymentCheckout session is already completed.Business action: The transaction has already been successfully processed through Copperx.
Please review the details and manually credit the user’s account as appropriate.
In ProcessThe transaction is already being processed.Copperx action: The transaction has been detected. Please wait for network confirmation before proceeding with any further actions.
Missing Payment IntentPayment intent amount or currency is not set. This is happens when user just sent payment to previously save address.

No action: At the time of checkout, no payment address was configured in the QR code.
If funds were sent to a random or incorrect address, they cannot be recovered.

Please ensure the payment address is properly set before initiating a transaction.

Wrong Token / NetworkThe transaction was sent to an incorrect token address or network.User action: Before sending any funds, verify that the payment address and network details are correct.
Mistakes may result in irreversible loss of funds.
Copperx action: Please contact the Copperx team so we can help you find the best possible solution.
Wrong ClaimReceiver address doesn’t match any checkout session from your organization.User action: Make sure you’re using the official and correct payment link for your session.
If you’re unsure, please contact support for assistance before proceeding.


[^1]: Once you reveal QR code in checkout session paymemt address will automatically set.