riverArk API Documentation

Postman collection → OpenAPI spec →

Introduction

API for managing your account programmatically.

Welcome to the riverArk API documentation. This API allows you to programmatically create, retrieve, list, and cancel invoices.

## Authentication

This API uses **Bearer Access Tokens** for authentication. You need to generate an API token from the web dashboard at `/api-keys`.

### Token Format

Tokens contain 16 lowercase letters, excluding the ambiguous letters `i`, `l`, and `o`.

Example: `vrcmhtwqaxfnszke`

### Using Your Token

Include your token in the `Authorization` header of each request:

```
Authorization: Bearer {apiKey}
```

### Token Abilities

Each token has specific abilities that control what actions it can perform:

- **`list-invoice`**: List all your invoices
- **`view-invoice`**: View details of a specific invoice
- **`create-invoice`**: Create new invoices
- **`cancel-invoice`**: Cancel existing invoices

You can assign multiple abilities to a single token. Attempting to access an endpoint without the required ability will result in a `403 Forbidden` response.

## API Versions

- **v1** (`/api/v1`): The original invoice API. Invoices are created at the requested item prices and dynamic pricing is never applied.
- **v2** (`/api/v2`): The same endpoints as v1 with dynamic pricing support. To migrate, change only the base URL from `/api/v1` to `/api/v2`; every endpoint, request and the rate limits stay the same.

Trade numbers are globally unique across versions. A trade number can only be replayed through the API version that created it; replaying it through a different version returns a `409 Conflict`. Invoices can be listed, viewed, checked and cancelled through either version.

## Dynamic Pricing

Dynamic pricing is a signed whole percentage configured on your account (Settings > Merchant Account) and optionally overridden per API key when the key is created. A negative value is a **Bitcoin Discount** and a positive value is a **Conversion Protection** surcharge; `0` means standard pricing.

Invoices created through `POST /api/v2/invoices` apply the API key's dynamic pricing when set, otherwise the account's dynamic pricing, to every invoice item. v2 responses keep `total` as the sum of the original item amounts and add the applied `dynamic_pricing` details, each item's `dynamic_pricing_amount` and `final_amount`, and the `final_total` the customer is invoiced for.

<aside>As you scroll, you'll see code examples for working with the API in different programming languages in the dark area to the right (or as part of the content on mobile).
You can switch the language used with the tabs at the top right (or from the nav menu at the top left on mobile).</aside>

Authenticating requests

To authenticate requests, include an Authorization header with the value "Bearer {YOUR_API_KEY}".

All authenticated endpoints are marked with a requires authentication badge in the documentation below.

You can retrieve your API token by visiting the web dashboard at /api-keys page and creating a new token with the appropriate abilities.

Default API Rate Limit is 60 Requests per Minute, however the "View invoice status" endpoint allows up to max 600 request per minute.

System

System health and connectivity endpoints.

v1


Ping the API

GET
https://ark.riverark.io
/api/v1/ping
requires authentication

Returns a simple pong response along with the authenticated token's abilities. Useful for testing API connectivity and token permissions.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://ark.riverark.io/api/v1/ping" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "pong",
    "abilities": [
        "View Invoice",
        "Create Invoice"
    ]
}
{
    "message": "Unauthenticated."
}

v2


Ping the API

GET
https://ark.riverark.io
/api/v2/ping
requires authentication

Returns a simple pong response along with the authenticated token's abilities. Useful for testing API connectivity and token permissions.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json
Example request: 
curl --request GET \
    --get "https://ark.riverark.io/api/v2/ping" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "pong",
    "abilities": [
        "View Invoice",
        "Create Invoice"
    ]
}
{
    "message": "Unauthenticated."
}

Invoice Management

APIs for managing invoices. All endpoints require authentication via Sanctum bearer token and specific token abilities as noted on each endpoint.

v1

The original invoice API. Invoices are created at the requested item prices and dynamic pricing is never applied.


List all invoices

GET
https://ark.riverark.io
/api/v1/invoices
requires authentication

Returns a paginated list of all invoices belonging to the authenticated user.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

page
integer

Page number for pagination.

Example:
1
per_page
integer

Number of items per page (default: 15, max: 100).

Example:
15
Example request: 
curl --request GET \
    --get "https://ark.riverark.io/api/v1/invoices?page=1&per_page=15" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "data": [
        {
            "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
            "provider": "strike",
            "provider_account_username": "accountusername",
            "provider_invoice_id": "0604cf8d-b22f-4d07-b30b-baf7d205e197",
            "machine_id": "VVM-005",
            "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
            "currency": "USD",
            "total": "1.00000000",
            "status": "paid",
            "status_label": "Paid",
            "status_reason": null,
            "status_version": 1,
            "status_updated_at": "2025-10-31T04:24:43+00:00",
            "items": [
                {
                    "reference": "7f6914a8-4809-4050-86cf-cd966a40faf9",
                    "description": "Soda",
                    "amount": "1.00000000",
                    "created_at": "2025-10-27T20:12:23+00:00"
                }
            ],
            "payment": {
                "amount": "0.00001534",
                "currency": "BTC",
                "status": "PAID",
                "status_label": "Paid",
                "completed_at": "2025-10-31T04:24:43+00:00"
            },
            "created_at": "2025-10-27T20:12:23+00:00",
            "updated_at": "2025-10-27T20:13:10+00:00"
        }
    ],
    "links": {
        "first": "http://example.com/api/v1/invoices?page=1",
        "last": "http://example.com/api/v1/invoices?page=3",
        "prev": null,
        "next": "http://example.com/api/v1/invoices?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "per_page": 15,
        "to": 15,
        "total": 42
    }
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}

Create a new invoice

POST
https://ark.riverark.io
/api/v1/invoices
requires authentication

Creates a new invoice with the provided items (1 to 10). The total is automatically calculated from the sum of all item amounts.

The trade number is a globally unique idempotency key shared across API versions. A replay of an identical payload by the owning account returns the complete current invoice (200) without any upstream interaction. Reusing the key with different business details, or with a trade number created through the v2 API, conflicts (409) and preserves the original invoice. Concurrent requests with the same trade number elect a single creator; the losers wait for the creator to finish and then replay. When creation outlives the wait window, the loser receives an explicitly retryable 503 whose Retry-After header and retry_after_seconds field bound the remaining creator time.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://ark.riverark.io/api/v1/invoices" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"machine_id\": \"MACHINE-001\",
    \"trade_no\": \"TRADE-20251024-001\",
    \"currency\": \"USD\",
    \"items\": [
        {
            \"description\": \"Small Coke Can\",
            \"amount\": 1
        }
    ]
}"
Example response:
{
    "data": {
        "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
        "provider": "strike",
        "provider_account_username": "accountusername",
        "provider_invoice_id": "0604cf8d-b22f-4d07-b30b-baf7d205e197",
        "machine_id": "VVM-005",
        "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
        "currency": "USD",
        "total": "1.00000000",
        "status": "paid",
        "status_label": "Paid",
        "status_version": 1,
        "items": [],
        "payment": null,
        "metadata": {
            "bolt11_invoice": "lnbc16090n1p48lvw8pp5qsr2r59gaa0j9l2njfwup9sv7v2gyzs63agwdz9s5hd0kq9geh9sdq523jhxapqd9h8vmmfvdjscqzzsxqzp6sp59g87jjdr553a8spz36ehaw6ds9cf9amt3hrqhtj6gc0cefjaqazq9qxpqysgqgjcdfqjyfgymjn760jfc4fsnkzf33lwvpcypafe30muwjwrn479h8kfelm4f4z7f6lzgu6t2jzlsg8r07rx3hzfr25mgefyue92aa6sqvk6wyr",
            "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
            "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
            "quote_expiration_in_sec": 58,
            "settlement_currency": "USD"
        }
    }
}
{
    "data": {
        "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
        "provider": "strike",
        "provider_account_username": "accountusername",
        "provider_invoice_id": "0604cf8d-b22f-4d07-b30b-baf7d205e197",
        "machine_id": "VVM-005",
        "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
        "currency": "USD",
        "total": "1.00000000",
        "status": "pending",
        "status_label": "Pending",
        "status_reason": null,
        "status_version": 0,
        "status_updated_at": null,
        "items": [
            {
                "reference": "7f6914a8-4809-4050-86cf-cd966a40faf9",
                "description": "Soda",
                "amount": "1.00000000",
                "created_at": "2025-10-27T20:12:23+00:00"
            }
        ],
        "payment": null,
        "metadata": {
            "bolt11_invoice": "lnbc16090n1p48lvw8pp5qsr2r59gaa0j9l2njfwup9sv7v2gyzs63agwdz9s5hd0kq9geh9sdq523jhxapqd9h8vmmfvdjscqzzsxqzp6sp59g87jjdr553a8spz36ehaw6ds9cf9amt3hrqhtj6gc0cefjaqazq9qxpqysgqgjcdfqjyfgymjn760jfc4fsnkzf33lwvpcypafe30muwjwrn479h8kfelm4f4z7f6lzgu6t2jzlsg8r07rx3hzfr25mgefyue92aa6sqvk6wyr",
            "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
            "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
            "quote_expiration_in_sec": 58,
            "settlement_currency": "USD"
        },
        "created_at": "2025-10-27T20:12:23+00:00",
        "updated_at": "2025-10-27T20:13:10+00:00"
    }
}
{
    "message": "Merchant account is not configured. Please set up your merchant account before creating invoices."
}
{
    "message": "Unauthenticated."
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Invoice creation outcome is unknown. Please contact support with this reference.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "outcome": "CREATE_UNKNOWN"
}
{
    "message": "This trade number has already been used with different invoice details.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306"
}
{
    "message": "This trade number has already been used through a different API version.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306"
}
{
    "message": "This trade number is not available."
}
{
    "message": "Invoice creation outcome is unknown. Please contact support with this reference.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "outcome": "CREATE_UNKNOWN"
}
{
    "message": "The machine ID is required. (and 3 more errors)",
    "errors": {
        "machine_id": [
            "The machine ID is required."
        ],
        "trade_no": [
            "The trade number is required."
        ],
        "currency": [
            "The currency is required."
        ],
        "items": [
            "At least one invoice item is required."
        ]
    }
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}
{
    "message": "Invoice created upstream but could not be persisted. Please contact support with this reference.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "outcome": "CREATE_UNKNOWN"
}
{
    "message": "Upstream invoice service returned incomplete invoice metadata (settlement_currency).",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306"
}
{
    "message": "Invoice creation outcome is unknown. Please retry.",
    "retry_after_seconds": 1
}
{
    "message": "An invoice with this trade number is currently being created. Please retry.",
    "retry_after_seconds": 25
}

View a specific invoice

GET
https://ark.riverark.io
/api/v1/invoices/{reference}
requires authentication

Returns details of a specific invoice by its reference UUID.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

reference
string
required

The invoice reference UUID.

Example:
9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a
Example request: 
curl --request GET \
    --get "https://ark.riverark.io/api/v1/invoices/9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "data": {
        "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
        "provider": "strike",
        "provider_account_username": "accountusername",
        "provider_invoice_id": "0604cf8d-b22f-4d07-b30b-baf7d205e197",
        "machine_id": "VVM-005",
        "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
        "currency": "USD",
        "total": "1.00000000",
        "status": "paid",
        "status_label": "Paid",
        "status_reason": null,
        "status_version": 1,
        "status_updated_at": "2025-10-31T04:24:43+00:00",
        "items": [
            {
                "reference": "7f6914a8-4809-4050-86cf-cd966a40faf9",
                "description": "Soda",
                "amount": "1.00000000",
                "created_at": "2025-10-27T20:12:23+00:00"
            }
        ],
        "payment": {
            "amount": "0.00001534",
            "currency": "BTC",
            "status": "PAID",
            "status_label": "Paid",
            "completed_at": "2025-10-31T04:24:43+00:00"
        },
        "metadata": {
            "bolt11_invoice": "lnbc16090n1p48lvw8pp5qsr2r59gaa0j9l2njfwup9sv7v2gyzs63agwdz9s5hd0kq9geh9sdq523jhxapqd9h8vmmfvdjscqzzsxqzp6sp59g87jjdr553a8spz36ehaw6ds9cf9amt3hrqhtj6gc0cefjaqazq9qxpqysgqgjcdfqjyfgymjn760jfc4fsnkzf33lwvpcypafe30muwjwrn479h8kfelm4f4z7f6lzgu6t2jzlsg8r07rx3hzfr25mgefyue92aa6sqvk6wyr",
            "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
            "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
            "quote_expiration_in_sec": 58,
            "settlement_currency": "USD"
        },
        "created_at": "2025-10-27T20:12:23+00:00",
        "updated_at": "2025-10-27T20:13:10+00:00"
    }
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Invoice not found."
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}

Cancel an invoice

DELETE
https://ark.riverark.io
/api/v1/invoices/{reference}
requires authentication

Cancels an invoice and returns its definitive current state. This action is idempotent: cancelling an already-cancelled invoice returns the cancelled state without side effects, and cancelling a paid invoice is rejected with 409 and the paid payment evidence. Cancelled invoices remain queryable via the detail and status endpoints.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

reference
string
required

The invoice reference UUID.

Example:
9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a
Example request: 
curl --request DELETE \
    "https://ark.riverark.io/api/v1/invoices/9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "Invoice cancelled successfully.",
    "status": "cancelled",
    "status_label": "Cancelled",
    "status_version": 1,
    "status_updated_at": "2025-10-27T20:13:10+00:00",
    "payment": null
}
{
    "message": "Invoice cancelled successfully.",
    "status": "cancelled",
    "status_label": "Cancelled",
    "status_version": 1,
    "status_updated_at": "2025-10-27T20:13:10+00:00",
    "payment": null
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Invoice not found."
}
{
    "message": "Invoice cannot be cancelled because it has already been paid.",
    "status": "paid",
    "status_label": "Paid",
    "status_version": 1,
    "status_updated_at": "2025-10-31T04:24:43+00:00",
    "payment": {
        "amount": "0.00001534",
        "currency": "BTC",
        "status": "PAID",
        "status_label": "Paid",
        "completed_at": "2025-10-31T04:24:43+00:00"
    }
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}

View invoice status

GET
https://ark.riverark.io
/api/v1/invoices/{reference}/status
requires authentication

Returns the authoritative status for a specific invoice by its reference UUID. The payload includes stable invoice identity (the RiverArk reference and the client-supplied trade number, which clients must match before accepting a status transition), a monotonic status_version that increments on every applied status transition, the immutable upstream quote details, and payment evidence when a payment event has been processed. payment.completed_at is the instant the complete required amount was irrevocably accepted, as reported by the provider's paid event.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

reference
string
required

The invoice reference UUID.

Example:
9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a
Example request: 
curl --request GET \
    --get "https://ark.riverark.io/api/v1/invoices/9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a/status" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
    "status": "pending",
    "status_label": "Pending",
    "status_version": 0,
    "status_updated_at": null,
    "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
    "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
    "payment": null
}
{
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
    "status": "paid",
    "status_label": "Paid",
    "status_version": 1,
    "status_updated_at": "2025-10-31T04:24:43+00:00",
    "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
    "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
    "payment": {
        "amount": "0.00001534",
        "currency": "BTC",
        "status": "PAID",
        "status_label": "Paid",
        "completed_at": "2025-10-31T04:24:43+00:00"
    }
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Invoice not found."
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}

v2

Every v1 endpoint with dynamic pricing support. The dynamic pricing configured on the API key, or on the account when the API key has none, is applied to every invoice created.


List all invoices

GET
https://ark.riverark.io
/api/v2/invoices
requires authentication

Returns a paginated list of all invoices belonging to the authenticated user.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Query Parameters

page
integer

Page number for pagination.

Example:
1
per_page
integer

Number of items per page (default: 15, max: 100).

Example:
15
Example request: 
curl --request GET \
    --get "https://ark.riverark.io/api/v2/invoices?page=1&per_page=15" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "data": [
        {
            "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
            "provider": "strike",
            "provider_account_username": "accountusername",
            "provider_invoice_id": "0604cf8d-b22f-4d07-b30b-baf7d205e197",
            "machine_id": "VVM-005",
            "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
            "currency": "USD",
            "total": "1.00000000",
            "dynamic_pricing": {
                "type": "discount",
                "type_label": "Bitcoin Discount",
                "percentage": -2,
                "source": "account",
                "amount": "-0.02000000"
            },
            "final_total": "0.98000000",
            "status": "paid",
            "status_label": "Paid",
            "status_reason": null,
            "status_version": 1,
            "status_updated_at": "2025-10-31T04:24:43+00:00",
            "items": [
                {
                    "reference": "7f6914a8-4809-4050-86cf-cd966a40faf9",
                    "description": "Soda",
                    "amount": "1.00000000",
                    "dynamic_pricing_amount": "-0.02000000",
                    "final_amount": "0.98000000",
                    "created_at": "2025-10-27T20:12:23+00:00"
                }
            ],
            "payment": {
                "amount": "0.00001534",
                "currency": "BTC",
                "status": "PAID",
                "status_label": "Paid",
                "completed_at": "2025-10-31T04:24:43+00:00"
            },
            "created_at": "2025-10-27T20:12:23+00:00",
            "updated_at": "2025-10-27T20:13:10+00:00"
        }
    ],
    "links": {
        "first": "http://example.com/api/v2/invoices?page=1",
        "last": "http://example.com/api/v2/invoices?page=3",
        "prev": null,
        "next": "http://example.com/api/v2/invoices?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "last_page": 3,
        "per_page": 15,
        "to": 15,
        "total": 42
    }
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}

Create a new invoice

POST
https://ark.riverark.io
/api/v2/invoices
requires authentication

Creates a new invoice with the provided items (1 to 10). The total is automatically calculated from the sum of all item amounts.

Dynamic pricing is applied per line item: the API key's dynamic pricing is used when set, otherwise the account's dynamic pricing applies. A negative percentage is a discount and a positive percentage is a surcharge. Each item carries its signed dynamic_pricing_amount and final_amount, and the invoice carries the applied dynamic_pricing snapshot and the final_total the customer is invoiced for. The total always remains the sum of the original item amounts.

The trade number is a globally unique idempotency key shared across API versions. A replay of an identical payload by the owning account returns the complete current invoice (200) without any upstream interaction. Reusing the key with different business details, or with a trade number created through the v1 API, conflicts (409) and preserves the original invoice. Concurrent requests with the same trade number elect a single creator; the losers wait for the creator to finish and then replay. When creation outlives the wait window, the loser receives an explicitly retryable 503 whose Retry-After header and retry_after_seconds field bound the remaining creator time.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

Body Parameters

Example request: 
curl --request POST \
    "https://ark.riverark.io/api/v2/invoices" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json" \
    --data "{
    \"machine_id\": \"MACHINE-001\",
    \"trade_no\": \"TRADE-20251024-001\",
    \"currency\": \"USD\",
    \"items\": [
        {
            \"description\": \"Small Coke Can\",
            \"amount\": 1
        }
    ]
}"
Example response:
{
    "data": {
        "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
        "provider": "strike",
        "provider_account_username": "accountusername",
        "provider_invoice_id": "0604cf8d-b22f-4d07-b30b-baf7d205e197",
        "machine_id": "VVM-005",
        "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
        "currency": "USD",
        "total": "1.00000000",
        "dynamic_pricing": {
            "type": "discount",
            "type_label": "Bitcoin Discount",
            "percentage": -2,
            "source": "account",
            "amount": "-0.02000000"
        },
        "final_total": "0.98000000",
        "status": "paid",
        "status_label": "Paid",
        "status_version": 1,
        "items": [],
        "payment": null,
        "metadata": {
            "bolt11_invoice": "lnbc16090n1p48lvw8pp5qsr2r59gaa0j9l2njfwup9sv7v2gyzs63agwdz9s5hd0kq9geh9sdq523jhxapqd9h8vmmfvdjscqzzsxqzp6sp59g87jjdr553a8spz36ehaw6ds9cf9amt3hrqhtj6gc0cefjaqazq9qxpqysgqgjcdfqjyfgymjn760jfc4fsnkzf33lwvpcypafe30muwjwrn479h8kfelm4f4z7f6lzgu6t2jzlsg8r07rx3hzfr25mgefyue92aa6sqvk6wyr",
            "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
            "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
            "quote_expiration_in_sec": 58,
            "settlement_currency": "USD"
        }
    }
}
{
    "data": {
        "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
        "provider": "strike",
        "provider_account_username": "accountusername",
        "provider_invoice_id": "0604cf8d-b22f-4d07-b30b-baf7d205e197",
        "machine_id": "VVM-005",
        "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
        "currency": "USD",
        "total": "1.00000000",
        "dynamic_pricing": {
            "type": "discount",
            "type_label": "Bitcoin Discount",
            "percentage": -2,
            "source": "account",
            "amount": "-0.02000000"
        },
        "final_total": "0.98000000",
        "status": "pending",
        "status_label": "Pending",
        "status_reason": null,
        "status_version": 0,
        "status_updated_at": null,
        "items": [
            {
                "reference": "7f6914a8-4809-4050-86cf-cd966a40faf9",
                "description": "Soda",
                "amount": "1.00000000",
                "dynamic_pricing_amount": "-0.02000000",
                "final_amount": "0.98000000",
                "created_at": "2025-10-27T20:12:23+00:00"
            }
        ],
        "payment": null,
        "metadata": {
            "bolt11_invoice": "lnbc16090n1p48lvw8pp5qsr2r59gaa0j9l2njfwup9sv7v2gyzs63agwdz9s5hd0kq9geh9sdq523jhxapqd9h8vmmfvdjscqzzsxqzp6sp59g87jjdr553a8spz36ehaw6ds9cf9amt3hrqhtj6gc0cefjaqazq9qxpqysgqgjcdfqjyfgymjn760jfc4fsnkzf33lwvpcypafe30muwjwrn479h8kfelm4f4z7f6lzgu6t2jzlsg8r07rx3hzfr25mgefyue92aa6sqvk6wyr",
            "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
            "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
            "quote_expiration_in_sec": 58,
            "settlement_currency": "USD"
        },
        "created_at": "2025-10-27T20:12:23+00:00",
        "updated_at": "2025-10-27T20:13:10+00:00"
    }
}
{
    "message": "Merchant account is not configured. Please set up your merchant account before creating invoices."
}
{
    "message": "Unauthenticated."
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Invoice creation outcome is unknown. Please contact support with this reference.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "outcome": "CREATE_UNKNOWN"
}
{
    "message": "This trade number has already been used with different invoice details.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306"
}
{
    "message": "This trade number has already been used through a different API version.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306"
}
{
    "message": "This trade number is not available."
}
{
    "message": "Invoice creation outcome is unknown. Please contact support with this reference.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "outcome": "CREATE_UNKNOWN"
}
{
    "message": "The machine ID is required. (and 3 more errors)",
    "errors": {
        "machine_id": [
            "The machine ID is required."
        ],
        "trade_no": [
            "The trade number is required."
        ],
        "currency": [
            "The currency is required."
        ],
        "items": [
            "At least one invoice item is required."
        ]
    }
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}
{
    "message": "Invoice created upstream but could not be persisted. Please contact support with this reference.",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "outcome": "CREATE_UNKNOWN"
}
{
    "message": "Upstream invoice service returned incomplete invoice metadata (settlement_currency).",
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306"
}
{
    "message": "Invoice creation outcome is unknown. Please retry.",
    "retry_after_seconds": 1
}
{
    "message": "An invoice with this trade number is currently being created. Please retry.",
    "retry_after_seconds": 25
}

View a specific invoice

GET
https://ark.riverark.io
/api/v2/invoices/{reference}
requires authentication

Returns details of a specific invoice by its reference UUID.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

reference
string
required

The invoice reference UUID.

Example:
9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a
Example request: 
curl --request GET \
    --get "https://ark.riverark.io/api/v2/invoices/9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "data": {
        "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
        "provider": "strike",
        "provider_account_username": "accountusername",
        "provider_invoice_id": "0604cf8d-b22f-4d07-b30b-baf7d205e197",
        "machine_id": "VVM-005",
        "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
        "currency": "USD",
        "total": "1.00000000",
        "dynamic_pricing": {
            "type": "discount",
            "type_label": "Bitcoin Discount",
            "percentage": -2,
            "source": "account",
            "amount": "-0.02000000"
        },
        "final_total": "0.98000000",
        "status": "paid",
        "status_label": "Paid",
        "status_reason": null,
        "status_version": 1,
        "status_updated_at": "2025-10-31T04:24:43+00:00",
        "items": [
            {
                "reference": "7f6914a8-4809-4050-86cf-cd966a40faf9",
                "description": "Soda",
                "amount": "1.00000000",
                "dynamic_pricing_amount": "-0.02000000",
                "final_amount": "0.98000000",
                "created_at": "2025-10-27T20:12:23+00:00"
            }
        ],
        "payment": {
            "amount": "0.00001534",
            "currency": "BTC",
            "status": "PAID",
            "status_label": "Paid",
            "completed_at": "2025-10-31T04:24:43+00:00"
        },
        "metadata": {
            "bolt11_invoice": "lnbc16090n1p48lvw8pp5qsr2r59gaa0j9l2njfwup9sv7v2gyzs63agwdz9s5hd0kq9geh9sdq523jhxapqd9h8vmmfvdjscqzzsxqzp6sp59g87jjdr553a8spz36ehaw6ds9cf9amt3hrqhtj6gc0cefjaqazq9qxpqysgqgjcdfqjyfgymjn760jfc4fsnkzf33lwvpcypafe30muwjwrn479h8kfelm4f4z7f6lzgu6t2jzlsg8r07rx3hzfr25mgefyue92aa6sqvk6wyr",
            "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
            "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
            "quote_expiration_in_sec": 58,
            "settlement_currency": "USD"
        },
        "created_at": "2025-10-27T20:12:23+00:00",
        "updated_at": "2025-10-27T20:13:10+00:00"
    }
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Invoice not found."
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}

Cancel an invoice

DELETE
https://ark.riverark.io
/api/v2/invoices/{reference}
requires authentication

Cancels an invoice and returns its definitive current state. This action is idempotent: cancelling an already-cancelled invoice returns the cancelled state without side effects, and cancelling a paid invoice is rejected with 409 and the paid payment evidence. Cancelled invoices remain queryable via the detail and status endpoints.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

reference
string
required

The invoice reference UUID.

Example:
9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a
Example request: 
curl --request DELETE \
    "https://ark.riverark.io/api/v2/invoices/9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "Invoice cancelled successfully.",
    "status": "cancelled",
    "status_label": "Cancelled",
    "status_version": 1,
    "status_updated_at": "2025-10-27T20:13:10+00:00",
    "payment": null
}
{
    "message": "Invoice cancelled successfully.",
    "status": "cancelled",
    "status_label": "Cancelled",
    "status_version": 1,
    "status_updated_at": "2025-10-27T20:13:10+00:00",
    "payment": null
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Invoice not found."
}
{
    "message": "Invoice cannot be cancelled because it has already been paid.",
    "status": "paid",
    "status_label": "Paid",
    "status_version": 1,
    "status_updated_at": "2025-10-31T04:24:43+00:00",
    "payment": {
        "amount": "0.00001534",
        "currency": "BTC",
        "status": "PAID",
        "status_label": "Paid",
        "completed_at": "2025-10-31T04:24:43+00:00"
    }
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}

View invoice status

GET
https://ark.riverark.io
/api/v2/invoices/{reference}/status
requires authentication

Returns the authoritative status for a specific invoice by its reference UUID. The payload includes stable invoice identity (the RiverArk reference and the client-supplied trade number, which clients must match before accepting a status transition), a monotonic status_version that increments on every applied status transition, the immutable upstream quote details, and payment evidence when a payment event has been processed. payment.completed_at is the instant the complete required amount was irrevocably accepted, as reported by the provider's paid event.

Headers

Authorization
Example:
Bearer {YOUR_API_KEY}
Content-Type
Example:
application/json
Accept
Example:
application/json

URL Parameters

reference
string
required

The invoice reference UUID.

Example:
9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a
Example request: 
curl --request GET \
    --get "https://ark.riverark.io/api/v2/invoices/9d8e7f6a-5b4c-3d2e-1f0a-9b8c7d6e5f4a/status" \
    --header "Authorization: Bearer {YOUR_API_KEY}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
    "status": "pending",
    "status_label": "Pending",
    "status_version": 0,
    "status_updated_at": null,
    "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
    "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
    "payment": null
}
{
    "reference": "453ac6e9-19d9-4a1a-b904-6bb52c85c306",
    "trade_no": "TRADE-UEI560RJIX5ZV1TYFHOK",
    "status": "paid",
    "status_label": "Paid",
    "status_version": 1,
    "status_updated_at": "2025-10-31T04:24:43+00:00",
    "quote_id": "d3511557-18ef-4bdb-83a6-a8d94da9e0f4",
    "quote_expiration": "2026-08-15T00:25:38.401427+00:00",
    "payment": {
        "amount": "0.00001534",
        "currency": "BTC",
        "status": "PAID",
        "status_label": "Paid",
        "completed_at": "2025-10-31T04:24:43+00:00"
    }
}
{
    "message": "Unauthenticated."
}
{
    "message": "This action is unauthorized."
}
{
    "message": "Invoice not found."
}
{
    "message": "Too many requests. Please try again later.",
    "retry_after_seconds": 53
}