Our Open Agreement solution allows you to generate and embed an agreement link anywhere. Once you've entered in an agreement, your future Payment Requests to that person/business will be automatically approved and processed based on the agreement terms.

You can include an Open Agreement (OA) link in a text message, invoice, email or website and be notified when it's been accepted in realtime so that you can start getting paid regularly and on your terms.

Get started

  1. Sign in to your Split account.
  2. Click on Agreements.
  3. Click on Add open agreement.
  4. Fill in your details.
  5. Copy, share your OA link.

Customise your Open Agreement page

The resulting OA page can be customised to suit your needs. For example, if you already know the name (business or personal) and email of the agreement authoriser, you can pre-fill these fields for the other party and further simplify the process.

Here's a current list of customisation options:

  • name : Prefill the name or business name of the entity that will be approving the payment request
  • email : Prefill the email of the entity that will be approving the payment request
  • success_url : On successful payment, redirect to this URL (leave blank to let Split handle it)
  • faillure_url : On failure, redirect to this URL (leave blank to let Split handle it)
  • cancel_url : On cancel, redirect to this URL (leave blank to let Split handle it)
  • header_title 
  • iav_tab : Instant bank verification title
  • other_institution_label 
  • submit_text : The submit button text
  • submitting_text : The text as shown on the submit button once clicked
  • hide_bank_icons : Only a dropdown of banks will be shown

Developers

In addition to the above options, we support embedding an unbranded & iframe friendly version of the OA page. Simply append the query string parameter to the URL:

  • embed=1  : Removes the frame styling for seamless iFrame usage
  • whitelabel=1  : Removes all Split branding

Example link structure using both options:
https://go.split.cash/open_agreements/7778f2f03-416d-4ed5-8ac2-27eeef757c73/agreements/invitation?embed=1&whitelabel=1 

Notes

  • iFrame integration is supported 👍
  • When an OA is accepted, an Agreement is created and accepted. The actual OA does not change as it is just as a template.
  • The OA URL can be generated within Split via the UI or API. However, if you're using the API to generate the OA URL, the customisation options must be manually appended to the URL.
  • When defining a custom success URL, Split will append an agreement_ref=xxx  as a query string parameter. You can then use our API to double check the validity of the resulting Agreement reference or enable web hooks to receive a notification of the successful acceptance of the OA and the newly created Agreement. This is a good way to ensure there's been no tampering.
  • When defining a custom failure URL, Split will append an errors key with the errors as a query string parameter: http://www.example.com/failed?errors=contact.name_too_long 
  • You can include query string parameters in any custom URL. For example, you may want to include your internal customer_id  to the URL so that you can easily relate the agreement result to your customer: http://www.example.com/success?customer_id=1234

Javascript events

You can optionally handle the success and/or failure events via dispatched event from the postMessage API:

  • handle_success=1  : When appended to the OA URL and the customer successfully accepts the agreement, the success event will be broadcast via the postMessage web API.
  • handle_failure=1  : When appended to the OA URL and the customer accepts the agreement but fails for some reason, the failure event will be broadcast via the postMessage web API.

For both above events, no redirect or render will happen. It's up to you to redirect the user or render a new view.

Example boilerplate:

function receive(event) {
  // Check to make sure it's coming from us
  if (event.origin !== "https://go-sandbox.split.cash") {
    return;
  }

  // See how the payload is formed, particularly the data key
  console.log(event)
  // Do stuff like redirect.
  window.location.replace("https://example.com");
}

// Listen for message from the iFrame
window.addEventListener('message', receive, false)

Dynamic HTML classes

A form-invalid class is added to the primary submission button. This class is automatically removed when all the required form fields are populated. Combined with your custom CSS, you can adjust the button behaviour to achieve your desired user experience (e.g Only show the submission button when all fields are populated).

Did this answer your question?