x-signature

Overview

All methods in the GPAS API are protected with a signature. The signature is generated using the body content or parameters depending on the method, it will be sent as a parameter in the message header and will be in capital letters.

Example: D4327150964967774DEA583AFCDDA7FA539F4164

Purpose

The x-signature header serves several important security functions:

1. Message Integrity: Ensures that the message has not been tampered with during transmission
2. Authentication: Verifies that the message comes from a trusted source
3. Non-repudiation: Prevents the sender from denying having sent the message

Generation Process

The signature is generated using the SHA1 hashing algorithm. The input to the hash function depends on whether the request transmits data in a JSON Body or exclusively via Query Parameters:

1. Requests WITHOUT JSON Body (Signature based on Query String)

Applies to: GET methods, and POST/PATCH methods where data is sent only in the URL (e.g., Sessions, Get Balance).

1. Concatenate the full query string with the secret key.
2. Apply the SHA1 hash function to the concatenated string.
3. Convert the hash to UPPERCASE.

Example (e.g. Sessions, Get Balance):

• Query String: walletId=2sdflsd
• Secret Key: Ax34deSfgdB
• Input to SHA1: walletId=2sdflsdAx34deSfgdB
• Resulting Signature: 8F0F3379F1C6CC24DF5A4DC2A937061102487C46

2. Requests WITH JSON Body (Signature based on Body)

Applies to: POST or PATCH methods that include a JSON payload (e.g., Credit, Debit, Rollback).

1. Concatenate the raw JSON request body (as a string) with the secret key.
2. Apply the SHA1 hash function to the concatenated string.
3. Convert the hash to UPPERCASE.

Example (e.g. Credit, Debit, Rollback):

• Request Body: {"externalReference":"agt-123","value":100}
• Secret Key: Ax34deSfgdB
• Input to SHA1: {"externalReference":"agt-123","value":100}Ax34deSfgdB
• Resulting Signature: A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6Q7R8S9T0

Verification Process

When the OAS receives a request from GPAS, it should:

1. Extract the x-signature from the request headers
2. Generate the expected signature using the same process as above
3. Compare the extracted signature with the expected signature
4. If they match, process the request; if not, return a signature error

Error Handling

If the signature verification fails, the OAS should return an error response with:

• HTTP Status Code: 400
• Error Code: 1006
• Error Type: SIGNATURE_FAILED
• Message: “Signature failed”

Implementation Notes

• The secret key will be provided by GPAS during the integration process
• The signature must be in uppercase letters
• The SHA1 hash function should be used as specified
• Be careful with the encoding of the input string to ensure consistent results