주문 생성
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원 인증을 마치지 않은 계좌가 있어요. |