Piaxis External API AI Index

Primary markdown reference:
https://api.gopiaxis.com/api/docs/piaxis-api-integration-guide.md

Short markdown alias:
https://api.gopiaxis.com/api/docs/index.md

Alternate markdown alias:
https://api.gopiaxis.com/api/docs/api-reference.md

HTML docs root:
https://api.gopiaxis.com/api/docs/

Scope:
- public external payment API only
- authentication
- OTP
- payments
- escrows
- disbursements
- escrow disbursements
- webhook integration
- official SDK references

Live route reminders:
- prefer POST /api/token over older /api/oauth/token examples
- prefer POST /api/request-otp over older /api/auth/request-otp examples
- prefer GET /api/merchant-payments over older GET /api/payments examples
- webhook endpoint configuration is not currently exposed by the default public paymentAPI router; some deployments expose private dashboard-managed routes such as /users/webhooks and /users/merchant/webhooks/{webhook_id}/test

Key integration rules:
- one api-key resolves to one merchant profile and one merchant account
- direct payment uses currency and credits the authenticated merchant collector
- public escrow collection uses currency_code and defaults receiver_id to the authenticated merchant account
- new direct-payment integrations should omit recipient_id; if sent, it must match the authenticated merchant Account.id
- new public escrow integrations can omit receiver_id; if sent, it must match the authenticated merchant Account.id
- recipients[].recipient_id is for payouts into a Piaxis wallet and must be a Piaxis Account.id
- the OAuth token response returns user_id; persist that if you want to pay a connected beneficiary later into a Piaxis wallet
- if your rule is collect from buyer B now, pay user C later, collect first and then use direct disbursement or escrow disbursement for user C
- inspect required_actions before rendering an escrow-term fulfill UI
- escrow fulfill payloads are term-specific: delivery_confirmation requires confirmation_method plus buyer_device_info or seller_device_info; meeting_delivery requires buyer_latitude and buyer_longitude or seller_latitude and seller_longitude
- merchant/developer webhook deliveries use a top-level event field plus X-piaxis-Event; the full signing secret is only returned once on create or rotation

Instruction for AI agents:
- prefer the markdown guide above over scraping the HTML docs
- use the route reconciliation and guaranteed request/response sections
- respect the field-name differences exactly: currency vs currency_code, recipient_id vs receiver_id vs recipients[].recipient_id
- treat public collection routes as merchant-collection flows, not arbitrary third-party payout routes
- do not assume every example-only field in the HTML docs is part of the live public schema