앱 등록 전화번호 검증 확인

Endpoint

PUT https://api.verifik.co/v2/phone-validations

이 엔드포인트는 앱 등록(온보딩) 과정에서 사용자의 전화번호로 전송된 일회용 비밀번호(OTP)를 검증합니다. 사용자가 제공한 OTP가 올바른지 확인하고 검증 상태를 그에 맞게 업데이트합니다. 이 경로는 앱 등록 플로우 중간에 있는 사용자를 위해 특별히 설계되었습니다.

warning

App Registration Phone Validations를 검증할 때 사용해야 하는 JWT 토큰은 App Registration 생성 시 제공됩니다. 이 요청을 인증하려면 App Registration을 생성할 때 반환된 토큰을 사용해야 합니다.

Headers

Name	Value
Content-Type	application/json
Authorization	Bearer <token>

Params

Name	Type	Required	Description
phone	string	Yes	전화 검증을 생성할 때 사용한 전화번호. 처리 중 공백은 자동으로 제거됨
countryCode	string	Yes	+XXX 형식의 전화번호 국가 코드(예: 파나마 +507, 미국 +1). + 뒤에 1~3자리 숫자 형식과 일치해야 함
otp	number	Yes	사용자의 전화번호로 전송된 일회용 비밀번호(OTP)
project	string	No	프로젝트의 고유 식별자. 선택 사항이며 검증 범위를 좁히는 데 도움
projectFlow	string	No	프로젝트 플로우의 고유 식별자. 선택 사항이며 검증 범위를 좁히는 데 도움
phoneGateway	string	No	사용된 전달 방법: sms, whatsapp, 또는 none

Request

Node.js

const fetch = require("node-fetch");

async function run() {
  const res = await fetch("https://api.verifik.co/v2/phone-validations", {
    method: "PUT",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${process.env.VERIFIK_TOKEN}`,
    },
    body: JSON.stringify({
      phone: "62647737",
      countryCode: "+507",
      otp: 123456
    }),
  });
  console.log(await res.json());
}

run();

PHP

<?php
$ch = curl_init("https://api.verifik.co/v2/phone-validations");
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    "Content-Type: application/json",
    "Authorization: Bearer " . getenv("VERIFIK_TOKEN")
]);
$body = json_encode([
    "phone" => "62647737",
    "countryCode" => "+507",
    "otp" => 123456
]);
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, "PUT");
curl_setopt($ch, CURLOPT_POSTFIELDS, $body);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

Python

import os, requests

url = "https://api.verifik.co/v2/phone-validations"
headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {os.getenv('VERIFIK_TOKEN')}"
}
payload = {
    "phone": "62647737",
    "countryCode": "+507",
    "otp": 123456
}
r = requests.put(url, json=payload, headers=headers)
print(r.json())

Go

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
    "os"
)

func main() {
    url := "https://api.verifik.co/v2/phone-validations"
    payload := map[string]interface{}{
        "phone": "62647737",
        "countryCode": "+507",
        "otp": 123456,
    }
    b, _ := json.Marshal(payload)
    req, _ := http.NewRequest("PUT", url, bytes.NewBuffer(b))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("Authorization", "Bearer "+os.Getenv("VERIFIK_TOKEN"))
    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()
    var out map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&out)
    fmt.Println(out)
}

Response

200

{
    "data": {
        "_id": "674de8df21c72be3cc42b8a7",
        "status": "validated",
        "countryCode": "+507",
        "phone": "62647737",
        "type": "onboarding",
        "showFaceLivenessRecommendation": false
    }
}

403

{
    "code": "otp_does_not_match",
    "message": "403:otp_does_not_match"
}

404

{
    "code": "phone_validation_not_found",
    "message": "404:phone_validation_not_found"
}

409

{
    "code": "MissingParameter",
    "message": "missing phone\n. missing countryCode\n. missing otp"
}

409 (Invalid Country Code Format)

{
    "code": "MissingParameter",
    "message": "Invalid countryCode format. CountryCode should be in the format + followed by 1 to 3 digits."
}

412

{
    "code": "phoneValidation_has_expired",
    "message": "412:phoneValidation_has_expired"
}

Notes

• 온보딩 플로우: 이 엔드포인트는 전화 검증이 온보딩 여정의 일부인 앱 등록 과정의 사용자를 위해 특별히 설계되었습니다.
• OTP 만료: OTP는 제한된 수명(일반적으로 10분)을 가지며 미리 정의된 시간이 지나면 만료됩니다. 만료된 OTP는 검증할 수 없습니다.
• 상태 업데이트: 성공적인 검증은 전화 검증 상태를 자동으로 "validated"로 업데이트하며 추가 온보딩 단계를 트리거할 수 있습니다.
• 웹훅 이벤트: 검증 이벤트는 추적 및 통합을 위한 웹훅 알림을 트리거합니다.
• Face Liveness: 일부 프로젝트 플로우는 온보딩 과정의 일부로 전화 검증 후 face liveness 확인을 권장할 수 있습니다.
• App Registration 연결: 이 엔드포인트를 통해 검증되면 전화 검증이 사용자의 앱 등록 레코드에 자동으로 연결됩니다.
• 전화번호 형식: 전화번호의 공백은 처리 중 자동으로 제거됩니다.
• 국가 코드 형식: 국가 코드는 +XXX 형식이어야 하며, X는 숫자입니다(최대 1–3자리).