Payment Refund

The Payment Refund API refunds an LTFO v2 transaction in full or in part, with a single POST request from your own system.

Q EnvironmentURL
Productionhttps://api.flexilongtermfinance.co.nz/api/gateway/rest/v1/payment/paymentrefund
Sandboxhttps://api.flexilongtermfinance.co.nz/api/simulator/gateway/rest/v1/payment/paymenturl

It sits alongside the existing LTFO v2 payment APIs and works on the voucher the original transaction created, which you identify with its hashed process_no.

Before you start

You need these details to build a request:

  • Merchant credentials: your login_id and password, provided by Flexi Cards.
  • API key: the api_key Flexi Cards defines for this service.
  • Merchant ID: your merchant_id.
  • Voucher number: the hashed LTFO v2 voucher number (process_no) of the transaction you are refunding.
  • Refund amount: in cents, in the currency of the card (NZD).

Credentials go in the request body, not in headers.

Request method and inputs

POST

The API supports both full and partial refunds, set by refund_amount.

M = Mandatory, O = Optional

NameTypeDescription
login_id (M)StringMerchant login ID provided by Flexi Cards
password (M)StringMerchant password provided by Flexi Cards
api_key (M)StringKey defined by Flexi Cards for this service
merchant_id (M)StringMerchant identifier
merchant_transaction_id (O)StringYour unique ID for this transaction, for example an order or invoice number
process_no (M)StringHashed LTFO v2 voucher number
refund_amount (M)IntRefund amount in cents. Must use the currency that matches the card (NZD)
refund_reason (O)StringReason for the refund
transmission_date_time (O)StringTimestamp when the request is generated. Format: yyyyMMddHHmmss

Outputs and examples

Outputs

NameTypeDescription
resultResultThe outcome of the request. See the Result object and Response codes below
merchant_transaction_idStringYour unique ID for this transaction, returned from the request
transmission_date_timeStringTimestamp when Flexi Payment Gateway generated the response. Format: yyyyMMddHHmmss
merchant_idStringMerchant ID, returned from the request
refund_transaction_idStringReference for the refund transaction. null if the refund was not accepted

Result object

NameTypeDescription
resultCodeString00 is successful. Any other value is an error and you should treat the response as one
resultDescStringDescription of the code

Example request

{
    "login_id": "YOUR_LOGIN_ID",
    "password": "YOUR_PASSWORD",
    "api_key": "YOUR_API_KEY",
    "merchant_id": "12321",
    "merchant_transaction_id": "123",
    "process_no": "YOUR_HASHED_VOUCHER_NUMBER",
    "refund_amount": 1000,
    "refund_reason": "This is a faulty item",
    "transmission_date_time": "20260202150306"
}

Example response - successful

{
    "result": {
        "resultCode": "00",
        "resultDesc": "ACCEPT_SUCCESSFUL"
    },
    "merchant_transaction_id": "123",
    "transmission_date_time": "20260202150306",
    "merchant_id": "12321",
    "refund_transaction_id": "1234567890"
}

Example response - unsuccessful

{
    "result": {
        "resultCode": "202",
        "resultDesc": "NOT_VALID"
    },
    "merchant_transaction_id": "123",
    "transmission_date_time": "20260202150306",
    "merchant_id": "12321",
    "refund_transaction_id": null
}

Response codes

Only 00 means the refund was accepted. Treat every other code as an error.

CodeValueDescription
00ACCEPT_SUCCESSFULWeb service was successful
202NOT_VALIDCombination of attributes is invalid. For example, missing values in the request, or the voucher is not in a valid status
203SYSTEM_ERRORUnrecoverable error. If this issue persists, contact support
204INVALID_USER_DETAILEither the username or password was incorrect
207VOUCHER_NOT_FOUNDCould not find a voucher with the given process number
209ACCESS_NOT_ALLOWEDEither the API key is invalid or the service has been disabled
329INVALID_AMOUNTRefund amount is not greater than zero, or the refund is more than the original transaction

Testing

Should you require testing of the plugin prior to pushing to your live site, please use the following details:

FieldValue
Merchant ID12321
Login ID203399
PasswordPassword01
GetPaymentURL Key2bef9740cd0be5995e58f9eef3249cabbd65d4bc
GetPaymentStatus Key2bef9740cd0be5995e58f9eef3249cabbd65d4bc

Did this page help you?