Toqio’s Transaction Monitoring flow allows customers to choose their preferred transaction monitoring solution and integrate it with Toqio.

Architecture overview

To start utilising the transaction monitoring service, the customer needs to choose a transaction monitoring service provider. Subsequently, they should establish an integration between Toqio and the selected transaction monitoring service provider

Transaction monitoring workflow

The service will operate as follows:

1. Payment initiation: The end-user initiates a payment through Toqio platform.
2. Notification to the customer: Toqio updates the customer's transaction monitoring service in real-time via an endpoint to be developed by the customer.
3. The customer informs Toqio of a decision via the endpoint's response, returning one of the following statuses based on the transaction data:
   1. APPROVED: Toqio sends the payment request to the BaaS.
   2. REJECTED: The payment is marked as REJECTED.
   3. PENDING_EXTERNAL_APPROVAL: The payment is marked as PENDING until an updated status is returned via a webhook.
4. Updated status notification : If the payment remains in a PENDING_EXTERNAL_APPROVAL status from the previous step, the customer can inform Toqio of a final decision via the TRANSACTION_MONITORING_STATUS_UPDATED webhook.
5. Payment execution: The Toqio platform acts accordingly, either processing the payment or rejecting it.

Authentication

To authenticate with the customer service, Toqio will utilize an API key. This API key will be generated by Toqio and securely transmitted to the customer.

The customer is required to furnish Toqio with a URL {customerApiUrl}to which the validation request will be sent. This request will undergo authentication using the provided API key. Ensure that the URL is shared with the Toqio delivery team, and they will configure it in the admin panel.

Endpoint specification

An endpoint must be developed on the customer's side, which Toqio will use synchronously. Toqio will send a request to this endpoint containing transaction information, which the customer's service will receive, process, and then forward to their transaction monitoring system. Subsequently, the customer service is required to synchronously return a response to Toqio, indicating the status of the transaction based on the process within the transaction monitoring system.

Method and url

The endpoint should be implemented as a POST method, and the URL should follow this format: {CustomerApiUrl}/transaction/validate .

Payload to be received

Once a transaction is initiated by the end-user, Toqio's Transaction Monitoring will send an object with the following parameters:

  String id; //Identifier of the transaction 
  Date date; // The date that the TX is initiated, e.g., 2023-05-19T08:00:02.342+00:00
  TransactionGroup group; // This field indicates whether it is an outbound or inbound transaction. Currently, only OUTBOUND will be received
  TransactionType type; // Type of transactions. Currently, only PAYMENT will be received 
  String baseCurrency; // Currency of the source account of the transaction
  double baseTotal; // Total amount of the transaction
  AssetTypeEnum currency; // Currency of the transaction 
  double total; // Total amount of the transaction
  String description; // Description added by transaction owner
  PaymentType payType; // Payment type of the transaction. Currently, only OUTBOUND_BANK_TRANSFER will be received. 

  String company; // companyId of the client
  String companyName; // companyName of the client
  ClientType companyType; // Client type: BUSINESS or CONSUMER

  double availableBalance; // Total available balance of the source account 
  AssetTypeEnum assetType; // Asset type of the source account
  String ukAccountNumber; // UK Account Number in case it's a GBP source account
  String ukSortCode; // UK Sort Code in case it's a GBP source account.
  String bicSwift; // Bic / Swift of the source account if applies
  String iban; // IBAN of the account if applies

  String userEmail; // Email address of the transaction owner
  Date userDateOfBirth; // Date of birth of the transaction owner
  String userCountry; // Country of the transaction owner
  String userAddress; // Address of the transaction owner
  String userPostCode; // Post code of the transaction owner
  String userPhoneNumber; // Phone number of the transaction owner

  String beneficiaryId; // Id of the beneficiary
  String beneficiaryName; // First name of the beneficiary
  BeneficiaryType beneficiaryType; // PERSON or COMPANY
  String beneficiaryUkAccountNumber; // UK Account Number if the beneficiary has a GBP account
  String beneficiaryUkSortCode; // UK Sort Code if the beneficiary has a GBP account.
  String beneficiaryBicSwift; // Bic / Swift of the beneficiary account
  String beneficiaryIban; // IBAN of the beneficiary account
  String beneficiaryAddressIsoCountry; // Country of the beneficiary

  String beneficiaryAddress; // Address of the beneficiary
  String beneficiaryPostCode; // Post Code of the beneficiary

Expected response

As a response, we expect an object with the following parameters:

• If "APPROVED" is received, the system will execute the payment.
• If "REJECTED" is received, the payment will be marked with a Rejected status.
• if "PENDING_EXTERNAL_APPROVAL" is received, the payment will be set to Pending status until an updated status notification is received via webhook.

{
  "transactionId":"string", // Unique identifier of the transaction, the same as sent in the payload
  "status":"APPROVED | REJECTED | PENDING_EXTERNAL_APPROVAL",
  "description":"string"//In case of the transaction being rejected, this should be filled 
} 

If Toqio receives an unrecognised status, the transaction will be considered as rejected.

Webhook

When to use it? When a payment remains in a PENDING_EXTERNAL_APPROVAL status, the customer can inform Toqio of the final decision of the transaction monitoring via this webhook.

webhookType: TRANSACTION_MONITORING_STATUS_UPDATED

model:

{
  "transactionId":"string", // Unique identifier of the transaction, the same as sent in the payload
  "status":"APPROVED | REJECTED",
  "description":"string"//In case of the transaction being rejected, this should be filled 
}