Transactions Management
A transaction is a record of agreement between two or more users. Each transaction record is represented by a Transaction object having several attributes.
postcreate a transaction
{"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"}}}​
This is the title for the transaction.
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. |
This is the description for the transaction. Here you can describe what the transaction is for.
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".
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.
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. |