Create a New Contact

When creating a new contact, the compliance information (Travel Rule information) is only necessary if the beneficiary receives amounts equal to or larger than 1,000 euros. Hence, you can create a beneficiary without including the Travel Rule information (compliance object).

Every beneficiary is associated with a transaction's taxonomy that identifies a currency, a protocol, and an integration with a payment gateway. You must specify this metadata in the request body, which includes: asset, currency,integration, network, and protocol.

To determine the specific values of these parameters, make an HTTP call to the following endpoint, which retrieves the withdrawal methods for the currency at hand:

GET https://api-stage.bitso.com/v3/withdrawal_methods/{currency}

🚧
For some cases, the taxonomy parameters aren't available via the endpoint.
The method GET /v3/withdrawal_methods/{currency} does not provide the taxonomy parameters for transactions over Polygon, Stellar, and Solana. Follow the configuration provided in this document.

If you do not have the receiving VASP's Decentralized Identifier (DID) that the compliance object requires, then you can retrieve a DID catalog by calling the following endpoint:

GET https://stage.bitso.com/api/v3/vasps

📘
VASP not in the catalog?
If the VASP you need is not in the catalog, then use the property name instead of didin your request body, "name": "VASPS's name".

🚧
Ensure you access the correct DID catalog.
For going to production, you need the VASPs' identifiers used in this environment. Use the URL https://bitso.com/api/v3/vasps to retrieve the DIDs of production.

🚀 Now that you are ready to create your contact, make the following HTTP request using the appropriate body parameters:

POST https://api-stage.bitso.com/v3/consumer-contacts

Body Parameters

alias: Name that helps users identify the beneficiary.
compliance: Contains the Travel Rule information. It is optional when creating the beneficiary.

travel_rule: Contains the VASP's and beneficiary's information.

vasp: Contains the receiving VASP's data. Provide only one of them:

did: Receiving VASP's Decentralized Identifier (DID). For example, Binance's is: did:ethr:0x401c4bc0241bc787f64510f21a4ae7ec3603487c (production).
name: VASP's name.

beneficiary: Contains the beneficiary data.

name: Indicates the business legal name or full personal name. In the case of an individual, it must specify both the First and Last name.
type: Indicates whether it's a business or personal account. Valid values: LEGAL or NATURAL.

details: Contains fields that provide further information on the transaction, such as digital address, destination tag, and chain.
taxonomy: Contains the taxonomy of the transaction, tied to the contact.

asset: The digital asset in the network. In most cases, it is the same as withdrawal currency. In some cases, for example, USD, you can use a 1:1 paired asset like usdp or usdc.
currency: Currency used with the beneficiary.
integration: A specific integration that enables Bitso to connect to a given network.
network: Payment network through which the transaction is processed.
protocol: A specific mechanism, protocol, or standard used in a network.

The following objects exemplify request bodies of the create contact call:

{
   "taxonomy":{
      "network":"rp",
      "asset":"xrp",
      "protocol":"ripple",
      "integration":"rippled",
      "currency":"xrp"
   },
   "details":{
         "address":"******T633ra63CcDXG6AciFT6qj******",
         "destination_tag":5403767
   },
   "compliance":{
      "travel_rule":{
         "vasp":{
            "did":"did:ethr:0x4cd9136034d9a63d855391fce6dba64021530b01"
         },
         "beneficiary":{
            "name":"Jane Doe",
            "type":"NATURAL"
         }
      }
   },
   "alias":"XRPTesting"
}

{
   "taxonomy":{
      "network":"circle",
      "protocol":"usdc_trf",
      "asset": "usdc",
      "integration": "circle-api",
     "currency":"usd"
   },
   "details":{
       "address": "******IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3Z******",
       "chain": "xlm",
       "addressTag": "memo"
   },
   "compliance":{
      "travel_rule":{
         "vasp":{
            "did":"did:ethr:0x4cd9136034d9a63d855391fce6dba64021530b01"
         },
         "beneficiary":{
            "name":"StellarNetwork",
            "type":"LEGAL"
         }
      }
   },
   "user_id":99999,
   "alias":"StellarNetwork"
}

{
    "taxonomy": {
        "network": "circle",
        "protocol": "usdc_trf",
        "asset": "usdc",
        "integration": "circle-api",
        "currency": "usd"
    },
    "details": {
        "address": "******sqQcKF7KcDNnNuSmiQmdq7k9CG6C19rZ******",
        "chain": "SOL"
    },
    "compliance": {
        "travel_rule": {
            "vasp": {
                "did": "did:ethr:0x4cd9136034d9a63d855391fce6dba64021530b01"
            },
            "beneficiary": {
                "name": "SolanaTest",
                "type": "LEGAL"
            }
        }
    },
    "user_id": 99999,
    "alias": "SolanaTest"
}

{
    "taxonomy": {
        "network": "tron",
        "protocol": "trc20",
        "asset": "usdt",
        "integration":"fblocks-v1",
        "currency": "usdt"
    },
    "details": {
        "address": "******12r9tya9NTp5qzVgQvmqAf******"
    },
    "compliance": {
        "travel_rule": {
            "vasp": {
                "did": "did:ethr:0x4cd9136034d9a63d855391fce6dba64021530b01"
            },
            "beneficiary": {
                "name": "USDTTronTest",
                "type": "LEGAL"
            }
        }
    },
    "user_id": 29602,
    "alias": "USDTTronTest"
}

A successful contact creation returns the following response object. It includes the variable contact_id, which helps you identify the beneficiary when making withdrawal requests.

{
    "success": true,
    "payload": {
        "contact_id": 4980,
        "alias": "XRPTesting",
        "taxonomy": {
            "network": "rp",
            "asset": "xrp",
            "protocol": "ripple",
            "integration": "rippled",
            "currency": "xrp"
        },
        "currency": "xrp",
        "details": [
            {
                "name": "Address",
                "key": "address",
                "value": "******T633ra63CcDXG6AciFT6qj******"
            },
            {
                "name": "Destination tag",
                "key": "destination_tag",
                "value": "5403767"
            }
        ],
        "created": "2023-05-03T18:33:39Z",
        "compliance": {
            "travel_rule": {
                "vasp": {
                    "did": "did:ethr:0x4cd9136034d9a63d855391fce6dba64021530b01"
                },
                "beneficiary": {
                    "name": "Jane Doe",
                    "type": "NATURAL"
                }
            }
        }
    }
}

{
    "success": true,
    "payload": {
        "contact_id": 3498,
        "alias": "StellarNetwork",
        "taxonomy": {
            "network": "circle",
            "asset": "usdc",
            "protocol": "usdc_trf",
            "integration": "circle-api",
            "currency": "usd"
        },
        "currency": "usd",
        "details": [
            {
                "name": "Address",
                "key": "address",
                "value": "******IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3Z******"
            },
            {
                "name": "Destination tag",
                "key": "addressTag",
                "value": "memo"
            },
            {
                "name": "chain",
                "key": "chain",
                "value": "xlm"
            }
        ],
        "created": "2023-02-21T18:29:29Z",
        "compliance": {
            "travel_rule": {
                "vasp": {
                    "did": "did:ethr:0x4cd9136034d9a63d855391fce6dba64021530b01"
                },
                "beneficiary": {
                    "name": "StellarNetwork",
                    "type": "LEGAL"
                }
            }
        }
    }
}

{
    "success": true,
    "payload": {
        "contact_id": 3813,
        "alias": "SolanaTest",
        "taxonomy": {
            "network": "circle",
            "asset": "usdc",
            "protocol": "usdc_trf",
            "integration": "circle-api",
            "currency": "usd"
        },
        "currency": "usd",
        "details": [
            {
                "name": "Address",
                "key": "address",
                "value": "******sqQcKF7KcDNnNuSmiQmdq7k9CG6C19rZ******"
            },
            {
                "name": "chain",
                "key": "chain",
                "value": "SOL"
            }
        ],
        "created": "2023-03-07T19:29:31Z",
        "compliance": {
            "travel_rule": {
                "vasp": {
                    "did": "did:ethr:0x4cd9136034d9a63d855391fce6dba64021530b01"
                },
                "beneficiary": {
                    "name": "SolanaTest",
                    "type": "LEGAL"
                }
            }
        }
    }
}

{
    "success": true,
    "payload": {
        "contact_id": 6456,
        "alias": "USDTTronTest",
        "taxonomy": {
            "network": "tron",
            "asset": "usdt",
            "protocol": "trc20",
            "integration": "fblocks-v1",
            "currency": "usdt"
        },
        "currency": "usdt",
        "details": [
            {
                "name": "Address",
                "key": "address",
                "value": "******12r9tya9NTp5qzVgQvmqAf******"
            }
        ],
        "created": "2023-07-10T21:09:21Z",
        "compliance": {
            "travel_rule": {
                "vasp": {
                    "did": "did:ethr:0x4cd9136034d9a63d855391fce6dba64021530b01"
                },
                "beneficiary": {
                    "name": "USDTTronTest",
                    "type": "LEGAL"
                }
            }
        }
    }
}