History
Version | Date | Key Changes |
V2.210802 | 2021-08-02 | First Created |
V2.211006 | 2021-10-06 | Extend signup URL lookup |
V2.211014 | 2021-10-14 | 3.10. Added bottom information search (Hosting → Toss Payments) |
V2.220228 | 2022-02-28 | Added a description of the API request format |
V2.220303 | 2022-03-03 | 2.5. Added access restrictions |
V2.220318 | 2022-03-18 | 3.8. Updated description of Delete store (Hosting → Toss Payments) |
V2.220408 | 2022-04-08 | 3.11. Added Card Company Review Callback |
V2.220830 | 2022-08-30 | 3.2. Added store ID and marked it as unused in the table of contents, due to lack of usage. |
V2.230315 | 2023-03-15 | 3.1.1 Deleted unused parameters |
V2.230526 | 2023-05-26 | 3.7.2 Deleted unused parameters (Under Review) |
V2.230905 | 2023-09-05 | Added Referrer codes(유치코드) and guides for testing |
V2.231013 | 2023-10-15 | 3.10 Deleted (unused API) , 3.12 Added Simple payment subscription status inquiry API |
1. Overview
The Instant Onboarding API provides the ability to register a Toss Payments store and store ID, retrieve the e-contract application URL, and retrieve store application information so that customers can go through the steps of (1) applying for PG at their hosting company and (2) submitting documents to Toss Payments in a single, fluid process.
2. API Commonalities
2.1. API Authentication
When requesting the Hosting → Toss Payments API, you must include an authentication token and authentication hash in the HTTP header for authentication.
Authentication tokens and secret keys are issued on a hosting company-by-hosting company basis and will be provided upon request.
API Request Header
Name | Type | Description |
Auth-Token | String | API Authentication Token |
Auth-Hash | String | Hash the Auth-Token, Client Secret, and Shop ID with SHA256 |
•
Authentication tokens (Auth-Tokens) are used to distinguish the entity calling the API. It
should always be exposed as an Auth-Token in the HTTP request header.
•
The Client Secret is used as part of the value that generates the Auth-Hash.
◦
The authentication hash generated by your hosting provider is computed on the Toss Payments server, and if it yields the same result, it accepts the API request and performs the requested function.
◦
If your secret key is compromised, anyone can generate an authentication hash, so be sure to request a reissue from Toss Payments.
•
A shop unique identifier (Shop ID) is used by Toss Payments to identify your store. You must assign a unique identifier to each of your shops.
•
An authentication hash (Auth-Hash) is a value used to authenticate API calls and is
generated by hashing the authentication token, secret key, and store unique identifier
with the SHA-256 algorithm. Here is the sample code for generating an authentication
hash in Kotlin.
•
Sample Code
fun makeHash(token: String, secret: String, shopId: String) =
MessageDigest.getInstance("SHA-256").also {
it.update(token.toByteArray())
it.update(secret.toByteArray())
it.update(shopId.toByteArray())
}.let {
it.digest().joinToString("") { "%02x".format(it) }
}
Kotlin
복사
public String makeHash (String authToken, String clientSecret, String shopId)
throws NoSuchAlgorithmException {
MessageDigest md = MessageDigest.getInstance( "SHA-256" );
md.update(authToken.getBytes());
md.update(clientSecret.getBytes());
md.update(shopId.getBytes());
return bytesToHex(md.digest());
}
private String bytesToHex ( byte [] bytes) {
StringBuilder builder = new StringBuilder();
for ( byte b : bytes) {
builder.append(String.format( "%02x" , b));
}
return builder.toString();
}
Java
복사
2.2. API Request
The request body of all API requests accepts the application/json format. Therefore, the request header must contain the values below.
Content-Type: application/json
2.3. API Response
All API responses are provided in application/json format with the following structure
Name | Type | Description |
success | Boolean | Success for API requests |
errorCode | String | Error code encountered during request processing (null on success) |
message | String | The error message that occurred while processing the request (null on success) |
result | JSON | Return an object per API response |
2.4. Base URL
The API call URLs for each deployment stage are shown below.
Stage | URL |
dev | https://onboarding-api-dev.tosspayments.com |
staging | https://onboarding-api-staging.tosspayments.com |
live | https://onboarding-api.tosspayments.com |
2.5. Restrict Access
Communication is only possible in restricted environments to ensure secure service delivery. Please provide Toss Payments with the hosts that will access the API and pages separately.
3. Instant Onboarding
3.0. [Common] About Referrer Codes for testing
With the introduction of Instant Onboarding, you can test onboarding with the agencycode
below, targeting a live environment.
Please share the business number or applicant information used for testing with Toss Payments. (For testing support and identification purposes)
agencyCode | TestTest |
header_ClientSecret | 307a52ff0e29cb008a0ceae48ed48ac047a65a621681cbe4832e43fbbb23ce4b |
header_authToken | 4f18e5c2-de8b-454c-a871-b8f2111134c3 |
3.1. Create a Store (Hosting Company → Toss Payments)
Hosting provider passes store's business information to Toss Payments through the store creation API, and the store is registered in Toss Payments.
The Create store API is used to apply for an initial store ID (MID), and if you need additional store IDs for the same business license number, call the 3.2. Request additional store ID API.
3.1.1. Request
POST /instant-onboarding/v2/shop/{shopId}
Name | Type | Required | Description |
shopName | String | Y | Store name (e.g., "MarketKurly") |
shopContactName | String | Y | Contract PIC’s name |
shopContactEmail | String | Y | Contract PIC’s email |
shopContactPhoneNumber | String | Y | Contract PIC’s mobile number |
shopBusinessRegistrationNumber | String | Y | Store business license number (null if you're not a business) |
shopUrl | String | Y | Store URL |
returnUrl | String | Y | The URL to which you will be redirected when you complete your application to join Toss Payments. |
returnFallbackUrl | String | Y | URL to go to if the
application to join Toss Payments fails |
callbackUrl | String | N | The webhook URL where the store checkout integration data will be delivered. |
cardScreeningCallbackUrl | String | N | Create a
webhook URL |
agencyCode | String | Y | Referrer Code |
preferredMid | String | N | Desired store ID (this will be used to generate the store ID, the actual generated store ID may be different) |
Validation rules on requests
Name | Type | Rules |
shopName | String | Up to 200 characters |
shopContactName | String | Up to 100 characters |
shopContactEmail | String | Up to 100 characters |
shopContactPhoneNumber | String | Up to 20 characters |
shopBusinessRegistrationNumber | String | Up to 20 characters |
shopUrl | String | Up to 200 characters |
returnUrl | String | Up to 255 characters |
returnFallbackUrl | String | Up to 255 characters |
callbackUrl | String | Up to 255 characters |
cardScreeningCallbackUrl | String | Up to 255 characters |
agencyCode | String | Up to 20 characters |
preferredMid | String | Up to 14 characters |
3.1.2. Response
Name | Type | Description |
shopId | String | Store unique identifier |
businessRegistrationNumber | String | Store business license number |
mid | String | The store ID (MID) to use to call the checkout. |
mertKey | String | Merttkey to use for invoking the checkout |
apiKey | String | API KEY to use to call the checkout window (for New Payment SDK) |
clientKey | String | CLIENT KEY to use to call the checkout window
(for New Payment SDK) |
3.2 / 3.3 deleted content due to lack of usage.
3.4. Get signup URL (hosting company → Toss Payments)
Requests a request URL to sign up for a service on Toss Payments. The application URL is generated per store ID and expires after a certain amount of time. When requested again, the existing URL will expire and a new URL will be returned.
3.4.1. Request
GET /instant-onboarding/v2/shop/{shopId}/mid/{mid}/open-onboarding-session
(1) Request Parameter
Name | Type | Required | Description |
type | String | N | Session type
- INSTANT_ONBOARDING: PC Instant Onboarding (default)
- MOBILE_INSTANT_ONBOARDING:
Mobile Instant Onboarding
* For mobile instant onboarding, sessions are kept indefinitely for easy re-entry. However, for privacy reasons, anything you write will be reset after a period of time if there is no interaction. |
Session keys of type INSTANT_ONBOARDING are only valid for 1 hour.
If there are customer complaints due to session expiry during INSTANT_ONBOARDING type, then the hosting company will need to reissue the session by requesting this API again for that customer.
3.4.2. Response
Name | Type | Description |
applyUrl | String | TossPayments signup URL (expires after a certain time) |
3.5. Callback after Registration Completion (Toss Payments → Hosting Company)
Caveats
This API is only valid when called from a “Pre-open(미리오픈)” product.
General products that allow normal payment only after contract completion will return an error response when called.
For ”Pre-open” services, please contact Toss Payments for more information. Contact your Toss Payments representative.
Contact us
- partners@tosspayment.com
- Toss Payments Customer Center : 1544-7772
When a customer completes the application to sign up for TopSpecs, we pass the information required for payment integration and the subscription fee payment information (if a subscription fee is applied) to the callbackUrl passed to you when you registered your store.
3.5.1. Request
POST callbackUrl entered when creating a stroe or adding Store ID
(1) Request Header
Name | Type | Description |
Auth-Hash | String | Auth-Hash used in the store registration request |
(2) Request Body
Name | Type | Description |
shopId | String | Store unique identifier |
businessRegistrationNumber | String | Store business license number |
merchantId | Number | Operator ID |
mid | String | The store ID (MID) to use to invoke the checkout. |
mertKey | String | Mertkeys for invoking the checkout |
apiKey | String | API key to use to call the checkout window (when using the new payment SDK) |
clientKey | String | CLIENT KEY to use to call the checkout window (when using the new payment SDK) |
feePaidAt | String (ISO8601) | When you pay your subscription fee
(예: “2021-07-28T20:10:33.298642”) |
3.5.2. Response
The server receiving the request will return an HTTP Status 200 on successful receipt. A
Response Body is not required.
3.6. Get payment integration information (Hosting company → Toss Payments)
If you do not receive a callback after completing the subscription application, you can view the payment integration information directly.
3.6.1. Request
GET /instant-onboarding/v2/shop/{shopId}/credentials
3.6.2. Response
Name | Type | Description |
credentials | JSON Array | About payment integrations |
credentials[].shopId | String | Store unique identifier |
credentials[].businessRegistrationNumber | String | Store business license number |
credentials[].mid | String | The store ID (MID) to use to invoke the checkout. |
credentials[].mertKey | String | Mertkey to use for invoking the checkout |
credentials[].apiKey | String | API key to use to call the checkout window (when using the new payment SDK) |
credentials[].clientKey | String | CLIENT KEY to use to call the checkout window (when using the new payment SDK) |
3.7. Get subscription information (hosting company → Toss Payments)
You can view the business information received from the customer during the Topspayments subscription application process, PG contract status, and card company sub-mall screening status.
3.7.1. Request
GET /instant-onboarding/v2/shop/{shopId}
3.7.2. Response
Name | Type | Description |
descriptions | JSON Array | About store subscriptions |
descriptions[].mid | String | Store ID (MID) |
descriptions[].companyName | String | Business name |
descriptions[].companyType | String | Business type
• "PRIVATE": Sole proprietor.
• "NON_BUSINESS": Non-business.
• "CORPORATE": A for-profit
corporation.
• "non_profit_corp": Non-profit corporation
• "NON_PROFIT": Any organization/country/place itself |
descriptions[].businessRegistrationNumber | String | Store business license number |
descriptions[].corporateNumber | String | Store tax ID number |
descriptions[].contractStatus | String | PG contract status
• "READY": Before filling out the
application.
• "IN_DRAFT": Application is being
drafted
• "wait_for_review": Application submission complete
• "DONE": Contract completed
• "CANCELED": Canceled
• "TERMINATED": Terminated |
descriptions[].submallAuditStatus | JSON | Cardholder submall review status |
descriptions[].modifying | Boolean | Require modification of store subscription information If true, customers should be able to enter the application URL (Toss Payments Signup URL Request API). |
descriptions[].feeStatus | String | Subscription fee payment status
• Paid: "PAID"
• Unpaid: "NOT_PAID"
• Waiver: "WAIVED" |
descriptions[].feePaidAt | String (ISO8601) | When the subscription fee was paid
(e.g., "2021-07-. 28t20:10:33.298642") |
descriptions[].dashboardUrl | String | Storefront entry URL |
submallAuditStatus delivers the card company audit status in JSON, with the following detailed fields
Name | Type | Description | Values |
summary | String | Overall card review status | Categorize review statuses
• "NONE": Not applicable or before screening • "REQUESTED": Review requested
• "IN_REVIEW": In review.
• "DONE": Done
• "REJECTED": Cardholder rejected |
bc | String | BC Card | |
samsung | String | Samsung Card | |
shinhan | String | Shinhan Card | |
hana | String | Hana Card | |
hyundai | String | Hyundai Card | |
lotte | String | Lotte Card | |
kookmin | String | Kookmin Card | |
nonghyup | String | Nonghyup Card | |
woori | String | Woori Card |
3.8. Delete a store (Hosting Company → Toss Payments)
Deletes subscription/payment information by combining the shopId and business number. However, if the shopId is included in a contract that has already been completed, deleting the shop will stop.
3.8.1. Request
DELETE /instant-onboarding/v2/shop/{shopId}
Name | Type | Required | Description |
businessRegistrationNumber | Query Parameter (String) | N | Business license number to be deleted
• Can be multiple, specify null for non-businesses.
• If not specified, the
corresponding award All
Delete the information. |
3.8.2. Response
This is the same as the API common response described in 2.2.
3.9. Delete store ID (Hosting provider → Toss Payments)
Delete the store's individual store ID (MID). However, you can't delete it if the contract has already been completed.
3.9.1. Request
DELETE /instant-onboarding/v2/shop/{shopId}/mid/{mid}
3.9.2. Response
This is the same as the API common response described in 2.2.
3.11. Card Audit Callback (Toss Payments → Hosting Company)
Caveats
In a test situation, it is difficult to get a normal response from the card company review callback. Test merchants are not subject to real-world credit card review, and the test merchant codes described in 3.0 are for "testing" purposes, so they are not subject to the same credit card reviews as real-world merchants.
When a card screening event occurs, call the cardScreeningCallbackUrl passed in during store registration.
※ The event occurs when all card company vetting is complete.
3.11.1. Request
POST cardScreeningCallbackUrl entered when creating a store or adding a store ID
(1) Request Header
Name | Type | Description |
Auth-Hash | String | Auth-Hash used in the store registration request |
3.11.2. Response
The server receiving the request will return an HTTP Status 200 on successful receipt. A
Response Body is not required.
3.12. Search for Easy Payments (Hosting Company → Toss Payments)
Get a list of payments that the merchant is using.
3.12.1. Request
GET /instant-onboarding/v2/shop/{shopId}/payment-methods/easy-pays
(1) Request Header
Name | Type | Description |
Auth-Hash | String | Auth-Hash used in the store registration request |
3.12.2. Response
Name | Type | Description |
[].mid | String | Store ID (MID) |
[].easyPays | JSON Array | Easy Payments |
[].easyPays[].code | String | Redeemed payment code |
[].easyPays[].description | String | Name of the payment method used |
(Note) Payment code & name
Code | Code Name |
SAMSUNG_PAY | Samsung Pay |
SSG_PAY | SSG Pay |
PAYCO | Payco |
L_PAY | L.pay |
SMILE_PAY | Smile Pay |
KAKAO_PAY | Kakao Pay |
NAVER_PAY | Naver Pay |
TOSS_PAY | Toss Pay |
APPLE_PAY | Apple Pay |
PIN_PAY | Pin Pay |