Before you go live
Prior to transitioning into the live production environment, your system must satisfy acceptance criteria covering connectivity, business workflow verification, data integrity safeguards, and operational monitoring. This page provides a concise, actionable checklist to evaluate your launch readiness before enabling live partner traffic.
The four acceptance gates
Section titled “The four acceptance gates”The four gates must be cleared in order. Subsequent gates depend strictly on previous ones: connectivity is required to test business flows, understanding flows is required to design safeguards, and monitoring only proves useful once safeguards are active.
The diagram below shows the four sequential acceptance gates before putting the system into production:
flowchart LR K["Gate 1 — Connection"] --> K1["Live key stored only in secrets manager"] K --> K2["Base URL confirmed in writing"] K1 --> N["Gate 2 — Business flows"] K2 --> N N --> N1["Execute 1 real order on UAT"] N --> N2["Identify automated ticketing operators"] N1 --> C["Gate 3 — Safeguards"] N2 --> C C --> C1["Block duplicate creation locally"] C --> C2["Check state on timeout"] C1 --> G["Gate 4 — Monitoring"] C2 --> G G --> G1["Daily scheduled reconciliation"] G --> G2["Abnormal silence alerts"]Acceptance checklist
Section titled “Acceptance checklist”Gate 1 — Connection and security
Section titled “Gate 1 — Connection and security”- Secret key protection: The live API key is stored exclusively in a secure secrets manager or protected environment variables, never hardcoded in source code or included in client-side builds.
- Base URL confirmation: The production Base URL has been officially verified in writing by Ferry representatives, not assumed from documentation.
- Environment separation: UAT and Production credentials are distinctly labelled in your configuration to avoid crossing environments.
- Key rotation drill: You have rehearsed the key rotation sequence (provision new key, load into system, verify traffic runs cleanly, and then request revocation of the retired key).
Keys have no expiry and no advance revocation warning. Revocation is immediate and irreversible; agree on a key-incident contact before opening sales.
Gate 2 — Business flows and ferry operators
Section titled “Gate 2 — Business flows and ferry operators”- End-to-end UAT order: You have exercised a complete booking lifecycle, including a controlled failure, and confirmed the real ticket on the tested operator’s system.
- Identify automated ticketing operators: You know which ferry operators support automated API ticketing versus those requiring custom operational handling.
- Partial ticketing handling: Your system properly manages scenarios where a round-trip or multi-leg booking succeeds on only one leg.
- Price formula verification: You have cross-checked customer retail prices and agency NET prices, ensuring calculations align across both systems.
Gate 3 — Data error prevention
Section titled “Gate 3 — Data error prevention”- Local duplicate prevention: You have submitted twice in succession and verified that only one booking exists, rather than only checking that the button becomes disabled.
- Safe timeout recovery: If an order creation call encounters a network timeout, your system queries order status before deciding whether to resubmit.
- Webhook deduplication: Your webhook ingestion pipeline deduplicates events by resource identifier and event type.
- Safe handling of empty lists: Your system does not interpret empty API list responses as justification to delete or cancel local records.
Gate 4 — Monitoring and operations
Section titled “Gate 4 — Monitoring and operations”- Scheduled reconciliation active: An automated background job compares order statuses and financial ledgers between both systems daily.
- Webhook receiver verified: Your webhook receiving URL runs HTTPS, responds with HTTP 200 in under 2 seconds, and has verified live event ingestion.
- Abnormal silence alerts: Monitoring alerts trigger when no events or orders arrive within an unexpectedly wide timeframe.
- Trace ID logging: Log trace IDs, order IDs, and error codes for every failed call; retain them for at least one month for investigations.
- Unexpected empty-list alerts: Alert when a query that normally returns data suddenly returns empty, even with HTTP 200.
What to monitor from day one
Section titled “What to monitor from day one”Four operational signals partners must monitor continuously:
- Order status is the authoritative truth: Webhooks serve as event signals; API polling provides the ground truth. Scheduled reconciliation tasks automatically backfill any dropped webhook events.
- Orders transition status without partner calls: Background sweep tasks automatically reconcile paid bookings with ferry operators. A booking may transition to issued status several minutes later without any API invocation from your side.
- Ticketing confirmation latency: Issuing tickets with certain ferry operator gateways can take several minutes. Ensure client request timeouts accommodate this duration and monitor latency to detect slow upstream gateways.
- Balance and business error rates: Track your organization’s available deposit balance and error code frequencies to replenish funds before orders fail due to balance shortages.
The global rate limit counts by IP address; there is no separate quota per API key or organization. Track both HTTP 429 and business error codes. Confirmation can take 5–8 minutes with some operators; do not treat a timeout as proof that the booking failed.
Differences between UAT and Production
Section titled “Differences between UAT and Production”| Item | UAT environment | Production environment | Action required when switching |
|---|---|---|---|
| Base URL | Typically api.ferryvn.net | api.ferry.vn | Update configuration based on written confirmation from Ferry |
| Operator connectivity | 11 operators blocked from logging in on UAT | This login block list is not applied | Test required operators; arrange temporary UAT access with Ferry before launch if needed |
| Debt healing tasks | Test mode only, no live ledger entries | Runs live and reconciles ledgers | Enable scheduled reconciliation before launch to catch drift |
| API key | UAT key (shares ferry_ prefix) | Production key (shares ferry_ prefix) | Distinctly isolate credentials in secret storage |
The 11 operators blocked from logging in on UAT are mailinhexpress, superdong, phuquocexpress, lightning68, hoabinhship, phuquyexpress, greenlines, cangsaky, hangchautourist, chankhaluxury, and saigonwatergo. This login block list is distinct from the list of operators without automated ticket issuance.
Common misconceptions
Section titled “Common misconceptions”| Misconception | Reality | Consequence |
|---|---|---|
| UAT is a mocked sandbox | UAT issues real tickets on operator portals | Flawed tests expend real agency balances |
| Going live only requires changing the Base URL | More operators are live on Production than UAT | Gateway-specific errors only surface live if unverified |
| Waiting for Ferry to provide idempotency keys | Ferry does not provide idempotency for order creation | Retrying on timeout creates duplicate orders and double charges |
| Webhooks are the sole source of truth | Webhooks do not retry and time out after 2 seconds | Stuck orders go unnoticed if webhooks drop |
| API keys do not expire so rotation is unneeded | Compromised keys remain usable without automated alerts | Unmonitored security exposure over time |
Where to look in Scalar
Section titled “Where to look in Scalar”The API reference at https://api.ferry.vn/docs is your final verification tool before going live. Call a read-only endpoint using your production credentials on the live domain:
| Verification target | Group in API reference |
|---|---|
| Read-only call to verify live API key validity | Voyage |
| Query booking state for reconciliation | Bookings |
| Inspect order detail structures during reconciliation | Order |
| Transaction history to reconcile balances and payments | Payment |
| Organization profile tied to your API key | Organizations |
Read next
Section titled “Read next”| Page | When to read |
|---|---|
| Overview | Review full functional boundaries and API scope |
| Environments | Compare technical details between UAT and Production |
| Authentication | Learn key rotation procedures and permission sets |
| Conventions | Review data formats, paging cursors, and duplicate handling |
| Errors and how to handle them | Inspect business error codes and retry rules |
| Rate limits | Configure throughput thresholds and monitor 429 errors |
| Webhooks | Set up event receivers and asynchronous ingestion |
| Booking flow | Review complete booking lifecycles before final sign-off |
Open questions
Section titled “Open questions”- Service Level Agreements (SLA): Ferry has not published formal commitments regarding platform uptime or incident turnaround times. Partners should establish emergency contact channels and support availability hours prior to opening live sales.
- Official Base URL confirmation: The production Base URL should be formally verified in writing with Ferry engineering before routing live customer traffic.
- Silence alert threshold: The threshold of X minutes depends on individual partner transaction volume; configure alert thresholds flexibly to account for peak and off-peak travel seasons.