Proxy

Proxy and Authentication

Overview

This API includes a secure proxy mechanism used to forward structured requests to other internal microservices. It allows clients to interact through a unified interface while delegating processing to specialized services behind the scenes.

The process ensures payload integrity, traceability, and seamless communication across microservices.

CustomerId Field

The CustomerId represents the unique identifier of the end user in our system. It is used to:

Link the request to a known customer

Enable request tracking and auditing

Enforce data consistency across services

Step 1: Request Signing

Before forwarding a request, the system computes an HMAC-SHA256 signature using the full request body and a private signing key shared only between internal services.

This signature is then added as a custom HTTP header.

Signature Header

JSON

Content-Type: application/json  
X_msg_signature: dce46aa67df3c0d7c65d8c6e924f8fced23e1ac07a4e1cb356c80e9fddf7c32a

Step 2: Proxy Execution

Once signed, the request is forwarded to the target microservice via HTTP POST. The proxy process is entirely transparent to the client.

Flow Summary

1. The client sends a request (often in XML-RPC format).
2. The request is internally wrapped into a JSON structure.
3. The full JSON body is signed and sent to a configured internal endpoint.
4. The response is received, parsed, and saved.
5. A normalized response is returned to the client.

Business Logic Errors Handling

Any issues related to business logic—such as insufficient balance, payment delays, or other domain-specific conditions—should be returned as a successful HTTP response with** status code 200**, accompanied by the appropriate error details in the response body.

Standard HTTP errors related to client or server faults (e.g., 400 Bad Request, 401 Unauthorized, 500 Internal Server Error) will be returned as usual.

Proxy Flow Example

Step A: Client Request (XML-RPC)

XML

<methodCall>
  <methodName>Deduct</methodName>
  <params>
    <param><value><string>terminal_01</string></value></param>
    <param><value><string>txn_987</string></value></param>
    <param><value><int>500</int></value></param>
  </params>
</methodCall>

Step B: Transformed Proxy Request (JSON)

JSON

{
  "Payload": "<methodCall>...</methodCall>",
  "CustomerId": 12345
}

Note: Payload contains the full XML-RPC request as a string.

Step C: Outgoing Proxy Request

bash

POST /internal/proxy-endpoint HTTP/1.1  
Content-Type: application/json  
X_msg_signature: <generated-signature>

{ ...JSON payload... }

Sample Response Received

JSON

{
  "Status": "Approved",
  "Reference": "abc123",
  "Amount": 500
}

Standard REQUEST

Path Parameters

Parameter	Type & Constraints	Description
terminalID	string, 10 characters, required	Our partner-issued terminal ID of the terminal requesting the transaction
reference	string, 1–255 characters, required	The reference of the wallet to retrieve the balance for
narrative	string, 1–255 characters, required	A description of the terminal where the card was used
transactionData	string, 0–2048 characters, required	Extra information about the transaction in a KLV Lookup
transactionID	string, 1–255 characters, required	Transaction ID generated by the client. Not guaranteed to be unique and may be reused over time
transactionDate	date, required	Transaction date generated by the calling client
checksum	string, required	HMAC-SHA256 hash of the concatenated method name + arguments, using the terminal password as private key