Payments Router API

Payments Router is an additive API with its own origin and merchant credential boundary.

https://payments-api.paybytoken.io/v2

Send a Payments credential only from trusted server code:

Authorization: Bearer $PAYBYTOKEN_PAYMENTS_API_KEY
Content-Type: application/json
Idempotency-Key: create-order_123

Merchant resources

Create Payments with customer-facing options, not providers:

{
  "amount": { "value": "50.00", "currency": "USD" },
  "options": ["stablecoin", "card", "apple_pay", "google_pay"],
  "line_items": [
    { "name": "Starter plan", "quantity": 1, "unit_amount": "50.00" }
  ],
  "metadata": { "order_id": "order_123" }
}

Create an attempt with an option_id:

{
  "option_id": "card",
  "ui_mode": "embedded",
  "allowed_origin": "https://shop.example"
}

The request never accepts a provider name, provider connection or provider account. Router derives that selection from merchant readiness, mode, option eligibility and its versioned routing policy.

Response groups

The merchant response separates:

• payment: canonical order and lifecycle state;
• attempts: customer option selections;
• routing_decisions: immutable policy evidence and ordered candidates; and
• processor_attempts: provider dispatch and reconciliation evidence.

Customer capability responses omit provider identities, routing evidence, merchant metadata and internal failure details.

Post-payment operations

Use the Payment ID throughout the v2 lifecycle. The operations response exposes the canonical payment, its successful_attempt, the winning successful_processor_attempt, refunds, disputes, settlement evidence and amount summaries. It does not expose provider idempotency keys or routing fingerprints.

curl https://payments-api.paybytoken.io/v2/payments/pay_123/operations \
  -H "Authorization: Bearer $PAYBYTOKEN_PAYMENTS_API_KEY"

Provider synchronization is an operator action, not a customer retry. Use it only when current state is ambiguous or stale. Refund creation requires an idempotency key and always follows the successful processor; clients cannot choose a different provider account.

Idempotency and retries

Every create operation requires a stable idempotency key. Reuse the same key and body after a timeout. Do not switch processors in application code, and do not create another attempt while the current attempt is processing or its processor result is unknown.

See Payments Router and Hosted Router checkout.