Create a transaction
The POST /v2/escrow-create endpoint is used to create an escrow transaction with the provided details. The request body should include information such as business ID, parties involved, title, type, description, milestones, quantity, amount, inspection period, due date, currency, source, and other related details. Additionally, files and recipients for each milestone can also be included in the request.
create a transaction
POST v2/escrow/create
Headers
Accept*
string
application/json
V-PRIVATE-KEY*
string
your vesicash private key
V-PUBLIC-KEY*
String
your vesicash public key
Request body
dashboard_url: The dashboard of the organization
currency (string): The currency used for the transaction.
title (string): The title of the escrow transaction.
type (string): The type of transaction, e.g., "milestone" or "oneoff"
description (string): A description of the transaction.
dispute_handler (string): The dispute handler for the transaction.
webhook_url (string): The URL for webhook events related to the escrow.
webhook_secret (string): The secret for verifying webhook events.
files (array): An array of file URLs related to the escrow.
url (string): The URL of the file.
parties (array): An array of parties involved in the escrow.
user_id (string): The ID of the user (unique identifier from your side).
email (string): The email of the party.
first_name (string): The first name of the party
last_name (string): The last name of the party.
phone (string): The phone number of the party.
is_initiator (boolean): Indicates if the party is the initiator.
role (string): The role of the party. eg buyer, seller or broker
role_description (string): The description of the party's role.
bank_account (object): The bank account details of the party.
bank_name (string): The name of the bank.
bank_code (string): The bank code.
account_number (string): The account number.
account_name (string): The account holder's name
milestones (array): An array of milestones for the escrow.
title (string): The title of the milestone.
amount (number): The amount associated with the milestone.
description (string): The description of the milestone.
inspection_period (number): The inspection period for the milestone.
grace_period (number): The grace period for the milestone.
due_date (string): The due date for the milestone.
Request
For example, you can make a post request to the endpoint above and pass in the raw json data below to create a one-off transaction.
{
"currency": "NGN",
"dashboard_url": "https://vesicash.com",
"title": "Third transaction",
"type": "milestone",
"description": "Fourth transaction",
"dispute_handler": "",
"webhook_url": "https://webhook.site/429e95ec-673e-4e07-a982-99178e95a263",
"webhook_secret": "XYSL-TEST-SECRET",
"escrow_charge":300.00,
"files": [
{
"url": ""
}
],
"parties": [
{
"user_id": "{{account_id}}",
"email": "[email protected]",
"first_name": "Ade",
"last_name": "Chi",
"phone": "+2349067362573",
"is_initiator": true,
"role": "buyer",
"role_description": "service buyer",
"bank_account": {
"bank_name": "Vesicash",
"bank_code": "VE000",
"account_number": "{{account_id}}",
"account_name": "Chi H"
}
},
{
"user_id": "{{account_id}}",
"email": "[email protected]",
"first_name": "Greg",
"last_name": "Chi",
"phone": "+2349067334573",
"is_initiator": false,
"role": "seller",
"role_description": "service seller",
"bank_account": {
"bank_name": "Vesicash",
"bank_code": "VE000",
"account_number": "{{account_id}}",
"account_name": "Chi H"
}
},
{
"user_id": "{{account_id}}",
"email": "[email protected]",
"first_name": "Greg",
"last_name": "Chi",
"phone": "+2349067334573",
"is_initiator": false,
"role": "broker",
"percentage": 10,
"role_description": "transaction broker",
"bank_account": {
"bank_name": "Vesicash",
"bank_code": "VE000",
"account_number": "{{account_id}}",
"account_name": "Chi H"
}
}
],
"milestones": [
{
"title": "milestone 1 for transaction 1",
"amount": 1000,
"description": "milestone 1 description",
"inspection_period": 24,
"grace_period": 24,
"due_date": "2024-03-19 15:04:05"
},
{
"title": "milestone 2 for transaction 1",
"amount": 1000,
"description": "milestone 1 description",
"inspection_period": 24,
"grace_period": 24,
"due_date": "2024-03-19 15:04:05"
}
]
}Response
The response of the request is a JSON schema representing the structure of the data returned. It includes various properties such as ID, transaction details, parties involved, milestones, files, and broker information. Each property has specific sub-properties that define the details of the escrow transaction and its associated entities. The response JSON schema is complex and includes nested objects and arrays, providing detailed information about the escrow transaction, parties, milestones, files, and broker details.
{
"status": "success",
"code": 201,
"message": "Created",
"data": {
"amount": 2000,
"amount_left": 0,
"amount_paid": 0,
"business_id": 4435451574,
"country": "NG",
"created_at": "2024-07-15T13:44:21.883210139Z",
"currency": "NGN",
"dashboard": "https://vesicash.com",
"description": "Fourth transaction",
"disbursement_charge": 0,
"dispute_handler": "",
"escrow_charge": 0,
"files": [
{
"type": "",
"url": ""
}
],
"id": 122,
"milestones": [
{
"amount": 1000,
"created_at": "2024-07-15T13:44:21.888155864Z",
"currency": "NGN",
"delivered_at": 0,
"description": "milestone 1 description",
"disbursed_to_parties": null,
"disbursement_retry_at": 12,
"due_date": "2024-03-19 15:04:05",
"grace_period": 24,
"id": 155,
"inspection_period": 24,
"milestone_id": "9ab9e7ebc24e4656a601",
"status": "Draft",
"title": "milestone 1 for transaction 1",
"transaction_id": "tr0f6d0d1837414ab19fbb",
"updated_at": "2024-07-15T13:44:21.888155864Z"
},
{
"amount": 1000,
"created_at": "2024-07-15T13:44:21.888155864Z",
"currency": "NGN",
"delivered_at": 0,
"description": "milestone 1 description",
"disbursed_to_parties": null,
"disbursement_retry_at": 12,
"due_date": "2024-03-19 15:04:05",
"grace_period": 24,
"id": 156,
"inspection_period": 24,
"milestone_id": "ce1ec5aa59a345938fb9",
"status": "Draft",
"title": "milestone 2 for transaction 1",
"transaction_id": "tr0f6d0d1837414ab19fbb",
"updated_at": "2024-07-15T13:44:21.888155864Z"
}
],
"parties": [
{
"bank_account": {
"account_name": "Chi H",
"account_number": "8685237835",
"bank_code": "VE000",
"bank_name": "Vesicash"
},
"created_at": "2024-07-15T13:44:21.880297485Z",
"email": "[email protected]",
"first_name": "Ade",
"has_accepted": true,
"id": 261,
"is_initiator": true,
"last_name": "Chi",
"percentage": 0,
"phone": "+2349067362573",
"role": "buyer",
"role_description": "service buyer",
"transaction_id": "tr0f6d0d1837414ab19fbb",
"transaction_party_id": "ef01c18137374824b099",
"updated_at": "2024-07-15T13:44:21.880297485Z",
"user_id": "8685237835"
},
{
"bank_account": {
"account_name": "Chi H",
"account_number": "8685237835",
"bank_code": "VE000",
"bank_name": "Vesicash"
},
"created_at": "2024-07-15T13:44:21.880297485Z",
"email": "[email protected]",
"first_name": "Greg",
"has_accepted": false,
"id": 262,
"is_initiator": false,
"last_name": "Chi",
"percentage": 90,
"phone": "+2349067334573",
"role": "seller",
"role_description": "service seller",
"transaction_id": "tr0f6d0d1837414ab19fbb",
"transaction_party_id": "7bc7857350be4855baca",
"updated_at": "2024-07-15T13:44:21.880297485Z",
"user_id": "8685237835"
},
{
"bank_account": {
"account_name": "Chi H",
"account_number": "8685237835",
"bank_code": "VE000",
"bank_name": "Vesicash"
},
"created_at": "2024-07-15T13:44:21.880297485Z",
"email": "[email protected]",
"first_name": "Greg",
"has_accepted": false,
"id": 263,
"is_initiator": false,
"last_name": "Chi",
"percentage": 10,
"phone": "+2349067334573",
"role": "broker",
"role_description": "transaction broker",
"transaction_id": "tr0f6d0d1837414ab19fbb",
"transaction_party_id": "2550a92e551b4a74aa67",
"updated_at": "2024-07-15T13:44:21.880297485Z",
"user_id": "8685237835"
}
],
"payment_status": "pending",
"status": "Draft",
"title": "Third transaction",
"transaction_id": "tr0f6d0d1837414ab19fbb",
"type": "milestone",
"updated_at": "2024-07-15T13:44:21.883210139Z"
}
}If the transaction requires a file upload such as photos or contracts from other sources, all you need to do is pass the files url as shown below:
{
...,
"files": [
{
"name": "sample.pdf",
"url": "https://uploaded_escrow_document_url_file.pdf"
}
],
...
}Last updated