Transaction Management

Creating a Transaction

Creating transactions with the Vesicash API is straight forward. Three kinds of transactions are allowed on the Vesicash API.

  • Product Transaction: For buying and selling of physical goods. This transaction type allows a user to add multiple items, their description, prices, shipping costs, and photos. The inspection period for this is 24 hours by default.

post
Create a Product Transaction

https://api.vesicash.com/transactions/products
Create a product transaction
Request
Response
Headers
authorization
required
string
Bearer <access_token>
Form Data Parameters
sender_firstname
required
string
Sender’s first name
sender_lastname
required
string
Sender’s last name
sender_email
required
string
Sender’s last email address
sender_phone
required
string
Sender’s phone number
recipient_firstname
required
string
Recipient’s first name
recipient_lastname
required
string
Recipient’s last name
recipient_email
required
string
Recipient’s last email address
recipient_phone
required
number
Recipient’s phone number
items[0][name]
required
string
First item name
items[0][description]
required
string
First Item description
items[0][price]
required
number
The price for the item
items[0][quantity]
required
integer
The quantity of the item
items[0][shipping_cost]
optional
number
Shipping cost of the item
items[0][photo]
optional
object
Photo of the item
payer
required
string
Who’s paying for the transaction. Possible values: 'sender' and 'recipient'.
charge_bearer
optional
string
Who bears Vesicash’s charge for the transaction. Possible values: 'sender' and 'recipient'. If not supplied, the payer bears the charge.
currency
required
string
The currency of the transaction. For now, only NG is supported
201: Created
{
"data": {
"id": 13,
"uuid": "1341ce79-dee6-46c1-b69f-26d2c1ceaea6",
"type": "one-off",
"sender": {
"id": 16,
"uuid": "f1041565-4b86-4af7-b792-ef7efe6279bf",
"firstname": "John",
"lastname": "Mark",
"phone": "07012345667",
"email": "johnmark@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-04-05 11:24:42",
"updated_at": "2019-04-05 11:24:42"
},
"recipient": {
"id": 4,
"uuid": "cad8580a-c6e3-44e4-83ca-25db675afbc1",
"firstname": "James",
"lastname": "Foss",
"phone": "07032047179",
"email": "jamesfoss@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-03-28 13:23:37",
"updated_at": "2019-03-28 13:23:37"
},
"invoice_no": "566210",
"amount": 5000,
"transaction_charge": 225,
"currency": "NGN",
"created_at": "2019-04-05 13:00:11",
"updated_at": "2019-04-05 13:00:11",
"items": [
{
"id": 3,
"invoice_id": 13,
"name": "Gucci Snake",
"description": "Gucci snake",
"shipping_cost": "0.00",
"price": "5000.00",
"quantity": 1,
"photo_url": "",
"created_at": "2019-04-05 13:00:11",
"updated_at": "2019-04-05 13:00:11"
}
]
}
}

Note: Creating a product transaction requires an array of product, hence you must specify an array of items while using this endpoint.

  • Service Transactions: For buying and selling of services where the clients get the money one-time.

post
Create a Service Transaction

https://api.vesicash.com/transactions/services
Create a service transaction
Request
Response
Headers
authorization
required
string
Bearer <access_token>
Form Data Parameters
sender_firstname
required
string
Sender’s first name
sender_lastname
required
string
Sender’s last name
sender_email
required
string
Sender’s last email address
sender_phone
required
number
Sender’s phone number
recipient_firstname
required
string
Recipient’s first name
recipient_lastname
required
string
Recipient’s last name
recipient_email
required
string
Recipient’s last email address
recipient_phone
required
number
Recipient’s phone number
task
required
string
The name of the task or service to be rendered
description
required
string
A description of the Service
price
required
number
Amount for the service
inspection_period
required
integer
The number of days to inspect the service rendered
document
optional
object
Documents containing more information or agreement regarding the service to be rendered
payer
required
string
Who’s paying for the transaction. Possible values: 'sender' and 'recipient'.
charge_bearer
optional
string
Who bears the Vesicash’s charge for the transaction. Possible values: 'sender' and 'recipient'. If not supplied, the payer bears the charge.
currency
required
string
The currency of the transaction. For now, only NGN is supported.
201: Created
{
"data": {
"id": 9,
"uuid": "7c6dc786-e4ef-4ab7-8758-05dfbb39c4e3",
"type": "service",
"sender": {
"id": 16,
"uuid": "f1041565-4b86-4af7-b792-ef7efe6279bf",
"firstname": "John",
"lastname": "Mark",
"phone": "07012345667",
"email": "johnmark@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-04-05 11:24:42",
"updated_at": "2019-04-05 11:24:42"
},
"recipient": {
"id": 4,
"uuid": "cad8580a-c6e3-44e4-83ca-25db675afbc1",
"firstname": "James",
"lastname": "Foss",
"phone": "07032047179",
"email": "jamesfoss@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-03-28 13:23:37",
"updated_at": "2019-03-28 13:23:37"
},
"invoice_no": "379394",
"amount": 5000,
"transaction_charge": 225,
"currency": "NGN",
"created_at": "2019-04-05 11:52:41",
"updated_at": "2019-04-05 11:52:41",
"service": {
"id": 6,
"invoice_id": 9,
"task": "Logo design",
"description": "new logo design",
"price": "5000.00",
"inspection_period": 3,
"document": "",
"created_at": "2019-04-05 11:52:41",
"updated_at": "2019-04-05 11:52:41"
},
}
}
  • Milestone Transactions: For buying and selling of services where the clients get the money based on completion milestones.

post
Create a Milestone Transaction

https://api.vesicash.com/transactions/milestones
Create a milestone transaction
Request
Response
Headers
authorization
required
string
Bearer <access_token>
Form Data Parameters
sender_firstname
required
string
Sender’s first name
sender_lastname
required
string
Sender’s last name
sender_email
required
string
Sender’s email address
sender_phone
required
string
Sender’s phone number
recipient_firstname
optional
string
Recipient's first name
recipient_lastname
required
string
Recipient’s last name
recipient_phone
required
string
Recipient’s phone number
recipient_email
required
string
Recipient’s last email address
milestones[0][task]
required
string
The milestone task
milestones[0][description]
required
string
The milestone description
milestones[0][price]
required
number
The price for the item
milestones[0][due_date]
required
string
The due date for the milestone
milestones[0][inpsection_period]
required
integer
The number of days to inspect the milestone.
payer
required
string
Who’s paying for the transaction. Possible values: 'sender' and 'recipient'.
charge_bearer
optional
string
Who bears the Vesicash’s charge for the transaction. Possible values: sender and recipient
currency
required
string
The currency of the transaction. For now, only NGN is supported.
201: Created
{
"data": {
"id": 14,
"uuid": "13d6f482-2507-4765-9637-7de541478c61",
"type": "milestone",
"sender": {
"id": 16,
"uuid": "f1041565-4b86-4af7-b792-ef7efe6279bf",
"firstname": "John",
"lastname": "Mark",
"phone": "07012345667",
"email": "johnmark@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-04-05 11:24:42",
"updated_at": "2019-04-05 11:24:42"
},
"recipient": {
"id": 4,
"uuid": "cad8580a-c6e3-44e4-83ca-25db675afbc1",
"firstname": "James",
"lastname": "Foss",
"phone": "07032047179",
"email": "jamesfoss@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-03-28 13:23:37",
"updated_at": "2019-03-28 13:23:37"
},
"invoice_no": "896530",
"amount": "5000.00",
"status": "not paid",
"currency": "NGN",
"created_at": "2019-04-05 13:28:03",
"updated_at": "2019-04-05 13:28:03",
"milestones": [
{
"id": 4,
"invoice_id": 14,
"name": "Banner design",
"description": "Banner design for our Instagram page",
"price": "5000.00",
"inspection_period": 2,
"due_date": "2019-04-05 00:00:00",
"status": "pending",
"created_at": "2019-04-05 13:28:03",
"updated_at": "2019-04-05 13:28:03"
}
]
}
}

Transaction Actions

At different phases of a transaction, there exists five (5) main actions that can be carried out on that transaction.

  • Agreement Phase: When a recipient receives a transaction notification, he/she is expected to carryout one of these actions on that transaction.

    • Accept Transaction: To signify that a recipient she has seen the terms of the transaction and accepts them. Only when a transaction has been accepted can it be paid for.

    • Review Transaction: To signify that a recipient has seen the terms of the transaction and does not quite agree with them. At this stage, the recipient is expected to leave a comment asking the sender to make necessary adjustments to the transaction.

    The sender is further expected to make necessary adjustments and resend the transaction. The agreement phase ends only when the recipient has accepted the transaction so that the paying party can proceed to make payment.

  • Fulfillment Phase: When a transaction has been paid for, both parties are expected to carryout one of these actions after they have fulfilled their part of the transaction.

    • Mark transaction as delivered: To signify that a seller has delivered the goods/service that was paid for.

    • Mark transaction as satisfied: To signify that a buyer has received the good/service he/she paid for and is satisfied. Once a transaction has been marked as Satisfied, the buyer can no longer open a dispute on such transaction.

    • Open a dispute: To signify that the buyer is not satisfied with the good/service he/she paid for.

    In-depth explanation of the specific endpoint to integrate these actions are described below:

Accepting a Transaction

Once a transaction has been created, the next step is for the other party to accept the transaction so it can be paid for.

post
Accepting a transaction

https://api.vesicash.com/transactions/{uuid}/accept
Accept a transaction
Request
Response
Path Parameters
uuid
required
string
The UUID of the transaction to be accepted
Headers
authorization
required
string
Bearer <access_token>
Form Data Parameters
user_id
required
string
The ID of the recipient of the transaction
200: OK
{
"data": {
"id": 9,
"uuid": "7c6dc786-e4ef-4ab7-8758-05dfbb39c4e3",
"type": "service",
"sender": {
"id": 16,
"uuid": "f1041565-4b86-4af7-b792-ef7efe6279bf",
"firstname": "John",
"lastname": "Mark",
"phone": "07012345667",
"email": "johnmark@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-04-05 11:24:42",
"updated_at": "2019-04-05 11:24:42"
},
"recipient": {
"id": 4,
"uuid": "cad8580a-c6e3-44e4-83ca-25db675afbc1",
"firstname": "James",
"lastname": "Foss",
"phone": "07032047179",
"email": "jamesfoss@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-03-28 13:23:37",
"updated_at": "2019-03-28 13:23:37"
},
"invoice_no": "379394",
"amount": 5000,
"sender_confirmed": false,
"recipient_confirmed": false,
"is_accepted": true,
"status": "not paid",
"currency": "NGN",
"created_at": "2019-04-05 11:52:41",
"updated_at": "2019-04-05 11:52:41",
"service": {
"id": 6,
"invoice_id": 9,
"task": "Logo design",
"description": "new logo design",
"price": "5000.00",
"inspection_period": 3,
"document": "",
"created_at": "2019-04-05 11:52:41",
"updated_at": "2019-04-05 11:52:41"
}
}
}

Reviewing a Transaction

When a recipient refuses to accept a transaction for whatever reasons, he/she is expected to leave a comment asking the sender to make necessary adjustments to the transaction. This endpoint takes care of that:

post
Review a Transaction

https://api.vesicash.com/reviews/create
To drop a review on a transaction.
Request
Response
Path Parameters
transaction_uuid
required
string
The UUID of the transaction
Headers
authorization
required
string
Bearer <access_token>
Form Data Parameters
user_id
required
string
The ID of the recipient of the transaction
message
required
string
The message describing what has to be changed on the transaction.
200: OK
{
"data": {
"id": 2,
"user_id": "53",
"message": "Kindly review this transaction",
"created_at": "2019-05-23 10:41:09",
"updated_at": "2019-05-23 10:44:44"
}
}

Marking a transaction as delivered

Once a transaction has been paid for, the seller of the transaction is expected to mark it as delivered to indicate that he/she has delievered the good/service to the buyer. To mark a transaction as delivered call the endpoint below:

post
Marking a transaction as delivered

https://api.vesicash.com/transactions/{uuid}/deliver
Mark a transaction as delivered
Request
Response
Path Parameters
uuid
required
string
The UUID of the transaction to be marked as delivered
Headers
authorization
required
string
Bearer <access_token>
200: OK
{
"data": {
"id": 9,
"uuid": "7c6dc786-e4ef-4ab7-8758-05dfbb39c4e3",
"type": "service",
"sender": {
"id": 16,
"uuid": "f1041565-4b86-4af7-b792-ef7efe6279bf",
"firstname": "John",
"lastname": "Mark",
"phone": "07012345667",
"email": "johnmark@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-04-05 11:24:42",
"updated_at": "2019-04-05 11:24:42"
},
"recipient": {
"id": 4,
"uuid": "cad8580a-c6e3-44e4-83ca-25db675afbc1",
"firstname": "James",
"lastname": "Foss",
"phone": "07032047179",
"email": "jamesfoss@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-03-28 13:23:37",
"updated_at": "2019-03-28 13:23:37"
},
"invoice_no": "379394",
"amount": 5000,
"sender_confirmed": true,
"recipient_confirmed": false,
"is_accepted": true,
"status": "not paid",
"currency": "NGN",
"created_at": "2019-04-05 11:52:41",
"updated_at": "2019-04-05 11:52:41",
"service": {
"id": 6,
"invoice_id": 9,
"task": "Logo design",
"description": "new logo design",
"price": "5000.00",
"inspection_period": 3,
"document": "",
"created_at": "2019-04-05 11:52:41",
"updated_at": "2019-04-05 11:52:41"
}
}
}

Marking a transaction as satisfied

Once a transaction has been marked as delivered, the recipient of the transaction can either mark it as satisfied or open a dispute. To mark a transaction as satisfied call the endpoint below:

post
Marking a transaction as satisfied

https://api.vesicash.com/transactions/{uuid}/satisfy
Mark a transaction as satisfied
Request
Response
Path Parameters
uuid
required
string
The UUID of the transaction to be marked as satisfied
Headers
authorization
required
string
Bearer <access_token>
Form Data Parameters
user_id
required
string
The UUID of the recipient of the transaction.
200: OK
{
"data": {
"id": 9,
"uuid": "7c6dc786-e4ef-4ab7-8758-05dfbb39c4e3",
"type": "service",
"sender": {
"id": 16,
"uuid": "f1041565-4b86-4af7-b792-ef7efe6279bf",
"firstname": "John",
"lastname": "Mark",
"phone": "07012345667",
"email": "johnmark@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-04-05 11:24:42",
"updated_at": "2019-04-05 11:24:42"
},
"recipient": {
"id": 4,
"uuid": "cad8580a-c6e3-44e4-83ca-25db675afbc1",
"firstname": "James",
"lastname": "Foss",
"phone": "07032047179",
"email": "jamesfoss@example.com",
"profile": {
"address": null,
"state": null,
"city": null,
"country": null
},
"created_at": "2019-03-28 13:23:37",
"updated_at": "2019-03-28 13:23:37"
},
"invoice_no": "379394",
"amount": 5000,
"sender_confirmed": true,
"recipient_confirmed": true,
"is_accepted": true,
"status": "not paid",
"currency": "NGN",
"created_at": "2019-04-05 11:52:41",
"updated_at": "2019-04-05 11:52:41",
"service": {
"id": 6,
"invoice_id": 9,
"task": "Logo design",
"description": "new logo design",
"price": "5000.00",
"inspection_period": 3,
"document": "",
"created_at": "2019-04-05 11:52:41",
"updated_at": "2019-04-05 11:52:41"
}
}
}

Marking a milestone as delivered

For milestone transactions, each individual milestone in the transaction has to be marked as delivered. The Vesicash API makes this seamless.

post
Marking a milestone as delivered

https://api.vesicash.com/transactions/{uuid}/milestones/{id}/deliver
To mark a milestone in a transaction as delivered
Request
Response
Path Parameters
uuid
required
string
The UUID of the transaction.
id
required
number
The ID of the milestone to be marked as delivered.
Headers
authorization
required
string
Bearer <access_token>
Query Parameters
user_id
required
string
The ID of the sender of the
200: OK

Marking a milestone as satisfied

Once a milestone in a transaction has been marked as delivered, the recipient of the transaction can either mark it as satisfied or open a dispute. To mark a milestone in a transaction as satisfied call the endpoint below:

post
Mark a milestone as satisfied

https://api.vesicash.com/transactions/{uuid}/milestones/{id}/satisfy
Mark a milestone in a transaction as satisfied
Request
Response
Path Parameters
uuid
required
string
The UUID of the transaction.
id
required
integer
The ID of the milestone to be marked as satisfied.
Headers
authorization
required
string
Bearer <access_token>
Form Data Parameters
user_id
required
integer
The ID of the recipient of the transaction.
200: OK
{
"data": {
"id": 5,
"invoice_id": 15,
"name": "Banner design",
"description": "Banner design for our Instagram page",
"price": "5000.00",
"sender_confirmed": true,
"recipient_confirmed": true,
"inspection_period": 2,
"due_date": "2019-04-05 00:00:00",
"status": "pending",
"created_at": "2019-04-05 13:31:27",
"updated_at": "2019-04-05 15:56:58"
}
}