해외 간편결제 연동

해외 간편결제는 해외에서 사용하는 모바일 및 온라인 간편결제 서비스를 제공하는 결제수단입니다. 결제창을 호출하면 특정 해외 간편결제사의 결제창이 바로 열려 고객이 편리하게 결제할 수 있습니다.

해외 간편결제는 응답 버전 1.4 부터 지원하는 결제수단입니다. 개발 정보 페이지의 응답 버전이 1.4로 설정되어야 해외 간편결제를 사용할 수 있습니다.

1 먼저, SDK를 준비하세요

스크립트를 삽입해서 SDK를 추가합니다.

<head>
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1"></script>
</head>

클라이언트 키를 사용해 객체를 초기화합니다.

var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
var tossPayments = TossPayments(clientKey)

2 결제창을 호출하세요 🚀

결제창 호출에 사용되는 메서드는 requestPayment입니다. 메서드를 실행하면 결제창이 열립니다.

requestPaymenttossPayments.requestPayment(결제수단, 결제정보)와 같은 방식으로 사용합니다.

호출 준비하기

첫번째 파라미터는 결제수단입니다. 결제수단으로 토스결제를 추가하세요.

tossPayments.requestPayment('해외간편결제', {
amount: 1.23,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
provider: '페이마야',
currency: 'PHP',
country: 'PH'
})
JavaScript

두번째 파라미터는 결제정보입니다. 주문정보, 결제정보, 그리고 결제요청 결과에 따라 리다이렉트(Redirect) 될 URL을 추가해보세요.

tossPayments.requestPayment('해외간편결제', {
amount: 1.23,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
provider: '페이마야',
currency: 'PHP',
country: 'PH',
})
JavaScript

결제금액(amount), 주문 ID(orderId) 같은 주문정보와 결제요청 결과에 따라 리다이렉트 될 URL(successUrlfailUrl)은 필수 파라미터입니다.

해외 간편결제사 코드(provider), 통화 단위 (currency), 결제 국가 정보(country)는 필수 파라미터입니다.

결제정보 파라미터

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    가맹점에서 사용하는 해당 주문에 대한 ID입니다. 각 주문마다 유니크해야 합니다.

  • orderName 필수 · string

    결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다.

  • successUrl 필수 · string

    결제가 성공하고 나면 리다이렉트(Redirect)되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터(Query Parameter)로 함께 전달됩니다. 반드시 오리진(origin)을 포함해야 합니다. 예를 들면 https://www.example.com/success 같은 형태입니다.

  • failUrl 필수 · string

    결제가 실패하면 리다이렉트되는 URL입니다. 에러코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진(origin)을 포함해야 합니다.

  • provider 필수 · string

    간편결제사 코드입니다. 사용할 수 있는 해외 간편결제사 코드를 참고하세요.

  • currency 필수 · string

    결제할 때 사용할 통화 단위입니다. 값이 없으면 기본 값은 KRW입니다. 사용할 수 있는 통화 단위 코드를 참고하세요.

  • country 필수 · string

    결제한 국가 정보입니다. 사용할 수 있는 국가 코드를 참고하세요.

결제정보 파라미터는 결제수단에 따라 조금씩 달라집니다. 각 결제 연동 가이드에서 결제수단별 파라미터 구성을 확인해보세요.

리다이렉트 URL 확인하기

결제요청이 성공하거나 실패하면 위에서 설정한 successUrl, failUrl 로 이동합니다. URL에 포함된 쿼리 파라미터로 결제승인을 요청할 수 있습니다.

성공 리다이렉트 URL에는 paymentKey, orderId, amount 세가지 쿼리 파라미터가 들어있습니다.

https://{origin}/success?paymentKey={paymentKey}&orderId={orderId}&amount={amount}
  • paymentKey: 결제 건에 대한 고유한 키 값입니다.
  • orderId: 가맹점에서 발급된 고유한 주문 ID값 입니다. 결제창을 열 때 requestPayment에 담아 보낸 값입니다.
  • amount: 실제로 결제된 금액입니다.

돌아온 파라미터를 이용해 결제승인 요청 API를 호출할 수 있습니다.

결제금액이 같은지 검증하기

결제창을 열 때 requestPayment 메서드에 담아 보냈던 amount 값과 리다이렉트 URL에 있는 실제 결제금액인 amount 값이 같은지 확인해보세요.

값이 같다면 결제가 제대로 처리된 것입니다.

3 결제를 성공적으로 완료하셨네요! 🎉

API 호출 결과로 HTTP 상태 코드 200이 돌아오면 결제 성공입니다.

상태 코드와 함께 아래와 같은 응답 본문이 돌아옵니다. 해외 간편결제 승인 응답에는 foreignEasyPay 필드가 포함되어 있어야 합니다.

응답
{
"mId": "tosspayments",
"version": "1.4",
"transactionKey": "01BDC3BE5C7EFB174EF4E551833E591C",
"paymentKey": "avNA96Bjgq7XZYkKL4MrjKZbZG7jE80zJwlEWR52xydGPnOQ",
"orderId": "",
"orderName": "토스 해외결제 외 1건",
"method": "해외간편결제",
"status": "ABORTED",
"requestedAt": "2021-11-15T15:19:37+09:00",
"approvedAt": null,
"useEscrow": null,
"cultureExpense": false,
"card": null,
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"foreignEasyPay": {
"provider": "페이마야"
},
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": "페이마야",
"country": "PH",
"failure": {
"code": "COMMON_ERROR",
"message": "Failed - external billing failure"
},
"currency": "PHP",
"totalAmount": 1.25,
"balanceAmount": 1.25,
"suppliedAmount": 1.14,
"vat": 0.11,
"taxFreeAmount": 0.0
}
JSON

해외 간편결제 응답에 추가되는 파라미터 정보

  • foreignEasyPay 해외 간편결제를 이용한 경우 제공되는 결제 정보입니다.
    • provider 간편결제사 코드 정보입니다. 라인페이, 페이마야 같은 형태입니다.
  • country 결제한 국가 정보입니다.
  • failure 결제 실패 정보입니다.
    • code: 오류 타입을 보여주는 에러코드입니다.
    • message: 에러 메시지입니다. 에러 발생 이유를 알려줍니다.

해외 간편결제 취소하기

해외 간편결제로 이루어진 결제를 취소할 때는 Request Body 파라미터에 currency 값을 필수로 추가해야 합니다.

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/payments/{paymentKey}/cancel"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"cancelReason\":\"고객이 취소를 원함\",\"cancelAmount\":1.23,\"currency\":\"PHP\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

응답은 결제취소 API와 동일하게 Payment 객체의 cancels 필드에 취소한 기록이 쌓입니다.

응답
// Payment 객체
{
// ...
"cancels": [
{
"cancelAmount": 1.23,
"cancelReason": "Change purchase item",
"taxFreeAmount": 0,
"taxAmount": null,
"refundableAmount": 1.23,
"canceledAt": "2021-11-16T15:19:37+09:00"
}
]
// ...
}
JSON

해외 간편결제사 관련 코드

간편결제사 한글 코드간편결제사 영문 코드사용할 수 있는 국가 코드사용할 수 있는 통화 코드
알리페이ALIPAYCN, HKCNY,HKD
위챗페이WECHATPAYCN, HKCNY, HKD
라인페이LINEPAYJP, THJPY, THB
페이페이PAYPAYJPJPY
머르페이MERPAYJPJPY
고페이GOPAYIDIDR
오보OVOIDIDR
다나DANAIDIDR
쇼피페이SHOPEEPAYID, MY,PH,SGIDR, MYR, PHP, SGD
그랩페이GRABPAYMY, PH, SGMYR, PHP, SGD
모모MOMOVNVND
잘로페이ZALOPAYVNVND
지캐시GCASHPHPHP
터치앤고TOUCHNGOMYMYR
트루머니TRUEMONEYTHTHB
페이마야PAYMAYAPHPHP

사용할 수 있는 통화 단위 코드

  • KRW: 대한민국 원
  • USD: 미국 달러
  • JPY: 일본 엔
  • CNY: 중국 위안(런민비)
  • IDR: 인도네시아 루피아
  • MYR: 말레이시아 링깃
  • PHP: 필리핀 페소
  • SGD: 싱가포르 달러
  • THB: 태국 밧
  • HKD: 홍콩 달러
  • VND: 베트남 동
내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기