Crypto On/Off Ramp API

This document provides a comprehensive guide to integrate with the Pay Agency's Crypto On/Off Ramp API. The Crypto On/Off Ramp API allows seamless on ramp (fiat to crypto) and offramp (crypto to fiat) transactions through a single endpoint. 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

Overview

The Crypto On/Off Ramp API provides a unified solution for both on ramp and off ramp cryptocurrency transactions:

On ramp (Fiat to Crypto): Convert fiat currency to cryptocurrency
Off ramp (Crypto to Fiat): Convert cryptocurrency to fiat currency

Both transaction types are handled through the same API endpoint, with the transaction type specified in the request payload.

Parameters

Parameter	Type	Description	Required
`first_name`	String	First name of the user (3-191 characters, letters only)	Yes
`last_name`	String	Last name of the user (3-191 characters, letters only)	Yes
`phone_number`	String	Phone number of the user (8-19 digits, with optional + prefix)	Yes
`transaction_type`	String	Transaction type: "ONRAMP" (fiat to crypto) or "OFFRAMP" (crypto to fiat)	Yes
`fiat_currency`	String	Fiat currency code (3 characters, e.g., USD, EUR)	Yes
`crypto_currency`	String	Cryptocurrency code (e.g., BTC, ETH, USDT)	Yes
`crypto_amount`	Number	Amount in cryptocurrency (required for OFFRAMP, not allowed for ONRAMP)	Conditional
`fiat_amount`	Number	Amount in fiat currency (required for ONRAMP, not allowed for OFFRAMP)	Conditional
`wallet_address`	String	Cryptocurrency wallet address for receiving/sending funds	Yes
`ip_address`	String	IP address of the user	Yes
`email`	String	Email address of the user	Yes
`country`	String	Country code (2 characters, ISO 3166-1 alpha-2 format)	Yes
`payment_method`	String	Payment method: "CARD", "BANK", or "WALLET"	No
`redirect_url`	String	URL to redirect users after transaction	Yes
`webhook_url`	String	URL for server-to-server webhook notifications	No
`order_id`	String	Unique order from merchant side	No
`terminal_id`	String	Connector unique terminal_id (It's usefull when you want to bypass all routing and cascading logic)	No

Transaction Type Rules

ON RAMP Transactions:

fiat_amount is required
crypto_amount should not be provided
User pays in fiat currency and receives cryptocurrency

OFFRAMP Transactions:

crypto_amount is required
fiat_amount should not be provided
User sends cryptocurrency and receives fiat currency

Example Payloads

On ramp Transaction (Fiat to Crypto)

{
  "first_name": "John",
  "last_name": "Doe",
  "phone_number": "+1234567890",
  "transaction_type": "ONRAMP",
  "fiat_currency": "USD",
  "crypto_currency": "BTC",
  "fiat_amount": 1000,
  "wallet_address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  "ip_address": "192.168.1.1",
  "email": "john.doe@example.com",
  "country": "US",
  "order_id": "ORD123456789",
  "redirect_url": "https://example.com/success",
  "webhook_url": "https://example.com/webhook"
}

Offramp Transaction (Crypto to Fiat)

{
  "first_name": "Jane",
  "last_name": "Smith",
  "phone_number": "+1987654321",
  "transaction_type": "OFFRAMP",
  "fiat_currency": "EUR",
  "crypto_currency": "ETH",
  "crypto_amount": 2.5,
  "wallet_address": "0x742d35Cc6634C0532925a3b8D4C9db96C4b4d8b6",
  "ip_address": "192.168.1.2",
  "email": "jane.smith@example.com",
  "country": "DE",
  "order_id": "ORD123456789",
  "redirect_url": "https://example.com/success",
  "webhook_url": "https://example.com/webhook"
}

Example Responses

Success Response

{
  "status": "REDIRECT",
  "message": "Please redirect user to complete the payment.",
  "redirect_url": "https://example.com/success",
  "data": {
    "transaction_id": "TXN123456789",
    "fiat": "USD",
    "fiat_amount": 1000,
    "crypto": "BTC",
    "crypto_amount": 0.025,
    "customer": {
      "first_name": "John",
      "last_name": "Doe",
      "email": "john.doe@example.com"
    }
  }
}

Error Response

{
  "message": "Encryption Key is invalid."
}

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).

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");
}
 
// Onramp transaction example
const onrampPayload = {
  first_name: "John",
  last_name: "Doe",
  phone_number: "+1234567890",
  transaction_type: "ONRAMP",
  fiat_currency: "USD",
  crypto_currency: "BTC",
  fiat_amount: 1000,
  wallet_address: "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh",
  ip_address: "192.168.1.1",
  email: "john.doe@example.com",
  country: "US",
  payment_method: "CARD",
  redirect_url: "https://example.com/success",
  webhook_url: "https://example.com/webhook"
};
 
const encryptionKey = "your-encryption-key-here";
const encryptedPayload = encryptData(JSON.stringify(onrampPayload), encryptionKey);
 
const response = await axios.post(
  "https://backend.pay.agency/api/v1/test/crypto",
  { data: encryptedPayload },
  {
    headers: {
      "Content-Type": "application/json",
      "Authorization": "Bearer your-secret-key-here"
    }
  }
);
 
console.log(response.data);

Crypto On/Off Ramp API

Transaction Type Rules

On this page