Integration

CoindPay provides a simple, universal way to initiate and complete payments. It works across web, mobile, and serE-commerce checkout pages, SaaS dashboards, or web-based payment portals.

Environment

Testnet

App https://test.coindpay.xyz （ Integration & Debugging ）

Core steps: register merchants, manage payments, bind settlement wallets, configure webhooks, and integrate the merchant order flow end-to-end > test.coindpay.xyz/account/payouts

Subscription-type Payments Links require contacting our team（ @CoindPay or collaboration group ）to whitelist static IPs and configure the necessary sandbox permissions.

Other payment types and business scenarios remain publicly available and open by default.

You can check your current IP at https://whatismyipaddress.com VPN may affect your outbound IP.

Prod

App https://coindpay.xyz （ Production Business & KYB Required ）

• Payments support USDT/USDC on EVM and SVM networks 2. Payout assets Please confirm that your connected wallet matches the correct network in your account settings.

• On/Off-ramps support 100+ assets across 30+ networks for large-volume buy and sell crypto transactions. When creating ramp orders, ensure that your selected asset type matches the corresponding wallet address.

• Wallet configuration is fully flexible — developers can specify either an EVM or SVM address as the payout primary wallet > coindpay.xyz/account/payouts

1. Create Account

Before using CoindPay, you need to create an account. This account serves as a unified identity for both your developer role and merchant enterprise.

Visit the CoindPay website and choose one of the account creation methods:

• Social Account

  • Supported social login providers (e.g. Google, X, etc.)

• Wallet

  • EVM wallet (Ethereum-compatible chains)

  • SVM wallet (Solana)

Note: Even if you sign up using a social account, you will still be required to bind a payout wallet to complete and enable payments.

💡 Once your account is created, you will have a unified merchant identity to manage Payments Links, track orders, and manage team members.

2. Create Payments

A Payments Link is a convenient way to collect payments. You can generate a link and share it with customers or embed it into your applications.

If merchant KYB compliance is not completed, users will be prompted to complete the KYB onboarding and compliance review. The prompt is triggered via More → Account profile or during Pay → Payments create, with an onboarding modal.

Option 1: Few Products（No-code）

If you have a small number of products:

1. Create a Payments Link and provide the necessary form information at once.

2. Share the link with your customers or embed it in your website/app.

Designed for no-code integration, for creators or merchants avoiding custom development.

Option 2: Many Products（Dynamic）

If you have many products or need dynamic payment links:

1. Create a Payments Link

2. Dynamically append parameters to generate unlimited dynamic Payments Links.

3. Share or embed these links into your applications or product flows.

1. All Payments Links support dynamic parameter appending only for the parameters listed in the table below.

2. All other settings, such as payment methods, subscription type, and additional options, must be selected and configured directly in the payments form.

3. Multiple integrations

URL Parameters

You can extend the embedded checkout link by appending parameters to the URL. This is especially useful when you want to dynamically pass metadata such as product title, description, price, images or others.

Parameter	Type	Description	Example
merchant_transaction_id	string*	Required. Unique Id for the order transaction generated by the merchant. Can be generated with randomUUID() to ensure uniqueness. The rampId is returned in webhook order payloads. corresponds to rampId	merchant_transaction_id=550e8400-e29b-41d4-a716-446655440000
currency	string?	Effective only if included in the payment link’s supported currency list; otherwise defaults to the first configured currency.	currency=EUR
price	string?	Payment amount in the supported fiat or crypto currency format. Lmimits #Fiat currencies	price=29.99
signature	string?	HMAC-SHA256 hex signature generated with the merchant secret key; Required if a custom price is provided.	signature=b95df8938****9fgk56
title	string?	The product or payment title displayed on the checkout page.	title=Hello
desc	string?	A short description of the product or service.	desc=Text
images	array?	A list of image objects to display in the checkout interface.	images=[{"url":"https://cdn.example.com/item.jpg"}]
name	string?	Pre-filled consumer name (≤120 characters)	name=Elon Musk
email	string?	Pre-fill the customer's email in the checkout form.	email=[e-mail]
payment_method	string?	optional. Fiat payments only. If not specified, all payment methods supported for the selected currency will be returned. If specified, the method will be automatically preselected at checkout. Supported values include card, google, apple, revolut_pay, volt_banktransfer_eur, EightBWorld_instapay, interac_gk, unlimint_pix_brl and others. Refer to Payment methods for the full and up-to-date list.	payment_method=apple
fix_payment_method	boolean?	Locks the selected payment_method and prevents changes during checkout. Recommended for channel-specific flows (e.g. iOS) to optimize conversion and payment success.	fix_payment_method=true
redirect_url Temporarily unavailable (risk control upgrade)	string?	URL to which the user is redirected after passing the payments or ramps scenes; We recommend using the default checkout exit flow rather than redirecting via redirect_url. redirect urls are subject to risk and compliance monitoring, and high-risk or non-compliant destinations may affect merchant account health.	redirect_url=https://coindpay.xyz/wallet
more		Please contact our Devs team for dynamic updates.

Checkout Tips

? The value is optional, * the value is required. Non-authentic product or consumer information, such as title, email, and desc, is not required to be provided.

1. merchant_transaction_id

• The merchant_transaction_id is required.

• Orders may transition through multiple statuses, but all remain tied to the same merchant_transaction_id

• Separate or recurring orders generate distinct merchant_transaction_id values.

• Use randomUUID() or other encrypted Id libraries to generate a unique Id for each transaction to avoid duplicates.

• merchant_transaction_id serves as an alias for rampId. The rampId is returned in webhook order payloads.

• If not provided, it will not cause an error, but you may lose the ability to reliably track the order or query its status via this Id.

1. email

• Ensure the pre-submitted email matches the one used in subsequent order flows.

• The email should be a user’s email address obtained in advance.

• If the email is in a valid format, it will be automatically pre-filled in the checkout form.

• If unsure, request the user to manually enter their email to prevent mismatches.

1. price

• When the price routing parameter is enabled, configure the product’s Amount Type as Fixed Amount.

• The Random Amount option is intended for tipping or donation scenarios and is not controlled by the price parameter.

• When price is not provided, the payment Link will use the amount configured in the merchant dashboard.

• When price is provided in the URL, it is treated as dynamic input and must be protected by a signature.

• Any modification to the price value without a valid signature will result in the Payment Link being marked as invalid.

1. signature

• The signature parameter is conditionally required.

• f price is present, a valid signature must be generated and included.

• If price is absent, signature is optional.

• The signature cryptographically binds the request parameters to the merchant and prevents client-side tampering.

1. currency

• The currency routing parameter is optional.

• Please ensure the provided currency is supported in the payment link currency configuration, passing an unconfigured currency will be ignored.

• Multiple Fiat Currencies ( USD-pegged Disabled )

• The product link resolves to either the first configured currency or the developer-provided currency parameter (must match one of the enabled currencies).

• Client-side currency switching is disabled; only the resolved currency is used.

• Multiple Fiat Currencies ( USD-pegged Enabled )

• The product link resolves to either the first configured currency or the developer-provided currency parameter (must exist in the enabled list).

• End users may freely switch between all enabled currencies.

• Amounts remain anchored to USD, with conversions applied automatically using real-time FX rates.

1. USD-pegged

• Default: USD-pegged is disabled. the amount remains uniform and can be controlled via the price parameter.

• When USD-pegged is enabled:

  • All selected fiat currencies are automatically pegged to USD.

  • Settlement amounts are calculated in real time based on current FX rates.

Code for Checkout

import { createHmac } from 'crypto'

export function createHmacSignature(secret: string, data: string): string {
  return createHmac('sha256', secret).update(data).digest('hex')
}

import { randomUUID } from 'crypto'

const paymentLink = 'xxx'  // The payment link created by the merchant in Step 2

const merchant_transaction_id = randomUUID() || 'Your Custom Order Id'

export interface priceSignaturePayload {
  merchant_transaction_id: string
  price: string
}

export function canonicalizePriceSignaturePath(payload: priceSignaturePayload): string {
  return `merchant_transaction_id=${payload?.merchant_transaction_id}&price=${payload?.price}`
}

// secretKey: The merchant/developer’s API Secret from the dashboard integration webhooks.
const secretKey = YOUR_MERCHANT_API_SECRET

// Merchant payment link signature（If price is included in the URL）
export function signCheckoutPriceSignature(payload: priceSignaturePayload): string {
  const canonical = canonicalizePriceSignaturePath(payload)
  return createHmacSignature(secretKey, canonical)
}

// Render to your dynamic product link params
const paramsData = {
  merchant_transaction_id,  // 'xxx-123456',
  title: 'Your product title', // 
  desc: 'Your product desc',
  price: 19.99,
  signature: 'xxx', // signCheckoutPriceSignature('your price payload')
  email: '[e-mail]'
})

export function getEncodeCheckoutUrl(
  link: string,
  queryData?: Record<string, any>
): string {
  const url = new URL(link)

  Object.entries(queryData || {}).forEach(([key, value]) => {
    if (value === undefined || value === null) return
    url.searchParams.set(
      key,
      typeof value === 'object' ? JSON.stringify(value) : String(value)
    )
  })

  return url.toString()
}


const url = getEncodeCheckoutUrl(paymentLink, paramsData)

// you can preview this url
console.log('url', url)

https://coindpay.xyz/pay/link/vVKAsfomepqD0fstx9bdE?name=Jason&email=[e-mail] Note: the actual checkout URL must include the merchant_transaction_id parameter.

Example: Quick payment methods limited to iOS channels

https://coindpay.xyz/pay/link/vVKAsfomepqD0fstx9bdE?payment_method=apple&fix_payment_method=true

① Web

E-commerce checkouts, SaaS dashboards, or any web-based payment page.

1. Embed via iFrame

Native HTML styles can be customized as needed.

You can freely customize the surrounding HTML, container styles, and transitions using TailwindCSS or your preferred styling approach.

// React component + TailwindCSS

const yourCustomName = '', yourCustomStyle = {}

const onIframeLoad = ()=> {} // If some scenes for iframe loading success

<iframe
  src={url}
  allowFullScreen
  sandbox="allow-scripts allow-same-origin allow-popups allow-forms allow-popups-to-escape-sandbox allow-top-navigation-by-user-activation"
  allow="camera; microphone; geolocation; fullscreen; accelerometer; autoplay; clipboard-write; clipboard-read; payment; gyroscope; encrypted-media; picture-in-picture"
  className={yourCustomName}
  style={yourCustomStyle}
  onLoad={onIframeLoad}
/>

2. Redirect to Payment Page

Customize your content area (Button, image, etc.) style

<a href={url} target="_blank">
  Pay with CoindPay
</a>

Highlights:

• ✅ No SDK required

• ✅ Instant integration

• ✅ Dynamic data and ui adaptation

② Mobile App

iOS / Android / React Native / Flutter apps that need to embed or redirect to a payment flow.

WebView Embed

// React Native example

<WebView source={{ uri: url }} />

White-label Checkout

Personalized parameters such as payment_method, fixed_payment_method can be used to initialize the frontend checkout experience and directly launch the CoindPay checkout interface, making it well-suited for developer merchants seeking a more native and streamlined checkout experience.

Embedded mode

Whether to enable Embedded mode depends on the merchant developer’s integration approach.

Suitable for iframe embedding（Enabling embedded mode will hide basic payment link details, including merchant and product information, to provide a cleaner and more seamless embedded checkout experience）

Theme & Brand

Customize the checkout theme color, brand logo, and other branding elements.

4. Account & Webhooks

Manage your account-related settings, including wallet bindings, event callback URLs, notifications, and developer or merchant information.

Go to More → Account/Payouts or Integration/Hooks to view and manage your developer information, webhook endpoints, and related configurations.

Wallet payouts

When creating a payment link, merchants will be prompted to link a settlement wallet.

This step is required for merchants using fiat pay-in and stablecoin or crypto pay-out flows.

Webhooks callback

Once your Webhooks are configured under Developer Settings → Webhooks URLs, CoindPay will automatically send webhook notifications to your specified endpoint whenever a payment event occurs (e.g., completed, failed, or pending).

Your server should handle these events, verify the request signature using your API Secret and update your own order database accordingly.

The following example code how to handle webhook order data in a Next.js API route.

⚠️ Merchants and developers should pay special attention to verifying the x-signature request header and securely managing the private API Secret found in your Developer Hooks settings.

⚠️ The API Secret is used to validate the callback signature. When a transaction status changes, CoindPay sends a webhook request containing the transaction data. If you’re using callbacks, make sure to enable signature verification to ensure authenticity.

⚠️ To verify the signature, generate an HMAC SHA-256 hash using your API Secret and the entire raw callback body as input. Because the signature is generated based on the full payload, the request body must be used exactly as received, without any modification or parsing before signature verification.

⚠️ To avoid compatibility issues caused by data serialization differences across programming languages, please pay attention to how rawBody is handled in environments such as Node.js, Go, and Java.

⚠️ Before using webhooks and managing the order flow, ensure that your API secret has been generated and that it is correctly applied to the signature headers.

Local Debugging Mode

If you are unable to open the checkout page due to network or connectivity issues, we also provide a local debugging mode. This allows you to effectively validate your webhook api integration and end-to-end order flow.

Below is a webhook API example based on Node (Next.js)

Some code referencesIntegration

// The unique ID from your front-end with the customers
const merchant_transaction_id = 'xxx' // See => Example with Parameters

// https://api.yourdomain.com/webhooks/payments/landing
import type { NextApiRequest, NextApiResponse } from 'next'
import getRawBody from 'raw-body'

// Refer to the utils code in the “Code with Parameters” ⬆️
import { createSignature } from '@/lib/utils' 

export const config = {
  api: {
    bodyParser: false, // ✅ Disable Next.js automatic body parsing
  },
}

export default async function landing(req: NextApiRequest, res: NextApiResponse) {
  if (req.method !== 'POST') {
    return res.status(405).json({ ok: false, message: 'Method not allowed ˙◠˙' })
  }
  
  try {
    const secretKey = process.env.COINDPAY_API_SECRET_KEY as string
    
    if (!secretKey) {
      throw new Error('Missing CoindPay API SECRET KEY in env ˙◠˙')
    }

    const signatureHeader = req.headers['x-signature'] as string

    if (!signatureHeader) {
      return res.status(400).json({
        ok: false,
        message: 'Invalid signature ˙◠˙',
      })
    }
    
    // 1. Retrieve the raw request body
    const rawBody = (await getRawBody(req)).toString('utf8')
    console.log('📦 raw body:', rawBody)
    
    // 2. Verify signature (must use rawBody for verification)
    const expectedSig = createSignature(secretKey, rawBody)

    if (signatureHeader !== expectedSig) {
      console.error(`🚫 x-signature mismatch:`, { expectedSig, got: signatureHeader })
      return res.status(401).json({ ok: false, message: 'Invalid signature ˙◠˙' })
    }
    
    // 3. Parse JSON payload after successful verification
    const data = JSON.parse(rawBody)
    console.log('💎 Parsed data:', data)
  
    if (!data || !data?.id) {
      return res.status(502).json({ ok: false, message: 'Invalid payment order ˙◠˙' })
    }
    
    console.log(`✅ CoindPay payment ${data?.id}-${data?.rampStatus} callback data：`, data)
    
    // post your order data to your db, create or poll for updates
    // const payment = await prisma.payment.upsert({
    //  where: { rampId: data.id },
    //  update: {
    //    ...data,
    //  },
    //  create: {
    //    ...data,
    //  },
    // })
    ....
  } catch (error) {
    console.error(`🚫 CoindPay order data storage failed:`, error?.message)
  }
}

Webhooks Data Example（Selected statuses）Full Order Fields

new

{
    "id": "69ae9bd******0de524430c",
    "createdAt": "2026-03-09T10:07:18.900Z",
    "updatedAt": "2026-03-09T10:07:40.021Z",
    "rampId": "SS2654******96s121",
    "rampStatus": "new",
    "rampType": "pay",
    "payMethod": "mobile_pay",
    "name": "andrew tim",
    "email": "[e-mail]",
    "timezone": "Australia/Adelaide",
    "chain": "BSC",
    "amount": 14.147862,
    "usd": 15,
    "fiatAmount": 15,
    "fiatCoin": "USD",
    "symbol": "USDT",
    "payeeId": "-m3NiJQWM***F8Ih8K6IE",
    "appid": "693a61c42******e914fe691"
}

pending

paid

order_scheduled

completed

fialed

Order status

Payments/On-Ramps Status Reference

Below is a list of possible rampStatus values returned

when rampType=buy paymentMethod=Payment methods

Status	Description
init	User opened the payment window but hasn’t entered the payment stage and the order has not yet entered the processing flow.
new	A new transaction has been created. Starting from the new status, merchants with configured webhooks will receive event notifications.
pending	Waiting for 3DS verification from the user.
paid	The payer’s card has been authorized and the funds have been deposited into the processing channel. Final settlement and any conversion are subject to the issuing bank’s compliance and eligibility checks. If the bank declines, no funds will be captured.
order_scheduled	Indicates that the order has entered the processing queue. This status only reflects queue placement — and no funds are reserved.
order_retry	The order was declined or cancelled due to legal, compliance, or banking constraints. The consumer attempts the payment again through an alternative recommended banking provider.
expired	Order has been created, customer has not made payment for the order within the expiry time. (Expiry times may differ for each payment method). Expired orders can become active again. If payment is received after expiry, the order will automatically continue through the normal processing stages.
cancelled	The transaction was canceled, usually due to timeout or user action.
refunded	Order has been refunded by our customer support in response to a request from the customer.
failed	The transaction was rejected or declined by the bank.
settling	Funds have been authorized and are in the settlement process. The payout transaction has not yet been finalized on-chain.
settle_failed	Settlement attempt failed due to a transient or recoverable error. The order is eligible for retry（caused by RPC, network, or temporary infrastructure issues, retry may be triggered）
completed	✅ The merchant’s account has received the funds, and a receipt/invoice is sent to the customer’s email. This status also serves as the final indicator that the order has successfully completed.

Off-Ramp Status Reference

Below is a list of possible rampStatus values returned

when rampType=sell paymentMethod=card

Status	Description
init	User opened the payment window but hasn’t entered the payment stage and the order has not yet entered the processing flow.
new	A new transaction has been created. Starting from the new status, merchants with configured webhooks will receive event notifications.
pending	The transaction is in progress; payout processing has started.
failed	The transaction failed; the crypto amount will be returned to the user.
completed	✅ The payout has been successfully transferred to the user’s card.

💡 Tips:

1. Keeping your secret key safe, don't forget add the .env file to .gitignore

2. The rampId is required, from your front-end merchant_transaction_id

3. An order is successful only when its status is completed

Testnet config

Testnet Provider A - card list

Payout Asset：ETH on the EVM Sepolia（Prod environment configurations remain unaffected.）

1

Card #1

• Card Number 4444 4444 4444 3333

• Expiration Date any future date

• CVV 123

• Cardholder Name name + surname

2

Card #2

• Card Number 5555 4444 3333 1111

• Expiration Date any future date

• CVV 123 for success, 555 for fail

• Cardholder Name name + surname

If you encounter risk control or KYC interactions that affect the payment flow in the Testnet sandbox environment, you can use our official verification email: [e-mail] In the regular payment environment, please use your own developer or customer email.

Order Fallback Testnet Provider B - card list

Payout Asset：USDT on the EVM BSC Testnet（Prod environment configurations remain unaffected.）No changes to the payment link payout configuration are required in the test environment.

Visa

Card PAN	3-D Secure result	Transaction result
4000000000000085	3-D secure version 2, challenge flow, full authentication	Payment has CONFIRMED status
4580000000000059	3-D secure version 2, frictionless flow, attempt	Payment has CONFIRMED status
4000000000000093	3-D secure version 2, frictionless flow, success	Payment has CONFIRMED status
4000000000000051	No 3-D Secure	Payment has AUTHORIZED status
4000000000000077	No 3-D Secure	Payment has CONFIRMED status
4444444444444455	3-D secure version 2, challenge flow, full authentication	Payment has DECLINED status
4444444444449777	No 3-D Secure	Payment has DECLINED status

Mastercard

Card PAN	3-D Secure result	Transaction result
5100000000000065	3-D secure version 2, challenge flow, full authentication	Payment has CONFIRMED status
2400000000000069	3-D secure version 2, frictionless flow, attempt	Payment has CONFIRMED status
5100000000000073	3-D secure version 2, frictionless flow, success	Payment has CONFIRMED status
5100000000000651	No 3-D Secure	Payment has AUTHORIZED status
2400000000000077	No 3-D Secure	Payment has CONFIRMED status
5555555555559955	3-D secure version 2, challenge flow, full authentication	Payment has DECLINED status
5555555555554477	No 3-D Secure	Payment has DECLINED status

Order Fallback Testnet Provider C - card list

Payout Asset：from your payment link configuration.

🆔 KYC Data

A first time customer will be guided through a KYC process during their first order with us. We suggested you input words and names that exist as opposed to random strings, as there are still some basic validations in place.

You may also be asked to upload Id documents. This can be any image with some text, captured using your device. This will not be verified, however will need to be in high resolution.

Card #1

Field	Value
Card Name	Use the name that you provided as part of KYC
Card Number	4111 1111 1111 1111
Expiry	Any expiry date in the future
Security Code	Any

Demo video（Payments）

18MB

CoindPay_Pay-in&Pay-out_Real-time_Settlement.mp4

Open