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 Environment | URL |
|---|---|
| Production | https://api.flexilongtermfinance.co.nz/api/gateway/rest/v1/payment/paymentrefund |
| Sandbox | https://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_idandpassword, provided by Flexi Cards. - API key: the
api_keyFlexi 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
| Name | Type | Description |
|---|---|---|
login_id (M) | String | Merchant login ID provided by Flexi Cards |
password (M) | String | Merchant password provided by Flexi Cards |
api_key (M) | String | Key defined by Flexi Cards for this service |
merchant_id (M) | String | Merchant identifier |
merchant_transaction_id (O) | String | Your unique ID for this transaction, for example an order or invoice number |
process_no (M) | String | Hashed LTFO v2 voucher number |
refund_amount (M) | Int | Refund amount in cents. Must use the currency that matches the card (NZD) |
refund_reason (O) | String | Reason for the refund |
transmission_date_time (O) | String | Timestamp when the request is generated. Format: yyyyMMddHHmmss |
Outputs and examples
Outputs
| Name | Type | Description |
|---|---|---|
result | Result | The outcome of the request. See the Result object and Response codes below |
merchant_transaction_id | String | Your unique ID for this transaction, returned from the request |
transmission_date_time | String | Timestamp when Flexi Payment Gateway generated the response. Format: yyyyMMddHHmmss |
merchant_id | String | Merchant ID, returned from the request |
refund_transaction_id | String | Reference for the refund transaction. null if the refund was not accepted |
Result object
| Name | Type | Description |
|---|---|---|
resultCode | String | 00 is successful. Any other value is an error and you should treat the response as one |
resultDesc | String | Description 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.
| Code | Value | Description |
|---|---|---|
| 00 | ACCEPT_SUCCESSFUL | Web service was successful |
| 202 | NOT_VALID | Combination of attributes is invalid. For example, missing values in the request, or the voucher is not in a valid status |
| 203 | SYSTEM_ERROR | Unrecoverable error. If this issue persists, contact support |
| 204 | INVALID_USER_DETAIL | Either the username or password was incorrect |
| 207 | VOUCHER_NOT_FOUND | Could not find a voucher with the given process number |
| 209 | ACCESS_NOT_ALLOWED | Either the API key is invalid or the service has been disabled |
| 329 | INVALID_AMOUNT | Refund 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:
| Field | Value |
|---|---|
| Merchant ID | 12321 |
| Login ID | 203399 |
| Password | Password01 |
| GetPaymentURL Key | 2bef9740cd0be5995e58f9eef3249cabbd65d4bc |
| GetPaymentStatus Key | 2bef9740cd0be5995e58f9eef3249cabbd65d4bc |
Updated about 19 hours ago
Did this page help you?