sayren Docs
스토어 설정

포트원 연결·수정

포트원(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`이다.

PUT
/v1/store/payment-providers/portone

포트원(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이다.

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/portone" \  -H "Content-Type: application/json" \  -d '{    "environment": "TEST",    "credentials": {      "storeId": "stringst",      "channels": [        {          "channelKey": "stringst",          "payMethods": [            "CARD"          ]        }      ]    }  }'
{  "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마다 `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`이다.

PG 사용 여부·샌드박스 스위치·간편결제 변경 PATCH

PG를 켜거나 끄고(`enabled`), 샌드박스 스위치(`sandboxMode`)와 이 PG로 받는 간편결제사(`easyPayProviders`)를 바꾼다. 셋 중 하나 이상을 보낸다. 켠 간편결제사마다 스토어프론트 결제 옵션이 생긴다. 끈 PG는 새 결제에 쓰이지 않지만, 이미 그 PG로 승인된 결제의 취소·환불은 계속 그 PG로 처리된다. `sandboxMode: false`(라이브 전환)는 `liveGate.conditions`를 모두 충족해야 한다 — 테스트 키 연결 테스트 성공, 지금 테스트 키로 샌드박스 결제 1건 승인, 그 결제의 환불 1건 성공, 라이브 키 연결 테스트 성공, 플랫폼 실결제 허용. `sandboxMode: true`는 언제든 허용되고 바로 실결제가 멈춘다. 사용 중인 PG 중 하나라도 라이브면 구매자 결제는 라이브 PG로만 진행되고 샌드박스 PG는 쓰이지 않는다. 콘솔에 로그인한 **OWNER 전용**이다. ADMIN·STAFF, API 토큰(PAT), M2M 클라이언트, 3rd-party 앱이 위임받은 토큰은 스코프가 있어도 `403 INSUFFICIENT_ROLE`이다.