Flow Overview

Proxy and Authentication

Overview

This API includes a secure 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

Content-Type: application/json  
X_msg_signature: dce46aa67df3c0d7c65d8c6e924f8fced23e1ac07a4e1cb356c80e9fddf7c32a

Step 2: Execution

Once signed, the request is forwarded to the target microservice via HTTP POST.

Flow Summary

The client sends a request (which can be in JSON or XML-RPC format).
The request is internally wrapped into a JSON structure(in case of XML-RPC format).
The full JSON body is signed and sent to a configured internal endpoint.
The response is received, parsed, and saved.
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.

Flow Example

Step A: Client Request (XML-RPC or JSON format)

<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>

{
"request":{
  "terminal_id":"0022436681",
  "reference":"41HOWu4ObRXulc1LLeBgBA==",
  "request_amount":60000,
  "narrative":"ST*UBER EATS           CIUDAD DE MEX MEX",
  "transaction_type":"00",
  "transaction_id":"peibo-proxy-deduct-017",
  "checksum":"AC98BEE8C137C04F3C32DB71EC4F1A3741462A9C280C7501FC724B2115F87DB3",
  "method_name":"Deduct",
  "transaction_data":{
    "tracking_number":"268436100000999",
    "original_transaction_amount":"000001203480",
    "merchant_category_code":"6011",
    "acquiring_institution_code":"25919",
    "retrieval_reference_number":"9347        ",
    "terminal_id":"N51375  ",
    "merchant_identifier":"HUBSITE MEXICO ",
    "fraud_scoring_data":"0103001020258",
    "original_currency_code":"484",
    "trace_id":"MCBNQSHO80325",
    "is_recurring":"0",
    "capture_mode":"EMV",
    "network":"MasterCard",
    "fee_type":"0",
    "last_four_digits_pan":"6853",
    "markup_type":"0",
    "acquirer_country":"MEX",
    "transaction_fee_amount":"0"
  },
  "transaction_date":"20220120T09:15:21"
},
 "customer_id":100,
 "card_id":2613,
 "request_id":"2613_20260330155949_8674665223082153551"
}

Different types of requests can be processed through this flow. Each request is described in the Transactions section.

Step B: Transformed Request (JSON in case of XML-RPC format)

{
  "request": {"terminalID"...},
  "customer_id":100,
  "card_id":2613,
  "request_id":"2613_20260330155949_8674665223082153551"
}

Note: Payload contains a JSON object in the request field.

Step C: Outgoing Proxy Request

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

Sample Response Received

{
"status":"success",
"message":"",
"customerId":2,
"response":"<methodResponse><params><param><value><struct><member><name>resultCode</name><value><int>1</int></value></member></struct></value></param></params></methodResponse>"}

{
  "status":"success",
  "message":"success",
  "customer_id": 2,
  "response":{
    "resultCode":1
  }
}

Standard Requests

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

Example Requests

<?xml version="1.0"?>
<methodCall>
  <methodName>Balance</methodName>
  <params>
    <param>
      <value><string>0029504320</string></value>
    </param>
    <param>
      <value><string>556789731480</string></value>
    </param>
    <param>
      <value><string>STARBUCKS HANOI VNM</string></value>
    </param>
    <param>
      <value><string>0021576138...</string></value>
    </param>
    <param>
      <value><string>415099</string></value>
    </param>
    <param>
      <value><dateTime.iso8601>20200824T14:17:06</dateTime.iso8601></value>
    </param>
    <param>
      <value><string>46719079...</string></value>
    </param>
  </params>
</methodCall>

{
"request":{
  "terminal_id":"0029504320",
  "reference":"556789731480",
  "request_amount":60000,
  "narrative":"STARBUCKS HANOI VNM",
  "transaction_type":"00",
  "transaction_id":"peibo-proxy-deduct-017",
  "checksum":"AC98BEE8C137C04F3C32DB71EC4F1A3741462A9C280C7501FC724B2115F87DB3",
  "method_name":"Balance",
  "transaction_data":{
    "tracking_number":"268436100000999",
    "original_transaction_amount":"000001203480",
    "merchant_category_code":"6011",
    "acquiring_institution_code":"25919",
    "retrieval_reference_number":"9347        ",
    "terminal_id":"N51375  ",
    "merchant_identifier":"HUBSITE MEXICO ",
    "fraud_scoring_data":"0103001020258",
    "original_currency_code":"484",
    "trace_id":"MCBNQSHO80325",
    "is_recurring":"0",
    "capture_mode":"EMV",
    "network":"MasterCard",
    "fee_type":"0",
    "last_four_digits_pan":"6853",
    "markup_type":"0",
    "acquirer_country":"MEX",
    "transaction_fee_amount":"0"
  },
  "transaction_date":"20220120T09:15:21"
},
 "customer_id":100,
 "card_id":2613,
 "request_id":"2613_20260330155949_8674665223082153551"
}