OPEN PASSAGE / API
Request a route decision. Execute it your way.
Your backend sends a payment intent and the policy to apply. Open Passage compares the routes available through your active provider connections and returns an explained decision: the selected provider, the alternatives, and why each one was excluded. Your system approves the decision and executes the payment with your provider.
Keep it only in your server environment. Keys are shown once and stored by Open Passage only as a one-way hash.
/api/v1/openapi.json is public documentation only; operational endpoints require the bearer key.
01 / QUICKSTART
Connect your service
- Create an API key in Console → Developer. Copy it directly into your server secret store.
- Configure
OPEN_PASSAGE_BASE_URLandOPEN_PASSAGE_API_KEYin the service that calls Open Passage. - Request a route recommendation for a payment intent, or create a payment instruction to record the decision alongside the payment.
- Optionally, in Console → Developer → Webhooks, register your HTTPS receiver and select event types. Copy the destination’s one-time signing secret into your service as
OPEN_PASSAGE_WEBHOOK_SECRET.
The Console configures provider connections, policies, and event subscriptions. The API key requests decisions, creates payment instructions, and reports the provider outcomes your system observes.
02 / ROUTE RECOMMENDATIONS
Ask for an explained decision
Send the payment intent and a policy ID. Open Passage collects quotes from providers with an active quote-retrieval connection, applies the policy to each, and selects among the eligible routes.
POST /api/v1/recommendations
Authorization: Bearer opg_your_tenant_key
Content-Type: application/json
{
"clientRequestReference": "php-payout-001",
"policyId": "policy_php_standard",
"intent": {
"sourceAmount": "1000",
"sourceAsset": "USDC",
"network": "Polygon",
"destinationCurrency": "PHP",
"rail": "bank",
"delivery": "standard"
}
}Response shape
Examples use Provider A, B, and C. In the demo workspace, the simulated providers are Atlas Payouts, Beacon Transfer, and Cedar Payments.
{
"clientRequestReference": "php-payout-001",
"id": "rec_demo_...",
"status": "recommended",
"selected": { "providerName": "Provider B", "status": "eligible", "quoteId": "...", "fee": "..." },
"alternatives": [
{ "providerName": "Provider A", "status": "excluded", "exclusionReason": "..." },
{ "providerName": "Provider C", "status": "unavailable", "exclusionReason": "..." }
],
"policyVersion": "demo-policy-v1",
"partial": true,
"decisionExpiresAt": "2026-11-18T10:30:38.000Z",
"rationale": "..."
}selectedThe recommended provider route and its quote. Absent when no route is eligible.alternativesEvery other provider evaluated, with eligible, excluded, or unavailable status and an exclusionReason.partialtrue when at least one provider did not respond in time, so the comparison did not include every connected route.decisionExpiresAtWhen the selected quote expires. Request a new decision after this time.statusrecommended, no_eligible_route, or evaluation_unavailable.03 / PAYMENT INSTRUCTIONS
Record the decision with the payment
A payment instruction stores the route decision against your funding account and beneficiary so the selected route, alternatives, and later provider outcomes share one record. The Idempotency-Key is required. Retrying the same request returns the original instruction; reusing a key with different payment inputs is rejected. Open Passage never accepts provider credentials in this request.
POST /api/v1/payment-intents
Authorization: Bearer opg_your_tenant_key
Idempotency-Key: pay-2026-0001
Content-Type: application/json
{
"clientReference": "pay-2026-0001",
"fundingAccountId": "fund_northstar_usdc",
"beneficiaryId": "bene_mara_ph",
"policyId": "policy_php_standard",
"sourceAmount": "250"
}Response semantics
201 createdA new payment instruction and route decision were recorded.200 replayedThe same idempotency key and input returned the original instruction. The response has Idempotent-Replayed: true.409 idempotency_key_reusedThe key belongs to a different payment request.04 / EXECUTION MODELS
Your system executes the payment
northstar_executedCustomer executedOpen Passage returns the decision. Your system approves it, calls your existing provider integration, and reports the provider’s lifecycle events back so the record stays complete.
A design preview, not available in production. With a provider connection authorized for execution and a mandate the customer approves in advance, Open Passage would submit the selected route to that provider. Production use requires a provider integration, defined approval and funds-flow responsibilities, and jurisdiction-specific legal review.
Only active, verified connections with the needed scope can be selected. Provider adapters remain fixed and allowlisted; no request-derived provider endpoint is used. In the API, the customer-executed mode is identified as northstar_executed.
05 / STATUS REPORTING
Report what your system observes
Use this endpoint for customer-executed routes. Use a stable provider event ID: duplicate events are deduplicated.
POST /api/v1/payment-intents/pay_7c2e31f9/provider-status
Authorization: Bearer opg_your_tenant_key
Content-Type: application/json
{
"providerExecutionId": "provider-49201",
"providerEventId": "provider-event-49201-completed",
"type": "payout.completed",
"occurredAt": "2026-11-18T10:30:00.000Z"
}Read the normalized Open Passage record with GET /api/v1/executions/:id. It joins the Open Passage execution ID, provider execution ID, client reference, recipient reference, amounts, fees, and the event history you reported.
06 / OUTBOUND EVENTS
Receive signed events
Open Passage is the caller for outbound events. Each destination receives a unique one-time signing secret when it is registered. Your receiver verifies the HMAC against the exact raw request body, records the event ID, and makes handling idempotent. A receiver must not trust an event merely because its URL is known.
POST https://your-service.example/api/webhooks/open-passage
X-Open-Passage-Event-Id: evt_...
X-Open-Passage-Timestamp: 2026-11-18T10:30:00.000Z
X-Open-Passage-Signature: <HMAC-SHA256 of raw JSON body>
{
"id": "evt_...",
"type": "payout.completed",
"occurredAt": "2026-11-18T10:30:00.000Z",
"data": { "executionId": "exe_...", "status": "paid" }
}Configured lifecycle events include execution.accepted, payout.pending_funding, payout.pending_compliance, payout.in_transit, payout.completed, payout.failed, and payout.returned. The local demo permits a loopback HTTP receiver; production requires a tenant-approved HTTPS destination.
07 / OPERATIONS
Run delivery as a worker, not as a browser action
Use a protected scheduler to invoke POST /api/v1/internal/webhook-delivery-cycle with Authorization: Bearer $OPEN_PASSAGE_OPERATIONS_TOKEN. This processes pending outbound deliveries and retries failures with backoff. The Console control remains available for local diagnostics only.
OPEN_PASSAGE_WEBHOOK_SECRET. Register http://localhost:<your-port>/api/webhooks/open-passage, then set the one-time destination secret shown by the Console in your service before triggering a delivery. The demo workspace is seeded with an example tenant, Northstar Treasury.08 / BEFORE PRODUCTION
What remains intentionally simulated
- Provider-specific adapter endpoints, authentication format, data mappings, and provider webhook/polling contracts.
- Delegated submission, including mandates, approval authority, and funds-flow responsibilities.
- Durable multi-tenant persistence, key scopes/rotation, secret-manager integration, and a scheduler deployment.
- Provider onboarding, funding/custody reconciliation, beneficiary/compliance source-of-truth integrations, and production incident handling.
This demo does not claim provider certification, licensing, PCI compliance, or SOC 2 status. Production credentials belong in a managed secrets system or KMS, never in the JSON demo store, browser state, logs, or API responses.