API Overview

OpenWave is defined by four OpenAPI 3.0.3 specification files. All are ready to load into Swagger UI, Postman, Redocly, or any OpenAPI-compatible tool.

Spec Files

File	Covers	Download
openwave-payments-v1.yaml	Payments · Recurring · Alias · Webhooks	View
openwave-open-banking-v1.0.yaml	AISP · PISP · OAuth 2.0 + PKCE Consent	View
openwave-identity-v1.0.yaml	NPT Identity · Multi-bank Alias · Bank Phonebook	View
openwave-gateway-interconnect-v1.yaml	Gateway Discovery · Remote Routing · Interconnect Settlement	View

Interactive Explorer

▶ Open API Explorer →

Browse and test the full API surface in your browser.

API Modules

Payments (openwave-payments-v1.yaml)

Method	Path	Description
POST	/payments/sessions	Create a payment session
GET	/payments/sessions/{id}	Get session status
GET	/payments/sessions	List sessions
POST	/payments/sessions/{id}/cancel	Cancel a pending session

Recurring Payments

Method	Path	Description
POST	/recurring/mandates	Create a recurring mandate
GET	/recurring/mandates/{id}	Get mandate details
DELETE	/recurring/mandates/{id}	Cancel a mandate
POST	/recurring/mandates/{id}/charge	Execute a charge

Alias (NPT)

Method	Path	Description
GET	/alias/{username}	Get alias details
GET	/alias/{username}/accounts	List linked accounts
DELETE	/alias/{username}	Deactivate alias

Webhooks

Method	Path	Description
POST	/merchants/{id}/webhooks	Register webhook endpoint
GET	/merchants/{id}/webhooks	List webhook endpoints
DELETE	/merchants/{id}/webhooks/{wid}	Remove endpoint
GET	/admin/webhooks	List all deliveries (admin)
POST	/admin/webhooks/{id}/retry	Retry failed delivery

Open Banking (openwave-open-banking-v1.0.yaml)

Method	Path	Description
POST	/ob/consents	Create a consent request
GET	/ob/consents/{id}	Get consent status
DELETE	/ob/consents/{id}	Revoke consent
POST	/ob/token	Exchange code or refresh token
POST	/ob/token/revoke	Revoke a token (RFC 7009)
GET	/ob/accounts	List consented accounts
GET	/ob/accounts/{id}/balances	Get account balances
GET	/ob/accounts/{id}/transactions	Get transactions
POST	/ob/payment-orders	Initiate a payment order
GET	/ob/payment-orders/{id}	Get payment order status
GET	/banks/{handle}/capabilities	Bank OB capabilities

Identity Registry (openwave-identity-v1.0.yaml)

Method	Path	Description
GET	/v1/identity/resolve	Resolve alias → IBAN (public)
POST	/v1/identity/claim	Claim an NPT handle
GET	/v1/identity/{handle}	Get public profile
GET	/v1/identity/{handle}/accounts	List linked accounts
POST	/v1/identity/{handle}/accounts	Link additional bank
PATCH	/v1/identity/{handle}/default	Set default account
DELETE	/v1/identity/{handle}	Delete identity
GET	/v1/banks	Bank phonebook (public)
POST	/v1/banks	Register bank (admin)
GET	/v1/registry/info	Registry metadata (public)

Gateway Interconnect (openwave-gateway-interconnect-v1.yaml)

Method	Path	Description
GET	/gateway-info	Get gateway metadata, capabilities, and fees
POST	/gateway-register	Register or update a gateway profile
POST	/resolve-alias-remote	Resolve an alias hosted by another gateway
POST	/route-payment	Initiate a cross-gateway payment route
POST	/route-status	Check cross-gateway route status
POST	/settlement-batch	Submit gateway-to-gateway settlement batch
GET	/settlement-status	Check settlement batch status
GET	/gateway-health	Get gateway health and routing availability

Base URL

https://<your-gateway-host>/api/v1

The exact base URL depends on your gateway operator. Example:

https://astro.neptune.ly/api/v1

Which endpoint should I read first?

I am building...	Start here	Then read
Merchant checkout	POST /payments/sessions	GET /payments/sessions/{id}, webhook events, idempotency
Subscription billing	POST /recurring/mandates	hosted mandate consent, mandate charges, cancellation
Bank connector	/send-otp, /verify-otp, /execute-transaction, /notify-credit	callback authentication and CBS idempotency
Open Banking TPP app	POST /ob/consents	PKCE, scopes, token exchange, consent revocation
NPT identity registry	GET /v1/identity/resolve	claim/link/default-account operations
Gateway operator	GET /gateway-info	POST /route-payment, status, settlement batch

Common headers

Header	Direction	Used by	Notes
Authorization: Bearer mk_...	Merchant → Gateway	Payment sessions, mandates, merchant webhooks	Keep server-side only
X-OpenWave-Internal-Key: ow_cbk_...	Gateway → Bank	Bank callback interface	DB/configured per bank integration
X-OpenWave-Bank-Key: owbk_...	Bank → Identity Registry	NPT claims and bank-owned account changes	Bank-scoped; not customer login
X-OpenWave-Gateway-Key: owgw_...	Gateway → Gateway	OW-GIP interconnect calls	Production profiles must also use mTLS
Idempotency-Key	Client → API	Payment/session/route/create operations	Required for retry-safe writes