브랜드페이 API

브랜드페이에서 제공하는 API 엔드포인트(Endpoint)와 객체 정보, 파라미터, 요청 및 응답 예제를 살펴보세요.

브랜드페이 API를 이용하면 SDK UI를 통해 제공하는 기능을 직접 구현할 수 있습니다.

브랜드페이 API 인증 방식에 대한 내용은 브랜드페이 인증에서 확인하세요. API 키 정보와 인증 방식, 보안에 대한 정보는 API 사용하기에서 자세히 알아보세요.

사용자 인증

Terms 객체

고객이 브랜드페이를 사용하기 위해 동의해야 하는 약관 정보를 담고 있는 객체입니다.

객체 상세

  • id integer

    약관의 ID입니다.

  • title string

    약관 제목입니다.

  • version string

    약관 버전입니다.

  • url string

    약관 전문이 들어있는 URL 입니다.

  • required boolean

    약관에 필수적으로 동의해야 하는지 여부입니다.

  • agreed boolean

    고객이 약관에 동의했는지 여부입니다.

미동의 약관 조회

GET /v1/brandpay/terms

customerKey에 해당하는 고객이 브랜드페이 사용 약관에 동의했는지 조회합니다. Basic 인증 방식을 사용합니다.

Query 파라미터

  • customerKey 필수 · string

    가맹점에서 만든 고객의 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -_=.@로 이루어진 1자 이상 50자 이하의 문자열이어야 합니다.

Response

성공

약관 조회 요청에 성공했다면 각 약관의 동의 여부와 약관 정보를 담은 Terms 객체가 배열로 돌아옵니다.

실패

약관 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request GET \
  --url 'https://api.tosspayments.com/v1/brandpay/terms?customerKey=c6thB674j9vCU4XsvcPk' \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
응답
[
  {
    "id": 1,
    "title": "브랜드페이 서비스 이용약관",
    "version": "1.0",
    "url": "https://pages.tosspayments.com/terms/brandpay/service",
    "required": true,
    "agreed": false
  },
  {
    "id": 2,
    "title": "전자금융거래 기본약관",
    "version": "1.0",
    "url": "https://pages.tosspayments.com/terms/user",
    "required": true,
    "agreed": false
  },
  {
    "id": 3,
    "title": "개인정보 수집 및 이용 동의",
    "version": "1.0",
    "url": "https://pages.tosspayments.com/terms/brandpay/privacy",
    "required": true,
    "agreed": false
  },
  {
    "id": 4,
    "title": "개인정보 제3자 제공 동의",
    "version": "1.0",
    "url": "https://pages.tosspayments.com/terms/brandpay/privacy3",
    "required": true,
    "agreed": false
  },
  {
    "id": 5,
    "title": "개인정보 제3자 제공 동의 (카드사)",
    "version": "1.0",
    "url": "https://pages.tosspayments.com/terms/brandpay/card-privacy3",
    "required": true,
    "agreed": false
  },
  {
    "id": 6,
    "title": "오픈뱅킹 이용약관 (은행)",
    "version": "1.0",
    "url": "https://pages.tosspayments.com/terms/brandpay/openbanking",
    "required": true,
    "agreed": false
  },
  {
    "id": 7,
    "title": "개인정보 제3자 제공 동의 (은행)",
    "version": "1.0",
    "url": "https://pages.tosspayments.com/terms/brandpay/openbanking-privacy3",
    "required": true,
    "agreed": false
  }
]

약관 동의

POST /v1/brandpay/terms/agree

동의가 필요한 약관 ID의 배열과 customerKey를 보내서 customerKey에 해당하는 고객의 약관 동의를 진행합니다. Basic 인증 방식을 사용합니다.

* 미동의 약관 조회 API 요청을 통해 동의해야 하는 약관 정보를 확인한 뒤 사용하세요.

Request Body 파라미터

  • customerKey 필수 · string

    가맹점에서 만든 고객의 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -_=.@로 이루어진 1자 이상 50자 이하의 문자열이어야 합니다.

  • termsId array

    약관 ID가 담긴 배열입니다.

Response

성공

약관 동의 요청에 성공했다면 임시 인증 코드(code)가 돌아옵니다. 이 값을 사용해서 Access Token 발급 API 요청을 할 수 있습니다.

인증에 대한 더 자세한 내용은 브랜드페이 인증 페이지를 참고하세요.

실패

약관 동의 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/brandpay/terms/agree \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"customerKey":"c6thB674j9vCU4XsvcPk","termsId":[1,2,3,4,5]}'
응답
{
    "code": "RnYX2w532omp6gDQgVNeyqAp"
}

AccessToken 객체

브랜드페이 API를 사용하기 위해 필요한 인증 토큰을 담고 있는 객체입니다.

객체 상세

  • accessToken string

    사용자에 할당된 Access Token 입니다. customerKey와 연결되어 있는 값으로 고객이 탈퇴하거나 Refresh Token으로 새로 발급받지 않는 한 변하지 않습니다.

  • tokenType string

    브랜드페이 API를 요청할 때 쓰는 인증 방식인 bearer가 고정값으로 돌아옵니다.

  • refreshToken string

    Access Token을 새로 발급 받을 때 사용할 토큰입니다.

  • expiresIn integer

    Access Token의 유효기간을 초 단위로 나타낸 값입니다. 30일로 설정되어 있습니다.

Access Token 발급

POST /v1/brandpay/authorizations/access-token

사용자를 식별하는 Access Token을 발급 받기 위한 요청입니다. Basic 인증 방식을 사용합니다.

약관 동의 API 실행 결과로 얻은 임시 인증 코드(code)를 이용해서 요청하세요.

Request Body 파라미터

  • grantType 필수 · string

    요청하는 token의 타입입니다. AuthorizationCodeRefreshToken 중 하나를 사용합니다. code를 사용해 Access Token을 처음으로 요청할 때는 AuthorizationCode를, refreshToken을 사용해 만료된 Access Token을 새로 요청할 때는 RefreshToken을 명시하세요.

  • customerKey 필수 · string

    가맹점에서 만든 고객의 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -_=.@로 이루어진 1자 이상 50자 이하의 문자열이어야 합니다.

  • code string

    grantType이 AuthorizationCode인 경우 필수입니다. 리다이렉트 URL의 쿼리 파라미터로 돌아온 임시 인증 코드 값을 넣어줍니다.

  • refreshToken string

    Access Token이 만료되어 새로 획득할 때 필수로 설정합니다. grantType을 RefreshToken으로 설정하고 함께 전달해야 합니다.

  • customerIdentity object

    인증을 위한 고객 정보입니다. 상점에서 가지고 있는 고객 정보를 사용해서 값을 채워주세요. 이 정보를 보내면 휴대폰 본인 인증 과정에서 입력해야 하는 정보가 미리 채워집니다. 상점에 가입한 고객과 브랜드페이 서비스에 가입한 고객이 같은지 인증하기 위해 이 정보와 본인 인증 결과로 받은 고객 정보가 일치하는지 비교합니다.

    • ci string

      고객의 연계 정보(CI) 값입니다.

    • mobilePhone string

      고객의 휴대폰 번호입니다.

    • name string

      고객 이름입니다.

    • rrn string

      고객의 주민번호 앞 7자리(생년월일+성별코드)입니다.

Response

성공

Access Token 발급 요청에 성공했다면 AccessToken 객체가 돌아옵니다. 발급된 Access Token을 사용해서 브랜드페이 API에 HTTP 요청을 보낼 수 있습니다.

실패

Access Token 발급 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/brandpay/authorizations/access-token \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"grantType":"AuthorizationCode","customerKey":"c6thB674j9vCU4XsvcPk","code":"RnYX2w532omp6gDQgVNeyqAp"}'
응답
{
  "accessToken": "Xy0E4Dv5qpMGjLJoQ1aVZ5449xB1P3w6KYe2RNgOWznZb7Bm",
  "refreshToken": "vG45eDbZnodP9BRQmyarYYdd2mMD2rJ07KzLNkE6AOMwXYWl",
  "tokenType": "bearer",
  "expiresIn": 2592000
}

결제 수단

결제 수단 API로 고객의 브랜드페이 결제 수단 정보를 조회하거나 삭제할 수 있습니다.

* 현재 결제 수단 등록은 브랜드페이 SDK 메서드를 통해 지원합니다.

BrandPayMethod 객체

고객을 특정하는 customerKey에 연결되어 있는 객체로, 해당 고객에게 등록되어 있는 전체 결제 수단 정보를 알려줍니다.

고객이 가장 최근에 사용했거나 등록한 결제 수단 정보도 제공합니다.

객체 상세

  • isIdentified boolean

    본인 인증 후 브랜드페이에 가입되어 있는지 여부입니다.

    브랜드페이 SDK를 통해 본인 인증을 했거나, Access Token 발급 API 요청 시 개인 식별 정보(customerIdentity) 객체의 값을 모두 채워서 인증이 진행됐을 때 true로 설정됩니다.

  • selectedMethodId string

    가장 최근에 등록했거나 사용한 결제 수단의 id 값입니다.

    * 전체 결제 수단의 등록 날짜와 최근 한 달 이내에 사용한 결제 수단의 사용일을 비교해 가장 최근에 등록했거나 사용한 결제 수단의 id가 내려갑니다. 등록한 결제 수단이 없다면 null이 내려갑니다.

  • cards array

    브랜드페이에 고객이 등록한 카드 정보가 배열로 들어옵니다. 아래 BrandPayCard 객체를 참고하세요.

  • accounts array

    브랜드페이에 고객이 등록한 계좌 정보가 배열로 들어옵니다. 아래 BrandPayBankAccount 객체를 참고하세요.

BrandPayCard 객체

고객이 결제 수단으로 등록한 카드 정보를 담고 있는 객체입니다.

객체 상세

  • id string

    결제 수단의 아이디입니다.

  • methodKey string

    결제 수단을 특정하는 키입니다. 자동 결제 API, 결제 수단 삭제 API 등 API를 사용할 때 고객이 등록해 둔 결제 수단을 특정하기 위해 사용합니다.

  • alias string

    고객이 직접 설정한 해당 결제 수단의 별명입니다.

    * 결제 수단의 별명 설정 및 변경은 SDK에서 제공하는 결제 관리 UI의 결제수단 관리에서 할 수 있습니다.

  • cardName string

    카드 이름입니다.

  • cardNumber string

    카드 번호입니다.

  • cardCompany string

    카드사 이름입니다.

  • companyCode string

    카드사를 특정하는 숫자 코드입니다. 카드사 코드에서 숫자 코드를 참고하세요.

  • issueCompany string

    카드 발급사 정보입니다.

  • ownerType string

    카드의 소유자 타입입니다. 개인법인 중 하나입니다.

  • cardType string

    카드 종류입니다. 신용체크기프트 중 하나입니다.

  • installmentMinimumAmount integer

    cardCompany에 해당하는 카드에서 할부가 가능한 최소 금액 정보입니다. 이 금액과 고객이 결제할 금액을 비교해서 할부 선택 UI를 보여줄 지 결정할 수 있습니다.

  • registeredAt string

    결제 수단을 등록한 날짜와 시간 정보입니다. ISO 8601 형식인 yyyy-MM-dd'T'HH:mm:ss±hh:mm으로 돌아옵니다. (e.g. 2022-01-01T00:00:00+09:00)

  • status string

    결제 수단 활성화 여부를 나타냅니다. 결제 수단을 조회할 때는 이 값이 ENABLED인 결제 수단만 돌아옵니다. 결제 수단을 삭제하면 이 값이 DISABLED로 변경됩니다.

    ENABLED: 결제 수단이 등록되어 사용할 수 있는 상태

    DISABLED: 결제 수단이 삭제되어 사용할 수 없는 상태

  • icon string

    카드사 아이콘 모양에 대한 정보입니다. 예를 들어 icn-bank-square-hyundaicard이면 현대카드 은행 아이콘입니다.

    icn-bank-square-에 카드사 이름이 조합되어 있습니다.

  • iconUrl string

    카드사 아이콘 이미지 URL입니다. 이 값을 이미지 주소로 사용하면 화면에 카드사 아이콘을 보여줄 수 있습니다.

  • cardImgUrl string

    카드 실물 이미지 URL입니다. 이 값을 이미지 주소로 사용하면 화면에 카드 실물 이미지를 보여줄 수 있습니다.

  • color object

    카드사 아이콘의 색상 정보입니다. 아이콘 이미지와 함께 카드 결제 수단 UI를 직접 만들 때 사용할 수 있습니다.

    • background string

      카드사 아이콘의 배경색입니다.

    • text string

      카드사 아이콘의 텍스트 색입니다.

BrandPayBankAccount 객체

고객이 결제 수단으로 등록한 계좌 정보를 담고 있는 객체입니다.

객체 상세

  • id string

    결제 수단의 ID입니다. SDK를 사용해서 결제할 때 이 값을 사용합니다.

  • methodKey string

    결제 수단을 특정하는 키입니다. 자동 결제 API, 결제 수단 삭제 API 등 API를 사용할 때 고객이 등록해 둔 결제 수단을 특정하기 위해 사용합니다.

  • accountName string

    계좌 이름입니다.

  • accountNumber string

    계좌 번호입니다.

  • alias string

    고객이 직접 설정한 해당 결제 수단의 별명입니다.

    * 결제 수단의 별명 설정 및 변경은 SDK에서 제공하는 결제 관리 UI의 결제수단 관리에서 할 수 있습니다.

  • bank string

    은행 이름입니다.

  • bankCode string

    은행을 특정하는 숫자 코드입니다. 은행 코드를 참고하세요.

  • icon string

    은행 아이콘 모양에 대한 정보입니다. 예를 들어 icn-bank-kb 이면 KB국민은행 아이콘입니다.

    NORMAL: 정사각형 형태의 은행 아이콘입니다.(96x96)

    SQUARE: 직사각형 형태의 은행 아이콘입니다. (160x256)

  • iconUrl string

    은행 아이콘 이미지 URL입니다. 이 값을 이미지 주소로 사용해서 화면에 은행 아이콘을 보여줄 수 있습니다.

  • registeredAt string

    결제 수단을 등록한 날짜와 시간 정보입니다. ISO 8601 형식인 yyyy-MM-dd'T'HH:mm:ss±hh:mm으로 돌아옵니다. (e.g. 2022-01-01T00:00:00+09:00)

  • status string

    결제 수단 활성화 여부를 나타냅니다. 결제 수단을 조회할 때는 이 값이 ENABLED인 결제 수단만 돌아옵니다. 결제 수단을 삭제하면 이 값이 DISABLED로 변경됩니다.

    ENABLED: 결제 수단이 등록되어 사용할 수 있는 상태

    DISABLED: 결제 수단이 삭제되어 사용할 수 없는 상태

  • color object

    은행 아이콘의 색상 정보입니다. 아이콘 이미지와 함께 계좌 결제 수단 UI를 직접 만들 때 사용할 수 있습니다.

    • background string

      은행 아이콘의 배경색입니다.

    • text string

      은행 아이콘의 텍스트 색입니다.

AccessToken을 이용한 결제 수단 조회

GET /v1/brandpay/payments/methods

사용자가 등록한 결제 수단을 조회합니다. Bearer 인증 방식을 사용합니다.

* AccessToken이 이미 발급되어 사용자에게 할당되어 있다면 API를 호출했을 때 바로 결제 수단을 조회할 수 있습니다.

Response

성공

결제 수단 조회 요청에 성공했다면 BrandPayMethod 객체가 돌아옵니다.

실패

결제 수단 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request GET \
  --url https://api.tosspayments.com/v1/brandpay/payments/methods \
  --header 'Authorization: Bearer Xy0E4Dv5qpMGjLJoQ1aVZ5449xB1P3w6KYe2RNgOWznZb7Bm'
응답
{
  "cards": [
    {
      "id": "m_Zzorzo1AJbaD78l5",
      "alias": "카드 별칭",
      "methodKey": "pa90ZoyegEOALnQvDd2VJ5vKkpRyN3Mj7X41mNW5kzKbwG6J",
      "cardName": "현대비자플래티늄",
      "cardNumber": "4330********1234",
      "cardCompany": "현대",
      "companyCode": "61",
      "issueCompany": "현대",
      "ownerType": "개인",
      "cardType": "신용",
      "installmentMinimumAmount": 10000,
      "registeredAt": "2022-06-07T18:37:04+09:00",
      "status": "ENABLED",
      "icon": "icn-bank-square-hyundaicard",
      "iconUrl": "https://static.toss.im/icons/png/4x/icn-bank-square-hyundaicard.png",
      "cardImgUrl": "",
      "color": {
        "background": "#3C3C42",
        "text": "#FFFFFF"
      }
    }
  ],
  "accounts": [
    {
      "id": "b_aPz8LBLadxD6WVy4",
      "methodKey": "b6vdX0wJDpj5mBZ1gQ4YVXe9DYzQparl2KPoqNbMGOkn9EW7y",
      "accountName": "신한은행 계좌",
      "accountNumber": "123***7890",
      "alias": "내 계좌",
      "bank": "신한",
      "bankCode": "88",
      "icon": "",
      "iconUrl": "",
      "registeredAt": "2022-06-07T10:00:43.838Z",
      "status": "DISABLED",
      "color": {
        "background": "#006AB6",
        "text": "#FFFFFF"
      }
    }
  ],
  "isIdentified": true,
  "selectedMethodId": "m_Zzorzo1AJbaD78l5"
}

SecretKey를 이용한 결제 수단 조회

GET /v1/brandpay/payments/methods/{customerKey}

사용자가 등록한 결제 수단을 조회합니다. Basic 인증 방식을 사용합니다.

Path 파라미터

  • customerKey 필수 · string

    가맹점에서 만든 고객의 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -_=.@로 이루어진 1자 이상 50자 이하의 문자열이어야 합니다.

Response

성공

결제 수단 조회 요청에 성공했다면 BrandPayMethod 객체가 돌아옵니다.

실패

결제 수단 조회 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request GET \
  --url https://api.tosspayments.com/v1/brandpay/payments/methods/{customerKey} \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
응답
{
  "cards": [
    {
      "id": "m_Zzorzo1AJbaD78l5",
      "alias": "카드 별칭",
      "methodKey": "pa90ZoyegEOALnQvDd2VJ5vKkpRyN3Mj7X41mNW5kzKbwG6J",
      "cardName": "현대비자플래티늄",
      "cardNumber": "4330********1234",
      "cardCompany": "현대",
      "companyCode": "61",
      "issueCompany": "현대",
      "ownerType": "개인",
      "cardType": "신용",
      "installmentMinimumAmount": 10000,
      "registeredAt": "2022-06-07T18:37:04+09:00",
      "status": "ENABLED",
      "icon": "icn-bank-square-hyundaicard",
      "iconUrl": "https://static.toss.im/icons/png/4x/icn-bank-square-hyundaicard.png",
      "cardImgUrl": "",
      "color": {
        "background": "#3C3C42",
        "text": "#FFFFFF"
      }
    }
  ],
  "accounts": [
    {
      "id": "b_aPz8LBLadxD6WVy4",
      "methodKey": "b6vdX0wJDpj5mBZ1gQ4YVXe9DYzQparl2KPoqNbMGOkn9EW7y",
      "accountName": "신한은행 계좌",
      "accountNumber": "123***7890",
      "alias": "내 계좌",
      "bank": "신한",
      "bankCode": "88",
      "icon": "",
      "iconUrl": "",
      "registeredAt": "2022-06-07T10:00:43.838Z",
      "status": "DISABLED",
      "color": {
        "background": "#006AB6",
        "text": "#FFFFFF"
      }
    }
  ],
  "isIdentified": true,
  "selectedMethodId": "m_Zzorzo1AJbaD78l5"
}

카드 결제 수단 삭제

POST /v1/brandpay/payments/methods/card/remove

methodKey를 이용해서 결제 수단으로 등록되어 있는 카드를 삭제합니다. Bearer 인증 방식을 사용합니다.

Request Body 파라미터

  • methodKey 필수 · string

    결제 수단을 특정하는 키입니다.

Response

성공

카드 삭제 요청에 성공했다면 삭제된 카드 객체가 돌아옵니다. 돌아온 결제 수단의 status 값은 DISABLED 입니다.

실패

카드 삭제 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/brandpay/payments/methods/card/remove \
  --header 'Authorization: Bearer Xy0E4Dv5qpMGjLJoQ1aVZ5449xB1P3w6KYe2RNgOWznZb7Bm' \
  --header 'Content-Type: application/json' \
  --data '{"methodKey":"pa90ZoyegEOALnQvDd2VJ5vKkpRyN3Mj7X41mNW5kzKbwG6J"}'
응답
{
  "id": "m_Zzorzo1AJbaD78l5",
  "alias": "카드 별칭",
  "methodKey": "pa90ZoyegEOALnQvDd2VJ5vKkpRyN3Mj7X41mNW5kzKbwG6J",
  "cardName": "현대비자플래티늄",
  "cardNumber": "4330********1234",
  "cardCompany": "현대",
  "companyCode": "61",
  "issueCompany": "현대",
  "ownerType": "개인",
  "cardType": "신용",
  "installmentMinimumAmount": 10000,
  "registeredAt": "2022-06-07T18:37:04+09:00",
  "status": "DISABLED",
  "icon": "icn-bank-square-hyundaicard",
  "iconUrl": "https://static.toss.im/icons/png/4x/icn-bank-square-hyundaicard.png",
  "cardImgUrl": "",
  "color": {
    "background": "#3C3C42",
    "text": "#FFFFFF"
  }
}

계좌 결제 수단 삭제

POST /v1/brandpay/payments/methods/account/remove

methodKey를 이용해서 결제 수단으로 등록되어 있는 계좌를 삭제합니다. 삭제된 계좌 정보를 담은 객체가 돌아옵니다. Bearer 인증 방식을 사용합니다.

Request Body 파라미터

  • methodKey 필수 · string

    결제 수단을 특정하는 키입니다.

Response

성공

계좌 삭제 요청에 성공했다면 삭제된 계좌 객체가 돌아옵니다. 돌아온 결제 수단의 status 값은 DISABLED 입니다.

실패

계좌 삭제 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/brandpay/payments/methods/account/remove \
  --header 'Authorization: Bearer Xy0E4Dv5qpMGjLJoQ1aVZ5449xB1P3w6KYe2RNgOWznZb7Bm' \
  --header 'Content-Type: application/json' \
  --data '{"methodKey":"b6vdX0wJDpj5mBZ1gQ4YVXe9DYzQparl2KPoqNbMGOkn9EW7y"}'
응답
{
  "id": "b_aPz8LBLadxD6WVy4",
  "methodKey": "b6vdX0wJDpj5mBZ1gQ4YVXe9DYzQparl2KPoqNbMGOkn9EW7y",
  "accountName": "신한은행 계좌",
  "accountNumber": "123***7890",
  "alias": "내 계좌",
  "bank": "신한",
  "bankCode": "88",
  "icon": "",
  "iconUrl": "",
  "registeredAt": "2022-06-07T10:00:43.838Z",
  "status": "DISABLED",
  "color": {
    "background": "#006AB6",
    "text": "#FFFFFF"
  }
}

결제

결제 승인

POST /v1/brandpay/payments/confirm

paymentKey에 해당하는 결제를 인증하고 승인합니다. Basic 인증 방식을 사용합니다.

* 결제 승인 엔드포인트가 /v1/brandpay/payments/{paymentKey}에서 /v1/brandpay/payments/confirm으로 변경되었습니다. 이전 엔드포인트는 사용을 권장하지 않습니다.

Request Body 파라미터

  • paymentKey 필수 · string

    결제 건에 대한 고유한 키 값입니다.

  • amount 필수 · integer

    결제할 금액입니다.

  • customerKey 필수 · string

    가맹점에서 만든 고객의 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -_=.@로 이루어진 1자 이상 50자 이하의 문자열이어야 합니다.

  • orderId 필수 · string

    가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -_=로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

Response

성공

결제 승인 요청에 성공했다면 Payment 객체가 돌아옵니다.

실패

결제 승인 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/brandpay/payments/confirm \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"paymentKey":"5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6","amount":"10000","customerKey":"c6thB674j9vCU4XsvcPk","orderId":"a4CWyWY5m89PNh7xJwhk1"}'
응답
{
  "mId": "tosspayments",
  "version": "2022-06-07",
  "paymentKey": "lOR1ZwdkQD5GePWvyJnrK1jPbp0qR3gLzN97EoqYA60XKx4a",
  "status": "DONE",
  "transactionKey": "AD441DDE040217780E2F7BFAAEF74566",
  "lastTransactionKey": "AD441DDE040217780E2F7BFAAEF74566",
  "orderId": "eQ2W9gCBN7Xu4l2vEUUC1",
  "orderName": "토스 티셔츠 외 2건",
  "requestedAt": "2022-06-07T17:20:48+09:00",
  "approvedAt": "2022-06-07T17:21:21+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": {
    "company": "현대",
    "number": "433012******1234",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://dashboard.tosspayments.com/sales-slip?transactionId=OX1cpNJJCl0tRRIBUqVS11Lx7er33DzBXIg68Xpie%2B%2BoG3%2Fr8DtjBp0gmBV&ref=PX",
    "amount": 10000
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "BRANDPAY",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "isPartialCancelable": true,
  "receipt": {
    "url": "https://dashboard.tosspayments.com/sales-slip?transactionId=OX1cpNJJCl0tRRIBUqVS11Lx7er33DzBXIg68Xpie%2B%2BoG3%2Fr8DtjBp0gmBV&ref=PX"
  },
  "currency": "KRW",
  "totalAmount": 10000,
  "balanceAmount": 10000,
  "suppliedAmount": 9091,
  "vat": 909,
  "taxFreeAmount": 0,
  "method": "카드"
}

자동 결제 실행

POST /v1/brandpay/payments

등록된 결제 수단 중 methodKey에 해당하는 결제 수단으로 상점에서 원하는 시점에 자동 결제를 실행합니다. Basic 인증 방식을 사용합니다.

Request Body 파라미터

  • customerKey 필수 · string

    가맹점에서 만든 고객의 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -_=.@로 이루어진 1자 이상 50자 이하의 문자열이어야 합니다.

  • methodKey 필수 · string

    결제 수단 키 입니다.

  • amount 필수 · integer

    결제할 금액입니다.

  • orderId 필수 · string

    가맹점에서 주문건에 대해 발급한 고유 ID입니다. 영문 대소문자, 숫자, 특수문자 -_=로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다.

  • orderName 필수 · string

    결제에 대한 주문명입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최소 1글자 이상 100글자 이하여야 합니다.

  • cardInstallmentPlan integer

    할부 개월 수입니다.

  • cashReceipt object

    현금영수증 정보입니다.

    • type 필수 · string

      현금영수증의 종류입니다. 소득공제지출증빙 중 하나의 값입니다.

    • registrationNumberType string

      현금영수증 번호 타입입니다. 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호 중 하나를 선택할 수 있습니다.

      MOBILE: 휴대폰 번호

      BUSINESS_REGISTRATION: 사업자등록번호

      CASH_RECEIPT_CARD: 현금영수증 카드 번호

    • registrationNumber 필수 · string

      현금영수증 발급을 위한 개인 식별 번호 정보입니다. 휴대폰 번호, 사업자등록번호, 현금영수증 카드 번호를 입력할 수 있습니다.

  • cultureExpense boolean

    문화비로 지출했는지 여부입니다. (도서구입, 공연 티켓, 박물관·미술관 입장권 등)

  • customerEmail string

    고객의 이메일 주소입니다. 결제 결과를 알려줄 때 사용합니다.

  • discountCode string

    즉시 할인 코드(카드사 고유 번호)로 결제할 때 함께 넘겨야 하는 값입니다.

  • shippingAddress string

    고객의 배송지 주소입니다. 부정거래탐지시스템(FDS, Fraud Detection System, 거래 정보와 고객 정보, 평소 거래 패턴 등을 분석해서 의심되는 전자금융거래를 탐지하고 차단하는 기술)에 사용할 수 있습니다.

  • taxFreeAmount integer

    전체 결제 금액 중 면세 금액입니다. 값이 0으로 돌아왔다면 전체 결제 금액이 과세 대상입니다.

    *일반 상점일 때는 모든 결제 금액이 과세에 해당하기 때문에 0이 돌아옵니다. 면세 상점, 복합 과세 상점일 때만 면세 금액이 돌아옵니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.

  • useCardPoint boolean

    카드로 결제할 때 설정하는 카드사 포인트 사용 여부입니다. 값을 주지 않으면 사용자가 카드사 포인트 사용 여부를 결정할 수 있습니다.

    이 값을 true로 주면 카드사 포인트 사용이 체크된 상태로 결제창이 열립니다. 이 값을 false로 주면 사용자는 카드사 포인트를 사용할 수 없습니다.

Response

성공

자동 결제 실행 요청에 성공했다면 Payment 객체가 돌아옵니다.

실패

자동 결제 실행 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/brandpay/payments \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --data '{"customerKey":"c6thB674j9vCU4XsvcPk","methodKey":"pa90ZoyegEOALnQvDd2VJ5vKkpRyN3Mj7X41mNW5kzKbwG6J","amount":"10000","orderId":"eQ2W9gCBN7Xu4l2vEUUC1","orderName":"토스 티셔츠 외 2건"}'
응답
{
  "mId": "tosspayments",
  "version": "2022-06-07",
  "paymentKey": "lOR1ZwdkQD5GePWvyJnrK1jPbp0qR3gLzN97EoqYA60XKx4a",
  "status": "DONE",
  "transactionKey": "AD441DDE040217780E2F7BFAAEF74566",
  "lastTransactionKey": "AD441DDE040217780E2F7BFAAEF74566",
  "orderId": "eQ2W9gCBN7Xu4l2vEUUC1",
  "orderName": "토스 티셔츠 외 2건",
  "requestedAt": "2022-06-07T17:20:48+09:00",
  "approvedAt": "2022-06-07T17:21:21+09:00",
  "useEscrow": false,
  "cultureExpense": false,
  "card": {
    "company": "현대",
    "number": "433012******1234",
    "installmentPlanMonths": 0,
    "isInterestFree": false,
    "interestPayer": null,
    "approveNo": "00000000",
    "useCardPoint": false,
    "cardType": "신용",
    "ownerType": "개인",
    "acquireStatus": "READY",
    "receiptUrl": "https://dashboard.tosspayments.com/sales-slip?transactionId=OX1cpNJJCl0tRRIBUqVS11Lx7er33DzBXIg68Xpie%2B%2BoG3%2Fr8DtjBp0gmBV&ref=PX",
    "amount": 10000
  },
  "virtualAccount": null,
  "transfer": null,
  "mobilePhone": null,
  "giftCertificate": null,
  "cashReceipt": null,
  "discount": null,
  "cancels": null,
  "secret": null,
  "type": "BRANDPAY",
  "easyPay": null,
  "country": "KR",
  "failure": null,
  "isPartialCancelable": true,
  "receipt": {
    "url": "https://dashboard.tosspayments.com/sales-slip?transactionId=OX1cpNJJCl0tRRIBUqVS11Lx7er33DzBXIg68Xpie%2B%2BoG3%2Fr8DtjBp0gmBV&ref=PX"
  },
  "currency": "KRW",
  "totalAmount": 10000,
  "balanceAmount": 10000,
  "suppliedAmount": 9091,
  "vat": 909,
  "taxFreeAmount": 0,
  "method": "카드"
}

결제 취소

일반 결제의 결제 취소 API를 사용합니다.

회원 관리

회원 탈퇴 처리하기

POST /v1/brandpay/customers/remove

회원 탈퇴 즉시 전체 결제 수단이 삭제됩니다. Bearer 인증 방식을 사용합니다.

Response

성공

회원 탈퇴 처리 요청에 성공했다면 삭제된 회원의 고유 ID인 customerKey와 탈퇴 성공 여부를 나타내는 success가 돌아옵니다.

실패

회원 탈퇴 처리 요청에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request POST \
  --url https://api.tosspayments.com/v1/brandpay/customers/remove \
  --header 'Authorization: Bearer Xy0E4Dv5qpMGjLJoQ1aVZ5449xB1P3w6KYe2RNgOWznZb7Bm'
응답
{
  "customerKey": "c6thB674j9vCU4XsvcPk",
  "success": true
}

카드 혜택

카드 혜택 API로 카드사별 즉시 할인, 무이자, 카드 포인트 프로모션 정보를 고객에게 제공할 수 있습니다.

BrandPayCardPromotion 객체

브랜드페이 카드 프로모션 정보를 담고 있는 객체입니다.

객체 상세

  • discountCards array

    즉시 할인 정보입니다.

    • cardCompany string

      즉시 할인을 진행하는 카드사 이름입니다.

    • companyCode string

      즉시 할인을 진행하는 카드사 코드입니다.

    • discountCode string

      즉시 할인 코드입니다.

    • discountAmount number

      즉시 할인 금액입니다.

    • minimumPaymentAmount number

      즉시 할인을 적용할 수 있는 최소 결제 금액입니다.

    • maximumPaymentAmount number

      즉시 할인을 적용할 수 있는 최대 결제 금액입니다.

    • dueDate string

      즉시 할인 프로모션을 마치는 시점입니다. yyyy-mm-dd 형태입니다.

    • balance number

      즉시 할인이 가능한 남은 잔액입니다.

  • interestFreeCards array

    무이자 할부 정보입니다.

    • cardCompany string

      무이자 할부를 적용할 수 있는 카드사 이름입니다.

    • companyCode string

      무이자 할부를 적용할 수 있는 카드사 코드입니다.

    • minimumPaymentAmount number

      무이자 할부를 적용할 수 있는 최소 결제 금액입니다.

    • installmentFreeMonths array

      무이자 할부를 적용할 수 있는 개월 수 입니다.

    • dueDate string

      무이자 할부 프로모션을 마치는 시점입니다. yyyy-mm-dd 형태입니다.

  • pointCards array

    카드 포인트 정보입니다.

    • cardCompany string

      카드 포인트를 적용할 수 있는 카드사 이름입니다.

    • companyCode string

      카드 포인트를 적용할 수 있는 카드사 코드입니다.

    • minimumPaymentAmount integer

      카드 포인트를 적용할 수 있는 최소 결제 금액입니다.

    • dueDate string

      카드 포인트 프로모션을 마치는 시점입니다. yyyy-mm-dd 형태입니다.

카드 혜택 조회

GET /v1/brandpay/promotions/card

카드사별 혜택 정보를 조회합니다. 즉시 할인, 무이자, 카드 포인트 정보가 내려갑니다. Basic 인증 방식을 사용합니다.

Response

성공

카드 혜택 조회에 성공했다면 BrandpayCardPromotions 객체가 돌아옵니다.

실패

카드 혜택 조회에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

요청
curl --request GET \
  --url https://api.tosspayments.com/v1/brandpay/promotions/card \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
응답
{
  "discountCards": [
    {
      "cardCompany": "롯데",
      "companyCode": "71",
      "discountCode": "12860",
      "dueDate": "2022-04-30",
      "minimumPaymentAmount": 1000,
      "maximumPaymentAmount": 99999999,
      "balance": 1000000,
      "discountAmount": 500
    },
    {
      "cardCompany": "BC",
      "companyCode": "31",
      "discountCode": "12861",
      "dueDate": "2022-04-30",
      "minimumPaymentAmount": 2000,
      "maximumPaymentAmount": 99999999,
      "balance": 1000000,
      "discountAmount": 600
    },
    {
      "cardCompany": "삼성",
      "companyCode": "51",
      "discountCode": "12862",
      "dueDate": "2022-04-30",
      "minimumPaymentAmount": 5000,
      "maximumPaymentAmount": 500000,
      "balance": 1000000,
      "discountAmount": 1000
    },
    {
      "cardCompany": "현대",
      "companyCode": "61",
      "discountCode": "12863",
      "dueDate": "2022-04-30",
      "minimumPaymentAmount": 10000,
      "maximumPaymentAmount": 888888888,
      "balance": 1000000,
      "discountAmount": 5000
    }
  ],
  "interestFreeCards": [
    {
      "cardCompany": "국민",
      "companyCode": "11",
      "dueDate": "2022-06-30",
      "installmentFreeMonths": [2, 3, 4, 5, 6, 7],
      "minimumPaymentAmount": 50000
    },
    {
      "cardCompany": "BC",
      "companyCode": "31",
      "dueDate": "2022-12-31",
      "installmentFreeMonths": [2, 3, 4, 5, 6, 7],
      "minimumPaymentAmount": 50000
    },
    {
      "cardCompany": "전북",
      "companyCode": "35",
      "dueDate": "2022-07-31",
      "installmentFreeMonths": [2, 3, 4, 5],
      "minimumPaymentAmount": 50000
    },
    {
      "cardCompany": "신한",
      "companyCode": "41",
      "dueDate": "2022-06-30",
      "installmentFreeMonths": [2, 3, 4, 5, 6, 7],
      "minimumPaymentAmount": 50000
    },
    {
      "cardCompany": "광주",
      "companyCode": "46",
      "dueDate": "2022-12-31",
      "installmentFreeMonths": [2, 3, 4, 5, 6, 7],
      "minimumPaymentAmount": 50000
    },
    {
      "cardCompany": "롯데",
      "companyCode": "71",
      "dueDate": "2022-06-30",
      "installmentFreeMonths": [2, 3, 4],
      "minimumPaymentAmount": 50000
    },
    {
      "cardCompany": "하나",
      "companyCode": "21",
      "dueDate": "2022-04-30",
      "installmentFreeMonths": [2, 3, 4, 5, 6, 7, 8],
      "minimumPaymentAmount": 50000
    },
    {
      "cardCompany": "농협",
      "companyCode": "91",
      "dueDate": "2022-04-30",
      "installmentFreeMonths": [2, 3, 4, 5, 6, 7, 8],
      "minimumPaymentAmount": 50000
    },
    {
      "cardCompany": "현대",
      "companyCode": "61",
      "dueDate": "2022-04-30",
      "installmentFreeMonths": [2, 3, 4, 5, 6, 7],
      "minimumPaymentAmount": 10000
    },
    {
      "cardCompany": "삼성",
      "companyCode": "51",
      "dueDate": "2022-04-30",
      "installmentFreeMonths": [2, 3, 4, 5, 6],
      "minimumPaymentAmount": 50000
    },
    {
      "cardCompany": "우리",
      "companyCode": "33",
      "dueDate": "2022-12-31",
      "installmentFreeMonths": [2, 3, 4, 5, 6, 7],
      "minimumPaymentAmount": 50000
    }
  ],
  "pointCards": [
    {
      "cardCompany": "우리",
      "companyCode": "33",
      "dueDate": "2022-04-30",
      "minimumPaymentAmount": 1000
    },
    {
      "cardCompany": "농협",
      "companyCode": "91",
      "dueDate": "2022-04-30",
      "minimumPaymentAmount": 2000
    },
    {
      "cardCompany": "삼성",
      "companyCode": "51",
      "dueDate": "2022-04-30",
      "minimumPaymentAmount": 3000
    },
    {
      "cardCompany": "현대",
      "companyCode": "61",
      "dueDate": "2022-04-30",
      "minimumPaymentAmount": 4000
    },
    {
      "cardCompany": "롯데",
      "companyCode": "71",
      "dueDate": "2022-04-30",
      "minimumPaymentAmount": 5000
    }
  ]
}