Payments API Reference

Complete reference for the Payments API endpoints (payment links, transactions, networks, and tokens).

Base URL

https://api.orcarail.com/api/v1

Payment Links

Create a Payment Link

Create a new payment link.

POST /payments/links

Authentication

• Bearer Token (JWT) - Required

Request Body

Parameter	Type	Required	Description
title	string	Yes	Title for the payment link
amount	string	Yes	Amount (e.g., "0.1")
tokenId	string	Yes	Token ID (UUID)
networkId	string	Yes	Network ID (UUID)
expiresAt	string	No	ISO 8601 expiration timestamp
metadata	object	No	Custom metadata

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

List User Payment Links

List all payment links for the authenticated user.

GET /payments/links

Authentication

• Bearer Token (JWT) - Required

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "title": "Payment for services",
    "slug": "pl_abc123",
    "amount": "0.1",
    "tokenId": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "status": "active",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

Get Payment Link by Slug

Get a payment link by its slug (public, no auth required).

GET /payments/links/:slug

Path Parameters

Parameter	Type	Required	Description
slug	string	Yes	Payment link slug (e.g., pl_abc123)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Payment for services",
  "slug": "pl_abc123",
  "amount": "0.1",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "metadata": {},
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Update a Payment Link

Update an existing payment link.

PATCH /payments/links/:id

Authentication

• Bearer Token (JWT) - Required

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Payment link ID (UUID)

Request Body

All fields are optional.

Parameter	Type	Required	Description
title	string	No	Updated title
amount	string	No	Updated amount
tokenId	string	No	Updated token ID (UUID)
networkId	string	No	Updated network ID (UUID)
status	string	No	Status: active, inactive, etc.
expiresAt	string	No	Updated expiration (ISO 8601)
metadata	object	No	Updated metadata

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "title": "Updated title",
  "slug": "pl_abc123",
  "amount": "0.2",
  "tokenId": "550e8400-e29b-41d4-a716-446655440001",
  "networkId": "550e8400-e29b-41d4-a716-446655440002",
  "status": "active",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Delete a Payment Link

Delete a payment link.

DELETE /payments/links/:id

Authentication

• Bearer Token (JWT) - Required

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Payment link ID (UUID)

Response

204 No Content

Quote

Get Quote

Get a quote for a payment link with optional payer token/network and support fee. For hosted platform pricing (per transaction and free tier), see Fees & limits overview. For how quote line items (support, commission, bridge) and minimums are applied and returned, see Fees & limits.

POST /payments/links/:slug/quote

Path Parameters

Parameter	Type	Required	Description
slug	string	Yes	Payment link slug

Request Body

All fields are optional.

Parameter	Type	Required	Description
payerTokenId	string	No	Token ID (UUID) payer wants to pay with
payerNetworkId	string	No	Network ID (UUID) payer wants to pay on
supportPercent	number	No	Support fee percent (e.g., 0.1 for 0.1%)

Response

{
  "originalAmount": "100.00",
  "supportPercent": "0.1",
  "supportAmount": "0.1",
  "originalTokenSymbol": "USDC",
  "payerTokenSymbol": "USDT",
  "bridgeFee": "0.001",
  "bridgeFeeUsd": "0.25",
  "bridgeFeeInPayerToken": "0.0001",
  "originalAmountInPayerToken": "1.0",
  "totalAmount": "100.0001",
  "requiresBridge": true,
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "payerNetworkName": "Ethereum",
  "payerNetwork": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "blockExplorerUrl": "https://etherscan.io",
    "publicRpcUrls": ["https://eth.llamarpc.com"],
    "isActive": true,
    "isTestnet": false,
    "listenerConfig": null,
    "requiredConfirmations": 12,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  },
  "payerToken": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "symbol": "USDT",
    "name": "Tether USD",
    "contractAddress": "0x...",
    "decimals": 6,
    "isNative": false,
    "isStablecoin": true,
    "isActive": true,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
}

payerNetwork and payerToken are full objects (see List Networks and List Tokens by Network for field descriptions).

Transactions

Create Transaction

Create a new transaction for a payment link.

POST /payments/links/:slug/transactions

Path Parameters

Parameter	Type	Required	Description
slug	string	Yes	Payment link slug

Request Body

All fields are optional.

Parameter	Type	Required	Description
payerTokenId	string	No	Token ID (UUID) payer wants to pay with
payerNetworkId	string	No	Network ID (UUID) payer wants to pay on
supportPercent	number	No	Support fee percent (e.g., 0.1)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "supportPercent": 0.1,
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Get Transaction by ID

Get a transaction by ID.

GET /payments/transactions/:id

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Transaction ID (UUID)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "completed",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "supportPercent": 0.1,
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T01:00:00.000Z"
}

List User Transactions

List all transactions for the authenticated user.

GET /payments/transactions

Authentication

• Bearer Token (JWT) - Required

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440003",
    "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
    "amount": "0.1",
    "status": "completed",
    "createdAt": "2024-01-01T00:00:00.000Z"
  }
]

Get Transaction with Full Payer Info

Get a transaction with full payer network and token details.

GET /payments/transactions/:id/full

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Transaction ID (UUID)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "completed",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440001",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440002",
  "payerToken": {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "symbol": "USDC",
    "decimals": 6,
    "contractAddress": "0x..."
  },
  "payerNetwork": {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "publicRpcUrls": ["https://eth.llamarpc.com"]
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Update Transaction Payer

Update the payer token and network for a transaction.

PATCH /payments/transactions/:id/payer

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Transaction ID (UUID)

Request Body

Parameter	Type	Required	Description
payerTokenId	string	Yes	Token ID (UUID) payer wants to pay with
payerNetworkId	string	Yes	Network ID (UUID) payer wants to pay on

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "payerTokenId": "550e8400-e29b-41d4-a716-446655440004",
  "payerNetworkId": "550e8400-e29b-41d4-a716-446655440005",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Update Transaction Support

Update the support fee percent for a transaction.

PATCH /payments/transactions/:id/support

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Transaction ID (UUID)

Request Body

Parameter	Type	Required	Description
supportPercent	number	Yes	Support fee percent (e.g., 0.1 for 0.1%)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440003",
  "paymentLinkId": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "0.1",
  "status": "pending",
  "supportPercent": 0.2,
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Networks and Tokens

List Networks

List all supported networks.

GET /payments/networks

Query Parameters

Parameter	Type	Required	Description
active	string	No	Set to true to return only active networks
testnet	string	No	true = testnets only (sandbox), false = mainnets only (live). Omit for all

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440002",
    "name": "Ethereum",
    "chainId": 1,
    "blockExplorerUrl": "https://etherscan.io",
    "publicRpcUrls": ["https://eth.llamarpc.com"],
    "isActive": true,
    "isTestnet": false,
    "listenerConfig": null,
    "requiredConfirmations": 12,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
]

List Tokens by Network

List tokens available for a specific network.

GET /payments/networks/:id/tokens

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Network ID (UUID)

Response

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440001",
    "networkId": "550e8400-e29b-41d4-a716-446655440002",
    "symbol": "USDC",
    "name": "USD Coin",
    "decimals": 6,
    "contractAddress": "0x...",
    "isNative": false,
    "isStablecoin": true,
    "isActive": true,
    "image": null,
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:00:00.000Z",
    "deletedAt": null
  }
]

Status Codes

Status Code	Description
200	Success
201	Created
204	No Content
400	Bad Request
401	Unauthorized
404	Not Found
500	Internal Server Error

See Also

• Payment Intents - Payment Intents API
• Pay - Pay by slug
• Authentication - Authentication methods