토스페이먼츠에서는 카드 및 계좌 즉시할인을 제공하고 있습니다. 아래는 프로모션 진행시, 연동 측면에서 각 제품별 고려해야할 부분입니다.
목차
결제창(카드, 퀵계좌이체), 결제위젯 , 브랜드페이 결제창
•
별도의 추가적인 연동 없이 즉시할인 기능 사용 가능합니다. 프로모션 안내/적용 모두 토스페이먼츠에서 자동으로 진행합니다.
•
단 가맹점에 따라 응답값 및 부분 취소 정책 확인이 필요할 수 있습니다. ‘ 공통사항’을 확인해주세요.
공통사항’을 확인해주세요. 카드사 직호출 (자체창)
토스페이먼츠 결제창을 통하지 않고, 카드사 결제창을 직접 호출할 경우 프로모션을 직접 적용 및 관리해주셔야합니다.
•
프로모션 적용
◦
프로모션 조회 API를 사용해 현재 진행 중인 Promotion 정보확인
◦
금액/잔액/issuerCode를 확인하여, 조건에 부합하는 카드가 있을 경우 discountCode를 결제요청시 보냅니다.
▪
카드사 프로모션은 발급사 기준으로 진행됩니다. 프로모션 조회API 응답값 중 cardCompany가 아닌 issuerCode 기반으로 비교해주세요.
◦
동일 원천사(카드사, 은행)에 조건(dueDate, MinMaxAmount 등)이 다른 경우 프로모션은 1개 이상 응답될 수 있습니다. 이 경우 고객에 유리한 조건 1개를 적용하거나 고객이 프로모션을 선택할 수 있도록 고려되어야 합니다.
tossPayments.requestPayment('카드', {
amount: 15000,
orderId: 'c9znPX7QtRfsLuIUiSD9-',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
discountCode: '10000',
flowMode: 'DIRECT',
cardCompany: '삼성',
})
JavaScript
복사
브랜드페이 API
브랜드페이 API 방식도 프로모션을 직접 적용 및 관리해주셔야합니다.
•
프로모션 적용
결제수단조회API (혹은 getPaymentMethods())를 사용해서 가맹점에서 직접 프로모션을 적용해줘야 해요. API 응답값으로 promotion 배열이 내려오는 결제 수단일 경우, 결제요청(requestPayment)시 discountCode 파라미터를 올려줘야해요.
[결제수단조희 데이터 샘플]
◦
단, 응답값이 내려오더라도 프로모션 기준금액 (minimumPaymentAmount)과 결제금액을 비교해줘야해요. 기준금액에 맞지 않은 주문에 discountCode를 포함해 결제요청할 경우, 아래와 같이 에러가 발생하고 결제 실패되요.
◦
프로모션 예산이 모두 소진되면, promotion 배열이 비어서 내려가요.
◦
1인 1회만 적용되도록 설정한 프로모션이라면, 1회 사용한 사용자에게는 promotion 배열이 비어서 내려가요.
공통 사항
•
결제 응답에 discount.amount 로 할인 금액을 전달드려요. 필수로 연동하셔야 하는 값은 아니지만, 이 값을 통해 거래에 적용된 할인 금액을 확인할 수 있어요.
{
"mId": "op_inmanaged",
"lastTransactionKey": "719C5B32D816BDF14476FEB1E4771821",
"paymentKey": "op_in20240216110925bkGf9",
"orderId": "tosspayments33063590",
"orderName": "토스 티셔츠% (베이지)",
"taxExemptionAmount": 0,
"status": "DONE",
"requestedAt": "2024-02-16T11:09:25+09:00",
"approvedAt": "2024-02-16T11:09:26+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": null,
"transfer": {
"bank": "하나",
"bankCode": "81",
"settlementStatus": "INCOMPLETED"
},
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": {
"type": "소득공제",
"receiptKey": "Wzn16mywdYPBal2vxj81galJKgdJQkV5RQgOAND7pJe9KE0q",
"issueNumber": "160384267",
"receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/tosspayments33063590/op_inmanaged?ref=PX",
"amount": 9000,
"taxFreeAmount": 0
},
"cashReceipts": [
{
"receiptKey": "Wzn16mywdYPBal2vxj81galJKgdJQkV5RQgOAND7pJe9KE0q",
"orderId": "tosspayments33063590",
"orderName": "토스 티셔츠% (베이지)",
"type": "소득공제",
"issueNumber": "160384267",
"receiptUrl": "https://dashboard.tosspayments.com/receipts/cash-receipt/tosspayments33063590/op_inmanaged?ref=PX",
"businessNumber": "2410301917",
"transactionType": "CONFIRM",
"amount": 9000,
"taxFreeAmount": 0,
"issueStatus": "IN_PROGRESS",
"failure": null,
"customerIdentityNumber": "01044084262",
"requestedAt": "2024-02-16T11:09:26+09:00"
}
],
"discount": { "amount": 1000 },
"cancels": null,
"secret": "ps_BX7zk2yd8ydDYBEjXN9Lrx9POLqK",
"type": "BRANDPAY",
"easyPay": null,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": {
"url": "https://pgweb.tosspayments.com:9091/MpFlowCtrl?eventDiv1=search&eventDiv2=getBankReceipt&trxid=op_in20240216110925bkGf9&SYSTEM=NEW"
},
"checkout": {
"url": "https://api.tosspayments.com/v1/payments/op_in20240216110925bkGf9/checkout"
},
"pgTransactionId": "op_in20240216110925bkGf9",
"transactionKey": "719C5B32D816BDF14476FEB1E4771821",
"currency": "KRW",
"totalAmount": 10000,
"balanceAmount": 10000,
"suppliedAmount": 9091,
"vat": 909,
"taxFreeAmount": 0,
"method": "계좌이체",
"version": "2022-07-27"
}
JSON
복사
응답 샘플
•
취소 정책 관련해서 확인 필요할 수 있어요. 취소 불가한 거래건일 경우 아래와 같이 에러메세지가 내려가요. {"code":"EXCEED_CANCEL_AMOUNT_DISCOUNT_AMOUNT","message":"즉시할인금액보다 적은 금액은 부분취소가 불가능합니다."}
•
프로모션 표기
취소 정책
전체 취소
중복 제한이 있는 프로모션에서 즉시할인이 적용된 거래 건을 전체 취소하는 경우, 받았던 할인도 취소되어 다시 혜택을 받을 수 있게 돼요.
정액할인_부분취소
부분취소 발생 시,
•
부분취소 후 잔액이 기준 금액 이상인 경우 지불금액에서 취소 처리해요.
•
부분취소 후 잔액이 기준 금액 미만인 경우
할인 받은 금액보다 큰 금액으로 취소 요청 시에만 취소가 가능해요.
이 때, 할인 금액부터 취소 후 남은 금액을 지불금액에서 취소 처리해요.
•
즉, 할인 금액의 부분취소는 불가해요.
잠깐 !
여기서 지불 금액은 즉시할인 적용 후 실제 유저의 계좌로 결제된 금액을 말해요.
ex. 프로모션 조건 : 50,000 원 이상 결제 시 3,000원 할인
1.
원승인
•
55,000 원 결제
•
3,000 원 할인 적용되서
•
유저가 결제한 지불금액은 52,000 원
•
고객은행잔고: -52,000
2.
부분취소 1
•
4,000 원 부분취소 요청
•
55,000 - 4,000 = 51,000 원으로 부분취소 후에도 할인 대상에 해당
•
할인 대상이기 때문에 할인 금액은 그대로 두고
지불금액 4,000 원을 취소해서 유저에 4,000 원을 돌려줌
•
고객은행잔고: +4,000
3.
부분취소 2 :: 잔여 승인금액 = 51,000
•
2,000 원을 부분취소 요청
•
51,000 - 2,000 = 49,000 원이라 부분취소 후 할인 달성 조건이 깨짐
•
할인 조건이 깨졌을 때 부분취소는 할인 금액보다 크게만 가능한데
•
할인 받은 금액은 3,000 원이고 부분취소 요청 금액은 2,000 원이라 취소 실패 처리 함
•
고객은행잔고: 변화없음
4.
부분취소 3 :: 잔여 승인금액 = 51,000
•
5,000 원을 부분취소 요청
•
51,000 - 5,000 = 46,000 원으로 부분취소 후 할인 달성 조건이 깨짐
•
할인 금액인 3,000 원 보다 큰 금액으로 부분취소를 요청했기 때문에 부분취소 성공 처리함
•
할인 금액을 우선 차감하기 때문에 할인 금액에서 3,000 원 취소,
지불금액에서 남은 2,000 원을 취소해서 유저에 2,000 원을 돌려줌
•
고객은행잔고: +2,000
[정액할인 부분취소 데이터 샘플]
정액할인_부분취소_가맹점대응방법
1.
부분취소는 할인받은 금액 이상으로만 취소한다.
2.
부분취소 실패시 안내문구(에러)를 노출하고 해당 금액 이상으로 부분취소 가능하다고 안내한다.
(부분취소 할인 금액 미만때문에 취소 안되는 경우 강제로 취소를 하는 것은 고객이 손해인 구조)
3.
정액할인 예외케이스를 대응하기 어렵다면 정률할인을 사용한다.
정률할인_부분취소 (정률할인은 퀵계좌이체에서만 제공 중)
부분취소 발생 시,
•
부분취소 후 잔액으로 할인 받을 수 있는 금액을 구해요.
•
재계산 한 할인금액 - 기존 잔여 할인금액 = 취소할 할인금액 을 구해요.
•
부분취소 요청 금액 - 취소할 할인금액 = 취소할 지불금액을 구해요.
•
마지막 부분취소로 전체취소가 발생하는 경우, 별도의 금액 계산 없이 남은 할인 금액과 지불 금액을 모두 취소해요.
•
이 때, 기준 금액은 고려하지 않아요.
ex. 프로모션 조건 : 50,000원 이상 결제 시 11.3% 할인, 최대 1,000원 할인
1.
원승인
•
55,000 원 결제
•
55,000 * 11.3% = 6,210원이나 최대 할인 금액 1,000원 적용되서
•
유저가 결제한 지불금액은 54,000 원
2.
부분취소 1
•
40,000원 부분취소 요청
•
부분취소 후 잔액은 55,000 - 40,000 = 15,000 원으로,
이 때 할인 받을 수 있는 금액은 15,000 * 11.3% = 1,690 원이나
최대 할인 금액 1,000 원 적용되어 1,000 원으로 계산
•
취소할 할인금액 1,000 - 1,000 = 0
•
취소할 지불금액 40,000 - 0 = 40,000 원으로, 유저에 40,000 원을 돌려줌
3.
부분취소 2
•
12,000 원 부분취소 요청
•
부분취소 후 잔액은 15,000 - 12,000 = 3,000원으로,
이 때 할인 받을 수 있는 금액은 3,000 * 11.3% = 330 원으로 계산
•
취소할 할인금액 330 - 1,000 = - 670
•
취소할 지불금액 12,000 - 670 = 11,330 원으로, 유저에 11,330 원을 돌려줌
4.
부분취소 3
•
3,000 원 부분취소 요청
•
부분취소 후 잔액은 3,000 - 3,000 = 0 원으로,
부분취소로 전체취소가 일어나기 때문에 별도 계산 없이
남은 할인 금액과 지불 금액을 각각 취소함
•
취소할 할인금액 = - 330
•
취소할 지불금액 = 2,670 원으로, 유저에 2,670 원을 돌려줌