Promotion (Toss Points)

Create a promotion reward payout key

post

This API issues a key for partner apps to pay out Toss Points to Toss users.

Business error code

The errors below are returned with HTTP 200 and resultType: FAIL.

errorCode	Description
4095	Request limit exceeded. Please try again later.

Request limit: 3,000 times per minute per app

Authorizations

mutualTLS

This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the Use the server API document for how to issue and manage certificates.

Responses

200

Successfully generated a promotion reward payout key

application/json

or

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

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="
  }
}

Pay out promotion rewards

post

This API lets partner apps grant Toss Points to Toss users

Business error code

The errors below are returned with HTTP 200 and resultType: FAIL.

errorCode	Description
4000	Invalid request.
4100	Promotion information not found
4108	The promotion has not been approved
4109	The promotion is not running
4114	You cannot pay out more than the one-time payout amount set for the promotion.
4112	Not enough promotion money
4105	The promotion has ended
4113	This has already been paid out/reclaimed
4110	Rewards cannot be paid out/reclaimed
4034	There is no workspace, or you don't have permission to access the workspace
4010	Authentication information could not be found.
4095	Request limit exceeded. Please try again later.

Request limit: 3,000 per minute per app, 20 per minute per user

Authorizations

mutualTLS

This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the Use the server API document for how to issue and manage certificates.

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is a promotion reward payout request.

amountinteger · int64Required

This is the promotion amount to be paid to Toss users.

Example: 1000

keystringRequired

This is the reward payout key issued through the Create Promotion Reward Payout Key API.

Example: AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs=

promotionCodestringRequired

This is the promotion code for the promotion created through the console.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

Responses

200

Successfully paid Toss Points to the Toss user

application/json

or

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

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="
  }
}

Check promotion Toss Points payout results

post

This API lets partner apps query the Toss Points paid out to Toss users

Business error code

The errors below are returned with HTTP 200 and resultType: FAIL.

errorCode	Description
4000	Invalid request.
4100	Promotion information not found
4111	No reward payout history found
4010	Authentication information could not be found.
4095	Request limit exceeded. Please try again later.

Request limit: 3,000 times per minute per app

Authorizations

mutualTLS

This is client-certificate-based mTLS authentication issued to the partner. The mini app is identified by the certificate's CN. Refer to the Use the server API document for how to issue and manage certificates.

Header parameters

x-toss-user-keystringOptional

It's a key for authenticating users. It can be obtained through the Get user information API

Example: 12345678

x-anon-keystringOptional

It's a key for authenticating users. You can issue it with the User.getAnonymousKey function in the mini app SDK

Example: kQ7pL2mZxN9wRt5vB8yD3jF6cA1

Body

This is a request to retrieve promotion execution results.

keystringRequired

This is the reward payout key issued through the Create Promotion Reward Payout Key API.

Example: AwQqk3XyZpLm9vT2sYbN7cQmR1F5oGxU8dK0hVn6ePs=

promotionCodestringRequired

This is the promotion code for the promotion created through the console.

Example: 01ARZ3NDEKTSV4RRFFQ69G5FAV

Responses

200

Successfully retrieved the promotion payout result

application/json

or

400

The request body is not in the correct format. Check the field-by-field details in error.data.errorDetails.

application/json

500

This is an unclassified server error. If it keeps failing, please contact the partner support channel.

application/json

post/api-partner/v1/apps-in-toss/promotion/execution-result

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

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

{
  "resultType": "SUCCESS",
  "success": "SUCCESS"
}