📘
POST
/v1/beneficiary/transfer/txid

이 페이지는 송신 VASP가 '자산 이전 결과(txid) 전송'을 통해 txid를 보냈을 때 응답하는 방법에 대해 설명합니다.
이 단계에서 자산을 수신 VASP가 해야 하는 일은 다음과 같습니다.
- 온체인에서 transaction을 감지
- 송신 VASP가 전달해 주는 txid를 받고 적절한 응답 반환
- txid를 저장
- transaction 데이터(Transfer Id)와 txid 매핑
일반적인 프로세스는 자산 이전 허가 요청에 대한 승인 -> 온체인 송금 -> txid 수신 순서로 진행이 되지만, VASP 별 노드 운영 방식과 상황에 따라 온체인 감지와 txid 수신은 순서가 바뀌는 경우도 있을 수 있습니다.
따라서 온체인 트랜잭션 감지되기 전 txid 수신이 먼저되는 경우가 있을 수 있음을 인지해야 합니다.
이 경우 우선 '자산 이전 결과(txid) 전송'에 대해서는 정상 응답을 반환하고, 온체인 데이터 확인 후 고객 자산에 반영하는 방법을 권고 드립니다.
또한 이 전체 프로세스는 프로토콜의 신뢰성을 전제로 하며 상대 VASP가 비정상적인 txid를 송신하지 않는다고 가정합니다.

API 동작 명세

요청으로 전달된 데이터 중 transferId에 해당하는 자산 이전 정보를 찾습니다.
찾아낸 자산 이전 정보의 txid값을 업데이트하고, 자산 이전 상태를 confirmed로 변경합니다.
만약, 업데이트 하려는 transferId에 이미 txid값이 있는 경우, 두 값이 다르면 에러를 반환하고 같다면 정상처리된 것으로 응답합니다.

📘
v1.6까지는 전달받은 Transaction ID 는 블록체인 트랜잭션이 실패하지 않는 단계에서 전달받았지만, 이제는 실패할 수 있습니다. 이 경우 자산을 전송하는 VASP 는 자산 이전 종료 API 를 재차 호출합니다.

Request

이름	필수 여부	타입	설명
transferId	필수	string	'자산 이전 허가 요청' 에서 부여한 UUID로 해당하는 자산 이전 내역에 자산 이전 결과(Transfer ID)를 저장하기 위해 설정
txid	필수	string	가상 자산 이전을 위해 블록체인 상에 실행된 특정한 트랜잭션을 식별하기 위한 고유한 값으로 블록체인 API에 의해서 생성되는 유일한 값
vout	옵션	string	utxo타입 코인은 복수의 블록체인 트랜잭션이 하나의 txid 를 공유하면서 그룹을 형성하기도 하는데, 이때 고유한 트랜잭션을 식별하기 위한 값으로 블록체인 API 의 실행 결과물

{
  "transferId": "b09c8d00-8da9-11ec-b909-0242ac120002",
  "txid": "311BFF73D9B7969CCF1042186180159C724FAB59013A7A034A93E5FB9D6BAFE6",
  "vout": ""
}

Response

이름	필수 여부	타입
transferId	필수	string
result	필수	string
reasonType	옵션	string

transferId: 모든 API 에서 자산 이전 트랜잭션을 구별하기 위한 ID 입니다.

result: 송금 정보 수신 결과 값입니다.

-normal: 요청을 정상적으로 처리하여 전달받은 Transaction ID 를 저장 완료한 상태입니다.

-error: 요청을 처리하는 VASP 에서 요청을 처리하지 못한 상태입니다.

reasonType: result 값이 error 인 경우, 상세 이유를 구분하는 값입니다.

-TXID_ALREADY_EXISTS: 이미 txid 가 저장된 자산 이전 내역에 대해서 다른 txid 를 저장하도록 요청받은 경우입니다. txid 가 한번 생성되면 실패할 수는 있지만 변경되지는 않습니다.

-TRANSFER_ALREADY_FAILED: txid 를 저장하려는 TransferId 에 해당하는 자산 내역이 이미 실패한 경우 txid 를 저장할 수 없습니다.

-UNKNOWN_TRANSFER_ID: Transfer ID 를 찾을 수 없는 경우입니다.

-UNKNOWN: 현재 이 API 에서 발생할 것으로 예상되는 에러 사유가 없습니다.

{
  "transferId": "b09c8d00-8da9-11ec-b909-0242ac120002",
  "result": "normal",
  "reasonType": "TXID_ALREADY_EXISTS"
}