Send payouts to your sellers
Make payouts to your sellers with Toss Payments. For open market merchants who have multiple sellers. Use the payout service to manage sellers and effectively handle your cash flow.
Encryption security mode
Toss Payments makes payment to your sellers during payout. Since the sellers are not directly in contract with Toss Payments, payouts require a higher level of security.
All payout API POST requests with a request body must be encrypted. Use the Toss Payments security key to encrypt the API request into JWE. Encrypted requests also return encrypted responses, that can be decrypted with the same security key.
Encryption is required for seller registration, seller updates, and payout requests.
Security key
Retrieve your security key from the API Key menu of the Toss Payments Development Center.
The security key is a hexadecimal string 64 characters long. Before encryption, decode security key into bytes as shown below.
Encrypting requests into JWE
Refer to the sample code below to create the JWE header and encrypt the request body. The below four headers are required as JWE headers.
alg: Key encryption algorithm. Set todirsince the Toss Payments security key is not encrypted.enc: Encryption algorithm for JWE. Set toA256GCM.iat(issued at): Time the request body was created. Useyyyy-MM-dd'T'HH:mm:ss±hh:mmISO 8601 format.nonce: Number only used once to ensure session's uniqueness. Use a random or pseudo-random number such as a UUID.
Decrypting JWE responses
All encrypted requests will return an encrypted response. Encrypted API responses can be decrypted with the same security key used for encryption.
Make a payout
1. Register your seller
Register a seller you want to make a payout to using the below API.
Request body parameters
- refSellerId 필수 · string
Unique identifier for your seller that can be used during payouts. The identifier may not be reused, even after the seller has been deleted.
- businessType 필수 · string
Business type of the seller. Use
INDIVIDUAL,INDIVIDUAL_BUSINESS, orCORPORATE. - company object
Seller information when the business type is
INDIVIDUAL_BUSINESSorCORPORATE. - name 필수 · string
Name of the business.
- representativeName 필수 · string
Name of the business representative.
- businessRegistrationNumber 필수 · string
The business registration number. Use a 10 digit number without any special characters.
- email 필수 · string
The email address of the business.
- phone 필수 · string
The business's phone number. The seller will receive customer identification and KYC notifications at this number through text. Use digits without any special characters.
- individual object
Seller information when the business type is
INDIVIDUAL. - name 필수 · string
The individual's name.
- email 필수 · string
The individual's email address.
- phone 필수 · string
The individual's phone number. The seller will receive customer identification and KYC notifications at this number through text. Use digits without any special characters.
- account 필수 · object
Seller's bank account information.
- bankCode 필수 · string
Code of the bank. Refer to bank and securities codes.
- accountNumber 필수 · string
Bank account number of the seller.
- holderName 필수 · string
Name registered as the bank account holder.
- metadata object
Add up to five key-value pairs as a JSON object. The key has a maximum length of 40 and must not include
[or]. The value has a maximum length of 500.
Returns
Returns an encrypted Seller object if successful. Returns an encrypted error object if unsuccessful. Decrypt the response using your security key.
Seller registration status
☑️ Individuals and individual businesses must be authenticated
When you register an individual or individual business seller, their initial status will be APPROVAL_REQUIRED. At this state, the sellers cannot receive a payout. Instead, the seller is sent a text message to the registered phone with instructions to complete customer identification (CI).
When the seller completes the CI will their status be updated to PARTIALLY_APPROVED. At this state, you can send the seller up to 10 million KRW each week.
☑️ Complete KYC to send sellers more than 10 million KRW per week
If you attempt to send a single seller more than 10 million KRW in the span of 7 days, the payout request is canceled and the seller's status is updated to KYC_REQUIRED. At this state, the seller cannot receive payouts of any amount.
Toss Payments emails the seller on instruction to KYC. When the seller passes the KYC, their status is updated to APPROVED. At this state, you can send the seller more than 10 million KRW per week. However, KYC is required every 1 or 3 years, depending on the seller's risk assessment.
☑️ Receive updates through webhooks
Get seller status updates using the seller.changed webhook event.
2. Retrieve your balance
See how much you can payout to sellers.
Returns
Returns a Balance object if successful. See the availableAmount for funds that can be used for payout right away.
Returns an error object if unsuccessful.
3. Request a payout
Send payouts to your registered sellers.
On each API, you can send a maximum of 100 payout requests. However, if a single request fails, all the requests will not go through and an error object about the failure will be responded. The maximum amount that can be sent with one request is 1 billion KRW.
* You will be charged for testing in live mode.Request body parameters
- refPayoutId 필수 · string
Unique identifier for your payout request.
- destination 필수 · string
The seller to make the payout to. Use the
idvalue of the Seller object. - scheduleType 필수 · string
The payout's schedule type.
EXPRESS: Payout is made to seller on the same day of the request.EXPRESSpayouts can be only requested on working days during 08:00-15:00.SCHEDULED: Set a payout date using thepayoutDateparameter.
- payoutDate string
The payout date in
yyyy-MM-ddformat. Required when the schedule type isSCHEDULED. The payout date must be a working day within a year of the request. If the payout date is set to a holiday, weekend, or a past date, an error occurs. - amount 필수 · string
Amount to payout to your seller.
- transactionDescription 필수 · string
Transaction description that is shown on the transfer statement.
- metadata string
Add up to five key-value pairs as a JSON object. The key has a maximum length of 40 and must not include
[or]. The value has a maximum length of 500.
Returns
Returns an encrypted Payout object if successful. Returns an encrypted error object if unsuccessful. Decrypt the response using your security key.
Payout failures
Even if your request is successful, the payout may fail due to unpredictable issues in the bank system. In such cases, the Payout object's status updates to FAILED and you can see the exact error in its error field.
If you want to test such failures, register a dummy seller with one of the below bank accounts and request a payout to the dummy seller.
| Account number | Bank(Code) |
|---|---|
77701777777 | 우리종합금융 (295) |
3025353430761 | 농협 (011) |
02004240994312 | 산업은행 (002) |
Cancel a payout
Only SCHEDULED type payouts can be canceled up until the day of the requested payout date. Because EXPRESS payouts occur on the same day of the request, they cannot be canceled. Get payout status updates with the payout.changed webhook.