Partner API, production
Base URL https://production.finmotreasury.net/v1. HTTP Basic with the production key pair Finmo sends you over a secure channel. The sandbox keys don't work here.
- Organizations are real Finmo production organizations, named
Zenith Test - <merchant name>so Finmo compliance can tell them apart. - KYB is approved by Finmo compliance, not instantly. Expect minutes to hours. Activation (AUD account details) is done by Finmo after approval.
- Payouts and FX move real money from the sub account's balance.
- Sandbox-only calls (
/payout/simulate,/virtual-account/simulate-payin,/partner/kyb/simulate) return 404. - Send
X-Idempotency-Key(UUID v4) on every POST. Never resend a payout after a timeout without checkingGET /payoutfirst.
Endpoints
| POST | /partner/invite-organization | wrapped | Accepts abn / acn + address_city (and state, postcode, address_line1, organization_reference_id). Finmo pulls the company record and submits KYB. Name in Finmo is prefixed "Zenith Test - ". |
| GET | /partner/organization | wrapped | Only sub accounts created through this API. Adds kyb.mode and kyb.action_required. |
| GET | /partner/organization/{org_id} | wrapped | Adds abn, acn and kyb { status, action_required, submitted_at, approved_at }. |
| PUT | /partner/organization-setting/{org_id} | wrapped | key webhook_url (https) and key webhook_security_token. Finmo's webhooks reach your URL with your token in x-security-token. |
| PATCH | /partner/kyb/save/{org_id} | Finmo API | For sub accounts created without an ABN. |
| POST | /partner/organization-document/{org_id} | Finmo API | Upload URL is valid for 30 seconds. |
| ANY | /wallet, /virtual-account, /fx-rate, /payout-beneficiary, /payout, /transaction, /webhook-notification ... | Finmo API | Passed to Finmo production unchanged. x-on-behalf-of is required and must be one of your sub accounts. |
| GET | /payout-method/all, /payout-method/param/{name} | Finmo API | Reference data. Finmo production requires x-on-behalf-of here too. |
Create a sub account by ABN
POST https://production.finmotreasury.net/v1/partner/invite-organization
X-Idempotency-Key: <uuid v4>
{
"first_name": "Priya", "last_name": "Nair", "email": "accounts@merchant.com.au",
"org_name": "Coral Coast Getaways Pty Ltd", "org_country": "AU",
"abn": "<11-digit ABN>", "address_city": "Cairns", "address_state": "QLD", "address_zip_code": "4870",
"organization_reference_id": "TPB2B-000417"
}
201 -> data.org_id, kyb { status: "NOT_STARTED", mode: "PARTNER_RELIANCE" }
Then: kyb.status SUBMITTED -> APPROVED (webhook ORGANIZATION_KYB_APPROVED) -> VA_CREATED when the AUD account is live.Without abn/acn the call behaves exactly like Finmo's partner API today: send KYB yourself with PATCH /partner/kyb/save.
Webhooks
Set webhook_url and webhook_security_token per sub account with PUT /partner/organization-setting/{org_id}. Every delivery carries your token in x-security-token. Respond 2xx within 5 seconds. Retries: 15m, 1h, 3h, 6h, 12h, 24h. Dedupe on webhook_notification_id and event_id.
| ORGANIZATION_KYB_APPROVED | Finmo compliance approved the sub account | proposed |
| ORGANIZATION_KYB_ACTION_REQUIRED | Registry data missing; Finmo compliance emails Zenith over a secure channel | proposed |
| ORGANIZATION_KYB_REJECTED | Sub account cannot be opened | proposed |
| VA_CREATED | Account activated: AUD BSB + account number live | live |
| VA_PAYIN_COMPLETED, PAYOUT_CREATED / COMPLETED / FAILED / RETURNED, FEES_PAYMENT | Same as Finmo production | live |
KYB fields: what the registry gives and what Finmo still needs
For this test, fields the KYB data provider can't supply use demo values set by Finmo. For live merchants, Zenith would send them (or Finmo agrees a reliance attestation in their place).
| Finmo needs | Field | Source today | Ask of Zenith for live merchants |
|---|---|---|---|
| Business name | name | Zenith create call | - |
| Legal registered name | legal_name | KYB data provider | - |
| Business registration number (ACN) | company_registration_number | KYB data provider, else Zenith | - |
| Tax registration number (ABN) | tax_registration_number | KYB data provider, else Zenith | - |
| Date of incorporation | incorporation_date | KYB data provider | - |
| Country of incorporation | country | Zenith create call | - |
| Registered address (line 1, city, state, postcode) | address_* | KYB data provider, else Zenith | - |
| Legal entity type | business_type | KYB data provider | - |
| Website | does_org_has_website, website_url | KYB data provider, else Zenith | Merchant website when the registry has none (or brochure / alternate online presence) |
| Compliance / dispute emails (max 3) | dispute_email_list | Not available: demo value | Compliance or disputes contact email for the merchant |
| Annual turnover band | annual_turnover | Not available: demo value | Turnover band from Zenith's onboarding record |
| Industry | industry_name | Not available: demo value | Industry (e.g. offline travel agency, OTA, tour operator). Registry industry codes are unreliable |
| Business description | account_usage_purpose | Not available: demo value | What the merchant will use the account for |
| Funds flow | funds_flow_desc | Not available: demo value | Where money comes from and where it goes |
| Employees, expected monthly volume and count | no_of_employees, expected_txn_* | Not available: demo value | Optional; send if Zenith holds them |
| Certificate of incorporation | company_registration_document_id | KYB data provider report (PDF) | - |
| Shareholding structure | company_shareholding_structure_document_id | KYB data provider report (PDF) | - |
| Company address proof | company_address_proof_document_id | Not available: demo value | Company address proof document (or confirmation the registry address is enough under reliance) |
| Directors and owners: name, role, share % | business_owner[] name, type, percentage | KYB data provider | - |
| Directors and owners: date of birth | business_owner[].dob | KYB data provider | Only when the registry has no DOB for a person |
| Directors and owners: residential address | business_owner[].address_* | Not available: demo value | Residential address per director/owner (registry addresses are partial) |
| Directors and owners: nationality | business_owner[].nationality | Not available: demo value | Nationality per director/owner |
| Directors and owners: ID type and number | business_owner[].identification_* | Not available: demo value | ID type and number per director/owner from Zenith's KYC |
| Directors and owners: ID document, address proof, IDV report | business_owner[].*_document_id | Not available: demo value | ID document, address proof and IDV result per person, or a reliance attestation in place of documents |
The registry check runs inside POST /partner/invite-organization, before the sub account is created, so the call takes about 25 seconds. Set your client timeout to at least 60 seconds. If the check fails, no sub account is created and the call returns an error:
422 REGISTRY_NO_MATCH_ERROR: no company record for the ABN/ACN. Check the number, business name and city.422 REGISTRY_INCOMPLETE_ERROR: a record exists but is missing one of legal_name, registration_number, incorporation_date, registered_address or directors_or_owners. The message names what's missing.502 REGISTRY_UNAVAILABLE_ERROR: the check couldn't complete. Safe to retry.
Gaps outside those core fields don't block the sub account. If Finmo compliance needs more, Zenith gets ORGANIZATION_KYB_ACTION_REQUIRED and compliance emails Zenith over a secure channel. Nothing is collected through the API.