Picture

Calculating Request Signatures - Payment Processing

To ensure that the API requests have been issued by valid users, messages must be signed.  The Signature field is calculated by concatenating the Security token with the contents of the Request node (represented as a string) and calculating a SHA2-512 hash of that concatenated string.

The signature must be correct to receive a non-error response.  Repeated use of an incorrect signature will lock out the ApiKey, and an administrator will need to unlock it.

 Using the following example ApiKey and Security Token:

ApiKey: 12345678-1234-1234-1234-1234567890ab
Security Token:
3031E5834AAD94B05C563292E6590ED13336501627EF1248036838C9BEBC08226A030134B3D791B488C086A97EA521FB192BD578CD 41583DCB6DC21A896A497E

 

…we can create a message to send to the Capture command to capture funds previously authorised on a transaction with ID 2345678.  To do this, we create the following “Request” node:

"Request": {"TransactionId": 2345678}

We then pre-pend the security token to the contents of the “Request” node: 

3031E5834AAD94B05C563292E6590ED13336501627EF1248036838C9BEBC08226A030134B3D791B488C086A97EA521FB192BD578CD 41583DCB6DC21A896A497E"TransactionId": 2345678

And calculate the SHA2-512 hash of that string: 

13D8C822AE18AD0A023806A3225682DC22C652D2514498E5DEDC050BD35B1F11BB53BD73F78EA3A631C446253D7DFF87F0DAD6DA54 3E84711A9A3C68352D741D

 

Then build the Capture message with the Version, ApiKey, Request node and the above result as the Signature:

{
    "Version": "1.1",
    "ApiKey": "12345678-1234-1234-1234-1234567890ab",     "Request": {"TransactionId": 2345678},
    "Signature":
"13D8C822AE18AD0A023806A3225682DC22C652D2514498E5DEDC050BD35B1F11BB53BD73F78EA3A631C446253D7DFF87F0DAD6DA5
43E84711A9A3C68352D741D"
  }

On the Cashflows Sandbox environment, this would be POSTed to:

https://integration.cashflows.com/payments/capture/

Below is the same example but in XML.

 XML Request node:

 <Request>
  <TransactionId>2345678</TransactionId>
</Request>

 

Now with the password hash pre-pended the string looks like this (IMPORTANT NOTE in this example there is whitespace and linefeeds, and these are included in the Hash calculation!):

 3031E5834AAD94B05C563292E6590ED13336501627EF1248036838C9BEBC08226A030134B3D791B488C086A97EA521FB192BD578CD
41583DCB6DC21A896A497E
  <TransactionId>2345678</TransactionId> 

 

Which produces a SHA2-512 Hash of: 

EAC92EE0431CC72192D1D4272E1B4A0CC29F209FA9C65F906D88629F69F60B3D827BAF09A35627AED47091A3B7EC5D8311445499D1 5D6315C108530177BE92AE

So, with the other required fields added, the body POSTed to the Capture command URI would be:

 <Version>1.1</Version>
<ApiKey>12345678-1234-1234-1234-1234567890ab</ApiKey>
<Request>
  <TransactionId>2345678</TransactionId>
</Request>
<Signature>EAC92EE0431CC72192D1D4272E1B4A0CC29F209FA9C65F906D88629F69F60B3D827BAF09A35627AED47091A3B7EC5D8 311445499D15D6315C108530177BE92AE</Signature>

For JSON requests (like the examples in this document) the request string to be hashed begins after the { following the word “Request” and ends at the } at the end of the node.  The open and close curly brackets {} should not be included in the hash calculation.

For XML requests, the request string starts after the > of <Request> and ends at the < of </Request>.  Again the close and open angled brackets >< should not be included in the hash calculation.

IMPORTANT: All whitespace and new lines within the request nodes will be included in the calculation of the Hash Value. Cashflows uses CR-LF for line breaks; Unix systems often use just LF, and this can affect calculations.  If you are unable to match signatures with the Payments API and have the correct Security token and ApiKey, consider removing unnecessary whitespace from your Request nodes.