베트남 결제 API 문서 | ucake API Docs

지급 API

POST /vnpay/api/v1/payment

이 API를 호출해 사용자 은행 계좌로 자금을 지급합니다.

요청 필드

• amount - integer - 필수 - 지급 금액. 범위: 50,000~50,000,000.
• orderNo - string - 필수 - 가맹점 주문번호. 각 요청마다 고유해야 합니다.
• accountName - string - 필수 - 사용자 이름
• phoneNo - string - 선택 - 사용자 휴대폰 번호
• accountNo - string - 필수 - 사용자 계좌번호
• accountType - integer - 필수 - 계좌 유형: 0 계좌번호, 1 카드번호.
• bankCode - string - 필수 - 은행 코드
• message - string - 필수 - 지급 메모
• returnURL - string - 필수 - 콜백 알림 URL
• companyID - string - 필수 - 백엔드에서 할당한 회사 ID입니다.
• merchantID - string - 필수 - 백엔드에서 할당한 가맹점 ID입니다.
• timestamp - number - 필수 - 타임스탬프
• sign - string - 필수 - 서명

응답 필드

• amount - integer - 거래 금액
• orderNo - string - 요청으로 전달된 가맹점 주문번호입니다.
• tradeNo - string - 거래 일련번호
• createTime - string - 거래 생성 시간. 형식: yyyy-MM-dd HH:mm:ss.
• updateTime - string - 거래 최종 업데이트 시간입니다.
• bankCode - string - 은행 코드
• phoneNo - string - 휴대폰 번호
• accountName - string - 사용자 이름
• accountNo - string - 사용자 계좌번호
• accountType - integer - 계좌 유형
• message - String - 메모

지급 결과 조회 API

GET /vnpay/api/v1/paymentResult

지급이 처리 중이면 알림을 기다리거나 직접 결과를 조회할 수 있습니다.

요청 필드

• orderNo - string - 필수 - 지급 API에 전달한 주문번호입니다.
• tradeNo - string - 필수 - 지급 API가 반환한 거래 일련번호입니다.
• companyID - string - 필수 - 백엔드에서 할당한 회사 ID입니다.
• merchantID - string - 필수 - 백엔드에서 할당한 가맹점 ID입니다.
• sign - string - 필수 - 서명
• timestamp - number - 필수 - 타임스탬프

응답 필드

• amount - integer - 거래 금액
• orderNo - string - 가맹점 주문번호
• tradeNo - string - 거래 일련번호
• createTime - string - 거래 생성 시간
• updateTime - string - 거래 최종 업데이트 시간입니다.
• bankCode - string - 은행 코드
• phoneNo - string - 휴대폰 번호
• accountName - string - 사용자 이름
• accountNo - string - 사용자 계좌번호
• accountType - integer - 계좌 유형
• message - string - 메모

가상 계좌 생성

POST /vnpay/api/v1/createVirtualCard

가상 계좌를 생성하고 계좌번호, QRCode 문자열, VietQR 이미지 링크를 반환합니다.

요청 필드

• orderNo - string - 필수 - 거래 주문번호
• accountName - string - 선택 - 가상 계좌명
• phoneNo - string - 선택 - 사용자 휴대폰 번호
• bankCode - string - 선택 - 가상 계좌를 신청할 은행입니다.
• companyID - string - 필수 - 백엔드에서 할당한 회사 ID입니다.
• merchantID - string - 필수 - 백엔드에서 할당한 가맹점 ID입니다.
• timestamp - string - 필수 - 타임스탬프
• sign - string - 필수 - 서명
• totalFee - Long - 선택 - 수금 금액

응답 필드

• orderNo - string - 거래 주문번호
• bankCode - string - 은행 코드
• accountName - string - 계좌명
• accountNo - string - 계좌번호
• accountStatus - integer - 상태: 0 종료, 1 정상.
• createdTime - string - 생성 시간
• expireTime - string - 만료 시간
• closeTime - string - 종료 시간
• QRCode - String - QR 코드 문자열 정보
• QRImgUrl - String - VietQR 이미지 링크

가상 계좌 종료

POST /vnpay/api/v1/closeVirtualCard

지정한 가상 계좌를 종료하고 종료 후 계좌 상태를 반환합니다.

요청 필드

• accountNo - string - 선택 - 생성 시 반환된 은행 계좌번호입니다.
• bankCode - string - 선택 - 은행 코드
• companyID - string - 선택 - 백엔드에서 할당한 회사 ID입니다.
• merchantID - string - 선택 - 백엔드에서 할당한 가맹점 ID입니다.
• timestamp - integer - 선택 - 타임스탬프
• sign - string - 선택 - 서명

응답 필드

• bankCode - string - 은행 코드
• accountName - string - 계좌명
• accountNo - string - 계좌번호
• accountStatus - integer - 상태: 0 종료, 1 정상.
• createdTime - string - 생성 시간
• expireTime - string - 만료 시간
• closeTime - string - 종료 시간

가상 계좌 조회

GET /vnpay/api/v1/queryVirtualCard

bankCode, accountName, accountNo로 가상 계좌 상태를 조회합니다.

요청 필드

• bankCode - string - 예 - 은행 코드
• accountName - string - 예 - 계좌명
• accountNo - string - 예 - 계좌번호
• companyID - string - 예 - 백엔드에서 할당한 회사 ID입니다.
• merchantID - string - 예 - 백엔드에서 할당한 가맹점 ID입니다.
• sign - string - 예 - 서명
• timestamp - string - 예 - 타임스탬프

응답 필드

• bankCode - string - 은행 코드
• accountName - string - 계좌명
• accountNo - string - 계좌번호
• accountStatus - integer - 상태: 0 종료, 1 정상.
• createdTime - string - 생성 시간
• expireTime - string - 만료 시간
• closeTime - string - 종료 시간

회사 잔액 조회

POST /vnpay/api/v1/queryBalance

회사 계좌의 현재 잔액을 조회합니다.

요청 필드

• companyID - string - 필수 - 백엔드에서 할당한 회사 ID입니다.
• merchantID - string - 필수 - 백엔드에서 할당한 가맹점 ID입니다.
• sign - string - 필수 - 서명
• timestamp - integer - 필수 - 타임스탬프

응답 필드

• companyID - string - 백엔드에서 할당한 회사 ID입니다.
• merchantID - string - 백엔드에서 할당한 가맹점 ID입니다.
• balance - string - 회사 현재 잔액

동적 QR 생성

POST /vnpay/api/v1/createDynamicQr

지정 금액의 동적 QR을 생성하고 QR 문자열과 만료 시간을 반환합니다.

요청 필드

• merchantID - string - 필수 - 백엔드에서 할당한 가맹점 ID입니다.
• companyID - string - 필수 - 백엔드에서 할당한 회사 ID입니다.
• orderNo - string - 필수 - 거래 주문번호
• amount - Long - 필수 - 수금 금액
• message - string - 선택 - 메모
• timestamp - string - 필수 - 타임스탬프
• sign - string - 필수 - 서명

응답 필드

• orderNo - string - 거래 주문번호
• amount - Long - 수금 금액
• expiresAt - string - 동적 QR 만료 시간
• qrCode - String - QR 코드 문자열 정보

지급 결과 알림

지급 API에 전달한 URL입니다.

처리 중인 지급의 최종 결과가 나오면 지급 API에 전달한 URL로 알림을 보냅니다.

• companyID - string - 회사 ID
• merchantID - string - 가맹점 ID
• orderNo - string - 가맹점 주문번호
• tradeNo - string - 거래 일련번호
• bankCode - string - 은행 코드
• accountNo - string - 계좌번호
• amount - number - 거래 금액
• message - string - 지급 메모
• result - String - 거래 실패 시 오류 원인입니다.
• updateTime - String - 거래 업데이트 시간
• status - number - 거래 상태: 0 성공, 3 실패, 4 취소.
• sign - string - 서명

수금 결과 알림

가맹점 백엔드에 설정된 알림 URL입니다.

가상 계좌가 입금을 받으면 수금 정보를 파트너에게 보냅니다.

• companyID - string - 회사 ID
• merchantID - string - 가맹점 ID
• orderNo - string - 가맹점 주문번호
• tradeNo - string - 거래 일련번호
• bankCode - string - 은행 코드
• accountNo - string - 가상 계좌번호
• amount - number - 수금 금액
• message - string - 결제 시스템이 반환한 거래 정보입니다.
• senderName - string - 지급인
• senderAccount - string - 지급 계좌
• senderBankCode - string - 지급 은행 코드
• sign - string - 서명

환불 알림

가맹점 백엔드에 설정된 환불 알림 URL입니다.

주문 환불이 성공하면 환불 정보를 파트너에게 보냅니다.

• companyID - string - 회사 ID
• merchantID - string - 가맹점 ID
• orderNo - string - 가맹점 주문번호
• tradeNo - string - 거래 일련번호
• bankCode - string - 은행 코드
• accountNo - string - 은행 계좌번호
• amount - number - 거래 금액
• updateTime - string - 업데이트 시간
• status - string - 상태: 5 환불 완료.
• sign - string - 서명