Bit Capital

The Bit Capital Developer Hub

Welcome to the Bit Capital developer hub. You'll find comprehensive guides and documentation to help you start working with the platform as quickly as possible, as well as support if you get stuck. Let's jump right in!


Handling failed verifications

An account creation request may be rejected by an external provider's KYC or fail a validation step, which will be reflected on the consumer's state with one of the following status:





Each status reflect a different problem with the account, and a different approach to fix it. Navigate through the status using the menu in the right side of the page →

Rejection Status

The identity was rejected in the verification step with the supplied information. This error usually denotes that, although the consumer' information may be real and valid, the account holder may not be suitable for operating the system.

It can be one of two types:

  • rejected: Bit Capital or its validation services rejected the account
  • provider_rejected: A partner custody provider from the network rejected the account

Each account has a highly specific approach of solving these issues, such as requiring additional documents from the consumer or even limiting the financial operating reach of the account holder in the platform.

If the consumer uploads information that does not meet an external provider's validation criteria, the consumer shall proceed to the provider_rejected state.

The consumer's rejected state should be in one of the following forms.

Simple rejection output:

    "id": "fdb9db8f-0943-4442-b900-ad68a33ca4b4",
    "status": "rejected",
    "createdAt": "2020-03-23T11:52:21.285Z",
    "updatedAt": "2020-03-23T11:52:21.285Z",
    "additionalData": {

Provider rejection output:

    "id": "fdb9db8f-0943-4442-b900-ad68a33ca4b4",
    "status": "provider_rejected",
    "createdAt": "2020-03-23T11:52:21.285Z",
    "updatedAt": "2020-03-23T11:52:21.285Z",
    "additionalData": {

The 'additionalData' field contains a list of fields which weren't validated by one of our service providers. You must update those fields with proper values in order to complete the account creation.
In the event that an uploaded image, be it a selfie or a picture of a document is rejected by an external provider's validation step, the additionalData field shall contain detailed information regarding which document failed the validation.

Recommended Action:

  • Contact the account holder for ensuring everything was correctly input;
  • Validate the consumer information using the KYC previewing APIs and the available platform bureaus;
  • In the event that a document is rejected, upload new files of the failing documents paying attention to the guidelines outiline on Selfie and Documents
  • Edit the user information (see below) with the retry parameter as true, the new information will be re-evaluated by the platform and its connected custody providers.

Information is correct and the provider is still rejecting?

Sometimes even with the correct information, some providers will automatically reject the account. This is due to many structural reasons, but most problems often comes from outdated information in the verification bureaus.

If that looks like your case, contact the compliance support with the User ID which was rejected through the Help Desk. It may be a false negative that will require manual intervention from the custody provider operational team.

Failure Status

The identity or the account data has generated an unknown exception in the communication with the custody providers associated with the instance. This can mean many things, but usually is some restriction of the provider internal system and APIs, such as:

  • Provider API is unavailable or has timed out
  • Data validation failed without specific warning
  • File upload failed without specific warning

Recommended Action: Contact the tech support with the User ID which was rejected and the Stack ID (can be found in the additionalData of the state) through the Help Desk.

Updating consumer information

It is possible to update consumer data using the POST /consumers/:userId endpoint after the initial verification has already taken place. For example, if the consumer must update the name and motherName, the request would be like this:

POST {{API_BASE_URL}}/consumers/:userId?retry=true

Body: { 
  "firstName": "The new user first name",
  "lastName": "The new user last name",
    "motherName": "The new mother name"


Retry parameter

You can use the retry parameter when you edit consumer data to retry the consumer creation at the provider.
Use this parameter when you are sure that all fields were corrected.

POST /consumers/:id/?retry=true

DOCK Provider Known Errors

Error Code



Invalid document.


Document status is not regular.


The name inserted does not match with data extracted from official government


The mother's name inserted does not match with data extracted from official
government sources.


The date of birth inserted does not match with the data extracted from official
government sources.


Operation not allowed for the informed document. (Sanctions)

Updated 9 months ago

What's Next

Platform Assets

Handling failed verifications

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.