6. API Documentation (Hosted Checkout Mode)

6. API Documentation (Hosted Checkout Mode)
Copy for LLM
Copy page as Markdown for LLMs
View as Markdown
Open this page as Markdown
Open in ChatGPT
Get insights from ChatGPT
Open in Claude
Get insights from Claude

Hosted Checkout mode is Infini's most recommended integration method. Merchants only need to create orders, redirect to checkout_url, and handle Webhooks to complete payment integration. This chapter only contains API documentation and corresponding field descriptions for Hosted Checkout mode.

All API prefix:

/v1/acquiring

6.1 Create Order

POST /v1/acquiring/order

Used to create an order and return the hosted checkout access URL (checkout_url).

Headers

Content-Type: application/json
Date: {GMT Time}
Authorization: Signature ...

Request Body

Field	Type	Required	Description
amount	string/number	Yes	Order fiat amount (up to 6 decimal places)
currency	string	Yes	Fiat currency, e.g. "USD"
request_id	string	Yes	Merchant-generated idempotency key, UUID "a759b99a-9d22-433d-bced-ab1d2e1bea1d"
client_reference	string	No	Merchant custom order number, recommended to be unique
order_desc	string	No	Order description
expires_in	number	No	Order expiration relative time (Unix seconds); use backend default if not provided
merchant_alias	string	No	Merchant display name (overrides backend configuration)
success_url	string	No	Redirect address after successful order payment
failure_url	string	No	Redirect address after failed order payment
pay_methods	array of integers	No	Payment modes: [1] crypto, [2] card, [1,2] both. Defaults to merchant config

Response Example

{
  "order_id": "10290d05-xxxx",
  "request_id": "your request_id",
  "checkout_url": "https://checkout.infini.money/pay/xxxx",
  "client_reference": "client_reference"
}

6.2 Query Order

GET /v1/acquiring/order?order_id ={order_id}

Returns real-time order status information.

Order Status Field Description

`status` - Payment Progress Status

Database stored field recording the order's processing status.

Value	Description
`pending`	Awaiting payment
`processing`	Processing (partial funds received)
`paid`	Paid
`partial_paid`	Partial payment expired
`expired`	Expired without payment

Response Example

{
  "order_id": "ord-123",
  "status": "processing",
  "amount": "100",
  "currency": "USD",
  "amount_confirming": "0",
  "amount_confirmed": "0.5",
  "expires_at": 1763512195,
  "created_at": 1763512000,
  "exception_tags": ["wrong_currency"],
  "client_reference": "ORDER-001"
}

6.3 Reissue Checkout Token

POST /v1/acquiring/token/reissue

Used to regenerate the hosted checkout URL, suitable for scenarios such as payment page closure or Token expiration.

Request Body

Field	Type	Required	Description
order_id	string	Yes	Unique order ID

Response

{
  "order_id": "ord-123",
  "checkout_url": "https://checkout.infini.money/pay/xxxx"
}

6.4 Payment APIs (Advanced)

Note: For most merchants, you only need to create an order and redirect to the checkout URL. The Payment APIs below are optional and require additional development work. They allow you to programmatically create and manage payments instead of using the hosted checkout.

Create Payment

POST /v1/acquiring/payment

Create a payment for an order programmatically.

Request Body:

order_id (string, required): Order ID
chain (string, required): Blockchain network name
token_id (string, required): Token identifier
payment_method (integer, optional): Payment method (currently only supports 1 for crypto)

Response:

{
  "payment_id": "pay-123",
  "amount": "100.00",
  "address": "0x1234567890abcdef1234567890abcdef12345678",
  "expires_at": 1763512195
}

Query Payment

GET /v1/acquiring/payment?payment_id={payment_id}

Query payment details including transaction history.

List Payments

GET /v1/acquiring/payment/list?order_id={order_id}

Get all payments associated with an order.

6.5 Fund Withdraw

POST /v1/acquiring/fund/withdraw

Used to withdraw funds from your Infini account to an external wallet address.

Request Body

Field	Type	Required	Description
chain	string	Yes	Blockchain network (see supported chains below)
token_type	string	Yes	Token type, e.g. "USDT"
amount	string	Yes	Withdrawal amount
wallet_address	string	Yes	Destination wallet address
note	string	No	Optional note for the withdrawal

Supported Chains and Tokens

Sandbox Environment:

Chain	Supported Tokens
TTRON	USDT

Production Environment:

Chain	Supported Tokens	Fee
ETHEREUM	USDT, USDC	5
BSC	USDT, USDC	0.5
SOLANA	USDT, USDC	1
ARBITRUM	USDT, USDC	0.5
TRON	USDT	3

Note:

Chain names and token types must be in uppercase
Fees are deducted in the same token type as your withdrawal. For example, if you withdraw USDT, the fee is deducted in USDT; if you withdraw USDC, the fee is deducted in USDC

Request Example

{
  "chain": "ETHEREUM",
  "token_type": "USDT",
  "amount": "6",
  "wallet_address": "0x5f716e5775b18409917e2a2f0762d29d6c385cb0",
  "note": "123"
}

Response Example

{"code":0,"message":"","data":{"request_id":"e94b4e88-36c2-4550-907e-839742cf5fae"}}

6.6 Webhook (Order Status Callback)

Merchants can configure Webhook receiving address in the backend. When order status changes, Infini will actively push the following events:

order.created
order.processing
order.completed
order.expired
order.late_payment

Webhook Headers

Header	Description
X-Webhook-Timestamp	Unix timestamp
X-Webhook-Event-Id	Unique event ID
X-Webhook-Signature	Webhook HMAC signature

Webhook Payload Example

{
  "event": "order.completed",
  "order_id": "ord-123",
  "client_reference": "ORDER-001",
  "amount": "100",
  "currency": "USD",
  "status": "paid",
  "amount_confirmed": "100",
  "amount_confirming": "0",
  "created_at": 1763512195,
  "updated_at": 1763512573,
  "exception_tags": []
}

For Webhook signature verification methods, please refer to Chapter 4: Authorization and Security Mechanisms.

6.7 Error Codes

All error response format:

{
  "code": 40001,
  "message": "Invalid request",
  "detail": "expires_at must be greater than current timestamp"
}

Common Error Codes

HTTP	Code	Description
400	40003	amount must be positive
400	40006	amount must be greater than 0.01
401	401	Invalid HMAC signature
404	40401	Order does not exist
409	40902	client_reference duplicate
409	40906	Order expired

6.8 Python Example (Hosted Checkout Mode)

The following example demonstrates the complete flow: Create Order → Redirect to Checkout → Webhook → Reissue Token.

6.8.1 Create Order

import hmac, hashlib, base64, time
from datetime import datetime, timezone
import requests

key_id = "merchant-001-prod"
secret_key = b"your-secret-key"

def create_order(amount):
    method = "POST"
    path = "/v1/acquiring/order"
    gmt_time = datetime.now(timezone.utc).strftime('%a, %d %b %Y %H:%M:%S GMT')

    signing_string = f"{key_id}\n{method} {path}\ndate: {gmt_time}\n"
    signature = base64.b64encode(
        hmac.new(secret_key, signing_string.encode(), hashlib.sha256).digest()
    ).decode()

    response = requests.post(
        f"https://openapi.infini.money{path}",
        json={
            "amount": amount,
            "currency": "USD",
            "client_reference": "ORDER-2024-001",
            "description": "Product purchase",
            "expires_at": int(time.time()) + 3600
        },
        headers={
            "Date": gmt_time,
            "Authorization": f'Signature keyId="{key_id}",algorithm="hmac-sha256",headers="@request-target date",signature="{signature}"',
            "Content-Type": "application/json"
        }
    )

    response.raise_for_status()
    return response.json()

6.8.2 Frontend Redirect to Checkout

@app.route('/create-payment', methods=['POST'])
def create_payment():
    order = create_order(amount=request.json['amount'])
    return {"checkout_url": order["checkout_url"]}

6.8.3 Webhook Callback Handling

@app.route('/webhook', methods=['POST'])
def handle_webhook():
    event = request.json

    if event['event'] == 'order.completed':
        process_fulfillment(event['order_id'], event['amount_confirmed'])
    elif event['event'] == 'order.processing':
        update_order_progress(event['order_id'], event['status'])
    elif event['event'] == 'order.expired':
        mark_order_expired(event['order_id'])

    return {"status": "ok"}

6.8.4 Reissue Checkout Token

def reissue_checkout_token(order_id):
    method = "POST"
    path = "/v1/acquiring/token/reissue"
    gmt_time = datetime.now(timezone.utc).strftime('%a, %d %b %Y %H:%M:%S GMT')

    signing_string = f"{key_id}\n{method} {path}\ndate: {gmt_time}\n"
    signature = base64.b64encode(
        hmac.new(secret_key, signing_string.encode(), hashlib.sha256).digest()
    ).decode()

    response = requests.post(
        f"https://api.infini.money{path}",
        json={"order_id": order_id},
        headers={
            "Date": gmt_time,
            "Authorization": f'Signature keyId="{key_id}",algorithm="hmac-sha256",headers="@request-target date",signature="{signature}"',
            "Content-Type": "application/json"
        }
    )

    response.raise_for_status()
    return response.json()