{"openapi":"3.0.3","info":{"title":"Finmo Partner API Sandbox","version":"2026-10-sandbox","description":"Mirrors api.finmo.net. Items marked x-status: proposed do not exist in Finmo today and are working names for discussion."},"servers":[{"url":"https://sandbox.finmotreasury.net"}],"security":[{"basic":[]}],"components":{"securitySchemes":{"basic":{"type":"http","scheme":"basic","description":"base64(access_key:secret_key)"}},"schemas":{"ErrorEnvelope":{"type":"object","description":"Every error. Branch on error.name; full catalogue with retry rules at /docs#errors.","properties":{"request_id":{"type":"string"},"request_time":{"type":"string","format":"date-time"},"success":{"type":"boolean","enum":[false]},"status_code":{"type":"integer"},"status_text":{"type":"string"},"error":{"type":"object","properties":{"code":{"type":"integer"},"name":{"type":"string","enum":["INVALID_FIELD_OR_VALUE_ERROR","FAILED_TO_VALIDATE_BENEFICIARY_DETAILS_ERROR","INSUFFICIENT_AMOUNT_IN_WALLET","CURRENCY_NOT_ENABLED_FOR_ORG","FX_RATE_EXPIRED_ERROR","FX_RATE_MISMATCH_ERROR","FX_RATE_ALREADY_USED_ERROR","INVALID_REQUEST_HEADER_ERROR","AUTH_MIDDLEWARE_ERROR","<OBJECT>_NOT_FOUND_ERROR","ROUTE_NOT_FOUND_ERROR","UNSUPPORTED_CURRENCY_PAIR_ERROR","PAYOUT_STATUS_MISMATCH_ERROR","VIRTUAL_ACCOUNT_NOT_ACTIVE_ERROR","IDEMPOTENCY_KEY_CONFLICT_ERROR","UPLOAD_URL_EXPIRED_ERROR","INTERNAL_SERVER_ERROR"]},"message":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}}}}}}},"paths":{"/v1/partner/invite-organization":{"post":{"tags":["Onboarding"],"summary":"Create organization","description":"Creates a merchant organization under your partner account and its admin user. KYB status starts at NOT_STARTED. Send KYB with PATCH /v1/partner/kyb/save.\n\n- In production, Finmo emails this user a link to set a Finmo dashboard password. The sandbox has no merchant dashboard and sends no email.\n- The email you pass becomes the org's admin user. Use your client's own address, not yours.","x-status":"live","parameters":[{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"first_name":{"type":"string","description":"First name of the organization's primary user"},"last_name":{"type":"string","description":"Last name of the organization's primary user"},"org_name":{"type":"string","description":"Business name of the organization"},"org_country":{"type":"string","description":"Country of incorporation, ISO 3166-1 alpha-2"},"email":{"type":"string","description":"Email of the organization's user. It becomes the org's admin user"}},"required":["first_name","last_name","org_name","org_country","email"]},"example":{"first_name":"Test","last_name":"Merchant","org_name":"Test Org Pte Ltd","org_country":"SG","email":"merchant@example.com"}}}}}},"/v1/partner/organization":{"get":{"tags":["Onboarding"],"summary":"List organizations","description":"Your merchant organizations with their KYB status, newest first. Paged: data[] plus _metadata.","x-status":"live","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/partner/organization/{org_id}":{"get":{"tags":["Onboarding"],"summary":"Get organization","description":"The organization's KYB profile, business owners and KYB status.","x-status":"live","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/partner/kyb/save/{org_id}":{"patch":{"tags":["Onboarding"],"summary":"Save and submit KYB","description":"Creates or updates the organization's KYB application. Send submit: true with all required fields to submit it for review.\n\n- Sandbox only: submit: true approves the organization at once, opens its wallet and accounts, and sends VIRTUAL_ACCOUNT_CREATED webhooks. In production, Finmo compliance reviews the application before approving it.","x-status":"live","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"submit":{"type":"boolean","description":"true submits the application"},"legal_name":{"type":"string","description":""},"company_registration_number":{"type":"string","description":""},"incorporation_date":{"type":"string","description":""},"address_line1":{"type":"string","description":""},"business_owner[]":{"type":"array","description":"Include business_owner_id to update an owner already saved"}},"required":[]},"example":{"submit":true,"name":"Acme Pte Ltd","legal_name":"Acme Pte Ltd","business_type":1,"company_registration_number":"202012345A","incorporation_date":"2020-01-15","address_line1":"1 Raffles Place","address_city":"Singapore","address_zip_code":"048616","company_registration_document_id":"{{org_document_id}}","business_owner":[{"business_owner_type":"1","first_name":"Jane","last_name":"Doe","dob":"1985-06-15","nationality":"SG","shareholder_percentage":"100","identification_type":"PASSPORT","identification_value":"E1234567X","identification_document_id":"{{org_document_id}}"}]}}}}}},"/v1/partner/organization-document/{org_id}":{"post":{"tags":["Onboarding"],"summary":"Request a document upload URL","description":"Two-step upload: this returns org_document_id + upload_url (valid 30 seconds); PUT the file bytes to upload_url.","x-status":"live","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"file_type":{"type":"string","description":"image/png, image/jpeg, image/jpg, application/pdf"},"doc_type":{"type":"string","description":"KYB_DOCUMENT or CUSTOMER_DOCUMENT"}},"required":["file_type","doc_type"]},"example":{"file_type":"application/pdf","doc_type":"KYB_DOCUMENT"}}}}}},"/v1/partner/organization-setting/{org_id}":{"put":{"tags":["Webhooks"],"summary":"Set webhook URL","description":"One webhook URL per organization. Every event carries org_id, so all organizations can point to the same listener. Deliveries carry your account's security token in the x-security-token header.","x-status":"live","parameters":[{"name":"org_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string","description":"webhook_url"},"value":{"type":"string","description":""}},"required":["key","value"]},"example":{"key":"webhook_url","value":"https://listener.example.com/finmo"}}}}}},"/v1/wallet":{"get":{"tags":["Balances"],"summary":"List wallets","description":"Wallet ids for the organization. One multi-currency wallet (category GCA) per organization. Header x-on-behalf-of-org-id: <organization org_id>.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/wallet/{wallet_id}":{"get":{"tags":["Balances"],"summary":"Get wallet balances","description":"wallet_account[] carries actual_balance and available_balance per currency. Available drops when a payout is created (funds reserved); actual drops when it completes.","x-status":"live","parameters":[{"name":"wallet_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/balance":{"get":{"tags":["Balances"],"summary":"Balances by currency","description":"Currency map of actual and available balance for the organization.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/virtual-account":{"get":{"tags":["Funding"],"summary":"List virtual accounts","description":"The organization's collection accounts. The sandbox opens USD, EUR and GBP (SWIFT), SGD (SWIFT and FAST) and AUD accounts on approval, with the bank details shape production returns.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/virtual-account/{va_id}":{"get":{"tags":["Funding"],"summary":"Get account details","description":"One virtual account.","x-status":"live","parameters":[{"name":"va_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/virtual-account/simulate-payin":{"patch":{"tags":["Sandbox tools"],"summary":"Simulate funds arriving","description":"Same endpoint as Finmo's merchant sandbox. Credits a virtual account as if funds arrived: returns a GCA_TOPUP payin (fee 0.33 in the account currency) and emits the GCA_TOPUP webhook.","x-status":"sandbox-only","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"406":{"description":"VIRTUAL_ACCOUNT_NOT_ACTIVE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"virtual_account_id":{"type":"string","description":""},"amount":{"type":"number","description":""},"currency":{"type":"string","description":""}},"required":["virtual_account_id","amount","currency"]},"example":{"virtual_account_id":"{{virtual_account_id}}","amount":25000,"currency":"USD"}}}}}},"/v1/transaction":{"get":{"tags":["Balances"],"summary":"Transactions (reconciliation)","description":"One record per money movement with fees, net amount and settlement flags.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"event_type","in":"query","required":false,"schema":{"type":"string"},"description":"PAYOUT, VIRTUAL_ACCOUNT"},{"name":"currency","in":"query","required":false,"schema":{"type":"string"}},{"name":"start_time","in":"query","required":false,"schema":{"type":"string"}},{"name":"end_time","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/transaction/{txn_id}":{"get":{"tags":["Balances"],"summary":"Get transaction","description":"One transaction.","x-status":"live","parameters":[{"name":"txn_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payout-method/all":{"get":{"tags":["FX & payouts"],"summary":"Payout methods for a corridor","description":"Rails available to a destination. beneficiary_country and beneficiary_currency are required.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"beneficiary_country","in":"query","required":true,"schema":{"type":"string"}},{"name":"beneficiary_currency","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payout-method/param/{name}":{"get":{"tags":["FX & payouts"],"summary":"Fields a method needs","description":"payout_beneficiary_param lists base_param (bank fields), company and individual fields with regex. Build the 'add supplier' form from this.","x-status":"live","parameters":[{"name":"name","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payout-beneficiary":{"post":{"tags":["FX & payouts"],"summary":"Create beneficiary (supplier)","description":"Saves an overseas supplier on the organization. Common suppliers are created once per organization, ideally at onboarding.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | FAILED_TO_VALIDATE_BENEFICIARY_DETAILS_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":{"type":"company","beneficiary_name":"Ubud Jungle Retreat","currency":"IDR","bank_country":"ID","account_number":"1234567890","bic_swift":"CENAIDJA","company":{"name":"Ubud Jungle Retreat","registration_number":"REG123456","address_line1":"1 Jl Raya Ubud","address_city":"Gianyar","address_country":"ID"}}}}}},"get":{"tags":["FX & payouts"],"summary":"List beneficiaries","description":"Suppliers saved on the organization.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payout-beneficiary/{ben_id}":{"get":{"tags":["FX & payouts"],"summary":"Get beneficiary","description":"One supplier.","x-status":"live","parameters":[{"name":"ben_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["FX & payouts"],"summary":"Update beneficiary","description":"Changes a saved supplier's details. The payout_beneficiary_id stays the same, so nothing that references it changes. Validate the new details first with POST /payout-beneficiary/validate.","x-status":"live","parameters":[{"name":"ben_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":{"beneficiary_name":"Ubud Jungle Retreat","account_number":"9876543210","company":{"name":"Ubud Jungle Retreat","address_line1":"1 Jl Raya Ubud","address_city":"Gianyar","address_country":"ID"}}}}}}},"/v1/payout-beneficiary/validate":{"post":{"tags":["FX & payouts"],"summary":"Validate bank details","description":"Checks fields against the method's rules (IBAN mod-97, ABA checksum, SWIFT format) before money moves.\n\n- Try payout_method_name de_bank_sct_eur with iban DE74123456784000000030 (two digits swapped) to see a 400 FAILED_TO_VALIDATE_BENEFICIARY_DETAILS_ERROR","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | FAILED_TO_VALIDATE_BENEFICIARY_DETAILS_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{},"required":[]},"example":{"payout_method_name":"gb_bank_fps_gbp","is_beneficiary_name_match_enabled":true,"payout_beneficiary":{"type":"company","beneficiary_name":"Thames Corporate Travel","sort_code":"601613","account_number":"31926819","company":{"name":"Thames Corporate Travel","address_line1":"1 King St","address_city":"London","address_country":"GB","address_zip_code":"EC2V 8AU"}}}}}}}},"/v1/fx-rate":{"post":{"tags":["FX & payouts"],"summary":"Live FX quote","description":"Returns fx_rate_id held for about 20 seconds. The rate already includes the organization's pricing.\n\n- Sandbox mirrors live limits: IDR, THB, PHP, MYR and INR can be bought but not sold (406 104607).","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | CURRENCY_NOT_ENABLED_FOR_ORG | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"406":{"description":"UNSUPPORTED_CURRENCY_PAIR_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_currency":{"type":"string","description":""},"target_currency":{"type":"string","description":""},"source_amount":{"type":"number","description":"Send exactly one of source_amount / target_amount"},"target_amount":{"type":"number","description":""}},"required":["source_currency","target_currency"]},"example":{"source_currency":"USD","target_currency":"EUR","source_amount":1000}}}}}},"/v1/fx-rate/{fx_id}":{"get":{"tags":["FX & payouts"],"summary":"Get quote","description":"One quote.","x-status":"live","parameters":[{"name":"fx_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payout":{"post":{"tags":["FX & payouts"],"summary":"Create payout","description":"Pays a supplier. Attach fx_rate_id for a cross-currency payout; the rate locks. Status goes CREATED, PENDING, then COMPLETED, FAILED or RETURNED, each with a webhook.\n\n- Send X-Idempotency-Key (UUID v4). A retry with the same key returns the original payout and an x-cached-request-id header.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | FAILED_TO_VALIDATE_BENEFICIARY_DETAILS_ERROR | INSUFFICIENT_AMOUNT_IN_WALLET | CURRENCY_NOT_ENABLED_FOR_ORG | FX_RATE_EXPIRED_ERROR | FX_RATE_MISMATCH_ERROR | FX_RATE_ALREADY_USED_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"406":{"description":"UNSUPPORTED_CURRENCY_PAIR_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payout_method_name":{"type":"string","description":""},"sender_currency":{"type":"string","description":""},"beneficiary_currency":{"type":"string","description":""},"beneficiary_country":{"type":"string","description":""},"sender_amount | beneficiary_amount":{"type":"number","description":""},"fx_rate_id":{"type":"string","description":""},"debit_wallet_id":{"type":"string","description":""},"payout_beneficiary_id | payout_beneficiary_param":{"type":"string","description":""},"purpose_code":{"type":"string","description":"e.g. GOODS_AND_SERVICES"},"organization_reference_id":{"type":"string","description":""}},"required":["payout_method_name","sender_currency","beneficiary_currency","debit_wallet_id","purpose_code"]},"example":{"payout_method_name":"de_bank_sct_eur","sender_currency":"USD","beneficiary_currency":"EUR","beneficiary_country":"DE","beneficiary_amount":900,"fx_rate_id":"{{fx_rate_id}}","debit_wallet_id":"{{wallet_id}}","payout_beneficiary_id":"{{payout_beneficiary_id}}","purpose_code":"GOODS_AND_SERVICES","organization_reference_id":"INV-88213"}}}}},"get":{"tags":["FX & payouts"],"summary":"List payouts","description":"Filter by status, payout_method_name, organization_reference_id, start_time, end_time.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payout/{payout_id}":{"get":{"tags":["FX & payouts"],"summary":"Get payout","description":"Status and details.","x-status":"live","parameters":[{"name":"payout_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payout/{payout_id}/get-payout-pdf":{"get":{"tags":["FX & payouts"],"summary":"Payment confirmation","description":"download_url to a payment confirmation (sandbox serves an HTML memo).","x-status":"live","parameters":[{"name":"payout_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payout/simulate":{"patch":{"tags":["Sandbox tools"],"summary":"Simulate payout outcome","description":"Same endpoint as Finmo's sandbox. COMPLETED/FAILED need status PENDING; RETURNED needs COMPLETED (406 100006 otherwise).","x-status":"sandbox-only","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"406":{"description":"PAYOUT_STATUS_MISMATCH_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payout_id":{"type":"string","description":""},"status":{"type":"string","description":"COMPLETED | FAILED | RETURNED"}},"required":["payout_id","status"]},"example":{"payout_id":"{{payout_id}}","status":"FAILED"}}}}}},"/v1/fx-conversion":{"post":{"tags":["FX & payouts"],"summary":"Create FX conversion","description":"Converts between two currencies in the organization's wallet. Pass fx_rate_id to use a quote, or omit it for the live rate. Returns PENDING and holds the source amount.\n\n- Sandbox: the conversion stays PENDING until PATCH /fx-conversion/simulate, like Finmo's merchant sandbox. In production it completes on its own, usually within 2 minutes, and sends FX_CONVERSION_COMPLETED.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"source_currency":{"type":"string","description":""},"target_currency":{"type":"string","description":""},"source_amount | target_amount":{"type":"number","description":"Exactly one"},"fx_rate_id":{"type":"string","description":""},"organization_reference_id":{"type":"string","description":""}},"required":["source_currency","target_currency"]},"example":{"source_currency":"USD","target_currency":"EUR","source_amount":100,"fx_rate_id":"{{fx_rate_id}}"}}}}},"get":{"tags":["FX & payouts"],"summary":"List FX conversions","description":"Newest first.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/fx-conversion/{fx_conversion_id}":{"get":{"tags":["FX & payouts"],"summary":"Get FX conversion","description":"One conversion.","x-status":"live","parameters":[{"name":"fx_conversion_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/fx-conversion/simulate":{"patch":{"tags":["Sandbox tools"],"summary":"Complete an FX conversion","description":"Same endpoint as Finmo's merchant sandbox. Moves a PENDING conversion to COMPLETED: debits the source, credits the target and emits FX_CONVERSION_COMPLETED.","x-status":"sandbox-only","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"fx_conversion_id":{"type":"string","description":""},"status":{"type":"string","description":"COMPLETED (default)"}},"required":["fx_conversion_id"]},"example":{"fx_conversion_id":"{{fx_conversion_id}}","status":"COMPLETED"}}}}}},"/v1/customer":{"post":{"tags":["Customers"],"summary":"Create customer","description":"An individual or company customer of the organization. With only first_name + last_name (individual) or name (company) the customer is PENDING_INFO; with every mandatory field it is APPROVED.\n\n- Sandbox: a customer with every mandatory field is APPROVED at once. In production it goes UNDER_REVIEW first.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":"individual | company"},"account_usage_purpose":{"type":"string","description":""},"individual | company":{"type":"object","description":""},"organization_reference_id":{"type":"string","description":""},"metadata":{"type":"object","description":""}},"required":["type"]},"example":{"type":"individual","account_usage_purpose":"Receive payments from overseas clients","individual":{"first_name":"Jane","last_name":"Tan"}}}}}},"get":{"tags":["Customers"],"summary":"List customers","description":"Newest first.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"type","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/customer/{customer_id}":{"get":{"tags":["Customers"],"summary":"Get customer","description":"One customer.","x-status":"live","parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"patch":{"tags":["Customers"],"summary":"Update customer","description":"type and account_usage_purpose are required; other fields are merged.","x-status":"live","parameters":[{"name":"customer_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string","description":""},"account_usage_purpose":{"type":"string","description":""}},"required":["type","account_usage_purpose"]},"example":{"type":"individual","account_usage_purpose":"Receive payments from overseas clients","description":"Updated"}}}}}},"/v1/payin-method/all":{"get":{"tags":["Payins"],"summary":"Payin methods for a country","description":"Payin methods enabled for a country and currency. The sandbox offers au_bank_npp (PayID, AUD) and sg_bank_paynowqr_sgd (PayNow QR, SGD) for direct payins, as Finmo's merchant sandbox does.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"country","in":"query","required":true,"schema":{"type":"string"}},{"name":"currency","in":"query","required":true,"schema":{"type":"string"}},{"name":"is_va_allowed","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payin":{"post":{"tags":["Payins"],"summary":"Create payin","description":"A payment request your payer completes. Returns PENDING with pay_code (a PayID for au_bank_npp, a QR for sg_bank_paynowqr_sgd). Expires after 48 hours.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":""},"currency":{"type":"string","description":""},"payin_method_name":{"type":"string","description":""},"payin_method_param":{"type":"object","description":""},"redirect_url":{"type":"string","description":"Or advanced_redirect_url"},"customer_id":{"type":"string","description":""},"organization_reference_id":{"type":"string","description":""}},"required":["amount","currency","payin_method_name","redirect_url"]},"example":{"amount":100,"currency":"AUD","payin_method_name":"au_bank_npp","payin_method_param":{},"redirect_url":"https://example.com/return"}}}}},"get":{"tags":["Payins"],"summary":"List payins","description":"Includes virtual account top-ups (payin_type GCA_TOPUP).","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"customer_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"payin_method_name","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer"}},{"name":"page","in":"query","required":false,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payin/{payin_id}":{"get":{"tags":["Payins"],"summary":"Get payin","description":"One payin.","x-status":"live","parameters":[{"name":"payin_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payin/simulate":{"patch":{"tags":["Sandbox tools"],"summary":"Complete or cancel a payin","description":"Same endpoint as Finmo's merchant sandbox. COMPLETED credits the wallet less a 0.45 fee; CANCELLED needs a cancellable payin (PayNow QR payins are not). Only PENDING payins (406 100006 otherwise).","x-status":"sandbox-only","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"payin_id":{"type":"string","description":""},"status":{"type":"string","description":"COMPLETED | CANCELLED"},"amount":{"type":"number","description":"Partial payment"}},"required":["payin_id","status"]},"example":{"payin_id":"{{payin_id}}","status":"COMPLETED"}}}}}},"/v1/webhook-notification":{"get":{"tags":["Webhooks"],"summary":"List webhook deliveries","description":"Every notification with status and attempt count.","x-status":"live","parameters":[{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"event_type","in":"query","required":false,"schema":{"type":"string"}},{"name":"event_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"event_name","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhook-notification/{webhook_id}":{"get":{"tags":["Webhooks"],"summary":"Get webhook delivery","description":"One notification with its attempts.","x-status":"live","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhook-notification/{webhook_id}/retrigger":{"patch":{"tags":["Webhooks"],"summary":"Re-send a webhook","description":"Queues an immediate delivery attempt. Picks up the current webhook_url.","x-status":"live","parameters":[{"name":"webhook_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"x-on-behalf-of-org-id","in":"header","required":true,"schema":{"type":"string"},"description":"org_id of the organization you act for"},{"name":"X-Idempotency-Key","in":"header","required":false,"schema":{"type":"string","format":"uuid"},"description":"UUID v4. Retries with the same key replay the original response (x-cached-request-id)."}],"responses":{"200":{"description":"Finmo envelope { request_id, request_time, success, status_code, status_text, data }"},"400":{"description":"INVALID_FIELD_OR_VALUE_ERROR | INVALID_REQUEST_HEADER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"AUTH_MIDDLEWARE_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"<OBJECT>_NOT_FOUND_ERROR | ROUTE_NOT_FOUND_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"IDEMPOTENCY_KEY_CONFLICT_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"INTERNAL_SERVER_ERROR","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}