Registration Flow: 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 a 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, 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 business customer, make an HTTP call to the following endpoint:

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

The following JSON object exemplifies the request body parameters used; all are required:

{
    "name": "a test business",
    "description": "A mock business to test the API",
    "email": "[email protected]",
    "source_of_funds": "profits",
    "website": "https://example.com",
    "tax_identification_number": "20-12345678-9",
    "signed_agreement_id": "signed-agreement-id",
    "address": {
        "street_line_1": "Fake st 123",
        "city": "Buenos Aires",
        "country": "ARG",
        "state": "AR-B",
        "postal_code": "1834"
    },
    "business_type": "llc",
    "is_dao": true,
    "transmits_customer_funds": false,
    "compliance_screening_explanation": "something",
    "ultimate_beneficial_owners": [
        {
            "address": {
                "street_line_1": "Fake st 123",
                "city": "Buenos Aires",
                "country": "ARG",
                "state": "AR-B",
                "postal_code": "1834"
            },
            "has_ownership": true,
            "has_control": true,
            "is_signer": true,
            "first_name": "Esteban",
            "last_name": "Garcia",
            "birth_date": "1993-12-03",
            "email": "[email protected]",
            "phone": "+541112345678",
            "tax_identification_number": "20-12345678-9",
            "relationship_established_at": "2024-01-01",
            "gov_id_image_front": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/..."
        }
    ],
    "formation_document": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/...",
    "ownership_document": "data:image/jpg;base64,/9j/4AAQSkZJRgABAQAAAQABAAD/..."
}

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

It also returns the status field that indicates the customer’s KYB state. Example KYB status values include not_started, active, or rejected. KYB reviews typically happen on the same business day and up to the next business day. KYB flows include collecting the KYC information for any ultimate beneficial owners.

{
    "success": true,
    "payload": {
        "id": "d5749ce9-3e84-42c0-8dfb-663c90d54839",
        "type": "business",
        "status": "active",
        "full_name": "a test business",
        "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-10-09T15:47:22.626Z",
        "updated_at": "2024-10-09T15:47:23.007Z"
    }
}