Merchant-Controlled Transaction Registration

This flow outlines the interaction among the client (payer), Paytiko & Merchant Server, detailing the process of registrating a payment transaction before processing on the payment system side.

The goal is to ensure that the transaction meets all necessary criteria before proceeding to authorization, and to handle any potential rejections in a structured manner. This setup prevents immediate requests to the payment system until the transaction is properly validated, adding an additional layer of control.

Purpose

• Validation Control: Before the transaction reaches external payment systems, the webhook mechanism between Paytiko and Merchant Server allows for internal registration (validation), either to register or disapprove the transaction based on the provided details.

• Flexible Response: The system can decide whether to proceed with the transaction based on analysis (such as fraud checks or compliance) and communicate this decision to Paytiko without involving the payment systems prematurely.

Prerequisites

The merchant must specifically request this feature, and it needs to be enabled by Paytiko (starting in the UAT environment before moving to production).

Additionally, the merchant will require the following keys issued by Paytiko:

1. MERCHANT_SECRET_KEY_ISSUED_BY_PAYTIKO

2. PAYTIKO_WHR_HOST

Flow Steps

1. The client enters payment details on the widget and clicks the Pay button

2. Initial Request to Paytiko A payment request is sent to Paytiko, and the widget enters Standby mode.

   Paytiko does not forward the request to external payment systems at this point.

3. Webhook from Paytiko to Merchant Server

   Paytiko sends a webhook to Merchant Server, similar to a regular callback but action type is "TRANSACTION_REGISTRATION" (for regular one "TRANSACTION_DATA_UPDATE" is used).

   Webhook sample:

   {
     "Action": "TRANSACTION_REGISTRATION",
     "ActionId": "abeb6075-8e09-4d95-816c-507648ae41e1",
     "OrganizationId": 17,
     "OrderId": "e7713563-fb75-4a57-a506-42a87037e16b",
     "AccountId": "[e-mail]-USD",
     "AccountDetails": {
       "MerchantId": 99800,
       "CreatedDate": "2024-01-06T15:21:46.752037+00:00",
       "FirstName": "John",
       "LastName": "Doe",
       "Email": "[e-mail]",
       "Country": "US",
       "Dob": null,
       "City": null,
       "ZipCode": null,
       "Region": null,
       "Street": null,
       "Currency": "USD"
     },
     "BinType": "DEBIT",
     "UsdAmount": 368.5,
     "Currency": "USD",
     "CardType": "Visa",
     "LastCcDigits": "7909",
     "IssueDate": "2024-09-23T08:58:14.6984228Z",
     "ClientIP": "185.84.71.135",
     "CreditCardCountry": "US",
     "Signature": "0e3ae94ac033f52b325873552148137d929939f926bd30b596de018c53d2a246",
     "CardIssuer": "MORGAN BANK, INC.",
     "MaskedPan": "460025******7909"
   }

4. Merchant Server Decision Process Upon receiving the webhook, Merchant Server analyzes the transaction details to determine the next steps. If the validation is successful, Merchant Server sends a POST request to Paytiko to approve or disapprove the transaction. POST URL https://{PAYTIKO_WHR_HOST}/transaction-registration HEADERS X-Merchant-Secret: MERCHANT_SECRET_KEY_ISSUED_BY_PAYTIKO REQUEST BODY

{
  "registrationActionId": "abeb6075-8e09-4d95-816c-507648ae41e1", // Taken from 'ActionId' field of webhook
  "registrationStatus": "Registered" // or "Disapproved"
  "signature": "15959820886ae86f7696813d30470fdefb18fe0bb0d5977dcc43e3ba626e1af2"
}

! Webhook signature generated as:

$signature = SHA256(`${orderId};${MERCHANT_SECRET_KEY_ISSUED_BY_PAYTIKO}`)

1. Paytiko Widget Response

   • Paytiko receives Merchant Servers’s decision (either Registered or Disapproved) and responds back to the widget through a specicif socket connection.

   • Based on the response, the widget will either proceed with the payment or display an error, depending on the outcome of the validation.