diff --git a/api-reference/fx-account/balances/get-balance.mdx b/api-reference/fx-account/balances/get-balance.mdx deleted file mode 100644 index ac09bd2..0000000 --- a/api-reference/fx-account/balances/get-balance.mdx +++ /dev/null @@ -1,5 +0,0 @@ ---- -title: "Get account balance" -description: "Retrieves the multi-currency balance for an account." -openapi: "apis/fx-account/openapi.yml GET /api/accounts/{accountId}/balances" ---- diff --git a/apis/fx-account/openapi.yml b/apis/fx-account/openapi.yml index 47031eb..b3c4af9 100644 --- a/apis/fx-account/openapi.yml +++ b/apis/fx-account/openapi.yml @@ -17,8 +17,6 @@ tags: description: Upload documents to fulfill account and UBO requirements. - name: Funding instructions description: Retrieve funding instructions for depositing into an account. - - name: Balances - description: Retrieve fiat and crypto balances for an account. components: securitySchemes: bearerAuth: @@ -136,13 +134,8 @@ components: properties: code: $ref: "#/components/schemas/Asset" - isVirtual: - type: boolean - description: Whether this is a virtual (non-custodial) asset. - example: false required: - code - - isVirtual OwnerRequest: description: The legal entity that owns the account. Discriminated by `type`. oneOf: @@ -175,6 +168,12 @@ components: nullable: true description: Company incorporation date in ISO format (yyyy-MM-dd). Optional. example: "2018-05-12" + isStartup: + type: boolean + nullable: true + default: false + description: Whether the company is a startup. Optional. + example: false address: $ref: "#/components/schemas/AddressRequest" required: @@ -267,16 +266,33 @@ components: $ref: "#/components/schemas/TaxIdRequest" address: $ref: "#/components/schemas/AddressRequest" + phone: + type: string + description: Contact phone number with country code. + example: "5511999999999" + email: + type: string + format: email + description: Contact email address. + example: "joao.silva@example.com" ownershipPercentage: type: number format: double nullable: true description: Percentage of ownership. Optional. example: 50.0 + isLegalRepresentative: + type: boolean + nullable: true + default: false + description: Whether this beneficial owner is the legal representative of the account. + example: false required: - name - taxId - address + - phone + - email UpdateUBORequest: type: object description: Request body for updating a beneficial owner. All fields are optional (patch semantics). @@ -289,12 +305,26 @@ components: $ref: "#/components/schemas/TaxIdRequest" address: $ref: "#/components/schemas/AddressRequest" + phone: + type: string + description: Contact phone number with country code. + example: "5511999999999" + email: + type: string + format: email + description: Contact email address. + example: "joao.silva@example.com" ownershipPercentage: type: number format: double nullable: true description: Percentage of ownership. example: 75.0 + isLegalRepresentative: + type: boolean + nullable: true + description: Whether this beneficial owner is the legal representative of the account. + example: false # ── Response schemas ───────────────────────────────────────────── AccountResponse: @@ -380,7 +410,7 @@ components: type: object description: An asset available on the account and the onboarding status of its underlying provider account. properties: - asset: + currency: $ref: "#/components/schemas/Asset" allowsVirtualAccounts: type: boolean @@ -398,7 +428,7 @@ components: example: "ONBOARDING" readOnly: true required: - - asset + - currency - allowsVirtualAccounts - status AmountResponse: @@ -423,47 +453,6 @@ components: - value - asset - decimals - BalanceEntryResponse: - type: object - description: > - A single balance entry for one asset. When `synced` is `false`, the - upstream provider was unreachable and `amount` is omitted; the customer - should retry or fall back to a previously cached value. - properties: - amount: - allOf: - - $ref: "#/components/schemas/AmountResponse" - nullable: true - description: The available balance. Null when `synced` is `false`. - synced: - type: boolean - description: Whether the balance was successfully retrieved from the underlying provider. - example: true - required: - - synced - BalanceResponse: - type: object - description: Multi-currency balance grouped by asset class. - properties: - accountId: - type: string - format: uuid - description: Identifier of the account these balances belong to. - example: "5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c" - fiat: - type: array - description: Fiat balances, one entry per enabled fiat currency. - items: - $ref: "#/components/schemas/BalanceEntryResponse" - crypto: - type: array - description: Crypto balances, one entry per enabled crypto currency. - items: - $ref: "#/components/schemas/BalanceEntryResponse" - required: - - accountId - - fiat - - crypto CustomerResponse: type: object properties: @@ -670,24 +659,39 @@ components: - errors - satisfied RequirementResponse: - type: object description: | - A single requirement. The `type` discriminates between two shapes: - - `DOCUMENT`: a specific document of a given `documentType` is required. - - `DOCUMENT_GROUP`: any one document from `options` will satisfy the requirement (e.g., proof of identity can be ID card, passport, or driver's license). + A single requirement. The `type` field discriminates between five shapes: + + - `ACCOUNT_DOCUMENT`: a specific document is required at the account level. + - `UBO_DOCUMENT`: a specific document is required for a beneficial owner. + - `IDENTITY_VERIFICATION`: any one document from `options` satisfies an identity verification requirement. + - `ACCOUNT_FIELD`: an account-level field was rejected during review. + - `UBO_FIELD`: a UBO field was rejected during review. + oneOf: + - $ref: "#/components/schemas/AccountDocumentRequirement" + - $ref: "#/components/schemas/UboDocumentRequirement" + - $ref: "#/components/schemas/IdentityVerificationRequirement" + - $ref: "#/components/schemas/AccountFieldRejection" + - $ref: "#/components/schemas/UboFieldRejection" + discriminator: + propertyName: type + mapping: + ACCOUNT_DOCUMENT: "#/components/schemas/AccountDocumentRequirement" + UBO_DOCUMENT: "#/components/schemas/UboDocumentRequirement" + IDENTITY_VERIFICATION: "#/components/schemas/IdentityVerificationRequirement" + ACCOUNT_FIELD: "#/components/schemas/AccountFieldRejection" + UBO_FIELD: "#/components/schemas/UboFieldRejection" + AccountDocumentRequirement: + title: Account document + type: object + description: A document required at the account level. properties: type: type: string - description: Requirement type discriminator. enum: - - DOCUMENT - - DOCUMENT_GROUP - example: "DOCUMENT" + - ACCOUNT_DOCUMENT documentType: - allOf: - - $ref: "#/components/schemas/DocumentType" - nullable: true - description: The specific document type required. Set when `type` is `DOCUMENT`. + $ref: "#/components/schemas/DocumentType" documentSubType: allOf: - $ref: "#/components/schemas/DocumentSubType" @@ -695,26 +699,49 @@ components: description: > Sub-classification of the document. Set when the `documentType` requires a specific side (e.g., `FRONT_SIDE` for `ID_CARD`). - group: - allOf: - - $ref: "#/components/schemas/RequirementGroup" - nullable: true - description: Group identifier. Set when `type` is `DOCUMENT_GROUP`. - options: + requiredMetadata: type: array nullable: true - description: Acceptable document types. Set when `type` is `DOCUMENT_GROUP`. + description: Metadata keys that must accompany the document upload (e.g., `country`, `number`). items: - $ref: "#/components/schemas/DocumentType" + type: string + example: ["country"] + metadata: + type: object + nullable: true + additionalProperties: + type: string + description: Metadata captured for an already-fulfilled requirement. + reason: + $ref: "#/components/schemas/Reason" + required: + - type + - documentType + UboDocumentRequirement: + title: UBO document + type: object + description: A document required for a specific beneficial owner. + properties: + type: + type: string + enum: + - UBO_DOCUMENT + documentType: + $ref: "#/components/schemas/DocumentType" + documentSubType: + allOf: + - $ref: "#/components/schemas/DocumentSubType" + nullable: true + description: Sub-classification of the document. uboId: type: string format: uuid - nullable: true - description: UBO identifier when the requirement belongs to a beneficial owner. `null` for account-level requirements. + description: Identifier of the beneficial owner this document belongs to. + example: "a1b2c3d4-e5f6-7890-1234-567890abcdef" requiredMetadata: type: array nullable: true - description: Metadata keys that must accompany the document upload (e.g., `country`, `number`). + description: Metadata keys that must accompany the document upload. items: type: string example: ["country"] @@ -728,6 +755,71 @@ components: $ref: "#/components/schemas/Reason" required: - type + - documentType + - uboId + IdentityVerificationRequirement: + title: Identity verification + type: object + description: > + A grouped requirement satisfied by any one of the document types listed + in `options` (e.g., identity verification can be fulfilled with an + `ID_CARD`, `PASSPORT`, or `DRIVER_LICENSE`). + properties: + type: + type: string + enum: + - IDENTITY_VERIFICATION + options: + type: array + description: Acceptable document types that satisfy this requirement. + items: + $ref: "#/components/schemas/DocumentType" + required: + - type + - options + AccountFieldRejection: + title: Account field rejection + type: object + description: An account-level field was rejected during compliance review. + properties: + type: + type: string + enum: + - ACCOUNT_FIELD + fieldName: + type: string + description: Name of the rejected field. + example: "owner.legalName" + reason: + $ref: "#/components/schemas/Reason" + required: + - type + - fieldName + - reason + UboFieldRejection: + title: UBO field rejection + type: object + description: A UBO field was rejected during compliance review. + properties: + type: + type: string + enum: + - UBO_FIELD + fieldName: + type: string + description: Name of the rejected field. + example: "name" + uboId: + type: string + description: Identifier of the beneficial owner whose field was rejected. + example: "a1b2c3d4-e5f6-7890-1234-567890abcdef" + reason: + $ref: "#/components/schemas/Reason" + required: + - type + - fieldName + - uboId + - reason DocumentType: type: string description: Type of document. @@ -758,6 +850,11 @@ components: - RESIDENCE_PERMIT - SELFIE - UTILITY_BILL + - KYC_FORM + - BAAS_ADHESION_FORM + - PJ_PARTNER_DOCUMENTS + - PJ_PARTNER_FINANCIAL_STATEMENT + - SIGNING_AUTHORITY_PROOF example: "ARTICLES_OF_ASSOCIATION" DocumentSubType: type: string @@ -1260,11 +1357,21 @@ components: $ref: "#/components/schemas/TaxIdResponse" address: $ref: "#/components/schemas/AddressResponse" + phone: + type: string + example: "5511999999999" + email: + type: string + format: email + example: "joao.silva@example.com" ownershipPercentage: type: number format: double nullable: true example: 50.0 + isLegalRepresentative: + type: boolean + example: false currentState: $ref: "#/components/schemas/UBOState" required: @@ -1272,19 +1379,10 @@ components: - name - taxId - address + - phone + - email + - isLegalRepresentative - currentState - UBOList: - type: object - properties: - data: - type: array - items: - $ref: "#/components/schemas/UBOResponse" - meta: - $ref: "#/components/schemas/PageMetadata" - required: - - data - - meta Rail: type: string description: Payment rail used to fund a deposit. @@ -1301,37 +1399,56 @@ components: - SEPA - ACH FundingInstructionResponse: - description: A funding instruction for depositing into an account. Discriminated by `rail`. + description: A funding instruction for depositing into an account. Discriminated by `type`. oneOf: - $ref: "#/components/schemas/PixKeyFundingInstruction" - $ref: "#/components/schemas/PixStaticQrCodeFundingInstruction" + - $ref: "#/components/schemas/PixBankInstructionFundingInstruction" - $ref: "#/components/schemas/TedFundingInstruction" - $ref: "#/components/schemas/BoletoFundingInstruction" - $ref: "#/components/schemas/CryptoWalletFundingInstruction" discriminator: - propertyName: rail + propertyName: type mapping: PIX_KEY: "#/components/schemas/PixKeyFundingInstruction" PIX_STATIC_QR_CODE: "#/components/schemas/PixStaticQrCodeFundingInstruction" + PIX_BANK_INSTRUCTION: "#/components/schemas/PixBankInstructionFundingInstruction" TED: "#/components/schemas/TedFundingInstruction" BOLETO: "#/components/schemas/BoletoFundingInstruction" - CRYPTO: "#/components/schemas/CryptoWalletFundingInstruction" + CRYPTO_WALLET: "#/components/schemas/CryptoWalletFundingInstruction" FundingInstructionBase: type: object properties: asset: $ref: "#/components/schemas/Asset" + type: + $ref: "#/components/schemas/FundingInstructionType" rail: $ref: "#/components/schemas/Rail" required: - asset + - type - rail + FundingInstructionType: + type: string + description: Funding instruction shape. Each value maps to one variant of `FundingInstructionResponse`. + enum: + - PIX_KEY + - PIX_STATIC_QR_CODE + - PIX_BANK_INSTRUCTION + - TED + - BOLETO + - CRYPTO_WALLET PixKeyFundingInstruction: title: PIX key allOf: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - PIX_KEY rail: type: string enum: @@ -1359,6 +1476,10 @@ components: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - PIX_STATIC_QR_CODE rail: type: string enum: @@ -1369,12 +1490,51 @@ components: example: "00020126580014br.gov.bcb.pix..." required: - qrCode + PixBankInstructionFundingInstruction: + title: PIX bank instruction + allOf: + - $ref: "#/components/schemas/FundingInstructionBase" + - type: object + properties: + type: + type: string + enum: + - PIX_BANK_INSTRUCTION + rail: + type: string + enum: + - PIX_BANK_INSTRUCTION + bankCode: + type: string + description: Bank code (ISPB or COMPE). + example: "001" + branch: + type: string + description: Branch number. + example: "0001" + accountNumber: + type: string + description: Account number. + example: "123456-7" + accountType: + type: string + description: Type of bank account. + example: "CHECKING" + required: + - bankCode + - branch + - accountNumber + - accountType TedFundingInstruction: title: TED allOf: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - TED rail: type: string enum: @@ -1406,6 +1566,10 @@ components: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - BOLETO rail: type: string enum: @@ -1428,6 +1592,10 @@ components: - $ref: "#/components/schemas/FundingInstructionBase" - type: object properties: + type: + type: string + enum: + - CRYPTO_WALLET rail: type: string enum: @@ -1443,18 +1611,6 @@ components: required: - network - walletAddress - FundingInstructionList: - type: object - properties: - data: - type: array - items: - $ref: "#/components/schemas/FundingInstructionResponse" - meta: - $ref: "#/components/schemas/PageMetadata" - required: - - data - - meta UploadDocumentRequest: type: object description: > @@ -1605,44 +1761,6 @@ components: message: "'not-a-uuid' cannot be converted to UUID" field: "path:accountId" params: {} - BalanceNotFound: - summary: No balance is tracked for the requested account - value: - code: "RESOURCE_NOT_FOUND" - message: "Balance with given parameters [Balance.accountId:5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c] not found" - details: - resource: "Balance" - parameters: - Balance.accountId: "5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c" - BalanceMixed: - summary: Account with fiat and crypto assets - value: - accountId: "5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c" - fiat: - - amount: - value: "5000.00" - asset: "BRL" - decimals: 2 - synced: true - crypto: - - amount: - value: "1.500000" - asset: "USDC" - decimals: 6 - synced: true - BalanceUnsyncedSource: - summary: Upstream provider was unreachable for one currency - value: - accountId: "5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c" - fiat: - - amount: - value: "5000.00" - asset: "BRL" - decimals: 2 - synced: true - - amount: null - synced: false - crypto: [] paths: # ── Account endpoints ──────────────────────────────────────────── @@ -1668,7 +1786,6 @@ paths: value: assets: - code: "BRL" - isVirtual: false owner: type: "COMPANY" legalName: "Acme Ltda" @@ -1677,6 +1794,7 @@ paths: type: "CNPJ" industry: "SOFTWARE_DEVELOPMENT" incorporateDate: "2018-05-12" + isStartup: false address: addressLine1: "Rua das Flores, 100" addressLine2: "Suite 456" @@ -1689,7 +1807,6 @@ paths: value: assets: - code: "BRL" - isVirtual: false owner: type: "INDIVIDUAL" firstName: "Maria" @@ -1956,44 +2073,50 @@ paths: tags: - Funding instructions summary: List funding instructions - description: Retrieves funding instructions for depositing into an account. Returns all available payment rails (PIX, TED, Boleto, crypto). + description: Retrieves funding instructions for depositing into an account. Returns all available payment rails (PIX, TED, Boleto, crypto). Optionally filter by `asset` and/or `rail`. parameters: - $ref: "#/components/parameters/AccountId" - $ref: "#/components/parameters/TraceVersion" - - $ref: "#/components/parameters/PaginationLimit" - - $ref: "#/components/parameters/PaginationCursor" - - $ref: "#/components/parameters/PaginationDirection" - - $ref: "#/components/parameters/PaginationSortOrder" - - $ref: "#/components/parameters/Filters" + - name: asset + in: query + required: false + description: Filter results by asset code. + schema: + $ref: "#/components/schemas/Asset" + - name: rail + in: query + required: false + description: Filter results by payment rail. + schema: + $ref: "#/components/schemas/Rail" responses: "200": - description: Paginated list of funding instructions. + description: List of funding instructions. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: - $ref: "#/components/schemas/FundingInstructionList" + type: array + items: + $ref: "#/components/schemas/FundingInstructionResponse" examples: mixed: summary: PIX and TED instructions value: - data: - - asset: "BRL" - rail: "PIX_KEY" - keyType: "CNPJ" - key: "12345678000101" - - asset: "BRL" - rail: "TED" - bankCode: "001" - branch: "0001" - accountNumber: "123456-7" - accountType: "CHECKING" - meta: - previousCursor: null - nextCursor: null - total: 2 + - asset: "BRL" + type: "PIX_KEY" + rail: "PIX_KEY" + keyType: "CNPJ" + key: "12345678000101" + - asset: "BRL" + type: "TED" + rail: "TED" + bankCode: "001" + branch: "0001" + accountNumber: "123456-7" + accountType: "CHECKING" "400": description: Invalid account ID format. headers: @@ -2021,66 +2144,6 @@ paths: accountNotFound: $ref: "#/components/examples/AccountNotFound" - # ── Balances ───────────────────────────────────────────────────── - /api/accounts/{accountId}/balances: - get: - operationId: getAccountBalance - tags: - - Balances - summary: Get account balance - description: > - Retrieves the multi-currency balance for the given account, - grouped into `fiat` and `crypto` arrays. - - When an upstream provider is unreachable for a given currency, the - corresponding entry is returned with `synced: false` and `amount: null` - instead of failing the entire request. See - [Errors](/guides/principles/errors) for the standard error envelope. - parameters: - - $ref: "#/components/parameters/AccountId" - - $ref: "#/components/parameters/TraceVersion" - responses: - "200": - description: Account balance. - headers: - X-Request-Id: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/BalanceResponse" - examples: - mixed: - $ref: "#/components/examples/BalanceMixed" - unsyncedSource: - $ref: "#/components/examples/BalanceUnsyncedSource" - "400": - description: Invalid account ID format. - headers: - X-Request-Id: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - invalidUuid: - $ref: "#/components/examples/InvalidAccountIdUuid" - "401": - $ref: "#/components/responses/UnauthorizedError" - "404": - description: No balance found for the given account. - headers: - X-Request-Id: - $ref: "#/components/headers/RequestId" - content: - application/json: - schema: - $ref: "#/components/schemas/ErrorResponse" - examples: - balanceNotFound: - $ref: "#/components/examples/BalanceNotFound" - # ── Documents ──────────────────────────────────────────────────── /api/documents: post: @@ -2356,21 +2419,18 @@ paths: parameters: - $ref: "#/components/parameters/AccountId" - $ref: "#/components/parameters/TraceVersion" - - $ref: "#/components/parameters/PaginationLimit" - - $ref: "#/components/parameters/PaginationCursor" - - $ref: "#/components/parameters/PaginationDirection" - - $ref: "#/components/parameters/PaginationSortOrder" - - $ref: "#/components/parameters/Filters" responses: "200": - description: Paginated list of beneficial owners. + description: List of beneficial owners. headers: X-Request-Id: $ref: "#/components/headers/RequestId" content: application/json: schema: - $ref: "#/components/schemas/UBOList" + type: array + items: + $ref: "#/components/schemas/UBOResponse" "401": $ref: "#/components/responses/UnauthorizedError" "404": diff --git a/docs.json b/docs.json index a5dee3b..ef6d7ab 100644 --- a/docs.json +++ b/docs.json @@ -107,13 +107,6 @@ "api-reference/fx-account/beneficial-owners/remove-ubo" ] }, - { - "group": "Balances", - "icon": "wallet", - "pages": [ - "api-reference/fx-account/balances/get-balance" - ] - }, { "group": "Funding instructions", "icon": "money-bill-transfer",