TradingJuno
Guides

Add a Receiving Account

Every receiving account is associated with a transaction's taxonomy that identifies a currency, a method, and an integration with a payment gateway. When creating an account, you must specify this metadata in the request body, which includes: asset, integration, network, and protocol. In some countries, another piece of information you might need to specify in your request is the bank's code that holds the account.

The following specifies the endpoints that enable you to retrieve the needed data.

Retrieve the Taxonomy Parameters

To determine the specific values of the taxonomy parameters for the currency you want to withdraw, 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}

Path Parameters

  • currency: Specifies the currency to use with the receiving account. Possible fiat values: mxn, brl, ars, and cop.

Retrieve the Bank's Code

To determine the code you need, make an HTTP call to the following endpoint, which retrieves the codes assigned to banks of a particular country:

GET https://stage.bitso.com/api/v3/banks/{country}

Path Parameters

  • country: Specifies the country where the bank that holds the account is located; uses code standard ISO 3166-1 alpha-2. Valid values: mx, br, and co.

Create the Account

🚀 You are now ready to create your receiving account for sending funds. To execute the account creation, make the following HTTP request using the appropriate body parameters:

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

The rest of the article provides examples of account creation calls for supported fiat currencies. The response returned to the account creation call includes the variable user_id, which represents the account holder's Bitso-provided identifier. It returns with the value set to zero for security reasons.

Receiving Accounts in MXN

Body Parameters

  • alias: Name that helps users identify the account.
  • currency: Currency used in the account.
  • details: Contains objects that provide further information on the account:
    • beneficiary: Recipient's full name.
    • clabe: unique, 18-number identifier of the receiving bank account that follows the Mexican standard for account numbering (Clave Bancaria Estandarizada). In the case of the Debit Card method, it stores the card number, and in the case of the Phone Number, it holds the mobile phone number.
    • institution_code: Identifier of the bank that holds the receiving account.
  • taxonomy: Contains the taxonomy of the transaction, which is linked to the account.
    • asset: The asset in the network on which you can withdraw the selected currency.
    • integration: A specific integration that enables Bitso to connect to a given network.
    • network: Network through which the transaction is processed.
    • protocol: A specific mechanism, protocol, or standard used in a network.

Examples of Account Creation Requests

The following objects exemplify the body parameters used in the create receiving account request for the three possible methods for MXN:

{
   "alias": "Test CLABE",
   "currency":"mxn",
   "taxonomy":{
      "network":"spei",
      "asset":"mxn",
      "protocol":"clabe",
      "integration":"praxis"
   },
   "details":{
      "beneficiary":"Juanita Pérez",
      "institution_code":"37006",
      "clabe":"123456789123456789"
   }
}
{
   "alias":"Test Debit Card",
   "currency":"mxn",
   "taxonomy":{
      "network":"spei",
      "asset":"mxn",
      "protocol":"debitcard",
      "integration":"praxis"
   },
   "details":{
      "beneficiary":"Juan Pérez",
      "institution_code":"40002",
      "clabe":"5482347403740547"
   }
}
{
   "alias":"Test Phone Number",
   "currency":"mxn",
   "taxonomy":{
      "network":"spei",
      "asset":"mxn",
      "protocol":"phonenum",
      "integration":"praxis"
   },
   "details":{
      "beneficiary":"Tolentino Pérez",
      "institution_code":"37019",
      "clabe":"8180833954"
   }
}

Examples of Account Creation Responses

A successful account creation returns the following response bodies. The returned payload includes the variable contact_id, which helps you identify the receiving account when making withdrawal requests.

{
   "success":true,
   "payload":{
      "contact_id":835,
      "user_id":0,
      "alias":"Test CLABE",
      "taxonomy":{
         "network":"spei",
         "asset":"mxn",
         "protocol":"clabe",
         "integration":"praxis"
      },
      "currency":"mxn",
      "details":[
         {
            "name":"Beneficiary",
            "key":"beneficiary",
            "value":"Juanita Pérez"
         },
         {
            "name":"CLABE",
            "key":"clabe",
            "value":"123456789123456789"
         },
         {
            "name":"Bank",
            "key":"institution_code",
            "value":"BANCOMEXT"
         }
      ],
      "created":"2022-08-25T21:55:28Z"
   }
}
{
   "success":true,
   "payload":{
      "contact_id":838,
      "user_id":0,
      "alias":"Test Debit Card",
      "taxonomy":{
         "network":"spei",
         "asset":"mxn",
         "protocol":"debitcard",
         "integration":"praxis"
      },
      "currency":"mxn",
      "details":[
         {
            "name":"Beneficiary",
            "key":"beneficiary",
            "value":"Juan Pérez"
         },
         {
            "name":"Debit card",
            "key":"clabe",
            "value":"5482347403740547"
         },
         {
            "name":"Bank",
            "key":"institution_code",
            "value":"BANAMEX"
         }
      ],
      "created":"2022-08-25T23:24:02Z"
   }
}
{
   "success":true,
   "payload":{
      "contact_id":840,
      "user_id":0,
      "alias":"Test Phone Number",
      "taxonomy":{
         "network":"spei",
         "asset":"mxn",
         "protocol":"phonenum",
         "integration":"praxis"
      },
      "currency":"mxn",
      "details":[
         {
            "name":"Beneficiary",
            "key":"beneficiary",
            "value":"Tolentino Pérez"
         },
         {
            "name":"Phone number",
            "key":"clabe",
            "value":"8180833954"
         },
         {
            "name":"Bank",
            "key":"institution_code",
            "value":"BANJERCITO"
         }
      ],
      "created":"2022-08-26T00:01:27Z"
   }
}

Receiving Accounts in BRL

BRL withdrawals require the client application to provide taxonomy parameters during the preview stage of the transaction. As a result, these transactions do not support previously created receiving accounts, and missing taxonomy parameters result in an error.

Receiving Accounts in ARS

Body Parameters

  • alias: Name that helps users identify the account.
  • currency: Currency used in the account.
  • details: Contains objects that provide further information on the account:
    • cvu: Clave Virtual Uniforme, unique, 22-digit code that identifies a virtual, nonbank account. You can also use the CBU (Clave Bancaria Uniforme), which identifies a bank account issued either by a traditional or digital bank.
    • recipient_name: Full name of the receiving account holder.
  • taxonomy: Contains the taxonomy of the transaction, which is linked to the receiving account.
    • asset: The asset in the network on which you can withdraw the selected currency.
    • integration: A specific integration that enables Bitso to connect to a given network.
    • network: Network through which the transaction is processed.
    • protocol: A specific mechanism, protocol, or standard used in a network.

Example of an Account Creation Request

The following object exemplifies the body parameters used in the create receiving account request for the possible method in ARS:

{
   "alias":"Testing ARS",
   "currency":"ars",
   "taxonomy":{
      "network":"coelsa",
      "asset":"ars",
      "protocol":"cvu",
      "integration":"bind"
   },
   "details":{
      "recipient_name":"JuanJo Martinelli",
      "cvu":"1430001713001199250012"
   }
}

Example of an Account Creation Response

A successful account creation returns the following response body. The returned payload includes the variable contact_id, which helps you identify the receiving account when making withdrawals requests:

{
   "success":true,
   "payload":{
      "contact_id":1223,
      "user_id":0,
      "alias":"Testing ARS",
      "taxonomy":{
         "network":"coelsa",
         "asset":"ars",
         "protocol":"cvu",
         "integration":"bind"
      },
      "currency":"ars",
      "details":[
         {
            "name":"CVU",
            "key":"cvu",
            "value":"1430001713001199250012"
         },
         {
            "name":"Beneficiario/a",
            "key":"recipient_name",
            "value":"JuanJo Martinelli"
         }
      ],
      "created":"2022-09-29T18:04:43Z"
   }
}

Receiving Accounts in COP

Body Parameters

  • alias: Name that helps users identify the account.
  • currency: Currency used in the account.
  • details: Contains objects that provide further information on the account:
    • account_type: Digit that identifies the receiving account type.
      Possible values: 1-Checking and 2-Savings.
    • bank_account: Identifier of the account that receives the funds.
    • bank_code: Code that identifies the bank that holds the receiving account.
    • beneficiary_name*: First name of the account holder who receives the sent funds. It can also be a company name.
    • beneficiary_lastname*: Last names of the account holder who receives the sent funds.
    • document_id*: Unique identifier of the beneficiary's identity document.
    • document_type*: Code that defines the beneficiary's identity document. Valid values:
      • CC - Cédula de Ciudadanía
      • CE - Cédula de Extranjería
      • NIT - Número de Identificación Tributaria
      • PASS - Passport
      • PEP - Permiso Especial de Permanencia
    • email*: Beneficiary's email address.
    • third_party_withdrawal*: A Boolean flag that indicates whether the funds are sent to a third party. Determines where to search for the beneficiary's information.
  • taxonomy: Contains the taxonomy of the transaction, which is linked to the receiving account.
    • asset: The asset in the network on which you can withdraw the selected currency.
    • integration: A specific integration that enables Bitso to connect to a given network.
    • network: Network through which the transaction is processed.
    • protocol: A specific mechanism, protocol, or standard used in a network.
📘

Third-Party Withdrawal Parameters

The parameter names followed by an asterisk in the list above are used only in third-party accounts.

Examples of Account Creation Requests

The following objects exemplify the body parameters used in the create receiving account request:

{
   "alias":"Testing",
   "currency":"cop",
   "taxonomy":{
      "network":"pse",
      "asset":"cop",
      "protocol":"pse",
      "integration":"dlocal"
   },
   "details":{
      "bank_account":"87654321",
      "account_type":"1",
      "bank_code":"064"
   }
}
{
    "alias" : "Testing 3rd party withdrawal",
    "currency": "cop",
    "taxonomy" : {
        "network": "pse",
        "asset": "cop",
        "protocol": "pse",
        "integration": "dlocal"
    },
    "details": {
        "bank_account": "12345679",
        "bank_code": "051",
        "account_type": "2",
        "third_party_withdrawal": "true",
        "beneficiary_name": "Fernando",
        "beneficiary_lastname": "Guzman Alarcón",
        "document_id": "1661105408",
        "document_type": "CC",
        "email": "[email protected]"
    }
}
{
   "alias":"Testing",
   "currency":"cop",
   "taxonomy":{
      "network":"ach",
      "asset":"cop",
      "protocol":"ach_co",
      "integration":"cobre"
   },
   "details":{
      "bank_account":"87654321",
      "account_type":"1",
      "bank_code":"064"
   }
}

Example of an Account Creation Response

A successful account creation returns the following response body. The returned payload includes the variable contact_id, which helps you identify the receiving account when making withdrawals requests:

{
   "success":true,
   "payload":{
      "contact_id":1423,
      "user_id":0,
      "alias":"Testing",
      "taxonomy":{
         "network":"pse",
         "asset":"cop",
         "protocol":"pse",
         "integration":"dlocal"
      },
      "currency":"cop",
      "details":[
         {
            "name":"Número de cuenta",
            "key":"bank_account",
            "value":"87654321"
         },
         {
            "name":"Banco",
            "key":"bank_code",
            "value":"Banco Multibank S.A."
         },
         {
            "name":"Tipo de cuenta",
            "key":"account_type",
            "value":"Checking"
         }
      ],
      "created":"2022-10-14T22:25:13Z"
   }
}
{
    "success" : true,
    "payload" : {
            "contact_id": 1455,
            "user_id": 0,
            "alias": "Testing 3rd party withdrawal",
            "taxonomy": {
                "network": "pse",
                "asset": "cop",
                "protocol": "pse",
                "integration": "dlocal"
            },
            "currency": "cop",
            "details": [
                {
                    "name": "Account number",
                    "key": "bank_account",
                    "value": "12345679"
                },
                {
                    "name": "Bank",
                    "key": "bank_code",
                    "value": "Banco Davivienda"
                },
                {
                    "name": "beneficiary_name",
                    "key": "beneficiary_name",
                    "value": "Fernando"
                },
                {
                    "name": "beneficiary_lastname",
                    "key": "beneficiary_lastname",
                    "value": "Guzman Alarcón"
                },
                {
                    "name": "third_party_withdrawal",
                    "key": "third_party_withdrawal",
                    "value": "true"
                },
                {
                    "name": "document_id",
                    "key": "document_id",
                    "value": "1661105408"
                },
                {
                    "name": "Account type",
                    "key": "account_type",
                    "value": "Savings"
                },
                {
                    "name": "Email",
                    "key": "email",
                    "value": "[email protected]"
                },
                {
                    "name": "Type of document",
                    "key": "document_type",
                    "value": "CC"
                }
            ],
            "created": "2022-10-21T17:13:23Z"
        }
}

Updated 8 months ago

Did this page help you?