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: '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.' 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/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. 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.' example: '40 650 703 736' required: true schema: type: string description: 'The Australian Business Number. Formatting spaces are accepted.' example: '40 650 703 736' - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Company found' content: application/json: schema: 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 reference: type: string example: ABC123 name: type: string example: 'Acme Corp Pty Ltd' abn: type: string example: '40650703736' acn: type: string example: '004085616' kyb_verified: type: boolean example: true aml_verified: type: boolean example: true aml_verified_at: type: string example: '2026-06-25T00:00:00.000000Z' bank_verified: type: boolean example: true abr_status: type: string example: Active representatives: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345679 reference: ABC123 name: 'Jane Doe' 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.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Company created successfully' content: application/json: schema: 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 reference: type: string example: ABC123 name: type: string example: 'Acme Corp Pty Ltd' abn: type: string example: '40650703736' acn: type: string example: '004085616' kyb_verified: type: boolean example: true aml_verified: type: boolean example: true aml_verified_at: type: string example: '2026-06-25T00:00:00.000000Z' bank_verified: type: boolean example: true abr_status: type: string example: Active representatives: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' 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: true content: application/json: schema: type: object properties: name: type: string description: 'Ignored when supplied; the company name is sourced from the Australian Business Register' example: 'Acme Corp Pty Ltd' abn: type: string description: 'Australian Business Number' 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' 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." example: unit_number: '3' street_number: '20' street: 'Company Street' suburb: Melbourne state: VIC postcode: '3000' country: Australia properties: {} 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: 'Company updated successfully' content: application/json: schema: 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 reference: type: string example: ABC123 name: type: string example: 'Acme Corp Pty Ltd' abn: type: string example: '40650703736' acn: type: string example: '004085616' kyb_verified: type: boolean example: true aml_verified: type: boolean example: true aml_verified_at: type: string example: '2026-06-25T00:00:00.000000Z' bank_verified: type: boolean example: true abr_status: type: string example: Active representatives: type: array example: - id: 9d2e5c8a-1234-5678-9abc-def012345678 reference: ABC123 name: 'Jane Doe' 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." example: unit_number: '3' street_number: '20' street: 'Company Street' suburb: Melbourne state: VIC postcode: '3000' country: Australia properties: {} 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/users: post: 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 responses: 201: description: 'User created 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 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 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 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 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. Must be a valid Australian phone number (e.g., 0412345678, +61412345678, or 61412345678)." 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.' 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/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 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 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. Must be a valid Australian phone number (e.g., 0412345678, +61412345678, or 61412345678)." 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." 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." 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 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: true aml_verified: type: boolean example: true aml_verified_at: type: string example: '2026-06-25T00: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: 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 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 - 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' reference: type: string example: XYZ789 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}/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' expires_in: type: string example: '60 minutes' 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.' dispute_reference: type: string example: DISP-2024-001234 transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 status: type: string example: disputed 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.' 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 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 details: type: string example: 'Property settlement for 123 Main St' created_at: type: string example: '2024-01-15T10:30:00Z' 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 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: - reprehenderit 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: azupay account_scope: transaction payment_reference: TXN-2024-001234 reference_required: false provisioning_status: ready amount_received: '0.00' amount_outstanding: '151500.50' 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: azupay 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' 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: fac6745b-d8fd-3df8-bad7-64b3a0a8d271 reference_id: type: string description: 'This field is required when transaction_id is not present.' example: delectus party_id: type: string description: 'Must be a valid UUID.' example: 32fbd4f4-b19d-3de9-84fa-3ff4c85c1f85 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: azupay account_scope: transaction payment_reference: TXN-2024-001234 reference_required: false provisioning_status: ready amount_received: '0.00' amount_outstanding: '151500.50' 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 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: azupay 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' required: - rail - account_scope - payment_reference - reference_required - provisioning_status - amount_received - amount_outstanding required: - id - reference - type - sub_type - status - funding_status - amount - fee - amount_with_fee - release_at - funding_details 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: eum required: true schema: type: string - in: path name: beneficiary description: 'The beneficiary UUID' example: sed 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 amount: type: number example: 150000.5 partner_fee: type: number example: 299.4 partner_fee_percentage: type: number example: 0.2 goescrow_fee: type: integer example: 0 goescrow_fee_percentage: type: integer example: 0 total_fees: type: number example: 299.4 net_amount: type: number example: 149701.1 disbursements_count: type: integer example: 2 disbursements: type: array example: - user_id: 9d2e5c8a-1234-5678-9abc-def012345679 amount: 74850.55 - company_id: 9d2e5c8a-1234-5678-9abc-def012345680 amount: 74850.55 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: - natus 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': post: summary: 'Trigger marketplace settlement' operationId: triggerMarketplaceSettlement description: 'Triggers settlement for a marketplace escrow transaction. Only the marketplace operator can trigger settlement.' 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.' transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 status: type: string example: settlement_in_progress required: - message - transaction_id - status 403: description: 'Not authorized' 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.' required: - message 422: description: 'Invalid transaction type' content: application/json: schema: type: object example: message: 'Only marketplace escrow transactions can be settled via API.' properties: message: type: string example: 'Only marketplace escrow transactions can be settled via API.' 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 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}/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 message: type: string example: 'Payment initiation queued. Use the tracking_id to poll for status.' tracking_id: type: string example: payto_9d2e5c8a 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 message: type: string example: 'This transaction is already funded.' 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 message: type: string example: 'User does not have a PayTo agreement set up.' 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 (from Azupay).' 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 message: type: string example: 'Payment settled successfully. Transaction is now funded.' status: type: string example: settled 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 message: type: string example: 'Payment is still processing.' status: type: string example: pending required: - code - message - status - description: 'Payment failed' type: object example: code: failed message: 'Payment was rejected.' status: failed properties: code: type: string example: failed message: type: string example: 'Payment was rejected.' status: type: string example: failed required: - code - message - status - description: 'Job queued' type: object example: code: queued message: 'Payment initiation is queued for processing.' status: queued properties: code: type: string example: queued message: type: string example: 'Payment initiation is queued for processing.' status: type: string example: queued 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 an Azupay 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.' is_verified: type: boolean example: false 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.' is_verified: type: boolean example: true 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.' 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 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 rapidid_verified_at: type: string example: null rapidid_failed_at: type: string example: null 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 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 rapidid_verified_at: type: string example: null rapidid_failed_at: type: string example: null 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 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 rapidid_verified_at: type: string example: null rapidid_failed_at: type: string example: null 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 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 rapidid_verified_at: type: string example: null rapidid_failed_at: type: string example: null 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 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 rapidid_verified_at: type: string example: null rapidid_failed_at: type: string example: null 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 agreement_id: type: string example: PA-123456 maximum_amount: type: integer example: 10000 status: type: string example: ACTIVE 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 agreement_id: type: string example: null maximum_amount: type: string example: null status: type: string example: null 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 status: type: string example: CREATED message: type: string example: 'PayTo agreement created. User must authorize in their banking app.' 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' 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).' 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.' id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 url: type: string example: 'https://partner.com/webhooks/goescrow' secret: type: string example: whsec_abc123xyz789... events: type: array example: - transaction.created - transaction.clearance_pending 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. 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.' 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.' 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 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 event: type: string example: transaction.funded status: type: string example: 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.' is_verified: type: boolean example: true 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.' is_verified: type: boolean example: true 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 url: type: string example: 'https://app.goescrow.com.au/partner-login/plaintext-session-token' expires_at: type: string example: '2026-08-31T04:15:00.000000Z' reference: type: string example: order-8812 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 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 reference: type: string example: order-8812 authenticated_at: type: string example: '2026-08-31T04:01:00.000000Z' 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