# Destination Bank Account management API

The following API end points should be used for creation of DBA (Destination Bank Account) or management of several DBAs.

{% hint style="warning" %}
Only one DBA at a time can be the **Main Beneficiary** account.
{% endhint %}

{% hint style="warning" %}
At least one account must be the  **Main Beneficiary** account to initiate a withdrawal request.
{% endhint %}

There are two ways to manage DBAs - host-to-host and using the XGateway UI. 

## Managing DBAs using UI

This API endpoints returns a URL with an interface for managing DBAs of a corresponding customer. 

{% hint style="danger" %}
A merchant is responsible for authentication of customers. XGateway fully relies on the data provided by the merchant to authorise DBA management. XGateway is not responsible for any damage done by misuse of the APIs below.
{% endhint %}

## Generates a Destination Bank Account checkout link for a customer.

> Initiates a Destination Bank Account (DBA) checkout link for a specified customer.\
> \
> It generates a Destination Bank Account checkout link for the customer, optionally localized by the provided locale.

```json
{"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_string_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"type":"string"}},"required":["success","data"],"type":"object","additionalProperties":false},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false},"InitiateCheckoutBaseSchemaInput":{"properties":{"isKycNoSdk":{"type":"boolean"},"applicationId":{"type":"string"},"locale":{"type":"string"}},"type":"object"}}},"paths":{"/customer/{id}/bank-transfer/destination-bank-account/initiate":{"post":{"operationId":"InitiateCheckoutDBA","responses":{"201":{"description":"Created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_string_"}}}},"400":{"description":"Database violation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}}},"description":"Initiates a Destination Bank Account (DBA) checkout link for a specified customer.\n\nIt generates a Destination Bank Account checkout link for the customer, optionally localized by the provided locale.","summary":"Generates a Destination Bank Account checkout link for a customer.","tags":["Customer"],"parameters":[{"description":"- Unique identifier of the customer.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"- The request body containing DBA link options.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InitiateCheckoutBaseSchemaInput","description":"- The request body containing DBA link options."}}}}}}}}
```

## Host-to-host DBA management

Use the following APIs for direct management of DBAs. 

{% hint style="danger" %}
A merchant is responsible for authentication of customers. XGateway fully relies on the data provided by the merchant to authorise DBA management. XGateway is not responsible for any damage done by misuse of the APIs below.
{% endhint %}

### List existing DBAs

## Returns destination bank accounts for a specified customer.

> Returns a list of destination bank accounts for a specified customer.\
> \
> Access to this endpoint requires a valid API key. The API key is sent in the \`x-api-key\` header on requests.

```json
{"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_IUnblockBankAccount-Array_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"items":{"$ref":"#/components/schemas/IUnblockBankAccount"},"type":"array"}},"required":["success","data"],"type":"object","additionalProperties":false},"IUnblockBankAccount":{"description":"Represents detailed information about the customer’s bank account in Unblock provider system.","properties":{"account_name":{"type":"string"},"account_number":{"type":"string"},"bank_code":{"type":"string"},"bank_country":{"type":"string"},"bank_name":{"type":"string"},"bic":{"type":"string"},"country":{"type":"string"},"currency":{"$ref":"#/components/schemas/BankTransferFiatCurrency"},"iban":{"type":"string"},"main_beneficiary":{"type":"boolean"},"receiving_address":{"type":"string"},"sort_code":{"type":"string"},"status":{"$ref":"#/components/schemas/UnblockBankAccountStatus"},"timestamp":{"type":"string"},"uuid":{"type":"string"}},"required":["currency","status","uuid"],"type":"object","additionalProperties":{}},"BankTransferFiatCurrency":{"type":"string","enum":["EUR","GBP"],"description":"Represents supported fiat currencies for `bank-transfer` payments in the payment processing\nsystem.\n\nCurrencies:\n- `EUR` - Euro\n- `GBP` - Pound Sterling."},"UnblockBankAccountStatus":{"type":"string"},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false}}},"paths":{"/customer/{id}/bank-transfer/destination-bank-account/accounts":{"get":{"operationId":"GetAllDestinationBankAccounts","responses":{"200":{"description":"Returned list of destination bank accounts","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_IUnblockBankAccount-Array_"}}}},"400":{"description":"Couldn't return destination bank accounts.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}}},"description":"Returns a list of destination bank accounts for a specified customer.\n\nAccess to this endpoint requires a valid API key. The API key is sent in the `x-api-key` header on requests.","summary":"Returns destination bank accounts for a specified customer.","tags":["Customer"],"parameters":[{"description":"- The external identifier for the customer.","in":"path","name":"id","required":true,"schema":{"type":"string"}}]}}}}
```

### Create a DBA

## Sets up a destination bank account for a specified customer.

> Sets up a new destination bank account for a specified customer.\
> Destination Bank Account is required for Crypto To Fiat (Withdrawal) Bank Transfer flow.\
> The customer must pass the KYC process before setting up a DBA.\
> \
> Access to this endpoint requires a valid API key. The API key is sent in the \`x-api-key\` header on requests.

```json
{"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_string_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"type":"string"}},"required":["success","data"],"type":"object","additionalProperties":false},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false},"SetupDestinationBankAccountInput":{"anyOf":[{"properties":{"iban":{"type":"string"},"mainBeneficiary":{"type":"boolean"},"accountName":{"type":"string"},"currency":{"type":"string","enum":["EUR"],"nullable":false}},"type":"object"},{"properties":{"accountNumber":{"type":"string"},"sortCode":{"type":"string"},"mainBeneficiary":{"type":"boolean"},"accountName":{"type":"string"},"currency":{"type":"string","enum":["GBP"],"nullable":false}},"type":"object"}]}}},"paths":{"/customer/{id}/bank-transfer/destination-bank-account/setup":{"post":{"operationId":"SetupDestinationBankAccount","responses":{"200":{"description":"29ceac55-8332-4daa-9652-00b13f3e2e7b","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_string_"}}}},"400":{"description":"The provided bank account details are invalid.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}},"403":{"description":"The user must pass the KYC first.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"409":{"description":"The destination bank account with the provided details already exists.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"500":{"description":"Couldn't configure the destination bank account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}}},"description":"Sets up a new destination bank account for a specified customer.\nDestination Bank Account is required for Crypto To Fiat (Withdrawal) Bank Transfer flow.\nThe customer must pass the KYC process before setting up a DBA.\n\nAccess to this endpoint requires a valid API key. The API key is sent in the `x-api-key` header on requests.","summary":"Sets up a destination bank account for a specified customer.","tags":["Customer"],"parameters":[{"description":"- The external identifier for the customer.","in":"path","name":"id","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"- Request body containing bank account details.","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SetupDestinationBankAccountInput","description":"- Request body containing bank account details."}}}}}}}}
```

### Select a DBA from the list of existing accounts

## Sets the main destination bank account for a customer.

> Activates the specified destination bank account as the main beneficiary for a customer.\
> \
> Access to this endpoint requires a valid API key. The API key is sent in the \`x-api-key\` header on requests.

```json
{"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_string_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"type":"string"}},"required":["success","data"],"type":"object","additionalProperties":false},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false}}},"paths":{"/customer/{id}/bank-transfer/destination-bank-account/{bankAccountUuid}/select":{"patch":{"operationId":"UpdateTheMainDestinationBankAccount","responses":{"200":{"description":"Destination bank account successfully activated!","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_string_"}}}},"400":{"description":"Couldn't activate the destination bank account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}}},"description":"Activates the specified destination bank account as the main beneficiary for a customer.\n\nAccess to this endpoint requires a valid API key. The API key is sent in the `x-api-key` header on requests.","summary":"Sets the main destination bank account for a customer.","tags":["Customer"],"parameters":[{"description":"- The external identifier for the customer.","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"- The UUID of the destination bank account to be selected as the main one.","in":"path","name":"bankAccountUuid","required":true,"schema":{"type":"string"}}]}}}}
```

### Delete a DBA

## Deletes a destination bank account for a specified customer.

> Deletes a specified destination bank account for a customer.\
> \
> Access to this endpoint requires a valid API key. The API key is sent in the \`x-api-key\` header on requests.

```json
{"openapi":"3.0.0","info":{"title":"x-gateway-external-api","version":"0.0.1"},"servers":[{"url":"https://api.xgateway.tech/api/v2"}],"security":[{"api_key":[]}],"components":{"securitySchemes":{"api_key":{"in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"AppSuccessResponse_string_":{"description":"The AppSuccessResponse object contains general information about the success execution.","properties":{"success":{"type":"boolean","default":true},"data":{"type":"string"}},"required":["success","data"],"type":"object","additionalProperties":false},"AppErrorResponse":{"description":"The AppErrorResponse object contains general information about the error message.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array"}},"required":["success","errors"],"type":"object","additionalProperties":false},"IAppError":{"description":"The IAppError interface represents an application error message.","properties":{"code":{"anyOf":[{"$ref":"#/components/schemas/AppClientErrorResponseCode"},{"$ref":"#/components/schemas/AppServerErrorResponseCode"}]},"message":{"type":"string"}},"required":["code","message"],"type":"object","additionalProperties":false},"AppClientErrorResponseCode":{"type":"string","enum":["bad_request","db_violation","unauthorized","payment_required","forbidden","not_found","method_not_allowed","not_acceptable","proxy_authentication_required","request_timeout","conflict","db_unique_violation","gone","length_required","precondition_failed","payload_too_large","uri_too_long","unsupported_media_type","range_not_satisfiable","expectation_failed","misdirected_request","unprocessable_content","db_non_null_violation","locked","failed_dependency","upgrade_required","precondition_required","too_many_requests","request_header_fields_too_large","unavailable_for_legal_reasons"],"nullable":false,"description":"The AppClientErrorResponseCode object contains all client error response codes."},"AppServerErrorResponseCode":{"type":"string","enum":["internal_server_error","not_implemented","bad_gateway","service_unavailable","gateway_timeout","http_version_not_supported","variant_also_negotiates","insufficient_storage","loop_detected","not_extended","network_authentication_required"],"nullable":false,"description":"The AppServerErrorResponseCode object contains all server error response codes."},"AppAuthenticationErrorResponse":{"description":"The AppAuthenticationErrorResponse object contains general information about the authentication\nerror.","properties":{"success":{"type":"boolean","default":false},"errors":{"items":{"$ref":"#/components/schemas/IAppError"},"type":"array","default":[{"code":"unauthorized","message":"You do not have permission to access this resource."}]}},"required":["success","errors"],"type":"object","additionalProperties":false}}},"paths":{"/customer/{id}/bank-transfer/destination-bank-account/{bankAccountUuid}/delete":{"delete":{"operationId":"DeleteDestinationBankAccount","responses":{"200":{"description":"Destination bank account successfully deleted!","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppSuccessResponse_string_"}}}},"400":{"description":"Couldn't delete the destination bank account.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AppAuthenticationErrorResponse"}}}}},"description":"Deletes a specified destination bank account for a customer.\n\nAccess to this endpoint requires a valid API key. The API key is sent in the `x-api-key` header on requests.","summary":"Deletes a destination bank account for a specified customer.","tags":["Customer"],"parameters":[{"description":"- The external identifier for the customer, used to uniquely identify them and associate them with a merchant.","in":"path","name":"id","required":true,"schema":{"type":"string"}},{"description":"- The UUID of the destination bank account to be deleted.","in":"path","name":"bankAccountUuid","required":true,"schema":{"type":"string"}}]}}}}
```