# Pay Station API

# 개요 {% #overview %}

* **버전:** 2.0.0
* **서버**:
  * `https://api.xsolla.com/api`

페이 스테이션을 통해 파트너가 사용자에게 게임 스토어에서 인게임 구매를 결제하도록 돕는 편리한 UI를 제공하고 수익을 창출할 수 있습니다. 
결제 UI를 열도록 설정하려면 다음 [지침](/ko/doc/pay-station/how-to/how-to-open-payment-ui/)을 참조해 
주세요.

페이 스테이션 API는 다음과 같은 호출 그룹을 제공합니다.
- 토큰 - 결제 UI를 통해 추후 결제 처리에 사용하는 임의 사용자 매개 변수로 토큰을 생성하는 API 호출을 포함합니다.
- [토큰화](/ko/doc/pay-station/features/tokenization/) - 결제 UI를 열지 않고 사용자의 개입이 없어도 안전하게 
  결제를 처리하는 API 호출을 포함합니다.
- 보고서 - 사용자 트랜잭션 데이터를 반환하고, 보고서를 생성하고, 통화별 지급액 내역을 확인할 수 있는 API 호출을 포함합니다.
- 환불 - 전액 및 부분 환불을 요청하는 API 호출을 포함합니다.
- 테스트 - 지불 거절 프로세스를 테스트하는 API 호출을 포함합니다.

결제 UI 구성에 대한 자세한 정보는 [결제 솔루션 연동 가이드](/ko/solutions/payments/integration-guide/integration-flow/)에서 확인할 수 있습니다.

<div class="note">
<p><strong>참고</strong></p><p>또한 <a href="https://github.com/xsolla/xsolla-postman">포스트맨 컬렉션</a>의 <b>Xsolla Base API</b> 섹션을 참조하여 연동에 사용되는 API 호출을 테스트할 수 있습니다.</p>
</div>


Version: 2.0

## Servers

```
https://api.xsolla.com/merchant/v2
```

## Security

### basicAuth

Xsolla API는 기본 액세스 인증을 사용합니다. API에 대한 모든 요청에는 `Authorization: Basic 
<your_authorization_basic_key>` 헤더가 포함되어야 하며 여기서 
`<your_authorization_basic_key>`는 Base64 표준에 따라 인코딩된 `merchant_id:api_key` 쌍입니다.

이러한 매개 변수를 확인하려면 [관리자 페이지](https://publisher.xsolla.com/)으로 이동하십시오.

- `merchant_id`가 표시됩니다.
  - **회사 설정 > 회사** 섹션에서
  - 관리자 페이지의 브라우저 주소 표시줄에 있는 URL에 있습니다. URL의 형식은 
    `https://publisher.xsolla.com/<merchant_id>`입니다.
- `api_key`는 관리자 페이지가 생성될 때 한 번만 표시되며 사용자 측에 저장해야 합니다. 다음 섹션에서 새 키를 만들 수 있습니다:
  - **회사 설정 > API 키**
  - **프로젝트 설정 > API 키**

API 키 작업에 대한 자세한 내용은 [API 참조](https://developers.xsolla.com/ko/api/getting-started/#api_keys_overview)를 참조하세요.


Type: http
Scheme: basic

## Download OpenAPI description

[Pay Station API](https://xsolla.redocly.app/_bundle/@l10n/ko/api/pay-station/index.yaml)

## 토큰

### 토큰 생성

 - [POST /merchants/{merchant_id}/token](https://xsolla.redocly.app/ko/api/pay-station/token/create-token.md): 임의의 사용자 매개변수로 토큰을 생성할 수 있습니다. 토큰을 받을 때 이러한 매개변수를 전송하고, 결제가 성공적으로 완료된 후 전송했던 
매개변수를 다시 받습니다. 토큰에는 이 문서에 설명되어 있거나 미리 정의한 매개변수만 포함할 수 있습니다.

매개변수가 잘못된 형식으로 전송되거나 잘못된 유형인 경우 토큰이 발급되지 않습니다. JSON 본문으로 오류 설명이 포함된 422 HTTP 
코드를 받게 됩니다. extended_message로 정확히 어떤 매개변수가 잘못 전송되었는지에 대한 정보를 받게 됩니다.

기본적으로 토큰의 수명은 24시간입니다. 이 값을 변경하려면 계정 관리자에게 문의하거나 csm@xsolla.com으로 이메일을 보내주세요. 새 값은 관리자 페이지에서 생성한 회사의 모든 프로젝트에서 활성화됩니다.


주의이 API 메소드를 호출한 후 획득한 토큰은 다른 요청을 인증하는 용도로만 사용할 수 있습니다. 이 토큰은 정기 결제 제품을 연동한 경우에만 결제 UI를 여는 데 사용할 수 있습니다.결제 UI를 새 창에서 열려면 https://secure.xsolla.com/paystation4/?token={token} 링크를 사용합니다. 여기서 {token} 은 수신한 토큰입니다.테스트를 진행할 때에는 https://sandbox-secure.xsolla.com/paystation4/?token={token} URL을 사용합니다.





주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### 토큰 무효화

 - [POST /projects/{project_id}/token/{token}/expire](https://xsolla.redocly.app/ko/api/pay-station/token/invalidate-token.md): 기존 결제 토큰을 무효화하여 해당 토큰으로 결제 UI를 열 수 없도록 합니다. 이 기능을 사용하면 병렬 세션 간에 단일 인스턴스 아이템에 대한 
중복 결제를 방지할 수 있습니다. 호출이 성공적으로 완료되면, 이 결제 토큰으로 열린 다른 모든 사용자 세션이 만료됩니다.


참고이 API 호출은 idempotent이므로 여러 번 사용할 수 있습니다.

## 직접 결제

### 저장된 결제 계정 나열

 - [GET /projects/{project_id}/users/{user_id}/payment_accounts](https://xsolla.redocly.app/ko/api/pay-station/tokenization/get-saved-accounts.md): 사용자의 저장된 결제 계정을 나열합니다.


참고샌드박스 모드에서는 3D 보안 기능이 없는 테스트 카드에서만 이 API 호출이 작동합니다.

### 저장된 결제 계정 삭제

 - [DELETE /projects/{project_id}/users/{user_id}/payment_accounts/{type}/{account_id}](https://xsolla.redocly.app/ko/api/pay-station/tokenization/delete-saved-account.md): 저장된 결제 계정 삭제.


참고샌드박스 모드에서는 3D 보안 기능이 없는 테스트 카드에서만 이 API 호출이 작동합니다.





참고샌드박스 모드에서 이 API 메소드를 호출할 수 있습니다. 이렇게 하려면 요청에서 테스트 결제 계정 데이터를 전달합니다. 샌드박스 모드 액세스 및 테스트 시나리오에 대한 자세한 내용은 지침을 참조하세요.

### 저장한 계정으로 청구

 - [POST /projects/{project_id}/users/{user_id}/payments/{type}/{account_id}](https://xsolla.redocly.app/ko/api/pay-station/tokenization/charge-with-saved-account.md): 저장된 결제 계정을 사용하여 청구합니다.


참고샌드박스 모드에서는 3D 보안 기능이 없는 테스트 카드에서만 이 API 호출이 작동합니다.





주의API 호출이 올바르게 작동되게 하려면 시간제한을 2분으로 구성하세요.

## 보고서

### 모든 보고서 나열

 - [GET /merchants/{merchant_id}/reports](https://xsolla.redocly.app/ko/api/pay-station/reports/get-reports.md): 지정된 데이터 범위의 재무 보고서 목록을 가져옵니다.


주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### 모든 작업 나열

 - [GET /merchants/{merchant_id}/reports/transactions/registry.{format}](https://xsolla.redocly.app/ko/api/pay-station/reports/get-transactions.md): 지정된 기간 동안의 성공 및 취소된 트랜잭션에 대한 세부 정보 목록을 반환합니다. 이에 대한 응답으로 수수료, 세금, 주문 및 사용자에 대한 
데이터를 포함한 결제 관련 정보를 얻을 수 있습니다. JSON 또는 CSV 형식으로 목록을 가져올 수 있습니다. 이 API 호출을 사용하여 
재정 조정을 수행할 수 있습니다.


주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### 모든 트랜잭션 검색

 - [GET /merchants/{merchant_id}/reports/transactions/search.{format}](https://xsolla.redocly.app/ko/api/pay-station/reports/find-transactions.md): 특정 검색 매개 변수를 기준으로 트랜잭션 목록을 반환합니다. 이에 대한 응답으로 성공적으로 완료되지 않았더라도 게임에서 이루어진 모든 결제에 
대한 데이터를 얻을 수 있습니다. 트랜잭션 기간뿐만 아니라 특정 사용자 또는 특정 결제 상태의 거래를 검색하는 등 다른 매개 변수도 지정할 수 
있습니다. JSON 또는 CSV 형식으로 목록을 가져올 수 있습니다.


주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### 트랜잭션 검색(빠른 검색)

 - [GET /merchants/{merchant_id}/reports/transactions/simple_search](https://xsolla.redocly.app/ko/api/pay-station/reports/find-transactions-fast.md): 몇 초 내에 특정 검색 매개변수를 기반으로 트랜잭션 목록을 구합니다. 이는 모든 트랜잭션 검색 API 호출을 대체할 수 있는 기능으로 JSON, CSV 또는 XLS 
형식으로 데이터를 반환합니다.


주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### 통화로 지불금 내역을 받습니다

 - [GET /merchants/{merchant_id}/reports/transactions/summary/transfer](https://xsolla.redocly.app/ko/api/pay-station/reports/get-payouts-breakdown.md): 통화로 지불금 내역을 받습니다.


주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### 트랜잭션 정보 가져오기

 - [GET /merchants/{merchant_id}/reports/transactions/{transaction_id}/details](https://xsolla.redocly.app/ko/api/pay-station/reports/get-transaction.md): ID별로 전체 트랜잭션 정보를 가져옵니다.


주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### 모든 송금 나열

 - [GET /merchants/{merchant_id}/reports/transfers](https://xsolla.redocly.app/ko/api/pay-station/reports/get-payouts.md): 일정 기간 동안의 모든 지불금을 나열합니다.


주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

## 환불

### 부분 환불

 - [PUT /merchants/{merchant_id}/reports/transactions/{transaction_id}/partial_refund](https://xsolla.redocly.app/ko/api/pay-station/refund/request-partial-refund.md): 사용자에게 부분 환불 요청을 보냅니다. 부분 환불과 부분 환불을 지원하는 결제 방식에 대한 자세한 내용은 
문서을 참조해 주세요.


참고샌드박스 모드에서 이 API 메소드를 호출할 수 있습니다. 이렇게 하려면 요청에서 테스트 결제 데이터를 전달합니다. 샌드박스 모드 액세스 및 테스트 시나리오에 대한 자세한 내용은 지침을 참조하세요.





주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

### 전체 환불

 - [PUT /merchants/{merchant_id}/reports/transactions/{transaction_id}/refund](https://xsolla.redocly.app/ko/api/pay-station/refund/request-refund.md): 환불 요청을 전송하여 사용자에게 결제 금액을 반환합니다. 해당 절차에 대해 자세히 알아보려면 [환불 
기능](https://developers.xsolla.com/ko/doc/pay-station/features/refund/)을 읽어 보십시오.


참고샌드박스 모드에서 이 API 메소드를 호출할 수 있습니다. 이렇게 하려면 요청에서 테스트 결제 데이터를 전달합니다. 샌드박스 모드 액세스 및 테스트 시나리오에 대한 자세한 내용은 지침을 참조하세요.





주의이 API 호출에는 project_id 경로 매개 변수가 포함되어 있지 않으므로 회사의 모든 프로젝트에서 유효한 API 키를 사용하여 인증을 설정해야 합니다.

## 테스트

### 지불 거절 요청

 - [POST /merchants/{merchant_id}/projects/{project_id}/payments/{transaction_id}/chargeback](https://xsolla.redocly.app/ko/api/pay-station/testing/request-chargeback.md): 샌드박스 모드에서 지불 거절 요청:

- 샌드박스 모드에 액세스하려면 토큰을 획득할 때 "mode":"sandbox"를 전달합니다.

- 테스트 결제는 테스트에 사용한 것과 동일한 프로젝트의 샌드박스 모드에서 이루어져야 합니다.

- 거래 상태는 refunded와 cancelled 이외여야 합니다.

- 게시자 계정에서 여러분의 역할이 최소한 재무 관리자여야 합니다(회사 설정 > 사용자 섹션에서 확인할 수 있습니다).

- 이 테스트 시나리오에 대한 자세한 정보는 지침을 참조하세요.


참고다른 테스트 시나리오에 대한 자세한 정보는 문서를 참조하세요.