Manage Merchant of Record sellers

Use the Seller API to register and manage downstream sellers when your platform operates as Merchant of Record (MoR) with the Airwallex payment gateway. This applies when you collect payments directly and need to screen sub-sellers under your MoR account.

Create and deactivate requests start seller KYB screening for that seller. You can track status by polling the retrieve endpoint or by subscribing to Seller webhook events.

Before you begin

• An account with the Merchant of Record (MoR) use case on the merchant profile. Without MoR, create requests return 403 Forbidden.
• An access tokenAPI for that account.
• Optional: a webhook subscription that includes Seller events, if you want status updates without polling.

Create a seller

Call Create a sellerAPI with the seller's business details. A successful response returns a seller id and an initial status, typically IN_REVIEW.

Provide at least one of merchant_category_code or industry_code. If you include address, country_code, address_line1, and suburb are required.

1{
2  "business_identification_number": "201626561Z",
3  "trading_name": "AIRWALLEX SG",
4  "legal_entity_name": "AIRWALLEX (SINGAPORE) PTE. LTD.",
5  "registration_country": "SG",
6  "registration_date": "2020-01-15",
7  "merchant_category_code": "5734",
8  "industry_code": "ICCV3_0001XX",
9  "email": "[email protected]",
10  "phone_number": "+1-555-1234",
11  "address": {
12    "country_code": "US",
13    "state": "California",
14    "suburb": "San Francisco",
15    "postcode": "94105",
16    "address_line1": "123 Market St",
17    "address_line2": "Suite 100"
18  },
19  "websites": [
20    {
21      "url": "https://www.subseller.com"
22    }
23  ]
24}

Example response:

1{
2  "id": "2ec93632-07c6-4afc-8519-25da56f3931a",
3  "status": "IN_REVIEW",
4  "created_at": "2025-10-24T06:15:09Z",
5  "updated_at": "2025-10-24T07:01:03Z"
6}

Common errors include validation_failed or invalid_argument (400), authentication failures (401), and rate limiting (429). If the account does not have an MoR use case, create requests fail with 403 Forbidden.

Check seller status

Call Retrieve a sellerAPI with the seller id until the seller reaches a terminal or actionable state such as ACTIVE or REJECTED.

1{
2  "id": "2ec93632-07c6-4afc-8519-25da56f3931a",
3  "status": "ACTIVE",
4  "created_at": "2025-10-24T06:45:12Z",
5  "updated_at": "2025-10-24T07:01:03Z",
6  "details": {
7    "business_identification_number": "201626561Z",
8    "trading_name": "AIRWALLEX SG",
9    "legal_entity_name": "AIRWALLEX (SINGAPORE) PTE. LTD.",
10    "registration_country": "SG",
11    "registration_date": "2020-01-15",
12    "merchant_category_code": "5734",
13    "industry_code": "ICCV3_0001XX",
14    "email": "[email protected]",
15    "phone_number": "+1-555-1234",
16    "address": {
17      "country_code": "US",
18      "state": "California",
19      "suburb": "San Francisco",
20      "postcode": "94105",
21      "address_line1": "123 Market St",
22      "address_line2": "Suite 100"
23    },
24    "websites": [
25      {
26        "url": "https://www.subseller.com"
27      }
28    ]
29  }
30}

For real-time updates, subscribe to Seller webhook events instead of polling. See Sellers for event names and payload examples.

Seller statuses

Deactivate a seller

When a seller is no longer needed, call Deactivate a sellerAPI. Deactivation also starts seller KYB screening. The seller typically moves to PENDING_DEACTIVATION while the request is reviewed, then to INACTIVE when deactivation completes.

1{
2  "id": "2ec93632-07c6-4afc-8519-25da56f3931a",
3  "status": "PENDING_DEACTIVATION",
4  "created_at": "2025-10-24T06:45:12Z",
5  "updated_at": "2025-10-24T07:01:03Z"
6}

Common errors include authentication failures (401), resource_not_found (404), and resource_conflict (409) when the seller is not in a state that can be deactivated (for example, not ACTIVE).

Field requirements

The API schema may mark fields as optional, but MoR create requests enforce the following rules.

Provide at least one of merchant_category_code or industry_code.

Next steps

• Review Seller webhook events.
• See Collect payments directly for the platform-as-MoR payment model.
• See the Sellers API referenceAPI for full request and response schemas.