diff --git a/v2/api-validator/src/config/index.ts b/v2/api-validator/src/config/index.ts index ff3e2b1..3d02b50 100644 --- a/v2/api-validator/src/config/index.ts +++ b/v2/api-validator/src/config/index.ts @@ -221,6 +221,8 @@ const config = convict({ 'fb-provider-liquidity-api.yaml', 'fb-provider-trading-api.yaml', 'fb-provider-transfer-api.yaml', + 'fb-provider-customers-api.yaml', + 'fb-provider-accountsexternal-api.yaml', 'fb-provider-crosstransfer-api.yaml', ], }, diff --git a/v2/openapi/README.md b/v2/openapi/README.md index ac6eb0d..bd5fffe 100644 --- a/v2/openapi/README.md +++ b/v2/openapi/README.md @@ -131,7 +131,10 @@ this response indicates that all the capabilities are supported: "transfersBlockchain": "*", "transfersFiat": "*", "transfersPeerAccounts": "*", - "transfersCrossTransfer": "*", + "crosstransfers": "*", + "crosstransfersOnRamp": '*', + "crosstransfersOffRamp": '*', + "crosstransfersBridging": '*', "trading": "*", "liquidity": "*" } @@ -159,6 +162,15 @@ be replaced by a list of account IDs: Based on the response, Fireblocks platform will use the endpoints specific to each component to discover the specific capabilities for each component. +Note that the `crosstransfers` component is used to define the capabilities for +on-ramp, off-ramp, and bridging without specifying a concrete account. +The actual transfers are executed using the **omnibus account**, which implies +the capabilities of that account. + +For individual accounts (customer accounts), the capabilities are defined in the +`crosstransfersOnRamp`, `crosstransfersOffRamp`, and `crosstransfersBridging` components. +So it is possible to have different capabilities for different customer accounts. + ## Mandatory endpoints All the capability, accounts, and balances endpoints must be always implemented, for all diff --git a/v2/openapi/fb-provider-accountsexternal-api.yaml b/v2/openapi/fb-provider-accountsexternal-api.yaml new file mode 100644 index 0000000..de41c91 --- /dev/null +++ b/v2/openapi/fb-provider-accountsexternal-api.yaml @@ -0,0 +1,420 @@ +openapi: 3.0.0 +info: + title: '[Draft] Fireblocks Provider CrossTransfer API' + version: 0.0.1 + + contact: + name: Fireblocks + url: https://fireblocks.com + +tags: + - name: crosstransfers + description: CrossTransfer API + +x-path-params: + EntityIdPathParam: { $ref: './fb-provider-api.yaml#/components/parameters/EntityIdPathParam' } + SubAccountIdPathParam: { $ref: './fb-provider-api.yaml#/components/parameters/SubAccountIdPathParam' } + +x-query-params: + PaginationLimit: { $ref: './fb-provider-api.yaml#/components/parameters/PaginationLimit' } + PaginationStartingAfter: { $ref: './fb-provider-api.yaml#/components/parameters/PaginationStartingAfter' } + PaginationEndingBefore: { $ref: './fb-provider-api.yaml#/components/parameters/PaginationEndingBefore' } + ListOrderQueryParam: { $ref: './fb-provider-api.yaml#/components/parameters/ListOrderQueryParam' } + +x-header-params: + X-FBAPI-KEY: { $ref: './fb-provider-api.yaml#/components/parameters/X-FBAPI-KEY' } + X-FBAPI-SIGNATURE: { $ref: './fb-provider-api.yaml#/components/parameters/X-FBAPI-SIGNATURE' } + X-FBAPI-NONCE: { $ref: './fb-provider-api.yaml#/components/parameters/X-FBAPI-NONCE' } + X-FBAPI-TIMESTAMP: { $ref: './fb-provider-api.yaml#/components/parameters/X-FBAPI-TIMESTAMP' } + +x-responses: + BadRequestResponse: { $ref: './fb-provider-api.yaml#/components/responses/BadRequestResponse' } + UnauthorizedResponse: { $ref: './fb-provider-api.yaml#/components/responses/UnauthorizedResponse' } + ErrorResponse: { $ref: './fb-provider-api.yaml#/components/responses/ErrorResponse' } + +x-schemas: + Address: { $ref: './fb-provider-api.yaml#/components/schemas/Address' } + AssetReference: { $ref: './fb-provider-api.yaml#/components/schemas/AssetReference' } + AccountHolderDetails: { $ref: './fb-provider-api.yaml#/components/schemas/AccountHolderDetails' } + SwiftAddress: { $ref: './fb-provider-transfer-api.yaml#/components/schemas/SwiftAddress' } + IbanAddress: { $ref: './fb-provider-transfer-api.yaml#/components/schemas/IbanAddress' } + + +paths: + /accounts/external: + get: + operationId: listExternalAccounts + summary: Get list of external accounts + tags: [ accounts ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - $ref: '#/x-query-params/PaginationLimit' + - $ref: '#/x-query-params/PaginationStartingAfter' + - $ref: '#/x-query-params/PaginationEndingBefore' + - in: query + name: customerId + required: false + description: ID of the customer whose external accounts are to be listed. + schema: + type: string + responses: + '200': + description: List of external accounts. + content: + application/json: + schema: + type: object + properties: + accounts: + type: array + items: + $ref: '#/components/schemas/ExternalAccount' + example: + accounts: + - id: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" + customerId: "123e4567-e89b-12d3-a456-426614174000" + servicedBy: "Bank of America" + asset: + nationalCurrencyCode: "USD" + swiftCode: "NWBKGB2L" + routingNumber: "123456789" + transferMethod: "Swift" + accountHolder: + type: "Company" + name: "Acme Inc." + country: "US" + city: "New York" + postalCode: "10001" + address: "123 Main St." + + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + '4XX': + $ref: '#/x-responses/ErrorResponse' + '5XX': + $ref: '#/x-responses/ErrorResponse' + post: + operationId: createExternalAccount + summary: Create a new external account. + tags: [ accounts ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateExternalAccount' + responses: + '200': + description: Sub-account created. + content: + application/json: + schema: + $ref: '#/components/schemas/ExternalAccount' + # examples: + # swiftExternalAccount: + # $ref: '#/components/examples/swiftExternalAccount' + # ibanExternalAccount: + # $ref: '#/components/examples/ibanExternalAccount' + # UsBankExternalAccount: + # $ref: '#/components/examples/usBankExternalAccount' + + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + '4XX': + $ref: '#/x-responses/ErrorResponse' + '5XX': + $ref: '#/x-responses/ErrorResponse' + + /accounts/external/{accountId}: + get: + operationId: getExternalAccountDetails + summary: Get external account details + tags: [ accounts ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - in: path + name: accountId + required: true + description: External account identifier. + schema: + type: string + responses: + '200': + description: External account details. + content: + application/json: + schema: + $ref: '#/components/schemas/ExternalAccount' + # examples: + # swiftExternalAccount: + # $ref: '#/components/examples/swiftExternalAccount' + # iBANExternalAccount: + # $ref: '#/components/examples/ibanExternalAccount' + # usBankExternalAccount: + # $ref: '#/components/examples/usBankExternalAccount' + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + '4XX': + $ref: '#/x-responses/ErrorResponse' + '5XX': + $ref: '#/x-responses/ErrorResponse' + put: + operationId: updateExternalAccount + summary: Update external account details + tags: [ accounts ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - in: path + name: accountId + required: true + description: External account identifier. + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateExternalAccount' + responses: + '200': + description: External account updated. + content: + application/json: + schema: + $ref: '#/components/schemas/ExternalAccount' + # examples: + # swiftExternalAccount: + # $ref: '#/components/examples/swiftExternalAccount' + # iBANExternalAccount: + # $ref: '#/components/examples/ibanExternalAccount' + # usBankExternalAccount: + # $ref: '#/components/examples/usBankExternalAccount' + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + '4XX': + $ref: '#/x-responses/ErrorResponse' + '5XX': + $ref: '#/x-responses/ErrorResponse' + delete: + operationId: deleteExternalAccount + summary: Delete external account + tags: [ accounts ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - in: path + name: accountId + required: true + description: External account identifier. + schema: + type: string + responses: + '200': + description: External account deleted. + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + '4XX': + $ref: '#/x-responses/ErrorResponse' + '5XX': + $ref: '#/x-responses/ErrorResponse' + +components: + schemas: + ExternalAccountId: + description: >- + ID of the account in the external system. + type: string + example: '76a33ed9-8aa2-4781-93f8-d2369c0c2b14' + + CreateExternalAccount: + description: >- + Create a new external account. + type: object + required: [ idempotencyKey, customerId ] + properties: + idempotencyKey: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + description: Unique identifier of the request. + customerId: + description: ID of the customer who will be account holder. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + currency: + $ref: '#/x-schemas/AssetReference' + servicedBy: + type: string + description: Name of the external service provider (e.g. bank name). + example: 'Bank of America' + account: + $ref: '#/components/schemas/ExternalAccountDetails' + accountHolder: + allOf: + - $ref: '#/x-schemas/AccountHolderDetails' + - type: object + required: + - type + properties: + type: + type: string + enum: + - Individual + - Company + + ExternalAccountDetails: + oneOf: + - $ref: '#/x-schemas/SwiftAddress' + - $ref: '#/x-schemas/IbanAddress' + + ExternalAccount: + description: >- + External account details. + allOf: + - $ref: '#/components/schemas/ExternalAccountDetails' + - type: object + required: [ id, customerId, servicedBy ] + properties: + id: + $ref: '#/components/schemas/ExternalAccountId' + customerId: + type: string + description: 'ID of the customer who will be account holder.' + example: 123e4567-e89b-12d3-a456-426614174000 + servicedBy: + type: string + description: 'Name of the external service provider (e.g. bank name).' + example: 'Bank of America' + + UpdateExternalAccount: + description: >- + Update external account details. + type: object + required: [ idempotencyKey ] + properties: + idempotencyKey: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + description: Unique identifier of the request. + account: + type: object + description: Update US bank account details. + properties: + accountType: + description: Type of the account. + type: string + enum: + - Checking + - Savings + example: 'Checking' + accountHolder: + type: object + description: Update account holder address. + properties: + address: + $ref: '#/x-schemas/Address' + examples: {} + # usBankExternalAccount: + # summary: US bank account + # description: >- + # Example of a US bank account. + # value: + # id: "4ff63424-7e09-4cdf-b7f1-da7b7c65eabe" + # customerId: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" + # currency: + # "nationalCurrencyCode": "USD" + # servicedBy: "Bank of America" + # account: + # type: "US" + # accountNumber: "1234567890" + # routingNumber: "123456789" + # accountType: "Checking" + # accountHolder: + # type: "Individual" + # name: "John Doe" + # address: "123 Main St." + # city: "Anytown" + # postalCode: "12345" + # country: "US" + + # ibanExternalAccount: + # summary: iBAN account + # description: >- + # Example of an iBAN account. + # value: + # id: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" + # customerId: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" + # currency: + # "nationalCurrencyCode": "EUR" + # servicedBy: "Deutsche Bank" + # account: + # type: "IBAN" + # accountNumber: "DE89370400440532013000" + # bic: "DEUTDEFF" + # country: "DE" + # accountHolder: + # type: "Individual" + # name: "John Mc. Doe" + # address: "123 Main St." + # city: "Anytown" + # postalCode: "12345" + # country: "DE" + + + # swiftExternalAccount: + # summary: SWIFT account + # description: >- + # Example of a SWIFT account. + # value: + # id: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" + # customerId: "2e7b3b9b-8aa2-4781-93f8-d2369c0c2b14" + # currency: + # "nationalCurrencyCode": "USD" + # servicedBy: "Bank of America" + # account: + # type: "Swift" + # accountNumber: "GB29NWBK60161331926819" + # bic: "NWBKGB2L" + # country: "GB" + # address: + # streetLine1: "1 Churchill Place" + # city: "London" + # postalCode: "E14 5HP" + # country: "GB" + # accountHolder: + # type: "Business" + # businessName: "Acme Inc." + # address: + # streetLine1: "1 Churchill Place" + # city: "London" + # postalCode: "E14 5HP" + # country: "GB" + # category: "Client" + # purpose: "IntraGroupTransfer" + # shortBusinessDescription: "Payment for goods and services" diff --git a/v2/openapi/fb-provider-api.yaml b/v2/openapi/fb-provider-api.yaml index 708fa98..a353a2f 100644 --- a/v2/openapi/fb-provider-api.yaml +++ b/v2/openapi/fb-provider-api.yaml @@ -40,7 +40,9 @@ paths: The capabilities are specified as a map. The map keys are the capability names and the values are lists of account IDs. If all the accounts support - a capability, an asterisk could be used, instead of listing all the accounts. + a capability, an asterisk could be used, instead of listing all the accounts. + Exception is `crosstransfers` where it can accept only `*` or an empty list, + it is not allowed to specify individual accounts. tags: [ capabilities ] parameters: - $ref: '#/components/parameters/X-FBAPI-KEY' @@ -68,9 +70,10 @@ paths: transfersFiat: "*" transfersPeerAccounts: "*" transfersInternal: "*" - transfersOnRamp: "*" - transfersOffRamp: "*" - transfersBridging: "*" + crosstransfers: "*" + crosstransfersOnRamp: "*" + crosstransfersOffRamp: "*" + crosstransfersBridging: "*" trading: "*" liquidity: "*" allAccountsSupportSomeCapabilities: @@ -283,267 +286,6 @@ paths: '5XX': $ref: '#/components/responses/ErrorResponse' - /accounts/external: - get: - operationId: listExternalAccounts - summary: Get list of external accounts - tags: [ accounts ] - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - - $ref: '#/components/parameters/PaginationLimit' - - $ref: '#/components/parameters/PaginationStartingAfter' - - $ref: '#/components/parameters/PaginationEndingBefore' - - in: query - name: customerId - required: false - description: ID of the customer whose external accounts are to be listed. - schema: - type: string - responses: - '200': - description: List of external accounts. - content: - application/json: - schema: - type: object - properties: - accounts: - type: array - items: - $ref: '#/components/schemas/ExternalAccount' - example: - accounts: - - id: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" - customerId: "123e4567-e89b-12d3-a456-426614174000" - currency: - "nationalCurrencyCode": "USD" - servicedBy: "Bank of America" - account: - type: "Swift" - accountNumber: "GB29NWBK60161331926819" - bic: "NWBKGB2L" - country: "GB" - address: - streetLine1: "1 Churchill Place" - city: "London" - postalCode: "E14 5HP" - country: "GB" - accountHolder: - type: "Business" - businessName: "Acme Inc." - address: - streetLine1: "1 Churchill Place" - city: "London" - postalCode: "E14 5HP" - country: "GB" - category: "Client" - purpose: "IntraGroupTransfer" - shortBusinessDescription: "Payment for goods and services" - - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - '4XX': - $ref: '#/components/responses/ErrorResponse' - '5XX': - $ref: '#/components/responses/ErrorResponse' - post: - operationId: createExternalAccount - summary: Create a new external account. - tags: [ accounts ] - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - requestBody: - required: true - content: - application/json: - schema: - type: object - required: [ idempotencyKey, customerId ] - properties: - idempotencyKey: - type: string - example: 123e4567-e89b-12d3-a456-426614174000 - description: Unique identifier of the request. - customerId: - description: ID of the customer who will be account holder. - example: 123e4567-e89b-12d3-a456-426614174000 - type: string - currency: - $ref: '#/components/schemas/AssetReference' - servicedBy: - type: string - description: Name of the external service provider (e.g. bank name). - example: 'Bank of America' - account: - $ref: '#/components/schemas/ExternalAccountDetails' - accountHolder: - oneOf: - - $ref: '#/components/schemas/BusinessAccountHolder' - - $ref: '#/components/schemas/IndividualAccountHolder' - responses: - '200': - description: Sub-account created. - content: - application/json: - schema: - $ref: '#/components/schemas/ExternalAccount' - examples: - swiftExternalAccount: - $ref: '#/components/examples/swiftExternalAccount' - iBANExternalAccount: - $ref: '#/components/examples/iBANExternalAccount' - usBankExternalAccount: - $ref: '#/components/examples/usBankExternalAccount' - - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - '4XX': - $ref: '#/components/responses/ErrorResponse' - '5XX': - $ref: '#/components/responses/ErrorResponse' - - /accounts/external/{accountId}: - get: - operationId: getExternalAccountDetails - summary: Get external account details - tags: [ accounts ] - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - - in: path - name: accountId - required: true - description: External account identifier. - schema: - type: string - responses: - '200': - description: External account details. - content: - application/json: - schema: - $ref: '#/components/schemas/ExternalAccount' - examples: - swiftExternalAccount: - $ref: '#/components/examples/swiftExternalAccount' - iBANExternalAccount: - $ref: '#/components/examples/iBANExternalAccount' - usBankExternalAccount: - $ref: '#/components/examples/usBankExternalAccount' - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - '4XX': - $ref: '#/components/responses/ErrorResponse' - '5XX': - $ref: '#/components/responses/ErrorResponse' - put: - operationId: updateExternalAccount - summary: Update external account details - tags: [ accounts ] - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - - in: path - name: accountId - required: true - description: External account identifier. - schema: - type: string - requestBody: - required: true - content: - application/json: - schema: - type: object - required: [ idempotencyKey ] - properties: - idempotencyKey: - type: string - example: 123e4567-e89b-12d3-a456-426614174000 - description: Unique identifier of the request. - account: - type: object - description: Update US bank account details. - properties: - accountType: - description: Type of the account. - type: string - enum: - - Checking - - Savings - example: 'Checking' - accountHolder: - type: object - description: Update account holder address. - properties: - address: - $ref: '#/components/schemas/Address' - responses: - '200': - description: External account updated. - content: - application/json: - schema: - $ref: '#/components/schemas/ExternalAccount' - examples: - swiftExternalAccount: - $ref: '#/components/examples/swiftExternalAccount' - iBANExternalAccount: - $ref: '#/components/examples/iBANExternalAccount' - usBankExternalAccount: - $ref: '#/components/examples/usBankExternalAccount' - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - '4XX': - $ref: '#/components/responses/ErrorResponse' - '5XX': - $ref: '#/components/responses/ErrorResponse' - delete: - operationId: deleteExternalAccount - summary: Delete external account - tags: [ accounts ] - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - - in: path - name: accountId - required: true - description: External account identifier. - schema: - type: string - responses: - '201': - description: External account deleted. - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - '4XX': - $ref: '#/components/responses/ErrorResponse' - '5XX': - $ref: '#/components/responses/ErrorResponse' - - /accounts/{accountId}/balances: get: @@ -835,6 +577,33 @@ components: $ref: '#/components/schemas/GeneralError' schemas: + AccountHolderDetails: + type: object + required: [ name ] + properties: + name: + description: Full name of the account holder. + type: string + city: + type: string + country: + description: Country code, as specified in ISO 3166-1 alpha-2. + type: string + subdivision: + description: Country administrative subdivision, as specified in ISO 3166-2. + type: string + address: + description: Account holder street address. + type: string + postalCode: + type: string + type: + description: Type of the account holder. + type: string + enum: + - Individual + - Company + GeneralError: description: >- Should be returned only if there in no more specific object. @@ -1009,82 +778,6 @@ components: - $ref: '#/components/schemas/AccountId' - $ref: '#/components/schemas/AccountData' - ExternalAccountRef: - type: object - required: [ type, externalAccountId ] - properties: - type: - type: string - enum: ['ExternalAccount'] - example: 'ExternalAccount' - externalAccountId: - $ref: '#/components/schemas/ExternalAccountId' - - AccountRef: - type: object - required: [ type, accountId ] - properties: - type: - type: string - enum: ['Account'] - example: 'Account' - accountId: - $ref: '#/components/schemas/AccountId' - - ExternalAccountId: - description: >- - ID of the account in the external system. - type: string - example: '76a33ed9-8aa2-4781-93f8-d2369c0c2b14' - - USBankAccountDetails: - type: object - required: [ type, accountNumber, routingNumber ] - properties: - type: - type: string - example: 'US' - description: Type of the account. - enum: - - US - accountNumber: - type: string - example: '123456789' - description: 'Account number of the US bank account.' - routingNumber: - type: string - example: '123456789' - description: 'Routing number of the US bank account.' - accountType: - type: string - enum: - - Checking - - Savings - example: 'Checking' - - iBanAccountDetails: - type: object - required: [ type, accountNumber, bic, country ] - properties: - type: - type: string - description: Type of the account. - example: 'IBAN' - enum: - - IBAN - accountNumber: - description: International Bank Account Number (iBAN). - type: string - example: 'DE89370400440532013000' - bic: - description: Bank Identifier Code (BIC). - type: string - example: 'DEUTDEFF' - country: - description: ISO 3166-1 alpha-2 country code. - type: string - example: 'DE' - Address: type: object required: [ streetLine1, city, country ] @@ -1110,125 +803,6 @@ components: type: string example: 'GB' - SwiftAccountDetails: - type: object - description: >- - Account details for the SWIFT transfer. - required: [ accountNumber, bic , address ] - properties: - type: - type: string - example: 'Swift' - description: Type of the account. - enum: - - Swift - accountNumber: - description: International Bank Account Number (iBAN). - type: string - example: 'GB29NWBK60161331926819' - bic: - description: Bank Identifier Code (BIC). - type: string - example: 'NWBKGB2L' - country: - description: ISO 3166-1 alpha-2 country code. - type: string - example: 'GB' - address: - $ref: '#/components/schemas/Address' - category: - description: The context of business operations - type: string - enum: - - Client - - ParentCompany - - Subsidiary - - Affiliate - - Supplier - purpose: - type: string - description: The nature of the transactions this account will participate in - enum: - - IntraGroupTransfer - - InvoiceForGoodsAndServices - shortBusinessDescription: - type: string - description: How the business uses the funds - example: 'Payment for goods and services' - - ExternalAccountDetails: - oneOf: - - $ref: '#/components/schemas/SwiftAccountDetails' - - $ref: '#/components/schemas/USBankAccountDetails' - - $ref: '#/components/schemas/iBanAccountDetails' - discriminator: - propertyName: type - mapping: - Swift: '#/components/schemas/SwiftAccountDetails' - US: '#/components/schemas/USBankAccountDetails' - IBAN: '#/components/schemas/iBanAccountDetails' - - IndividualAccountHolder: - description: >- - Individual account holder details. - type: object - required: [ type, firstName, lastName, address ] - properties: - type: - type: string - enum: - - Individual - firstName: - type: string - lastName: - type: string - address: - $ref: '#/components/schemas/Address' - - BusinessAccountHolder: - description: >- - Business account holder details. - type: object - required: [ type, businessName, address ] - properties: - type: - type: string - enum: - - Business - businessName: - type: string - example: 'Acme Inc.' - address: - $ref: '#/components/schemas/Address' - - ExternalAccount: - type: object - required: [ id, currency, customerId, servicedBy, account, accountHolder ] - properties: - id: - $ref: '#/components/schemas/ExternalAccountId' - currency: - $ref: '#/components/schemas/AssetReference' - customerId: - type: string - description: 'ID of the customer who will be account holder.' - example: 123e4567-e89b-12d3-a456-426614174000 - servicedBy: - type: string - description: 'Name of the external service provider (e.g. bank name).' - example: 'Bank of America' - account: - $ref: '#/components/schemas/ExternalAccountDetails' - accountHolder: - oneOf: - - $ref: '#/components/schemas/BusinessAccountHolder' - - $ref: '#/components/schemas/IndividualAccountHolder' - discriminator: - propertyName: type - mapping: - Individual: '#/components/schemas/IndividualAccountHolder' - Business: '#/components/schemas/BusinessAccountHolder' - Balances: type: array description: >- @@ -1371,16 +945,6 @@ components: - $ref: '#/components/schemas/NativeCryptocurrency' - $ref: '#/components/schemas/OtherAssetReference' - FiatRail: - type: string - example: 'SWIFT' - enum: - - ACH - - SEPA - - SWIFT - - IBAN - - Wire - Blockchain: type: string enum: @@ -1811,86 +1375,3 @@ components: - ZWN - ZWR - examples: - usBankExternalAccount: - summary: US bank account - description: >- - Example of a US bank account. - value: - id: "4ff63424-7e09-4cdf-b7f1-da7b7c65eabe" - customerId: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" - currency: - "nationalCurrencyCode": "USD" - servicedBy: "Bank of America" - account: - type: "US" - accountNumber: "1234567890" - routingNumber: "123456789" - accountType: "Checking" - accountHolder: - type: "Individual" - firstName: "John" - lastName: "Doe" - address: - streetLine1: "1 Churchill Place" - city: "London" - postalCode: "E14 5HP" - country: "GB" - - iBANExternalAccount: - summary: iBAN account - description: >- - Example of an iBAN account. - value: - id: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" - customerId: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" - currency: - "nationalCurrencyCode": "EUR" - servicedBy: "Deutsche Bank" - account: - type: "IBAN" - accountNumber: "DE89370400440532013000" - bic: "DEUTDEFF" - country: "DE" - accountHolder: - type: "Individual" - firstName: "John" - lastName: "Doe" - address: - streetLine1: "1 Churchill Place" - city: "London" - postalCode: "E14 5HP" - country: "GB" - - swiftExternalAccount: - summary: SWIFT account - description: >- - Example of a SWIFT account. - value: - id: "76a33ed9-8aa2-4781-93f8-d2369c0c2b14" - customerId: "2e7b3b9b-8aa2-4781-93f8-d2369c0c2b14" - currency: - "nationalCurrencyCode": "USD" - servicedBy: "Bank of America" - account: - type: "Swift" - accountNumber: "GB29NWBK60161331926819" - bic: "NWBKGB2L" - country: "GB" - address: - streetLine1: "1 Churchill Place" - city: "London" - postalCode: "E14 5HP" - country: "GB" - accountHolder: - type: "Business" - businessName: "Acme Inc." - address: - streetLine1: "1 Churchill Place" - city: "London" - postalCode: "E14 5HP" - country: "GB" - category: "Client" - purpose: "IntraGroupTransfer" - shortBusinessDescription: "Payment for goods and services" - diff --git a/v2/openapi/fb-provider-crosstransfer-api.yaml b/v2/openapi/fb-provider-crosstransfer-api.yaml index 4047e14..39b5e52 100644 --- a/v2/openapi/fb-provider-crosstransfer-api.yaml +++ b/v2/openapi/fb-provider-crosstransfer-api.yaml @@ -8,8 +8,6 @@ info: url: https://fireblocks.com tags: - - name: capabilities - description: Server capabilities discovery operations. - name: crosstransfers description: Fund transfers from fiat to digital assets, digital assets to fiat or digital to digital assets. @@ -37,16 +35,15 @@ x-schemas: NationalCurrency: { $ref: './fb-provider-api.yaml#/components/schemas/NationalCurrency' } NativeCryptocurrency: { $ref: './fb-provider-api.yaml#/components/schemas/NativeCryptocurrency' } AccountId: { './fb-provider-api.yaml#/components/schemas/AccountId' } - AccountRef: { './fb-provider-api.yaml#/components/schemas/AccountRef' } - ExternalAccountRef: { './fb-provider-api.yaml#/components/schemas/ExternalAccountRef' } - FiatRail: { './fb-provider-api.yaml#/components/schemas/FiatRail' } + + x-responses: BadRequestResponse: { $ref: './fb-provider-api.yaml#/components/responses/BadRequestResponse' } UnauthorizedResponse: { $ref: './fb-provider-api.yaml#/components/responses/UnauthorizedResponse' } ErrorResponse: { $ref: './fb-provider-api.yaml#/components/responses/ErrorResponse' } paths: - /crosstransfer/onramp: + /crosstransfers/onramp/standingorders: post: operationId: createCrossTransferOnRampRouting summary: >- @@ -83,7 +80,7 @@ paths: $ref: '#/x-responses/ErrorResponse' - /crosstransfer/offramp: + /crosstransfers/offramp/standingorders: post: operationId: createCrossTransferOffRampRouting summary: >- @@ -118,9 +115,9 @@ paths: '5XX': $ref: '#/x-responses/ErrorResponse' - /crosstransfer/bridging: + /crosstransfers/bridging/standingorders: post: - operationId: createCrossTransferBridging + operationId: createCrossTransferBridgingRouting summary: >- Creates deposit-only crypto account as a source, configures trigger and stores payment instruction details about destination crypto address. As a result, the user will be @@ -156,6 +153,24 @@ paths: components: schemas: + CryptoPaymentAccountParams: + allOf: + - $ref: '#/x-schemas/NativeCryptocurrency' + type: object + required: [ developerFee ] + properties: + developerFee: + $ref: './fb-provider-api.yaml#/components/schemas/PositiveAmount' + + FiatPaymentAccountParams: + allOf: + - $ref: '#/x-schemas/NationalCurrency' + type: object + required: [ developerFee ] + properties: + developerFee: + $ref: './fb-provider-api.yaml#/components/schemas/PositiveAmount' + CreateBridgingRequest: type: object required: [ idempotencyKey, customerId, source, destination, ] @@ -167,9 +182,10 @@ components: type: string example: '76a33ed9-8aa2-4781-93f8-d2369c0c2b14' source: - $ref: '#/components/schemas/BridgingSourceParameters' + $ref: '#/components/schemas/CryptoPaymentAccountParams' destination: $ref: '#/components/schemas/BridgingDestination' + BridgingDestination: type: object required: @@ -187,16 +203,7 @@ components: memo: description: Memo field for the destination address. Required for some blockchains. type: string - BridgingSourceParameters: - type: object - required: [ currency ] - properties: - chain: - $ref: '#/x-schemas/Blockchain' - currency: - $ref: '#/x-schemas/NativeCryptocurrency' - developerFee: - $ref: './fb-provider-api.yaml#/components/schemas/PositiveAmount' + CreateOnRampRoutingRequest: type: object required: @@ -212,9 +219,10 @@ components: type: string example: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 source: - $ref: '#/components/schemas/OnRampSourceParameters' + $ref: '#/components/schemas/FiatPaymentAccountParams' destination: $ref: '#/components/schemas/OnRampDestination' + OnRampDestination: type: object required: @@ -232,62 +240,18 @@ components: memo: description: Memo field for the destination address. Required for some blockchains. type: string - OnRampSourceParameters: - type: object - required: - - currency - properties: - currency: - $ref: '#/x-schemas/NativeCryptocurrency' - developerFee: - $ref: '#/x-schemas/PositiveAmount' - OffRampSourceParameters: - type: object - required: [ chain, currency ] - properties: - chain: - $ref: '#/x-schemas/Blockchain' - currency: - $ref: '#/x-schemas/NativeCryptocurrency' - developerFee: - $ref: '#/x-schemas/PositiveAmount' - returnAddress: - type: string - description: >- - Blockchain address to return the funds in case of a failed transaction. - MUST be on same blockchain network that is selected in the chain field. - Field will be ignored in case of Stellar chain. + OffRampDestination: type: object - required: [ rail, currency, account ] properties: - rail: - $ref: '#/x-schemas/FiatRail' - currency: - $ref: '#/x-schemas/NationalCurrency' - message: - type: string - description: >- - A message to be sent with a wire transfer. - It can have at most 3 lines (separated by "\n"), - each line with a max length of 35 chars - maxLength: 109 + externalAccountId: + $ref: '#/x-schemas/AccountId' + accountId: + $ref: '#/x-schemas/AccountId' reference: type: string - description: >- - If rail is SEPA, this is the SEPA reference and must be from 6 to 140 characters. - The allowed characters are a-z, A-Z, 0-9, spaces, ampersand (&), hyphen (-), - full stop (.), and solidus (/). If rail is ACH, this is the ACH reference and - can be at most 10 characters, A-Z, a-z, 0-9, and spaces. - account: - oneOf: - - $ref: '#/x-schemas/ExternalAccountRef' - - $ref: '#/x-schemas/AccountRef' - discriminator: - propertyName: type - mapping: - ExternalAccount: '#/x-schemas/ExternalAccountRef' - Account: '#/components/schemas/AccountRef' + description: Optional reference to be included in transaction. + CreateOffRampRoutingRequest: type: object required: [ idempotencyKey, customerId, source, destination, ] @@ -299,6 +263,6 @@ components: type: string example: '76a33ed9-8aa2-4781-93f8-d2369c0c2b14' source: - $ref: '#/components/schemas/OffRampSourceParameters' + $ref: '#/components/schemas/CryptoPaymentAccountParams' destination: $ref: '#/components/schemas/OffRampDestination' diff --git a/v2/openapi/fb-provider-customers-api.yaml b/v2/openapi/fb-provider-customers-api.yaml new file mode 100644 index 0000000..387576b --- /dev/null +++ b/v2/openapi/fb-provider-customers-api.yaml @@ -0,0 +1,413 @@ +openapi: 3.0.0 +info: + title: 'FB Provider Customers API' + version: 0.0.1 + contact: + name: Fireblocks + url: https://fireblocks.com +tags: + - name: customers + description: |- + Customers API + This API is used to manage customers and their KYC processes. Kyc processes can be started, updated and checked for status. + +x-path-params: + EntityIdPathParam: { $ref: './fb-provider-api.yaml#/components/parameters/EntityIdPathParam' } + SubAccountIdPathParam: { $ref: './fb-provider-api.yaml#/components/parameters/SubAccountIdPathParam' } + +x-query-params: + PaginationLimit: { $ref: './fb-provider-api.yaml#/components/parameters/PaginationLimit' } + PaginationStartingAfter: { $ref: './fb-provider-api.yaml#/components/parameters/PaginationStartingAfter' } + PaginationEndingBefore: { $ref: './fb-provider-api.yaml#/components/parameters/PaginationEndingBefore' } + ListOrderQueryParam: { $ref: './fb-provider-api.yaml#/components/parameters/ListOrderQueryParam' } + + +x-header-params: + X-FBAPI-KEY: { $ref: './fb-provider-api.yaml#/components/parameters/X-FBAPI-KEY' } + X-FBAPI-NONCE: { $ref: './fb-provider-api.yaml#/components/parameters/X-FBAPI-NONCE' } + X-FBAPI-SIGNATURE: { $ref: './fb-provider-api.yaml#/components/parameters/X-FBAPI-SIGNATURE' } + X-FBAPI-TIMESTAMP: { $ref: './fb-provider-api.yaml#/components/parameters/X-FBAPI-TIMESTAMP' } + +x-responses: + BadRequestResponse: { $ref: './fb-provider-api.yaml#/components/responses/BadRequestResponse' } + UnauthorizedResponse: { $ref: './fb-provider-api.yaml#/components/responses/UnauthorizedResponse' } + ErrorResponse: { $ref: './fb-provider-api.yaml#/components/responses/ErrorResponse' } + + +paths: + /customers: + get: + operationId: listCustomers + summary: List customers + tags: [ customers ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - $ref: '#/x-query-params/PaginationLimit' + - $ref: '#/x-query-params/PaginationStartingAfter' + - $ref: '#/x-query-params/PaginationEndingBefore' + - $ref: '#/x-query-params/ListOrderQueryParam' + responses: + '200': + description: List of customers. + content: + application/json: + schema: + $ref: '#/components/schemas/CustomerList' + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + 'default': + $ref: '#/x-responses/ErrorResponse' + /customers/{customerId}: + get: + operationId: getCustomer + summary: Get customer details + tags: [ customers ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - name: customerId + in: path + required: true + schema: + type: string + format: uuid + description: Customer ID + responses: + '200': + description: Customer details. + content: + application/json: + schema: + $ref: '#/components/schemas/Customer' + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + 'default': + $ref: '#/x-responses/ErrorResponse' + /customers/{customerId}/kyc: + put: + operationId: updateCustomerKycTier + summary: Update customer KYC tier + tags: [ customers ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - name: customerId + in: path + required: true + schema: + type: string + format: uuid + description: Customer ID + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CustomerUpdateKycTier' + responses: + '200': + description: KYC tier upgrade process started. + content: + application/json: + schema: + $ref: '#/components/schemas/CustomerKycTierResponse' + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + 'default': + $ref: '#/x-responses/ErrorResponse' + /kyc: + get: + operationId: listKycProcesses + summary: List KYC processes + tags: [ customers ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - $ref: '#/x-query-params/PaginationLimit' + - $ref: '#/x-query-params/PaginationStartingAfter' + - $ref: '#/x-query-params/PaginationEndingBefore' + - $ref: '#/x-query-params/ListOrderQueryParam' + responses: + '200': + description: List of KYC processes. + content: + application/json: + schema: + type: object + properties: + kycProcesses: + type: array + items: + $ref: '#/components/schemas/CustomerKycTierResponse' + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + 'default': + $ref: '#/x-responses/ErrorResponse' + post: + operationId: registerCustomer + summary: Register a new customer + tags: [ customers ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterCustomer' + responses: + '200': + description: Customer registration process started. + content: + application/json: + schema: + $ref: '#/components/schemas/CustomerKycTierResponse' + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + 'default': + $ref: '#/x-responses/ErrorResponse' + /kyc/{kycId}: + get: + operationId: getKycProcessStatus + summary: Get KYC process details and status + tags: [ customers ] + parameters: + - $ref: '#/x-header-params/X-FBAPI-KEY' + - $ref: '#/x-header-params/X-FBAPI-NONCE' + - $ref: '#/x-header-params/X-FBAPI-SIGNATURE' + - $ref: '#/x-header-params/X-FBAPI-TIMESTAMP' + - name: kycId + in: path + required: true + schema: + type: string + format: uuid + description: KYC process reference ID + responses: + '200': + description: KYC process status. + content: + application/json: + schema: + $ref: '#/components/schemas/CustomerKycTierResponse' + '400': + $ref: '#/x-responses/BadRequestResponse' + '401': + $ref: '#/x-responses/UnauthorizedResponse' + 'default': + $ref: '#/x-responses/ErrorResponse' + +components: + schemas: + CustomerList: + type: object + properties: + customers: + type: array + items: + $ref: '#/components/schemas/Customer' + required: + - customers + + CustomerStatus: + type: string + description: |- + Status of the customer: + - Draft: Customer is in draft state. Not yet submitted for review. + - Pending: Customer details are submitted for review. Awaiting approval. + - Incomplete: Customer details are incomplete. KYC is not yet completed requres that customer resolve input issues. + - InReview: Customer details are under review. + - Active: Customer is approved and active. + - Inactive: Customer is inactive and cannot be used. + - Rejected: Customer is rejected and cannot be used. + enum: + - Draft + - Pending + - Incomplete + - InReview + - Active + - Inactive + - Rejected + + CustomerType: + type: string + description: |- + Type of the customer: + - Individual: Customer is an individual person. + - Business: Customer is a business entity. + enum: + - Individual + - Business + + Customer: + type: object + properties: + id: + type: string + description: Customer ID + format: uuid + name: + type: string + description: Customer full name + email: + type: string + description: Customer email address + status: + $ref: '#/components/schemas/CustomerStatus' + type: + $ref: '#/components/schemas/CustomerType' + required: + - id + - name + - email + - status + - type + + RegisterCustomer: + type: object + properties: + idempotencyKey: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + description: Unique identifier of the request. Used to prevent duplicate requests. + name: + type: string + description: Customer full name + email: + type: string + description: Customer email address + type: + $ref: '#/components/schemas/CustomerType' + kycTier: + type: string + description: KYC tier validation to use when registering the customer + required: + - idempotencyKey + - name + - email + - type + + CustomerUpdateKycTier: + type: object + properties: + idempotencyKey: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + description: Unique identifier of the request. Used to prevent duplicate requests. + kycTier: + type: string + description: KYC tier to which the customer is upgrading + required: + - idempotencyKey + - kycTier + + CustomerKycTierResponse: + type: object + required: [ id, name, email, type, kycTier, kycLink, status, tosLink, tosStatus ] + properties: + id: + type: string + description: ID unique for each started KYC process. Registration or KYC tier upgrade. + format: uuid + customerId: + type: string + description: |- + Customer ID. + If the KYC process is for a new customer, this field is empty until the + customer is registered and first kyc tier is set. + format: uuid + name: + type: string + description: Customer full name + # this must accept all letters, cirilc, latin, chinese, etc then numbers and apostrophes dashes and spaces + example: 'John Doe' + email: + type: string + description: Customer email address + example: 'john.doe@example.com' + type: + $ref: '#/components/schemas/CustomerType' + kycTier: + type: string + description: KYC tier to which the customer is upgrading + example: 'Tier 2' + kycLink: + type: string + description: URL to the KYC process + status: + $ref: '#/components/schemas/KycStatus' + tosLink: + type: string + description: URL to the terms of service agreement + tosStatus: + $ref: '#/components/schemas/TosStatus' + rejection: + description: |- + KYC rejection details. + type: array + items: + $ref: '#/components/schemas/KycRejectionReason' + + TosStatus: + type: string + description: |- + Status of the terms of service agreement: + - Pending: Terms of service agreement is pending customer acceptance. + - Accepted: Terms of service agreement is accepted by the customer. + enum: + - Pending + - Accepted + + KycRejectionReason: + type: object + description: |- + Reason for KYC rejection. + properties: + reason: + type: string + description: Reason for KYC rejection + details: + type: string + description: Additional details about the rejection reason + rejectedAt: + type: string + description: Date and time when the KYC was rejected + format: date-time + + KycStatus: + description: |- + Status of the KYC process: + - Pending: KYC is pending. + - InReview: KYC is under review. + - AwaitingCustomer: KYC is awaiting customer input. + - Approved: KYC is approved. + - Rejected: KYC is rejected. + type: string + enum: + - Pending + - InReview + - AwaitingCustomer + - Approved + - Rejected diff --git a/v2/openapi/fb-provider-transfer-api.yaml b/v2/openapi/fb-provider-transfer-api.yaml index 2e980e4..0a8276c 100644 --- a/v2/openapi/fb-provider-transfer-api.yaml +++ b/v2/openapi/fb-provider-transfer-api.yaml @@ -766,26 +766,6 @@ components: $ref: '#/components/schemas/Withdrawal' schemas: - AccountHolderDetails: - type: object - required: [ name ] - properties: - name: - description: Full name of the account holder. - type: string - city: - type: string - country: - description: Country code, as specified in ISO 3166-1 alpha-2. - type: string - subdivision: - description: Country administrative subdivision, as specified in ISO 3166-2. - type: string - address: - description: Account holder street address. - type: string - postalCode: - type: string Iban: type: string @@ -807,7 +787,7 @@ components: required: [ accountHolder, iban ] properties: accountHolder: - $ref: '#/components/schemas/AccountHolderDetails' + $ref: './fb-provider-api.yaml#/components/schemas/AccountHolderDetails' iban: $ref: '#/components/schemas/Iban' @@ -848,7 +828,7 @@ components: required: [ accountHolder, swiftCode, routingNumber ] properties: accountHolder: - $ref: '#/components/schemas/AccountHolderDetails' + $ref: './fb-provider-api.yaml#/components/schemas/AccountHolderDetails' swiftCode: $ref: '#/components/schemas/SwiftCode' routingNumber: diff --git a/v2/openapi/fb-unified-openapi.yaml b/v2/openapi/fb-unified-openapi.yaml index d92e100..4282822 100644 --- a/v2/openapi/fb-unified-openapi.yaml +++ b/v2/openapi/fb-unified-openapi.yaml @@ -39,8 +39,12 @@ tags: description: Transfers to a peer account managed by the same provider. - name: transfersInternal description: Transfers to a sub account in the same account. + - name: customers + description: |- + Customers API + This API is used to manage customers and their KYC processes. Kyc processes can be started, updated and checked for status. - name: crosstransfers - description: Fund transfers from fiat to digital assets, digital assets to fiat or digital to digital assets. + description: CrossTransfer API paths: /capabilities: get: @@ -48,7 +52,7 @@ paths: summary: Describe server capabilities description: |- Returns the API version and all the capabilities that the server supports. - The capabilities are specified as a map. The map keys are the capability names and the values are lists of account IDs. If all the accounts support a capability, an asterisk could be used, instead of listing all the accounts. + The capabilities are specified as a map. The map keys are the capability names and the values are lists of account IDs. If all the accounts support a capability, an asterisk could be used, instead of listing all the accounts. Exception is `crosstransfers` where it can accept only `*` or an empty list, it is not allowed to specify individual accounts. tags: - capabilities parameters: @@ -76,9 +80,10 @@ paths: transfersFiat: '*' transfersPeerAccounts: '*' transfersInternal: '*' - transfersOnRamp: '*' - transfersOffRamp: '*' - transfersBridging: '*' + crosstransfers: '*' + crosstransfersOnRamp: '*' + crosstransfersOffRamp: '*' + crosstransfersBridging: '*' trading: '*' liquidity: '*' allAccountsSupportSomeCapabilities: @@ -280,270 +285,6 @@ paths: $ref: '#/components/responses/ErrorResponse' 5XX: $ref: '#/components/responses/ErrorResponse' - /accounts/external: - get: - operationId: listExternalAccounts - summary: Get list of external accounts - tags: - - accounts - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - - $ref: '#/components/parameters/PaginationLimit' - - $ref: '#/components/parameters/PaginationStartingAfter' - - $ref: '#/components/parameters/PaginationEndingBefore' - - in: query - name: customerId - required: false - description: ID of the customer whose external accounts are to be listed. - schema: - type: string - responses: - '200': - description: List of external accounts. - content: - application/json: - schema: - type: object - properties: - accounts: - type: array - items: - $ref: '#/components/schemas/ExternalAccount' - example: - accounts: - - id: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 - customerId: 123e4567-e89b-12d3-a456-426614174000 - currency: - nationalCurrencyCode: USD - servicedBy: Bank of America - account: - type: Swift - accountNumber: GB29NWBK60161331926819 - bic: NWBKGB2L - country: GB - address: - streetLine1: 1 Churchill Place - city: London - postalCode: E14 5HP - country: GB - accountHolder: - type: Business - businessName: Acme Inc. - address: - streetLine1: 1 Churchill Place - city: London - postalCode: E14 5HP - country: GB - category: Client - purpose: IntraGroupTransfer - shortBusinessDescription: Payment for goods and services - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - 4XX: - $ref: '#/components/responses/ErrorResponse' - 5XX: - $ref: '#/components/responses/ErrorResponse' - post: - operationId: createExternalAccount - summary: Create a new external account. - tags: - - accounts - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - requestBody: - required: true - content: - application/json: - schema: - type: object - required: - - idempotencyKey - - customerId - properties: - idempotencyKey: - type: string - example: 123e4567-e89b-12d3-a456-426614174000 - description: Unique identifier of the request. - customerId: - description: ID of the customer who will be account holder. - example: 123e4567-e89b-12d3-a456-426614174000 - type: string - currency: - $ref: '#/components/schemas/AssetReference' - servicedBy: - type: string - description: Name of the external service provider (e.g. bank name). - example: Bank of America - account: - $ref: '#/components/schemas/ExternalAccountDetails' - accountHolder: - oneOf: - - $ref: '#/components/schemas/BusinessAccountHolder' - - $ref: '#/components/schemas/IndividualAccountHolder' - responses: - '200': - description: Sub-account created. - content: - application/json: - schema: - $ref: '#/components/schemas/ExternalAccount' - examples: - swiftExternalAccount: - $ref: '#/components/examples/swiftExternalAccount' - iBANExternalAccount: - $ref: '#/components/examples/iBANExternalAccount' - usBankExternalAccount: - $ref: '#/components/examples/usBankExternalAccount' - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - 4XX: - $ref: '#/components/responses/ErrorResponse' - 5XX: - $ref: '#/components/responses/ErrorResponse' - /accounts/external/{accountId}: - get: - operationId: getExternalAccountDetails - summary: Get external account details - tags: - - accounts - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - - in: path - name: accountId - required: true - description: External account identifier. - schema: - type: string - responses: - '200': - description: External account details. - content: - application/json: - schema: - $ref: '#/components/schemas/ExternalAccount' - examples: - swiftExternalAccount: - $ref: '#/components/examples/swiftExternalAccount' - iBANExternalAccount: - $ref: '#/components/examples/iBANExternalAccount' - usBankExternalAccount: - $ref: '#/components/examples/usBankExternalAccount' - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - 4XX: - $ref: '#/components/responses/ErrorResponse' - 5XX: - $ref: '#/components/responses/ErrorResponse' - put: - operationId: updateExternalAccount - summary: Update external account details - tags: - - accounts - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - - in: path - name: accountId - required: true - description: External account identifier. - schema: - type: string - requestBody: - required: true - content: - application/json: - schema: - type: object - required: - - idempotencyKey - properties: - idempotencyKey: - type: string - example: 123e4567-e89b-12d3-a456-426614174000 - description: Unique identifier of the request. - account: - type: object - description: Update US bank account details. - properties: - accountType: - description: Type of the account. - type: string - enum: - - Checking - - Savings - example: Checking - accountHolder: - type: object - description: Update account holder address. - properties: - address: - $ref: '#/components/schemas/Address' - responses: - '200': - description: External account updated. - content: - application/json: - schema: - $ref: '#/components/schemas/ExternalAccount' - examples: - swiftExternalAccount: - $ref: '#/components/examples/swiftExternalAccount' - iBANExternalAccount: - $ref: '#/components/examples/iBANExternalAccount' - usBankExternalAccount: - $ref: '#/components/examples/usBankExternalAccount' - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - 4XX: - $ref: '#/components/responses/ErrorResponse' - 5XX: - $ref: '#/components/responses/ErrorResponse' - delete: - operationId: deleteExternalAccount - summary: Delete external account - tags: - - accounts - parameters: - - $ref: '#/components/parameters/X-FBAPI-KEY' - - $ref: '#/components/parameters/X-FBAPI-NONCE' - - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - - in: path - name: accountId - required: true - description: External account identifier. - schema: - type: string - responses: - '201': - description: External account deleted. - '400': - $ref: '#/components/responses/BadRequestResponse' - '401': - $ref: '#/components/responses/UnauthorizedResponse' - 4XX: - $ref: '#/components/responses/ErrorResponse' - 5XX: - $ref: '#/components/responses/ErrorResponse' /accounts/{accountId}/balances: get: operationId: getBalances @@ -1959,99 +1700,472 @@ paths: $ref: '#/components/responses/ErrorResponse' 5XX: $ref: '#/components/responses/ErrorResponse' - /crosstransfer/onramp: - post: - operationId: createCrossTransferOnRampRouting - summary: Creates deposit-only fiat account as a source, configures trigger and stores payment instruction details about destination crypto account. As a result, the user will be able to deposit fiat to the source account and receive payment in crypto to the destination account. + /customers: + get: + operationId: listCustomers + summary: List customers tags: - - crosstransfers + - customers parameters: - $ref: '#/components/parameters/X-FBAPI-KEY' - $ref: '#/components/parameters/X-FBAPI-NONCE' - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateOnRampRoutingRequest' + - $ref: '#/components/parameters/PaginationLimit' + - $ref: '#/components/parameters/PaginationStartingAfter' + - $ref: '#/components/parameters/PaginationEndingBefore' + - $ref: '#/components/parameters/ListOrderQueryParam' responses: '200': - description: Sub-account created. + description: List of customers. content: application/json: schema: - $ref: '#/components/schemas/AccountId' + $ref: '#/components/schemas/CustomerList' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' - 4XX: + default: $ref: '#/components/responses/ErrorResponse' - 5XX: + /customers/{customerId}: + get: + operationId: getCustomer + summary: Get customer details + tags: + - customers + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + - name: customerId + in: path + required: true + schema: + type: string + format: uuid + description: Customer ID + responses: + '200': + description: Customer details. + content: + application/json: + schema: + $ref: '#/components/schemas/Customer' + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + default: $ref: '#/components/responses/ErrorResponse' - /crosstransfer/offramp: - post: - operationId: createCrossTransferOffRampRouting - summary: Creates deposit-only crypto account as a source, configures trigger and stores payment instruction details about destination fiat account. As a result, the user will be able to deposit crypto to the source account and receive fiat to the destination account. + /customers/{customerId}/kyc: + put: + operationId: updateCustomerKycTier + summary: Update customer KYC tier tags: - - crosstransfers + - customers parameters: - $ref: '#/components/parameters/X-FBAPI-KEY' - $ref: '#/components/parameters/X-FBAPI-NONCE' - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + - name: customerId + in: path + required: true + schema: + type: string + format: uuid + description: Customer ID requestBody: required: true content: application/json: schema: - $ref: '#/components/schemas/CreateOffRampRoutingRequest' + $ref: '#/components/schemas/CustomerUpdateKycTier' responses: '200': - description: Sub-account created. + description: KYC tier upgrade process started. content: application/json: schema: - $ref: '#/components/schemas/AccountId' + $ref: '#/components/schemas/CustomerKycTierResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' - 4XX: - $ref: '#/components/responses/ErrorResponse' - 5XX: + default: $ref: '#/components/responses/ErrorResponse' - /crosstransfer/bridging: - post: - operationId: createCrossTransferBridging - summary: Creates deposit-only crypto account as a source, configures trigger and stores payment instruction details about destination crypto address. As a result, the user will be able to deposit crypto to the source account and receive exchanged value to destination address in selected cryptocurrency. + /kyc: + get: + operationId: listKycProcesses + summary: List KYC processes tags: - - crosstransfers + - customers parameters: - $ref: '#/components/parameters/X-FBAPI-KEY' - $ref: '#/components/parameters/X-FBAPI-NONCE' - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' - requestBody: - required: true - content: - application/json: - schema: - $ref: '#/components/schemas/CreateBridgingRequest' + - $ref: '#/components/parameters/PaginationLimit' + - $ref: '#/components/parameters/PaginationStartingAfter' + - $ref: '#/components/parameters/PaginationEndingBefore' + - $ref: '#/components/parameters/ListOrderQueryParam' responses: '200': - description: Sub-account created. + description: List of KYC processes. content: application/json: schema: - $ref: '#/components/schemas/AccountId' + type: object + properties: + kycProcesses: + type: array + items: + $ref: '#/components/schemas/CustomerKycTierResponse' '400': $ref: '#/components/responses/BadRequestResponse' '401': $ref: '#/components/responses/UnauthorizedResponse' - 4XX: + default: + $ref: '#/components/responses/ErrorResponse' + post: + operationId: registerCustomer + summary: Register a new customer + tags: + - customers + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterCustomer' + responses: + '200': + description: Customer registration process started. + content: + application/json: + schema: + $ref: '#/components/schemas/CustomerKycTierResponse' + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + default: + $ref: '#/components/responses/ErrorResponse' + /kyc/{kycId}: + get: + operationId: getKycProcessStatus + summary: Get KYC process details and status + tags: + - customers + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + - name: kycId + in: path + required: true + schema: + type: string + format: uuid + description: KYC process reference ID + responses: + '200': + description: KYC process status. + content: + application/json: + schema: + $ref: '#/components/schemas/CustomerKycTierResponse' + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + default: + $ref: '#/components/responses/ErrorResponse' + /accounts/external: + get: + operationId: listExternalAccounts + summary: Get list of external accounts + tags: + - accounts + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - $ref: '#/components/parameters/PaginationLimit' + - $ref: '#/components/parameters/PaginationStartingAfter' + - $ref: '#/components/parameters/PaginationEndingBefore' + - in: query + name: customerId + required: false + description: ID of the customer whose external accounts are to be listed. + schema: + type: string + responses: + '200': + description: List of external accounts. + content: + application/json: + schema: + type: object + properties: + accounts: + type: array + items: + $ref: '#/components/schemas/ExternalAccount' + example: + accounts: + - id: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 + customerId: 123e4567-e89b-12d3-a456-426614174000 + servicedBy: Bank of America + asset: + nationalCurrencyCode: USD + swiftCode: NWBKGB2L + routingNumber: '123456789' + transferMethod: Swift + accountHolder: + type: Company + name: Acme Inc. + country: US + city: New York + postalCode: '10001' + address: 123 Main St. + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + 4XX: + $ref: '#/components/responses/ErrorResponse' + 5XX: + $ref: '#/components/responses/ErrorResponse' + post: + operationId: createExternalAccount + summary: Create a new external account. + tags: + - accounts + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateExternalAccount' + responses: + '200': + description: Sub-account created. + content: + application/json: + schema: + $ref: '#/components/schemas/ExternalAccount' + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + 4XX: + $ref: '#/components/responses/ErrorResponse' + 5XX: + $ref: '#/components/responses/ErrorResponse' + /accounts/external/{accountId}: + get: + operationId: getExternalAccountDetails + summary: Get external account details + tags: + - accounts + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - in: path + name: accountId + required: true + description: External account identifier. + schema: + type: string + responses: + '200': + description: External account details. + content: + application/json: + schema: + $ref: '#/components/schemas/ExternalAccount' + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + 4XX: + $ref: '#/components/responses/ErrorResponse' + 5XX: + $ref: '#/components/responses/ErrorResponse' + put: + operationId: updateExternalAccount + summary: Update external account details + tags: + - accounts + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - in: path + name: accountId + required: true + description: External account identifier. + schema: + type: string + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateExternalAccount' + responses: + '200': + description: External account updated. + content: + application/json: + schema: + $ref: '#/components/schemas/ExternalAccount' + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + 4XX: + $ref: '#/components/responses/ErrorResponse' + 5XX: + $ref: '#/components/responses/ErrorResponse' + delete: + operationId: deleteExternalAccount + summary: Delete external account + tags: + - accounts + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - in: path + name: accountId + required: true + description: External account identifier. + schema: + type: string + responses: + '200': + description: External account deleted. + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + 4XX: + $ref: '#/components/responses/ErrorResponse' + 5XX: + $ref: '#/components/responses/ErrorResponse' + /crosstransfer/routing/onramp: + post: + operationId: createCrossTransferOnRampRouting + summary: Creates deposit-only fiat account as a source, configures trigger and stores payment instruction details about destination crypto account. As a result, the user will be able to deposit fiat to the source account and receive payment in crypto to the destination account. + tags: + - crosstransfers + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateOnRampRoutingRequest' + responses: + '200': + description: Sub-account created. + content: + application/json: + schema: + $ref: '#/components/schemas/AccountId' + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + 4XX: + $ref: '#/components/responses/ErrorResponse' + 5XX: + $ref: '#/components/responses/ErrorResponse' + /crosstransfer/routing/offramp: + post: + operationId: createCrossTransferOffRampRouting + summary: Creates deposit-only crypto account as a source, configures trigger and stores payment instruction details about destination fiat account. As a result, the user will be able to deposit crypto to the source account and receive fiat to the destination account. + tags: + - crosstransfers + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateOffRampRoutingRequest' + responses: + '200': + description: Sub-account created. + content: + application/json: + schema: + $ref: '#/components/schemas/AccountId' + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + 4XX: + $ref: '#/components/responses/ErrorResponse' + 5XX: + $ref: '#/components/responses/ErrorResponse' + /crosstransfer/routing/bridging: + post: + operationId: createCrossTransferBridgingRouting + summary: Creates deposit-only crypto account as a source, configures trigger and stores payment instruction details about destination crypto address. As a result, the user will be able to deposit crypto to the source account and receive exchanged value to destination address in selected cryptocurrency. + tags: + - crosstransfers + parameters: + - $ref: '#/components/parameters/X-FBAPI-KEY' + - $ref: '#/components/parameters/X-FBAPI-NONCE' + - $ref: '#/components/parameters/X-FBAPI-SIGNATURE' + - $ref: '#/components/parameters/X-FBAPI-TIMESTAMP' + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateBridgingRequest' + responses: + '200': + description: Sub-account created. + content: + application/json: + schema: + $ref: '#/components/schemas/AccountId' + '400': + $ref: '#/components/responses/BadRequestResponse' + '401': + $ref: '#/components/responses/UnauthorizedResponse' + 4XX: $ref: '#/components/responses/ErrorResponse' 5XX: $ref: '#/components/responses/ErrorResponse' @@ -2190,6 +2304,33 @@ components: items: $ref: '#/components/schemas/Withdrawal' schemas: + AccountHolderDetails: + type: object + required: + - name + properties: + name: + description: Full name of the account holder. + type: string + city: + type: string + country: + description: Country code, as specified in ISO 3166-1 alpha-2. + type: string + subdivision: + description: Country administrative subdivision, as specified in ISO 3166-2. + type: string + address: + description: Account holder street address. + type: string + postalCode: + type: string + type: + description: Type of the account holder. + type: string + enum: + - Individual + - Company GeneralError: description: Should be returned only if there in no more specific object. type: object @@ -2350,89 +2491,6 @@ components: allOf: - $ref: '#/components/schemas/AccountId' - $ref: '#/components/schemas/AccountData' - ExternalAccountRef: - type: object - required: - - type - - externalAccountId - properties: - type: - type: string - enum: - - ExternalAccount - example: ExternalAccount - externalAccountId: - $ref: '#/components/schemas/ExternalAccountId' - AccountRef: - type: object - required: - - type - - accountId - properties: - type: - type: string - enum: - - Account - example: Account - accountId: - $ref: '#/components/schemas/AccountId' - ExternalAccountId: - description: ID of the account in the external system. - type: string - example: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 - USBankAccountDetails: - type: object - required: - - type - - accountNumber - - routingNumber - properties: - type: - type: string - example: US - description: Type of the account. - enum: - - US - accountNumber: - type: string - example: '123456789' - description: Account number of the US bank account. - routingNumber: - type: string - example: '123456789' - description: Routing number of the US bank account. - accountType: - type: string - enum: - - Checking - - Savings - example: Checking - iBanAccountDetails: - type: object - required: - - type - - accountNumber - - bic - - country - properties: - type: - type: string - description: Type of the account. - example: IBAN - enum: - - IBAN - accountNumber: - description: International Bank Account Number (iBAN). - type: string - example: DE89370400440532013000 - bic: - description: Bank Identifier Code (BIC). - type: string - example: DEUTDEFF - country: - description: ISO 3166-1 alpha-2 country code. - type: string - example: DE Address: type: object required: @@ -2447,145 +2505,18 @@ components: streetLine2: type: string example: Canary Wharf - city: - type: string - example: London - state: - type: string - postalCode: - type: string - example: E14 5HP - country: - description: ISO 3166-1 alpha-2 country code. - type: string - example: GB - SwiftAccountDetails: - type: object - description: Account details for the SWIFT transfer. - required: - - accountNumber - - bic - - address - properties: - type: - type: string - example: Swift - description: Type of the account. - enum: - - Swift - accountNumber: - description: International Bank Account Number (iBAN). - type: string - example: GB29NWBK60161331926819 - bic: - description: Bank Identifier Code (BIC). - type: string - example: NWBKGB2L - country: - description: ISO 3166-1 alpha-2 country code. - type: string - example: GB - address: - $ref: '#/components/schemas/Address' - category: - description: The context of business operations - type: string - enum: - - Client - - ParentCompany - - Subsidiary - - Affiliate - - Supplier - purpose: - type: string - description: The nature of the transactions this account will participate in - enum: - - IntraGroupTransfer - - InvoiceForGoodsAndServices - shortBusinessDescription: - type: string - description: How the business uses the funds - example: Payment for goods and services - ExternalAccountDetails: - oneOf: - - $ref: '#/components/schemas/SwiftAccountDetails' - - $ref: '#/components/schemas/USBankAccountDetails' - - $ref: '#/components/schemas/iBanAccountDetails' - discriminator: - propertyName: type - mapping: - Swift: '#/components/schemas/SwiftAccountDetails' - US: '#/components/schemas/USBankAccountDetails' - IBAN: '#/components/schemas/iBanAccountDetails' - IndividualAccountHolder: - description: Individual account holder details. - type: object - required: - - type - - firstName - - lastName - - address - properties: - type: - type: string - enum: - - Individual - firstName: - type: string - lastName: - type: string - address: - $ref: '#/components/schemas/Address' - BusinessAccountHolder: - description: Business account holder details. - type: object - required: - - type - - businessName - - address - properties: - type: + city: type: string - enum: - - Business - businessName: + example: London + state: type: string - example: Acme Inc. - address: - $ref: '#/components/schemas/Address' - ExternalAccount: - type: object - required: - - id - - currency - - customerId - - servicedBy - - account - - accountHolder - properties: - id: - $ref: '#/components/schemas/ExternalAccountId' - currency: - $ref: '#/components/schemas/AssetReference' - customerId: + postalCode: type: string - description: ID of the customer who will be account holder. - example: 123e4567-e89b-12d3-a456-426614174000 - servicedBy: + example: E14 5HP + country: + description: ISO 3166-1 alpha-2 country code. type: string - description: Name of the external service provider (e.g. bank name). - example: Bank of America - account: - $ref: '#/components/schemas/ExternalAccountDetails' - accountHolder: - oneOf: - - $ref: '#/components/schemas/BusinessAccountHolder' - - $ref: '#/components/schemas/IndividualAccountHolder' - discriminator: - propertyName: type - mapping: - Individual: '#/components/schemas/IndividualAccountHolder' - Business: '#/components/schemas/BusinessAccountHolder' + example: GB Balances: type: array description: Maps balance assets to their balances. @@ -2737,15 +2668,6 @@ components: - $ref: '#/components/schemas/NationalCurrency' - $ref: '#/components/schemas/NativeCryptocurrency' - $ref: '#/components/schemas/OtherAssetReference' - FiatRail: - type: string - example: SWIFT - enum: - - ACH - - SEPA - - SWIFT - - IBAN - - Wire Blockchain: type: string enum: @@ -3414,27 +3336,6 @@ components: - REJECTED - EXPIRED - FULFILLED - AccountHolderDetails: - type: object - required: - - name - properties: - name: - description: Full name of the account holder. - type: string - city: - type: string - country: - description: Country code, as specified in ISO 3166-1 alpha-2. - type: string - subdivision: - description: Country administrative subdivision, as specified in ISO 3166-2. - type: string - address: - description: Account holder street address. - type: string - postalCode: - type: string Iban: type: string pattern: ^[A-Z]{2}\d{2}[a-zA-Z0-9]{1,30}$ @@ -3458,7 +3359,7 @@ components: - iban properties: accountHolder: - $ref: '#/components/schemas/AccountHolderDetails' + $ref: ./fb-provider-api.yaml#/components/schemas/AccountHolderDetails iban: $ref: '#/components/schemas/Iban' IbanTransferDestination: @@ -3501,7 +3402,7 @@ components: - routingNumber properties: accountHolder: - $ref: '#/components/schemas/AccountHolderDetails' + $ref: ./fb-provider-api.yaml#/components/schemas/AccountHolderDetails swiftCode: $ref: '#/components/schemas/SwiftCode' routingNumber: @@ -3959,6 +3860,301 @@ components: enum: - CanCreate - CannotCreate + CustomerList: + type: object + properties: + customers: + type: array + items: + $ref: '#/components/schemas/Customer' + required: + - customers + CustomerStatus: + type: string + description: |- + Status of the customer: + - Draft: Customer is in draft state. Not yet submitted for review. + - Pending: Customer details are submitted for review. Awaiting approval. + - Incomplete: Customer details are incomplete. KYC is not yet completed requres that customer resolve input issues. + - InReview: Customer details are under review. + - Active: Customer is approved and active. + - Inactive: Customer is inactive and cannot be used. + - Rejected: Customer is rejected and cannot be used. + enum: + - Draft + - Pending + - Incomplete + - InReview + - Active + - Inactive + - Rejected + CustomerType: + type: string + description: |- + Type of the customer: + - Individual: Customer is an individual person. + - Business: Customer is a business entity. + enum: + - Individual + - Business + Customer: + type: object + properties: + id: + type: string + description: Customer ID + format: uuid + name: + type: string + description: Customer full name + email: + type: string + description: Customer email address + status: + $ref: '#/components/schemas/CustomerStatus' + type: + $ref: '#/components/schemas/CustomerType' + required: + - id + - name + - email + - status + - type + RegisterCustomer: + type: object + properties: + idempotencyKey: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + description: Unique identifier of the request. Used to prevent duplicate requests. + name: + type: string + description: Customer full name + email: + type: string + description: Customer email address + type: + $ref: '#/components/schemas/CustomerType' + kycTier: + type: string + description: KYC tier validation to use when registering the customer + required: + - idempotencyKey + - name + - email + - type + CustomerUpdateKycTier: + type: object + properties: + idempotencyKey: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + description: Unique identifier of the request. Used to prevent duplicate requests. + kycTier: + type: string + description: KYC tier to which the customer is upgrading + required: + - idempotencyKey + - kycTier + CustomerKycTierResponse: + type: object + required: + - id + - name + - email + - type + - kycTier + - kycLink + - status + - tosLink + - tosStatus + properties: + id: + type: string + description: ID unique for each started KYC process. Registration or KYC tier upgrade. + format: uuid + customerId: + type: string + description: |- + Customer ID. + If the KYC process is for a new customer, this field is empty until the + customer is registered and first kyc tier is set. + format: uuid + name: + type: string + description: Customer full name + example: John Doe + email: + type: string + description: Customer email address + example: john.doe@example.com + type: + $ref: '#/components/schemas/CustomerType' + kycTier: + type: string + description: KYC tier to which the customer is upgrading + example: Tier 2 + kycLink: + type: string + description: URL to the KYC process + status: + $ref: '#/components/schemas/KycStatus' + tosLink: + type: string + description: URL to the terms of service agreement + tosStatus: + $ref: '#/components/schemas/TosStatus' + rejection: + description: KYC rejection details. + type: array + items: + $ref: '#/components/schemas/KycRejectionReason' + TosStatus: + type: string + description: |- + Status of the terms of service agreement: + - Pending: Terms of service agreement is pending customer acceptance. + - Accepted: Terms of service agreement is accepted by the customer. + enum: + - Pending + - Accepted + KycRejectionReason: + type: object + description: Reason for KYC rejection. + properties: + reason: + type: string + description: Reason for KYC rejection + details: + type: string + description: Additional details about the rejection reason + rejectedAt: + type: string + description: Date and time when the KYC was rejected + format: date-time + KycStatus: + description: |- + Status of the KYC process: + - Pending: KYC is pending. + - InReview: KYC is under review. + - AwaitingCustomer: KYC is awaiting customer input. + - Approved: KYC is approved. + - Rejected: KYC is rejected. + type: string + enum: + - Pending + - InReview + - AwaitingCustomer + - Approved + - Rejected + ExternalAccountId: + description: ID of the account in the external system. + type: string + example: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 + CreateExternalAccount: + description: Create a new external account. + type: object + required: + - idempotencyKey + - customerId + properties: + idempotencyKey: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + description: Unique identifier of the request. + customerId: + description: ID of the customer who will be account holder. + example: 123e4567-e89b-12d3-a456-426614174000 + type: string + currency: + $ref: '#/components/schemas/AssetReference' + servicedBy: + type: string + description: Name of the external service provider (e.g. bank name). + example: Bank of America + account: + $ref: '#/components/schemas/ExternalAccountDetails' + accountHolder: + allOf: + - $ref: '#/components/schemas/AccountHolderDetails' + - type: object + required: + - type + properties: + type: + type: string + enum: + - Individual + - Company + ExternalAccountDetails: + oneOf: + - $ref: '#/components/schemas/SwiftAddress' + - $ref: '#/components/schemas/IbanAddress' + ExternalAccount: + description: External account details. + allOf: + - $ref: '#/components/schemas/ExternalAccountDetails' + - type: object + required: + - id + - customerId + - servicedBy + properties: + id: + $ref: '#/components/schemas/ExternalAccountId' + customerId: + type: string + description: ID of the customer who will be account holder. + example: 123e4567-e89b-12d3-a456-426614174000 + servicedBy: + type: string + description: Name of the external service provider (e.g. bank name). + example: Bank of America + UpdateExternalAccount: + description: Update external account details. + type: object + required: + - idempotencyKey + properties: + idempotencyKey: + type: string + example: 123e4567-e89b-12d3-a456-426614174000 + description: Unique identifier of the request. + account: + type: object + description: Update US bank account details. + properties: + accountType: + description: Type of the account. + type: string + enum: + - Checking + - Savings + example: Checking + accountHolder: + type: object + description: Update account holder address. + properties: + address: + $ref: '#/components/schemas/Address' + CryptoPaymentAccountParams: + allOf: + - $ref: '#/components/schemas/NativeCryptocurrency' + type: object + required: + - developerFee + properties: + developerFee: + $ref: ./fb-provider-api.yaml#/components/schemas/PositiveAmount + FiatPaymentAccountParams: + allOf: + - $ref: '#/components/schemas/NationalCurrency' + type: object + required: + - developerFee + properties: + developerFee: + $ref: ./fb-provider-api.yaml#/components/schemas/PositiveAmount CreateBridgingRequest: type: object required: @@ -3974,7 +4170,7 @@ components: type: string example: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 source: - $ref: '#/components/schemas/BridgingSourceParameters' + $ref: '#/components/schemas/CryptoPaymentAccountParams' destination: $ref: '#/components/schemas/BridgingDestination' BridgingDestination: @@ -3994,17 +4190,6 @@ components: memo: description: Memo field for the destination address. Required for some blockchains. type: string - BridgingSourceParameters: - type: object - required: - - currency - properties: - chain: - $ref: '#/components/schemas/Blockchain' - currency: - $ref: '#/components/schemas/NativeCryptocurrency' - developerFee: - $ref: ./fb-provider-api.yaml#/components/schemas/PositiveAmount CreateOnRampRoutingRequest: type: object required: @@ -4020,7 +4205,7 @@ components: type: string example: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 source: - $ref: '#/components/schemas/OnRampSourceParameters' + $ref: '#/components/schemas/FiatPaymentAccountParams' destination: $ref: '#/components/schemas/OnRampDestination' OnRampDestination: @@ -4040,57 +4225,16 @@ components: memo: description: Memo field for the destination address. Required for some blockchains. type: string - OnRampSourceParameters: - type: object - required: - - currency - properties: - currency: - $ref: '#/components/schemas/NativeCryptocurrency' - developerFee: - $ref: '#/components/schemas/PositiveAmount' - OffRampSourceParameters: - type: object - required: - - chain - - currency - properties: - chain: - $ref: '#/components/schemas/Blockchain' - currency: - $ref: '#/components/schemas/NativeCryptocurrency' - developerFee: - $ref: '#/components/schemas/PositiveAmount' - returnAddress: - type: string - description: Blockchain address to return the funds in case of a failed transaction. MUST be on same blockchain network that is selected in the chain field. Field will be ignored in case of Stellar chain. OffRampDestination: type: object - required: - - rail - - currency - - account properties: - rail: - $ref: '#/components/schemas/FiatRail' - currency: - $ref: '#/components/schemas/NationalCurrency' - message: - type: string - description: A message to be sent with a wire transfer. It can have at most 3 lines (separated by "\n"), each line with a max length of 35 chars - maxLength: 109 + externalAccountId: + $ref: '#/components/schemas/AccountId' + accountId: + $ref: '#/components/schemas/AccountId' reference: type: string - description: If rail is SEPA, this is the SEPA reference and must be from 6 to 140 characters. The allowed characters are a-z, A-Z, 0-9, spaces, ampersand (&), hyphen (-), full stop (.), and solidus (/). If rail is ACH, this is the ACH reference and can be at most 10 characters, A-Z, a-z, 0-9, and spaces. - account: - oneOf: - - $ref: '#/components/schemas/ExternalAccountRef' - - $ref: '#/components/schemas/AccountRef' - discriminator: - propertyName: type - mapping: - ExternalAccount: '#/components/schemas/ExternalAccountRef' - Account: '#/components/schemas/AccountRef' + description: Optional reference to be included in transaction. CreateOffRampRoutingRequest: type: object required: @@ -4106,84 +4250,7 @@ components: type: string example: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 source: - $ref: '#/components/schemas/OffRampSourceParameters' + $ref: '#/components/schemas/CryptoPaymentAccountParams' destination: $ref: '#/components/schemas/OffRampDestination' - examples: - usBankExternalAccount: - summary: US bank account - description: Example of a US bank account. - value: - id: 4ff63424-7e09-4cdf-b7f1-da7b7c65eabe - customerId: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 - currency: - nationalCurrencyCode: USD - servicedBy: Bank of America - account: - type: US - accountNumber: '1234567890' - routingNumber: '123456789' - accountType: Checking - accountHolder: - type: Individual - firstName: John - lastName: Doe - address: - streetLine1: 1 Churchill Place - city: London - postalCode: E14 5HP - country: GB - iBANExternalAccount: - summary: iBAN account - description: Example of an iBAN account. - value: - id: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 - customerId: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 - currency: - nationalCurrencyCode: EUR - servicedBy: Deutsche Bank - account: - type: IBAN - accountNumber: DE89370400440532013000 - bic: DEUTDEFF - country: DE - accountHolder: - type: Individual - firstName: John - lastName: Doe - address: - streetLine1: 1 Churchill Place - city: London - postalCode: E14 5HP - country: GB - swiftExternalAccount: - summary: SWIFT account - description: Example of a SWIFT account. - value: - id: 76a33ed9-8aa2-4781-93f8-d2369c0c2b14 - customerId: 2e7b3b9b-8aa2-4781-93f8-d2369c0c2b14 - currency: - nationalCurrencyCode: USD - servicedBy: Bank of America - account: - type: Swift - accountNumber: GB29NWBK60161331926819 - bic: NWBKGB2L - country: GB - address: - streetLine1: 1 Churchill Place - city: London - postalCode: E14 5HP - country: GB - accountHolder: - type: Business - businessName: Acme Inc. - address: - streetLine1: 1 Churchill Place - city: London - postalCode: E14 5HP - country: GB - category: Client - purpose: IntraGroupTransfer - shortBusinessDescription: Payment for goods and services securitySchemes: {}