2. 토스페이 생성을 요청합니다

고객은 'A상점'을 둘러보다가 35,000원짜리 'B티셔츠'를 선택하여 결제를 요청합니다. 이 때, A몰은 토스 결제 서버에게 '결제 생성'을 요청해야합니다. 아래와 같이 결제 생성 API를 호출하세요.

curl https://pay.toss.im/api/v2/payments \
-H "Content-Type: application/json" \
-d '{
  "orderNo":"1",
  "amount":35000,
  "amountTaxFree":0,
  "productDesc":"B티셔츠",
  "apiKey":"sk_test_w5lNQylNqa5lNQe013Nq",
  "autoExecute":true,
  "resultCallback":"https://pay.toss.im/payfront/demo/callback",
  "retUrl":"https://pay.toss.im/payfront/demo/completed",
  "retCancelUrl":"https://pay.toss.im/payfront/demo/cancel"
}'

위 예제에서 알 수 있듯이 '결제 생성'을 위해서는 9가지 설정값을 담아 토스에 요청해야합니다.

1. orderNo (상점 주문번호) : 추후 상점 주문 정보와 결제 정보를 매칭하기 위해 필요합니다.
2. amount (결제 금액) : 손님으로부터 받을 총 결제금액
3. amountTaxFree (비과세 금액) : 손님으로부터 받을 금액중 비과세 금액
4. productDesc (상품명) : 결제할 상품에 대한 정보
5. apiKey (상점 API Key) : 이곳에 '테스트용 API Key'를 넣으면 테스트 결제가, '실거래용 API Key'를 넣으면 진짜 출금되는 결제가 생성됩니다.
6. autoExecute (자동 승인 설정) : true 를 사용하는 경우, 구매자 인증이 완료되면 토스가 알아서 승인을 진행합니다.
7. resultCallback (결제 결과 Callback URL) : 자동 승인 설정을 true로 설정할 경우에는 반드시 함께 보내주셔야 합니다. 토스 서버는 출금을 성공한 후 이 곳에 입력한 가맹점 서버로 callback을 HttpMethod POST 로 요청합니다. 최종적으로 토스 결제완료 여부를 확인할 수 있습니다.
8. retUrl (인증 완료 후 연결할 URL) : 구매자가 결제 인증을 완료하면 이 곳에 입력한 URL로 연결해드립니다. 이 URL은 단순히 가맹점의 결제 완료 페이지의 이동을 위해 사용됩니다.
9. retCancelUrl (결제 중단 시 사용자를 이동시킬 가맹점 페이지) : 토스페이창에 진입한 사용자가 결제를 중단할 때 사용자를 이동시킬 가맹점 취소 페이지 URL을 입력해주세요.

요청하신 결제 생성이 무사히 완료되면 토스는 아래와 같이 응답합니다.

{
  "code": 0,
  "checkoutPage": "https://pay.toss.im/payfront/auth?payToken=test_token1234567890",
  "payToken": "example-payToken"
}

code '0'은 결제 생성에 '성공'했음을 나타냅니다. 그 외에는 오류코드와 메시지가 전달됩니다.

checkoutPage는 결제를 진행할 수 있는 토스페이 웹페이지 URL입니다. 상점에서는 이 URL을 사용자에게 띄워주세요.

payToken은 거래를 구분할 수 있는 토스 고유 값입니다. 결제를 진행할 때, 결제를 환불할 때, 결제의 현재 상태를 파악할 때 이 고유번호를 통해 해당 결제 건에 접근하게 되니 잘 보관해주세요!