Create a Payment Intent

Create a Payment Intent to start collecting payment from a customer.

Endpoint

POST /api/v1/payment_intents

The API version is in the URL path (v1). There is no version field in the request body.

API version and SDK

• Version in URL: The base path includes the version (e.g. /api/v1/payment_intents). Current version is v1. When newer versions exist, the path will reflect them (e.g. /api/v2/payment_intents).
• Node SDK: The client accepts baseUrl (default https://api.orcarail.com/api/v1) and apiVersion (default "v1"). To use a different API version, set baseUrl to the desired versioned base (e.g. https://api.orcarail.com/api/v2). Payment Intent create params do not include a version field; the client uses the base URL. See Node SDK for full configuration.

Authentication

This endpoint supports both authentication methods:

• Bearer Token (JWT) - Authorization: Bearer YOUR_JWT_TOKEN
• API Key (Basic Auth) - Authorization: Basic base64(key:secret)

Request

Request Body

{
  "amount": "100.00",
  "currency": "usd",
  "payment_method_types": ["crypto"],
  "tokenId": 1,
  "networkId": 1,
  "return_url": "https://merchant.example.com/return",
  "cancel_url": "https://merchant.example.com/cancel",
  "description": "Payment for services",
  "metadata": {
    "order_id": "12345",
    "customer_id": "67890"
  },
  "expires_at": "2024-12-31T23:59:59Z",
  "withdrawal_addresses": { "evm": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" }
}

Parameters

Parameter	Type	Required	Description
amount	string	Yes	The amount to charge, in the smallest currency unit (e.g., cents for USD). Must be a positive number.
currency	string	Yes	Three-letter ISO currency code (e.g., usd, eur).
payment_method_types	array	Yes	Array of payment method types. Must include "crypto".
tokenId	number	Yes	The ID of the token to accept (e.g., USDC, USDT).
networkId	number	Yes	The ID of the blockchain network (e.g., Ethereum, Polygon).
return_url	string	Yes	The URL to redirect customers to after payment completion.
cancel_url	string	No	The URL to redirect customers to if they cancel the payment.
description	string	No	An optional description of the payment.
metadata	object	No	Set of key-value pairs that you can attach to the Payment Intent.
expires_at	string	No	ISO 8601 timestamp when the Payment Intent expires.
withdrawal_addresses	object	No	Withdrawal addresses by chain type. Keys must be valid chain types: evm, solana, bitcoin, tron, cosmos, polkadot, move, ton (e.g. { "evm": "0x...", "solana": "..." }). When omitted or empty for a chain, your account default from Withdrawal Settings is used.

Response

Success 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",
  "cancelUrl": "https://merchant.example.com/cancel",
  "description": "Payment for services",
  "metadata": {
    "order_id": "12345",
    "customer_id": "67890"
  },
  "paymentLink": {
    "id": 1,
    "link": "https://pay.orcarail.com/pay/pl_abc123"
  },
  "expiresAt": "2024-12-31T23:59:59.000Z",
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z"
}

Response Fields

Field	Type	Description
id	string	Unique identifier for the Payment Intent (e.g., 550e8400-e29b-41d4-a716-446655440000).
amount	string	The amount to charge.
currency	string	The currency code.
status	string	Current status of the Payment Intent.
paymentMethodTypes	array	Array of payment method types.
clientSecret	string	Important: This is only shown once. Use it to confirm the Payment Intent.
returnUrl	string	The return URL you specified.
cancelUrl	string	The cancel URL you specified (if any).
description	string	The description you provided (if any).
metadata	object	The metadata you provided (if any).
paymentLink	object	Contains the hosted pay URL in link.
expiresAt	string	When the Payment Intent expires (if specified).
createdAt	string	When the Payment Intent was created.
updatedAt	string	When the Payment Intent was last updated.

Example

cURL

curl https://api.orcarail.com/api/v1/payment_intents \
  -X POST \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "100.00",
    "currency": "usd",
    "payment_method_types": ["crypto"],
    "tokenId": 1,
    "networkId": 1,
    "return_url": "https://merchant.example.com/return"
  }'

JavaScript (Node.js)

const response = await fetch(
  'https://api.orcarail.com/api/v1/payment_intents',
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      amount: '100.00',
      currency: 'usd',
      payment_method_types: ['crypto'],
      tokenId: 1,
      networkId: 1,
      return_url: 'https://merchant.example.com/return',
      description: 'Payment for services',
      metadata: {
        order_id: '12345',
      },
    }),
  }
)

const paymentIntent = await response.json()
console.log('Client Secret:', paymentIntent.clientSecret)
console.log('Payment Link:', paymentIntent.paymentLink.link)

Python

import requests

response = requests.post(
    'https://api.orcarail.com/api/v1/payment_intents',
    headers={
        'Authorization': f'Bearer {jwt_token}',
        'Content-Type': 'application/json',
    },
    json={
        'amount': '100.00',
        'currency': 'usd',
        'payment_method_types': ['crypto'],
        'tokenId': 1,
        'networkId': 1,
        'return_url': 'https://merchant.example.com/return',
        'description': 'Payment for services',
        'metadata': {
            'order_id': '12345',
        },
    },
)

payment_intent = response.json()
print(f"Client Secret: {payment_intent['clientSecret']}")
print(f"Payment Link: {payment_intent['paymentLink']['link']}")

Next Steps

After creating a Payment Intent:

1. Confirm the Payment Intent - Get the redirect URL for your customer
2. Redirect the customer to the hosted pay app
3. Handle the return URL callback