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 Transaction Cancellations' - 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' 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: post: summary: 'Create a new company' operationId: createANewCompany description: "Creates a new company with a designated company representative. The company representative will be created as a user if they don't already exist." 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 name: 'Acme Corp Pty Ltd' abn: '12345678901' acn: '123456789' company_representative_id: 9d2e5c8a-1234-5678-9abc-def012345678 company_representative_reference: ABC123 properties: data: type: object properties: id: type: string example: comp_123 description: '' enum: [] name: type: string example: 'Acme Corp Pty Ltd' description: '' enum: [] abn: type: string example: '12345678901' acn: type: string example: '123456789' company_representative_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] company_representative_reference: type: string example: ABC123 description: '' enum: [] required: - id - name - company_representative_id - company_representative_reference tags: - 'Company Management' requestBody: required: true content: application/json: schema: type: object properties: name: type: string description: 'The company name' example: 'Acme Corp Pty Ltd' nullable: false abn: type: string description: 'Australian Business Number' example: '12345678901' nullable: false acn: type: string description: 'Australian Company Number' example: '123456789' nullable: false email: type: string description: 'Company email address' example: info@acmecorp.com.au nullable: false phone: type: string description: 'Company phone number in international format' example: '+61298765432' nullable: false website: type: string description: 'Company website URL' example: 'https://www.acmecorp.com.au' nullable: false type: type: string description: 'Company type/structure' example: 'Proprietary Limited' nullable: false majority_owned_by_another_australian_company: type: boolean description: 'Whether the company is majority owned by another Australian company' example: false nullable: 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 nullable: false majority_owned_by_listed_australian_company: type: boolean description: 'Whether the company is majority owned by a listed Australian company' example: false nullable: false acting_as_trustee_for_a_trust: type: boolean description: 'Whether the company is acting as trustee for a trust' example: false nullable: false company_representative: type: object description: '' example: first_name: John nullable: false properties: first_name: type: string description: 'Company representative first name' example: John nullable: false last_name: type: string description: 'Company representative last name' example: Smith nullable: false email: type: string description: 'Company representative email address' example: john.smith@acmecorp.com.au nullable: false phone: type: string description: 'Company representative phone number in international format' example: '+61412345678' nullable: false birth_date: type: string description: 'Company representative date of birth in YYYY-MM-DD format' example: '1985-03-15' nullable: false address: type: object description: '' example: unit_number: 12B nullable: false properties: unit_number: type: string description: 'Unit number' example: 12B nullable: false street_number: type: string description: 'Street number' example: '123' nullable: false street: type: string description: 'Street name' example: 'Main St' nullable: false suburb: type: string description: Suburb example: Brisbane nullable: false state: type: string description: State example: QLD nullable: false postcode: type: string description: Postcode example: '4000' nullable: false required: - first_name - last_name - email - phone - birth_date required: - name - email - phone - 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 '/api/v1/companies/{id}': put: summary: 'Update a company' operationId: updateACompany description: 'Updates an existing company. Only provided fields will be updated.' 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 name: 'Acme Corp Pty Ltd' company_representative_id: 9d2e5c8a-1234-5678-9abc-def012345678 company_representative_reference: ABC123 properties: data: type: object properties: id: type: string example: comp_123 description: '' enum: [] name: type: string example: 'Acme Corp Pty Ltd' description: '' enum: [] company_representative_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] company_representative_reference: type: string example: ABC123 description: '' enum: [] required: - id - name - company_representative_id - company_representative_reference 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' nullable: false abn: type: string description: 'Australian Business Number' example: '12345678901' nullable: false acn: type: string description: 'Australian Company Number' example: '123456789' nullable: false email: type: string description: 'Company email address' example: info@acmecorp.com.au nullable: false phone: type: string description: 'Company phone number in international format' example: '+61298765432' nullable: false website: type: string description: 'Company website URL' example: 'https://www.acmecorp.com.au' nullable: false type: type: string description: 'Company type/structure' example: 'Proprietary Limited' nullable: false majority_owned_by_another_australian_company: type: boolean description: 'Whether the company is majority owned by another Australian company' example: false nullable: 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 nullable: false majority_owned_by_listed_australian_company: type: boolean description: 'Whether the company is majority owned by a listed Australian company' example: false nullable: false acting_as_trustee_for_a_trust: type: boolean description: 'Whether the company is acting as trustee for a trust' example: false nullable: false 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.' 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 email_verified: false mobile_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 description: '' enum: [] reference: type: string example: ABC123 description: '' enum: [] first_name: type: string example: John description: '' enum: [] last_name: type: string example: Doe description: '' enum: [] email: type: string example: john.doe@example.com description: '' enum: [] phone: type: string example: '+61412345678' description: '' enum: [] birth_date: type: string example: '1990-01-15' description: '' enum: [] kyc_verified: type: boolean example: false description: '' enum: [] email_verified: type: boolean example: false description: '' enum: [] mobile_verified: type: boolean example: false description: '' enum: [] bank_verified: type: boolean example: false description: '' enum: [] suspended: type: boolean example: false description: '' enum: [] address: type: object properties: unit_number: type: string example: 10B street_number: type: string example: '123' street: type: string example: 'Smith St' suburb: type: string example: Sydney state: type: string example: NSW postcode: type: string example: '2000' country: type: string example: Australia description: '' required: - id - reference - first_name - last_name - email - phone - birth_date - kyc_verified - email_verified - mobile_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 nullable: false last_name: type: string description: "The user's last name" example: Doe nullable: false email: type: string description: "The user's email address. Must be a valid email format." example: john.doe@example.com nullable: false phone: type: string description: "The user's phone number. Must be a valid Australian phone number (e.g., 0412345678, +61412345678, or 61412345678)." example: '+61412345678' nullable: false birth_date: type: string description: "The user's date of birth in YYYY-MM-DD format. Optional." example: '1990-01-15' nullable: false 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' nullable: false 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 email_verified: false mobile_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 email_verified: type: boolean example: false mobile_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 nullable: false last_name: type: string description: "The user's last name" example: Doe nullable: false email: type: string description: "The user's email address. Must be a valid email format." example: john.doe@example.com nullable: false phone: type: string description: "The user's phone number. Must be a valid Australian phone number (e.g., 0412345678, +61412345678, or 61412345678)." example: '+61412345678' nullable: false birth_date: type: string description: "The user's date of birth in YYYY-MM-DD format. Optional." example: '1990-01-15' nullable: false 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' nullable: false 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' operationId: lookupUser description: 'Look up an existing user by email OR phone without creating. At least one parameter must be provided. Returns user details if found, 404 if not found.' parameters: - in: query name: email description: "The user's email address to search for (OR phone required)." example: john.doe@example.com required: false schema: type: string description: "The user's email address to search for (OR phone required)." example: john.doe@example.com nullable: false - in: query name: phone description: "The user's phone number to search for (OR email required). Can be in various formats (0412345678, +61412345678, 61412345678)." example: '+61412345678' required: false schema: type: string description: "The user's phone number to search for (OR email required). Can be in various formats (0412345678, +61412345678, 61412345678)." example: '+61412345678' nullable: false - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'User found' 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: true email_verified: true mobile_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 description: '' enum: [] reference: type: string example: ABC123 description: '' enum: [] first_name: type: string example: John description: '' enum: [] last_name: type: string example: Doe description: '' enum: [] email: type: string example: john.doe@example.com description: '' enum: [] phone: type: string example: '+61412345678' description: '' enum: [] birth_date: type: string example: '1990-01-15' description: '' enum: [] kyc_verified: type: boolean example: true description: '' enum: [] email_verified: type: boolean example: true description: '' enum: [] mobile_verified: type: boolean example: true description: '' enum: [] bank_verified: type: boolean example: true description: '' enum: [] suspended: type: boolean example: false description: '' enum: [] address: type: object properties: unit_number: type: string example: '1' street_number: type: string example: '123' street: type: string example: 'Main Street' suburb: type: string example: Sydney state: type: string example: NSW postcode: type: string example: '2000' country: type: string example: Australia description: '' required: - id - reference - first_name - last_name - email - phone - birth_date - kyc_verified - email_verified - mobile_verified - bank_verified - suspended - address 404: description: 'User not found' content: application/json: schema: type: object example: message: 'User not found.' properties: message: type: string example: 'User not found.' 422: description: 'Validation error' content: application/json: schema: 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.' 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' nullable: false 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' nullable: false 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}/password-reset-link': post: summary: 'Generate password reset link' operationId: generatePasswordResetLink description: 'Generates a 24-hour 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: '24 hours' properties: reset_url: type: string example: 'https://app.goescrow.com.au/auth/forgot-password/abc123' description: '' enum: [] expires_in: type: string example: '24 hours' description: '' enum: [] 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 nullable: false 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 responses: 201: description: 'Dispute created' content: application/json: schema: type: object example: message: 'Dispute created successfully.' dispute_reference: DISP-2024-001234 transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: disputed properties: message: type: string example: 'Dispute created successfully.' description: '' enum: [] dispute_reference: type: string example: DISP-2024-001234 description: '' enum: [] transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] status: type: string example: disputed description: '' enum: [] required: - message - dispute_reference - transaction_id - status 422: description: 'Invalid transaction status' content: application/json: schema: type: object example: message: 'Transaction status does not allow disputes.' properties: message: type: string example: 'Transaction status does not allow disputes.' description: '' enum: [] 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 nullable: false requester_role: type: string description: 'The role of the requester: buyer or seller' example: buyer nullable: false enum: - buyer - seller transaction_id: type: string description: 'The transaction ID' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false request_type: type: string description: 'The type of request: pause, settle_to_requester, split, other' example: pause nullable: false 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.' nullable: false 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 a cancellation request for a transaction. For pending/unfunded transactions, cancellation is immediate. For funded transactions, 2FA codes will be sent to the requester.' 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 requested. 2FA verification required.' requires_2fa: true transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: accepted properties: message: type: string example: 'Cancellation requested. 2FA verification required.' description: '' enum: [] requires_2fa: type: boolean example: true description: '' enum: [] transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] status: type: string example: accepted description: '' enum: [] required: - message - requires_2fa - transaction_id - status - description: 'Transaction cancelled (pending/unfunded)' 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: '' enum: [] requires_2fa: type: boolean example: false description: '' enum: [] transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] status: type: string example: canceled description: '' enum: [] 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 ID of the party requesting cancellation' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false 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 2FA codes' operationId: verifyCancellation2FACodes description: 'Completes a funded transaction cancellation by verifying the 2FA codes sent to the requester.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Cancellation completed' content: application/json: schema: type: object example: message: 'Transaction cancelled successfully. Refund initiated.' transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: canceled properties: message: type: string example: 'Transaction cancelled successfully. Refund initiated.' description: '' enum: [] transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] status: type: string example: canceled description: '' enum: [] required: - message - 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: '' enum: [] required: - message tags: - 'Transaction Cancellation' requestBody: required: true content: application/json: schema: type: object properties: requester_id: type: string description: 'The user ID of the party requesting cancellation' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false email_code: type: string description: 'The 6-digit code sent to email' example: '123456' nullable: false phone_code: type: string description: 'The 6-digit code sent to phone' example: '654321' nullable: false 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: 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 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' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] reference: type: string example: TXN-2024-001234 description: '' enum: [] type: type: string example: anytime_escrow description: '' enum: [] sub_type: type: string example: marketplace description: '' enum: [] status: type: string example: accepted description: '' enum: [] funding_status: type: string example: pending description: '' enum: [] amount: type: number example: 150000.5 details: type: string example: 'Property settlement for 123 Main St' description: '' enum: [] created_at: type: string example: '2024-01-15T10:30:00Z' description: '' enum: [] required: - id - reference - type - sub_type - status - funding_status - details - created_at 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 nullable: false type: type: string description: 'Transaction type: anytime_escrow or timed_escrow.' example: anytime_escrow nullable: false amount_type: type: string description: 'Indicates whether amount is escrow (gross) or settlement (net).' example: escrow nullable: false other_user: type: string description: 'Counterparty user ID for standard escrow (required when disbursements not provided).' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false sub_type: type: string description: 'The transaction sub type (optional: omit or null for plain anytime escrow, marketplace for marketplace-controlled settlement)' example: marketplace nullable: false user_id: type: string description: 'The ID of the buyer/payer' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false company_id: type: string description: 'The ID of the agent company (required for super_disbursement)' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false 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 nullable: false 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' nullable: false details: type: string description: 'Transaction details and description' example: 'Dental Surgery' nullable: false amount: type: integer description: 'Total transaction amount in cents (e.g., 15000050 for $150,000.50)' example: 15000050 nullable: false disbursements: type: array description: 'Array of disbursement objects (required for super_disbursement). Omit for standard escrow to auto-allocate to other_user.' example: - dignissimos items: type: string required: - action - type - amount_type - user_id - details - amount '/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 nullable: false - 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 properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] reference: type: string example: TXN-2024-001234 description: '' enum: [] type: type: string example: anytime_escrow description: '' enum: [] sub_type: type: string example: marketplace description: '' enum: [] status: type: string example: accepted description: '' enum: [] funding_status: type: string example: pending description: '' enum: [] amount: type: number example: 150000.5 description: '' enum: [] fee: type: integer example: 1500 description: '' enum: [] amount_with_fee: type: number example: 151500.5 description: '' enum: [] details: type: string example: 'Property settlement' release_at: type: string example: null description: '' enum: [] 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 description: '' 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/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: 200: description: 'Transaction quote calculated successfully' content: application/json: schema: type: object example: data: sub_type: super_disbursement amount: 150000.5 partner_fee: 750 partner_fee_percentage: 0.5 goescrow_fee: 300 goescrow_fee_percentage: 0.2 total_fees: 1050 net_amount: 149950.5 disbursements_count: 2 properties: data: type: object properties: sub_type: type: string example: super_disbursement amount: type: number example: 150000.5 partner_fee: type: integer example: 750 partner_fee_percentage: type: number example: 0.5 goescrow_fee: type: integer example: 300 goescrow_fee_percentage: type: number example: 0.2 total_fees: type: integer example: 1050 net_amount: type: number example: 149950.5 disbursements_count: type: integer example: 2 tags: - 'Transaction Management' requestBody: required: true content: application/json: schema: type: object properties: action: type: string description: 'Transaction direction: buy or sell' example: buy nullable: false type: type: string description: 'Transaction type: anytime_escrow or timed_escrow' example: anytime_escrow nullable: false amount_type: type: string description: 'Indicates whether amount is escrow (gross) or settlement (net).' example: escrow nullable: false other_user: type: string description: 'Counterparty user ID for standard escrow (required when disbursements not provided).' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false sub_type: type: string description: 'The transaction sub type (optional: omit or null for plain anytime escrow)' example: super_disbursement nullable: false user_id: type: string description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false company_id: type: string description: 'The ID of the agent company (required for super_disbursement)' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false 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' nullable: false details: type: string description: 'Transaction details and description' example: 'Dental Surgery' nullable: false amount: type: integer description: 'Total transaction amount in cents (e.g., 15000050 for $150,000.50)' example: 15000050 nullable: false disbursements: type: array description: 'Array of disbursement objects (required for super_disbursement). Omit for standard escrow to auto-allocate to other_user.' example: - repellendus items: type: string required: - action - type - amount_type - user_id - details - amount '/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 responses: 200: description: 'Settlement initiated' content: application/json: schema: type: object example: message: 'Settlement initiated successfully.' transaction_id: 9d2e5c8a-1234-5678-9abc-def012345678 status: settlement_in_progress properties: message: type: string example: 'Settlement initiated successfully.' description: '' enum: [] transaction_id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] status: type: string example: settlement_in_progress description: '' enum: [] 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.' description: '' enum: [] 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.' description: '' enum: [] required: - message tags: - 'Transaction Management' requestBody: required: true content: application/json: schema: type: object properties: buyer_id: type: string description: 'The buyer user ID for verification' example: 9d2e5c8a-1234-5678-9abc-def012345678 nullable: false seller_id: type: string description: 'The seller user ID for verification' example: 9d2e5c8a-1234-5678-9abc-def012345679 nullable: false settlement_amount: type: number description: 'The settlement amount (must match escrow amount)' example: 150000.5 nullable: false 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 responses: 202: description: 'Payment initiation queued for processing' content: application/json: schema: type: object example: code: accepted message: 'Payment initiation queued. Use the tracking_id to poll for status.' tracking_id: payto_9d2e5c8a properties: code: type: string example: accepted description: '' enum: [] message: type: string example: 'Payment initiation queued. Use the tracking_id to poll for status.' description: '' enum: [] tracking_id: type: string example: payto_9d2e5c8a description: '' enum: [] required: - code - message - tracking_id 400: description: '' content: application/json: schema: oneOf: - description: 'Transaction already funded' type: object example: code: transaction_already_funded message: 'This transaction is already funded.' properties: code: type: string example: transaction_already_funded description: '' enum: [] message: type: string example: 'This transaction is already funded.' description: '' enum: [] required: - code - message - description: 'PayTo not configured' type: object example: code: no_payment_agreement message: 'User does not have a PayTo agreement set up.' properties: code: type: string example: no_payment_agreement description: '' enum: [] message: type: string example: 'User does not have a PayTo agreement set up.' description: '' enum: [] 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 nullable: false 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 description: '' enum: [] message: type: string example: 'Payment settled successfully. Transaction is now funded.' description: '' enum: [] status: type: string example: settled description: '' enum: [] required: - code - message - status - description: 'Payment pending' type: object example: code: pending message: 'Payment is still processing.' status: pending properties: code: type: string example: pending description: '' enum: [] message: type: string example: 'Payment is still processing.' description: '' enum: [] status: type: string example: pending description: '' enum: [] required: - code - message - status - description: 'Payment failed' type: object example: code: failed message: 'Payment was rejected.' status: failed properties: code: type: string example: failed description: '' enum: [] message: type: string example: 'Payment was rejected.' description: '' enum: [] status: type: string example: failed description: '' enum: [] 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 description: '' enum: [] message: type: string example: 'Payment initiation is queued for processing.' description: '' enum: [] status: type: string example: queued description: '' enum: [] 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.' description: '' enum: [] is_verified: type: boolean example: false description: '' enum: [] 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' nullable: false account_number: type: string description: 'The bank account number' example: '12345678' nullable: false account_name: type: string description: 'The account holder name' example: 'John Doe' nullable: false required: - bsb_number - account_number - account_name parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/bank-account/verify': post: summary: 'Verify user bank account' operationId: verifyUserBankAccount description: 'Verifies the bank account using the 6-digit code received in the $0.01 verification payout.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Bank account verified successfully' content: application/json: schema: type: object example: message: 'Bank account verified successfully.' is_verified: true properties: message: type: string example: 'Bank account verified successfully.' description: '' enum: [] is_verified: type: boolean example: true description: '' enum: [] required: - message - is_verified 422: description: 'Invalid verification code' content: application/json: schema: type: object example: message: 'The verification code is incorrect.' properties: message: type: string example: 'The verification code is incorrect.' description: '' enum: [] 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' nullable: false 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: Australian date_of_birth: '1990-01-15' date_of_issue: '2020-01-15' date_of_expiration: '2030-01-15' place_of_birth: 'Sydney, Australia' gender: M rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] document_number: type: string example: N1234567 description: '' enum: [] first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael nationality: type: string example: Australian date_of_birth: type: string example: '1990-01-15' date_of_issue: type: string example: '2020-01-15' date_of_expiration: type: string example: '2030-01-15' place_of_birth: type: string example: 'Sydney, Australia' gender: type: string example: M rapidid_verification_requested_at: type: string example: null description: '' enum: [] rapidid_verified_at: type: string example: null description: '' enum: [] rapidid_failed_at: type: string example: null description: '' enum: [] 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 nullable: false first_name: type: string description: 'First name as shown on passport' example: John nullable: false last_name: type: string description: 'Last name as shown on passport' example: Doe nullable: false middle_name: type: string description: 'Middle name as shown on passport' example: Michael nullable: false nationality: type: string description: 'Nationality as shown on passport' example: Australian nullable: false date_of_birth: type: string description: 'Date of birth in YYYY-MM-DD format' example: '1990-01-15' nullable: false date_of_issue: type: string description: 'Date of issue in YYYY-MM-DD format' example: '2020-01-15' nullable: false date_of_expiration: type: string description: 'Date of expiration in YYYY-MM-DD format' example: '2030-01-15' nullable: false place_of_birth: type: string description: 'Place of birth as shown on passport' example: 'Sydney, Australia' nullable: false gender: type: string description: 'Gender as shown on passport (M, F, X, or BLANK)' example: M nullable: false required: - document_number - first_name - last_name - nationality - 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: Australian 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: Australian 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' 404: description: 'Passport not found' content: application/json: schema: type: object example: error: 'Passport not found for this user.' properties: error: type: string example: 'Passport not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user passport' operationId: deleteUserPassport description: 'Deletes the passport record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Passport deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Passport not found' content: application/json: schema: type: object example: error: 'Passport not found for this user.' properties: error: type: string example: 'Passport not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/medicare': post: summary: 'Create or update user Medicare card' operationId: createOrUpdateUserMedicareCard description: 'Creates a new Medicare card record for the user or updates an existing one. Only one Medicare card per user is allowed.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Medicare card created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 document_number: '1234567890' name_on_card: 'John Michael Doe' card_color: green individual_reference_number: '1' expiration_date: 2025-12 rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] document_number: type: string example: '1234567890' description: '' enum: [] name_on_card: type: string example: 'John Michael Doe' card_color: type: string example: green description: '' enum: [] individual_reference_number: type: string example: '1' expiration_date: type: string example: 2025-12 rapidid_verification_requested_at: type: string example: null description: '' enum: [] rapidid_verified_at: type: string example: null description: '' enum: [] rapidid_failed_at: type: string example: null description: '' enum: [] 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' nullable: false name_on_card: type: string description: 'Name as shown on Medicare card' example: 'John Michael Doe' nullable: false card_color: type: string description: 'Medicare card color (green, blue, or yellow)' example: green nullable: false individual_reference_number: type: string description: 'Individual reference number (1 digit)' example: '1' nullable: false expiration_date: type: string description: 'Expiration date in YYYY-MM format' example: 2025-12 nullable: false 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 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' 404: description: 'Medicare card not found' content: application/json: schema: type: object example: error: 'Medicare card not found for this user.' properties: error: type: string example: 'Medicare card not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user Medicare card' operationId: deleteUserMedicareCard description: 'Deletes the Medicare card record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Medicare card deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Medicare card not found' content: application/json: schema: type: object example: error: 'Medicare card not found for this user.' properties: error: type: string example: 'Medicare card not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/driver-license': post: summary: 'Create or update user driver license' operationId: createOrUpdateUserDriverLicense description: 'Creates a new driver license record for the user or updates an existing one. Only one driver license per user is allowed.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Driver license created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 state_issued: NSW license_number: '12345678' card_number: '1234567890' expiration_date: '2030-01-15' first_name: John last_name: Doe middle_name: Michael date_of_birth: '1990-01-15' rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] state_issued: type: string example: NSW description: '' enum: [] license_number: type: string example: '12345678' description: '' enum: [] card_number: type: string example: '1234567890' expiration_date: type: string example: '2030-01-15' first_name: type: string example: John last_name: type: string example: Doe middle_name: type: string example: Michael date_of_birth: type: string example: '1990-01-15' rapidid_verification_requested_at: type: string example: null description: '' enum: [] rapidid_verified_at: type: string example: null description: '' enum: [] rapidid_failed_at: type: string example: null description: '' enum: [] 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 nullable: false license_number: type: string description: 'Driver license number' example: '12345678' nullable: false card_number: type: string description: 'Driver license card number' example: '1234567890' nullable: false expiration_date: type: string description: 'Expiration date in YYYY-MM-DD format' example: '2030-01-15' nullable: false first_name: type: string description: 'First name as shown on license' example: John nullable: false last_name: type: string description: 'Last name as shown on license' example: Doe nullable: false middle_name: type: string description: 'Middle name as shown on license' example: Michael nullable: false date_of_birth: type: string description: 'Date of birth in YYYY-MM-DD format' example: '1990-01-15' nullable: false 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 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' 404: description: 'Driver license not found' content: application/json: schema: type: object example: error: 'Driver license not found for this user.' properties: error: type: string example: 'Driver license not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user driver license' operationId: deleteUserDriverLicense description: 'Deletes the driver license record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Driver license deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Driver license not found' content: application/json: schema: type: object example: error: 'Driver license not found for this user.' properties: error: type: string example: 'Driver license not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/immigration-card': post: summary: 'Create or update user immigration card' operationId: createOrUpdateUserImmigrationCard description: 'Creates a new immigration card record for the user or updates an existing one. Only one immigration card per user is allowed.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Immigration card created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 given_name: John family_name: Doe card_number: IMM123456 expiration_date: '2030-01-15' card_type: ams vevo_check_given_name: John vevo_check_family_name: Doe vevo_check_passport_number: N1234567 vevo_check_country_of_issue: Australia rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] given_name: type: string example: John family_name: type: string example: Doe card_number: type: string example: IMM123456 description: '' enum: [] expiration_date: type: string example: '2030-01-15' card_type: type: string example: ams description: '' enum: [] vevo_check_given_name: type: string example: John vevo_check_family_name: type: string example: Doe vevo_check_passport_number: type: string example: N1234567 vevo_check_country_of_issue: type: string example: Australia rapidid_verification_requested_at: type: string example: null description: '' enum: [] rapidid_verified_at: type: string example: null description: '' enum: [] rapidid_failed_at: type: string example: null description: '' enum: [] 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 nullable: false family_name: type: string description: 'Family name as shown on the card' example: Doe nullable: false card_number: type: string description: 'Immigration card number' example: IMM123456 nullable: false expiration_date: type: string description: 'Card expiration date (YYYY-MM-DD)' example: '2030-01-15' nullable: false card_type: type: string description: 'Type of immigration card (ams, eis, pre, rdi)' example: ams nullable: false vevo_check_given_name: type: string description: 'Given name for VEVO check' example: John nullable: false vevo_check_family_name: type: string description: 'Family name for VEVO check' example: Doe nullable: false vevo_check_passport_number: type: string description: 'Passport number for VEVO check' example: N1234567 nullable: false vevo_check_country_of_issue: type: string description: 'Country of passport issue for VEVO check' example: Australia nullable: false required: - given_name - family_name - card_number - expiration_date - card_type - vevo_check_given_name - vevo_check_family_name - vevo_check_passport_number - vevo_check_country_of_issue 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 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' 404: description: 'Immigration card not found' content: application/json: schema: type: object example: error: 'Immigration card not found for this user.' properties: error: type: string example: 'Immigration card not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user immigration card' operationId: deleteUserImmigrationCard description: 'Deletes the immigration card record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Immigration card deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Immigration card not found' content: application/json: schema: type: object example: error: 'Immigration card not found for this user.' properties: error: type: string example: 'Immigration card not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/centrelink-card': post: summary: 'Create or update user Centrelink card' operationId: createOrUpdateUserCentrelinkCard description: 'Creates a new Centrelink card record for the user or updates an existing one. Only one Centrelink card per user is allowed.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'Centrelink card created/updated successfully' content: application/json: schema: type: object example: data: id: 9d2e5c8a-1234-5678-9abc-def012345678 crn: 123456789A name_on_card: 'John Doe' expiration_date: '2030-01-15' card_type: hcc rapidid_verification_requested_at: null rapidid_verified_at: null rapidid_failed_at: null created_at: '2024-01-15T10:30:00Z' updated_at: '2024-01-15T10:30:00Z' properties: data: type: object properties: id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] crn: type: string example: 123456789A description: '' enum: [] name_on_card: type: string example: 'John Doe' expiration_date: type: string example: '2030-01-15' card_type: type: string example: hcc description: '' enum: [] rapidid_verification_requested_at: type: string example: null description: '' enum: [] rapidid_verified_at: type: string example: null description: '' enum: [] rapidid_failed_at: type: string example: null description: '' enum: [] 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 nullable: false name_on_card: type: string description: 'Name as shown on the card' example: 'John Doe' nullable: false expiration_date: type: string description: 'Card expiration date (YYYY-MM-DD)' example: '2030-01-15' nullable: false card_type: type: string description: 'Type of Centrelink card (hcc, pcc, shc)' example: hcc nullable: false 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 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' 404: description: 'Centrelink card not found' content: application/json: schema: type: object example: error: 'Centrelink card not found for this user.' properties: error: type: string example: 'Centrelink card not found for this user.' tags: - 'User Identification Management' delete: summary: 'Delete user Centrelink card' operationId: deleteUserCentrelinkCard description: 'Deletes the Centrelink card record for the specified user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 204: description: 'Centrelink card deleted successfully' content: application/json: schema: type: array items: type: object example: [] 404: description: 'Centrelink card not found' content: application/json: schema: type: object example: error: 'Centrelink card not found for this user.' properties: error: type: string example: 'Centrelink card not found for this user.' tags: - 'User Identification Management' parameters: - in: path name: user_id description: 'The user UUID (36-character internal identifier)' example: 9d2e5c8a-1234-5678-9abc-def012345678 required: true schema: type: string '/api/v1/users/{user_id}/payto-agreement': get: summary: 'Get PayTo agreement status' operationId: getPayToAgreementStatus description: 'Returns the current PayTo agreement status and details for a user.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: '' content: application/json: schema: oneOf: - description: 'PayTo agreement found' type: object example: has_agreement: true agreement_id: PA-123456 maximum_amount: 10000 status: ACTIVE properties: has_agreement: type: boolean example: true description: '' enum: [] agreement_id: type: string example: PA-123456 description: '' enum: [] maximum_amount: type: integer example: 10000 description: '' enum: [] status: type: string example: ACTIVE description: '' enum: [] required: - has_agreement - agreement_id - maximum_amount - status - description: 'No PayTo agreement' type: object example: has_agreement: false agreement_id: null maximum_amount: null status: null properties: has_agreement: type: boolean example: false description: '' enum: [] agreement_id: type: string example: null description: '' enum: [] maximum_amount: type: string example: null description: '' enum: [] status: type: string example: null description: '' enum: [] required: - has_agreement - agreement_id - maximum_amount - status tags: - 'User PayTo Agreement Management' post: summary: 'Create PayTo agreement' operationId: createPayToAgreement description: 'Creates a new PayTo agreement for the user. The user must authorize the agreement in their banking app.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 201: description: 'PayTo agreement created' content: application/json: schema: type: object example: agreement_id: PA-123456 status: CREATED message: 'PayTo agreement created. User must authorize in their banking app.' properties: agreement_id: type: string example: PA-123456 description: '' enum: [] status: type: string example: CREATED description: '' enum: [] message: type: string example: 'PayTo agreement created. User must authorize in their banking app.' description: '' enum: [] 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 nullable: false 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 nullable: false pay_id_type: type: string description: 'The PayID type: PHONE, EMAIL, ABN, or ORG' example: EMAIL nullable: false account_name: type: string description: 'Bank account holder name (required if using bank account)' example: 'John Doe' nullable: false account_number: type: string description: 'Bank account number (required if using bank account)' example: '12345678' nullable: false bsb: type: string description: 'Bank BSB number (required if using bank account)' example: '123456' nullable: false 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.funded - transaction.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.funded - transaction.status_changed is_active: true last_triggered_at: '2024-01-15T10:30:00Z' failure_count: 0 created_at: '2024-01-01T00:00:00Z' description: '' enum: [] 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.funded - transaction.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.funded (when a transaction is funded), transaction.status_changed (when transaction status changes), transaction.completed (when a transaction is completed/settled).' 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.funded properties: message: type: string example: 'Webhook registered successfully.' description: '' enum: [] id: type: string example: 9d2e5c8a-1234-5678-9abc-def012345678 description: '' enum: [] url: type: string example: 'https://partner.com/webhooks/goescrow' description: '' enum: [] secret: type: string example: whsec_abc123xyz789... description: '' enum: [] events: type: array example: - transaction.created - transaction.funded description: '' enum: [] 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' nullable: false events: type: array description: 'Array of events to subscribe to. Available events: transaction.created, transaction.funded, transaction.status_changed, transaction.completed. Omit or pass null to receive all events.' example: - transaction.created - transaction.funded items: type: string required: - url '/api/v1/webhooks/{id}': delete: summary: 'Delete webhook' operationId: deleteWebhook description: 'Unregisters a webhook.' parameters: - in: header name: X-API-Key description: '' example: '{YOUR_AUTH_KEY}' schema: type: string responses: 200: description: 'Webhook deleted' content: application/json: schema: type: object example: message: 'Webhook deleted successfully.' properties: message: type: string example: 'Webhook deleted successfully.' description: '' enum: [] required: - message 404: description: 'Webhook not found' content: application/json: schema: type: object example: message: 'Webhook not found.' properties: message: type: string example: 'Webhook not found.' description: '' enum: [] 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