---
title: 파트너용 API
description: 쇼핑몰 솔루션이나 정산 도구 같은 파트너 서비스가 OAuth 2.0 인가 코드 방식으로 고객의 페이싱크 워크스페이스에 연결하는 흐름과 앱 등록 방법이에요.
sidebar:
  label: 개요
---

파트너 앱은 여러 고객의 페이싱크 워크스페이스에 연결해서 API를 호출하는 외부 서비스예요. 고객에게 API 키를 받아 저장하는 대신, 고객이 페이싱크 연결 화면에서 허용하면 워크스페이스 하나에 쓸 액세스 토큰을 받아요. 페이싱크는 OAuth 2.0 인가 코드 방식(RFC 6749)을 지원하고, PKCE(S256)는 선택이에요.

내 워크스페이스 하나만 연동한다면 이 방식이 필요 없어요. [API 키](/api-keys)를 쓰세요.

## 연결 흐름

1. **인가 요청**

    고객을 페이싱크 연결 화면(`https://paysync.kr/oauth/authorize`)으로 보내요. [인가 요청](/partners/oauth/authorize)을 참고하세요.

2. **고객의 허용**

    고객이 로그인하고 연결할 워크스페이스를 고른 뒤 요청한 권한을 허용해요. 페이싱크는 `redirect_uri`로 인가 코드를 보내요.

3. **토큰 발급**

    파트너 서버가 인가 코드를 액세스 토큰으로 바꿔요. [토큰 발급](/partners/oauth/token)을 참고하세요.

4. **API 호출**

    액세스 토큰으로 `/v2` API를 호출해요. [API 호출](/partners/calling-api)을 참고하세요.

고객 쪽에서 보이는 화면은 [연결된 앱](/connected-apps)에 정리해 뒀어요.

## 앱 등록

파트너 앱은 페이싱크가 등록해요. [페이싱크](https://paysync.kr) 화면의 상담 위젯이나 [디스코드](https://paysync.kr/discord)로 아래 정보를 보내 주세요.

| 항목 | 설명 |
| --- | --- |
| 앱 이름 | 연결 화면과 고객의 연결된 앱 화면에 보여요. 2~32자예요. |
| 로고 | 연결 화면과 연결된 앱 화면에 보여요. 없으면 앱 이름의 첫 글자를 보여요. |
| 리디렉션 URI | 인가 코드를 받을 주소예요. 1~10개를 등록할 수 있어요. 아래 [리디렉션 URI 규칙](#리디렉션-uri-규칙)을 참고하세요. |
| 필요한 스코프 | 앱이 요청할 [스코프](/partners/scopes)예요. 앱은 등록된 스코프 안에서만 요청할 수 있어요. |

등록하면 클라이언트 자격 증명을 받아요.

| 값 | 형식 | 설명 |
| --- | --- | --- |
| `client_id` | `oap_` + 24자 | 앱 ID예요. 인가 요청과 토큰 요청에 넣어요. |
| `client_secret` | `oas_` + 40자 | 토큰 요청에 넣는 비밀 값이에요. |

:::warning
`client_secret`은 등록할 때 한 번만 전달돼요. 서버의 비밀 관리 도구에 보관하고, 브라우저나 모바일 앱에 넣지 마세요. 유출됐다면 페이싱크에 재발급을 요청하세요. 재발급하면 이전 시크릿은 바로 멈추고, 이미 연결된 워크스페이스와 발급한 액세스 토큰은 그대로 동작해요.
:::

## 리디렉션 URI 규칙

- `https` 주소여야 해요. 개발용으로는 `http://localhost`와 `http://127.0.0.1`도 쓸 수 있어요.
- `#` 뒤 프래그먼트와 `user:password@` 형식의 사용자 정보는 넣을 수 없어요.
- 2048자까지예요.
- 인가 요청과 토큰 요청의 `redirect_uri`는 등록한 값과 글자 하나까지 같아야 해요. 경로 일부나 와일드카드로는 맞추지 않아요.

## 기본 주소

| 용도 | 주소 |
| --- | --- |
| [연결 화면](/partners/oauth/authorize) | `GET https://paysync.kr/oauth/authorize` |
| [토큰 발급](/partners/oauth/token) | `POST https://api.paysync.kr/v2/oauth-apps/token` |
| [토큰 폐기](/partners/oauth/revoke) | `POST https://api.paysync.kr/v2/oauth-apps/revoke` |
| [API](/partners/calling-api) | `https://api.paysync.kr/v2` |