Contents x
    Basic Auth & Signature Calculation
    • 30 Sep 2024
    • 3 Minutes to read
    • Print
    • Dark
      Light
    Contents

    Basic Auth & Signature Calculation

    • Updated on 30 Sep 2024
    • 3 Minutes to read
    • Print
    • Dark
      Light
    Article summary

    Basic Authorization

    1. Generate a Base64-encoded string: Concatenate your ClientID and ClientSecret with a colon (e.g., "ClientID:ClientSecret") and convert the resulting string to Base64 encoding. This encoded string will serve as your credentials for Basic Authorization.

    2. Include the Authorization header: In each API request, add an "Authorization" header to the request headers. The value of this header should be "Basic" followed by a space and the Base64-encoded credentials generated in the previous step.

    Example: Authorization: Basic MzoxNDU0NDlmNGUyODI0NTUyYTNl…

    By including the Basic Authorization header with the encoded credentials, you ensure that each request is properly authenticated with the provided API key and secret.

    Signature Calculation

    With every request and response Apcopay calculates and checks the signature parameter received in the header. Calculating and verifying the signature for each request and response is crucial for ensuring security and preventing any unauthorized tampering with the payload.

    By calculating the signature using a secure algorithm like HMAC SHA256 and including it in the request headers or verifying it in the received response, you can maintain the integrity and authenticity of the data exchanged between the parties involved in the payment process.

    This helps to prevent any malicious modifications to the payload and ensures a secure transaction flow. Ensuring the integrity and security of the data exchanged between your system and the gateway is of utmost importance.

    To calculate signatures for each request and verify them in the received responses, follow these steps:

    You can also see an example here.

    1. Prepare the payload

    Construct the request or response payload in the required format, adhering to the specified parameters and their values.

    2. Sort parameters

    Sort the parameters alphabetically to establish a consistent order for calculating the signature. This ensures the same result every time, regardless of parameter order. This also ensures a consistent approach across other ApcoPay interactions having different number of parameters as part of the payload.

    3. Concatenate parameters

    Concatenate the sorted parameters into a single string, separating each parameter with an ampersand (&). For example: param1=value1&param2=value2&....

    4. Convert to lowercase

    Convert the concatenated string to lowercase to maintain parsing consistency.

    5. Calculate the signature

    Apply HMAC SHA256 to the concatenated string with the signature secret key. This generates a hash value unique to the payload and secret combination.

    6. Encode as base64

    Encode the resulting hash value as a base64 string to ensure compatibility and safe representation across web systems.

    7. Include signature

    Attach the base64-encoded signature to the request as a request header (e.g., Signature) or as part of the payload, depending on the specified method.

    8. Verify the signature

    For received responses, extract the signature from the response headers or payload. Repeat steps 1 to 5 using the received parameters and the shared signature secret. Calculate the signature again and compare it with the received signature to verify the integrity of the response. More detailed explanation can be found here.

    Nested Fields
    Prefix the parent field name followed by a full stop. For example, if you have a field named "FirstName" with a parent field "ExtraData," the name would be "ExtraData.FirstName".

    Arrays
    If the JSON request includes arrays, postfix the array keys with the item index surrounded by square brackets. For example, if you have an array named "arr" with the values "value1" and "value2," the keys would be "arr[0]" and "arr[1]."

    The exact implementation details may vary based on the programming language or framework you are using. Ensure you have access to HMAC SHA256 functions and base64 encoding libraries to perform the necessary calculations.

    Sample request can be found

    here

    Based on the following JSON sample; here are the signature calculated steps

    {
    "TransactionType": "PURC",
    "Currency": "EUR",
    "Amount": "1.23",
    "OrderReference": "OREF-123",
    "UniqueReference": "9547a661-e9cd-480d-b83a-9c8d5488296812322222",
    "RedirectionURL": "https://api.dev.apspglobal.com/technicalsupporttool-fe/Redirect",
    "CallBackURL": "https://api.dev.apspglobal.com/technicalsupporttool-fe/Listener",
    "FailRedirectionURL": "https://api.dev.apspglobal.com/technicalsupporttool-fe/Redirect?page=failed",
    "Language": "en",
    "IsTest": true,
    "Routing": {
        "ForcePayment": null,
        "ForceBank": "PTEST",
        "MainAcquirer": null,
        "ForceMID": null
    },
    "AntiFraud": {
        "FraudProfile": "profile1",
        "CardRestrict": false
    },
    "Client": {
        "email": "joe.bloggs@testjb.com",
        "clientAccount": "CliAcc01002",
        "firstName": "Joe",
        "lastName": "Bloggs",
        "country": "EN",
        "mobileNo": "00441234567",
        "street": "12, High Street",
        "city": "MagicCity",
        "ZIPCode": "BGGC1234",
        "state": "UK",
        "dateOfBirth": "1977-12-31",
        "IPAddress": "127.0.0.1"
    },
    "UDF": {
        "MerchantField1": "MerchantValue 1"
    },
    "PaymentMethodData": {
        "ExampleBankParameter": "1"
    },
    "Configuration": {
        "ShowWallets": {
            "GooglePay": true,
            "ApplePay": false
        },
        "Profile": "termsandconditions",
        "AllowRetryOnFail": false,
        "ShowSavedCards": 2,
        "CardHolderNameEdit": true,
        "HidePayment": "Example1,Example1",
        "AllowAddNewCard": true
    }
}

    Name-value list of the JSON request (sorted alphabetically):

    Amount=1.23
AntiFraud.CardRestrict=false
AntiFraud.FraudProfile=profile1
CallBackURL=https://api.dev.apspglobal.com/technicalsupporttool-fe/Listener
Client.city=MagicCity
Client.clientAccount=CliAcc01002
Client.country=EN
Client.dateOfBirth=1977-12-31
Client.email=joe.bloggs@testjb.com
Client.firstName=Joe
Client.IPAddress=127.0.0.1
Client.lastName=Bloggs
Client.mobileNo=00441234567
Client.state=UK
Client.street=12, High Street
Client.ZIPCode=BGGC1234
Configuration.AllowAddNewCard=true
Configuration.AllowRetryOnFail=false
Configuration.CardHolderNameEdit=true
Configuration.HidePayment=Example1,Example1
Configuration.Profile=termsandconditions
Configuration.ShowSavedCards=2
Configuration.ShowWallets.ApplePay=false
Configuration.ShowWallets.GooglePay=true
Currency=EUR
FailRedirectionURL=https://api.dev.apspglobal.com/technicalsupporttool-fe/Redirect?page=failed
IsTest=true
Language=en
OrderReference=OREF-123
PaymentMethodData.ExampleBankParameter=1
RedirectionURL=https://api.dev.apspglobal.com/technicalsupporttool-fe/Redirect
Routing.ForceBank=PTEST
Routing.ForceMID=
Routing.ForcePayment=
Routing.MainAcquirer=
TransactionType=PURC
UDF.MerchantField1=MerchantValue 1
UniqueReference=9547a661-e9cd-480d-b83a-9c8d5488296812322222

    Lowercase concatenation:

    amount=1.23&antifraud.cardrestrict=false&antifraud.fraudprofile=profile1&callbackurl=https://api.dev.apspglobal.com/technicalsupporttool-fe/listener&client.city=magiccity&client.clientaccount=cliacc01002&client.country=en&client.dateofbirth=1977-12-31&client.email=joe.bloggs@testjb.com&client.firstname=joe&client.ipaddress=127.0.0.1&client.lastname=bloggs&client.mobileno=00441234567&client.state=uk&client.street=12, high street&client.zipcode=bggc1234&configuration.allowaddnewcard=true&configuration.allowretryonfail=false&configuration.cardholdernameedit=true&configuration.hidepayment=example1,example1&configuration.profile=termsandconditions&configuration.showsavedcards=2&configuration.showwallets.applepay=false&configuration.showwallets.googlepay=true&currency=eur&failredirectionurl=https://api.dev.apspglobal.com/technicalsupporttool-fe/redirect?page=failed&istest=true&language=en&orderreference=oref-123&paymentmethoddata.examplebankparameter=1&redirectionurl=https://api.dev.apspglobal.com/technicalsupporttool-fe/redirect&routing.forcebank=ptest&routing.forcemid=&routing.forcepayment=&routing.mainacquirer=&transactiontype=purc&udf.merchantfield1=merchantvalue 1&uniquereference=9547a661-e9cd-480d-b83a-9c8d5488296812322222

    Signature Calculation: HMACSHA256
    Secret Key: hello1

    Base64-encoded Signature: UmQW0VUkLxkTlLHmqZkFXzvYctvnXJsNw+GwPeRq4Fw=

    Add Signature as a header parameter in your POST request.



    Was this article helpful?
    What's Next