openapi: 3.0.3 info: title: 'GoEscrow API Documentation' description: '' version: 1.0.0 servers: - url: 'https://partners.staging.goescrow.net' tags: - name: System description: '' - name: 'Company Management' description: 'Manage Companies' - name: Compliance description: 'Submit compliance evidence collected on your platform' - name: 'User Management' description: 'Manage Users' - name: 'Dispute Management' description: 'Create and manage transaction disputes' - name: 'Transaction Cancellation' description: "Manage cancellation requests and approvals for partner transactions.\n\n### Multiple payees: standard and marketplace Anytime and Timed transactions\n\nA transaction with two or more disbursement entries uses per-party cancellation approval. The API derives the parties from the saved payer and disbursement recipients. Do not include a list of other parties or resend the disbursement array in cancellation requests. All calls below use the existing `/api/v1/transactions/{transaction_id}` endpoints.\n\n1. POST `/cancellation-request` with `requester_id`, the requesting user or company UUID. For a company with multiple representatives, also send `representative_id`, the UUID of the linked user acting for that company. Use the same representative for code delivery and verification.\n2. If `requires_2fa` is true, codes have been sent but the request has not yet been created. POST `/verify-cancellation` with the same actor details, `email_code` and `phone_code` to create it.\n3. Save the returned `cancellation_request_id`. Each other party POSTs `/cancellation-accept` with its own `accepter_id`, the current `cancellation_request_id` and, where needed, `representative_id`.\n4. If acceptance returns `requires_2fa: true`, that party POSTs `/verify-cancellation-accept` with the same actor details and request ID, plus `email_code` and `phone_code`.\n5. A party still requiring approval can instead POST `/cancellation-deny` with `denier_id`, the current `cancellation_request_id` and, where needed, `representative_id`. Denial does not require verification codes.\n\nFor example, an individual requests cancellation without listing the other parties:\n\n```json\n{\"requester_id\": \"9d2e5c8a-1234-5678-9abc-def012345678\"}\n```\n\nAfter the request is created, another party accepts using the returned request ID:\n\n```json\n{\"accepter_id\": \"9d2e5c8a-1234-5678-9abc-def012345680\", \"cancellation_request_id\": \"2c9bb6a0-b123-4567-89ab-0123456789ab\"}\n```\n\nMarketplace cancellation includes the payer and every disbursement recipient, including fee recipients. The marketplace operator is not an additional approval party solely because it is the operator. Beneficiaries confirm receipt of goods or services; they are not cancellation parties. Cancellation can start while beneficiary confirmation is outstanding, and settlement is blocked while cancellation is pending.\n\nThe requester contributes the first approval. With one payer and two distinct payees, all three legal parties must approve; one representative acting for two companies must approve separately for each company. An HTTP 200 can mean only that one approval was recorded. The transaction remains `cancellation_requested` until all required approvals are complete. Check `status` for `canceled`; refund processing may still be pending.\n\nPending multi-payee transactions also require all parties to approve; they are not cancelled immediately. Partially or fully funded multi-payee transactions require email and phone verification for every approval, based on positive, unreversed payment receipts. If funding arrives after an unverified approval, that party must approve again with verification. Codes expire after five minutes and are bound to the transaction, legal party, representative and cancellation attempt.\n\nA missing or stale `cancellation_request_id` on acceptance, acceptance verification or denial returns HTTP 422. Refresh the transaction and use the current ID; do not replay an old approval against a new request. The response ID is null before a request is created and after cancellation or denial ends it. Older active requests without a generated ID return `legacy`; send the returned value unchanged.\n\nDenial normally restores the previous status. Marketplace denial rechecks beneficiary requirements before restoring accepted or awaiting_beneficiary_confirmation. For a multi-payee Timed transaction less than 12 hours before a future release, denial instead sets `contact_helpdesk`, suspends payee settlements and alerts customer service.\n\nSingle-payee and Super Disbursement transactions retain their existing cancellation flow. The multi-payee-only fields and approval rules below do not change that flow." - name: 'Transaction Management' description: 'Manage Transactions' - name: 'Transaction PayTo Payment' description: 'Initiate PayTo Payments for Transactions' - name: 'User Bank Account Management' description: 'Manage User Bank Accounts' - name: 'User Identification Management' description: 'Manage User Identification Documents' - name: 'User PayTo Agreement Management' description: 'Manage User PayTo Agreements' - name: 'Webhook Management' description: 'Manage webhook subscriptions for transaction events' - name: 'Company Bank Account Management' description: 'Manage company bank accounts using Confirmation of Payee' - name: 'Hosted Login' description: 'Create an identity-only hosted login session, send the user to the returned GoEscrow URL, receive a one-time code at the registered redirect URL, then verify the code server-to-server. The redirect URL is configured by GoEscrow and snapshotted when the session is created.' - name: 'Verification Codes' description: "Send your users a one-time code by email or SMS for your own checks, such as confirming a login or a change of details, then check the code they give you. A verified code is only for your use: it does not verify the user's email or mobile in GoEscrow and does not approve any GoEscrow action. GoEscrow must enable verification codes for your account." components: securitySchemes: default: type: apiKey name: X-API-Key in: header description: "To connect via API authentication is required.\n\nContact your GoEscrow account manager for a one time use URL token to create your X-API-Key. Send that specific X-API-Key in a custom header (replacing '123456789abcdef') as follows:\n\n```\nPOST /v1/transactions HTTP/1.1\nHost: partners.goescrow.net\nX-API-Key: 123456789abcdef\nContent-Type: application/json\nAccept: application/json\n```" security: - default: [] paths: /api/v1/users: post: responses: 201: content: application/json: schema: properties: data: properties: companies: items: type: object properties: id: type: string example: 9d2e5c8a-8765-4321-9abc-def012345678 reference: type: string example: XYZ789 name: type: string example: 'Acme Corp Pty Ltd' abn: type: string example: '53004085616' kyb_verified: type: boolean example: true type: array example: [] description: 'The companies the user is a representative for. Always empty for a newly created user.' id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The unique identifier of the user' reference: type: string example: ABC123 description: 'The unique reference code for the user (GoEscrow ID)' first_name: type: string example: John description: "The user's first name" last_name: type: string example: Doe description: "The user's last name" email: type: string example: john.doe@example.com description: "The user's email address" phone: type: string example: '+61412345678' description: "The user's phone number in E.164 format" birth_date: type: string example: '1990-01-15' description: "The user's date of birth" kyc_verified: type: boolean example: false description: 'Whether the user has completed KYC verification' aml_verified: type: boolean example: false description: 'Whether the user has completed AML verification' aml_verified_at: type: string example: null description: 'Timestamp when the user completed AML verification' email_verified: type: boolean example: false description: 'Whether the user has verified their email' mobile_verified: type: boolean example: false description: 'Whether the user has verified their mobile' mobilekyc_verified: type: boolean example: false description: 'Whether the user has completed mobile KYC verification' bank_verified: type: boolean example: false description: 'Whether the user has verified their bank account' suspended: type: boolean example: false description: 'Whether the user account is suspended' address: type: object properties: unit_number: type: string example: 10B street_number: type: string example: '123' street: type: string example: 'Smith St' suburb: type: string example: Sydney state: type: string example: NSW postcode: type: string example: '2000' country: type: string example: Australia description: "The user's address (null if not set)" type: object required: - id - reference - first_name - last_name - email - phone - birth_date - kyc_verified - aml_verified - aml_verified_at - email_verified - mobile_verified - mobilekyc_verified - bank_verified - suspended - address - companies type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 first_name: John last_name: Doe email: john.doe@example.com phone: '+61412345678' birth_date: '1990-01-15' kyc_verified: false aml_verified: false aml_verified_at: null email_verified: false mobile_verified: false mobilekyc_verified: false bank_verified: false suspended: false address: unit_number: 10B street_number: '123' street: 'Smith St' suburb: Sydney state: NSW postcode: '2000' country: Australia companies: [] description: 'User created successfully' summary: 'Create a new user' operationId: createANewUser description: 'Creates a new user. Email and phone must be unique. The user will be automatically associated with the authenticated partner. If the authenticated Partner has welcome emails enabled, newly created API users receive a GoEscrow Welcome By Partner email with a 24-hour, single-use password setup link.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string tags: - 'User Management' requestBody: required: true content: application/json: schema: type: object properties: first_name: type: string description: "The user's first name" example: John last_name: type: string description: "The user's last name" example: Doe email: type: string description: "The user's email address. Must be a valid email format." example: john.doe@example.com phone: type: string description: "The user's phone number. Australian numbers can be sent as 0412345678, +61412345678 or 61412345678. Numbers from other countries must include the country code (e.g., +447911123456). Stored and returned in E.164 format." example: '+61412345678' birth_date: type: string description: "The user's date of birth in YYYY-MM-DD format. Optional." example: '1990-01-15' initiate_mobile_verification_flow: type: string description: 'Whether to send the KYC ID scanner to the user mobile. Accepts yes or no and defaults to no. To send it to an existing user later, use Send the mobile ID scan (POST /api/v1/users/{user_id}/mobile-verification-flow).' example: 'yes' address: type: object description: "The user's address. Optional." example: unit_number: 10B street_number: '123' street: 'Smith St' suburb: Sydney state: NSW postcode: '2000' properties: {} required: - first_name - last_name - email - phone /api/v1/healthcheck: get: summary: '' operationId: getApiV1Healthcheck description: '' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: {} tags: - System /api/v1/companies/lookup: get: summary: 'Lookup a company by ABN' operationId: lookupACompanyByABN description: 'Looks up an existing company by Australian Business Number, or by the INT- identifier of an international company. Access is limited to companies represented by a user belonging to the authenticated partner, unless using an internal API key.' parameters: - in: query name: abn description: 'The Australian Business Number. Formatting spaces are accepted. For an international company, the INT-- identifier it was created with.' example: '40 650 703 736' required: true schema: type: string description: 'The Australian Business Number. Formatting spaces are accepted. For an international company, the INT-- identifier it was created with.' example: '40 650 703 736' - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: 'Company found' type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Acme Corp Pty Ltd' abn: '40650703736' acn: '004085616' kyb_verified: true aml_verified: true aml_verified_at: '2026-06-25T00:00:00.000000Z' bank_verified: true abr_status: Active representatives: - id: 9d2e5c8a-1234-5678-9abc-def012345679 reference: ABC123 name: 'Jane Doe' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The unique identifier of the company' reference: type: string example: ABC123 description: 'The unique reference code for the company (GoEscrow ID)' name: type: string example: 'Acme Corp Pty Ltd' description: 'The company name' abn: type: string example: '40650703736' description: 'The Australian Business Number, or INT-- for an international company' acn: type: string example: '004085616' description: 'The Australian Company Number' kyb_verified: type: boolean example: true description: 'Whether the company has completed KYB verification' aml_verified: type: boolean example: true description: 'Whether the company has completed AML verification' aml_verified_at: type: string example: '2026-06-25T00:00:00.000000Z' description: 'Timestamp when the company completed AML verification' bank_verified: type: boolean example: true description: 'Whether the company has a verified bank account' abr_status: type: string example: Active description: 'The status from the latest Australian Business Register lookup, or International for an international company, which is not looked up' representatives: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345679 reference: ABC123 name: 'Jane Doe' description: 'The company representatives' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 reference: type: string example: ABC123 name: type: string example: 'Jane Doe' required: - id - reference - name - abn - acn - kyb_verified - aml_verified - aml_verified_at - bank_verified - abr_status - representatives - description: 'International company found' type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345680 reference: DEF456 name: 'Example Trading Pte Ltd' abn: INT-SG-201912345K acn: null kyb_verified: true aml_verified: true aml_verified_at: '2026-06-25T00:00:00.000000Z' bank_verified: false abr_status: International representatives: - id: 9d2e5c8a-1234-5678-9abc-def012345679 reference: ABC123 name: 'Jane Doe' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345680 description: 'The unique identifier of the company' reference: type: string example: DEF456 description: 'The unique reference code for the company (GoEscrow ID)' name: type: string example: 'Example Trading Pte Ltd' description: 'The company name' abn: type: string example: INT-SG-201912345K description: 'The Australian Business Number, or INT-- for an international company' acn: type: string example: null description: 'The Australian Company Number' kyb_verified: type: boolean example: true description: 'Whether the company has completed KYB verification' aml_verified: type: boolean example: true description: 'Whether the company has completed AML verification' aml_verified_at: type: string example: '2026-06-25T00:00:00.000000Z' description: 'Timestamp when the company completed AML verification' bank_verified: type: boolean example: false description: 'Whether the company has a verified bank account' abr_status: type: string example: International description: 'The status from the latest Australian Business Register lookup, or International for an international company, which is not looked up' representatives: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345679 reference: ABC123 name: 'Jane Doe' description: 'The company representatives' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 reference: type: string example: ABC123 name: type: string example: 'Jane Doe' required: - id - reference - name - abn - acn - kyb_verified - aml_verified - aml_verified_at - bank_verified - abr_status - representatives 404: description: 'Company not found or access denied' content: application/json: schema: type: object example: message: 'Company not found or access denied.' properties: message: type: string example: 'Company not found or access denied.' tags: - 'Company Management' /api/v1/companies: post: summary: 'Create a new company' operationId: createANewCompany description: 'Creates a new company and attaches one or more existing users as its representatives. An international company without an ABN is created by sending abn as INT--; it is not looked up on the Australian Business Register, so name and address.country are required.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: '' content: application/json: schema: oneOf: - description: 'Company created successfully' type: object example: data: id: comp_123 reference: ABC123 name: 'Acme Corp Pty Ltd' abn: '40650703736' acn: '004085616' kyb_verified: true aml_verified: true aml_verified_at: '2026-06-25T00:00:00.000000Z' bank_verified: true abr_status: Active representatives: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' properties: data: type: object properties: id: type: string example: comp_123 description: 'The unique identifier of the company' reference: type: string example: ABC123 description: 'The unique reference code for the company (GoEscrow ID)' name: type: string example: 'Acme Corp Pty Ltd' description: 'The company name' abn: type: string example: '40650703736' description: 'The Australian Business Number, or INT-- for an international company' acn: type: string example: '004085616' description: 'The Australian Company Number' kyb_verified: type: boolean example: true description: 'Whether the company has completed KYB verification' aml_verified: type: boolean example: true description: 'Whether the company has completed AML verification' aml_verified_at: type: string example: '2026-06-25T00:00:00.000000Z' description: 'Timestamp when the company completed AML verification' bank_verified: type: boolean example: true description: 'Whether the company has a verified bank account' abr_status: type: string example: Active description: 'The status from the latest Australian Business Register lookup, or International for an international company, which is not looked up' representatives: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' description: 'The company representatives' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 reference: type: string example: ABC123 name: type: string example: 'Jane Doe' required: - id - reference - name - abn - acn - kyb_verified - aml_verified - aml_verified_at - bank_verified - abr_status - representatives - description: 'International company created successfully' type: object example: data: id: comp_456 reference: DEF456 name: 'Example Trading Pte Ltd' abn: INT-SG-201912345K acn: null kyb_verified: false aml_verified: false aml_verified_at: null bank_verified: false abr_status: International representatives: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' properties: data: type: object properties: id: type: string example: comp_456 description: 'The unique identifier of the company' reference: type: string example: DEF456 description: 'The unique reference code for the company (GoEscrow ID)' name: type: string example: 'Example Trading Pte Ltd' description: 'The company name' abn: type: string example: INT-SG-201912345K description: 'The Australian Business Number, or INT-- for an international company' acn: type: string example: null description: 'The Australian Company Number' kyb_verified: type: boolean example: false description: 'Whether the company has completed KYB verification' aml_verified: type: boolean example: false description: 'Whether the company has completed AML verification' aml_verified_at: type: string example: null description: 'Timestamp when the company completed AML verification' bank_verified: type: boolean example: false description: 'Whether the company has a verified bank account' abr_status: type: string example: International description: 'The status from the latest Australian Business Register lookup, or International for an international company, which is not looked up' representatives: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' description: 'The company representatives' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 reference: type: string example: ABC123 name: type: string example: 'Jane Doe' required: - id - reference - name - abn - acn - kyb_verified - aml_verified - aml_verified_at - bank_verified - abr_status - representatives 422: description: 'Validation failed, for example a malformed international identifier or a missing address.country' content: application/json: schema: type: object example: message: 'The abn for an international company must look like INT-SG-201912345K: INT, a 2-letter country code, then the registration number (letters and digits only). (and 1 more error)' errors: abn: - 'The abn for an international company must look like INT-SG-201912345K: INT, a 2-letter country code, then the registration number (letters and digits only).' address.country: - 'The address.country field is required.' properties: message: type: string example: 'The abn for an international company must look like INT-SG-201912345K: INT, a 2-letter country code, then the registration number (letters and digits only). (and 1 more error)' errors: type: object properties: abn: type: array example: - 'The abn for an international company must look like INT-SG-201912345K: INT, a 2-letter country code, then the registration number (letters and digits only).' items: type: string address.country: type: array example: - 'The address.country field is required.' items: type: string tags: - 'Company Management' requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: "Ignored when supplied for an ABN; the entity name is sourced from the Australian Business Register (the registered name, or the individual's legal name for sole traders). Required for an international company, as its legal name." example: 'Acme Corp Pty Ltd' abn: type: string description: 'Australian Business Number. For an international company without an ABN, send INT--, for example INT-SG-201912345K. The registration number may contain letters and digits only (3 to 30 characters); letter case is ignored and the value is stored in upper case.' example: '40650703736' acn: type: string description: 'Australian Company Number' example: '004085616' email: type: string description: 'Company email address' example: info@acmecorp.com.au phone: type: string description: 'Company phone number in international format' example: '+61298765432' website: type: string description: 'Company website URL' example: 'https://www.acmecorp.com.au' type: type: string description: 'Company type/structure; sourced from the Australian Business Register when available. For an international company, the value supplied is stored.' example: 'Proprietary Limited' majority_owned_by_another_australian_company: type: boolean description: 'Whether the company is majority owned by another Australian company' example: false majority_owned_by_overseas_person_or_company: type: boolean description: 'Whether the company is majority owned by an overseas person or company' example: false majority_owned_by_listed_australian_company: type: boolean description: 'Whether the company is majority owned by a listed Australian company' example: false acting_as_trustee_for_a_trust: type: boolean description: 'Whether the company is acting as trustee for a trust' example: false representatives: type: array description: 'Existing user UUIDs to attach as company representatives' example: - 9d2e5c8a-1234-5678-9abc-def012345678 items: type: string address: type: object description: "The company's address. All fields are optional for an ABN, where state must be an Australian state code and postcode 4 digits. Required for an international company, with country required and any state or postcode format accepted." example: unit_number: '3' street_number: '20' street: 'Company Street' suburb: Melbourne state: VIC postcode: '3000' country: Australia properties: unit_number: type: string description: 'Unit number' example: '3' street_number: type: string description: 'Street number' example: '20' street: type: string description: 'Street name' example: 'Company Street' suburb: type: string description: 'Suburb or city' example: Melbourne state: type: string description: 'For an ABN, one of NSW, VIC, QLD, WA, SA, TAS, ACT or NT. For an international company, any state or region.' example: VIC postcode: type: string description: 'For an ABN, 4 digits. For an international company, any postcode up to 10 characters.' example: '3000' country: type: string description: 'Country. Required for an international company.' example: Australia required: - abn - majority_owned_by_another_australian_company - majority_owned_by_overseas_person_or_company - majority_owned_by_listed_australian_company - acting_as_trustee_for_a_trust - representatives '/api/v1/companies/{id}': put: summary: 'Update a company' operationId: updateACompany description: 'Updates an existing company. Only provided fields will be updated. ABN must be omitted, even when unchanged; create a new company for a different ABN.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: 'Company updated successfully' type: object example: data: id: comp_123 reference: ABC123 name: 'Acme Corp Pty Ltd' abn: '40650703736' acn: '004085616' kyb_verified: true aml_verified: true aml_verified_at: '2026-06-25T00:00:00.000000Z' bank_verified: true abr_status: Active representatives: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' properties: data: type: object properties: id: type: string example: comp_123 description: 'The unique identifier of the company' reference: type: string example: ABC123 description: 'The unique reference code for the company (GoEscrow ID)' name: type: string example: 'Acme Corp Pty Ltd' description: 'The company name' abn: type: string example: '40650703736' description: 'The Australian Business Number, or INT-- for an international company' acn: type: string example: '004085616' description: 'The Australian Company Number' kyb_verified: type: boolean example: true description: 'Whether the company has completed KYB verification' aml_verified: type: boolean example: true description: 'Whether the company has completed AML verification' aml_verified_at: type: string example: '2026-06-25T00:00:00.000000Z' description: 'Timestamp when the company completed AML verification' bank_verified: type: boolean example: true description: 'Whether the company has a verified bank account' abr_status: type: string example: Active description: 'The status from the latest Australian Business Register lookup, or International for an international company, which is not looked up' representatives: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' description: 'The company representatives' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 reference: type: string example: ABC123 name: type: string example: 'Jane Doe' required: - id - reference - name - abn - acn - kyb_verified - aml_verified - aml_verified_at - bank_verified - abr_status - representatives - description: 'International company updated successfully' type: object example: data: id: comp_456 reference: DEF456 name: 'Example Trading Pte Ltd' abn: INT-SG-201912345K acn: null kyb_verified: true aml_verified: true aml_verified_at: '2026-06-25T00:00:00.000000Z' bank_verified: false abr_status: International representatives: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' properties: data: type: object properties: id: type: string example: comp_456 description: 'The unique identifier of the company' reference: type: string example: DEF456 description: 'The unique reference code for the company (GoEscrow ID)' name: type: string example: 'Example Trading Pte Ltd' description: 'The company name' abn: type: string example: INT-SG-201912345K description: 'The Australian Business Number, or INT-- for an international company' acn: type: string example: null description: 'The Australian Company Number' kyb_verified: type: boolean example: true description: 'Whether the company has completed KYB verification' aml_verified: type: boolean example: true description: 'Whether the company has completed AML verification' aml_verified_at: type: string example: '2026-06-25T00:00:00.000000Z' description: 'Timestamp when the company completed AML verification' bank_verified: type: boolean example: false description: 'Whether the company has a verified bank account' abr_status: type: string example: International description: 'The status from the latest Australian Business Register lookup, or International for an international company, which is not looked up' representatives: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' description: 'The company representatives' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 reference: type: string example: ABC123 name: type: string example: 'Jane Doe' required: - id - reference - name - abn - acn - kyb_verified - aml_verified - aml_verified_at - bank_verified - abr_status - representatives tags: - 'Company Management' requestBody: required: false content: application/json: schema: type: object properties: name: type: string description: 'The company name' example: 'Acme Corp Pty Ltd' acn: type: string description: 'Australian Company Number' example: '004085616' email: type: string description: 'Company email address' example: info@acmecorp.com.au phone: type: string description: 'Company phone number in international format' example: '+61298765432' website: type: string description: 'Company website URL' example: 'https://www.acmecorp.com.au' type: type: string description: 'Company type/structure' example: 'Proprietary Limited' majority_owned_by_another_australian_company: type: boolean description: 'Whether the company is majority owned by another Australian company' example: false majority_owned_by_overseas_person_or_company: type: boolean description: 'Whether the company is majority owned by an overseas person or company' example: false majority_owned_by_listed_australian_company: type: boolean description: 'Whether the company is majority owned by a listed Australian company' example: false acting_as_trustee_for_a_trust: type: boolean description: 'Whether the company is acting as trustee for a trust' example: false add_representatives: type: array description: 'User UUIDs to attach as company representatives' example: - 9d2e5c8a-1234-5678-9abc-def012345678 items: type: string remove_representatives: type: array description: 'User UUIDs to detach as company representatives' example: - 9d2e5c8a-1234-5678-9abc-def012345679 items: type: string address: type: object description: "The company's address. All fields are optional. State must be an Australian state code and postcode 4 digits, except for an international company, where any format is accepted." example: unit_number: '3' street_number: '20' street: 'Company Street' suburb: Melbourne state: VIC postcode: '3000' country: Australia properties: unit_number: type: string description: 'Unit number' example: '3' street_number: type: string description: 'Street number' example: '20' street: type: string description: 'Street name' example: 'Company Street' suburb: type: string description: 'Suburb or city' example: Melbourne state: type: string description: 'For an ABN company, one of NSW, VIC, QLD, WA, SA, TAS, ACT or NT. For an international company, any state or region.' example: VIC postcode: type: string description: 'For an ABN company, 4 digits. For an international company, any postcode up to 10 characters.' example: '3000' country: type: string description: Country example: Australia parameters: - in: path name: company_id description: 'The company UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/companies/{company_id}/files': post: summary: 'Upload company files' operationId: uploadCompanyFiles description: 'Uploads one or more files to a company filing cabinet. The authenticated partner must represent the company.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Files uploaded' content: application/json: schema: type: object example: data: - id: 9d2e5c8a-1234-5678-9abc-def012345678 file: a1b2c3d4/document.pdf filename: document.pdf created_at: '2024-01-15T10:30:00Z' properties: data: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 file: a1b2c3d4/document.pdf filename: document.pdf created_at: '2024-01-15T10:30:00Z' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 file: type: string example: a1b2c3d4/document.pdf filename: type: string example: document.pdf created_at: type: string example: '2024-01-15T10:30:00Z' 422: description: 'Not authorised' content: application/json: schema: type: object example: message: 'Company not found or access denied.' properties: message: type: string example: 'Company not found or access denied.' tags: - 'Company Management' requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array description: 'One or more files to upload.' items: type: string format: binary required: - files parameters: - in: path name: company_id description: 'The company UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string /api/v1/compliance/fingerprint-events: post: summary: 'Record a Fingerprint event' operationId: recordAFingerprintEvent description: "Records Fingerprint device evidence for a user or company. Identify the visitor with the GoEscrow Fingerprint browser key when the user submits the action (not on page load: each identification uses GoEscrow's Fingerprint allowance), then send the event ID from your backend. GoEscrow retrieves the event from Fingerprint itself; do not send visitor IDs, IP addresses or signals.\n\nGoEscrow checks that the event was collected on one of your registered origins, is under five minutes old, and has not been used before. A recorded event is evidence for compliance review. It does not verify identity, change device trust, or approve the action it describes.\n\n**Settlement evidence.** If you trigger settlement through the API (a marketplace transaction you operate, or an Anytime or Timed escrow you created), record a `settlement` event when the buyer approves the settlement on your site, then call settle. Send the buyer as the subject (the buyer company, with the buyer representative on the transaction as the actor, for a company buyer) and the transaction in `context.transaction_id`. GoEscrow's settlement risk check uses this event as the buyer's device: a settlement without one, or whose device shows risk signals, is held for compliance review. An event sent after a settlement is held is used when the settlement is rechecked.\n\n**Earlier evidence.** The settlement risk check also asks whether you recorded the buyer's device before. Any earlier event you recorded for the buyer user from the same device counts: account creation, bank account submission, identity document upload, PayTo agreement initiation, or creating a transaction, including the transaction being settled. Settlement events for the same transaction do not count, so retrying an approval cannot make a device familiar. Record `transaction_creation` with the transaction in `context.transaction_id` and the party that created it (buyer or seller) as the subject. Identify the visitor when they submit the transaction, before you create it: an identification taken more than 5 seconds after the transaction was created is rejected.\n\nEach event ID can be recorded once, so retries are safe without an Idempotency-Key. Sending the same event again with the same subject, actor, action, transaction and submission reference returns the original record with `duplicate: true`. Any other reuse returns 409. GoEscrow must register your collection origins before this endpoint can be used.\n\nError responses include a stable `code` and a `retryable` flag. Retry only when `retryable` is true." parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'The same event was already recorded with the same subject, actor, action, transaction and submission reference' content: application/json: schema: type: object example: data: duplicate: true id: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f status: recorded subject: type: company id: 6f302a63-83af-49df-80d8-c82c62229ce6 actor: user_id: 2ab54e19-65c2-4f51-a9cc-2145299e6010 fingerprint: event_id: 1727926800123.Ab12Cd action: new_company_account transaction_id: null submission_reference: ABN-20261003-00008 recorded_at: '2026-10-03T03:40:05.000000Z' properties: data: type: object properties: duplicate: type: boolean example: true description: 'True when this event had already been recorded with the same binding' id: type: string example: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f description: 'Identifier of the stored evidence record' status: type: string example: recorded description: 'Always recorded. The evidence was verified and stored; this is not an approval.' subject: type: object properties: type: type: string example: company id: type: string example: 6f302a63-83af-49df-80d8-c82c62229ce6 description: 'The subject type and UUID the evidence is stored against' actor: type: object properties: user_id: type: string example: 2ab54e19-65c2-4f51-a9cc-2145299e6010 description: 'The user UUID of the person who operated the browser' fingerprint: type: object properties: event_id: type: string example: 1727926800123.Ab12Cd description: 'The Fingerprint event ID' action: type: string example: new_company_account description: 'The workflow that collected the evidence' transaction_id: type: string example: null description: 'The transaction UUID for transaction_creation and settlement evidence, otherwise null' submission_reference: type: string example: ABN-20261003-00008 description: 'Your submission reference, or null' recorded_at: type: string example: '2026-10-03T03:40:05.000000Z' description: 'When GoEscrow first recorded the event, as an ISO 8601 timestamp' required: - duplicate - id - status - subject - actor - fingerprint - action - transaction_id - submission_reference - recorded_at 201: description: 'Fingerprint event recorded' content: application/json: schema: type: object example: data: id: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f status: recorded duplicate: false subject: type: company id: 6f302a63-83af-49df-80d8-c82c62229ce6 actor: user_id: 2ab54e19-65c2-4f51-a9cc-2145299e6010 fingerprint: event_id: 1727926800123.Ab12Cd action: new_company_account transaction_id: null submission_reference: ABN-20261003-00008 recorded_at: '2026-10-03T03:40:05.000000Z' properties: data: type: object properties: id: type: string example: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f description: 'Identifier of the stored evidence record' status: type: string example: recorded description: 'Always recorded. The evidence was verified and stored; this is not an approval.' duplicate: type: boolean example: false description: 'True when this event had already been recorded with the same binding' subject: type: object properties: type: type: string example: company id: type: string example: 6f302a63-83af-49df-80d8-c82c62229ce6 description: 'The subject type and UUID the evidence is stored against' actor: type: object properties: user_id: type: string example: 2ab54e19-65c2-4f51-a9cc-2145299e6010 description: 'The user UUID of the person who operated the browser' fingerprint: type: object properties: event_id: type: string example: 1727926800123.Ab12Cd description: 'The Fingerprint event ID' action: type: string example: new_company_account description: 'The workflow that collected the evidence' transaction_id: type: string example: null description: 'The transaction UUID for transaction_creation and settlement evidence, otherwise null' submission_reference: type: string example: ABN-20261003-00008 description: 'Your submission reference, or null' recorded_at: type: string example: '2026-10-03T03:40:05.000000Z' description: 'When GoEscrow first recorded the event, as an ISO 8601 timestamp' required: - id - status - duplicate - subject - actor - fingerprint - action - transaction_id - submission_reference - recorded_at 403: description: 'No collection origins are registered for this partner' content: application/json: schema: type: object example: message: 'Fingerprint evidence is not enabled for this partner. Contact GoEscrow to register your collection origins.' code: fingerprint_evidence_not_enabled retryable: false properties: message: type: string example: 'Fingerprint evidence is not enabled for this partner. Contact GoEscrow to register your collection origins.' code: type: string example: fingerprint_evidence_not_enabled description: 'Error responses only: a stable machine-readable error code' retryable: type: boolean example: false description: 'Error responses only: whether retrying the same request can succeed' required: - code - retryable 404: description: 'The subject (subject_not_found), actor (actor_not_found) or transaction (transaction_not_found) does not exist or is not accessible to this partner' content: application/json: schema: type: object example: message: 'Subject not found or access denied.' code: subject_not_found retryable: false properties: message: type: string example: 'Subject not found or access denied.' code: type: string example: subject_not_found description: 'Error responses only: a stable machine-readable error code' retryable: type: boolean example: false description: 'Error responses only: whether retrying the same request can succeed' required: - code - retryable 409: description: 'The event was already recorded with a different binding or used for a GoEscrow login (fingerprint_event_already_assigned), or is being recorded by a concurrent request (fingerprint_event_in_progress, retryable)' content: application/json: schema: type: object example: message: 'This Fingerprint event has already been used for a different submission.' code: fingerprint_event_already_assigned retryable: false properties: message: type: string example: 'This Fingerprint event has already been used for a different submission.' code: type: string example: fingerprint_event_already_assigned description: 'Error responses only: a stable machine-readable error code' retryable: type: boolean example: false description: 'Error responses only: whether retrying the same request can succeed' required: - code - retryable 422: description: 'The event or actor failed verification. Codes: actor_invalid, action_subject_mismatch, settlement_subject_not_buyer, transaction_subject_not_party, transaction_creation_evidence_too_late, fingerprint_event_not_found (retryable), fingerprint_event_invalid, fingerprint_event_expired, fingerprint_event_origin_not_allowed' content: application/json: schema: type: object example: message: 'The Fingerprint event was not collected on a registered origin for this partner.' code: fingerprint_event_origin_not_allowed retryable: false properties: message: type: string example: 'The Fingerprint event was not collected on a registered origin for this partner.' code: type: string example: fingerprint_event_origin_not_allowed description: 'Error responses only: a stable machine-readable error code' retryable: type: boolean example: false description: 'Error responses only: whether retrying the same request can succeed' required: - code - retryable 503: description: 'Fingerprint could not be reached or failed to process the event' content: application/json: schema: type: object example: message: 'Fingerprint verification is temporarily unavailable. Retry later.' code: fingerprint_service_unavailable retryable: true properties: message: type: string example: 'Fingerprint verification is temporarily unavailable. Retry later.' code: type: string example: fingerprint_service_unavailable description: 'Error responses only: a stable machine-readable error code' retryable: type: boolean example: true description: 'Error responses only: whether retrying the same request can succeed' required: - code - retryable tags: - Compliance requestBody: required: true content: application/json: schema: type: object properties: subject: type: object description: 'The account the evidence is about' example: [] properties: type: type: string description: 'user or company' example: company enum: - user - company id: type: string description: 'The user or company UUID. It must be accessible to your partner key.' example: 6f302a63-83af-49df-80d8-c82c62229ce6 required: - type - id actor: type: object description: 'The person who operated the browser' example: [] properties: user_id: type: string description: 'The user UUID of the person who operated the browser. Required for a company subject, where it must be one of the company representatives; for transaction_creation and settlement it must be the representative recorded on that side of the transaction. For a user subject it defaults to, and must equal, the subject.' example: 2ab54e19-65c2-4f51-a9cc-2145299e6010 fingerprint: type: object description: 'The Fingerprint identification event' example: [] properties: event_id: type: string description: 'The Fingerprint event (request) ID returned to the browser' example: 1727926800123.Ab12Cd required: - event_id context: type: object description: 'The workflow that collected the evidence' example: [] properties: action: type: string description: 'The workflow: new_individual_account (user subject), new_company_account (company subject), bank_account_submission (either), identity_document_upload (either), payto_agreement (user subject, initiating a PayTo agreement), transaction_creation (the buyer or seller creating a transaction) or settlement (the buyer approving a settlement you will trigger)' example: new_company_account enum: - new_individual_account - new_company_account - bank_account_submission - identity_document_upload - payto_agreement - transaction_creation - settlement transaction_id: type: string description: 'Required for transaction_creation and settlement, and not allowed for other actions. For transaction_creation, a transaction you created or operate. For settlement, the transaction you will settle: a marketplace transaction you operate, or an Anytime or Timed escrow you created.' example: null submission_reference: type: string description: 'Your own reference for the submission, returned unchanged' example: ABN-20261003-00008 form_type: type: string description: 'Your name for the form, stored for review' example: new_abn_account occurred_at: type: string description: 'When your platform says the submission happened, stored for review. Freshness is checked against the Fingerprint timestamp, not this value.' example: '2026-10-03T13:40:00+10:00' required: - action required: - subject - fingerprint - context '/api/v1/users/{id}': put: summary: 'Update a user' operationId: updateAUser description: 'Updates an existing user for the authenticated partner. Email and phone must remain unique.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'User updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 first_name: John last_name: Doe email: john.doe@example.com phone: '+61412345678' birth_date: '1990-01-15' kyc_verified: false aml_verified: false aml_verified_at: null email_verified: false mobile_verified: false mobilekyc_verified: false bank_verified: false suspended: false address: unit_number: 10B street_number: '123' street: 'Smith St' suburb: Sydney state: NSW postcode: '2000' country: Australia companies: - id: 9d2e5c8a-8765-4321-9abc-def012345678 reference: XYZ789 name: 'Acme Corp Pty Ltd' abn: '53004085616' kyb_verified: true properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 reference: type: string example: ABC123 first_name: type: string example: John last_name: type: string example: Doe email: type: string example: john.doe@example.com phone: type: string example: '+61412345678' birth_date: type: string example: '1990-01-15' kyc_verified: type: boolean example: false aml_verified: type: boolean example: false aml_verified_at: type: string example: null nullable: true email_verified: type: boolean example: false mobile_verified: type: boolean example: false mobilekyc_verified: type: boolean example: false bank_verified: type: boolean example: false suspended: type: boolean example: false address: type: object properties: unit_number: type: string example: 10B street_number: type: string example: '123' street: type: string example: 'Smith St' suburb: type: string example: Sydney state: type: string example: NSW postcode: type: string example: '2000' country: type: string example: Australia companies: type: array example: - id: 9d2e5c8a-8765-4321-9abc-def012345678 reference: XYZ789 name: 'Acme Corp Pty Ltd' abn: '53004085616' kyb_verified: true description: 'The companies the user is a representative for that your partner account can access (at least one of their representatives is one of your users), ordered by name. Includes international companies. Empty when there are none. Each id can be used as company_id when creating a transaction.' items: type: object properties: id: type: string example: 9d2e5c8a-8765-4321-9abc-def012345678 reference: type: string example: XYZ789 name: type: string example: 'Acme Corp Pty Ltd' abn: type: string example: '53004085616' kyb_verified: type: boolean example: true required: - companies tags: - 'User Management' requestBody: required: false content: application/json: schema: type: object properties: first_name: type: string description: "The user's first name" example: John last_name: type: string description: "The user's last name" example: Doe email: type: string description: "The user's email address. Must be a valid email format." example: john.doe@example.com phone: type: string description: "The user's phone number. Australian numbers can be sent as 0412345678, +61412345678 or 61412345678. Numbers from other countries must include the country code (e.g., +447911123456). Stored and returned in E.164 format." example: '+61412345678' birth_date: type: string description: "The user's date of birth in YYYY-MM-DD format. Optional." example: '1990-01-15' address: type: object description: "The user's address. Optional." example: unit_number: 10B street_number: '123' street: 'Smith St' suburb: Sydney state: NSW postcode: '2000' properties: {} parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string /api/v1/users/lookup: get: summary: 'Lookup user or company' operationId: lookupUserOrCompany description: 'Look up an existing user by email, phone, or GoEscrow reference. Company reference matches return only the company name and reference. Exactly one parameter must be provided.' parameters: - in: query name: email description: "The user's email address. Supply exactly one of email, phone, or reference." example: john.doe@example.com required: false schema: type: string description: "The user's email address. Supply exactly one of email, phone, or reference." example: john.doe@example.com - in: query name: phone description: "The user's phone number. Supply exactly one of email, phone, or reference. Accepts 0412345678, +61412345678, or 61412345678. Numbers from other countries must include the country code (e.g., +447911123456)." example: '+61412345678' required: false schema: type: string description: "The user's phone number. Supply exactly one of email, phone, or reference. Accepts 0412345678, +61412345678, or 61412345678. Numbers from other countries must include the country code (e.g., +447911123456)." example: '+61412345678' - in: query name: reference description: 'A user or company GoEscrow reference. Supply exactly one of email, phone, or reference.' example: ABC123 required: false schema: type: string description: 'A user or company GoEscrow reference. Supply exactly one of email, phone, or reference.' example: ABC123 - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: 'User found' type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 first_name: John last_name: Doe email: john.doe@example.com phone: '+61412345678' birth_date: '1990-01-15' kyc_verified: true aml_verified: true aml_verified_at: '2026-06-25T00:00:00.000000Z' email_verified: true mobile_verified: true mobilekyc_verified: true bank_verified: true suspended: false address: unit_number: '1' street_number: '123' street: 'Main Street' suburb: Sydney state: NSW postcode: '2000' country: Australia companies: - id: 9d2e5c8a-8765-4321-9abc-def012345678 reference: XYZ789 name: 'Acme Corp Pty Ltd' abn: '53004085616' kyb_verified: true properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The unique identifier of the user' reference: type: string example: ABC123 description: 'The unique reference code for the user (GoEscrow ID)' first_name: type: string example: John description: "The user's first name" last_name: type: string example: Doe description: "The user's last name" email: type: string example: john.doe@example.com description: "The user's email address" phone: type: string example: '+61412345678' description: "The user's phone number in E.164 format" birth_date: type: string example: '1990-01-15' description: "The user's date of birth" kyc_verified: type: boolean example: true description: 'Whether the user has completed KYC verification' aml_verified: type: boolean example: true description: 'Whether the user has completed AML verification' aml_verified_at: type: string example: '2026-06-25T00:00:00.000000Z' description: 'Timestamp when the user completed AML verification' email_verified: type: boolean example: true description: 'Whether the user has verified their email' mobile_verified: type: boolean example: true description: 'Whether the user has verified their mobile' mobilekyc_verified: type: boolean example: true description: 'Whether the user has completed mobile KYC verification' bank_verified: type: boolean example: true description: 'Whether the user has verified their bank account' suspended: type: boolean example: false description: 'Whether the user account is suspended' address: type: object properties: unit_number: type: string example: '1' street_number: type: string example: '123' street: type: string example: 'Main Street' suburb: type: string example: Sydney state: type: string example: NSW postcode: type: string example: '2000' country: type: string example: Australia description: "The user's address (null if not set)" companies: type: array example: - id: 9d2e5c8a-8765-4321-9abc-def012345678 reference: XYZ789 name: 'Acme Corp Pty Ltd' abn: '53004085616' kyb_verified: true description: 'The companies the user is a representative for that your partner account can access (at least one of their representatives is one of your users), ordered by name. Includes international companies. Empty when there are none. Each id can be used as company_id when creating a transaction.' items: type: object properties: id: type: string example: 9d2e5c8a-8765-4321-9abc-def012345678 reference: type: string example: XYZ789 name: type: string example: 'Acme Corp Pty Ltd' abn: type: string example: '53004085616' kyb_verified: type: boolean example: true required: - id - reference - first_name - last_name - email - phone - birth_date - kyc_verified - aml_verified - aml_verified_at - email_verified - mobile_verified - mobilekyc_verified - bank_verified - suspended - address - companies - description: 'Company found by reference; representative and contact details are never returned' type: object example: data: name: 'Acme Corp Pty Ltd' reference: XYZ789 properties: data: type: object properties: name: type: string example: 'Acme Corp Pty Ltd' description: 'The company name (company reference lookups only)' reference: type: string example: XYZ789 description: 'The unique reference code for the user (GoEscrow ID)' required: - name - reference 404: description: 'No accessible reference match found' content: application/json: schema: type: object example: message: 'User or company not found.' properties: message: type: string example: 'User or company not found.' 422: description: '' content: application/json: schema: oneOf: - description: 'No lookup parameter supplied (legacy user lookup contract)' type: object example: message: 'At least one of email or phone is required.' properties: message: type: string example: 'At least one of email or phone is required.' - description: 'Both legacy user lookup parameters supplied' type: object example: message: 'Please provide either email or phone, not both.' properties: message: type: string example: 'Please provide either email or phone, not both.' - description: 'Reference combined with another lookup parameter' type: object example: message: 'Please provide only one of email, phone, or reference.' properties: message: type: string example: 'Please provide only one of email, phone, or reference.' tags: - 'User Management' '/api/v1/users/{user_id}/verify-mobile': get: summary: 'Send mobile verification code' operationId: sendMobileVerificationCode description: "Sends a verification code via SMS to the user's registered phone number. The code will be valid for a limited time." parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Verification code sent successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' post: summary: 'Verify mobile phone' operationId: verifyMobilePhone description: "Verifies the mobile phone number using the code sent via SMS. Upon successful verification, the user's phone will be marked as verified." parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Phone number verified successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: 'The verification code received via SMS' example: '123456' required: - code parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/verify-email': get: summary: 'Send email verification code' operationId: sendEmailVerificationCode description: "Sends a verification code via email to the user's registered email address. The code will be valid for a limited time." parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Verification code sent successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' post: summary: 'Verify email address' operationId: verifyEmailAddress description: "Verifies the email address using the code sent via email. Upon successful verification, the user's email will be marked as verified." parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Email address verified successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: 'The verification code received via email' example: '123456' required: - code parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/mobile-verification-flow': post: summary: 'Send the mobile ID scan' operationId: sendTheMobileIDScan description: "Sends the user an SMS link to the mobile ID scan for an existing user. Works whether or not the user has already completed KYC or AML verification, so a partner can ask for a fresh scan at any time. The user's current verification status is kept: a scan that is declined or abandoned does not remove KYC or AML verification the user already holds. Sending again within an hour resends the same link. Limited to 5 sends per user every 10 minutes." parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'The ID scan link was sent to the user by SMS' content: application/json: schema: type: array items: type: object example: [] 422: description: '' content: application/json: schema: oneOf: - description: 'The user does not belong to the authenticated partner' type: object example: message: 'User not found or access denied.' properties: message: type: string example: 'User not found or access denied.' - description: 'The user has no phone number' type: object example: message: 'The given data was invalid.' errors: phone: - 'Phone number is required for mobile identification flow.' properties: message: type: string example: 'The given data was invalid.' errors: type: object properties: phone: type: array example: - 'Phone number is required for mobile identification flow.' items: type: string 429: description: 'Too many sends for this user' content: application/json: schema: type: object example: message: 'Too Many Attempts.' properties: message: type: string example: 'Too Many Attempts.' 502: description: 'The ID scan provider could not start a session' content: application/json: schema: type: object example: message: 'Failed to initiate mobile identification flow. Please try again later.' properties: message: type: string example: 'Failed to initiate mobile identification flow. Please try again later.' tags: - 'User Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/bank-statement': get: summary: 'Generate user bank statement' operationId: generateUserBankStatement description: 'Generates and returns a PDF bank statement for the specified user. The statement includes transaction history and account details.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'PDF bank statement generated successfully' content: application/json: schema: type: array items: type: object example: [] tags: - 'User Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/files': post: summary: 'Upload user files' operationId: uploadUserFiles description: 'Uploads one or more files to a user filing cabinet. The authenticated partner must own the user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Files uploaded' content: application/json: schema: type: object example: data: - id: 9d2e5c8a-1234-5678-9abc-def012345678 file: a1b2c3d4/document.pdf filename: document.pdf created_at: '2024-01-15T10:30:00Z' properties: data: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 file: a1b2c3d4/document.pdf filename: document.pdf created_at: '2024-01-15T10:30:00Z' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 file: type: string example: a1b2c3d4/document.pdf filename: type: string example: document.pdf created_at: type: string example: '2024-01-15T10:30:00Z' 422: description: 'Not authorised' content: application/json: schema: type: object example: message: 'User not found or access denied.' properties: message: type: string example: 'User not found or access denied.' tags: - 'User Management' requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array description: 'One or more files to upload.' items: type: string format: binary required: - files parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/password-reset-link': post: summary: 'Generate password reset link' operationId: generatePasswordResetLink description: 'Generates a short-lived password reset link for the user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: type: object example: reset_url: 'https://app.goescrow.com.au/auth/forgot-password/abc123' expires_in: '60 minutes' properties: reset_url: type: string example: 'https://app.goescrow.com.au/auth/forgot-password/abc123' description: 'The password reset URL' expires_in: type: string example: '60 minutes' description: 'Link expiry time' required: - reset_url - expires_in tags: - 'User Management' requestBody: required: false content: application/json: schema: type: object properties: send_email: type: boolean description: 'If true, sends a password reset email to the user.' example: true parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string /api/v1/disputes: post: summary: 'Create a dispute' operationId: createADispute description: 'Creates a dispute for a transaction. This will mark the transaction as disputed and create a compliance note for the CS team to review.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string - in: header name: Idempotency-Key description: '' example: 6f3a8e1c-9b2d-4f5a-8c1e-2a7b9d0e1f23 schema: type: string responses: 201: description: 'Dispute created' content: application/json: schema: type: object example: message: 'Dispute created successfully.' dispute_reference: DISP-2024-001234 transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: disputed properties: message: type: string example: 'Dispute created successfully.' description: 'Status message' dispute_reference: type: string example: DISP-2024-001234 description: 'The compliance note reference for tracking' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction ID' status: type: string example: disputed description: 'The new transaction status' required: - message - dispute_reference - transaction_id - status 422: description: 'Invalid transaction status' content: application/json: schema: type: object example: message: 'Transaction status does not allow disputes.' properties: message: type: string example: 'Transaction status does not allow disputes.' description: 'Status message' required: - message tags: - 'Dispute Management' requestBody: required: true content: application/json: schema: type: object properties: requester_id: type: string description: 'The ID of the user raising the dispute' example: 9d2e5c8a-1234-5678-9abc-def012345678 requester_role: type: string description: 'The role of the requester: buyer or seller' example: buyer enum: - buyer - seller transaction_id: type: string description: 'The transaction ID' example: 9d2e5c8a-1234-5678-9abc-def012345678 request_type: type: string description: 'The type of request: pause, settle_to_requester, split, other' example: pause enum: - pause - settle_to_requester - split - other issue_description: type: string description: 'Detailed description of the issue' example: 'The goods were not delivered as described.' required: - requester_id - requester_role - transaction_id - request_type - issue_description '/api/v1/transactions/{transaction_id}/cancellation-request': post: summary: 'Request transaction cancellation' operationId: requestTransactionCancellation description: 'Initiates cancellation. For standard and marketplace multi-payee Anytime and Timed transactions, supply only the requesting party ID and, when needed, its representative ID; the API already knows the other parties. Unfunded pending, accepted or awaiting_beneficiary_confirmation transactions enter cancellation_requested with the requester approval recorded. If requires_2fa is true, call verify-cancellation to create the request. Single-payee pending transactions retain immediate cancellation; accepted transactions retain the existing counterparty flow.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string - in: header name: Idempotency-Key description: '' example: 6f3a8e1c-9b2d-4f5a-8c1e-2a7b9d0e1f23 schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: '2FA required for funded accepted transaction' type: object example: message: "Cancellation requested. 2FA verification required. Codes sent to requester's email and phone." requires_2fa: true transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: accepted properties: message: type: string example: "Cancellation requested. 2FA verification required. Codes sent to requester's email and phone." description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: true description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: accepted description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' required: - message - requires_2fa - transaction_id - status - description: 'Cancellation request created' type: object example: message: 'Cancellation requested. Waiting for counterparty response.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: cancellation_requested properties: message: type: string example: 'Cancellation requested. Waiting for counterparty response.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: cancellation_requested description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' required: - message - requires_2fa - transaction_id - status - description: 'Single-payee pending transaction cancelled' type: object example: message: 'Transaction cancelled successfully.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: canceled properties: message: type: string example: 'Transaction cancelled successfully.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: canceled description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' required: - message - requires_2fa - transaction_id - status - description: 'Multi-payee approval recorded; other parties must still approve' type: object example: message: 'Approval recorded. Waiting for the remaining parties.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: cancellation_requested cancellation_request_id: 2c9bb6a0-b123-4567-89ab-0123456789ab properties: message: type: string example: 'Approval recorded. Waiting for the remaining parties.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: cancellation_requested description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: 2c9bb6a0-b123-4567-89ab-0123456789ab description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status - description: 'Multi-payee verification codes sent; approval not yet recorded' type: object example: message: 'Verification codes sent. Verify them to record this party’s approval.' requires_2fa: true transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: accepted cancellation_request_id: null properties: message: type: string example: 'Verification codes sent. Verify them to record this party’s approval.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: true description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: accepted description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: null description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status tags: - 'Transaction Cancellation' requestBody: required: true content: application/json: schema: type: object properties: requester_id: type: string description: 'The user or company legal-party ID requesting cancellation' example: 9d2e5c8a-1234-5678-9abc-def012345678 representative_id: type: string description: 'Multi-payee only: UUID of a current representative of the acting company. Required when the company has multiple representatives; optional when exactly one exists. Use the same representative for code delivery and verification. Omit for an individual party.' example: 9d2e5c8a-1234-5678-9abc-def012345679 required: - requester_id parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/verify-cancellation': post: summary: 'Verify cancellation request 2FA codes' operationId: verifyCancellationRequest2FACodes description: 'Verifies requester codes and creates the cancellation request. For multi-payee transactions, this records only the requester approval and returns cancellation_request_id for the remaining parties. Use the same requester_id and representative_id as the code-delivery call. No cancellation_request_id is needed to create the request.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: 'Cancellation request created' type: object example: message: 'Cancellation requested. Waiting for counterparty response.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: cancellation_requested properties: message: type: string example: 'Cancellation requested. Waiting for counterparty response.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: cancellation_requested description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' required: - message - requires_2fa - transaction_id - status - description: 'Multi-payee approval recorded; other parties must still approve' type: object example: message: 'Approval recorded. Waiting for the remaining parties.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: cancellation_requested cancellation_request_id: 2c9bb6a0-b123-4567-89ab-0123456789ab properties: message: type: string example: 'Approval recorded. Waiting for the remaining parties.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: cancellation_requested description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: 2c9bb6a0-b123-4567-89ab-0123456789ab description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status 422: description: 'Invalid codes' content: application/json: schema: type: object example: message: 'Invalid or expired verification codes.' properties: message: type: string example: 'Invalid or expired verification codes.' description: 'Status message. Use status and requires_2fa to decide the next step.' required: - message tags: - 'Transaction Cancellation' requestBody: required: true content: application/json: schema: type: object properties: requester_id: type: string description: 'The user or company legal-party ID requesting cancellation' example: 9d2e5c8a-1234-5678-9abc-def012345678 email_code: type: string description: 'The 6-digit code sent to email' example: '123456' phone_code: type: string description: 'The 6-digit code sent to phone' example: '654321' representative_id: type: string description: 'Multi-payee only: UUID of a current representative of the acting company. Required when the company has multiple representatives; optional when exactly one exists. Use the same representative for code delivery and verification. Omit for an individual party.' example: 9d2e5c8a-1234-5678-9abc-def012345679 required: - requester_id - email_code - phone_code parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/cancellation-accept': post: summary: 'Accept transaction cancellation' operationId: acceptTransactionCancellation description: 'Records approval from one outstanding party. Multi-payee requests require the current cancellation_request_id. If requires_2fa is true, codes were sent but approval is not yet recorded: call verify-cancellation-accept. Otherwise HTTP 200 may still have status cancellation_requested while other approvals are outstanding. Only the final required approval completes cancellation. Single-payee requests retain the existing counterparty flow.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: '2FA required for funded transaction' type: object example: message: "Cancellation acceptance requires 2FA verification. Codes sent to accepter's email and phone." requires_2fa: true transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: cancellation_requested properties: message: type: string example: "Cancellation acceptance requires 2FA verification. Codes sent to accepter's email and phone." description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: true description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: cancellation_requested description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' required: - message - requires_2fa - transaction_id - status - description: 'Cancellation accepted' type: object example: message: 'Cancellation accepted. Transaction cancelled successfully.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: canceled properties: message: type: string example: 'Cancellation accepted. Transaction cancelled successfully.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: canceled description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' required: - message - requires_2fa - transaction_id - status - description: 'Multi-payee approval recorded; other parties must still approve' type: object example: message: 'Approval recorded. Waiting for the remaining parties.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: cancellation_requested cancellation_request_id: 2c9bb6a0-b123-4567-89ab-0123456789ab properties: message: type: string example: 'Approval recorded. Waiting for the remaining parties.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: cancellation_requested description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: 2c9bb6a0-b123-4567-89ab-0123456789ab description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status - description: 'Multi-payee verification codes sent; approval not yet recorded' type: object example: message: 'Verification codes sent. Verify them to record this party’s approval.' requires_2fa: true transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: cancellation_requested cancellation_request_id: 2c9bb6a0-b123-4567-89ab-0123456789ab properties: message: type: string example: 'Verification codes sent. Verify them to record this party’s approval.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: true description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: cancellation_requested description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: 2c9bb6a0-b123-4567-89ab-0123456789ab description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status - description: 'Multi-payee final approval completes cancellation' type: object example: message: 'All parties approved. Transaction cancelled.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: canceled cancellation_request_id: null properties: message: type: string example: 'All parties approved. Transaction cancelled.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: canceled description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: null description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status 422: description: 'Multi-payee cancellation request ID missing or stale' content: application/json: schema: type: object example: message: 'The cancellation request has changed. Refresh the transaction and try again.' errors: cancellation_request_id: - 'The cancellation request has changed. Refresh the transaction and try again.' properties: message: type: string example: 'The cancellation request has changed. Refresh the transaction and try again.' description: 'Status message. Use status and requires_2fa to decide the next step.' errors: type: object properties: cancellation_request_id: type: array example: - 'The cancellation request has changed. Refresh the transaction and try again.' items: type: string required: - message tags: - 'Transaction Cancellation' requestBody: required: true content: application/json: schema: type: object properties: accepter_id: type: string description: 'The user or company legal-party ID accepting cancellation' example: 9d2e5c8a-1234-5678-9abc-def012345678 representative_id: type: string description: 'Multi-payee only: UUID of a current representative of the acting company. Required when the company has multiple representatives; optional when exactly one exists. Use the same representative for code delivery and verification. Omit for an individual party.' example: 9d2e5c8a-1234-5678-9abc-def012345679 cancellation_request_id: type: string description: 'Required for multi-payee cancellation responses: the current ID returned when the cancellation request was created or read from the transaction. Missing or stale IDs return 422. Not required for single-payee transactions.' example: 2c9bb6a0-b123-4567-89ab-0123456789ab required: - accepter_id parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/verify-cancellation-accept': post: summary: 'Verify cancellation acceptance 2FA codes' operationId: verifyCancellationAcceptance2FACodes description: 'Verifies one party approval using email_code and phone_code. For multi-payee transactions, include the current cancellation_request_id and use the same accepter_id and representative_id as the code-delivery call. Cancellation remains pending until the payer and every payee have approved with any required verification.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: 'Cancellation accepted' type: object example: message: 'Cancellation accepted. Transaction cancelled successfully.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: canceled properties: message: type: string example: 'Cancellation accepted. Transaction cancelled successfully.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: canceled description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' required: - message - requires_2fa - transaction_id - status - description: 'Multi-payee approval recorded; other parties must still approve' type: object example: message: 'Approval recorded. Waiting for the remaining parties.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: cancellation_requested cancellation_request_id: 2c9bb6a0-b123-4567-89ab-0123456789ab properties: message: type: string example: 'Approval recorded. Waiting for the remaining parties.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: cancellation_requested description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: 2c9bb6a0-b123-4567-89ab-0123456789ab description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status - description: 'Multi-payee final approval completes cancellation' type: object example: message: 'All parties approved. Transaction cancelled.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: canceled cancellation_request_id: null properties: message: type: string example: 'All parties approved. Transaction cancelled.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: canceled description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: null description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status 422: description: '' content: application/json: schema: oneOf: - description: 'Invalid codes' type: object example: message: 'Invalid or expired verification codes.' properties: message: type: string example: 'Invalid or expired verification codes.' description: 'Status message. Use status and requires_2fa to decide the next step.' required: - message - description: 'Multi-payee cancellation request ID missing or stale' type: object example: message: 'The cancellation request has changed. Refresh the transaction and try again.' errors: cancellation_request_id: - 'The cancellation request has changed. Refresh the transaction and try again.' properties: message: type: string example: 'The cancellation request has changed. Refresh the transaction and try again.' description: 'Status message. Use status and requires_2fa to decide the next step.' errors: type: object properties: cancellation_request_id: type: array example: - 'The cancellation request has changed. Refresh the transaction and try again.' items: type: string required: - message tags: - 'Transaction Cancellation' requestBody: required: true content: application/json: schema: type: object properties: accepter_id: type: string description: 'The user or company legal-party ID accepting cancellation' example: 9d2e5c8a-1234-5678-9abc-def012345678 email_code: type: string description: 'The 6-digit code sent to email' example: '123456' phone_code: type: string description: 'The 6-digit code sent to phone' example: '654321' representative_id: type: string description: 'Multi-payee only: UUID of a current representative of the acting company. Required when the company has multiple representatives; optional when exactly one exists. Use the same representative for code delivery and verification. Omit for an individual party.' example: 9d2e5c8a-1234-5678-9abc-def012345679 cancellation_request_id: type: string description: 'Required for multi-payee cancellation responses: the current ID returned when the cancellation request was created or read from the transaction. Missing or stale IDs return 422. Not required for single-payee transactions.' example: 2c9bb6a0-b123-4567-89ab-0123456789ab required: - accepter_id - email_code - phone_code parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/cancellation-deny': post: summary: 'Deny transaction cancellation' operationId: denyTransactionCancellation description: 'Denies an active cancellation request without verification codes. For multi-payee transactions, only a party still requiring approval may deny; supply the current cancellation_request_id. Normally restores the previous status. Within 12 hours before a future Timed release, multi-payee denial instead sets contact_helpdesk, suspends payee settlements and alerts customer service. Single-payee requests retain their existing denial flow.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: 'Cancellation denied' type: object example: message: 'Cancellation denied. Transaction reverted to active status.' transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: accepted properties: message: type: string example: 'Cancellation denied. Transaction reverted to active status.' description: 'Status message. Use status and requires_2fa to decide the next step.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: accepted description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' required: - message - transaction_id - status - description: 'Multi-payee cancellation denied; previous status restored' type: object example: message: 'Cancellation denied. Transaction is active again.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: accepted cancellation_request_id: null properties: message: type: string example: 'Cancellation denied. Transaction is active again.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: accepted description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: null description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status - description: 'Multi-payee Timed cancellation denial requires safety review' type: object example: message: 'Transaction under review. CS Team has been notified.' requires_2fa: false transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: contact_helpdesk cancellation_request_id: null properties: message: type: string example: 'Transaction under review. CS Team has been notified.' description: 'Status message. Use status and requires_2fa to decide the next step.' requires_2fa: type: boolean example: false description: 'Whether codes were sent and the corresponding verification endpoint must be called before recording this approval.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction UUID.' status: type: string example: contact_helpdesk description: 'Current transaction status. For multi-payee transactions, cancellation_requested can mean that further approvals remain; canceled means cancellation completed.' cancellation_request_id: type: string example: null description: 'Multi-payee only: current cancellation attempt ID while status is cancellation_requested; null otherwise. Single-payee responses omit this field.' nullable: true required: - message - requires_2fa - transaction_id - status 422: description: 'Multi-payee cancellation request ID missing or stale' content: application/json: schema: type: object example: message: 'The cancellation request has changed. Refresh the transaction and try again.' errors: cancellation_request_id: - 'The cancellation request has changed. Refresh the transaction and try again.' properties: message: type: string example: 'The cancellation request has changed. Refresh the transaction and try again.' description: 'Status message. Use status and requires_2fa to decide the next step.' errors: type: object properties: cancellation_request_id: type: array example: - 'The cancellation request has changed. Refresh the transaction and try again.' items: type: string required: - message tags: - 'Transaction Cancellation' requestBody: required: true content: application/json: schema: type: object properties: denier_id: type: string description: 'The user or company legal-party ID denying cancellation' example: 9d2e5c8a-1234-5678-9abc-def012345678 representative_id: type: string description: 'Multi-payee only: UUID of a current representative of the acting company. Required when the company has multiple representatives; optional when exactly one exists. Use the same representative for code delivery and verification. Omit for an individual party.' example: 9d2e5c8a-1234-5678-9abc-def012345679 cancellation_request_id: type: string description: 'Required for multi-payee cancellation responses: the current ID returned when the cancellation request was created or read from the transaction. Missing or stale IDs return 422. Not required for single-payee transactions.' example: 2c9bb6a0-b123-4567-89ab-0123456789ab required: - denier_id parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string /api/v1/transactions: post: summary: 'Create transaction' operationId: createTransaction description: 'Creates a new escrow transaction with disbursements. Partner API transactions are auto-accepted (skip pending status).' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string - in: header name: Idempotency-Key description: '' example: 6f3a8e1c-9b2d-4f5a-8c1e-2a7b9d0e1f23 schema: type: string responses: 201: description: 'Transaction created successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: TXN-2024-001234 type: anytime_escrow sub_type: marketplace status: accepted funding_status: pending amount: 150000.5 details: 'Property settlement for 123 Main St' created_at: '2024-01-15T10:30:00Z' beneficiaries: - id: 9d2e5c8a-1234-5678-9abc-def012345679 first_name: 'G**g' last_name: 'R*******t' mobile: '+61******001' required: true status: pending properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'Transaction ID' reference: type: string example: TXN-2024-001234 description: 'Transaction reference code' type: type: string example: anytime_escrow description: 'Transaction type (anytime_escrow|timed_escrow)' sub_type: type: string example: marketplace description: 'Transaction sub type (null, marketplace, super_disbursement)' status: type: string example: accepted description: 'Transaction status' funding_status: type: string example: pending description: 'Funding status' amount: type: number example: 150000.5 details: type: string example: 'Property settlement for 123 Main St' description: 'Transaction details/description' created_at: type: string example: '2024-01-15T10:30:00Z' description: 'Creation datetime (ISO8601)' beneficiaries: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345679 first_name: 'G**g' last_name: 'R*******t' mobile: '+61******001' required: true status: pending description: 'Masked beneficiaries attached to the transaction (id, first_name, last_name, mobile, required, status)' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 first_name: type: string example: 'G**g' last_name: type: string example: 'R*******t' mobile: type: string example: '+61******001' required: type: boolean example: true status: type: string example: pending required: - id - reference - type - sub_type - status - funding_status - details - created_at - beneficiaries 422: description: 'A company is inaccessible or ineligible, the parties are self-dealing, or a disbursement does not identify exactly one recipient' content: application/json: schema: type: object example: message: 'This company is not currently eligible to transact.' errors: company_id: - 'This company is not currently eligible to transact.' properties: message: type: string example: 'This company is not currently eligible to transact.' errors: type: object properties: company_id: type: array example: - 'This company is not currently eligible to transact.' items: type: string tags: - 'Transaction Management' requestBody: required: true content: application/json: schema: type: object properties: action: type: string description: 'Transaction direction: buy (payer) or sell (requester).' example: buy type: type: string description: 'Transaction type: anytime_escrow or timed_escrow.' example: anytime_escrow amount_type: type: string description: 'Indicates whether amount is escrow (gross) or settlement (net).' example: escrow other_user: type: string description: 'Counterparty user ID for standard escrow. Exactly one of other_user or other_company_id is required when disbursements are omitted.' example: 9d2e5c8a-1234-5678-9abc-def012345678 other_company_id: type: string description: 'Counterparty company ID for standard escrow. The company must be accessible to the partner and eligible to transact.' example: 9d2e5c8a-1234-5678-9abc-def012345678 sub_type: type: string description: 'The transaction sub type (optional: omit or null for plain anytime escrow, marketplace for marketplace-controlled settlement)' example: marketplace user_id: type: string description: 'The ID of the buyer/payer' example: 9d2e5c8a-1234-5678-9abc-def012345678 company_id: type: string description: 'Source legal-party company ID. The user_id must be its representative. Required for super_disbursement and must then match the partner associated company.' example: 9d2e5c8a-1234-5678-9abc-def012345678 marketplace_operator_id: type: string description: 'The partner ID of the marketplace operator who can trigger settlement (required for marketplace sub_type)' example: 9d2e5c8a-1234-5678-9abc-def012345678 release_at: type: string description: 'The date/time for auto-release (creates timed escrow). ISO 8601 format. Required when type is timed_escrow.' example: '2024-12-31T23:59:59Z' details: type: string description: 'Transaction details and description' example: 'Dental Surgery' amount: type: integer description: 'Total transaction amount in cents (e.g., 15000050 for $150,000.50)' example: 15000050 disbursements: type: array description: 'Array of disbursement objects (required for super_disbursement). Omit for standard escrow to allocate automatically to other_user or other_company_id.' example: - eius items: type: string beneficiaries: type: array description: 'Beneficiaries to attach to the transaction. Only valid when sub_type is marketplace.' example: - first_name: Greg last_name: Recipient mobile: '+61400000001' required: true items: type: object properties: first_name: type: string description: 'The beneficiary first name (maximum 100 characters).' example: Greg last_name: type: string description: 'The beneficiary last name (maximum 100 characters).' example: Recipient mobile: type: string description: 'A valid Australian mobile number. A beneficiary mobile cannot belong to a transaction party or the marketplace operator.' example: '+61400000001' required: type: boolean description: 'Whether the beneficiary is required for settlement. Defaults to true. An optional beneficiary who declines still blocks settlement.' example: true required: - first_name - last_name - mobile required: - action - type - amount_type - user_id - details - amount /api/v1/transactions/status: get: summary: 'Get transaction status by identifier' operationId: getTransactionStatusByIdentifier description: 'Returns full transaction details including funding information. Provide exactly one of transaction_id or reference_id. Requires party_id to verify access.' parameters: - in: query name: transaction_id description: 'The transaction UUID (36-character internal identifier). Required when reference_id is not provided. Must not be provided with reference_id.' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: false schema: type: string description: 'The transaction UUID (36-character internal identifier). Required when reference_id is not provided. Must not be provided with reference_id.' example: 9d2e5c8a-1234-5678-9abc-def012345678 - in: query name: reference_id description: 'The transaction reference number. Required when transaction_id is not provided. Must not be provided with transaction_id.' example: TXN-2024-001234 required: false schema: type: string description: 'The transaction reference number. Required when transaction_id is not provided. Must not be provided with transaction_id.' example: TXN-2024-001234 - in: query name: party_id description: 'The ID of the buyer, seller, or disbursement recipient to verify access' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string description: 'The ID of the buyer, seller, or disbursement recipient to verify access' example: 9d2e5c8a-1234-5678-9abc-def012345678 - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Transaction details' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: TXN-2024-001234 type: anytime_escrow sub_type: marketplace status: accepted funding_status: pending amount: 150000.5 fee: 1500 amount_with_fee: 151500.5 details: 'Property settlement' release_at: null created_at: '2024-01-15T10:30:00Z' buyer_id: 9d2e5c8a-1234-5678-9abc-def012345678 buyer_reference: ABC123 seller_id: 9d2e5c8a-1234-5678-9abc-def012345679 seller_reference: XYZ789 other_party_hint: 'J*** D***' funding_details: bsb: '123456' account_number: '12345678' account_name: 'GoEscrow Trust' pay_id: pay@goescrow.com.au reference: TXN-2024-001234 rail: poprail account_scope: transaction payment_reference: TXN-2024-001234 reference_required: false provisioning_status: ready amount_received: '0.00' amount_outstanding: '151500.50' beneficiaries: - id: 5c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f first_name: 'J**n' last_name: 'S***h' mobile: '+61******678' required: true status: pending settled_amount: 50000.25 remaining_escrow_balance: 100000.25 payees: - payee_id: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: 150000.5 settled_amount: 50000.25 remaining_amount: 100000.25 properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 reference: type: string example: TXN-2024-001234 type: type: string example: anytime_escrow sub_type: type: string example: marketplace status: type: string example: accepted funding_status: type: string example: pending amount: type: number example: 150000.5 fee: type: integer example: 1500 amount_with_fee: type: number example: 151500.5 details: type: string example: 'Property settlement' release_at: type: string example: null nullable: true created_at: type: string example: '2024-01-15T10:30:00Z' buyer_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 buyer_reference: type: string example: ABC123 seller_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 seller_reference: type: string example: XYZ789 other_party_hint: type: string example: 'J*** D***' funding_details: type: object properties: bsb: type: string example: '123456' account_number: type: string example: '12345678' account_name: type: string example: 'GoEscrow Trust' pay_id: type: string example: pay@goescrow.com.au reference: type: string example: TXN-2024-001234 rail: type: string example: poprail account_scope: type: string example: transaction payment_reference: type: string example: TXN-2024-001234 reference_required: type: boolean example: false provisioning_status: type: string example: ready amount_received: type: string example: '0.00' amount_outstanding: type: string example: '151500.50' beneficiaries: type: array example: - id: 5c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f first_name: 'J**n' last_name: 'S***h' mobile: '+61******678' required: true status: pending description: 'Beneficiaries who confirm receipt before settlement, with masked names and mobile, whether they are required, and their status' items: type: object properties: id: type: string example: 5c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f first_name: type: string example: 'J**n' last_name: type: string example: 'S***h' mobile: type: string example: '+61******678' required: type: boolean example: true status: type: string example: pending settled_amount: type: number example: 50000.25 description: 'Amount paid to payees so far through partial settlements, in dollars' remaining_escrow_balance: type: number example: 100000.25 description: 'Net amount still held in escrow for payees, in dollars' payees: type: array example: - payee_id: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: 150000.5 settled_amount: 50000.25 remaining_amount: 100000.25 description: "Each payee's ID, allocation, settled amount and remaining amount, in dollars" items: type: object properties: payee_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: type: number example: 150000.5 settled_amount: type: number example: 50000.25 remaining_amount: type: number example: 100000.25 required: - beneficiaries - settled_amount - remaining_escrow_balance - payees tags: - 'Transaction Management' requestBody: required: true content: application/json: schema: type: object properties: transaction_id: type: string description: 'This field is required when reference_id is not present. Must be a valid UUID.' example: 0d90054a-9c5c-3ce4-8db8-625eeab6204c reference_id: type: string description: 'This field is required when transaction_id is not present.' example: aut party_id: type: string description: 'Must be a valid UUID.' example: f57b254a-e049-3363-a0c1-b4be4a679eac required: - party_id '/api/v1/transactions/{id}': get: summary: 'Get transaction status' operationId: getTransactionStatus description: 'Returns full transaction details including funding information. Requires party_id to verify access.' parameters: - in: query name: party_id description: 'The ID of the buyer or seller to verify access' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string description: 'The ID of the buyer or seller to verify access' example: 9d2e5c8a-1234-5678-9abc-def012345678 - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Transaction details' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: TXN-2024-001234 type: anytime_escrow sub_type: marketplace status: accepted funding_status: pending amount: 150000.5 fee: 1500 amount_with_fee: 151500.5 details: 'Property settlement' release_at: null created_at: '2024-01-15T10:30:00Z' buyer_id: 9d2e5c8a-1234-5678-9abc-def012345678 buyer_reference: ABC123 seller_id: 9d2e5c8a-1234-5678-9abc-def012345679 seller_reference: XYZ789 other_party_hint: 'J*** D***' funding_details: bsb: '123456' account_number: '12345678' account_name: 'GoEscrow Trust' pay_id: pay@goescrow.com.au reference: TXN-2024-001234 rail: poprail account_scope: transaction payment_reference: TXN-2024-001234 reference_required: false provisioning_status: ready amount_received: '0.00' amount_outstanding: '151500.50' beneficiaries: - id: 5c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f first_name: 'J**n' last_name: 'S***h' mobile: '+61******678' required: true status: pending settled_amount: 50000.25 remaining_escrow_balance: 100000.25 payees: - payee_id: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: 150000.5 settled_amount: 50000.25 remaining_amount: 100000.25 properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The unique transaction ID' reference: type: string example: TXN-2024-001234 description: 'The transaction reference number' type: type: string example: anytime_escrow description: 'The transaction type: anytime_escrow, timed_escrow, super_disbursement' sub_type: type: string example: marketplace description: 'The transaction sub-type: super_disbursement, marketplace' status: type: string example: accepted description: 'The transaction status' funding_status: type: string example: pending description: 'The funding status' amount: type: number example: 150000.5 description: 'Net settlement amount in dollars (the create response instead uses a Money object in cents).' fee: type: integer example: 1500 description: 'The escrow fee in dollars' amount_with_fee: type: number example: 151500.5 description: 'Total amount including fee' details: type: string example: 'Property settlement' release_at: type: string example: null description: 'Auto-release date for timed escrow (null for anytime)' created_at: type: string example: '2024-01-15T10:30:00Z' buyer_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 buyer_reference: type: string example: ABC123 seller_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 seller_reference: type: string example: XYZ789 other_party_hint: type: string example: 'J*** D***' funding_details: type: object properties: bsb: type: string example: '123456' account_number: type: string example: '12345678' account_name: type: string example: 'GoEscrow Trust' pay_id: type: string example: pay@goescrow.com.au reference: type: string example: TXN-2024-001234 rail: type: string example: poprail description: 'Pinned funding rail: poprail or fixedrail' account_scope: type: string example: transaction description: 'Account scope: transaction for PopRail or party for FixedRail' payment_reference: type: string example: TXN-2024-001234 description: 'Reference to include with the payment. BECS may truncate lodgement references; a unique prefix of at least 12 hexadecimal UUID characters is accepted.' reference_required: type: boolean example: false description: 'Whether the payment reference is required for automatic allocation' provisioning_status: type: string example: ready description: 'Funding account readiness: ready or pending' amount_received: type: string example: '0.00' description: 'Active amount received as a major-unit decimal string' amount_outstanding: type: string example: '151500.50' description: 'Outstanding amount as a major-unit decimal string' required: - rail - account_scope - payment_reference - reference_required - provisioning_status - amount_received - amount_outstanding description: 'Bank details for EFT/PayID funding' beneficiaries: type: array example: - id: 5c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f first_name: 'J**n' last_name: 'S***h' mobile: '+61******678' required: true status: pending description: 'Beneficiaries who confirm receipt before settlement, with masked names and mobile, whether they are required, and their status' items: type: object properties: id: type: string example: 5c1d2e3f-4a5b-6c7d-8e9f-0a1b2c3d4e5f first_name: type: string example: 'J**n' last_name: type: string example: 'S***h' mobile: type: string example: '+61******678' required: type: boolean example: true status: type: string example: pending settled_amount: type: number example: 50000.25 description: 'Amount paid to payees so far through partial settlements, in dollars' remaining_escrow_balance: type: number example: 100000.25 description: 'Net amount still held in escrow for payees, in dollars' payees: type: array example: - payee_id: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: 150000.5 settled_amount: 50000.25 remaining_amount: 100000.25 description: "Each payee's ID, allocation, settled amount and remaining amount, in dollars" items: type: object properties: payee_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: type: number example: 150000.5 settled_amount: type: number example: 50000.25 remaining_amount: type: number example: 100000.25 required: - id - reference - type - sub_type - status - funding_status - amount - fee - amount_with_fee - release_at - funding_details - beneficiaries - settled_amount - remaining_escrow_balance - payees tags: - 'Transaction Management' parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/beneficiaries/{beneficiary_id}/confirmation-request': post: summary: 'Request beneficiary confirmation' operationId: requestBeneficiaryConfirmation description: 'Creates or rotates a single-use beneficiary confirmation link and sends it by SMS to the beneficiary. The token and confirmation URL are not returned to the partner.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Confirmation link sent by SMS' content: application/json: schema: type: object example: data: message: 'Confirmation link sent' beneficiary_id: 9d2e5c8a-1234-5678-9abc-def012345678 sent_to: '+614****5678' expires_at: '2026-08-16T12:00:00+00:00' heading: 'Confirm receipt' properties: data: type: object properties: message: type: string example: 'Confirmation link sent' description: 'A safe acknowledgement that the confirmation link was sent.' beneficiary_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The UUID of the beneficiary receiving the confirmation request.' sent_to: type: string example: '+614****5678' description: 'The masked mobile number to which the confirmation SMS was sent.' expires_at: type: string example: '2026-08-16T12:00:00+00:00' description: 'The confirmation link expiry time as an ISO 8601 timestamp.' heading: type: string example: 'Confirm receipt' description: 'The heading displayed on the beneficiary confirmation page.' required: - message - beneficiary_id - sent_to - expires_at - heading tags: - 'Transaction Management' requestBody: required: false content: application/json: schema: type: object properties: heading: type: string description: 'Optional plain-text confirmation page heading (maximum 60 characters).' example: 'Confirm your session' parameters: - in: path name: transaction description: 'The transaction UUID' example: voluptate required: true schema: type: string - in: path name: beneficiary description: 'The beneficiary UUID' example: nemo required: true schema: type: string /api/v1/transactions/quote: post: summary: 'Get transaction quote' operationId: getTransactionQuote description: 'Calculates fees and provides a quote for a transaction without creating it. Uses the same request structure as transaction creation. This allows partners to show pricing to their customers before committing to a transaction.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Transaction quote calculated successfully' content: application/json: schema: type: object example: data: sub_type: super_disbursement amount: 150000.5 partner_fee: 299.4 partner_fee_percentage: 0.2 goescrow_fee: 0 goescrow_fee_percentage: 0 total_fees: 299.4 net_amount: 149701.1 disbursements_count: 2 disbursements: - user_id: 9d2e5c8a-1234-5678-9abc-def012345679 amount: 74850.55 - company_id: 9d2e5c8a-1234-5678-9abc-def012345680 amount: 74850.55 properties: data: type: object properties: sub_type: type: string example: super_disbursement description: 'Transaction sub type (null|super_disbursement|marketplace)' amount: type: number example: 150000.5 description: 'Gross amount in dollars' partner_fee: type: number example: 299.4 description: 'Partner fee in dollars' partner_fee_percentage: type: number example: 0.2 description: 'Partner fee percentage applied' goescrow_fee: type: integer example: 0 description: 'GoEscrow fee in dollars' goescrow_fee_percentage: type: integer example: 0 description: 'GoEscrow fee percentage applied' total_fees: type: number example: 299.4 description: 'Total fees in dollars' net_amount: type: number example: 149701.1 description: 'Net amount after fees in dollars' disbursements_count: type: integer example: 2 description: 'Count of disbursements' disbursements: type: array example: - user_id: 9d2e5c8a-1234-5678-9abc-def012345679 amount: 74850.55 - company_id: 9d2e5c8a-1234-5678-9abc-def012345680 amount: 74850.55 description: 'Array of disbursements (exactly one of user_id/company_id, plus amount) if provided' items: type: object properties: user_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 amount: type: number example: 74850.55 required: - sub_type - amount - partner_fee - partner_fee_percentage - goescrow_fee - goescrow_fee_percentage - total_fees - net_amount - disbursements_count - disbursements tags: - 'Transaction Management' requestBody: required: true content: application/json: schema: type: object properties: action: type: string description: 'Transaction direction: buy or sell' example: buy type: type: string description: 'Transaction type: anytime_escrow or timed_escrow' example: anytime_escrow amount_type: type: string description: 'Indicates whether amount is escrow (gross) or settlement (net).' example: escrow other_user: type: string description: 'Counterparty user ID. Exactly one of other_user or other_company_id is required when disbursements are omitted.' example: 9d2e5c8a-1234-5678-9abc-def012345678 other_company_id: type: string description: 'Counterparty company ID. The company must be accessible to the partner and eligible to transact.' example: 9d2e5c8a-1234-5678-9abc-def012345678 sub_type: type: string description: 'The transaction sub type (optional: omit or null for plain anytime escrow)' example: super_disbursement user_id: type: string description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 company_id: type: string description: 'Source legal-party company ID. user_id must represent it. For super_disbursement this is required and must match the authenticated partner associated company.' example: 9d2e5c8a-1234-5678-9abc-def012345678 release_at: type: string description: 'Auto-release date for timed escrow in ISO 8601 format. Required when type is timed_escrow.' example: '2024-12-31T23:59:59Z' details: type: string description: 'Transaction details and description' example: 'Dental Surgery' amount: type: integer description: 'Total transaction amount in cents (e.g., 15000050 for $150,000.50)' example: 15000050 disbursements: type: array description: 'Array of disbursement objects (required for super_disbursement). Omit for standard escrow to allocate automatically to other_user or other_company_id.' example: - adipisci items: type: string required: - action - type - amount_type - user_id - details - amount '/api/v1/transactions/{transaction_id}/files': post: summary: 'Upload transaction files' operationId: uploadTransactionFiles description: 'Uploads one or more files to a transaction filing cabinet. The authenticated partner must own the transaction or be its marketplace operator.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Files uploaded' content: application/json: schema: type: object example: data: - id: 9d2e5c8a-1234-5678-9abc-def012345678 file: a1b2c3d4/document.pdf filename: document.pdf created_at: '2024-01-15T10:30:00Z' properties: data: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 file: a1b2c3d4/document.pdf filename: document.pdf created_at: '2024-01-15T10:30:00Z' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 file: type: string example: a1b2c3d4/document.pdf filename: type: string example: document.pdf created_at: type: string example: '2024-01-15T10:30:00Z' 422: description: 'Not authorised' content: application/json: schema: type: object example: message: 'Transaction not found or access denied.' properties: message: type: string example: 'Transaction not found or access denied.' tags: - 'Transaction Management' requestBody: required: true content: multipart/form-data: schema: type: object properties: files: type: array description: 'One or more files to upload.' items: type: string format: binary required: - files parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/settle/codes': post: summary: 'Send settlement codes' operationId: sendSettlementCodes description: 'Sends the buyer of an Anytime or Timed escrow transaction one verification code by email and one by SMS. The buyer gives both codes to you, and you send them when you trigger settlement. Only the partner that created the transaction can call it, and API settlement must be enabled for your account. The buyer needs a verified email address and a verified mobile number. For a company buyer, the codes go to the representative on the transaction. Codes expire after 10 minutes and are thrown away after 5 incorrect attempts. Sending again replaces the previous codes. Marketplace settlement does not use codes.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Codes sent' content: application/json: schema: type: object example: message: 'Settlement codes sent to the buyer.' transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 expires_at: '2026-10-15T10:40:00+10:00' properties: message: type: string example: 'Settlement codes sent to the buyer.' description: 'Success message' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction ID' expires_at: type: string example: '2026-10-15T10:40:00+10:00' description: 'When the codes expire, as an ISO 8601 timestamp' required: - message - transaction_id - expires_at 403: description: 'API settlement not enabled, or not the partner that created the transaction' content: application/json: schema: type: object example: message: 'API settlement is not enabled for this partner. Contact GoEscrow to turn it on.' properties: message: type: string example: 'API settlement is not enabled for this partner. Contact GoEscrow to turn it on.' description: 'Success message' required: - message 409: description: 'Settlement has already started, or another request for these codes is in progress (retry shortly)' content: application/json: schema: type: object example: message: 'Settlement has already started for this transaction.' properties: message: type: string example: 'Settlement has already started for this transaction.' description: 'Success message' required: - message 422: description: 'Not an Anytime or Timed escrow, not ready for settlement, or the buyer has no verified email address or mobile number' content: application/json: schema: type: object example: message: 'Marketplace settlement does not use settlement codes.' properties: message: type: string example: 'Marketplace settlement does not use settlement codes.' description: 'Success message' required: - message 429: description: 'Codes were sent for this transaction 5 times in the last 10 minutes' content: application/json: schema: type: object example: message: 'Too Many Attempts.' properties: message: type: string example: 'Too Many Attempts.' description: 'Success message' required: - message tags: - 'Transaction Management' parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/settle': post: summary: 'Trigger settlement' operationId: triggerSettlement description: 'Settles a funded marketplace, Anytime or Timed escrow transaction in full. API settlement must be enabled for your account. For a marketplace transaction, only the marketplace operator can trigger settlement. For an Anytime or Timed escrow, only the partner that created it can, and the buyer must approve: call Send settlement codes, then send both codes the buyer received. A Timed escrow can be settled before its release date. Before calling it, record a settlement Fingerprint event for the buyer (see Record a Fingerprint event); without one, GoEscrow holds the settlement for compliance review. A successful response means settlement has started; the transaction.status_changed webhook reports when it completes.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string - in: header name: Idempotency-Key description: '' example: 6f3a8e1c-9b2d-4f5a-8c1e-2a7b9d0e1f23 schema: type: string responses: 200: description: 'Settlement initiated' content: application/json: schema: type: object example: message: 'Settlement initiated successfully.' transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: settlement_in_progress properties: message: type: string example: 'Settlement initiated successfully.' description: 'Success message' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The transaction ID' status: type: string example: settlement_in_progress description: 'The new transaction status' required: - message - transaction_id - status 403: description: 'API settlement not enabled for this partner, or not the marketplace operator (marketplace) or the partner that created the transaction (Anytime and Timed escrow)' content: application/json: schema: type: object example: message: 'Only the marketplace operator can trigger settlement.' properties: message: type: string example: 'Only the marketplace operator can trigger settlement.' description: 'Success message' required: - message 409: description: 'Settlement has already started, another settlement is in progress, or another request for these codes is in progress (retry shortly). Send an Idempotency-Key to get the original response on a retry.' content: application/json: schema: type: object example: message: 'Settlement has already started for this transaction.' properties: message: type: string example: 'Settlement has already started for this transaction.' description: 'Success message' required: - message 422: description: 'Codes incorrect, missing or expired; transaction type not settleable via API; or buyer, seller or amount does not match' content: application/json: schema: type: object example: message: 'The settlement codes are incorrect.' properties: message: type: string example: 'The settlement codes are incorrect.' description: 'Success message' required: - message tags: - 'Transaction Management' requestBody: required: true content: application/json: schema: type: object properties: buyer_id: type: string description: 'The buyer legal-party user or company ID for verification' example: 9d2e5c8a-1234-5678-9abc-def012345678 seller_id: type: string description: 'The seller legal-party or disbursement-recipient user or company ID for verification' example: 9d2e5c8a-1234-5678-9abc-def012345679 settlement_amount: type: number description: 'The settlement amount (must match escrow amount)' example: 150000.5 email_code: type: string description: 'Anytime and Timed escrow only: the 6-digit code the buyer received by email. Not used for marketplace transactions.' example: '482913' sms_code: type: string description: 'Anytime and Timed escrow only: the 6-digit code the buyer received by SMS. Not used for marketplace transactions.' example: '105577' required: - buyer_id - seller_id - settlement_amount parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/partial-settlements': post: summary: 'Create partial settlement' operationId: createPartialSettlement description: 'Pays part of a funded marketplace transaction to one payee while the rest stays in escrow. Only the marketplace operator can call it, and API settlement must be enabled for your account. One settlement runs at a time; the transaction returns to accepted once its payout is submitted, and completes when the balance reaches zero and every payout is paid. Follow progress with the settlement.submitted, settlement.paid and settlement.failed webhooks. Only a payout the provider refused before sending is marked failed, and its amount returns to the balance. Before calling it, record a settlement Fingerprint event for the buyer (see Record a Fingerprint event); without one, GoEscrow holds the settlement for compliance review.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string - in: header name: Idempotency-Key description: '' example: 6f3a8e1c-9b2d-4f5a-8c1e-2a7b9d0e1f23 schema: type: string responses: 202: description: 'Partial settlement started' content: application/json: schema: type: object example: data: settlement_id: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 transaction_reference: '12345678' status: processing amount: 5000 payee: payee_id: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: 20000 settled_amount: 5000 remaining_amount: 15000 remaining_escrow_balance: 15000 transaction_status: settlement_in_progress partner_reference: PC-104/step-3 created_at: '2026-09-26T10:30:00+10:00' submitted_at: null paid_at: null failed_at: null properties: data: type: object properties: settlement_id: type: string example: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f description: 'Identifier of this settlement' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 transaction_reference: type: string example: '12345678' status: type: string example: processing description: 'processing, submitted, paid or failed' amount: type: integer example: 5000 description: 'Amount of this settlement in dollars' payee: type: object properties: payee_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: type: integer example: 20000 settled_amount: type: integer example: 5000 remaining_amount: type: integer example: 15000 description: "The payee's share, how much of it is settled, and what remains" remaining_escrow_balance: type: integer example: 15000 description: 'What the transaction still holds in escrow after this settlement, in dollars' transaction_status: type: string example: settlement_in_progress description: 'The transaction status after this request' partner_reference: type: string example: PC-104/step-3 created_at: type: string example: '2026-09-26T10:30:00+10:00' submitted_at: type: string example: null nullable: true paid_at: type: string example: null nullable: true failed_at: type: string example: null nullable: true required: - settlement_id - status - amount - payee - remaining_escrow_balance - transaction_status 400: description: 'Missing Idempotency-Key' content: application/json: schema: type: object example: message: 'An Idempotency-Key header is required for this request.' properties: message: type: string example: 'An Idempotency-Key header is required for this request.' 403: description: 'Not the marketplace operator, or API settlement is not enabled for this partner' content: application/json: schema: type: object example: message: 'Only the marketplace operator can settle this transaction.' properties: message: type: string example: 'Only the marketplace operator can settle this transaction.' 409: description: 'Another settlement is in progress' content: application/json: schema: type: object example: message: 'A settlement is already in progress for this transaction.' properties: message: type: string example: 'A settlement is already in progress for this transaction.' 422: description: 'Amount, payee or transaction state not valid' content: application/json: schema: type: object example: message: 'The settlement amount is more than the remaining escrow balance.' properties: message: type: string example: 'The settlement amount is more than the remaining escrow balance.' tags: - 'Transaction Management' requestBody: required: true content: application/json: schema: type: object properties: amount: type: number description: "Amount to pay in dollars, at most the remaining escrow balance and the payee's remaining share" example: 5000.0 payee_id: type: string description: "The payee's user or company ID, as sent in disbursements when the transaction was created. Required when the transaction has more than one payee." example: 9d2e5c8a-1234-5678-9abc-def012345679 partner_reference: type: string description: 'Your own reference for reconciliation, returned unchanged' example: PC-104/step-3 required: - amount get: summary: 'List partial settlements' operationId: listPartialSettlements description: 'Lists every partial settlement of a transaction, newest first. Only the marketplace operator can call it.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Partial settlements' content: application/json: schema: type: object example: data: - settlement_id: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 transaction_reference: '12345678' status: processing amount: 5000 payee: payee_id: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: 20000 settled_amount: 5000 remaining_amount: 15000 remaining_escrow_balance: 15000 transaction_status: settlement_in_progress partner_reference: PC-104/step-3 created_at: '2026-09-26T10:30:00+10:00' submitted_at: null paid_at: null failed_at: null properties: data: type: array example: - settlement_id: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 transaction_reference: '12345678' status: processing amount: 5000 payee: payee_id: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: 20000 settled_amount: 5000 remaining_amount: 15000 remaining_escrow_balance: 15000 transaction_status: settlement_in_progress partner_reference: PC-104/step-3 created_at: '2026-09-26T10:30:00+10:00' submitted_at: null paid_at: null failed_at: null items: type: object properties: settlement_id: type: string example: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 transaction_reference: type: string example: '12345678' status: type: string example: processing amount: type: integer example: 5000 payee: type: object properties: payee_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: type: integer example: 20000 settled_amount: type: integer example: 5000 remaining_amount: type: integer example: 15000 remaining_escrow_balance: type: integer example: 15000 transaction_status: type: string example: settlement_in_progress partner_reference: type: string example: PC-104/step-3 created_at: type: string example: '2026-09-26T10:30:00+10:00' submitted_at: type: string example: null nullable: true paid_at: type: string example: null nullable: true failed_at: type: string example: null nullable: true 403: description: 'Not the marketplace operator' content: application/json: schema: type: object example: message: 'Only the marketplace operator can settle this transaction.' properties: message: type: string example: 'Only the marketplace operator can settle this transaction.' tags: - 'Transaction Management' parameters: - in: path name: transaction_id description: 'The transaction UUID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/partial-settlements/{settlement_id}': get: summary: 'Get partial settlement' operationId: getPartialSettlement description: 'Returns one partial settlement of a transaction. Only the marketplace operator can call it.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Partial settlement' content: application/json: schema: type: object example: data: settlement_id: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 transaction_reference: '12345678' status: processing amount: 5000 payee: payee_id: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: 20000 settled_amount: 5000 remaining_amount: 15000 remaining_escrow_balance: 15000 transaction_status: settlement_in_progress partner_reference: PC-104/step-3 created_at: '2026-09-26T10:30:00+10:00' submitted_at: null paid_at: null failed_at: null properties: data: type: object properties: settlement_id: type: string example: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 transaction_reference: type: string example: '12345678' status: type: string example: processing amount: type: integer example: 5000 payee: type: object properties: payee_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345679 allocation: type: integer example: 20000 settled_amount: type: integer example: 5000 remaining_amount: type: integer example: 15000 remaining_escrow_balance: type: integer example: 15000 transaction_status: type: string example: settlement_in_progress partner_reference: type: string example: PC-104/step-3 created_at: type: string example: '2026-09-26T10:30:00+10:00' submitted_at: type: string example: null nullable: true paid_at: type: string example: null nullable: true failed_at: type: string example: null nullable: true 403: description: 'Not the marketplace operator' content: application/json: schema: type: object example: message: 'Only the marketplace operator can settle this transaction.' properties: message: type: string example: 'Only the marketplace operator can settle this transaction.' 404: description: 'The settlement does not belong to this transaction' content: application/json: schema: type: object example: message: 'No query results for model [App\Models\TransactionSettlement] 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f' properties: message: type: string example: 'No query results for model [App\Models\TransactionSettlement] 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f' tags: - 'Transaction Management' parameters: - in: path name: transaction_id description: 'The transaction UUID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string - in: path name: settlement_id description: 'The settlement ID' example: 4b1f6c2e-8d3a-4e5b-9c7d-1a2b3c4d5e6f required: true schema: type: string '/api/v1/transactions/{transaction_id}/payto-payment': post: summary: 'Initiate PayTo payment' operationId: initiatePayToPayment description: "Initiates a PayTo debit payment from the specified user's bank account to fund the transaction. The user must have an active PayTo agreement. This endpoint dispatches an async job and returns immediately with a tracking ID." parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string - in: header name: Idempotency-Key description: '' example: 6f3a8e1c-9b2d-4f5a-8c1e-2a7b9d0e1f23 schema: type: string responses: 202: description: 'Payment initiation queued for processing' content: application/json: schema: type: object example: code: accepted message: 'Payment initiation queued. Use the tracking_id to poll for status.' tracking_id: payto_9d2e5c8a properties: code: type: string example: accepted description: 'Result code: accepted, transaction_already_funded, no_payment_agreement, transaction_not_payable' message: type: string example: 'Payment initiation queued. Use the tracking_id to poll for status.' description: 'Human-readable message' tracking_id: type: string example: payto_9d2e5c8a description: 'Unique tracking ID to poll for payment status' required: - code - message - tracking_id 400: description: '' content: application/json: schema: oneOf: - description: 'Transaction already funded' type: object example: code: transaction_already_funded message: 'This transaction is already funded.' properties: code: type: string example: transaction_already_funded description: 'Result code: accepted, transaction_already_funded, no_payment_agreement, transaction_not_payable' message: type: string example: 'This transaction is already funded.' description: 'Human-readable message' required: - code - message - description: 'PayTo not configured' type: object example: code: no_payment_agreement message: 'User does not have a PayTo agreement set up.' properties: code: type: string example: no_payment_agreement description: 'Result code: accepted, transaction_already_funded, no_payment_agreement, transaction_not_payable' message: type: string example: 'User does not have a PayTo agreement set up.' description: 'Human-readable message' required: - code - message tags: - 'Transaction PayTo Payment' requestBody: required: true content: application/json: schema: type: object properties: user_id: type: string description: 'The ID of the user initiating the payment (must have active PayTo agreement)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: - user_id parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/transactions/{transaction_id}/payto-payment/{id}': get: summary: 'Check PayTo payment status' operationId: checkPayToPaymentStatus description: 'Checks the status of a PayTo payment using either a tracking_id (from async initiation) or a payment_initiation_id.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: 'Payment settled' type: object example: code: settled message: 'Payment settled successfully. Transaction is now funded.' status: settled properties: code: type: string example: settled description: 'Result code: queued, processing, initiated, pending, settled, failed, timeout, error' message: type: string example: 'Payment settled successfully. Transaction is now funded.' description: 'Human-readable message' status: type: string example: settled description: 'Current payment status' required: - code - message - status - description: 'Payment pending' type: object example: code: pending message: 'Payment is still processing.' status: pending properties: code: type: string example: pending description: 'Result code: queued, processing, initiated, pending, settled, failed, timeout, error' message: type: string example: 'Payment is still processing.' description: 'Human-readable message' status: type: string example: pending description: 'Current payment status' required: - code - message - status - description: 'Payment failed' type: object example: code: failed status: failed tracking_id: payto_9b2f1c4e message: 'Cannot initiate payment. Transaction status: canceled' error_code: transaction_not_payable properties: code: type: string example: failed description: 'Result code: queued, processing, initiated, pending, settled, failed, timeout, error' status: type: string example: failed description: 'Current payment status' tracking_id: type: string example: payto_9b2f1c4e message: type: string example: 'Cannot initiate payment. Transaction status: canceled' description: 'Human-readable message' error_code: type: string example: transaction_not_payable description: 'Why the payment failed, when status is failed or error: no_payment_agreement, payment_agreement_failed, payment_agreement_inactive, transaction_not_payable (the transaction was cancelled, declined, expired or completed after the payment was queued), transaction_already_funded, transaction_clearance_pending, amount_exceeds_limit, initiation_failed, invalid_response, payment_failed or exception' required: - code - status - message - error_code - description: 'Job queued' type: object example: code: queued message: 'Payment initiation is queued for processing.' status: queued properties: code: type: string example: queued description: 'Result code: queued, processing, initiated, pending, settled, failed, timeout, error' message: type: string example: 'Payment initiation is queued for processing.' description: 'Human-readable message' status: type: string example: queued description: 'Current payment status' required: - code - message - status tags: - 'Transaction PayTo Payment' parameters: - in: path name: transaction_id description: 'The transaction UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string - in: path name: id description: 'Either a tracking_id (e.g., payto_abc123) or a payment_initiation_id (e.g., PI-123456789)' example: payto_abc123 required: true schema: type: string '/api/v1/users/{user_id}/bank-account': put: summary: 'Update user bank account' operationId: updateUserBankAccount description: 'Updates the bank account details for a user. This will automatically trigger a verification payout of $0.01 to the new account with a 6-digit verification code in the transaction description.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Bank account updated successfully' content: application/json: schema: type: object example: message: 'Bank account updated. Verification code sent via $0.01 payout.' is_verified: false properties: message: type: string example: 'Bank account updated. Verification code sent via $0.01 payout.' description: 'Success message' is_verified: type: boolean example: false description: 'Whether the bank account is verified (will be false after update)' required: - message - is_verified tags: - 'User Bank Account Management' requestBody: required: true content: application/json: schema: type: object properties: bsb_number: type: string description: 'The BSB number (6 digits)' example: '123456' account_number: type: string description: 'The bank account number' example: '12345678' account_name: type: string description: 'The account holder name' example: 'John Doe' required: - bsb_number - account_number - account_name parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/bank-account/verify': post: summary: 'Verify user bank account' operationId: verifyUserBankAccount description: 'Verifies the bank account using the 6-digit code received in the $0.01 verification payout.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Bank account verified successfully' content: application/json: schema: type: object example: message: 'Bank account verified successfully.' is_verified: true properties: message: type: string example: 'Bank account verified successfully.' description: 'Success or error message' is_verified: type: boolean example: true description: 'Whether the bank account is now verified' required: - message - is_verified 422: description: 'Invalid verification code' content: application/json: schema: type: object example: message: 'The verification code is incorrect.' properties: message: type: string example: 'The verification code is incorrect.' description: 'Success or error message' required: - message tags: - 'User Bank Account Management' requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: 'The 6-digit verification code from the bank transaction' example: '123456' required: - code parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/passport': post: summary: 'Create or update user passport' operationId: createOrUpdateUserPassport description: 'Creates a new passport record for the user or updates an existing one. Only one passport per user is allowed.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Passport created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: N1234567 first_name: John last_name: Doe middle_name: Michael nationality: 'United Kingdom' issuing_country: 'United Kingdom' date_of_birth: '1990-01-15' date_of_issue: '2020-01-15' date_of_expiration: '2030-01-15' place_of_birth: 'Sydney, Australia' gender: M rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The unique identifier of the passport record' document_number: type: string example: N1234567 description: 'The passport document number' first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael nationality: type: string example: 'United Kingdom' issuing_country: type: string example: 'United Kingdom' date_of_birth: type: string example: '1990-01-15' date_of_issue: type: string example: '2020-01-15' date_of_expiration: type: string example: '2030-01-15' place_of_birth: type: string example: 'Sydney, Australia' gender: type: string example: M rapidid_verification_requested_at: type: string example: null description: 'Timestamp when RapidID verification was requested' rapidid_verified_at: type: string example: null description: 'Timestamp when RapidID verification was completed successfully' rapidid_failed_at: type: string example: null description: 'Timestamp when RapidID verification failed' created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' required: - id - document_number - rapidid_verification_requested_at - rapidid_verified_at - rapidid_failed_at tags: - 'User Identification Management' requestBody: required: true content: application/json: schema: type: object properties: document_number: type: string description: 'Passport document number' example: N1234567 first_name: type: string description: 'First name as shown on passport' example: John last_name: type: string description: 'Last name as shown on passport' example: Doe middle_name: type: string description: 'Middle name as shown on passport' example: Michael issuing_country: type: string description: 'Country that issued the passport, as shown on the document. Required unless nationality is provided.' example: 'United Kingdom' nationality: type: string description: 'Deprecated: kept for backwards compatibility; use issuing_country. Required unless issuing_country is provided.' example: British date_of_birth: type: string description: 'Date of birth in YYYY-MM-DD format' example: '1990-01-15' date_of_issue: type: string description: 'Date of issue in YYYY-MM-DD format' example: '2020-01-15' date_of_expiration: type: string description: 'Date of expiration in YYYY-MM-DD format' example: '2030-01-15' place_of_birth: type: string description: 'Place of birth as shown on passport' example: 'Sydney, Australia' gender: type: string description: 'Gender as shown on passport (M, F, X, or BLANK)' example: M required: - document_number - first_name - last_name - date_of_birth - date_of_issue - date_of_expiration - place_of_birth get: summary: 'Get user passport' operationId: getUserPassport description: 'Retrieves the passport information for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Passport retrieved successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: N1234567 first_name: John last_name: Doe middle_name: Michael nationality: 'United Kingdom' issuing_country: 'United Kingdom' date_of_birth: '1990-01-15' date_of_issue: '2020-01-15' date_of_expiration: '2030-01-15' place_of_birth: 'Sydney, Australia' gender: M rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: type: string example: N1234567 first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael nationality: type: string example: 'United Kingdom' issuing_country: type: string example: 'United Kingdom' date_of_birth: type: string example: '1990-01-15' date_of_issue: type: string example: '2020-01-15' date_of_expiration: type: string example: '2030-01-15' place_of_birth: type: string example: 'Sydney, Australia' gender: type: string example: M rapidid_verification_requested_at: type: string example: null nullable: true rapidid_verified_at: type: string example: null nullable: true rapidid_failed_at: type: string example: null nullable: true created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' 404: description: 'Passport not found' content: application/json: schema: type: object example: error: 'Passport not found for this user.' properties: error: type: string example: 'Passport not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user passport' operationId: deleteUserPassport description: 'Deletes the passport record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Passport deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Passport not found' content: application/json: schema: type: object example: error: 'Passport not found for this user.' properties: error: type: string example: 'Passport not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/medicare': post: summary: 'Create or update user Medicare card' operationId: createOrUpdateUserMedicareCard description: 'Creates a new Medicare card record for the user or updates an existing one. Only one Medicare card per user is allowed.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Medicare card created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: '1234567890' name_on_card: 'John Michael Doe' card_color: green individual_reference_number: '1' expiration_date: 2025-12 rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The unique identifier of the Medicare card record' document_number: type: string example: '1234567890' description: 'The Medicare card number' name_on_card: type: string example: 'John Michael Doe' card_color: type: string example: green description: 'The Medicare card color' individual_reference_number: type: string example: '1' expiration_date: type: string example: 2025-12 rapidid_verification_requested_at: type: string example: null description: 'Timestamp when RapidID verification was requested' rapidid_verified_at: type: string example: null description: 'Timestamp when RapidID verification was completed successfully' rapidid_failed_at: type: string example: null description: 'Timestamp when RapidID verification failed' created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' required: - id - document_number - card_color - rapidid_verification_requested_at - rapidid_verified_at - rapidid_failed_at tags: - 'User Identification Management' requestBody: required: true content: application/json: schema: type: object properties: document_number: type: string description: 'Medicare card number (10 digits)' example: '1234567890' name_on_card: type: string description: 'Name as shown on Medicare card' example: 'John Michael Doe' card_color: type: string description: 'Medicare card color (green, blue, or yellow)' example: green individual_reference_number: type: string description: 'Individual reference number (1 digit)' example: '1' expiration_date: type: string description: 'Expiration date in YYYY-MM format' example: 2025-12 required: - document_number - card_color - individual_reference_number - expiration_date get: summary: 'Get user Medicare card' operationId: getUserMedicareCard description: 'Retrieves the Medicare card information for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Medicare card retrieved successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: '1234567890' name_on_card: 'John Michael Doe' card_color: green individual_reference_number: '1' expiration_date: 2025-12 rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: type: string example: '1234567890' name_on_card: type: string example: 'John Michael Doe' card_color: type: string example: green individual_reference_number: type: string example: '1' expiration_date: type: string example: 2025-12 rapidid_verification_requested_at: type: string example: null nullable: true rapidid_verified_at: type: string example: null nullable: true rapidid_failed_at: type: string example: null nullable: true created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' 404: description: 'Medicare card not found' content: application/json: schema: type: object example: error: 'Medicare card not found for this user.' properties: error: type: string example: 'Medicare card not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user Medicare card' operationId: deleteUserMedicareCard description: 'Deletes the Medicare card record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Medicare card deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Medicare card not found' content: application/json: schema: type: object example: error: 'Medicare card not found for this user.' properties: error: type: string example: 'Medicare card not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/driver-license': post: summary: 'Create or update user driver license' operationId: createOrUpdateUserDriverLicense description: 'Creates a new driver license record for the user or updates an existing one. Only one driver license per user is allowed.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Driver license created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 state_issued: NSW license_number: '12345678' card_number: '1234567890' expiration_date: '2030-01-15' first_name: John last_name: Doe middle_name: Michael date_of_birth: '1990-01-15' rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The unique identifier of the driver license record' state_issued: type: string example: NSW description: 'The state or territory that issued the license' license_number: type: string example: '12345678' description: 'The driver license number' card_number: type: string example: '1234567890' expiration_date: type: string example: '2030-01-15' first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael date_of_birth: type: string example: '1990-01-15' rapidid_verification_requested_at: type: string example: null description: 'Timestamp when RapidID verification was requested' rapidid_verified_at: type: string example: null description: 'Timestamp when RapidID verification was completed successfully' rapidid_failed_at: type: string example: null description: 'Timestamp when RapidID verification failed' created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' required: - id - state_issued - license_number - rapidid_verification_requested_at - rapidid_verified_at - rapidid_failed_at tags: - 'User Identification Management' requestBody: required: true content: application/json: schema: type: object properties: state_issued: type: string description: 'State or territory that issued the license (NSW, VIC, QLD, SA, WA, TAS, NT, ACT)' example: NSW license_number: type: string description: 'Driver license number' example: '12345678' card_number: type: string description: 'Driver license card number' example: '1234567890' expiration_date: type: string description: 'Expiration date in YYYY-MM-DD format' example: '2030-01-15' first_name: type: string description: 'First name as shown on license' example: John last_name: type: string description: 'Last name as shown on license' example: Doe middle_name: type: string description: 'Middle name as shown on license' example: Michael date_of_birth: type: string description: 'Date of birth in YYYY-MM-DD format' example: '1990-01-15' required: - state_issued - license_number - card_number - expiration_date - first_name - last_name - date_of_birth get: summary: 'Get user driver license' operationId: getUserDriverLicense description: 'Retrieves the driver license information for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Driver license retrieved successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 state_issued: NSW license_number: '12345678' card_number: '1234567890' expiration_date: '2030-01-15' first_name: John last_name: Doe middle_name: Michael date_of_birth: '1990-01-15' rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 state_issued: type: string example: NSW license_number: type: string example: '12345678' card_number: type: string example: '1234567890' expiration_date: type: string example: '2030-01-15' first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael date_of_birth: type: string example: '1990-01-15' rapidid_verification_requested_at: type: string example: null nullable: true rapidid_verified_at: type: string example: null nullable: true rapidid_failed_at: type: string example: null nullable: true created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' 404: description: 'Driver license not found' content: application/json: schema: type: object example: error: 'Driver license not found for this user.' properties: error: type: string example: 'Driver license not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user driver license' operationId: deleteUserDriverLicense description: 'Deletes the driver license record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Driver license deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Driver license not found' content: application/json: schema: type: object example: error: 'Driver license not found for this user.' properties: error: type: string example: 'Driver license not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/immigration-card': post: summary: 'Create or update user immigration card' operationId: createOrUpdateUserImmigrationCard description: 'Creates a new immigration card record for the user or updates an existing one. Only one immigration card per user is allowed.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Immigration card created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 given_name: John family_name: Doe card_number: IMM123456 expiration_date: '2030-01-15' card_type: ams vevo_check_given_name: John vevo_check_family_name: Doe vevo_check_passport_number: N1234567 vevo_check_country_of_issue: Australia rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The unique identifier of the immigration card record' given_name: type: string example: John family_name: type: string example: Doe card_number: type: string example: IMM123456 description: 'The immigration card number' expiration_date: type: string example: '2030-01-15' card_type: type: string example: ams description: 'Type of immigration card' vevo_check_given_name: type: string example: John vevo_check_family_name: type: string example: Doe vevo_check_passport_number: type: string example: N1234567 vevo_check_country_of_issue: type: string example: Australia rapidid_verification_requested_at: type: string example: null description: 'Timestamp when RapidID verification was requested' rapidid_verified_at: type: string example: null description: 'Timestamp when RapidID verification was completed successfully' rapidid_failed_at: type: string example: null description: 'Timestamp when RapidID verification failed' created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' required: - id - card_number - card_type - rapidid_verification_requested_at - rapidid_verified_at - rapidid_failed_at tags: - 'User Identification Management' requestBody: required: true content: application/json: schema: type: object properties: given_name: type: string description: 'Given name as shown on the card' example: John family_name: type: string description: 'Family name as shown on the card' example: Doe card_number: type: string description: 'Immigration card number' example: IMM123456 expiration_date: type: string description: 'Card expiration date (YYYY-MM-DD)' example: '2030-01-15' card_type: type: string description: 'Type of immigration card (ams, eis, pre, rdi)' example: ams vevo_check_given_name: type: string description: 'DEPRECATED. Never fed a VEVO check and is no longer read; still accepted and stored for backwards compatibility.' example: John vevo_check_family_name: type: string description: 'DEPRECATED. Never fed a VEVO check and is no longer read; still accepted and stored for backwards compatibility.' example: Doe vevo_check_passport_number: type: string description: 'DEPRECATED. Not part of the ImmiCard document check; still accepted and stored for backwards compatibility.' example: N1234567 vevo_check_country_of_issue: type: string description: 'DEPRECATED. Not part of the ImmiCard document check; still accepted and stored for backwards compatibility.' example: Australia required: - given_name - family_name - card_number - expiration_date - card_type get: summary: 'Get user immigration card' operationId: getUserImmigrationCard description: 'Retrieves the immigration card information for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Immigration card retrieved successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 given_name: John family_name: Doe card_number: IMM123456 expiration_date: '2030-01-15' card_type: ams vevo_check_given_name: John vevo_check_family_name: Doe vevo_check_passport_number: N1234567 vevo_check_country_of_issue: Australia rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 given_name: type: string example: John family_name: type: string example: Doe card_number: type: string example: IMM123456 expiration_date: type: string example: '2030-01-15' card_type: type: string example: ams vevo_check_given_name: type: string example: John vevo_check_family_name: type: string example: Doe vevo_check_passport_number: type: string example: N1234567 vevo_check_country_of_issue: type: string example: Australia rapidid_verification_requested_at: type: string example: null nullable: true rapidid_verified_at: type: string example: null nullable: true rapidid_failed_at: type: string example: null nullable: true created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' 404: description: 'Immigration card not found' content: application/json: schema: type: object example: error: 'Immigration card not found for this user.' properties: error: type: string example: 'Immigration card not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user immigration card' operationId: deleteUserImmigrationCard description: 'Deletes the immigration card record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Immigration card deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Immigration card not found' content: application/json: schema: type: object example: error: 'Immigration card not found for this user.' properties: error: type: string example: 'Immigration card not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/centrelink-card': post: summary: 'Create or update user Centrelink card' operationId: createOrUpdateUserCentrelinkCard description: 'Creates a new Centrelink card record for the user or updates an existing one. Only one Centrelink card per user is allowed.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Centrelink card created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 crn: 123456789A name_on_card: 'John Doe' expiration_date: '2030-01-15' card_type: hcc rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The unique identifier of the Centrelink card record' crn: type: string example: 123456789A description: 'The Customer Reference Number' name_on_card: type: string example: 'John Doe' expiration_date: type: string example: '2030-01-15' card_type: type: string example: hcc description: 'Type of Centrelink card' rapidid_verification_requested_at: type: string example: null description: 'Timestamp when RapidID verification was requested' rapidid_verified_at: type: string example: null description: 'Timestamp when RapidID verification was completed successfully' rapidid_failed_at: type: string example: null description: 'Timestamp when RapidID verification failed' created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' required: - id - crn - card_type - rapidid_verification_requested_at - rapidid_verified_at - rapidid_failed_at tags: - 'User Identification Management' requestBody: required: true content: application/json: schema: type: object properties: crn: type: string description: 'Customer Reference Number (9 digits + letter)' example: 123456789A name_on_card: type: string description: 'Name as shown on the card' example: 'John Doe' expiration_date: type: string description: 'Card expiration date (YYYY-MM-DD)' example: '2030-01-15' card_type: type: string description: 'Type of Centrelink card (hcc, pcc, shc)' example: hcc required: - crn - name_on_card - expiration_date - card_type get: summary: 'Get user Centrelink card' operationId: getUserCentrelinkCard description: 'Retrieves the Centrelink card information for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Centrelink card retrieved successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 crn: 123456789A name_on_card: 'John Doe' expiration_date: '2030-01-15' card_type: hcc rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 crn: type: string example: 123456789A name_on_card: type: string example: 'John Doe' expiration_date: type: string example: '2030-01-15' card_type: type: string example: hcc rapidid_verification_requested_at: type: string example: null nullable: true rapidid_verified_at: type: string example: null nullable: true rapidid_failed_at: type: string example: null nullable: true created_at: type: string example: '2024-01-15T10:30:00Z' updated_at: type: string example: '2024-01-15T10:30:00Z' 404: description: 'Centrelink card not found' content: application/json: schema: type: object example: error: 'Centrelink card not found for this user.' properties: error: type: string example: 'Centrelink card not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user Centrelink card' operationId: deleteUserCentrelinkCard description: 'Deletes the Centrelink card record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Centrelink card deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Centrelink card not found' content: application/json: schema: type: object example: error: 'Centrelink card not found for this user.' properties: error: type: string example: 'Centrelink card not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/payto-agreement': get: summary: 'Get PayTo agreement status' operationId: getPayToAgreementStatus description: 'Returns the current PayTo agreement status and details for a user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: 'PayTo agreement found' type: object example: has_agreement: true agreement_id: PA-123456 maximum_amount: 10000 status: ACTIVE properties: has_agreement: type: boolean example: true description: 'Whether the user has a PayTo agreement' agreement_id: type: string example: PA-123456 description: 'The PayTo agreement ID (null if no agreement)' maximum_amount: type: integer example: 10000 description: 'The maximum amount allowed per transaction (null if no agreement)' status: type: string example: ACTIVE description: 'The agreement status: ACTIVE, CREATED, SUSPENDED, CANCELLED, FAILED (null if no agreement)' required: - has_agreement - agreement_id - maximum_amount - status - description: 'No PayTo agreement' type: object example: has_agreement: false agreement_id: null maximum_amount: null status: null properties: has_agreement: type: boolean example: false description: 'Whether the user has a PayTo agreement' agreement_id: type: string example: null description: 'The PayTo agreement ID (null if no agreement)' maximum_amount: type: string example: null description: 'The maximum amount allowed per transaction (null if no agreement)' status: type: string example: null description: 'The agreement status: ACTIVE, CREATED, SUSPENDED, CANCELLED, FAILED (null if no agreement)' required: - has_agreement - agreement_id - maximum_amount - status tags: - 'User PayTo Agreement Management' post: summary: 'Create PayTo agreement' operationId: createPayToAgreement description: 'Creates a new PayTo agreement for the user. The user must authorize the agreement in their banking app.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'PayTo agreement created' content: application/json: schema: type: object example: agreement_id: PA-123456 status: CREATED message: 'PayTo agreement created. User must authorize in their banking app.' properties: agreement_id: type: string example: PA-123456 description: 'The new PayTo agreement ID' status: type: string example: CREATED description: 'The initial agreement status (CREATED - awaiting user authorization)' message: type: string example: 'PayTo agreement created. User must authorize in their banking app.' description: 'Instructions for next steps' required: - agreement_id - status - message tags: - 'User PayTo Agreement Management' requestBody: required: true content: application/json: schema: type: object properties: maximum_amount: type: number description: 'The maximum amount per transaction (max 10,000)' example: 5000.0 pay_id: type: string description: 'The PayID (email, phone, ABN, or ORG ID). Either pay_id or bank account details required.' example: john@example.com pay_id_type: type: string description: 'The PayID type: PHONE, EMAIL, ABN, or ORG' example: EMAIL account_name: type: string description: 'Bank account holder name (required if using bank account)' example: 'John Doe' account_number: type: string description: 'Bank account number (required if using bank account)' example: '12345678' bsb: type: string description: 'Bank BSB number (required if using bank account)' example: '123456' required: - maximum_amount parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string /api/v1/webhooks: get: summary: 'List webhooks' operationId: listWebhooks description: 'Returns all registered webhooks for the authenticated partner.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'List of webhooks' content: application/json: schema: type: object example: data: - id: 9d2e5c8a-1234-5678-9abc-def012345678 url: 'https://partner.com/webhooks/goescrow' events: - transaction.created - transaction.clearance_pending - transaction.funded - transaction.status_changed - transaction.funding_status_changed is_active: true last_triggered_at: '2024-01-15T10:30:00Z' failure_count: 0 created_at: '2024-01-01T00:00:00Z' properties: data: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 url: 'https://partner.com/webhooks/goescrow' events: - transaction.created - transaction.clearance_pending - transaction.funded - transaction.status_changed - transaction.funding_status_changed is_active: true last_triggered_at: '2024-01-15T10:30:00Z' failure_count: 0 created_at: '2024-01-01T00:00:00Z' description: 'Array of webhook objects' items: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 url: type: string example: 'https://partner.com/webhooks/goescrow' events: type: array example: - transaction.created - transaction.clearance_pending - transaction.funded - transaction.status_changed - transaction.funding_status_changed items: type: string is_active: type: boolean example: true last_triggered_at: type: string example: '2024-01-15T10:30:00Z' failure_count: type: integer example: 0 created_at: type: string example: '2024-01-01T00:00:00Z' required: - data tags: - 'Webhook Management' post: summary: 'Register webhook' operationId: registerWebhook description: 'Registers a new webhook URL to receive transaction event notifications. Available events: transaction.created (when a transaction is created), transaction.clearance_pending (when inbound funding is held for clearance), transaction.funded (when a transaction is funded), transaction.status_changed (when transaction status changes), transaction.funding_status_changed (when transaction funding status changes), transaction.completed (when a transaction is completed/settled), beneficiary.confirmation_requested (when beneficiary confirmation is requested), beneficiary.confirmed (when a beneficiary confirms receipt), beneficiary.declined (when a beneficiary reports non-receipt), settlement.submitted (when a partial settlement payout is accepted by the provider), settlement.paid (when a partial settlement payout is confirmed paid), settlement.failed (when a partial settlement payout was refused before it left, and its amount returns to the balance).' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Webhook registered' content: application/json: schema: type: object example: message: 'Webhook registered successfully.' id: 9d2e5c8a-1234-5678-9abc-def012345678 url: 'https://partner.com/webhooks/goescrow' secret: whsec_abc123xyz789... events: - transaction.created - transaction.clearance_pending properties: message: type: string example: 'Webhook registered successfully.' description: 'Success message' id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The webhook ID' url: type: string example: 'https://partner.com/webhooks/goescrow' description: 'The registered webhook URL' secret: type: string example: whsec_abc123xyz789... description: 'The signing secret for HMAC verification. Store this securely - it is only shown once.' events: type: array example: - transaction.created - transaction.clearance_pending description: 'Array of subscribed events' items: type: string required: - message - id - url - secret - events tags: - 'Webhook Management' requestBody: required: true content: application/json: schema: type: object properties: url: type: string description: 'The webhook URL (must be HTTPS)' example: 'https://partner.com/webhooks/goescrow' events: type: array description: 'Array of events to subscribe to. Available events: transaction.created, transaction.clearance_pending, transaction.funded, transaction.status_changed, transaction.funding_status_changed, transaction.completed, beneficiary.confirmation_requested, beneficiary.confirmed, beneficiary.declined, settlement.submitted, settlement.paid, settlement.failed. Omit or pass null to receive all events.' example: - transaction.created - beneficiary.confirmation_requested - beneficiary.confirmed - beneficiary.declined items: type: string required: - url '/api/v1/webhooks/{id}': delete: summary: 'Delete webhook' operationId: deleteWebhook description: 'Unregisters a webhook.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Webhook deleted' content: application/json: schema: type: object example: message: 'Webhook deleted successfully.' properties: message: type: string example: 'Webhook deleted successfully.' description: 'Success message' required: - message 404: description: 'Webhook not found' content: application/json: schema: type: object example: message: 'Webhook not found.' properties: message: type: string example: 'Webhook not found.' description: 'Success message' required: - message tags: - 'Webhook Management' parameters: - in: path name: webhook description: 'The webhook ID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/webhooks/{webhook_id}/deliveries': get: summary: 'List webhook deliveries' operationId: listWebhookDeliveries description: 'Returns the delivery history for a webhook (most recent first), so missed events can be inspected and replayed after an outage. Each delivery records the event, the exact payload that was (or will be) sent, the number of attempts, and the last response status.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'List of deliveries' content: application/json: schema: type: object example: data: - id: 9f1b2c3d-4567-89ab-cdef-0123456789ab event: transaction.funded status: failed attempts: 3 response_status: 500 last_attempted_at: '2024-01-15T10:32:00Z' delivered_at: null created_at: '2024-01-15T10:30:00Z' payload: transaction_id: ... status: pending meta: current_page: 1 last_page: 1 per_page: 50 total: 1 properties: data: type: array example: - id: 9f1b2c3d-4567-89ab-cdef-0123456789ab event: transaction.funded status: failed attempts: 3 response_status: 500 last_attempted_at: '2024-01-15T10:32:00Z' delivered_at: null created_at: '2024-01-15T10:30:00Z' payload: transaction_id: ... status: pending description: 'Array of delivery objects (most recent first)' items: type: object properties: id: type: string example: 9f1b2c3d-4567-89ab-cdef-0123456789ab event: type: string example: transaction.funded status: type: string example: failed attempts: type: integer example: 3 response_status: type: integer example: 500 last_attempted_at: type: string example: '2024-01-15T10:32:00Z' delivered_at: type: string example: null nullable: true created_at: type: string example: '2024-01-15T10:30:00Z' payload: type: object properties: transaction_id: type: string example: ... status: type: string example: pending meta: type: object properties: current_page: type: integer example: 1 last_page: type: integer example: 1 per_page: type: integer example: 50 total: type: integer example: 1 required: - data tags: - 'Webhook Management' parameters: - in: path name: webhook description: 'The webhook ID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver': post: summary: 'Redeliver a webhook event' operationId: redeliverAWebhookEvent description: 'Queues a fresh delivery attempt for a past event, using the original payload. Use this to backfill events your endpoint missed during an outage. A new delivery record is created (with a new id) so the original attempt history is preserved.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 202: description: 'Redelivery queued' content: application/json: schema: type: object example: message: 'Webhook delivery has been queued for redelivery.' id: a1b2c3d4-5678-90ab-cdef-1234567890ab event: transaction.funded status: pending properties: message: type: string example: 'Webhook delivery has been queued for redelivery.' id: type: string example: a1b2c3d4-5678-90ab-cdef-1234567890ab description: 'The ID of the new delivery created for this redelivery' event: type: string example: transaction.funded description: 'The event being redelivered' status: type: string example: pending description: 'Status of the new delivery (pending)' required: - id - event - status 404: description: 'Delivery not found' content: application/json: schema: type: object example: message: 'Delivery not found.' properties: message: type: string example: 'Delivery not found.' 409: description: 'Webhook inactive, or delivery still in progress' content: application/json: schema: type: object example: message: 'This delivery is still in progress; wait for it to finish before redelivering.' properties: message: type: string example: 'This delivery is still in progress; wait for it to finish before redelivering.' tags: - 'Webhook Management' parameters: - in: path name: webhook description: 'The webhook ID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string - in: path name: delivery description: 'The delivery ID to redeliver' example: 9f1b2c3d-4567-89ab-cdef-0123456789ab required: true schema: type: string '/api/v1/companies/{company_id}/bank-account': put: summary: 'Update company bank account' operationId: updateCompanyBankAccount description: "Updates company bank details and runs Confirmation of Payee checks against the company's active known names." parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Company bank account updated' content: application/json: schema: type: object example: message: 'Company bank account updated successfully.' is_verified: true properties: message: type: string example: 'Company bank account updated successfully.' description: 'Success message' is_verified: type: boolean example: true description: 'Whether Confirmation of Payee has verified the bank account' required: - message - is_verified tags: - 'Company Bank Account Management' requestBody: required: true content: application/json: schema: type: object properties: bsb_number: type: string description: 'The BSB number (6 digits)' example: '123456' account_number: type: string description: 'The bank account number' example: '12345678' account_name: type: string description: 'The submitted account holder name' example: 'Acme Corp Pty Ltd' required: - bsb_number - account_number - account_name parameters: - in: path name: company_id description: 'The company UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/companies/{company_id}/bank-account/verify': post: summary: 'Re-check company bank account' operationId: reCheckCompanyBankAccount description: "Re-runs Confirmation of Payee against the company's existing bank details. This is not payout-code verification." parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Confirmation of Payee re-check completed' content: application/json: schema: type: object example: message: 'Company bank account check completed.' is_verified: true properties: message: type: string example: 'Company bank account check completed.' description: 'Success message' is_verified: type: boolean example: true description: 'Whether Confirmation of Payee has verified the bank account' required: - message - is_verified tags: - 'Company Bank Account Management' parameters: - in: path name: company_id description: 'The company UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string /api/v1/login-sessions: post: summary: 'Create a hosted login session' operationId: createAHostedLoginSession description: "Creates a short-lived hosted login session. Open the returned `url` in the user's browser. After the user signs in and confirms, GoEscrow redirects to the partner's registered URL with `session_id`, `code`, and the optional `reference` query parameters.\n\n```bash\ncurl -X POST 'https://partner-api.goescrow.com.au/api/v1/login-sessions' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"email\":\"jane@example.com\",\"reference\":\"order-8812\"}'\n```" parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Hosted login session created' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 url: 'https://app.goescrow.com.au/partner-login/plaintext-session-token' expires_at: '2026-08-31T04:15:00.000000Z' reference: order-8812 properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: 'The hosted login session UUID' url: type: string example: 'https://app.goescrow.com.au/partner-login/plaintext-session-token' description: 'The single-use GoEscrow-hosted URL to open in the user browser' expires_at: type: string example: '2026-08-31T04:15:00.000000Z' description: 'The hosted URL expiry as an ISO 8601 timestamp' reference: type: string example: order-8812 description: 'The optional partner correlation identifier' required: - id - url - expires_at - reference 422: description: 'No redirect URL is registered' content: application/json: schema: type: object example: message: 'Hosted login is not configured for this partner. Contact GoEscrow to register a redirect URL.' properties: message: type: string example: 'Hosted login is not configured for this partner. Contact GoEscrow to register a redirect URL.' tags: - 'Hosted Login' requestBody: required: false content: application/json: schema: type: object properties: email: type: string description: 'Optional email address used only to prefill the hosted login form. It does not constrain the identity that can sign in.' example: jane@example.com reference: type: string description: 'Optional partner correlation identifier, echoed in the redirect and verification response.' example: order-8812 '/api/v1/login-sessions/{loginSession}/verify': post: summary: 'Verify a hosted login code' operationId: verifyAHostedLoginCode description: "Redeems the one-time code delivered to the registered redirect URL. Verification must use the same partner API key that created the session and must occur before the code expires.\n\n```bash\ncurl -X POST 'https://partner-api.goescrow.com.au/api/v1/login-sessions/9d2e5c8a-1234-5678-9abc-def012345678/verify' \\\n -H 'X-Api-Key: YOUR_API_KEY' \\\n -H 'Content-Type: application/json' \\\n -d '{\"code\":\"CODE_FROM_REDIRECT\"}'\n```" parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Login code verified' content: application/json: schema: type: object example: data: user: id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 first_name: Jane last_name: Doe email: jane@example.com phone: '+61412345678' birth_date: '1990-01-15' kyc_verified: true aml_verified: true aml_verified_at: '2026-08-20T00:00:00.000000Z' email_verified: true mobile_verified: true mobilekyc_verified: true bank_verified: true suspended: false address: null companies: - id: 9d2e5c8a-8765-4321-9abc-def012345678 reference: XYZ789 name: 'Acme Corp Pty Ltd' abn: '53004085616' kyb_verified: true reference: order-8812 authenticated_at: '2026-08-31T04:01:00.000000Z' properties: data: type: object properties: user: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 reference: type: string example: ABC123 first_name: type: string example: Jane last_name: type: string example: Doe email: type: string example: jane@example.com phone: type: string example: '+61412345678' birth_date: type: string example: '1990-01-15' kyc_verified: type: boolean example: true aml_verified: type: boolean example: true aml_verified_at: type: string example: '2026-08-20T00:00:00.000000Z' email_verified: type: boolean example: true mobile_verified: type: boolean example: true mobilekyc_verified: type: boolean example: true bank_verified: type: boolean example: true suspended: type: boolean example: false address: type: string example: null nullable: true companies: type: array example: - id: 9d2e5c8a-8765-4321-9abc-def012345678 reference: XYZ789 name: 'Acme Corp Pty Ltd' abn: '53004085616' kyb_verified: true description: 'The companies the user is a representative for that your partner account can access, ordered by name. A user from another partner can sign in through hosted login, so companies with none of your users as a representative are left out.' items: type: object properties: id: type: string example: 9d2e5c8a-8765-4321-9abc-def012345678 reference: type: string example: XYZ789 name: type: string example: 'Acme Corp Pty Ltd' abn: type: string example: '53004085616' kyb_verified: type: boolean example: true required: - companies description: 'The authenticated user, in the same format as GET /api/v1/users/lookup' reference: type: string example: order-8812 description: 'The optional partner correlation identifier' authenticated_at: type: string example: '2026-08-31T04:01:00.000000Z' description: 'When the user authenticated, as an ISO 8601 timestamp' required: - user - reference - authenticated_at 404: description: 'The session does not exist for this partner' content: application/json: schema: type: object example: message: 'Not Found' properties: message: type: string example: 'Not Found' 422: description: 'The code is wrong, expired, already redeemed, or the session is not authenticated' content: application/json: schema: type: object example: message: 'Invalid or expired login code.' properties: message: type: string example: 'Invalid or expired login code.' tags: - 'Hosted Login' requestBody: required: true content: application/json: schema: type: object properties: code: type: string description: 'The one-time code received at the registered redirect URL.' example: CODE_FROM_REDIRECT required: - code parameters: - in: path name: loginSession description: 'The hosted login session UUID returned during creation.' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/verification-codes/email': post: summary: 'Send a verification code by email' operationId: sendAVerificationCodeByEmail description: 'Only users your account created can be sent codes. Codes are 6 digits, expire after 10 minutes, work once, and lock after 5 incorrect attempts. Sending again for the same user, channel and reference replaces the previous code. Up to 5 codes per user and channel every 10 minutes. Errors from these endpoints carry a stable code and a retryable flag, except invalid input (the standard validation response with errors per field) and the per-user send limit (the standard 429 response). The user needs a verified email address. Without a message, GoEscrow sends its standard verification email. With a message, your subject and body are used inside the GoEscrow email, which always shows the code and "Sent on behalf of" your name.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Code sent' content: application/json: schema: type: object example: data: channel: email sent_to: 's***h@e*****e.com' id: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f reference: payout-change-981 expires_at: '2026-10-16T10:40:00+10:00' properties: data: type: object properties: channel: type: string example: email description: 'email or sms' sent_to: type: string example: 's***h@e*****e.com' description: 'The masked email address or mobile number the code went to' id: type: string example: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f description: 'Identifier of the code. Send it with the code the user gives you to check it.' reference: type: string example: payout-change-981 description: 'Your reference, unchanged' expires_at: type: string example: '2026-10-16T10:40:00+10:00' description: 'When the code expires, as an ISO 8601 timestamp' required: - channel - sent_to - id - reference - expires_at 403: description: 'Verification codes are not enabled for your account' content: application/json: schema: type: object example: message: 'Verification codes are not enabled for this partner. Contact GoEscrow to turn them on.' code: verification_codes_not_enabled retryable: false properties: message: type: string example: 'Verification codes are not enabled for this partner. Contact GoEscrow to turn them on.' code: type: string example: verification_codes_not_enabled retryable: type: boolean example: false 404: description: 'The user does not exist or was not created by your account' content: application/json: schema: type: object example: message: 'User not found or access denied.' code: user_not_found retryable: false properties: message: type: string example: 'User not found or access denied.' code: type: string example: user_not_found retryable: type: boolean example: false 409: description: 'A send for the same user, channel and reference is in progress' content: application/json: schema: type: object example: message: 'Another request for this code is in progress. Retry shortly.' code: verification_code_busy retryable: true properties: message: type: string example: 'Another request for this code is in progress. Retry shortly.' code: type: string example: verification_code_busy retryable: type: boolean example: true 422: description: '' content: application/json: schema: oneOf: - description: 'No verified email address' type: object example: message: 'The user has no verified email address.' code: email_not_verified retryable: false properties: message: type: string example: 'The user has no verified email address.' code: type: string example: email_not_verified retryable: type: boolean example: false - description: 'Invalid input: the standard validation response, with errors per field' type: object example: message: 'The reference field is required.' errors: reference: - 'The reference field is required.' properties: message: type: string example: 'The reference field is required.' errors: type: object properties: reference: type: array example: - 'The reference field is required.' items: type: string 429: description: 'More than 5 codes for this user in 10 minutes: the standard rate limit response' content: application/json: schema: type: object example: message: 'Too Many Attempts.' properties: message: type: string example: 'Too Many Attempts.' 503: description: 'Sending failed; the code was not issued' content: application/json: schema: type: object example: message: 'The code could not be sent. Retry shortly.' code: verification_code_send_failed retryable: true properties: message: type: string example: 'The code could not be sent. Retry shortly.' code: type: string example: verification_code_send_failed retryable: type: boolean example: true tags: - 'Verification Codes' requestBody: required: true content: application/json: schema: type: object properties: reference: type: string description: 'Your label for what the code is for, up to 100 characters. It is returned when the code is checked, so a code sent for one task cannot be mistaken for another.' example: payout-change-981 message: type: object description: 'Optional wording for the email. Plain text only, no links or web addresses.' example: [] properties: subject: type: string description: 'Email subject, up to 80 characters. Required with message.' example: 'Confirm your new payout account' body: type: string description: 'Email text shown above the code, up to 600 characters. Required with message.' example: 'Use this code to confirm the new payout account on your CarHub profile.' required: - reference parameters: - in: path name: user_id description: 'The user UUID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/verification-codes/sms': post: summary: 'Send a verification code by SMS' operationId: sendAVerificationCodeBySMS description: 'Only users your account created can be sent codes. Codes are 6 digits, expire after 10 minutes, work once, and lock after 5 incorrect attempts. Sending again for the same user, channel and reference replaces the previous code. Up to 5 codes per user and channel every 10 minutes. Errors from these endpoints carry a stable code and a retryable flag, except invalid input (the standard validation response with errors per field) and the per-user send limit (the standard 429 response). The user needs a verified mobile number. Without a message, the SMS reads " via GoEscrow: Your verification code is 123456. It expires in 10 minutes. Never share it." With a message, it reads " via GoEscrow: Never share this code." There is a daily limit on SMS codes per partner.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Code sent' content: application/json: schema: type: object example: data: id: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f channel: sms reference: payout-change-981 sent_to: '+61******111' expires_at: '2026-10-16T10:40:00+10:00' properties: data: type: object properties: id: type: string example: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f description: 'Identifier of the code. Send it with the code the user gives you to check it.' channel: type: string example: sms description: 'email or sms' reference: type: string example: payout-change-981 description: 'Your reference, unchanged' sent_to: type: string example: '+61******111' description: 'The masked email address or mobile number the code went to' expires_at: type: string example: '2026-10-16T10:40:00+10:00' description: 'When the code expires, as an ISO 8601 timestamp' required: - id - channel - reference - sent_to - expires_at 403: description: 'Verification codes are not enabled for your account' content: application/json: schema: type: object example: message: 'Verification codes are not enabled for this partner. Contact GoEscrow to turn them on.' code: verification_codes_not_enabled retryable: false properties: message: type: string example: 'Verification codes are not enabled for this partner. Contact GoEscrow to turn them on.' code: type: string example: verification_codes_not_enabled retryable: type: boolean example: false 404: description: 'The user does not exist or was not created by your account' content: application/json: schema: type: object example: message: 'User not found or access denied.' code: user_not_found retryable: false properties: message: type: string example: 'User not found or access denied.' code: type: string example: user_not_found retryable: type: boolean example: false 409: description: 'A send for the same user, channel and reference is in progress' content: application/json: schema: type: object example: message: 'Another request for this code is in progress. Retry shortly.' code: verification_code_busy retryable: true properties: message: type: string example: 'Another request for this code is in progress. Retry shortly.' code: type: string example: verification_code_busy retryable: type: boolean example: true 422: description: '' content: application/json: schema: oneOf: - description: 'No verified mobile number' type: object example: message: 'The user has no verified mobile number.' code: mobile_not_verified retryable: false properties: message: type: string example: 'The user has no verified mobile number.' code: type: string example: mobile_not_verified retryable: type: boolean example: false - description: 'Invalid input: the standard validation response, with errors per field' type: object example: message: 'The reference field is required.' errors: reference: - 'The reference field is required.' properties: message: type: string example: 'The reference field is required.' errors: type: object properties: reference: type: array example: - 'The reference field is required.' items: type: string 429: description: '' content: application/json: schema: oneOf: - description: 'Daily SMS limit reached' type: object example: message: 'This partner has reached its daily limit of SMS verification codes. Try again tomorrow or contact GoEscrow.' code: verification_code_daily_sms_limit retryable: false properties: message: type: string example: 'This partner has reached its daily limit of SMS verification codes. Try again tomorrow or contact GoEscrow.' code: type: string example: verification_code_daily_sms_limit retryable: type: boolean example: false - description: 'More than 5 codes for this user in 10 minutes: the standard rate limit response' type: object example: message: 'Too Many Attempts.' properties: message: type: string example: 'Too Many Attempts.' 503: description: 'Sending failed; the code was not issued' content: application/json: schema: type: object example: message: 'The code could not be sent. Retry shortly.' code: verification_code_send_failed retryable: true properties: message: type: string example: 'The code could not be sent. Retry shortly.' code: type: string example: verification_code_send_failed retryable: type: boolean example: true tags: - 'Verification Codes' requestBody: required: true content: application/json: schema: type: object properties: reference: type: string description: 'Your label for what the code is for, up to 100 characters. It is returned when the code is checked, so a code sent for one task cannot be mistaken for another.' example: payout-change-981 message: type: string description: 'Optional SMS text, up to 120 characters, containing {code} exactly once where the code goes. Plain text on one line, no links or web addresses.' example: 'Your code to confirm your new CarHub payout account is {code}.' required: - reference parameters: - in: path name: user_id description: 'The user UUID' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/verification-codes/{verification_code_id}/verify': post: summary: 'Check a verification code' operationId: checkAVerificationCode description: 'Checks the code your user gave you. A correct code is marked as used and cannot be checked again. Only the partner that sent a code can check it. Up to 30 checks a minute.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Code correct' content: application/json: schema: type: object example: data: verified: true id: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f channel: sms reference: payout-change-981 verified_at: '2026-10-16T10:32:00+10:00' properties: data: type: object properties: verified: type: boolean example: true description: 'Always true. Any other outcome is an error response.' id: type: string example: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f channel: type: string example: sms reference: type: string example: payout-change-981 description: 'The reference the code was sent with. Check it matches the task you are confirming.' verified_at: type: string example: '2026-10-16T10:32:00+10:00' description: 'When the code was checked, as an ISO 8601 timestamp' required: - verified - reference - verified_at 403: description: 'Verification codes are not enabled for your account' content: application/json: schema: type: object example: message: 'Verification codes are not enabled for this partner. Contact GoEscrow to turn them on.' code: verification_codes_not_enabled retryable: false properties: message: type: string example: 'Verification codes are not enabled for this partner. Contact GoEscrow to turn them on.' code: type: string example: verification_codes_not_enabled retryable: type: boolean example: false 404: description: 'No code with this id was sent by your account' content: application/json: schema: type: object example: message: 'Verification code not found.' code: verification_code_not_found retryable: false properties: message: type: string example: 'Verification code not found.' code: type: string example: verification_code_not_found retryable: type: boolean example: false 409: description: 'Another check of the same code is in progress' content: application/json: schema: type: object example: message: 'Another request for this code is in progress. Retry shortly.' code: verification_code_busy retryable: true properties: message: type: string example: 'Another request for this code is in progress. Retry shortly.' code: type: string example: verification_code_busy retryable: type: boolean example: true 422: description: '' content: application/json: schema: oneOf: - description: 'Codes: verification_code_incorrect, verification_code_locked (5 incorrect attempts), verification_code_expired, verification_code_used, verification_code_replaced (a newer code was sent for the reference)' type: object example: message: 'The verification code is incorrect.' code: verification_code_incorrect retryable: false properties: message: type: string example: 'The verification code is incorrect.' code: type: string example: verification_code_incorrect retryable: type: boolean example: false - description: 'Invalid input: the standard validation response, with errors per field' type: object example: message: 'The verification code field must be 6 digits.' errors: verification_code: - 'The verification code field must be 6 digits.' properties: message: type: string example: 'The verification code field must be 6 digits.' errors: type: object properties: verification_code: type: array example: - 'The verification code field must be 6 digits.' items: type: string 429: description: 'More than 30 checks in a minute: the standard rate limit response' content: application/json: schema: type: object example: message: 'Too Many Attempts.' properties: message: type: string example: 'Too Many Attempts.' tags: - 'Verification Codes' requestBody: required: true content: application/json: schema: type: object properties: verification_code: type: string description: 'The 6-digit code the user gave you' example: '482913' required: - verification_code parameters: - in: path name: verification_code_id description: 'The id returned when the code was sent' example: 7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f required: true schema: type: string