지급대행 Version 2

리소스 객체는 일반적으로 API 요청이 성공하면 응답되는 객체입니다. version, traceId 등 API 요청에 대한 필드가 있고 entityBody 필드에서는 요청에 대한 응답을 확인할 수 있습니다. 예를 들어 잔액 조회를 요청하면 리소스 객체가 응답되고, 리소스 객체의 entityBody 필드에는 Balance 객체가 응답됩니다.

version string

API 버전입니다.

traceId string

토스페이먼츠에서 발급하는 API 요청의 고유 식별자입니다. 기술문의 시 traceId를 첨부하면 더 빠르게 답변을 받을 수 있습니다.

entityType string

응답 객체 유형입니다. 단건 객체가 응답되는 요청이라면 payout와 같이 객체 이름이 응답됩니다. 목록이 응답되는 요청이라면 payout-list와 같이 객체 이름 뒤에 -list가 붙습니다.

entityBody object

응답 객체입니다. 단건 응답이라면 객체가 돌아옵니다. 목록 응답에는 pagination 정보와 응답 목록이 돌아옵니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}",
	"entityType": "{entityType}", // 객체 이름
	"entityBody": {
		// 객체 데이터
	}
}
JSON
복사

에러 객체

에러 객체는 API 요청이 실패하면 응답되는 객체입니다. 에러 객체의 에러 코드와 메시지를 확인해주세요.

version string

API 버전입니다.

traceId string

토스페이먼츠에서 발급하는 API 요청의 고유 식별자입니다. 기술문의 시 traceId를 첨부하면 더 빠르게 답변을 받을 수 있습니다.

error object

에러 객체입니다.

└ code string

에러 코드입니다.

└ message string

에러 메시지입니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}",
	"error": {
		"code": "{CODE}",
		"message": "{MESSAGE}",
	}		
}
JSON
복사

지급대행 암호화

지급대행은 토스페이먼츠와 계약한 상점의 하위 셀러에게 정산금을 대신 지급하는 서비스입니다. 토스페이먼츠와 직접 계약하지 않은 셀러에게 토스페이먼츠가 정산금을 보내야 되기 때문에 KYC 등 리스크 검토 절차가 있습니다.

그리고 연동 측면에서도 더 강화된 보안을 요구합니다. 지급대행 관련 POST 요청은 모두 ENCRYPTION 보안을 사용합니다. ENCRYPTION 보안은 토스페이먼츠에서 발급하는 보안키를 사용해서 API의 Request Body를 JWE로 암호화하는 방식입니다. 보안키는 9월 19일부터 토스페이먼츠 개발자센터의 API 키 메뉴에서 확인할 수 있습니다.

ENCRYPTION 보안을 적용하는 방법을 지급대행 요청 API의 예시로 살펴볼게요.

지급대행 요청 API의 파라미터를 확인하고 Request Body를 생성하세요.

[{ 
    "refPayoutId": "my-payout-1", 
    "destination": "seller-1", 
    "scheduleType": "SCHEDULED", 
    "payoutDate": "2024-08-08", 
    "amount": { 
        "currency": "KRW", 
        "value": 5000.0 
    }, 
    "transactionDescription": "8월대금지급", 
    "metadata": { 
        "key1": "value1", 
        "key2": "value2" 
    } 
}]
JSON
복사

Request Body를 아래와 같이 보안키(securityKey)로 암호화하세요. 

•

AES256-GCM 방식을 사용하기 때문에 JWE 헤더의 enc 값을 “A256GCM” 으로 설정하세요({"enc":"A256GCM","alg":"dir","iat": "2023-11-23T21:52:13.378367+09:00", nonce: "{NONCE}"}). 

•

JWE 헤더의 iat 값을 Request Body를 만든 시간으로 설정하세요. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다.

•

JWE 헤더의 nonce 값을 설정하세요. UUID와 같이 충분히 무작위적인 고유 값으로 생성해주세요.

/**
 * @param target target object for encryption (requestBody)
 * @param securityKey symmetric key from tosspayments
 * @return requestBody in JWE
 */
fun encrypt(target: Any, securityKey: String): String {
    val payload = objectMapper.writeValueAsString(target)
    val jweHeader = JWEHeader.Builder(JWEAlgorithm.DIR, EncryptionMethod.A256GCM)
        .customParam("iat", OffsetDateTime.now(ZoneId.of("Asia/Seoul")).toString())
				.customParam("nonce", UUID.randomUUID().toString())
        .build()
    val jweObject = JWEObject(jweHeader, Payload(payload))
    val key = Hex.decode(securityKey)
    jweObject.encrypt(DirectEncrypter(key))
    return jweObject.serialize()
}
Kotlin
복사

JWE로 암호화한 Request Body를 API 요청의 데이터 값으로 넣고 TossPayments-api-security-mode: ENCRYPTION 헤더를 추가하세요. API 개별 연동 키 > 시크릿 키를 이용하는 Basic 인증도 반드시 해주세요.

curl --location 'https://api.tosspayments.com/v2/payouts' \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: text/plain' \
--header 'TossPayments-api-security-mode: ENCRYPTION'
--data 'eyJpYXQiOiIyMDIzLTExLTI3VDE4OjA4OjE5LjUzNTA0NyswOTowMCIsIm5vbmNlIjoiZTQ2YTBlNzgtNzZjYy00OGJlLWE0OTItODcwZTJmODAxMTNlIiwiYWxnIjoiSFMyNTYifQ.eyJhbW91bnQiOjUwMCwiYmFuayI6IuyLoO2VnCIsImN1c3RvbWVyTmFtZSI6Iuuwle2GoOyKpCIsIm9yZGVySWQiOiJ0ZXN0X29yZGVyXzExOSIsIm9yZGVyTmFtZSI6Iu2GoOyKpCDti7DshZTsuKAg7Jm4IDLqsbQifQ.U9FzvHYlEMqBgwe-7UfaX2-qsgEOlgkOB98MqEpu_hg'
Bash
복사

응답도 JWE로 암호화되어 반환됩니다.

eyJlbmMiOiJBMjU2R0NNIiwiaWF0IjoiMjAyMy0xMS0yN1QxODoxMDozOC45NDY1MTMrMDk6MDAiLCJub25jZSI6IjIxNDA1ZjdlLWJiNTctNGQwYS04YWQ5LWI5OWY3MzU3MTEwMiIsImFsZyI6ImRpciJ9..YePTUVJyNBU3YcxI.RwSc28MLtUWt9v2rcCnfIJuHDPTYUHFgVvoa5ZnEXsIq_Sv5wH-70mGqa6CZp8xpy-yOSsdeFYqbNv4JZ1wKSNZcbhK4l030QEk6H-uLPkdRPh8xRgXJ5o9LC6UpUkVFNUbtzzsZWB0XECGbSBtn_gg-eTLGL8LZT02JrP5Y79sN8ooE-4zyvBaEL3FZFcTWuDrCm565s2g84jes4q0Sr3o3HnW3nJ7nJiXFBCrQdlmFYeWrWEJZucFmb_0KxBAWVMOSQBQ6lMEDpomImpgGZwjhSz_zj-W09HICb3Nhp4Hx0hha8iTMIVyF4vIn6rdh9n_A-SVB5tN0qwcQB33MJ4rZfC1-ycKIDqDNQcnNMcrPfMwFsb3KECpKKOudH5yf5EveKwWEJul_-njs1OLyumYKGKj20fn1QE_twSFiWpfOfxsDzizXh5TetgO-c2PSjSQ2ksi-k05sNATQrxwjqXtS6KH01qig6QL7xVHhj34eEy6QU-67k80PUsZK2BXNhy__Daw0LGuMMpadQY2d7O-zAKjb4m6SVEpXuqKf-dOvX7H4Y5d0zuZGJZ21AG2Y2HmE-J-G4fzAKcbV41QaZQswgyz64uEtqTqeD4TkDYvUEr0AqMLcZc71iwBxUcEiQ6UQCPgytBhjBSgzxITeZ0GS6RUZ-tbhIGDwE1LbsMglqdXuNDu4ASUzOpeCzGnEHLcU0nGWD_a4ymWOQxYbmBjQ3j6Lb3UlkkaRBKrjIwvLBfB60J4ZZtWkLugo0dY4iWik0r1-AGKT3yJOEgE_PjebFTJ7mznRWzOD_ORpGKDhOMz12Y6UE8Kfvoss33D--8scEm03U6GvSspM7S7WD_juHqpQmFdTPAPx28OqxllDq94lE9g81pX6WeqcmdDNpgy6pZCpMCmQPKQH3lkeRaGEHiFsSPrJNNWO7EkvOcdhj9uyGGtQilTHsXbupruchQzQNKfDsGC2aQdLhCaC20atsbRpry-739W0WRqnIFZ8_2W4aZIRXpkygpaZ5vUTyq_xpp5BjV_vt5-NdOSkpZSvU79HroOR0-oCjddixO6AuBpFuQtVz8J6ajBfUUFFVD91GWzj3beqAKtWQkk0Een8c-f57FMJ9o1bmqtwVVAwV8BfAYLBBUdYKIBYfwPlvog_2B_OAMKgXEQOyD9EnTsk9uZlRbWt7-ofICtslhNB1f_V0-sRQQ7nzs8cv51fvSX0lrflvnhq8KJNHFmX0KKIYb1kpP66ld9m7sLlNvXYnjZog6FaH40evekW4hehiHCFnFF25_NSfIgmGcISmskO-m3d2fk1j3UwS-CgkEsSKaz0xxKcqjPhy2fT3Ec63OLwCpuP0ePBX3HSDKwQlSVmVz1TFU_aTimo81ufGKKfiNEXrv42SomNiXbSVPELu5tLQOyVnDrvUha31fiarHzNL9mfhqsemo3-hj6VKk6YQspM8d8ldzFVVyxekUGLRIxeaJKoStIu-2R7FrjTVgfPweDKw1RrfAoazTen9wKGcCC66XiARIpZ0sg6qjGRs-TQgLRO2eeYfrVlspevwoABFTnhzL9wQqhQySm_M2Chkn6u21ElJjlw1pHaoqABeky0LG3uolUUUYbPmbDyz5lUrDXwrCYYvP1M_iQn2Qcua5InQsIkGfnUtgwotSTXhqpwJw3qetAcKXgM0H78bE4Cr57mN_UR7yGat8NIkD79PIvkrA4F04x9JmsSCVcvlLW-FmGaNuUmziPXb6E.nwY-rgvJMEnkGvdqJqC8KA
JSON
복사

보안키로 응답을 복호화하고 응답 값을 확인하세요. 성공 응답, 에러 응답 모두 암호화되어 전달됩니다. 
암호화가 잘못 되면 다음과 같은 오류가 응답됩니다.

•

400 INVALID_ENCRYPTION 
요청 바디 암호화가 잘못 되었습니다. 보안키 및 암호화 방법을 다시 확인해주세요.

/**
* @param encryptedTarget decrypt target (responseBody from tosspayments)
* @param securityKey symmetric key from tosspayments
* @return JWE payload (plain responseBody in JSON)
*/
fun decrypt(encryptedTarget: String, securityKey: String): String {
  val jweObject = JWEObject.parse(encryptedTarget)
  val key = Hex.decode(securityKey)
  jweObject.decrypt(DirectDecrypter(key))
  val decryptedJweObject = if (jweObject.state == JWEObject.State.DECRYPTED) {
      jweObject
  } else {
      throw JOSEException("Failed to decrypt")
  }
  return decryptedJweObject.payload.toString()
}
Kotlin
복사

// 복호화된 응답
{
	"version": "2022-11-16",
	"traceId": "{traceId}"
	"entityType": "payout-list",
	"entityBody": {
		"items": [
			{
				"id": "FPA_12345",
				"refPayoutId": "my-payout-1",
				"destination": "seller-1",
				"scheduleType": "SCHEDULED",
				"payoutDate": "2024-08-08",
				"amount": {
					"currency": "KRW",
					"value": 5000.00
				},
				"transactionDescription": "8월대금지급",
				"requestedAt": "2024-08-07T22:00:00+09:00",
				"status": "REQUESTED",
				"error": null,
				"metadata": {
					"key1": "value1",
					"key2": "value2"
				}
			}
		]
	}
}
JSON
복사

Balance 객체

지급대행 상점이 셀러에게 지급할 수 있는 잔액 정보입니다.

pendingAmount object

셀러에게 지급이 불가한 잔액 정보입니다.

└ currency string

통화입니다. 현재는 KRW만 지원합니다.

└ value bigdecimal

잔액입니다.

availableAmount

셀러에게 지급이 가능한 잔액 정보입니다.

└ currency string

통화입니다. 현재는 KRW만 지원합니다.

└ value bigdecimal

잔액입니다.

잔액 조회

지급대행 상점이 셀러에게 지급할 수 있는 잔액을 조회합니다.

GET /v2/balances

요청

curl --request GET \
  --url https://api.tosspayments.com/v2/balances  \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg=='
Bash
복사

응답

잔액 조회에 성공하면 Balance 객체가 응답됩니다. 실패하면 에러 객체가 응답됩니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}",
	"entityType": "balance",
	"entityBody": {
		"pendingAmount": {
			"currency": "KRW",
			"value": 10000.00,
		},
		"availableAmount": {
			"currency": "KRW",
			"value": 20000.00,
		}
	}
}
JSON
복사

Seller 객체

지급대행 상점의 하위 셀러 정보입니다.

id string

토스페이먼츠에서 발급하는 셀러의 식별자입니다. 셀러 정보 조회 및 삭제와 지급대행에 사용됩니다. 셀러의 상태 및 지급대행 상태가 바뀌어도 id는 바뀌지 않고, 삭제된 id는 다시 발급되지 않습니다.

refSellerId string

지급대행 상점에서 등록하는 셀러의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에 수정할 수 없고, 삭제된 셀러의 refSellerId는 다시 사용할 수 없습니다.

businessType string

사업자 유형입니다. INDIVIDUAL(개인), INDIVIDUAL_BUSINESS (개인사업자), CORPORATE(법인사업자) 중 하나입니다.

company nullable object

법인사업자 또는 개인사업자 셀러의 정보입니다.

└ name string

사업자명입니다.

└ representativeName string

대표자명입니다.

└ businessRegistrationNumber string

사업자번호입니다.

└ email string

사업자 이메일입니다.

└ phone string

사업자 전화번호입니다.

individual nullable object

개인 셀러의 정보입니다.

└ name string

개인 이름입니다.

└ email string

개인 이메일입니다.

└ phone string

개인 전화번호입니다.

status string

셀러 상태입니다. 아래 네 개의 상태 중 하나입니다.

셀러 상태 흐름

•

APPROVAL_REQUIRED: 지급이 불가능한 상태입니다. 개인(INDIVIDUAL) 셀러 등록 직후의 상태이며, 본인인증이 필요합니다.

•

PARTIALLY_APPROVED: 일주일 동안 1천만원까지 지급 요청이 가능한 상태입니다. 등록 직후의 사업자 셀러 또는 본인인증을 완료한 개인 셀러의 상태입니다.

•

KYC_REQUIRED: 지급이 불가능한 상태입니다. 일주일 동안 1천만원을 초과하는 금액을 지급 요청하면 셀러는 해당 상태로 변경됩니다. 셀러가 KYC 심사를 완료해야 합니다.

•

APPROVED: 금액 제한 없이 지금 요청이 가능한 상태입니다. KYC 심사가 정상적으로 완료된 셀러의 상태입니다.

account object

셀러가 정산금을 지급받을 계좌 정보입니다.

└ bankCode string

은행 두 자리 코드입니다. 은행 코드와 증권사 코드를 참고하세요.

└ accountNumber string

계좌번호입니다.

└ holderName string

예금주입니다.

metadata nullable object

셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하입니다.

셀러 등록

셀러의 사업자번호, 계좌 유효성을 검증하고 셀러를 등록합니다.

POST /v2/sellers

Request Body를 ENCRYPTION 방식으로 암호화해야 되는 요청입니다.

Request Body 파라미터

refSellerId 필수 · string

businessType 필수 · string

사업자 유형입니다. INDIVIDUAL(개인), INDIVIDUAL_BUSINESS (개인사업자), CORPORATE(법인사업자) 중 하나입니다.

company object

법인사업자 또는 개인사업자 셀러 정보입니다. businessType이 INDIVIDUAL_BUSINESS 또는 CORPORATE이면 필수입니다.

└ name 필수 · string

사업자명입니다.

└ representativeName 필수 · string

대표자명입니다.

└ businessRegistrationNumber 필수 · string

사업자번호입니다. - 없이 10자리 사업자번호 숫자만 입력해주세요.

└ email 필수 · string

사업자 이메일입니다.

└ phone 필수 · string

사업자 전화번호입니다. - 없이 숫자만 입력해주세요.

individual object

개인 셀러 정보입니다. businessType이 INDIVIDUAL이면 필수입니다.

└ name string

이름입니다.

└ email string

이메일입니다.

└ phone string

전화번호입니다. - 없이 숫자만 입력해주세요.

account 필수 · string

셀레가 정산 금액을 지급받을 계좌 정보입니다.

└ bankCode 필수 · string 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고하세요.

└ accountNumber 필수 · string 계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 20자입니다.

└ holderName 필수 · string 계좌의 예금주입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.

metadata object

셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 JSON 객체입니다. 최대 5개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하입니다.

요청

Request Body를 JWE로 암호화하세요.

{
	"refSellerId": "my-seller-1", 
	"businessType": "INDIVIDUAL_BUSINESS", 
	"company": {
		"name": "테스트 상호", 
		"representativeName": "김토페", 
		"businessRegistrationNumber": "1234567890", 
		"email": "abc@toss.im", "phone": "01012345678"
	},
	"account": {
		"bankCode": "092", 
		"accountNumber": "123*****90123", 
		"holderName": "아무개"
	}, 
	"metadata": {
		"key1": "value1",
		"key2": "value2"
	}
}
JSON
복사

암호화된 Request Body를 API에 넣고, API의TossPayments-api-security-mode 헤더를 ENCRYPTION으로 설정해주세요.

curl --request POST \
  --url https://api.tosspayments.com/v2/sellers \
  --header 'Authorization: Basic Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'TossPayments-api-security-mode: ENCRYPTION'
  --data '{ENCRYPTED_REQUEST_BODY}'
Bash
복사

응답

JWE로 암호화된 응답이 반환됩니다.

{ENCRYPTED_RESPONSE_BODY}
JSON
복사

응답을 복호화하고 결과 값을 확인하세요. 셀러 등록이 성공하면 Seller 객체 목록이 돌아옵니다. 실패하면 에러 객체가 돌아옵니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}",
	"entityType": "seller",
	"entityBody": {
		"id": "seller-1",
		"refSellerId": "my-seller-1",
		"businessType": "INDIVIDUAL_BUSINESS",
		"company": {
			"name": "테스트 상호",
			"representativeName": "김토페",
			"businessRegistrationNumber": "1234567890",
			"email": "abc@toss.im",
			"phone": "01012345678"
		},
		"individual": null,
		"account": {
			"bankCode": "092",
			"accountNumber": "123*****90123",
			"holderName": "아무개"
		},
		"status": "PARTIALLY_APPROVED",
		"metadata": {
			"key1": "value1",
			"key2": "value2"
		}
	}
}
JSON
복사

에러 목록

•

400, DUPLICATE_SELLER
이미 존재하는 셀러(refSellerID)입니다.

•

400, INVALID_BUSINESS_NUMBER
존재하지 않거나 휴업 또는 폐업한 사업자입니다.

•

400, INVALID_ACCOUNT_INFO
예금주 정보와 계좌번호가 일치하지 않습니다. 예금주, 은행코드, 계좌번호를 정확히 입력해주세요.

•

400, INVALID_REQUEST
잘못된 요청입니다.

셀러 수정

등록된 서브믈 정보를 수정합니다. 수정하고 싶은 필드를 Request Body 파라미터로 보내주세요. 데이터를 삭제하고 싶다면 파라미터의 값을 null로 보내주세요. 등록할 때 필수 값이었던 파라미터는 삭제할 수 없습니다.

POST /v2/sellers/{id}

Request Body를 ENCRYPTION 방식으로 암호화해야 되는 요청입니다.

Path 파라미터

id 필수 · string

수정하고 싶은 Seller 객체의 id입니다. 토스페이먼츠에서 발급한 값이며, 지급대행 상점에서 발급한 refSellerId와 다른 값입니다.

Request Body 파라미터

company object

법인사업자 또는 개인사업자 셀러 정보입니다.

└ name string

사업자명입니다.

└ representativeName string

대표자명입니다.

└ email string

사업자 이메일입니다.

└ phone string

사업자 전화번호입니다. - 없이 숫자만 입력해주세요.

individual object

개인 셀러 정보입니다.

└ name string

이름입니다.

└ email string

이메일입니다.

└ phone string

전화번호입니다. - 없이 숫자만 입력해주세요.

account 필수 · string

셀러에서 정산 금액을 지급받을 계좌 정보입니다.

└ bankCode 필수 · string 계좌의 은행 코드입니다. 은행 코드와 증권사 코드를 참고하세요.

└ accountNumber 필수 · string 계좌번호입니다. - 없이 숫자만 입력해주세요. 최대 길이는 20자입니다.

└ holderName 필수 · string 계좌 예금주입니다. 최대 길이는 공백을 포함한 한글 30자, 영문 60자입니다.

metadata object

셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 JSON 객체입니다. 최대 5개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하입니다.

요청

Request Body를 JWE로 암호화하세요.

{
	"company": {
		"email": "def@toss.im", 
		"phone": "01087654321"
	}
}
JSON
복사

암호화된 Request Body를 API에 넣고, API의TossPayments-api-security-mode 헤더를 ENCRYPTION으로 설정해주세요.

curl --request POST \
  --url https://api.tosspayments.com/v2/sellers/seller-1 \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
  --header 'TossPayments-api-security-mode: ENCRYPTION'
  --data '{ENCRYPTED_RESPONSE_BODY}'
Bash
복사

응답

JWE로 암호화된 응답이 반환됩니다.

{ENCRYPTED_RESPONSE_BODY}
JSON
복사

응답을 복호화하고 결과 값을 확인하세요. 셀러 수정에 성공하면 Seller 객체가 돌아옵니다. 실패하면 에러 객체가 응답됩니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}"
	"entityType": "seller",
	"entityBody": {
		"id": "seller-1",
		"refSellerId": "my-seller-1",
		"businessType": "INDIVIDUAL_BUSINESS",
		"company": {
			"name": "테스트 상호",
			"representativeName": "김토페",
			"businessRegistrationNumber": "1234567890",
			"email": "def@toss.im", // abc@toss.im -> def@toss.im
			"phone": "01087654321" // 01012345678 -> 01087654321
		},
		"individual": null,
		"account": {
			"bankCode": "092",
			"accountNumber": "123*****90123",
			"holderName": "아무개"
		},
		"status": "PARTIALLY_APPROVED",
		"metadata": {
			"key1": "value1",
			"key2": "value2"
		}
	}
}
JSON
복사

에러 목록

•

400, INVALID_ACCOUNT_INFO
예금주 정보와 계좌번호가 일치하지 않습니다. 예금주, 은행코드, 계좌번호를 정확히 입력해주세요.

•

400, INVALID_REQUEST
잘못된 요청입니다.

•

404, NOT_FOUND 
존재하지 않는 정보 입니다.

셀러 삭제

등록된 셀러를 삭제합니다. 삭제한 셀러의 식별자는 다시 발급되지 않고 조회가 불가능합니다.

DELETE /v2/sellers/{id}

요청

curl --request DELETE \
  --url https://api.tosspayments.com/v2/sellers/seller-1 \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
Bash
복사

응답

셀러 삭제가 성공하면 아래와 같은 deleted-entity 객체가 돌아옵니다. entityBody 필드에는 삭제된 Seller 객체를 구분할 수 있는 id, refSellerId 필드가 있습니다. 실패하면 에러 객체가 응답됩니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}"
	"entityType": "deleted-entity",
	"entityBody": {
		"id": "seller-1",
		"refSellerId": "my-seller-1"
	}
}
JSON
복사

에러 목록

•

403, FORBIDDEN_SELLER_DELETE 
처리가 완료되지 않은 지급 요청이 있어서 삭제할 수 없습니다.

•

404, NOT_FOUND 
존재하지 않는 정보 입니다.

셀러 단건 조회

등록된 셀러 하나를 조회합니다. 삭제되지 않은 셀러만 조회할 수 있어요.

GET /v2/sellers/{id}

요청

curl --request GET \
  --url https://api.tosspayments.com/v2/sellers/seller-1 \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
Bash
복사

응답

셀러 조회에 성공하면 Seller 객체가 돌아옵니다. 실패하면 에러 객체가 응답됩니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}"
	"entityType": "seller",
	"entityBody": {
		"id": "seller-1",
		"refSellerId": "my-seller-1",
		"businessType": "INDIVIDUAL_BUSINESS",
		"company": {
			"name": "테스트 상호",
			"representativeName": "김토페",
			"businessRegistrationNumber": "1234567890",
			"email": "def@toss.im",
			"phone": "01087654321"
		},
		"individual": null,
		"account": {
			"bankCode": "092",
			"accountNumber": "123*****90123",
			"holderName": "아무개"
		},
		"status": "PARTIALLY_APPROVED",
		"metadata": {
			"key1": "value1",
			"key2": "value2"
		}
	}
}
JSON
복사

셀러 목록 조회

등록된 셀러 목록을 조회합니다. 삭제되지 않은 셀러만 조회할 수 있어요.

GET /v2/sellers?limit={limit}&startingAfter={startingAfter}

Path 파라미터

limit integer

조회하고 싶은 셀러 갯수입니다. 기본 값은 10입니다. 설정할 수 있는 최대값은 10000입니다.

startingAfter string

특정 셀러의 id입니다. 해당 id 의 셀러 다음으로 등록된 셀러부터 조회됩니다. 기본 값은 처음으로 등록된 셀러입니다.

Response Body

hasMore boolean

더 조회할 수 있는 데이터가 있는지 알려줍니다. 마지막 데이터라면 false, 다음 데이터가 있다면 true입니다.

size integer

조회된 객체의 갯수입니다. items의 크기입니다.

nextCursor nullable ・ string

다음 조회 시 startingAfter로 설정하면 되는 커서입니다. 만약에 더 조회할 데이터 없다면 null 입니다.

items array

Seller 객체 목록입니다.

요청

curl --request GET \
  --url https://api.tosspayments.com/v2/sellers?limit=1 \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
Bash
복사

응답

성공하면 Seller 객체 목록이 돌아옵니다. 실패하면 에러 객체가 응답됩니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}",
	"entityType": "seller-list",
	"entityBody": {
		"items": [
			{
				"id": "seller-1",
				"refSellerId": "my-seller-1",
				"businessType": "INDIVIDUAL_BUSINESS",
				"company": {
					"name": "테스트 상호",
					"representativeName": "김토페",
					"businessRegistrationNumber": "1234567890",
					"email": "def@toss.im",
					"phone": "01087654321"
				},
				"individual": null,
				"account": {
					"bankCode": "092",
					"accountNumber": "123*****90123",
					"holderName": "아무개"
				},
				"status": "PARTIALLY_APPROVED",
				"metadata": {
					"key1": "value1",
					"key2": "value2"
				}
			}
		],
		"hasMore": false,
		"size": 1,
		"nextCursor": null
	}
}
JSON
복사

에러 목록

•

400, INVALID_REQUEST
잘못된 요청입니다.

Payout 객체

지급대행 요청 정보입니다.

id string

토스페이먼츠에서 각 지급대행 요청에 발급하는 고유 식별자입니다. 지급대행 취소, 조회 등에 사용됩니다.

refPayoutId string

지급대행 상점에서 직접 발급하는 지급대행 요청의 고유 식별자입니다. 연동 중에 참고할 수 있는 값입니다. 등록 이후에 수정할 수 없고, 같은 값을 다시 사용할 수 없습니다.

destination string

정산금을 지급받는 셀러입니다. Seller 객체의 id 값입니다.

scheduleType string

지급대행의 유형입니다. 아래 둘 중 하나입니다.

•

EXPRESS: 바로 지급입니다. 요청한 당일 이내 정산이 지급됩니다.

•

SCHEDULED: 예약 지급입니다. 요청일을 설정해서 정산 지급을 예약합니다.

payoutDate string

yyyy-MM-dd 형식의 지급일입니다.

amount object

셀러에게 지급하는 정산 금액입니다.

└ currency string

통화입니다. 현재는 KRW만 지원합니다.

└ value bigdecimal

잔액입니다.

transactionDescription string

이체 내역에 표시되는 적요입니다. 최대 길이는 7자입니다.

requestedAt string

지급대행이 요청된 시점입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm 형식입니다.

status string

지급대행 상태입니다.

지급대행 상태 흐름

•

REQUESTED: 지급이 요청되었지만 아직 처리되지 않은 상태입니다. REQUESTED 상태일 때만 지급대행 요청을 취소할 수 있습니다.

•

IN_PROGRESS: 지급을 처리하고 있는 상태입니다.

•

COMPLETED: 셀러에 지급이 완료된 상태입니다.

•

FAILED: 지급 요청이 실패한 상태입니다.

•

CANCELED: 지급 요청이 취소된 상태입니다.

error nullable object

지급대행 요청에서 일어난 에러 객체입니다.

metadata nullable object

셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하입니다.

지급대행 요청

지급 대상 셀러에게 설정된 금액을 이체합니다. 요청 시점에 잔액이 부족하면 지급이 실패하고, 요청 가능한 시간은 영업일 08:00~15:00입니다. Request Body를 Array로 보내면 최대 100 건의 지급대행을 한 번에 요청할 수 있습니다. 하지만 하나의 요청이 실패하면 요청 모두 실패하고 첫 번째 실패 건에 대한 에러 객체가 돌아옵니다.

POST /v2/payouts

Request Body를 ENCRYPTION 방식으로 암호화해야 되는 요청입니다.

Request Body 파라미터

refPayoutId 필수 · string

지급대행 상점에서 발급하는 지급대행 식별자입니다. 각 지급대행 요청 건에 고유 값을 발급해야 되고 지급대행 상점에서 참고용으로 사용할 수 있습니다.

destination 필수 · string

정산금을 지급받는 셀러입니다. Seller 객체의 id 값입니다.

scheduleType 필수 · string

지급대행의 유형입니다. 아래 둘 중 하나입니다.

•

EXPRESS: 바로 지급입니다. 요청한 당일 이내 정산이 지급됩니다.

•

SCHEDULED: 예약 지급입니다. 요청일을 설정해서 정산 지급을 예약합니다.

payoutDate string

yyyy-MM-dd 형식의 지급일입니다. 지급대행 유형이 SCHEDULED일 때는 필수입니다.

amount 필수 · object

지급 금액 정보입니다.

└ currency 필수 · string

통화입니다. 현재는 KRW만 지원합니다.

└ value 필수 · bigdecimal

지급할 금액입니다.

transactionDescription 필수 · string

이체 내역에 표시되는 적요입니다. 최대 길이는 7자입니다.

metadata object

셀러와 관련된 추가 정보를 key-value 쌍으로 담고 있는 객체입니다. 최대 5개의 key-value 쌍을 포함할 수 있으며 전체 크기는 4kB 이하입니다.

요청

Request Body를 JWE로 암호화하세요.

[{ 
    "refPayoutId": "my-payout-1", 
    "destination": "seller-1", 
    "scheduleType": "SCHEDULED", 
    "payoutDate": "2024-08-08", 
    "amount": { 
        "currency": "KRW", 
        "value": 5000.0 
    }, 
    "transactionDescription": "8월대금지급", 
    "metadata": { 
        "key1": "value1", 
        "key2": "value2" 
    } 
}]
JSON
복사

암호화된 Request Body를 API에 넣고, API의TossPayments-api-security-mode 헤더를 ENCRYPTION으로 설정해주세요.

curl --location 'https://api.tosspayments.com/v2/payouts' \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: text/plain' \
--header 'TossPayments-api-security-mode: ENCRYPTION'
--data 'eyJpYXQiOiIyMDIzLTExLTI3VDE4OjA4OjE5LjUzNTA0NyswOTowMCIsIm5vbmNlIjoiZTQ2YTBlNzgtNzZjYy00OGJlLWE0OTItODcwZTJmODAxMTNlIiwiYWxnIjoiSFMyNTYifQ.eyJhbW91bnQiOjUwMCwiYmFuayI6IuyLoO2VnCIsImN1c3RvbWVyTmFtZSI6Iuuwle2GoOyKpCIsIm9yZGVySWQiOiJ0ZXN0X29yZGVyXzExOSIsIm9yZGVyTmFtZSI6Iu2GoOyKpCDti7DshZTsuKAg7Jm4IDLqsbQifQ.U9FzvHYlEMqBgwe-7UfaX2-qsgEOlgkOB98MqEpu_hg''
Bash
복사

응답

JWE로 암호화된 응답이 반환됩니다.

eyJpYXQiOiIyMDIzLTExLTI3VDE4OjA4OjMzLjMyNTEzMSswOTowMCIsIm5vbmNlIjoiMWQ3Y2E4MjItZDM3Zi00ZTMyLTkyM2YtZDIyNWI5OTFlNWI2IiwiYWxnIjoiSFMyNTYifQ.eyJtSWQiOiJ0dml2YXJlcHVibGljYSIsImxhc3RUcmFuc2FjdGlvbktleSI6IkY5OUVBODNDMjI5NTM4NjdGNzdFNkEzMDAyODM3RUFEIiwicGF5bWVudEtleSI6IjAxT0F2MlA2eXFMbERKYVluZ3JvendKa0F5anpvWFZlekdkUnBYeEtON0JRTUVrNCIsIm9yZGVySWQiOiJ0ZXN0X29yZGVyXzExOSIsIm9yZGVyTmFtZSI6Iu2GoOyKpCDti7DshZTsuKAg7Jm4IDLqsbQiLCJ0YXhFeGVtcHRpb25BbW91bnQiOjAsInN0YXR1cyI6IldBSVRJTkdfRk9SX0RFUE9TSVQiLCJyZXF1ZXN0ZWRBdCI6IjIwMjMtMTEtMjdUMTg6MDg6MjYrMDk6MDAiLCJhcHByb3ZlZEF0IjpudWxsLCJ1c2VFc2Nyb3ciOmZhbHNlLCJjdWx0dXJlRXhwZW5zZSI6ZmFsc2UsImNhcmQiOm51bGwsInZpcnR1YWxBY2NvdW50Ijp7ImFjY291bnROdW1iZXIiOiJYMzc5MDEwODg3MzI2MiIsImFjY291bnRUeXBlIjoi7J2867CYIiwiYmFua0NvZGUiOiI4OCIsImN1c3RvbWVyTmFtZSI6Iuuwle2GoOyKpCIsImR1ZURhdGUiOiIyMDIzLTEyLTA0VDE4OjA4OjI2KzA5OjAwIiwiZXhwaXJlZCI6ZmFsc2UsInNldHRsZW1lbnRTdGF0dXMiOiJJTkNPTVBMRVRFRCIsInJlZnVuZFN0YXR1cyI6Ik5PTkUiLCJyZWZ1bmRSZWNlaXZlQWNjb3VudCI6bnVsbH0sInRyYW5zZmVyIjpudWxsLCJtb2JpbGVQaG9uZSI6bnVsbCwiZ2lmdENlcnRpZmljYXRlIjpudWxsLCJjYXNoUmVjZWlwdCI6bnVsbCwiY2FzaFJlY2VpcHRzIjpudWxsLCJkaXNjb3VudCI6bnVsbCwiY2FuY2VscyI6bnVsbCwic2VjcmV0IjoicHNfMjR4TGVhNXpWQWd3am5QTUE0NzhRQU1ZTndXNiIsInR5cGUiOiJOT1JNQUwiLCJlYXN5UGF5IjpudWxsLCJjb3VudHJ5IjoiS1IiLCJmYWlsdXJlIjpudWxsLCJpc1BhcnRpYWxDYW5jZWxhYmxlIjp0cnVlLCJyZWNlaXB0Ijp7InVybCI6Imh0dHBzOi8vcGd3ZWIudG9zc3BheW1lbnRzLmNvbTo3MDg2L01wRmxvd0N0cmw_ZXZlbnREaXYxPXNlYXJjaCZldmVudERpdjI9Z2V0Q2FzUmVjZWlwdExpc3QmdHJ4aWQ9dHZpdmEyMDIzMTEyNzE4MDgzMW51Nmg5JlNZU1RFTT1ORVcifSwiY2hlY2tvdXQiOnsidXJsIjoiaHR0cDovL2xvY2FsaG9zdDoxMDUwMS92MS9wYXltZW50cy8wMU9BdjJQNnlxTGxESmFZbmdyb3p3SmtBeWp6b1hWZXpHZFJwWHhLTjdCUU1FazQvY2hlY2tvdXQifSwiY3VycmVuY3kiOiJLUlciLCJ0b3RhbEFtb3VudCI6NTAwLCJiYWxhbmNlQW1vdW50Ijo1MDAsInN1cHBsaWVkQW1vdW50Ijo0NTUsInZhdCI6NDUsInRheEZyZWVBbW91bnQiOjAsIm1ldGhvZCI6IuqwgOyDgeqzhOyijCIsInZlcnNpb24iOiIyMDIyLTExLTE2In0.O-jD5nCUQGMGYtlJ98ccwNnl2rNEc8HbhrVGEHTcP1A
JSON
복사

응답을 복호화하고 결과 값을 확인하세요. 지급대행 요청이 성공하면 Payout 객체 목록이 돌아옵니다. 실패하면 에러 객체가 돌아옵니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}"
	"entityType": "payout-list",
	"entityBody": {
		"items": [
			{
				"id": "FPA_12345",
				"refPayoutId": "my-payout-1",
				"destination": "seller-1",
				"scheduleType": "SCHEDULED",
				"payoutDate": "2024-08-08",
				"amount": {
					"currency": "KRW",
					"value": 5000.00
				},
				"transactionDescription": "8월대금지급",
				"requestedAt": "2024-08-07T22:00:00+09:00",
				"status": "REQUESTED",
				"error": null,
				"metadata": {
					"key1": "value1",
					"key2": "value2"
				}
			}
		]
	}
}
JSON
복사

에러 목록

•

400, INVALID_PAYOUT_DATE
지급일자는 과거일자 또는 공휴일로 설정할 수 없습니다. 올바른 지급일자를 입력해주세요. (refPayoutId: {refPayoutId})

•

400, INCORRECT_PAYOUT_DATE_FORMAT
지급일 형식이 올바르지 않습니다. yyyy-MM-dd 형식으로 입력해주세요.(refPayoutId: {refPayoutId})

•

400, EXCEEDED_PAYOUT_BALANCE_AMOUNT
지급가능한 금액을 초과했습니다.

•

400, DUPLICATE_PAYOUT_REQUEST
중복된 지급대행 요청입니다.(refPayoutId: {refPayoutId})

•

400, INVALID_SELLER_INFO
필수값이 누락된 셀러입니다.(refPayoutId: {refPayoutId})

•

403, FORBIDDEN_SELLER_PAYOUT
고객 확인 심사(KYC)가 필요한 셀러가 포함돼있습니다. 해당 셀러를 제외하거나 셀러 심사가 완료될 때까지 기다려주세요.(refPayoutId: {refPayoutId})

•

400, INVALID_PAYOUT_REQUEST
잘못된 요청입니다.(refPayoutId: {refPayoutId})

•

404, NOT_FOUND_SELLER
존재하지 않는 셀러입니다.(refPayoutId: {refPayoutId})

지급대행 요청 취소

REQUESTED 상태의 지급대행 요청 건을 취소합니다. 이미 처리 중이거나 완료된 지급대행 요청 건은 취소할 수 없습니다.

POST /v2/payouts/{id}/cancel

Path 파라미터

id string

취소하고 싶은 Payout 객체의 id입니다.

요청

curl --request GET \
  --url https://api.tosspayments.com/v2/payouts/FPA_12345/cancel \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
Bash
복사

응답

성공하면 상태가 바뀐 Payout 객체가 돌아옵니다.

{
	"version": "2022-11-16",
	"traceId": "{traceId}"
	"entityType": "payout",
	"entityBody": {
		"id": "FPA_12345",
		"refPayoutId": "my-payout-1",
		"destination": "seller-1",
		"scheduleType": "SCHEDULED",
		"payoutDate": "2024-08-08",
		"amount": {
			"currency": "KRW",
			"value": 5000.00
		},
		"transactionDescription": "8월대금지급",
		"requestedAt": "2024-08-07T22:00:00+09:00",
		"status": "CANCELED",
		"error": null,
		"metadata": {
			"key1": "value1",
			"key2": "value2"
		}
	}
}
JSON
복사

에러 목록

•

403, FORBIDDEN_PAYOUT_CANCEL_REQUEST
REQUESTED 상태일 때만 취소할 수 있습니다.

•

404, NOT_FOUND
존재하지 않는 정보 입니다.

지급 단건 조회

지급 요청 한 건을 조회합니다.

GET /v2/payouts/{id}

요청

curl --request GET \
  --url https://api.tosspayments.com/v2/payouts/FPA_12345 \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
Bash
복사

응답

요청이 성공하면 조회한 Payout 객체가 응답됩니다.

{
	"apiVersion": "2022-11-16",
	"traceId": "{traceId}"
	"entityType": "payout",
	"entityBody": {
		"id": "FPA_12345",
		"refPayoutId": "my-payout-1",
		"destination": "seller-1",
		"scheduleType": "SCHEDULED",
		"payoutDate": "2024-08-08",
		"amount": {
			"currency": "KRW",
			"value": 5000.00
		},
		"transactionDescription": "8월대금지급",
		"requestedAt": "2024-08-07T22:00:00+09:00",
		"status": "CANCELED",
		"error": null,
		"metadata": {
			"key1": "value1",
			"key2": "value2"
		}
	}
}
JSON
복사

에러 목록

•

404, NOT_FOUND
존재하지 않는 정보 입니다.

지급 목록 조회

지급 요청 목록을 조회합니다.

GET /v2/payouts?limit={limit}&startingAfter={startingAfter}&payoutDate[gt]={payoutDate}

Path 파라미터

limit integer

조회하고 싶은 지급대행 요청건의 갯수입니다. 기본 값은 10이고, 설정할 수 있는 최대값은 10000입니다.

startingAfter string

지급대행 요청건의 id입니다. 설정한 id 의 지급대행 요청건 다음으로 등록된 요청건부터 조회됩니다. 설정하지 않으면 첫 지급대행 요청건부터 조회됩니다.

payoutDate string

지급일입니다. 특정 지급일 기준으로 지급 목록을 조회하고 싶을 때 사용합니다.

아래와 같이 gt, lt 등 하위 필드를 사용할 수도 있습니다.

•

[gt]: 해당 지급일보다 더 큰 레코드 조회 (초과)

•

[gte]: 해당 지급일보다 더 크거나 같은 레코드 조회 (이상)

•

[lt]: 해당 지급일보다 더 작은 레코드 조회 (미만)

•

[lte]: 해당 지급일보다 더 작거나 같은 레코드 조회 (이하)

Response Body

hasMore boolean

더 조회할 수 있는 데이터가 있는지 알려줍니다. 마지막 데이터라면 false, 다음 데이터가 있다면 true입니다.

size integer

조회된 객체의 갯수입니다. data의 크기입니다.

nextCursor nullable ・ string

다음 조회 시 startingAfter로 설정하면 되는 커서입니다. 만약에 더 조회할 데이터 없다면 null 입니다.

items array

Payout 객체 목록입니다.

요청

curl --request GET \
  --url https://api.tosspayments.com/v2/payouts?limit={limit}&startingAfter={startingAfter}&payoutDate[gt]=2024-01-01 \
  --header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
  --header 'Content-Type: application/json' \
Bash
복사

응답

{
	"version": "2022-11-16",
	"traceId": "{traceId}"
	"entityType": "payout-list",
	"entityBody": {
		"items": [
			{
				"id": "FPA_12345",
				"refPayoutId": "my-payout-1",
				"destination": "seller-1",
				"scheduleType": "PLANNED",
				"payoutDate": "2024-08-08",
				"amount": {
					"currency": "KRW",
					"value": 5000.00
				},
				"transactionDescription": "8월대금지급",
				"requestedAt": "2024-08-07T22:00:00+09:00",
				"status": "CANCELED",
				"error": null,
				"metadata": {
					"key1": "value1",
					"key2": "value2"
				}
			}
		],
		"hasMore": false,
		"size": 1,
		"nextCursor": null
	}
}
JSON
복사

에러 목록

•

400, INVALID_REQUEST
잘못된 요청입니다.

지급대행 웹훅

토스페이먼츠 지급대행은 2개의 웹훅을 제공합니다.

payout.changed

지급대행 요청 상태가 COMPLETED, FAILED로 바뀌면 웹훅이 전송됩니다.

flowchart TD

    classDef webhook fill:#f3f4f6,stroke:#e9eaec

    id1(지급 요청) -->|EXPRESS| id2([IN_PROGRESS])
    id1 -->|SCHEDULED| id3([REQUESTED])
    id3 -->|지급대행 요청 취소| id4([CANCELED])
    id3 -->|처리 시작| id2
    id2 -->|성공| id5([COMPLETED]):::webhook
    id2 -->|실패| id6([FAILED]):::webhook
Mermaid
복사

이벤트 본문

eventType string

웹훅 이벤트 타입입니다.

createdAt string

웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. version string

API 버전입니다.

eventId string

웹훅의 고유 식별자입니다.

entityType string

payout입니다. 응답 객체 유형입니다.

entityBody object

상태가 변경된 Payout 객체입니다. 사용하는 API 버전에 따라 객체 필드가 다를 수 있습니다.

{
  "eventType": "payout.changed",
  "createdAt": "{yyyy-MM-dd'T'HH:mm:ss±hh:mm}",
  "version": "2022-11-16",
  "eventId": "{eventId}",
	"entityType": "payout", 
	"entityBody": { 
		"id": "FPA_12345",
		"refPayoutId": "my-payout-1",
		"destination": "seller-1",
		"scheduleType": "SCHEDULED",
		"payoutDate": "2024-08-08",
		"amount": {
			"currency": "KRW",
			"value": 5000.00
		},
		"transactionDescription": "8월대금지급",
		"requestedAt": "2024-08-07T22:00:00+09:00",
		"status": "COMPLETED",
		"error": null,
		"metadata": {
			"key1": "value1",
			"key2": "value2"
		}
	}
}
JSON
복사

seller.changed

셀러의 상태가 PARTIALLY_APPROVED, KYC_REQUIRED, APPROVED로 바뀌면 웹훅이 전송됩니다. 셀러의 리스크 상태에 따라 1년 또는 3년마다 셀러의 상태가 APPROVED에서 KYC_REQUIRED로 바뀔 수 있어요.

flowchart TD
    classDef webhook fill:#f3f4f6,stroke:#e9eaec

    id4(셀러 등록) -->|법인사업자 셀러| id1
    id4 -->|개인 및 개인사업자 셀러| id5([APPROVAL_REQUIRED])
    id5 -->|본인인증| id1:::webhook
    id1([PARTIALLY_APPROVED]) -->|1천만원 이상 지급 요청| id2([KYC_REQUIRED]):::webhook
    id2 -->|KYC 심사 완료| id3([APPROVED]):::webhook
    id3 -->|KYC 심사 재이행| id2
Mermaid
복사

이벤트 본문

eventType string

웹훅 이벤트 타입입니다.

createdAt string

웹훅이 생성된 시간입니다. yyyy-MM-dd'T'HH:mm:ss±hh:mm ISO 8601 형식입니다. version string

API 버전입니다.

eventId string

웹훅의 고유 식별자입니다.

entityType string

seller입니다. 응답 객체 유형입니다.

entityBody object

상태가 변경된 Seller 객체입니다. 사용하는 API 버전에 따라 객체 필드가 다를 수 있습니다.

{
  "eventType": "seller.changed",
  "createdAt": "{yyyy-MM-dd'T'HH:mm:ss±hh:mm}",
  "version": "2022-11-16",
  "eventId": "{eventId}",
	"entityType": "seller",
	"entityBody": {
		"id": "seller-1",
		"refSellerId": "my-seller-1",
		"businessType": "INDIVIDUAL_BUSINESS",
		"company": {
			"name": "테스트 상호",
			"representativeName": "김토페",
			"businessRegistrationNumber": "1234567890",
			"email": "def@toss.im",
			"phone": "01087654321"
		},
		"individual": null,
		"account": {
			"bankCode": "092",
			"accountNumber": "123*****90123",
			"holderName": "아무개"
		},
		"status": "KYC_REQUIRED",
		"metadata": {
			"key1": "value1",
			"key2": "value2"
		}
	}
}
JSON
복사