Advance Integration
If you use this method, you must handle the additional tasks yourself. These include calling tickers, rendering the UI, showing QR codes, and displaying the deposit addresses where users send their payments.
Base URL
Use this URL if SSL is not enabled.
http://yourpayramserver.com:8080Use this URL if SSL is enabled.
https://yourpayramserver.com:8443API to create payment link
Endpoint
POST : /api/v1/paymentThis API generates a payment link for a user and amount. The returned reference_id is required to track payment status and reconcile transactions.
Request headers (required)
api-key
API_KEY
Your platform’s secret API key
content-type
application/json
Ensure JSON payload is used
Note
API_KEYvalues are unique to each project.
Request body
{
"customerID": "79473632",
"customerEmail": "[email protected]",
"amountInUSD": 12.
}Parameters
customerID
String
✅ Yes
A unique ID you assign to the user (e.g., UUID or numeric ID)
customerEmail
String
✅ Yes
User’s email (for internal record / fraud checks)
amountInUSD
Number
✅ Yes
The dollar equivalent to be paid by the user
Successful response
{
"host": "http://yourpayramserver.com:8080",
"reference_id": "c80f5363-0397-4761-aa1a-3155c3a21470",
"url": "http://yourpayramserver.com/payments?reference_id=c80f5363-0397-4761-aa1a-3155c3a21470&host=http://35.188.192.37:8080"
}reference_id: Critical. Use it to track status, fetch payment results, or verify webhook events.
url: The actual payment link shown to the user (for example, QR page or wallet selector). The link expires after 15 minutes.
host: Used for internal routing purposes.
API: Fetch supported tickers
Endpoint
GET /api/v1/tickerThis endpoint returns a list of supported tickers on PayRam. Each ticker includes details such as the blockchain, token address, precision, and current market price.
Response
Status: 200 OK
Content-Type: application/json
Each object in the response array represents a supported ticker.
[
{
"blockchainCode": "ETH",
"currencyCode": "ETH",
"tokenAddress": "0x0000000000000000000000000000000000000000",
"standard": "ETH",
"walletPrecision": 18,
"family": "ETH_Family",
"price": "2557.8441"
},
...
]Supported coins by blockchain
ETH
ETH, USDT, USDC
ETH, ERC-20
BTC
BTC
BTC
TRX
TRX, USDT
TRX, TRC-20
BASE
ETH, USDC
ETH,
API: Get blockchain currencies by reference ID
Endpoint
GET /api/v1/blockchain-currency/reference/{reference_id}This API retrieves all available blockchain deposit addresses for a user linked to a specific reference_id. The reference_id comes from the payment link creation API.
Each returned object represents one supported currency on a specific blockchain (for example, ETH on Ethereum or USDC on Base). These addresses are used to receive user deposits.
Note For first-time payments, the customerAddress field is empty because new users haven’t been assigned deposit addresses yet.
Example response
[
{
"blockchainCode": "ETH",
"network": "Ethereum",
"currencyCode": "ETH",
"currency": "Ethereum",
"customerAddress": "0xAB551d539aac5CB1548EBBDFdB71Af43bDC552D9",
"tokenAddress": "0x0000000000000000000000000000000000000000",
"standard": "ETH",
"walletPrecision": 18,
"family": "ETH_Family",
"recommended": false,
"mostUsed": false
},
...
]Relation to Payment Link
Use this API only after creating a payment link because the reference_id is generated in that step.
The API returns all supported deposit options for the transaction associated with that reference_id.
Assign deposit addresses to a user
What happens on the first payment?
When a user makes their first payment, two things occur:
The customerAddress field is empty (for example:
"customerAddress": "").This happens because the user hasn’t been assigned a deposit address on the blockchain family yet.
In the EVM family, there are two blockchains: Base and Ethereum. If you generate a deposit address once for Base, the same address also applies to Ethereum because they share the same family.
Call the Deposit Address API only if the customerAddress is empty for a blockchain family. This assigns the user a static address once per family so you can track their payments.
How to generate a deposit address
To assign a customerAddress, you must generate a deposit address for the user. Do this by calling the following endpoint.
Endpoint
POST /api/v1/deposit-address/reference/{reference_id}Example request body
{
"blockchain_code": "ETH"
}Other valid values for blockchain_code are:
BTC — Bitcoin
ETH — Ethereum
TRX — Tron
BASE — Base
Example response
{
"id": 20,
"Address": "0xAB551d539aac5CB1548EBBDFdB71Af43bDC552D9",
"Family": "ETH_Family",
"Status": "active",
"MemberID": 25,
"xpub_id": 1,
...
}The Address field becomes the customerAddress for future payments.
This address is stored and reused for the same user on the same blockchain.
API: Get payment status by reference ID
Use this endpoint to fetch payment details for a given reference_id. This endpoint is used to check the current status of a payment, such as whether it’s open, completed, or failed.
Possible payment statuses
OPEN — The payment has not been processed yet.
CANCELLED — The payment link has expired. (Links expire after 15 minutes.)
FILLED — The user has paid the full requested amount.
PARTIALLY_FILLED — The user has paid less than the requested amount.
OVER_FILLED — The user has paid more than the requested amount.
Endpoint
GET /api/v1/payment/reference/{reference_id}Example response
{
"amount": "35",
"blockchain_symbol": "ETH",
"cancel_url": "abc",
"created_at": "2024-05-24T10:44:08.469147221Z",
"currency_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"currency_decimals": 6,
"currency_desc": null,
"currency_name": "ethereum",
"currency_symbol": "USDC",
"customer_id": "104755546182221158537",
"deposit_address": "0x8e25fE332188B027aD2119906eD1e3954195ED1a",
"filled_amount": "",
"filled_amount_in_usd": "",
"invoice_id": "1716559699",
"merchant_name": "Merchant Name",
"payment_state": "OPEN",
"reference_id": "2618e325-b533-447c-b203-98cb9c6a8665",
"success_url": "https://www.coinpaymentsuk.com/usdc_check_payment.php"
}Last updated