⌨️Schedule payment API

Schedules a non-authenticated payment using customer_uid.

The result of the payment request can be received (POST request) through the endpoint URL set in notice_url via webhook.

Schedule API

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

A payment is scheduled with the billing key associated with customer_uid. If you specify a new customer_uid instead of using the existing customer_uid, you must also enter the credit card information. In this case, both a new billing key is issued and payment is scheduled.

Request Body

Name	Type	Description
customer_uid*	String	Billing key
pg	String	PG code
cvc	String	Credit card CVC
pwd_2digit	String	First 2 digits of credit card password
birth	String	6-digit DOB (YYMMDD) (10-digit business registration number for corporate card)
expiry	String	Credit card expiration (YYYY-MM)
card_number	String	Credit card number (dddd-dddd-dddd-dddd)
checking_amount	Integer	Test amount approved to check validity of the credit card (cancelled immediately)
schedules*	array	Payment schedule

401: Unauthorized Missing or invalid access token

{
    // Response
}

200: OK Success

ScheduleResponse

code * integer

Response code

0: success, Not 0: check the message

message * string

Response message

A non-zero code includes a message like 'Invalid payment info'.

response (Array[ScheduleResultAnnotation], optional)

ScheduleResultAnnotation

code * integer

Response code

0: success, Not 0: check the message

message * string

Response message

A non-zero code includes a message like 'Invalid payment info'.

customer_uid * string

Billing key

merchant_uid * string

Order ID

imp_uid * string

i'mport transaction UID

schedule_at * UNIX timestamp

Payment scheduled at

executed_at * UNIX timestamp

Payment started at

revoked_at * UNIX timestamp

Payment cancelled at

amount * integer

Payment amount

name string

Product name

buyer_name string

Customer name

buyer_email string

Customer email

buyer_tel string

Customer phone number

buyer_addr string

Customer address

buyer_postcode string

Customer zip code

custom_data string

Echo data as JSON string

schedule_status * string

Status of scheduled payment

• scheduled (payment is scheduled for execution)

• executed (payment is completed)

• revoked (payment is cancelled)

payment_status * string

Payment approval state

• null: Scheduled payment has not executed yet (actual null value, not string)

• paid: Scheduled payment is approved

• failed: Scheduled payment approval failed

• cancelled: Scheduled payment is refunded (cancelled) after approval

fail_reason string

Reason for failure

Key request parameter description

schedules * array

Payment schedule

[ Required ]

• merchant_uid : Merchant order ID (Must be unique for each request)

• schedule_at : Scheduled time (UNIX timestamp)

• currency : Currency code (Example: KRW, USD, ... )

• amount : Amount

[ Optional ]

• tax_free : Tax free amount out of amount (Default: 0)

• name : Order name (If omitted, sets to i'mport default setting)

• buyer_name : Customer name

• buyer_email : Customer email

• buyer_tel : Customer phone number

• buyer_addr : Customer address

• buyer_postcode : Customer zip code

• custom_data : Custom data

• notice_url : Notification URL to receive payment result

(If omitted, sets to Notification URL setting in Admin console)

• extra.naverUseCfm : Expiration date (string in yyyyMMdd format).

  • Specify if contract between Naver Pay and merchant requires this value for recurring payment.

Schedules Model Schema

Sample

[
    {
        "merchant_uid": "your_merchant_uid1",
	"schedule_at": 1478150985,
	"currency": "KRW",
	"amount": 1004,
	"name": "order name",
	"buyer_name": "customer name",
	"buyer_email": "customer email",
	"buyer_tel": "customer phone number",
	"buyer_addr": "customer address",
	"buyer_postcode": "customer zip code"
},
    {
        "merchant_uid": "your_merchant_uid2",
        "schedule_at": 1478150985,
	"amount": 1004,
	"name": "order name",
	"buyer_name": "customer name",
	"buyer_email": "customer email",
	"buyer_tel": "customer phone number",
	"buyer_addr": "customer address",
	"buyer_postcode": "customer zip code"
    }
]

pg * string

pg code

This is required when there are multiple API method, non-authenticated PG settings in the Admin console.

If there are multiple MID settings for the same PG, specify as:

{PG}.{PG Merchant ID}

If this is unspecified or set to an invalid value, the default PG is used.

• If there are 2 PG settings, NICE Payments and JTNet, specify as nice or jtnet.

• If you have multiple MIDs from NICE Payments, specify as nice.MID1 or nice.MID2.

schedules details

If buyer_name, buyer_email, buyer_tel, buyer_addr, or buyer_postcode is omitted, it is set to the corresponding value of 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