Split API v1.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Split allows you to make, get and manage payments using nothing but bank accounts.
It is important to understand that there are 2 main ways Split can be used for maximum flexibility:
- Between Split accounts.
- Between a Split account and anyone.
Due to the above, certain endpoints and techniques will differ slightly depending on who you are interacting with. You can find more on this in the Making payments and Getting paid guides.
- Authentication is performed using OAuth2. See the Get started and Authentication & Authorisation guides for more.
- All communication is via
https
and supports onlyTLSv1.2
. - Production API:
https://api.split.cash/
. - Production UI:
https://go.split.cash/
. - Sandbox API:
https://api.sandbox.split.cash/
. - Sandbox UI:
https://go.sandbox.split.cash/
. - Data is sent and received as JSON.
- Clients should include the
Accepts: application/json
header in their requests. - Currencies are represented by 3 characters as defined in ISO 4217.
- Dates & times are returned in UTC using ISO 8601 format with second accuracy. With requests, when no TZ is supplied, the configured TZ of the authenticated user is used, or
Australia/Sydney
if no TZ is configured. - Amounts are always in cents with no decimals unless otherwise stated.
- Split provides static public IP addresses for all outbound traffic, including webhooks.
- Sandbox IP:
13.237.142.60
- Production IPs:
52.64.11.67
and13.238.78.114
- Sandbox IP:
Check the platform status, or subscribe to receive notifications at status.split.cash. If you would like to check platform status programmatically, please refer to status.split.cash/api.
Guides
Try it out
The best way to familiarise yourself with our API is by interacting with it.
We've preloaded a collection of all our endpoints for you to use in Postman. Before you start, load up our API collection:
Okay, lets get things setup!
Create a Split account
If you haven't already, you'll want to create a sandbox Split account at https://go.sandbox.split.cash
Register your application with Split
Sign in and create an OAuth2 application: https://go.sandbox.split.cash/oauth/applications.
Generate personal access tokens
The quickest way to access your Split account via the API is using personal access tokens. Click on your newly created application from your application list and click on + Personal Access Token.
(You'll have the option to give the token a title)
Use personal access token in Postman
You can use this
access_token
to authorise any requests to the Split API in Postman by choosing the Bearer Token option under the Authorization tab.Make an API request!
You are now ready to interact with your Split account via the API! Go ahead and send a request using Postman.
Get started
This guide will help you setup an OAuth2 app in order to get authenticated & authorised to communicate with the Split API.
Before you start:
- We use the term user below but the user can be a third party or the same user that owns the OAuth2 application.
- As noted below, some access tokens expire every 2 hours. To get a new access token use the refresh grant strategy to swap a refresh token for a new access token.
Create a Split account
If you haven't already, you'll want to create a sandbox Split account at https://go.sandbox.split.cash.
Choose authentication method
All requests to the Split API require an
access_token
for authentication. There are two options for obtaining these tokens, the correct option will depend on your use case:Personal access token If you only need to access your own Split account via the API, then using personal access tokens are the most straight-forward way. Refer to Personal access token to setup. These tokens do not expire so no refreshing is required.
OAuth grant flow When you require your application to act on behalf of other Split accounts you'll need to implement the OAuth grant flow process. Refer to OAuth grant flow guide to setup. There is also an OAuth grant flow tutorial. These access tokens expire every 2 hours, unless the
offline_access
scope is used in which case the tokens will not expire.
Personal access token
If you're looking to only access your own account via the API, you can generate a personal access token from the UI. These tokens do not expire, but can be deleted.
To do this, sign in to your Split account and create an application if you haven't already. Click on your application from your application list and click on Personal access.
(You'll have the option to give the token a title)
Now that you have an
access_token
you can interact with your Split account via the API.To do so, you must simply append the access token to the header of any API request:
Authorization: Bearer {access_token}
OAuth grant flow
Register your application with Split
Once you've got your account up and running, sign in and create an OAuth2 profile for your application: https://go.sandbox.split.cash/oauth/applications
Parameter Description Name The name of your application. When using the the Authorisation Grant Flow, users will see this name as the application requesting access to their account. Redirect URI Set this to your application's endpoint charged with receiving the authorisation code. Obtain an authorisation code
Construct the initial URL the user will need to visit in order to grant your application permission to act on his/her behalf. The constructed URL describes the level of permission (
scope
), the application requesting permission (client_id
) and where the user gets redirected once they've granted permission (redirect_uri
).The URL should be formatted to look like this:
https://go.sandbox.split.cash/oauth/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope={scope}
Parameter Description response_type
Always set to code
client_id
This is your Application ID
as generated when you registered your application with Splitredirect_uri
URL where the user will get redirected along with the newly generated authorisation code scope
The scope of permission you're requesting Exchange the authorisation code for an access token
When the user visits the above-mentioned URL, they will be presented with a Split login screen and then an authorisation screen:
After the user has authorised your application, they will be returned to your application at the URL specified in
redirect_uri
along with thecode
query parameter as the authorisation code.Finally, the authorisation code can then be exchanged for an access token and refresh token pair by POSTing to:
https://go.sandbox.split.cash/oauth/token
Note The authorisation code is a ONE-TIME use code. It will not work again if you try to POST it a second time.
Parameter Description grant_type
Set to authorization_code
client_id
This is your Application ID
as generated when you registered your application with Splitclient_secret
This is your Secret
as generated when you registered your application with Splitcode
The authorisation code returned with the user (ONE-TIME use) redirect_uri
Same URL used in step 3 Wrap-up
Now that you have an access token and refresh token, you can interact with the Split API as the user related to the access token. To do so, you must simply append the access token to the header of any API request:
Authorization: Bearer {access_token}
OAuth grant flow tutorial
The OAuth grant flow process is demonstrated using Postman in the steps below.
Before you start, load up our API collection:
A screencast of this process is also available: https://vimeo.com/246203244.
Create a Split account
If you haven't already, you'll want to create a sandbox Split account at https://go.sandbox.split.cash
Register your application with Split
Sign in and create an OAuth2 application: https://go.sandbox.split.cash/oauth/applications.
Use the special Postman callback URL:
https://www.getpostman.com/oauth2/callback
In Postman, setup your environment variables
We've included the Split Payments Public Sandbox environment to get you started. Select it in the top right corner of the window then click the
icon and click edit.
Using the details from the OAuth2 app you created earlier, fill in the oauth2_application_id & oauth2_secret fields.
Setup the authorization
Click on the Authorization tab and select OAuth 2.0
Click the Get New Access Token button
Fill in the OAuth2 form as below:
Get authorised
Click Request Token and wait a few seconds and a browser window will popup
Sign in with your Split account (or any other Split account you want to authorise).
Click Authorise to allow the app to access the signed in account. Once complete, Postman will automatically exchange the authorisation code it received from Split for the
access_token/refresh_token
pair. It will then store theaccess_token/refresh_token
for you to use in subsequent API requests. Theaccess_token
effectively allows you to send requests via the API as the user who provided you authorisation.You're now ready to use the API
Select an endpoint from the Split collection from the left hand side menu. Before you send an API request ensure you select your access token and Postman will automatically add it to the request header.
Authentication and Authorisation
Split uses OAuth2 over https to manage authentication and authorisation.
OAuth2 is a protocol that lets external applications request permission from another Split user to send requests on their behalf without getting their password. This is preferred over Basic Authentication because access tokens can be limited by scope and can be revoked by the user at any time.
New to OAuth2? DigitalOcean has a fantastic 5 minute introduction to OAuth2.
We currently support the authorisation code and refresh token grants.
Authorisation Code Grant
This type of grant allows your application to act on behalf of a user. If you've ever used a website or application with your Google, Twitter or Facebook account, this is the grant being used.
See the Get Started guide for step by step details on how to use this grant.
Refresh Token Grant
Code sample
curl -F "grant_type=refresh_token" \
-F "client_id={{oauth2_application_id}}" \
-F "client_secret={{oauth2_application_secret }}" \
-F "refresh_token={{refresh_token}}" \
-X POST https://go.sandbox.split.cash/oauth/token
Example response
{
"access_token": "ad0b5847cb7d254f1e2ff1910275fe9dcb95345c9d54502d156fe35a37b93e80",
"token_type": "bearer",
"expires_in": 7200,
"refresh_token": "cc38f78a5b8abe8ee81cdf25b1ca74c3fa10c3da2309de5ac37fde00cbcf2815",
"scope": "public"
}
When using the authorisation code grant above, Split will return a refresh token
along with the access token. Access tokens are short lived and last 2 hours but refresh tokens do not expire.
When the access token expires, instead of sending the user back through the authorisation flow you can use the refresh token to retrieve a new access token with the same permissions as the old one.
Making payments
In order to payout funds, you'll be looking to use the Payments endpoint. Whether you're paying out another Split account holder or anyone, the process is the same:
- Add the recipient to your Contacts: Split Contact or Anyone Contact
- Make the Payment to your Contact.
Common use cases:
- Automated payout disbursement (Referal programs, net/commission payouts, etc...)
Getting paid
There are 2 ways to get paid:
POSTing a Payment Request
Provides the ability to send a Payment Request (get paid) to any Contact that is either:
- A Split Contact (The contact has a Split account); or
- An Anyone Contact (The contact does not have a Split account) with an accepted Agreement in place.
For a Split Contact:
They will receive a request that they must approve via the Split UI or API in order for the funds to flow from their bank account to yours.
To automate the Payment Request approval, process you must first enter into an Agreement with the Split Contact. Once the Agreement is accepted, any future Payment Request will be automatically approved and processed per the Agreement terms.
For an Anyone Contact:
- To send a Payment Request using the API to an Anyone Contact, you must first have an accepted Agreement with them . To do so, you can send them an Open Agreement link or Unassigned Agreement link for them to elect & verify their bank account and accept the Agreement.
Common use cases:
- Subscriptions
- On-account balance payments
- Bill smoothing
- Repayment plans
Example flow embedding an Open Agreement link using an iFrame in order to automate future Payment Request approvals:
Sharing an Open Payment Request
Provides the ability to get paid once-off by a anyone whether they are a Split account holder or not.
Usage notes:
- Utilise a customisable hosted Payment Request form that takes care of everything from confirming the payer's bank account access to the transfer of funds.
- The Open Payment Request link can be shared and sit as a secure form either outside your app or embeded within via iframe with the ability to whitelabel.
- The URL for the form contains all the customisation parameters enabling you to generate the form on the fly.
Common use cases:
- Online or offline purchases (eCommerce, fundraiser, etc...)
- Invoice payment
- Group funding (paying for a restaurant bill)
Example flow embedding the Open Payment Request link using an iFrame:
Idempotent requests
Example response
{
"errors": [
{
"title": "Duplicate idempotency key",
"detail": "A resource has already been created with this idempotency key",
"links": {
"about": "https://docs.split.cash/"
},
"meta": {
"resource_ref": "PB.1a4"
}
}
]
}
The Split API supports idempotency for safely retrying requests without accidentally performing the same operation twice.
For example, if a Payment is POST
ed and a there is a network connection error, you can retry the Payment with the same idempotency key to guarantee that only a single Payment is created.
To perform an idempotent request, provide an additional Idempotency-Key: <key>
header to the request.
You can pass any value as the key but we suggest that you use V4 UUIDs or another appropriately random string.
Keys expire after 24 hours. If there is a subsequent request with the same idempotency key within the 24 hour period, we will return a 409 Conflict
.
- The
meta.resource_ref
value is the reference of the resource that was previously created with the conflicting idempotency key. - The
Idempotency-Key
header is optional but recommended. - Only the
POST
action for the Payments, Payment Requests and Refunds endpoints support the use of theIdempotency-Key
. - Endpoints that use the
GET
orDELETE
actions are idempotent by nature. - A request that quickly follows another with the same idempotency key may return with
503 Service Unavailable
. If so, retry the request after the number of seconds specified in theRetry-After
response header.
Error responses
Example detailed error response
{
"errors": [
{
"title": "A Specific Error",
"detail": "Details about the error",
"links": {
"about": "https://docs.split.cash/..."
}
}
]
}
Example resource error response
{
"errors": "A sentence explaining error/s encounted"
}
The Split API returns two different types of error responses depending on the context.
Detailed error responses are returned for:
- Authentication
- Request types
- Idempotency
All other errors relating to Split specific resources(e.g. Contacts) will return the Resource error response style.
403 errors are generally returned from any of our endpoints if your application does not have the required authorisation. This is usually due to:
- An invalid/expired
access_token
; or - The required scopes not being present when setting up your OAuth application; or
- The required scopes not being present in the authorisation code link used to present your user with an authorisation request.
Speeding up onboarding
Consider the following scenario:
Split is integrated in your application to handle payments.
A customer would like to use Split but does not yet have Split account.
You already have some information about this customer.
Given the above, in a standard implementation where a customer enables/uses Split within your application, these are the steps they would follow:
- Click on some sort of button within your app to use Split.
- They get redirected to the Split sign in page (possibly via a popup or modal).
- Since they don't yet have a Split account, they would click on sign up.
- They would fill in all their signup details and submit.
- They would be presented with the authorisation page.
- They would click the "Authorise" button and be redirected to your app.
Whilst not too bad, we can do better!
In order to speed up the process, we allow query string params to be appended to the authorisation URL. For instance, if we already have some information about the customer and know they probably don't have a Split account, we can embed this information in the authorisation URL.
Supported query string parameters
Parameter | Description |
---|---|
landing |
Accepted value: sign_up . What page the user should see first if not already signed in. Default is the sign in page. Deprecated values: business_sign_up , personal_sign_up . |
nickname |
Only letters, numbers, dashes and underscores are permitted. This will be used to identify the account in Split. |
name |
Business account only. Business name. |
abn |
Business account only. Business ABN. |
phone |
Business account only. Business phone number. |
street_address |
|
suburb |
|
state |
See the sign up page for accepted values |
postcode |
|
first_name |
|
last_name |
|
mobile_phone |
|
email |
All values should be URL encoded.
As an example, the following authorisation URL would display the personal sign up & prefill the first name field with George:
https://go.sandbox.split.cash/oauth/authorize?response_type=code&client_id=xxx&redirect_uri=xxx&scope=xxx&landing=sign_up&first_name=George
You can also pass the values directly to the sign up page outside of the OAuth2 authorisation process. Click on the following link to see the values preloaded: https://go.sandbox.split.cash/business/sign_up?name=GeorgeCo&nickname=georgeco&first_name=George.
Sandbox Testing Details
Try out your happy paths and not-so happy paths, the sandbox is a great place to get started without transferring actual funds. All transactions are simulated and no communication with financial institutions is performed.
The sandbox works on a 1 minute cycle to better illustrate how transactions are received and the lifecyle they go through. In other words, every minute, we simulate communicating with financial institutions and update statuses and events accordingly.
All 6 digits BSBs are valid in the sandbox with the exception of 100000
which is a place keeper for an invalid BSB. In production, only real BSBs are accepted.
Transaction failures
To simulate transaction failures create a Payment or Payment Request with a specific amount listed in the table.
Transaction failure reason | Debit | Credit |
---|---|---|
invalid_bsb_number |
$0.01 | $0.51 |
account_closed |
$0.02 | $0.52 |
customer_deceased |
$0.03 | $0.53 |
incorrect_account_number |
$0.04 | $0.54 |
refer_to_split |
$0.05 | $0.55 |
user_voided |
$0.06 | $0.56 |
admin_voided |
$0.07 | $0.57 |
refer_to_customer |
$0.10 | |
insufficient_funds |
$0.11 | |
payment_stopped |
$0.12 |
Example scenarios
- Pay a contact with an invalid account number:
- Initiate a Payment for
$0.54
. - Split will mimic a successful debit from your bank account.
- Split will mimic a failure to credit the contact's bank account.
- Split will automatically create a
payout_reversal
credit transaction back to your bank account.
- Initiate a Payment for
- Pay a contact whilst having insufficient funds:
- Initiate a Payment for
$0.11
. - Split will mimic a failure to debit your bank account.
- Split will mark the debit as
returned
due toinsufficient_funds
. - Split will void the scheduled credit to the contact's bank account.
- Initiate a Payment for
- Request payment from a contact with a closed bank account:
- Initiate a Payment Request for
$0.02
. - Split will mimic a failure to debit the contact's bank account.
- Initiate a Payment Request for
NPP payment failures
If you are utilising an Account Float to create NPP payments, you can simulate a transaction that fails to process through the NPP channel by creating a Payment from your account float for one of the following amounts.
Transaction failure reason | Failure details | Amount |
---|---|---|
refer_to_split |
Real-time payment service currently unavailable | $1.55 |
refer_to_customer |
Real-time payment rejected by recipient | $1.60 |
You will receive all the same notifications as if this happened in our live environment. We recommend you check out our article on what happens when an NPP Payment fails to learn more about what happens when an NPP Payment is unable to process.
Special accounts
There are some accounts with a special behaviour. You can add them to your Contacts by nickname or bank details.
Account nickname | Branch code (BSB) | Account number | Description |
---|---|---|---|
accept_agreements | 900000 |
99999 |
Always accepts agreements |
decline_agreements | 900001 |
99999 |
Always declines agreements |
(Deprecated) Payment credit failure bank accounts
You can send Payments to the following reserved bank accounts to trigger specific failures on the credit side.
Failure type | Branch code (BSB) | Account number |
---|---|---|
account_closed |
300000 |
99999 |
customer_deceased |
400000 |
99999 |
incorrect_account_number |
500000 |
99999 |
refer_to_split |
700000 |
99999 |
(Deprecated) Payment Request failure bank accounts
You can send Payment Requests to the following reserved bank accounts to trigger specific failures.
Failure type | Branch code (BSB) | Account number |
---|---|---|
payment_stopped |
200000 |
99999 |
account_closed |
300000 |
99999 |
customer_deceased |
400000 |
99999 |
incorrect_account_number |
500000 |
99999 |
refer_to_customer |
600000 |
99999 |
refer_to_split |
700000 |
99999 |
insufficient_funds |
800000 |
99999 |
By default, all Agreements sent to Contacts with a failure bank account will be automatically accepted.
Instant account verification accounts
When using any of our hosted solutions (Payment Requests, Open Agreements or Unassigned Agreements) you may want to test the Instant Account Verification (IAV) process where we accept online banking credentials to validate bank account access. To do so, you can use the following credentials:
Login | Password |
---|---|
12345678 |
TestMyMoney |
Available balances in the Sandbox
If your integration includes allowing us to pre-fail transactions prior to being processed, you may want to test that your system is handling these events correctly. A transaction will pre-fail when the available balance of the customers account is less than the amount of the payment being requested. This is checked during pre-processing just before your debit is sent for processing if there is an active bank connection.
In the Sandbox environment, if the contact you are attempting to debit has a bank connection that was created through our Instant Account Verification feature, the available balance of their bank account will always be $123.45
. Any payment requests above this amount will pre-fail and any amount less than or equal to this amount will succeed.
Configuration
Scopes
Scopes define the level of access granted via the OAuth2 authorisation process. As a best practice, only use the scopes your application will require.
Scope | Description |
---|---|
public |
View user's public information |
agreements |
Manage user's Agreements |
bank_accounts |
Manage user's Bank Accounts |
bank_connections |
Manage user's Bank Connections |
contacts |
Manage user's Contacts |
open_agreements |
Manage user's Open Agreements |
payments |
Manage user's Payments |
payment_requests |
Manage user's Payment Requests |
refunds |
Manage user's Refunds |
transactions |
Access user's Transactions |
offline_access |
Create non-expiring access tokens for user |
Pagination
Example response header
Link: <http://api.sandbox.split.cash/contacts?page=5>; rel="last", <http://api.sandbox.split.cash/contacts?page=2>; rel="next"
Per-Page: 25
Total: 5
All collections are paginated to 25 items by default and the pagination information may be found in the response header. You can customise the pagination by appending ?per_page=x
and/or ?page=x
to the endpoint URL.
Remitter
Example request
{
"...": "...",
"metadata": {
"remitter": "CustomRem"
}
}
You can elect to assign a remitter name on a per-request basis when submitting Payments & Payment Requests. Simply append the remitter
key and a value within the metadata
key.
- For Payments, the party being credited will see the designated remitter name along the entry on their bank statement.
- For Payment Requests, the party being debited will see the designated remitter name along the entry on their bank statement.
Aggregation
Split will automatically aggregate debits that are:
- From the same bank account; and
- Initiated by the same Split account.
Likewise for credits:
- To the same bank account; and
- Initiated by the same Split account.
Should you prefer aggregation to be disabled, please contact support@splitpayments.com.au. Note that additional charges may apply.
Webhooks
Example response
{
"event": {
"type": "object.action",
"at": "yyyy-mm-ddThh:mm:ssZ",
"who": {
"account_id": "x",
"bank_account_id": "x"
}
},
"data": [
{}
]
}
Please refer to our help centre article on webhooks for more information and an overview of what you can achieve with webhooks.
We support two main categories of webhooks:
- Owner: These webhooks are managed by the owner of the Split account and only report on events owned by the Split account.
- App: These webhooks are managed by the Split OAuth2 application owner and will report on events relating to any authorised Split account (limited by scope).
Name | Type | Required | Description |
---|---|---|---|
event | object | true | Webhook event details |
» type | string | true | The webhook event key (list available in the webhook settings) |
» at | string(date-time) | true | When the event occurred |
» who | object | true | Who the webhook event relates to |
»» account_id | string(uuid) | true | The Split account who's the owner of the event |
»» bank_account_id | string(uuid) | true | The above Split account's bank account |
data | [object] | true | Array of response bodies |
Data schemas
Use the following table to discover what type of response schema to expect for for the data.[{}]
component of the webhook delivery.
Event | Data schema |
---|---|
agreement.* |
GetAnAgreementResponse |
contact.* |
GetAContactResponse |
credit.* |
ListAllTransactionsResponse |
creditor_debit.* |
ListAllTransactionsResponse |
debit.* |
ListAllTransactionsResponse |
debtor_credit.* |
ListAllTransactionsResponse |
open_agreement.* |
ListAllOpenAgreementsRespose |
payment.* |
GetAPaymentResponse |
payment_request.* |
GetAPaymentRequestResponse |
unassigned_agreement.* |
GetAnUnassignedAgreementResponse |
Our Delivery Promises
- We only consider a webhook event delivery as failed if we don't receive any http response code (2xx, 4xx, 5xx, etc.)
- We will auto-retry failed deliveries every 5 minutes for 1 hour.
- Delivery order for webhook events is not guaranteed.
- We guarantee at least 1 delivery attempt.
Request ID
Example header
Split-Request-ID: 07f4e8c1-846b-5ec0-8a25-24c3bc5582b5
Split provides a Split-Request-ID
header in the form of a UUID
which uniquely identifies a webhook event. If the webhook event is retried/retransmitted by Split, the UUID will remain the same. This allows you to check if a webhook event has been previously handled/processed.
Checking Webhook Signatures
Example header
Split-Signature: 1514772000.93eee90206280b25e82b38001e23961cba4c007f4d925ba71ecc2d9804978635
Split signs the webhook events it sends to your endpoints. We do so by including a signature in each event’s Split-Signature
header. This allows you to validate that the events were indeed sent by Split.
Before you can verify signatures, you need to retrieve your endpoint’s secret from your Webhooks settings. Each endpoint has its own unique secret; if you use multiple endpoints, you must obtain a secret for each one.
The Split-Signature
header contains a timestamp and one or more signatures. All separated by .
(dot).
Example code
# Shell example is not available
package main
import (
"crypto/hmac"
"crypto/sha256"
"strings"
"fmt"
"encoding/hex"
)
func main() {
secret := "1234"
message := "full payload of the request"
splitSignature := "1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f"
data := strings.Split(splitSignature, ".")
timestamp, givenSignature := data[0], data[1]
signedPayload := timestamp + "." + message
hash := hmac.New(sha256.New, []byte(secret))
hash.Write([]byte(signedPayload))
expectedSignature := hex.EncodeToString(hash.Sum(nil))
fmt.Println(expectedSignature)
// f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
fmt.Println(givenSignature)
// f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
}
import hashlib
import hmac
split_signature = '1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f'
secret = bytes('1234').encode('utf-8')
message = bytes('full payload of the request').encode('utf-8')
data = split_signature.split('.')
timestamp = data[0]
given_signature = data[1]
signed_payload = timestamp + '.' + message
expected_signature = hmac.new(secret, signed_payload, digestmod=hashlib.sha256).hexdigest()
print(expected_signature)
# > f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
print(given_signature)
# > f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
require 'openssl'
split_signature = '1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f'
secret = '1234'
message = 'full payload of the request'
timestamp, given_signature, *other = split_signature.split('.')
signed_payload = timestamp + '.' + message
expected_signature = OpenSSL::HMAC.hexdigest('sha256', secret, signed_payload)
puts(expected_signature)
# => f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
puts(given_signature)
# => f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
var crypto = require('crypto')
var message = 'full payload of the request'
var secret = '1234'
var splitSignature = '1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f'
var data = splitSignature.split('.')
var timestamp = data[0]
var givenSignature = data[1]
var signedPayload = timestamp + '.' + message
var expectedSignature = crypto.createHmac('sha256', secret).update(signedPayload).digest('hex')
console.log(expectedSignature)
// f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
console.log(givenSignature)
// f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
$split_signature = '1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f';
$secret = '1234';
$message = 'full payload of the request';
list($timestamp, $given_signature, $other) = explode('.', $split_signature);
$signed_payload = $timestamp . "." . $message;
$expected_signature = hash_hmac('sha256', $signed_payload, $secret, false);
echo $expected_signature; // f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
echo "\n";
echo $given_signature; // f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
class Main {
public static void main(String[] args) {
try {
String splitSignature = "1514772000.f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f";
String secret = "1234";
String message = "full payload of the request";
String[] data = splitSignature.split("\\.");
String timestamp = data[0];
String givenSignature = data[1];
String signedPayload = timestamp + "." + message;
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
sha256_HMAC.init(secret_key);
String expectedSignature = javax.xml.bind.DatatypeConverter.printHexBinary(sha256_HMAC.doFinal(signedPayload.getBytes())).toLowerCase();
System.out.println(expectedSignature);
// f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
System.out.println(givenSignature);
// f04cb05adb985b29d84616fbf3868e8e58403ff819cdc47ad8fc47e6acbce29f
}
catch (Exception e){
System.out.println("Error");
}
}
}
Step 1. Extract the timestamp and signatures from the header
Split the header, using the .
(dot) character as the separator, to get a list of elements.
Element | Description |
---|---|
timestamp |
Unix time in seconds when the signature was created |
signature |
Request signature |
other |
Placeholder for future parameters (currently not used) |
Step 2: Prepare the signed_payload string
You achieve this by concatenating:
- The timestamp from the header (as a string)
- The character
.
(dot) - The actual JSON payload (request body)
Step 3: Determine the expected signature
Compute an HMAC with the SHA256 hash function. Use the endpoint’s signing secret as the key, and use the signed_payload
string as the message.
Step 4: Compare signatures
Compare the signature in the header to the expected signature. If a signature matches, compute the difference between the current timestamp and the received timestamp, then decide if the difference is within your tolerance.
To protect against timing attacks, use a constant-time string comparison to compare the expected signature to each of the received signatures.
Changelog
We take backwards compatibility seriously. The following list contains backwards compatible changes:
- 2021-03-17 - Remove note indicating single active bank account limitation
- 2021-03-12 - Add ref to GetAContactResponse
- 2020-12-17 - Add Sandbox Only API endpoints
- 2020-12-17 - Enhance response schema for several endpoints
- 2020-12-16 - Add webhook schema table
- 2020-12-15 - Improve webhooks section
- 2020-12-15 - Add changelog
- 2020-12-15 - Re-word Payment Requests introduction to better cover its use with Receivable Contacts.
- 2021-02-24 - Added details on enabling the Receivable Contact feature and amended the POST/contacts/receivable response body
Looking for more? Our docs are open sourced! https://github.com/splitpayments/api-documentation
Agreements
An Agreement is an arrangement between two parties that allows them to agree on terms for which future Payment Requests will be auto-approved.
Split Agreements are managed on a per Contact basis and are unidirectional. In other words, if both parties wish for auto-approved Payment Requests, they must each propose an Agreement to the other.
If a Payment Request is sent for an amount that exceeds the terms of the agreement, it will need to be manually approved by the recipient. Please refer to the What is an Agreement article in our knowledge base for an overview.
Agreements are therefore broken up by direction:
- Incoming: Agreement received from another Split account
- Outgoing: Agreement sent to another Split account
Lifecycle
An Agreement can have the following statuses:
Status | Description |
---|---|
proposed |
Waiting for the Agreement to be accepted or declined. |
accepted |
The Agreement has been accepted and is active. |
cancelled |
The Agreement has been cancelled (The initiator or authoriser can cancel an Agreement). |
declined |
The Agreement has been declined. |
expended |
The Agreement has been expended (Only for single_use Unassigned Agreements). |
Propose an Agreement
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/agreements \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"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"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/agreements")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
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\"}}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/agreements",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
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' }
}));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"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\"}}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/agreements", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/agreements")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.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\"}}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"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"}}');
$request->setRequestUrl('https://api.sandbox.split.cash/agreements');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/agreements"
payload := strings.NewReader("{\"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\"}}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /agreements
Propose an Agreement to another Split Contact
Body parameter
{
"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"
}
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
body | body | ProposeAgreementRequest | true | No description |
» authoriser_contact_id | body | string | true | The Authoriser's contact ID (Contact.data.id ) |
» terms | body | Terms | true | Terms |
»» per_payout | body | PerPayout | true | No description |
»»» min_amount | body | integer | true | Minimum amount in cents a PR can be in order to be auto-approved. Specify null for no limit. |
»»» max_amount | body | integer | true | Maximum amount in cents a PR can be in order to be auto-approved. Specify null for no limit. |
»» per_frequency | body | PerFrequency | true | No description |
»»» days | body | integer | true | Amount of days to apply against the frequency. Specify null for no limit. |
»»» max_amount | body | integer | true | Maximum amount in cents the total of all PRs can be for the duration of the frequency. Specify null for no limit. |
»» metadata | body | Metadata | false | Use for your custom data and certain Split customisations. |
Example responses
200 Response
{
"data": {
"ref": "A.2",
"initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
"authoriser_id": "0d290763-bd5a-4b4d-a8ce-06c64c4a697b",
"contact_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
"bank_account_id": "fb9381ec-22af-47fd-8998-804f947aaca3",
"status": "proposed",
"status_reason": null,
"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
}
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Created | ProposeAgreementResponse |
List Agreements
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/agreements/outgoing \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/agreements/outgoing")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/agreements/outgoing",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/agreements/outgoing", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/agreements/outgoing")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/agreements/outgoing');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/agreements/outgoing"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /agreements/outgoing
By default, all outgoing Agreements will be returned. You can apply filters to your query to customise the returned Agreements.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
authoriser_id | query | string | false | Authoriser ID (Contact.data.account.id ), single value, exact match |
contact_id | query | string | false | Contact ID (Contact.data.id ), single value, exact match |
status | query | array[string] | false | Exact match |
Enumerated Values
Parameter | Value |
---|---|
status | proposed |
status | accepted |
status | declined |
status | cancelled |
Example responses
200 Response
{
"data": [
{
"ref": "A.4",
"initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
"authoriser_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
"contact_id": "a80ac411-c8fb-45c0-9557-607c54649907",
"bank_account_id": "fa80ac411-c8fb-45c0-9557-607c54649907",
"status": "proposed",
"status_reason": null,
"responded_at": null,
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": 1
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
}
},
{
"ref": "A.3",
"initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
"authoriser_id": "56df206a-aaff-471a-b075-11882bc8906a",
"contact_id": "a80ac411-c8fb-45c0-9557-607c54649907",
"bank_account_id": "fa80ac411-c8fb-45c0-9557-607c54649907",
"status": "proposed",
"status_reason": null,
"responded_at": null,
"created_at": "2017-03-16T22:51:48Z",
"terms": {
"per_payout": {
"max_amount": 5000,
"min_amount": 0
},
"per_frequency": {
"days": "1",
"max_amount": 10000
}
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListOutgoingAgreementsResponse |
Get an Agreement
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/agreements/A.2 \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/agreements/A.2")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/agreements/A.2",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/agreements/A.2", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/agreements/A.2")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/agreements/A.2');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/agreements/A.2"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /agreements/{agreement_ref}
Get a single Agreement by its reference
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
agreement_ref | path | string | true | Single value, exact match |
Example responses
200 Response
{
"data": {
"ref": "A.2",
"initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
"authoriser_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
"contact_id": "0d290763-bd5a-4b4d-a8ce-06c64c4a697b",
"bank_account_id": "fb9381ec-22af-47fd-8998-804f947aaca3",
"status": "approved",
"status_reason": null,
"responded_at": "2017-03-20T02:13:11Z",
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": 1
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | GetAgreementResponse |
Cancel an Agreement
Code samples
curl --request DELETE \
--url https://api.sandbox.split.cash/agreements/A.2 \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/agreements/A.2")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "DELETE",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/agreements/A.2",
"headers": {
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = { 'authorization': "Bearer {access-token}" }
conn.request("DELETE", "/agreements/A.2", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.delete("https://api.sandbox.split.cash/agreements/A.2")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/agreements/A.2');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/agreements/A.2"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
DELETE /agreements/{agreement_ref}
An Agreement can be cancelled by the initiator at any time whilst the authoriser (Agreement recipient) can only cancel a previously accepted Agreement.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
agreement_ref | path | string | true | Single value, exact match |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | No Content | None |
Approve an Agreement
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/agreements/A.2/accept \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/agreements/A.2/accept")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/agreements/A.2/accept",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/agreements/A.2/accept", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/agreements/A.2/accept")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/agreements/A.2/accept');
$request->setRequestMethod('POST');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/agreements/A.2/accept"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /agreements/{agreement_ref}/accept
Approve an incoming Agreement
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
agreement_ref | path | string | true | Single value, exact match |
Example responses
200 Response
{
"data": {
"ref": "A.2",
"initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
"authoriser_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
"contact_id": "0d290763-bd5a-4b4d-a8ce-06c64c4a697b",
"bank_account_id": "fb9381ec-22af-47fd-8998-804f947aaca3",
"status": "accepted",
"status_reason": null,
"responded_at": "2017-03-20T02:13:11Z",
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": 1
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ApproveAgreementResponse |
Decline an Agreement
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/agreements/A.2/decline \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/agreements/A.2/decline")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/agreements/A.2/decline",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/agreements/A.2/decline", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/agreements/A.2/decline")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/agreements/A.2/decline');
$request->setRequestMethod('POST');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/agreements/A.2/decline"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /agreements/{agreement_ref}/decline
Decline an incoming Agreement
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
agreement_ref | path | string | true | Single value, exact match |
Example responses
200 Response
{
"data": {
"ref": "A.2",
"initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
"authoriser_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
"contact_id": "0d290763-bd5a-4b4d-a8ce-06c64c4a697b",
"bank_account_id": "fb9381ec-22af-47fd-8998-804f947aaca3",
"status": "declined",
"status_reason": null,
"responded_at": "2017-03-20T02:13:11Z",
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": 1
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | DeclineAgreementResponse |
List incoming Agreements
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/agreements/incoming \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/agreements/incoming")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/agreements/incoming",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/agreements/incoming", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/agreements/incoming")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/agreements/incoming');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/agreements/incoming"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /agreements/incoming
By default, all incoming Agreements will be returned. You can apply filters to your query to customise the returned Agreements.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
contact_id | query | string | false | Contact ID (Contact.data.id ), single value, exact match |
initiator_id | query | string | false | Initiator ID (Contact.data.account.id ), single value, exact match |
status | query | array[string] | false | Multiple values, exact match |
Enumerated Values
Parameter | Value |
---|---|
status | proposed |
status | accepted |
status | declined |
status | cancelled |
Example responses
200 Response
{
"data": [
{
"ref": "A.2",
"initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
"authoriser_id": "8df89c16-330f-462b-8891-808d7bdceb7f",
"contact_id": "0d290763-bd5a-4b4d-a8ce-06c64c4a697b",
"bank_account_id": "fb9381ec-22af-47fd-8998-804f947aaca3",
"status": "proposed",
"status_reason": null,
"responded_at": null,
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": 1
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
}
},
{
"ref": "A.1",
"initiator_id": "4e2728cc-b4ba-42c2-a6c3-26a7758de58d",
"authoriser_id": "56df206a-aaff-471a-b075-11882bc8906a",
"contact_id": "a80ac411-c8fb-45c0-9557-607c54649907",
"bank_account_id": "fa80ac411-c8fb-45c0-9557-607c54649907",
"status": "proposed",
"status_reason": null,
"responded_at": null,
"created_at": "2017-03-16T22:51:48Z",
"terms": {
"per_payout": {
"max_amount": 5000,
"min_amount": 0
},
"per_frequency": {
"days": "1",
"max_amount": 10000
}
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListIncomingAgreementsResponse |
Bank Accounts
Your currently linked up bank accounts.
List all Bank Accounts
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/bank_accounts \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/bank_accounts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/bank_accounts",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/bank_accounts", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/bank_accounts")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/bank_accounts');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/bank_accounts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /bank_accounts
By default, all Bank Accounts will be returned.
Example responses
200 Response
{
"data": [
{
"id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
"branch_code": "493192",
"bank_name": "National Australia Bank",
"account_number": "3993013",
"status": "active",
"title": "AU.493192.3993013",
"available_balance": null
},
{
"id": "56df206a-aaff-471a-b075-11882bc8906a",
"branch_code": "302193",
"bank_name": "National Australia Bank",
"account_number": "119302",
"status": "active",
"title": "Trust Account",
"available_balance": null
},
{
"id": "ab3de19b-709b-4a41-82a5-3b43b3dc58c9",
"branch_code": "000000",
"bank_name": "Split Float Account",
"account_number": "1748212",
"status": "active",
"title": "Float Account",
"available_balance": 10000
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListAllBankAccountsResponse |
Bank Connections
Bank connections are read-only connections to your contacts' banking data. This allows Split (and yourself) to make intelligent transactional decisions leading to better outcomes.
Use these endpoints to:
- List your bank connections and check their status
- Retrieve a link that you can share with your contact to update their invalidated bank connection (e.g Their online banking credentials have changed)
List all Bank Connections
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/bank_connections \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/bank_connections")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/bank_connections",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/bank_connections", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/bank_connections")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/bank_connections');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/bank_connections"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /bank_connections
By default, all Bank Connections will be returned. You can apply filters to your query to customise the returned Bank Connection list.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
provider_name | query | string | false | Single value, exact match |
state | query | string | false | Single value, exact match |
Enumerated Values
Parameter | Value |
---|---|
provider_name | basiq |
provider_name | proviso |
provider_name | split |
state | active |
state | credentials_invalid |
Example responses
200 Response
{
"data": [
{
"id": "fb497754-87e2-407d-871f-32aec39d09d4",
"provider_name": "split",
"state": "active",
"refreshed_at": "2020-02-13T09:05:00Z",
"removed_at": null,
"failure_reason": null,
"institution": {
"short_name": "CBA",
"full_name": "Commonwealth Bank of Australia"
},
"contact": {
"id": "626e15b1-aa4a-496e-b5d6-3f8c1a6d2189",
"name": "George Morissette",
"email": "randy@windler.net"
},
"links": {
"update_bank_connection": "http://go.split.cash/authorise_bank_connections/williams-and-sons-5/fb497754-87e2-407d-871f-32aec39d09d4"
}
},
{
"id": "ddbee875-7344-4d74-9503-6233149fe1a0",
"provider_name": "split",
"state": "credentials_invalid",
"refreshed_at": "2020-02-13T09:05:00Z",
"removed_at": null,
"failure_reason": null,
"institution": {
"short_name": "CBA",
"full_name": "Commonwealth Bank of Australia"
},
"contact": {
"id": "72e37667-6364-440f-b1bd-56df5654e258",
"name": "Joel Boyle",
"email": "travis@hermanntorp.net"
},
"links": {
"update_bank_connection": "http://go.split.cash/authorise_bank_connections/williams-and-sons-5/ddbee875-7344-4d74-9503-6233149fe1a0"
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListAllBankConnectionsResponse |
Get a Bank Connection
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/bank_connections/c397645b-bd4f-4fc6-b1fe-4993fef6c3c7 \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/bank_connections/c397645b-bd4f-4fc6-b1fe-4993fef6c3c7")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/bank_connections/c397645b-bd4f-4fc6-b1fe-4993fef6c3c7",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/bank_connections/c397645b-bd4f-4fc6-b1fe-4993fef6c3c7", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/bank_connections/c397645b-bd4f-4fc6-b1fe-4993fef6c3c7")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/bank_connections/c397645b-bd4f-4fc6-b1fe-4993fef6c3c7');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/bank_connections/c397645b-bd4f-4fc6-b1fe-4993fef6c3c7"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /bank_connections/{id}
Get a single Bank Connection by its ID
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
id | path | string(UUID) | true | BankConnection ID (BankConnection.data.id ) |
Example responses
200 Response
{
"data": {
"id": "c397645b-bd4f-4fc6-b1fe-4993fef6c3c7",
"provider_name": "split",
"state": "credentials_invalid",
"refreshed_at": "2020-02-13T09:01:00Z",
"removed_at": null,
"failure_reason": null,
"institution": {
"short_name": "CBA",
"full_name": "Commonwealth Bank of Australia"
},
"contact": {
"id": "72e37667-6364-440f-b1bd-56df5654e258",
"name": "Joel Boyle",
"email": "travis@hermanntorp.net"
},
"links": {
"update_bank_connection": "https://go.sandbox.split.cash/authorise_bank_connections/thomas-morgan-1/c397645b-bd4f-4fc6-b1fe-4993fef6c3c7"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | GetABankConnectionResponse |
404 | Not Found | Not Found | None |
Remove a Bank Connection
Code samples
curl --request DELETE \
--url https://api.sandbox.split.cash/bank_connections/01586a3f-f25b-404f-b135-c42a1b7ef4de \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/bank_connections/01586a3f-f25b-404f-b135-c42a1b7ef4de")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "DELETE",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/bank_connections/01586a3f-f25b-404f-b135-c42a1b7ef4de",
"headers": {
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = { 'authorization': "Bearer {access-token}" }
conn.request("DELETE", "/bank_connections/01586a3f-f25b-404f-b135-c42a1b7ef4de", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.delete("https://api.sandbox.split.cash/bank_connections/01586a3f-f25b-404f-b135-c42a1b7ef4de")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/bank_connections/01586a3f-f25b-404f-b135-c42a1b7ef4de');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/bank_connections/01586a3f-f25b-404f-b135-c42a1b7ef4de"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
DELETE /bank_connections/{id}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
id | path | string(UUID) | true | BankConnection ID (BankConnection.data.id ) |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | No description | None |
Contacts
Your Contacts form an address book of parties with whom you can interact. In order to initiate any type of transaction you must first have the party in your Contact list.
Add a Contact
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/contacts/anyone \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"name":"Hunter Thompson","email":"hunter@batcountry.com","branch_code":"123456","account_number":"13048322","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/contacts/anyone")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"name\":\"Hunter Thompson\",\"email\":\"hunter@batcountry.com\",\"branch_code\":\"123456\",\"account_number\":\"13048322\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/contacts/anyone",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
name: 'Hunter Thompson',
email: 'hunter@batcountry.com',
branch_code: '123456',
account_number: '13048322',
metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"name\":\"Hunter Thompson\",\"email\":\"hunter@batcountry.com\",\"branch_code\":\"123456\",\"account_number\":\"13048322\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/contacts/anyone", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/contacts/anyone")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.body("{\"name\":\"Hunter Thompson\",\"email\":\"hunter@batcountry.com\",\"branch_code\":\"123456\",\"account_number\":\"13048322\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"name":"Hunter Thompson","email":"hunter@batcountry.com","branch_code":"123456","account_number":"13048322","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');
$request->setRequestUrl('https://api.sandbox.split.cash/contacts/anyone');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/contacts/anyone"
payload := strings.NewReader("{\"name\":\"Hunter Thompson\",\"email\":\"hunter@batcountry.com\",\"branch_code\":\"123456\",\"account_number\":\"13048322\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /contacts/anyone
Use this endpoint when you want to pay somebody.
Body parameter
{
"name": "Hunter Thompson",
"email": "hunter@batcountry.com",
"branch_code": "123456",
"account_number": "13048322",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
body | body | AddAnAnyoneContactRequest | true | No description |
» name | body | string | true | The name of the Contact (140 max. characters) |
body | string | true | The email of the Contact (256 max. characters) | |
» branch_code | body | string | true | The bank account BSB of the Contact |
» account_number | body | string | true | The bank account number of the Contact |
» metadata | body | Metadata | false | Use for your custom data and certain Split customisations. |
Example responses
201 Response
{
"data": {
"id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
"name": "Hunter Thompson",
"email": "hunter@batcountry.com",
"type": "anyone",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
},
"bank_account": {
"id": "55afddde-4296-4daf-8e49-7ba481ef9608",
"account_number": "13048322",
"branch_code": "123456",
"bank_name": "National Australia Bank",
"state": "pending_verification",
"iav_provider": null,
"iav_status": null,
"blocks": {
"debits_blocked": false,
"credits_blocked": false
}
},
"links": {
"add_bank_connection": "https://go.sandbox.split.cash/invite_contact/thomas-morgan-1/1030bfef-cef5-4938-b10b-5841cafafc80"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created | Created | AddAnAnyoneContactResponse |
Add a Receivable Contact
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/contacts/receivable \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"name":"Delphine Jestin","email":"delphine@gmail.com","payid_email":"delphine_123@merchant.com.au","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/contacts/receivable")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"name\":\"Delphine Jestin\",\"email\":\"delphine@gmail.com\",\"payid_email\":\"delphine_123@merchant.com.au\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/contacts/receivable",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
name: 'Delphine Jestin',
email: 'delphine@gmail.com',
payid_email: 'delphine_123@merchant.com.au',
metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"name\":\"Delphine Jestin\",\"email\":\"delphine@gmail.com\",\"payid_email\":\"delphine_123@merchant.com.au\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/contacts/receivable", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/contacts/receivable")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.body("{\"name\":\"Delphine Jestin\",\"email\":\"delphine@gmail.com\",\"payid_email\":\"delphine_123@merchant.com.au\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"name":"Delphine Jestin","email":"delphine@gmail.com","payid_email":"delphine_123@merchant.com.au","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');
$request->setRequestUrl('https://api.sandbox.split.cash/contacts/receivable');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/contacts/receivable"
payload := strings.NewReader("{\"name\":\"Delphine Jestin\",\"email\":\"delphine@gmail.com\",\"payid_email\":\"delphine_123@merchant.com.au\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /contacts/receivable
Receive funds from a Contact by allowing them to pay to a personalised PayID or account number. Perfect for reconciling incoming funds to a customer, receiving funds instantly, eliminating human error & improving your customer's experience.
Body parameter
{
"name": "Delphine Jestin",
"email": "delphine@gmail.com",
"payid_email": "delphine_123@merchant.com.au",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
body | body | AddAReceivableContactRequest | true | No description |
» name | body | string | true | Contact name (Min: 3 - Max: 140) |
body | string | true | Contact email (Min: 6 - Max: 256) | |
» payid_email | body | string | true | Contact PayID email (Min: 6 - Max: 256) |
» metadata | body | Metadata | false | Use for your custom data and certain Split customisations. |
Example responses
201 Response
{
"data": {
"id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
"name": "Delphine Jestin",
"email": "delphine@gmail.com",
"type": "anyone",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
},
"bank_account": {
"id": "55afddde-4296-4daf-8e49-7ba481ef9608",
"account_number": "1408281",
"branch_code": "802919",
"bank_name": "Split Float Account",
"state": "active",
"iav_provider": null,
"iav_status": null,
"blocks": {
"debits_blocked": false,
"credits_blocked": false
}
},
"anyone_account": {
"id": "77be6ecc-5fa7-454b-86d6-02a5f147878d"
},
"payid_details": {
"alias_value": "delphine_123@merchant.com.au",
"alias_type": "email",
"alias_name": "your merchant's alias_name",
"state": "pending"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created | Created | AddAReceivableContactResponse |
404 | Not Found | Not Found | None |
Add a Split Contact
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/contacts \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"nickname":"outstanding_tours","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/contacts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"nickname\":\"outstanding_tours\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/contacts",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
nickname: 'outstanding_tours',
metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"nickname\":\"outstanding_tours\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/contacts", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/contacts")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.body("{\"nickname\":\"outstanding_tours\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"nickname":"outstanding_tours","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');
$request->setRequestUrl('https://api.sandbox.split.cash/contacts');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/contacts"
payload := strings.NewReader("{\"nickname\":\"outstanding_tours\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /contacts
Add a Split Contact
Body parameter
{
"nickname": "outstanding_tours",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
body | body | AddASplitContactRequest | true | No description |
» nickname | body | string | true | Split account nickname |
» metadata | body | Metadata | false | Use for your custom data and certain Split customisations. |
Example responses
201 Response
{
"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"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created | Created | AddASplitContactResponse |
404 | Not Found | Not Found | None |
List all Contacts
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/contacts \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/contacts")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/contacts",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/contacts", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/contacts")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/contacts');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/contacts"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /contacts
By default, all Contacts will be returned. You can apply filters to your query to customise the returned Contact list.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
name | query | string | false | Single value, string search |
nickname | query | string | false | Single value, string search |
query | string | false | Single value, string search | |
bank_account_id | query | string | false | Single value, exact match |
bank_account_branch_code | query | string | false | Single value, exact match |
bank_account_account_number | query | string | false | Single value, exact match |
Example responses
200 Response
{
"data": [
{
"id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
"name": "Outstanding Tours Pty Ltd",
"email": "accounts@outstandingtours.com.au",
"type": "Split account",
"bank_account": {
"id": "095c5ab7-7fa8-40fd-b317-cddbbf4c8fbc",
"account_number": "494307",
"branch_code": "435434",
"bank_name": "National Australia Bank",
"state": "active",
"iav_provider": "split",
"iav_status": "active",
"blocks": {
"debits_blocked": false,
"credits_blocked": false
}
},
"bank_connection": {
"id": "c397645b-bd4f-4fc6-b1fe-4993fef6c3c7"
}
},
{
"id": "49935c67-c5df-4f00-99f4-1413c18a89a0",
"name": "Adventure Dudes Pty Ltd",
"email": "accounts@adventuredudes.com.au",
"type": "Split account",
"bank_account": {
"id": "861ff8e4-7acf-4897-9e53-e7c5ae5f7cc0",
"account_number": "4395959",
"branch_code": "068231",
"bank_name": "National Australia Bank",
"state": "active",
"iav_provider": "split",
"iav_status": "credentials_invalid",
"blocks": {
"debits_blocked": false,
"credits_blocked": false
}
},
"bank_connection": {
"id": "c397645b-bd4f-4fc6-b1fe-4993fef6c3c7"
}
},
{
"id": "eb3266f9-e172-4b6c-b802-fe5ac4d3250a",
"name": "Surfing World Pty Ltd",
"email": "accounts@surfingworld.com.au",
"type": "Split account",
"bank_account": {
"id": null,
"account_number": null,
"branch_code": null,
"bank_name": null,
"state": "disabled",
"iav_provider": null,
"iav_status": null,
"blocks": {
"debits_blocked": false,
"credits_blocked": false
}
},
"links": {
"add_bank_connection": "https://go.sandbox.split.cash/invite_contact/thomas-morgan-1/1030bfef-cef5-4938-b10b-5841cafafc80"
}
},
{
"id": "6a7ed958-f1e8-42dc-8c02-3901d7057357",
"name": "Hunter Thompson",
"email": "hunter@batcountry.com",
"type": "anyone",
"bank_account": {
"id": "55afddde-4296-4daf-8e49-7ba481ef9608",
"account_number": "13048322",
"branch_code": "123456",
"bank_name": "National Australia Bank",
"state": "pending_verification",
"iav_provider": null,
"iav_status": null,
"blocks": {
"debits_blocked": false,
"credits_blocked": false
}
},
"links": {
"add_bank_connection": "https://go.sandbox.split.cash/invite_contact/thomas-morgan-1/1030bfef-cef5-4938-b10b-5841cafafc80"
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListAllContactsResponse |
Get a Contact
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608 \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /contacts/{id}
Get a single Contact by its ID
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
id | path | string(UUID) | true | Contact ID (Contact.data.id ) |
Example responses
200 Response
{
"data": {
"id": "55afddde-4296-4daf-8e49-7ba481ef9608",
"ref": "CNT.123",
"name": "Outstanding Tours Pty Ltd",
"email": "accounts@outstandingtours.com.au",
"type": "anyone",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
},
"bank_account": {
"id": "fcabeacb-2ef6-4b27-ba19-4f6fa0d57dcb",
"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
}
},
"anyone_account": {
"id": "31a05f81-25a2-4085-92ef-0d16d0263bff"
},
"bank_connection": {
"id": null
},
"links": {
"add_bank_connection": "https://go.sandbox.split.cash/invite_contact/thomas-morgan-1/1030bfef-cef5-4938-b10b-5841cafafc80"
},
"payid_details": {
"alias_value": "otp@pay.travel.com.au",
"alias_type": "email",
"alias_name": "your merchant's alias_name",
"state": "active"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | GetAContactResponse |
404 | Not Found | Not Found | None |
Remove a Contact
Code samples
curl --request DELETE \
--url https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608 \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "DELETE",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608",
"headers": {
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = { 'authorization': "Bearer {access-token}" }
conn.request("DELETE", "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.delete("https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
DELETE /contacts/{id}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
id | path | string(UUID) | true | Contact ID (Contact.data.id ) |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | No description | None |
Update a Contact
Code samples
curl --request PATCH \
--url https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608 \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"name":"My very own alias","email":"updated@email.com","branch_code":"123456","account_number":"99887766","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Patch.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"name\":\"My very own alias\",\"email\":\"updated@email.com\",\"branch_code\":\"123456\",\"account_number\":\"99887766\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "PATCH",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
name: 'My very own alias',
email: 'updated@email.com',
branch_code: '123456',
account_number: '99887766',
metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"name\":\"My very own alias\",\"email\":\"updated@email.com\",\"branch_code\":\"123456\",\"account_number\":\"99887766\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("PATCH", "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.patch("https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.body("{\"name\":\"My very own alias\",\"email\":\"updated@email.com\",\"branch_code\":\"123456\",\"account_number\":\"99887766\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"name":"My very own alias","email":"updated@email.com","branch_code":"123456","account_number":"99887766","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');
$request->setRequestUrl('https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608');
$request->setRequestMethod('PATCH');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608"
payload := strings.NewReader("{\"name\":\"My very own alias\",\"email\":\"updated@email.com\",\"branch_code\":\"123456\",\"account_number\":\"99887766\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
PATCH /contacts/{id}
You can update the name, email, bank account and metadata of any Contact.
Body parameter
{
"name": "My very own alias",
"email": "updated@email.com",
"branch_code": "123456",
"account_number": "99887766",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
id | path | string | true | Contact ID (Contact.data.id ) |
body | body | UpdateAContactRequest | true | No description |
» name | body | string | false | The name of the Contact |
body | string | false | The email of the Contact | |
» branch_code | body | string | false | The bank account BSB of the Contact |
» account_number | body | string | false | The bank account number of the Contact |
» metadata | body | Metadata | false | Use for your custom data and certain Split customisations. |
Example responses
200 Response
{
"data": {
"id": "fcabeacb-2ef6-4b27-ba19-4f6fa0d57dcb",
"name": "My very own alias",
"email": "updated@email.com",
"type": "anyone",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
},
"bank_account": {
"id": "55afddde-4296-4daf-8e49-7ba481ef9608",
"account_number": "99887766",
"branch_code": "123456",
"bank_name": "Split SANDBOX Bank",
"state": "active",
"iav_provider": null,
"iav_status": null,
"blocks": {
"debits_blocked": false,
"credits_blocked": false
}
},
"anyone_account": {
"id": "63232c0a-a783-4ae9-ae73-f0974fe1e345"
},
"links": {
"add_bank_connection": "http://go.sandbox.split.cash/invite_contact/dog-bones-inc/fcabeacb-2ef6-4b27-ba19-4f6fa0d57dcb"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | UpdateAContactResponse |
404 | Not Found | Not Found | None |
Refresh contact bank connection
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608/refresh_balance \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608/refresh_balance")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608/refresh_balance",
"headers": {
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = { 'authorization': "Bearer {access-token}" }
conn.request("POST", "/contacts/55afddde-4296-4daf-8e49-7ba481ef9608/refresh_balance", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608/refresh_balance")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608/refresh_balance');
$request->setRequestMethod('POST');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/contacts/55afddde-4296-4daf-8e49-7ba481ef9608/refresh_balance"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /contacts/{id}/refresh_balance
Request the bank connection for a contact to refresh available funds. This is intended for use in conjunction with the precheck_funds
option, see Payment Request - Precheck Funds
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
id | path | string(UUID) | true | Contact ID (Contact.data.id ) |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | No Content (success) | None |
422 | Unprocessable Entity | Unprocessable Entity (errors) | None |
Open Agreements
An Open Agreement is essentially an Agreement template with no specific authoriser. Each time an Open Agreement is accepted by either a Split account holder or anyone, the authoriser is added to your Contacts list and a new Agreement is automatically created between the Open Agreement initiator and the authoriser.
An Open Agreement can be accepted multiple times by different parties and the result is the same: A new Agreement. Additionally, an Open Agreement can be accepted by anybody, not just other Split users. This is achieved by using our Instant Account Verification process as part of accepting an Open Agreement.
Lifecycle
An Open Agreement can have the following statuses:
Status | Description |
---|---|
active |
The Open Agreement can be viewed and accepted. |
closed |
The Open Agreement can not be viewed or accepted. |
Create an Open Agreement
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/open_agreements \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"title":"Subscription Plan A","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"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/open_agreements")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"title\":\"Subscription Plan A\",\"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\"}}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/open_agreements",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
title: 'Subscription Plan A',
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' }
}));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"title\":\"Subscription Plan A\",\"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\"}}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/open_agreements", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/open_agreements")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.body("{\"title\":\"Subscription Plan A\",\"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\"}}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"title":"Subscription Plan A","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"}}');
$request->setRequestUrl('https://api.sandbox.split.cash/open_agreements');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/open_agreements"
payload := strings.NewReader("{\"title\":\"Subscription Plan A\",\"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\"}}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /open_agreements
Create an Open Agreement that can be accepted by anyone.
Body parameter
{
"title": "Subscription Plan A",
"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"
}
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
body | body | CreateOpenAgreementRequest | true | No description |
» title | body | string | true | Title of the Open Agreement (Visible to authorisers) |
» terms | body | Terms | true | Terms |
»» per_payout | body | PerPayout | true | No description |
»»» min_amount | body | integer | true | Minimum amount in cents a PR can be in order to be auto-approved. Specify null for no limit. |
»»» max_amount | body | integer | true | Maximum amount in cents a PR can be in order to be auto-approved. Specify null for no limit. |
»» per_frequency | body | PerFrequency | true | No description |
»»» days | body | integer | true | Amount of days to apply against the frequency. Specify null for no limit. |
»»» max_amount | body | integer | true | Maximum amount in cents the total of all PRs can be for the duration of the frequency. Specify null for no limit. |
»» metadata | body | Metadata | false | Use for your custom data and certain Split customisations. |
Example responses
200 Response
{
"data": {
"ref": "OA.1",
"title": "Subscription Plan A",
"status": "active",
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"min_amount": null,
"max_amount": 10000
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
},
"link": "https://go.sandbox.split.cash/open_agreements/aecff76d-13e0-4e17-b7c5-844ae07fa675/agreements/invitation"
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Created | CreateOpenAgreementResponse |
List all Open Agreements
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/open_agreements \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/open_agreements")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/open_agreements",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/open_agreements", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/open_agreements")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/open_agreements');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/open_agreements"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /open_agreements
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
Example responses
200 Response
{
"data": [
{
"ref": "OA.1",
"title": "Subscription Plan A",
"status": "active",
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": null
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
},
"link": "https://go.sandbox.split.cash/open_agreements/2e002c0b-ffaf-44eb-a35c-15fa384ddde1/agreements/invitation"
},
{
"ref": "OA.2",
"title": "Subscription Plan B",
"status": "closed",
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": null
},
"per_frequency": {
"days": null,
"max_amount": null
}
},
"link": "https://go.sandbox.split.cash/open_agreements/948e3662-154d-42d1-bdc9-a05c251d3981/agreements/invitation"
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListAllOpenAgreementsResponse |
Activate a closed Open Agreement
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/open_agreements/OA.1/activate \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/open_agreements/OA.1/activate")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/open_agreements/OA.1/activate",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/open_agreements/OA.1/activate", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/open_agreements/OA.1/activate")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/open_agreements/OA.1/activate');
$request->setRequestMethod('POST');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/open_agreements/OA.1/activate"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /open_agreements/{open_agreement_ref}/activate
Allow the Open Agreement to viewed and accepted
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
open_agreement_ref | path | string | true | Single value, exact match |
Example responses
200 Response
{
"data": {
"ref": "OA.1",
"title": "Subscription Plan A",
"status": "active",
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": null
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
},
"link": "https://go.sandbox.split.cash/open_agreements/2e002c0b-ffaf-44eb-a35c-15fa384ddde1/agreements/invitation"
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ActivateOpenAgreementResponse |
Close an active Open Agreement
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/open_agreements/OA.1/close \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/open_agreements/OA.1/close")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/open_agreements/OA.1/close",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/open_agreements/OA.1/close", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/open_agreements/OA.1/close")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/open_agreements/OA.1/close');
$request->setRequestMethod('POST');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/open_agreements/OA.1/close"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /open_agreements/{open_agreement_ref}/close
Disable the Open Agreement from being viewed or accepted
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
open_agreement_ref | path | string | true | Single value, exact match |
Example responses
200 Response
{
"data": {
"ref": "OA.1",
"title": "Subscription Plan A",
"status": "closed",
"created_at": "2017-03-20T00:53:27Z",
"terms": {
"per_payout": {
"max_amount": 10000,
"min_amount": null
},
"per_frequency": {
"days": 7,
"max_amount": 1000000
}
},
"link": "https://go.sandbox.split.cash/open_agreements/2e002c0b-ffaf-44eb-a35c-15fa384ddde1/agreements/invitation"
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | CloseOpenAgreementResponse |
Payment Requests
A Payment Request (PR) is used to identify incoming funds from another party.
- You send a Payment Request to a Contact in order to collect funds:
- Given there is an Agreement in place and the Payment Request is within the terms of the Agreement, then it will be automatically approved; or
- Given the Payment Request is not within the terms of the Agreement, then it will not be created; or
- There is no Agreement in place, then it will not be created.
- Your customer sends funds to you as a Receivable Contact:
- A receivable Payment Request will be automatically created and approved to identify the movement of funds from your customer to your chosen Split float account.
Lifecycle
A Payment Request can have the following statuses:
Status | Description |
---|---|
pending_approval |
Waiting for the debtor to approve the Payment Request. |
unverified |
Waiting for available funds response (only applicable when precheck_funds enabled). |
approved |
The debtor has approved the Payment Request. |
declined |
The debtor has declined the Payment Request. |
cancelled |
The creditor has cancelled the Payment Request. |
Split will automatically check for available funds before attempting to debit the debtor. This check is only performed for contacts with an active bank connection.
Prechecking as part of a Payment Request approval
When the precheck_funds
option is enabled, approval of a Payment Request will only be allowed when there are sufficient funds. The debtor contact must have a valid agreement and bank connection to make use of this option.
There are synchronous and asynchronous lifecycles when the precheck_funds
option is enabled.
- When the available funds for a contact's bank account are considered out of date, the API response will return the Payment Request with a state of
unverified
while the bank account data is refreshed. Once the precheck has completed, the Payment Request state will transition to eitherapproved
ordeclined
. This process can be followed by subscribing to the relevant webhook events or regularly polling the Payment Request and verifying its status. - When the available funds for a contact are current, the API will respond immediately with a final state of either
approved
or an error message if there are insufficient funds.
You can gain some control over this process by preemptively telling Split to refresh a contact's available balance at least 1 minute before making a Payment Request. See Contact balance refresh for more.
Request Payment
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/payment_requests \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"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","your_bank_account_id":"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679","precheck_funds":false,"metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payment_requests")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
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\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"precheck_funds\":false,\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payment_requests",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
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',
your_bank_account_id: '9c70871d-8e36-4c3e-8a9c-c0ee20e7c679',
precheck_funds: false,
metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"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\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"precheck_funds\":false,\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/payment_requests", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/payment_requests")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.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\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"precheck_funds\":false,\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"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","your_bank_account_id":"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679","precheck_funds":false,"metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');
$request->setRequestUrl('https://api.sandbox.split.cash/payment_requests');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payment_requests"
payload := strings.NewReader("{\"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\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"precheck_funds\":false,\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /payment_requests
Body parameter
{
"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",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"precheck_funds": false,
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
body | body | MakeAPaymentRequestRequest | true | No description |
» description | body | string | true | Description visible to the initiator (payee). The first 9 characters supplied will be visible to the authoriser (payer) |
» matures_at | body | string(date-time) | true | Date & time in UTC ISO8601 that the Payment will be processed if the request is approved. (If the request is approved after this point in time, it will be processed straight away) |
» amount | body | integer | true | Amount in cents to pay the initiator (Min: 1 - Max: 99999999999) |
» authoriser_contact_id | body | string | true | The Contact the payment will be requested from (Contact.data.id ) |
» precheck_funds | body | boolean | false | Enforce prechecking of available funds before approving the Payment Request. see Payment Request - Precheck Funds |
» your_bank_account_id | body | string(uuid) | false | Specify where we should settle the funds for this transaction. If omitted, your primary bank account will be used. |
» metadata | body | object | false | Use for your custom data and certain Split customisations. Stored against generated transactions and included in associated webhook payloads. |
Example responses
200 Response
{
"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",
"status_reason": null,
"matures_at": "2016-12-25T00:00:00Z",
"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"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Created | MakeAPaymentRequestResponse |
422 | Unprocessable Entity | When a payment is requested from an Anyone Contact with no valid Agreement | MakeAPaymentRequestWithNoAgreementResponse |
Get a Payment Request
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/payment_requests/PR.3 \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payment_requests/PR.3")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payment_requests/PR.3",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/payment_requests/PR.3", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/payment_requests/PR.3")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payment_requests/PR.3');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payment_requests/PR.3"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /payment_requests/{payment_request_ref}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
payment_request_ref | path | string | true | Single value, exact match |
Example responses
200 Response
{
"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": "approved",
"status_reason": null,
"matures_at": "2016-12-25T00:00:00Z",
"responded_at": "2016-12-19T02:38:04Z",
"created_at": "2016-12-19T02:10:56Z",
"credit_ref": "C.b",
"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"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | GetAPaymentRequestResponse |
Cancel a Payment Request
Code samples
curl --request DELETE \
--url https://api.sandbox.split.cash/payment_requests/PR.3 \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payment_requests/PR.3")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Delete.new(url)
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "DELETE",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payment_requests/PR.3",
"headers": {
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = { 'authorization': "Bearer {access-token}" }
conn.request("DELETE", "/payment_requests/PR.3", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.delete("https://api.sandbox.split.cash/payment_requests/PR.3")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payment_requests/PR.3');
$request->setRequestMethod('DELETE');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payment_requests/PR.3"
req, _ := http.NewRequest("DELETE", url, nil)
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
DELETE /payment_requests/{payment_request_ref}
A Payment Request can be cancelled as long as the associated transaction's state is maturing or matured.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
payment_request_ref | path | string | true | Single value, exact match |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | No Content | None |
List Payment Requests
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/payment_requests/outgoing \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payment_requests/outgoing")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payment_requests/outgoing",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/payment_requests/outgoing", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/payment_requests/outgoing")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payment_requests/outgoing');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payment_requests/outgoing"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /payment_requests/outgoing
Payment Requests where you're the creditor and collecting funds from the debtor. Alternatively the debtor is sending you funds (Receivable Contacts)
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
Example responses
200 Response
{
"data": [
{
"ref": "PR.4",
"initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"authoriser_id": "de86472c-c027-4735-a6a7-234366a27fc7",
"authoriser_contact_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
"schedule_ref": "PRS.2",
"status": "approved",
"status_reason": null,
"matures_at": "2016-12-20T00:00:00Z",
"responded_at": "2016-12-19T02:10:18Z",
"created_at": "2016-12-19T02:09:09Z",
"credit_ref": "C.a",
"payout": {
"amount": 30000,
"description": "The SuperPackage",
"matures_at": "2016-12-20T00:00:00Z"
}
},
{
"ref": "PR.5",
"initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"authoriser_id": "de86472c-c027-4735-a6a7-234366a27fc7",
"authoriser_contact_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
"schedule_ref": null,
"status": "pending_approval",
"status_reason": null,
"matures_at": "2016-12-25T00:00:00Z",
"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"
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListOutgoingPaymentRequestsResponse |
Get a Payment Request's history
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/payment_requests/PR.3/history \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payment_requests/PR.3/history")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payment_requests/PR.3/history",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/payment_requests/PR.3/history", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/payment_requests/PR.3/history")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payment_requests/PR.3/history');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payment_requests/PR.3/history"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /payment_requests/{payment_request_ref}/history
Gives you visibility of the entire Payment Request lifecycle including the generated debit and credit transactions.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
payment_request_ref | path | string | true | Single value, exact match |
Example responses
200 Response
{
"data": [
{
"type": "payout_request",
"event": "requested",
"at": "2017-01-05T07:47:45Z",
"ref": "PR.3",
"by": "Fancy Pants (fancy_pants)"
},
{
"type": "payout_request",
"event": "approved",
"at": "2017-01-07T06:13:52Z",
"ref": "PR.3",
"by": "Lycra Co (lycra_co)"
},
{
"type": "debit",
"event": "scheduled",
"at": "2017-01-07T06:13:52Z",
"ref": "D.n",
"by": "Split Payments"
},
{
"type": "credit",
"event": "scheduled",
"at": "2017-01-07T06:13:52Z",
"ref": "C.e",
"by": "Split Payments"
},
{
"type": "debit",
"event": "matured",
"at": "2017-01-08T04:30:14Z",
"ref": "D.n",
"by": "Split Payments"
},
{
"type": "debit",
"event": "processing",
"at": "2017-01-08T04:30:14Z",
"ref": "D.n",
"by": "Split Payments"
},
{
"type": "debit",
"event": "clearing",
"at": "2017-01-08T19:02:20Z",
"ref": "D.n",
"by": "Split Payments"
},
{
"type": "debit",
"event": "cleared",
"at": "2017-01-11T19:07:52Z",
"ref": "D.n",
"by": "Split Payments"
},
{
"type": "credit",
"event": "matured",
"at": "2017-01-11T19:07:52Z",
"ref": "C.e",
"by": "Split Payments"
},
{
"type": "credit",
"event": "processing",
"at": "2017-01-12T04:30:25Z",
"ref": "C.e",
"by": "Split Payments"
},
{
"type": "credit",
"event": "clearing",
"at": "2017-01-12T05:17:32Z",
"ref": "C.e",
"by": "Split Payments"
},
{
"type": "credit",
"event": "cleared",
"at": "2017-01-15T05:27:12Z",
"ref": "C.e",
"by": "Split Payments"
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | GetAPaymentRequestsHistoryResponse |
List incoming Payment Requests
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/payment_requests/incoming \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payment_requests/incoming")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payment_requests/incoming",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/payment_requests/incoming", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/payment_requests/incoming")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payment_requests/incoming');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payment_requests/incoming"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /payment_requests/incoming
Payment Requests where you're the debtor and another Split account is collecting funds from you.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
Example responses
200 Response
{
"data": [
{
"ref": "PR.2",
"initiator_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
"your_bank_account_id": "049528f7-6698-40a6-8221-52ec406e5424",
"authoriser_id": "de86472c-c027-4735-a6a7-234366a27fc7",
"authoriser_contact_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
"schedule_ref": "PRS.1",
"status": "approved",
"status_reason": null,
"matures_at": "2016-12-20T00:00:00Z",
"responded_at": "2016-12-19T02:10:18Z",
"created_at": "2016-12-19T02:09:09Z",
"debit_ref": "D.a",
"payout": {
"amount": 30000,
"description": "The SuperPackage",
"matures_at": "2016-12-20T00:00:00Z"
}
},
{
"ref": "PR.3",
"initiator_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
"your_bank_account_id": "049528f7-6698-40a6-8221-52ec406e5424",
"authoriser_id": "de86472c-c027-4735-a6a7-234366a27fc7",
"authoriser_contact_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
"schedule_ref": null,
"status": "pending_approval",
"status_reason": null,
"matures_at": "2016-12-25T00:00:00Z",
"responded_at": null,
"created_at": "2016-12-19T02:10:56Z",
"debit_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"
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListIncomingPaymentRequestsResponse |
Approve a Payment Request
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/payment_requests/PR.3/approve \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payment_requests/PR.3/approve")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payment_requests/PR.3/approve",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/payment_requests/PR.3/approve", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/payment_requests/PR.3/approve")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payment_requests/PR.3/approve');
$request->setRequestMethod('POST');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payment_requests/PR.3/approve"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /payment_requests/{payment_request_ref}/approve
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
payment_request_ref | path | string | true | Single value, exact match |
Example responses
200 Response
{
"data": {
"ref": "PR.3",
"initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"authoriser_id": "d194c54b-9183-410c-966b-50485c5ce3f0",
"authoriser_contact_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
"schedule_ref": null,
"status": "approved",
"status_reason": null,
"matures_at": "2016-12-25T00:00:00Z",
"responded_at": "2016-12-19T02:38:04Z",
"created_at": "2016-12-19T02:10:56Z",
"debit_ref": "D.b",
"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"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ApprovePaymentRequestResponse |
Decline a Payment Request
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/payment_requests/PR.3/decline \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payment_requests/PR.3/decline")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payment_requests/PR.3/decline",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/payment_requests/PR.3/decline", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/payment_requests/PR.3/decline")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payment_requests/PR.3/decline');
$request->setRequestMethod('POST');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payment_requests/PR.3/decline"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /payment_requests/{payment_request_ref}/decline
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
payment_request_ref | path | string | true | Single value, exact match |
Example responses
200 Response
{
"data": {
"ref": "PR.3",
"initiator_id": "ca7bc5b3-e47f-4153-96fb-bbe326b42772",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"authoriser_id": "d194c54b-9183-410c-966b-50485c5ce3f0",
"authoriser_contact_id": "fb6a9252-3818-44dc-b5aa-2195391a746f",
"schedule_ref": null,
"status": "declined",
"status_reason": null,
"matures_at": "2016-12-25T00:00:00Z",
"responded_at": "2016-12-19T02:38:04Z",
"created_at": "2016-12-19T02:10:56Z",
"debit_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"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | No description | DeclinePaymentRequestResponse |
Payments
A Payment is made up of two parts:
- General details about the Payment.
- One or many Payouts with individual recipients, amounts and descriptions.
Lifecycle
Example payout reversal response
{
"data": [
{
"ref": "C.3",
"parent_ref": "PB.1",
"type": "credit",
"category": "payout_reversal",
"created_at": "2016-12-07T23:15:00Z",
"matures_at": "2016-12-10T23:15:00Z",
"cleared_at": null,
"bank_ref": null,
"status": "maturing",
"status_changed_at": "2016-12-08T23:15:00Z",
"party_contact_id": "26297f44-c5e1-40a1-9864-3e0b0754c32a",
"party_name": "Sanford-Rees",
"party_nickname": "sanford-rees-8",
"description": "Payout reversal of D.1 for Sanford-Rees due to no account or incorrect account number"
"amount": 1,
"reversal_details": {
"source_debit_ref": "D.1",
"source_credit_failure_reason": "incorrect_account_number",
}
}
]
}
A Payment is simply a group of Payouts, therefore it does not have a particular status. Its Payouts however have their status regularly updated. For a list of possible Payout statuses check out the Transactions.
When Split is unable to credit funds to a recipient, we will automatically create a payout reversal credit back to the payer. Furthermore, within the payout reversal credit, Split will include details in the description
and under the reversal_details
key as to why the original credit to the recipient failed.
Make a Payment
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/payments \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"description":"The SuperPackage","matures_at":"2016-09-13T00:00:00Z","your_bank_account_id":"83623359-e86e-440c-9780-432a3bc3626f","payouts":[{"amount":30000,"description":"A tandem skydive jump SB23094","recipient_contact_id":"48b89364-1577-4c81-ba02-96705895d457","metadata":{"invoice_ref":"BILL-0001","invoice_id":"c80a9958-e805-47c0-ac2a-c947d7fd778d","custom_key":"Custom string","another_custom_key":"Maybe a URL"}},{"amount":30000,"description":"A scuba dive SDS5464","recipient_contact_id":"dc6f1e60-3803-43ca-a200-7d641816f57f"}],"metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"description\":\"The SuperPackage\",\"matures_at\":\"2016-09-13T00:00:00Z\",\"your_bank_account_id\":\"83623359-e86e-440c-9780-432a3bc3626f\",\"payouts\":[{\"amount\":30000,\"description\":\"A tandem skydive jump SB23094\",\"recipient_contact_id\":\"48b89364-1577-4c81-ba02-96705895d457\",\"metadata\":{\"invoice_ref\":\"BILL-0001\",\"invoice_id\":\"c80a9958-e805-47c0-ac2a-c947d7fd778d\",\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}},{\"amount\":30000,\"description\":\"A scuba dive SDS5464\",\"recipient_contact_id\":\"dc6f1e60-3803-43ca-a200-7d641816f57f\"}],\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payments",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
description: 'The SuperPackage',
matures_at: '2016-09-13T00:00:00Z',
your_bank_account_id: '83623359-e86e-440c-9780-432a3bc3626f',
payouts: [
{
amount: 30000,
description: 'A tandem skydive jump SB23094',
recipient_contact_id: '48b89364-1577-4c81-ba02-96705895d457',
metadata: {
invoice_ref: 'BILL-0001',
invoice_id: 'c80a9958-e805-47c0-ac2a-c947d7fd778d',
custom_key: 'Custom string',
another_custom_key: 'Maybe a URL'
}
},
{
amount: 30000,
description: 'A scuba dive SDS5464',
recipient_contact_id: 'dc6f1e60-3803-43ca-a200-7d641816f57f'
}
],
metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"description\":\"The SuperPackage\",\"matures_at\":\"2016-09-13T00:00:00Z\",\"your_bank_account_id\":\"83623359-e86e-440c-9780-432a3bc3626f\",\"payouts\":[{\"amount\":30000,\"description\":\"A tandem skydive jump SB23094\",\"recipient_contact_id\":\"48b89364-1577-4c81-ba02-96705895d457\",\"metadata\":{\"invoice_ref\":\"BILL-0001\",\"invoice_id\":\"c80a9958-e805-47c0-ac2a-c947d7fd778d\",\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}},{\"amount\":30000,\"description\":\"A scuba dive SDS5464\",\"recipient_contact_id\":\"dc6f1e60-3803-43ca-a200-7d641816f57f\"}],\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/payments", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/payments")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.body("{\"description\":\"The SuperPackage\",\"matures_at\":\"2016-09-13T00:00:00Z\",\"your_bank_account_id\":\"83623359-e86e-440c-9780-432a3bc3626f\",\"payouts\":[{\"amount\":30000,\"description\":\"A tandem skydive jump SB23094\",\"recipient_contact_id\":\"48b89364-1577-4c81-ba02-96705895d457\",\"metadata\":{\"invoice_ref\":\"BILL-0001\",\"invoice_id\":\"c80a9958-e805-47c0-ac2a-c947d7fd778d\",\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}},{\"amount\":30000,\"description\":\"A scuba dive SDS5464\",\"recipient_contact_id\":\"dc6f1e60-3803-43ca-a200-7d641816f57f\"}],\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"description":"The SuperPackage","matures_at":"2016-09-13T00:00:00Z","your_bank_account_id":"83623359-e86e-440c-9780-432a3bc3626f","payouts":[{"amount":30000,"description":"A tandem skydive jump SB23094","recipient_contact_id":"48b89364-1577-4c81-ba02-96705895d457","metadata":{"invoice_ref":"BILL-0001","invoice_id":"c80a9958-e805-47c0-ac2a-c947d7fd778d","custom_key":"Custom string","another_custom_key":"Maybe a URL"}},{"amount":30000,"description":"A scuba dive SDS5464","recipient_contact_id":"dc6f1e60-3803-43ca-a200-7d641816f57f"}],"metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');
$request->setRequestUrl('https://api.sandbox.split.cash/payments');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payments"
payload := strings.NewReader("{\"description\":\"The SuperPackage\",\"matures_at\":\"2016-09-13T00:00:00Z\",\"your_bank_account_id\":\"83623359-e86e-440c-9780-432a3bc3626f\",\"payouts\":[{\"amount\":30000,\"description\":\"A tandem skydive jump SB23094\",\"recipient_contact_id\":\"48b89364-1577-4c81-ba02-96705895d457\",\"metadata\":{\"invoice_ref\":\"BILL-0001\",\"invoice_id\":\"c80a9958-e805-47c0-ac2a-c947d7fd778d\",\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}},{\"amount\":30000,\"description\":\"A scuba dive SDS5464\",\"recipient_contact_id\":\"dc6f1e60-3803-43ca-a200-7d641816f57f\"}],\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /payments
Body parameter
{
"description": "The SuperPackage",
"matures_at": "2016-09-13T00:00:00Z",
"your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
"payouts": [
{
"amount": 30000,
"description": "A tandem skydive jump SB23094",
"recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
"metadata": {
"invoice_ref": "BILL-0001",
"invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
},
{
"amount": 30000,
"description": "A scuba dive SDS5464",
"recipient_contact_id": "dc6f1e60-3803-43ca-a200-7d641816f57f"
}
],
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
body | body | MakeAPaymentRequest | true | No description |
» description | body | string | true | User description. Only visible to the payer |
» matures_at | body | string(date-time) | true | Date & time in UTC ISO8601 the Payment should be processed. (Can not be earlier than the start of current day) |
» your_bank_account_id | body | string | false | Specify where we should take the funds for this transaction. If omitted, your primary bank account will be used. |
» payouts | body | [Payout] | true | One or many Payouts |
»» Payout | body | Payout | false | The actual Payout |
»»» amount | body | integer | true | Amount in cents to pay the recipient |
»»» description | body | string | true | Description that both the payer and recipient can see. For Direct Entry payments, the payout recipient will see the first 9 characters of this description. For NPP payments, the payout recipient will see the first 280 characters of this description. |
»»» recipient_contact_id | body | string | true | Contact to pay (Contact.data.id ) |
»»» metadata | body | Metadata | false | Use for your custom data and certain Split customisations. Stored against generated transactions and included in associated webhook payloads. |
»» metadata | body | Metadata | false | Use for your custom data and certain Split customisations. |
Example responses
201 Response
{
"data": {
"ref": "PB.1",
"your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
"payouts": [
{
"ref": "D.1",
"recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
"batch_description": "The SuperPackage",
"matures_at": "2016-09-13T23:50:44Z",
"created_at": "2016-09-10T23:50:44Z",
"status": "maturing",
"amount": 30000,
"description": "A tandem skydive jump SB23094",
"from_id": "83623359-e86e-440c-9780-432a3bc3626f",
"to_id": "21066764-c103-4e7f-b436-4cee7db5f400",
"metadata": {
"invoice_ref": "BILL-0001",
"invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
},
{
"ref": "D.2",
"recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
"batch_description": "The SuperPackage",
"matures_at": "2016-09-13T23:50:44Z",
"created_at": "2016-09-10T23:50:44Z",
"status": "maturing",
"amount": 30000,
"description": "A scuba dive SDS5464",
"from_id": "83623359-e86e-440c-9780-432a3bc3626f",
"to_id": "21066764-c103-4e7f-b436-4cee7db5f400"
}
],
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created | Created | MakeAPaymentResponse |
List all Payments
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/payments \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payments",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/payments", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/payments")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payments');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payments"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /payments
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
Example responses
200 Response
{
"data": [
{
"ref": "PB.1",
"your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
"payouts": [
{
"ref": "D.1",
"recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
"batch_description": "This description is only available to the payer",
"matures_at": "2016-09-13T23:50:44Z",
"created_at": "2016-09-10T23:50:44Z",
"status": "maturing",
"amount": 30000,
"description": "The recipient will see this description",
"from_id": "83623359-e86e-440c-9780-432a3bc3626f",
"to_id": "21066764-c103-4e7f-b436-4cee7db5f400",
"metadata": {
"invoice_ref": "BILL-0001",
"invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
},
{
"ref": "D.2",
"recipient_contact_id": "dc6f1e60-3803-43ca-a200-7d641816f57f",
"batch_description": "This description is only available to the payer",
"matures_at": "2016-09-13T23:50:44Z",
"created_at": "2016-09-10T23:50:44Z",
"status": "maturing",
"amount": 30000,
"description": "The recipient will see this description",
"from_id": "48b89364-1577-4c81-ba02-96705895d457",
"to_id": "f989d9cd-87fc-4c73-b0a4-1eb0e8768d3b"
}
],
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListAllPaymentsResponse |
Get a Payment
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/payments/PB.1 \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payments/PB.1")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payments/PB.1",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/payments/PB.1", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/payments/PB.1")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payments/PB.1');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payments/PB.1"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /payments/{payment_ref}
Get a single payment by its reference
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
payment_ref | path | string | true | Payment reference |
Example responses
200 Response
{
"data": {
"ref": "PB.1",
"your_bank_account_id": "83623359-e86e-440c-9780-432a3bc3626f",
"payouts": [
{
"ref": "D.1",
"recipient_contact_id": "48b89364-1577-4c81-ba02-96705895d457",
"batch_description": "The SuperPackage",
"matures_at": "2016-09-13T23:50:44Z",
"created_at": "2016-09-10T23:50:44",
"status": "maturing",
"amount": 30000,
"description": "A tandem skydive jump SB23094",
"from_id": "83623359-e86e-440c-9780-432a3bc3626f",
"to_id": "21066764-c103-4e7f-b436-4cee7db5f400",
"metadata": {
"invoice_ref": "BILL-0001",
"invoice_id": "c80a9958-e805-47c0-ac2a-c947d7fd778d",
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
},
{
"ref": "D.2",
"recipient_contact_id": "dc6f1e60-3803-43ca-a200-7d641816f57f",
"batch_description": "The SuperPackage",
"matures_at": "2016-09-13T23:50:44Z",
"created_at": "2016-09-10T23:50:44Z",
"status": "maturing",
"amount": 30000,
"description": "A scuba dive SDS5464",
"from_id": "48b89364-1577-4c81-ba02-96705895d457",
"to_id": "f989d9cd-87fc-4c73-b0a4-1eb0e8768d3b"
}
],
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | GetAPaymentResponse |
Payouts
Payouts are what a Payment or Payment Request are made of and can be either a debit or a credit. One or all Payouts can be voided individually as part of the larger Payment or Payment Request.
Retry a credit/debit Payout
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/payouts/C.2/retry \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payouts/C.2/retry")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payouts/C.2/retry",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/payouts/C.2/retry", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/payouts/C.2/retry")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/payouts/C.2/retry');
$request->setRequestMethod('POST');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payouts/C.2/retry"
req, _ := http.NewRequest("POST", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /payouts/{ref}/retry
Split will prefail a debit and its associated credit transaction before ever sending it to the bank if we detect a high probability of insufficient funds.
This endpoint allows you to retry the payout without having to recreate the parent request. e.g A Payment or Payment Request.
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
ref | path | string | true | Payout debit or credit reference |
Example responses
200 Response
{
"data": {
"ref": "C.2",
"parent_ref": "PR.039a",
"type": "credit",
"category": "payout",
"created_at": "2016-12-05T23:15:00Z",
"matures_at": "2016-12-06T23:15:00Z",
"cleared_at": null,
"bank_ref": null,
"status": "maturing",
"status_changed_at": "2016-12-05T23:15:00Z",
"party_contact_id": "33c6e31d3-1dc1-448b-9512-0320bc44fdcf",
"party_name": "Price and Sons",
"party_nickname": "price-and-sons-2",
"party_bank_ref": null,
"description": "Money for jam",
"amount": 1
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | RetryPayoutResponse |
Void a Payout
Code samples
curl --request DELETE \
--url https://api.sandbox.split.cash/payouts/D.1 \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"details":"Incorrect recipient"}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/payouts/D.1")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Delete.new(url)
request["content-type"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"details\":\"Incorrect recipient\"}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "DELETE",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/payouts/D.1",
"headers": {
"content-type": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ details: 'Incorrect recipient' }));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"details\":\"Incorrect recipient\"}"
headers = {
'content-type': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("DELETE", "/payouts/D.1", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.delete("https://api.sandbox.split.cash/payouts/D.1")
.header("content-type", "application/json")
.header("authorization", "Bearer {access-token}")
.body("{\"details\":\"Incorrect recipient\"}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"details":"Incorrect recipient"}');
$request->setRequestUrl('https://api.sandbox.split.cash/payouts/D.1');
$request->setRequestMethod('DELETE');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/payouts/D.1"
payload := strings.NewReader("{\"details\":\"Incorrect recipient\"}")
req, _ := http.NewRequest("DELETE", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
DELETE /payouts/{ref}
You can void any Payout debit from your account that has not yet matured.
Body parameter
{
"details": "Incorrect recipient"
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
ref | path | string | true | Payout debit reference |
body | body | VoidAPayoutRequest | false | No description |
» details | body | string | false | Optional details about why the payout has been voided |
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
204 | No Content | No Content | None |
Refunds
Refunds can be issued for any successfully cleared Payout (credit) transactions.
Refunds are broken up by direction:
- Incoming: An incoming Refund (you are the recipient of the refund)
- Outgoing: An outgoing Refund (you are the issuer of the refund)
There are two response fields that differ depending on the direction:
Field | Description |
---|---|
debit_ref |
Only visible to the Refund issuer (outgoing Refunds). This reference corresponds to the newly created debit to process the Refund. |
credit_ref |
Only visible to the Refund recipient (incoming Refunds). This reference corresponds to the newly created credit to process the Refund. |
Issue a Refund
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/credits/string/refunds \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"amount":500,"reason":"Because reason","your_bank_account_id":"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/credits/string/refunds")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"amount\":500,\"reason\":\"Because reason\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/credits/string/refunds",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
amount: 500,
reason: 'Because reason',
your_bank_account_id: '9c70871d-8e36-4c3e-8a9c-c0ee20e7c679',
metadata: { custom_key: 'Custom string', another_custom_key: 'Maybe a URL' }
}));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"amount\":500,\"reason\":\"Because reason\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/credits/string/refunds", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/credits/string/refunds")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.body("{\"amount\":500,\"reason\":\"Because reason\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"amount":500,"reason":"Because reason","your_bank_account_id":"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679","metadata":{"custom_key":"Custom string","another_custom_key":"Maybe a URL"}}');
$request->setRequestUrl('https://api.sandbox.split.cash/credits/string/refunds');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/credits/string/refunds"
payload := strings.NewReader("{\"amount\":500,\"reason\":\"Because reason\",\"your_bank_account_id\":\"9c70871d-8e36-4c3e-8a9c-c0ee20e7c679\",\"metadata\":{\"custom_key\":\"Custom string\",\"another_custom_key\":\"Maybe a URL\"}}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /credits/{credit_ref}/refunds
Certain rules apply to the issuance of a refund:
- Must be applied against a successfully cleared payout (credit)
- The refund amount must not exceed the original amount of the credit
Body parameter
{
"amount": 500,
"reason": "Because reason",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
credit_ref | path | string | true | No description |
body | body | IssueARefundRequest | true | No description |
» amount | body | integer | true | Amount in cents refund (Min: 1 - Max: 99999999999) |
» reason | body | string | false | Reason for the refund. First 9 characters are visible to both parties. |
» your_bank_account_id | body | string(uuid) | false | Specify where we should take the funds for this transaction. If omitted, your primary bank account will be used. |
» metadata | body | Metadata | false | Use for your custom data and certain Split customisations. |
Example responses
200 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"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | Created | IssueARefundResponse |
List incoming Refunds
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/refunds/incoming \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/refunds/incoming")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/refunds/incoming",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/refunds/incoming", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/refunds/incoming")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/refunds/incoming');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/refunds/incoming"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /refunds/incoming
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
Example responses
200 Response
{
"data": [
{
"ref": "PRF.2",
"for_ref": "D.5",
"credit_ref": "C.q",
"your_bank_account_id": "049528f7-6698-40a6-8221-52ec406e5424",
"created_at": "2017-05-09T04:45:26Z",
"amount": 5,
"reason": "Because reason",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListIncomingRefundsResponse |
List outgoing Refunds
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/refunds/outgoing \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/refunds/outgoing")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/refunds/outgoing",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/refunds/outgoing", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/refunds/outgoing")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/refunds/outgoing');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/refunds/outgoing"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /refunds/outgoing
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
Example responses
200 Response
{
"data": [
{
"ref": "PRF.2",
"for_ref": "C.5",
"debit_ref": "D.5a",
"your_bank_account_id": "9c70871d-8e36-4c3e-8a9c-c0ee20e7c679",
"created_at": "2017-05-09T04:45:26Z",
"amount": 5,
"reason": "Because reason",
"metadata": {
"custom_key": "Custom string",
"another_custom_key": "Maybe a URL"
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListOutgoingRefundsResponse |
Retrieve a Refund
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/refunds/PRF.1 \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/refunds/PRF.1")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/refunds/PRF.1",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/refunds/PRF.1", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/refunds/PRF.1")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/refunds/PRF.1');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/refunds/PRF.1"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /refunds/{refund_ref}
Get a single Refund by its reference
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
refund_ref | path | string | true | Single value, exact match |
Example responses
200 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"
}
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | RetrieveARefundResponse |
Sandbox Only
Special testing endpoints that only exist in the sandbox environment.
Simulate incoming PayID payment
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/simulate/incoming_payid_payment \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"payid_email":"incoming@split.cash","amount":10000}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/simulate/incoming_payid_payment")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"payid_email\":\"incoming@split.cash\",\"amount\":10000}"
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "POST",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/simulate/incoming_payid_payment",
"headers": {
"content-type": "application/json",
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({ payid_email: 'incoming@split.cash', amount: 10000 }));
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
payload = "{\"payid_email\":\"incoming@split.cash\",\"amount\":10000}"
headers = {
'content-type': "application/json",
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("POST", "/simulate/incoming_payid_payment", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.sandbox.split.cash/simulate/incoming_payid_payment")
.header("content-type", "application/json")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.body("{\"payid_email\":\"incoming@split.cash\",\"amount\":10000}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$body = new http\Message\Body;
$body->append('{"payid_email":"incoming@split.cash","amount":10000}');
$request->setRequestUrl('https://api.sandbox.split.cash/simulate/incoming_payid_payment');
$request->setRequestMethod('POST');
$request->setBody($body);
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json',
'content-type' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"strings"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/simulate/incoming_payid_payment"
payload := strings.NewReader("{\"payid_email\":\"incoming@split.cash\",\"amount\":10000}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("content-type", "application/json")
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
POST /simulate/incoming_payid_payment
Simulate receiving a real time PayID payment from one of your Receivable Contacts.
Body parameter
{
"payid_email": "incoming@split.cash",
"amount": 10000
}
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
body | body | SimulateIncomingPayIDPaymentRequest | true | No description |
» payid_email | body | string | true | Receivable Contact PayID email (Min: 6 - Max: 256) |
» amount | body | integer | true | Amount in cents (Min: 1 - Max: 99999999999) |
Example responses
201 Response
{
"data": {
"id": "92c75281-5b60-489a-bd8a-e513ba9277c5",
"payid_email": "incoming@split.cash",
"amount": 10000
}
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
201 | Created | OK | SimulateIncomingPayIDPaymentResponse |
Transactions
By default, the transactions endpoint provides a detailed look at all past, current and future debits & credits related to your account.
Lifecycle
A transaction (debit or credit) can have the following statuses:
Status | Description |
---|---|
maturing |
The maturation date has not yet been reached |
matured |
The maturation date has been reached and the transaction is eligible for processing. |
preprocessing |
The transaction is undergoing pre-checks before being sent to the bank. |
processing |
The transaction has been submitted to the bank. |
clearing |
Waiting for confirmation from the bank that the transaction has succeeded. |
cleared |
The transaction is complete. |
rejected |
The bank has rejected the transaction due to incorrect bank account details. |
returned |
The transaction did not successfully clear. |
voided |
The transaction has been cancelled and is no longer eligible for processing. |
pending_verification |
The bank account must be verified before the transaction can proceed. |
paused |
The transaction has temporary been paused by Split pending internal review. |
prefailed |
The transaction was never submitted to the bank because we detected that there were insufficient funds. The transaction can be retried. |
Failure reasons
Example response
{
"data": [
{
"ref": "D.3",
"parent_ref": null,
"type": "debit",
"category": "payout_refund",
"created_at": "2016-12-07T23:15:00Z",
"matures_at": "2016-12-10T23:15:00Z",
"cleared_at": null,
"bank_ref": null,
"status": "returned",
"status_changed_at": "2016-12-08T23:15:00Z",
"failure_reason": "user_voided",
"failure_details": "Wrong amount - approved by Stacey"
"party_contact_id": "26297f44-c5e1-40a1-9864-3e0b0754c32a",
"party_name": "Sanford-Rees",
"party_nickname": "sanford-rees-8",
"description": null,
"amount": 1,
"bank_account_id": "56df206a-aaff-471a-b075-11882bc8906a"
}
]
}
The rejected
, returned
, voided
& prefailed
statuses are always accompanied by a failure_reason
:
Reason | Description |
---|---|
refer_to_customer |
Usually due to insufficient funds |
insufficient_funds |
Insufficient funds |
payment_stopped |
The payment was stopped at the bank. Can be due to a customer requesting a stop payment with their financial institution. |
invalid_bsb_number |
BSB number is invalid |
account_closed |
The bank account is closed |
customer_deceased |
Customer is deceased |
incorrect_account_number |
Account number is incorrect |
refer_to_split |
Failed due to reasons not listed here. Please contact us. |
user_voided |
Voided by payout initiator |
admin_voided |
Voided by Split Payments admin |
List all transactions
Code samples
curl --request GET \
--url https://api.sandbox.split.cash/transactions \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/transactions")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Get.new(url)
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
response = http.request(request)
puts response.read_body
var http = require("https");
var options = {
"method": "GET",
"hostname": "api.sandbox.split.cash",
"port": null,
"path": "/transactions",
"headers": {
"accept": "application/json",
"authorization": "Bearer {access-token}"
}
};
var req = http.request(options, function (res) {
var chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.end();
import http.client
conn = http.client.HTTPSConnection("api.sandbox.split.cash")
headers = {
'accept': "application/json",
'authorization': "Bearer {access-token}"
}
conn.request("GET", "/transactions", headers=headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.get("https://api.sandbox.split.cash/transactions")
.header("accept", "application/json")
.header("authorization", "Bearer {access-token}")
.asString();
<?php
$client = new http\Client;
$request = new http\Client\Request;
$request->setRequestUrl('https://api.sandbox.split.cash/transactions');
$request->setRequestMethod('GET');
$request->setHeaders(array(
'authorization' => 'Bearer {access-token}',
'accept' => 'application/json'
));
$client->enqueue($request)->send();
$response = $client->getResponse();
echo $response->getBody();
package main
import (
"fmt"
"net/http"
"io/ioutil"
)
func main() {
url := "https://api.sandbox.split.cash/transactions"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("accept", "application/json")
req.Header.Add("authorization", "Bearer {access-token}")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := ioutil.ReadAll(res.Body)
fmt.Println(res)
fmt.Println(string(body))
}
GET /transactions
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
page | query | string | false | Page of results to return, single value, exact match |
per_page | query | string | false | Number of results per page, single value, exact match |
ref (debit or credit) | query | string | false | Single value, exact match |
parent_ref | query | string | false | Single value, exact match |
bank_ref | query | string | false | Single value, exact match |
both_parties | query | boolean | false | Single value, exact match. Will also list debits & credits applied to the other party |
status | query | array[string] | false | Multiple values, exact match |
category | query | array[string] | false | Multiple values, exact match |
type | query | array[string] | false | Multiple values, exact match |
other_party | query | string | false | Single value, string search. Cannot be combine with both_parties query string |
other_party_bank_ref | query | string | false | Single value, exact match |
party_contact_id | query | string | false | Single value, exact match. Cannot be combine with both_parties query string |
description | query | string | false | Single value, string search |
min_amount | query | integer | false | Cents, single value, exact match |
max_amount | query | integer | false | Cents, single value, exact match |
min_created_date | query | string(date-time) | false | Date/time UTC ISO 8601 format, single value, exact match |
max_created_date | query | string(date-time) | false | Date/time UTC ISO 8601 format, single value, exact match |
min_matured_date | query | string(date-time) | false | Date/time UTC ISO 8601 format, single value, exact match |
max_matured_date | query | string(date-time) | false | Date/time UTC ISO 8601 format, single value, exact match |
min_cleared_date | query | string(date-time) | false | Date/time UTC ISO 8601 format, single value, exact match |
max_cleared_date | query | string(date-time) | false | Date/time UTC ISO 8601 format, single value, exact match |
min_status_changed_date | query | string(date-time) | false | Date/time UTC ISO 8601 format, single value, exact match |
max_status_changed_date | query | string(date-time) | false | Date/time UTC ISO 8601 format, single value, exact match |
Enumerated Values
Parameter | Value |
---|---|
status | maturing |
status | matured |
status | preprocessing |
status | processing |
status | clearing |
status | cleared |
status | rejected |
status | returned |
status | voided |
status | pending_verification |
status | paused |
category | payout |
category | payout_refund |
category | invoice |
type | debit |
type | credit |
Example responses
200 Response
{
"data": [
{
"ref": "D.3",
"parent_ref": null,
"type": "debit",
"category": "payout_refund",
"created_at": "2016-12-07T23:15:00Z",
"matures_at": "2016-12-10T23:15:00Z",
"cleared_at": "2016-12-10T23:15:00Z",
"bank_ref": "DT.9a",
"status": "cleared",
"status_changed_at": "2016-12-10T23:15:00Z",
"party_contact_id": "31354923-b1e9-4d65-b03c-415ead89cbf3",
"party_name": "Sanford-Rees",
"party_nickname": null,
"party_bank_ref": "CT.11",
"description": null,
"amount": 20000,
"bank_account_id": "56df206a-aaff-471a-b075-11882bc8906a"
},
{
"ref": "D.2",
"parent_ref": "PB.2",
"type": "debit",
"category": "payout",
"created_at": "2016-12-06T23:15:00Z",
"matures_at": "2016-12-09T23:15:00Z",
"cleared_at": null,
"bank_ref": null,
"status": "maturing",
"status_changed_at": "2016-12-06T23:15:00Z",
"party_contact_id": "3c6e31d3-1dc1-448b-9512-0320bc44fdcf",
"party_name": "Gutmann-Schmidt",
"party_nickname": null,
"party_bank_ref": null,
"description": "Batteries for hire",
"amount": 2949299,
"bank_account_id": "56df206a-aaff-471a-b075-11882bc8906a"
},
{
"ref": "C.2",
"parent_ref": "PB.s0z",
"type": "credit",
"category": "payout",
"created_at": "2016-12-05T23:15:00Z",
"matures_at": "2016-12-06T23:15:00Z",
"cleared_at": "2016-12-09T23:15:00Z",
"bank_ref": "CT.1",
"status": "cleared",
"status_changed_at": "2016-12-09T23:15:00Z",
"party_contact_id": "33c6e31d3-1dc1-448b-9512-0320bc44fdcf",
"party_name": "Price and Sons",
"party_nickname": "price-and-sons-2",
"party_bank_ref": null,
"description": "Online purchase",
"amount": 19999,
"bank_account_id": "c2e329ae-606f-4311-a9ab-a751baa1915c",
"metadata": {
"customer_id": "xur4492",
"product_ref": "TSXL392110x"
}
}
]
}
Responses
Status | Meaning | Description | Schema |
---|---|---|---|
200 | OK | OK | ListAllTransactionsResponse |
Unassigned Agreements
An agreement with no preset authoriser that can only be accepted once and must be accepted within a predefined time period.
Unassigned Agreements are shared using the generated link available in the response body. You can then include it in an email, text message, embed it in an iFrame, etc...
Please refer to the Unassigned Agreement article in our knowledge base for more information.
Propose an Unassigned Agreement
Code samples
curl --request POST \
--url https://api.sandbox.split.cash/unassigned_agreements \
--header 'accept: application/json' \
--header 'authorization: Bearer {access-token}' \
--header 'content-type: application/json' \
--data '{"expiry_in_seconds":60,"single_use":false,"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"}}'
require 'uri'
require 'net/http'
url = URI("https://api.sandbox.split.cash/unassigned_agreements")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["content-type"] = 'application/json'
request["accept"] = 'application/json'
request["authorization"] = 'Bearer {access-token}'
request.body = "{\"expiry_in_seconds\":60,\"single_use\":false,\"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\"}}"
response = http.request(request)
puts response.read_body