Send Money

One of the primary use cases of the IC API is to facilitate money transfer transactions, allowing your customers to send money quickly and securely through your application. In this section, we'll explore the steps involved in sending money including the necessary endpoints and request parameters.

How it works

The following endpoints should be called to get the parameter values required for the Create Transaction endpoint.

See the detailed instructions: https://docs.instantcashworldwide.com/recipes

Best integration practices

The sequence diagram is for your reference but we recommend that you follow the best practices below when integrating with the IC API:

• Cache static data and reuse
• Asynchronous processing to enhance page loads
• Optimize codes and queries to improve processing time and performance

Authenticating your request

Before sending a money transfer request, you'll need to authenticate your request 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 request. In addition, you may need to include other custom headers, such as the subscription key and financial API headers, depending on the endpoint you're using. Consult the API Reference for more information on required headers and authentication methods.

Initiating a Money Transfer

Before sending a transaction, you need to generate a unique Instant Cash Transaction Code (ICTC) reference number for your transaction.

To do this, call the /transactions/generate-ictc endpoint and use the ICTC number returned in the response.

Once you are authenticated and your transaction is created, you can initiate a money transfer by calling the transactions/initiate endpoint. This endpoint allows you to specify the transaction being sent, the target amount, and the target currency of the transfer. Here are the parameters you'll need to include in your request:

• reference: A 9-digit unique Instant Cash Transaction Code (ICTC) is given to the sender of the money.
• partnerReference: A number sent by Partner’s system for each transaction.
• payingAgent: This code represents the Partner receiving the money.
• targetCurrency: The local currency code of the Partner receiving the money.
• targetAmount: The amount of money the recipient will receive.
• sourceAmount: The amount of money the sender has sent in the local currency.
  • Note: Either targetAmount or sourceAmount is required. Both values cannot be passed at the same time.
• sourceCurrency: The currency code of the settlement amount.
• customerPrincAmount: The amount collected from the customer.
• originatingCountry: This code represents the originating country for the transaction.
• destinationCountry: This country is where the money is being sent to.
• sourceOfFund: The source of the funds. Use the /types?filter=source-of-funds endpoint to get a list of allowed types.
• deliveryMode: Defines a delivery method of remittance. Use the /types?filter=delivery-modes endpoint to get a list of allowed types.
• remittancePurpose: The purpose of the remittance. Use the /types?filter=remittance-purposes endpoint to get a list of allowed types.

Once you've included these parameters in your request, submit the request to the API using the appropriate HTTP method (typically POST). The API will process the request and respond with a confirmation or an error message, depending on the result of the transfer.

For a detailed example of how to create a transaction and send money, see our recipe.

Static List for Bangladesh Home Districts

As as special condition, when sending transactions to Bangladesh, if the sender/recipient's nationality is Bangladeshi (BD) and the delivery method is Cash, it is necessary to record the sender/recipient's home district. This list is predefined and partners must integrate it into their POS systems to transmit the corresponding district value to the Instant Cash system. Refer to this list which is available as 'Bangladesh Home Districts List' under 'Simulation And Testing'.

Checking the Status of a Transfer

After submitting a money transfer request, you can check the status of the transfer by calling the transactions/details endpoint. This endpoint allows you to retrieve information about a specific transfer, including its status, transaction ID, and other details. To call this endpoint, you'll need to include the transaction reference as a parameter in your request.

Once you've submitted the request, the API will respond with information about the status of the transfer. You can use this information to update your application's user interface and provide feedback to your customers about the progress of their transfer.

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.