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

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"
    }
  ]
}

Swagger Test Link

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