About KYC Trusted Customer Accounts

It is a strict requirement when setting up regular payments via direct entry that a customer sights and agrees to a Direct Debit Request (DDR) and a Direct Debit Request Service Agreement (DDRSA). Similarly, there are also minimum identification requirements for the on-boarding process, referred to as ‘Know Your Customer’, or KYC. 

Using the standard Split Payments API integration, these DDR and DDRSA documents are embedded as links, and the KYC requirements are handled as part of the Instant Account Verification (IAV) process. We fully appreciate, however, that some of our partners have an existing on-boarding process with Illion Open Data Solutions Bank Feeds, for example, that collects the required KYC materials before passing this information through to establish regular direct debits via Split Payments.

To cater for this, Split Payments offer a KYC-Trusted status for partners that meet the following requirements:

Minimum Requirements for KYC-Trusted Status

  • Display the Split DDRSA via a link or copy in-App: www.splitpayments.com.au/ddrsa
  • Display the Split DDR via a link or copy in-App: www.splitpayments.com.au/ddr
  • Record & archive the acceptance of the DDR (via check-box opt-in for example)
  • Ensure the record can be provided in the event of any payment disputes.
  • Demonstrate a process of how you will keep a copy of the DDR
  • Demonstrate how you provide a customer either a printed or non-changeable electronic copy of the Direct Debit Request and DDR Service Agreement within 7 days. (ex. emailing them a confirmation email with their T's and C's of using the platform)
  • Provide evidence of suitable refund or dispute policy in place
  • Demonstrate how a customer is identified and that you keep this information.

Step 1 – Set up a Sandbox Account

The first step to configure your KYC status is to set up a sandbox account. This allows you to configure our platform using dummy information for testing purposes. 

Step 2 – Configure the Proviso integration

To set up the Proviso integration on our platform:

  1. Sign in to your Split Payments sandbox account
  2. Click on the arrow on the top left corner and select Settings then Integrations
  3. If your KYC Status has been activated, you will see a Proviso Integration
  4. Add the Proviso lender ID related to the customers you plan on submitting with your requests. 

Note: If you cannot see the Proviso Integration as per the screenshot above, please notify our support team to activate KYC Trusted status via enquiries@splitpayments.com.au or call 1300 611 406 during business hours and dial 2 for support.

Step 3 – Duplicate the Proviso customer encryption key to Split’s Proviso account

Before you can send a request to Split referencing a Proviso customer, you must duplicate the customer encryption key with Split via Proviso’s API.  

Configuration details:

Request parameters (in json format):

{
  "customerId": Customer ID of the customer you want to share
  "encryptionKey": Encryption Key of the customer you want to share
  "sendTo": Split Payment’s provider ID
  "reference": Self-generated reference that you will share with Split to reference this customer
  "tcAcceptedAt": T&C Accepted Date (Y-m-d H:i:s)
}

Response output (in json format):
Confirms that the duplication has occurred and that the Split has received it.

Please note that for added security, Proviso changes the encryptionKey for a customer every time you send it to their API. You must save the updated encryptionKey when it is provided in an API response, or you will lose access to the user’s account, and they will be required to create another customer object for the user. For more information on this please refer to this information on Encryption Keys in the Proviso api documentation.

{  
  "success":"true",
  "message":"Customer has been split",
  "toProviderId":"sp-xxx",
  "customer":{  
    "customerId":"82198495-725f-42ea-acd0-eef8d5953f08",
    "encryptionKey":"vilwIx0Q0/cSLFt4K/bM1CMQ2Qz/2AsjPWsmUGXPb1o="
  }
}

Error Response:

{
  "success":"false",
  "message":"Callback returned with the error code: 500",
  "toProviderId":"sp-xxx",
  "customer":{
    "customerId":"f37c4efe-4e78-4159-8815-d55e151587bd",
    "encryptionKey":"B7LTcW9sOwlWgz0D5zXBZcKMDQSnOnjdcvoypAF3rXQ="
  }
}

Step 4 – Create an Agreement via the KYC Endpoint

The following endpoint will allow you to achieve three actions simultaneously: 

  • Create a contact 
  • Input the bank account details (BSB + Account Number)
  • Create the Agreement

Endpoint: POST /agreements/kyc

Payload Signature: 

{
  "authoriser":{
    "name":"John Doe",
    "email":"john@supplies.com",
    "bank_account":{
      "branch_code":"433444",
      "account_number":"3934342",
      "proviso_reference":"same_self_generated_reference_from_step_3"
    },
    "metadata": {
      "some_data": "stored on the authoriser contact"
    }
  },
  "terms":{
    "per_payout":{
      "min_amount":null,
      "max_amount":null
    },
    "per_frequency":{
      "days":null,
      "max_amount":null
    }
  },
  "metadata":{
    "your_customer_uid": "6041475e-c5b4-4abe-a8e9-e2c3620a0a3e",
    "some_other_data": "stored on the agreement"
  }
}

The terms  fields are defined in our API docs or use null  for a no limits agreement.

Response:

{
  "data":{
    "ref":"A.ci",
    "initiator_id":"6a0a05c4-8ad9-495d-bcf9-66a7d0046909",
    "authoriser_id":"9fa1be8d-40fb-4bf6-9743-577a1d5a3775",
    "contact_id":"bea8107a-a5b5-4719-92ec-8389ad7aa619",
    "bank_account_id":"91dbef6d-b596-4387-a36c-5a8497822b97",
    "status":"unverified",
    "responded_at":"2018-04-30T04:43:52Z",
    "created_at":"2018-04-30T04:43:52Z",
    "terms":{
      "per_payout":{
        "max_amount":null,
        "min_amount":null
      },
      "per_frequency":{
        "days":null,
        "max_amount":null
      }
    },
    "metadata":{
      "your_customer_uid": "6041475e-c5b4-4abe-a8e9-e2c3620a0a3e",
      "some_other_data": "stored on the agreement"
    }
  }
}

Step 5 - Wait for the Agreement to be accepted


Notice how the response status is unverified. This is because we asynchronously verify that the supplied Proviso reference works and matches the provided branch_code and account_number. This is done asynchronously to ensure speedy response times.

Once the check is successfully completed, the Agreement status will transition to accepted. If the check is unsuccessful, the Agreement status will become declined. 

If you try to create a Payment Request before the Agreement has transitioned to Accepted, the Payment Request will be declined.

The best way for your system to be notified that the Agreement has been accepted is to subscribe to the Agreement webhooks. It usually only takes a few seconds for the notification to be sent.

Some important notes: 

  1. This will only work once ‘KYC Trusted’ is activated on your sandbox account so please wait for confirmation by our support team before testing.
  2. The request is idempotent to safeguard against accidental duplication. For example, if you POST the same payload, it will return the currently live Agreement. 
  3. Once this KYC endpoint is set up, payments requests can be sent to the contact_id. Configuration details can be found at docs.split.cash/#request-payment
  4. For testing purposes you will need to use one of the BSB and Account numbers returned by a Proviso test account https://docs.bankfeeds.com.au/#basic-test-account-details - and note that the Split Payments special account numbers will not work.

Updating Bank Account
Some of your customers, over time, will change their bank account and require you to update their account details within your integration. It is important that this is taken into account and planned in advance to ensure a smooth transition for both your customers and yourself.

If your application relies on metadata that you supply when creating an Agreement, a Bank Connection or the Agreement reference, your application will need to remove the Agreement that is in place with this customer, remove the existing Contact and then send a request to the KYC endpoint to create a new Contact and Agreement within Split. This ensures that the correct data is persisted in your application and everything is set up and referenced correctly.

This process is explained in more detail in this article.

Step 6 – Going Live 

Once the sandbox testing is complete you simply need to register for a production account and the same approval process as per Step 1 will take place to activate KYC Trusted and verify that the integration is suitable as per the minimum requirements outlined above. 

Register: go.split.cash/sign-in

If you need any further support, please do not hesitate to contact our support team: 

Help Desk: help.split.cash

Email: support@splitpayments.com.au

Call: 1300 611406 (normal business hours) 

Did this answer your question?