페이지 이동경로
- 문서>
- 카카오모먼트>
- 쉬운 메시지광고: 결제 관리
카카오모먼트
쉬운 메시지광고: 결제 관리
이 문서는 카카오모먼트 쉬운 메시지광고의 결제 관리 API 사용 방법을 안내합니다.
충전 내역 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/cash/list |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고에 사용할 수 있는 캐시 충전 내역을 조회합니다.
- 쉬운 메세지 미발송분
type:CHARGEchargeMethod:SYSTEM_FREECASH
- 일반 메세지 미발송분
type:CHARGEchargeMethod:ADMIN_FREECASH
충전 내역 중 무상캐시는 무상캐시 사용을 호출해 상태(status)를 사용 중(USING)으로 변경하면 사용 가능합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 광고계정의 캐시 충전 내역을 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
쿼리 파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| page | Integer |
페이지 번호 0번부터 시작 |
X |
| limit | Integer |
페이지 사이즈(기본값: 20) | X |
| from | String |
지표 조회 기간 시작일yyyy-MM-dd 형식미입력 시 조회 당일부터 2년 전으로 설정하여 조회함 |
X |
| to | String |
지표 조회 기간 종료일yyyy-MM-dd 형식 |
X |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| content | CashTo[] |
충전 내역 |
CashTo
| 이름 | 타입 | 설명 |
|---|---|---|
| dt | String |
거래일시 |
| type | String |
CHARGE(충전), REFUND(환급), WITHDRAW(환불), REPAYMENT(채권상환) |
| chargeMethod | String |
거래 유형, 아래 중 하나CREDIT_CARD: 신용카드 결제KAKAOPAY_CARD_AUTO: 카카오페이에 설정된 신용카드로 결제-체크 카드 포함VIRTUAL_ACCOUNT: 무통장 입금ADMIN_CASH: 관리자 유상캐시 지급ADV_RET_CASH: 광고주 환원 유상캐시 지급CREDIT_CARD_REGULAR: 자동결제카드KAKAOPAY_CARD: 카카오페이 결제ADMIN_FREECASH: 관리자 무상캐시 지급SYSTEM_FREECASH: 시스템 무상캐시 지급EVENT_FREE_CASH: 프로모션 무상캐시 지급ADV_RET_FREE_CASH: 광고주 환원 무상캐시 지급ADMIN_ADJUST_FREECASH: 무상캐시 금액조정으로 인한 지급CPMS: CPMS계약조정으로 인한 지급CPT: CPT계약조정으로 인한 지급WITHDRAW: 환불EXPIRE_FREECASH: 무상캐시 만료 |
| amount | Double |
유, 무상캐시 금액 |
| memberType | String |
충전 거래자 유형, 아래 중 하나DSP_ACCOUNT: 광고계정ID를 사용해 DSP 또는 API로 충전하는 광고주INHOUSE_ACCOUNT: 어드민 기능으로 충전하는 카카오 내부 관리자AGENCY_ACCOUNT: 에이전시 플랫폼에서 충전하는 마케터 혹은 대행사SYSTEM: 카카오 시스템 |
| memberEmail | String |
거래자 이메일 |
| memberName | String |
거래자 이름 |
| methodDetail | String |
거래수단 |
| withdrawMethod | String |
환불 유형(CREDIT_CARD, VIRTUAL_ACCOUNT, ADMIN_CASH) |
예제
요청
curl -G GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/cash/list" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json" \
-d "page=0" \
-d "limit=20" \
-d "from=2023-01-01" \
-d "to=2023-12-31"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"content": [
{
"dt": "2023-10-13T00:01:49",
"type": "CHARGE",
"chargeMethod": "SYSTEM_FREECASH",
"amount": 10000.0,
"memberType": "SYSTEM",
"memberEmail": "-",
"memberName": "(주)카카오",
"methodDetail": null,
"withdrawMethod": null
},
{
"dt": "2023-10-05T16:49:10",
"type": "CHARGE",
"chargeMethod": "ADMIN_FREECASH",
"amount": 66.0,
"memberType": "DSP_ACCOUNT",
"memberEmail": "test1***@gmail.com",
"memberName": "라이언",
"methodDetail": null,
"withdrawMethod": null
},
{
"dt": "2023-10-05T16:48:43",
"type": "CHARGE",
"chargeMethod": "ADMIN_FREECASH",
"amount": 1000.0,
"memberType": "DSP_ACCOUNT",
"memberEmail": "test***@gmail.com",
"memberName": "어피치",
"methodDetail": null,
"withdrawMethod": null
},
{
"dt": "2023-09-13T20:00:43",
"type": "REFUND",
"chargeMethod": "CPMS",
"amount": 220.0,
"memberType": "SYSTEM",
"memberEmail": "-",
"memberName": "(주)카카오",
"methodDetail": null,
"withdrawMethod": null
},
{
"dt": "2023-09-12T19:46:46",
"type": "CHARGE",
"chargeMethod": "CREDIT_CARD",
"amount": 1000000.0,
"memberType": "DSP_ACCOUNT",
"memberEmail": "tes****@gmail.com",
"memberName": "죠르디",
"methodDetail": "신한 553146**********",
"withdrawMethod": null
},
{
"dt": "2023-10-06T00:06:35",
"type": "CHARGE",
"chargeMethod": "EXPIRE_FREECASH",
"amount": -3499.0,
"memberType": "SYSTEM",
"memberEmail": "-",
"memberName": "(주)카카오",
"methodDetail": null,
"withdrawMethod": null
}
],
"pageable": {
"sort": {
"unsorted": true,
"sorted": false,
"empty": true
},
"pageNumber": 0,
"pageSize": 5,
"offset": 0,
"unpaged": false,
"paged": true
},
"totalPages": 1,
"totalElements": 5,
"last": true,
"first": true,
"size": 20,
"number": 0,
"sort": {
"unsorted": true,
"sorted": false,
"empty": true
},
"numberOfElements": 5,
"empty": false
}
충전 결제 요청
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/cash/charge-order |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고에 사용할 광고캐시 충전 결제를 요청합니다. 이 API로 쉬운 메시지광고 전용 선불 광고주에게 필요한 충전 결제 기능을 제공할 수 있습니다. 결제 요청 시 카카오 고객센터 연락처(1577-3754)를 제공해 결제 중 발생하는 문제를 문의할 수 있도록 안내해야 합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청합니다. 요청 시 제휴사가 제공하는 결제 완료 후 랜딩 페이지의 URL을 redirectUrl로 전달해야 합니다. 요청 성공 시 응답은 PG사의 팝업 결제 페이지 URL인 paymentUrl를 포함합니다.
요청 파라미터의 redirectUrl과 응답 필드의 paymentUrl 값으로 아래와 같이 결제 요청을 처리할 수 있습니다.
- 충전 결제 요청 API를 호출합니다.
- 충전 결제 요청 API 성공 응답으로 받은
paymentUrl을 새 창으로 열어 사용자가 결제를 수행하도록 합니다. - 결제 완료 후, 결제 페이지에서 직접 이동(
location.href = '#redirect_url#')으로 부모창을 제어해redirectUrl로 돌아갑니다.
실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
본문
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| amount | Long |
결제 금액 | O |
| redirectUrl | String |
제휴사가 제공하는 결제 완료 후 랜딩 페이지의 URL | O |
| userIp | String |
결제 요청자 IP, 제휴사 또는 선불 광고주의 IP | X |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| kakaoBillingTxId | String |
트랜잭션(Transaction) ID |
| paymentUrl | String |
PG사의 팝업 결제 페이지 URL |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/cash/charge-order" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
-d '{
"amount" : 10000,
"redirectUrl" : "https://daum.net",
"userIp" : "127.0.0.1"
}'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"kakaoBillingTxId": "7000000000385335",
"paymentUrl": "https://dkpg-web.payments.kakao.com/dkpg/v1/pay_form?&dkpg_payment_id=7000000000385335&session_key=1699590828399-3d15a741-e751-4aea-9973-bc4538981b78"
}
무상캐시 사용 현황 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/free-cash |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고에 사용할 수 있는 무상캐시 사용 현황을 조회합니다. 광고계정 생성 시 지급받은 쉬운 메시지광고 전용 무상캐시는 status이 USING, description이 메세지 발송 프로모션 무상캐시 지급입니다.
무상캐시의 만료기간은 아래와 같습니다.
- 최초 지급된 무상캐시: 생성일 기준 30일까지
- 메세지 미발송분으로 지급된 무상캐시: 지급일 기준 3개월까지
무상캐시의 상태에 따라 제공하는 기간정보는 아래와 같습니다.
- USING, USED :
beginDt,usedDt,endDt,createDt - READY, EXPIRED :
endDt,createDt
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 무상캐시 사용 현황을 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| content | FreeCashTo[] |
무상캐시 사용 현황 |
FreeCashTo
| 이름 | 타입 | 설명 |
|---|---|---|
| id | Long |
무상캐시 지급 ID |
| amount | String |
무상캐시 지급 액수 |
| status | String |
무상캐시 상태 READY: 대기 USING: 사용중 USED: 사용완료 EXPIRED: 기간만료 CANCEL: 취소 |
| description | String |
무상캐시 지급 (메세지 발송 프로모션 무상캐시 지급) |
| issueMemberKakaoEmail | String |
무상캐시 사용자 이메일 |
| createDt | String |
무상캐시 생성일 |
| beginDt | String |
무상캐시 사용 시작일 |
| endDt | String |
무상캐시 만료일 |
| usedDt | String |
무상캐시 사용일 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/free-cash" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
{
"id": 31778,
"amount": 1000.0,
"status": "USING",
"description": "메세지 발송 프로모션 무상캐시 지급",
"issueMemberKakaoEmail": null,
"createDt": "2023-10-06T16:15:37",
"beginDt": "2023-10-06T16:15:37",
"endDt": "2023-11-05",
"usedDt": "2023-10-06T16:15:37",
},
{
"id": 32068,
"amount": 66.0,
"status": "READY",
"description": "메세지 미발송분",
"issueMemberKakaoEmail": null,
"createDt": "2023-10-25T14:19:29",
"beginDt": null,
"endDt": "2024-01-25",
"usedDt": null
}
]
무상캐시 사용
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/free-cash/${FREE_CASH_ID}/use |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
무상캐시를 사용하도록 설정합니다. 무상캐시 사용 현황 조회 시 status가 READY이고 만료일이 경과하지 않은 무상캐시 대상으로만 요청할 수 있습니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청합니다. 요청 성공 시 응답은 무상캐시 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
경로 변수
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| FREE_CASH_ID | String |
무상캐시 지급 ID | O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| id | Long |
무상캐시 지급 ID |
| amount | Double |
무상캐시 지급 액수 |
| status | String |
무상캐시 상태 READY: 대기 USING: 사용중 USED: 사용완료 EXPIRED: 기간만료 CANCEL: 취소 |
| description | String |
무상캐시 지급 이유(메세지 미발송분) |
| issueMemberKakaoEmail | String |
무상캐시 사용자 이메일 |
| createDt | String |
무상캐시 생성일 |
| beginDt | String |
무상캐시 사용 시작일 |
| endDt | String |
무상캐시 만료일 |
| usedDt | String |
무상캐시 사용일 |
예제
요청
curl -X POST "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/free-cash/${FREE_CASH_ID}/use" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": 493206,
"amount": 100000,
"status": "USING",
"description": "메시지 미발송분",
"beginDt": "2024-11-01T13:27:10.620737",
"endDt": "2025-11-30",
"usedDt": "2024-11-01T13:27:10.620737"
}
광고캐시 잔액 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/balance |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고 전용 광고캐시 잔액을 조회합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 광고캐시 잔액 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| cash | Double |
유상캐시(환불 가능 금액) |
| freeCash | Double |
무상캐시 |
| freeCashReady | Double |
무상캐시(대기) |
| creditLimit | Long |
후불 한도 |
| remainedCreditLimit | Double |
가용 후불 한도 |
| holdAutopayCard | Boolean |
자동결제 신용카드 등록 여부 |
| deferredPayment | Boolean |
후불 여부 |
| active | Boolean |
삭제 여부 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/balance" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"cash": 0.0,
"freeCash": 9087.0,
"freeCashReady": 797.5,
"creditLimit": 10000,
"remainedCreditLimit": 10000.0,
"holdAutopayCard": false,
"deferredPayment": true,
"active": true
}
광고캐시 소진 금액 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/spend |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고에 사용된 광고캐시를 조회합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 광고캐시 잔액과 소진금액 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| cash | Double |
유상캐시(환불 가능 금액) |
| freeCash | Double |
무상캐시 |
| creditLimit | Long |
후불 한도 |
| deferredPayment | Boolean |
후불 여부 |
| balance | Double |
잔액(유상캐시와 무상캐시의 합) |
| todaySpend | Double |
오늘 소진 공급가액 |
| todaySpendVat | Double |
오늘 소진 부가세액 |
| yesterdaySpend | Double |
어제 소진 공급가액 |
| yesterdaySpendVat | Double |
어제 소진 부가세액 |
| thisMonthSpendCash | Double |
당월 유상캐시 소진 공급가액 |
| thisMonthSpendCashVat | Double |
당월 유상캐시 소진 부가세액 |
| monthSpend | Double |
당월 소진 공급가액 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/spend" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"cash": 0.0,
"freeCash": 9087.0,
"creditLimit": 10000,
"deferredPayment": true,
"balance": 9087.0,
"todaySpend": 0.0,
"todaySpendVat": 0.0,
"yesterdaySpend": 0.0,
"yesterdaySpendVat": 0.0,
"thisMonthSpendCash": 105.0,
"thisMonthSpendCashVat": 10.5,
"monthSpend": 105.0
}
환불 요청
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고 전용 광고캐시를 환불 요청합니다. 전액 환불 요청은 광고계정 상태가 OFF일 때만 가능합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청합니다. 요청 성공 시 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
본문
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| allWithdraw | Boolean |
전액 환불 여부 | O |
| amount | Long |
환불 금액 | O |
| reason | String |
환불 이유 | O |
예제
요청
curl -X POST "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
-d '{
"allWithdraw": false,
"amount" : 10000,
"reason" : "이유"
}'
응답
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8
환불 내역 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고 전용 광고캐시의 환불 내역을 조회합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 환불 내역을 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
쿼리 파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| page | Integer |
페이지 번호 0부터 시작 |
X |
| limit | Integer |
페이지 사이즈(기본값: 20) | X |
| from | String |
지표 조회 기간 시작일(yyyy-MM-dd 형식)미입력 시 조회 당일부터 2년 전으로 설정하여 조회함 |
X |
| to | String |
지표 조회 기간 종료일(yyyy-MM-dd 형식) |
X |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| content | WithdrawTo[] |
환불 내역 |
| totalElements | Long |
전체 응답 가능한 결과 수 |
| totalPages | Long |
총 페이지 수 조회 시 응답될 총 페이지 수 |
| first | Boolean |
첫 페이지 여부 true: 첫 페이지false: 첫 페이지가 아님 |
| last | Boolean |
마지막 페이지 여부true: 마지막 페이지false: 마지막 페이지가 아님 |
| size | Integer |
페이지 사이즈 1페이지당 노출되는 결과 수 |
| number | Integer |
페이지 번호 |
| numberOfElements | Integer |
현재 페이지에 응답된 결과 수 |
WithdrawTo
| 이름 | 타입 | 설명 |
|---|---|---|
| id | Long |
환불 요청 ID |
| requestDt | String |
요청 날짜 |
| requestReason | String |
요청 이유 |
| requestAmount | Long |
환불 요청 금액 |
| status | String |
환불 상태(RESERVED, STANDBY, APPROVED, REJECTED, ASK_ADMIN) |
| memberId | String |
환불 요청자 ID |
| memberEmail | String |
환불 요청자 이메일 |
| memberStatus | String |
환불 요청자 상태 |
| requestType | String |
환불 요청 타입(MANUAL_REQUEST, AUTO_REQUEST) |
| details | DetailTo[] |
환불 상세 내역 |
DetailTo
| 이름 | 타입 | 설명 |
|---|---|---|
| id | Long |
환불 상세 내역 ID |
| dt | String |
날짜 |
| amount | Long |
환불 금액 |
| requestAmount | Long |
환불 요청 금액 |
| requestWithdrawMethod | String |
환불 요청 방법 |
| status | String |
환불 상세 상태(SETTLED, PRE, SUCCESS, FAIL, ASK_ADMIN, CANCELED_SETTLE) |
| statusDesc | String |
환불 상태 설명 |
| kakaoBillingTxId | String |
거래번호 |
| chargeMethod | String |
충전 방법 |
| chargeCardName | String |
충전 카드명 |
| chargeCardNumber | String |
충전 카드번호 |
| chargeKakaoEmail | String |
충전 거래자 이메일 |
| chargeMemberStatus | String |
충전 거래자 상태 |
| chargeMemberType | String | 충전 거래자 유형, 아래 중 하나DSP_ACCOUNT: 광고계정ID를 사용해 DSP 또는 API로 충전하는 광고주INHOUSE_ACCOUNT: 어드민 기능으로 충전하는 카카오 내부 관리자AGENCY_ACCOUNT: 에이전시 플랫폼에서 충전하는 마케터 혹은 대행사SYSTEM: 카카오 시스템 |
| chargeAmount | Long | 충전 금액 |
| chargeRemainAmount | Long | 충전 잔여금액 |
| withdrawMethod | String | 환불 방법 |
| failReason | String | 환불 실패 원인 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw?page=0&size=20&from=2023-01-01&to=2023-12-31" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"content": [
{
"id": 7299,
"requestDt": "2023-11-08T11:17:59",
"requestReason": "auto withdraw because of charging on deferred payment wallet",
"requestAmount": 19000,
"status": "STANDBY",
"memberId": "system",
"memberEmail": null,
"memberStatus": null,
"requestType": "AUTO_REQUEST",
"details": [
{
"id": 6017,
"dt": null,
"amount": null,
"requestAmount": 19000,
"requestWithdrawMethod": "계좌 환불",
"status": "SETTLED",
"statusDesc": "금액확정",
"kakaoBillingTxId": null,
"chargeMethod": "무통장 입금",
"chargeCardName": null,
"chargeCardNumber": null,
"chargeKakaoEmail": null,
"chargeMemberStatus": null,
"chargeMemberType": "SYSTEM",
"chargeAmount": 19000,
"chargeRemainAmount": 0,
"withdrawMethod": null,
"failReason": null
}
]
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 20,
"sort": {
"empty": true,
"sorted": false,
"unsorted": true
},
"offset": 0,
"paged": true,
"unpaged": false
},
"last": true,
"totalElements": 1,
"totalPages": 1,
"first": true,
"size": 20,
"number": 0,
"sort": {
"empty": true,
"sorted": false,
"unsorted": true
},
"numberOfElements": 1,
"empty": false
}
환불계좌 등록
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
환불계좌를 등록합니다. 은행 정기점검 시간에는 환불계좌 등록이 불가능합니다. 사업자 유형에 따라 아래 조건을 만족하는 환불계좌만 등록할 수 있습니다.
- 개인사업자
- 등록 가능한 환불계좌: 사업자 명의의 사업용 계좌 또는 사업자 본인의 개인 명의 계좌
- 예금주명: 대표자명, 상호명
- 법인사업자
- 등록 가능한 환불계좌: 법인 명의 계좌
- 예금주명: 법인명
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청하고, 요청 성공 시 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
본문
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| accountNumber | String |
환불 계좌번호 | O |
| bankCode | String |
은행 코드 참고: 환불계좌 등록 가능 은행코드 조회 |
O |
| ownerName | String |
예금주명 | O |
예제
요청
curl -X POST "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json" \
-d '{
"accountNumber": "111-2********",
"bankCode": "88",
"ownerName": "플*토"
}'
응답
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8
환불계좌 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
환불계좌 정보를 조회합니다. 은행 정기점검 시간에는 환불계좌 조회가 불가능합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 환불계좌 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| accountNumber | String |
환불 계좌번호 |
| bankCode | String |
은행 코드 |
| ownerName | String |
예금주명 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"accountNumber": "111-2********",
"bankCode": "88",
"ownerName": "플*토"
}
환불계좌 수정
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
PUT |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
환불계좌 정보를 수정합니다. 은행 정기점검 시간에는 환불계좌 수정이 불가능합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 PUT으로 요청합니다. 요청 성공 시 응답 본문은 없습니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
본문
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| accountNumber | String |
환불 계좌번호 | O |
| bankCode | String |
은행 코드 참고: 환불계좌 등록 가능 은행코드 조회 |
O |
| ownerName | String |
예금주명 | O |
예제
요청
curl -X PUT "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json" \
-d '{
"accountNumber": "111-2********",
"bankCode": "88",
"ownerName": "플*토"
}'
응답
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8
환불계좌 삭제
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
DELETE |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
환불계좌 정보를 수정합니다. 은행 정기점검 시간에는 환불계좌 삭제가 불가능합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 DELETE로 요청합니다. 요청 성공 시 응답은 본문 없이 HTTP 200 상태 코드만 반환합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
예제
요청
curl -v -X DELETE "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Length: 0
Content-Type: application/json;charset=UTF-8
환불계좌 등록 가능 은행코드 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account/bank-code |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
환불계좌 등록 시 사용할 은행 코드를 조회합니다. 조회 결과에 포함된 은행 코드만 환불계좌 등록 및 수정 시 사용할 수 있습니다. 은행 코드는 추후 추가될 수 있습니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 은행 코드 목록을 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| - | BankCodeTo |
은행 코드 목록 |
BankCodeTo
| 이름 | 타입 | 설명 |
|---|---|---|
| code | String |
은행 코드 |
| type | String |
은행 종류 |
| name | String |
은행 이름 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/withdraw/account/bank-code" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
[
{"code":"02","type":"SANUP","name":"산업"},
{"code":"03","type":"KIUP","name":"기업"},
{"code":"04","type":"KOOKMIN","name":"국민"},
{"code":"07","type":"SUHYUP","name":"수협"},
{"code":"11","type":"NONGHYUP_CENTER","name":"농협중앙"},
{"code":"12","type":"NONGHYUP_LOCAL","name":"농협(단위조합)"},
{"code":"20","type":"WOORI","name":"우리"},
{"code":"23","type":"SC","name":"SC제일"},
{"code":"27","type":"CITY","name":"씨티"},
{"code":"31","type":"DAEGU","name":"대구"},
{"code":"32","type":"BUSAN","name":"부산"},
{"code":"34","type":"GWANGJU","name":"광주"},
{"code":"35","type":"JEJU","name":"제주"},
{"code":"37","type":"JEONBOOK","name":"전북"},
{"code":"39","type":"KYEONGNAM","name":"경남"},
{"code":"45","type":"SAEMAEUL","name":"새마을"},
{"code":"48","type":"SINHYUP","name":"신협"},
{"code":"54","type":"HSBC","name":"HSBC"},
{"code":"71","type":"POSTOFFICE","name":"우체국"},
{"code":"81","type":"HANA","name":"KEB하나"},
{"code":"88","type":"SINHAN","name":"신한"},
{"code":"89","type":"K_BANK","name":"케이뱅크"},
{"code":"90","type":"KAKAO_BANK","name":"카카오뱅크"},
{"code":"209","type":"YUANTA_SECURITIES","name":"유안타증권"},
{"code":"240","type":"SAMSUNG_SECURITIES","name":"삼성증권"}
]
가상계좌 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/virtual-accounts |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고 전용으로 발급된 가상계좌를 조회합니다. 선불 광고주는 충전 결제 요청, 후불 광고주는 후불 결제 요청으로 결제 시 무통장 입금을 선택해 가상계좌를 발급받을 수 있습니다. 가상계좌는 30일간 유효합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 가상계좌 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| accountNumber | String |
가상계좌 번호 |
| accountOwnerName | String |
가상계좌 예금주명 |
| amount | Long |
입금금액 |
| bankCode | String |
은행코드 |
| bankName | String |
은행명 |
| expireDttm | String |
가상계좌 만료일시 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/bond/virtual-accounts" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"content": [
{
"accountNumber": "string",
"accountOwnerName": "string",
"amount": 0,
"bankCode": "string",
"bankName": "string",
"expireDttm": "yyyy-MM-dd'T'HH:mm:ss"
}
]
}
후불 결제 현황 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/bond |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고 전용 후불 결제 현황을 조회합니다. repaymentAmount는 결제 가능 내역 조회의 전체 미결제 금액에서 가상계좌 입금대기 금액을 뺀 금액입니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 후불 결제 현황 정보를 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
쿼리 파라미터
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| page | Integer |
페이지 번호 0부터 시작 |
X |
| limit | Integer |
페이지 사이즈(기본값: 20) | X |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| content | BondTo[] |
후불 결제 현황 |
| totalElements | Long |
전체 응답 가능한 결과 수 |
| totalPages | Long |
총 페이지 수 조회 시 응답될 총 페이지 수 |
| first | Boolean |
첫 페이지 여부 true: 첫 페이지false: 첫 페이지가 아님 |
| last | Boolean |
마지막 페이지 여부true: 마지막 페이지false: 마지막 페이지가 아님 |
| size | Integer |
페이지 사이즈 1페이지당 노출되는 결과 수 |
| number | Integer |
페이지 번호 |
| numberOfElements | Integer |
현재 페이지에 응답된 결과 수 |
BondTo
| 이름 | 타입 | 설명 |
|---|---|---|
| bondAmount | Long |
채권 금액 |
| bondType | String |
채권 유형(GENERAL, PENALTY) |
| businessRegistrationNumber | String |
사업자 등록 번호 |
| companyName | String |
사업자 이름 |
| dueDt | String |
상환 기간 |
| lastestRepaymentDt | String |
최근 상환일 |
| overdue | Boolean |
연체 여부 |
| remainedBondAmount | Long |
채권 잔액 |
| repayable | Boolean |
미결제액 존재여부 |
| repaymentAmount | Long |
상환 누적금액 |
| repaymentCompleted | Boolean |
상환여부 |
| repaymentPeriod | String |
결제기준일(DAYS_30, DAYS_60, DAYS_90, DAYS_120) |
| repaymentStatus | String |
채권 상태(READY, PARTIAL, DONE, OVERDUE) |
| settleDt | String |
정산월 |
| repayments | RepaymentTo[] |
상환 상세 |
RepaymentTo
| 이름 | 타입 | 설명 |
|---|---|---|
| chargeAmount | Long |
충전 금액 |
| chargeMethod | String |
충전 방법 |
| chargeMethodDetail | String |
충전 방법 상세 |
| dt | String |
날짜 |
| journalTransactionId | String |
저널식별자 |
| memberEmail | String |
거래자 카카오 이메일 |
| memberId | String |
거래자 ID |
| memberName | String |
거래자 이름 |
| memberStatus | String |
거래자 상태 |
| memberType | String |
충전 거래자 유형, 아래 중 하나DSP_ACCOUNT: 광고계정ID를 사용해 DSP 또는 API로 충전하는 광고주INHOUSE_ACCOUNT: 어드민 기능으로 충전하는 카카오 내부 관리자AGENCY_ACCOUNT: 에이전시 플랫폼에서 충전하는 마케터 혹은 대행사SYSTEM: 카카오 시스템 |
| repaymentAmount | Long |
상환 금액 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/bond?page=0&size=20" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"content": [
{
"bondAmount": 10000,
"bondType": "GENERAL",
"businessRegistrationNumber": "string",
"companyName": "string",
"dspId": "KAKAOMOMENT",
"dueDt": "90",
"lastestRepaymentDt": "string",
"overdue": true,
"remainedBondAmount": 0,
"repayable": true,
"repaymentAmount": 10000,
"repaymentCompleted": false,
"repaymentPeriod": "DAYS_90",
"repaymentStatus": "READY",
"settleDt": "2024-02",
"repayments": [
{
"chargeAmount": 0,
"chargeMethod": "string",
"chargeMethodDetail": "string",
"dt": "yyyy-MM-dd'T'HH:mm:ss",
"journalTransactionId": "string",
"memberEmail": "string",
"memberId": "string",
"memberName": "string",
"memberStatus": "string",
"memberType": "DSP_ACCOUNT",
"repaymentAmount": 10000
}
]
}
],
"pageable": {
"pageNumber": 0,
"pageSize": 20,
"sort": {
"empty": true,
"sorted": false,
"unsorted": true
},
"offset": 0,
"paged": true,
"unpaged": false
},
"last": true,
"totalElements": 1,
"totalPages": 0,
"first": true,
"size": 20,
"number": 1,
"sort": {
"empty": true,
"sorted": false,
"unsorted": true
},
"numberOfElements": 0,
"empty": true
}
결제 가능 내역 조회
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/bond/repay |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고 전용 후불 광고주 대상으로 결제 가능 내역을 조회합니다. 결제 가능한 금액은 미결제 금액으로, 전체 미결제 금액 중 가상계좌 입금대기 금액을 제외한 금액입니다. 미결제 금액에 대해 후불 결제 요청으로 결제 가능합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 결제 가능 내역을 포함합니다. 실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| nextDueDt | String |
다음 결제기한일 |
| repays | RepayTo[] |
정산 결제 정보 |
RepayTo
| 이름 | 타입 | 설명 |
|---|---|---|
| dueDtRemainedBondAmount | Long |
기한일 기준 미결제 금액 |
| planRepayAmount | Long |
가상계좌 입금대기 금액 |
| remainedBondAmount | Long |
전체 미결제 금액 |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/bond/repay" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${CHANNEL_PROFILE_ID}" \
-H "Content-Type: application/json"
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"repays": [
{
"dueDtRemainedBondAmount": 0,
"planRepayAmount": 0,
"remainedBondAmount": 0
}
],
"nextDueDt": "string"
}
후불 결제 요청
기본 정보
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST |
https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/bond/repay |
비즈니스 토큰 |
| 권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
|---|---|---|---|
| 필요: 제휴 및 대행 계약 | 비즈 앱 전환 비즈니스 리다이렉트 URI 등록 비즈니스 동의항목 |
필요 | 필요 |
쉬운 메시지광고 전용 후불 광고주 대상으로 후불 결제를 요청합니다. 결제 가능 내역 조회로 확인한 미결제 금액에 대해 결제 요청해야 합니다. 결제 요청 시 카카오 고객센터 연락처(1577-3754)를 제공해 결제 중 발생하는 문제를 문의할 수 있도록 안내해야 합니다.
비즈니스 토큰과 카카오톡 채널 프로필 ID를 헤더에 담아 POST로 요청합니다. 요청 시 제휴사가 제공하는 결제 완료 후 랜딩 페이지의 URL을 redirectUrl로 전달해야 합니다. 요청 성공 시 응답은 PG사의 팝업 결제 페이지 URL인 paymentUrl를 포함합니다.
요청 파라미터의 redirectUrl과 응답 필드의 paymentUrl 값으로 아래와 같이 결제 요청을 처리할 수 있습니다.
- 후불 결제 요청 API를 호출합니다.
- 후불 결제 요청 API 성공 응답으로 받은
paymentUrl을 새 창으로 열어 사용자가 결제를 수행하도록 합니다. - 결제 완료 후, 결제 페이지에서 직접 이동(
location.href = '#redirect_url#')으로 부모창을 제어해redirectUrl로 돌아갑니다.
실패 시 에러 코드 및 상세 에러 코드로 원인을 확인합니다.
요청
헤더
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
| channel-profile-id | channel-profile-id: ${CHANNEL_PROFILE_ID}카카오톡 채널 프로필 ID |
O |
| Content-Type | Content-Type: application/json요청 데이터 타입 |
O |
본문
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| amount | Long |
결제 금액 | O |
| redirectUrl | String |
제휴사가 제공하는 결제 완료 후 랜딩 페이지의 URL | O |
| userIp | String |
결제 요청자 IP 제휴사 또는 선불 광고주의 IP |
O |
응답
본문
| 이름 | 타입 | 설명 |
|---|---|---|
| kakaoBillingTxId | String |
트랜잭션(Transaction) ID |
| paymentUrl | String |
PG사의 팝업 결제 페이지 URL |
예제
요청
curl -X GET "https://apis.moment.kakao.com/openapi/message/v1/message-ad-accounts/wallet/bond/repay" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}" \
-H "channel-profile-id: ${channel-profile-id}" \
-H "Content-Type: application/json"
-d '{
"amount" : 10000,
"redirectUrl" : "https://daum.net",
"userIp" : "127.0.0.1"
}'
응답
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"kakaoBillingTxId": "7000000000385335",
"paymentUrl": "https://dkpg-web.payments.kakao.com/dkpg/v1/pay_form?&dkpg_payment_id=7000000000385335&session_key=1699590828399-3d15a741-e751-4aea-9973-bc4538981b78"
}