⌨️결제 예약 API

원하는 시점에 결제를 예약하고 결제 결과를 Webhook으로 받을 수 있는 API입니다.

Deprecated

이 문서는 더 이상 관리되지 않습니다.

customer_uid 를 이용하여 비 인증 결제 요청을 예약할수 있는 API 입니다.

결제 요청에 대한 결과는 notice_url 에 설정한 EndPoint URL 로 웹훅을 통해 결제 결과를 수신(POST request)받을 수 있습니다.

결제 예약(Schedule) API

POST https://api.iamport.kr/subscribe/payments/schedule

customer_uid와 연결된 빌링키로 결제가 예약됩니다. 기존에 발급한 customer_uid 를 이용하지 않고 새로운 값을 지정하는 경우 카드정보를 반드시 기재하여야 하며 요청이 성공적으로 처리되면 빌링키 발급과 결제예약이 동시에 이루어 집니다.

Request Body

Name	Type	Description
customer_uid*	String	빌링키
checking_amount	Integer	유효카드 체크 승인금액
card_number	String	카드번호( dddd-dddd-dddd-dddd )
expiry	String	카드 유효기간( YYYY-MM )
birth	String	생년월일 6자리(YYMMDD) (법인카드의 경우 사업자등록번호10자리)
pwd_2digit	String	카드비밀번호 앞 2자리
cvc	String	카드 인증번호
pg	String	pg 구분코드
schedules*	array	결제예약 스케쥴

Name

Type

Description

customer_uid*

String

빌링키

checking_amount

Integer

유효카드 체크 승인금액

card_number

String

카드번호(

dddd-dddd-dddd-dddd

)

expiry

String

카드 유효기간(

YYYY-MM

)

birth

String

생년월일 6자리(YYMMDD)

(법인카드의 경우 사업자등록번호10자리)

pwd_2digit

String

카드비밀번호 앞 2자리

cvc

String

카드 인증번호

String

pg 구분코드

schedules*

array

결제예약 스케쥴

code integer

응답코드

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

message string

응답메세지

code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

response (Array[ScheduleResultAnnotation], optional)

code integer

응답코드

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

message string

응답메세지

code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

customer_uid string

빌링키

merchant_uid string

주문번호

imp_uid * string

포트원 결제 고유 UID

schedule_at UNIX timestamp

예약결제 실행 예정 시각

executed_at UNIX timestamp

예약결제가 실행된 시각

revoked_at UNIX timestamp

예약결제 실행을 철회한 시각

amount integer

주문(결제)금액

name string

제품명

buyer_name string

주문자명

buyer_email string

주문자 Email주소\

buyer_tel string

주문자 전화번호

buyer_addr string

주문자 주소

buyer_postcode string

주문자 우편번호

custom_data string

echo data JSON string으로 전달

schedule_status string

예약상태

scheduled: 예약됨(실행되기 전)
executed: 예약된 결제실행완료
revoked: 예약철회

payment_status string

실행된 결제의 승인 상태

null: 아직 예약결제가 실행되지 않음(null 이라는 값의 문자열이 아닌 실제 null 입니다)
paid: 예약결제가 결제승인됨
failed: 예약결제가 승인실패됨
cancelled: 예약결제가 결제승인 후 환불됨

fail_reason string

실패사유

{
    // Response
}

주요 요청 파라미터 상세 설명

schedules array
결제예약 스케쥴
[ 필수항목 ]
merchant_uid : 가맹점 주문번호(동일한 주문번호로 중복결제 불가)
schedule_at : 결제요청 예약시각 UNIX timestamp
currency : 외환부호 e.g.) KRW, USD, ...
amount : 결제금액
[ 선택항목 ]
tax_free : amount 중 면세공급가액(기본값 : 0)
vat_amount: amount 중 부가세(기본값: null). 나이스페이먼츠에서만 사용 가능
name : 주문명(누락되면 포트원 자체 기본값 사용)
buyer_name : 주문자명
buyer_email : 주문자Email
buyer_tel : 주문자 전화번호
buyer_addr : 주문자 주소
buyer_postcode : 주문자 우편번호
custom_data : 결제수행 시 사용될 custom_data 값
notice_url : 예약결제수행 후 통지될 Notification URL
(지정되지 않으면 관리자페이지의 Notification URL로 발송)
extra.naverUseCfm : 이용완료일 YYYYMMDD
(네이버페이 반복결제 계약 시 이용완료일 필수로 설정된 가맹점에 한함)

Sample

[
    {
        "merchant_uid": "your_merchant_uid1",
	"schedule_at": 1478150985,
	"currency": "KRW",
	"amount": 1004,
	"name": "주문명",
	"buyer_name": "주문자명",
	"buyer_email": "주문자 Email주소",
	"buyer_tel": "주문자 전화번호",
	"buyer_addr": "주문자 주소",
	"buyer_postcode": "주문자 우편번호"
    },
    {
        "merchant_uid": "your_merchant_uid2",
        "schedule_at": 1478150985,
	"amount": 1004,
	"name": "주문명",
	"buyer_name": "주문자명",
	"buyer_email": "주문자 Email주소",
	"buyer_tel": "주문자 전화번호",
	"buyer_addr": "주문자 주소",
	"buyer_postcode": "주문자 우편번호"
    }
]

pg string
pg 구분코드
관리자콘솔 API 방식 비인증 PG설정이 2개 이상인 경우 필수적으로 기재해야 하는 항목입니다.
동일 PG사에 두개의 MID 를 설정한 경우 아래 양식으로 기재 합니다. > {PG사}.{PG상점아이디}
나이스페이먼츠, JTNet 2가지 PG설정이 되어있다면, pg 파라미터로 nice 또는 jtnet로 구분 가능
나이스페이먼츠로부터 2개 이상의 상점아이디를 발급받았다면, nice.MID1 또는 nice.MID2로 구분 가능

schedules의 상세정보

buyer_name, buyer_email, buyer_tel, buyer_addr, buyer_postcode 누락시

customer_uid 에 해당되는 customer_name, customer_email, customer_tel, customer_addr, customer_postcode 정보로 대체됩니다.

Request Sample Json

{
  "customer_uid": "TEST0001",
  "schedules": [
    {
      "merchant_uid": "order_id001",
      "schedule_at": 1658480415,
      "amount": 1004,
      "name": "carrot",
    }
  ]
}

Response Model Schema

{
  "code": 0,
  "message": "string",
  "response": [
    {
      "customer_uid": "string",
      "merchant_uid": "string",
      "imp_uid": "string",
      "schedule_at": "0",
      "executed_at": "0",
      "revoked_at": "0",
      "amount": 0,
      "name": "string",
      "buyer_name": "string",
      "buyer_email": "string",
      "buyer_tel": "string",
      "buyer_addr": "string",
      "buyer_postcode": "string",
      "custom_data": "string",
      "schedule_status": "scheduled",
      "payment_status": "paid",
      "fail_reason": "string"
    }
  ]
}

Swagger Test Link

https://api.iamport.kr/#!/subscribe/schedule

Previous정기결제 관련 API Next결제 예약취소 API

Last updated 1 year ago