Escrow Transactions

An escrow transaction is a financial arrangement where a third party(Vesicash), known as the escrow agent, holds and regulates payment of escrowed funds between transaction parties.

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 with several attributes.

title (required)

This is the title of the transaction.

type (required)

This attribute is used to determine the type of transaction a user wants to create. Our API allows two types; one-off and milestone transactions.

Type	Description
one-off	For transactions where the receiving party receives the total agreed amount at once after completion of the transaction requirements.
milestone	For transactions where the receiving party receives a certain amount of the escrowed fund at intervals, based on agreement, till the completion of the transaction.

currency (required)

This is the currency selected to carry out the transaction. For transactions between local clients, it is expected to be in the local currency, while transactions with clients from another country is expected to be in the USD currency.

amount (required)

This attributes assigns the total amount of money needed to complete the escrow transaction either one-off or milestone.

dispute_handler (required)

This attribute signifies who handles dispute between parties involved in the transaction. By default Vesicash manages any dispute from the transaction, the transaction can also be managed by an external party. Available options here are "vesicash" and "arbitration"

files (optional)

This attribute holds any files or documents relevant for the escrow transaction flow. It is an array of file object with name and url as object data.

files: [
    {
        name: 'file_name.pdf',
        url: 'file_uploaded_url_on_vesicash_server'
    }
]

parties (required)

The parties attribute signifies the role and permission level of each users involved in a transaction. Usually, there is a buyer and a seller in every transaction but in some cases, there could also be a broker - hence, why we have three major roles: buyer, seller and a 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 party purchasing the product or service. This party is obligated to fund the escrow transaction, and accept the delivered product or service after the inspection period. The seller is the user providing the product or service in the transaction. This party is obligated 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 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 assign who pays. Below is a basic party payload representation.

 [
     {
        account_id: 1721718438,
        role: "buyer", // 'seller' or 'broker'
        status: "Accepted",
        access_level: {
            can_view: true,
            can_receive: true,
            mark_as_done: true,
            approve: false
        }
    },
]

The account_id attribute above signifies the account_id of the transaction party, in a case where the transaction party does not have an account_id, an account_id would be created for the user. More clarification would be provided on escrow transaction process flow.

The role attribute can either be a "buyer", "seller" or a "broker"

The status attribute represents the level of a party involvement, when the transaction is created each parties involved would be sent an invitation to the transaction and take up the status "Created" while the party creating the escrow transaction would take up the status "Accepted". On acceptance of the invitation sent, each party status would be updated to "Accepted".

The access_level object attribute holds for main data:

• can_view: all parties should be able to view the transaction

• can_receive: all parties aside the buyer can receive transaction fund

• mark_as_done: only the seller can mark as done

• approve: only the buyer can approve a transaction

milestones (required)

The milestones attribute represents the breakdown of the transaction. For a one-off transaction, the milestones attribute should contain only one milestone object while a milestone transaction type should contain multiple milestone object. Below is a basic milestones payload

[
     {
        "title": "Milestone 1",
        "status": "Sent - Awaiting Confirmation",
        "amount": 4000,
        "inspection_period": "2",
        "due_date": "2023-04-08",
        "recipients": [
            {
                "account_id": 9753325191,
                "amount": 2000
            },
            {
                "account_id": 1721718438,
                "amount": 2000
            }
        ]
    }
]

The amount attribute above represent the amount to be disbursed per milestone.

The due_date attribute represents the date for the delivery of a product or service per milestone.

The inspection_period attribute represents the period of time the buyer would need to inspect the shipment or service by the seller. This is usually calculated in days. For example "1" representing "1 day".

The recipients payload contains an object of the parties receiving the fund at the end of a milestone and amount.

Transaction Status

The status of a transaction informs the current state of that transaction. Generally, you don't need to carry out any action on this, however, it is important to be aware of how it works. Below is a list of status codes and their meanings:

Status code	Meaning	Usage
draft	Draft	All transactions initiated and saved for later. These transactions can be modified and sent later.
sac	Sent - Awaiting Confirmation	This is the status of any new transaction created and sent to the recipient.
af	Accepted - Funded	When a transaction has been funded, the status is changed to this to reflect the payment.
anf	Accepted - Not Funded	This is the status of a transaction that has been accepted but 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 changed to reflect 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 status of the transaction when the seller clicks "Mark as Done" button to indicate delivery of product or service.
da	Delivered - Accepted	This is the status of a transaction when a buyer clicks the "Approve" button to indicate satisfaction.
dr	Delivered Rejected	This is the status of the transaction when a buyer clicks "Reject Delivery" button to indicate dissatisfaction
c	Closed	This is the status of the transaction closed after it exceeds the due date without been paid for.
cr	Closed Refunded	This is the status of a paid transaction which closed before completion, hence the fund would be refunded to the buyer's wallet.
cd	Closed Disputed	This is the status of a transaction was closed for dispute reasons.
cdp	Closed - Disbursement Pending	This is the status of the transaction when the escrow is ready to disburse funds.
cdc	Closed - Disbursement Complete	This is the status of a transaction which has been closed and funds disbursed completely.