post
https://api.myvendy.com/transactions/initiate
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Sends a payment request to your customer and creates a pending transaction. The customer completes it on the checkout channel you choose.
Request:
| Field | Type | Required | Description |
|---|---|---|---|
| amount | Number | Yes | The amount to collect. Must be greater than zero |
| msisdn | String | One of msisdn or email | Customer phone number with country code, for example 2348012345678 |
| String | One of msisdn or email | Customer email | |
| channel | Enum (String) | No | How the customer is asked to pay: whatsapp, ussd, telegram or web. Defaults to web. See checkout channels |
| currency | String | No | ISO 4217 code, for example NGN. Defaults to your business currency |
| expiry | String | No | ISO 8601 date-time when the request expires, at least 2 minutes in the future, for example 2026-11-01T12:00:00Z |
| product | Enum (String) | No | What the customer is paying for: transactions, events, foods, retail, services, reservations or vendings. Defaults to transactions |
| walletId | Integer | No | Wallet to credit. Its currency must match currency |
| refid | String | No | Your own reference for this payment |
| message | String | No | Message shown to the customer |
| device | Enum (String) | No | Customer's device: android, ios or web |
| charge_customer | Boolean | No | Add Vendy's fee to the amount the customer pays |
| channel_fee_charge_customer | Boolean | No | Add the channel fee to the amount the customer pays. Only applies when charge_customer is also sent |
| meta | JSON Object | No | Any extra data to store with the transaction. It's returned in webhooks |
| businessId | Integer | No | Ignored when you use API keys. See Authentication |
Example request
curl --location 'https://api.myvendy.com/transactions/initiate' \
--header 'Content-Type: application/json' \
--header "AccessKey: $VENDY_ACCESS_KEY" \
--header "SecretKey: $VENDY_SECRET_KEY" \
--data '{
"amount": 100,
"msisdn": "2348012345678",
"channel": "whatsapp",
"meta": {
"email": "[email protected]",
"narration": "Order 1042",
"custom_field": "custom field"
}
}'Response:
| Field | Type | Description |
|---|---|---|
| status | Boolean | States if request was successfully executed or not |
| code | Integer | Internal code, success if 200 |
| msg | String | A description of the status of the request |
| data | Transaction | Newly initiated transaction details |
Example response
{
"status": true,
"code": 200,
"msg": "Transaction Sent",
"error": "Transaction Sent",
"data": {
"vended": "-1",
"reversed": "-1",
"debited": "-1",
"isreversing": "-1",
"processing": "-1",
"flag": "-1",
"id": 605513775,
"uid": 1,
"businessId": "1",
"msisdn": "2348012345678",
"requestamount": 100,
"amount": 100,
"method": "whatsapp",
"currency": "NGN",
"refid": "4930517800770623045",
"failed": -1,
"delivered": -1,
"meta": {
"email": "[email protected]",
"custom_field": "custom field",
"narration": "Order 1042",
"fee": 0,
"commission": 0,
"charge_customer": false,
"total": 100
},
"walletId": 1689,
"commissionWallet": 1690,
"staffId": null,
"updated_on": "2026-10-20T15:37:50.523Z",
"created_on": "2026-10-20T15:37:50.523Z"
}
}Possible errors
| Error code | Description |
|---|---|
204 | Input is invalid. data lists each field, for example msisdn or email must be specified |
217 | Wallet not supported. You have no wallet in this currency |
306 | Transaction failed. Please try again later |
326 | Business not found |
338 | Amount above or below your transaction limit |
360 | Wallet blocked no inflow activity allowed |
361 | Service is currently unavailable |
438 | The customer is no longer allowed to transact |