{"consumes":["application/json"],"definitions":{"FeeServiceUpdateOrgFeesBody":{"properties":{"railFees":{"items":{"$ref":"#/definitions/v1FeeRailFeeInput","type":"object"},"type":"array"},"schedules":{"items":{"$ref":"#/definitions/v1FeeScheduleInput","type":"object"},"type":"array"}},"type":"object"},"OrganizationServiceUpdateOrganizationBody":{"properties":{"business":{"$ref":"#/definitions/v1BusinessDetails"},"email":{"type":"string"},"externalId":{"type":"string"},"individual":{"$ref":"#/definitions/v1IndividualDetails"},"phone":{"type":"string"}},"type":"object"},"PaymentServiceCreateSavedWalletBody":{"properties":{"address":{"type":"string"},"label":{"type":"string"},"network":{"type":"string"},"token":{"type":"string"}},"type":"object"},"RecipientServiceCreateOrgRecipientBody":{"properties":{"accountNumber":{"type":"string"},"accountSubtype":{"description":"Account subtype for ACH recipients. Values: \"checking\", \"savings\".","type":"string"},"accountType":{"description":"Account/rail type. Values: \"ACH\", \"WIRE\", \"SWIFT\", \"WALLET\".","type":"string"},"address":{"$ref":"#/definitions/v1BankAddress"},"bankAddress":{"$ref":"#/definitions/v1BankAddress"},"bankName":{"type":"string"},"channel":{"description":"Recipient channel. Values: \"fiat\" or \"crypto\".","type":"string"},"companyName":{"type":"string"},"docCountryCode":{"description":"ISO 3166-1 alpha-2 country code that issued the identification document\r\nreferenced by doc_type / doc_number.","type":"string"},"docNumber":{"type":"string"},"docType":{"description":"Identification document type, e.g. \"passport\", \"driver_license\", \"national_id\".","type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"intermediaryRoutingNumber":{"description":"Intermediary bank routing number, used for SWIFT recipients that need to\r\nroute through a correspondent bank.","type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string"},"network":{"description":"Blockchain network for crypto recipients, e.g. \"tron\", \"polygon\", \"solana\".","type":"string"},"phone":{"type":"string"},"routingNumber":{"type":"string"},"swiftCode":{"type":"string"},"token":{"description":"Stablecoin token. Values: \"USDC\" or \"USDT\".","type":"string"},"type":{"description":"Recipient legal type. Values: \"individual\" or \"business\".","type":"string"},"walletAddress":{"type":"string"},"walletName":{"type":"string"}},"type":"object"},"protobufAny":{"additionalProperties":{},"properties":{"@type":{"type":"string"}},"type":"object"},"rpcStatus":{"properties":{"code":{"format":"int32","type":"integer"},"details":{"items":{"$ref":"#/definitions/protobufAny","type":"object"},"type":"array"},"message":{"type":"string"}},"type":"object"},"v1Address":{"properties":{"city":{"type":"string"},"country":{"title":"3-letter ISO 3166-1 alpha-3 country code (e.g. \"USA\", \"MEX\")","type":"string"},"state":{"type":"string"},"street":{"type":"string"},"street2":{"type":"string"},"zipCode":{"type":"string"}},"type":"object"},"v1ApiKeyMetadata":{"description":"ApiKeyMetadata represents an API key in list responses.\r\nThe plain-text key is never included - only identifying metadata.","properties":{"createdAt":{"format":"date-time","type":"string"},"createdBy":{"type":"string"},"expiresAt":{"format":"date-time","type":"string"},"id":{"type":"string"},"keyPrefix":{"description":"key_prefix is the first 8 characters of the hex portion (e.g. \"a3f1b8c2\").","type":"string"},"lastUsedAt":{"format":"date-time","type":"string"},"name":{"type":"string"},"status":{"description":"API key status. Values: \"active\" or \"revoked\".","type":"string"}},"type":"object"},"v1AssociatedPerson":{"properties":{"address":{"$ref":"#/definitions/v1Address"},"birthDate":{"title":"YYYY-MM-DD","type":"string"},"documentCountry":{"title":"3-letter ISO country code for the document","type":"string"},"documentNumber":{"title":"Document number for international associated persons (e.g. passport/ID number)","type":"string"},"email":{"type":"string"},"firstName":{"type":"string"},"hasControl":{"type":"boolean"},"hasOwnership":{"type":"boolean"},"identifyingInformation":{"items":{"$ref":"#/definitions/v1IdentifyingInformation","type":"object"},"type":"array"},"isSigner":{"type":"boolean"},"lastName":{"type":"string"},"nationality":{"title":"3-letter ISO country code","type":"string"},"ownershipPercentage":{"format":"double","type":"number"},"ssn":{"type":"string"},"title":{"type":"string"}},"type":"object"},"v1BankAddress":{"description":"BankAddress holds the structured address of a recipient's bank.\r\nRequired for WIRE and SWIFT account types.","properties":{"city":{"type":"string"},"country":{"description":"ISO 3166-1 alpha-2 country code (e.g. \"US\", \"GB\").","type":"string"},"postalCode":{"type":"string"},"state":{"type":"string"},"streetName":{"type":"string"}},"type":"object"},"v1BusinessDetails":{"properties":{"accountPurpose":{"type":"string"},"address":{"$ref":"#/definitions/v1Address"},"associatedPersons":{"items":{"$ref":"#/definitions/v1AssociatedPerson","type":"object"},"type":"array"},"businessDescription":{"type":"string"},"businessIndustry":{"items":{"type":"string"},"type":"array"},"businessLegalName":{"type":"string"},"businessType":{"type":"string"},"businessWebsite":{"type":"string"},"cnpj":{"type":"string"},"companyName":{"title":"Trade name shown to end users","type":"string"},"doingBusinessAs":{"type":"string"},"ein":{"type":"string"},"expectedMonthlyPayments":{"type":"string"},"formationCountry":{"title":"3-letter ISO country code","type":"string"},"formationDate":{"title":"YYYY-MM-DD","type":"string"},"formationState":{"type":"string"},"hasDeniedBankAccount":{"type":"boolean"},"hasMaterialIntermediaryOwnership":{"type":"boolean"},"hasUsBankAccount":{"title":"Additional compliance info","type":"boolean"},"identifyingInformation":{"items":{"$ref":"#/definitions/v1IdentifyingInformation","type":"object"},"title":"Business compliance documents (file_proof_of_address, file_business_formation, file_source_of_wealth)","type":"array"},"internationalEntityType":{"title":"For non-US businesses","type":"string"},"pepStatus":{"type":"boolean"},"representativeBirthDate":{"title":"YYYY-MM-DD","type":"string"},"representativeFirstName":{"type":"string"},"representativeLastName":{"type":"string"},"representativeSsn":{"type":"string"},"representativeTitle":{"type":"string"},"rfc":{"type":"string"},"sourceOfFunds":{"type":"string"}},"type":"object"},"v1CreateApiKeyRequest":{"properties":{"expiresAt":{"description":"expires_at is an optional expiration timestamp. Omit for a key that\r\nnever expires.","format":"date-time","type":"string"},"name":{"description":"name is a human-readable label for the key (e.g. \"CI/CD Pipeline\").","type":"string"}},"type":"object"},"v1CreateApiKeyResponse":{"properties":{"apiKey":{"description":"api_key contains the full plain-text key. This is the ONLY time it is\r\nreturned - store it securely.","type":"string"},"metadata":{"$ref":"#/definitions/v1ApiKeyMetadata","description":"metadata contains the key's non-secret attributes."}},"type":"object"},"v1CreateCryptoPayoutRequest":{"properties":{"amount":{"description":"Recipient fiat amount to send. The response returns the exact stablecoin\r\namount the sender must deposit.","format":"double","type":"number"},"currency":{"description":"ISO currency code for the recipient side. v1 crypto-to-fiat payouts use \"USD\".","type":"string"},"description":{"type":"string"},"invoiceNumber":{"type":"string"},"memo":{"type":"string"},"network":{"description":"Supported payout networks. Values: \"solana\", \"polygon\".","type":"string"},"organizationId":{"type":"string"},"recipientId":{"type":"string"},"supportingDocuments":{"description":"Supporting documents required for crypto-to-fiat payouts (minimum 1).\r\n`content` is base64-encoded bytes over the wire.","items":{"$ref":"#/definitions/v1SupportingDocument","type":"object"},"type":"array"},"token":{"description":"Stablecoin token. Values: \"USDC\" or \"USDT\".","type":"string"}},"type":"object"},"v1CreateCryptoPayoutResponse":{"properties":{"amountCrypto":{"description":"Amount the sender must deposit in stablecoin units.","format":"double","type":"number"},"createdAt":{"format":"date-time","type":"string"},"depositAddress":{"description":"Single-use deposit address — marked with \"SINGLE USE\" in the UI.","type":"string"},"depositLink":{"type":"string"},"expiresAt":{"description":"Deadline for the sender to deposit (24 h window).","format":"date-time","type":"string"},"fees":{"$ref":"#/definitions/v1FeeBreakdown"},"network":{"description":"Blockchain network used for the single-use deposit address.","type":"string"},"recipientGets":{"description":"Amount the recipient receives in USD.","format":"double","type":"number"},"reference":{"type":"string"},"status":{"description":"Initial status is usually \"awaiting_deposit\". Subsequent transaction\r\nstatuses include \"processing\", \"completed\", \"expired\".","type":"string"},"token":{"description":"Stablecoin token the sender must deposit. Values: \"USDC\" or \"USDT\".","type":"string"},"transactionId":{"type":"string"}},"type":"object"},"v1CreateFiatPayoutRequest":{"properties":{"amount":{"description":"Recipient amount to send. Minimum accepted by product flows is 1.00.","format":"double","type":"number"},"currency":{"description":"ISO currency code. v1 fiat payouts use \"USD\".","type":"string"},"description":{"type":"string"},"invoiceNumber":{"type":"string"},"memo":{"type":"string"},"organizationId":{"type":"string"},"paymentRail":{"description":"Fiat rail. Values: \"ACH\", \"WIRE\", \"SWIFT\". Defaults to the recipient's\r\naccount_type when omitted.","type":"string"},"recipientId":{"type":"string"},"supportingDocuments":{"description":"Optional compliance evidence (PDF, PNG or JPG, max 10 MB each).\n\nRequired header: Idempotency-Key. Use a unique UUID per payout attempt;\r\n replaying the same key prevents duplicate payouts.","items":{"$ref":"#/definitions/v1SupportingDocument","type":"object"},"type":"array"}},"type":"object"},"v1CreateFiatPayoutResponse":{"properties":{"amountDeducted":{"format":"double","type":"number"},"createdAt":{"format":"date-time","type":"string"},"fees":{"$ref":"#/definitions/v1FeeBreakdown"},"recipientGets":{"format":"double","type":"number"},"reference":{"type":"string"},"status":{"description":"Initial transaction status, typically \"pending\" or \"processing\".","type":"string"},"transactionId":{"type":"string"}},"type":"object"},"v1CreateOrgRecipientResponse":{"properties":{"recipient":{"$ref":"#/definitions/v1Recipient"}},"type":"object"},"v1CreateOrganizationRequest":{"properties":{"business":{"$ref":"#/definitions/v1BusinessDetails"},"email":{"title":"Contact email - KYC/KYB link will be sent here","type":"string"},"externalId":{"title":"Optional external reconciliation ID (e.g. \"EXT-ACME-001\")","type":"string"},"feeBps":{"format":"double","title":"Basis points markup applied to all transactions (e.g. 20 = 0.20%)","type":"number"},"feeFixedUsd":{"format":"double","title":"Fixed per-transaction fee in USD","type":"number"},"individual":{"$ref":"#/definitions/v1IndividualDetails"},"phone":{"type":"string"},"redirectUri":{"title":"Redirect URI after verification_link flow completes","type":"string"},"type":{"description":"Organization type. Values: \"business\" or \"individual\".","type":"string"},"verificationMode":{"description":"Verification mode. Values: \"verification_link\" (default; sends a hosted\r\nKYC/KYB link) or \"automatic\" (all compliance data supplied in request).","type":"string"}},"required":["type","email"],"type":"object"},"v1CreateOrganizationResponse":{"properties":{"organization":{"$ref":"#/definitions/v1Organization"}},"type":"object"},"v1CreateSavedWalletResponse":{"properties":{"wallet":{"$ref":"#/definitions/v1SavedWallet"}},"type":"object"},"v1DeleteRecipientResponse":{"type":"object"},"v1DepositCoordinates":{"description":"DepositCoordinates is the banking detail set used by Top-Up USD and Get Crypto\r\nbank-transfer funding.","properties":{"accountNumber":{"type":"string"},"accountType":{"type":"string"},"bankAddress":{"type":"string"},"bankName":{"type":"string"},"beneficiaryName":{"type":"string"},"referenceMemo":{"type":"string"},"routingNumber":{"type":"string"},"swiftBic":{"type":"string"}},"type":"object"},"v1DepositInfo":{"properties":{"accountNumber":{"type":"string"},"accountType":{"title":"e.g. \"Checking\"","type":"string"},"bankAddress":{"type":"string"},"bankName":{"type":"string"},"beneficiaryName":{"type":"string"},"referenceMemo":{"title":"Unique memo for deposit reconciliation (e.g. \"HERCLE-USD-OPS-001\")","type":"string"},"routingNumber":{"type":"string"},"swiftBic":{"type":"string"}},"type":"object"},"v1Document":{"properties":{"file":{"title":"Base64 data URI (max 10 MB)","type":"string"},"type":{"title":"front, back, selfie, file_proof_of_address, file_source_of_wealth, file_business_formation","type":"string"}},"type":"object"},"v1DownloadBankLetterResponse":{"properties":{"contentType":{"description":"Always \"application/pdf\".","type":"string"},"fileName":{"description":"Suggested filename (e.g. \"bank-letter-\u003cvirtual_account_id\u003e.pdf\").","type":"string"},"pdfData":{"description":"Raw PDF bytes - base64-encoded by gRPC-Gateway in JSON responses.","format":"byte","type":"string"}},"type":"object"},"v1DownloadTransactionReceiptResponse":{"properties":{"contentType":{"description":"Always \"application/pdf\".","type":"string"},"fileName":{"description":"Suggested filename (e.g. \"receipt-PAY-2026-000042.pdf\").","type":"string"},"pdfData":{"description":"Raw PDF bytes — base64-encoded by gRPC-Gateway in JSON responses.","format":"byte","type":"string"}},"type":"object"},"v1EffectiveLayer":{"description":"EffectiveLayer is the resolved per-layer view returned by GetEffectiveFees.\r\nPercentages collapse to the layer's currently-cached tier; rail fees are\r\nreturned in full because they are not tiered.","properties":{"percentages":{"additionalProperties":{"format":"double","type":"number"},"description":"fee_type -\u003e percent (e.g. \"fx\" -\u003e 0.06).","type":"object"},"railFees":{"additionalProperties":{"format":"double","type":"number"},"description":"rail -\u003e USD amount.","type":"object"},"railPercentages":{"additionalProperties":{"format":"double","type":"number"},"description":"rail -\u003e percent units (e.g. \"TRON\" -\u003e 0.5). Empty/zero for fiat rails.","type":"object"},"tier":{"description":"Resolved tier for this layer (\"t1\" | \"t2\" | \"t3\").","type":"string"}},"type":"object"},"v1ExportTransactionsCSVResponse":{"properties":{"csvData":{"description":"Raw CSV bytes — base64-encoded by gRPC-Gateway in JSON responses.","format":"byte","type":"string"},"fileName":{"description":"Suggested filename (e.g. \"transactions-2026-01-15.csv\").","type":"string"},"rowCount":{"format":"int32","type":"integer"}},"type":"object"},"v1ExportTransactionsPDFRequest":{"properties":{"fromDate":{"format":"date-time","type":"string"},"organizationId":{"type":"string"},"status":{"description":"Transaction status filter. See ListTransactionsRequest.status for values.","type":"string"},"toDate":{"format":"date-time","type":"string"},"type":{"description":"Transaction type filter. See ListTransactionsRequest.type for values.","type":"string"}},"type":"object"},"v1ExportTransactionsPDFResponse":{"properties":{"total":{"format":"int64","type":"string"},"transactions":{"description":"Transaction list for client-side jsPDF rendering.","items":{"$ref":"#/definitions/v1Transaction","type":"object"},"type":"array"}},"type":"object"},"v1FeeBreakdown":{"description":"FeeBreakdown is the two-layer fee result for a single transaction.\r\nProvider (Kira) fees are folded into platform at the API boundary so the\r\nclient only sees platform (Magma + Kira) and fintech (customer markup).","properties":{"currency":{"type":"string"},"fintech":{"$ref":"#/definitions/v1LayerBreakdown","description":"Fintech layer."},"platform":{"$ref":"#/definitions/v1LayerBreakdown","description":"Magma (platform) layer, inclusive of provider (Kira) costs."},"total":{"description":"platform.total + fintech.total.","format":"double","type":"number"}},"type":"object"},"v1FeeRailFee":{"description":"FeeRailFee mirrors a fee_rail_fees row. Amount in USD; percentage in\r\npercent units (0.5 = 0.5%). Crypto chain rails (TRON, POLYGON, ...) can\r\ncarry both components; fiat rails leave percentage at 0.","properties":{"amount":{"format":"double","type":"number"},"createdAt":{"format":"date-time","type":"string"},"fintechId":{"type":"string"},"id":{"type":"string"},"layer":{"description":"Fee layer. Values: \"platform\" (Magma/provider cost) or \"fintech\" (your markup).","type":"string"},"organizationId":{"type":"string"},"percentage":{"format":"double","type":"number"},"rail":{"description":"Rail identifier. Values include \"FEDNOW\", \"ACH_SAMEDAY\",\r\n\"ACH_STANDARD\", \"WIRE_DOMESTIC_US\", \"WIRE_SWIFT\", \"TRON\", \"POLYGON\", \"SOLANA\".","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"type":"object"},"v1FeeRailFeeInput":{"properties":{"amount":{"format":"double","type":"number"},"layer":{"description":"Fee layer. Values: \"platform\" or \"fintech\". Public callers normally write \"fintech\".","type":"string"},"percentage":{"description":"Percent units (0.5 = 0.5%). Optional; defaults to 0 for fiat rails.","format":"double","type":"number"},"rail":{"description":"Rail identifier. Values include \"FEDNOW\", \"ACH_SAMEDAY\",\r\n\"ACH_STANDARD\", \"WIRE_DOMESTIC_US\", \"WIRE_SWIFT\", \"TRON\", \"POLYGON\", \"SOLANA\".","type":"string"}},"type":"object"},"v1FeeSchedule":{"description":"FeeSchedule mirrors a fee_schedules row. Percentages are in percent units\r\n(0.06 = 0.06%).","properties":{"createdAt":{"format":"date-time","type":"string"},"feeType":{"description":"Fee type. Values: \"fx\" or \"in_out\".","type":"string"},"fintechId":{"type":"string"},"id":{"type":"string"},"layer":{"description":"Fee layer. Values: \"platform\" (Magma/provider cost) or \"fintech\" (your markup).","type":"string"},"organizationId":{"description":"Empty when this is a fintech-wide default (organization_id IS NULL in DB).","type":"string"},"percentage":{"format":"double","type":"number"},"tier":{"description":"Volume tier. Values: \"t1\", \"t2\", \"t3\".","type":"string"},"updatedAt":{"format":"date-time","type":"string"}},"type":"object"},"v1FeeScheduleInput":{"description":"FeeScheduleInput is the writable subset of FeeSchedule. fintech_id and\r\norganization_id come from the URL / auth context, not the body.","properties":{"feeType":{"description":"Fee type. Values: \"fx\" or \"in_out\".","type":"string"},"layer":{"description":"Fee layer. Values: \"platform\" or \"fintech\". Public callers normally write \"fintech\".","type":"string"},"percentage":{"format":"double","type":"number"},"tier":{"description":"Volume tier. Values: \"t1\", \"t2\", \"t3\".","type":"string"}},"type":"object"},"v1GetBalanceResponse":{"properties":{"available":{"description":"Funds currently spendable for outbound payouts.","format":"double","type":"number"},"currency":{"description":"ISO currency code, e.g. \"USD\".","type":"string"},"reserved":{"description":"Funds locked by in-flight transactions; released if the transaction fails\r\nor returns, and no longer available after settlement.","format":"double","type":"number"},"updatedAt":{"format":"date-time","type":"string"}},"type":"object"},"v1GetDepositInfoResponse":{"properties":{"depositInfo":{"$ref":"#/definitions/v1DepositInfo"}},"type":"object"},"v1GetEffectiveFeesResponse":{"properties":{"fintech":{"$ref":"#/definitions/v1EffectiveLayer"},"platform":{"$ref":"#/definitions/v1EffectiveLayer","description":"Magma (platform) layer, inclusive of provider (Kira) costs."}},"type":"object"},"v1GetFeesResponse":{"properties":{"effective":{"$ref":"#/definitions/v1EffectiveLayer","description":"Aggregated view: provider (Kira) + platform (Magma markup) summed. This\r\nis what the fintech pays on every transaction. Tier is the fintech's\r\nplatform-layer tier; percentages and rail fees are additive across layers."},"railFees":{"items":{"$ref":"#/definitions/v1FeeRailFee","type":"object"},"type":"array"},"schedules":{"items":{"$ref":"#/definitions/v1FeeSchedule","type":"object"},"type":"array"}},"type":"object"},"v1GetOrganizationResponse":{"properties":{"kpis":{"$ref":"#/definitions/v1OrgKPIs"},"organization":{"$ref":"#/definitions/v1Organization"}},"type":"object"},"v1GetRecipientResponse":{"properties":{"recipient":{"$ref":"#/definitions/v1Recipient"}},"type":"object"},"v1GetSavedWalletResponse":{"properties":{"wallet":{"$ref":"#/definitions/v1SavedWallet"}},"type":"object"},"v1GetSelfOrganizationResponse":{"properties":{"organization":{"$ref":"#/definitions/v1Organization"}},"type":"object"},"v1GetSupportedNetworksResponse":{"properties":{"networks":{"items":{"$ref":"#/definitions/v1NetworkInfo","type":"object"},"type":"array"}},"type":"object"},"v1GetTransactionResponse":{"properties":{"transaction":{"$ref":"#/definitions/v1Transaction"}},"type":"object"},"v1GetVirtualAccountResponse":{"properties":{"virtualAccount":{"$ref":"#/definitions/v1VirtualAccount"}},"type":"object"},"v1IdentifyingInformation":{"properties":{"documents":{"items":{"$ref":"#/definitions/v1Document","type":"object"},"type":"array"},"expiration":{"title":"YYYY-MM-DD","type":"string"},"issuingCountry":{"title":"3-letter ISO country code","type":"string"},"number":{"type":"string"},"type":{"title":"passport, national_id, drivers_license, ssn, ein, curp, rfc, cpf, cnpj","type":"string"}},"type":"object"},"v1IndividualDetails":{"properties":{"accountPurpose":{"type":"string"},"address":{"$ref":"#/definitions/v1Address"},"birthDate":{"title":"YYYY-MM-DD","type":"string"},"currentEmployer":{"type":"string"},"employmentStatus":{"type":"string"},"expectedMonthlyPayments":{"type":"string"},"firstName":{"type":"string"},"gender":{"type":"string"},"hasDeniedBankAccount":{"type":"boolean"},"hasUsBankAccount":{"title":"Additional compliance info for international accounts","type":"boolean"},"identifyingInformation":{"items":{"$ref":"#/definitions/v1IdentifyingInformation","type":"object"},"type":"array"},"immigrationStatus":{"type":"string"},"incomeSource":{"type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string"},"nationality":{"title":"3-letter ISO country code","type":"string"},"occupation":{"type":"string"},"pepStatus":{"type":"boolean"},"sourceOfFunds":{"type":"string"}},"type":"object"},"v1LayerBreakdown":{"description":"LayerBreakdown is the per-layer slice of FeeBreakdown. Percentage and Fixed\r\nare kept full precision; Total = Percentage + Fixed.","properties":{"fixed":{"description":"Rail-specific fixed component, 0 when no rail applies.","format":"double","type":"number"},"percentage":{"description":"amount * rate / 100, where rate is in percent units.","format":"double","type":"number"},"tier":{"description":"Resolved tier (\"t1\" | \"t2\" | \"t3\").","type":"string"},"total":{"format":"double","type":"number"}},"type":"object"},"v1ListApiKeysResponse":{"properties":{"apiKeys":{"items":{"$ref":"#/definitions/v1ApiKeyMetadata","type":"object"},"type":"array"}},"type":"object"},"v1ListOrgRecipientsResponse":{"properties":{"limit":{"format":"int32","type":"integer"},"page":{"format":"int32","type":"integer"},"recipients":{"items":{"$ref":"#/definitions/v1Recipient","type":"object"},"type":"array"},"total":{"format":"int64","type":"string"}},"type":"object"},"v1ListOrganizationsResponse":{"properties":{"limit":{"format":"int32","type":"integer"},"organizations":{"items":{"$ref":"#/definitions/v1Organization","type":"object"},"type":"array"},"page":{"format":"int32","type":"integer"},"total":{"format":"int64","type":"string"}},"type":"object"},"v1ListSavedWalletsResponse":{"properties":{"wallets":{"items":{"$ref":"#/definitions/v1SavedWallet","type":"object"},"type":"array"}},"type":"object"},"v1ListTransactionsResponse":{"properties":{"limit":{"format":"int32","type":"integer"},"page":{"format":"int32","type":"integer"},"total":{"format":"int64","type":"string"},"transactions":{"items":{"$ref":"#/definitions/v1Transaction","type":"object"},"type":"array"}},"type":"object"},"v1ListVirtualAccountsResponse":{"properties":{"virtualAccounts":{"items":{"$ref":"#/definitions/v1VirtualAccount","type":"object"},"type":"array"}},"type":"object"},"v1NetworkInfo":{"properties":{"availableForGetCrypto":{"description":"True for all 6 networks — usable in Get Crypto.","type":"boolean"},"availableForPayout":{"description":"True for Solana and Polygon — usable in Payout w/ Crypto.","type":"boolean"},"id":{"description":"Internal ID used in API calls. Common values: \"tron\", \"polygon\",\r\n\"solana\", \"ethereum\", \"arbitrum\", \"base\".","type":"string"},"name":{"description":"Human-readable name (e.g. \"Solana\", \"Polygon\", \"Tron\").","type":"string"},"tokens":{"description":"Supported stablecoin tokens on this network, e.g. \"USDC\" and/or \"USDT\".","items":{"type":"string"},"type":"array"}},"type":"object"},"v1OrgKPIs":{"properties":{"currency":{"type":"string"},"feesCollected":{"format":"double","type":"number"},"totalInflow":{"format":"double","type":"number"},"totalOutflow":{"format":"double","type":"number"},"totalTransactions":{"format":"int64","type":"string"}},"type":"object"},"v1Organization":{"properties":{"business":{"$ref":"#/definitions/v1BusinessDetails"},"createdAt":{"format":"date-time","type":"string"},"email":{"type":"string"},"externalId":{"type":"string"},"feeSummary":{"title":"Computed for list view: e.g. \"25 bps + $0.30 fixed\"","type":"string"},"fintechId":{"type":"string"},"id":{"type":"string"},"individual":{"$ref":"#/definitions/v1IndividualDetails"},"isSelf":{"description":"True for the single org that represents the fintech itself.","type":"boolean"},"kycLink":{"type":"string"},"name":{"type":"string"},"onboardingStatus":{"description":"Onboarding lifecycle status. Values: \"created\", \"verifying\", \"verified\",\r\n\"active\", \"rejected\", \"review\", \"suspended\".","type":"string"},"phone":{"type":"string"},"type":{"description":"Organization type. Values: \"own\" (the fintech itself), \"business\", \"individual\".","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"verificationMode":{"description":"Verification mode. Values: \"verification_link\" (hosted KYC/KYB link) or\r\n\"automatic\" (all compliance data supplied in the request).","type":"string"},"verifiedAt":{"format":"date-time","type":"string"},"volume":{"format":"double","title":"Aggregated transaction volume","type":"number"},"volumeCurrency":{"type":"string"}},"type":"object"},"v1PreviewPayoutRequest":{"properties":{"amount":{"description":"Recipient amount to preview. Minimum accepted by product flows is 1.00.","format":"double","type":"number"},"currency":{"description":"ISO currency code. v1 fiat payouts use \"USD\".","type":"string"},"network":{"description":"Crypto network for crypto-funded payouts, e.g. \"polygon\" or \"solana\".","type":"string"},"organizationId":{"type":"string"},"paymentRail":{"description":"Optional fiat rail. Values: \"ACH\", \"WIRE\", \"SWIFT\". Defaults to the\r\nrecipient's account_type when omitted.","type":"string"},"recipientId":{"type":"string"},"token":{"description":"Stablecoin token for crypto-funded payouts. Values: \"USDC\" or \"USDT\".","type":"string"}},"type":"object"},"v1PreviewPayoutResponse":{"properties":{"amount":{"format":"double","type":"number"},"currency":{"type":"string"},"exchangeRate":{"format":"double","type":"number"},"fees":{"$ref":"#/definitions/v1FeeBreakdown"},"recipientGets":{"format":"double","type":"number"}},"type":"object"},"v1Recipient":{"description":"Recipient is an organisation-scoped recipient, optionally linked to a template.","properties":{"accountNumber":{"type":"string"},"accountSubtype":{"description":"Account subtype for ACH recipients. Values: \"checking\", \"savings\".","type":"string"},"accountType":{"description":"Fiat bank account fields\r\nAccount/rail type. Values: \"ACH\", \"WIRE\", \"SWIFT\", \"WALLET\".","type":"string"},"address":{"$ref":"#/definitions/v1BankAddress","description":"Recipient's personal/business address (structured)."},"bankAddress":{"$ref":"#/definitions/v1BankAddress"},"bankName":{"type":"string"},"channel":{"description":"Recipient channel. Values: \"fiat\" or \"crypto\".","type":"string"},"companyName":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"docCountryCode":{"description":"ISO 3166-1 alpha-2 country code that issued the identification document\r\nreferenced by doc_type / doc_number.","type":"string"},"docNumber":{"type":"string"},"docType":{"description":"Identification document type, e.g. \"passport\", \"driver_license\", \"national_id\".","type":"string"},"email":{"type":"string"},"fintechId":{"type":"string"},"firstName":{"type":"string"},"id":{"type":"string"},"intermediaryRoutingNumber":{"description":"Intermediary bank routing number, used for SWIFT recipients that need to\r\nroute through a correspondent bank.","type":"string"},"lastName":{"type":"string"},"middleName":{"type":"string"},"network":{"description":"Blockchain network for crypto recipients, e.g. \"tron\", \"polygon\", \"solana\".","type":"string"},"organizationId":{"type":"string"},"phone":{"type":"string"},"routingNumber":{"type":"string"},"swiftCode":{"type":"string"},"templateId":{"description":"Empty when created directly without a template.","type":"string"},"token":{"description":"Stablecoin token. Values: \"USDC\" or \"USDT\".","type":"string"},"type":{"description":"Recipient legal type. Values: \"individual\" or \"business\".","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"walletAddress":{"type":"string"},"walletName":{"title":"Crypto wallet fields","type":"string"}},"type":"object"},"v1RevokeApiKeyResponse":{"properties":{"apiKey":{"$ref":"#/definitions/v1ApiKeyMetadata"}},"type":"object"},"v1SavedWallet":{"properties":{"address":{"type":"string"},"createdAt":{"format":"date-time","type":"string"},"fintechId":{"type":"string"},"id":{"type":"string"},"label":{"description":"Friendly label (e.g. \"Phantom Wallet\", \"Main Treasury\").","type":"string"},"network":{"type":"string"},"organizationId":{"type":"string"},"token":{"type":"string"},"updatedAt":{"format":"date-time","type":"string"},"virtualAccount":{"$ref":"#/definitions/v1SavedWalletVA","description":"Crypto virtual account linked to this wallet. Always populated for wallets\r\ncreated via CreateSavedWallet; may be nil only for legacy rows."}},"type":"object"},"v1SavedWalletVA":{"description":"SavedWalletVA is the crypto virtual account automatically provisioned with a\r\nsaved wallet. Populated for every wallet created through the on-ramp flow;\r\nnil for legacy rows imported before the link migration.","properties":{"currency":{"description":"Source fiat currency of the VA (e.g. \"USD\").","type":"string"},"depositCoordinates":{"$ref":"#/definitions/v1DepositCoordinates","description":"Banking coordinates the customer must use to fund this VA. Available only\r\nonce Kira has activated the account."},"id":{"description":"Magma virtual_account row id.","type":"string"},"kiraVaId":{"description":"Kira virtual account id (va_xxx).","type":"string"},"mode":{"description":"Always \"crypto\" for wallet-linked VAs.","type":"string"},"status":{"description":"VA lifecycle status: \"pending\", \"active\", or \"suspended\".","type":"string"}},"type":"object"},"v1SupportingDocument":{"description":"SupportingDocument attaches compliance evidence to a payout.","properties":{"content":{"description":"File content — base64-encoded JSON string over the wire.","format":"byte","type":"string"},"contentType":{"description":"MIME type. Values: \"application/pdf\", \"image/png\", \"image/jpeg\".","type":"string"},"description":{"type":"string"},"fileName":{"type":"string"},"type":{"description":"Document type. Values: \"invoice\" or \"other\".","type":"string"}},"type":"object"},"v1SwiftDepositInstructions":{"description":"SwiftDepositInstructions mirrors Kira's `swift_deposit_instructions` payload\r\nand describes how a sender should wire funds via the SWIFT network into a\r\nvirtual account. Two routing shapes share this message:\r\n  1. Intermediary-routed (Kira's swift_deposit_instructions): the wire goes\r\n     through a correspondent bank identified by intermediary_bank_*.\r\n  2. Direct (synthesized from source_deposit_instructions): the underlying\r\n     bank receives SWIFT directly and only beneficiary_bank_swift_code is\r\n     set; intermediary_bank_* fields are empty.","properties":{"beneficiaryAccountName":{"description":"Legal entity that owns the virtual account.","type":"string"},"beneficiaryAccountNumber":{"type":"string"},"beneficiaryAddress":{"type":"string"},"beneficiaryBankAddress":{"type":"string"},"beneficiaryBankName":{"description":"Bank that holds the virtual account (the beneficiary bank).","type":"string"},"beneficiaryBankRoutingNumber":{"type":"string"},"beneficiaryBankSwiftCode":{"description":"SWIFT/BIC of the beneficiary bank itself. Populated for direct-SWIFT VAs\r\nwhere no intermediary bank is needed; left empty when intermediary fields\r\nare set instead.","type":"string"},"currency":{"description":"ISO currency code (e.g. \"USD\").","type":"string"},"intermediaryBankAddress":{"type":"string"},"intermediaryBankName":{"description":"Correspondent bank the wire is routed through.","type":"string"},"intermediaryBankSwiftCode":{"type":"string"},"memo":{"description":"Memo the sender must include on the wire (typically forwards funds to the\r\nultimate beneficiary referenced by source_deposit_instructions).","type":"string"}},"type":"object"},"v1Transaction":{"description":"Transaction is the full transaction record returned by GetTransaction and\r\nthe list endpoints.  Optional fields are empty/zero when not applicable to\r\nthe transaction type.","properties":{"amount":{"format":"double","type":"number"},"createdAt":{"format":"date-time","type":"string"},"createdBy":{"description":"Operator ID who created the transaction (empty for webhook-sourced deposits).","type":"string"},"currency":{"type":"string"},"depositAddress":{"description":"Single-use deposit address for crypto-to-fiat payouts.","type":"string"},"description":{"type":"string"},"destinationLabel":{"description":"Destination display label.","type":"string"},"destinationType":{"description":"Destination type (e.g. \"recipient_bank\", \"crypto_wallet\").","type":"string"},"destinationWallet":{"description":"Destination wallet address for Get Crypto transactions.","type":"string"},"documents":{"description":"Attached supporting documents (crypto payouts only).","items":{"$ref":"#/definitions/v1TransactionDocument","type":"object"},"type":"array"},"expiresAt":{"description":"For crypto-to-fiat payouts: 24-hour deposit deadline.","format":"date-time","type":"string"},"feeAmount":{"format":"double","type":"number"},"feeCurrency":{"type":"string"},"fintechId":{"type":"string"},"id":{"type":"string"},"idempotencyKey":{"type":"string"},"invoiceNumber":{"type":"string"},"kiraDepositId":{"type":"string"},"kiraPayoutId":{"type":"string"},"memo":{"type":"string"},"network":{"description":"Blockchain network for crypto transactions. Common values: \"tron\",\r\n\"polygon\", \"solana\", \"ethereum\", \"arbitrum\", \"base\".","type":"string"},"organizationId":{"type":"string"},"organizationName":{"description":"Joined from the organizations table for display.","type":"string"},"originLabel":{"description":"Origin display label (e.g. \"USD Operations Account\").","type":"string"},"originType":{"description":"Origin type (e.g. \"fiat_account\", \"bank_external\").","type":"string"},"paymentRail":{"description":"\"ACH\" | \"WIRE\" | \"SWIFT\" — fiat payouts only.","type":"string"},"recipientId":{"type":"string"},"recipientName":{"type":"string"},"reference":{"description":"Human-readable reference with type prefix (e.g. PAY-2026-000001).","type":"string"},"settledAt":{"format":"date-time","type":"string"},"status":{"description":"Transaction status. Values: \"created\", \"pending\", \"processing\",\r\n\"completed\", \"failed\", \"action_required\", \"under_review\", \"returned\",\r\n\"expired\", \"canceled\".","type":"string"},"token":{"description":"Stablecoin token. Values: \"USDC\" or \"USDT\".","type":"string"},"txHash":{"type":"string"},"type":{"description":"Transaction type. Values: \"deposit_fiat\", \"payout_fiat\", \"payout_crypto\",\r\n\"crypto_conversion\", \"fee\".","type":"string"},"updatedAt":{"format":"date-time","type":"string"},"virtualAccountId":{"type":"string"}},"type":"object"},"v1TransactionDocument":{"description":"TransactionDocument is a supporting file attached to a crypto payout.","properties":{"createdAt":{"format":"date-time","type":"string"},"description":{"type":"string"},"docType":{"title":"\"invoice\" or \"other\"","type":"string"},"fileName":{"type":"string"},"fileSize":{"description":"File size in bytes.","format":"int32","type":"integer"},"id":{"type":"string"},"mimeType":{"type":"string"}},"type":"object"},"v1UpdateFeesRequest":{"properties":{"railFees":{"items":{"$ref":"#/definitions/v1FeeRailFeeInput","type":"object"},"type":"array"},"schedules":{"items":{"$ref":"#/definitions/v1FeeScheduleInput","type":"object"},"type":"array"}},"type":"object"},"v1UpdateFeesResponse":{"properties":{"railFees":{"items":{"$ref":"#/definitions/v1FeeRailFee","type":"object"},"type":"array"},"schedules":{"items":{"$ref":"#/definitions/v1FeeSchedule","type":"object"},"type":"array"}},"type":"object"},"v1UpdateOrgFeesResponse":{"properties":{"railFees":{"items":{"$ref":"#/definitions/v1FeeRailFee","type":"object"},"type":"array"},"schedules":{"items":{"$ref":"#/definitions/v1FeeSchedule","type":"object"},"type":"array"}},"type":"object"},"v1UpdateOrganizationResponse":{"properties":{"organization":{"$ref":"#/definitions/v1Organization"}},"type":"object"},"v1UploadPayoutDocumentRequest":{"properties":{"data":{"format":"byte","type":"string"},"description":{"type":"string"},"docType":{"description":"Document type. Values: \"invoice\" or \"other\".","type":"string"},"fileName":{"type":"string"},"fileSize":{"description":"File size in bytes (max 10 485 760 = 10 MB).","format":"int32","type":"integer"},"mimeType":{"description":"MIME type. Values: \"application/pdf\", \"image/png\", \"image/jpeg\".","type":"string"},"transactionId":{"description":"Optional: link to an existing transaction. Empty for pre-upload before tx creation.","type":"string"}},"type":"object"},"v1UploadPayoutDocumentResponse":{"properties":{"createdAt":{"format":"date-time","type":"string"},"documentId":{"type":"string"},"fileName":{"type":"string"}},"type":"object"},"v1VirtualAccount":{"properties":{"accountNumber":{"type":"string"},"accountType":{"type":"string"},"balanceUpdatedAt":{"format":"date-time","type":"string"},"bankAddress":{"type":"string"},"bankName":{"type":"string"},"beneficiaryName":{"type":"string"},"cachedBalance":{"description":"Last cached total balance reported for this account. Use GetBalance for the\r\nspendable split between available and reserved funds.","format":"double","type":"number"},"createdAt":{"format":"date-time","type":"string"},"currency":{"description":"ISO currency code. v1 currently supports \"USD\" for fiat virtual accounts.","type":"string"},"destinationAddress":{"type":"string"},"destinationCurrency":{"description":"Crypto destination (empty for fiat accounts).","type":"string"},"destinationNetwork":{"type":"string"},"fintechId":{"type":"string"},"id":{"type":"string"},"mode":{"description":"Virtual account mode, e.g. \"fiat\" or \"crypto\".","type":"string"},"organizationId":{"type":"string"},"referenceMemo":{"type":"string"},"routingNumber":{"type":"string"},"status":{"description":"Provider-backed lifecycle status for this virtual account.","type":"string"},"swiftBic":{"type":"string"},"swiftDepositInstructions":{"$ref":"#/definitions/v1SwiftDepositInstructions","description":"Inbound SWIFT wire instructions. Populated for fiat virtual accounts that\r\naccept SWIFT funding. Distinct from the ACH/WIRE-domestic fields above,\r\nwhich target the underlying bank directly."},"updatedAt":{"format":"date-time","type":"string"}},"type":"object"}},"info":{"title":"gateway/api_keys.proto","version":"version not set"},"paths":{"/api/v1/api-keys":{"get":{"description":"Retrieves a list of all API keys associated with your fintech organization. For security reasons, the full API key strings are never returned; only the key identifiers and metadata (such as creation date and last used time) are provided.","operationId":"ApiKeyService_ListApiKeys","responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1ListApiKeysResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"List API keys","tags":["ApiKeyService"]},"post":{"description":"Generates a new programmatic API key for your fintech organization. This key is used to authenticate server-to-server requests to the Magma API. The raw API key string is returned exactly once in this response payload. Ensure you store it securely in your secrets management system immediately, as it cannot be retrieved again.","operationId":"ApiKeyService_CreateApiKey","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/v1CreateApiKeyRequest"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1CreateApiKeyResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Create an API key","tags":["ApiKeyService"]}},"/api/v1/api-keys/{id}":{"delete":{"description":"Permanently disables an API key by its unique ID. Any subsequent API requests using this revoked key will be immediately rejected with an authentication error. This action is irreversible.","operationId":"ApiKeyService_RevokeApiKey","parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1RevokeApiKeyResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Revoke an API key","tags":["ApiKeyService"]}},"/api/v1/crypto/networks":{"get":{"description":"Retrieves a comprehensive list of all blockchain networks and specific stablecoin tokens currently supported by Magma for both 'Get Crypto' features and crypto-funded payouts.","operationId":"PaymentService_GetSupportedNetworks","responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetSupportedNetworksResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"List supported crypto networks","tags":["PaymentService"]}},"/api/v1/fees":{"get":{"description":"Retrieves the complete set of base fee schedules and fixed rail fees configured for your fintech. This includes both your platform pricing (what Magma charges you) and your default fintech pricing (what you charge your customers by default).","operationId":"FeeService_GetFees","responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetFeesResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"List fintech-wide fee schedules","tags":["FeeService"]},"put":{"description":"Performs a bulk upsert of your fintech's default fee schedules and rail fees. Operators can only modify 'fintech' layer rows to update the baseline pricing applied to all newly created organizations.","operationId":"FeeService_UpdateFees","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/v1UpdateFeesRequest"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1UpdateFeesResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Update fintech-wide fee schedules","tags":["FeeService"]}},"/api/v1/organizations":{"get":{"description":"Retrieves a paginated list of all organizations under your fintech. Results can be optionally filtered by their `status` (e.g. created, verified, active) or queried via a free-text `search` that matches across name, email, and your custom `external_id`.","operationId":"OrganizationService_ListOrganizations","parameters":[{"description":"Filter by onboarding_status. Values: \"created\", \"verifying\", \"verified\",\r\n\"active\", \"rejected\", \"review\", \"suspended\".","in":"query","name":"status","required":false,"type":"string"},{"description":"Free-text search across name, email, external_id","in":"query","name":"search","required":false,"type":"string"},{"format":"int32","in":"query","name":"page","required":false,"type":"integer"},{"format":"int32","in":"query","name":"limit","required":false,"type":"integer"},{"description":"When false (default), organizations flagged as is_self are excluded.\r\nSet to true to include them in the result set.","in":"query","name":"includeSelf","required":false,"type":"boolean"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1ListOrganizationsResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"List organizations","tags":["OrganizationService"]},"post":{"description":"Creates a new organization profile (either 'business' or 'individual') and initiates the KYC/KYB onboarding process. Depending on the `verification_mode`, you can either pass all required compliance data upfront (`automatic`) or rely on a Magma-hosted verification flow (`verification_link`) which automatically emails the contact with a link to complete their profile.","operationId":"OrganizationService_CreateOrganization","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/v1CreateOrganizationRequest"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1CreateOrganizationResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Create an organization","tags":["OrganizationService"]}},"/api/v1/organizations/{id}":{"get":{"description":"Retrieves the full details of a specific organization by its unique system ID, along with its specific KPIs.","operationId":"OrganizationService_GetOrganization","parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetOrganizationResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Get an organization","tags":["OrganizationService"]},"put":{"description":"Updates mutable information for an existing organization. The organization `type` (business or individual) is immutable and cannot be modified after creation.","operationId":"OrganizationService_UpdateOrganization","parameters":[{"in":"path","name":"id","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/OrganizationServiceUpdateOrganizationBody"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1UpdateOrganizationResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Update an organization","tags":["OrganizationService"]}},"/api/v1/organizations/{orgId}/fees":{"put":{"description":"Performs a bulk upsert of custom fee overrides for a specific organization. This allows you to offer custom pricing to individual clients that supersedes your fintech's default fee schedules.","operationId":"FeeService_UpdateOrgFees","parameters":[{"in":"path","name":"orgId","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/FeeServiceUpdateOrgFeesBody"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1UpdateOrgFeesResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Update organization-specific fee overrides","tags":["FeeService"]}},"/api/v1/organizations/{orgId}/fees/effective":{"get":{"description":"Retrieves the final, fully resolved fee matrix actively applied to an organization. This endpoint does the math for you: it merges the organization's custom overrides with your fintech defaults, evaluates volume-based tiers, and outputs the exact rates and fixed fees currently in effect.","operationId":"FeeService_GetEffectiveFees","parameters":[{"in":"path","name":"orgId","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetEffectiveFeesResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Get effective fee matrix","tags":["FeeService"]}},"/api/v1/organizations/{orgId}/recipients":{"get":{"description":"Retrieves a complete list of all recipients that have been created for or linked to a specific organization. You can filter the list to only return 'fiat' or 'crypto' recipients via the `channel` parameter.","operationId":"RecipientService_ListOrgRecipients","parameters":[{"in":"path","name":"orgId","required":true,"type":"string"},{"description":"Optional: filter by channel (\"fiat\" or \"crypto\").","in":"query","name":"channel","required":false,"type":"string"},{"format":"int32","in":"query","name":"page","required":false,"type":"integer"},{"format":"int32","in":"query","name":"limit","required":false,"type":"integer"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1ListOrgRecipientsResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"List organization recipients","tags":["RecipientService"]},"post":{"description":"Creates a new recipient specifically scoped to a single organization. Unlike recipient templates, this beneficiary is private to the organization and cannot be easily reused across your entire fintech portfolio.","operationId":"RecipientService_CreateOrgRecipient","parameters":[{"in":"path","name":"orgId","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/RecipientServiceCreateOrgRecipientBody"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1CreateOrgRecipientResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Create an organization recipient","tags":["RecipientService"]}},"/api/v1/organizations/{orgId}/transactions":{"get":{"description":"Retrieves a paginated list of transactions strictly scoped to a specific organization. Supports the exact same powerful filtering parameters (like status, type, and date range) as the global transaction list endpoint.","operationId":"TransactionService_ListOrgTransactions","parameters":[{"in":"path","name":"orgId","required":true,"type":"string"},{"description":"Transaction status. Values: \"created\", \"pending\", \"processing\",\r\n\"completed\", \"failed\", \"action_required\", \"under_review\", \"returned\",\r\n\"expired\", \"canceled\".","in":"query","name":"status","required":false,"type":"string"},{"description":"Transaction type. Values: \"deposit_fiat\", \"payout_fiat\",\r\n\"payout_crypto\", \"crypto_conversion\", \"fee\".","in":"query","name":"type","required":false,"type":"string"},{"in":"query","name":"recipientId","required":false,"type":"string"},{"description":"Blockchain network filter for crypto transactions, e.g. \"polygon\" or \"solana\".","in":"query","name":"network","required":false,"type":"string"},{"format":"date-time","in":"query","name":"fromDate","required":false,"type":"string"},{"format":"date-time","in":"query","name":"toDate","required":false,"type":"string"},{"in":"query","name":"q","required":false,"type":"string"},{"format":"int32","in":"query","name":"page","required":false,"type":"integer"},{"format":"int32","in":"query","name":"limit","required":false,"type":"integer"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1ListTransactionsResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"List organization transactions","tags":["TransactionService"]}},"/api/v1/organizations/{orgId}/virtual-accounts":{"get":{"description":"Retrieves a complete list of all virtual accounts (both fiat and crypto) assigned to a specific organization. Virtual accounts are used to hold balances and receive or send funds.","operationId":"OrganizationService_ListVirtualAccounts","parameters":[{"in":"path","name":"orgId","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1ListVirtualAccountsResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"List virtual accounts","tags":["OrganizationService"]}},"/api/v1/organizations/{orgId}/wallets":{"get":{"description":"Retrieves a list of all pre-saved, verified destination crypto wallets associated with a specific organization.","operationId":"PaymentService_ListSavedWallets","parameters":[{"in":"path","name":"orgId","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1ListSavedWalletsResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"List saved wallets","tags":["PaymentService"]},"post":{"description":"Securely saves a new destination crypto wallet address to an organization's profile, allowing it to be easily reused for future crypto payouts without manual reentry.","operationId":"PaymentService_CreateSavedWallet","parameters":[{"in":"path","name":"orgId","required":true,"type":"string"},{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/PaymentServiceCreateSavedWalletBody"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1CreateSavedWalletResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Create a saved wallet","tags":["PaymentService"]}},"/api/v1/organizations:self":{"get":{"description":"Retrieves the internal 'self' organization profile for the authenticated fintech. This distinct organization record legally represents your fintech itself as an operating business entity within the Magma ecosystem.","operationId":"OrganizationService_GetSelfOrganization","responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetSelfOrganizationResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Get self organization","tags":["OrganizationService"]}},"/api/v1/payouts/crypto":{"post":{"description":"Initiates a crypto-funded payout and provisions a unique, single-use cryptocurrency deposit address. The sending party has a strictly enforced 24-hour window to deposit the correct stablecoin amount to this address before it expires.","operationId":"PaymentService_CreateCryptoPayout","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/v1CreateCryptoPayoutRequest"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1CreateCryptoPayoutResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Create a crypto-to-fiat payout","tags":["PaymentService"]}},"/api/v1/payouts/crypto/upload-doc":{"post":{"description":"Securely uploads a required supporting compliance document (e.g. an invoice) to be permanently attached to a crypto payout. Supported formats include PDF, PNG, and JPG, with a strict maximum file size of 10 MB.","operationId":"PaymentService_UploadPayoutDocument","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/v1UploadPayoutDocumentRequest"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1UploadPayoutDocumentResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Upload a payout supporting document","tags":["PaymentService"]}},"/api/v1/payouts/fiat":{"post":{"description":"Submits the payment instruction for ACH, WIRE, or SWIFT execution. This endpoint strictly requires you to provide the `Idempotency-Key` header to ensure safety and prevent duplicate transactions.","operationId":"PaymentService_CreateFiatPayout","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/v1CreateFiatPayoutRequest"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1CreateFiatPayoutResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Create a fiat payout","tags":["PaymentService"]}},"/api/v1/payouts/preview":{"post":{"description":"Calculates and returns the precise fee breakdown, applicable currency exchange rates, and the exact net amount a recipient will receive for a prospective payout. This endpoint does not execute any transaction.","operationId":"PaymentService_PreviewPayout","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/v1PreviewPayoutRequest"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1PreviewPayoutResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Preview a payout","tags":["PaymentService"]}},"/api/v1/recipients/{id}":{"delete":{"description":"Permanently deletes an organization-scoped recipient, preventing any future payouts to this beneficiary. Historical transaction records involving this recipient remain intact.","operationId":"RecipientService_DeleteRecipient","parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1DeleteRecipientResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Delete a recipient","tags":["RecipientService"]},"get":{"description":"Retrieves the complete data record for an organization-scoped recipient, identified by its unique ID.","operationId":"RecipientService_GetRecipient","parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetRecipientResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Get a recipient","tags":["RecipientService"]}},"/api/v1/transactions":{"get":{"description":"Retrieves a paginated list of all transactions across your entire fintech portfolio. You can thoroughly filter the results using various parameters including `status`, transaction `type`, `organization_id`, `recipient_id`, date range (`from_date` and `to_date`), or use the free-text `q` parameter to search across transaction references and descriptions.","operationId":"TransactionService_ListTransactions","parameters":[{"description":"Transaction status. Values: \"created\", \"pending\", \"processing\",\r\n\"completed\", \"failed\", \"action_required\", \"under_review\", \"returned\",\r\n\"expired\", \"canceled\".","in":"query","name":"status","required":false,"type":"string"},{"description":"Transaction type. Values: \"deposit_fiat\", \"payout_fiat\",\r\n\"payout_crypto\", \"crypto_conversion\", \"fee\".","in":"query","name":"type","required":false,"type":"string"},{"in":"query","name":"organizationId","required":false,"type":"string"},{"in":"query","name":"recipientId","required":false,"type":"string"},{"description":"Blockchain network filter for crypto transactions, e.g. \"polygon\" or \"solana\".","in":"query","name":"network","required":false,"type":"string"},{"format":"date-time","in":"query","name":"fromDate","required":false,"type":"string"},{"format":"date-time","in":"query","name":"toDate","required":false,"type":"string"},{"in":"query","name":"q","required":false,"type":"string"},{"format":"int32","in":"query","name":"page","required":false,"type":"integer"},{"format":"int32","in":"query","name":"limit","required":false,"type":"integer"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1ListTransactionsResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"List transactions","tags":["TransactionService"]}},"/api/v1/transactions/export-csv":{"get":{"description":"Generates a fully formatted CSV export of transactions matching your specified filter parameters. The raw CSV text data is returned as a Base64-encoded string within the `csv_data` field. Perfect for accounting reconciliations.","operationId":"TransactionService_ExportTransactionsCSV","parameters":[{"description":"Transaction status filter. See ListTransactionsRequest.status for values.","in":"query","name":"status","required":false,"type":"string"},{"description":"Transaction type filter. See ListTransactionsRequest.type for values.","in":"query","name":"type","required":false,"type":"string"},{"in":"query","name":"organizationId","required":false,"type":"string"},{"format":"date-time","in":"query","name":"fromDate","required":false,"type":"string"},{"format":"date-time","in":"query","name":"toDate","required":false,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1ExportTransactionsCSVResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Export transactions as CSV","tags":["TransactionService"]}},"/api/v1/transactions/export-pdf":{"post":{"description":"Returns a flattened, unpaginated JSON array of transactions matching your specified filters. This endpoint is specifically optimized for client-side applications that need to rapidly render PDF transaction statements without handling pagination logic.","operationId":"TransactionService_ExportTransactionsPDF","parameters":[{"in":"body","name":"body","required":true,"schema":{"$ref":"#/definitions/v1ExportTransactionsPDFRequest"}}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1ExportTransactionsPDFResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Export transactions for PDF","tags":["TransactionService"]}},"/api/v1/transactions/{id}":{"get":{"description":"Retrieves the complete, detailed record of a single transaction identified by its unique ID. This payload includes exhaustive data such as applied fees, conversion rates, and any attached compliance documents.","operationId":"TransactionService_GetTransaction","parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetTransactionResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Get a transaction","tags":["TransactionService"]}},"/api/v1/transactions/{id}/receipt":{"get":{"description":"Generates and returns an official, Magma-branded PDF receipt for a specific completed transaction. The binary PDF file is Base64-encoded within the `pdf_data` field of the JSON response.","operationId":"TransactionService_DownloadTransactionReceipt","parameters":[{"description":"Transaction UUID.","in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1DownloadTransactionReceiptResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Download transaction receipt PDF","tags":["TransactionService"]}},"/api/v1/virtual-accounts/{id}":{"get":{"description":"Retrieves the full details of a single virtual account by its unique ID. This includes account routing information, currency, and current status.","operationId":"OrganizationService_GetVirtualAccount","parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetVirtualAccountResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Get a virtual account","tags":["OrganizationService"]}},"/api/v1/virtual-accounts/{id}/balance":{"get":{"description":"Retrieves the most recent available and reserved balance for a specific virtual account. `available` balance can be used for outbound payments, while `reserved` balance is currently locked in pending transactions.","operationId":"OrganizationService_GetBalance","parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetBalanceResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Get virtual account balance","tags":["OrganizationService"]}},"/api/v1/virtual-accounts/{id}/bank-letter":{"get":{"description":"Generates and returns an official, Magma-branded PDF bank letter. This document formally confirms the virtual account details and provides standardized deposit transfer instructions. The raw PDF binary data is securely Base64-encoded within the `pdf_data` field of the JSON response.","operationId":"OrganizationService_DownloadBankLetter","parameters":[{"description":"Virtual account UUID.","in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1DownloadBankLetterResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Download virtual account bank letter PDF","tags":["OrganizationService"]}},"/api/v1/virtual-accounts/{id}/deposit-info":{"get":{"description":"Retrieves the corresponding bank coordinates and wire/ACH transfer instructions required to deposit fiat funds into a specific virtual account.","operationId":"OrganizationService_GetDepositInfo","parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetDepositInfoResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Get deposit info","tags":["OrganizationService"]}},"/api/v1/wallets/{id}":{"get":{"description":"Retrieves a single saved wallet together with the crypto virtual account linked to it and the banking deposit coordinates used to fund the on-ramp.","operationId":"PaymentService_GetSavedWallet","parameters":[{"in":"path","name":"id","required":true,"type":"string"}],"responses":{"200":{"description":"A successful response.","schema":{"$ref":"#/definitions/v1GetSavedWalletResponse"}},"default":{"description":"An unexpected error response.","schema":{"$ref":"#/definitions/rpcStatus"}}},"summary":"Get a saved wallet","tags":["PaymentService"]}}},"produces":["application/json"],"security":[{"ApiKeyAuth":[]},{"OAuth2":["openid"]}],"securityDefinitions":{"ApiKeyAuth":{"in":"header","name":"X-Api-Key","type":"apiKey"},"OAuth2":{"authorizationUrl":"https://auth.magma.builders/realms/magma/protocol/openid-connect/auth","flow":"accessCode","scopes":{"openid":"OpenID Connect"},"tokenUrl":"https://auth.magma.builders/realms/magma/protocol/openid-connect/token","type":"oauth2"}},"swagger":"2.0","tags":[{"name":"ApiKeyService"},{"name":"FeeService"},{"name":"OrganizationService"},{"name":"PaymentService"},{"name":"RecipientService"},{"name":"TransactionService"}]}