Receive Money

In addition to sending money, the IC API also allows you to receive money through your application. In this section, we'll explore the steps involved in receiving money using the IC API, including the necessary endpoints and request parameters.

How it works

The following endpoints should be called to get the parameter values required for Receive Money. There are 2 ways to receive money depending on the Delivery Mode.

Authenticating Your Requests

For the API calls described below, you will have to authenticate your requests using your API key and other required headers. The IC API uses Basic Authentication, so you'll need to include your API key in the Authorization header of your requests. Consult the API Reference for more information on required headers and authentication methods.

There are two different methods to receive money:

• Receiving Bank Account and Mobile Wallet Transactions.
• Receiving Cash Transactions.

Receiving Bank Account and Mobile Wallet Transactions

To successfully receive bank account and mobile wallet transactions, you must complete three steps:

1. Get ICTC Payment Status (Optional)
2. Get outstanding transactions.
3. Confirm the transaction.

Get ICTC Payment Status

We need to check the current status of the transaction to ensure it is ready to be confirmed. Check the status of the transfer by calling the transactions/status endpoint. This endpoint returns the current status of the transaction associated with the provided Instant Cash Transaction Code (ICTC) number.

Get outstanding transactions

Before confirming the transaction, check for other outstanding transactions that belong to the receiving partner. Call the transactions/outstanding endpoint to return a list of outstanding transactions which belong to a receiving partner.

Confirm the transaction

Confirming a transaction is the final step in receiving money in the form of a bank transfer or mobile wallet transaction. Transactions must have one of the following statuses to be confirmed:

• F (Read by Receiving Agent).
• D (Downloaded).

When you confirm a transaction, a new status will be applied. The following restrictions are in place for what new status can be applied to a transaction:

To confirm a transaction call the transactions/confirm endpoint and supply the mandatory parameters:

• reference: A 9-digit unique Instant Cash Transaction Code (ICTC) reference number that identifies the transaction.
• newStatus: The new status to apply to the confirmed transaction.

Receiving Cash

To successfully receive cash transactions:

1. Get ICTC Payment Status (Optional)
2. Receive payment
3. Unlock the transaction (Optional)
4. Confirm the transaction.

Get ICTC Payment Status

Check the status of the transfer by calling the transactions/status endpoint. This endpoint returns the current status of the transaction associated with the provided ICTC reference number.

Receive payment

Once the payment is received by the Partner, the transaction is locked and the status of the transaction is changed to F (Read by Receiving Agent). To receive payment, call the transactions/receive-payment endpoint and supply the following parameters:

• reference: A 9-digit unique Instant Cash Transaction Code (ICTC) reference number that identifies the transaction.
• partnerReference: A number sent by Partner’s system for each transaction.

Unlock a transaction

This unlocks the transaction associated with the provided ICTC reference number if Partner does not want to proceed with the payment,.. 
Transaction status returns to "Outstanding". To unlock a transaction, call the transactions/unlock endpoint.

Auto Unlock Feature:

When a receiving partner retrieves a transaction via the Receive Payment method, its status changes to "F-Read by Receiving Agent," indicating it's locked. If the teller cannot process the transaction, it should be unlocked and returned to "Outstanding." To automate this process, a timer/scheduler can be introduced to auto-unlock the transaction after a defined period (e.g., 30 minutes, 1 hour), based on the typical processing time on your end, if the transaction is not marked as Paid.

Confirm the transaction

Confirming a transaction is the final step in receiving money. Transactions must have one of the following statuses to be confirmed:

• F (Read by Receiving Agent).
• D (Downloaded).

When you confirm a transaction, a new status will be applied. The following restrictions are in place for what new status can be applied to a transaction:

To confirm a transaction call the transactions/confirm endpoint and supply the mandatory parameters:

• reference: A 9-digit unique Instant Cash Transaction Code (ICTC) reference number that identifies the transaction.
• newStatus: The new status to apply to the confirmed transaction.

Error handling

As with any API integration, there may be errors or edge cases that occur during the money transfer process. To handle these errors gracefully, be sure to implement error handling and retry mechanisms in your application.

In addition, be sure to review the API Reference for guidance on error codes and messages that may be returned by the API and use this information to provide informative error messages to your customers.