Ledger Account model

Copy for LLMView as Markdown

This model is ideal for marketplaces outside Europe seeking a lightweight solution for rapid launch or requiring extensive seller payout coverage. Refer to the guide below for a sample integration.

Step 1: Create a ledger connected account for sellers

Use Create a Connected Account API to create a seller ledger. The data requirements will vary depending on the seller type as described in the sections below.

Field	Registered sellers	Non-registered sellers
`identifier`	Provide Seller ID on the platform	Provide Seller ID on the platform
`account_details.business_details.industry_category_code`	Industry category code for your business	Industry category code for your business
`account_details.business_details.url`	URL(s) for your store	URL(s) for your store
`primary_contact.email`	Primary contact details for your business	Primary contact details for your business
`customer_agreements.terms_and_conditions.service_agreement_type`	Set this to `RECIPIENT`	Set this to `RECIPIENT`
`account_details.business_details.business_structure`	Set this to `COMPANY` or `SOLE_PROPRIETOR`	Set this to `NON_REGISTERED_SOLE_PROPRIETOR`
`account_details.business_details.business_name`	Legal entity name	Optional
`account_details.business_details.business_name_trading`	Trading/DBA name	Optional
`account_details.business_details.registration_address.country_code`	Country where the business is registered	Optional
`account_details.business_details.business_identifiers.*`	Local business registration number	Optional
`account_details.business_address.country_code`	Optional	Country where seller's business operates
`account_details.business_person_details.first_name`	Optional	Seller's first name
`account_details.business_person_details.last_name`	Optional	Seller's last name
`account_details.business_person_details.date_of_birth`	Optional	Seller's date of birth
`account_details.business_person_details.roles`	Optional	Business person role
`account_details.business_person_details.identifications.primary.*`	Optional	Details of the business person for identity verification, such as a passport, driver's license, or other government-issued ID card

Collecting customer agreements to terms and conditions

The platform needs to collect the corresponding terms and conditions acceptance from sellers for the use of ledger.

A RECIPIENT service agreement clarifies that there is no service relationship between Airwallex and the recipient, and that the recipient's relationship is with the platform.

If terms & conditions are agreed during account creation, use Create a Connected Account API.
If terms & conditions are agreed upon after account creation, use Agree to Terms and Conditions API.

Refer to this resource for display T&C links: Collect T&C acceptance guide.

Example request

Shell

1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/accounts/create' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{
6    "identifier": "TEST_LA_1",
7    "account_details": {
8        "business_person_details": [{
9            "date_of_birth": "2020-01-01",
10            "first_name": "John",
11            "last_name": "Smith",
12            "roles": [
13                "CONTROLLING_PERSON"
14            ],
15            "identifications": {
16                "primary":{
17                    "issuing_country_code": "SG",
18                    "identification_type": "PASSPORT",
19                    "passport": {
20                        "number": "123"
21                    }
22                }
23            }
24        }],
25        "business_details": {
26            "industry_category_code": "ICCV3_0002XX",
27            "business_address": {
28                "country_code": "DE"
29            },
30            "business_structure": "NON_REGISTERED_SOLE_PROPRIETOR",
31            "url": "https://www.ebay.com/str/doverjewelry?_trksid=p4429486.m3561.l161211"
32        }
33    },
34    "customer_agreements": {
35        "terms_and_conditions": {
36            "agreed_at": "2024-08-17T16:08:02+1100",
37            "service_agreement_type": "RECIPIENT",
38            "device_data": {
39                "ip_address": "127.0.0.1",
40                "user_agent": "Chrome/51.0.2704.103 Safari/537.36"
41            }
42        },
43        "agreed_to_terms_and_conditions": true,
44        "agreed_to_data_usage": true,
45        "opt_in_for_marketing": true
46    },
47    "primary_contact": {
48        "email": "[email protected]"
49    }
50}'

Step 2: Payout to sellers

As a marketplace platform, you can choose from the two options below to pay sellers.

Option A: Payout to seller's external bank account directly

Ledger direct payout flow

In this integration flow, the platform will calculate the amount to be paid to sellers on their own and payout to the seller's external bank account directly using Airwallex Transfer APIs. Platform doesn't need to initiate fund splits and no funds will be held in the seller's ledger.

Apart from the standard information required to Create a new transfer API, you need to specify the seller account id as the additional parameter in your request:

beneficiary.additional_info.recipient_account_id: Specify the account id of seller ledger (recipient) in Beneficiary object.

When a refund happens, funds will go back to the platform's account.

Only same-name payout ("beneficiary name" matches "recipient account name") will be accepted.

Example request

Shell

1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/transfers/create' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--data '{
6    "beneficiary": {
7        "additional_info": {
8            "external_identifier": "",
9            "personal_email": "[email protected]",
10            "recipient_account_id": "acct_O9JasXyBPNagXgd5L8rhDA"
11        },
12        "address": {
13            "city": "Seattle",
14            "country_code": "US",
15            "postcode": "98104",
16            "state": "Washington",
17            "street_address": "412 5th Avenue"
18        },
19        "bank_details": {
20            "account_currency": "USD",
21            "account_name": "John Walker",
22            "account_number": "50001121",
23            "account_routing_type1": "aba",
24            "iban": "123123123",
25            "account_routing_value1": "021000021",
26            "bank_country_code": "US",
27            "bank_name": "JP Morgan Chase Bank",
28            "local_clearing_system": "ACH"
29        },
30        "company_name": "Complete Concrete Pty Ltd",
31        "entity_type": "COMPANY",
32        "type": "BANK_ACCOUNT"
33    },
34    "metadata": {
35        "order_id": "0123456789"
36    },
37    "reason": "travel",
38    "reference": "INV-123456",
39    "remarks": "",
40    "request_id": "ce6e34d6-1fbc-4d6a-8b0c-0f1a4a552404",
41    "source_currency": "CNY",
42    "transfer_amount": "1000.00",
43    "transfer_currency": "USD",
44    "transfer_date": "2026-01-07",
45    "transfer_method": "LOCAL"
46}'

Option B: Use ledger account to hold funds and payout from ledger

Ledger payout via ledger flow

In this integration flow, the platform will first split and deposit funds to the seller's wallet, then trigger payouts to the seller's external bank account. This allows the funds to be stored in the seller's wallet.

Deposit funds to seller's ledger

Depending on your choice of acquiring entity, follow the corresponding steps to split and deposit funds to the seller's wallet.

Use Airwallex as the payment service provider (PSP) to acquire funds: See details in Process payments and manage funds.
Use other payment service providers (PSPs) as the acquirer: See details in Get started with PSP-agnostic solutions.

Payout from seller's ledger to seller's external bank account

Trigger payouts to seller's external bank accounts using Airwallex's Transfer APIs. Airwallex's network of local clearing systems supports payouts to bank accounts in multiple countries and currencies, with country-specific delivery time taken into consideration to ensure the payouts arrive in time.

When a refund happens, funds will go back to the seller's ledger account. Use Scale Charges API if you need to debit the ledger account's wallet and credit the platform account's wallet.

Only same-name payout ("beneficiary name" matches "recipient account name") will be accepted.

Example request

Shell

1curl --request POST \
2--url 'https://api-demo.airwallex.com/api/v1/transfers/create' \
3--header 'Content-Type: application/json' \
4--header 'Authorization: Bearer <your_bearer_token>' \
5--header 'x-on-behalf-of: <ledger_account_id>' \
6--data '{
7    "beneficiary": {
8        "additional_info": {
9            "personal_email": "[email protected]"
10        },
11        "address": {
12            "city": "Brandonbury",
13            "country_code": "DE",
14            "postcode": "10115",
15            "state": "",
16            "street_address": "8860 Graciela Heights"
17        },
18        "bank_details": {
19            "account_currency": "EUR",
20            "account_name": "Deondre Kuvalis",
21            "account_routing_type1": "bsb",
22            "account_routing_value1": "[email protected]",
23            "bank_country_code": "DE",
24            "iban": "DE04370502990081288281"
25        },
26        "company_name": "Complete Concrete Pty Ltd",
27        "entity_type": "COMPANY"
28    },
29    "metadata": {
30        "order_id": "0123456789"
31    },
32    "transfer_amount": "1.00",
33    "transfer_currency": "EUR",
34    "transfer_method": "SWIFT",
35    "reason": "travel",
36    "reference": "test-ccs-in-tm",
37    "remarks": "",
38    "request_id": "a9fa3ea9-73de-47c5-bd04-74a13131d6922",
39    "source_currency": "EUR",
40    "payer": {
41        "additional_info": {
42            "business_registration_number": "SG-647-37-3333"
43        },
44        "address": {
45            "city": "Melbourne",
46            "country_code": "AU",
47            "postcode": "3000",
48            "state": "VIC",
49            "street_address": "15 William Street"
50        },
51        "company_name": "happiness store",
52        "entity_type": "COMPANY"
53    }
54}'

Was this page helpful?