eKYC Open API

1 Introduction

1.1 Overview

The DTC eKYC OpenAPI is a RESTful JSON-based web service that allows third parties to integrate DTC eKYC solutions into their platforms.

This specification defines a set of interfaces and security standards.

1.2 Specification Titles

• Name: The JSON field name in the request or response.

• Type: The JSON type of the field.

  • String, Integer, Long, Enum (an integer ID unless stated otherwise), Object, Array.

• Required:

  • M — Mandatory. Validated by the server.
  • C — Conditional. Mandatory only under the condition stated in the Description column.
  • O — Optional.

• Description: The meaning, allowed values, or format of the field.

1.3 Security Standards

• HTTPS: TLS 1.2, mandatory for every connection.
• Whitelist: Optional IP whitelist, configurable on the API Key Management page.
• OAuth 2.0: Request session management.
• Signature: Request integrity checking.

2 Quick Start

2.1 Disclaimer

Use of these APIs is subject to dtcpay's review and approval. dtcpay reserves the right, at its sole discretion, to approve, restrict, suspend, or revoke access at any time.

2.2 Before Integration

1. Request account registration on the DTC Wallet platform.
2. Log in with the username/password issued by the DTC team and go to the API Key Management page.
3. Click + Create to open the dialog, and choose Wallet / Card API (not Payments API — that's a separate credential for the Payment Open API).
4. Enter the Name and IP Whitelist, then submit.
5. The API Key, API Secret, and Sign Key are generated and shown once. Keep them safe before closing the dialog.
6. Request domain names — see Fetch Access Token below.

2.3 OAuth 2.0 Authentication

2.3.1 Usage

Fetch an access token first, then add Authorization: Bearer {access_token} to every other request.

If the token expires, re-fetch it, or use Fetch Access Token by Refresh Token.

NOTE: Only one access token can exist at a time per client_id. Cache it (e.g. in Redis) rather than fetching a fresh one per request.

2.3.2 Fetch Access Token

Host

• Sbx test environment: https://open-api.sbx.dtcpayment.net
• Production environment: https://open-api.dtcpay.com

Request Body Sample

curl -X "POST" "https://{host}/auth/v1/oauth2/token" \
     -H "Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__" \
     -F "client_id=xxx" \
     -F "client_secret=xxx" \
     -F "grant_type=client_credentials"

The client_id/client_secret are obtained via the web portal at https://business.dtcpay.com/login — navigate to the API menu and create a Wallet API to generate the credentials.

Response Body Sample

{
  "access_token": "CkppLkyiqEUKITGdtCZRUZBl",
  "expires_in": 21600,
  "refresh_token": "CpCAhcCRtLU4kPjs54omWW3A",
  "rt_expires_in": 43200,
  "token_type": "bearer"
}

NOTE: Access denied (errCode 00006) usually means a client_id/client_secret mismatch, or the calling IP does not match the whitelist configured for the API key.

2.3.3 Fetch Access Token by Refresh Token

Request Body Sample

curl -X "POST" "https://{host}/openapi/auth/oauth2/token" \
     -H "Content-Type: multipart/form-data; charset=utf-8; boundary=__X_PAW_BOUNDARY__" \
     -F "refresh_token=CpCAhcCRtLU4kPjs54omWW3A" \
     -F "grant_type=refresh_token"

Response Body Sample — same shape as Fetch Access Token, with fresh access_token/refresh_token.

2.4 Request Signature

For every request, a signature is mandatory in the HTTP header — this is enforced unconditionally for every CLIENT-token-authenticated call (WalletOauthInterceptor.checkSignature), not just a "sensitive" subset.

1. Components of the string to sign:

   • HTTP Method — uppercase.
   • Timestamp — Timestamp number in millis, Singapore timezone. The request will be failed if the timestamp is before or after 2 minutes.
   • URL — the request path, no scheme/host.
   • Querystring — in-URL parameters without the leading ?, un-encoded.
   • Request Body — the exact raw body string, empty if none. Must match byte-for-byte, including invisible characters.

2. Concatenate in order: Method + Timestamp + URL + ('?' + Querystring if present) + Body.

GET1636360576641/ekyc/v1/verification-result/demo_12345
POST1636360661729/ekyc/v1/get-verification-url{"query":{"externalId":"demo_12345"}}

1. Sign the string with HMAC-SHA512 using the Sign Key from Before Integration, then Base64-encode the result.

2. Attach headers to the request:

   • D-TIMESTAMP — Timestamp number in millis, Singapore timezone. The request will be failed if the timestamp is before or after 2 minutes.
   • D-SIGNATURE — the generated signature.

NOTE: The server reads the raw body directly from the HTTP request stream for signature verification. The body used to compute the signature must be byte-identical to the body actually sent — any difference (an extra space, a different key order after re-serialization) breaks verification. Sign the exact same string you send, don't re-serialize a JSON object.

2.4.1 Example: POST Request (Java)

import com.google.common.hash.Hashing;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class SignatureTestGuavaPOST {
    public static void main(String[] args) {
        String signKey = "4mt0MUecOtOEDI42WjN4BmM0";
        String method = "POST";
        String uri = "/ekyc/v1/get-verification-url";
        String query = "";
        String body = "{\"query\":{\"externalId\":\"demo_12345\",\"email\":\"user@example.com\",\"mobile\":\"+60 123456789\",\"countryOfResidence\":\"SGP\",\"targetKycLevel\":100}}";
        String timestamp = String.valueOf(System.currentTimeMillis());

        String stringToSign = method + timestamp + uri;
        if (!query.isEmpty()) {
            stringToSign += "?" + query;
        }
        stringToSign += body;

        String signature = Base64.getEncoder().encodeToString(
                Hashing.hmacSha512(signKey.getBytes(StandardCharsets.UTF_8))
                        .hashBytes(stringToSign.getBytes(StandardCharsets.UTF_8))
                        .asBytes()
        );

        System.out.println("Timestamp   : " + timestamp);
        System.out.println("StringToSign: " + stringToSign);
        System.out.println("Signature   : " + signature);
    }
}

3 API

3.1 Message Structure

Every request body:

{
  "query": {}
}

Paginated requests additionally carry:

{
  "query": {},
  "page": {
    "current": 1,
    "size": 10
  }
}

Responses come in three shapes depending on the endpoint:

Single object

{
  "header": {
    "success": true,
    "errCode": null,
    "errMsg": null
  },
  "result": {}
}

Plain list (no pagination — used by a small number of endpoints not covered in this document)

{
  "header": {
    "success": true
  },
  "resultList": []
}

Paginated list

{
  "header": {
    "success": true
  },
  "resultList": [],
  "pagination": {
    "current": 1,
    "size": 10,
    "total": 100
  }
}

Failure:

{
  "header": {
    "success": false,
    "errCode": "31005",
    "errMsg": "Card Information is invalid"
  }
}

3.2 eKYC Process

This is used to obtain the eKYC verification URL, then poll (or receive a webhook for) the verification result.

3.2.1 Get Verification URL

Endpoint

[POST] /ekyc/v1/get-verification-url

Description

Creates (or resumes, if externalId was already registered by the same caller) an applicant's eKYC session and returns an H5 verification URL for them to complete identity verification.

Request Parameters

Country-of-residence whitelist: separately from reverse solicitation, an institution can also be configured (again in the DTC back-office, InstitutionConfig.corWhitelist) with a whitelist of allowed countryOfResidence values. When configured and non-empty, a countryOfResidence outside that whitelist is rejected with 00025 before any other validation — this is a different, independent admin setting from the reverse-solicitation map above.

Request Body Sample

{
  "query": {
    "externalId": "demo_12345",
    "email": "user@example.com",
    "mobile": "+60 123456789",
    "countryOfResidence": "SGP",
    "targetKycLevel": 100
  }
}

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "url": "https://h5.example.com/openapi/ekyc-h5/?token=eyJhbGciOi...",
    "urlExpiredTime": "2026-09-10 22:00:00"
  }
}

Possible Error Codes

3.2.2 Get Verification Result

Endpoint

[GET] /ekyc/v1/verification-result/{externalId}

Description

Returns the current eKYC verification status and level for a previously registered applicant.

Request Parameters

Response Parameters

Response Body Sample

{
  "header": {
    "success": true
  },
  "result": {
    "externalId": "demo_12345",
    "clientId": 214234123552,
    "clientStatus": 99,
    "nationality": "SGP",
    "countryOfResidence": "SGP",
    "currentKycLevel": 100,
    "passportVerifyStatus": 3,
    "faceIdVerifyStatus": 3,
    "proofOfAddressVerifyStatus": 3,
    "verifyStatus": null,
    "updatedAt": "2026-09-02 16:13:59"
  }
}

Possible Error Codes

3.3 Webhook

3.3.1 Description

DTC supports webhook callbacks in various business scenarios. Customers can implement their own business logic in the callback interface.

The webhook URL is not part of any eKYC request — it is resolved server-side from your own institution's (the value configured for your API key on the API Key Management page), the same URL used by every other webhook this API sends you. To change it, update it on the API Key Management page.

Transport and Payload

DTC sends webhook callbacks using the HTTP POST method. The request body is formatted as JSON and encoded in UTF-8. The request Content-Type is application/json; charset=utf-8.

Acknowledgement and Failure Handling

Each webhook delivery attempt is considered successful only when all of the following conditions are met:

• The request is completed successfully.
• The endpoint returns HTTP status 200.
• The response body is exactly the plain-text string OK, without quotation marks.

An attempt is considered unsuccessful if the request fails, times out, returns a non-200 status code, or returns an empty or different response body.

A webhook notification is marked as FAILED only after the initial delivery attempt and all configured retries have failed. A failed attempt that still has retries available is marked as RETRYING.

Delivery and Retry Model

Each delivery attempt is a synchronous HTTP request/response exchange. The callback endpoint must respond promptly and must not rely on fire-and-forget processing.

The initial delivery attempt is started during notification processing. If an attempt fails, DTC records the notification and schedules the next attempt asynchronously in the background. Therefore, the response from the notification submission API confirms that the notification was accepted for processing; it must not be interpreted as confirmation that the customer endpoint has successfully processed the callback.

DTC performs up to six automatic retries after the initial attempt, for a maximum of seven delivery attempts in total. The retry delay is applied after each failed attempt. Retry timing is best-effort and may be later than the stated interval because of scheduling or service availability.

Webhook endpoints should be idempotent because the same event may be delivered more than once.

Retry Intervals: 15s, 30s, 60s, 120s, 240s, 480s.

3.3.2 Signature Verification

The signature field in the webhook payload is generated using HMAC-SHA512 + Base64 encoding with the Sign Key from Before Integration, but not the same string-to-sign as Request Signature (that scheme is for inbound API calls; this is DTC signing an outbound webhook).

The string signed is POST + the exact webhook URL configured on the API Key Management page (the full URL, not a request path) + the data object only (never the whole envelope — event/clientId/signature are not part of the signed string), with data's JSON keys recursively sorted before signing. No timestamp is included.

Example: Webhook Signature Verification (Java)

import com.google.common.hash.Hashing;
import java.nio.charset.StandardCharsets;
import java.util.Base64;

public class WebhookSignatureVerification {
    public static void main(String[] args) {
        String signKey = "4mt0MUecOtOEDI42WjN4BmM0";

        String method = "POST";
        String webhookUrl = "https://partner.example.com/webhooks/endpoint"; // exactly as configured in API Key Management
        // `dataJson` must be the "data" object only, with its keys recursively sorted
        // (including nested objects) — not the whole envelope, and not raw bytes as received.
        String dataJson = "{\"clientStatus\":1,\"countryOfResidence\":\"SGP\",\"currentKycLevel\":100,\"externalId\":\"demo_12345\",\"faceIdVerifyStatus\":3,\"nationality\":\"SGP\",\"passportVerifyStatus\":3,\"proofOfAddressVerifyStatus\":3,\"verifyStatus\":1}"; // keys sorted alphabetically

        String receivedSignature = "MxrYnCm9Q7JOAvOrISf8+T2kuTW1d/w0at8aaPaoiX08VWfun3XPokVlIx1TkHXdcitls09wzfUGtXQZq23xdg==";

        String stringToSign = method + webhookUrl + dataJson;

        String expectedSignature = Base64.getEncoder().encodeToString(
                Hashing.hmacSha512(signKey.getBytes(StandardCharsets.UTF_8))
                        .hashBytes(stringToSign.getBytes(StandardCharsets.UTF_8))
                        .asBytes()
        );

        boolean isValid = expectedSignature.equals(receivedSignature);
        System.out.println("StringToSign : " + stringToSign);
        System.out.println("Expected     : " + expectedSignature);
        System.out.println("Received     : " + receivedSignature);
        System.out.println("Valid        : " + isValid);
    }
}

To verify a real payload: take the data object exactly as received, recursively sort its own keys, and rebuild the same string — do not sign the raw bytes of the whole request body, since key order there is not guaranteed to match what was actually signed.

Webhook Payload Sample

{
  "event": "KYC_VERIFICATION",
  "clientId": 852042402430001,
  "signature": "MxrYnCm9Q7JOAvOrISf8+T2kuTW1d/w0at8aaPaoiX08VWfun3XPokVlIx1TkHXdcitls09wzfUGtXQZq23xdg==",
  "data": {
    "externalId": "demo_12345",
    "clientStatus": 1,
    "nationality": "SGP",
    "countryOfResidence": "SGP",
    "verifyStatus": 1,
    "currentKycLevel": 100,
    "passportVerifyStatus": 3,
    "faceIdVerifyStatus": 3,
    "proofOfAddressVerifyStatus": 3
  }
}

4 Appendix A: Data Structure

Every response object referenced above by name is fully specified inline at its first use (see the Response Parameters table for each endpoint). There are no shared cross-endpoint object shapes in this API beyond what is documented per endpoint.

5 Appendix B: Error Structure

All DTC Pay APIs return errors in a consistent structure, under the header field:

{
  "header": {
    "success": false,
    "errCode": "<unique error code>",
    "errMsg": "<description of the error>"
  }
}

Every endpoint above lists its own specific error codes with the condition that triggers each one; the table below lists common codes that can be returned by essentially any endpoint:

5.1 Common Error Codes (any endpoint)

6 Appendix C: Enum List

ExternalKycLevel (used by targetKycLevel / currentKycLevel)

EkycVerifyStatus (used by verifyStatus)

EKycFileVerifyStatus (used by passportVerifyStatus / faceIdVerifyStatus / proofOfAddressVerifyStatus)

ClientStatus (used by clientStatus)