⚡Quick API Integration

In this section, you’ll learn how to use the PayRam API to create payment links that can be integrated into your backend server for receiving payments.

Ask ChatGPT about this page

---

Prerequisites

Before using the PayRam API to create payment links, make sure you have completed the following:

• PayRam Server Setup: Ensure your PayRam server is installed and running successfully.

• API Key Generation: Generate an API key from your PayRam dashboard. This key will be required to authenticate API requests from your backend.

---

Example integration

Check out the Next.js demo application for a practical example of the Standard API Integration:

👉 PayRam API Integration Example

This example demonstrates how to build a simple payment form that connects to your PayRam server, generates payment links, and enables customers to start accepting payments seamlessly.

---

PayRam API integration

This is the simplest way to integrate PayRam into your website or server. Your backend calls the PayRam server API directly with the required details.

Base URL

Use this BASE_URL if SSL is not enabled.

BASE_URL = http://yourpayramserver.com:8080

Use this BASE_URL if SSL is enabled.

BASE_URL = https://yourpayramserver.com:8443

Create payment link

Use this endpoint if SSL is not enabled.

POST : ${BASE_URL}/api/v1/payment

Request headers (required)

Header	Value	Description
api-key	API_KEY	Your platform’s secret API key
content-type	application/json	Ensure JSON payload is used

Example request

Include these required details in the request body when generating a payment link.

{
    "customerEmail": "[email protected]",
    "customerId": "79473632",
    "amountInUSD": 12
}

Field	Type	Required	Description
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

Example response

This is the response you receive from the API request when it is successful.

{
  "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://yourpayramserver.com:8080"
}

• reference_id — Use this to track status, fetch payment results. This field is critical.

• url — The payment link to show to the user (for example, QR page or wallet selector). The URL expires after 15 minutes.

• host — Returned for internal routing purposes.

cURL request example

Replace api_key with the API key you received earlier.

curl --location 'https://yourdomain.com/api/v1/payment' \
--header 'API-Key: api_key' \
--header 'Content-Type: application/json' \
--data '{
    "customerEmail": "[email protected]",
    "customerId": "79473632",
    "amountInUSD": 12
}'

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

1. OPEN — The payment has not been processed yet.

2. CANCELLED — The payment link has expired. (Links expire after 15 minutes.)

3. FILLED — The user has paid the full requested amount.

4. PARTIALLY_FILLED — The user has paid less than the requested amount.

5. OVER_FILLED — The user has paid more than the requested amount.

Endpoint

GET ${BASE_URL}/api/v1/payment/reference/{reference_id}

Note: Use the reference_id from the payment creation response to retrieve specific payment details using this endpoint.

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"
}

---

You’ve successfully integrated PayRam with your application. You can now easily create payment links and start accepting payments from your customers.