1. 개요
본 문서는 토스페이먼츠에서 USD 및 JPY 통화로 결제 요청하는 법에 대해 안내합니다. 요청 이후 결제승인 Flow는 기존 국내 결제와 동일하게 승인API(링크)를 호출해주시면 됩니다.
2. 사전 준비
•
계약전에는 아래 정보로 테스트해보실 수 있습니다.
## 결제창
clientKey: test_ck_ALnQvDd2VJYmLewOane3Mj7X41mN
secretKey : test_sk_5OWRapdA8dYwzX15xxA3o1zEqZKL
##결제위젯
widgetClientKey : test_gck_docs_Ovk5rk1EwkEbP0W43n07xlzm
widgetSecretKey : test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6
variantKey : FOREIGN-PAY
JavaScript
복사
•
MID는 각 통화별로 구분되어야 합니다. 기존 국내 결제 수단을 사용하던 MID가 있더라도 USD, JPY 모두 도입 시 추가로 2개의 MID가 필요합니다.
3. 연동 특이사항
다통화 결제는 토스페이먼츠 결제창 및 결제위젯을 통해 연동할 수 있습니다.
A. 결제창
•
요청한 통화(currency) 기반으로 결제창이 열립니다. (예: JPY > 일본어) 이후 결제창에서 언어 변경이 가능하며, 한국어/영어/일본어/중국어를 지원합니다.
•
국내 카드는 토스페이먼츠 결제창을 거치지 않고 카드사를 직접 호출할 수 있지만, 해외 카드는 VISA/MASTER 등 카드사를 직접 호출할 수 없으며 반드시 토스페이먼츠 결제창을 거쳐야 합니다.
B. 결제위젯
결제 위젯은 동일한 통화를 사용하는 결제 수단끼리만 하나의 variantKey(= UI)에 구성할 수 있습니다.
KRW : 국내 카드사, 가상계좌, 계좌이체, 핸드폰, 간편결제(토스페이, 카카오 네이버..) 등
USD : 해외 카드, PAYPAL, Alipay 및 동남아 간편결제수단
JPY : 해외 카드 (일본 간편결제 수단은 추후 추가 예정)
** 해외간편결제+다통화 카드를 동일한 위젯에서 사용하기 위해서는 하나의 MID에 청약되어야 합니다.
결제 위젯에서 각 브랜드사를 선택한 후 결제를 요청하면, 이후 호출되는 결제창에서는 선택한 브랜드사가 고정됩니다.
4. 연동 샘플
주요파라미터
amount number
결제 금액입니다. currency로 USD를 사용할 때는 소수점 사용을 지원합니다. currency로 KRW, JPY를 사용할 때는 소수점 사용을 지원하지 않습니다.
currency string
결제 통화입니다. 일반결제는 KRW, USD, JPY를 지원하며, 기본값은 KRW 입니다.
useInternationalCardOnly boolean
해외카드(Visa, MasterCard, JCB, UnionPay 등) 결제 여부입니다. 다통화 결제시 true로 보내주셔야합니다.
A. 결제창
<script src="https://js.tosspayments.com/v1/payment"></script>
<script>
var clientKey = "{clientKey}";
var tossPayments = TossPayments(clientKey);
tossPayments
.requestPayment("카드", {
orderId: 'rpXzzMZBz3zRM2Z6yo3Hc',
orderName: "토스 티셔츠 외 2건",
successUrl: window.location.origin + "/success",
failUrl: window.location.origin + "/fail",
//** 다통화 주요 파라미터 **//
amount: 10.01,
currency:"USD",
useInternationalCardOnly:"true" // 다통화 결제시 True로 보내주셔야합니다.
})
</script>
JavaScript
복사
<script src="https://js.tosspayments.com/v2/standard"></script>
<script>
const clientKey = "{clientKey}";
const customerKey = "l4rD8quK0dKI44VOA7TgC";
const tossPayments = TossPayments(clientKey);
async function requestPayment() {
await payment.requestPayment({
method: "CARD",
orderId: "LU1khs53rntkCdRgBn0s5",
orderName: "토스 티셔츠 외 2건",
successUrl: window.location.origin + "/success",
failUrl: window.location.origin + "/fail",
//** 다통화 주요 파라미터 **//
amount: {
currency: "USD",
value: 10.01,
},
card: {
useInternationalCardOnly: true
},
});
}
</script>
JavaScript
복사
B. 결제위젯
<script src="https://js.tosspayments.com/v1/payment-widget"></script>
<body>
<div id="payment-method"></div> <!-- 결제 UI -->
<div id="agreement"></div> <!-- 이용약관 UI -->
<button id="payment-button">결제하기</button>
<script>
const clientKey = "{clientKey}";
const customerKey = "l4rD8quK0dKI44VOA7TgC";
const paymentWidget = PaymentWidget(clientKey, customerKey);
paymentWidget.renderPaymentMethods('#payment-method', {
value: 1000,
currency: "JPY"
},{ variantKey: 'GLOBAL_CARD_JPY'});
// ------ 이용약관 UI 렌더링 ------
paymentWidget.renderAgreement("#agreement", {
variantKey: "AGREEMENT_JA"
})
document.querySelector('#payment-button').addEventListener('click', () => {
paymentWidget.requestPayment({
orderId: "LU1khs53rntkCdRgBn0s5",
orderName: "토스 티셔츠 외 2건",
successUrl: window.location.origin + "/success",
failUrl: window.location.origin + "/fail",
useInternationalCardOnly: true // 값이 true면 해외카드 결제가 가능한 다국어 결제창이 열립니다.
})
})
</script>
</body>
HTML
복사
<script src="https://js.tosspayments.com/v2/standard"></script>
<body>
<div id="payment-method"></div> <!-- 결제 UI -->
<div id="agreement"></div> <!-- 이용약관 UI -->
<button id="payment-button">결제하기</button>
<script>
main();
async function main() {
// ------ 결제위젯 초기화 ------
const clientKey = "{clientKey}";
const customerKey = "l4rD8quK0dKI44VOA7TgC";
const tossPayments = TossPayments(clientKey);
const widgets = tossPayments.widgets({ customerKey });
// ------ 주문의 결제 금액 설정 ------
await widgets.setAmount({
currency: "JPY",
value: 1000,
});
await Promise.all([
// ------ 결제 UI 렌더링 ------
widgets.renderPaymentMethods({
selector: "#payment-method",
variantKey: "GLOBAL_CARD_JPY",
}),
// ------ 이용약관 UI 렌더링 ------
widgets.renderAgreement({ selector: "#agreement", variantKey: "AGREEMENT_EN" }),
]);
// ------ '결제하기' 버튼 누르면 결제창 띄우기 ------
document.querySelector('#payment-button').addEventListener('click', () => {
await widgets.requestPayment({
orderId: "LU1khs53rntkCdRgBn0s5",
orderName: "토스 티셔츠 외 2건",
successUrl: window.location.origin + "/success",
failUrl: window.location.origin + "/fail",
useInternationalCardOnly: true // 값이 true면 해외카드 결제가 가능한 다국어 결제창이 열립니다.
});
});
}
</script>
</body>
HTML
복사
5. FAQ
국내 카드사에서 발급한 해외결제 가능한 카드로도 결제가 가능한가요? 카드에 브랜드사(VISA, MASTER 등) 로고도 있어요.
아니요, 해외에서 발급한 카드로만 결제 가능합니다. 해외에서 발급한 카드가 없어요. 어떻게 테스트할 수 있을까요?
라이브 테스트를 위해서는 해외에서 발급한 카드가 필요합니다. 단 토스페이먼츠 테스트 환경(test api key)에서는 아래과 같이 테스트 할 수 있습니다. _skipAuth string
FORCE_SUCCESS 값을 보내면 인증을 건너뛰고 바로 successUrl로 이동합니다. 해당 데이터로 승인 요청을 하면 다통화결제 응답값을 받을 수 있습니다.
tossPayments
.requestPayment("카드", {
orderId: 'rpXzzMZBz3zRM2Z6yo3Hc',
orderName: "토스 티셔츠 외 2건",
successUrl: window.location.origin + "/success",
failUrl: window.location.origin + "/fail",
amount: 10.01,
currency:"USD",
useInternationalCardOnly:"true",
_skipAuth : 'FORCE_SUCCESS' // test Key에서만 동작합니다.
})
JavaScript
복사
** _skipAuth 는 현재 v2 sdk에서 미지원되며, 2월 중 지원될 예정입니다.
해외카드X다통화결제 승인응답은 국내카드와 다른가요?
동일하게 Payment 객체가 응답되요. 결제한 통화에 맞춰 currency 값이 내려갑니다. {
"mId": "globalcard",
"lastTransactionKey": "5FBF479FAF9E54FE9970CFFD19A6BE92",
"paymentKey": "tglob20250117161159Cbzv5",
"orderId": "rpXzzMZBz3zR123M2Z6yo3Hc",
"orderName": "테스트 결제",
"taxExemptionAmount": 0,
"status": "DONE",
"requestedAt": "2025-01-17T16:11:59+09:00",
"approvedAt": "2025-01-17T16:12:39+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"issuerCode": "34",
"acquirerCode": "31",
"number": "123412******123*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": "BUYER",
"approveNo": "sa_000000000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"amount": 100
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"cashReceipts": null,
"discount": null,
"cancels": null,
"secret": "ps_ALnQvDd2VJGgPlRKNnJYrMj7X41m",
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"isPartialCancelable": false,
"receipt": {
"url": "https://dashboard.tosspayments.com/receipt/redirection?transactionId=tglob20250117161159Cbzv5&ref=PX"
},
"checkout": {
"url": "https://api.tosspayments.com/v1/payments/tglob20250117161159Cbzv5/checkout"
},
"currency": "JPY",
"totalAmount": 100,
"balanceAmount": 100,
"suppliedAmount": 91,
"vat": 9,
"taxFreeAmount": 0,
"method": "카드",
"version": "2022-11-16",
"metadata": null
}
JSON
복사
승인 요청시 isPartialCancelable : false 로 응답되었는데요. 이럴 경우 부분취소 불가능한 카드인가요?
아니요. 해외 발급 카드는 각 카드사에서 부분취소 가능 여부를 알려주지 않아요. 그래서 isPartialCancelable 응답이 정확하지 않습니다. 직접 취소해보기 전까지는 부분취소 가능여부를 알 수 없어요.