Our networked membership model is ideal for an agent to the operator payment arrangement, providing complete control and transparency to both parties at all times during the payment cycle. Using Split you'll be able to ensure the security of payment for all bookings made by your agents on your payment terms.
Step 1. Agent Setup
To onboard your agents:
- Request that your agent creates a Split account: Split sign up
- Once they have an account they'll need to provide you with their Split nickname
- Add them as a Contact (see below)
- Send them an Agreement (see below), this is optional depending on whether you want automated Payment Request approval within agreed terms, or manual approval of each Payment Request.
Once the above is completed your agent is ready to be direct debited via Payment Requests for all bookings made in accordance with your trading terms.
Adding your Agent as a Contact
Ensure they send their nickname correctly, it will not contain any spaces but may contain special characters such as underscores, hyphens etc.
Adding your agent as a Contact so that you can reference them when proposing Agreements and creating Payment Requests. To do this you can simply make one POST request to our /contacts endpoint and pass the nickname they have provided. This will add this Agent to your list of Contacts and you can now send them Agreements (optional) or send Payment Requests (Direct Debits).
Example request body
{
"nickname": "outstanding_tours",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}This endpoint is documented here
We will return all details that your application will need to persist in our response to your request, an example response is shown below.
The first id field in the response will need to be stored and associated with your Agents profile in your application. This is the contacts UUID and is required to create Payment Requests
Example response body
{
"data": {
"id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
"name": "Outstanding Tours Pty Ltd",
"email": "accounts@outstandingtours.com.au",
"type": "Split account",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
},
"bank_account": {
"id": "55afddde-4296-4daf-8e49-7ba481ef9608",
"account_number": "947434694",
"branch_code": "304304",
"bank_name": "National Australia Bank",
"state": "active",
"iav_provider": null,
"iav_status": null,
"blocks": {
"debits_blocked": false,
"credits_blocked": false
}
},
"account": {
"id": "77be6ecc-5fa7-454b-86d6-02a5f147878d",
"nickname": "outstanding_tours",
"abn": "123456789",
"name": "Outstanding Tours Pty Ltd"
},
"links": {
"add_bank_connection": "https://go.sandbox.split.cash/invite_contact/thomas-morgan-1/1030bfef-cef5-4938-b10b-5841cafafc80"
}
}
}Step 2. Agreement Setup (Optional)
If you would like all Payment Requests to be automatically approved, you can send an Agreement to your Agents Split account. Your Agent will then need to manually accept this agreement via their UI.
How an agent accepts an Agreement
To send an Agreement simply make a POST request to our /agreements endpoint, passing the contact ID and terms in the requests body. This will propose an Agreement to your Agent that they will need to log in and accept.
Example request body
{
"authoriser_contact_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
"terms": {
"per_payout": {
"min_amount": null,
"max_amount": 10000
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
},
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}This endpoint is documented here
Once the Agent accepts the Agreement all Payment Requests that fall within the terms of the Agreement, will be automatically approved. Those that exceed the terms of the Agreement will need to be manually approved.
Step 3. Issuing Payment Requests To Your Agents
Payment Request is our terminology for a Direct Debit, so, if you wish to Debit one of your Agents for $50.00, you would issue a Payment Request to that Contact for $50.00, essentially requesting this payment from them.
This can be achieved by making a POST request to our /payment_requests endpoint. This endpoint requires you to include the Contact ID to be Debited, the amount that you are requesting in cents, a maturation date and a description that will be viewable within the Split portal.
Example request body
{
"description": "Visible to both initiator and authoriser",
"matures_at": "2016-12-19T02:10:56.000Z",
"amount": 99000,
"authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
"precheck_funds": false,
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}Full Payment Request API Documentation is available here
Our response to this request will, again, include all details that your application will need to persist in order to reference this transaction in the future.
{
"data": {
"ref": "PR.3",
"initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"authoriser_id": "970e4526-67d9-4ed9-b554-f5cf390ab775",
"authoriser_contact_id": "de86472c-c027-4735-a6a7-234366a27fc7",
"schedule_ref": null,
"status": "pending_approval",
"responded_at": null,
"created_at": "2016-12-19T02:10:56Z",
"credit_ref": null,
"payout": {
"amount": 99000,
"description": "The elite package for 4",
"matures_at": "2016-12-25T00:00:00Z"
},
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
}If you have setup an Agreement with this Agent, these Payment Requests will be automatically approved and paid so long as the amount is within the agreed terms. If you don't have an Agreement, or you do have an Agreement but the payment request exceeds the agreed terms, the Agent will need to login to their Split account and approve the Payment Request. To do this they will need to:
- Log into their Split account
- Click on the Payment Requests tab on the left-hand side of their dashboard.
- Scroll down to incoming the Payment Requests section.
- Find the correct Payment Request and click on the blue reference
- Click Approve
Your Agents will have the ability to decline these Payment Requests, and your system can be notified of this via webhooks or manual checking of your reports. In case your Agent does decline a Payment Request, you would need to contact them to find out why and arrange payment if required.
Amending Previously Issued Payment Requests
Note. If your Debit has already reached the processing status, you will not be able to cancel it. You will need to allow it to process as it normally would and refund the amount once the funds have reached your account.
Should a booking change and you need to change the amount or maturation date of a Payment Request or completely remove the transaction altogether, the first step will always be the same. You will need to cancel the Payment Request to stop it from processing. This can only be done prior to the Debit being sent for processing.
To do this, simply make a DELETE request to the /payment_requests/{payment_request_ref} endpoint and pass the Payment Request reference, PR.xxx, in place of {payment_request_ref}
Full documentation for this endpoint is available here
Now that this Payment Request has been cancelled, your application will need to create a new Payment Request with all of the amended details of the booking.
Refunding Payment Requests
Once a Payment Request has cleared and you have the funds in your account, you will have to option to refund the person that was Debited. In this case, you will need to do the following.
Make a POST request to the /credits/{credit_ref}/refunds endpoint. The {credit_ref} field here will be the reference for the associated Credit to your account. This reference will always be a C followed by a period followed by a unique identifier. For example C.ab12.
Example request body
{
"amount": 500,
"reason": "Because reason",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}Example response
{
"data": {
"ref": "PRF.1",
"for_ref": "C.59",
"debit_ref": "D.hi",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"created_at": "2017-05-08T07:20:24Z",
"amount": 500,
"reason": "Because reason",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
}This will create a Debit from your account and a Credit to this customers account and will process the same as any other Payment Request that you have created.
Full documentation for his endpoint is available here
Reporting
We suggest tracking each of your transactions and the stage that they are at by utilising our webhooks. We offer a variety of events to subscribe to and give you the ability to have a complete view of where each Direct Debit is up to in its lifecycle.
If you do not wish to subscribe to our Webhooks, you do have the ability to manually check your reports using your Reports tab in your Split Account
Using Splits Reports Tab To View Your Transactions
Alternatively you can make a GET request to the list all transactions endpoint, /transactions. This endpoint will allow you to filter your transactions using a wide range of query strings, which will allow you to retrieve all details about any transaction you wish to check on.
Full documentation on the transactions endpoint
Technical Support
For any questions regarding your integration or best practice approaches to managing payments, please don't hesitate to reach out via our in-app messaging.