주문 단건 조회
GET /v2/invoices/{id} 로 주문 하나의 상세 정보와 처리 이력을 조회해요.
GET /v2/invoices/{id}
주문 ID로 주문 하나를 조회해요. 상태는 status로 확인해요. 결제 완료를 바로 알아야 한다면 폴링보다 invoice.paid 웹훅을 쓰세요.
경로 파라미터
| 파라미터 | 타입 | 설명 |
|---|---|---|
id |
string | 조회할 주문 ID예요. ivc_로 시작해요. |
요청 예시
curl https://api.paysync.kr/v2/invoices/ivc_a1b2c3d4e5f6g7h8i9j0k1l2 \
-H "Authorization: Bearer $PAYSYNC_API_KEY"const res = await fetch(`https://api.paysync.kr/v2/invoices/${invoiceId}`, {
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/invoices/{invoice_id}",
headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
)
print(res.json())응답
{
"code": "10001",
"data": {
"id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
"number": 1043,
"status": "PAID",
"customer": {
"name": "홍길동",
"email": "hong@example.com",
"phoneNumber": "01012345678"
},
"amount": 50000,
"paidAmount": 50000,
"amountDiff": null,
"bankAccountIds": [],
"cashReceipt": null,
"metadata": { "orderId": "ORDER-2026-0001" },
"source": "API",
"createdBy": {
"type": "API_KEY",
"accountId": null,
"apiKeyId": "apk_k3l4m5n6o7p8q9r0s1t2u3v4",
"name": "쇼핑몰 서버"
},
"shopOrder": null,
"guideUrl": "https://paysync.kr/pay/Xk2f9QaB7cLmN4pR8sTvW1yZ3dE6gH0j",
"guideEmailSentAt": null,
"createdAt": 1777346055,
"updatedAt": 1777346412,
"expiresAt": 1777432455,
"paidAt": 1777346412,
"paidTrigger": "AUTOMATIC_MATCHING",
"paidBy": { "type": "SYSTEM", "accountId": null, "apiKeyId": null, "name": null },
"matchedTransactionId": "trx_m1n2o3p4q5r6s7t8u9v0w1x2",
"canceledAt": null,
"cancelReason": null,
"canceledBy": null,
"expiredAt": null,
"reopenedAt": null,
"history": [
{
"type": "CREATED",
"at": 1777346055,
"actor": { "type": "API_KEY", "accountId": null, "apiKeyId": "apk_k3l4m5n6o7p8q9r0s1t2u3v4", "name": "쇼핑몰 서버" },
"detail": null,
"changes": []
},
{
"type": "PAID",
"at": 1777346412,
"actor": { "type": "SYSTEM", "accountId": null, "apiKeyId": null, "name": null },
"detail": null,
"changes": []
}
]
}
}
주문 객체
| 필드 | 타입 | 설명 |
|---|---|---|
id |
string | 주문 ID예요. ivc_로 시작해요. |
number |
integer | 워크스페이스 안의 주문번호예요. 1001부터 매겨요. |
status |
string | 주문 상태예요. 아래 표를 참고하세요. |
customer.name |
string | 입금자명이에요. |
customer.email |
string | null | 구매자 이메일이에요. |
customer.phoneNumber |
string | null | 구매자 전화번호예요. |
amount |
integer | 주문 금액(원)이에요. |
paidAmount |
integer | null | 실제로 받은 금액이에요. 결제 완료 전에는 null이에요. |
amountDiff |
integer | null | paidAmount에서 amount를 뺀 값이에요. 같으면 null이에요. 금액이 다른 입금을 대시보드에서 직접 매칭했거나, 2026년 10월에 없어진 금액이 조금 달라도 매칭 규칙으로 그 전에 매칭됐을 때 생겨요. |
bankAccountIds |
string[] | 입금받을 계좌 ID 목록이에요. 빈 배열이면 모든 계좌로 받아요. |
cashReceipt |
object | null | 결제 완료 때 발급할 현금영수증 정보예요. type과 identifier를 담아요. |
metadata |
object | 주문을 만들 때 넣은 키와 값이에요. 없으면 빈 객체예요. |
source |
string | 주문을 만든 곳이에요. API, DASHBOARD, CSV, CAFE24, SIXSHOP, GODOMALL 중 하나예요. |
createdBy |
object | 주문을 만든 주체예요. 주체 객체 참고 |
shopOrder |
object | null | 쇼핑몰 주문으로 만든 주문의 쇼핑몰 주문 정보예요. 아니면 null이에요. shopOrder 객체 참고 |
guideUrl |
string | 구매자용 입금 안내 페이지 주소예요. 입금 안내 페이지 참고 |
guideEmailSentAt |
integer | null | 입금 안내 메일을 마지막으로 보낸 시각이에요. |
createdAt |
integer | 주문을 만든 시각이에요. |
updatedAt |
integer | null | 주문이 마지막으로 바뀐 시각이에요. |
expiresAt |
integer | null | 입금 기한이에요. 기한 없이 만들었으면 null이에요. |
paidAt |
integer | null | 결제 완료된 시각이에요. |
paidTrigger |
string | null | 결제 완료 경로예요. AUTOMATIC_MATCHING, MANUAL_MATCHING, MANUAL_APPROVE, API_CALL 중 하나예요. invoice.paid 참고 |
paidBy |
object | null | 결제 완료로 바꾼 주체예요. |
matchedTransactionId |
string | null | 매칭된 입금 ID예요. 입금 없이 결제 완료 처리했으면 null이에요. |
canceledAt |
integer | null | 취소된 시각이에요. |
cancelReason |
string | null | 취소 사유예요. |
canceledBy |
object | null | 취소한 주체예요. |
expiredAt |
integer | null | 만료 처리된 시각이에요. |
reopenedAt |
integer | null | 매칭이 해제돼 결제 대기로 돌아간 시각이에요. |
history |
object[] | 처리 이력이에요. 단건 조회에만 있어요. |
시각은 모두 Unix 초예요.
주문 상태
status |
뜻 |
|---|---|
PENDING |
결제 대기예요. 입금이 들어오면 자동 매칭돼요. |
PAID |
결제 완료예요. |
EXPIRED |
입금 기한이 지났어요. 자동 매칭에서 빠지지만 수동 매칭과 결제 완료 처리는 할 수 있어요. |
CANCELED |
취소됐어요. 입금을 매칭할 수 없어요. |
대시보드에서 매칭을 해제하면 PAID 주문이 PENDING으로 돌아가요. 입금 기한이 이미 지났다면 EXPIRED로 돌아가요. 이때 invoice.reopened 웹훅이 가요.
주체 객체
createdBy, paidBy, canceledBy, history[].actor의 형식이에요.
| 필드 | 타입 | 설명 |
|---|---|---|
type |
string | MEMBER(대시보드 멤버), API_KEY, CONNECTED_APP(연결된 앱), SYSTEM(자동 매칭, 만료, 쇼핑몰 연동 등) 중 하나예요. |
accountId |
string | null | 멤버의 계정 ID예요. |
apiKeyId |
string | null | API 키 ID예요. |
name |
string | null | 멤버 이름, API 키 이름, 연결된 앱 이름이에요. 카페24로 만든 주문은 카페24 {쇼핑몰 아이디}, 식스샵으로 만든 주문은 식스샵 {스토어 아이디}예요. |
shopOrder 객체
| 필드 | 타입 | 설명 |
|---|---|---|
platform |
string | 쇼핑몰 플랫폼이에요. CAFE24, SIXSHOP, GODOMALL 중 하나예요. |
storeId |
string | 쇼핑몰 아이디예요. 카페24는 쇼핑몰 아이디(myshop.cafe24.com의 myshop), 식스샵은 스토어 아이디예요. |
shopNo |
integer | null | 멀티쇼핑몰 번호예요. 카페24 기본 쇼핑몰은 1이에요. 멀티쇼핑몰이 없는 플랫폼은 null이에요. |
orderId |
string | 쇼핑몰 주문번호예요. |
처리 이력
| 필드 | 타입 | 설명 |
|---|---|---|
type |
string | CREATED, GUIDE_EMAIL_SENT, GUIDE_RESENT, UPDATED, PAID, EXPIRED, CANCELED, REOPENED 중 하나예요. |
at |
integer | 일어난 시각이에요. |
actor |
object | null | 처리한 주체예요. |
detail |
string | null | 취소 사유 같은 추가 설명이에요. |
changes |
object[] | UPDATED에서 바뀐 필드예요. field, before, after를 담아요. |
오류
| HTTP | code |
발생 조건 |
|---|---|---|
| 401 | 290006 |
API 키가 올바르지 않아요. |
| 403 | 80002 |
API 키의 계좌 범위 밖의 주문이에요. |
| 404 | 20014 |
주문이 없어요. |
| 422 | 220001 |
주문 ID 형식이 틀렸어요. |