프로모션(토스 포인트)

프로모션 리워드 지급 키 생성하기

post

이 API는 파트너 앱이 토스 사용자에게 토스 포인트를 지급하기 위한 키를 발급해줘요.

비즈니스 오류 코드

아래 오류는 HTTP 200과 resultType: FAIL로 응답해요.

errorCode

설명

4095

요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.

요청 한도: 앱당 분당 3,000회

Authorizations

mutualTLS

파트너에게 발급된 클라이언트 인증서 기반 mTLS 인증이에요. 인증서의 CN으로 미니앱을 식별해요. 인증서 발급·관리 방법은 서버 API 이용하기 문서를 참고하세요.

Responses

200

프로모션 리워드 지급 키 생성에 성공했어요

application/json

400

요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.

application/json

500

분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.

application/json

post/api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key

POST /api-partner/v1/apps-in-toss/promotion/execute-promotion/get-key HTTP/1.1
Host: apps-in-toss-api.toss.im

{
  "resultType": "SUCCESS",
  "success": {
    "key": "AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs="
  }
}

프로모션 리워드 지급하기

post

이 API는 파트너 앱이 토스 유저에게 토스 포인트를 지급할 수 있도록 해줘요

비즈니스 오류 코드

아래 오류는 HTTP 200과 resultType: FAIL로 응답해요.

errorCode

설명

4000

잘못된 요청입니다.

4100

프로모션 정보를 찾을 수 없어요

4108

프로모션이 승인되지 않았어요

4109

프로모션이 실행중이 아니에요

4114

프로모션에 설정된 1회 지급 금액을 초과해서 지급할 수 없습니다.

4112

프로모션 머니가 부족해요

4105

프로모션이 종료되어 있어요

4113

이미 지급/회수된 내역이에요

4110

리워드를 지급/회수할 수 없어요

4034

워크스페이스가 없거나 워크스페이스에 접근할 수 있는 권한이 없어요

4010

인증 정보를 찾을 수 없어요.

4095

요청 한도를 초과했습니다. 잠시 후 다시 시도해주세요.

요청 한도: 앱당 분당 3,000회, 사용자당 분당 20회

Authorizations

mutualTLS

Header parameters

x-toss-user-keystringOptional

사용자를 인증하기 위한 키예요. 사용자 정보 받기 API를 통해 획득할 수 있어요

Example: 12345678

x-anon-keystringOptional

사용자를 인증하기 위한 키예요. 미니앱 SDK의 User.getAnonymousKey 함수로 발급받을 수 있어요

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

프로모션 리워드 지급 요청이에요.

amountinteger · int64Required

토스 유저에게 지급할 프로모션 금액이에요

Example: 1000

keystringRequired

프로모션 리워드 지급 키 생성하기 API를 통해 발급받은 리워드 지급 키예요

Example: AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs=

promotionCodestringRequired

콘솔을 통해 생성된 프로모션의 프로모션 코드예요

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

Responses

200

성공적으로 토스유저에게 토스 포인트를 지급했어요

application/json

400

요청 본문이 형식에 맞지 않아요. error.data.errorDetails에서 필드별 상세를 확인하세요.

application/json

500

분류되지 않은 서버 오류예요. 계속 실패하면 파트너 지원 채널로 문의해 주세요.

application/json

post/api-partner/v1/apps-in-toss/promotion/execute-promotion

POST /api-partner/v1/apps-in-toss/promotion/execute-promotion HTTP/1.1
Host: apps-in-toss-api.toss.im
x-toss-user-key: {userKey}
Content-Type: application/json

{
  "promotionCode": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "key": "AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs=",
  "amount": 1000
}

{
  "resultType": "SUCCESS",
  "success": {
    "key": "AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs="
  }
}