트랜잭션 상태 문의 API

트랜잭션 상태 문의

POST http://<enclave-endpoint>/v1/verifications/tx/inquiry

Originating VASP로부터 일정 시간 동안 트랜잭션 아이디 (Transaction hash, txHash)를 리포트 받지 못했을 경우, 트랜잭션 상태를 질의할 수 있습니다.

호출 정책

• 수신 VASP에서 입금을 감지하면 먼저 txHash 필터링과 함께 검증 결과 조회 API를 호출하여 매칭되는 검증 이력이 있는지 검색할 수 있습니다.

• 만약 txHash가 매칭되는 것이 아직 없다면, 송신 VASP에서 트랜잭션 리포트 API를 호출하기를 일정 시간 기다릴 수 있습니다.

• 일정 시간 이후, 송신 VASP로부터 아직 트랜잭션 리포트가 오지 않았다면, 검증 결과 조회 API를 통해 candidate verification을 추릴 수 있습니다.

  • 이때 감지된 입금의 from 주소와 to 주소를 각각 originator account number와 beneficiary account number로 설정하여 검색하면 범위를 좁힐 수 있습니다.

  • 또한 실제 전송된 가상 자산의 수량을 비교하면 범위를 더욱더 좁힐 수 있습니다.

• 이렇게 추린 candidate verification 들에 대해 각각 트랜잭션 상태 문의 API를 호출하여 트랜잭션 ID 정보를 매칭할 수 있습니다.

Request Body

Request Body Examples

{
    "verificationUuid": "8557f2b2-985e-431f-8d52-75c2e5a01e46"
}

Field Name	Data Type	Required	Example	Description
verificationUuid	string	true	“8557f2b2-985e-431f-8d52-75c2e5a01e46”	트랜잭션 처리 상태를 조회할 verification의 UUID. 실제 Transaction을 블록체인에 보내기 전에, 수행했던 검증(/verifications) 과정에서 키로 사용하였던 UUID입니다.

Response Body

성공 케이스

Response Body Examples

• 200 OK

{
  "verificationUuid": "8557f2b2-985e-431f-8d52-75c2e5a01e46",
  "transactionStatus": "PROCESSING",
  "txHash": ""
}

• 200 OK

{
  "verificationUuid": "8557f2b2-985e-431f-8d52-75c2e5a01e46",
  "transactionStatus": "CONFIRMED",
  "txHash": "8a54d58ca4100112a5430818776d74898f2232770bae03046862575cb851a042",
  "vout": "2"
}

Field Name	Data Type	Required	Example	Description
verificationUuid	string	true	"8557f2b2-985e-431f-8d52-75c2e5a01e46"	트랜잭션 처리 상태를 조회한 verification의 uuid
transactionStatus	string	true	"PROCESSING"	트랜잭션의 처리 상태. (하단 설명 참조)
txHash	string	false	"8a54d58ca4100112a5430818776d74898f2232770bae03046862575cb851a042"	트랜잭션의 id (transaction hash), 알 수 있는 경우에만 반환
vout	string	false	"2"	트랜잭션 내에서 몇 번째 거래에 해당하는지를 나타내는 인덱스 값, 알 수 있는 경우에만 반환

• transactionStatus 필드에는 다음과 같은 값이 들어갈 수 있습니다.

  • PENDING: 어떤 이유에서든 아직 블록체인 트랜잭션을 보내지 않고 대기하고 있는 상태

  • PROCESSING: 블록체인에 트랜잭션을 전송했고 채굴 대기 중인 상태

  • WAIT-CONFIRM: 블록체인 트랜잭션이 채굴이 된 것을 확인했지만 아직 finality를 확보하지 못한 상태

  • CONFIRMED: 블록체인 트랜잭션이 채굴되었고 finality도 확보된 상태

  • CANCELED: 블록체인 트랜잭션을 보내지 않고 취소한 상태 혹은 보냈는데 취소한 상태 (영구히 취소된 경우)

실패 케이스

필수 파라미터를 입력하지 않은 경우

Response Body Examples

• 400 Bad Request

{
  "code": "MISSING-VERIFICATION-UUID",
  "message": "`verificationUuid` is required."
}

존재하지 않는 verification uuid를 입력한 경우

Response Body Examples

• 400 Bad Request

{
  "code": "VERIFICATION-NOT-FOUND",
  "message": "Verification(9faab87c-54a6-4145-baa9-7a3a42d7410c) is not found"
}

beneficiary VASP이 아닌 다른 VASP이 이 API를 호출했을 경우

Response Body Examples

• 400 Bad Request

{
  "code": "VASP-NOT-MATCHED",
  "message": "You are not the beneficiary VASP for the verification"
}