# 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 %}