가맹점 API 설명서

가맹점 사이트에 EGG PAY 를 붙이면, 사용자가 결제한 금액만큼 USDE 가 가맹점 지갑으로 전송됩니다.

1. 시작하기

1. 가맹점 신청을 하면 검토 후 알려 드립니다.
2. 승인되면 가맹점 코드와 API 키를 드립니다.
3. 사용자가 지갑 연동을 마쳐야 결제할 수 있습니다 (3절).
4. 사용자가 거래소 회원이어야 결제할 수 있습니다. 연동 확인의 exchange.ready 로 보실 수 있습니다 (3절).

결제 순서

1. 가맹점 사이트에서 충전 요청 — 가맹점 서버가 결제 요청을 부릅니다 (5절)
2. 로그인 (회원이 아니면 회원가입) — 방식마다 다릅니다 (5절)
3. 구매 등록
4. 매칭
5. 지갑 앱으로 이동
6. 서명
7. 컨트랙트 시작 — 끝나면 결과를 보내 드립니다 (6절)

가맹점이 하시는 곳은 결제 요청, API 만 방식의 구매 등록, 그리고 결과 받기(웹훅 · 상태 조회)입니다.

2. 인증

모든 요청에 두 헤더를 넣습니다.

키는 둘입니다. API 키는 가맹점이 우리를 부를 때, 웹훅 비밀키는 우리가 가맹점을 부를 때 씁니다 (6절).

호출 한도 (가맹점 하나당, 분당)

표의 값은 기본값입니다. 넘으면 429 와 함께 retryAfterSeconds 를 돌려드립니다.

공통 모양

3. 지갑 연동

사용자가 SJO 지갑앱을 설치하고, 계정 주소를 만들고, 가맹점 회원 아이디에 그 주소를 연동해 두어야 결제할 수 있습니다.

연동 시작

POST /api/v1/merchant/wallet-links

{ "linkId": "…", "status": "PENDING", "expiresAt": "…" }

이 뒤로 사용자의 지갑앱에 알림이 가고, 사용자가 지갑앱에서 서명으로 승인하면 연동이 끝납니다. 옮겨 칠 숫자는 없습니다. 요청은 5분 동안 살아 있습니다 (expiresAt). 같은 회원·같은 주소로 다시 부르시면 살아 있는 요청을 그대로 드립니다. 같은 회원·같은 주소가 이미 연동돼 있으면 새 요청을 만들지 않고 그 연동을 "status": "LINKED" 로 드립니다.

한 가맹점 안에서 지갑 하나는 회원 하나에만 연동됩니다. 그 회원이 이미 다른 주소로, 또는 그 주소가 다른 회원으로 연동돼 있으면 409 wallet_link_conflict 입니다. 살아 있는 요청(5분 안)도 같습니다 — 그 회원의 다른 주소 요청, 또는 그 주소의 다른 회원 요청이 살아 있으면 409 wallet_link_conflict 입니다. 5분이 지난 요청은 막지 않습니다. 바꾸시려면 연동은 연동 해제 뒤, 요청은 expiresAt 이 지난 뒤 다시 시작해 주십시오. 그 주소의 지갑 사용자가 없으면 422 wallet_undeliverable 입니다.

연동 확인

GET /api/v1/merchant/wallet-links/{merchantUserId}

결제 버튼을 그리기 전에 부르십시오. 연동되고 거래소 준비가 된 사용자만 결제할 수 있습니다.

{ "linked": true, "status": "LINKED", "walletAddress": "sjo1…", "linkedAt": "…",
  "exchange": { "ready": true, "reason": null } }

이름 · 거래소 아이디 같은 개인정보는 싣지 않습니다.

연동 해제

DELETE /api/v1/merchant/wallet-links/{merchantUserId}

{ "linked": false }

그 지갑으로 진행 중인 결제가 있으면 409 payment_in_flight 입니다. 연동된 것이 없으면 404 입니다. 새 주소는 연동 시작부터 다시 해 주십시오.

4. 환율

GET /api/v1/rates

키가 필요 없습니다. 사용자가 금액을 치는 동안 브라우저에서 바로 불러 환산해 보여주실 수 있습니다. IP 하나당 분당 120회입니다 (기본값).

{ "base": "USDE", "quote": "…", "rate": …, "asOf": "…" }

환율을 지금 확인할 수 없을 때는 503 과 rate_unavailable 을 드립니다. 이전 값을 대신 드리지 않습니다 — 잠시 후 다시 불러 주십시오.

{ "error": { "code": "rate_unavailable", "message": "…" } }

5. 결제

방식 셋

결제를 요청할 때 mode 로 고르십니다. 로그인과 구매 등록만 다르고, 매칭부터는 같습니다.

결제 요청

POST /api/v1/payments

{ "paymentId": "pay_…", "status": "REQUESTED", "statusReason": null,
  "popupUrl": "https://…", "created": true }

• 이때는 거래소 주문이 생기지 않습니다. 주문은 구매 등록에서 생깁니다.
• 같은 merchantRequestId 로 다시 보내시면 같은 결제입니다. 결제를 만들지 않은 거절은 남기지 않습니다 — 같은 키로 다시 부르시면 그때 상태로 다시 봅니다.
• 구매자 지갑 하나에 진행 중인 결제는 1건입니다 — 있으면 409 payment_in_flight.
• USDE 가 멈췄으면 503 usde_paused, 멈춤 상태를 읽지 못했으면 503 chain_unavailable 입니다. 둘 다 결제를 만들지 않았습니다 — chain_unavailable 은 같은 merchantRequestId 로 다시 부르시면 됩니다.
• 수량은 지갑 앱 · 팝업에서 바꿀 수 없습니다.

필드가 하나라도 없거나 잘못되면 거절합니다 (10절). 그때는 가맹점 화면에서 경고를 띄워 주십시오.

팝업 열기

popup_wallet · popup_password 만 해당합니다.

window.open(popupUrl, '_blank', 'noopener,noreferrer')

새 창으로 여십시오. 틀(iframe) 안에 넣지 마십시오 — 팝업은 거래소 화면입니다. PC 와 모바일 둘 다 됩니다.

구매 등록

api 만 해당합니다.

POST /api/v1/payments/{paymentId}/purchase

본문은 없습니다. 사용자가 지갑 앱에서 로그인을 승인한 뒤 5분 안에 가맹점 화면의 [구매] 를 누르면 부르십시오. 409 login_required 면 아직 승인 전입니다 — 잠시 뒤 다시 부르십시오. 승인 뒤 5분 안에 [구매] 가 없으면 결제는 거래취소 (login_expired)입니다.

{ "paymentId": "…", "status": "TRADING", "statusReason": null, "orderStatus": "WAITING" }

거래소가 주문을 거절하면 status 가 CANCELLED 이고 까닭이 statusReason 에 옵니다. orderStatus 는 거래소 주문 상태입니다. 방식이 api 가 아니면 409 wrong_mode, 결제가 거래중이 아니거나 취소 요청이 있으면 409 payment_not_open 입니다.

매칭 전 취소

POST /api/v1/payments/{paymentId}/cancel

본문은 없습니다. 매칭 전에만 됩니다. 매칭 뒤면 409 already_matched — 결제는 그대로 진행됩니다. 이미 거래완료면 409 payment_finished 입니다.

{ "paymentId": "…", "status": "CANCELLED", "statusReason": "cancelled_before_match" }

취소가 곧바로 끝나지 않으면 status 가 그대로이고, 끝나면 웹훅으로 알려 드립니다. 끝난 취소도 웹훅이 갑니다.

결제 상태 조회

GET /api/v1/payments/{paymentId}

지갑 잔액 조회

GET /api/v1/merchant/wallets/{walletAddress}/balance

{ "walletAddress": "sjo1…", "balanceUsde": "12.50", "height": … }

그때 체인에서 읽은 USDE 잔액과 블록 높이입니다. 한 번 더 확인하는 용도입니다 — 어느 결제의 입금인지는 가르지 못합니다. 결제의 입금은 웹훅 · 상태 조회의 arrivedUsde · txHash 로 보십시오. 체인을 읽지 못하면 503 chain_unavailable 입니다.

6. 웹훅 — 저희가 보내드리는 것

결제 상태가 바뀌면 저희가 등록해 주신 주소로 POST 합니다.

signature = HMAC-SHA256(웹훅 비밀키, X-EggPay-Timestamp + "." + 받은 본문)

⚠ 받은 본문 그대로 서명해 주십시오. JSON 을 다시 만들면 띄어쓰기 하나로 서명이 달라집니다. 시각이 서명 안에 들어 있어, 한 번 가로챈 알림을 나중에 다시 보내도 가맹점이 걸러낼 수 있습니다.

본문의 필드는 결제 상태 조회와 같은 뜻입니다.

결제를 만들 때는 보내지 않습니다 — 요청 기록(REQUESTED), api 방식의 TRADING, 곧바로 거래취소(CANCELLED) 모두 결제 요청의 답으로 아십니다.

2xx 를 돌려주시면 됩니다. 3xx 는 따르지 않고 실패로 봅니다. 그 밖이면 6회까지 다시 보냅니다 — 30초 · 2분 · 8분 · 32분 · 2시간 · 8시간 뒤입니다 (기본값).

순서는 보장하지 않습니다. occurredAt 과 상태 조회로 최신을 가려 주십시오.

웹훅은 못 갈 수 있습니다. 서버가 잠깐 죽거나 네트워크가 끊기면 그 줄기가 끊깁니다. 상태 조회로 따라잡아 주십시오 — 그래서 둘 다 드리는 것입니다.

7. 결제 상태

결제는 거래완료나 거래취소 가운데 하나로 반드시 끝납니다.

거래취소 까닭 (statusReason)

8. 수수료

간편결제는 수수료를 받지 않습니다. 도착 수량에서 체인 전송 수수료와 가스만 빠집니다 — 100.00 USDE 미만은 전송 수수료 0.17 + 가스 0.02 USDE 고정, 100.00 USDE 부터는 전송 수수료 0.17% 와 가스 0.1% 를 각각 올림(0.01 USDE 단위)합니다.

도착 수량은 체인이 정한 값(arrivedUsde)이 기준입니다. 식으로 다시 계산해 맞추지 않으셔도 됩니다.

100개 결제의 예

9. 관리자 웹

승인되면 가맹점 계정도 함께 드립니다. 관리자 웹에서 가맹점 계정으로 하실 수 있는 일은 이렇습니다.

9-1. 가맹점 정보를 바꾸려면

지갑 주소와 웹훅 주소는 스스로 바꾸실 수 없습니다. 신청해 주시면 저희가 확인하고 승인합니다.

10. 오류

{ "error": { "code": "invalid_address", "message": "…" } }

message 는 사람이 읽는 글입니다. 프로그램은 code 로 가르십시오.

사용자가 거래소 회원이 아니거나 거래소 계정으로 결제할 수 없는 경우는 오류가 아닙니다 — 연동 확인의 exchange.ready · reason 과, 결제의 CANCELLED 와 statusReason(not_member 등)으로 알려 드립니다.