Authentication

The POSitiveRails API uses API keys to authenticate requests. You can view and manage your keys in the OmniPOS Developer Dashboard. Your API keys carry many privileges, so be sure to keep them secure.

                    # Authenticate via Bearer Token

                    Authorization: Bearer sk_live_POS...

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Create a Charge (Dynamic Route)

This is the core orchestration endpoint. Submit a payment payload, and the ATRI engine will automatically evaluate the `mcc_code` and `amount` to route the transaction to the optimal acquiring rail (e.g., Priority for B2B L3, PayRoc for Retail).

Endpoint

POST https://api.positiverails.com/v1/route/charge

Body Parameters

amount integer REQUIRED

Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00).
currency string REQUIRED

Three-letter ISO currency code, in lowercase. Must be a supported currency (currently `usd`).
l3_data object OPTIONAL

If provided, the POSitiveRails engine will force-route to a commercial acquiring BIN (Priority) and inject the nested line items for interchange optimization.

Request (cURL)

curl -X POST https://api.positiverails.com/v1/route/charge \
  -H "Authorization: Bearer sk_live_POS_8xj29..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 4500000, // $45,000.00
    "currency": "usd",
    "source": "tok_1NmK...",
    "l3_data": {
      "po_number": "FRT-992-881",
      "tax_amount": 0
    }
  }'

Response (JSON)

{
  "id": "ch_1Oxa22L...",
  "object": "charge",
  "amount": 4500000,
  "status": "succeeded",
  "orchestration_meta": {
    "routed_rail": "Priority_Commercial",
    "l3_injected": true,
    "est_interchange_savings": 675.00,
    "nmi_switch_latency_ms": 142
  }
}