1. 연동 준비하기
1) 연동 기본 정보 확인
•
페이먼스는 UTF-8 인코딩 방식을 지원하며,
•
메시지 포맷은 기본적으로 JSON(JavaScript Object Notation) 입니다.
◦
Content-Type: application/json
•
TLS v1.2 이상 / SSL 보안 통신(HTTPS)을 필수적으로 적용해야 합니다.
•
페이먼스(API 서버) 접속 정보
구분 | URL | 비고 |
테스트 서버 | https://service.apis.paymonths.io/test/ | 추후 변경될 수 있음 |
운영 서버 | https://service.apis.paymonths.io/ |
2) Access Key / Access Secret 수령
•
연동 일정이 협의되고 나면, Access Key와 Access Secret 발급을 위한 기본 정보를 요청드립니다.
•
전달주신 정보로 Key를 발급하여 담당자께 전달드립니다.
Secret 정보를 노출하거나 탈취당하지 않게 안전하게 보관해 주세요.
특히, Secret값은 브라우저 등 클라이언트 환경에 노출시키면 안됩니다.
페이먼스는 실제 결제가 발생하는 운영 서버와 테스트 서버를 분리하여 제공합니다.
각 서버의 Key가 다르므로 주의해주세요.
3) 파트너 인증 API - Access token 발급
•
전달받은 Access Key / Access Secret으로 인증 API를 호출하여 Access Token을 획득할 수 있습니다.
◦
Basic 인증 스킴을 사용하여 요청해야 합니다. RFC7617 을 참고해주세요.
•
모든 API는 Access Token이 있어야 호출할 수 있습니다.
•
Access token은 만료되기 전에 재발급 받아야 합니다. expirationTime 만료시각을 참고해주세요.
Request
•
URL
GET /access
JavaScript
복사
•
Headers
Authorization: Basic <encoded access key & access secret>
Plain Text
복사
Response
•
Status code: 200
•
Body
{
"data": {
"scheme": "<string>",
"token": "<string>",
"expirationTime": <int>
},
"eventTime": "<string>"
}
JSON
복사
•
Field
Field | type | 설명 |
data.scheme | string | 인증 스킴 타입 (예: Bearer, JWT 등) |
data.token | string | 토큰 (JWT token 등) |
data.expirationTime | int | 토큰 만료 시각, POSIX timestamp (without millisecond) |
eventTime | string | 서버 전송 시각, ISO 8601 with time zone |
•
응답 예시
// 파트너 인증 응답 예시
{
"data": {
"scheme": "Bearer",
"token": "qgjir12048REI1NF0SDJIOEIOG130us94t4ck193dfigEE0230",
"expirationTime": 1695177465 //without millisecond
},
"eventTime": "2023-08-21T02:37:46.108359+00:00"
}
JSON
복사
2. 외상결제 프로세스 이해하기
1.
고객의 구매 요청
•
파트너 주문서 페이지에서 페이먼스 외상결제를 클릭해 구매를 요청합니다.
•
고객의 구매요청이 발생하면 페이먼스로 외상결제생성을 요청합니다.
2.
외상결제 생성
•
파트너에서 외상결제 상세정보(구매일자, 구매금액, 구매품명 등)을 페이먼스 서버로 전달해 외상결제를 생성하는 단계입니다.
•
파트너에서 전달준 상세정보를 기준으로 페이먼스에서 외상결제URL을 응답합니다.
•
외상결제URL을 팝업(새창) 혹은 페이지 이동(리다이렉션) 방식으로 띄울 수 있으며, 페이지 이동 방식을 권장합니다.
3.
외상결제 처리
•
사용자 로그인 및 인증 단계로, 외상결제URL에서 외상결제가 가능한 사용자의 상태, 잔여한도 등을 확인하고 결과값을 파트너로 응답합니다.
◦
외상결제성공 : 파트너 returnURL로 리다이렉트
◦
외상결제실패 : 파트너 cancelURL로 리다이렉트
▪
cancelUrl 형식 : {cancelURL}?reservedId={reservedId}&reason={code}
▪
상세 케이스는 아래 API 상세 설명을 참고해주세요.
4.
외상결제 승인
•
파트너가 전달받은 외상결제를 최종적으로 확인 후 승인하여 외상결제를 완료하는 단계입니다.
•
마지막 외상결제승인이 완료돼야 전체 프로세스가 성공적으로 종료됩니다.
[외상결제 프로세스 Overview]
[외상결제 프로세스 | 화면 기준]
3. 외상결제 API 상세
️ 모든 API는 Authorization 헤더를 통해 유효한 Access token을 포함해야 합니다.[외상결제 프로세스 상세]
1) 외상결제 생성 API
•
외상결제하고자 하는 주문 정보를 페이먼스 서버에 전달하면 외상결제 URL을 호출할 수 있습니다.
외상결제URL의 유효시간은 10분입니다.
* 유효시간은 변경될 수 있으며, 변경사항은 사전 고지 후 업데이트 노트에 추가됩니다.
Request
•
URL
POST /payments
JavaScript
복사
•
Headers
Authorization: <scheme> <access token>
Plain Text
복사
•
Body
{
"customerBusinessNumber": "<string>",
"partnerUserId" : "<string>",
"totalAmount" : <int>,
"displayName" : "<string>",
"partnerOrderNo": "<string>",
"returnUrl" : "<string>",
"cancelUrl": "<string>"
}
JSON
복사
•
Parameter
Parameter | type | 설명 |
customerBusinessNumber | string | 도매플랫폼 사업자 정보와 페이먼스 사업자 정보의 일치 여부 확인에 사용, Max Length : 10 |
partnerUserId | string | 외상결제 진행 중인 파트너 측 사용자 ID, Max Length : 50 |
totalAmount | int | 외상결제 총액, Max Length : 10 |
displayName | string | 외상결제 화면에 노출할 품목명, Max Length : 50 |
partnerOrderNo | string | 파트사 고유 주문번호(unique value), Max Length : 50 |
returnUrl | string | 외상결제 성공 시 리턴할 callback URL (https를 포함한 전체 URL)
함께 전달받을 값을 Query string으로 추가할 수 있습니다. Max Length : 1,024byte |
cancelUrl | string | 외상결제 중단/취소/실패 시 리턴할 callback URL(https를 포함한 전체 URL)
함께 전달받을 값을 Query string으로 추가할 수 있습니다. Max Length : 1,024byte |
Response
•
Status Code : 200
•
Body
{
"data": {
"reservedId": "<string>",
"paymentUrl": "<string>"
},
"eventTime": "<string>"
}
JSON
복사
•
Field
Field | type | 설명 |
data.reservedId | string | 외상결제생성ID |
data.paymentUrl | string | 외상결제 진행을 위한 URL로 외상결제ID(payableId)를 포함합니다. URL-encoded string
* Base64 URL-safe Encoding (RFC3986 Percent-Encoding) |
eventTime | string | 서버 전송 시각, ISO 8601 with time zone |
•
응답 예시
// 외상결제 생성 응답 예시
{
"data": {
"reservedId": "EIW0983JGD0FJ25DOC10EF9CSE", //26자리
"paymentUrl": "https%3A//pay.paymonths.io/payment/EIW0983JGD0FJ25DOC10EF9CSE%3FpaySecretCode%39c9fd29D9B012HFDJBL38yt4gklJU9357%26cancelUrl%3Dhttps%253A//cancelurl.com"
},
"eventTime": "2023-08-22T05:38:21.866623+00:00"
}
JSON
복사
응답받은 외상결제URL(paymentUrl)은 URL 디코딩이 필요합니다.
디코딩된 paymenUrl 형식은 다음과 같습니다.
https://pay.paymonths.io/payment/{reservedId}?paySecretCode={paySecretCode}&cancelUrl={cancelUrl}
2) 외상결제 승인 API
•
고객 사용자가 외상결제를 완료하면, 최종적으로 파트너에서 외상결제를 검증하고 승인하는 단계입니다.
Request
•
URL
POST /payments/{reservedId}/approval
JavaScript
복사
•
Headers
Authorization: <scheme> <access token>
Plain Text
복사
•
Body
{
"payableId": "<string>"
}
JSON
복사
•
Parameter
Parameter | type | 설명 |
reservedId | string | 외상결제생성ID, Length : 26 |
payableId | string | 외상결제ID, Length : 26, 외상결제 생성 API response 중 paymentUrl에 포함하여 전달됩니다. |
Response
•
Status Code : 200
•
Body
{
"data": {
"approvedId": "<string>",
"partnerOrderNo": "<string>",
"totalAmount": <int>,
"approvalTime": <int>,
"redemptionDate": "<string>"
},
"eventTime": "<string>"
}
JSON
복사
•
Field
Field | type | 설명 |
data.approvedId | string | 외상결제승인ID, Length : 26 |
data.partnerOrderNo | string | 외상결제 생성 시 전달받은 파트너 측 주문번호, Max Length : 50 |
data.totalAmount | int | 외상결제 총액, Max Length : 10 |
data.approvalTime | int | 외상결제 승인 시각, POSIX timestamp (with millisecond) |
data.redemptionDate | string | 결제예정일, KST 기준 date (ex. 2024-05-24) |
eventTime | string | 서버 전송 시각, ISO 8601 with time zone |
•
응답 예시
// 외상결제 승인 응답 예시
{
"data": {
"approvedId": "20DM46CIDIENG0187B237YKDM3", //26자리
"partnerOrderNo": "O56789",
"totalAmount": 300000,
"approvalTime": 1692682777375, //with millisecond
"redemptionDate": "2023-09-21"
},
"eventTime": "2023-08-22T05:39:38.084981+00:00"
}
JSON
복사
결제예정일이란? 고객이 외상대금을 결제해야 하는 날로, 2023년 6일 1일에 30일 외상결제를 했다면, 결제예정일은 7월 1일입니다.
3) 외상결제 실패
•
외상결제 프로세스 중 실패한 경우 파트너에서 전달 준 cancelURL로 return하며 각 응답코드와 외상결제생성ID(reservedId)를 함께 전달합니다.
◦
cancelUrl 형식 : {cancelURL}?reservedId={reservedId}&reason={code}
케이스 | 에러코드 (reason) | 설명 |
사업자 번호 불일치 | BUSINESS_NUMBER_NOT_MATCH | 도매플랫폼 계정의 사업자 번호와 페이먼스 계정의 사업자번호가 일치하지 않는 경우 발생합니다.
일치한 사업자 번호의 계정으로만 외상결제를 이용할 수 있습니다. |
미승인상태 | UNCERTIFIED | 고객이 미승인 단계인 경우 발생합니다.
페이먼스 고객인증을 완료한 후 이용할 수 있습니다. |
연체상태 | NOT_REPAID | 고객이 연체중인 경우 발생합니다.
고객이 연체중인 대금을 모두 결제한 후 이용할 수 있습니다. |
한도초과 | OVER_CREDIT | 잔여한도보다 외상결제금액이 큰 경우 발생합니다.
고객이 외상결제금액을 변경해 재시도 할 수 있습니다. |
유효시간 만료 | TIME-EXPIRED | 외상결제 유효시간이 만료된 경우 발생합니다.
새로운 외상결제를 생성해 재시도할 수 있습니다. |
결제중단 | ABORTED | 고객이 외상결제 상세화면에서 그만두기를 클릭해 직접 결제를 중단한 경우 발생합니다.
새로운 외상결제를 생성해 재시도할 수 있습니다. |
기타 | ETC | 서버에러 / 중복 결제 시도 등 기타 사유로 발생합니다. |
4. 외상결제 취소 API 상세
️ 모든 API는 Authorization 헤더를 통해 유효한 Access token을 포함해야 합니다.[외상결제취소 프로세스 상세]
1) 외상결제 취소 API
•
최종 승인된 외상결제 건 중 파트너 플랫폼에서 취소/환불 처리된 건은 외상결제취소API를 통해 외상결제도 취소할 수 있습니다.
•
외상결제 취소는 파트너 Back-end와 페이먼스 Back-end 간 통신하여 처리하므로, 별도 Front 화면은 없습니다.
•
원외상결제금액과 취소요청금액을 비교하여 취소처리하며, 전체취소 / 부분취소 모두 가능합니다.
API를 통한 취소는 결제예정일 1일 전까지만 가능합니다.
가능 기간 이후 취소 건은 별도로 전달주셔야 하며, 방법은 페이먼스 운영팀과 협의할 수 있습니다.
(예시. 2023년 6일 1일에 30일 외상결제를 했다면, 결제예정일인 7월 1일의 하루 전인 6월 30일까지만 외상결제취소 API를 통한 취소가 가능합니다.)
Request
•
URL
PUT /payments/approval/{approvedId}
JSON
복사
•
Headers
Authorization: <scheme> <access token>
Plain Text
복사
•
Body
{
"prevAmount": <int>,
"cancelAmount": <int>,
"remarks": "<string>"
}
JSON
복사
•
Parameter
Parameter | type | 설명 |
approvedId | string | 외상결제승인ID, Max Length : 26 |
prevAmount | int | 취소 직전 외상결제금액, Max Length : 10 |
cancelAmount | int | 외상결제 취소 금액, Max Length : 10 |
remarks | string | 취소 사유 또는 비고, Max Length : 50 |
취소 직전 외상결제금액은 부분취소가 여러 번 발생한 경우, 취소 가능 금액을 확인하고 중복 취소를 방지하기 위해 필요합니다.
부분취소가 여러 번 발생할 경우 아래 예시를 참고하셔서 작업해주세요.
원외상결제금액 100,000원이고, 부분취소가 2번 나눠서 발생한 경우
# 첫번째 취소 | 20,000원
- 원외상결제금액이 100,000원이었으므로, prevAmount(취소 직전 외상결제금액)은 100,000원이어야 합니다.
{
"prevAmount": 100000,
"cancelAmount": 20000,
"remarks": "부분취소"
}
# 두번째 취소 | 50,000원
- 첫번째 20,000원 취소되어 남은 외상결제금액은 80,000원이므로, prevAmount(취소 직전 외상결제금액)은 80,000원이어야 합니다.
{
"prevAmount": 80000,
"cancelAmount": 50000,
"remarks": "부분취소"
}
JSON
복사
Response
•
Status Code : 200
•
Body
{
"data": {
"cancelledId": "<string>",
"cancelledTime": <int>
},
"eventTime": "<string>"
}
JSON
복사
•
Field
Field | type | 설명 |
cancelledId | string | 외상결제취소ID, Max Length : 26 |
cancelledTime | int | 외상결제취소 시각, POSIX timestamp (with millisecond) |
eventTime | string | 서버 전송 시각, ISO 8601 with time zone |
•
응답 예시
// 외상결제취소 응답 예시
{
"data": {
"cancelledId": "CA01QOAPEOG92424CNVBOIR35", //26자리
"cancelledTime": 1692682877442 //with millisecond
},
"eventTime": "2023-08-22T05:41:18.114946+00:00"
}
JSON
복사
2) 외상결제취소 실패
•
외상결제취소를 실패한 경우 각 응답코드를 함께 전달합니다.
케이스 | 에러코드 (reason) | 설명 |
취소 요청 기한 만료 | CANCELABLE_PERIOD_EXPIRED | 취소 가능한 기한이 지난 경우 발생합니다.
기한이 지난 취소 건은 페이먼스 운영팀에게 별도로 전달주셔야 합니다. |
취소 가능 금액 범위 벗어남 | AMOUNT_OUT_OF_RANGE | 취소금액이 외상결제금액보다 크거나, 취소 직전 외상결제금액이 맞지 않는 경우 발생합니다.
취소금액과 취소 직전 외상결제금액을 확인해주세요. |
기타 | FAILED_TO_CANCEL | 원외상결제의 파트너 토큰 불일치 등 그 밖의 기타 사유로 발생합니다. |
•
응답 예시
// 외상결제취소 실패 응답 예시
{
"code": "FAILED_TO_CANCEL", //에러 코드
"codeDescription": "외상 결제 취소를 실패했습니다.", //설명
"extra": []
}
JSON
복사
5. 응답코드
•
응답코드는 HTTP 상태 코드와 에러에 대한 정보를 담은 에러코드와 메시지를 포함합니다.
•
요청 성공 시 HTTP 상태 코드 200과 요청에 대한 response body가 반환되고, 요청이 실패한 경우 에러코드와 메시지로 이루어진 에러코드를 반환합니다.
HTTP 상태 코드 | 에러코드 | 메시지 |
400 | LOGIN_FAILED | 로그인에 실패 하였습니다. |
400 | INVALID_REQUEST | 잘못된 요청입니다. |
400 | INVALID_SECRET_CODE | Secret Code가 일치하지 않습니다. |
400 | EXPIRED_PAYMENT | 해당 결제는 만료되었습니다. |
400 | DUPLICATED_PAYMENT | 중복된 결제시도입니다. |
400 | INSUFFICIENT_CREDIT_BALANCE | 브런치의 잔여한도가 부족합니다. |
400 | FAILED_TO_CANCEL | 외상 결제 취소를 실패했습니다. |
400 | OVERDUE_PAYMENT | 현재 연체중 상태이므로 결제를 하실 수 없습니다. |
403 | PERMISSION_DENIED | 허용되지 않은 접근입니다. |
404 | NO_DATA_FOUND | 데이터를 찾을 수 없습니다. |
500 | CLIENT_DB_ERROR | 잘못된 요청에 인해 DB 에러가 발생했습니다. |
500 | UNDEFINED_SERVER_ERROR | 정의하지 않은 서버 에러입니다. |
500 | RESOURCE_API_ERROR | 잘못된 요청으로 인해 리소스 서버에서 에러가 발생했습니다. |
2023.08.25 Updated
기타 문의사항은 페이먼스 고객센터로 연락주세요.
