Registration Flow: Non-Business Customers

The following sections exemplify the API calls your client application needs to include to register customers and enable them to complete USD transactions.

Requesting the Security Token

Firstly, request the security token you must send in the X-Bitso-Security-Token header of your create customer call. Otherwise, the system rejects the creation call.

To request the token, make an HTTP call with an empty request body to the following endpoint:

POST https://api-stage.bitso.com/v3/payments/usd/bridge/security-tokens

A successful call returns the token you need to store for later use.

{
    "success": true,
    "payload": {
        "token": "4ed7a6c8-a0ab-49e9-9220-28ded3f8b1bd"
    }
}

Requesting and Sharing the Terms of Service URL

Next, your customers must agree to the Terms of Service (ToS) before they can be registered. To request the ToS address, make an HTTP call to the following endpoint:

POST https://api-stage.bitso.com/v3/payments/usd/bridge/money-transmitters/customers/terms-of-service

The endpoint returns a URL that enables the customer to access the ToS page:

{
    "success": true,
    "payload": {
        "url": "https://dashboard.bridge.xyz/accept-terms-of-service?session_token=ec313a8f-776e-438a-b320-9eb50aa90821"
    }
}

You can embed this URL in an iFrame or display it in a new browser window. Moreover, you can pass a redirect_uri query parameter to redirect the ToS page back to your application with the signed_agreement_id as a query parameter (perform a GET request). Ensure you store this ID, as it is necessary for customer creation.

Creating a Customer

Now that you have the security token and the agreement ID (signed_agreement_id parameter), you can register your customer. The agreement ID signals that the customer has accepted the ToS and acts as an idempotency key, a unique identifier that prevents customer duplication.

Ensure you include the following items in your create customer request:

• The security token obtained: Send it in the X-Bitso-Security-Token header, as the bare token value with no prefix.
• The previously received agreement ID.
• Your customer’s complete data.

To register a non-business customer, make an HTTP call to the following endpoint:

POST https://api-stage.bitso.com/v3/payments/usd/bridge/money-transmitters/customers

The following JSON object exemplifies the request body parameters used; phone and street_line_2 are optional:

{
    "signed_agreement_id": "1481bde7-4e08-4aed-9097-78c03ac7d40e",
    "first_name": "Jane",
    "last_name": "Doe",
    "email": "[email protected]",
    "phone": "5555-5555",
    "birth_date": "1980-01-01",
    "tax_identification_number": "12345678",
    "gov_id_image_front": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD",
    "gov_id_image_back": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAgAAZABkAAD",
    "address": {
        "street_line_1": "Av. de la Paz 171",
        "street_line_2": "Col. Providencia",
        "city": "Zapopan",
        "state": "JAL",
        "postal_code": "45130",
        "country": "MEX"
    }
}

A successful call returns the customer ID (id field), essential for retrieving your customer's KYC status or completing transactions on their behalf.

It also returns the status field that indicates the customer’s KYC state. Example KYC status values include not_started, active, or rejected. The average decision time for KYC is typically a few minutes. However, if the KYC process requires a manual review or due diligence is necessary, the decision might take until the next business day.

{
    "success": true,
    "payload": {
        "id": "dba20525-aa3c-4f43-8b3d-45069b355802",
        "type": "individual",
        "status": "active",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "[email protected]",
        "has_accepted_terms_of_service": true,
        "capabilities": {
            "payin_crypto": "pending",
            "payout_crypto": "pending",
            "payin_fiat": "pending",
            "payout_fiat": "pending"
        },
        "requirements_due": [],
        "rejection_reasons": [],
        "future_requirements_due": [],
        "endorsements": [
            {
                "name": "base",
                "status": "approved",
                "additional_requirements": null
            },
            {
                "name": "sepa",
                "status": "approved",
                "additional_requirements": null
            }
        ],
        "created_at": "2024-07-09T23:02:39.108Z",
        "updated_at": "2024-07-09T23:02:39.509Z"
    }
}