API & SDK

ARS결제 API

ARS결제 API로 콜센터·홈쇼핑 등 비대면 전화 채널에서 카드 결제를 진행할 수 있습니다. ARS결제는 별도 계약 후 사용할 수 있습니다.

목차
인증 및 기타 헤더 설정
요청·응답 본문

링크 복사예약

예약 API로 ARS결제 진행 단위를 생성하고 관리할 수 있습니다. Basic 인증 방식을 사용합니다.

링크 복사Reservation 객체

ARS결제 예약 정보를 담고 있는 객체입니다.

링크 복사객체 상세

  • arsReservationKey string

    토스페이먼츠에서 발급하는 예약의 고유 식별자입니다. 예약 조회·수정·취소에 사용합니다.

  • mId string

    상점아이디(MID)입니다.

  • reserveNumber string

    가맹점에서 발급하는 예약 번호입니다. 가맹점 시스템에서 식별용으로 사용할 수 있습니다. 8~12자리 숫자만 입력할 수 있고, 동일한 상점에서 같은 번호로 두 번 등록할 수 없습니다.

  • status string

    예약 상태입니다. 아래 중 하나입니다.

    - READY: 예약이 생성되어 ARS 호 진행을 대기 중인 상태입니다.

    - DONE: ARS 호가 정상 종료되고 결제가 성공한 상태입니다. 종료 상태입니다.

    - CANCELED: 가맹점이 예약 취소 API로 명시 취소한 상태입니다. 종료 상태입니다.

  • requestedAt string

    API 호출 시각입니다. 서버가 자동으로 채웁니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

  • reservedAt string

    예약의 이용 가능 시작 시각입니다. 클라이언트가 옵션으로 지정할 수 있고, 미지정 시 requestedAt과 동일합니다.

  • canceledAt nullable · string

    예약이 취소된 시각입니다. status가 CANCELED일 때만 채워집니다.

  • cancelReason nullable · string

    예약 취소 사유입니다. status가 CANCELED일 때만 채워집니다.

  • completedAt nullable · string

    예약이 완료된 시각입니다. status가 DONE일 때만 채워집니다.

링크 복사ARS 예약 생성

POST /v2/ars/reservations

ARS결제 예약을 생성합니다. 응답으로 받은 arsReservationKey로 이후 조회·수정·취소를 진행합니다.

링크 복사Request Body 파라미터

  • arsType 필수 · string

    ARS의 유형입니다. 현재는 PAYMENT(결제)만 지원합니다.

  • payment object

    결제 정보입니다. arsType이 PAYMENT일 때 필수입니다.

    • method 필수 · string

      결제수단입니다. 현재는 CARD만 지원합니다.

    • amount 필수 · object

      결제 금액 정보입니다.

      • currency 필수 · string

        통화입니다. 현재는 KRW만 지원합니다.

      • value 필수 · number

        결제 금액입니다.

    • orderName 필수 · string

      주문명입니다. 결제창과 영수증에 표시됩니다.

    • customerMobilePhone 필수 · string

      고객 휴대폰 번호입니다. - 없이 숫자만 입력해주세요.

  • reserveNumber 필수 · string

    가맹점에서 발급하는 예약 번호입니다. 8~12자리 숫자만 입력할 수 있고, 동일한 상점에서 같은 번호로 두 번 등록할 수 없습니다.

  • reservedAt string

    예약의 이용 가능 시작 시각입니다. 미지정 시 즉시 이용 가능합니다. 과거 시각은 사용할 수 없습니다. ISO 8601 형식입니다.

링크 복사Response

성공

예약 생성에 성공하면 entityBody에 Reservation 객체가 돌아옵니다.

실패

예약 생성에 실패하면 에러 객체가 돌아옵니다. 예약 번호가 이미 등록되어 있으면 ALREADY_EXIST_RESERVATION 에러가 돌아옵니다.

링크 복사ARS 예약 단건 조회

GET /v2/ars/reservations/{arsReservationKey}

예약 하나의 정보를 조회합니다.

링크 복사Path 파라미터

  • arsReservationKey 필수 · string

    조회할 예약의 고유 식별자입니다.

링크 복사Response

성공

예약 조회에 성공하면 entityBody에 Reservation 객체가 돌아옵니다.

실패

예약 조회에 실패하면 에러 객체가 돌아옵니다.

링크 복사ARS 예약 수정

POST /v2/ars/reservations/{arsReservationKey}

예약 정보를 수정합니다. 종료 상태(DONE, CANCELED)인 예약은 수정할 수 없습니다. 변경하고 싶은 필드만 본문에 담아 요청하세요.

링크 복사Path 파라미터

  • arsReservationKey 필수 · string

    수정할 예약의 고유 식별자입니다.

링크 복사Request Body 파라미터

  • payment object

    결제 정보입니다.

    • amount object

      결제 금액 정보입니다.

      • currency 필수 · string

        통화입니다. 현재는 KRW만 지원합니다.

      • value 필수 · number

        결제 금액입니다.

    • orderName string

      주문명입니다. 결제창과 영수증에 표시됩니다.

  • reservedAt string

    예약의 이용 가능 시작 시각입니다.

링크 복사Response

성공

예약 수정에 성공하면 entityBody에 Reservation 객체가 돌아옵니다.

실패

예약 수정에 실패하면 에러 객체가 돌아옵니다.

링크 복사ARS 예약 취소

POST /v2/ars/reservations/{arsReservationKey}/cancel

예약을 명시적으로 취소합니다. 종료 상태(DONE, CANCELED)인 예약은 취소할 수 없습니다.

링크 복사Path 파라미터

  • arsReservationKey 필수 · string

    취소할 예약의 고유 식별자입니다.

링크 복사Request Body 파라미터

  • cancelReason 필수 · string

    취소 사유입니다.

링크 복사Response

성공

예약 취소에 성공하면 entityBody에 status=CANCELED로 갱신된 Reservation 객체가 돌아옵니다.

실패

예약 취소에 실패하면 에러 객체가 돌아옵니다.

링크 복사ARS

ARS API로 예약에 연결된 ARS 호 세션과 결제 정보를 조회할 수 있습니다.

링크 복사ARS 객체

ARS 호 세션 정보를 담고 있는 객체입니다.

링크 복사객체 상세

  • arsKey string

    ARS 호 세션의 고유 식별자입니다.

  • arsType string

    ARS의 유형입니다. 현재는 PAYMENT(결제)만 지원합니다.

  • reservation object

    연결된 Reservation 객체입니다.

  • payment nullable · object

    결제 정보입니다. arsType이 PAYMENT이고 결제 승인이 완료되면 Payment 객체가 채워집니다.

링크 복사ARS 조회

GET /v2/ars

예약에 연결된 ARS 호 세션과 결제 정보를 함께 조회합니다. 결제 객체 상세 정보가 필요할 때 사용합니다.

링크 복사Query 파라미터

  • arsReservationKey 필수 · string

    조회할 예약의 고유 식별자입니다.

링크 복사Response

성공

조회에 성공하면 entityBody에 ARS 객체가 돌아옵니다. payment 필드에는 Payment 객체 전체가 포함됩니다.

실패

조회에 실패하면 에러 객체가 돌아옵니다.