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.

Specify type attribute to 'one off' for one off transactions and milestone for transactions with multiple milestones

create a transaction

POST v2/escrow/create

Headers

Name	Type	Description
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": "[e-mail]",
            "first_name": "Ade",
            "last_name": "Chi",
            "phone": "[phone]",
            "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": "[e-mail]",
            "first_name": "Greg",
            "last_name": "Chi",
            "phone": "[phone]",
            "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": "[e-mail]",
            "first_name": "Greg",
            "last_name": "Chi",
            "phone": "[phone]",
            "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.

201: Created

{
    "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": "[e-mail]",
                "first_name": "Ade",
                "has_accepted": true,
                "id": 261,
                "is_initiator": true,
                "last_name": "Chi",
                "percentage": 0,
                "phone": "[phone]",
                "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": "[e-mail]",
                "first_name": "Greg",
                "has_accepted": false,
                "id": 262,
                "is_initiator": false,
                "last_name": "Chi",
                "percentage": 90,
                "phone": "[phone]",
                "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": "[e-mail]",
                "first_name": "Greg",
                "has_accepted": false,
                "id": 263,
                "is_initiator": false,
                "last_name": "Chi",
                "percentage": 10,
                "phone": "[phone]",
                "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:

See how to upload files to our server and get the file url.

{
    ...,
     "files": [
        {
            "name": "sample.pdf",
            "url": "https://uploaded_escrow_document_url_file.pdf"
        }
    ],
    ...
}