Payment Intents API Reference

Complete reference for the Payment Intents API endpoints.

Base URL

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

The API version is in the path (v1). To use another version, use the corresponding base URL (e.g. https://api.orcarail.com/api/v2). The Node SDK uses baseUrl and apiVersion in config; see Node SDK.

Create a Payment Intent

Create a new Payment Intent.

POST /payment_intents

Authentication

• Bearer Token (JWT) or API Key (Basic Auth)

Request Body

Parameter	Type	Required	Description
amount	string	Yes	Amount to charge (e.g., "100.00")
currency	string	Yes	Currency code (e.g., "usd")
payment_method_types	array	Yes	Must include "crypto"
tokenId	number	Yes	Token ID (e.g., USDC, USDT)
networkId	number	Yes	Network ID (e.g., Ethereum, Polygon)
return_url	string	Yes	Return URL after payment
cancel_url	string	No	Cancel URL
description	string	No	Payment description
metadata	object	No	Custom metadata
expires_at	string	No	ISO 8601 expiration timestamp
withdrawal_addresses	object	No	Withdrawal addresses by chain type. Keys: valid chain types (evm, solana, bitcoin, tron, cosmos, polkadot, move, ton). Omit or leave empty for a chain to use your account default from Withdrawal Settings.

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "paymentMethodTypes": ["crypto"],
  "clientSecret": "550e8400-e29b-41d4-a716-446655440000_secret_abc123",
  "returnUrl": "https://merchant.example.com/return",
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "createdAt": "2024-01-01T00:00:00.000Z"
}

Retrieve a Payment Intent

Get details of a Payment Intent.

GET /payment_intents/:id

Authentication

• Bearer Token (JWT) or API Key (Basic Auth)

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Payment Intent ID (e.g., 550e8400-e29b-41d4-a716-446655440000)

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "100.00",
  "currency": "usd",
  "status": "succeeded",
  "paymentMethodTypes": ["crypto"],
  "latestTransaction": {
    "id": "txn_1234567890",
    "status": "completed",
    "hash": "0x1234567890abcdef...",
    "amount": "100.00"
  },
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Confirm a Payment Intent

Confirm a Payment Intent to get the redirect URL.

POST /payment_intents/:id/confirm

Authentication

• Bearer Token (JWT) or API Key (Basic Auth)

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Payment Intent ID

Request Body

Parameter	Type	Required	Description
client_secret	string	Yes	Client secret from Payment Intent
return_url	string	No	Override return URL
payment_method_data	object	No	Payment method data

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "requires_confirmation",
  "nextAction": {
    "type": "redirect_to_url",
    "redirectToUrl": {
      "url": "https://pay.orcarail.com/pay/pl_abc123?payment_intent=550e8400-e29b-41d4-a716-446655440000&payment_intent_client_secret=550e8400-e29b-41d4-a716-446655440000_secret_abc123"
    }
  }
}

Cancel a Payment Intent

Cancel a Payment Intent. Once canceled, it cannot be used for payment.

POST /payment_intents/:id/cancel

Authentication

• API Key (Basic Auth) - Required

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Payment Intent ID

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "canceled",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Complete a Payment Intent

Mark a Payment Intent as processing and trigger the payment_intent.processing webhook. Call this after the customer has been redirected back to your return URL (e.g., from your success page) so that your backend can mark the intent as processing while you poll or wait for the final payment_intent.complete webhook.

POST /payment_intents/:id/complete

Authentication

• API Key (Basic Auth) - Required

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Payment Intent ID

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "processing",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Update a Payment Intent

Update a Payment Intent before confirmation.

PATCH /payment_intents/:id

Authentication

• Bearer Token (JWT) or API Key (Basic Auth)

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Payment Intent ID

Request Body

All fields are optional. Only include fields to update.

Parameter	Type	Required	Description
amount	string	No	Updated amount
currency	string	No	Updated currency
description	string	No	Updated description
metadata	object	No	Updated metadata
return_url	string	No	Updated return URL
cancel_url	string	No	Updated cancel URL
withdrawal_addresses	object	No	Withdrawal addresses by chain type; omit to use account default

Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "amount": "150.00",
  "currency": "usd",
  "status": "requires_payment_method",
  "updatedAt": "2024-01-01T12:00:00.000Z"
}

Status Codes

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

Error Response Format

{
  "statusCode": 400,
  "message": "Invalid request",
  "error": "Bad Request"
}

Rate Limits

API requests are rate-limited. Current limits:

• Authenticated requests: 100 requests per minute per API key/user
• Unauthenticated requests: 10 requests per minute per IP

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

See Also

• Payment Intents Guide - Detailed guides
• Webhooks - Receive payment notifications