결제 상태 알아보기

결제가 생성되고 진행됨에 따라 결제의 '상태'는 끊임없이 바뀝니다. 상점 운영을 위해선 특정 결제건이 현재 어떤 상태인지 파악할 일이 많을 것입니다. 결제가 잘 끝난 것인지, 취소된 것은 아닌지. 환불 요청에 들어왔던 주문은 잘 환불 되었는지...

그럴땐 '결제 상태 확인 API'를 찾아주세요. 상황에 따라 승인,환불 응답을 수신하지 못한 경우에도 활용할 수 있습니다. 아래 예제는 결제 상태 확인 API 호출 코드입니다.

예제 코드

curl "https://pay.toss.im/api/v2/status" \
-H "Content-Type: application/json" \
-d '{
"apiKey":"sk_test_w5lNQylNqa5lNQe013Nq",   # 상점의 API Key (필수)
"payToken":"example-payToken",             # 결제 고유 번호 (필수)
}'

결제 생성 API의 Endpoint

POSThttps://pay.toss.im/api/v2/status

필수 Parameters

필수 파라미터는 딱 2가지 입니다. '어느 가맹점'에서 일어난 '어떤 결제건'을 조회하고 싶은지 알려주세요.

1. 상점 API Key (apiKey) : 결제를 생성한 상점의 API Key가 필요합니다.
2. 결제 고유 토큰 (payToken) : 결제 생성 완료 후 받은 결제 고유번호

• '결제 고유 토큰 (payToken)' 대신 '상점의 주문번호 (orderNo)'값을 사용할 수도 있습니다.

결제 상태 확인 요청에 대한 응답

결제 상태 확인 요청에 대한 응답은 아래와 같은 형태로 받게됩니다. 응답의 일부이며, 상세한 내용은 결제상태 API를 확인해주세요.

{
  "code": 0,                            # 응답코드
  "payToken": "example-payToken",       # 결제 고유 토큰
  "orderNo": "1",                       # 상점의 주문번호
  "payStatus": "PAY_COMPLETE",          # 결제 상태
  "payMethod": "TOSS_MONEY",            # 결제 수단
  "amount": 15000,                      # 결제 요청금액
  "transactions": [                     # 거래 트랜잭션 목록
    {
      "stepType": "PAY",
      "transactionId": "3243c76e-4669-881b-33a3b82ddf49",
      "transactionAmount": 15000,
      "discountAmount": 300,
      "pointAmount": 0,
      "paidAmount": 14700,
      "regTs": "2020-03-01 12:33:20"
    }
  ],
  "createdTs": "2020-03-01 12:33:04",   # 최초 결제요청 시간
  "paidTs": "2020-03-01 12:33:20"       # 결제 완료 처리 시간
}

각 항목은 다음과 같은 의미를 가지고 있습니다.

• 응답코드 : 요청에 대한 결과. 성공하면 '0' 입니다.
• 결제 고유 토큰 : 결제 생성 완료 후 받은 결제토큰. '주문번호'로 상태를 조회하면 이 값을 참조하여 '결제 고유번호 값을 알 수 있습니다.
• 상점의 주문번호 : 상점에서 사용하는 주문번호. 'payToken'으로 상태를 조회하면 이 값을 참조하여 '주문번호'를 알 수 있습니다.
• 결제 수단 : 구매자가 선택한 결제수단을 확인할 수 있습니다.
• 결제 상태 : 조회 당시의 결제 상태 (아래 '결제 상태 목록'을 참고하세요)
• 거래 트랜잭션 목록 : 조회 당시에 처리된 트랜잭션 목록(취소,환불 등)
• 최초 결제요청 시간 : 구매자가 최초 결제요청한 시간을 확인할 수 있습니다.
• 결제완료 처리 시간 : 요청에 대한 처리를 완료한 시간을 확인할 수 있습니다.

결제 상태 목록

결제 상태는 아래 중 하나입니다. 각 상태에 대한 자세한 설명은 API 명세서 > 결제 상태 문서를 참고하세요.