변경이력
버전 | 날짜 | 변경사항 |
V1.211014 | 2021-10-14 | 최초 작성 |
V1.220217 | 2022-02-17 | 대표 상점아이디(MID) 필드 추가 (primeMid) |
V1.231127 | 2023-11-27 | 매핑 조회 api 추가 (단건) |
1. 개요
식별자 매핑 연동 스펙 정의
2. API 공통사항
2.1. API 인증
2차PG → 토스페이먼츠 API 요청 시 HTTP Bearer Authentication 인증을 수행합니다.
인증 토큰은 2차PG 단위로 발급되며, 별도로 전달드립니다.
API Request Header
Name | Type | Description |
Authorization | String | Bearer 인증 값 |
2.2. API 응답
모든 API 응답은 아래와 같은 구조의 JSON포맷으로 제공됩니다.
Name | Type | Description |
success | Boolean | API 요청에 대한 성공여부 |
errorCode | String | 요청 처리 과정에서 발생한 에러코드 (성공시 null) |
message | String | 요청 처리 과정에서 발생한 오류메시지 (성공시 null) |
result | JSON | API 응답 별 객체 반환 |
2.3. Base URL
배포 스테이지 별 API 호출 URL은 아래와 같습니다.
Stage | URL |
dev | https://partners-api-dev.tosspayments.com |
staging | https://partners-api-staging.tosspayments.com |
live | https://partners-api.tosspayments.com |
3. API 사양
3.1. 매핑 추가 (2차PG → 토스페이먼츠)
2차PG에서 상점의 식별자를 토스페이먼츠의 상점아이디(MID)와 새롭게 매핑합니다.
3.1.1. Request
POST /merchants/api/v1/secondary-pg/mapping/add
Name | Type | Required | Description |
salesPartnerShopId | String | Y | 2차PG의 상점 식별자 (TID) |
mid | String | Y | 상점아이디(MID) |
primeMid | String | N | 대표 상점아이디(MID) |
3.2. 매핑 삭제 (2차PG → 토스페이먼츠)
매핑 추가 API 에서 생성한 매핑을 제거합니다.
3.2.1. Request
POST /merchants/api/v1/secondary-pg/mapping/delete
(1) Request Parameter
Name | Type | Required | Description |
salesPartnerShopId | String | Y | 2차PG의 상점 식별자 (TID) |
3.3. 매핑 조회
토스페이먼츠 
호스팅사 간의 상점 식별자 매핑을 조회합니다.
호스팅사 간의 상점 식별자 매핑을 조회합니다.매핑이 존재하지 않는 경우 http status 404로 응답합니다.
3.3.1. Request
GET /api/v1/secondary-pg/mapping
(1) Request Parameter
Name | Type | Required | Description |
salesPartnerShopId | String | Y | 호스팅사 측 상점 식별자 |
mid | String | Y | 상점 생성 시 전달된 토스페이먼츠 측 식별자 |
3.3.2. Response
Name | Type | Description |
salesPartnerShopId | String | 호스팅사 측 식별자 |
mid | String | 토스페이먼츠 측 식별자 |
createdAt | String | 매핑 생성 일시 (yyyy-MM-ddThh:mm:ss) |