Online API Signing Mechanisms

Signing mechanism (Request Body)#

When creating a sale, the request needs to contain a signature parameter that is signed using HMAC-SHA256. This is to ensure that the request hasn’t been tampered with and that the request originated from the correct signing authority. Using the client_secret that was supplied to the merchant.

The signing mechanism is done as follows:

1. Using this sample sale detail#

{
    "customer": {
        "mobileNumber": "02222222620",
        "firstName": "John",
        "surname": "Doe",
        "email": "jd@genoapay.com",
        "address": {
            "addressLine1": "124 Fifth Avenue",
            "suburb": "Hobsonville",
            "cityTown": "Auckland",
            "state": "Auckland",
            "postcode": "0618",
            "countryCode": "NZ"
        },
        "dateOfBirth": "1987-10-17"
    },
    "shippingAddress": {
        "addressLine1": "Unit F, 16 Workday Drive",
        "suburb": "Albany",
        "cityTown": "Auckland",
        "state": "Auckland",
        "postcode": "0751",
        "countryCode": "NZ"
    },
    "billingAddress": {
        "addressLine1": "124 Fifth Avenue",
        "suburb": "Hobsonville",
        "cityTown": "Auckland",
        "state": "Auckland",
        "postcode": "0618",
        "countryCode": "NZ"
    },
    "products": [
        {
            "name": "Tennis Ball Multipack",
            "price": {
            "amount": 30,
            "currency": "NZD"
        },
        "sku": "abc123",
        "quantity": 1,
        "taxIncluded": true
        }
    ],
    "shippingLines": [
        {
            "carrier": "NZ Post",
            "price": {
                "amount": 5.50,
                "currency": "NZD"
            }
        }
    ],
    "taxAmount": {
        "amount": 5.325,
        "currency": "NZD"
    },
    "reference": "INV000045",
    "totalAmount": {
        "amount": 35.5,
        "currency": "NZD"
    },
    "returnUrls": {
        "successUrl": "http://genoapay.com/success",
        "failUrl": "http://.genoapay.com/fail",
        "callbackUrl": "http://genoapay.com/fail-safe-callback"
    }
}

2. Strip out the json formatting, leaving only keys and values#

customermobileNumber02222222620firstNameJohnsurnameDoeemailjd@genoapay.comaddressaddressLine1124FifthAvenuesuburbHobsonvillecityTownAucklandstateAucklandpostcode0618countryCodeNZdateOfBirth1987-10-17shippingAddressaddressLine1UnitF,16WorkdayDrivesuburbAlbanycityTownAucklandstateAucklandpostcode0751countryCodeNZbillingAddressaddressLine1124FifthAvenuesuburbHobsonvillecityTownAucklandstateAucklandpostcode0618countryCodeNZproductsnameTennisBallMultipackpriceamount30currencyNZDskuabc123quantity1taxIncludedtrueshippingLinescarrierNZPostpriceamount5.50currencyNZDtaxAmountamount5.325currencyNZDreferenceINV000045totalAmountamount35.5currencyNZDreturnUrlssuccessUrlhttp://genoapay.com/successfailUrlhttp://.genoapay.com/failcallbackUrlhttp://genoapay.com/fail-safe-callback

3. Encode the resulting string to Base64#

Y3VzdG9tZXJtb2JpbGVOdW1iZXIwMjIyMjIyMjYyMGZpcnN0TmFtZUpvaG5zdXJuYW1lRG9lZW1haWxqZEBnZW5vYXBheS5jb21hZGRyZXNzYWRkcmVzc0xpbmUxMTI0RmlmdGhBdmVudWVzdWJ1cmJIb2Jzb252aWxsZWNpdHlUb3duQXVja2xhbmRzdGF0ZUF1Y2tsYW5kcG9zdGNvZGUwNjE4Y291bnRyeUNvZGVOWmRhdGVPZkJpcnRoMTk4Ny0xMC0xN3NoaXBwaW5nQWRkcmVzc2FkZHJlc3NMaW5lMVVuaXRGLDE2V29ya2RheURyaXZlc3VidXJiQWxiYW55Y2l0eVRvd25BdWNrbGFuZHN0YXRlQXVja2xhbmRwb3N0Y29kZTA3NTFjb3VudHJ5Q29kZU5aYmlsbGluZ0FkZHJlc3NhZGRyZXNzTGluZTExMjRGaWZ0aEF2ZW51ZXN1YnVyYkhvYnNvbnZpbGxlY2l0eVRvd25BdWNrbGFuZHN0YXRlQXVja2xhbmRwb3N0Y29kZTA2MThjb3VudHJ5Q29kZU5acHJvZHVjdHNuYW1lVGVubmlzQmFsbE11bHRpcGFja3ByaWNlYW1vdW50MzBjdXJyZW5jeU5aRHNrdWFiYzEyM3F1YW50aXR5MXRheEluY2x1ZGVkdHJ1ZXNoaXBwaW5nTGluZXNjYXJyaWVyTlpQb3N0cHJpY2VhbW91bnQ1LjUwY3VycmVuY3lOWkR0YXhBbW91bnRhbW91bnQ1LjMyNWN1cnJlbmN5TlpEcmVmZXJlbmNlSU5WMDAwMDQ1dG90YWxBbW91bnRhbW91bnQzNS41Y3VycmVuY3lOWkRyZXR1cm5Vcmxzc3VjY2Vzc1VybGh0dHA6Ly9nZW5vYXBheS5jb20vc3VjY2Vzc2ZhaWxVcmxodHRwOi8vLmdlbm9hcGF5LmNvbS9mYWlsY2FsbGJhY2tVcmxodHRwOi8vZ2Vub2FwYXkuY29tL2ZhaWwtc2FmZS1jYWxsYmFjaw==

4. Compute the HMAC using SHA256 digest algorithm#

Assuming the client_secret is 1y02Nwqzj1FbznAw, you will end up with:

81ddf72b57031a0b956cc368edac0fcd51d6669a4a0b82cd7aeb3b17e2712389

Payment Responses#

When the LatitudePay/Genoapay payment has been completed or cancelled, the customer is redirected to the merchant site and an asynchronous response is sent to the callback url specified in Create Payment request under returnUrls (if specified).

The request parameters with the payment result are appended to the end of the callback url.

Example query parameter string

token=8dddcfe6-eeb4-4a2a-8290-e0afc0e90ef5&reference=b2fdf124d010acc2482b44eb54a18954&message=Account+active&result=COMPLETED&signature=1aeabecfef0c82ebe9f64e110ae7e0e5b69215a0aab0470eaaaced26bdef482e

This query parameters are signed and should be verified by the API consumer to ensure that the response has not been tampered with, and that it originated from the LatitudePay/Genoapay system.

Using the client_secret that was supplied to the merchant, the signing mechanism can be verified using the following steps:

1. Using the query parameters in the order provided, extract all query parameters except the signature itself#

token=8dddcfe6-eeb4-4a2a-8290-e0afc0e90ef5&reference=b2fdf124d010acc2482b44eb54a18954&message=Account+active&result=COMPLETED

2. Unescape the parameters and remove the query parameter delimiters#

token8dddcfe6-eeb4-4a2a-8290-e0afc0e90ef5referenceb2fdf124d010acc2482b44eb54a18954messageAccount activeresultCOMPLETED

3. Strip any white space from the resulting string#

token8dddcfe6-eeb4-4a2a-8290-e0afc0e90ef5referenceb2fdf124d010acc2482b44eb54a18954messageAccountactiveresultCOMPLETED

4. Encode the resulting string to Base64#

dG9rZW44ZGRkY2ZlNi1lZWI0LTRhMmEtODI5MC1lMGFmYzBlOTBlZjVyZWZlcmVuY2ViMmZkZjEyNGQwMTBhY2MyNDgyYjQ0ZWI1NGExODk1NG1lc3NhZ2VBY2NvdW50YWN0aXZlcmVzdWx0Q09NUExFVEVE

5. Compute the HMAC using SHA256 digest algorithm#