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 are in the format: `{tokenId}|{plainTextToken}`

Example: `1|AbCdEfGhIjKlMnOpQrStUvWxYz1234567890`

### Using Your Token

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

```
Authorization: Bearer {tokenId}|{plainTextToken}
```

### 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.

<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_TOKEN_ID}|{YOUR_TOKEN_SECRET}".

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.

Invoice Management

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

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_TOKEN_ID}|{YOUR_TOKEN_SECRET}
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_TOKEN_ID}|{YOUR_TOKEN_SECRET}" \
    --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. 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 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_TOKEN_ID}|{YOUR_TOKEN_SECRET}
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_TOKEN_ID}|{YOUR_TOKEN_SECRET}" \
    --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 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_TOKEN_ID}|{YOUR_TOKEN_SECRET}
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_TOKEN_ID}|{YOUR_TOKEN_SECRET}" \
    --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_TOKEN_ID}|{YOUR_TOKEN_SECRET}
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_TOKEN_ID}|{YOUR_TOKEN_SECRET}" \
    --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_TOKEN_ID}|{YOUR_TOKEN_SECRET}
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_TOKEN_ID}|{YOUR_TOKEN_SECRET}" \
    --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
}

System

System health and connectivity endpoints.

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_TOKEN_ID}|{YOUR_TOKEN_SECRET}
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_TOKEN_ID}|{YOUR_TOKEN_SECRET}" \
    --header "Content-Type: application/json" \
    --header "Accept: application/json"
Example response:
{
    "message": "pong",
    "abilities": [
        "View Invoice",
        "Create Invoice"
    ]
}
{
    "message": "Unauthenticated."
}