Create an Invoice

Create a merchant crypto POS invoice

Endpoint

POST {BASE_URL}/crypto/v1/createInvoice

Create invoice

post

Creates a new merchant invoice and returns an invoice id and hosted payment URL.

Runtime caveat: this endpoint currently enforces exact content-type: application/json.

Header parameters

apikeystringRequired

Merchant API key.

merchantidstringRequired

Merchant identifier bound to the API key.

content-typeconst: application/jsonRequired

Runtime currently requires exact value application/json.

Body

application/json

amountnumber · min: 0.05Required

descriptionstring · max: 250Optional

partialPaymentsEnabledbooleanOptionalDefault: false

tippingEnabledbooleanOptionalDefault: true

btcOnlybooleanOptional

dueDateone ofOptional

string · date-timeOptional

or

numberOptional

Other propertiesanyOptional

Responses

200

Invoice created

application/json

400

Bad request

application/json

401

Missing body (legacy guard)

application/json

403

Missing API key or merchant ID header

application/json

405

Invalid content-type, merchantid, or API key

application/json

408

Non-matching merchantid and API key

application/json

412

Merchant is not actively enrolled in cryptoPOS-V1

application/json

420

Invoice object creation failure

application/json

501

Server error validating merchant/API key

application/json

502

Merkle validation failure

application/json

post

/crypto/v1/createInvoice

HTTPcURLJavaScriptPython

POST /crypto/v1/createInvoice HTTP/1.1
Host: api.example.com
apikey: text
merchantid: text
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "amount": 23.1
}

minimalfull

{
  "success": true,
  "id": "text",
  "paymentURL": "text",
  "details": {
    "subtotal": 1,
    "total": 1,
    "currency": "text"
  }
}

Required Headers

Header	Required	Type	Value
content-type	Yes	String	application/json
apikey	Yes	String	Merchant API key
merchantid	Yes	String	Merchant identifier

Request Body

Field	Required	Type	Notes
amount	Yes	Number	Must be >= 0.05
client.name	No	String	Max 50 chars
client.email	No	String	Email format, max 100 chars
client.phone	No	String	Max 25 chars
client.referenceID	No	String	Max 25 chars
client.cryptoAddress	No	String	Accepted by validator
description	No	String	Max 250 chars
partialPaymentsEnabled	No	Boolean	Defaults to false
tippingEnabled	No	Boolean	Defaults to true
btcOnly	No	Boolean	If true, invoice is BTC-only in widget flow
dueDate	No	Date/String	Accepted by validator as date-like input

Minimal Request Example

{
  "amount": 23.10
}

Full Request Example

{
  "client": {
    "name": "First Last",
    "email": "[email protected]",
    "phone": "[phone]",
    "referenceID": "order-10001",
    "cryptoAddress": "0x1234567890abcdef1234567890abcdef12345678"
  },
  "amount": 23.10,
  "description": "Invoice #10001",
  "partialPaymentsEnabled": true,
  "tippingEnabled": true,
  "btcOnly": false,
  "dueDate": "2026-03-01T00:00:00.000Z"
}

Success Response (200)

{
  "success": true,
  "id": "66da1bc34f03a871430c1a71",
  "paymentURL": "https://crypto-pay.ibanera.com/crypto/v1/66da1bc34f03a871430c1a71",
  "details": {
    "subtotal": 23.1,
    "total": 23.1,
    "currency": "USDC"
  }
}

After creating an invoice, send customers to the returned paymentURL to complete payment in the hosted widget.

Hosted widget landing page opened from `paymentURL`

Error Statuses

Status	Meaning
400	Validation or persistence failure
401	Missing request body (legacy guard)
403	Missing apikey or merchantid
405	Invalid content-type, invalid merchant ID, or invalid API key
408	API key and merchant mismatch
412	Merchant not actively enrolled in cryptoPOS-V1
420	Invoice object creation failure
501	Credential validation server error
502	Merkle validation/generation failure

Notes

• Runtime currently uses partialPaymentsEnabled (not partialPayments) as the canonical request field.

• Returned paymentURL is built from deployment configuration.

• See Known Caveats and Legacy Behavior for behavior details and compatibility notes.