Re-Query Transaction

Last updated: Sep 25th, 2017

Introduction

Every one likes to be sure and concise especially when finances are involved, so doing re-query simply means this...

Merchant A: "Hello First Chekout, I just got notified of transaction XYZ. Could you please confirm that this happened?" 
... a few micro seconds later
 First Chekout: "Hi esteemed Merchant, transaction XYZ happened please feel free to give value"
You will often check your customer's transaction validity, so as to determine the next line of action as to give value or not. So this is a really important and integral part of your transaction validation. We have provided a simple REST service for us to achieve this important validation so as to ensure safe and credible business services, kindly follow the instructions below to consume this service.

Request

Type

The request type is a GET request to the host shown below

Example:

TEST: GET api/sandbox/transactions/{transaction_reference}/{hash}/query HTTP/1.1
LIVE: GET api/transactions/{transaction_reference}/{hash}/query HTTP/1.1
Host: https://bespoke.firstchekout.com/

Did you take note of the path parameters in the code block shown above, let's quickly break it down below

See the Parameters:

>>> transaction_reference
A unique identifier for each transaction, will typically look like "220-WEB-014421111-KGD"

>>> hash
A long string generated using sha512 hash algorithm of a concatenation of the transaction reference, merchant's secret and merchant's code, looks like "9ed92692c2b09b8aeb538bd23abf8fd9713defc201e8d3327afe775117f9d1e697334755bbc845f4d89abb718e1ab213bc04bcd2c8a29e99d6a0ebcfd9d9b034"

The actual request URL

TEST

https://bespoke.firstchekout.com/api/sandbox/transactions/220-WEB-014421111-KGD/9ed92692c2b09b8aeb538bd23abf8fd9713defc201e8d3327afe775117f9d1e697334755bbc845f4d89abb718e1ab213bc04bcd2c8a29e99d6a0ebcfd9d9b034/query

LIVE

https://bespoke.firstchekout.com/api/transactions/220-WEB-014421111-KGD/9ed92692c2b09b8aeb538bd23abf8fd9713defc201e8d3327afe775117f9d1e697334755bbc845f4d89abb718e1ab213bc04bcd2c8a29e99d6a0ebcfd9d9b034/query
So we got the long Hash 
<?php
//So let's get the hash in php

$transaction_reference = "220-WEB-014421111-KGD";
$merchant_secret = "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX";
$merchant_code = "XXXX";

$hash = hash('sha512', $transaction_reference . $merchant_secret . $merchant_code)
?>

Header

The request header will be of JSON Content type and will contain an api key which is the merchant's secret, provided in every merchant's dashboard, specifically on preferences page.

Example:

Content-Type: application/json
Api-Key: {MERCHANT_SECRET}

Yeah it's that simple...

Response

Type

The response follows the standard REST format which is of JSON format

Accepts: application/json

You may want to add this line to your request headers too, to state that the expected response is in JSON format

Useful Tip:

You may at some point encounter unsuccessful re-query requests, this may be due to wrong hash, merchant code or merchant secret. Hence, ensure that you always pass the correct parameters.

Body

For every successful re-query the response format will be as given below

{
    "status": true,
    "status_code": "00",
    "message": "Ok",
    "data": {
        "status": "Paid",
        "status_code": "00",
        "status_message": "Successful",
        "amount": "1605.0000",
        "amount_paid": "1605.0000",
        "payment_transaction_reference": "987715373168",
        "transaction_reference": "220-WEB-275582569-6ZM",
        "currency": "NGN",
        "transaction_date": "2017-10-29 12:14:09",
        "narration": "BAP-DSTV Access-275582569-6ZM",
        "date_created": "2017-10-29 12:14:09",
        "date_paid": 2017-10-29 12:14:10,
        "date_reversed": null
    },
    "validation":null
}
But for an invalid or unknown transaction...

{
    "status": true,
    "status_code": "00",
    "message": "Ok",
    "data": {
        "status": "Unknown",
        "status_code": "022",
        "status_message": "Unknown transaction",
        "amount": 0
    },
    "validation": null
}
You may also failed request responses like...
"Server Error: Bad Request"
"Server Error: Unknown merchant api key"
and so on... //when your hash, api key or merchant code is invalid

Tokenization

When customers decide to save their payment for future use from the checkout pop, there will be an additional object in the response, which is "mandate_token"

{
    "status": true,
    "status_code": "00",
    "message": "Ok",
    "data": {
        "status": "Reversed",
        "status_code": "03",
        "status_message": "Successful, but was reversed",
        "amount": "1605.0000",
        "amount_paid": "0.0000",
        "payment_transaction_reference": "987715373168",
        "transaction_reference": "220-WEB-275582569-6ZM",
        "currency": "NGN",
        "transaction_date": "2017-10-29 12:14:09",
        "narration": "BAP--DSTV Access-275582569-6ZM",
        "date_created": "2017-10-29 12:14:09",
        "date_paid": null,
        "date_reversed": "2017-10-29 14:53:24",
        "mandate_token": {
            "signature": "548e941c492185384ec57dbf8c7bb31d3a78051e89b699cb23c911964487f1557acab2acd208486b3259c87ee724d48a285d",
            "payload": {
                "token_id":"rR\/Gk3mTphOeOlH94rUTGg==",
                "account_number":"8087****80",
                "account_name":"Willow Friesen",
                "badge":null
            }
        }
    },
    "validation":null
}

The signature will be required when initiating direct debits. Hence, the signature returned need's to be saved against your customer, where it doesn't exist