해외 간편결제 연동

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

해외 간편결제는 아직 테스트 중인 기능입니다. 정식 오픈 후 사용해주세요.

더 궁금한 점이 있다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

1. 먼저, SDK를 준비하세요

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

<head>
  <title>결제하기</title>
  <meta charset="utf-8" />
  <script src="https://js.tosspayments.com/v1/payment"></script>
</head>

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

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

2. 결제창을 호출하세요 🚀

객체가 초기화 되었다면 이제 SDK에 포함된 메서드를 실행할 수 있습니다. 결제창 호출에 사용되는 메서드는 requestPayment()입니다.

아래와 같이 tossPayments.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',
})
.catch(function (error) {
  if (error.code === 'USER_CANCEL') {
    // 결제 고객이 결제창을 닫았을 때 에러 처리
  } else if (error.code === 'INVALID_CARD_COMPANY') {
    // 유효하지 않은 카드 코드에 대한 에러 처리
  }
})

JavaScript

requestPayment() 메서드의 첫 번째 파라미터는 결제수단입니다. 결제수단으로 해외간편결제를 추가하세요.

두 번째 파라미터는 결제 정보입니다. 필수 파라미터인 결제 금액(amount), 주문 ID(orderId)과 같은 주문 정보와 결제 요청 결과에 따라 리다이렉트 될 URL(successUrl, failUrl)을 추가하세요. 해외 간편결제라면 해외 간편결제사 코드(provider), 통화 단위 (currency), 결제 국가 정보(country)도 필수 파라미터입니다.

requestPayment() 메서드 실행에 실패해서 reject 된 에러는 Promise의 catch 블록에서 처리할 수 있습니다. 결제 고객이 창을 닫았거나 에러가 났을 때 처리하고 싶은 로직이 있다면 catch 블록에서 처리하세요. 메서드 실행에 실패했을 때 발생할 수 있는 에러는 에러 코드 페이지에서 살펴보세요.

결제 정보 파라미터

amount 필수 · number
결제되는 금액입니다.
orderId 필수 · string
주문 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 영문 대소문자, 숫자, 특수문자 -, _, =로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.
orderName 필수 · string
주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
successUrl 필수 · string
결제가 성공하면 리다이렉트되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터로 함께 전달됩니다. 반드시 오리진을 포함해야 합니다. 예를 들면 https://www.example.com/success 같은 형태입니다.
failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진을 포함해야 합니다.
provider 필수 · string
간편결제사 코드입니다. 아래 표에서 사용할 수 있는 해외 간편결제사 코드를 참고하세요.
currency 필수 · string
결제할 때 사용할 통화 단위입니다. 값을 넣지 않으면 기본값인 KRW로 설정됩니다. 아래 표에서 간편결제사 별로 사용할 수 있는 통화 단위 코드를 참고하세요.
country 필수 · string
결제한 국가 정보입니다. ISO-3166의 두 자리 국가 코드를 지원합니다. 아래 표에서 간편결제사 별로 사용할 수 있는 국가 코드를 참고하세요.
customerName string
고객의 이름입니다. 최대 길이는 100자입니다.
customerEmail string
고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다. 최대 길이는 100자입니다.
taxFreeAmount number
면세 금액입니다.

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

3. 결제 승인을 요청하세요

리다이렉트 URL 확인하기

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

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

https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}

paymentKey: 결제의 키 값입니다.
orderId: 주문 ID입니다. 결제창을 열 때 requestPayment()에 담아 보낸 값입니다.
amount: 실제로 결제된 금액입니다.

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

결제 요청에 실패했다면 결제 실패 URL 리다이렉트를 살펴보세요.

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

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

값이 같다면 이제 결제 승인 API를 호출할 준비가 되었습니다.

결제 승인 API 호출하기

결제 승인 API를 호출합니다. 리다이렉트 URL로 받은 paymentKey, orderId, amount를 요청 본문으로 함께 보냅니다.

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/confirm \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"paymentKey":"tDNORxplOMDCFLhaRA1Tn","amount":1.23,"orderId":"dQvRoluAQXSYR-ZYhU15o"}'

successUrl로 리다이렉트 된 후 10분 이내에 결제 승인 API를 호출해야 합니다.

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

승인 응답을 확인해보세요. API 호출 결과로 HTTP 상태 코드 200이 돌아오면 결제 성공입니다.

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

응답

{
  "mId": "tosspayments",
  "version": "2022-11-16",
  "lastTransactionKey": "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,
  "cashReceipts": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "NORMAL",
  "easyPay": "페이마야",
  "country": "PH",
  "failure": null,
  "currency": "PHP",
  "totalAmount": 1.25,
  "balanceAmount": 1.25,
  "suppliedAmount": 1.14,
  "vat": 0.11,
  "taxFreeAmount": 0,
  "taxExemptionAmount": 0.0
}

JSON

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

foreignEasyPay 해외 간편결제를 이용하면 제공되는 결제 정보입니다.
- provider 간편결제사 코드 정보입니다. 라인페이, 페이마야 같은 형태입니다.

해외 간편결제 부분 취소하기

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

요청

curl --request POST \
  --url https://api.tosspayments.com/v1/payments/{paymentKey}/cancel \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"cancelReason":"고객이 부분 취소를 원함","cancelAmount":0.23,"currency":"PHP"}'

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

응답

// Payment 객체

{
  // ...
  "cancels": [
    {
      "cancelAmount": 0.23,
      "cancelReason": "Change purchase item",
      "taxFreeAmount": 0,
      "taxExemptionAmount": 0,
      "refundableAmount": 1,
      "easyPayDiscountAmount": 0,
      "easyPayDiscountAmount": 0,
      "canceledAt": "2023-01-01T15:19:37+09:00",
      "transactionKey": "D8NZZE5SEQFGH89JNJ1FUY09M2NDM70J",
      "receiptKey": "RwFiDefvNi6v2kvC4gSaqN0HeiHllaTJxKCDmIhGU0XKT1Hd",
    }
  ]
  // ...
}