코드가 복사되었습니다.

글로벌 지급대행

Eximbay 글로벌 지급대행은 서브몰 관리(등록 · 수정 · 조회)와 수취계좌 관리, 환전, 지급(견적 · 생성 · 조회 · 취소)에 대한 API 를 포함하고 있습니다.
지급대행 API 는 결제 API 와 동일하게 API Key 로 인증합니다. API Key 준비는 결제창 연동 준비에서 자세히 알아보세요. 

curl --location 'https://api.eximbay.com/v2/payouts/policies' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic dGVzdF8xODQ5NzA1QzY0MkMyMTdFMEIyRDo='

본 문서에 따라 API 연동이 완료되면 서비스용 URL 과 관련 파라미터를 변경한 뒤 실 서비스를 이용할 수 있습니다.

•  본 문서의 규격은 앞으로 Eximbay 지급대행의 표준 규격이 됩니다.
•  현재 운영 중인 기존 '지급대행' 서비스는 차후 본 규격으로 순차적으로 흡수 · 통합될 예정입니다.
•  신규 연동은 물론 기존 연동의 확장 · 개선도 본 문서를 기준으로 진행하시길 권장합니다.
•  기존 지급대행을 이용 중인 가맹점의 전환 시점과 절차는 별도로 안내해 드립니다. 안내 전까지는 기존 연동을 그대로 이용할 수 있습니다.

요청 URL

모든 엔드포인트는 아래 Base URL 아래에 있습니다. 메서드는 POST 와 GET 만 사용합니다.

구분 URL
운영 https://api.eximbay.com
테스트 https://api-test.eximbay.com

타임아웃

가맹점 서버에서 Eximbay API 를 호출할 때 HTTP 클라이언트에 아래 값을 설정하시길 권장합니다.

구분 권장값 설명
Connection Timeout 3초 Eximbay 서버와 연결을 맺기까지 기다리는 시간
Read Timeout 35초 연결된 뒤 응답을 받기까지 기다리는 시간

•  Read Timeout 이 지나 응답을 받지 못했더라도 요청이 Eximbay 에서 처리됐을 수 있습니다. 생성 계열 POST(서브몰 · 수취계좌 · 환전 실행 · 지급 생성)는 같은 reference 로 그대로 재전송하면 됩니다. 이미 처리된 경우에는 409 duplicate_reference 로 응답하므로 중복 생성을 막을 수 있습니다.
•  처리 결과는 목록 · 단건 조회 API 로 확인합니다. 조회(GET)는 재시도해도 부작용이 없습니다.

서브몰 정보 관리

서브몰 등록

POST /v2/submalls

지급대행을 요청할 하위 가맹점을 Eximbay 에 등록합니다. 국가 무관 최소 필드만 받으며, 국가별 KYB 필드 · UBO · 대표자 · 서류는 별도 화면에서 수집합니다.

•  country 가 심사 범위와 안내 언어를 결정합니다.
•  contact.email 로 서류 요청 링크가 발송됩니다.
•  merchant_submall_reference 가 중복되면 409 duplicate_reference 로 거절합니다.
•  payout_method 를 함께 보내면 서브몰과 수취계좌를 한 번에 등록합니다. 선택 항목이며 보내지 않으면 서브몰만 등록됩니다.

요청 파라미터

merchant_submall_reference string(100) · Body

필수
가맹점이 지정하는 서브몰 식별값입니다. 가맹점 내에서 유일해야 합니다.

business_type string(50) · Body

필수
사업자 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

country string(2) · Body

필수
심사 범위와 안내 언어를 결정합니다. ISO 3166-1 alpha-2 대문자 2자입니다.

legal_name string(200) · Body

필수
법인명 · 상호입니다.

trading_name string(200) · Body

거래상 사용하는 이름입니다.

registration_number string(100) · Body

필수
사업자 등록번호입니다.

tax_id string(100) · Body

세금 식별번호입니다.

incorporation_date string(8) · Body

회사 설립일 입니다. YYYYMMDD 형식입니다.

registered_address Address · Body*등기주소입니다.

필수

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

operating_address Address · Body*영업주소입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

contact Contact · Body*담당자 연락처입니다.

필수

name string(100)

필수
담당자명입니다.

email string(254)

필수
담당자 이메일 주소입니다. 서류 요청 링크가 이 주소로 발송됩니다.

phone string(30)

담당자 전화번호입니다. E.164 표기를 권장합니다.

payout_method object · Body*함께 등록할 수취계좌입니다.

선택 항목이며, 보내면 서브몰과 수취계좌가 한 번에 만들어집니다. 보내지 않으면 서브몰만 만들어지고, 계좌는 나중에 수취계좌 등록 으로 등록합니다.
최초 1건

: 배열이 아니라 객체입니다. 두 번째 계좌부터는 수취계좌 등록 API 를 사용합니다.

merchant_payout_method_reference string(100)

필수
가맹점이 지정하는 수취계좌 식별값입니다. 가맹점 내에서 유일해야 합니다.

label string(100)

가맹점용 별칭입니다.

bank_account object *계좌 정보입니다.

필수
수취계좌 등록 API 의 bank_account 와 완전히 같습니다. route 에 따라 필수 필드가 달라집니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체.

OVERSEAS_BANK

: 해외 계좌이체. 허용 통화는 KRW USD JPY EUR 입니다.

currency string(3)

필수
계좌 통화입니다. 이 값이 지급통화가 됩니다.

account_holder_name string(200)

필수
예금주명입니다. 서브몰 명의여야 합니다.

account_holder_type string(50)

필수
예금주 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

bank_country string(2)

필수
계좌가 개설된 은행 소재 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

account_number string(64)

필수
계좌번호입니다.

domestic_bank_code string(20)

계좌를 개설한 은행을 지정하는 국내 은행 코드입니다. DOMESTIC_BANK 일 때 필수입니다. 은행 코드

swift_bic string(11)

수취 은행을 국제적으로 식별하는 SWIFT/BIC 코드입니다. OVERSEAS_BANK 일 때 필수이며 8자 또는 11자입니다.

bank_name string(200)

수취 은행명입니다. 해외송금 전문에 그대로 실리므로 영문 정식 명칭을 사용합니다. OVERSEAS_BANK 일 때 필수입니다.

bank_address Address *수취 은행의 주소입니다.

계좌가 개설된 은행 · 지점의 소재지이며, 해외송금 전문에 포함됩니다. OVERSEAS_BANK 일 때 필수입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

beneficiary_address Address *수취인의 주소입니다.

자금세탁방지 규정상 해외송금 전문에는 수취인의 이름 · 계좌번호와 함께 주소가 실려야 하고, 비어 있거나 부정확하면 중개은행에서 반송되거나 지급이 지연될 수 있습니다. OVERSEAS_BANK 일 때 필수입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

iban string(34)

국제 표준 계좌번호(IBAN)입니다. 국가 코드 · 검사숫자 · 계좌 식별자로 구성된 국제 표준 형식이며, IBAN 을 사용하는 국가일 때 필수입니다. 15~34자입니다.
요청 ① 서브몰만 등록 

{
    "merchant_submall_reference": "SELLER-US-00042",
    "business_type": "COMPANY",
    "country": "US",
    "legal_name": "ACME TRADING INC",
    "trading_name": "ACME",
    "registration_number": "84-1234567",
    "tax_id": "84-1234567",
    "incorporation_date": "20190315",
    "registered_address": {
        "line1": "500 Market St",
        "line2": "Suite 200",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    },
    "contact": {
        "name": "John Doe",
        "email": "finance@acme.example",
        "phone": "+14155550100"
    }
}
요청 ② 서브몰 + 수취계좌 동시 등록 

{
    "merchant_submall_reference": "SELLER-US-00042",
    "business_type": "COMPANY",
    "country": "US",
    "legal_name": "ACME TRADING INC",
    "trading_name": "ACME",
    "registration_number": "84-1234567",
    "tax_id": "84-1234567",
    "incorporation_date": "20190315",
    "registered_address": {
        "line1": "500 Market St",
        "line2": "Suite 200",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94105",
        "country": "US"
    },
    "contact": {
        "name": "John Doe",
        "email": "finance@acme.example",
        "phone": "+14155550100"
    },
    "payout_method": {
        "merchant_payout_method_reference": "PM-US-0001",
        "label": "ACME 주거래",
        "bank_account": {
            "route": "OVERSEAS_BANK",
            "currency": "USD",
            "account_holder_name": "ACME TRADING INC",
            "account_holder_type": "COMPANY",
            "bank_country": "US",
            "swift_bic": "CHASUS33XXX",
            "account_number": "1234567890",
            "bank_name": "JPMORGAN CHASE BANK, N.A.",
            "bank_address": {
                "line1": "270 Park Avenue",
                "city": "New York",
                "state": "NY",
                "postal_code": "10017",
                "country": "US"
            },
            "beneficiary_address": {
                "line1": "500 Market St",
                "city": "San Francisco",
                "state": "CA",
                "postal_code": "94105",
                "country": "US"
            }
        }
    }
}
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

submall object *서브몰 정보입니다.

필수

submall_id string(32)

필수
Eximbay 가 발급한 서브몰 ID 입니다. 이후 모든 API 에서 이 서브몰을 지정하는 값이며 sm_ + Base36 24자입니다.

merchant_submall_reference string(100)

필수
가맹점이 지정한 값입니다. 변경할 수 없습니다.

submall_status string(50)

필수
서브몰 상태입니다. 7종입니다.
DRAFT

: 등록됨. 서류 요청 전

REQUIREMENTS_DUE

: 서류 요청 링크 발급됨

ACTION_REQUIRED

: 제출 서류 보완 필요

UNDER_REVIEW

: 서류 제출 완료 · 심사 중

ACTIVE

: KYB 승인. 지급 가능

RESTRICTED

: AML · 재심사 제한

DEACTIVATED

: 서비스 종료

business_type string(50)

필수
사업자 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

country string(2)

필수
심사 범위와 안내 언어의 근거가 되는 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

legal_name string(200)

필수
법인명 · 상호입니다.

trading_name string(200)|null

필수
거래상 사용하는 이름입니다.

registration_number string(100)

필수
사업자 등록번호입니다.

tax_id string(100)|null

필수
세금 식별번호입니다.

incorporation_date string(8)|null

필수
설립일입니다.

registered_address Address *등기주소입니다.

필수

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

operating_address Address|null *영업주소입니다.

필수
등록하지 않았으면 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

contact Contact *담당자 연락처입니다.

필수

name string(100)

필수
담당자명입니다.

email string(254)

필수
담당자 이메일 주소입니다. 서류 요청 링크가 이 주소로 발송됩니다.

phone string(30)

담당자 전화번호입니다. E.164 표기를 권장합니다.

kyb_completed_dt datetime|null

필수
심사 완료 시각입니다. 미완료면 null 입니다.

payout_method_count int

필수
등록된 수취수단 수입니다. ARCHIVED 는 제외합니다. 계좌를 함께 등록했으면 1 입니다.

payout_method_id string(32)|null

필수
함께 등록한 수취계좌 ID 입니다. pm_ + Base36 24자이며 요청에 payout_method 가 없었으면 null 입니다. 서브몰 등록 응답에만 있습니다 — 목록 · 단건 조회 · 수정 응답에는 없습니다. 계좌 상세는 수취계좌 단건조회 로 조회합니다.

created_dt datetime

필수
생성 시각입니다.

updated_dt datetime

필수
수정 시각입니다.
응답 201 Created — ① 서브몰만 등록 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "submall": {
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "merchant_submall_reference": "SELLER-US-00042",
        "submall_status": "DRAFT",
        "business_type": "COMPANY",
        "country": "US",
        "legal_name": "ACME TRADING INC",
        "trading_name": "ACME",
        "registration_number": "84-1234567",
        "tax_id": "84-1234567",
        "incorporation_date": "20190315",
        "registered_address": {
            "line1": "500 Market St",
            "line2": "Suite 200",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94105",
            "country": "US"
        },
        "operating_address": null,
        "contact": {
            "name": "John Doe",
            "email": "finance@acme.example",
            "phone": "+14155550100"
        },
        "kyb_completed_dt": null,
        "payout_method_count": 0,
        "payout_method_id": null,
        "created_dt": "2026-08-26 12:00:00",
        "updated_dt": "2026-08-26 12:00:00"
    }
}
응답 201 Created — ② 서브몰 + 수취계좌 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "submall": {
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "merchant_submall_reference": "SELLER-US-00042",
        "submall_status": "DRAFT",
        "business_type": "COMPANY",
        "country": "US",
        "legal_name": "ACME TRADING INC",
        "trading_name": "ACME",
        "registration_number": "84-1234567",
        "tax_id": "84-1234567",
        "incorporation_date": "20190315",
        "registered_address": {
            "line1": "500 Market St",
            "line2": "Suite 200",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94105",
            "country": "US"
        },
        "operating_address": null,
        "contact": {
            "name": "John Doe",
            "email": "finance@acme.example",
            "phone": "+14155550100"
        },
        "kyb_completed_dt": null,
        "payout_method_count": 1,
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "created_dt": "2026-08-26 12:00:00",
        "updated_dt": "2026-08-26 12:00:00"
    }
}

•  등록 응답은 서브몰 단건 조회에 payout_method_id 하나가 더 붙은 구조입니다. 등록 직후에는 submall_status 가 DRAFT, kyb_completed_dt 이 null 입니다.
•  payout_method_count 는 계좌를 함께 등록했으면 1, 아니면 0 입니다.
•  함께 등록한 계좌는 payout_method_status 가 PENDING 으로 접수됩니다. 계좌명의 검증은 KYB 심사가 끝난 뒤에 시작하므로 서브몰이 ACTIVE 가 될 때까지 PENDING 에 머뭅니다.

서브몰 목록

GET /v2/submalls

조건에 맞는 서브몰을 조회합니다.
요청 파라미터

submall_status string(100) · Query

서브몰 상태입니다. 7종이며 쉼표로 복수 지정할 수 있습니다.

country string(2) · Query

서브몰의 국가로 조회합니다. ISO 3166-1 alpha-2 대문자 2자입니다.

merchant_submall_reference string(100) · Query

가맹점이 지정한 서브몰 식별값으로 조회합니다. 완전 일치로 검색합니다.
요청 

// (1) 심사 중인 서브몰
GET /v2/submalls?submall_status=UNDER_REVIEW

// (2) 지급 가능한 미국 서브몰
GET /v2/submalls?submall_status=ACTIVE&country=US
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

submalls list *서브몰 등록 응답과 같은 구조입니다.

필수

submall_id string(32)

필수
Eximbay 가 발급한 서브몰 ID 입니다. 이후 모든 API 에서 이 서브몰을 지정하는 값이며 sm_ + Base36 24자입니다.

merchant_submall_reference string(100)

필수
가맹점이 지정한 값입니다. 변경할 수 없습니다.

submall_status string(50)

필수
서브몰 상태입니다. 7종입니다.
DRAFT

: 등록됨. 서류 요청 전

REQUIREMENTS_DUE

: 서류 요청 링크 발급됨

ACTION_REQUIRED

: 제출 서류 보완 필요

UNDER_REVIEW

: 서류 제출 완료 · 심사 중

ACTIVE

: KYB 승인. 지급 가능

RESTRICTED

: AML · 재심사 제한

DEACTIVATED

: 서비스 종료

business_type string(50)

필수
사업자 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

country string(2)

필수
심사 범위와 안내 언어의 근거가 되는 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

legal_name string(200)

필수
법인명 · 상호입니다.

trading_name string(200)|null

필수
거래상 사용하는 이름입니다.

registration_number string(100)

필수
사업자 등록번호입니다.

tax_id string(100)|null

필수
세금 식별번호입니다.

incorporation_date string(8)|null

필수
설립일입니다.

registered_address Address *등기주소입니다.

필수

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

operating_address Address|null *영업주소입니다.

필수
등록하지 않았으면 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

contact Contact *담당자 연락처입니다.

필수

name string(100)

필수
담당자명입니다.

email string(254)

필수
담당자 이메일 주소입니다. 서류 요청 링크가 이 주소로 발송됩니다.

phone string(30)

담당자 전화번호입니다. E.164 표기를 권장합니다.

kyb_completed_dt datetime|null

필수
심사 완료 시각입니다. 미완료면 null 입니다.

payout_method_count int

필수
등록된 수취수단 수입니다. ARCHIVED 는 제외합니다.

created_dt datetime

필수
생성 시각입니다.

updated_dt datetime

필수
수정 시각입니다.
응답 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "submalls": [
        {
            "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
            "merchant_submall_reference": "SELLER-US-00042",
            "submall_status": "ACTIVE",
            "business_type": "COMPANY",
            "country": "US",
            "legal_name": "ACME TRADING INC",
            "trading_name": "ACME",
            "registration_number": "84-1234567",
            "tax_id": "84-1234567",
            "incorporation_date": "20190315",
            "registered_address": {
                "line1": "500 Market St", "line2": "Suite 200",
                "city": "San Francisco", "state": "CA",
                "postal_code": "94105", "country": "US"
            },
            "operating_address": null,
            "contact": {
                "name": "John Doe", "email": "finance@acme.example", "phone": "+14155550100"
            },
            "kyb_completed_dt": "2026-08-24 17:00:00",
            "payout_method_count": 1,
            "created_dt": "2026-08-20 12:00:00",
            "updated_dt": "2026-08-24 17:00:00"
        }
    ]
}

서브몰 단건 조회

GET /v2/submalls/{submall_id}

서브몰 한 건을 조회합니다. 가맹점은 이 API 로 온보딩 진행 상황을 조회합니다. 응답은 서브몰 등록에서 payout_method_id 하나만 빠진 구조입니다.
요청 파라미터

submall_id string(32) · Path

필수
대상 서브몰의 ID 입니다. 서브몰 등록 응답의 submall_id 를 사용합니다. sm_ 로 시작합니다.
요청 

GET /v2/submalls/sm_7k3qx9zp2mnvb8tlcy4wjf6h
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

submall object *서브몰 정보입니다.

필수

submall_id string(32)

필수
Eximbay 가 발급한 서브몰 ID 입니다. 이후 모든 API 에서 이 서브몰을 지정하는 값이며 sm_ + Base36 24자입니다.

merchant_submall_reference string(100)

필수
가맹점이 지정한 값입니다. 변경할 수 없습니다.

submall_status string(50)

필수
서브몰 상태입니다. 7종입니다.
DRAFT

: 등록됨. 서류 요청 전

REQUIREMENTS_DUE

: 서류 요청 링크 발급됨

ACTION_REQUIRED

: 제출 서류 보완 필요

UNDER_REVIEW

: 서류 제출 완료 · 심사 중

ACTIVE

: KYB 승인. 지급 가능

RESTRICTED

: AML · 재심사 제한

DEACTIVATED

: 서비스 종료

business_type string(50)

필수
사업자 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

country string(2)

필수
심사 범위와 안내 언어의 근거가 되는 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

legal_name string(200)

필수
법인명 · 상호입니다.

trading_name string(200)|null

필수
거래상 사용하는 이름입니다.

registration_number string(100)

필수
사업자 등록번호입니다.

tax_id string(100)|null

필수
세금 식별번호입니다.

incorporation_date string(8)|null

필수
설립일입니다.

registered_address Address *등기주소입니다.

필수

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

operating_address Address|null *영업주소입니다.

필수
등록하지 않았으면 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

contact Contact *담당자 연락처입니다.

필수

name string(100)

필수
담당자명입니다.

email string(254)

필수
담당자 이메일 주소입니다. 서류 요청 링크가 이 주소로 발송됩니다.

phone string(30)

담당자 전화번호입니다. E.164 표기를 권장합니다.

kyb_completed_dt datetime|null

필수
심사 완료 시각입니다. 미완료면 null 입니다.

payout_method_count int

필수
등록된 수취수단 수입니다. ARCHIVED 는 제외합니다.

created_dt datetime

필수
생성 시각입니다.

updated_dt datetime

필수
수정 시각입니다.
응답 200 OK 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "submall": {
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "merchant_submall_reference": "SELLER-US-00042",
        "submall_status": "ACTIVE",
        "business_type": "COMPANY",
        "country": "US",
        "legal_name": "ACME TRADING INC",
        "trading_name": "ACME",
        "registration_number": "84-1234567",
        "tax_id": "84-1234567",
        "incorporation_date": "20190315",
        "registered_address": {
            "line1": "500 Market St",
            "line2": "Suite 200",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94105",
            "country": "US"
        },
        "operating_address": null,
        "contact": {
            "name": "John Doe",
            "email": "finance@acme.example",
            "phone": "+14155550100"
        },
        "kyb_completed_dt": "2026-08-24 17:00:00",
        "payout_method_count": 1,
        "created_dt": "2026-08-20 12:00:00",
        "updated_dt": "2026-08-24 17:00:00"
    }
}

진행에 따라 바뀌는 필드

•  submall_status (string) — 심사가 진행되어 상태가 변경될 때
•  kyb_completed_dt (datetime|null) — KYB 승인이 완료될 때
•  payout_method_count (int) — 수취계좌를 등록 · 폐기할 때

서브몰 수정

POST /v2/submalls/{submall_id}/update

보낸 필드만 바뀝니다. 보내지 않은 필드는 그대로 유지됩니다.

•  객체 필드는 부분 병합이 아니라 전체 교체입니다. contact 를 보내면서 phone 을 생략하면 phone 이 null 이 됩니다.
•  수정할 수 없는 필드를 요청에 포함하면 400 invalid_request 로 거절합니다.

요청 파라미터

submall_id string(32) · Path

필수
대상 서브몰의 ID 입니다. 서브몰 등록 응답의 submall_id 를 사용합니다. sm_ 로 시작합니다.

trading_name string(200) · Body

거래상 사용하는 이름입니다.

registered_address Address · Body*등기주소입니다.

객체 전체를 덮어씁니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

operating_address Address · Body*영업주소입니다.

객체 전체를 덮어씁니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

contact Contact · Body*담당자 연락처입니다.

객체 전체를 덮어씁니다.

name string(100)

필수
담당자명입니다.

email string(254)

필수
담당자 이메일 주소입니다. 서류 요청 링크가 이 주소로 발송됩니다.

phone string(30)

담당자 전화번호입니다. E.164 표기를 권장합니다.
요청 

{
    "trading_name": "ACME GLOBAL",
    "contact": {
        "name": "Jane Roe",
        "email": "ap@acme.example",
        "phone": "+14155550188"
    }
}

수정할 수 없는 필드

•  legal_name · country · registration_number · business_type — KYB 재심사 대상입니다. country 는 심사 범위와 안내 언어를 결정하므로 변경 시 재심사가 필요합니다.
•  tax_id · incorporation_date — 이 API 로는 수정할 수 없습니다. 요청에 포함하면 400 invalid_request 로 거절합니다.
•  merchant_submall_reference — 변경할 수 없습니다. 가맹점이 지정한 식별자입니다.

응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

submall object *서브몰 정보입니다.

필수

submall_id string(32)

필수
Eximbay 가 발급한 서브몰 ID 입니다. 이후 모든 API 에서 이 서브몰을 지정하는 값이며 sm_ + Base36 24자입니다.

merchant_submall_reference string(100)

필수
가맹점이 지정한 값입니다. 변경할 수 없습니다.

submall_status string(50)

필수
서브몰 상태입니다. 7종입니다.
DRAFT

: 등록됨. 서류 요청 전

REQUIREMENTS_DUE

: 서류 요청 링크 발급됨

ACTION_REQUIRED

: 제출 서류 보완 필요

UNDER_REVIEW

: 서류 제출 완료 · 심사 중

ACTIVE

: KYB 승인. 지급 가능

RESTRICTED

: AML · 재심사 제한

DEACTIVATED

: 서비스 종료

business_type string(50)

필수
사업자 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

country string(2)

필수
심사 범위와 안내 언어의 근거가 되는 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

legal_name string(200)

필수
법인명 · 상호입니다.

trading_name string(200)|null

필수
거래상 사용하는 이름입니다.

registration_number string(100)

필수
사업자 등록번호입니다.

tax_id string(100)|null

필수
세금 식별번호입니다.

incorporation_date string(8)|null

필수
설립일입니다.

registered_address Address *등기주소입니다.

필수

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

operating_address Address|null *영업주소입니다.

필수
등록하지 않았으면 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

contact Contact *담당자 연락처입니다.

필수

name string(100)

필수
담당자명입니다.

email string(254)

필수
담당자 이메일 주소입니다. 서류 요청 링크가 이 주소로 발송됩니다.

phone string(30)

담당자 전화번호입니다. E.164 표기를 권장합니다.

kyb_completed_dt datetime|null

필수
심사 완료 시각입니다. 미완료면 null 입니다.

payout_method_count int

필수
등록된 수취수단 수입니다. ARCHIVED 는 제외합니다.

created_dt datetime

필수
생성 시각입니다.

updated_dt datetime

필수
수정 시각입니다.
응답 200 OK 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "submall": {
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "merchant_submall_reference": "SELLER-US-00042",
        "submall_status": "ACTIVE",
        "business_type": "COMPANY",
        "country": "US",
        "legal_name": "ACME TRADING INC",
        "trading_name": "ACME GLOBAL",
        "registration_number": "84-1234567",
        "tax_id": "84-1234567",
        "incorporation_date": "20190315",
        "registered_address": {
            "line1": "500 Market St",
            "line2": "Suite 200",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94105",
            "country": "US"
        },
        "operating_address": null,
        "contact": {
            "name": "Jane Roe",
            "email": "ap@acme.example",
            "phone": "+14155550188"
        },
        "kyb_completed_dt": "2026-08-24 17:00:00",
        "payout_method_count": 1,
        "created_dt": "2026-08-20 12:00:00",
        "updated_dt": "2026-08-26 19:15:00"
    }
}

수취계좌 관리

수취계좌 등록

POST /v2/submalls/{submall_id}/payout-methods

서브몰의 수취계좌를 등록합니다. 서브몰이 ACTIVE 가 아니어도 등록할 수 있습니다 — DRAFT 부터 가능하며, 계좌는 PENDING 으로 접수됩니다. 같은 Body 를 서브몰 등록의 payout_method 로도 보낼 수 있습니다.

•  account_holder_name 은 서브몰 명의여야 합니다.
•  계좌번호는 응답에서 항상 마스킹(뒤 5자리)되며 원문을 되돌려주지 않습니다.

요청 파라미터

submall_id string(32) · Path

필수
대상 서브몰의 ID 입니다. 서브몰 등록 응답의 submall_id 를 사용합니다. sm_ 로 시작합니다.

merchant_payout_method_reference string(100) · Body

필수
가맹점이 지정하는 식별값입니다. 가맹점 내에서 유일해야 합니다.

label string(100) · Body

가맹점용 별칭입니다.

bank_account object · Body*계좌 정보입니다.

필수
route 에 따라 필수 필드가 달라집니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체.

OVERSEAS_BANK

: 해외 계좌이체. 허용 통화는 KRW USD JPY EUR 입니다.

currency string(3)

필수
계좌 통화입니다. 이 값이 지급통화가 됩니다.

account_holder_name string(200)

필수
예금주명입니다. 서브몰 명의여야 합니다.

account_holder_type string(50)

필수
예금주 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

bank_country string(2)

필수
계좌가 개설된 은행 소재 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

account_number string(64)

필수
계좌번호입니다.

domestic_bank_code string(20)

계좌를 개설한 은행을 지정하는 국내 은행 코드입니다. DOMESTIC_BANK 일 때 필수입니다. 은행 코드

swift_bic string(11)

수취 은행을 국제적으로 식별하는 SWIFT/BIC 코드입니다. OVERSEAS_BANK 일 때 필수이며 8자 또는 11자입니다.

bank_name string(200)

수취 은행명입니다. 해외송금 전문에 그대로 실리므로 영문 정식 명칭을 사용합니다. OVERSEAS_BANK 일 때 필수입니다.

bank_address Address *수취 은행의 주소입니다.

계좌가 개설된 은행 · 지점의 소재지이며, 해외송금 전문에 포함됩니다. OVERSEAS_BANK 일 때 필수입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

beneficiary_address Address *수취인의 주소입니다.

수취인은 돈을 받는 쪽, 즉 예금주인 서브몰이며 은행 주소가 아닙니다. 자금세탁방지 규정상 해외송금 전문에는 수취인의 이름 · 계좌번호와 함께 주소가 실려야 하고, 비어 있거나 부정확하면 중개은행에서 반송되거나 지급이 지연될 수 있습니다. OVERSEAS_BANK 일 때 필수입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

iban string(34)

국제 표준 계좌번호(IBAN)입니다. 국가 코드 · 검사숫자 · 계좌 식별자로 구성된 국제 표준 형식이며, IBAN 을 사용하는 국가일 때 필수입니다. 15~34자입니다.
요청 ① 국내 계좌이체 

{
    "merchant_payout_method_reference": "PM-KR-0001",
    "label": "아크메 주거래",
    "bank_account": {
        "route": "DOMESTIC_BANK",
        "currency": "KRW",
        "account_holder_name": "주식회사 아크메",
        "account_holder_type": "COMPANY",
        "bank_country": "KR",
        "domestic_bank_code": "088",
        "account_number": "1234567890123"
    }
}
요청 ② 해외 계좌이체 (USD) 

{
    "merchant_payout_method_reference": "PM-US-0001",
    "bank_account": {
        "route": "OVERSEAS_BANK",
        "currency": "USD",
        "account_holder_name": "ACME TRADING INC",
        "account_holder_type": "COMPANY",
        "bank_country": "US",
        "swift_bic": "CHASUS33XXX",
        "account_number": "1234567890",
        "bank_name": "JPMORGAN CHASE BANK, N.A.",
        "bank_address": {
            "line1": "270 Park Avenue",
            "city": "New York",
            "state": "NY",
            "postal_code": "10017",
            "country": "US"
        },
        "beneficiary_address": {
            "line1": "500 Market St",
            "city": "San Francisco",
            "state": "CA",
            "postal_code": "94105",
            "country": "US"
        }
    }
}
요청 ③ 해외 계좌이체 (동일 통화 KRW) 

{
    "merchant_payout_method_reference": "PM-JP-KRW-0001",
    "bank_account": {
        "route": "OVERSEAS_BANK",
        "currency": "KRW",
        "account_holder_name": "ACME JAPAN K.K.",
        "account_holder_type": "COMPANY",
        "bank_country": "JP",
        "swift_bic": "BOTKJPJT",
        "account_number": "9876543210",
        "bank_name": "MUFG BANK, LTD.",
        "bank_address": {
            "line1": "2-7-1 Marunouchi", "city": "Chiyoda-ku", "state": "Tokyo",
            "postal_code": "100-8388", "country": "JP"
        },
        "beneficiary_address": {
            "line1": "1-1-1 Shibuya", "city": "Shibuya-ku", "state": "Tokyo",
            "postal_code": "150-0002", "country": "JP"
        }
    }
}
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

payout_method object *수취계좌 정보입니다.

필수

payout_method_id string(32)

필수
Eximbay 가 발급한 수취계좌 ID 입니다. 지급 견적 요청의 payout_method_id 에 사용하며 pm_ + Base36 24자입니다.

merchant_payout_method_reference string(100)

필수
가맹점이 지정한 값입니다.

submall_id string(32)

필수
소속 서브몰입니다.

payout_method_status string(50)

필수
수취계좌 상태입니다.
PENDING

: 검증 중 — 지급 불가

ACTIVE

: 지급 가능

REJECTED

: 검증 실패

ARCHIVED

: 폐기됨

label string(100)|null

필수
가맹점용 별칭입니다.

bank_account object *계좌 정보입니다.

필수
계좌번호는 항상 마스킹되어 반환됩니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

currency string(3)

필수
지급통화입니다.

account_holder_name string(200)

필수
예금주명입니다.

account_holder_type string(50)

필수
예금주 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

bank_country string(2)

필수
은행 소재 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

account_number_masked string(64)

필수
마스킹된 계좌번호입니다. 뒤 5자리를 * 로 가리며, 원문을 되돌려주지 않습니다.

domestic_bank_code string(20)|null

필수
국내 은행 코드입니다. DOMESTIC_BANK 일 때만 값이 있고 그 외에는 null 입니다. 은행 코드

swift_bic string(11)|null

필수
수취 은행의 SWIFT/BIC 코드입니다. OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

bank_name string(200)|null

필수
수취 은행명입니다.

bank_address Address|null *수취 은행의 주소입니다.

필수
OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

beneficiary_address Address|null *수취인(예금주인 서브몰)의 주소입니다.

필수
해외송금 전문에 실리는 값이며, OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

iban_masked string(64)|null

필수
마스킹된 IBAN 입니다. 앞 4자와 뒤 4자만 노출하며 원문을 되돌려주지 않습니다. IBAN 을 등록한 계좌에만 값이 있습니다.

created_dt datetime

필수
생성 시각입니다.

updated_dt datetime

필수
수정 시각입니다.
응답 ① 201 국내 계좌이체 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout_method": {
        "payout_method_id": "pm_7c4vq9zx2km5bp1tlcy8wjfa",
        "merchant_payout_method_reference": "PM-KR-0001",
        "submall_id": "sm_1a5qx8zp3mnvb6tlcy2wjf9h",
        "payout_method_status": "PENDING",
        "label": "아크메 주거래",
        "bank_account": {
            "route": "DOMESTIC_BANK",
            "currency": "KRW",
            "account_holder_name": "주식회사 아크메",
            "account_holder_type": "COMPANY",
            "bank_country": "KR",
            "account_number_masked": "12345678*****",
            "domestic_bank_code": "088",
            "swift_bic": null,
            "bank_name": null,
            "bank_address": null,
            "beneficiary_address": null,
            "iban_masked": null
        },
        "created_dt": "2026-08-26 12:12:00",
        "updated_dt": "2026-08-26 12:12:00"
    }
}
응답 ② 201 해외 계좌이체 (USD) 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout_method": {
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "merchant_payout_method_reference": "PM-US-0001",
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_status": "PENDING",
        "label": null,
        "bank_account": {
            "route": "OVERSEAS_BANK",
            "currency": "USD",
            "account_holder_name": "ACME TRADING INC",
            "account_holder_type": "COMPANY",
            "bank_country": "US",
            "account_number_masked": "12345*****",
            "domestic_bank_code": null,
            "swift_bic": "CHASUS33XXX",
            "bank_name": "JPMORGAN CHASE BANK, N.A.",
            "bank_address": {
                "line1": "270 Park Avenue", "city": "New York",
                "state": "NY", "postal_code": "10017", "country": "US"
            },
            "beneficiary_address": {
                "line1": "500 Market St", "city": "San Francisco",
                "state": "CA", "postal_code": "94105", "country": "US"
            },
            "iban_masked": null
        },
        "created_dt": "2026-08-26 12:10:00",
        "updated_dt": "2026-08-26 12:10:00"
    }
}
응답 ③ 201 해외 계좌이체 (동일 통화 KRW) 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout_method": {
        "payout_method_id": "pm_9k2vq6zx3km8bp4tlcy7wjfe",
        "merchant_payout_method_reference": "PM-JP-KRW-0001",
        "submall_id": "sm_3d9qx2zp7mnvb4tlcy8wjf1h",
        "payout_method_status": "PENDING",
        "label": null,
        "bank_account": {
            "route": "OVERSEAS_BANK",
            "currency": "KRW",
            "account_holder_name": "ACME JAPAN K.K.",
            "account_holder_type": "COMPANY",
            "bank_country": "JP",
            "account_number_masked": "98765*****",
            "domestic_bank_code": null,
            "swift_bic": "BOTKJPJT",
            "bank_name": "MUFG BANK, LTD.",
            "bank_address": {
                "line1": "2-7-1 Marunouchi", "city": "Chiyoda-ku",
                "state": "Tokyo", "postal_code": "100-8388", "country": "JP"
            },
            "beneficiary_address": {
                "line1": "1-1-1 Shibuya", "city": "Shibuya-ku",
                "state": "Tokyo", "postal_code": "150-0002", "country": "JP"
            },
            "iban_masked": null
        },
        "created_dt": "2026-08-26 12:15:00",
        "updated_dt": "2026-08-26 12:15:00"
    }
}

수취계좌 목록

GET /v2/submalls/{submall_id}/payout-methods

서브몰의 수취계좌를 조회합니다. Query 파라미터가 없습니다. 전량을 한 번에 반환합니다.
요청 파라미터

submall_id string(32) · Path

필수
대상 서브몰의 ID 입니다. 서브몰 등록 응답의 submall_id 를 사용합니다. sm_ 로 시작합니다.
요청 

GET /v2/submalls/sm_7k3qx9zp2mnvb8tlcy4wjf6h/payout-methods
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

payout_methods list *수취계좌 등록 응답과 같은 구조입니다.

필수
ARCHIVED 를 포함한 전량입니다.

payout_method_id string(32)

필수
Eximbay 가 발급한 수취계좌 ID 입니다. 지급 견적 요청의 payout_method_id 에 사용하며 pm_ + Base36 24자입니다.

merchant_payout_method_reference string(100)

필수
가맹점이 지정한 값입니다.

submall_id string(32)

필수
소속 서브몰입니다.

payout_method_status string(50)

필수
수취계좌 상태입니다.
PENDING

: 검증 중 — 지급 불가

ACTIVE

: 지급 가능

REJECTED

: 검증 실패

ARCHIVED

: 폐기됨

label string(100)|null

필수
가맹점용 별칭입니다.

bank_account object *계좌 정보입니다.

필수
계좌번호는 항상 마스킹되어 반환됩니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

currency string(3)

필수
지급통화입니다.

account_holder_name string(200)

필수
예금주명입니다.

account_holder_type string(50)

필수
예금주 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

bank_country string(2)

필수
은행 소재 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

account_number_masked string(64)

필수
마스킹된 계좌번호입니다. 뒤 5자리를 * 로 가리며, 원문을 되돌려주지 않습니다.

domestic_bank_code string(20)|null

필수
국내 은행 코드입니다. DOMESTIC_BANK 일 때만 값이 있고 그 외에는 null 입니다. 은행 코드

swift_bic string(11)|null

필수
수취 은행의 SWIFT/BIC 코드입니다. OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

bank_name string(200)|null

필수
수취 은행명입니다.

bank_address Address|null *수취 은행의 주소입니다.

필수
OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

beneficiary_address Address|null *수취인(예금주인 서브몰)의 주소입니다.

필수
해외송금 전문에 실리는 값이며, OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

iban_masked string(64)|null

필수
마스킹된 IBAN 입니다. 앞 4자와 뒤 4자만 노출하며 원문을 되돌려주지 않습니다. IBAN 을 등록한 계좌에만 값이 있습니다.

created_dt datetime

필수
생성 시각입니다.

updated_dt datetime

필수
수정 시각입니다.
응답 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout_methods": [
        {
            "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
            "merchant_payout_method_reference": "PM-US-0001",
            "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
            "payout_method_status": "ACTIVE",
            "label": null,
            "bank_account": {
                "route": "OVERSEAS_BANK",
                "currency": "USD",
                "account_holder_name": "ACME TRADING INC",
                "account_holder_type": "COMPANY",
                "bank_country": "US",
                "account_number_masked": "12345*****",
                "domestic_bank_code": null,
                "swift_bic": "CHASUS33XXX",
                "bank_name": "JPMORGAN CHASE BANK, N.A.",
                "bank_address": {
                    "line1": "270 Park Avenue", "city": "New York",
                    "state": "NY", "postal_code": "10017", "country": "US"
                },
                "beneficiary_address": {
                    "line1": "500 Market St", "city": "San Francisco",
                    "state": "CA", "postal_code": "94105", "country": "US"
                },
                "iban_masked": null
            },
            "created_dt": "2026-08-26 12:10:00",
            "updated_dt": "2026-08-26 14:30:00"
        }
    ]
}

수취계좌 단건 조회

GET /v2/submalls/{submall_id}/payout-methods/{method_id}

수취계좌 한 건을 조회합니다. 응답은 수취계좌 등록과 완전히 같은 구조입니다.
요청 파라미터

submall_id string(32) · Path

필수
대상 서브몰의 ID 입니다. 서브몰 등록 응답의 submall_id 를 사용합니다. sm_ 로 시작합니다.

method_id string(32) · Path

필수
대상 수취계좌의 ID 입니다. 수취계좌 등록 응답의 payout_method_id 를 사용합니다. pm_ 로 시작합니다.
요청 

GET /v2/submalls/sm_7k3qx9zp2mnvb8tlcy4wjf6h/payout-methods/pm_4n8vq2zx7km3bp9tlcy5wjfd
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

payout_method object *수취계좌 정보입니다.

필수

payout_method_id string(32)

필수
Eximbay 가 발급한 수취계좌 ID 입니다. 지급 견적 요청의 payout_method_id 에 사용하며 pm_ + Base36 24자입니다.

merchant_payout_method_reference string(100)

필수
가맹점이 지정한 값입니다.

submall_id string(32)

필수
소속 서브몰입니다.

payout_method_status string(50)

필수
수취계좌 상태입니다.
PENDING

: 검증 중 — 지급 불가

ACTIVE

: 지급 가능

REJECTED

: 검증 실패

ARCHIVED

: 폐기됨

label string(100)|null

필수
가맹점용 별칭입니다.

bank_account object *계좌 정보입니다.

필수
계좌번호는 항상 마스킹되어 반환됩니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

currency string(3)

필수
지급통화입니다.

account_holder_name string(200)

필수
예금주명입니다.

account_holder_type string(50)

필수
예금주 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

bank_country string(2)

필수
은행 소재 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

account_number_masked string(64)

필수
마스킹된 계좌번호입니다. 뒤 5자리를 * 로 가리며, 원문을 되돌려주지 않습니다.

domestic_bank_code string(20)|null

필수
국내 은행 코드입니다. DOMESTIC_BANK 일 때만 값이 있고 그 외에는 null 입니다. 은행 코드

swift_bic string(11)|null

필수
수취 은행의 SWIFT/BIC 코드입니다. OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

bank_name string(200)|null

필수
수취 은행명입니다.

bank_address Address|null *수취 은행의 주소입니다.

필수
OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

beneficiary_address Address|null *수취인(예금주인 서브몰)의 주소입니다.

필수
해외송금 전문에 실리는 값이며, OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

iban_masked string(64)|null

필수
마스킹된 IBAN 입니다. 앞 4자와 뒤 4자만 노출하며 원문을 되돌려주지 않습니다. IBAN 을 등록한 계좌에만 값이 있습니다.

created_dt datetime

필수
생성 시각입니다.

updated_dt datetime

필수
수정 시각입니다.
응답 ① 200 검증 완료 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout_method": {
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "merchant_payout_method_reference": "PM-US-0001",
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_status": "ACTIVE",
        "label": null,
        "bank_account": {
            "route": "OVERSEAS_BANK",
            "currency": "USD",
            "account_holder_name": "ACME TRADING INC",
            "account_holder_type": "COMPANY",
            "bank_country": "US",
            "account_number_masked": "12345*****",
            "domestic_bank_code": null,
            "swift_bic": "CHASUS33XXX",
            "bank_name": "JPMORGAN CHASE BANK, N.A.",
            "bank_address": {
                "line1": "270 Park Avenue", "city": "New York",
                "state": "NY", "postal_code": "10017", "country": "US"
            },
            "beneficiary_address": {
                "line1": "500 Market St", "city": "San Francisco",
                "state": "CA", "postal_code": "94105", "country": "US"
            },
            "iban_masked": null
        },
        "created_dt": "2026-08-26 12:10:00",
        "updated_dt": "2026-08-26 14:30:00"
    }
}
응답 ② 200 검증 실패 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout_method": {
        "payout_method_id": "pm_8b3vq5zx9km2bp7tlcy4wjfc",
        "merchant_payout_method_reference": "PM-US-0002",
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_status": "REJECTED",
        "label": null,
        "bank_account": {
            "route": "OVERSEAS_BANK",
            "currency": "USD",
            "account_holder_name": "ACME TRADING",
            "account_holder_type": "COMPANY",
            "bank_country": "US",
            "account_number_masked": "87654*****",
            "domestic_bank_code": null,
            "swift_bic": "CHASUS33XXX",
            "bank_name": "JPMORGAN CHASE BANK, N.A.",
            "bank_address": {
                "line1": "270 Park Avenue", "city": "New York",
                "state": "NY", "postal_code": "10017", "country": "US"
            },
            "beneficiary_address": {
                "line1": "500 Market St", "city": "San Francisco",
                "state": "CA", "postal_code": "94105", "country": "US"
            },
            "iban_masked": null
        },
        "created_dt": "2026-08-26 13:00:00",
        "updated_dt": "2026-08-26 15:15:00"
    }
}

수취계좌 폐기

POST /v2/submalls/{submall_id}/payout-methods/{method_id}/archive

삭제(DELETE)가 아닙니다. 지급 이력이 이 계좌를 참조하므로 ARCHIVED 로 표시만 합니다.

•  본문이 비어 있어도 됩니다. {} 를 보내도 폐기됩니다.
•  이미 ARCHIVED 인 수단을 다시 폐기해도 같은 응답이 반환됩니다.

요청 파라미터

submall_id string(32) · Path

필수
대상 서브몰의 ID 입니다. 서브몰 등록 응답의 submall_id 를 사용합니다. sm_ 로 시작합니다.

method_id string(32) · Path

필수
대상 수취계좌의 ID 입니다. 수취계좌 등록 응답의 payout_method_id 를 사용합니다. pm_ 로 시작합니다.

reason string(255) · Body

가맹점 내부 사유입니다.
요청 

{
    "reason": "계좌 변경으로 기존 수단 폐기"
}
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

payout_method object *수취계좌 정보입니다.

필수

payout_method_id string(32)

필수
Eximbay 가 발급한 수취계좌 ID 입니다. 지급 견적 요청의 payout_method_id 에 사용하며 pm_ + Base36 24자입니다.

merchant_payout_method_reference string(100)

필수
가맹점이 지정한 값입니다.

submall_id string(32)

필수
소속 서브몰입니다.

payout_method_status string(50)

필수
수취계좌 상태입니다.
PENDING

: 검증 중 — 지급 불가

ACTIVE

: 지급 가능

REJECTED

: 검증 실패

ARCHIVED

: 폐기됨

label string(100)|null

필수
가맹점용 별칭입니다.

bank_account object *계좌 정보입니다.

필수
계좌번호는 항상 마스킹되어 반환됩니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

currency string(3)

필수
지급통화입니다.

account_holder_name string(200)

필수
예금주명입니다.

account_holder_type string(50)

필수
예금주 유형입니다.
COMPANY

: 법인

INDIVIDUAL_BUSINESS

: 개인사업자

bank_country string(2)

필수
은행 소재 국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

account_number_masked string(64)

필수
마스킹된 계좌번호입니다. 뒤 5자리를 * 로 가리며, 원문을 되돌려주지 않습니다.

domestic_bank_code string(20)|null

필수
국내 은행 코드입니다. DOMESTIC_BANK 일 때만 값이 있고 그 외에는 null 입니다. 은행 코드

swift_bic string(11)|null

필수
수취 은행의 SWIFT/BIC 코드입니다. OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

bank_name string(200)|null

필수
수취 은행명입니다.

bank_address Address|null *수취 은행의 주소입니다.

필수
OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

beneficiary_address Address|null *수취인(예금주인 서브몰)의 주소입니다.

필수
해외송금 전문에 실리는 값이며, OVERSEAS_BANK 일 때만 값이 있고 그 외에는 null 입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.

iban_masked string(64)|null

필수
마스킹된 IBAN 입니다. 앞 4자와 뒤 4자만 노출하며 원문을 되돌려주지 않습니다. IBAN 을 등록한 계좌에만 값이 있습니다.

created_dt datetime

필수
생성 시각입니다.

updated_dt datetime

필수
수정 시각입니다.
응답 200 OK 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout_method": {
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "merchant_payout_method_reference": "PM-US-0001",
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_status": "ARCHIVED",
        "label": null,
        "bank_account": {
            "route": "OVERSEAS_BANK",
            "currency": "USD",
            "account_holder_name": "ACME TRADING INC",
            "account_holder_type": "COMPANY",
            "bank_country": "US",
            "account_number_masked": "12345*****",
            "domestic_bank_code": null,
            "swift_bic": "CHASUS33XXX",
            "bank_name": "JPMORGAN CHASE BANK, N.A.",
            "bank_address": {
                "line1": "270 Park Avenue", "city": "New York",
                "state": "NY", "postal_code": "10017", "country": "US"
            },
            "beneficiary_address": {
                "line1": "500 Market St", "city": "San Francisco",
                "state": "CA", "postal_code": "94105", "country": "US"
            },
            "iban_masked": null
        },
        "created_dt": "2026-08-26 12:10:00",
        "updated_dt": "2026-08-28 11:40:00"
    }
}

지급 관리

지급 정책 조회

GET /v2/payouts/policies

지급경로 · 통화별 한도와 수수료, 부가세율, 운영시간을 조회합니다. 정책 행의 키는 route + currency 입니다.

•  요율은 안내값입니다. 실제 적용 수수료 · 부가세 · 차감액은 견적이 확정합니다.

요청 파라미터

route string(50) · Query

조회할 지급경로입니다. 지정하지 않으면 전체를 조회합니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

currency string(3) · Query

조회할 지급통화입니다. 지정하지 않으면 전체를 조회합니다.
KRW USD JPY EUR
요청 

GET /v2/payouts/policies?route=OVERSEAS_BANK&currency=USD
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

policies list *정책 행 목록입니다.

필수

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

currency string(3)

필수
지급 통화입니다.

min_payout_amount Money

필수
최소 지급금액입니다.

max_payout_amount Money|null

필수
1건당 최대 지급금액입니다. null 이면 은행 · 규제 한도를 따릅니다.

vat_rate string

필수
부가세율입니다. decimal 문자열이며 현재 값은 0.1 입니다.

operating_hours object *견적을 만들 수 있는 시간대입니다.

필수
국내 · 해외를 가리지 않습니다.

start string(5)

필수
견적을 발급할 수 있는 시작 시각입니다. HH:mm 형식이며 현재 값은 09:00 입니다.

end string(5)

필수
견적을 발급할 수 있는 종료 시각입니다. HH:mm 형식이며 현재 값은 24:00 입니다.

fees list(object) *이 정책 행에 적용되는 수수료 목록입니다.

필수

type string

필수
수수료 종류입니다.
TRANSFER_FEE

: 송금 수수료

PAYOUT_SERVICE_FEE

: 지급대행 서비스 수수료

calculation_type string(10)

필수
산정 방식입니다.
FIXED

: 정액

RATE

: 요율

amount Money|null

정액 수수료 금액입니다. calculation_type 이 FIXED 일 때만 값이 있습니다.

rate string|null

수수료 요율입니다. 소수로 표기하며 0.002 는 0.2% 를 뜻합니다. calculation_type 이 RATE 일 때만 값이 있으며 decimal 문자열입니다.

basis string(50)

필수
요율의 적용 기준입니다.
PER_PAYOUT

: 지급 건당

PAYOUT_AMOUNT

: 지급 원금 기준

응답 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "policies": [
        {
            "route": "DOMESTIC_BANK",
            "currency": "KRW",
            "min_payout_amount": { "currency": "KRW", "value": "10000" },
            "max_payout_amount": { "currency": "KRW", "value": "100000000" },
            "vat_rate": "0.1",
            "operating_hours": { "start": "09:00", "end": "24:00" },
            "fees": [
                { "type": "PAYOUT_SERVICE_FEE", "calculation_type": "FIXED",
                  "amount": { "currency": "KRW", "value": "500" }, "rate": null,
                  "basis": "PER_PAYOUT" }
            ]
        },
        {
            "route": "OVERSEAS_BANK",
            "currency": "USD",
            "min_payout_amount": { "currency": "USD", "value": "100.00" },
            "max_payout_amount": null,
            "vat_rate": "0.1",
            "operating_hours": { "start": "09:00", "end": "24:00" },
            "fees": [
                { "type": "TRANSFER_FEE", "calculation_type": "FIXED",
                  "amount": { "currency": "USD", "value": "10.00" }, "rate": null,
                  "basis": "PER_PAYOUT" },
                { "type": "PAYOUT_SERVICE_FEE", "calculation_type": "RATE",
                  "amount": null, "rate": "0.002",
                  "basis": "PAYOUT_AMOUNT" }
            ]
        },
        {
            "route": "OVERSEAS_BANK",
            "currency": "KRW",
            "min_payout_amount": { "currency": "KRW", "value": "140000" },
            "max_payout_amount": null,
            "vat_rate": "0.1",
            "operating_hours": { "start": "09:00", "end": "24:00" },
            "fees": [
                { "type": "TRANSFER_FEE", "calculation_type": "FIXED",
                  "amount": { "currency": "KRW", "value": "14000" }, "rate": null,
                  "basis": "PER_PAYOUT" },
                { "type": "PAYOUT_SERVICE_FEE", "calculation_type": "RATE",
                  "amount": null, "rate": "0.002",
                  "basis": "PAYOUT_AMOUNT" }
            ]
        },
        {
            "route": "OVERSEAS_BANK",
            "currency": "JPY",
            "min_payout_amount": { "currency": "JPY", "value": "15000" },
            "max_payout_amount": null,
            "vat_rate": "0.1",
            "operating_hours": { "start": "09:00", "end": "24:00" },
            "fees": [
                { "type": "TRANSFER_FEE", "calculation_type": "FIXED",
                  "amount": { "currency": "JPY", "value": "1500" }, "rate": null,
                  "basis": "PER_PAYOUT" },
                { "type": "PAYOUT_SERVICE_FEE", "calculation_type": "RATE",
                  "amount": null, "rate": "0.002",
                  "basis": "PAYOUT_AMOUNT" }
            ]
        },
        {
            "route": "OVERSEAS_BANK",
            "currency": "EUR",
            "min_payout_amount": { "currency": "EUR", "value": "90.00" },
            "max_payout_amount": null,
            "vat_rate": "0.1",
            "operating_hours": { "start": "09:00", "end": "24:00" },
            "fees": [
                { "type": "TRANSFER_FEE", "calculation_type": "FIXED",
                  "amount": { "currency": "EUR", "value": "10.00" }, "rate": null,
                  "basis": "PER_PAYOUT" },
                { "type": "PAYOUT_SERVICE_FEE", "calculation_type": "RATE",
                  "amount": null, "rate": "0.002",
                  "basis": "PAYOUT_AMOUNT" }
            ]
        }
    ]
}

잔액 조회

GET /v2/payouts/balances

가맹점의 통화별 계좌 잔액을 조회합니다. 계좌는 통화당 1개이며, 응답의 account_id 를 견적의 funding_account_id 와 환전의 from_account_id · to_account_id 에 사용합니다.

•  별도의 계좌 조회 엔드포인트가 없습니다. 계좌에 대해 알아야 할 값(account_id · 잔액)을 이 응답이 모두 제공합니다.

요청 파라미터

currency string(3) · Query

조회할 통화입니다. 지정하지 않으면 보유 통화 전체를 조회합니다.
요청 

GET /v2/payouts/balances?currency=USD
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

accounts list *가맹점 계좌 목록입니다.

필수
통화당 1개입니다.

account_id string(32)

필수
Eximbay 가 발급한 가맹점 계좌 ID 입니다. acc_ + Base36 24자이며, 견적의 funding_account_id, 환전의 from_account_id · to_account_id 에 사용합니다.

currency string(3)

필수
ISO 4217. 이 계좌의 통화입니다.

available_amount Money

필수
지금 지급 · 환전에 사용할 수 있는 금액입니다.

reserved_amount Money

필수
SCHEDULED REQUIRES_REVIEW ACTION_REQUIRED PROCESSING 지급건이 보류 중인 금액입니다.
응답 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "accounts": [
        {
            "account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
            "currency": "KRW",
            "available_amount": { "currency": "KRW", "value": "125000000" },
            "reserved_amount":  { "currency": "KRW", "value": "3500000" }
        },
        {
            "account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
            "currency": "USD",
            "available_amount": { "currency": "USD", "value": "0.00" },
            "reserved_amount":  { "currency": "USD", "value": "0.00" }
        }
    ]
}

환전 견적 생성

POST /v2/payouts/exchange-quotes

가맹점 계좌 사이의 환전 환율과 금액을 조회합니다. 이 호출은 잔액을 옮기지 않습니다.

•  00:00 ~ 09:00 에는 환전 견적을 조회할 수 없습니다.
•  이 견적은 잔액을 보류하지 않습니다.

요청 파라미터

from_account_id string(32) · Body

필수
acc_ 로 시작합니다. 파는 통화 계좌입니다.

to_account_id string(32) · Body

필수
acc_ 로 시작합니다. 사는 통화 계좌이며 from_account_id 와 달라야 합니다.

exchange_basis string(20) · Body

필수
requested_amount 를 어느 쪽 금액으로 읽을지 결정합니다.
SELL

: 파는 금액 — from 계좌에서 뺄 금액. 통화는 from 계좌 통화이며 Eximbay가 to_amount 를 계산합니다.

BUY

: 사는 금액 — to 계좌에 넣을 금액. 통화는 to 계좌 통화이며 Eximbay가 from_amount 를 계산합니다.

requested_amount Money · Body*요청 금액입니다.

필수

currency string(3)

필수
SELL 이면 from 계좌 통화, BUY 면 to 계좌 통화입니다.

value string

필수
금액입니다. decimal 문자열이며 통화별 소수 자릿수를 따릅니다.
요청 ① BUY 

{
    "from_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
    "to_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
    "exchange_basis": "BUY",
    "requested_amount": { "currency": "USD", "value": "10033.00" }
}
요청 ② SELL 

{
    "from_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
    "to_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
    "exchange_basis": "SELL",
    "requested_amount": { "currency": "KRW", "value": "14000000" }
}

•  BUY 가 주 경로입니다. 실제 사용 순서가 “지급에 필요한 금액을 확인 → 그만큼 환전 → 지급”이기 때문입니다.

응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

exchange_quote object *환전 견적 정보입니다.

필수

exchange_quote_id string(32)

필수
Eximbay 가 발급한 환전 견적 ID 입니다. 환전 실행 요청에 사용하며 exq_ + Base36 24자입니다.

exchange_quote_status string(50)

필수
환전 견적의 상태입니다.
ACTIVE

: 사용 가능

CONSUMED

: 해당 견적 사용 완료

EXPIRED

: 발급 당일 23:59:59 경과

from_account_id string(32)

필수
파는 통화 계좌입니다.

to_account_id string(32)

필수
사는 통화 계좌입니다.

exchange_basis string(20)

필수
견적 요청 때 지정한 금액 기준입니다. 요청값을 그대로 되돌려줍니다.

from_amount Money

필수
from 계좌에서 빠질 금액입니다.

to_amount Money

필수
to 계좌에 들어올 금액입니다.

exchange_rate string

필수
고시환율입니다. 소수 8자리입니다.

rate_quoted_dt datetime

필수
환율 기준 시각입니다.

expires_dt datetime

필수
견적 만료 시각입니다. 발급 당일 23:59:59 고정입니다.

created_dt datetime

필수
생성 시각입니다.
응답 ① BUY 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "exchange_quote": {
        "exchange_quote_id": "exq_5n7kx3bq9zm2vp6tlcy8wjfa",
        "exchange_quote_status": "ACTIVE",
        "from_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
        "to_account_id":   "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "exchange_basis":  "BUY",
        "from_amount":     { "currency": "KRW", "value": "14046200" },
        "to_amount":       { "currency": "USD", "value": "10033.00" },
        "exchange_rate":   "1400.00000000",
        "rate_quoted_dt":  "2026-08-27 10:00:00",
        "expires_dt":      "2026-08-27 23:59:59",
        "created_dt":      "2026-08-27 10:00:00"
    }
}

// from_amount = HALF_UP(10,033.00 x 1,400.00000000) = KRW 14,046,200
응답 ② SELL 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "exchange_quote": {
        "exchange_quote_id": "exq_7p4mkx9bq2zn6vr3tlcy5wjf",
        "exchange_quote_status": "ACTIVE",
        "from_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
        "to_account_id":   "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "exchange_basis":  "SELL",
        "from_amount":     { "currency": "KRW", "value": "14000000" },
        "to_amount":       { "currency": "USD", "value": "10000.00" },
        "exchange_rate":   "1400.00000000",
        "rate_quoted_dt":  "2026-08-27 10:00:00",
        "expires_dt":      "2026-08-27 23:59:59",
        "created_dt":      "2026-08-27 10:00:00"
    }
}

// to_amount = HALF_UP(14,000,000 / 1,400.00000000) = USD 10,000.00

환전 실행

POST /v2/payouts/exchanges

환전 견적을 사용해 두 계좌의 잔액을 옮깁니다. 실행 즉시 체결이며 취소 · 역환전이 없습니다.

•  금액 · 환율 · 계좌는 모두 견적이 확정한 값이므로 요청은 두 필드만 받습니다.
•  같은 exchange_quote_id 를 재요청 시 409 quote_already_used 로 거절 됩니다.

요청 파라미터

merchant_exchange_reference string(100) · Body

필수
가맹점이 지정하는 환전 식별값입니다. 가맹점 내에서 유일해야 합니다.

exchange_quote_id string(32) · Body

필수
사용할 환전 견적의 ID 입니다. exq_ 로 시작하고, 상태가 ACTIVE 여야 합니다.
요청 

{
    "merchant_exchange_reference": "EX-2026-08-0001",
    "exchange_quote_id": "exq_5n7kx3bq9zm2vp6tlcy8wjfa"
}
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

exchange object *환전 정보입니다.

필수

exchange_id string(32)

필수
Eximbay 가 발급한 환전 ID 입니다. exc_ + Base36 24자입니다.

merchant_exchange_reference string(100)

필수
가맹점이 지정한 값입니다.

exchange_quote_id string(32)

필수
사용된 환전 견적의 ID 입니다.

from_account_id string(32)

필수
견적이 확정한 파는 통화 계좌입니다.

to_account_id string(32)

필수
견적이 확정한 사는 통화 계좌입니다.

exchange_basis string(20)

필수
견적이 확정한 값입니다.
SELL

: 파는 금액 기준

BUY

: 사는 금액 기준

from_amount Money

필수
from 계좌에서 실제로 빠진 금액입니다.

to_amount Money

필수
to 계좌에 실제로 들어온 금액입니다.

exchange_rate string

필수
적용된 환율입니다. 소수 8자리입니다.

rate_quoted_dt datetime

필수
환율 기준 시각입니다.

created_dt datetime

필수
체결 시각입니다.
응답 201 Created 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "exchange": {
        "exchange_id": "exc_2q8mkx5bp7zn3vr9tlcy4wjf",
        "merchant_exchange_reference": "EX-2026-08-0001",
        "exchange_quote_id": "exq_5n7kx3bq9zm2vp6tlcy8wjfa",
        "from_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
        "to_account_id":   "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "exchange_basis":  "BUY",
        "from_amount":     { "currency": "KRW", "value": "14046200" },
        "to_amount":       { "currency": "USD", "value": "10033.00" },
        "exchange_rate":   "1400.00000000",
        "rate_quoted_dt":  "2026-08-27 10:00:00",
        "created_dt":      "2026-08-27 10:02:13"
    }
}

•  이 시점에 요청한 exchange_quote_id 의 exchange_quote_status 는 CONSUMED 가 됩니다.

환전 이력 목록

GET /v2/payouts/exchanges

환전 이력을 조회합니다. 실제 환전 된 이력만 조회 됩니다.
요청 파라미터

merchant_exchange_reference string(100) · Query

가맹점이 지정한 환전 식별값으로 조회합니다. 완전 일치로 검색합니다.

from_currency string(3) · Query

파는 통화로 조회합니다. ISO 4217 통화 코드입니다.

to_currency string(3) · Query

사는 통화로 조회합니다. ISO 4217 통화 코드입니다.

created_from string(8) · Query

체결일 하한(이상)입니다. YYYYMMDD 형식입니다.

created_to string(8) · Query

체결일 상한(이하)입니다. YYYYMMDD 형식입니다.
요청 

GET /v2/payouts/exchanges?from_currency=KRW&to_currency=USD

GET /v2/payouts/exchanges?created_from=20260827&created_to=20260827
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

exchanges list *환전 실행 응답과 같은 구조입니다.

필수

exchange_id string(32)

필수
Eximbay 가 발급한 환전 ID 입니다. exc_ + Base36 24자입니다.

merchant_exchange_reference string(100)

필수
가맹점이 지정한 값입니다.

exchange_quote_id string(32)

필수
사용된 환전 견적의 ID 입니다.

from_account_id string(32)

필수
견적이 확정한 파는 통화 계좌입니다.

to_account_id string(32)

필수
견적이 확정한 사는 통화 계좌입니다.

exchange_basis string(20)

필수
견적이 확정한 값입니다.
SELL

: 파는 금액 기준

BUY

: 사는 금액 기준

from_amount Money

필수
from 계좌에서 실제로 빠진 금액입니다.

to_amount Money

필수
to 계좌에 실제로 들어온 금액입니다.

exchange_rate string

필수
적용된 환율입니다. 소수 8자리입니다.

rate_quoted_dt datetime

필수
환율 기준 시각입니다.

created_dt datetime

필수
체결 시각입니다.
응답 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "exchanges": [
        {
            "exchange_id": "exc_2q8mkx5bp7zn3vr9tlcy4wjf",
            "merchant_exchange_reference": "EX-2026-08-0001",
            "exchange_quote_id": "exq_5n7kx3bq9zm2vp6tlcy8wjfa",
            "from_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
            "to_account_id":   "acc_8m2vq4zx7km3bp9tlcy5wjfd",
            "exchange_basis":  "BUY",
            "from_amount":     { "currency": "KRW", "value": "14046200" },
            "to_amount":       { "currency": "USD", "value": "10033.00" },
            "exchange_rate":   "1400.00000000",
            "rate_quoted_dt":  "2026-08-27 10:00:00",
            "created_dt":      "2026-08-27 10:02:13"
        }
    ]
}

환전 단건 조회

GET /v2/payouts/exchanges/{exchange_id}

체결된 환전 한 건을 조회합니다. 응답은 환전 실행과 완전히 같은 구조입니다.

•  환전 견적에는 단건 조회를 두지 않습니다. 견적의 사용 여부는 환전 실행 응답과 환전 이력 목록이 알려줍니다.

요청 파라미터

exchange_id string(32) · Path

필수
조회할 환전의 ID 입니다. 환전 실행 응답의 exchange_id 를 사용합니다. exc_ + Base36 24자입니다.
요청 

GET /v2/payouts/exchanges/exc_2q8mkx5bp7zn3vr9tlcy4wjf
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

exchange object *환전 정보입니다.

필수

exchange_id string(32)

필수
Eximbay 가 발급한 환전 ID 입니다. exc_ + Base36 24자입니다.

merchant_exchange_reference string(100)

필수
가맹점이 지정한 값입니다.

exchange_quote_id string(32)

필수
사용된 환전 견적의 ID 입니다.

from_account_id string(32)

필수
견적이 확정한 파는 통화 계좌입니다.

to_account_id string(32)

필수
견적이 확정한 사는 통화 계좌입니다.

exchange_basis string(20)

필수
견적이 확정한 값입니다.
SELL

: 파는 금액 기준

BUY

: 사는 금액 기준

from_amount Money

필수
from 계좌에서 실제로 빠진 금액입니다.

to_amount Money

필수
to 계좌에 실제로 들어온 금액입니다.

exchange_rate string

필수
적용된 환율입니다. 소수 8자리입니다.

rate_quoted_dt datetime

필수
환율 기준 시각입니다.

created_dt datetime

필수
체결 시각입니다.
응답 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "exchange": {
        "exchange_id": "exc_2q8mkx5bp7zn3vr9tlcy4wjf",
        "merchant_exchange_reference": "EX-2026-08-0001",
        "exchange_quote_id": "exq_5n7kx3bq9zm2vp6tlcy8wjfa",
        "from_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
        "to_account_id":   "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "exchange_basis":  "BUY",
        "from_amount":     { "currency": "KRW", "value": "14046200" },
        "to_amount":       { "currency": "USD", "value": "10033.00" },
        "exchange_rate":   "1400.00000000",
        "rate_quoted_dt":  "2026-08-27 10:00:00",
        "created_dt":      "2026-08-27 10:02:13"
    }
}

견적 생성

POST /v2/payouts/quotes

지급 금액과 수수료를 조회합니다. 국내 · 해외 모두 필수입니다.

•  00:00 ~ 09:00 에는 견적을 만들 수 없습니다.
•  견적은 발급 당일 23:59:59 에 만료됩니다.
•  견적은 출금 계좌 잔액을 검증하므로 잔액이 부족할 경우 422 insufficient_payout_balance 로 응답합니다.

요청 파라미터

submall_id string(32) · Body

필수
지급 대상 서브몰입니다.

payout_method_id string(32) · Body

필수
지급에 사용할 수취계좌의 ID 입니다. 지급경로(route)와 지급통화가 이 값으로 결정됩니다.

funding_account_id string(32) · Body

필수
acc_ 로 시작합니다. 출금 계좌이며 통화가 지급통화와 같아야 합니다.

amount_basis string(50) · Body

필수
requested_amount 를 어느 기준으로 읽을지 결정합니다.
PAYOUT

: 지급 원금 — 서브몰에게 보낼 금액을 지정합니다.

WITHDRAWAL_LIMIT

: 출금 계좌에서 뺄 금액의 상한을 지정합니다. 이 금액을 넘지 않는 범위에서 최대로 견적합니다.

requested_amount Money · Body*요청 금액입니다.

필수

currency string(3)

필수
지급통화입니다.

value string

필수
금액입니다. decimal 문자열이며 통화별 소수 자릿수를 따릅니다.

fee_payer string(50) · Body

수수료 부담 주체입니다. 지정하지 않으면 MERCHANT 입니다.
MERCHANT

: 가맹점 부담 (기본값)

SUBMALL

: 서브몰 부담

요청 ① PAYOUT · 가맹점 부담 

{
    "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
    "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
    "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
    "amount_basis": "PAYOUT",
    "requested_amount": { "currency": "USD", "value": "10000.00" }
}
요청 ② WITHDRAWAL_LIMIT · 가맹점 부담 

{
    "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
    "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
    "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
    "amount_basis": "WITHDRAWAL_LIMIT",
    "requested_amount": { "currency": "USD", "value": "10000.00" }
}
요청 ③ PAYOUT · 서브몰 부담 

{
    "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
    "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
    "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
    "amount_basis": "PAYOUT",
    "requested_amount": { "currency": "USD", "value": "10000.00" },
    "fee_payer": "SUBMALL"
}
요청 ④ PAYOUT · 가맹점 부담 · 동일 통화 해외 

{
    "submall_id": "sm_3d9qx2zp7mnvb4tlcy8wjf1h",
    "payout_method_id": "pm_9k2vq6zx3km8bp4tlcy7wjfe",
    "funding_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
    "amount_basis": "PAYOUT",
    "requested_amount": { "currency": "KRW", "value": "5000000" }
}
요청 ⑤ PAYOUT · 가맹점 부담 · 국내 

{
    "submall_id": "sm_1a5qx8zp3mnvb6tlcy2wjf9h",
    "payout_method_id": "pm_7c4vq9zx2km5bp1tlcy8wjfa",
    "funding_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
    "amount_basis": "PAYOUT",
    "requested_amount": { "currency": "KRW", "value": "500000" }
}
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

quote object *지급 견적 정보입니다.

필수

quote_id string(32)

필수
Eximbay 가 발급한 지급 견적 ID 입니다. 지급 생성 요청에 사용하며 qte_ + Base36 24자입니다.

quote_status string(50)

필수
견적의 상태입니다.
ACTIVE

: 사용 가능

CONSUMED

: 해당 견적 사용 완료

EXPIRED

: 발급 당일 23:59:59 경과

route string(50)

필수
payout_method 가 결정한 지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

submall_id string(32)

필수
지급 대상 서브몰입니다.

payout_method_id string(32)

필수
지급에 사용할 수취계좌입니다.

funding_account_id string(32)

필수
요청값을 되돌려줍니다. 이 지급의 출금 계좌입니다.

amount_basis string(50)

필수
견적 요청 때 지정한 금액 기준입니다. 요청값을 그대로 되돌려줍니다.

fee_payer string(50)

필수
요청값입니다. 지정하지 않았다면 MERCHANT 입니다.

payout_amount Money

필수
지급 원금입니다. 통화는 지급통화입니다.

net_transfer_amount Money

필수
실제 송금 지시액입니다. MERCHANT 부담이면 원금과 같습니다.

fees list(Fee) *항목별 수수료입니다.

필수
통화는 항상 지급통화입니다.

type string

필수
수수료 종류입니다.
TRANSFER_FEE

: 송금 수수료 — 지급통화별 정액

PAYOUT_SERVICE_FEE

: 지급대행 서비스 수수료

amount Money

필수
공급가액입니다. 부가세를 제외한 금액입니다.

vat_amount Money

필수
세액입니다.

total_supply_amount Money

필수
공급가액 합계입니다. 과세표준입니다.

total_vat_amount Money

필수
세액 합계입니다.

total_fee_amount Money

필수
수수료 총액입니다. 부가세를 포함하며 앞의 두 값의 합입니다.

withdrawal_amount Money

필수
출금 계좌에서 실제로 빠지는 금액입니다.

expires_dt datetime

필수
견적 만료 시각입니다. 발급 당일 23:59:59 고정입니다.

created_dt datetime

필수
생성 시각입니다.
응답 ① PAYOUT · 가맹점 부담 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "quote": {
        "quote_id": "qte_9m2xk7bq4zn8vp3tlcy6wjfh",
        "quote_status": "ACTIVE",
        "route": "OVERSEAS_BANK",
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "amount_basis": "PAYOUT",
        "fee_payer": "MERCHANT",

        "payout_amount":       { "currency": "USD", "value": "10000.00" },
        "net_transfer_amount": { "currency": "USD", "value": "10000.00" },
        "fees": [
            { "type": "TRANSFER_FEE",
              "amount":     { "currency": "USD", "value": "10.00" },
              "vat_amount": { "currency": "USD", "value": "1.00" } },
            { "type": "PAYOUT_SERVICE_FEE",
              "amount":     { "currency": "USD", "value": "20.00" },
              "vat_amount": { "currency": "USD", "value": "2.00" } }
        ],
        "total_supply_amount": { "currency": "USD", "value": "30.00" },
        "total_vat_amount":    { "currency": "USD", "value": "3.00" },
        "total_fee_amount":    { "currency": "USD", "value": "33.00" },
        "withdrawal_amount":   { "currency": "USD", "value": "10033.00" },

        "expires_dt": "2026-08-27 23:59:59",
        "created_dt": "2026-08-27 10:04:00"
    }
}
응답 ② WITHDRAWAL_LIMIT · 가맹점 부담 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "quote": {
        "quote_id": "qte_5t8rmx2bq7zn4vp9tlcy3wjf",
        "quote_status": "ACTIVE",
        "route": "OVERSEAS_BANK",
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "amount_basis": "WITHDRAWAL_LIMIT",
        "fee_payer": "MERCHANT",

        "payout_amount":       { "currency": "USD", "value": "9967.08" },
        "net_transfer_amount": { "currency": "USD", "value": "9967.08" },
        "fees": [
            { "type": "TRANSFER_FEE",
              "amount":     { "currency": "USD", "value": "10.00" },
              "vat_amount": { "currency": "USD", "value": "1.00" } },
            { "type": "PAYOUT_SERVICE_FEE",
              "amount":     { "currency": "USD", "value": "19.93" },
              "vat_amount": { "currency": "USD", "value": "1.99" } }
        ],
        "total_supply_amount": { "currency": "USD", "value": "29.93" },
        "total_vat_amount":    { "currency": "USD", "value": "2.99" },
        "total_fee_amount":    { "currency": "USD", "value": "32.92" },
        "withdrawal_amount":   { "currency": "USD", "value": "10000.00" },

        "expires_dt": "2026-08-27 23:59:59",
        "created_dt": "2026-08-27 10:04:00"
    }
}
응답 ③ PAYOUT · 서브몰 부담 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "quote": {
        "quote_id": "qte_8w4nkx6bq3zm7vp2tlcy9wjf",
        "quote_status": "ACTIVE",
        "route": "OVERSEAS_BANK",
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "amount_basis": "PAYOUT",
        "fee_payer": "SUBMALL",

        "payout_amount":       { "currency": "USD", "value": "10000.00" },
        "net_transfer_amount": { "currency": "USD", "value": "9967.00" },
        "fees": [
            { "type": "TRANSFER_FEE",
              "amount":     { "currency": "USD", "value": "10.00" },
              "vat_amount": { "currency": "USD", "value": "1.00" } },
            { "type": "PAYOUT_SERVICE_FEE",
              "amount":     { "currency": "USD", "value": "20.00" },
              "vat_amount": { "currency": "USD", "value": "2.00" } }
        ],
        "total_supply_amount": { "currency": "USD", "value": "30.00" },
        "total_vat_amount":    { "currency": "USD", "value": "3.00" },
        "total_fee_amount":    { "currency": "USD", "value": "33.00" },
        "withdrawal_amount":   { "currency": "USD", "value": "10000.00" },

        "expires_dt": "2026-08-27 23:59:59",
        "created_dt": "2026-08-27 10:04:00"
    }
}
응답 ④ PAYOUT · 가맹점 부담 · 동일 통화 해외 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "quote": {
        "quote_id": "qte_2p7mkx9bq4zn8vp3tlcy6wjf",
        "quote_status": "ACTIVE",
        "route": "OVERSEAS_BANK",
        "submall_id": "sm_3d9qx2zp7mnvb4tlcy8wjf1h",
        "payout_method_id": "pm_9k2vq6zx3km8bp4tlcy7wjfe",
        "funding_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
        "amount_basis": "PAYOUT",
        "fee_payer": "MERCHANT",

        "payout_amount":       { "currency": "KRW", "value": "5000000" },
        "net_transfer_amount": { "currency": "KRW", "value": "5000000" },
        "fees": [
            { "type": "TRANSFER_FEE",
              "amount":     { "currency": "KRW", "value": "14000" },
              "vat_amount": { "currency": "KRW", "value": "1400" } },
            { "type": "PAYOUT_SERVICE_FEE",
              "amount":     { "currency": "KRW", "value": "10000" },
              "vat_amount": { "currency": "KRW", "value": "1000" } }
        ],
        "total_supply_amount": { "currency": "KRW", "value": "24000" },
        "total_vat_amount":    { "currency": "KRW", "value": "2400" },
        "total_fee_amount":    { "currency": "KRW", "value": "26400" },
        "withdrawal_amount":   { "currency": "KRW", "value": "5026400" },

        "expires_dt": "2026-08-27 23:59:59",
        "created_dt": "2026-08-27 10:04:00"
    }
}
응답 ⑤ PAYOUT · 가맹점 부담 · 국내 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "quote": {
        "quote_id": "qte_6j3nkx8bq5zm2vp7tlcy4wjf",
        "quote_status": "ACTIVE",
        "route": "DOMESTIC_BANK",
        "submall_id": "sm_1a5qx8zp3mnvb6tlcy2wjf9h",
        "payout_method_id": "pm_7c4vq9zx2km5bp1tlcy8wjfa",
        "funding_account_id": "acc_3k9qx7zp2mnvb8tlcy4wjf6h",
        "amount_basis": "PAYOUT",
        "fee_payer": "MERCHANT",

        "payout_amount":       { "currency": "KRW", "value": "500000" },
        "net_transfer_amount": { "currency": "KRW", "value": "500000" },
        "fees": [
            { "type": "PAYOUT_SERVICE_FEE",
              "amount":     { "currency": "KRW", "value": "500" },
              "vat_amount": { "currency": "KRW", "value": "50" } }
        ],
        "total_supply_amount": { "currency": "KRW", "value": "500" },
        "total_vat_amount":    { "currency": "KRW", "value": "50" },
        "total_fee_amount":    { "currency": "KRW", "value": "550" },
        "withdrawal_amount":   { "currency": "KRW", "value": "500550" },

        "expires_dt": "2026-08-27 23:59:59",
        "created_dt": "2026-08-27 10:04:00"
    }
}

견적 조회

GET /v2/payouts/quotes/{quote_id}

견적 내용과 사용 여부를 확인합니다.
요청 파라미터

quote_id string(32) · Path

필수
조회할 지급 견적의 ID 입니다. qte_ 로 시작합니다.
요청 

GET /v2/payouts/quotes/qte_9m2xk7bq4zn8vp3tlcy6wjfh
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

quote object *지급 견적 정보입니다.

필수

quote_id string(32)

필수
Eximbay 가 발급한 지급 견적 ID 입니다. 지급 생성 요청에 사용하며 qte_ + Base36 24자입니다.

quote_status string(50)

필수
견적의 상태입니다.
ACTIVE

: 사용 가능

CONSUMED

: 해당 견적 사용 완료

EXPIRED

: 발급 당일 23:59:59 경과

route string(50)

필수
payout_method 가 결정한 지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

submall_id string(32)

필수
지급 대상 서브몰입니다.

payout_method_id string(32)

필수
지급에 사용할 수취계좌입니다.

funding_account_id string(32)

필수
요청값을 되돌려줍니다. 이 지급의 출금 계좌입니다.

amount_basis string(50)

필수
견적 요청 때 지정한 금액 기준입니다. 요청값을 그대로 되돌려줍니다.

fee_payer string(50)

필수
요청값입니다. 지정하지 않았다면 MERCHANT 입니다.

payout_amount Money

필수
지급 원금입니다. 통화는 지급통화입니다.

net_transfer_amount Money

필수
실제 송금 지시액입니다. MERCHANT 부담이면 원금과 같습니다.

fees list(Fee) *항목별 수수료입니다.

필수
통화는 항상 지급통화입니다.

type string

필수
수수료 종류입니다.
TRANSFER_FEE

: 송금 수수료 — 지급통화별 정액

PAYOUT_SERVICE_FEE

: 지급대행 서비스 수수료

amount Money

필수
공급가액입니다. 부가세를 제외한 금액입니다.

vat_amount Money

필수
세액입니다.

total_supply_amount Money

필수
공급가액 합계입니다. 과세표준입니다.

total_vat_amount Money

필수
세액 합계입니다.

total_fee_amount Money

필수
수수료 총액입니다. 부가세를 포함하며 앞의 두 값의 합입니다.

withdrawal_amount Money

필수
출금 계좌에서 실제로 빠지는 금액입니다.

consumed_by_payout_id string(32)|null

필수
이 견적을 사용한 지급건입니다. 사용되지 않았으면 null 입니다. 견적 조회 응답에만 있습니다 — 견적 생성 응답에는 없습니다.

consumed_dt datetime|null

필수
견적 사용 시각입니다. 사용되지 않았으면 null 입니다. 견적 조회 응답에만 있습니다 — 견적 생성 응답에는 없습니다.

expires_dt datetime

필수
견적 만료 시각입니다. 발급 당일 23:59:59 고정입니다.

created_dt datetime

필수
견적 생성 시각입니다.
응답 ① 미사용 ACTIVE 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "quote": {
        "quote_id": "qte_9m2xk7bq4zn8vp3tlcy6wjfh",
        "quote_status": "ACTIVE",
        "route": "OVERSEAS_BANK",
        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "amount_basis": "PAYOUT",
        "fee_payer": "MERCHANT",

        "payout_amount":       { "currency": "USD", "value": "10000.00" },
        "net_transfer_amount": { "currency": "USD", "value": "10000.00" },
        "fees": [
            { "type": "TRANSFER_FEE",
              "amount":     { "currency": "USD", "value": "10.00" },
              "vat_amount": { "currency": "USD", "value": "1.00" } },
            { "type": "PAYOUT_SERVICE_FEE",
              "amount":     { "currency": "USD", "value": "20.00" },
              "vat_amount": { "currency": "USD", "value": "2.00" } }
        ],
        "total_supply_amount": { "currency": "USD", "value": "30.00" },
        "total_vat_amount":    { "currency": "USD", "value": "3.00" },
        "total_fee_amount":    { "currency": "USD", "value": "33.00" },
        "withdrawal_amount":   { "currency": "USD", "value": "10033.00" },

        "consumed_by_payout_id": null,
        "consumed_dt": null,
        "expires_dt": "2026-08-27 23:59:59",
        "created_dt": "2026-08-27 10:04:00"
    }
}
응답 ② 사용됨 CONSUMED 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "quote": {
        "quote_id": "qte_9m2xk7bq4zn8vp3tlcy6wjfh",
        "quote_status": "CONSUMED",
        "consumed_by_payout_id": "po_1f6nkx8bq2zm9vp3tlcy7wjf",
        "consumed_dt": "2026-08-27 10:06:00",
        "expires_dt": "2026-08-27 23:59:59",
        "created_dt": "2026-08-27 10:04:00"
    }
}

// 위 예시 ②는 지면상 금액 필드를 줄였습니다.
// 실제 응답에는 생성 시점의 금액 필드가 전량 그대로 실립니다.

지급 생성

POST /v2/payouts

견적을 사용해 지급을 만듭니다. 생성 즉시 SCHEDULED 이고 출금 계좌의 잔액이 보류됩니다.

•  scheduled_date 는 D+3 이후 · 영업일 기준입니다. 기산일은 견적 생성일입니다.

요청 파라미터

merchant_payout_reference string(100) · Body

필수
가맹점이 지정하는 지급 식별값입니다. 가맹점 내에서 유일해야 합니다.

submall_id string(32) · Body

필수
지급 대상 서브몰의 ID 입니다. 견적의 값과 일치해야 합니다.

quote_id string(32) · Body

필수
사용할 지급 견적의 ID 입니다. 1회만 사용할 수 있고 당일 발급분만 유효합니다.

scheduled_date string(8) · Body

필수
YYYYMMDD 형식입니다. D+3 이후 · 영업일이어야 합니다.

remittance_info string(255) · Body

필수
수취인에게 전달되는 적요입니다.

obligation_id string(100) · Body

가맹점 정산 채무 식별자입니다.

description string(500) · Body

가맹점 내부 메모입니다. 수취인에게 전달되지 않습니다.
요청 

{
    "merchant_payout_reference": "PO-2026-08-0001",
    "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
    "quote_id": "qte_9m2xk7bq4zn8vp3tlcy6wjfh",
    "scheduled_date": "20260901",
    "remittance_info": "2026-08 SETTLEMENT",
    "obligation_id": "STL-2026-08",
    "description": "8월 정산분 1차"
}
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

payout object *지급 정보입니다.

필수

payout_id string(32)

필수
Eximbay 가 발급한 지급 ID 입니다. 지급 조회 · 취소에 사용하며 po_ + Base36 24자입니다.

merchant_payout_reference string(100)

필수
가맹점이 지정한 값입니다.

payout_status string(50)

필수
지급 상태입니다. 9종이며 상태표에서 전체를 확인할 수 있습니다.
SCHEDULED

: 생성 즉시 진입. 출금 계좌 잔액 보류

REQUIRES_REVIEW

: 추가 심사 진행 중

ACTION_REQUIRED

: 심사에 추가 서류 필요. 보류 유지

PROCESSING

: 지정일 도래 · 지급망 처리 중

POSTED

: 지급망으로 출금 · 실행

DELIVERED

: 수취 확인

CANCELED

: 실행 전 취소. 보류 해제

NOT_COMPLETED

: 지급망 최종 거절 · 처리 불가. 보류 해제

RETURNED

: 실행 후 반환

submall_id string(32)

필수
지급 대상 서브몰입니다.

payout_method_id string(32)

필수
견적이 확정한 수취계좌입니다.

quote_id string(32)

필수
사용된 견적입니다.

funding_account_id string(32)

필수
출금 계좌입니다. 견적이 확정한 값입니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

fee_payer string(50)

필수
수수료 부담 주체입니다. 견적에서 확정된 값을 그대로 따릅니다.

payout_amount Money

필수
지급 원금입니다. 통화는 지급통화입니다.

net_transfer_amount Money

필수
실제 송금 지시액입니다. MERCHANT 부담이면 원금과 같습니다.

fees list(Fee) *항목별 수수료입니다.

필수
통화는 항상 지급통화입니다.

type string

필수
수수료 종류입니다.
TRANSFER_FEE

: 송금 수수료 — 지급통화별 정액

PAYOUT_SERVICE_FEE

: 지급대행 서비스 수수료

amount Money

필수
공급가액입니다. 부가세를 제외한 금액입니다.

vat_amount Money

필수
세액입니다.

total_supply_amount Money

필수
공급가액 합계입니다. 과세표준입니다.

total_vat_amount Money

필수
세액 합계입니다.

total_fee_amount Money

필수
수수료 총액입니다. 부가세를 포함하며 앞의 두 값의 합입니다.

withdrawal_amount Money

필수
출금 계좌에서 실제로 빠지는 금액입니다.

trace Trace|null

필수
지급망 추적 식별자입니다. POSTED 이전에는 null 입니다.

scheduled_date string(8)

필수
지급 요청일입니다.

remittance_info string(255)

필수
수취인에게 전달되는 적요입니다.

obligation_id string(100)|null

필수
가맹점 정산 채무 식별자입니다.

description string(500)|null

필수
가맹점 내부 메모입니다. 수취인에게 전달되지 않습니다.

created_dt datetime

필수
지급 생성 시각입니다.

updated_dt datetime

필수
마지막 수정 시각입니다. 지급 목록 조회의 updated_after 가 이 값을 기준으로 조회합니다.
응답 201 Created 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout": {
        "payout_id": "po_1f6nkx8bq2zm9vp3tlcy7wjf",
        "merchant_payout_reference": "PO-2026-08-0001",
        "payout_status": "SCHEDULED",

        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "quote_id": "qte_9m2xk7bq4zn8vp3tlcy6wjfh",
        "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "route": "OVERSEAS_BANK",
        "fee_payer": "MERCHANT",

        "payout_amount":       { "currency": "USD", "value": "10000.00" },
        "net_transfer_amount": { "currency": "USD", "value": "10000.00" },
        "fees": [
            { "type": "TRANSFER_FEE",
              "amount":     { "currency": "USD", "value": "10.00" },
              "vat_amount": { "currency": "USD", "value": "1.00" } },
            { "type": "PAYOUT_SERVICE_FEE",
              "amount":     { "currency": "USD", "value": "20.00" },
              "vat_amount": { "currency": "USD", "value": "2.00" } }
        ],
        "total_supply_amount": { "currency": "USD", "value": "30.00" },
        "total_vat_amount":    { "currency": "USD", "value": "3.00" },
        "total_fee_amount":    { "currency": "USD", "value": "33.00" },
        "withdrawal_amount":   { "currency": "USD", "value": "10033.00" },

        "trace": null,
        "scheduled_date": "20260901",
        "remittance_info": "2026-08 SETTLEMENT",
        "obligation_id": "STL-2026-08",
        "description": "8월 정산분 1차",
        "created_dt": "2026-08-27 10:06:00",
        "updated_dt": "2026-08-27 10:06:00"
    }
}

지급 목록

GET /v2/payouts

지급건을 조회합니다.
요청 파라미터

payout_status string(200) · Query

지급 상태입니다. 9종이며 쉼표로 복수 지정할 수 있습니다.

submall_id string(32) · Query

서브몰로 조회합니다.

route string(50) · Query

지급경로로 조회합니다. 지정하지 않으면 전체를 조회합니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

funding_account_id string(32) · Query

출금 계좌로 조회합니다.

merchant_payout_reference string(100) · Query

가맹점이 지정한 지급 식별값으로 조회합니다. 완전 일치로 검색합니다.

scheduled_from string(8) · Query

지급 요청일 하한(이상)입니다. YYYYMMDD 형식입니다.

scheduled_to string(8) · Query

지급 요청일 상한(이하)입니다. YYYYMMDD 형식입니다.

created_from string(8) · Query

지급 생성일 하한(이상)입니다. YYYYMMDD 형식입니다.

created_to string(8) · Query

지급 생성일 상한(이하)입니다. YYYYMMDD 형식이며, 그 날 하루 전체를 포함합니다.

updated_after string(8) · Query

이 날짜 이후 변경된 건만 조회합니다. YYYYMMDD 형식이며, 그 날 하루 전체를 포함합니다.
요청 

// (1) 변경분 폴링 - 가장 흔한 사용법
GET /v2/payouts?updated_after=20260827

// (2) 특정일 실행 예정인 건
GET /v2/payouts?payout_status=SCHEDULED&scheduled_from=20260901&scheduled_to=20260901

// (3) 종료되지 않은 건만 - ACTION_REQUIRED 는 되돌아오므로 포함한다
GET /v2/payouts?payout_status=SCHEDULED,REQUIRES_REVIEW,ACTION_REQUIRED,PROCESSING,POSTED
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

payouts list *지급 생성 응답과 같은 구조입니다.

필수

payout_id string(32)

필수
Eximbay 가 발급한 지급 ID 입니다. 지급 조회 · 취소에 사용하며 po_ + Base36 24자입니다.

merchant_payout_reference string(100)

필수
가맹점이 지정한 값입니다.

payout_status string(50)

필수
지급 상태입니다. 9종이며 상태표에서 전체를 확인할 수 있습니다.
SCHEDULED

: 생성 즉시 진입. 출금 계좌 잔액 보류

REQUIRES_REVIEW

: 추가 심사 진행 중

ACTION_REQUIRED

: 심사에 추가 서류 필요. 보류 유지

PROCESSING

: 지정일 도래 · 지급망 처리 중

POSTED

: 지급망으로 출금 · 실행

DELIVERED

: 수취 확인

CANCELED

: 실행 전 취소. 보류 해제

NOT_COMPLETED

: 지급망 최종 거절 · 처리 불가. 보류 해제

RETURNED

: 실행 후 반환

submall_id string(32)

필수
지급 대상 서브몰입니다.

payout_method_id string(32)

필수
견적이 확정한 수취계좌입니다.

quote_id string(32)

필수
사용된 견적입니다.

funding_account_id string(32)

필수
출금 계좌입니다. 견적이 확정한 값입니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

fee_payer string(50)

필수
수수료 부담 주체입니다. 견적에서 확정된 값을 그대로 따릅니다.

payout_amount Money

필수
지급 원금입니다. 통화는 지급통화입니다.

net_transfer_amount Money

필수
실제 송금 지시액입니다. MERCHANT 부담이면 원금과 같습니다.

fees list(Fee) *항목별 수수료입니다.

필수

type string

필수
수수료 종류입니다.
TRANSFER_FEE

: 송금 수수료 — 지급통화별 정액

PAYOUT_SERVICE_FEE

: 지급대행 서비스 수수료

amount Money

필수
공급가액입니다. 부가세를 제외한 금액입니다.

vat_amount Money

필수
세액입니다.

total_supply_amount Money

필수
공급가액 합계입니다. 과세표준입니다.

total_vat_amount Money

필수
세액 합계입니다.

total_fee_amount Money

필수
수수료 총액입니다. 부가세를 포함하며 앞의 두 값의 합입니다.

withdrawal_amount Money

필수
출금 계좌에서 실제로 빠지는 금액입니다.

trace Trace|null

필수
지급망 추적 식별자입니다. POSTED 이전에는 null 입니다.

scheduled_date string(8)

필수
지급 요청일입니다.

remittance_info string(255)

필수
수취인에게 전달되는 적요입니다.

obligation_id string(100)|null

필수
가맹점 정산 채무 식별자입니다.

description string(500)|null

필수
가맹점 내부 메모입니다. 수취인에게 전달되지 않습니다.

created_dt datetime

필수
지급 생성 시각입니다.

updated_dt datetime

필수
마지막 수정 시각입니다. 지급 목록 조회의 updated_after 가 이 값을 기준으로 조회합니다.
응답 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payouts": [
        {
            "payout_id": "po_1f6nkx8bq2zm9vp3tlcy7wjf",
            "merchant_payout_reference": "PO-2026-08-0001",
            "payout_status": "SCHEDULED",
            "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
            "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
            "quote_id": "qte_9m2xk7bq4zn8vp3tlcy6wjfh",
            "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
            "route": "OVERSEAS_BANK",
            "fee_payer": "MERCHANT",
            "payout_amount":       { "currency": "USD", "value": "10000.00" },
            "net_transfer_amount": { "currency": "USD", "value": "10000.00" },
            "fees": [
                { "type": "TRANSFER_FEE",
                  "amount":     { "currency": "USD", "value": "10.00" },
                  "vat_amount": { "currency": "USD", "value": "1.00" } },
                { "type": "PAYOUT_SERVICE_FEE",
                  "amount":     { "currency": "USD", "value": "20.00" },
                  "vat_amount": { "currency": "USD", "value": "2.00" } }
            ],
            "total_supply_amount": { "currency": "USD", "value": "30.00" },
            "total_vat_amount":    { "currency": "USD", "value": "3.00" },
            "total_fee_amount":    { "currency": "USD", "value": "33.00" },
            "withdrawal_amount":   { "currency": "USD", "value": "10033.00" },
            "trace": null,
            "scheduled_date": "20260901",
            "remittance_info": "2026-08 SETTLEMENT",
            "obligation_id": "STL-2026-08",
            "description": null,
            "created_dt": "2026-08-27 10:06:00",
            "updated_dt": "2026-08-27 10:06:00"
        }
    ]
}

지급 단건 조회

GET /v2/payouts/{payout_id}

지급건 한 건을 조회합니다.
요청 파라미터

payout_id string(32) · Path

필수
대상 지급건의 ID 입니다. po_ 로 시작합니다.
요청 

GET /v2/payouts/po_1f6nkx8bq2zm9vp3tlcy7wjf
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

payout object *지급 정보입니다.

필수

payout_id string(32)

필수
Eximbay 가 발급한 지급 ID 입니다. 지급 조회 · 취소에 사용하며 po_ + Base36 24자입니다.

merchant_payout_reference string(100)

필수
가맹점이 지정한 값입니다.

payout_status string(50)

필수
지급 상태입니다. 9종이며 상태표에서 전체를 확인할 수 있습니다.
SCHEDULED

: 생성 즉시 진입. 출금 계좌 잔액 보류

REQUIRES_REVIEW

: 추가 심사 진행 중

ACTION_REQUIRED

: 심사에 추가 서류 필요. 보류 유지

PROCESSING

: 지정일 도래 · 지급망 처리 중

POSTED

: 지급망으로 출금 · 실행

DELIVERED

: 수취 확인

CANCELED

: 실행 전 취소. 보류 해제

NOT_COMPLETED

: 지급망 최종 거절 · 처리 불가. 보류 해제

RETURNED

: 실행 후 반환

submall_id string(32)

필수
지급 대상 서브몰입니다.

payout_method_id string(32)

필수
견적이 확정한 수취계좌입니다.

quote_id string(32)

필수
사용된 견적입니다.

funding_account_id string(32)

필수
출금 계좌입니다. 견적이 확정한 값입니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

fee_payer string(50)

필수
수수료 부담 주체입니다. 견적에서 확정된 값을 그대로 따릅니다.

payout_amount Money

필수
지급 원금입니다. 통화는 지급통화입니다.

net_transfer_amount Money

필수
실제 송금 지시액입니다. MERCHANT 부담이면 원금과 같습니다.

fees list(Fee) *항목별 수수료입니다.

필수
통화는 항상 지급통화입니다.

type string

필수
수수료 종류입니다.
TRANSFER_FEE

: 송금 수수료 — 지급통화별 정액

PAYOUT_SERVICE_FEE

: 지급대행 서비스 수수료

amount Money

필수
공급가액입니다. 부가세를 제외한 금액입니다.

vat_amount Money

필수
세액입니다.

total_supply_amount Money

필수
공급가액 합계입니다. 과세표준입니다.

total_vat_amount Money

필수
세액 합계입니다.

total_fee_amount Money

필수
수수료 총액입니다. 부가세를 포함하며 앞의 두 값의 합입니다.

withdrawal_amount Money

필수
출금 계좌에서 실제로 빠지는 금액입니다.

trace Trace|null

필수
지급망 추적 식별자입니다. POSTED 이전에는 null 입니다.

scheduled_date string(8)

필수
지급 요청일입니다.

remittance_info string(255)

필수
수취인에게 전달되는 적요입니다.

obligation_id string(100)|null

필수
가맹점 정산 채무 식별자입니다.

description string(500)|null

필수
가맹점 내부 메모입니다. 수취인에게 전달되지 않습니다.

created_dt datetime

필수
지급 생성 시각입니다.

updated_dt datetime

필수
마지막 수정 시각입니다. 지급 목록 조회의 updated_after 가 이 값을 기준으로 조회합니다.
응답 ① SCHEDULED 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout": {
        "payout_id": "po_1f6nkx8bq2zm9vp3tlcy7wjf",
        "merchant_payout_reference": "PO-2026-08-0001",
        "payout_status": "SCHEDULED",

        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "quote_id": "qte_9m2xk7bq4zn8vp3tlcy6wjfh",
        "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "route": "OVERSEAS_BANK",
        "fee_payer": "MERCHANT",

        "payout_amount":       { "currency": "USD", "value": "10000.00" },
        "net_transfer_amount": { "currency": "USD", "value": "10000.00" },
        "fees": [
            { "type": "TRANSFER_FEE",
              "amount":     { "currency": "USD", "value": "10.00" },
              "vat_amount": { "currency": "USD", "value": "1.00" } },
            { "type": "PAYOUT_SERVICE_FEE",
              "amount":     { "currency": "USD", "value": "20.00" },
              "vat_amount": { "currency": "USD", "value": "2.00" } }
        ],
        "total_supply_amount": { "currency": "USD", "value": "30.00" },
        "total_vat_amount":    { "currency": "USD", "value": "3.00" },
        "total_fee_amount":    { "currency": "USD", "value": "33.00" },
        "withdrawal_amount":   { "currency": "USD", "value": "10033.00" },

        "trace": null,
        "scheduled_date": "20260901",
        "remittance_info": "2026-08 SETTLEMENT",
        "obligation_id": "STL-2026-08",
        "description": null,
        "created_dt": "2026-08-27 10:06:00",
        "updated_dt": "2026-08-27 10:06:00"
    }
}
응답 ② POSTED 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout": {
        "payout_id": "po_1f6nkx8bq2zm9vp3tlcy7wjf",
        "payout_status": "POSTED",
        "trace": { "type": "SWIFT_UETR", "value": "550e8400-e29b-41d4-a716-446655440000" },
        "scheduled_date": "20260901",
        "updated_dt": "2026-09-01 15:20:00"
    }
}
응답 ③ DELIVERED (국내) 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout": {
        "payout_id": "po_9f2mkx4bq7zn3vp8tlcy5wjd",
        "payout_status": "DELIVERED",
        "route": "DOMESTIC_BANK",
        "trace": { "type": "DOMESTIC_BANK_REFERENCE", "value": "20260901000123" },
        "scheduled_date": "20260901",
        "updated_dt": "2026-09-01 16:02:00"
    }
}
응답 ④ ACTION_REQUIRED 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout": {
        "payout_id": "po_1f6nkx8bq2zm9vp3tlcy7wjf",
        "payout_status": "ACTION_REQUIRED",
        "trace": null,
        "scheduled_date": "20260901",
        "updated_dt": "2026-08-31 11:40:00"
    }
}

// 종료 상태가 아닙니다. 보류가 유지되고,
// 서브몰이 서류를 다시 올리면 REQUIRES_REVIEW 로 되돌아갑니다.
응답 ⑤ NOT_COMPLETED 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout": {
        "payout_id": "po_4b7mkx2bq9zn5vp6tlcy8wjf",
        "payout_status": "NOT_COMPLETED",
        "trace": null,
        "scheduled_date": "20260901",
        "updated_dt": "2026-09-02 09:15:00"
    }
}

// 종료 상태입니다. 보류가 풀립니다.
응답 ⑥ RETURNED 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout": {
        "payout_id": "po_1f6nkx8bq2zm9vp3tlcy7wjf",
        "payout_status": "RETURNED",
        "trace": { "type": "SWIFT_UETR", "value": "550e8400-e29b-41d4-a716-446655440000" },
        "total_supply_amount": { "currency": "USD", "value": "30.00" },
        "total_vat_amount":    { "currency": "USD", "value": "3.00" },
        "total_fee_amount":    { "currency": "USD", "value": "33.00" },
        "withdrawal_amount":   { "currency": "USD", "value": "10033.00" },
        "updated_dt": "2026-09-04 07:12:00"
    }
}

// 금액 필드는 지급 시점 값 그대로입니다.
// 예시 (2)~(6) 은 지면상 바뀐 필드만 표시했습니다.
// 실제 응답에는 (1) 과 같은 필드가 전량 실립니다.

지급 취소

POST /v2/payouts/{payout_id}/cancel

payout_status 가 SCHEDULED 일 때만 취소할 수 있습니다. 성공하면 CANCELED 로 변경되고 출금 계좌의 보류 잔액을 해제합니다.

•  REQUIRES_REVIEW · ACTION_REQUIRED 에서는 취소할 수 없습니다. 심사가 진행 중인 건이며 보류도 유지됩니다.
•  본문이 비어 있어도 됩니다. reason 만 있는 선택 필드이므로 {} 를 보내도 취소됩니다.

요청 파라미터

payout_id string(32) · Path

필수
대상 지급건의 ID 입니다. po_ 로 시작합니다.

reason string(255) · Body

가맹점 내부 사유입니다.
요청 

{
    "reason": "가맹점 요청으로 8월 정산 보류"
}
응답 파라미터

rescode string

필수
응답 코드입니다. 성공은 0000 입니다.

resmsg string

필수
응답 메시지입니다. 성공은 Success. 입니다.

payout object *지급 정보입니다.

필수

payout_id string(32)

필수
Eximbay 가 발급한 지급 ID 입니다. 지급 조회 · 취소에 사용하며 po_ + Base36 24자입니다.

merchant_payout_reference string(100)

필수
가맹점이 지정한 값입니다.

payout_status string(50)

필수
지급 상태입니다. 9종이며 상태표에서 전체를 확인할 수 있습니다.
SCHEDULED

: 생성 즉시 진입. 출금 계좌 잔액 보류

REQUIRES_REVIEW

: 추가 심사 진행 중

ACTION_REQUIRED

: 심사에 추가 서류 필요. 보류 유지

PROCESSING

: 지정일 도래 · 지급망 처리 중

POSTED

: 지급망으로 출금 · 실행

DELIVERED

: 수취 확인

CANCELED

: 실행 전 취소. 보류 해제

NOT_COMPLETED

: 지급망 최종 거절 · 처리 불가. 보류 해제

RETURNED

: 실행 후 반환

submall_id string(32)

필수
지급 대상 서브몰입니다.

payout_method_id string(32)

필수
견적이 확정한 수취계좌입니다.

quote_id string(32)

필수
사용된 견적입니다.

funding_account_id string(32)

필수
출금 계좌입니다. 견적이 확정한 값입니다.

route string(50)

필수
지급경로입니다.
DOMESTIC_BANK

: 국내 계좌이체

OVERSEAS_BANK

: 해외 계좌이체

fee_payer string(50)

필수
수수료 부담 주체입니다. 견적에서 확정된 값을 그대로 따릅니다.

payout_amount Money

필수
지급 원금입니다. 통화는 지급통화입니다.

net_transfer_amount Money

필수
실제 송금 지시액입니다. MERCHANT 부담이면 원금과 같습니다.

fees list(Fee) *항목별 수수료입니다.

필수
통화는 항상 지급통화입니다.

type string

필수
수수료 종류입니다.
TRANSFER_FEE

: 송금 수수료 — 지급통화별 정액

PAYOUT_SERVICE_FEE

: 지급대행 서비스 수수료

amount Money

필수
공급가액입니다. 부가세를 제외한 금액입니다.

vat_amount Money

필수
세액입니다.

total_supply_amount Money

필수
공급가액 합계입니다. 과세표준입니다.

total_vat_amount Money

필수
세액 합계입니다.

total_fee_amount Money

필수
수수료 총액입니다. 부가세를 포함하며 앞의 두 값의 합입니다.

withdrawal_amount Money

필수
출금 계좌에서 실제로 빠지는 금액입니다.

trace Trace|null

필수
지급망 추적 식별자입니다. POSTED 이전에는 null 입니다.

scheduled_date string(8)

필수
지급 요청일입니다.

remittance_info string(255)

필수
수취인에게 전달되는 적요입니다.

obligation_id string(100)|null

필수
가맹점 정산 채무 식별자입니다.

description string(500)|null

필수
가맹점 내부 메모입니다. 수취인에게 전달되지 않습니다.

created_dt datetime

필수
지급 생성 시각입니다.

updated_dt datetime

필수
마지막 수정 시각입니다. 지급 목록 조회의 updated_after 가 이 값을 기준으로 조회합니다.
응답 200 OK 

{
    "rescode": "0000",
    "resmsg": "Success.",
    "payout": {
        "payout_id": "po_1f6nkx8bq2zm9vp3tlcy7wjf",
        "merchant_payout_reference": "PO-2026-08-0001",
        "payout_status": "CANCELED",

        "submall_id": "sm_7k3qx9zp2mnvb8tlcy4wjf6h",
        "payout_method_id": "pm_4n8vq2zx7km3bp9tlcy5wjfd",
        "quote_id": "qte_9m2xk7bq4zn8vp3tlcy6wjfh",
        "funding_account_id": "acc_8m2vq4zx7km3bp9tlcy5wjfd",
        "route": "OVERSEAS_BANK",
        "fee_payer": "MERCHANT",

        "payout_amount":       { "currency": "USD", "value": "10000.00" },
        "net_transfer_amount": { "currency": "USD", "value": "10000.00" },
        "fees": [
            { "type": "TRANSFER_FEE",
              "amount":     { "currency": "USD", "value": "10.00" },
              "vat_amount": { "currency": "USD", "value": "1.00" } },
            { "type": "PAYOUT_SERVICE_FEE",
              "amount":     { "currency": "USD", "value": "20.00" },
              "vat_amount": { "currency": "USD", "value": "2.00" } }
        ],
        "total_supply_amount": { "currency": "USD", "value": "30.00" },
        "total_vat_amount":    { "currency": "USD", "value": "3.00" },
        "total_fee_amount":    { "currency": "USD", "value": "33.00" },
        "withdrawal_amount":   { "currency": "USD", "value": "10033.00" },

        "trace": null,
        "scheduled_date": "20260901",
        "remittance_info": "2026-08 SETTLEMENT",
        "obligation_id": "STL-2026-08",
        "description": null,
        "created_dt": "2026-08-27 10:06:00",
        "updated_dt": "2026-08-27 14:41:00"
    }
}

•  이미 CANCELED 인 건을 다시 취소해도 같은 응답이 반환됩니다.

전체 흐름

서브몰 등록 → 수취계좌 → KYC · KYB → 지급

지급 한 건이 나가기까지의 전 과정입니다. 가맹점이 직접 호출하는 것은 파란 실선이고 Eximbay 내부와 서브몰 · 지급망 사이에서 일어나는 일은 회색 점선입니다.

← 각 단계의 다이어그램은 좌우로 스크롤됩니다.

가맹점API 호출 주체
서브몰하위 가맹점
Eximbay API · 심사지급대행 플랫폼 · KYB/AML
지급망은행 · 송금망
1서브몰 등록

지급 대상이 될 하위 가맹점을 Eximbay 에 등록합니다.

  • payout_method 를 함께 보내면 2단계 수취계좌까지 한 번에 등록됩니다.
  • 등록 직후 서브몰은 DRAFT 입니다. 아직 지급 대상이 아닙니다.
POST /v2/submalls
201 Created · submall_id · DRAFT
2수취계좌 등록

서브몰이 실제로 돈을 받을 계좌를 등록합니다.

  • 1단계에서 payout_method 를 함께 보냈다면 이 단계는 생략합니다.
  • 서브몰이 아직 DRAFT 여도 계좌는 등록할 수 있습니다.
POST /v2/submalls/{submall_id}/payout-methods
201 Created · payout_method_id · PENDING
3KYC · KYB 심사

Eximbay 와 서브몰 사이에서 진행됩니다. 가맹점은 결과만 조회합니다.

  • 가맹점 API 에는 서류 제출 단계가 없습니다. 서류는 Eximbay 가 서브몰에게 직접 받습니다.
  • 서류 요청 링크는 Contact.email 로 발송됩니다.
  • 보완이 필요하면 ACTION_REQUIRED → 재제출 → UNDER_REVIEW 가 승인될 때까지 반복됩니다.
  • 계좌명의 검증은 KYB 승인 뒤에 시작합니다. 그전까지 계좌가 PENDING 인 것은 정상입니다.
서류 요청 링크 발송 · REQUIREMENTS_DUE
KYC · KYB 서류 제출 · UNDER_REVIEW
보완 요청 · ACTION_REQUIRED
서류 재제출 · UNDER_REVIEW 복귀
↻ 승인될 때까지 반복
KYB 승인 → ACTIVE · kyb_completed_dt 기록
계좌명의 검증 → 계좌 ACTIVE · 실패 시 REJECTED
GET /v2/submalls/{submall_id}
submall_status ACTIVE · payout_method_status ACTIVE
4환전조건부

출금 계좌 통화와 지급통화가 다를 때만 거칩니다.

  • 출금 계좌 통화 = 지급통화 이면 이 단계를 통째로 건너뜁니다.
  • 환전 견적은 당일 23:59:59 에 만료되고, 00:00 ~ 09:00 에는 만들 수 없습니다.
GET /v2/payouts/balances
통화별 available_amount · reserved_amount · account_id
POST /v2/payouts/exchange-quotes
exchange_quote_id · ACTIVE
POST /v2/payouts/exchanges
즉시 완결 · 견적 CONSUMED
5지급 처리

견적으로 금액을 확정하고, 지급을 만들고, 상태를 폴링합니다.

  • scheduled_date 는 견적일 기준 D+3 영업일 이후여야 합니다.
  • 견적은 00:00 ~ 09:00 에 만들 수 없고, 당일 23:59:59 에 만료됩니다.
  • 지급 생성 시 withdrawal_amount 만큼 잔액이 보류됩니다.
  • REQUIRES_REVIEW ⇄ ACTION_REQUIRED 는 해외 건만 거칩니다.
  • 취소는 SCHEDULED 에서만 됩니다. 실행이 시작되면 취소할 수 없습니다.
  • 자금이 돌아오면 RETURNED 입니다. 상태는 조회 API 폴링으로 확인합니다.
  • 괄호 숫자는 지급 상태 전이도의 선형 진행 순번입니다.
POST /v2/payouts/quotes
quote_id · ACTIVE · 수수료 확정
POST /v2/payouts · quote_id + scheduled_date
payout_id · SCHEDULED (1) · 잔액 보류
해외 건만 · REQUIRES_REVIEW (2) ⇄ ACTION_REQUIRED
scheduled_date 도래 → PROCESSING (3)
출금 · 지급망 실행
실행 완료 → POSTED (4) · 차감 확정
수취 확인 → DELIVERED (5)
GET /v2/payouts
payout_status 목록
POST /v2/payouts/{payout_id}/cancel → CANCELED
가맹점이 직접 호출 응답 · 내부 진행 · 외부 구간 ↻ = 승인될 때까지 반복되는 구간

•  계좌명의 검증은 KYB 승인 뒤에 시작합니다. 명의를 대조할 법인명이 심사로 확정되기 때문이며 그전까지 계좌는 PENDING 에 머뭅니다.
•  ACTION_REQUIRED 는 종료가 아닙니다. 서류를 다시 올리면 심사로 되돌아가고 그동안 보류 잔액도 풀리지 않습니다.

공통 규격

데이터 형식

요청 · 응답에 공통으로 적용되는 값의 표기 기준입니다.
형식 기준
JSON 필드명 snake_case
ID {접두}{소문자 Base36 24자}. 예: sm_7k3qx9zp2mnvb8tlcy4wjf6h
시각 KST · yyyy-MM-dd HH:mm:ss. 예: 2026-08-27 10:00:00. 타임존 표기를 붙이지 않습니다.
날짜 YYYYMMDD · string(8). 예: 20260827. KST 기준
국가 ISO 3166-1 alpha-2 대문자 2자
통화 ISO 4217 대문자 3자
금액 JSON string decimal. 부동소수점을 사용하지 않습니다.
비율 JSON string decimal
환율 JSON string decimal, 소수 8자리
전화번호 E.164 권장
Null 값이 없으면 null 입니다. 빈 문자열과 구분합니다.

ID 접두 일람

접두 리소스 접두 리소스
sm_ Submall acc_ 가맹점 계좌
per_ Person exq_ 환전 견적
doc_ Document exc_ 환전
pm_ Payout Method qte_ 견적
po_ Payout req_ 요청 추적값

•  ID 에는 대문자를 사용하지 않습니다.

오류 응답

오류도 성공과 같이 rescode · resmsg 로 시작합니다. 리소스 객체 대신 오류 상세 3필드를 실어 평면 5필드로 응답합니다.

rescode string

필수
오류 코드입니다. 성공의 0000 과 달리 영어 의미 문자열을 사용하며, 번호 체계를 사용하지 않습니다.

resmsg string

필수
오류에 대한 한국어 설명입니다. 성공일 때의 Success. 자리입니다.

description string

상세 설명입니다. 값이 null 이면 응답에서 빠집니다.

parameter string

문제가 된 입력 필드 하나입니다. 여러 개가 문제일 경우 첫 번째만 지목하고 나머지는 description 에 문장으로 담습니다.
응답 

{
    "rescode": "submall_not_active",
    "resmsg": "서브몰이 활성 상태가 아닙니다.",
    "description": "KYB 심사가 완료되지 않았습니다.",
    "parameter": "submall_id"
}

오류 코드 — 15종

HTTP rescode resmsg
400 invalid_request 요청 형식이 올바르지 않습니다.
401 invalid_api_key API Key 가 유효하지 않습니다.
403 payout_not_enabled 지급 서비스가 활성화되어 있지 않습니다.
404 resource_not_found 요청한 리소스를 찾을 수 없습니다.
409 duplicate_reference 이미 사용된 reference 입니다.
409 invalid_state_transition 현재 상태에서 허용되지 않는 상태 전이입니다.
409 quote_already_used 이미 사용된 견적입니다.
422 unsupported_country_currency 지원하지 않는 국가·통화 조합입니다.
422 submall_not_active 서브몰이 활성 상태가 아닙니다.
422 payout_method_not_eligible 지급수단이 지급 가능한 상태가 아닙니다.
422 kyb_requirement_missing KYB 심사가 완료되지 않았습니다.
422 quote_expired 견적이 만료되었습니다.
422 amount_below_minimum 최소 지급 금액에 미달합니다.
422 insufficient_payout_balance 출금 계좌의 지급 가능 잔액이 부족합니다.
500 internal_error 서버 내부 오류가 발생했습니다.

•  404 는 소유권 불일치 · 없는 ID · 잘못된 경로를 모두 포함하며 description 과 parameter 를 싣지 않습니다.
•  quote_already_used 와 quote_expired 는 지급 견적 · 환전 견적에 공통으로 사용합니다.

400 invalid_request 로 응답하는 검증

상황 parameter
funding_account_id 형식 오류 · 누락 funding_account_id
exchange_basis 가 정의되지 않은 값 exchange_basis
from_account_id 와 to_account_id 가 같음 to_account_id
requested_amount.currency 가 exchange_basis 가 정한 계좌 통화와 다름 requested_amount
scheduled_date 가 D+3 미만이거나 영업일이 아님 scheduled_date
requested_amount.currency 가 지급통화가 아님 — PAYOUT · WITHDRAWAL_LIMIT 두 모드 공통 requested_amount
요청 submall_id 가 견적의 값과 다름 submall_id
bank_account.route 와 채워진 계좌 필드가 어긋남 누락된 첫 필드

공통 객체

Money

금액은 통화와 값을 함께 담은 객체로 주고받습니다.

currency string(3)

필수
ISO 4217 통화 코드입니다.

value string

필수
금액입니다. decimal 문자열이며 통화별 소수 자릿수를 따릅니다.
Money 

{
    "currency": "USD",
    "value": "1250.00"
}

•  모든 반올림은 대상 통화의 소수 자릿수를 기준으로 합니다.

Address

주소를 나타내는 공통 객체입니다.

line1 string(200)

필수
주소 1행입니다.

line2 string(200)

주소 2행입니다.

city string(100)

필수
도시입니다.

state string(100)

필수
주 · 도입니다.

postal_code string(20)

우편번호입니다.

country string(2)

필수
국가입니다. ISO 3166-1 alpha-2 대문자 2자입니다.
Address 

{
    "line1": "500 Market St",
    "line2": "Suite 200",
    "city": "San Francisco",
    "state": "CA",
    "postal_code": "94105",
    "country": "US"
}

Contact

서브몰 담당자 연락처입니다.

name string(100)

필수
담당자명입니다.

email string(254)

필수
담당자 이메일 주소입니다. 서류 요청 링크가 이 주소로 발송됩니다.

phone string(30)

담당자 전화번호입니다. E.164 표기를 권장합니다.
Contact 

{
    "name": "John Doe",
    "email": "finance@acme.example",
    "phone": "+14155550100"
}

•  서류 요청 안내의 언어는 Submall 의 country 가 결정합니다. KR 는 한국어, JP 는 일본어, 그 외는 영어입니다.

Fee

항목별 수수료입니다. 공급가액과 세액을 함께 담습니다.

type string

필수
수수료 종류입니다.
TRANSFER_FEE

: 송금 수수료

PAYOUT_SERVICE_FEE

: 지급대행 서비스 수수료

amount Money

필수
공급가액입니다. 부가세를 제외한 금액이며 항상 지급통화입니다.

vat_amount Money

필수
세액입니다.
Fee 

{
    "type": "TRANSFER_FEE",
    "amount":     { "currency": "USD", "value": "10.00" },
    "vat_amount": { "currency": "USD", "value": "1.00" }
}

Trace

지급망이 부여한 추적 식별자입니다. 지급망이 늘어나도 type 값만 늘고 필드는 늘지 않습니다.

type string(50)

필수
추적 식별자의 종류입니다.
SWIFT_UETR

: 해외송금망 고유 거래 참조번호 (UUID)

DOMESTIC_BANK_REFERENCE

: 국내 은행 접수번호

value string(100)

필수
추적 식별자 값입니다.
Trace 

{ "type": "SWIFT_UETR",              "value": "550e8400-e29b-41d4-a716-446655440000" }

{ "type": "DOMESTIC_BANK_REFERENCE", "value": "20260827000123" }

상태와 코드

Submall 상태

submall_status

서브몰의 온보딩 · 심사 상태입니다. 전이는 Eximbay 가 처리하며, 가맹점은 GET /v2/submalls/{submall_id} 로 확인합니다.
상태 의미
DRAFT 등록됨. 서류 요청 전
REQUIREMENTS_DUE 서류 요청 링크 발급됨
ACTION_REQUIRED 제출 서류 보완 필요
UNDER_REVIEW 서류 제출 완료 · 심사 중
ACTIVE KYB 승인. 지급 가능
RESTRICTED AML · 재심사 제한
DEACTIVATED 서비스 종료
DRAFTREQUIREMENTS_DUEUNDER_REVIEWACTIVERESTRICTEDDEACTIVATEDACTION_REQUIRED서류 요청 링크 발급서류 제출KYB 승인AML · 재심사 제한서비스 종료보완 필요서류 재제출 · 다시 심사

전이는 Eximbay 가 처리하며 가맹점은 GET /v2/submalls/{submall_id} 로 확인합니다 · 점선은 되돌아가는 전이 · 회색은 종료 · 제한 상태

Payout 상태

payout_status

지급건의 상태입니다. 9종이며 순번이 붙은 다섯 상태가 선형 진행을 나타냅니다.
순번 상태 진입 조건 국내 해외 자금 처리 취소
1 SCHEDULED 생성 즉시 O O withdrawal_amount 보류 O
2 REQUIRES_REVIEW AML · 고액 · 예외 심사 — 조건부 보류 X
3 PROCESSING scheduled_date 도래 · 지급망 처리 O O 보류 또는 출금 처리 X
4 POSTED 지급망으로 출금 · 실행 O O 차감 확정 X
5 DELIVERED 수취 확인 데이터 확보 O O 변동 없음 X
— ACTION_REQUIRED 심사에 추가 서류 필요 — O 보류 유지 X
— CANCELED 실행 전 취소 O O 보류 해제 —
— NOT_COMPLETED 지급망 최종 거절 · 처리 불가 O O 보류 해제 —
— RETURNED 실행 후 반환 O O 순반환액 복원 —

ACTION_REQUIRED 와 NOT_COMPLETED 의 차이

•  서류 보완이 필요해 멈춤 → ACTION_REQUIRED · 자금 보류 유지. 서브몰이 서류를 올리면 REQUIRES_REVIEW 로 복귀해 심사가 재개되며 그동안 보류 잔액도 풀리지 않습니다.
•  지급망이 최종 거절 → NOT_COMPLETED · 자금 보류 해제. 가맹점은 지급요청을 다시 진행해야 합니다.

1SCHEDULED3PROCESSING4POSTED5DELIVERED2REQUIRES_REVIEWNOT_COMPLETEDRETURNEDACTION_REQUIREDCANCELEDscheduled_date 도래출금 · 지급망 실행수취 확인취소해외 · 추가 심사승인처리 불가최종 거절실행 후 반환서류 보완 필요재제출 → 재검토

숫자는 선형 진행 순번 · REQUIRES_REVIEW · ACTION_REQUIRED 은 해외(OVERSEAS_BANK) 건만 거칩니다 · NOT_COMPLETED 은 국내 · 해외 모두 PROCESSING와 REQUIRES_REVIEW에서 진입합니다 · ACTION_REQUIRED → REQUIRES_REVIEW 복귀는 서브몰이 심사 서류를 다시 업로드해 재검토가 시작될 때 일어납니다

케이스별 상태 순서

(1) 국내 송금 · 완료순번 2를 타지 않습니다
SCHEDULEDPROCESSINGPOSTEDDELIVERED
(2) 국내 송금 · 요청 후 취소
SCHEDULEDCANCELED
(3) 국내 송금 · 지급망 거절보류가 해제됩니다. 사유는 담당자가 안내합니다
SCHEDULEDPROCESSINGNOT_COMPLETED
(4) 해외 송금 · 추가 심사 없이 완료(1) 과 순번이 같습니다
SCHEDULEDPROCESSINGPOSTEDDELIVERED
(5) 해외 송금 · 추가 심사 → 서류 재업로드 → 심사 → 완료
SCHEDULEDREQUIRES_REVIEWACTION_REQUIREDREQUIRES_REVIEWPROCESSINGPOSTEDDELIVERED
(6) 해외 송금 · 실행 후 반환금액 필드는 지급 시점 값 그대로입니다
SCHEDULEDPROCESSINGPOSTEDRETURNED

•  취소는 SCHEDULED 에서만 가능합니다.
•  금액 필드는 상태가 바뀌어도 갱신되지 않습니다. RETURNED 가 되어도 fees[] · total_* 은 지급 시점 값 그대로입니다.

Quote 상태

quote_status · exchange_quote_status

지급 견적과 환전 견적은 같은 상태 집합과 같은 오류 코드를 사용합니다.

quote_status — 지급 견적

상태 의미 지급 생성 시
ACTIVE 사용 가능 O
CONSUMED 해당 견적 사용 완료 X 409 quote_already_used
EXPIRED 발급 당일 23:59:59 경과 X 422 quote_expired

exchange_quote_status — 환전 견적

상태 의미 환전 실행 시
ACTIVE 사용 가능 O
CONSUMED 해당 견적 사용 완료 X 409 quote_already_used
EXPIRED 발급 당일 23:59:59 경과 X 422 quote_expired
ACTIVECONSUMEDEXPIRED지급 생성 / 환전 실행당일 23:59:59 경과

•  당일 발급 견적이 아니면 정의상 만료입니다. 날짜가 넘어간 견적에 별도 코드를 두지 않고 422 quote_expired 를 사용합니다.
•  Exchange 에는 상태 필드가 없습니다. 실행 즉시 완결되고 취소 · 역환전이 없으므로 표현할 상태가 없습니다.

주요 코드

요청 · 응답에 사용되는 주요 코드 값입니다.

Route

값 의미 허용 통화
DOMESTIC_BANK 국내 계좌이체 KRW
OVERSEAS_BANK 해외 계좌이체 KRW USD JPY EUR

Payout Method Status

값 의미
PENDING 검증 중 — 지급 불가
ACTIVE 지급 가능
REJECTED 검증 실패
ARCHIVED 폐기됨

•  서브몰 심사가 끝나지 않았으면 계속 PENDING 입니다. 계좌는 DRAFT 서브몰에도 등록되지만 계좌명의 검증은 KYB 승인 뒤에 시작합니다.
•  PENDING 이 길다고 문제가 아닙니다. 진행 상황은 submall_status 가 알려줍니다.

Fee Payer

값 수수료 부담 net_transfer_amount withdrawal_amount
MERCHANT (기본) 가맹점 원금 그대로 원금 + 수수료 총액(부가세 포함)
SUBMALL 서브몰 원금 − 수수료 총액(부가세 포함) 원금

•  값을 지정하지 않으면 MERCHANT 입니다. 부담 기준은 부가세를 포함한 총액입니다.

Fee Type

값 의미 발생 조건 응답 fees[]
TRANSFER_FEE 송금 수수료 — 통화별 정액 route=OVERSEAS_BANK O
PAYOUT_SERVICE_FEE 지급대행 서비스 수수료 항상 O
RETURN_FEE 반환 처리 비용 반환 발생 시 X

•  세 값 모두 부가세 10% 대상입니다.
•  RETURN_FEE 는 반환이 확정된 뒤에 금액이 정해지므로 응답 fees[] 에 나타나지 않습니다. 확정되지 않은 값을 실으면 같은 필드가 시간에 따라 값이 변하게 됩니다. 지급 1건의 금액 필드는 한 번 확정되면 불변입니다.

Exchange Basis

값 requested_amount 의 뜻 통화 서버가 계산하는 값
SELL 파는 금액 — from 계좌에서 뺄 금액 from 계좌 통화 to_amount
BUY 사는 금액 — to 계좌에 넣을 금액 to 계좌 통화 from_amount

Amount Basis

값 requested_amount 의 뜻 requested_amount.currency
PAYOUT 지급 원금 — 서브몰에게 보낼 금액을 지정합니다. 지급통화
WITHDRAWAL_LIMIT 출금 계좌에서 뺄 금액의 상한을 지정합니다. 지급통화

Fee Basis

필드 값 뜻
calculation_type FIXED 정액 — amount 가 그대로 수수료입니다. rate 는 null 입니다.
RATE 요율 — rate 를 basis 에 곱해 계산합니다. amount 는 null 입니다.
basis PER_PAYOUT 지급 건당 부과합니다.
PAYOUT_AMOUNT 지급 원금에 요율을 적용합니다.

•  exchange_basis · amount_basis · 지급 정책의 basis 는 이름이 비슷하지만 서로 다른 필드입니다. 환전은 exchange_basisSELLBUY, 견적은 amount_basisPAYOUTWITHDRAWAL_LIMIT, 지급 정책의 수수료 항목은 basisPER_PAYOUTPAYOUT_AMOUNT 를 씁니다. 코드가 섞이지 않도록 필드를 나눴습니다.
•  WITHDRAWAL_LIMIT 는 말 그대로 상한입니다. withdrawal_amount 는 어떤 경우에도 requested_amount 를 넘지 않습니다.

Trace Type

값 의미
SWIFT_UETR 해외송금망 고유 거래 참조번호 (UUID)
DOMESTIC_BANK_REFERENCE 국내 은행 접수번호

Business Type

값 의미
COMPANY 법인
INDIVIDUAL_BUSINESS 개인사업자

응답 마스킹

민감 정보는 응답에서 마스킹되어 반환됩니다. 계좌번호는 뒤 5자리를 가립니다.
대상 규칙
계좌번호 account_number_masked 로 반환합니다. 뒤 5자리를 * 로 가리고 앞자리는 그대로 노출합니다. 예: 1234567890 → 12345*****. 원문을 되돌려주지 않습니다.
IBAN iban_masked 로 반환하며 앞 4자와 뒤 4자만 노출합니다.

오류 코드별 발생 API

오류 CASE

각 API 가 돌려줄 수 있는 오류를 HTTP 상태 · rescode 별로 모았습니다. 코드의 정의와 resmsg 는 절을 참고하세요. 401 invalid_api_key 와 500 internal_error 는 모든 API 에서 발생할 수 있어 표에서 생략했습니다.
HTTP rescode 발생 API 상황 parameter
400 invalid_request 필수 누락 · 형식 오류 · 길이 초과 해당 필드
payout_method.bank_account 의 route 별 필수 필드 누락 · 형식 오류 누락된 첫 필드
필터 값 · 형식 오류 해당 필드
수정 불가 필드 포함 · 형식 오류 해당 필드
route 별 필수 필드 누락 · 형식 오류 누락된 첫 필드
route · currency 값 오류 해당 필드
currency 값 오류 currency
exchange_basis 값 오류, 필수 누락 해당 필드
from_account_id 와 to_account_id 가 같음 to_account_id
requested_amount.currency 가 exchange_basis 가 정한 계좌 통화와 다름 requested_amount
필수 누락 · 형식 오류 해당 필드
Query 값 오류 해당 필드
amount_basis · fee_payer 값 오류, 필수 누락 해당 필드
requested_amount.currency 가 지급통화가 아님 — 두 모드 공통 requested_amount
scheduled_date 가 하한 미만 · 영업일 아님 · 형식 오류 scheduled_date
submall_id 가 견적의 값과 다름 submall_id
필수 누락 · 길이 초과 해당 필드
Query 값 오류 · 정의되지 않은 payout_status 해당 필드
403 payout_not_enabled 지급 서비스 미활성 —
404 resource_not_found 없거나 소유하지 않은 submall_id —
없거나 소유하지 않은 submall_id · method_id, 또는 둘의 소유 관계 불일치 —
없거나 소유하지 않은 리소스, 소유 관계 불일치 —
없거나 소유하지 않은 계좌 ID —
없거나 소유하지 않은 exchange_quote_id —
없거나 소유하지 않은 exchange_id —
없거나 소유하지 않은 submall_id · payout_method_id · funding_account_id —
없거나 소유하지 않은 quote_id —
없거나 소유하지 않은 리소스 —
없거나 소유하지 않은 payout_id —
409 duplicate_reference merchant_submall_reference 중복 merchant_submall_reference
payout_method.merchant_payout_method_reference 중복 payout_method.merchant_payout_method_reference
동일 계좌 중복 등록 bank_account.account_number
merchant_payout_method_reference 중복 merchant_payout_method_reference
merchant_exchange_reference 중복 merchant_exchange_reference
merchant_payout_reference 중복 merchant_payout_reference
409 invalid_state_transition 처리 중인 지급건이 이 계좌를 참조 —
SCHEDULED 가 아님 — 심사 중이거나 이미 처리됨 —
409 quote_already_used 사용된 환전 견적 재사용 exchange_quote_id
이미 사용된 quote_id quote_id
422 unsupported_country_currency route · currency 조합이 허용되지 않음 payout_method.bank_account.currency
route · currency 조합이 허용되지 않음 bank_account.currency
지원하지 않는 통화 조합 requested_amount
지급 통화가 KRW USD JPY EUR 이 아님 requested_amount
422 submall_not_active DEACTIVATED 서브몰 submall_id
submall_status 가 ACTIVE 아님 submall_id
422 submall_not_active · kyb_requirement_missing · payout_method_not_eligible 자격 미달 —
422 payout_method_not_eligible payout_method_status 가 ACTIVE 아님 payout_method_id
422 kyb_requirement_missing KYB 미완료 submall_id
422 quote_expired 환전 견적 만료 (당일 23:59:59 경과) exchange_quote_id
견적 만료 · 당일 발급분이 아님 quote_id
422 amount_below_minimum 최소 지급금액 미달 requested_amount
422 insufficient_payout_balance from 계좌 available_amount 부족 from_account_id
견적 발급 후 from 계좌 잔액이 줄어 부족 exchange_quote_id
출금 계좌 available_amount 부족 funding_account_id
견적 발급 후 출금 계좌 잔액이 줄어 부족 quote_id

•  parameter 는 문제가 된 입력 필드 하나를 가리킵니다. 여러 필드가 문제이면 첫 번째만 지목하고 나머지는 description 에 담습니다.
•  404 는 없는 ID · 소유하지 않은 리소스 · 잘못된 경로를 모두 포함하며 description · parameter 를 싣지 않습니다.
•  서브몰 등록 · 수취계좌 등록에서는 submall_not_active kyb_requirement_missing 이 발생하지 않습니다. 자격은 견적 생성 시점에 판정합니다.