Integration docs

Overview

The 101pay API is a JSON REST API. All requests and responses use application/json. Base URL:

https://api-production-4983.up.railway.app

Authentication

The API accepts three credential types depending on the endpoint:

1 · API key pair — for the Charge API

A public key (pk_test_…) and a private key (sk_test_…), generated in Key management. A transaction only settles when the two keys form a matched pair. The pair is passed in the request body.

2 · Session token (JWT) — for account & management endpoints

Obtain a token from POST /v1/auth/login and send it as Authorization: Bearer <token>. Used for checkout-session creation, key management, the transaction statement, KYC and payment methods.

3 · Merchant API key — for x402 payment history

Shown once at signup (ap_test_…). Sent as Authorization: Bearer <apiKey> for GET /v1/payments.

Quickstart

• 1 — Create an account at the dashboard (or POST /v1/auth/register).
• 2 — Open Key management and generate a key pair. Store the private key.
• 3 — Settle your first transaction with the Charge API (below).

Charge API

Settle a transaction with a key pair. No header auth — the pair travels in the body.

Request body

• publicKey — string, required
• privateKey — string, required
• amount — decimal string, required (e.g. "9.99")
• currency — USDC · USDT · JPY · USD (default USDC)
• description — string, optional

curl -X POST https://api-production-4983.up.railway.app/v1/transactions/charge \
  -H "content-type: application/json" \
  -d '{
    "publicKey":  "pk_test_…",
    "privateKey": "sk_test_…",
    "amount":     "9.99",
    "currency":   "USD",
    "description":"order #1024"
  }'

Response 200

{
  "orderNo":     "20260517000000042",
  "transaction": "0x…",
  "amount":      "999",
  "currency":    "USD",
  "status":      "settled"
}

A mismatched pair returns 401 key_pair_invalid. amount is echoed back in minor units (see Reference).

Hosted Checkout

Create a checkout session, then send the customer to the hosted url. The customer picks a crypto method (USDC, BTC, ETH, …) and pays via a requires_action → confirm flow on the hosted page.

curl -X POST https://api-production-4983.up.railway.app/v1/checkout/sessions \
  -H "authorization: Bearer <JWT>" \
  -H "content-type: application/json" \
  -d '{ "amount":"1500", "currency":"JPY", "description":"Pro plan" }'

# → { "session": { "id": "…", "status": "open", … }, "url": "https://…/checkout/<id>" }

In production the confirm step is driven by the payment provider's webhook; the hosted page handles this for you.

USDT payment

Accept USDT on the TRON network (TRC20). The platform is non-custodial — funds settle straight into your own receiving address.

1 · Configure a receiving account

In the dashboard, open Receiving accounts and add your USDT-TRC20 address. Every USDT payment for your account settles there.

2 · Create a payment

Your server calls the endpoint below with your Client ID and a secret key — one of the private keys from the Keys page. A mismatch returns 401.

Request body

• clientId your 15-digit Client ID
• secret a key-pair private key (sk_test_…)
• amount decimal string, e.g. "1.00"
• currency invoice currency — USDC · USDT
• method payment rail — usdt

curl -X POST https://api-production-4983.up.railway.app/v1/payments \
  -H "content-type: application/json" \
  -d '{
    "clientId": "101000000000000",
    "secret":   "sk_test_…",
    "amount":   "1.00",
    "currency": "USDT",
    "method":   "usdt"
  }'

Response

The response returns cryptoPayLink — the hosted-checkout URL you send your customer to.

{
  "success": true,
  "payment": { "id": "…", "status": "open", "amount": "1.00", "currency": "USDT", "method": "usdt" },
  "cryptoPayLink": "https://…/en/checkout/<id>"
}

3 · The customer pays

The customer opens cryptoPayLink, chooses USDT, and is shown your receiving address and the exact amount. The order is marked paid once the on-chain transfer is confirmed via TronGrid.

The amount carries a unique sub-cent suffix so each payment can be matched on-chain. The customer must transfer exactly that amount and keep the checkout page open until it confirms.

Agentic payments (x402)

Price any resource with the x402 protocol so AI agents can pay per request.

Without an X-PAYMENT header the endpoint answers 402 with PaymentRequirements. The agent signs an EIP-3009 authorization and retries with the X-PAYMENT header; the facilitator verifies and settles, and the resource is returned. Payment history: GET /v1/payments (merchant API key).

Reference

Currencies

• USDC — 6 decimals · USD — 2 decimals · JPY — 0 decimals
• Amounts in responses are integer minor units (e.g. USD “999” = $9.99, JPY “1500” = ¥1500).

Payment methods

• usdc · btc · eth · usdt · bnb · sol · ada · xrp · doge · dot
• All methods are crypto rails — the customer sends to a deposit address.

Order number

Every transaction gets a unique 17-digit order number: 8 digits of the transaction date (YYYYMMDD) + a 9-digit sequence — e.g. 20260517000000042.

Errors

Errors return a JSON body and a matching HTTP status:

{ "error": "key_pair_invalid", "message": "the public key and private key do not form a valid pair" }

• 400 invalid_request · 401 unauthorized · 402 payment_rejected
• 404 not_found · 409 conflict · 500 internal_error