First steps - DCS Technical Documentation

📄 Guide

Whether you are running a technical evaluation or starting the integration outright, walk through this page first: get the credentials, callback URL, egress IPs and shared conventions in place, then move on to the Quickstart to issue your first card. DCS, as the licensed issuer, carries issuing and settlement; you implement three things — signing, calling and receiving webhooks.

Integration stages

From contract signing to running at scale, integration goes through six stages. Each has explicit prerequisites; do not enter a stage before the previous one is ready.

Stage	Main work
1 · Contract and scoping	Sign commercially, submit qualification and due-diligence material for the partner and the first company, confirm card types, card face, whether physical cards (and shipping range) are needed, and whether you hold PCI DSS
2 · Environment setup	Register the callback URL and egress IPs, receive and store the keys securely, confirm the card product and card face configuration
3 · Development	Implement request signing and run the shortest issuing path; implement the webhook receiver (signature check, idempotency, fast 2xx); implement scheduled polling of the query endpoints as fallback
4 · Testing and certification	Verify case by case: the happy path, resubmission after rejection, idempotent repeats, callback retry and dedup, signature failures and clock skew, limit and parameter validation
5 · Pilot	Grey-launch with a small volume in production (recommended: one company, one employee, one card) with monitoring and alerting in place
6 · Launch and scale	Once the pilot is clean, open up issuing and transaction volume step by step into normal operations

Environments and credentials

Environment isolation: the test and production environments are fully independent deployments — domains, credentials, data and callback keys are all separate, non-interchangeable and non-migratable; switch both the domain and the credentials when switching environments. Both use the same path prefix, /open-api-corp/.
Credential handling: the AK (API key) identifies the partner in request headers; the SK (secret key) is used only to compute signatures locally and doubles as the decryption key for the secure card endpoint; the webhook signing key is issued separately by DCS. Store the SK in a key-management service or encrypted configuration — never in code repositories, logs or the frontend.

Three ground rules

① Every create-type endpoint is accepted asynchronously. Company onboarding, employee creation and virtual card application return only an the application ID and status=PENDING synchronously — meaning “accepted”, not “created”. For the real final state, rely on webhooks first, with polling of the query endpoints as the fallback. ② Success is judged by the response body’s code, not the HTTP status. The unified response envelope is {code, message, data}; only code == "SYS_SUCCESS" is success, everything else is failure. The HTTP status is informational only (authentication failures return 401). ③ Your identity comes from the AK, never from the request body. DCS establishes the partner identity from the AK signature check on the request headers. Do not carry any partner or enterprise identifier in the body — if you do, it is ignored.

Shared conventions

This section sets the ground rules shared by every endpoint; each endpoint page then only needs to describe its own parameters and fields.

Convention	Description
Base URL	`https://{access-domain}/open-api-corp/{module}/v1/{action}`; HTTPS throughout. Test and production use separate access domains, issued by DCS during onboarding.
Method semantics	Query endpoints use GET (parameters in the query string); write and action endpoints use POST (parameters in a JSON body, Content-Type `application/json`).
Response envelope	Success or failure, the response is always `{code, message, data}`. Judge business success by `code == "SYS_SUCCESS"`; everything else is failure. HTTP status is informational (401 for authentication failure).
Pagination	List endpoints share `page` (from 1, default 1), `pageSize` (1–100, default 20), `total`, `result`.
Idempotency	Every write endpoint carries an idempotency key (`organizationRef` / `customerRef` / `cardApplyRef` / `transferRef` / `ruleRef` and so on), generated and persisted by the partner and reused on retries.
Versioning	The version number is embedded in the path (currently v1). Backwards-compatible changes (new optional fields, enum values, error codes) ship within v1 — parse responses leniently and ignore unknown fields; incompatible changes ship under a new version.

ID conventions. Every ID in the contract is a JSON string: organizationId and customerId are UUID-shaped strings from the unified user center; cardId, the application ID and webhookId are 19-digit snowflake strings (transmit them as strings — numeric literals overflow the double-precision safe-integer range and get silently truncated); transferId, ruleId, statementId, transactionId and the rest are business strings to pass through verbatim. The meaning of a polymorphic ID (subjectId, subjectId, subjectId) is determined by the type field in the same structure, never inferred from its shape. Partner-side IDs (externalXxx) are custom strings matching ^[A-Za-z0-9_-]+$, at most 64 characters, and double as idempotency keys.

Next steps

Once ready, head to the Quickstart and issue your first card along the shortest path.
Understand holders, funding and state machines: Holders and the funding model

​📄 Guide

​Integration stages

​Environments and credentials

​Three ground rules

​Shared conventions

​Next steps