ABIS PAY

개발자 문서

API 시험 키가 아직 없나요?
서류 없이 바로 받아 지금 연동을 시작하세요.
시험 키 바로 받기
시험 환경준비인증결제창승인조회취소수기결제웹훅한도·정산오류

시험 환경

키가 없으면 시험 키 바로 받기에서 서류 없이 받습니다. 시험 키(ck_test_·sk_test_)로 연 결제창은 실제 카드로 인증까지 진행해도 돈이 빠져나가지 않습니다.

준비

계약하면 가맹점 코드(MID), 앱 코드, client key(ck_test_/ck_live_), server secret key(sk_test_/sk_live_), webhook 서명 키(whsec_)를 드립니다. 테스트 키는 실제 돈이 움직이지 않습니다. 운영 전환 때 운영 키를 따로 드립니다. server secret key 와 webhook 서명 키는 서버에만 두세요.

가맹점 관리자(/portal)에서 웹훅 주소, 허용 Origin(결제창을 여는 웹사이트), 허용 IP(API를 부르는 서버)를 등록합니다.

인증

서버 API는 HTTP Basic 인증입니다. 아이디에 server secret key, 비밀번호는 빈 값입니다.

curl https://abispay.app/v1/payments/tracks/order_1 -u "sk_test_…:"

승인·취소·수기결제 요청에는 Idempotency-Key 헤더가 필요합니다. 같은 키로 같은 요청을 다시 보내면 처음 결과를 그대로 돌려줍니다. 결과가 불확실하면 새 키로 다시 보내지 말고 먼저 조회하세요.

결제창

import createPay from "https://abispay.app/sdk/pay.js";
const pay = createPay("ck_test_…");
await pay.startPayment({
  amount: 14900, trackId: "order_8f12", orderName: "프리미엄 1개월",
  customerName: "홍길동",            // 필수
  customerEmail: "[email protected]", customerPhone: "01012345678",
  successUrl: "https://shop.example.com/pay/success",
  failUrl: "https://shop.example.com/pay/fail",
});

trackId는 영문·숫자·-·_ 40자 이내, 주문마다 새 값입니다. 결제창은 화면 이동 방식으로 열립니다. 인증이 끝나면 successUrl로 paymentId·transactionId·confirmToken·trackId·amount가 붙어 돌아옵니다. 실패하면 failUrl로 status·code가 붙습니다.

승인

successUrl 로 돌아오면 서버에서 금액을 대조하고 승인을 부릅니다. 승인을 부르기 전에는 주문을 확정하지 마세요.

curl -X POST https://abispay.app/v1/payments/confirm -u "sk_test_…:" \
  -H "Idempotency-Key: order_8f12_confirm" -H "Content-Type: application/json" \
  -d '{"paymentId":"P…","transactionId":"T…","trackId":"order_8f12","confirmToken":"cft_…","amount":14900}'

응답의 lastPaymentStatus가 APPROVED면 완료입니다. 응답에는 수수료(fee), 받을 돈(settleAmount), 정산 예정일(settleDue)이 함께 옵니다. confirmToken 은 15분 안에 한 번만 쓸 수 있습니다.

조회

GET /v1/payments/{paymentId}
GET /v1/payments/tracks/{trackId}

상태: APPROVED 승인 · PARTIAL_CANCELLED 부분취소 · CANCELLED 전체취소 · FAILED 실패.

취소

curl -X POST https://abispay.app/v1/payments/P…/cancel -u "sk_test_…:" \
  -H "Idempotency-Key: order_8f12_cancel_1" -H "Content-Type: application/json" \
  -d '{"cancelReason":"고객 요청","cancelAmount":10000}'

잔액보다 작으면 부분취소입니다. 카드 부분취소는 보통 승인 다음 영업일부터 됩니다. 취소 금액만큼 수수료도 함께 취소됩니다.

수기결제

매장·전화 주문처럼 결제창을 띄울 수 없을 때 카드 정보로 바로 승인합니다. 서버에서만 부르고, 카드 정보는 저장·기록하지 마세요. 가맹점 관리자의 「매장 결제」 화면에서도 같은 결제를 할 수 있습니다.

POST /v1/payments/key-in
{"amount":30000,"trackId":"pos_0912","productName":"커트",
 "customerName":"홍길동",
 "card":{"cardNumber":"4242424242424242","expireDate":"1228","birthday":"900101","password":"00"},
 "installmentMonths":0}

테스트 카드 4242 4242 4242 4242 는 테스트 키에서만 됩니다. 운영 키에서는 실제 카드로 승인됩니다.

웹훅

승인·취소 상태가 바뀌면 등록한 주소로 POST 합니다. 5초 안에 2xx로 답하세요. 실패하면 1분·5분·30분·2시간·6시간 뒤 다시 보냅니다. 같은 이벤트가 두 번 올 수 있으니 eventId로 한 번만 처리하세요.

Payment-Webhook-Id: evt_…
Payment-Webhook-Timestamp: 1781913851
Payment-Webhook-Signature: v1=<HMAC-SHA256(whsec, timestamp + "." + 원문 본문) 소문자 hex>

본문을 파싱하기 전에 원문 바이트로 서명을 검증하고, 시각은 ±5분 안인지, 헤더 ID와 본문 eventId가 같은지 확인하세요.

한도·정산

운영 결제는 월 한도 안에서 됩니다. 보증보험이 없으면 월 1천만 원, 보증보험 증권을 등록하면 증권 금액의 2배입니다. 한도를 넘으면 SETTLEMENT_LIMIT_EXCEEDED로 막힙니다. 정산은 계약한 주기(D+1·D+3, 영업일 기준)에 결제대행사가 등록 계좌로 지급합니다.

오류

code뜻
UNAUTHORIZED · INVALID_CLIENT_KEY키가 틀렸거나 가맹점이 정지됨
CLIENT_KEY_ORIGIN_NOT_ALLOWED · SUCCESS_URL_NOT_ALLOWED허용 Origin 밖에서 결제창을 열었음
INVALID_AMOUNT · INVALID_TRACK_ID · INVALID_CUSTOMER_NAME요청 값 오류
TRACK_ID_CONFLICT · ALREADY_CONFIRMED이미 쓴 주문번호 · 이미 승인됨 — 조회하세요
CONFIRM_TOKEN_EXPIRED · CONFIRM_TOKEN_ALREADY_USEDconfirmToken 만료·재사용
IDEMPOTENCY_KEY_CONFLICT · IDEMPOTENCY_KEY_PROCESSING같은 키로 다른 요청 · 처리 중
APPROVAL_RESULT_UNCONFIRMED · CANCEL_RESULT_UNCONFIRMED결과 미확정 — 새로 요청하지 말고 조회
SETTLEMENT_LIMIT_EXCEEDED월 한도 초과 — 보증보험 증액
UPSTREAM_NOT_READY운영 결제 준비 중