MolnPayDocs
API reference

Billing

Your plan and operational balance

GET/v1/billing

Every fee on the rate card is drawn from a prepaid OPERATIONAL BALANCE in USD cents. You fund it by sending USDT or USDC (credited at par) or a chain's native coin (credited at spot) to one of your funding addresses (GET /v1/billing/funding).

live.ok says whether live invoices are accepted right now; activation says how much more the balance needs before the plan you chose switches on. The balance stays yours: it is refundable on request.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/billing"
{  "object": "billing",  "plan": "drift",  "plan_name": "string",  "plan_status": "pending",  "plan_activated_at": "2019-08-24T14:15:22Z",  "requested_plan": "string",  "requested_plan_name": "string",  "balance_cents": "string",  "onboarding_paid_cents": "string",  "live": {    "ok": true,    "reason": "plan_not_active"  },  "onboarding": {    "steps": [      {        "step": "plan",        "done": true,        "bypassed": true,        "complete": true      }    ],    "bypassed": [      "address"    ],    "skipped_at": "2019-08-24T14:15:22Z",    "can_skip": true,    "remaining": 0  },  "activation": {    "plan": "string",    "plan_name": "string",    "onboarding_due_cents": "string",    "balance_required_cents": "string",    "shortfall_cents": "string"  },  "fees": {    "rate_bps": 0,    "fixed_cents": "string",    "cap_cents": "string",    "address_fee_cents": "string",    "min_monthly_cents": "string"  },  "plans": [    {      "key": "string",      "name": "string",      "onboarding_fee_cents": "string",      "min_monthly_cents": "string",      "operational_balance_cents": "string",      "rate_bps": 0,      "fixed_cents": "string",      "cap_cents": "string",      "negotiated": true    }  ]}

Choose or change your plan

POST/v1/billing/plan

Activates immediately when the balance already covers the plan's onboarding fee (an upgrade pays only the difference) plus its operational balance; otherwise the plan is recorded as requested and activates on the funding credit that closes the gap. Enterprise is agreed with us and cannot be self-selected.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/billing/plan" \  -H "Content-Type: application/json" \  -d '{    "plan": "drift"  }'
{  "object": "billing",  "plan": "drift",  "plan_name": "string",  "plan_status": "pending",  "plan_activated_at": "2019-08-24T14:15:22Z",  "requested_plan": "string",  "requested_plan_name": "string",  "balance_cents": "string",  "onboarding_paid_cents": "string",  "live": {    "ok": true,    "reason": "plan_not_active"  },  "onboarding": {    "steps": [      {        "step": "plan",        "done": true,        "bypassed": true,        "complete": true      }    ],    "bypassed": [      "address"    ],    "skipped_at": "2019-08-24T14:15:22Z",    "can_skip": true,    "remaining": 0  },  "activation": {    "plan": "string",    "plan_name": "string",    "onboarding_due_cents": "string",    "balance_required_cents": "string",    "shortfall_cents": "string"  },  "fees": {    "rate_bps": 0,    "fixed_cents": "string",    "cap_cents": "string",    "address_fee_cents": "string",    "min_monthly_cents": "string"  },  "plans": [    {      "key": "string",      "name": "string",      "onboarding_fee_cents": "string",      "min_monthly_cents": "string",      "operational_balance_cents": "string",      "rate_bps": 0,      "fixed_cents": "string",      "cap_cents": "string",      "negotiated": true    }  ]}

Dismiss the getting-started checklist

POST/v1/billing/onboarding/skip

Hides the four-step panel on your console overview. It is a display preference and grants nothing: the steps after the first — issue an address, take a test payment, go live — were never gates, and the only thing standing between your account and a live payment is an active plan with a positive balance.

Refused with plan_not_active until your plan is on, because until then the panel is the only thing explaining why live invoices are being declined. Idempotent: calling it twice does not move the recorded timestamp.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/v1/billing/onboarding/skip"
{  "object": "billing",  "plan": "drift",  "plan_name": "string",  "plan_status": "pending",  "plan_activated_at": "2019-08-24T14:15:22Z",  "requested_plan": "string",  "requested_plan_name": "string",  "balance_cents": "string",  "onboarding_paid_cents": "string",  "live": {    "ok": true,    "reason": "plan_not_active"  },  "onboarding": {    "steps": [      {        "step": "plan",        "done": true,        "bypassed": true,        "complete": true      }    ],    "bypassed": [      "address"    ],    "skipped_at": "2019-08-24T14:15:22Z",    "can_skip": true,    "remaining": 0  },  "activation": {    "plan": "string",    "plan_name": "string",    "onboarding_due_cents": "string",    "balance_required_cents": "string",    "shortfall_cents": "string"  },  "fees": {    "rate_bps": 0,    "fixed_cents": "string",    "cap_cents": "string",    "address_fee_cents": "string",    "min_monthly_cents": "string"  },  "plans": [    {      "key": "string",      "name": "string",      "onboarding_fee_cents": "string",      "min_monthly_cents": "string",      "operational_balance_cents": "string",      "rate_bps": 0,      "fixed_cents": "string",      "cap_cents": "string",      "negotiated": true    }  ]}

Where to send money to top up

GET/v1/billing/funding

One address per chain, created on first call and stable forever. EVM chains on the MolnPay factory share one address; read the list rather than assuming. Send only the assets listed for that chain; anything else is not credited.

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/billing/funding"
{  "object": "list",  "has_more": true,  "next_cursor": "string",  "data": [    {      "object": "funding_address",      "chain": "ethereum",      "address": "string",      "memo": "string",      "account_kind": "contract",      "assets": [        {          "symbol": "string",          "decimals": 0,          "par": true        }      ]    }  ]}

Your billing ledger, line by line

GET/v1/billing/entries

Authorization

apiKey
AuthorizationBearer <token>

Authorization: Bearer mp<64 hex> for live, mptest<64 hex> for test.

The token is the prefix plus 64 lowercase hex characters (32 CSPRNG bytes) and nothing else — no separators, no embedded fields — so nothing in it needs quoting, escaping or encoding. Send it in the Authorization header and nowhere else. Never put it in a query string: URLs reach access logs, proxy logs, browser history and Referer headers, and a key that lands in any of those is a leaked key. A key's KIND (checkout, payout or wallet) is a property of the key, not of the string: it is chosen at creation, returned by GET /v1/ping, and decides which routes the key may reach.

The full key is shown exactly once, at creation. No endpoint can return it afterwards. Moving funds additionally requires signing to be enabled globally, for your project, and for that key — so a read-only key is a supported configuration.

In: header

Query Parameters

limit?integer
Range1 <= value <= 100
Default25
cursor?string

Opaque cursor from the previous page's next_cursor.

kind?string

Value in

  • "funding"
  • "onboarding_fee"
  • "payment_fee"
  • "address_fee"
  • "payout_fee"
  • "withdrawal_fee"
  • "monthly_minimum"
  • "refund"
  • "adjustment"
  • "conversion_fee"

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/v1/billing/entries"
{  "object": "list",  "has_more": true,  "next_cursor": "string",  "data": [    {      "object": "billing_entry",      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "kind": "funding",      "amount_cents": "string",      "ref_type": "string",      "ref_id": "string",      "chain": "string",      "asset": "string",      "amount_atomic": "string",      "rate": "string",      "rate_source": "string",      "note": "string",      "created_at": "2019-08-24T14:15:22Z",      "transfer": {        "amount_decimal": "string",        "tx_hash": "string",        "explorer_url": "string",        "from_address": "string",        "confirmations": 0,        "required_confirmations": 0,        "status": "detected",        "block_time": "2019-08-24T14:15:22Z"      }    }  ]}

Checkout

Previous Page

Conversions

Next Page