In the event that you have already set a contact up in your Split account and they would like to update their bank account details, you can follow this article to correctly change their account details and continue debiting them.

The steps involved with changing a Contacts Bank Account details will vary depending on whether you are KYC trusted or not.

KYC Trusted

If your account is KYC trusted, changing a Contacts Bank details is a simple process and can be done programmatically via the API or manually via the User Interface.

Please Note

If the contact that you are editing has an active Bank Connection, this will be lost when changing bank details. Once you have followed the steps in this document and the details are updated, you will need to invite this contact to confirm their credentials to be able to use the Bank Connection again.

If your standard on-boarding process involves passing a Bank Connection to us via the KYC endpoint, you may want to remove the existing Contact and Agreement and use that same endpoint to create a new Contact with the updated details rather than following the steps in this document.

In addition to this, any metadata that was stored against the Agreement will not be accessible anymore as the existing Agreement is deleted and a new one created. If this is an issue for your integration, as above, you may want to remove the existing Contact and Agreement and use the KYC endpoint to create a new Contact instead of following this document. 

KYC via the API

Our update contact endpoint now has the option to include the branch_code and account_number fields when submitting a PATCH request. An example body parameter is shown below.

PATCH /contacts/{id}

{
  "name": "New Name",
  "email": "newemail@example.com",
  "branch_code": "123456",
  "account_number": "456789"
}

The above request will change the details of the contact referenced by the id in the endpoint url. You are able to specify multiple fields to change, as done above, or a single field should you only want to change that field.

An example successful response is shown below

{
  "data": {
    "id": {id},
    "name": "New Name",
    "email": "newemail@example.com",
    "type": "Split account",
    "bank_account": {
      "id": {bank_account_id},
      "account_number": "456789",
      "branch_code": "123456",
      "bank_name": "{bank_name}",
      "state": "active",
      "iav_provider": "split",
      "iav_status": "active",
      "blocks": {
        "debits_blocked": false,
        "credits_blocked": false
      }
    },
    "bank_connection": {
      "id": "1030bfef-cef5-4938-b10b-5841cafafc80"
    }
  }
}

KYC via the User Interface

You are now able to change your contacts Bank details using your Split account user interface. Follow these simple steps to successfully update a BSB and Account Number for your contact. 

  • Log into your Split Account
  • Click on the Contacts button on the lefthand side of your dashboard
  • Locate the Contact you wish to edit and click on their blue reference number 
  • Click on the green Edit button in the top right of this page
  • On this page you are able to enter a new BSB and Account Number for this Contact
  • Once the new numbers have been entered click on the green Change Bank Account button
  • You should have taken you to your Contacts page again with a green success message stating that the contact was updated.

Keep in mind that changing a contacts Bank Account will remove the existing Agreement that is in place between you and this Contact and create a new identical one in its place. If your integration uses an Agreements reference number, A.xxxx  for any reason, this reference will need to be updated to this new Agreements reference.

Not KYC Trusted

To change a customers banking details, you will need to create a new Contact with the new bank account details. Before you do this, we recommend that you remove the existing Contact in order to keep a "clean" contact list, and make referencing the correct Contact easier.

You can remove a contact via the Split User Interface or the API depending on what type of integration you currently have with us. Choose from the options below to see how to remove a contact using your preferred method.

Now that you have removed the contact and all associated Agreements you can create a new Contact with updated banking credentials. How you do this will, again, depend on what type of integration you have. Choose from the following options to see how to add a Contact using your preferred method.

Remove a Contact With the Split Interface

In order to change your customers bank details you will first need to stop any current Payment Request Schedules that you have in place with them. 

Once this is done you can remove the Agreement you have in place between your company and this contact.

With the Payment Request Schedule and Agreement removed you are now able to remove this contact from your contact list.

Now that you have removed the previous contact and any details associated with them, you can create a new contact.

Remove a Contact With the Split API

To remove a Contact you will require the associated contact ID. You can find this using the API:

# Make a GET request to the following endpoint to retrieve all details
# associated with this contact

GET /contacts?name={contact_name}

Note. You have multiple query string options that can be used to filter your contacts. These are outlined here

Our response to this request will include the contacts ID which should be persisted for future use in this process.

You are now able to use this contact ID to retrieve all outgoing Agreements that are currently in place between you and this contact. These need to be cancelled in order to remove the contact. To remove these you will need to list each Agreement and then use the associated Agreement reference (A.xxxx) to cancel each one.

GET /agreements/outgoing?contact_id={contact_id}

Documentation on above endpoint

You can then use the returned Agreement references with the following endpoint to cancel each Agreement.

DELETE /agreements/{agreement_ref}

Documentation on above endpoint
Note. Any Payment Requests that were approved prior to this cancellation will still go ahead and should be cancelled if you don't want them to proceed.

Now that all Agreements are cancelled you can go ahead and remove this contact using the following endpoint.

DELETE /contacts/{contact_id}

Documentation on above endpoint

This contact has now been removed and you are able to create a new contact with updated banking credentials.

Add a Contact using an Open Agreement

Now that you have removed this contact and all details associated with them, you are able to share your Open Agreement link with them and have them fill it out using their updated credentials. This will do two things:

  1. Create a contact in your Split Account with the correct banking details
  2. Put an Agreement in place between yourself and this contact, allowing you to issue Payment Requests and create any Payment Request Schedules you require.

The following is the process your contact should go through when viewing the link you have copied.

You are now able to issue any Payment Requests or create Payment Request Schedules that you normally would.

Add a contact using an Unassigned Agreement

Now that this contact has been removed, you are able to create a new contact with new banking credentials. You can do this as you normally would by POSTing a valid payload to the Unassigned Agreements endpoint and giving the retrieved link to your customer to follow. When your customer clicks on this link they will be able to enter their updated credentials and verify the bank account by filling out the displayed form.

Example body of an API call to propose an Unassigned Agreement link.

POST the following body to the /unassigned_agreements endpoints.

{
  "expiry_in_seconds": 60,
  "terms": {
    "per_payout": {
      "min_amount": null,
      "max_amount": 10000
    },
    "per_frequency": {
      "days": 7,
      "max_amount": 1000000
    }
  }
}

Example response to the previous call. Note the link field.

{
  "data": {
    "ref": "A.4k",
    "initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
    "status": "proposed",
    "responded_at": null,
    "created_at": "2017-03-20T00:53:27Z",
    "terms": {
      "per_payout": {
        "max_amount": 10000,
        "min_amount": null
      },
      "per_frequency": {
        "days": 7,
        "max_amount": 1000000
      }
    },
    "assignment_expires_at": "2017-03-20T00:54:27Z",
    "link": "https://go.sandbox.split.cash/unassigned_agreements/b61fc159-8779-4a17-a826-e398e3e7e211/invitation"
  }
}

When your customer follows the retrieved link they will go through the following process.

Once your Contact has correctly filled out this form you will be able to issue Payment Requests and set up Schedules as you normally would.

Did this answer your question?