본문으로 건너뛰기
페이싱크 개발자센터
Esc
↑↓이동↵열기⌘J미리보기
이 페이지에서

주문 단건 조회

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 형식이 틀렸어요.

이 페이지가 도움이 되었나요?