Transactions

This page contains the logic that governs the creation and retrieval of transactions - sale or purchase.

Create Bi-Anonymous Transaction

POST {{url}}/transactions/anonymous/bi

Create a transaction where both parties are anonymous to the Vahlid system and generate a checkout link.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>

Request Body

Name	Type	Description
currency*	String	Currency code E.g NGN, GHS
buyer*	String	Buyers' email
seller*	String	Sellers' email
products*	Array<Object>	List of product objects that include the name, product description, product image URL (Optional) and price to be purchased. E.g [ { "name": "Cleaning", "prod_desc": "House Cleaning", "prod_image": "https://prod_image.jpg", "prod_price": "25000" }, ],
deadline_action	String	The action to be taken when the deadline reaches. The value provided should be either nothing or delete. The default value is nothing.
pay_deadline	String	Deadline to make payment for the product E.g Wed, 7 June 2023 13:47:13 GMT
disburse*	Object	This consist of amount, currency, exchangeRate E.g: { "amount": "25000", "currency": "NGN", "exchangeRate": 1 }
delivery_addr	String	Address where the product can be delivered.
is_service*	boolean	Indicating whether the transaction should be a service or a product, true indicate service false indicate product.

201: Created If successful

{
    "status": true,
    "code": 201,
    "message": "Bi-anonymous transaction created successfully.",
    "data": {
        "transaction": {
            "trans_id": "TEST-47489085",
            "delivery_addr": "Ikorodu, Lagos State",
            "pay_deadline": "2023-06-12T17:45:55.000Z",
            "deadline_action": "delete",
            "seller": {
                "_id": "644bb008c3c5e79ac2857cef",
                "firstname": null,
                "lastname": null,
                "phone": null,
                "username": "Vicolas",
                "vahlid_id": "68151491",
                "email": "[e-mail]",
                "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0"
            },
            "buyer": {
                "_id": "64525e2c9c29739758c8dadd",
                "firstname": null,
                "lastname": null,
                "phone": null,
                "username": "toyabilo",
                "vahlid_id": "68162524",
                "email": "[e-mail]",
                "notificationToken": null
            },
            "products": [
                {
                    "name": "Television",
                    "prod_desc": "LG 32' Television",
                    "prod_image": "https://ng.jumia.is/unsafe/fit-in/300x300/filters:fill(white)/product/78/713234/1.jpg?6751",
                    "prod_price": 370000,
                    "_id": "6485bec9540f6f6433deed03"
                }
            ],
            "products_price": 370000,
            "is_deposit_made": false,
            "is_delivery_made": false,
            "is_delivery_confirmed": false,
            "is_payment_reminded": false,
            "status": "pending",
            "is_service": false,
            "test": false,
            "fee": 7500,
            "vendorFee": 2000,
            "source": "developer",
            "source_api_key": "VHL-8w6kzuewtr5x48rtkr1s4nc83dz8vzgr44auiw1q",
            "dev_mode": "live",
            "promoPointsAwarded": false,
            "anonymous": "both",
            "currency": "NGN",
            "disburse": {
                "amount": 370000,
                "exchangeRate": 1,
                "currency": "NGN",
                "_id": "6485bec9540f6f6433deed04"
            },
            "_id": "6485bec9540f6f6433deed02",
            "created_at": "2023-06-11T12:32:09.105Z",
            "updated_at": "2023-06-11T12:32:09.105Z",
            "hash": "2fq5mp6e3ouo4sh14m6nawzf4grbdnp5ov85v3nb5f72uemnwp"
        },
        "checkoutLink": "https://vahlid-checkout-test.onrender.com/transaction/2fq5mp6e3ouo4sh14m6nawzf4grbdnp5ov85v3nb5f72uemnwp/track?target=J6NKZtsWl9xMl3JkjqwePnHqnUIpKe5pnJxMl3JkqGd7WRAwvzP0oEgdHOYBGnN9VR7Por21LdrmaciX"
    }
}

Get Transactions

GET {{url}}/transactions

Return users transactions data

Query Parameters

Name	Type	Description
limit	String	The number of results to be returned. The default is 10
sort	String	Arrange the data returned in a specific order, either in ascending or descending order, based on one or more fields.
page	String	Page of the transaction to be returned. The default is 1 (first page).

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK If successful

{
    "status": true,
    "code": 200,
    "message": "Transactions retrieved successfully.",
    "data": {
        "transactions": {
            "count": 13,
            "results": [
                {
                    "_id": "6485bec9540f6f6433deed02",
                    "trans_id": "TEST-47489085",
                    "delivery_addr": "Ikorodu, Lagos State",
                    "pay_deadline": "2023-06-12T17:45:55.000Z",
                    "deadline_action": "delete",
                    "seller": {
                        "_id": "644bb008c3c5e79ac2857cef",
                        "firstname": null,
                        "lastname": null,
                        "phone": null,
                        "photo": null,
                        "username": "Vicolas",
                        "vahlid_id": "68151491",
                        "email": "[e-mail]",
                        "referralCode": "VAHL-68151491",
                        "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
                        "terms_conditions": {
                            "accepted": true,
                            "meta": {
                                "transaction": "6473d45cc667f96a3eb3d9f1",
                                "accepted_date": "2023-06-08T19:29:54.963Z",
                                "_id": "64822c32c8548d4c3cff91bb"
                            },
                            "_id": "64822c32c8548d4c3cff91ba"
                        }
                    },
                    "buyer": {
                        "_id": "64525e2c9c29739758c8dadd",
                        "firstname": null,
                        "lastname": null,
                        "phone": null,
                        "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
                        "username": "[e-mail]",
                        "vahlid_id": "68162524",
                        "email": "[e-mail]",
                        "notificationToken": null
                    },
                    "products": [
                        {
                            "name": "Television",
                            "prod_desc": "LG 32' Television",
                            "prod_image": "https://ng.jumia.is/unsafe/fit-in/300x300/filters:fill(white)/product/78/713234/1.jpg?6751",
                            "prod_price": 370000,
                            "_id": "6485bec9540f6f6433deed03"
                        }
                    ],
                    "products_price": 370000,
                    "is_deposit_made": false,
                    "is_delivery_made": false,
                    "is_delivery_confirmed": false,
                    "is_payment_reminded": false,
                    "status": "pending",
                    "is_service": false,
                    "test": false,
                    "fee": 7500,
                    "vendorFee": 2000,
                    "source": "developer",
                    "source_api_key": "VHL-8w6kzuewtr5x48rtkr1s4nc83dz8vzgr44auiw1q",
                    "dev_mode": "live",
                    "promoPointsAwarded": false,
                    "anonymous": "both",
                    "currency": "NGN",
                    "disburse": {
                        "amount": 370000,
                        "exchangeRate": 1,
                        "currency": "NGN",
                        "_id": "6485bec9540f6f6433deed04"
                    },
                    "created_at": "2023-06-11T12:32:09.105Z",
                    "updated_at": "2023-06-11T12:32:09.105Z",
                    "hash": "2fq5mp6e3ouo4sh14m6nawzf4grbdnp5ov85v3nb5f72uemnwp"
                }
            ]
        }
    }
}

Verify Transaction

GET {{url}}/v1/transaction/verify/:transactionHash

Returns a verified transaction or an error if no such transaction exists.

Path Parameters

Name	Type	Description
transactionHash*	string	The hash of the transaction to be verified.

Headers

Name	Type	Description
Authorization	string	"Bearer <YOUR_API_KEY>"

200

{
    "status": true,
    "code": 200,
    "message": "Transaction retrieved successfully.",
    "data": {
        "_id": "64775cf6be2fa624e6c2ca85",
        "trans_id": "423914151",
        "delivery_addr": "Jos, Plateau State",
        "pay_deadline": "2023-06-03T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151678",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-01T20:41:04.144Z",
                    "_id": "6479026027720b593b7ee0e0"
                },
                "_id": "6479026027720b593b7ee0df"
            }
        },
        "buyer": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151531",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-01T20:41:04.144Z",
                    "_id": "6479026027720b593b7ee0e0"
                },
                "_id": "6479026027720b593b7ee0df"
            }
        },
        "products": [
            {
                "name": "Cassava Flour",
                "prod_desc": "Perishable food",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 5500,
                "_id": "64775cf6be2fa624e6c2ca86"
            }
        ],
        "products_price": 5500,
        "is_deposit_made": false,
        "is_delivery_made": true,
        "is_delivery_confirmed": true,
        "is_payment_reminded": false,
        "status": "completed",
        "is_service": false,
        "test": false,
        "fee": 237,
        "vendorFee": 77,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": true,
        "anonymous": "nil",
        "currency": "NGN",
        "created_at": "2023-05-31T14:43:02.288Z",
        "updated_at": "2023-05-31T14:43:02.288Z",
        "hash": "kz5isnw55xpd4fzobd81uvk254n39j4ptszo76rm2ap4xv2vz1",
        "checkoutFee": 70
    }
S

404: Not Found

Confirm Delivered Transaction

PATCH {{url}}/v1/transaction/confirm

Returns a transaction with delivery confirmed set to true.

Request Body

Name	Type	Description
transactionHash*	String	Transaction hash

200: OK

{
    "status": true,
    "code": 200,
    "message": "Delivery for this transaction has been confirmed.",
    "data": {
        "_id": "64775cf6be2fa624e6c2ca85",
        "trans_id": "423914151",
        "delivery_addr": "Jos, Plateau State",
        "pay_deadline": "2023-06-03T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-01T20:41:04.144Z",
                    "_id": "6479026027720b593b7ee0e0"
                },
                "_id": "6479026027720b593b7ee0df"
            }
        },
        "buyer": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-01T20:41:04.144Z",
                    "_id": "6479026027720b593b7ee0e0"
                },
                "_id": "6479026027720b593b7ee0df"
            }
        },
        "products": [
            {
                "name": "Cassava Flour",
                "prod_desc": "Perishable food",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 5500,
                "_id": "64775cf6be2fa624e6c2ca86"
            }
        ],
        "products_price": 5500,
        "is_deposit_made": false,
        "is_delivery_made": true,
        "is_delivery_confirmed": true,
        "is_payment_reminded": false,
        "status": "completed",
        "is_service": false,
        "test": false,
        "fee": 237,
        "vendorFee": 77,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": true,
        "anonymous": "nil",
        "currency": "NGN",
        "created_at": "2023-05-31T14:43:02.288Z",
        "updated_at": "2023-05-31T14:43:02.288Z",
        "hash": "kz5isnw55xpd4fzobd81uvk254n39j4ptszo76rm2ap4xv2vz1"
    }
}JSON

404: Not Found

Make Payment by Card Method Anonymously

POST {{url}}/v1/transaction/:transactionID/pay/card

Make payment for a transaction specified by the path variable transactionID using debit card as an anonymous user

Path Parameters

Name	Type	Description
transactionID*	String	Transaction _id

Request Body

Name	Type	Description
card_number*	Number	The sixteen digits on the front of your debit card
cvv*	Number	Card Verification Value, CVV is a 3-digit code printed on the back of the credit card or debit card
expired_month*	Number	The expiration date can be found on the card, written as XX/XX (month and year). The first number before the slash
expired_year*	Number	The expiration date can be found on the card, written as XX/XX (month and year). The second number after the slash
address*	String	House address of the card owner
city*	String	The city where the card owner resides
country*	String	The country where the card owner resides
state*	String	State where the card owner resides
zipcode*	String	A postal code or zip code is series of codes that may contain numerals, alphabets and/or punctuations, used for sorting out mailing address.

400: Bad Request Return the below if payment has been made for a transaction already

{
    "status": "fail",
    "error": {
        "statusCode": 400,
        "status": "fail",
        "isOperational": true
    },
    "message": "Payment has been made for this transaction."
}

400: Bad Request Return the below response, if transaction is completed

404: Not Found Return the below response, if transaction does not exist

200: OK Return the below response, if successful

Make Payment by Account Method Anonymously

POST {{url}}/v1/transaction/:transactionID/pay/account

Make payment for a transaction specified by the path variable transactionID using a bank account as an anonymous user

Path Parameters

Name	Type	Description
transactionID*	String	Transaction _id

Request Body

Name	Type	Description
bankCode*	String	A bank code is a code assigned by a central bank. E.g 044
accountNumber*	String	Bank account number

200: OK Returns the below, If payment is successful

{
    "status": true,
    "code": 200,
    "message": "Payment initiated successfully.",
    "data": {
        "transaction": {
            "dev_mode": "live",
            "_id": "61af2507b143dfcb8396c382",
            "trans_id": "480075038",
            "delivery_addr": "Obalende",
            "pay_deadline": "2021-12-17T00:00:00.000Z",
            "deadline_action": "nothing",
            "seller": {
                "_id": "61a0d3eb780f50d2d3c0b8a1",
                "firstname": null,
                "lastname": null,
                "phone": null,
                "photo": null,
                "username": "Qoyyum",
                "vahlid_id": "68590835",
                "email": "[e-mail]",
                "referralCode": "VAHL-68590835",
                "notificationToken": null
            },
            "buyer": {
                "_id": "618559827c7b9bcfbcb8b073",
                "firstname": "Nurudeen",
                "lastname": "Qoyyum",
                "phone": null,
                "photo": "https://res.cloudinary.com/vahlid/image/upload/v1649158065/vahlid_mern/avatar/xxurbh0oyoxojxkqnydy.jpg",
                "username": "CloudNQT",
                "vahlid_id": "68985022",
                "email": "[e-mail]",
                "referralCode": "VAHL-68985022",
                "notificationToken": "fqwvH28_QWCv2bKcwECcoZ:APA91bGKSeS2gyBpwHortzTNp6O2ux2l51zbdtT0dZbc4K5idZY_fJbxfpln2ZhVwDj3o0TDBp57gLpcMNcCrNEr7Qv9wWgdbmKwziyPc52OqXX3zNQ2kHguefyTn1MpGeZzfVC6Z7wd"
            },
            "products": [
                {
                    "name": "Ewa",
                    "prod_desc": "Cool",
                    "prod_price": 200,
                    "_id": "61af2507b143dfcb8396c383"
                }
            ],
            "products_price": 200,
            "is_deposit_made": false,
            "is_delivery_made": false,
            "is_delivery_confirmed": false,
            "is_payment_reminded": false,
            "status": "pending",
            "is_service": true,
            "test": false,
            "fee": 5,
            "vendorFee": 2.8,
            "source": "api",
            "promoPointsAwarded": false,
            "anonymous": "nil",
            "created_at": "2021-12-07T09:10:31.696Z",
            "updated_at": "2021-12-07T09:10:31.696Z",
            "hash": "b7ep9vroh3nrn9r4whkfd2rut663vgad38voquxm7wduvy3dro",
            "currency": "NGN"
        }
    }
}s

404: Not Found Return the below, If transaction does not exist

Get Single Transaction Anonymously

GET {{url}}/v1/transaction/retrieve/:id

Returns a single transaction specified in the path variable id by an anonymous user

Path Parameters

Name	Type	Description
id*	String	Transaction _id

200: OK Return the below, if successful

{
    "status": "success",
    "code": 200,
    "message": "Data retrieved successfully",
    "data": {
        "_id": "61af2507b143dfcb8396c382",
        "trans_id": "480075038",
        "delivery_addr": "Obalende",
        "pay_deadline": "2021-12-17T00:00:00.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "61a0d3eb780f50d2d3c0b8a1",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Qoyyum",
            "vahlid_id": "68590835",
            "email": "[e-mail]",
            "referralCode": "VAHL-68590835",
            "notificationToken": null
        },
        "buyer": {
            "_id": "618559827c7b9bcfbcb8b073",
            "firstname": "Nurudeen",
            "lastname": "Qoyyum",
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1649158065/vahlid_mern/avatar/xxurbh0oyoxojxkqnydy.jpg",
            "username": "CloudNQT",
            "vahlid_id": "68985022",
            "email": "[e-mail]",
            "referralCode": "VAHL-68985022",
            "notificationToken": "fqwvH28_QWCv2bKcwECcoZ:APA91bGKSeS2gyBpwHortzTNp6O2ux2l51zbdtT0dZbc4K5idZY_fJbxfpln2ZhVwDj3o0TDBp57gLpcMNcCrNEr7Qv9wWgdbmKwziyPc52OqXX3zNQ2kHguefyTn1MpGeZzfVC6Z7wd"
        },
        "products": [
            {
                "name": "Ewa",
                "prod_desc": "Cool",
                "prod_price": 200,
                "_id": "61af2507b143dfcb8396c383"
            }
        ],
        "products_price": 200,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": true,
        "test": false,
        "fee": 5,
        "vendorFee": 2.8,
        "source": "api",
        "promoPointsAwarded": false,
        "anonymous": "nil",
        "created_at": "2021-12-07T09:10:31.696Z",
        "updated_at": "2021-12-07T09:10:31.696Z",
        "hash": "b7ep9vroh3nrn9r4whkfd2rut663vgad38voquxm7wduvy3dro",
        "__v": 0,
        "currency": "NGN"
    }
}

404: Not Found Return the below, if transaction does not exist

Store Anonymous Seller Account Information

PUT {{url}}/v1/transaction/:transactionID/account

Stores the bank information of an anonymous user whose a seller gotten from the transaction specified in the path variable transactionID

Path Parameters

Name	Type	Description
transactionID*	String	Transaction trans_id

Request Body

Name	Type	Description
bankCode*	String	A bank code is a code assigned by a central bank. E.g 044
bankName*	String	Name of the bank
accountNumber*	String	Ten digit bank account number
currency*	String	Currency code of the bank E.g NGN, GHS, USD

200: OK Return the below, if successful

{
    "status": true,
    "code": 200,
    "message": "Anonymous seller account details updated successfully.",
    "data": {
        "_id": "6478fbb78bd80d2c5ddcd401",
        "currency": "NGN",
        "user": "64525e2c9c29739758c1dadd",
        "__v": 0,
        "bank_code": "044",
        "bank_name": "Abbas Tobi",
        "created_at": "2023-06-01T20:12:39.121Z",
        "dev_mode": "test",
        "name": "Bale Gary",
        "number": "0690000033",
        "source": "developer",
        "updated_at": "2023-06-08T17:51:40.398Z"
    }
}

404: Not Found Return the below, if the transaction specified in the path variable transactionID does not exist

Get Anonymous Seller Account Information

GET {{url}}/v1/transaction/:transactionID/account?currency=NGN

Get the bank account information of an anonymous user (seller)

Path Parameters

Name	Type	Description
transactionID*	String	Transaction trans_id

Query Parameters

Name	Type	Description
currency*	String	currency code E.g NGN, GHS, USD

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Anonymous seller account details retrieved successfully.",
    "data": {
        "_id": "6478fbb78bd86d2c5ddcb201",
        "currency": "NGN",
        "type": "PanAfrican",
        "user": "64525e2c9c29739758c8dadd",
        "__v": 0,
        "bank_code": "044",
        "bank_name": "Abbas Tobi",
        "created_at": "2023-06-01T20:12:39.121Z",
        "dev_mode": "test",
        "name": "Bale Gary",
        "number": "0690000033",
        "source": "developer",
        "updated_at": "2023-06-08T17:51:40.398Z"
    }
}

404: Not Found Return the response below, if the transaction specified in the path variable transactionID does not exist

Accept Terms and Condition by Anonymous User

PATCH {{url}}/v1/transaction/:transactionID/tc?target=buyer

Accept terms and conditions of a transaction specified in the path variable transactionID base on the query variable target which could be either buyer or seller

Path Parameters

Name	Type	Description
transactionID*	String	Transaction transactionID

Query Parameters

Name	Type	Description
target*	String	Target either the buyer or seller of the specified transaction. This could be either buyer or seller

404: Not Found Return the below response if the transaction specified in the transactionID does not exist

{
    "status": false,
    "code": 404,
    "message": "Transaction not found",
    "errors": []
}

200: OK Return the response below, if successful

Get List of Recent Transactions

GET {{url}}/v1/transaction/recent/:limit/:filter

Returns list of most recent transactions

Path Parameters

Name	Type	Description
limit	String	The number of results to be returned. The default number is 10
filter	String	Filter Transaction, if sales filter based on the seller. if purchase filter is based on the buyer, else filter is on either buyer or seller

Query Parameters

Name	Type	Description
currency	String	Currency code. The default value is NGN

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the below response, if successful

{
    "status": true,
    "code": 200,
    "message": "Transaction retrieved successfully.",
    "data": [
        {
            "_id": "64792b9dc792f00da9c747f4",
            "trans_id": "TEST-517480270",
            "delivery_addr": "Ikorudu, Lagos State",
            "pay_deadline": "2023-06-04T15:46:13.000Z",
            "deadline_action": "nothing",
            "seller": {
                "_id": "64525e2c9c29739758c8dadd",
                "firstname": null,
                "lastname": null,
                "phone": null,
                "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
                "username": "[e-mail]",
                "vahlid_id": "68162524",
                "email": "[e-mail]",
                "notificationToken": null
            },
            "buyer": {
                "_id": "644bb008c3c5e79ac2857cef",
                "firstname": null,
                "lastname": null,
                "phone": null,
                "photo": null,
                "username": "Vicolas",
                "vahlid_id": "68151491",
                "email": "[e-mail]",
                "referralCode": "VAHL-68151491",
                "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
                "terms_conditions": {
                    "accepted": true,
                    "meta": {
                        "transaction": "6473d45cc667f96a3eb3d9f1",
                        "accepted_date": "2023-06-08T19:29:54.963Z",
                        "_id": "64822c32c8548d4c3cff91bb"
                    },
                    "_id": "64822c32c8548d4c3cff91ba"
                }
            },
            "products": [
                {
                    "name": "House Cleaning",
                    "prod_desc": "Cleaning services",
                    "prod_image": "https://www.cleansweepofamerica.com/wp-content/uploads/2020/10/office-cleaning-service.jpeg",
                    "prod_price": 15000,
                    "_id": "64792b9dc792f00da9c747f5"
                }
            ],
            "products_price": 15000,
            "is_deposit_made": false,
            "is_delivery_made": false,
            "is_delivery_confirmed": false,
            "is_payment_reminded": false,
            "status": "pending",
            "is_service": true,
            "test": false,
            "fee": 475,
            "vendorFee": 210,
            "source": "api",
            "dev_mode": "live",
            "promoPointsAwarded": false,
            "anonymous": "buyer",
            "currency": "NGN",
            "disburse": {
                "amount": 15000,
                "exchangeRate": 1,
                "currency": "NGN",
                "_id": "64792b9dc792f00da9c747f6"
            },
            "created_at": "2023-06-01T23:37:01.619Z",
            "updated_at": "2023-06-01T23:37:01.619Z",
            "hash": "gehkukwp7mt3piw4bd3bq7jqzagnxtdja7a73axvrtzi1ov5u3"
        },
    ]
}

Calculate Vahlid Transaction Charge

GET {{url}}/v1/transaction/charge

Calculate Vahlid transaction charges based on the query value passed in the variable amount

Query Parameters

Name	Type	Description
amount*	String	Amount to be calculated
currency*	String	Currency code of the amount provided E.g NGN, GHS

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Charges for transaction retrieved successfully.",
    "data": {
        "charge": 225,
        "amount": "5000"
    }
}

Cancel Transaction

GET {{url}}/v1/transaction/cancel/:trans_id

Cancel the Transaction specified in the path variable trans_id by setting the status to cancelled.

Path Parameters

Name	Type	Description
trans_id*	String	Transaction trans_id of the transaction to be cancelled

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

404: Not Found Returns the response below, if the transaction specified in the path variable trans_id does not exist

{
    "status": false,
    "code": 404,
    "message": "Transaction record not found",
    "errors": []
}

200: OK Return the response below, if successful

400: Bad Request Return the response below, if transaction specified in the path variable has been cancelled already

Get Total Transaction Sales

GET {{url}}/v1/transaction/sales/total

Return the total amount of completed transaction sales of a user (seller) based on the currency provided in the query value currency.

Query Parameters

Name	Type	Description
currency*	String	Currency code of the transaction E.g NGN, GHS

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Total sales retrieved.",
    "data": {
        "totalSales": 5500
    }
}

Get Total Transaction Purchases

GET {{url}}/v1/transaction/purchases/total

Return the total amount of completed transaction purchases of a user (buyer) based on the currency provided in the query value currency.

Query Parameters

Name	Type	Description
currency*	String	Currency code on the transaction E.g NGN, GHS

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Total sales retrieved.",
    "data": {
        "totalPurchases": 8000
    }
}

Get Transactions Count

GET {{url}}/v1/transaction/count

Return the number of transactions done by a user.

Query Parameters

Name	Type	Description
currency	String	Currency code of the transaction to be returned E.g NGN, GHS

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Transaction count retrieved successfully.",
    "data": {
        "count": 11
    }
}

Search Users' Transactions

GET {{url}}/v1/transaction/search

Return a list of a matched user's transactions based on the value specified in the query variablesearchQuery.

Query Parameters

Name	Type	Description
limit	String	The number of results to be return. The default is 10
page	String	Page of the transaction to be returned. The default is 1 (first page).
searchQuery*	String	Text that will return a matching transaction. Text is case-insensitive.
is_service	String	Set the transaction to be a service if the value istrue. If not provided returns false.
is_seller	String	If the value is true set the user of a transaction as a seller, else as a buyer. If not provided returns false.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "count": 1,
    "message": "Records searched successfully.",
    "data": [
        {
            "_id": "64775cf6be2fa624e6c2ca85",
            "trans_id": "423914151",
            "delivery_addr": "Jos, Plateau State",
            "pay_deadline": "2023-06-03T13:47:13.000Z",
            "deadline_action": "nothing",
            "products": [
                {
                    "name": "Cassava Flour",
                    "prod_desc": "Perishable food",
                    "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                    "prod_price": 5500,
                    "_id": "64775cf6be2fa624e6c2ca86"
                }
            ],
            "products_price": 5500,
            "is_deposit_made": false,
            "is_delivery_made": true,
            "is_delivery_confirmed": true,
            "is_payment_reminded": false,
            "status": "completed",
            "is_service": false,
            "test": false,
            "fee": 237,
            "vendorFee": 77,
            "source": "developer",
            "dev_mode": "test",
            "promoPointsAwarded": true,
            "anonymous": "nil",
            "currency": "NGN",
            "created_at": "2023-05-31T14:43:02.288Z",
            "updated_at": "2023-05-31T14:43:02.288Z",
            "hash": "kz5isnw55xpd4fzobd81uvk254n39j4ptszo76rm2ap4xv2vz1",
            "__v": 0,
            "seller": [],
            "buyer": []
        }
    ]
}

Get Single Transaction

GET {{url}}/v1/transaction/:trans_id

Returns a single transaction specified in the path variable trans_id

Path Parameters

Name	Type	Description
trans_id*	String	Transaction trans_id

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Transaction retrieved successfully.",
    "data": {
        "_id": "6473d080a0fb841e56bb9aee",
        "trans_id": "TEST-11944705",
        "delivery_addr": "Ikeja, Lagos State",
        "pay_deadline": "2023-06-01T16:45:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "64525e2c9c29739758c8dadd",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
            "username": "[e-mail]",
            "vahlid_id": "68162524",
            "email": "[e-mail]",
            "notificationToken": null
        },
        "buyer": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "products": [
            {
                "name": "Jersey",
                "prod_desc": "Basket Jersey",
                "prod_image": "https://res.cloudinary.com/vahlid/image/upload/v1684514773/vahlid_mern/transactions/fod8e23yuxmxo9puxsdd.jpg",
                "prod_price": 9200,
                "_id": "6473d080a0fb841e56bb9aef"
            }
        ],
        "products_price": 9200,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "cancelled",
        "is_service": false,
        "test": false,
        "fee": 330,
        "vendorFee": 128.8,
        "source": "developer",
        "dev_mode": "live",
        "promoPointsAwarded": false,
        "anonymous": "buyer",
        "currency": "NGN",
        "disburse": {
            "amount": 9200,
            "exchangeRate": 1,
            "currency": "NGN",
            "_id": "6473d080a0fb841e56bb9af0"
        },
        "created_at": "2023-05-28T22:06:56.634Z",
        "updated_at": "2023-05-28T22:06:56.634Z",
        "hash": "fzi6u5eit2sxbugva12ejcnnmygrugt32aiwqhkkt5ycb8oj9p"
    }
}K

404: Not Found Return the response below, if the transaction specified in the path variable trans_id does not exit

Get All Transactions for A Single User

GET {{url}}/v1/transaction

Return a list of all the transactions done by a user.

Query Parameters

Name	Type	Description
limit	String	The number of results to be returned. The default is 10
page	String	Page of the transaction to be returned. The default is 1 (first page).
fields	String	Transaction fields or key values to be returned by the transaction data E.g source, dev_mode, products_price
sort	String	Arrange the data returned in a specific order, either in ascending or descending order, based on one or more fields.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": "success",
    "code": 200,
    "count": 144,
    "message": "Data retrieved successfully",
    "data": [
        {
            "_id": "647f1a51981d967082432dc8",
            "trans_id": "TEST-988317736",
            "delivery_addr": "Jos, Plateau State",
            "pay_deadline": "2023-06-07T13:47:13.000Z",
            "deadline_action": "nothing",
            "seller": {
                "_id": "64525e2c9c29739758c8dadd",
                "firstname": null,
                "lastname": null,
                "phone": null,
                "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
                "username": "[e-mail]",
                "vahlid_id": "68162524",
                "email": "[e-mail]",
                "notificationToken": null
            },
            "buyer": {
                "_id": "644bb008c3c5e79ac2857cef",
                "firstname": null,
                "lastname": null,
                "phone": null,
                "photo": null,
                "username": "Vicolas",
                "vahlid_id": "68151491",
                "email": "[e-mail]",
                "referralCode": "VAHL-68151491",
                "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
                "terms_conditions": {
                    "accepted": true,
                    "meta": {
                        "transaction": "6473d45cc667f96a3eb3d9f1",
                        "accepted_date": "2023-06-08T19:29:54.963Z",
                        "_id": "64822c32c8548d4c3cff91bb"
                    },
                    "_id": "64822c32c8548d4c3cff91ba"
                }
            },
            "products": [
                {
                    "name": "Irish Potatoes",
                    "prod_desc": "Perishable food",
                    "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                    "prod_price": 5000,
                    "_id": "647f1a51981d967082432dc9"
                }
            ],
            "products_price": 5000,
            "is_deposit_made": false,
            "is_delivery_made": false,
            "is_delivery_confirmed": false,
            "is_payment_reminded": false,
            "status": "pending",
            "is_service": false,
            "test": false,
            "fee": 225,
            "vendorFee": 70,
            "source": "developer",
            "dev_mode": "live",
            "promoPointsAwarded": false,
            "anonymous": "seller",
            "currency": "NGN",
            "created_at": "2023-06-06T11:36:49.033Z",
            "updated_at": "2023-06-06T11:36:49.033Z",
            "hash": "77e831qwt6gwpm8cauv1jkeesbaxbnf5buo7gqfxdfm1f358sk"
        }
    ]
}

Get Transaction Monthly Summary

GET {{url}}/v1/transaction/month-summary

Returns the summary of all completed transactions of a user

Query Parameters

Name	Type	Description
position	String	Filter transaction with the value specified here. The value could be either buyer or seller. Return zero for each month, if nothing is provided.
type	String	If the provided value is service sets the transaction's field is_service to true, else set it to false. By default, is false

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Returns the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "successful",
    "data": {
        "Jan": 0,
        "Feb": 0,
        "Mar": 0,
        "Apr": 0,
        "May": 5600,
        "Jun": 67800,
        "Jul": 0,
        "Aug": 0,
        "Sep": 0,
        "Oct": 0,
        "Nov": 0,
        "Dec": 0
    }
}

Product Purchase Transaction

POST {{url}}/v1/transaction/product/purchase

Make a purchase for a product. Return a new transaction data populated with buyer and seller data.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

Request Body

Name	Type	Description
currency*	String	Currency code E.g NGN, GHS
delivery_addr	String	Address where the product can be delivered.
pay_deadline	String	Deadline to make payment for the product E.g Wed, 7 June 2023 13:47:13 GMT
deadline_action	String	The action to be taken when the deadline reaches. The value provided should be either nothing or delete. The default value is nothing.
products*	Array<Object>	List of product objects that include the name, product description, product image URL and price to be purchased. E.g [ { "name": "Irish Potatoes", "prod_desc": "Perishable food", "prod_image": "https://prod_image.jpeg" "prod_price": "5000" }, ],
promoCode	String	Promo code
vahlid_id*	String	Seller's Vahlid ID or email E.g 68985022, [e-mail]

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Product purchase transaction created successfully.",
    "data": {
        "trans_id": "TEST-816264995",
        "delivery_addr": "Jos, Plateau State",
        "pay_deadline": "2023-06-10T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "64525e2c9c29739758c8dadd",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
            "username": "toyabipo6",
            "vahlid_id": "68162524",
            "email": "[e-mail]",
            "notificationToken": null
        },
        "buyer": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151991",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "products": [
            {
                "name": "Irish Potatoes",
                "prod_desc": "Perishable food",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 5000,
                "_id": "64832fb99cffa2266474564b"
            }
        ],
        "products_price": 5000,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": false,
        "test": true,
        "fee": 225,
        "vendorFee": 70,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": false,
        "anonymous": "seller",
        "currency": "NGN",
        "_id": "64832fb99cffa2266474564a",
        "created_at": "2023-06-09T13:57:13.435Z",
        "updated_at": "2023-06-09T13:57:13.435Z",
        "hash": "5821mcxoi4vcwnkgm59owi6pk91dzxsvmpui7tjhzhorIRy597"
    }
}

Service Purchase Transaction

POST {{url}}/v1/transaction/service/purchase

Make a purchase for service(s). Return a new transaction data populated with buyer and seller data.

Query Parameters

Name	Type	Description
currency*	String	Currency code E.g NGN, GHS
delivery_addr	String	Address where the product can be delivered.
pay_deadline	String	Deadline to make payment for the product E.g Wed, 7 June 2023 13:47:13 GMT
deadline_action	String	The action to be taken when the deadline reaches. The value provided should be either nothing or delete. The default value is nothing.
products*	Array<Object>	List of product objects that include the name, product description, product image URL and price to be purchased. E.g [ { "name": "Home Lesson", "prod_desc": "Household lesson for kids", "prod_image": "https://prod_image.jpeg" "prod_price": "25000" }, ],
promoCode	String	Promo code
vahlid_id*	String	Seller's Vahlid ID or email E.g 68985022, [e-mail]

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if sucessful

{
    "status": true,
    "code": 200,
    "message": "Service purchase transaction successfully created.",
    "data": {
        "trans_id": "TEST-677252295",
        "delivery_addr": "Kwali, Abuja",
        "pay_deadline": "2023-06-10T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "618559827c7b9bcfbcb8b073",
            "firstname": "Nurudeen",
            "lastname": "Qoyyum",
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1649158065/vahlid_mern/avatar/xxurbh0oyoxojxkqnydy.jpg",
            "username": "CloudNQT",
            "vahlid_id": "68985022",
            "email": "[e-mail]",
            "referralCode": "VAHL-68985022",
            "notificationToken": "fqwvH28_QWCv2bKcwECcoZ:APA91bGKSeS2gyBpwHortzTNp6O2ux2l51zbdtT0dZbc4K5idZY_fJbxfpln2ZhVwDj3o0TDBp57gLpcMNcCrNEr7Qv9wWgdbmKwziyPc52OqXX3zNQ2kHguefyTn1MpGeZzfVC6Z7wd"
        },
        "buyer": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "products": [
            {
                "name": "Lesson",
                "prod_desc": "Home lesson for kids",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 113000,
                "_id": "64833aa99cffa22664745676"
            }
        ],
        "products_price": 113000,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": true,
        "test": true,
        "fee": 2925,
        "vendorFee": 1582,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": false,
        "anonymous": "nil",
        "currency": "NGN",
        "_id": "64833aa99cffa22664745675",
        "created_at": "2023-06-09T14:43:53.092Z",
        "updated_at": "2023-06-09T14:43:53.092Z",
        "hash": "jmd123a8nz2dobtrqrjnasne2p6b7ifh73jsoxc9rg9dxi3mov"
    }
}

Product Sale Transaction

POST {{url}}/v1/transaction/product/sale

Make sales for a product(s). Return a new transaction data populated with buyer and seller data.

Query Parameters

Name	Type	Description
currency*	String	Currency code E.g NGN, GHS
vahlid_id*	String	Buyer's Vahlid ID or email E.g 68985022, [e-mail]
promoCode	String	Promo code
products*	Array<Object>	List of product objects that include the name, product description, product image URL and price to be purchased. E.g [ { "name": "Irish Potatoes", "prod_desc": "Perishable food", "prod_image": "https://prod_image.jpeg" "prod_price": "5000" }, ],
deadline_action	String	The action to be taken when the deadline reaches. The value provided should be either nothing or delete. The default value is nothing.
pay_deadline	String	Deadline to make payment for the product E.g Wed, 7 June 2023 13:47:13 GMT
delivery_addr	String	Address where the product can be delivered.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Product sale transaction has been successfully created.",
    "data": {
        "trans_id": "TEST-503028339",
        "delivery_addr": "Jos, Plateau State",
        "pay_deadline": "2023-06-10T15:27:16.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "vicola2gmail.com",
            "referralCode": "VAHL-68152491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "buyer": {
            "_id": "64525e2c9c29739758c8dadd",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
            "username": "toyabipo1",
            "vahlid_id": "68160524",
            "email": "[e-mail]",
            "notificationToken": null
        },
        "products": [
            {
                "name": "Toy",
                "prod_desc": "Perishable toy",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 2500,
                "_id": "64833f209cffa2266474568d"
            }
        ],
        "products_price": 2500,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": false,
        "test": false,
        "fee": 62,
        "vendorFee": 35,
        "source": "developer",
        "dev_mode": "live",
        "promoPointsAwarded": false,
        "anonymous": "buyer",
        "currency": "NGN",
        "_id": "64833f209cffa2266474568c",
        "created_at": "2023-06-09T15:02:56.807Z",
        "updated_at": "2023-06-09T15:02:56.807Z",
        "hash": "jogc42w45ey2k3bpw2q578sojsmngynrk6b44hxr6y3xdt9fvj"
    }
}

Service Sale Transaction

POST {{url}}/v1/transaction/service/sale

Make sales for service(s). Return a new transaction data populated with buyer and seller data.

Query Parameters

Name	Type	Description
currency*	String	Currency code E.g NGN, GHS
vahlid_id*	String	Buyer's Vahlid ID or email E.g 68985022, [e-mail]
promoCode	String	Promo code
products*	Array<Object>	List of product objects that include the name, product description, product image URL and price to be purchased. E.g [ { "name": "Cleaning", "prod_desc": "House Cleaning", "prod_image": "https://prod_image.jpeg" "prod_price": "25000" }, ],
delivery_addr	String	Address where the product can be delivered.
deadline_action	String	The action to be taken when the deadline reaches. The value provided should be either nothing or delete. The default value is nothing.
pay_deadline	String	Deadline to make payment for the product E.g Wed, 7 June 2023 13:47:13 GMT

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Service sale transaction successfully created.",
    "data": {
        "trans_id": "TEST-520549503",
        "delivery_addr": "Otukpo, Benue State",
        "pay_deadline": "2023-06-11T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "buyer": {
            "_id": "64525e2c9c29739758c8dadd",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
            "username": "[e-mail]",
            "vahlid_id": "68162524",
            "email": "[e-mail]",
            "notificationToken": null
        },
        "products": [
            {
                "name": "Cleaning",
                "prod_desc": "House cleaning",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 5000,
                "_id": "648340c99cffa226647456a1"
            }
        ],
        "products_price": 5000,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": true,
        "test": true,
        "fee": 225,
        "vendorFee": 70,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": false,
        "anonymous": "buyer",
        "currency": "NGN",
        "_id": "648340c99cffa226647456a0",
        "created_at": "2023-06-09T15:10:01.220Z",
        "updated_at": "2023-06-09T15:10:01.220Z",
        "hash": "p3913ps22vt4d5chvizhdjgnqeevfcfkt3gyreayjzybh15p8s"
    }
}

Confirm Transaction Delivery Made

POST {{url}}/v1/transaction/ive-delivered

Return transaction data specified in the request body with is_delivery_made field set to true.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

Request Body

Name	Type	Description
trans_id*	String	Transaction trans_id

400: Bad Request If transaction is_delivery_made is set to true

{
    "status": false,
    "code": 400,
    "message": "Delivery has been made already.",
    "errors": []
}

404: Not Found If Transaction does not exist

400: Bad Request If Transaction is_deposit_made is false

400: Bad Request If Transaction status is either completed or cancelled

400: Bad Request if trying to confirm delivery made as a buyer

200: OK If successful

Make Payment and Confirm Transaction Delivery

POST {{url}}/v1/transaction/confirm-delivery

Initiate the payment to the seller of the transaction specified by the trans_id provided in the request body, and proceed to confirm the payment and mark the transaction as complete. Return transaction data specified in the request body with is_delivery_confirmed field set to true and status set to complete.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

Request Body

Name	Type	Description
trans_id*	String	Transaction trans_id

404: Not Found If transaction does not exist

{
    "status": false,
    "code": 400,
    "message": "Transaction record not foundjs.",
    "errors": []
}

200: OK If successful

Initialize Transaction

POST {{url}}/v1/transaction/initialize

Generates direct payment link with Flutterwave.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

Request Body

Name	Type	Description
trans_id*	String	Transaction trans_id
seller*	String	Seller's user ID E.g 64525e2c9c29739758c8daya
buyer*	String	Buyer's user ID E.g 64525e2c9c29739758c8dafh
type*	String	This can be either sell or buy
callbackUrl	String	Callback URL to redirect to after Vahlid confirms payment E.g https://www.google.com

404: Not Found If the transaction trans_id does not exist

{
    "status": false,
    "code": 404,
    "message": "Transaction not found.",
    "errors": []
}

200: OK If successful

Initialize Transaction Anonymously

POST {{url}}/v1/transaction/sales

Initializes a purchase transaction. Returns a Vahlid Link - in the format - https://checkout.vahlid.com/transaction/{{HASH}}/track. This link can be used by the customer to track the status of the transaction in realtime.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

Request Body

Name	Type	Description
webhook	String	The webhook that should be called for status updates of the transaction.
products*	Array<Object>	An array of the products/services to be rendered. Products must have the following String properties: - name (required): The name of the product. - prod_desc (required): The description for the product. - prod_price (optional): The price for the product. - prod_image (optional): The URLs of the images for the product.
email*	String	The email of the customer.
pay_deadline	String	Timestamp to indicate the deadline for payment. After this deadline, if the customer has not made payment, the transaction will be cancelled.
delivery_addr*	String	Delivery Address
deadline_action	String	Action taken when the deadline reaches. The value can be eithernothing or delete.
vahlid_id*	String	The vahlid_id of the customer
promoCode	String	Promo Code

200 if successful

{
    "status": true,
    "code": 200,
    "message": "Product sale transaction has been successfully created.",
    "data": {
        "link": "https://vahlid-checkout-test.onrender.com/transaction/133qrp9n84bcixd2yq7749fm821xfd319eikdq94pv2ewfjc2n/track",
        "transaction_hash": "133qrp9n84bcixd2yq7749fm821xfd319eikdq94pv2ewfjc2n"
    }
}

Make Payment to Seller and Confirm Transactions

POST {{url}}/v2/transactions/confirm

Initiate the payment to the seller of the transaction specified by the trans_id provided in the request body, and proceed to confirm the payment and mark the transaction as complete. Return transaction data specified in the request body with is_delivery_confirmed field set to true and status set to complete.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

Request Body

Name	Type	Description
trans_id*	String	Transaction trans_id

200: OK If successful

{
    "status": true,
    "code": 200,
    "message": "success",
    "data": {
        "_id": "64775c8ebe2fa624e6c2ca77",
        "trans_id": "933283739",
        "delivery_addr": "Jos, Plateau State",
        "pay_deadline": "2023-06-02T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "buyer": {
            "_id": "64525e2c9c29739758c8dadd",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
            "username": "[e-mail]",
            "vahlid_id": "68162524",
            "email": "[e-mail]",
            "notificationToken": null
        },
        "products": [
            {
                "name": "Yam Flour",
                "prod_desc": "Perishable food",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 2500,
                "_id": "64775c8ebe2fa624e6c2ca78"
            }
        ],
        "products_price": 2500,
        "is_deposit_made": true,
        "is_delivery_made": true,
        "is_delivery_confirmed": true,
        "is_payment_reminded": false,
        "status": "completed",
        "is_service": false,
        "test": false,
        "fee": 62,
        "vendorFee": 35,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": false,
        "anonymous": "buyer",
        "currency": "NGN",
        "created_at": "2023-05-31T14:41:18.733Z",
        "updated_at": "2023-05-31T14:41:18.733Z",
        "hash": "j5mphvppbqastsiwa615f5nmxdj8acah1x8qmm9u121inwx5cz"
    }
}

404: Not Found If transaction does not exist

Confirm Transaction Delivery Made

POST {{url}}/v2/transactions/ive-delivered

Return transaction data specified in trans_id in the request body with is_delivery_made field set to true.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

Request Body

Name	Type	Description
trans_id*	String	Transaction trans_id

200: OK If successful

{
    "status": true,
    "code": 200,
    "message": "success",
    "data": {
        "_id": "64775c8ebe2fa624e6c2ca77",
        "trans_id": "933283739",
        "delivery_addr": "Jos, Plateau State",
        "pay_deadline": "2023-06-02T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151401",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "buyer": {
            "_id": "64525e2c9c29739758c8dadd",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
            "username": "toyabilo",
            "vahlid_id": "68162524",
            "email": "[e-mail]",
            "notificationToken": null
        },
        "products": [
            {
                "name": "Yam Flour",
                "prod_desc": "Perishable food",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 2500,
                "_id": "64775c8ebe2fa624e6c2ca78"
            }
        ],
        "products_price": 2500,
        "is_deposit_made": true,
        "is_delivery_made": true,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": false,
        "test": false,
        "fee": 62,
        "vendorFee": 35,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": false,
        "anonymous": "buyer",
        "currency": "NGN",
        "created_at": "2023-05-31T14:41:18.733Z",
        "updated_at": "2023-05-31T14:41:18.733Z",
        "hash": "j5mphvppbqastsiwa615f5nmxdj8acah1x8qmm9u121inwx5cz"
    }
}

Cancel Transaction

GET {{url}}/v2/transactions/cancel/:trans_id

Cancel Transaction specified in the path variable trans_id, by setting the status field to cancelled.

Path Parameters

Name	Type	Description
trans_id*	String	Transaction trans_id of the transaction to be cancelled

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK If successful

{
    "status": true,
    "code": 200,
    "message": "Transaction cancelled successfully",
    "data": {
        "dev_mode": "live",
        "_id": "61ae25afa8367b20f16d864d",
        "trans_id": "99264006",
        "delivery_addr": "Obalende",
        "pay_deadline": "2021-12-18T00:00:00.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "618559827c7b9bcfbcb8b073",
            "firstname": "Nurudeen",
            "lastname": "Qoyyum",
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1649158065/vahlid_mern/avatar/xxurbh0oyoxojxkqnydy.jpg",
            "username": "CloudNQT",
            "vahlid_id": "68985022",
            "email": "[e-mail]",
            "referralCode": "VAHL-68985022",
            "notificationToken": "fqwvH28_QWCv2bKcwECcoZ:APA91bGKSeS2gyBpwHortzTNp6O2ux2l51zbdtT0dZbc4K5idZY_fJbxfpln2ZhVwDj3o0TDBp57gLpcMNcCrNEr7Qv9wWgdbmKwziyPc52OqXX3zNQ2kHguefyTn1MpGeZzfVC6Z7wd"
        },
        "buyer": {
            "_id": "61a0d3eb780f50d2d3c0b8a1",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Qoyyum",
            "vahlid_id": "68590835",
            "email": "[e-mail]",
            "referralCode": "VAHL-68590835",
            "notificationToken": null
        },
        "products": [
            {
                "name": "Ac",
                "prod_desc": "Brand New",
                "prod_image": "https://res.cloudinary.com/vahlid/image/upload/v1638802861/vahlid_mern/transactions/aukkiphfnv5eis4lmfyq.jpg",
                "prod_price": 300,
                "_id": "61ae25afa8367b20f16d864e"
            }
        ],
        "products_price": 300,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "cancelled",
        "is_service": false,
        "test": false,
        "fee": 7,
        "vendorFee": 4.2,
        "source": "api",
        "promoPointsAwarded": false,
        "anonymous": "nil",
        "created_at": "2021-12-06T15:01:03.108Z",
        "updated_at": "2021-12-06T15:01:03.108Z",
        "hash": "i1ak1g9wgtyuby4twa4izqp53hh2nf83gvny6qyji56rpcbrty",
        "currency": "NGN"
    }
}

Product Purchase Transaction

POST {{url}}/v2/transactions/product/purchase

Make a purchase for a product. Return a new transaction data populated with buyer and seller data.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

Request Body

Name	Type	Description
currency*	String	Currency code E.g NGN, GHS
disburse*	Object	This consist of amount, currency, exchangeRate E.g: { "amount": "25000", "currency": "NGN", "exchangeRate": 1 }
vahlid_id*	String	Seller's Vahlid ID or email E.g 68985022, [e-mail]
promoCode	String	Promo code
products*	Array<Object>	List of product objects that include the name, product description, product image URL and price to be purchased. E.g [ { "name": "Cleaning", "prod_desc": "House Cleaning", "prod_image": "https://prod_image.jpeg" "prod_price": "25000" }, ],
deadline_action	String	The action to be taken when the deadline reaches. The value provided should be either nothing or delete. The default value is nothing.
pay_deadline	String	Deadline to make payment for the product E.g Wed, 7 June 2023 13:47:13 GMT
delivery_addr	String	Address where the product can be delivered.

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Product purchase transaction created successfully.",
    "data": {
        "trans_id": "TEST-816264995",
        "delivery_addr": "Jos, Plateau State",
        "pay_deadline": "2023-06-10T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "64525e2c9c29739758c8dadd",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
            "username": "toyabipo6",
            "vahlid_id": "68162524",
            "email": "[e-mail]",
            "notificationToken": null
        },
        "buyer": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151991",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "products": [
            {
                "name": "Irish Potatoes",
                "prod_desc": "Perishable food",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 5000,
                "_id": "64832fb99cffa2266474564b"
            }
        ],
        "products_price": 5000,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": false,
        "test": true,
        "fee": 225,
        "vendorFee": 70,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": false,
        "anonymous": "seller",
        "currency": "NGN",
        "_id": "64832fb99cffa2266474564a",
        "created_at": "2023-06-09T13:57:13.435Z",
        "updated_at": "2023-06-09T13:57:13.435Z",
        "hash": "5821mcxoi4vcwnkgm59owi6pk91dzxsvmpui7tjhzhorIRy597"
    }
}J

Product Sale Transaction

POST {{url}}/v2/transactions/product/sale

Make sales for a product. Return a new transaction data populated with buyer and seller data.

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

Request Body

Name	Type	Description
vahlid_id*	String	Buyer's Vahlid ID or email E.g 68985022, [e-mail]
promoCode	String	Promo code
products*	String	List of product objects that include the name, product description, product image URL and price to be purchased. E.g [ { "name": "Cleaning", "prod_desc": "House Cleaning", "prod_image": "https://prod_image.jpeg" "prod_price": "25000" }, ],
deadline_action	String	The action to be taken when the deadline reaches. The value provided should be either nothing or delete. The default value is nothing.
pay_deadline	String	Deadline to make payment for the product E.g Wed, 7 June 2023 13:47:13 GMT
disburse*	Object	This consist of amount, currency, exchangeRate E.g: { "amount": "25000", "currency": "NGN", "exchangeRate": 1 }
delivery_addr	String	Address where the product can be delivered.
currency*	String	Currency code E.g NGN, GHS

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Product sale transaction has been successfully created.",
    "data": {
        "trans_id": "TEST-503028339",
        "delivery_addr": "Jos, Plateau State",
        "pay_deadline": "2023-06-10T15:27:16.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "vicola2gmail.com",
            "referralCode": "VAHL-68152491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "buyer": {
            "_id": "64525e2c9c29739758c8dadd",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
            "username": "toyabipo1",
            "vahlid_id": "68160524",
            "email": "[e-mail]",
            "notificationToken": null
        },
        "products": [
            {
                "name": "Toy",
                "prod_desc": "Perishable toy",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 2500,
                "_id": "64833f209cffa2266474568d"
            }
        ],
        "products_price": 2500,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": false,
        "test": false,
        "fee": 62,
        "vendorFee": 35,
        "source": "developer",
        "dev_mode": "live",
        "promoPointsAwarded": false,
        "anonymous": "buyer",
        "currency": "NGN",
        "_id": "64833f209cffa2266474568c",
        "created_at": "2023-06-09T15:02:56.807Z",
        "updated_at": "2023-06-09T15:02:56.807Z",
        "hash": "jogc42w45ey2k3bpw2q578sojsmngynrk6b44hxr6y3xdt9fvj"
    }
}

Service Purchase Transaction

POST {{url}}/v2/transactions/service/purchase

Make a purchase for service(s). Return a new transaction data populated with buyer and seller data.

Query Parameters

Name	Type	Description
vahlid_id	String	Seller's Vahlid ID or email E.g 68985022, [e-mail]
promoCode	String	Promo code
products*	Array<Object>	List of product objects that include the name, product description, product image URL and price to be purchased. E.g [ { "name": "Cleaning", "prod_desc": "House Cleaning", "prod_image": "https://prod_image.jpeg" "prod_price": "25000" }, ],
deadline_action	String	The action to be taken when the deadline reaches. The value provided should be either nothing or delete. The default value is nothing.
pay_deadline	String	Deadline to make payment for the product E.g Wed, 7 June 2023 13:47:13 GMT
disburse*	Object	This consist of amount, currency, exchangeRate E.g: { "amount": "25000", "currency": "NGN", "exchangeRate": 1 }
delivery_addr	String	Address where the product can be delivered.
currency*	String	Currency code E.g NGN, GHS

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Service purchase transaction successfully created.",
    "data": {
        "trans_id": "TEST-677252295",
        "delivery_addr": "Kwali, Abuja",
        "pay_deadline": "2023-06-10T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "618559827c7b9bcfbcb8b073",
            "firstname": "Nurudeen",
            "lastname": "Qoyyum",
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1649158065/vahlid_mern/avatar/xxurbh0oyoxojxkqnydy.jpg",
            "username": "CloudNQT",
            "vahlid_id": "68985022",
            "email": "[e-mail]",
            "referralCode": "VAHL-68985022",
            "notificationToken": "fqwvH28_QWCv2bKcwECcoZ:APA91bGKSeS2gyBpwHortzTNp6O2ux2l51zbdtT0dZbc4K5idZY_fJbxfpln2ZhVwDj3o0TDBp57gLpcMNcCrNEr7Qv9wWgdbmKwziyPc52OqXX3zNQ2kHguefyTn1MpGeZzfVC6Z7wd"
        },
        "buyer": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "products": [
            {
                "name": "Lesson",
                "prod_desc": "Home lesson for kids",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 113000,
                "_id": "64833aa99cffa22664745676"
            }
        ],
        "products_price": 113000,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": true,
        "test": true,
        "fee": 2925,
        "vendorFee": 1582,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": false,
        "anonymous": "nil",
        "currency": "NGN",
        "_id": "64833aa99cffa22664745675",
        "created_at": "2023-06-09T14:43:53.092Z",
        "updated_at": "2023-06-09T14:43:53.092Z",
        "hash": "jmd123a8nz2dobtrqrjnasne2p6b7ifh73jsoxc9rg9dxi3mov"
    }
}

Service Sale Transaction

POST {{url}}/v2/transactions/service/sale

Make sales for service(s). Return a new transaction data populated with buyer and seller data.

Query Parameters

Name	Type	Description
vahlid_id	String	Buyer's Vahlid ID or email E.g 68985022, [e-mail]
promoCode	String	Promo code
products*	Array<Object>	List of product objects that include the name, product description, product image URL and price to be purchased. E.g [ { "name": "Cleaning", "prod_desc": "House Cleaning", "prod_image": "https://prod_image.jpeg" "prod_price": "25000" }, ],
deadline_action	String	The action to be taken when the deadline reaches. The value provided should be either nothing or delete. The default value is nothing.
pay_deadline	String	Deadline to make payment for the product E.g Wed, 7 June 2023 13:47:13 GMT
disburse*	Object	This consist of amount, currency, exchangeRate E.g: { "amount": "25000", "currency": "NGN", "exchangeRate": 1 }
delivery_addr	String	Address where the product can be delivered.
currency*	String	Currency code E.g NGN, GHS

Headers

Name	Type	Description
Authorization*	String	"Bearer <YOUR_API_KEY>"

200: OK Return the response below, if successful

{
    "status": true,
    "code": 200,
    "message": "Service sale transaction successfully created.",
    "data": {
        "trans_id": "TEST-520549503",
        "delivery_addr": "Otukpo, Benue State",
        "pay_deadline": "2023-06-11T13:47:13.000Z",
        "deadline_action": "nothing",
        "seller": {
            "_id": "644bb008c3c5e79ac2857cef",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": null,
            "username": "Vicolas",
            "vahlid_id": "68151491",
            "email": "[e-mail]",
            "referralCode": "VAHL-68151491",
            "notificationToken": "BBDFvCzB2w0pPh6HdHD9LEe9OsGnE6tBjEJ60gNcmMMcKFlUgmp1dMPrCYmgVFezkNBuFjapm29AOT5Ni0BRPM0",
            "terms_conditions": {
                "accepted": true,
                "meta": {
                    "transaction": "6473d45cc667f96a3eb3d9f1",
                    "accepted_date": "2023-06-08T19:29:54.963Z",
                    "_id": "64822c32c8548d4c3cff91bb"
                },
                "_id": "64822c32c8548d4c3cff91ba"
            }
        },
        "buyer": {
            "_id": "64525e2c9c29739758c8dadd",
            "firstname": null,
            "lastname": null,
            "phone": null,
            "photo": "https://res.cloudinary.com/vahlid/image/upload/v1685907632/vahlid_mern/avatar/w2yjl1o3uai5zo2zufwd.png",
            "username": "[e-mail]",
            "vahlid_id": "68162524",
            "email": "[e-mail]",
            "notificationToken": null
        },
        "products": [
            {
                "name": "Cleaning",
                "prod_desc": "House cleaning",
                "prod_image": "https://lh6.googleusercontent.com/j4GKpC0L9fQ4PoqvZuuBAkEH7qXJ-_8BI4rphOJjbJmAJptgQ3SxKAl87WvEgdqPsy3XdEnthka0u2fivk4Fot9aW9rkBEBqzwLdo_mRs2BTGbv8BuEB-0WNeq8hrpyEzneGJDZT",
                "prod_price": 5000,
                "_id": "648340c99cffa226647456a1"
            }
        ],
        "products_price": 5000,
        "is_deposit_made": false,
        "is_delivery_made": false,
        "is_delivery_confirmed": false,
        "is_payment_reminded": false,
        "status": "pending",
        "is_service": true,
        "test": true,
        "fee": 225,
        "vendorFee": 70,
        "source": "developer",
        "dev_mode": "test",
        "promoPointsAwarded": false,
        "anonymous": "buyer",
        "currency": "NGN",
        "_id": "648340c99cffa226647456a0",
        "created_at": "2023-06-09T15:10:01.220Z",
        "updated_at": "2023-06-09T15:10:01.220Z",
        "hash": "p3913ps22vt4d5chvizhdjgnqeevfcfkt3gyreayjzybh15p8s"
    }
}