# 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

<mark style="color:green;">`POST`</mark> `https://api.iamport.kr/subscribe/payments/schedule`

A payment is scheduled with the billing key associated with customer\_ui&#x64;*.* If you specify a new custome&#x72;*\_*&#x75;id 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<mark style="color:red;">\*</mark> | String  | <mark style="color:red;">**Billing key**</mark>                                                               |
| pg                                              | String  | PG code                                                                                                       |
| cvc                                             | String  | Credit card CVC                                                                                               |
| pwd\_2digit                                     | String  | First 2 digits of credit card password                                                                        |
| birth                                           | String  | <p>6-digit DOB (<strong>YYMMDD</strong>)</p><p>(10-digit business registration number for corporate card)</p> |
| 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<mark style="color:red;">\*</mark>     | array   | <mark style="color:red;">**Payment schedule**</mark>                                                          |

{% tabs %}
{% tab title="401: Unauthorized Missing or invalid access token" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="200: OK Success" %}
{% tabs %}
{% tab title="ScheduleResponse" %}
**`code`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:purple;">**integer**</mark>

**Response code**

0: success, Not 0: check the message

**`message`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string**</mark>

**Response message**

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

**`response`** <mark style="color:red;">**(Array\[ScheduleResultAnnotation], optional)**</mark>
{% endtab %}
{% endtabs %}

{% tabs %}
{% tab title="ScheduleResultAnnotation" %}
**`code`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**integer**</mark>

**Response code**

0: success, Not 0: check the message

**`message`** <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:green;">**string**</mark>

**Response message**

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

**`customer_uid`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>

**Billing key**

**`merchant_uid`  \* &#x20;**<mark style="color:green;">**string**</mark>

**Order ID**

**`imp_uid`** <mark style="color:red;">\*</mark> <mark style="color:green;">**string**</mark>

**i'mport transaction UID**

**`schedule_at`**  <mark style="color:red;">**\***</mark>  <mark style="color:blue;">**UNIX timestamp**</mark>&#x20;

**Payment scheduled at**

**`executed_at`** <mark style="color:red;">**\***</mark>  <mark style="color:blue;">**UNIX timestamp**</mark>

**Payment started at**

**`revoked_at`** <mark style="color:red;">**\***</mark>  <mark style="color:blue;">**UNIX timestamp**</mark>

**Payment cancelled at**&#x20;

**`amount`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**integer**</mark>

**Payment amount**

**`name`**  <mark style="color:green;">**string**</mark>

**Product name**

**`buyer_name`**  <mark style="color:green;">**string**</mark>

**Customer name**

**`buyer_email`**  <mark style="color:green;">**string**</mark>

**Customer email**<br>

**`buyer_tel`**  <mark style="color:green;">**string**</mark>

**Customer phone number**

**`buyer_addr`**  <mark style="color:green;">**string**</mark>

**Customer address**

**`buyer_postcode`**  <mark style="color:green;">**string**</mark>

**Customer zip code**

**`custom_data`**  <mark style="color:green;">**string**</mark>

**Echo data as JSON string**

**`schedule_status`**  <mark style="color:red;">**\***</mark>**&#x20;** <mark style="color:green;">**string**</mark>

**Status of scheduled payment**&#x20;

* `scheduled` (payment is scheduled for execution)
* `executed` (payment is completed)
* `revoked` (payment is cancelled)

**`payment_status`** <mark style="color:red;">**\***</mark>**&#x20;** <mark style="color:green;">**string**</mark>

**Payment approval state**&#x20;

* `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`**  <mark style="color:green;">**string**</mark>

**Reason for failure**&#x20;
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

### **Key request parameter description**

> **`schedules`**  <mark style="color:red;">**\***</mark>**&#x20;**<mark style="color:blue;">**array**</mark>
>
> **Payment schedule**
>
> <mark style="color:red;">**\[ Required ]**</mark>
>
> * `merchant_uid` : Merchant order ID (Must be unique for each request)&#x20;
> * `schedule_at` : Scheduled time (UNIX timestamp)
> * `currency` : Currency code (Example: KRW, USD, ... )
> * `amount` : Amount
>
> <mark style="color:green;">**\[ Optional ]**</mark>
>
> * `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&#x20;
>
> &#x20;                               (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.

{% tabs %}
{% tab title="Schedules Model Schema" %}
{% code title="Sample" %}

```json
[
    {
        "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"
    }
]
```

{% endcode %}
{% endtab %}
{% endtabs %}

> **`pg`**  <mark style="color:red;">**\***</mark>  <mark style="color:green;">**string**</mark>
>
> **pg code**
>
> This is required when there are multiple API method, non-authenticated PG settings in the Admin console.&#x20;
>
> If there are <mark style="color:red;">**multiple MID**</mark> settings for the same PG, specify as:
>
> **{PG}.{PG Merchant ID}**&#x20;
>
> If this is unspecified or set to an invalid value, the default PG is used.&#x20;
>
> * 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**.

{% hint style="info" %}
`schedules` details

**If buyer\_name, buyer\_email, buyer\_tel, buyer\_addr, or buyer\_postcode** is omitted, it is set to the corresponding value of <mark style="color:red;">**customer\_uid**</mark> (**customer\_name, customer\_email, customer\_tel, customer\_addr, customer\_postcode)**.
{% endhint %}

<details>

<summary>Request Sample Json</summary>

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

</details>

<details>

<summary>Response Model Schema</summary>

```json
{
  "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"
    }
  ]
}
```

</details>

{% hint style="success" %}
**Swagger Test Link**

[**https://api.iamport.kr/#!/subscribe/schedule**](https://api.iamport.kr/#!/subscribe/schedule)
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://portone.gitbook.io/docs-en/api/subscription-payment-api/schedule-payment-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.