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

주문 생성

POST /v2/invoices 로 결제받을 주문을 만들어요.

POST /v2/invoices

결제받을 주문을 만들어요. 받을 계좌에 입금자명과 금액이 모두 같은 입금이 들어오면 페이싱크가 주문을 결제 완료로 바꾸고 invoice.paid 웹훅을 보내요. 주문을 만들면 invoice.created 웹훅도 가요.

v1 API로 만들던 방식은 주문 생성 (v1)을 참고하세요. v2에서는 bankAccountIds를 빼도 되고, 만료는 expireAfter 문자열 대신 expiresAt이나 expireAfterDays로 정해요.

요청 본문

필드 타입 필수 설명
customer.name string 예 입금자명이에요. 1~16자, 공백 없이 입력해요. 앞뒤 공백은 지우고 저장해요.
customer.email string 구매자 이메일이에요. 5~255자예요. 입금 안내 메일과 결제 완료 메일을 이 주소로 보내요.
customer.phoneNumber string 구매자 전화번호예요. 숫자 10~11자리예요. 하이픈과 공백은 빼고 저장해요.
amount integer 예 금액(원)이에요. 0보다 커야 해요.
bankAccountIds string[] 입금받을 계좌 ID 목록이에요. 빼거나 빈 배열이면 워크스페이스의 모든 계좌로 받아요. 1원 인증을 마친 계좌만 넣을 수 있어요. 다중 계좌 라우팅 참고
expiresAt integer 입금 기한이에요. Unix 초로 보내요. 지금보다 뒤이고 365일 안이어야 해요.
expireAfterDays integer 지금부터 며칠 뒤에 만료할지 정해요. 1~365예요. expiresAt과 함께 보낼 수 없어요.
cashReceipt.type string 현금영수증 종류예요. PERSONAL(소득공제용) 또는 CORPORATE(지출증빙용)예요.
cashReceipt.identifier string PERSONAL이면 휴대폰 번호나 현금영수증 카드 번호(숫자 10~18자리), CORPORATE이면 사업자등록번호(숫자 10자리)예요. 하이픈과 공백은 빼고 저장해요.
metadata object 주문에 함께 저장할 문자열 키와 값이에요. 최대 5쌍, 키 1~64자, 값 1024자까지 넣을 수 있어요.
sendGuideEmail boolean 구매자에게 입금 안내 메일을 보낼지 정해요. 빼면 자동화 설정을 따라요.

expiresAt과 expireAfterDays를 모두 빼면 만료되지 않는 주문이 만들어져요.

만료

입금 기한이 지나면 페이싱크가 1분 안에 주문을 EXPIRED로 바꾸고 invoice.expired 웹훅을 보내요. 만료된 주문은 자동 매칭에서 빠지지만, 대시보드에서 입금을 직접 매칭하거나 결제 완료 처리할 수 있어요.

현금영수증 자동 발급

cashReceipt를 넣으면 주문이 결제 완료될 때 페이싱크가 현금영수증을 발급해요. 이 조건을 모두 갖춰야 해요.

  • 워크스페이스 소유자가 대시보드 설정 > 일반에서 사업자 정보를 등록했어요.
  • 대시보드 현금영수증 > 발급 설정에서 입금 확인 시 자동 발급이 켜져 있어요. 기본값은 켜짐이에요.
  • 이 주문으로 발급했거나 발급 중인 현금영수증이 없어요.

발급 금액은 실제로 받은 금액(paidAmount)이에요. 결과는 현금영수증 목록 조회에서 invoiceId로 확인하세요. cashReceipt가 없는 주문도 자진발급을 켰다면 기준 금액 이상일 때 자진발급해요.

metadata 활용

쇼핑몰 주문 ID 같은 내 시스템의 값을 넣어 두면 웹훅을 받았을 때 바로 주문을 찾을 수 있어요. CAFE24_, SIXSHOP_으로 시작하는 키는 카페24 연동과 식스샵 프로 연동에서 쓰니 피하세요.

요청 예시

curl -X POST https://api.paysync.kr/v2/invoices \
  -H "Authorization: Bearer $PAYSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "홍길동",
      "email": "hong@example.com",
      "phoneNumber": "01012345678"
    },
    "amount": 50000,
    "expireAfterDays": 1,
    "cashReceipt": { "type": "PERSONAL", "identifier": "01012345678" },
    "metadata": { "orderId": "ORDER-2026-0001" }
  }'
const res = await fetch("https://api.paysync.kr/v2/invoices", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.PAYSYNC_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    customer: { name: "홍길동", email: "hong@example.com", phoneNumber: "01012345678" },
    amount: 50000,
    expireAfterDays: 1,
    cashReceipt: { type: "PERSONAL", identifier: "01012345678" },
    metadata: { orderId: "ORDER-2026-0001" },
  }),
});
const { code, data } = await res.json();
import os
import requests

res = requests.post(
    "https://api.paysync.kr/v2/invoices",
    headers={"Authorization": f"Bearer {os.environ['PAYSYNC_API_KEY']}"},
    json={
        "customer": {"name": "홍길동", "email": "hong@example.com", "phoneNumber": "01012345678"},
        "amount": 50000,
        "expireAfterDays": 1,
        "cashReceipt": {"type": "PERSONAL", "identifier": "01012345678"},
        "metadata": {"orderId": "ORDER-2026-0001"},
    },
)
print(res.json())

응답

HTTP 200과 함께 만든 주문 객체가 와요. 단건 조회와 달리 history는 없어요.

{
  "code": "10001",
  "data": {
    "id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
    "number": 1043,
    "status": "PENDING",
    "customer": {
      "name": "홍길동",
      "email": "hong@example.com",
      "phoneNumber": "01012345678"
    },
    "amount": 50000,
    "paidAmount": null,
    "amountDiff": null,
    "bankAccountIds": [],
    "cashReceipt": { "type": "PERSONAL", "identifier": "01012345678" },
    "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": 1777346055,
    "createdAt": 1777346055,
    "updatedAt": null,
    "expiresAt": 1777432455,
    "paidAt": null,
    "paidTrigger": null,
    "paidBy": null,
    "matchedTransactionId": null,
    "canceledAt": null,
    "cancelReason": null,
    "canceledBy": null,
    "expiredAt": null,
    "reopenedAt": null
  }
}

오류

HTTP code 발생 조건
401 290006 API 키가 올바르지 않아요.
403 80002 bankAccountIds에 API 키의 계좌 범위 밖의 계좌가 있거나, 계좌를 제한한 키로 bankAccountIds를 비웠어요.
403 290007 읽기 전용 API 키예요.
409 220010 입금자명과 금액이 같고 받을 계좌가 겹치는 결제 대기 주문이 이미 있어요. data에 기존 주문의 invoiceId와 number가 와요. 주문 충돌 규칙 참고
422 30007 JSON 본문을 읽을 수 없거나 customer.name, amount가 없어요.
422 220002 customer.name이 1~16자가 아니거나 공백이 있어요.
422 220003 amount가 0 이하예요.
422 220004 customer.email 형식이나 길이가 맞지 않아요.
422 220005 customer.phoneNumber가 숫자 10~11자리가 아니에요.
422 220006 expiresAt이 지났거나 365일 뒤를 넘어요. expireAfterDays가 1~365가 아니거나 expiresAt과 함께 보냈어요.
422 220007 cashReceipt.type이나 cashReceipt.identifier가 올바르지 않아요.
422 220008 metadata가 5쌍을 넘거나 키, 값 길이가 맞지 않아요.
422 220009 bankAccountIds에 형식이 틀렸거나 없는 계좌 ID가 있어요.
422 220018 bankAccountIds에 1원 인증을 마치지 않은 계좌가 있어요.

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