API Reference

Complete API documentation for integrating MakaPay into your application.

---

Base URL

Production: https://app.makapay.com/api

---

Authentication

All API requests require authentication via API key.

Obtaining an API Key

1. Log in to the MakaPay Dashboard

2. Navigate to API Keys

3. Click Create New Key

4. Copy and securely store your API key

Using the API Key

Include the API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Important: Never expose your API key in client-side code.

---

Endpoints

Create Payment

Create a new payment link.

POST /payments

Request Body

Field	Type	Required	Description
merchant	string	Yes	Ethereum address to receive payment
chainId	string	Yes	Target blockchain chain ID
token	string	Yes	ERC20 token contract address
amount	string	Yes	Payment amount (human-readable, e.g., "100.00")
orderId	string	Yes	Your internal order reference (max 100 chars)
description	string	No	Payment description (max 200 chars)
blockConfirmations	number	No	Required confirmations (default: 1, max: 100)
gasless	boolean	No	Enable gasless mode (default: false)
payerCoversFee	boolean	No	Payer covers fees (default: false)

Example Request

curl -X POST https://app.makapay.com/api/payments \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
    "chainId": "137",
    "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
    "amount": "50.00",
    "orderId": "order-12345",
    "description": "Premium subscription",
    "blockConfirmations": 1,
    "gasless": false,
    "payerCoversFee": false
  }'

Response

{
  "url": "https://app.makapay.com/pay/01234567-89ab-cdef-0123-456789abcdef"
}

Response Fields

Field	Type	Description
url	string	Payment page URL to share with customer

Error Responses

Status	Error	Description
400	Invalid form data	Request validation failed
401	Unauthorized	Invalid or missing API key
500	Failed to create payment	Internal server error

---

Get Balance

Get your Gas Tank balance.

GET /balance

Example Request

curl https://app.makapay.com/api/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "balance": "25.500000"
}

Response Fields

Field	Type	Description
balance	string	Current Gas Tank balance in USDT (6 decimals)

---

Supported Networks & Tokens

Mainnet

Ethereum (Chain ID: 1)

Token	Contract Address	Decimals
USDT	0xdAC17F958D2ee523a2206206994597C13D831ec7	6
USDC	0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48	6

Polygon (Chain ID: 137)

Token	Contract Address	Decimals
USDT	0xc2132D05D31c914a87C6611C10748AEb04B58e8F	6
USDC	0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359	6

BNB Smart Chain (Chain ID: 56)

Token	Contract Address	Decimals
USDT	0x55d398326f99059ff775485246999027b3197955	18
USDC	0x8ac76a51cc950d9822d68b83fe1ad97b32cd580d	18
XRP	0x1d2f0da169ceb9fc7b3144628db156f3f6c60dbe	18
TRX	0xce7de646e7208a4ef112cb6ed5038fa6cc6b12e3	6

MakaChain (Chain ID: 777178)

Token	Contract Address	Decimals
USDT	0x30C28E393E0732335235685B345c95E6465Ad8A5	6

Testnet

Sepolia (Chain ID: 11155111)

Token	Contract Address	Decimals
USDT	0x3B62e45fB977773c2eF0404d80e0C59de22A97ec	6
USDC	0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238	6

MakaChain Testnet (Chain ID: 777177)

Token	Contract Address	Decimals
USDT	0x309F410f92A98e43E1EEF623015a2e784F80ed72	6
USDC	0x1C978Ed2de920eA6c5844d011Ab9f574979F82A6	6

---

Webhooks

Configure webhooks to receive real-time payment notifications.

Setup

1. Go to Dashboard > Webhooks

2. Enter your webhook URL (HTTPS required)

3. Save configuration

Webhook Payload

{
  "event": "payment.completed",
  "paymentId": "01234567-89ab-cdef-0123-456789abcdef",
  "orderId": "order-12345",
  "status": "completed",
  "amount": "50.00",
  "receivedAmount": "50.00",
  "token": "0xc2132D05D31c914a87C6611C10748AEb04B58e8F",
  "chainId": 137,
  "merchant": "0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00",
  "transactionHash": "0x...",
  "timestamp": "2024-01-15T10:30:00Z"
}

Event Types

Event	Description
payment.completed	Payment successfully settled
payment.failed	Settlement failed
payment.expired	Payment link expired

Retry Policy

• Failed deliveries are retried up to 3 times

• Retry intervals: 1 minute, 5 minutes, 30 minutes

• View delivery logs in the dashboard

---

Code Examples

Node.js

const axios = require('axios');

const API_KEY = 'your_api_key';
const BASE_URL = 'https://app.makapay.com/api';

async function createPayment(orderData) {
  const response = await axios.post(
    `${BASE_URL}/payments`,
    {
      merchant: '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
      chainId: '137',
      token: '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
      amount: orderData.total.toString(),
      orderId: orderData.id,
      description: `Order #${orderData.id}`,
    },
    {
      headers: {
        'Authorization': `Bearer ${API_KEY}`,
        'Content-Type': 'application/json',
      },
    }
  );

  return response.data.url;
}

// Usage
const paymentUrl = await createPayment({
  id: 'order-12345',
  total: 99.99,
});
console.log('Payment URL:', paymentUrl);

Python

import requests

API_KEY = 'your_api_key'
BASE_URL = 'https://app.makapay.com/api'

def create_payment(order_data):
    response = requests.post(
        f'{BASE_URL}/payments',
        json={
            'merchant': '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
            'chainId': '137',
            'token': '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
            'amount': str(order_data['total']),
            'orderId': order_data['id'],
            'description': f"Order #{order_data['id']}",
        },
        headers={
            'Authorization': f'Bearer {API_KEY}',
            'Content-Type': 'application/json',
        }
    )
    response.raise_for_status()
    return response.json()['url']

# Usage
payment_url = create_payment({
    'id': 'order-12345',
    'total': 99.99,
})
print(f'Payment URL: {payment_url}')

PHP

<?php
$api_key = 'your_api_key';
$base_url = 'https://app.makapay.com/api';

function createPayment($orderData) {
    global $api_key, $base_url;

    $ch = curl_init();

    curl_setopt_array($ch, [
        CURLOPT_URL => "$base_url/payments",
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_POST => true,
        CURLOPT_HTTPHEADER => [
            "Authorization: Bearer $api_key",
            "Content-Type: application/json",
        ],
        CURLOPT_POSTFIELDS => json_encode([
            'merchant' => '0x742d35Cc6634C0532925a3b844Bc9e7595f8fE00',
            'chainId' => '137',
            'token' => '0xc2132D05D31c914a87C6611C10748AEb04B58e8F',
            'amount' => (string)$orderData['total'],
            'orderId' => $orderData['id'],
            'description' => "Order #{$orderData['id']}",
        ]),
    ]);

    $response = curl_exec($ch);
    curl_close($ch);

    $data = json_decode($response, true);
    return $data['url'];
}

// Usage
$paymentUrl = createPayment([
    'id' => 'order-12345',
    'total' => 99.99,
]);
echo "Payment URL: $paymentUrl\n";

---

Rate Limits

Endpoint	Rate Limit
POST /payments	100 requests/minute
GET /balance	60 requests/minute

Exceeding rate limits returns HTTP 429 (Too Many Requests).

---

Error Handling

Error Response Format

{
  "error": "Error message describing what went wrong"
}

Common Errors

Status	Error	Solution
400	Invalid Merchant address format	Verify the merchant address is a valid Ethereum address
400	Invalid Token address format	Verify the token contract address
400	Invalid network selected	Use a supported chain ID
400	Amount must be a positive number	Ensure amount is > 0
401	Unauthorized	Check your API key
503	Oracle price unavailable	Retry after a few seconds

---

SDK (Coming Soon)

Official SDKs for popular languages:

• JavaScript/TypeScript: npm install @makapay/sdk

• Python: pip install makapay

• PHP: composer require makapay/sdk

• Go: go get github.com/makapay/go-sdk

---

Changelog

v1.0.0 (Current)

• Initial API release

• Payment creation endpoint

• Balance endpoint

• Webhook support