Crypto Payin API

This document provides a comprehensive guide to integrate with the Pay Agency's Crypto Payin API. The Crypto Payin API allows seamless cryptocurrency payment processing. The API endpoint and payload details are provided below, along with examples in multiple programming languages.

API Endpoint

POST https://backend.pay.agency/api/v1/live/crypto/payin

Parameters

Parameter	Type	Description	Required
`first_name`	String	First name of the payer	Yes
`last_name`	String	Last name of the payer	Yes
`email`	String	Email address of the user	Yes
`amount`	Number	Transaction amount in smallest currency unit	Yes
`currency`	String	Currency code (ISO 4217 format)	Yes
`crypto_currency`	String	Cryptocurrency code (e.g., BTC, ETH, USDT)	Yes
`crypto_network`	String	Cryptocurrency network (e.g., ETHEREUM, BITCOIN)	Yes
`ip_address`	String	IP address of the user	Yes
`phone_number`	String	Phone number of the payer	Yes
`address`	String	Billing address	Yes
`country`	String	Country code (2 characters, ISO 3166-1 alpha-2 format)	Yes
`order_id`	String	Unique order from merchant side	Yes
`redirect_url`	String	URL to redirect users after payment	Yes
`webhook_url`	String	URL for server-to-server webhook notifications	No
`terminal_id`	String	Connector unique terminal_id (It's useful when you want to bypass all routing and cascading logic)	No

Payload

The payload should be sent in JSON format. Below is the structure of the payload:

{
  "first_name": "James",
  "last_name": "Crypto",
  "email": "james.crypto@gmail.com",
  "amount": 100,
  "currency": "USD",
  "crypto_currency": "BTC",
  "crypto_network": "BITCOIN",
  "ip_address": "127.0.0.1",
  "phone_number": "7654233212",
  "address": "64 Hertingfordbury Rd",
  "order_id": "CRYPTO_12524",
  "redirect_url": "https://pay.agency",
  "webhook_url": "https://pay.agency/webhook",
  "terminal_id": "T7244234",
}

Example Responses

Success Response

{
  "status": "SUCCESS",
  "message": "Payment processed successfully",
  "redirect_url": "https://example.com/success",
  "data": {
    "amount": 100.50,
    "currency": "USD",
    "order_id": "ORD123456",
    "transaction_id": "TXN789012",
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john@example.com"
    },
    "refund": {
      "status": false,
      "refund_date": null
    },
    "crypto_currency": "BTC",
    "crypto_network": "BITCOIN",
    "crypto_payment_status": "FULLPAID",
    "crypto_amount": 0.0025,
    "crypto_paid_amount": 0.0025
 
  }
}

Error Response

{
  "status": "FAILED",
  "message": "Transaction could not processed. Please try again.",
  "data": {
      "amount": 11,
      "currency": "USD",
      "order_id": null,
      "transaction_id": "PA0244285617663887",
      "customer": {
          "first_name": "James",
          "last_name": "doe",
          "email": "james@gmail.com"
      },
      "refund": {
          "status": false,
          "refund_date": null
      },
      "crypto_currency": "TRX",
      "crypto_network": "TRON",
      "crypto_payment_status": "UNDERPAID",
      "crypto_amount": 10,
      "crypto_paid_amount": 6.4
  }
}

Understanding Crypto Payment Status

The crypto_payment_status field in the response indicates the payment completion status for cryptocurrency transactions. This field helps you determine whether the customer has paid the exact amount, underpaid, or overpaid.

Payment Status Values

{
  "crypto_payment_status": "FULLPAID"
}

Description: The customer has paid the exact amount requested.

Implementation Notes

Important: Always check the crypto_payment_status field before fulfilling orders when dealing with cryptocurrency payments. Due to blockchain transaction characteristics, slight variations in payment amounts can occur due to:

Network fees and gas prices
Exchange rate fluctuations during transaction processing
User wallet limitations

Integration Examples

The API uses AES-256-CBC encryption to ensure secure transmission of sensitive data. Before sending the payload, you need to encrypt it using your encryption key and a dynamically generated initialization vector (IV). The encrypted payload and the IV must be sent to the API for proper decryption on the server side.

Each integration example demonstrates:

How to encrypt the payload using AES-256-CBC.
How to generate a random IV.
How to include both the encrypted data and the IV in the API request.

const { randomBytes, createCipheriv } = require("crypto");
const axios = require("axios");
 
// AES Encryption function
function encryptData(data, key) {
  const iv = randomBytes(16);
  const cipher = createCipheriv(
      "aes-256-cbc",
      Buffer.from(key, "utf-8"),
      iv
  );
  let encrypted = cipher.update(data, "utf-8");
  encrypted = Buffer.concat([encrypted, cipher.final()]);
  return iv.toString("hex") + ":" + encrypted.toString("hex");
}
 
const payload = {
  first_name: "James",
  last_name: "Crypto",
  email: "james.crypto@gmail.com",
  amount: 100,
  currency: "USD",
  crypto_currency: "BTC",
  ip_address: "127.0.0.1",
  phone_number: "7654233212",
  address: "64 Hertingfordbury Rd",
  order_id: "CRYPTO_12524",
  redirect_url: "https://pay.agency",
  webhook_url: "https://pay.agency/webhook",
  terminal_id: "T7244234",
};
 
const encryptionKey = "your-encryption-key-here";
const encryptedPayload = encryptData(JSON.stringify(payload), encryptionKey);
 
const response = await axios.post(
  "https://backend.pay.agency/api/v1/test/crypto/payin",
  { payload: encryptedPayload },
  {
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer your-secret-key-here"
    }
  }
);
 
console.log(response.data);

Crypto Payin API

On this page