입금 단건 조회
GET /v2/transactions/{id} 로 입금 하나의 계좌, 입금자명, 매칭 결과, 매칭 실패 사유를 조회해요.
GET /v2/transactions/{id}
입금 ID로 입금 하나를 조회해요. 입금 계좌, 입금자명, 매칭된 주문과 매칭 방식을 확인할 수 있어요. 매칭되지 않은 입금이면 이유도 알려 줘요.
경로 파라미터
| 파라미터 | 타입 | 설명 |
|---|---|---|
id |
string | 조회할 입금 ID예요. trx_로 시작해요. |
요청 예시
curl https://api.paysync.kr/v2/transactions/trx_m1n2o3p4q5r6s7t8u9v0w1x2 \
-H "Authorization: Bearer $PAYSYNC_API_KEY"const res = await fetch(`https://api.paysync.kr/v2/transactions/${transactionId}`, {
headers: { Authorization: `Bearer ${process.env.PAYSYNC_API_KEY}` },
});
const { code, data } = await res.json();import os
import requests
res = requests.get(
f"https://api.paysync.kr/v2/transactions/{transaction_id}",
headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
)
print(res.json())응답
{
"code": "10001",
"data": {
"id": "trx_m1n2o3p4q5r6s7t8u9v0w1x2",
"bankAccount": {
"id": "bac_x9y8z7w6v5u4t3s2r1q0p9o8",
"alias": "대표 계좌",
"provider": "KB_KOOKMIN_BANK",
"type": "CORPORATE",
"number": "123456-01-234567"
},
"depositorName": "홍길동",
"amount": 50000,
"receivedAt": 1777346400,
"status": "MATCHED",
"match": {
"invoiceId": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
"invoiceNumber": 1043,
"method": "EXACT",
"automatic": true,
"matchedAt": 1777346412,
"matchedBy": { "type": "SYSTEM", "accountId": null, "apiKeyId": null, "name": null },
"amountDiff": null
},
"failureReason": null,
"candidateCount": null,
"hidden": false,
"hiddenAt": null,
"unmatches": [],
"createdAt": 1777346412
}
}
입금 객체
| 필드 | 타입 | 설명 |
|---|---|---|
id |
string | 입금 ID예요. trx_로 시작해요. |
bankAccount |
object | 입금이 들어온 계좌예요. 아래 표를 참고하세요. |
depositorName |
string | 은행 알림에 적힌 입금자명이에요. |
amount |
integer | 입금 금액(원)이에요. |
receivedAt |
integer | 은행 알림 기준 입금 시각이에요. |
status |
string | MATCHED(매칭됨), UNMATCHED(매칭 안 됨), HIDDEN(대시보드에서 숨김) 중 하나예요. |
match |
object | null | 매칭 정보예요. 매칭되지 않았으면 null이에요. 아래 표를 참고하세요. |
failureReason |
string | null | 자동 매칭에 실패한 이유예요. 아래 표를 참고하세요. |
candidateCount |
integer | null | 매칭에 실패했을 때 금액이 같은 결제 대기 주문 수예요. |
hidden |
boolean | 대시보드에서 숨긴 입금인지 여부예요. API로는 바꿀 수 없어요. |
hiddenAt |
integer | null | 숨긴 시각이에요. |
unmatches |
object[] | 매칭을 해제한 기록이에요. 해제한 적이 없으면 빈 배열이에요. unmatches 항목 참고 |
createdAt |
integer | 페이싱크가 입금을 기록한 시각이에요. |
bankAccount 객체
| 필드 | 타입 | 설명 |
|---|---|---|
id |
string | 계좌 ID예요. bac_로 시작해요. |
alias |
string | 대시보드에서 정한 계좌 별칭이에요. |
provider |
string | 은행이에요. 지원 은행의 API 값 중 하나예요. |
type |
string | PERSONAL(개인) 또는 CORPORATE(기업)예요. |
number |
string | 은행 표기 방식대로 하이픈을 넣은 계좌번호예요. |
bankAccount는 입금을 받은 시점의 계좌 정보예요. 이후 별칭을 바꾸거나 계좌 연결을 해제해도 이미 받은 입금의 값은 바뀌지 않아요.
match 객체
| 필드 | 타입 | 설명 |
|---|---|---|
invoiceId |
string | 매칭된 주문 ID예요. |
invoiceNumber |
integer | 매칭된 주문번호예요. |
method |
string | 매칭 방식이에요. 매칭 방식 확인 참고 |
automatic |
boolean | 자동 매칭이면 true, 대시보드에서 직접 매칭했으면 false예요. |
matchedAt |
integer | 매칭된 시각이에요. |
matchedBy |
object | 매칭한 주체예요. 형식은 주체 객체와 같아요. |
amountDiff |
integer | null | 입금액에서 주문 금액을 뺀 값이에요. 금액이 같으면 null이에요. |
unmatches 항목
매칭 해제는 대시보드에서만 할 수 있어요. 해제할 때마다 항목이 하나씩 쌓여요.
| 필드 | 타입 | 설명 |
|---|---|---|
invoiceId |
string | 매칭을 해제한 주문 ID예요. |
invoiceNumber |
integer | 매칭을 해제한 주문번호예요. |
method |
string | 해제하기 전의 매칭 방식이에요. match.method와 같은 값이에요. |
reason |
string | 해제 사유예요. WRONG_MATCH(잘못 매칭됨), BUYER_REFUND(구매자 환불), OTHER(기타) 중 하나예요. |
note |
string | null | 해제할 때 남긴 메모예요. 메모가 없으면 null이에요. |
unmatchedAt |
integer | 해제한 시각이에요. |
unmatchedBy |
object | 해제한 주체예요. 형식은 주체 객체와 같아요. |
매칭 실패 사유
failureReason |
뜻 |
|---|---|
NO_CANDIDATE |
입금자명과 금액이 맞는 결제 대기 주문이 없어요. |
MULTIPLE_EXACT |
입금자명과 금액이 같은 결제 대기 주문이 여러 건이라 고르지 않았어요. |
MULTIPLE_RULE |
매칭 어시스트 규칙에 맞는 주문이 여러 건이라 고르지 않았어요. |
ONLY_EXPIRED |
맞는 주문이 있지만 입금 기한이 지났어요. |
ONLY_CANCELED |
맞는 주문이 있지만 취소됐어요. |
AMOUNT_MISMATCH |
입금자명이 맞는 결제 대기 주문은 있지만 금액이 달라요. |
오류
| HTTP | code |
발생 조건 |
|---|---|---|
| 401 | 290006 |
API 키가 올바르지 않아요. |
| 403 | 80002 |
API 키의 계좌 범위 밖의 계좌로 들어온 입금이에요. |
| 404 | 20013 |
입금이 없어요. |
| 422 | 210001 |
입금 ID 형식이 틀렸어요. |