Transaction monitoring for outbound payment
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:
- Payment initiation: The end-user initiates a payment through Toqio platform.
- Notification to the customer: Toqio updates the customer's transaction monitoring service in real-time via an endpoint to be developed by the customer.
- The customer informs Toqio of a decision via the endpoint's response, returning one of the following statuses based on the transaction data:
- APPROVED: Toqio sends the payment request to the BaaS.
- REJECTED: The payment is marked as REJECTED.
- PENDING_EXTERNAL_APPROVAL: The payment is marked as PENDING until an updated status is returned via a webhook.
- 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.
- 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
}
Updated 12 days ago