Finxera

Back to documentation index

createClient

Use the createClient method to register a user (Client) onto the Finxera platform. Creating the client is the first step to tokenizing external account information, such as a credit card number, or for opening a bank account for your user, collecting money into the account, and sending money to billers or other users. It is important to note, for the purposes of tokenizing payment information, such as external bank account for ACH collections, or credit card information, you do not need to provide DOB or SSN information. However, when creating a bank account under the client, the following four fields are required:
            1. First Name
            2. Last Name
            3. DOB
            4. SSN
While createClient will not fail if you do not provide the DOB and SSN, you will not be able to execute openAccount for that client until you provide correct information for these fields, and subsequently, use the verifyClient API to perform identity verification necessary for opening a bank account.
The createClient API has been enhanced to link a client with a Merchant. There is an optional parameter Merchant ID in the API which does this linking. While creating a client, if all the information (personal, address and contact) is entered and also a Merchant ID, a link between the client and merchant will be established. In case no client information is entered but only the merchant ID, the API will fetch all the possible client related information from the merchant record and insert it for the client.
 View Demo

Request Parameters

  Parameter Required Type Description
subscriberId Y Long Specify subscriber ID issued when Finxera account is created
referenceId N String Create a subscriber-set reference ID for the client being created (Max length:45)
firstName Y String Client first name (Max length:45)
lastName Y String Client last name (Max length:45)
middleInitial N String Client middle name initial (Max length:45)
ssn N String Client social security number can be either in the format NNN-NN-NNNN (with hyphens) or NNNN (last four digits)
dob N date Client date of birth must be a valid date formatted as YYYY-MM-DD
+ address N Object Address
homePhone N String Client home phone number
mobilePhone N String Client mobile phone number
workPhone N String Client work phone number
email N String Client email address (Max length:45)
username N String Login username for Finxera client portal (Max length:45)
merchantId N int On providing the mandatory information in the create client, the client is created with the details provided even if MerchantId is provided. In case no information is provided while creating the client except the merchant Id, then the client is created as per the information stored for the provided merchant Id.When we provide only the merchantId and no other information to create a client, client is created with the details of that particular merchant. In every case merchantId gets linked to the client created.

Response Parameters

  Parameter   Type Description
requestId   Long 13 digit ID for the API request being made
status   int Status of completed request, either 1 for pass, or 0 for fail
+ warnings   Object A Warning object containing a code and description.
+ errors   Object Request failed, error response.
+ clientId   Object Client Id
cipStatus   String Responds with one of the following cipstatuses for the newly created client { 'VERIFIED', 'REJECTED', 'IGNORED', 'UNVERIFIED'}
clientStatus   String Responds with one of the following statuses of the client { 'ACTIVE', 'INACTIVE', 'CANCELLED', 'SUSPENDED', 'DELETED'
username   String User name

WSDL URL (Production) :  https://api.bancbox.com/v3/BBXPort?wsdl
WSDL URL (SandBox) :  https://sandbox-api.bancbox.com/v3/BBXPort?wsdl

Sample Request

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
xmlns:sch="schema.bancbox.com">
    <soapenv:Header>
        <wsse:Security soapenv:mustUnderstand="1" xmlns:wsse="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-secext-1.0.xsd">
            <wsse:UsernameToken wsu:Id="XWSSGID-1261544568770-474929336" xmlns:wsu="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-wssecurity-utility-1.0.xsd">
                <wsse:Username>sample@email.com</wsse:Username>
                <wsse:Password Type="http://docs.oasis-open.org/wss/2004/01/oasis-200401-wss-username-token-profile-1.0#PasswordText">sample</wsse:Password>
            </wsse:UsernameToken>
        </wsse:Security>
    </soapenv:Header>
    <soapenv:Body>
        <sch:createClient>
            <createClientRequest>
                <subscriberId>?</subscriberId>
                <!--Optional:-->
                <referenceId>?</referenceId>
                <firstName>?</firstName>
                <lastName>?</lastName>
                <!--Optional:-->
                <middleInitial>?</middleInitial>
		<!--Optional:-->
                <ssn>?</ssn>
		<!--Optional:-->
                <dob>?</dob>
		<!--Optional:-->
                <address>
		    <!--Optional:-->
                    <line1>?</line1>
                    <!--Optional:-->
                    <line2>?</line2>
		    <!--Optional:-->
                    <city>?</city>
		    <!--Optional:-->
                    <state>?</state>
		    <!--Optional:-->
                    <zipcode>?</zipcode>
                </address>
		<!--Optional:-->
                <homePhone>?</homePhone>
                <!--Optional:-->
                <mobilePhone>?</mobilePhone>
                <!--Optional:-->
                <workPhone>?</workPhone>
		<!--Optional:-->
                <email>?</email>
                <!--Optional:-->
                <username>?</username>
		<!--Optional:-->
		<merchantId>?</merchantId>
            </createClientRequest>
        </sch:createClient>
    </soapenv:Body>
</soapenv:Envelope>

Sample Response

<sch:createClientResponse>
        <return>
            <!--Optional:-->
            <requestId>?</requestId>
            <status>?</status>
            <!--Zero or more repetitions:-->
            <warnings>
               <!--Optional:-->
               <code>?</code>
               <!--Optional:-->
               <message>?</message>
            </warnings>
            <!--Zero or more repetitions:-->
            <errors>
               <!--Optional:-->
               <code>?</code>
               <!--Optional:-->
               <message>?</message>
            </errors>
            <!--Optional:-->
            <clientId>
               <!--Optional:-->
               <bancBoxId>?</bancBoxId>
               <!--Optional:-->
               <subscriberReferenceId>?</subscriberReferenceId>
            </clientId>
            <!--Optional:-->
            <clientStatus>?</clientStatus>
	    <!--Optional:-->
            <cipStatus>?</cipStatus> 
            <!--Optional:-->
            <username>?</username>
         </return>
</sch:createClientResponse>

Note:For REST, Content-type should be set to application/json
URL (Production) :  https://api.bancbox.com/v3/BBXPortRest/createClient
URL (SandBox) :  https://sandbox-api.bancbox.com/v3/BBXPortRest/createClient

Sample Request

{
    "authentication": {
        "apiKey": "YOUR_API_KEY_HERE",
        "secret": "SECRET_PASSPHRASE"
    },
    "subscriberId": ,
    "referenceId": "",
    "firstName": "",
    "lastName": "",
    "middleInitial": "",
    "ssn": "",
    "dob": "",
    "address": {
        "line1": "",
        "line2": "",
        "city": "",
        "state": "",
        "zipcode": ""
    },
    "homePhone": "",
    "mobilePhone": "",
    "workPhone": "",
    "email": "",
    "username": "",
    "merchantId":""
}

Sample Response

{
    "clientId": {
        "bancBoxId": ? ,
        "subscriberReferenceId" : "?"
    },
    "clientStatus": "?",
     "cipStatus": "?",
    "username": "?",
    "requestId": ? ,
    "status" : ? ,
    "warnings" : [{
        "code": "?",
        "message": "?"
    }],
    "errors": [{
        "code": "?",
        "message": "?"
    }]
} 

Note: This is a beta version. The api listed here are likely to change.