Voucher
Voucher Create
POST /voucher/create
Create a new payment voucher.
Request Body
{
"clientPaymentId": "yourid01",
"amount": "100.45",
"voucherNumber": "",
"expenseType": "",
"branchId": ""
}Request Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
clientPaymentId | string | Yes | Unique payment identifier in your system. This will be used to track and reference the payment. Must be unique across all your payments. |
amount | string | Yes | Payment amount. Must be >= 1 and can have maximum 2 decimal places (e.g., "100.45"). |
voucherNumber | string | Yes | This will be shown in marketpe app. Use a value that your users recognize. |
expenseType | string | Yes | Expense type. Must be one of the values configured in the system |
branchId | string | Yes | Branch ID. Must be one of the values configured in the system. |
Handling the response
clientPaymentId is your idempotency key. Always retry with the same clientPaymentId so a lost response never creates a duplicate voucher.
// PSEUDO CODE, NOT ACTUAL LOGIC
response = await marketpe.voucherApi.create() // send same clientPaymentId on every retry
if (response.status === 'success') {
// ✅ voucher created
return;
}
if (response.errorCode === 'failed' && response.message.includes('already exists')) {
// ✅ already created on a previous attempt — treat as success
// use `voucher/get` with the same clientPaymentId to fetch it
return;
}
if (response.errorCode === 'schema_validation_failed' || response.errorCode === 'failed') {
// ❌ voucher NOT created (bad payload, unknown branch/expenseType, etc.)
// deterministic — fix the request, do not blindly retry. details in response.message
return;
}
if (response.errorCode === 'forbidden') {
// ❌ auth/permission issue (API key, IP allow-list, or voucher access)
// do not retry in a loop
return;
}
// 🤷🏻♂️ everything else is unknown error, and you must retry
// transient — retry with backoff using the SAME clientPaymentId.
// if unsure whether it went through, use `voucher/get` to check.
return;Last updated on