Skip to main content
A Consumer uses an Offer in one of two ways, depending on its type. A Cashback Offer rewards them automatically when a transaction matches the Offer’s terms. A Voucher Offer is activated by purchasing a Voucher. This page covers both flows. For what happens to the Reward once it exists, see Reward lifecycle.

​
Cashback offers (automatic)

A Cashback Offer needs no action from the Consumer. Once they are enrolled in Perks, every eligible transaction the bank shares with Paylead is matched against the Consumer’s active Offers, and a match creates a Cashback Reward automatically.
1

The Consumer is enrolled in Perks

Onboarding and consent put the Consumer into the Perks service. From that point their transactions are eligible for matching.
2

The bank shares the transaction

The bank pushes the transaction to Paylead through the Share transactions flow. This is a platform-level task, independent of any single Offer.
3

Paylead matches it against active Offers

Paylead checks the transaction against the Consumer’s active Offers (Brand, amount, channel, validity, targeting).
4

A Reward is created

On a match, Paylead creates a Reward. Over 95% of Rewards reach the Pending status within 10 seconds of the transaction being shared.
There is nothing to render for the act of earning itself: the Consumer does not tap or confirm anything. Your job is to surface the resulting Reward. See Reward lifecycle for the status tracks and the list and detail endpoints.

​
Voucher offers (bought up front)

The Voucher API is in beta. The endpoints and payloads below describe the main flow; the exact fields are still subject to change.
A Voucher Offer lets the Consumer buy a prepaid value redeemable at a participating Brand. Unlike a Cashback Offer, the Consumer actively places an order and pays for it. The whole flow runs through the Paylead API: Voucher order payment no longer depends on a WebApp.

​
The purchase flow

1

Browse Voucher Offers

Voucher Offers are the VOUCHER entries in the catalog. Surface them like any other Offer (see The Offer catalog).
2

Create a Voucher Order

Place an order on the chosen Offer with POST /offers/{offer_id}/vouchers/orders. The body carries one or more amount_selections, each an amount and a quantity. The order starts in CREATED.
{
  "amount_selections": [
    { "amount": 50, "quantity": 1 }
  ]
}
3

Pay the order

Two payment models are available. Pick the one that matches your integration.
Paylead processes the payment page.
  1. Call POST /vouchers/orders/{order_id}/payments/webview to get a redirect_url.
  2. Redirect the Consumer to that payment webview.
  3. When the Consumer returns, call POST /vouchers/orders/{order_id}/payments/confirm.
4

The order completes

Once payment is confirmed, the order moves to READY and the Vouchers are issued. A failed or abandoned payment leaves the order in PAYMENT_FAILED or CANCELLED.
5

Deliver the Vouchers

List the Consumer’s Vouchers with GET /vouchers, fetch one with GET /vouchers/{voucher_id}, and download its file with GET /vouchers/{voucher_id}/pdf. Display the code, PIN, validity date, and Brand.
Code examples coming soon. The Paylead API (v2) is still under construction. Request and response examples for this section will be published once the contract is finalized. In the meantime, contact your Paylead account manager for early-access details.

​
Order states

StatusWhat it means
CREATEDOrder placed, payment not yet completed.
CONFIRMEDPayment confirmed, Vouchers being issued.
READYVouchers issued and ready to use.
PAYMENT_FAILEDPayment did not go through. No Voucher is issued.
CANCELLEDOrder cancelled before completion.

​
What a Voucher carries

FieldDescription
idUnique identifier of the Voucher.
order_idThe order the Voucher was issued from.
statusThe order status the Voucher reflects.
brandThe Brand the Voucher is redeemable at (identity, logo, color).
amountFace value of the Voucher.
valid_untilExpiry date.
pin_code_1, pin_code_2PIN codes, when the Brand uses them.
card_numberVoucher or gift card number.
card_urlLink to the Brand’s redemption page, when provided.
pdf_idIdentifier of the downloadable Voucher file.
archived_at, refunded_atWhen the Voucher was archived or refunded, if applicable.
Let the Consumer tidy their wallet by archiving used or expired Vouchers with POST /vouchers/{voucher_id}/archive, and restore them with POST /vouchers/{voucher_id}/unarchive.

​
What’s next

Reward lifecycle

Track and display the Rewards a Cashback Offer generates.

Pool & payout

How a validated Reward reaches the Consumer’s pool and gets paid out.

Webhooks reference

React to Reward and Voucher events in real time.