← Home

Authentication

Customers

Payments and Disbursements

Webhooks

Release Notes

Introduction

Payments and Disbursements are offered through Vivamo after a simple few-step integration. Once integrated, both payments and disbursements can be made to an end customers compatible stored payment methods

Ensure the script is loaded onto your webpage:

<script src=”<https://js.vivamo.co/v1>" async></script>

Statuses

A payment intent is intentionally decoupled from the actual attempted processing of said payment. Therefore, one payment intent may have multiple non-successful payment statuses associated with it.

The possible statuses flow of a payment intent is as follows:

Expiration

Within Vivamo, payment Intents have an expiry of 2 hours. Attempting to setup the Vivamo SDK using an expired payment intent will result in a “Intent has expired” message appearing in the Vivamo UI. The Vivamo UI will need to be re-initialised with a new intent.

SMS Verification

In the test environment you may use any code when performing the SMS verification step and a success result will be returned.

To force an invalid (failed) verification, use the code 000000.

Payment flow

The full payment flow follows these steps:

1. Create a payment intent

The first step of the payment and disbursement flow is creating a payment intent. This generates a record that allows server-to-server authentication for the duration of the payment flow.

Creating a payment intent requires an existing customer record, along with the desired purchase amount and currency.

Full API information can be found here:

Create Payment Intent

2. Initialise the Vivamo payment form

The response will include a clientSecretKey, which is then passed into the setup of the payment form.

For example:

<script src="<https://js.vivamo.co/v1>"></script>

...

const vivamo = Vivamo();

fetch("<https://your-backend/create-payment-intent>")
	.then((response) => {
	  return response.json();
	})
	.then((paymentIntent) => {
	  vivamo.createElements(
	    "#payment-form",
	    paymentIntent.clientSecretKey
	  );
	});

You can also register a listener to be called when the payment is executed and complete. This is useful if you would like to poll for a payment result:

vivamo.on("payment-created", (data) => {
	console.log("Payment created: ", data);
})

vivamo.on("payment-completed", () => {
	window.url = "success_url";
})

Once setup, this will initialise the Vivamo form for the Customer to then complete the flow of adding or selecting a payment method, verifying (completing an SMS OTP), and submitting the payment for processing.

3. Get the payment outcome

Once the payment is submitted, a webhook will be sent to your backend containing the result of the payment.

Alternatively, you may poll for the payment result:

Get Payment Intent Status

<aside> ⚠️

Note: A payment intent may have multiple Failure outcomes, however there will only be one successful outcome. It is recommended to cater for the result of a payment to be updated in case failed attempts are retried with a successful outcome.

</aside>

Disbursement flow

The disbursement flow has a very similar look and feel to payments, with one extra step:

1. The disbursement intent is created and the disbursement enters a pending state.
2. A subsequent call is made to either proceed with the disbursement, or cancel it.

The primary case for this flow being a request → approve type process, where the customer requests the disbursement through the secure Vivamo integration followed by your platform rejecting/approving the disbursement.

1. Create a disbursement intent

Similar to the payment flow, a disbursement intent is created and passed onto the Vivamo SDK for next steps.

Create disbursement intent

2. Initialise the Vivamo payment form

Using the clientSecretKey value in the response of the intent creation, initialise the Vivamo SDK and begin the process for the customer to select a disbursement method.

For example:

<script src="<https://js.vivamo.co/v1>"></script>

...

const vivamo = Vivamo();

fetch("<https://your-backend/create-disbursement-intent>")
	.then((response) => {
	  return response.json();
	})
	.then((disbursementIntent) => {
	  vivamo.createElements(
	    "#disbursement-form",
	    disbursementIntent.clientSecretKey
	  );
	});

When the customer completes the first step of the disbursement flow, the intent will be in the status pending-validation, which occurs in the next step and the Disbursement created webhook is sent.

Additionally, the UI will emit an event:

vivamo.on("disbursement-created", (data) => {
	console.log("Disbursement created: ", data);
})

3. Approve the disbursement intent

In order for the disbursement funds to actually be sent to the customer, the final step you must perform is the approval of the disbursement. Until this point, the customer has requested funds be sent to them, and the method of which to send. After performing desired checks internally, the following approval can be given to then deliver the funds.

To get a full list of pending disbursements, you can get a list with:

Get pending validation disbursements

To then proceed (approve or decline) with the disbursement, use:

Proceed with disbursement

Once the disbursement is approved, you should await a webhook for the the final result. The timing for this may vary depending on the payment method. For instance, ACH rejections/returns can take up to 5-10 business days to return a response, more details below.

ACH Rejections

When there are failures in ACH payments (often due to mistyped, closed, or other reasons at a bank level), the necessary webhook will be sent to your backend for the resolution to be carried out.