API reference

Authentication

Every request carries an API key as a bearer token. A key is two parts joined by a single dot — a public key id and a secret — and it is shown once, when you create it in the dashboard. Only a SHA-256 hash of the secret is stored, so a lost key is replaced rather than recovered.

Authorization: Bearer <key_id>.<secret>

• The comparison is constant time, and the hash is computed even for an unknown key id, so response timing does not tell an attacker which key ids are real.
• Revoking a key takes effect on the next request. The record of what it did survives revocation.
• A suspended account is rejected at the same point, even with a valid key.

Rate limits

The merchant API allows 120 requests per minute. The public payer endpoint is separately limited to 60 per minute because it is unauthenticated. Exceeding either returns 429 with a Retry-After header.

Amounts and precision

Every amount in this API is a decimal string, both in and out. A JSON number is a double, and a double cannot hold 0.1 exactly — so a number where a string was expected is rejected rather than silently rounded.

Arithmetic runs at 18 decimal places, wider than any chain supported. An amount must match ^\d+(\.\d+)?$ — no exponent notation, no thousands separators — and must not carry more decimal places than the asset itself: an amount the chain cannot represent can never be paid exactly, so the invoice would sit at partial forever.

Confirmation counts are the shipped defaults and are stored per asset, so an operator can raise them. Check the dashboard for the values on your account.

Create a payment request

Creates a fixed-amount invoice, or an open-amount donation link when type is donation. Each request is given its own freshly derived receive address — that address is what makes an inbound payment attributable to one invoice rather than another.

Body parameters

Request

curl -X POST https://cryptogate.foundrcode.com/api/merchant/v1/payment-requests \
  -H "Authorization: Bearer $CRYPTOGATE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "asset_id": 1,
    "title": "Invoice 1042",
    "amount": "0.0125",
    "reference": "ORD-1042",
    "ttl_minutes": 60,
    "webhook_url": "https://example.com/hooks/cryptogate"
  }'

Response 201

{
  "payment_request": {
    "id": "k3n8qzv2rt7wp1xd9fhs4bmc",
    "type": "invoice",
    "title": "Invoice 1042",
    "description": null,
    "status": "pending",
    "asset": "BTC",
    "chain": "bitcoin",
    "address": "tb1qw508d6qejxtdg4y5r3zarvary0c5xw7kxpjzsx",
    "amount_requested": "0.0125",
    "amount_paid": "0",
    "amount_outstanding": "0.0125",
    "expires_at": "2026-08-05T12:00:00.000000Z",
    "paid_at": null,
    "redirect_url": null,
    "reference": "ORD-1042",
    "webhook_url": "https://example.com/hooks/cryptogate",
    "created_at": "2026-08-05T11:00:00.000000Z"
  }
}

List payment requests

Your requests, newest first, in a standard Laravel paginator envelope. Only your own — the key identifies the account.

curl https://cryptogate.foundrcode.com/api/merchant/v1/payment-requests?per_page=50 \
  -H "Authorization: Bearer $CRYPTOGATE_KEY"

# 200
{
  "data": [ { /* payment request objects */ } ],
  "current_page": 1,
  "per_page": 50,
  "total": 128
}

Retrieve one

id here is the internal numeric identifier, an integer in the path. A request belonging to another account answers 404, not 403: confirming that a record exists is itself a leak.

curl https://cryptogate.foundrcode.com/api/merchant/v1/payment-requests/1042 \
  -H "Authorization: Bearer $CRYPTOGATE_KEY"

# 200
{ "payment_request": { /* as above */ } }

Cancel one

Closes the request so the hosted page stops accepting payment and the public endpoint answers 404. A request that has already settled cannot be cancelled — the money is on chain, and pretending otherwise would be a lie about a real balance. That attempt returns 422.

curl -X POST https://cryptogate.foundrcode.com/api/merchant/v1/payment-requests/1042/cancel \
  -H "Authorization: Bearer $CRYPTOGATE_KEY"

# 200
{ "payment_request": { "status": "cancelled", ... } }

# 422 when it has already settled
{ "message": "A settled request cannot be cancelled." }

The payer view

Unauthenticated, so you can build your own checkout in front of it. The random slug is the capability, which is why slugs are not sequential. The payload deliberately omits the merchant's identity, internal ids and your reference, which may carry order information.

The hosted page at https://cryptogate.foundrcode.com/pay/{slug} is the same data rendered for a human. A cancelled or unknown slug answers 404 from both.

The payment request object

The last three fields are returned to an authenticated merchant only; the public payer endpoint stops at redirect_url.

Errors

Errors are JSON with a message. Validation failures add an errors object keyed by field. Send Accept: application/json so a validation failure is never answered with a redirect.

{
  "message": "Invalid API credentials."
}

{
  "message": "The amount field format is invalid.",
  "errors": {
    "amount": ["The amount field format is invalid."],
    "asset_id": ["The selected asset id is invalid."]
  }
}

{
  "message": "Too Many Attempts."
}

{
  "message": "Not found."
}