Build a sample app
Customers and accounts
15 min
create a customer record and a funded account customers and accounts /#create a customer record customers and accounts /#create a deposit account a deposit account customers and accounts /#fund an account an account create a customer record before you use cross river services, you need to onboard a customer for each of your customers the customer onboarding process includes creating a customer record with relevant customer information all customers are automatically scanned for regulatory compliance purposes, so you need to register for relevant webhooks events to receive customer record status updates the customer record can be for either personal or business customers once registered, a customer can be associated with one or more accounts webhooks accounts, cards and payment events for webhooks the following webhooks are used true false 267false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type false unhandled content type example of record creation in this example, we'll onboard john smith first, let's create a customer record we are registering john as a personal customer to onboard a business customer, first create a personal customer record for the primary owner of that business after that, create a business customer and add the personal record as a add a beneficial owner call post /core/v1/cm/customers in the following example you can see customer management apis are required important we highly recommend you include an idempotency docid\ jiv0q1 cymjqqger3ijmp in your request header to provide duplicate protection in the event of a failure curl x post /core/v1/cm/customers header 'content type application/json' header 'accept application/json' header 'authorization bearer xxx' d '{ \\ { "partnerid" "6e80b097 693c 4592 8440 02f345335bbf", "name" { "firstname" "john", "lastname" "smith" }, "classification" "personal", "profile" { "rego" false, "politicallyexposedperson" false, "taxidtype" "ssn", "taxid" "119988776", "birthdate" "1953 09 22", "riskrating" "low" "primaryaddress" { "addresstype" "home", "classification" "residential", "isprimary" true, "street1" "123 any st", "city" "anywhere", "state" "ny", "postalcode" "12345", "countrycode" "us" }, "primaryphone" { "isprimary" true, "phonetype" "home", "phonenumber" "2015551234" }, "primaryemail" { "isprimary" true, "emailtype" "personal", "emailaddress" "john smith\@xxxxx com" } } a successful api call returns a json response with the unique customer id in the first line of the response body your customer has been created onboarding a customer response body { "id" "9052b6a5 3f09 41d1 b526 ade80104eb79", "cifnumber" "32653745014", "classification" "personal", "status" "active", "ofac" "pending", "pepscan" "pending", "name" { "firstname" "john", "lastname" "smith", "fullname" "john smith" }, "profile" { "rego" false, "politicallyexposedperson" false, "enablebackupwithholding" false, "taxidtype" "ssn", "taxid" "119988776", "birthdate" "1953 09 22", "riskrating" "low" }, "createdat" "2021 01 25t17 55 24 4422582 05 00", "lastmodifiedat" "2021 01 25t17 55 24 4432543 05 00", "partnerid" "6e80b097 693c 4592 8440 02f345335bbf" } the core customer onboarded webhook event is triggered when the customer record is created customer onboarded event { "id" "3d9c5e1a 623b 4cf2 812e ade80105048e", "eventname" "core customer onboarded", "status" "pending", "partnerid" "30dee145 b6a2 4058 8dc3 ac4000dee91f", "createdat" "2021 11 22t10 50 20 553 05 00", "resources" \[ "core/v1/cm/customers/9052b6a5 3f09 41d1 b526 ade80104eb79" ], "details" \[] } cross river scans the new customer record for ofac and pep compliance sometimes the results of the scan require a review by the our anti money laundering (aml) team on scan completion, core customer ofac changed and core customer pepscan changed webhook events return with a status customers with no compliance issues show a clear status customer ofac scan changed { "id" "45db5592 56ee 41f5 85e7 ade8010571ce", "eventname" "core customer ofac changed", "status" "pending", "partnerid" "30dee145 b6a2 4058 8dc3 ac4000dee91f", "createdat" "2021 11 22t10 51 53 657 05 00", "resources" \[ "core/v1/cm/customers/9052b6a5 3f09 41d1 b526 ade80104eb79" ], "details" \[] } customer pep scan changed { "id" "a5000831 3e01 4231 9ec2 ade8010571c5", "eventname" "core customer pepscan changed", "status" "pending", "partnerid" "30dee145 b6a2 4058 8dc3 ac4000dee91f", "createdat" "2021 11 22t10 51 53 597 05 00", "resources" \[ "core/v1/cm/customers/9052b6a5 3f09 41d1 b526 ade80104eb79" ], "details" \[] } you have now created a customer record update customer record it is possible to update the customer details such as address, phone number and email these details are considered primary information if you add a second address, this is secondary use the customer id returned when you create the customer record to call post /core/v1/cm/customers/{id}/addresses to add the customer management apis the first address you add is the primary address in the following example you can see which attributes are required update customer address post /core/v1/cm/customers/9052b6a5 3f09 41d1 b526 ade80104eb79/addresses { "addresstype" "home", "classification" "residential", "isprimary" true, "street1" "123 any st", "city" "anywhere", "state" "ny", "postalcode" "12345", "countrycode" "us" } call post /core/v1/cm/customers/{id}/phones to add the customer management apis the first phone number you add is the primary phone number update customer phone number post /core/v1/cm/customers/9052b6a5 3f09 41d1 b526 ade80104eb79/phones { "isprimary" true, "phonetype" "mobile", "phonenumber" "2015552345" } c all post /core/v1/cm/customers/{id}/email to update the customer management apis update customer email post /core/v1/cm/customers/9052b6a5 3f09 41d1 b526 ade80104eb79/email { "isprimary" true, "emailtype" "personal", "emailaddress" "john jones\@xxx com" } create a deposit account cr provides a number of different types of accounts, including check and savings, certificates of deposit (cds or time deposit accounts), and more to open any kind of deposit account you must have a valid product id for the type of account you want to open, and a customer id (onboarded customer record id) for the account holder note that the account holder must have at least one address and phone number in their customer record, and their ofac status must be clear in addition, the classification of the customer must match the configured classification for the product for example, only business customers can be added to a business product before you begin make sure you have get api credentials partner id (that you received when you registered) onboard a customer cos product types and ids (defines the type of account being opened) important we strongly recommend that you include an idempotency in the request header to prevent duplicate payments in case of a failure endpoints and webhooks the following api endpoint is used true falsefalse unhandled content type false unhandled content type false unhandled content type false unhandled content type the following webhook is used true falsefalse unhandled content type false unhandled content type false unhandled content type false unhandled content type open an account in the following scenario, you'll open an account for john smith, a customer who you successfully onboarded to open an account call post core/v1/dda/accounts for this call, some attributes are required see the full accounts sample request post /core/v1/dda/accounts { "customerid" "59e3bc15 bbec 4990 88e9 a9a600d3296c", "productid" "44015e68 1afb 40fc 9497 abc1014f52da", "title" "john smith", "statementaddress" { "street1" "257 dalton groves", "city" "barton city", "state" "mi", "postalcode" "48705", "countrycode" "us" } } a successful api call returns a json response with the details of the new account sample response post /core/v1/dda/accounts { "customerid" "59e3bc15 bbec 4990 88e9 a9a600d3296c", "productid" "44015e68 1afb 40fc 9497 abc1014f52da", "title" "john smith", "statementaddress" { "street1" "257 dalton groves", "city" "barton city", "state" "mi", "postalcode" "48705", "countrycode" "us" } } the accountnumber field provides the account number for the new account in the response example, the account is classified as personal because the user configured the product classification as personal the account classification always matches the configured product classification the account status is automatically updated to active , and is immediately available for use this triggers the core account opened event core account opened event details { "id" "259cdbca 6a89 4af8 a50e ada3010fb13f", "eventname" "core account opened", "status" "pending", "partnerid" "e6c3824a 377f 44d5 a2f6 a9a600c9b37e", "createdat" "2021 01 26t09 48 10 1011462 05 00", "resources" \[ "core/v1/dda/accounts/2235223803" ], "details" \[] } fund an account when you work in the sandbox to test payment rails and account behavior you need to have funds in an account you can use any rail that has an inbound simulation endpoint to fund a sandbox account, if the account is configured for it in particular, you can simulate inbound ach payments simulate an inbound wire for any simulation, you need the number of the cross river sandbox account that you want to fund the originator information is not important, and in some cases can even be completely fictitious next steps check out our payment tutorials