> For the complete documentation index, see [llms.txt](https://ofin.gitbook.io/document/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ofin.gitbook.io/document/payment/creation.md).

# 결제 생성

구매자의 **후불 결제 요청**을 시작하기 위해 결제를 생성하는 API입니다.

## Endpoints

* **URL:** `/api/v1/user/payment`
* **Method:** `POST` 

## **Request**

<table><thead><tr><th width="158.88671875">변수명</th><th width="123.17578125">타입</th><th width="110.35546875">필수 여부</th><th width="120.2109375">max length</th><th>description</th></tr></thead><tbody><tr><td>apiKey</td><td>String</td><td>O</td><td>255</td><td>플랫폼 API Key</td></tr><tr><td>orderNo</td><td>String</td><td>O</td><td>50</td><td>주문번호는 숫자, 영문자, 특수문자(_-:.)만 사용 가능</td></tr><tr><td>productDescription</td><td>String</td><td>O</td><td>255</td><td><ul><li>상품 설명은 한글, 영문, 숫자, 공백만 사용 가능</li><li>공백만 입력 불가</li></ul></td></tr><tr><td>businessNumber</td><td>String</td><td>O</td><td>10</td><td>사업자등록번호는 숫자만 입력 가능</td></tr><tr><td>purchaseAmount</td><td>Integer</td><td>O</td><td>16</td><td>결제 금액</td></tr><tr><td>scheduleIdentifier</td><td>String</td><td>O</td><td>10</td><td><ul><li>스케줄 식별자는 상환 일시를 지정하는 값으로 <strong>사전에 협의된 식별자만</strong> 사용 가능</li><li>항상 결제일 기준</li><li>{숫자}M{숫자}D 형식</li><li>1달 후 30일 = <strong><code>1M30D</code></strong> </li><li>2달 후 30일 = <strong><code>2M30D</code></strong></li><li>익월 7일 = <strong><code>1M7D</code></strong></li><li>오늘로부터 45일 뒤 = <strong><code>0M45D</code></strong></li></ul></td></tr><tr><td>resultCallback</td><td>String</td><td>O</td><td>500</td><td>결제 결과 Callback 받을 URL</td></tr><tr><td>successCallbackUrl</td><td>String</td><td>O</td><td>500</td><td>결제 완료 후 성공 시 redirect 할 URL</td></tr><tr><td>failCallbackUrl</td><td>String</td><td>O</td><td>500</td><td>결제 완료 후 실패 시 redirect 할 URL</td></tr></tbody></table>

#### **Request Example**

```json
{
  "apiKey": "my8isVOhkPvAeLbtealSrEYyJBCZa ... BSDINWJPKs6th5QBTdYZHCtLxavagMR2I",
  "orderNo" : "order:20250901:000001",
  "productDesciption" : "테스트 결제",
  "businessNumber": "5098601645",
  "purchaseAmount": 128900,
  "scheduleIdentifier" : "1M30D",
  "resultCallback": "https://ofin.co.kr/demo/callback",
  "successCallbackUrl": "https://ofin.co.kr/demo/success",
  "failCallbackUrl": "https://ofin.co.kr/demo/fail"
}
```

## Response

* **checkoutPage (String) (maxLen:500)**
  * 결제 진행 가능한 URL
* **paymentToken (String) (maxLen:25)**
  * 25자리 계약 토큰

{% hint style="warning" %} <mark style="color:orange;">**✔️ 결제 프로세스는 생성 시점부터 3분간 유효합니다.**</mark>

<mark style="color:orange;">**✔️ 유효 시간이 경과하면 토큰이 만료되어 결제를 진행할 수 없습니다.**</mark>

<mark style="color:orange;">**✔️ 계속 진행하려면 새로운 결제를 생성해야 합니다.**</mark>

<mark style="color:orange;">**✔️ 새로운 결제 생성 시, 기존 결제 토큰은 자동으로 비활성화됩니다.**</mark>
{% endhint %}

#### **Response Example**

```json
{
  "meta": {
    "code": "SUCCESS",
    "message": "성공"
  },
  "data": {
    "checkoutPage": "https://ofin.co.kr/payment-front/auth?paymentToken=example-paymentToken",
    "paymentToken": "example-paymentToken"
  }
}
```

### Error Handling

* DUPLICATED\_ORDER\_NO : 중복 주문번호가 존재합니다.
* PAYMENT\_LIMIT\_EXCEEDED : 한도가 부족합니다. 잔여 한도를 확인해주세요.
* PAYMENT\_OVERDUE\_USER : 미납 고객으로 사용이 불가합니다.
* PAYMENT\_INVALID\_USER : 비정상 고객(비회원, 차단회원 등)으로 사용이 불가합니다.
* INTERNAL\_SERVER\_ERROR : 서버 내부 에러입니다.
* BAD\_REQUEST : 유효하지 않은 데이터입니다.

<pre class="language-json"><code class="lang-json"><strong>{
</strong>  "meta": {
    "code": "PAYMENT_LIMIT_EXCEEDED",
    "message": "한도가 부족합니다. 잔여 한도를 확인해주세요."
  },
  "data": null
}
</code></pre>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

```
GET https://ofin.gitbook.io/document/payment/creation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.