빠른 시작

가입, 계좌 연결, API 키와 웹훅 만들기, 첫 주문 생성, 직접 입금해서 invoice.paid 웹훅 받기까지 페이싱크 연동을 처음부터 끝까지 따라 해요.

계좌를 연결하고, API로 주문을 하나 만들고, 그 주문에 직접 입금해서 결제 완료 웹훅을 받아 봐요. 30분 정도 걸려요.

페이싱크에는 테스트 모드가 없어서 실제 계좌로 실제 돈을 보내 확인해요. 보낸 돈은 내 계좌로 들어오니 금액은 작게 정하세요.

1. 가입하고 워크스페이스 만들기

paysync.kr에서 가입하고 워크스페이스를 하나 만들어요. 만든 사람이 소유자가 되고, 무료 요금제로 시작해요. 무료 요금제로도 결제 주기마다 입금 30건까지 확인할 수 있어요.

멤버 초대와 역할은 워크스페이스와 멤버, 요금제는 요금제와 결제를 참고하세요.

2. 계좌 연결

대시보드 계좌에서 계좌 추가를 누르고 화면 안내를 따라요.

1. 은행, 계좌 유형, 계좌번호를 입력해요.
2. 은행 앱이나 인터넷뱅킹에서 입출금 알림을 신청하고, 받을 번호를 010-8370-0166으로 입력해요.
3. 은행이 인증번호를 보내면 화면에 나온 번호를 은행 앱에 입력해요.
4. 화면에 나온 5자리 코드를 입금자명으로 넣어 그 계좌로 1원을 보내요.

1원 입금이 확인되면 계좌 상태가 연결됨이 돼요. 은행별 신청 경로는 지원 은행, 자세한 절차는 계좌 연결을 참고하세요.

3. API 키 만들기

대시보드 API 키에서 키 만들기를 눌러요. 권한은 읽기·쓰기, 계좌 범위는 모든 계좌로 정해요. 키 값(sk_live_...)은 한 번만 보이니 바로 복사해서 환경변수에 넣어요.

export PAYSYNC_API_KEY="sk_live_..."

권한과 계좌 범위는 API 키를 참고하세요.

4. 웹훅 만들기

결제 완료를 내 서버로 받으려면 웹훅을 만들어요. 아직 서버가 없다면 이 단계는 건너뛰고 6단계에서 API로 상태를 확인해도 돼요.

1. 대시보드 웹훅에서 웹훅 추가를 눌러요.
2. 받을 URL에 이벤트를 받을 공개 주소를 넣어요. 로컬 서버라면 ngrok 같은 터널 주소를 써요.
3. API 버전은 v2 (권장), 받을 이벤트는 invoice.paid를 골라요.
4. 웹훅 목록의 보기에서 서명 키(whsec_...)를 복사해 환경변수에 넣어요.
5. 행 메뉴의 테스트 이벤트 보내기로 내 서버가 받는지 확인해요.

서명 검증 코드는 웹훅 개요에 언어별로 있어요.

5. 주문 만들기

입금자명은 내가 이체할 때 쓸 이름, 금액은 보낼 금액으로 주문을 만들어요.

curl -X POST https://api.paysync.kr/v2/invoices \
  -H "Authorization: Bearer $PAYSYNC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": { "name": "홍길동" },
    "amount": 100,
    "expireAfterDays": 1
  }'

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: "홍길동" },
    amount: 100,
    expireAfterDays: 1,
  }),
});
console.log(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": "홍길동"}, "amount": 100, "expireAfterDays": 1},
)
print(res.json())

응답의 code가 "10001"이면 성공이에요. data.id(ivc_...)는 주문 ID, data.guideUrl은 구매자용 입금 안내 페이지예요. 브라우저로 열어 보세요.

{
  "code": "10001",
  "data": {
    "id": "ivc_a1b2c3d4e5f6g7h8i9j0k1l2",
    "number": 1001,
    "status": "PENDING",
    "customer": { "name": "홍길동", "email": null, "phoneNumber": null },
    "amount": 100,
    "guideUrl": "https://paysync.kr/pay/Xk2f9QaB7cLmN4pR8sTvW1yZ3dE6gH0j",
    "...": "..."
  }
}

필드 전체는 주문 생성을 참고하세요.

6. 입금하고 확인하기

다른 계좌에서 연결한 계좌로 주문 금액을 보내요. 받는 사람에게 표시되는 이름(입금자명)은 주문의 customer.name과 똑같이 넣어요.

은행 입금 문자가 페이싱크에 도착하면 바로 주문을 찾아 결제 완료로 바꿔요. 은행 문자는 보통 이체 직후 오지만, 은행 사정으로 늦을 때도 있어요.

• 웹훅을 만들었다면 invoice.paid 이벤트가 와요.
• 주문 단건 조회로 status가 PAID인지 확인할 수 있어요.

curl https://api.paysync.kr/v2/invoices/ivc_a1b2c3d4e5f6g7h8i9j0k1l2 \
  -H "Authorization: Bearer $PAYSYNC_API_KEY"

대시보드 입금 내역에도 입금이 나와요. 이 입금도 입금 감지 사용량에 한 건으로 세요.

다음 단계