> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.
# First steps
> What to prepare before integrating: the six stages from contract to launch, environment isolation and credential handling, three ground rules that run through everything, and the conventions shared by every endpoint.
## 📄 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](./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](./quickstart) and issue your first card along the shortest path.
* Understand holders, funding and state machines: [Holders and the funding model](../basic-concepts/identity-and-funding)