API Reference Manual
Payments & Marketplace Modules — Implementation-grade contract for programmable financial flows
Version:
v1.0 Master
Classification:
Strategic Confidential
Base URL:
api.zoikopay.com/v1
RESTFUL
JSON
ATOMIC LEDGER-BACKED
EVENT-DRIVEN
01 • Core Principles
System Architecture & Global Constraints
Atomicity
No partial money movement. All state transitions are ACID at ledger level.
Idempotency
Safe retries guaranteed. Every write requires Idempotency-Key header.
Ledger Truth
Every movement journaled. Immutable audit trail with deterministic reconstruction.
Events
Verifiable events with cryptographic webhook signatures and correlation IDs.
02 • Connectivity
Base Connectivity & Headers
BASE
https://api.zoikopay.com/v1
Transport Security
REQUIRED
TLS 1.3 only • HTTP/2 preferred • HSTS enabled • Perfect Forward Secrecy required
Mandatory Headers
Content-Type: application/json; charset=utf-8
Authorization: Bearer sk_live_...
Idempotency-Key: {uuid}
Zoiko-Version: 2026-01-12
Authentication Models
- Secret API Keys (server-to-server) - scoped per environment and capability
- OAuth 2.0 (platform delegation) - for third-party app access
- Minimum requirements: key rotation, least privilege scopes, IP allowlisting
03 • Payment Intent API
Core Payment Orchestration
Unified Payment Intent orchestrates multiple rails with consistent lifecycle semantics
POST
/v1/payment_intents
{ "amount": 10000, "currency": "usd", "payment_method_types": ["card", "us_bank_account", "zoiko_wallet"], "capture_method": "automatic", "application_fee_amount": 500, "transfer_data": { "destination": "acct_bookingorbit_123" }, "metadata": { "order_id": "BO-9954" } }
Lifecycle States
requires_confirmation
requires_payment_method
requires_action
processing
succeeded
canceled
Payment Methods
card
bank_account
zoiko_wallet
apple_pay / google_pay
local_methods
Capabilities
Capabilities
Multi-rail support
Split payments
Application fees
Metadata tracking
Network tokenization
04 • Marketplace
Split Logic & Revenue Sharing
POST
/v1/split_plans
{ "name": "bookingorbit_standard", "rules": [ {"type": "platform_fee_pct", "value": 0.05}, {"type": "processor_reserve_pct", "value": 0.01}, {"type": "seller_payout_pct", "value": 0.94} ] }
Split Capabilities
- Automatic platform fee calculation
- Multi-seller commission splits
- Tax withholding vaults
- Transfer groups for complex flows
- Ledger-backed atomic execution
05 • Error Handling
Error Object & Taxonomy
{ "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "currency must be a supported ISO 4217 code", "param": "currency", "request_id": "req_01HZ...", "doc_url": "https://docs.zoikopay.com/errors#parameter_invalid" } }
