Bridge
Contact us
API reference · Savings & everyday money

Vouchers

Single-use, partial and cash-pickup vouchers on a code. About vouchers Live

GET List the caller's vouchers

GET /voucher

Codes are masked. mode=SENT returns vouchers the caller issued, RECEIVED those bound to them, ALL both.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Query parameters

NameDefault
modeOptional
typeOptional
statusOptional
page0
size20

Example

Response: VoucherPageResponse

curl -X GET "https://api.bridgemoni.com/voucher?mode=value&type=value&status=value&page=0&size=20" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Vouchers retrieved successfully

POST Issue a voucher

POST /voucher

Escrows the full face value from the caller's main account up front. An ONLINE voucher is drawn once; a PARTIAL_OFFLINE voucher is a reusable code drawn down in parts at online terminals, PIN-validated on every draw. Cash vouchers use POST /voucher/cash. Omit voucherSecret to have a PIN generated - it is returned in this response only and is never retrievable again.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Example

Request body: CreateVoucherRequest · Response: VoucherResponse

curl -X POST "https://api.bridgemoni.com/voucher" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "voucherType": "ONLINE",
    "amount": 250000.0,
    "currencyCode": "NGN",
    "description": "March payroll",
    "voucherSecret": "text",
    "secretRequired": true,
    "receiverUserReference": "b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e",
    "receiverMsisdn": "+2348012345678",
    "receiverEmailAddress": "ada@example.com",
    "partialRedemptionAllowed": true,
    "maxRedemptions": 1,
    "expiryDateTime": "2027-03-14T14:30:01",
    "allowedChannels": [
      "APP"
    ],
    "idempotencyKey": "text"
  }'

Responses

StatusWhen
200Voucher created successfully

POST Issue a batch of vouchers

POST /voucher/batch

Each entry is a full independent voucher, not a denomination of a larger one. Entries are issued one at a time in their own transactions, so an entry that cannot be funded is reported under 'failures' rather than rolling back the rest. PINs are always generated here - supplying one for the whole batch is what the per-creator PIN-reuse guard exists to prevent.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Example

Request body: CreateVoucherBatchRequest · Response: VoucherBatchResponse

curl -X POST "https://api.bridgemoni.com/voucher/batch" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "voucherType": "ONLINE",
    "count": 1,
    "unitAmount": 250000.0,
    "currencyCode": "NGN",
    "purpose": "March payroll",
    "partialRedemptionAllowed": true,
    "maxRedemptions": 1,
    "secretRequired": true,
    "expiryDateTime": "2027-03-14T14:30:01",
    "allowedChannels": [
      "APP"
    ],
    "idempotencyKey": "text"
  }'

Responses

StatusWhen
200Voucher batch issued

POST Issue a cash voucher

POST /voucher/cash

For an agent who has just taken physical cash over the counter. Debits the calling agent's own main account and credits their voucher escrow, leaving them flat - the cash in the drawer is reimbursement for the float spent. At payout the escrow is debited and the redeeming agent's main credited. Restricted to agent/merchant roles; fails with INSUFFICIENT_AGENT_FLOAT if the agent is not pre-funded. A PIN is always issued and cannot be switched off - it is the only thing gating the held value, and the receiver may have no Bridge account at all.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Example

Request body: CreateCashVoucherRequest · Response: VoucherResponse

curl -X POST "https://api.bridgemoni.com/voucher/cash" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 250000.0,
    "currencyCode": "NGN",
    "receiverMsisdn": "+2348012345678",
    "receiverFirstName": "first name",
    "receiverLastName": "last name",
    "description": "March payroll",
    "voucherSecret": "text",
    "expiryDateTime": "2027-03-14T14:30:01",
    "allowedRedeemerRole": "text",
    "idempotencyKey": "text"
  }'

Responses

StatusWhen
200Cash voucher created successfully

GET Fetch a voucher by its code

GET /voucher/code/{voucherCode}

Receiver-facing and redacted - the code itself is returned masked.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
voucherCode

Example

Response: VoucherResponse

curl -X GET "https://api.bridgemoni.com/voucher/code/BRG-001" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Voucher retrieved successfully

POST Redeem a voucher

POST /voucher/redeem

Draws value out of a voucher and credits the caller's main account. For a reusable PARTIAL_OFFLINE voucher this is called once per draw with the same code and PIN; the response carries the remaining balance. Supply an idempotencyKey - it is what stops a timed-out terminal retry consuming a second slice of the remainder. Every failure returns the same generic rejection by design.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Example

Request body: RedeemVoucherRequest · Response: VoucherRedemptionResponse

curl -X POST "https://api.bridgemoni.com/voucher/redeem" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "voucherCode": "voucher code",
    "voucherSecret": "text",
    "amount": 250000.0,
    "currencyCode": "NGN",
    "payoutMode": "LEDGER",
    "channel": "APP",
    "deviceId": "a7f3-k2m9-4c1d-8e5b",
    "terminalReference": "text",
    "idempotencyKey": "text"
  }'

Responses

StatusWhen
200Voucher redeemed successfully

POST Check a voucher without redeeming it

POST /voucher/verify

Moves no money. A terminal accepting a PARTIAL_OFFLINE voucher MUST call this before charging: the face value baked into the signed QR payload goes stale as soon as the first draw lands, and only remainingAmount here is safe to charge against. An unusable voucher returns redeemable=false with no reason - a bad code, a blocked voucher and an exhausted one are deliberately indistinguishable.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live
Content-Typeapplication/json

Example

Request body: VerifyVoucherRequest · Response: VoucherVerificationResponse

curl -X POST "https://api.bridgemoni.com/voucher/verify" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV" \
  -H "Content-Type: application/json" \
  -d '{
    "voucherCode": "voucher code",
    "channel": "APP"
  }'

Responses

StatusWhen
200Voucher verified

DELETE Close a voucher

DELETE /voucher/{reference}

Terminal. Any unspent balance is returned to the creator's main account and the voucher can never be redeemed again. The row is retained for audit rather than removed.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Example

Response: VoucherResponse

curl -X DELETE "https://api.bridgemoni.com/voucher/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Voucher closed successfully

GET Fetch one of the caller's vouchers

GET /voucher/{reference}

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Example

Response: VoucherResponse

curl -X GET "https://api.bridgemoni.com/voucher/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Voucher retrieved successfully

POST Block a voucher

POST /voucher/{reference}/block

Stops redemption without releasing the escrowed value. Reversible - unblock restores the status the voucher held before, which for a part-drawn voucher is PARTIALLY_REDEEMED rather than CREATED.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Example

Response: VoucherResponse

curl -X POST "https://api.bridgemoni.com/voucher/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/block" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Voucher blocked successfully

GET Fetch a voucher's QR payload

GET /voucher/{reference}/qr

For an OFFLINE payload the embedded faceValue is what the voucher was issued for and is signed at issuance - it is NOT the spendable balance once any draw has landed. A terminal must call POST /voucher/verify for the true remaining amount.

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Example

Response: VoucherQrResponse

curl -X GET "https://api.bridgemoni.com/voucher/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/qr" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Voucher QR payload retrieved successfully

POST Unblock a voucher

POST /voucher/{reference}/unblock

Headers

NameNotes
AuthorizationBearer token
X-TenantYour tenant
X-Environmenttest or live

Path parameters

Name
reference

Example

Response: VoucherResponse

curl -X POST "https://api.bridgemoni.com/voucher/b3f1c2d4-5e6a-4b7c-8d9e-0f1a2b3c4d5e/unblock" \
  -H "Authorization: Bearer $BRIDGEMONI_TOKEN" \
  -H "X-Tenant: $BRIDGEMONI_TENANT" \
  -H "X-Environment: $BRIDGEMONI_ENV"

Responses

StatusWhen
200Voucher unblocked successfully

Generated from the OpenAPI document. Branch on the HTTP status: there is no machine-readable error code on the wire. Errors