API Introduction - InventPay

Welcome to the InventPay API

The InventPay API allows you to integrate cryptocurrency payment processing into your applications. Our RESTful API is designed to be simple, predictable, and easy to integrate.

RESTful Design

Standard HTTP methods and status codes

JSON Format

All requests and responses use JSON

Comprehensive SDKs

Official libraries for JavaScript and Python

Real-time Webhooks

Instant notifications for all events

Base URL

All API requests should be made to:

https://api.inventpay.io

Authentication

The InventPay API uses API keys for authentication. Include your API key in the X-API-Key header of every request.

Get Your API Key

Sign up at inventpay.io
Navigate to Dashboard → Settings → API Keys
Click “Generate New API Key”
Copy and securely store your API key

Never expose your API key in client-side code or public repositories. Always use environment variables to store sensitive credentials.

Example Authentication

curl https://api.inventpay.io/v1/merchant/balance \
  -H "X-API-Key: cmfnz7jei0005p54eekx4e6mb"

Request Format

HTTP Methods

The API uses standard HTTP methods:

Method	Usage
`GET`	Retrieve resources
`POST`	Create new resources
`PUT`	Update existing resources
`DELETE`	Remove resources

Content Type

All requests with a body must include the Content-Type: application/json header.

Example Request

curl -X POST https://api.inventpay.io/v1/create_payment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 29.99,
    "amountCurrency": "USD",
    "currency": "USDT_BEP20",
    "orderId": "order-12345"
  }'

Response Format

All API responses are returned in JSON format with a consistent structure.

Successful Response

{
  "success": true,
  "data": {
    // Response data here
  },
  "message": "Operation completed successfully",
  "statusCode": 200
}

Error Response

{
  "success": false,
  "error": "Error message",
  "details": {
    // Additional error details
  },
  "statusCode": 400
}

HTTP Status Codes

The API uses standard HTTP status codes:

Code	Meaning	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing API key
404	Not Found	Resource not found
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred

Error Handling

Error Response Structure

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "currency": "Invalid currency. Must be one of: BTC, ETH, LTC, USDT_ERC20, USDT_BEP20"
  },
  "statusCode": 400
}

Common Errors

401 Unauthorized

Cause: Invalid or missing API keySolution: Verify your API key is correct and included in the X-API-Key header

{
  "success": false,
  "error": "Invalid API key",
  "statusCode": 401
}

400 Bad Request

Cause: Invalid request parametersSolution: Check the details field for specific validation errors

{
  "success": false,
  "error": "Validation failed",
  "details": {
    "amount": "Amount must be greater than 0"
  },
  "statusCode": 400
}

429 Rate Limit Exceeded

Cause: Too many requests in a short timeSolution: Implement exponential backoff and respect rate limits

{
  "success": false,
  "error": "Rate limit exceeded",
  "retryAfter": 60,
  "statusCode": 429
}

404 Not Found

Cause: Resource doesn’t existSolution: Verify the resource ID is correct

{
  "success": false,
  "error": "Payment not found",
  "statusCode": 404
}

Rate Limits

To ensure fair usage and system stability, the API implements rate limiting:

Endpoint Type	Limit	Window
Payment Creation	100 requests	Per minute
Status Checks	300 requests	Per minute
Withdrawals	10 requests	Per minute
Other Endpoints	60 requests	Per minute

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640000000

Handling Rate Limits

async function makeRequest(url, options) {
  const response = await fetch(url, options);

  if (response.status === 429) {
    const retryAfter = response.headers.get("X-RateLimit-Reset");
    const waitTime = retryAfter - Date.now();

    await new Promise((resolve) => setTimeout(resolve, waitTime));
    return makeRequest(url, options); // Retry
  }

  return response;
}

Pagination

Endpoints that return lists support pagination using query parameters:

Parameter	Type	Default	Description
`page`	integer	1	Page number
`limit`	integer	10	Items per page (max 100)

Example

GET /v1/payments?page=2&limit=20

Response

{
  "success": true,
  "data": {
    "items": [...],
    "pagination": {
      "page": 2,
      "limit": 20,
      "total": 150,
      "pages": 8
    }
  }
}

Idempotency

To safely retry requests without performing the same operation twice, use idempotency keys:

curl -X POST https://api.inventpay.io/v1/create_payment \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "X-Idempotency-Key: unique-key-123" \
  -H "Content-Type: application/json" \
  -d '{...}'

Idempotency keys are stored for 24 hours. Use a unique key for each unique request.

Versioning

The API version is included in the URL path:

https://api.inventpay.io/v1/...

Current Version: v1 We maintain backwards compatibility within a major version. Breaking changes will result in a new major version (v2, v3, etc.).

SDKs and Libraries

JavaScript/TypeScript

Official Node.js and browser SDK with full TypeScript support

npm install inventpay

Python

Official Python SDK with type hints and async support

pip install inventpay

Webhooks

For real-time event notifications, configure webhooks:

Configure Webhook URL

Set your endpoint in the dashboard or via API

Verify Signatures

Always verify webhook signatures for security

Handle Events

Process payment and withdrawal events

Return 200 OK

Respond quickly to acknowledge receipt

Webhook Documentation

Learn how to set up and secure webhooks

Testing

Test Mode

Use separate test API keys for development and testing:

Test payments don’t process real cryptocurrency
Test all integration flows safely
Generate test API keys in dashboard

Test Data

Use these test values for development:

Field	Test Value
Amount	Any positive number
Currency	All supported currencies
Order ID	Any string

Never use production API keys in test environments or public repositories.

Best Practices

Secure Your API Keys

Store keys in environment variables
Never commit keys to version control
Rotate keys periodically
Use separate keys for different environments

Handle Errors Gracefully

Always check response status codes - Parse error messages for details - Implement retry logic with exponential backoff - Log errors for debugging

Use Webhooks

Don’t poll for status changes - Implement webhook signature verification - Handle duplicate deliveries - Return 200 OK quickly

Implement Idempotency

Use idempotency keys for critical operations - Store request IDs to prevent duplicates - Handle retries safely

Monitor Your Integration

Track API response times
Monitor error rates
Set up alerts for failures
Review webhook delivery success rates

API Endpoints

Payments

Create Payment

Create a fixed-currency payment request

Create Invoice

Create a multi-currency invoice

Get Payment Status

Check payment status and confirmations

Balances

Get Balances

Retrieve all cryptocurrency balances

Get Balance by Currency

Get specific currency balance

Withdrawals

Create Withdrawal

Withdraw funds to external wallet

Get Withdrawal

Check withdrawal status

Support

Documentation

Browse complete documentation

Email Support

Contact our support team

API Status

Check current API status

GitHub Issues

Report bugs or request features

Next Steps

Get Your API Key

Try the Quickstart

Create your first payment in 5 minutes

Install an SDK

Choose JavaScript or Python SDK

Set Up Webhooks

Configure real-time notifications

Go Live

Switch to production API keys

Quickstart Guide

Get started in under 5 minutes

Overview

Payments

Balances

Withdrawals

​Welcome to the InventPay API

RESTful Design

JSON Format

Comprehensive SDKs

Real-time Webhooks

​Base URL

​Authentication

​Get Your API Key

​Example Authentication

​Request Format

​HTTP Methods

​Content Type

​Example Request

​Response Format

​Successful Response

​Error Response

​HTTP Status Codes

​Error Handling

​Error Response Structure

​Common Errors

​Rate Limits

​Rate Limit Headers

​Handling Rate Limits

​Pagination

​Example

​Response

​Idempotency

​Versioning

​SDKs and Libraries

JavaScript/TypeScript

Python

​Webhooks

Webhook Documentation

​Testing

​Test Mode

​Test Data

​Best Practices

​API Endpoints

​Payments

Create Payment

Create Invoice

Get Payment Status

​Balances

Get Balances

Get Balance by Currency

​Withdrawals

Create Withdrawal

Get Withdrawal

​Support

Documentation

Email Support

API Status

GitHub Issues

​Next Steps

Quickstart Guide

Welcome to the InventPay API

Base URL

Authentication

Get Your API Key

Example Authentication

Request Format

HTTP Methods

Content Type

Example Request

Response Format

Successful Response

Error Response

HTTP Status Codes

Error Handling

Error Response Structure

Common Errors

Rate Limits

Rate Limit Headers

Handling Rate Limits

Pagination

Example

Response

Idempotency

Versioning

SDKs and Libraries

Webhooks

Testing

Test Mode

Test Data

Best Practices

API Endpoints

Payments

Balances

Withdrawals

Support

Next Steps