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
create a transaction

https://api.vesicash.com/v1/transactions/create
These are the parameters needed to make a transaction
Request
Response
Request
Headers
Accept
required
string
application/json
V-PRIVATE-KEY
required
string
your vesicash private key
Form Data Parameters
title
optional
string
title of the transaction
type
required
string
the type of transaction. Possible values are: 'product', 'oneoff', 'milestone', 'broker', 'pool'.
description
optional
string
description of the transaction
parties
required
object
An object of the people involved in the transaction. Barest minimum is the "sender" and "recipient". E.g { "sender": account_id, "recipient": account_id, "buyer": account_id, "seller": account_id, "charge_bearer": account_id } Note: The account_id for each party can be gotten by sending the user's email and phone to the signup endpoint.
inspection_period
required
integer
number of days you need to inspect the product or service delivery. Example: "inspection_period": 1
due_date
required
string
expected delivery date for that transaction in MM/DD/YYYY format. Example: "due_date": "2/12/2020".
currency
required
string
Currency of the transaction. Possible values are: 'NGN', 'USD', 'RWF', 'GHS', 'KES'
Response
200: OK
{
"status": "ok",
"code": 200,
"message": "Created",
"data": {
"transaction": {
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"parties_id": "fYDQEc8jUVvrpc9wPQ8Y",
"title": "Test transaction",
"type": "product",
"description": "eBook",
"status": "Draft",
"inspection_period": 1582542740,
"due_date": 1581465600,
"shipping_fee": 500,
"currency": "NGN",
"amount": 40000,
"updated_at": "2020-02-19 11:12:20",
"created_at": "2020-02-19 11:12:20",
"id": 63,
"is_paylinked": true,
"products": [
{
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"product_transaction_id": "HxCWy1AwLZJfDlM3MhDj",
"title": "1 test",
"photo": "",
"amount": 20000,
"quantity": 1,
"updated_at": "2020-02-19 11:12:20",
"created_at": "2020-02-19 11:12:20",
"id": 75
},
{
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"product_transaction_id": "HxCWy1AwLZJfDlM3MhDj",
"title": "1 test",
"photo": "",
"amount": 20000,
"quantity": 1,
"updated_at": "2020-02-19 11:12:20",
"created_at": "2020-02-19 11:12:20",
"id": 76
}
],
"milestones": [],
"broker": [],
"parties": [
{
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"transaction_parties_id": "fYDQEc8jUVvrpc9wPQ8Y",
"account_id": 4865544336,
"role": "buyer",
"created_at": "2020-02-19T11:12:20.364832Z",
"updated_at": "2020-02-19T11:12:20.364846Z"
},
{
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"transaction_parties_id": "1jxr0EtBOHo5v8g11PIk",
"account_id": 4865544336,
"role": "seller",
"created_at": "2020-02-19T11:12:20.364871Z",
"updated_at": "2020-02-19T11:12:20.364876Z"
},
{
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"transaction_parties_id": "RlOMVHBGRrtLFpgi2wt7",
"account_id": 4865544336,
"role": "sender",
"created_at": "2020-02-19T11:12:20.364884Z",
"updated_at": "2020-02-19T11:12:20.364902Z"
},
{
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"transaction_parties_id": "MfjIOmb7MnyhbZHdcnHO",
"account_id": 4865544336,
"role": "recipient",
"created_at": "2020-02-19T11:12:20.364910Z",
"updated_at": "2020-02-19T11:12:20.364914Z"
},
{
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"transaction_parties_id": "Bt5RJF7jcycDqKHQzNVM",
"account_id": 4865544336,
"role": "charge_bearer",
"created_at": "2020-02-19T11:12:20.364924Z",
"updated_at": "2020-02-19T11:12:20.364928Z"
}
],
"files": [
{
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"account_id": 4865544336,
"file_url": "https:\/\/vesicash.ams3.digitaloceanspaces.com\/document\/7df1c685367bb8c906473b3f7d15f0fc8c3f1642.pdf",
"updated_at": "2020-02-19 11:12:20",
"created_at": "2020-02-19 11:12:20",
"id": 59
},
{
"transaction_id": "I79gmJ7NgE1Lx6nq8VQC",
"account_id": 4865544336,
"file_url": "https:\/\/vesicash.ams3.digitaloceanspaces.com\/document\/7df1c685367bb8c906473b3f7d15f0fc8c3f1642.pdf",
"updated_at": "2020-02-19 11:12:20",
"created_at": "2020-02-19 11:12:20",
"id": 60
}
],
"inspection_period_formatted": "2020-02-24 11:12:20",
"due_date_formatted": "2020-02-12 00:00:00"
}
}
}
‚Äč

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 "2 days".

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 times, there will be no need to use this, however, it is important to know them should the need arise. Below are a list of status codes and their meanings:

Status code

Meaning

Usage

draft

Draft

All transactions that were initiated and saved for later. This kinds of transaction 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.