Ver. Korean

Introduction

TomoIDV is an API service that provides an eKYC flow for foreign visitors to Korea using identity documents issued in their home countries.

This document defines a complete onboarding flow for using the TomoIDV API, from OAuth2 authentication and KYC policy selection through KYC initiation, the KYC flow, and result retrieval.

sequenceDiagram
    participant ClientApp as Client App
    participant ClientServer as Client Server
    participant IDVServer as TomoIDV Server
    participant IDVApp as TomoIDV App

    ClientServer->>+IDVServer: [1] Get Access Token (POST /v1/oauth2/token)
    IDVServer-->>-ClientServer: 200 OK
    ClientApp->>+ClientServer: Start IDV
    ClientServer->>+IDVServer: [2] Start IDV(Get IDV URL) (POST /v1/idv/start)
    IDVServer-->>-ClientServer: 200 OK
    ClientServer-->>-ClientApp: 200 OK
    ClientApp->>IDVApp: [3] Launch IDV App
    IDVApp-->>ClientApp: [4] Return to Origin App
    ClientServer->>+IDVServer: [5] Get Kyc (POST /v1/idv/result)
    IDVServer->>-ClientServer: 200 OK
Term Meaning
client_id API client identifier created in the dashboard
secret/key material Backend-only credentials used to sign the client_assertion JWT
client_assertion Client-signed JWT submitted with an OAuth2 token request
access_token Bearer token used to call the IDV server API
kyc_policy Public policy object that specifies the KYC method and owner verification level
policy_key Canonical key returned by the server to identify the completed policy
ppid / PPID Persistent unique value issued upon completion of KYC

Requirements

Preparing to Use the API

1. Obtaining a Client ID and Secret Key

To use the API, you must obtain a client ID and secret key. These credentials are used for OAuth2.0 authentication and are issued through the Console. For details about the issuance process, see the Register Client document. Once you have obtained a client ID and secret key, you can request an access token. You can then use this access token to call the TomoIDV API.

Developer Console URL Description
Sandbox Console https://test-console.tomopayment.com Test console that supports the KYC flow in sandbox mode without using actual identity documents
Production Console https://console.tomopayment.com Production console that supports the production KYC flow using actual identity documents for foreign nationals

2. API Base URL

TomoIDV uses two domains (base URLs): Sandbox and Production. A client ID created in the Sandbox Console can use the Sandbox Base URL, while a client ID created in the Production Console can use the Production Base URL.

API Environment IDV API Base URL
Sandbox https://test.tomopayment.com
Production https://api.tomopayment.com

3. Obtaining an OAuth2 Access Token

POST /v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
Field Type Required Value
grant_type string Required client_credentials
client_assertion_type string Required urn:ietf:params:oauth:client-assertion-type:jwt-bearer
client_assertion string Required Client-signed client_assertion (JWT)
scope string Optional idv.read (idv.read is the default value if omitted)
resource string Optional null (not currently used)