Developers
V1
V2

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.

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

Schedule API

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.

Parameters

Body

customer_uid*
String

Billing key

checking_amount
Integer

Test amount approved to check validity of the credit card (cancelled immediately)

card_number
String

Credit card number (

dddd-dddd-dddd-dddd

)

expiry
String

Credit card expiration (

YYYY-MM

)

birth
String

6-digit DOB (YYMMDD)

(10-digit business registration number for corporate card)

pwd_2digit
String

First 2 digits of credit card password

cvc
String

Credit card CVC

pg
String

PG code

schedules*
array

Payment schedule

Responses

200: OK
Success

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)

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 (UNIX timestamp in seconds)

executed_at * UNIX timestamp

Payment started at (UNIX timestamp in seconds)

revoked_at * UNIX timestamp

Payment cancelled at (UNIX timestamp in seconds)

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

401: Unauthorized
Missing or invalid access token
{
  // Response
}

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 in seconds)
  • 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.
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"
    }
  ]
}