Environments

Ferry provides two runtime environments: Production for real customer operations and UAT for partner integration testing. This page explains the differences between the two environments, essential testing cautions, and the list of ferry operators supporting automated electronic ticket issuance.

Key points

• Ferry operates two environments: Production (https://api.ferry.vn) and UAT (base URL provided in writing).
• The UAT environment is not an emulated sandbox: ticket confirmation calls on UAT connect directly to live operator systems and spend real money from the agency deposit.
• All business routes are version-prefixed under /api/v1/; interactive OpenAPI documentation is located at /docs on each respective domain.
• Of the 13 ferry operators integrated with the system, 9 support automated API ticket issuance and 4 support schedule and fare inquiries only.

Comparing the two environments

Partner systems interact with Ferry across two distinct environments configured as follows:

Environment	Primary purpose	Base URL	OpenAPI documentation
Production	Live commercial operations	https://api.ferry.vn	https://api.ferry.vn/docs
UAT	System integration testing	Provided in writing by Ferry	/docs on the UAT domain

Key configuration principles to keep in mind:

• Version prefix: All business API routes follow the format /api/v1/<resource-name>.
• OpenAPI documentation: The interactive Scalar portal is served directly at /docs (without the /api prefix). Opening /docs on a given domain displays the documentation for that specific environment.
• Confirming UAT base URL: Because testing infrastructure hostnames may be adjusted, partners must obtain the confirmed official base URL in writing from Ferry technical operations.

UAT is not an emulated sandbox

The most critical principle for partners: Ferry does not maintain a mock sandbox environment. The UAT environment is a live secondary system connected directly to live ferry operator ticketing engines.

The diagram below illustrates the order flow between the test environment and ferry operators:

flowchart TB
    PROD["Production Environment<br/>api.ferry.vn"]
    UAT["UAT Environment<br/>Integration testing"]
    CHECK{"Ticket confirmation call<br/>confirmToIssue"}
    PROD --> CHECK
    UAT --> CHECK
    CHECK -->|"Confirm"| REAL["Call operator booking gate<br/>Real ticket created"]
    REAL --> MONEY["Real money deducted from agency deposit"]
    CHECK -->|"Booking creation only"| SAFE["Temporary seat hold<br/>No charges incurred"]

Practical implications when testing on UAT:

• Real tickets and real money: Every ticket confirmation call (POST /api/v1/bookings/confirmToIssue/:id) on UAT places a real ticket order in the operator’s system and deducts funds from your agency deposit account.
• CangSaKy operator exception: CangSaKy connects directly to operator systems and always creates real tickets regardless of test-blocking configurations. Test bookings on CangSaKy always incur charges immediately.
• Cancellation procedures: Cancelling test tickets requires following the standard operator cancellation workflow and incurs applicable operator cancellation penalties.
• Safe testing approach: During initial development, partners should stop at the tentative booking creation step (POST /api/v1/bookings) to verify data shapes safely. Only confirm ticket issuance when test voyages and associated costs have been agreed upon with Ferry.

Operator automated ticketing capabilities

The Ferry platform connects to 13 ferry operators for schedule and fare lookups. However, automated e-ticket issuance capabilities differ across operators:

Operator	Schedule search	Automated API ticketing	Operational note
ChanKhaLuxury	Supported	Supported	Direct API e-ticketing
Greenlines	Supported	Supported	Direct API e-ticketing
HoaBinhShip	Supported	Supported	Direct API e-ticketing
Lightning68	Supported	Supported	Direct API e-ticketing
MaiLinhExpress	Supported	Supported	Direct API e-ticketing
PhuQuocExpress	Supported	Supported	Direct API e-ticketing
PhuQuyExpress	Supported	Supported	Direct API e-ticketing
SuperDong	Supported	Supported	Direct API e-ticketing
CangSaKy	Supported	Supported	Direct operator connection
BinhAnHaTien	Supported	Not supported	Inquiries only
ThanhThoi	Supported	Not supported	Inquiries only
HangChauTourist	Supported	Not supported	Inquiries only
SaiGonWaterGo	Supported	Not supported	Inquiries only

For the 4 operators without automated ticketing, ticket confirmation calls will return an unsupported method error. Partners should filter or display clear notices on their user interface for sailings operated by these carriers.

Behavioral differences between Production and UAT

Attribute	UAT environment	Production environment	Partner recommendation
Testing data	Detailed payload logging enabled for debugging	Standard secure production logging	Never submit real passenger personal identifiable data (PII) on UAT
Operator connections	Login for 11 operators may be temporarily disabled	All contracted operators connected	Notify Ferry in advance if you require a specific operator unblocked on UAT (avoids empty voyage search results)
Debt healing	Debt reconciliation process runs in dry-run mode	Automatically reconciles and offsets balances	Discrepancies on UAT after testing will not automatically self-heal
API key format	Key string configured per environment, looks similar to Prod	Key string configured for Production	Maintain separate environment variable stores to prevent accidental crossover
Test ticket issuance	Real tickets issued; select low-cost sailings	Commercial customer ticketing	Only run ticket confirmation tests under mutual supervision and agreed costs
Persist auth on Scalar	Does not persist keys across page reloads	Does not persist keys across page reloads	Re-paste API key into Authorize button after reloading browser

Common misconceptions

Misconception	Reality	Correct practice
Assuming UAT is a free mock sandbox	UAT issues real tickets on operator systems	Do not attach automated regression test suites to ticket confirmation calls
Sharing one API key across UAT and Production	Each environment has its own independent database and keys	Maintain distinct keys in separate server-side environment configurations
Assuming all searchable voyages can be ticketed via API	4 operators support schedule and fare queries only	Verify operator ticketing capabilities before presenting booking flows to users
Submitting real customer identity data on UAT	UAT enables verbose payload logging	Use synthetic passenger details during integration testing
Voyage search on UAT returning empty means no sailings	Operator login might be disabled on UAT	Contact Ferry to unblock the required operator for testing

Where to look in Scalar

Each environment hosts its own independent OpenAPI portal. To inspect schemas and test endpoints:

Target environment	Documentation portal
Inspect schemas and test on Production	Scalar UI — Ferry VN API
Inspect schemas and test on UAT	Open /docs on your assigned UAT domain

Read next

Guide	Recommended next reading
Authentication with an API key	Header format rules and key management across environments
Getting started: from zero to the first booking	10 safe testing steps in the UAT environment
Ticket issuance and orders	Detailed electronic ticket fulfillment workflow with operators
Before going live	Final technical verification checklist before transitioning to Production