Vesicash API V1
Search…
API DOCUMENTATION
Customizations
Transactions Management
A transaction is an record of agreement between two or more users.
Creating a new Transaction
A transaction is a record of agreement between two or more users. Each transaction record is represented by a Transaction object having several attributes.
post
https://api.vesicash.com/v1
/transactions/create
create a transaction
title (required)
This is the title for the transaction.
type (required)
This attribute is used to determine the type of transaction a user wish to create. For now, our APIs allows three main kinds of transactions which are product, milestone, broker.
Type
Description
product
For buying and selling of physical goods. This transaction type allows a user to add multiple items, description, prices, shipping costs, and photos. The seller gets the fund once the buyer confirms receipt of goods.
oneoff
For buying and selling of services where the clients get the money at once on delivery of the service. While product transaction is used to identify a transaction which involves sales of physical goods, oneoff identifies sales of services hence there's no provision for multiple items, shipping cost, etc.
milestone
For buying and selling of services where the clients get the money based on completion of milestones.
broker
For transactions that involves a third party middleman.
pool
For group contributions and group payments.
description
This is the description for the transaction. Here you can describe what the transaction is for.
parties (required)
The parties attribute is used to determine the role of each users involved in a transaction. Usually, there will always be a buyer and a seller in every transaction but in some cases, there could also be a broker - hence, we have three major roles: buyer, seller, broker.
Specific actions can be performed by specific user based on their roles, therefore, it is important to set the users to their correct role as it cannot be changed once the transaction has been created.
The buyer refers to the user that is purchasing the product or service in the transaction. They are required to fund the transaction, and accept the delivered product or service after the inspection period.
The seller is the user that is providing the product or service in the transaction. They are required to ship the delivery to the buyer, and have their funds disbursed after the buyer accepts the delivery.
The broker is a third-party user that is setting up a transaction on behalf of the other users. Brokers are responsible for creating the transaction terms, specify who the buyer is, set a broker commission, and able to set who pays this.
The charge_bearer is the user that is required to bear the transaction charge in that transaction.
For notification purposes, we added two other important roles such as the sender and the recipient .
The sender as the name implies is the person initiating the transaction.
The recipient as the name implies is the person that is expected to receive the transaction.
Other roles such as shipping_charge_bearer (the person paying the shipping fee) and shipping_charge_recipient (the person receiving the shipping fee, usually the shipping company) are also allowed specifically for product transactions.
due_date (required)
This attribute represents the date our escrow expects the delivery of a product or milestone to be made.
inspection_period (required)
This attribute represents the period of time the buyer would need to inspect the shipment made by the seller. This is usually in number of days. For example "1" representing "1 day".
currency (required)
This attribute assigns the currency to be used for the transaction. Currently, the only currencies we supported are 'NGN', 'KES', 'GHS', 'GBP, 'RWF' and 'USD'; however, we may add more currencies in the future.
The next page shows examples of the different transaction creation types.
Transaction Status
The status of a transaction informs the current state of that transaction.
Most of the time, there will be no need to use this, however, it is important to know them should the need arise. Below is a list of status codes and their meanings:
Status code
Meaning
Usage
draft
Draft
All transactions that were initiated and saved for later. These kinds of transactions can be modified and sent at a later time.
sac
Sent - Awaiting Confirmation
This is the state of any new transaction that was created and sent to the recipient.
af
Accepted - Funded
When a transaction has been paid for, the state is changed to this to reflect the payment.
anf
Accepted - Not Funded
This is the state of transaction that has been accepted but is pending payment from the buyer.
fr
Funded - Rejected
Some transactions would require that the buyer pays before the recipient/seller gets a chance to accept the terms of the transaction. If the recipient chooses to decline/reject such transaction, the status is change to this to reflect that it was funded but was rejected.
ip
In Progress
A transaction is "In Progress" when it has both been funded and accepted.
d
Delivered
This is the state of the transaction when the seller clicks "Mark as shipped" button to indicate delivery such transaction.
da
Delivered - Accepted
This is the state of a transaction when a buyer clicks the "Accept delivery" button to indicate satisfaction.
dr
Delivered Rejected
This is the state of the transaction when a buyer clicks "Reject Delivery" button to indicate dissatisfaction
cdp
Closed - Disbursement Pending
This is the state of the transaction when the escrow is ready to disburse funds.
c
Closed
This is the state of the transaction when the escrow has completely disbursed fund to the recipient.
Last modified 5mo ago
Copy link