Flexepin Merchant API

Everything you need to accept Flexepin vouchers: validate a PIN, redeem it, and handle the responses correctly.

1. What Flexepin Is

The Flexepin voucher is essentially a 16-digit code (the "PIN") that a customer enters at the merchant's checkout to deposit funds, or pay for a product or service. Each PIN is unique, single-use, and has its own fixed monetary value. Once a voucher is redeemed, the transaction is final and cannot be reversed.

A voucher's PIN can reach you one of two ways:

• Manual entry: the customer manually enters their pre-purchased 16-digit PIN at your checkout — this is the flow this document covers.
• Automatic delivery via Flexpay: the PIN is delivered directly to you via the Flexpay add-on, instead of the customer typing it in — see the Flexpay documentation for that flow.

2. General Info

Environments

Credentials

The API key & secret, and Back Office (Merchant Portal) credentials, are provided by the Flexepin support team.

The production credentials will be shared after the integration has been completed and a commercial agreement has been put in place.

Support

If you need your credentials reset or for any other help, contact support@flexepin.com.

3. Integration at a Glance

4. Try It Live

Before writing any code, you can generate real test vouchers and submit them for validation and redemption through the interactive demo site — it shows you the actual request and response for every API call.

https://demo.staging.flexepin.com/

Prefer to test in Postman?

Download the collection below and import it — it includes Validate, Redeem, and the transaction lookup requests, all with the HMAC signature computed for you automatically before each send. Just set your API Key, Merchant Secret, and a test PIN in the collection's Variables tab.

⬇ flexepin_merchant_api.postman_collection.json

5. Validate & Redeem APIs, Side by Side

Confirmed: reusing the same current_transaction_id on repeated Validate calls does not cause any issue and does not affect redemption.

Validate — response example

See Section 7 for a complete, runnable Validate request.

{
  "result": "0",
  "result_description": "Success",
  "serial": "54040500000303719",
  "currency": "EUR",
  "description": "Flexepin EUR 100",
  "value": 100
}

Redeem — response example

See Section 7 for a complete, runnable Redeem request.

{
  "result": "0",
  "result_description": "Success",
  "transaction_id": "..."
}

6. Authentication (HMAC)

Every request must prove it genuinely came from you, but without ever sending your secret key over the network. Instead, each request carries a one-time "signature" — built from the request itself plus your secret key — that Flexepin recalculates on their end to confirm it matches. This applies to both the Validate and Redeem calls you just saw above.

The header

AUTHENTICATION: HMAC [api_key]:[signature]:[nonce]

Building the signature

Concatenate these four items with a newline (\n) between each, then compute a SHA-256 HMAC of the result, keyed with your Merchant Secret:

Request Method
URI Endpoint
nonce
Request body

If there's no body, leave it empty — but the newline before it must still be there.

Worked example

This is a signed Redeem request, using the URL shape from Section 5:

7. Starter Code

Complete, working functions for Validate and Redeem — not a template with a gap where the signature should go. Swap in your real PIN, API Key, and Merchant Secret before using it.

8. Flexepin Voucher Currencies & Types

The various Flexepin currencies fall into two types.

Note: If you are not sure which currencies you should implement — confirm this with your team. Implementing EUR and CAD covers all scenarios from a technical point of view.

• The end user sees no difference in the validation/redemption between the 2 types.
• The Validation/Redemption API requests are the same between the 2 types.
• Only a small difference exists in the API responses between the 2 types.

Voucher handling as per Voucher type

Closed Loop:

When EUR, GBP, PLN & CHF vouchers are submitted to the Validate API they come back as having the 'Quarantine' status — this is expected, not an error, proceed to redemption.

When a closed loop voucher is submitted to the Redeem API, it is automatically swapped in the background (by the Flexepin system) for an equivalent Active status voucher, and that one is redeemed toward the merchant instead. The redeemed voucher takes on the status of 'Used'.

Open Loop:

When CAD, USD, NZD, ZAR vouchers are submitted to the Validate API they come back as having the 'Active' status — proceed to redemption.

When an open loop voucher is submitted to the Redeem API, the same voucher is redeemed towards the merchant and takes on the status of 'Used'.

9. Result Codes

Success / still valid

Errors

10. Flexepin Terms & Conditions Acceptance by the User

Required on any screen where a customer enters or submits a Flexepin PIN:

• A Terms & Conditions checkbox, unchecked by default
• The user must manually check it before proceeding — if it is left unchecked, the customer must not be able to continue with the transaction
• The site may remember the user's selection for future transactions
• "Flexepin Terms & Conditions" as a hyperlink opening in a new tab
• On hover: "By checking, you acknowledge that you have read, understood, and agree to be bound by the Terms and Conditions associated with the use of a Flexepin voucher. Acceptance is necessary to access and utilise our offerings."

Live example

Reference implementation

<div class="flexepin-tc">
  <input type="checkbox" id="tcdemo">
  <label for="tcdemo">
    I agree to the <a href="https://www.flexepin.com/flexepin-terms-and-conditions-eea/" target="_blank">Flexepin Terms &amp; Conditions</a>
  </label>
</div>

11. Reference Appendix

All endpoints

Common parameters