sayren Docs
스토어 설정

토스페이먼츠 연결·수정

토스페이먼츠 자격 증명을 저장한다. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 자격 증명 세트를 따로 저장한다. 요청의 `environment`는 **저장할 세트**이고, 어느 세트로 결제할지는 샌드박스 스위치(`PATCH …/{provider}`의 `sandboxMode`)가 정한다. 같은 가맹점(토스 클라이언트 키·포트원 Store ID)이면 그 세트를 갱신하고, 가맹점이 바뀌면 이전 세트를 **보관**한 뒤 새 세트를 만든다 (예전에 보관한 같은 가맹점 세트가 있으면 새로 만들지 않고 그 세트를 다시 쓴다). 보관된 세트는 새 결제에 쓰이지 않지만, 그 가맹점으로 이미 받은 결제의 취소·환불과 결제 확인에는 계속 쓰인다. 실결제 중(샌드박스 꺼짐)인 PG의 LIVE 세트를 저장하면 가맹점이 같아도 저장 전에 연결 테스트를 한다. 처음 연결하면 **사용 중지·샌드박스 켜짐 상태**로 만들어진다 — 연결 테스트 후 `PATCH /v1/store/payment-providers/tosspayments`로 켠다. 수정할 때 `secretKey`·`webhookSecret`을 생략하면 저장된 값을 유지한다(저장된 비밀 값은 다시 조회할 수 없고 교체만 된다). 자격 증명을 바꾸면 마지막 연결 테스트 결과가 초기화된다. 콘솔에 로그인한 **OWNER 전용**이다. ADMIN·STAFF, API 토큰(PAT), M2M 클라이언트, 3rd-party 앱이 위임받은 토큰은 스코프가 있어도 `403 INSUFFICIENT_ROLE`이다.

PUT
/v1/store/payment-providers/tosspayments

토스페이먼츠 자격 증명을 저장한다. PG마다 TEST(샌드박스)·LIVE(실결제) 자격 증명 세트를 따로 저장한다. 요청의 environment는 저장할 세트이고, 어느 세트로 결제할지는 샌드박스 스위치(PATCH …/{provider}의 sandboxMode)가 정한다. 같은 가맹점(토스 클라이언트 키·포트원 Store ID)이면 그 세트를 갱신하고, 가맹점이 바뀌면 이전 세트를 보관한 뒤 새 세트를 만든다 (예전에 보관한 같은 가맹점 세트가 있으면 새로 만들지 않고 그 세트를 다시 쓴다). 보관된 세트는 새 결제에 쓰이지 않지만, 그 가맹점으로 이미 받은 결제의 취소·환불과 결제 확인에는 계속 쓰인다. 실결제 중(샌드박스 꺼짐)인 PG의 LIVE 세트를 저장하면 가맹점이 같아도 저장 전에 연결 테스트를 한다. 처음 연결하면 사용 중지·샌드박스 켜짐 상태로 만들어진다 — 연결 테스트 후 PATCH /v1/store/payment-providers/tosspayments로 켠다. 수정할 때 secretKey·webhookSecret을 생략하면 저장된 값을 유지한다(저장된 비밀 값은 다시 조회할 수 없고 교체만 된다). 자격 증명을 바꾸면 마지막 연결 테스트 결과가 초기화된다. 콘솔에 로그인한 OWNER 전용이다. ADMIN·STAFF, API 토큰(PAT), M2M 클라이언트, 3rd-party 앱이 위임받은 토큰은 스코프가 있어도 403 INSUFFICIENT_ROLE이다.

Authorization

bearer
AuthorizationBearer <token>

userToken(계정 스코프) 또는 storeToken(스토어 스코프)

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

environment*string

저장할 자격 증명 세트. PG마다 TEST(샌드박스)·LIVE(실결제) 세트를 따로 둔다. 어느 세트로 결제할지는 이 값이 아니라 샌드박스 스위치(sandboxMode)가 정한다

Value in

  • "TEST"
  • "LIVE"
credentials*

Response Body

application/json

curl -X PUT "https://example.com/v1/store/payment-providers/tosspayments" \  -H "Content-Type: application/json" \  -d '{    "environment": "TEST",    "credentials": {      "clientKey": "stringst"    }  }'
{  "meta": {    "status": 200,    "code": "OK",    "message": "OK",    "isSuccess": true  },  "data": {    "provider": "tosspayments",    "displayName": "string",    "connected": true,    "enabled": true,    "priority": 0,    "environment": "TEST",    "publicConfig": {      "clientKey": "string"    },    "secrets": [      {        "field": "string",        "configured": true,        "masked": "string"      }    ],    "lastVerification": {      "result": "SUCCESS",      "message": "string",      "checkedAt": "string"    },    "updatedAt": "string",    "sandboxMode": true,    "credentialSets": {      "TEST": {        "environment": "TEST",        "publicConfig": {          "clientKey": "string"        },        "secrets": [          {            "field": "string",            "configured": true,            "masked": "string"          }        ],        "lastVerification": {          "result": "SUCCESS",          "message": "string",          "checkedAt": "string"        },        "updatedAt": "string"      },      "LIVE": {        "environment": "TEST",        "publicConfig": {          "clientKey": "string"        },        "secrets": [          {            "field": "string",            "configured": true,            "masked": "string"          }        ],        "lastVerification": {          "result": "SUCCESS",          "message": "string",          "checkedAt": "string"        },        "updatedAt": "string"      }    },    "liveGate": {      "status": "LOCKED",      "conditions": [        {          "code": "TEST_CONNECTION",          "met": true,          "message": "string"        }      ],      "openedAt": "string"    },    "easyPayProviders": [      "string"    ],    "retiredCredentialCount": 0,    "routingExclusion": null  },  "error": null}

결제 설정 변경 (우선순위·결제 도메인) PUT

PG 우선순위(스토어프론트 결제 옵션 목록의 PG 순서)와 결제 도메인을 바꾼다. 보낸 항목만 바꾼다. `priority`에는 연결된 PG를 모두 한 번씩 나열한다. `checkoutOrigins`는 결제를 마친 구매자가 돌아올 스토어프론트 origin 목록이다(https, 경로 없음) — 결제 시작의 `returnUrl`이 이 안이어야 하고, 비어 있으면 실결제를 시작할 수 없다. 콘솔에 로그인한 **OWNER 전용**이다. ADMIN·STAFF, API 토큰(PAT), M2M 클라이언트, 3rd-party 앱이 위임받은 토큰은 스코프가 있어도 `403 INSUFFICIENT_ROLE`이다.

포트원 연결·수정 PUT

포트원(V2) Store ID·채널·API Secret을 저장한다. 채널은 결제수단별로 여러 개 등록할 수 있고, 결제수단마다 그 결제수단을 받는 첫 채널이 쓰인다. 결제 요청의 결제수단을 받는 채널이 없으면 그 결제에서 포트원은 준비 장애로 처리된다. PG마다 `TEST`(샌드박스)·`LIVE`(실결제) 자격 증명 세트를 따로 저장한다. 요청의 `environment`는 **저장할 세트**이고, 어느 세트로 결제할지는 샌드박스 스위치(`PATCH …/{provider}`의 `sandboxMode`)가 정한다. 같은 가맹점(토스 클라이언트 키·포트원 Store ID)이면 그 세트를 갱신하고, 가맹점이 바뀌면 이전 세트를 **보관**한 뒤 새 세트를 만든다 (예전에 보관한 같은 가맹점 세트가 있으면 새로 만들지 않고 그 세트를 다시 쓴다). 보관된 세트는 새 결제에 쓰이지 않지만, 그 가맹점으로 이미 받은 결제의 취소·환불과 결제 확인에는 계속 쓰인다. 실결제 중(샌드박스 꺼짐)인 PG의 LIVE 세트를 저장하면 가맹점이 같아도 저장 전에 연결 테스트를 한다. 처음 연결하면 사용 중지·샌드박스 켜짐 상태로 만들어진다. 수정 시 `apiSecret`·`webhookSecret`을 생략하면 저장된 값을 유지한다. 콘솔에 로그인한 **OWNER 전용**이다. ADMIN·STAFF, API 토큰(PAT), M2M 클라이언트, 3rd-party 앱이 위임받은 토큰은 스코프가 있어도 `403 INSUFFICIENT_ROLE`이다.