# 빌링키 발급 API

{% hint style="warning" %}
**Deprecated**

이 문서는 더 이상 관리되지 않습니다.

[PortOne 개발자센터](https://developers.portone.io/)를 이용해주세요.
{% endhint %}

### 카드정보를 이용하여 빌링키를 발급할수 있는 API 입니다.

## 빌링키 발급 API

<mark style="color:green;">`POST`</mark> `https://api.iamport.kr/subscribe/customers/{customer_uid}`

구매자에 대해 빌링키 발급을 요청 할 수 있습니다.

#### Path Parameters

| Name                                            | Type       | Description                             |
| ----------------------------------------------- | ---------- | --------------------------------------- |
| customer\_uid<mark style="color:red;">\*</mark> | String(80) | <mark style="color:red;">**빌링키**</mark> |

#### Request Body

| Name                                           | Type   | Description                                                                                             |
| ---------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| pg                                             | String | **PG 구분코드**                                                                                             |
| card\_number<mark style="color:red;">\*</mark> | String | <p><strong>카드번호</strong></p><p><mark style="color:red;"><strong>XXXX-XXXX-XXXX-XXXX</strong></mark></p> |
| expiry<mark style="color:red;">\*</mark>       | String | <p><strong>카드 유효기간</strong></p><p><mark style="color:red;"><strong>YYYY-MM</strong></mark></p>          |
| birth                                          | String | <p><strong>생년월일 6자리</strong></p><p><strong>법인카드인 경우 사업자 번호 10자리</strong></p>                            |
| pwd\_2digit                                    | String | **카드비밀번호 앞 2자리**                                                                                        |
| cvc                                            | String | **카드 인증번호**                                                                                             |
| customer\_name                                 | String | **카드소유자명**                                                                                              |
| customer\_tel                                  | String | **카드소유자 연락처**                                                                                           |
| customer\_email                                | String | **카드소유자 이메일주소**                                                                                         |
| customer\_addr                                 | String | **카드소유자 주소**                                                                                            |
| customer\_postcode                             | String | 카드소유자 우편번호                                                                                              |
| customer\_id                                   | String | <p>구매자 ID(</p><p><mark style="color:red;"><strong>토스페이먼츠 전용</strong></mark></p><p>)</p>                 |

{% tabs %}
{% tab title="200: OK 빌링키 발급성공" %}
{% tabs %}
{% tab title="CustomerResponse" %}
**`code`** <mark style="color:red;">**\***</mark> <mark style="color:purple;">**integer**</mark>

**응답코드**

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

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

**응답메세지**

code 값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

**`response`** <mark style="color:red;">**(CustomerAnnotation, optional)**</mark>
{% endtab %}
{% endtabs %}

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

**`응답코드`**

0이면 정상적인 조회, 0 이 아닌 값이면 message를 확인해봐야 합니다

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

**`응답메세지`**

code값이 0이 아닐 때, '존재하지 않는 결제정보입니다'와 같은 오류 메세지를 포함합니다

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

**`고객 고유번호`**\\

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

**빌링키가 등록된 PG사 코드**

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

**빌링키가 등록된 PG사 상점아이디(MID)**

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

**`카드사명`**

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

**`카드사 코드`**

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

**`마스킹 카드번호`**

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

**`카드유형`**

**(주의)해당 정보를 제공하지 않는 일부 PG사의 경우 null 로 응답됨**

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

**`고객성함`**

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

**`고객 전화번호`**

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

**`고객 Email`**

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

**`고객 주소`**

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

**`고객 우편번호`**

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

**`빌키가 등록된 시각`** UNIX timestamp

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

**`빌키가 업데이트된 시각`** UNIX timestamp
{% endtab %}
{% endtabs %}
{% endtab %}

{% tab title="401: Unauthorized 인증 Token이 전달되지 않았거나 유효하지 않은 경우" %}

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

{% endtab %}
{% endtabs %}

### **주요 요청 파라미터 상세 설명**

> **`pg`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>
>
> **PG 구분코드**
>
> 한 PG사에 복수개 MID 를 이용중인 경우 <mark style="color:red;">**PG구분코드.MID**</mark> 형태로 기입하시면 됩니다.
>
> *ex) NHN KCP를 사용하고 사이트 코드가 IPXC 인 경우*
>
> **kcp.IPXC**

> **`birth`** <mark style="color:red;">**\***</mark> <mark style="color:green;">**string**</mark>
>
> **생년월일**
>
> 일부 PG사에 한하여 생략 가능(PG사 협의 필요)

> **`customer_id`** <mark style="color:green;">**`string`**</mark>
>
> **`구매자 ID`**
>
> 빌링키를 발급한 고객의 고유 ID <mark style="color:red;">**토스페이먼츠 전용**</mark>

{% hint style="info" %}
**해당 빌링키 발급 API 는 PG사와 협의가 완료된 경우 이용 가능한 서비스입니다.**

* PG사 협의를 통해 카드정보 필수 조건 값 조정이 가능합니다.
* 민감한 카드정보를 이용하기 때문에 보안에 특히 유의하셔야 합니다.
* customer\_uid 값은 **고객 & 카드번호** 단위별로 고유하게 발급 관리되어야 합니다
  {% endhint %}

<details>

<summary>Response Model Schema</summary>

```json
{
  "code": 0,
  "message": "string",
  "response": {
    "customer_uid": "string",
    "pg_provider": "string",
    "pg_id": "string",
    "card_name": "string",
    "card_code": "string",
    "card_number": "string",
    "card_type": "null",
    "customer_name": "string",
    "customer_tel": "string",
    "customer_email": "string",
    "customer_addr": "string",
    "customer_postcode": "string",
    "inserted": 0,
    "updated": 0
  }
```

</details>

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

[**https://api.iamport.kr/#!/subscribe.customer/customer\_save**](https://api.iamport.kr/#!/subscribe.customer/customer_save)
{% endhint %}