sayren Docs
스토어 설정

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

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

PUT
/v1/store/payment-settings

PG 우선순위(스토어프론트 결제 옵션 목록의 PG 순서)와 결제 도메인을 바꾼다. 보낸 항목만 바꾼다. priority에는 연결된 PG를 모두 한 번씩 나열한다. checkoutOrigins는 결제를 마친 구매자가 돌아올 스토어프론트 origin 목록이다(https, 경로 없음) — 결제 시작의 returnUrl이 이 안이어야 하고, 비어 있으면 실결제를 시작할 수 없다. 콘솔에 로그인한 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.

priority?array<>

PG 우선순위(앞이 1순위) — 스토어프론트 결제 옵션 목록의 PG 순서다. 연결된 PG 수만큼 모두 한 번씩 나열한다(길이 상한 50은 안전장치다). 빠지거나 중복되거나 연결되지 않은 PG가 있으면 INVALID_PRIORITY

Items1 <= items <= 50
checkoutOrigins?array<>

결제 도메인 — 통째로 바꾼다. 결제를 마친 구매자가 돌아올 스토어프론트 origin(https://shop.example.com, https·경로 없음). 결제 시작의 returnUrl은 이 목록 안이어야 한다. 비어 있으면 실결제를 시작할 수 없다(테스트 결제는 localhost 허용). 같은 도메인을 PG 가맹 정보에도 등록한다. 형식이 틀리면 INVALID_CHECKOUT_ORIGIN

Itemsitems <= 20

Response Body

application/json

curl -X PUT "https://example.com/v1/store/payment-settings" \  -H "Content-Type: application/json" \  -d '{}'
{  "meta": {    "status": 200,    "code": "OK",    "message": "OK",    "isSuccess": true  },  "data": {    "checkoutOrigins": [      "string"    ],    "providers": [      {        "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      }    ],    "environment": "TEST",    "candidates": []  },  "error": null}

결제 설정 조회 GET

결제 도메인과 지원하는 모든 PG의 연결 상태(간편결제 포함)를 조회한다. 비밀 값(시크릿 키·API Secret·웹훅 시크릿)은 앞 4자리 마스킹만 나오고 평문은 어떤 응답에도 없다. 콘솔에 로그인한 **OWNER 전용**이다. ADMIN·STAFF, API 토큰(PAT), M2M 클라이언트, 3rd-party 앱이 위임받은 토큰은 스코프가 있어도 `403 INSUFFICIENT_ROLE`이다.

토스페이먼츠 연결·수정 PUT

토스페이먼츠 자격 증명을 저장한다. 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`이다.