가맹점 API 설명서

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

1. 시작하기

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

결제 순서

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

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

2. 인증

환율(4절) 밖의 모든 요청에 두 헤더를 넣습니다.

키는 둘입니다. API 키는 가맹점이 우리를 부를 때, 웹훅 비밀키는 우리가 가맹점을 부를 때 씁니다 (6절). API 키는 관리자 웹 「API」에서 [재발급], 웹훅 비밀키는 마이페이지의 「웹훅 서명 키」 [새로 발급]으로 가맹점이 직접 새로 받으실 수 있습니다 (9-1절).

둘 중 하나라도 없거나 틀리면 401 unauthorized 입니다 — 어느 쪽이 틀렸는지는 알려 드리지 않습니다. 승인된 가맹점이 아니거나 정지 · 삭제된 가맹점이면 403 merchant_inactive 입니다.

요청 공통

다시 보내기 키는 따로 헤더로 받지 않습니다. 결제 요청 본문의 merchantRequestId 가 그 키입니다 (5절).

GET /api/v1/payments/pay_Q2x7Lr0kVb3sT9mWzA1cN-8e
X-EggPay-Merchant-Id: (가맹점 코드)
X-EggPay-Api-Key: (API 키)
Accept-Language: ko

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

표의 값은 기본값입니다. 넘으면 429 와 함께 retryAfterSeconds 를 돌려드립니다. 한도는 1분 창(매 분 0초부터)으로 셉니다.

공통 모양

오류를 받으면

창구마다 오류 표의 「하실 일」 칸은 아래 셋 가운데 하나입니다.

어느 창구에서나 오는 것은 이렇습니다.

• 없는 주소를 부르시면 404 not_found, 방식이 틀리면(예: POST 창구를 GET 으로) 405 method_not_allowed 와 맞는 방식을 적은 Allow 헤더입니다 — 고쳐서 다시. 키가 필요한 주소에서는 키 검사가 먼저라, 키가 없으면 이 둘보다 401 이 먼저 옵니다.
• 주소 안에 %2F(/) · %5C(\) 가 있으면 저희 웹 서버가 JSON 이 아닌 400 을 줍니다 — 그런 글자는 회원 아이디에 넣지 마십시오 (3절).
• Accept 가 JSON 을 받지 않으면 본문 없는 406 입니다.

3. 지갑 연동

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

연동 시작

POST /api/v1/merchant/wallet-links

사용자의 SJO 지갑 주소를 가맹점 회원 아이디에 연동해 달라고 요청합니다. 한도는 「지갑 연동」 몫입니다.

요청

{ "merchantUserId": "member-1024", "walletAddress": "sjo1…" }

성공 응답 · 200 OK

{ "linkId": "lnk_Hk3Pq9Ws2LmX7vR0aTe5Yc_J", "status": "PENDING", "expiresAt": "2026-10-21T03:09:05.123Z" }

이 뒤로 사용자의 지갑앱에 알림이 가고, 사용자가 지갑앱에서 서명으로 승인하면 연동이 끝납니다. 옮겨 칠 숫자는 없습니다. 요청은 5분 동안 살아 있습니다 (expiresAt). 결과는 연동 확인으로 보십시오. 지갑 앱에 알림을 곧바로 전하지 못해도 답은 PENDING 이고, 마감 전까지 저희가 다시 보냅니다. 같은 회원·같은 주소로 다시 부르시면 살아 있는 요청을 그대로 드립니다. 같은 회원·같은 주소가 이미 연동돼 있으면 새 요청을 만들지 않고 그 연동을 "status": "LINKED" 로 드립니다. 이때 expiresAt 은 그 연동을 만든 요청의 마감(이미 지난 시각)입니다.

{ "linkId": "lnk_Hk3Pq9Ws2LmX7vR0aTe5Yc_J", "status": "LINKED", "expiresAt": "2026-10-20T01:05:00.000Z" }

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

오류

연동 확인

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

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

요청

성공 응답 · 200 OK

{ "linked": true, "status": "LINKED", "walletAddress": "sjo1…", "linkedAt": "2026-10-20T01:01:12.345Z",
  "exchange": { "ready": true, "reason": null } }

연동이 없는 회원도 오류가 아니라 이렇게 답합니다.

{ "linked": false, "status": "NONE", "walletAddress": null, "linkedAt": null, "exchange": null }

가맹점마다 따로 봅니다 — 다른 가맹점의 회원은 보이지 않습니다. 사용자가 지갑 앱에서 거절했거나 지갑 앱에 전할 수 없었으면 REJECTED, 5분 안에 승인이 없었거나 지갑 서명을 확인하지 못했으면 EXPIRED 입니다. 이름 · 거래소 아이디 같은 개인정보는 싣지 않습니다.

오류

연동 해제

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

회원의 연동을 풉니다. 한도는 「지갑 연동」 몫입니다.

요청

성공 응답 · 200 OK

{ "linked": false }

이 가맹점에서 그 지갑의 팝업 결제가 아직 요청 기록(REQUESTED)이면 먼저 닫고 풉니다 — 그 결제는 거래취소 (request_closed)가 되고 웹훅이 갑니다. 연동 기록은 지우지 않지만, 해제한 뒤 연동 확인은 NONE 입니다. 새 주소는 연동 시작부터 다시 해 주십시오.

그 지갑으로 진행 중인 결제가 있으면 409 payment_in_flight 입니다. 연동된 것이 없으면 404 입니다.

오류

4. 환율

GET /api/v1/rates

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

요청

헤더 · 주소 값 · 본문 모두 없습니다.

성공 응답 · 200 OK

{ "base": "USDE", "rates": { "USD": 1.0, "KRW": 1342.34042 }, "timestamp": 1791528601, "next_update": 1791550201 }

환율은 매일 한국 시간 0시와 12시에 재단에서 받아 바뀝니다. timestamp 와 next_update 는 재단이 정한 기준 시각과 재단의 다음 갱신 시각입니다(유닉스 초). 그 시각에 재단 환율을 받지 못하면 앞서 받은 환율을 그대로 드립니다.

받아 둔 환율이 하나도 없을 때만 503 과 rate_unavailable 을 드립니다 — 잠시 후 다시 불러 주십시오.

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

오류

5. 결제

방식 셋

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

결제 요청

POST /api/v1/payments

한도는 「결제 요청」 몫입니다.

요청

{ "merchantRequestId": "order-20261021-0001", "buyerWalletAddress": "sjo1…", "merchantWalletAddress": "sjo1…",
  "amountUsde": "100.00", "mode": "popup_wallet" }

성공 응답 · 200 OK

{ "paymentId": "pay_Q2x7Lr0kVb3sT9mWzA1cN-8e", "status": "REQUESTED", "statusReason": null,
  "popupUrl": "https://…", "created": true }

api 방식이면 이렇습니다.

{ "paymentId": "pay_Q2x7Lr0kVb3sT9mWzA1cN-8e", "status": "TRADING", "statusReason": null,
  "popupUrl": null, "created": true }

• 이때는 거래소 주문이 생기지 않습니다. 주문은 구매 등록에서 생깁니다.
• 같은 merchantRequestId 로 다시 보내시면 같은 결제입니다 — 그 결제의 지금 값을 created: false 로 드립니다. 같은 내용인지는 구매자 지갑 · 가맹점 지갑 · 수량 · 방식으로 봅니다 ("12.5" 와 "12.50" 은 같습니다). 결제를 만들지 않은 거절은 남기지 않습니다 — 같은 키로 다시 부르시면 그때 상태로 다시 봅니다.
• 구매자 지갑 하나에 진행 중인 결제는 1건입니다 — 있으면 409 payment_in_flight. 같은 구매자의 팝업 결제가 아직 요청 기록이면 그것을 닫고(request_closed) 새 결제를 만듭니다.
• USDE 가 멈췄으면 503 usde_paused, 멈춤 상태를 읽지 못했으면 503 chain_unavailable 입니다. 둘 다 결제를 만들지 않았습니다 — chain_unavailable 은 같은 merchantRequestId 로 다시 부르시면 됩니다.
• 처리 중에 지갑 앱에 전할 수 없거나(wallet_undeliverable) 거래소가 팝업 결제를 받지 않으면 (amount_out_of_range 등) 어느 방식이든 답이 곧바로 CANCELLED 일 수 있습니다.
• 수량은 지갑 앱 · 팝업에서 바꿀 수 없습니다.

필드가 하나라도 없거나 잘못되면 거절합니다. 그때는 가맹점 화면에서 경고를 띄워 주십시오. 저희는 아래 차례로 봅니다 — 형식 → 같은 merchantRequestId → 가맹점 지갑 → 연동 → USDE 멈춤 → 진행 중 결제 → 거래소 회원 자격(api 만).

오류

팝업 열기

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)입니다.

성공 응답 · 200 OK

{ "paymentId": "pay_Q2x7Lr0kVb3sT9mWzA1cN-8e", "status": "TRADING", "statusReason": null, "orderStatus": "WAITING" }

거래소가 주문을 거절하면 status 가 CANCELLED 이고 까닭이 statusReason 에 옵니다 — 오류가 아니라 200 입니다. 한 번 받아들인 구매 등록은 다시 부르셔도 다른 확인 없이 그 결제의 지금 값을 드립니다. 방식이 api 가 아니면 409 wrong_mode, 결제가 거래중이 아니거나 취소 요청이 있으면 409 payment_not_open 입니다.

오류

매칭 전 취소

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

매칭 전에만 됩니다. 매칭 뒤면 409 already_matched — 결제는 그대로 진행됩니다. 이미 거래완료면 409 payment_finished 입니다. 한도는 「전체 합」 몫만 셉니다.

요청

성공 응답 · 200 OK

{ "paymentId": "pay_Q2x7Lr0kVb3sT9mWzA1cN-8e", "status": "CANCELLED", "statusReason": "cancelled_before_match" }

이미 거래취소된 결제면 같은 답을 다시 드립니다. 거래취소도 웹훅이 갑니다. 취소를 받은 뒤에는 구매 등록이 409 payment_not_open 입니다.

거래소나 지갑이 곧바로 답하지 않으면 503 입니다. 이때 취소 요청은 받아 두었고 저희가 다시 보냅니다 — 거래취소가 되면 웹훅으로 알려 드립니다. 그 사이 매칭되면 결제는 그대로 진행됩니다.

오류

결제 상태 조회

GET /api/v1/payments/{paymentId}

웹훅을 못 받으셨을 때 따라잡는 창구입니다. 한도는 「결제 상태 조회」 몫입니다.

요청

성공 응답 · 200 OK

{ "paymentId": "pay_Q2x7Lr0kVb3sT9mWzA1cN-8e", "mode": "popup_wallet", "popupUrl": "https://…",
  "status": "COMPLETED", "statusReason": null, "merchantUserId": "member-1024",
  "buyerWalletAddress": "sjo1…", "merchantWalletAddress": "sjo1…", "amountUsde": "100.00",
  "tradeNo": "…", "contract": { "address": "sjo1…", "paymentId": "pay_Q2x7Lr0kVb3sT9mWzA1cN-8e",
  "status": "paid", "merchantAmountUsde": "99.73" }, "arrivedUsde": "99.73", "txHash": "…",
  "createdAt": "2026-10-21T03:04:05.123Z", "updatedAt": "2026-10-21T03:12:40.551Z" }

오류

지갑 잔액 조회

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

한도는 「전체 합」 몫만 셉니다.

요청

성공 응답 · 200 OK

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

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

오류

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

결제 상태가 바뀌면 저희가 등록해 주신 주소(마이페이지의 웹훅 주소, https://)로 POST 합니다. 웹훅 주소가 비어 있으면 보내지 않습니다 — 그때는 결제 상태 조회로 보십시오. 사설망 같은 내부 주소로 가는 웹훅 주소에는 보내지 않습니다.

언제

상태가 바뀔 때마다 한 번 보냅니다 — 요청 기록에서 거래중(REQUESTED → TRADING), 거래완료(COMPLETED), 거래취소(CANCELLED), 분쟁(DISPUTED). 결제를 만들 때는 보내지 않습니다 — 요청 기록(REQUESTED), api 방식의 TRADING, 곧바로 거래취소(CANCELLED) 모두 결제 요청의 답으로 아십니다. 만든 뒤에 바뀐 것은 보냅니다 — 결제 요청 처리 중 뒤이어 거래취소가 된 경우(wallet_undeliverable 등)도 웹훅이 갑니다.

저희가 보내는 요청

{"paymentId":"pay_Q2x7Lr0kVb3sT9mWzA1cN-8e","status":"COMPLETED","statusReason":null,"amountUsde":"100.00","tradeNo":"…","contract":{"address":"sjo1…","paymentId":"pay_Q2x7Lr0kVb3sT9mWzA1cN-8e","status":"paid","merchantAmountUsde":"99.73"},"arrivedUsde":"99.73","txHash":"…","occurredAt":"2026-10-21T03:12:40.551Z"}

본문의 필드는 결제 상태 조회와 같은 뜻입니다. 모든 필드가 늘 오고, 값이 없으면 null 입니다.

상태마다 하실 일은 7절에 있습니다.

서명 확인

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

1. 본문을 받은 바이트 그대로 둡니다 (JSON 으로 읽기 전).
2. X-EggPay-Timestamp 값, 점(.) 하나, 받은 본문을 이어 붙입니다.
3. 웹훅 비밀키 글자(UTF-8)를 키로 HMAC-SHA256 을 계산해 소문자 16진수로 씁니다.
4. X-EggPay-Signature 와 같은지 봅니다. 시간 차가 드러나지 않는 비교를 쓰십시오. 다르면 버리십시오.

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

계산이 맞는지 볼 때 쓰는 예입니다 (실제 본문이 아닙니다).

// Java
Mac mac = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(webhookSecret.getBytes(StandardCharsets.UTF_8), "HmacSHA256"));
mac.update((timestampHeader + ".").getBytes(StandardCharsets.UTF_8));
String expected = HexFormat.of().formatHex(mac.doFinal(rawBody));   // rawBody: 받은 본문 byte[]
boolean ok = MessageDigest.isEqual(expected.getBytes(StandardCharsets.UTF_8),
                                   signatureHeader.getBytes(StandardCharsets.UTF_8));

가맹점의 답

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

다시 보내기 간격은 앞 실패에서 잽니다. 다시 보낼 때도 본문은 처음과 같고, X-EggPay-Timestamp 와 서명만 새로 만듭니다. 처음 1회와 다시 보내기 6회가 모두 실패하면 그 알림은 더 보내지 않습니다 — 결제 상태 조회로 보십시오. 답이 늦어 실패로 본 뒤 다시 보내면 같은 알림을 두 번 받으실 수 있습니다 — paymentId 와 status 로 한 번만 처리해 주십시오.

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

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

7. 결제 상태

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

거래취소 까닭 (statusReason)

거래소가 준 까닭은 그 이름 그대로 싣습니다. 위 표에 없는 이름이 오더라도 CANCELLED 면 충전건을 취소 처리해 주십시오.

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 는 사람이 읽는 글입니다(Accept-Language 에 따라 한국어 · 영어). 프로그램은 code 로 가르십시오. 429 에는 error 옆에 retryAfterSeconds(다시 보내도 되는 때까지의 초)가 붙고, 같은 값이 Retry-After 헤더에도 옵니다.

{ "error": { "code": "rate_limited", "message": "…" }, "retryAfterSeconds": 12 }

아래는 가맹점 API 가 돌려드리는 모든 오류 코드입니다. 창구마다 언제 오는지는 각 창구의 오류 표에 있습니다.

JSON 오류 본문 없이 오는 답도 있습니다 — 주소 안의 %2F · %5C 에 저희 웹 서버가 주는 400, Accept 가 JSON 을 받지 않을 때의 406 이 그렇습니다 (2절). HTTP 상태로 가르십시오.

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