API Transaction Processing Guidelines
To ensure the integrity, security, and accuracy of transaction processing, Instant Cash (IC) has implemented robust measures for transaction processing within its ecosystem. This document provides mandatory and recommended guidelines for IC partners to adhere to when creating and managing transactions via IC APIs. This also covers exceptional scenarios involving network retries, or timeouts or any other system related errors.
Adherence to these guidelines will:
- Provide seamless transaction processing
- Maintain precise synchronization between IC and Partner systems.
- Significantly improve reconciliation accuracy and efficiency.
- Eliminate the occurrence of any duplicate transactions.
Mandatory Guidelines for Transaction Processing
These steps are mandatory to ensure a seamless transaction process to maintain system integrity.
1. Pre-Submission Data Capture & Storage:
Before initiating any call to the IC Create Transaction API:
Action: All relevant transaction details (e.g., sender information, receiver details, amount, currency, generated ICTC number, Agent Order Number) must be captured and durably stored within your local system.
You must save transaction data to your local system before initiating IC API
Rationale: This critical step acts as the primary safeguard in ensuring that your system maintains complete records regardless of the IC API's response. It is fundamental for accurate reconciliation.
2. Unique ICTC Number Generation & Usage:
Action: Utilize the Generate ICTC API to obtain a new and unique ICTC number for every new transaction attempt.
Prohibition: An ICTC number, once successfully used for a transaction, must never be reused for a different transaction.
3. Consistent Use of Agent Order Number
Action: Ensure that each transaction originates with a unique Agent Order Number generated by your internal system.
Consistency during Retries: When retrying a transaction (see Section 3.4), do not generate a new Agent Order Number. The original Agent Order Number must be used alongside the original ICTC Number to maintain transactional consistency across systems.
4. API Failure Handling & Retries:
In the event of API failures such as:
- Timeout errors (connection, read, or write timeouts)
- IC API non-responsiveness
- Network connectivity issues
- Uncertain response status (e.g., no response, partial response)
Follow these strict protocols:
Action: DO NOT generate a new ICTC number for the failed transaction attempt.
Action: Retry the transaction using the same original ICTC number and the same original Agent Order Number that were used in the initial attempt.
IC System Behavior: If IC has already processed a transaction with the submitted ICTC number (even if your system didn't receive the initial success response), it will return a "Duplicate Transaction" error, and the transaction will not be created again. This mechanism prevents any duplicate transaction processing on the IC system.
5. Transaction Cancellation Protocol:
If a transaction is initiated by the Partner system is to be cancelled (due to any reason):
Action: It is mandatory to ensure the corresponding transaction is also cancelled in the IC system.
Methods: Utilize the Cancel Transaction API, the IC IMS System, or contact the IC Operations Team to perform the cancellation.
Prohibition: Do not simply cancel the transaction in your internal system and re-issue a new transaction without first ensuring the original transaction is definitively cancelled or its status confirmed in the IC system.
Pre-Reissue Check: If there is any intent to re-issue a transaction that was previously in an uncertain state, first call the Get Transaction Status API using the original ICTC number to verify its current status.
Scenario A: Transaction exists in IC system (e.g., "Success")
Action: Treat the transaction as successful in your system. No re-issue is required.
Scenario B: No record found in IC system
Action: Proceed to retry the transaction using the same original ICTC number and Agent Order Number.
Updated 20 days ago