Skip to main content

Overview

Money Transfer is one of the products within Flip for Business which was created with the aim to facilitate users complete high volume transactions in an easier, faster, and more cost-efficient manner. With Money Transfer, users can transfer money up to 20,000 accounts in one go across different beneficiaries.

As of now, Flip is providing Money Transfer service across three different beneficiary types: Bank, VA, and E-wallet which all bank codes are listed in the destination bank code section. You can also get this list of bank codes via API along with other information such as bank status in Get Bank Info API.

For VA, currently we support transfer to :

  • BRI VA
  • Danamon VA
  • CIMB VA
  • BNI VA
  • Permata VA
  • Mandiri VA
  • Muamalat VA

Step for Integration​

To ensure a smooth integration with Flip's Money Transfer API, please follow the steps outlined below. This process will guide you from initial testing to live production, ensuring that your system is fully prepared for a seamless operation. To integrate with Money Transfer, please follow the steps given below:

1. Preparation Steps Before Integration​

  • Testing in Test Mode/Sandbox
    Start by testing your integration in the Test Mode/Sandbox environment. You can access it here: Flip Sandbox Overview.

  • Preparing and Retrieving API Secret Keys
    To verify that the HTTP requests we receive are genuinely from you, it's crucial to use basic authentication with your API Secret Key for every request you send. Flip’s API Gateway employs basic access authentication. The format is [username]:[password]; use your API Secret key as the username and leave the password field empty. Then, encode this string in Base64. The resulting encoded string must be included in the Authorization HTTP header for every API call. For development make sure you use the Test environment's API Secret Key. Read for more information for Retrieving API Secret Key.

    • Here’s an example of an authentication string (in plain text) - note the colon:
      • JDJ5JDEzJDBkRTB6T2tBdk8uQWcvRDU2TTY0TmVQd0NrNC5POVF5elZuQnpJUTJvdWc4a2t0Tm44RnlT:
    • And the corresponding Base64 encoded string:
      • SkRKNUpERXpKREJrUlRCNlQydEJkazh1UVdjdlJEVTJUVFkwVG1WUWQwTnJOQzVQT1ZGNWVsWnVRbnBKVVRKdmRXYzRhMnQwVG00NFJubFQ6
    • For the HTTP Authorization header, it should look like this:
      • Authorization: Basic SkRKNUpERXpKREJrUlRCNlQydEJkazh1UVdjdlJEVTJUVFkwVG1WUWQwTnJOQzVQT1ZGNWVsWnVRbnBKVVRKdmRXYzRhMnQwVG00NFJubFQ6
    Base64 Code Simulator
    Live Editor
      function Base64Encoder() {
    // Replace the value with your test mode API Secret Key
    const apiSecretKey 
    = 'JDJ5JDEzJDBkRTB6T2tBdk8uQWcvRDU2TTY0TmVQd0NrNC5POVF5elZuQnpJUTJvdWc4a2t0Tm44RnlT'

    const [encodedString, setEncodedString] = useState('');
    useEffect(() => {
      // Encode the API Secret Key to Base64
      const encoded = btoa(`${apiSecretKey} + :`);
      setEncodedString(encoded);
    }, [apiSecretKey]);

    return (
      <div>
        <h2>Base64 Encoded String:</h2>
        <p>{encodedString}</p>
      </div>
    )
  }
    Result
    Loading...

2. Generate Signature (Optional)​

Signature is used to secure your API request and prevent attackers from altering your payload. It is optional and disabled by default. This feature is only applicable to Disbursement-related APIs. If you want to use signature, follow these steps:

  1. Generate a public and private key pair using the OPENSSL_KEYTYPE_RSA 2048-bit algorithm.
  2. Send your public key to Flip API Integration team and notify when you're ready to make requests with a signature.
  3. Generate the signature using your private key with input data from your POST and GET request parameters, encoded as strings (ensure all data types are strings). The signature must use the sha256WithRSAEncryption algorithm and be encoded with Base64.
Generate Signature Algorithm
function generateSignature(privateKey, payload) {
const payloadString = JSON.stringify(payload); // Step 1: Convert payload to string
const sign = createSignature(payloadString, privateKey); // Step 2: Create signature with sha256WithRSAEncryption algorithm
const signature = btoa(sign); // Step 3: Convert signature to Base64

return signature;
}

// In actual implementation, use a library like crypto-js, or Web Crypto API
function createSignature(data, key) {
  return `signature`;
}

// Example usage:
const privateKey = "your-private-key";
const payload = {
  "account_number": "0437051936",
  "bank_code": "bni",
  "amount": "10000",
  "remark": "testing",
  "recipient_city": "391",
  "beneficiary_email": "",
};

const signature = generateSignature(privateKey, payload);
console.log("Generated Signature:", signature);
  1. For every Disbursement API request, include the X-Signature header. Sample request with Signature in the Header :

Sample Request with Signature:​

curl -X POST 'https://bigflip.id/big_sandbox_api/v2/disbursement/bank-account-inquiry' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>' \
-H 'X-Signature: Your-Generated-Signature' \ # <-- Signature
-d 'account_number=5465327020' \
-d 'bank_code=bca' \
-d 'inquiry_key=your-unique-id-12344'

3. Verify Bank Account Inquiry​

Before performing a money transfer, you need to verify the bank account number's validity that will receive the funds. You can use API Account Inquiry to get the bank account holder name and verify the validity of bank account. For now, it still take us a few seconds to do the inquiry. The final status result will be returned as a callback, but if the account available in our chache we will return directly to our API Response. Be sure to set up your callback inquiry entry in your Flip for Business Dashboard.

Sequence Diagram
bank inquiry sequence diagram

Request Details​

EnvironmentMethodURL
Test ModePOSThttps://bigflip.id/big_sandbox_api/v2/disbursement/bank-account-inquiry
Live ModePOSThttps://bigflip.id/v2/disbursement/bank-account-inquiry
RequirementDescription
API Secret KeyThe api key that will be used to authenticate the request. For more details, refer to Retrieving API Access Keys.
account_numberThe Bank account number will validate
bank_codeBank code of the account. Accepted value are listed here
inquiry_keyUnique id that will be used for handling multiple request with multiple callback

Sample Request:​

curl -X POST 'https://bigflip.id/big_sandbox_api/v2/disbursement/bank-account-inquiry' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>' \
-d 'account_number=5465327020' \
-d 'bank_code=bca' \
-d 'inquiry_key=your-unique-id-12344'

Sample Response:​

The sample response when the account is not avaliable in our cache, the final status will be send via callback. So then you need to continue with step no 3

{
  "bank_code": "bca",
  "account_number": "5465327020",
  "account_holder": "",
  "status": "PENDING",
  "inquiry_key": "your-unique-id-12344"
}
API Reference

Refer to this page for more information about the Account Inquiry API Reference.

4. Handling Bank Account Inquiry Callback​

When you perform a bank account inquiry, Flip will send a callback to your designated webhook URL that you set on Flip Dashboard with the inquiry result. This callback contains crucial information about the validity of the bank account that you need to process befoe make disbursement.

We will hit your URL using POST request with content type application/x-www-form-urlencoded and payload as described below:

AttributeDescription
dataJSON object string with content exactly the same as the response of bank account inquiry (see example below)
tokenValidation token to ensure that the callback is coming from our server. You can get your token in your Flip for Business dashboard.

Sample CURL:​

curl -X POST 'https://your-domain-callback-url.com/account-inquiry' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'data={"bank_code":"bca","account_number":"5465327020","account_holder":"PT Fliptech Lentera IP","status":"SUCCESS","inquiry_key":"your-unique-id-12344"}&token=YOUR_VALIDATION_TOKEN_KEY'

Steps to Handle the Callback:

  1. Receive the Callback:
    • The callback will include data such as the account number, bank code, inquiry status, and other relevant details. Parse this data to extract the necessary information. 
      data={
        "bank_code": "bca",
        "account_number": "5465327020",
        "account_holder": "PT Fliptech Lentera IP",
        "status": "SUCCESS",
        "inquiry_key": "your-unique-id-12344"
      }&token=YOUR_VALIDATION_TOKEN_KEY
    • Extract and process the necessary data to update your records and trigger any follow-up actions.
  2. Verify the Inquiry Status:
    • Check the status field in the callback to determine whether the bank account is valid. The status will typically indicate SUCCESS or INVALID_ACCOUNT_NUMBER, SUSPECTED_ACCOUNT, BLACK_LISTED for failure.
    • If the inquiry was successful, the account_holder field will contain the name of the account holder.
  3. Process the Response:
    • Based on the inquiry status, you can proceed with your desired action. For instance:
      • If the account is valid which means with status SUCCESS you may proceed with the money transfer.
      • If the account is invalid which can with status INVALID_ACCOUNT_NUMBER, SUSPECTED_ACCOUNT or BLACK_LISTED, notify the user or take corrective action as needed.
  4. Respond to the Callback:
    • It is mandatory to respond to the callback with HTTP Status Code 200 which Flip mark as success delivery. If the URL returns a non-200 HTTP Status Code or if Flip doesn’t receive any response within 30 seconds (timeout), Flip will retry the request 5 times, with a 2-minute interval for each retry.
    • You can respond immediately to Flip and then process the callback data asynchronously to ensure prompt acknowledgement.

5. Perform Money Transfer​

Once the account inquiry is verified, you can proceed with the money transfer API to disburse.

Request Details​

EnvironmentMethodURL
Test ModePOSThttps://bigflip.id/big_sandbox_api/api/v3/disbursement
Live ModePOSThttps://bigflip.id/api/v3/disbursement
RequirementDescription
API Secret KeyThe api key that will be used to authenticate the request. For more details, refer to Retrieving API Access Keys.
Content-TypeRequest content type: application/x-www-form-urlencoded.
idempotency-keyUnique identifier for each request. Please see more detail on Idempotent Request section.
account_numberThe account number of the recipient.
bank_codeBank code of the account. Accepted value are listed here
amountThe amount of money to be disbursed
remarkRemark to be included in the transfer made to the recipient. Usually will appear as berita transfer or remark in the transfer receipt.

Sample Request:​

curl -X POST 'https://bigflip.id/big_sandbox_api/v3/disbursement' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'idempotency-key: your-unique-id-12344' \
-H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>' \
-d 'account_number=5465327020' \
-d 'bank_code=bca' \
-d 'amount=100000' \
-d 'remark=test%20disburse'

Sample Response:​

{
  "id": 210108,
  "user_id": 12950853,
  "amount": 100000,
  "status": "PENDING",
  "reason": "",
  "timestamp": "2024-08-28 11:40:29",
  "bank_code": "bca",
  "account_number": "5465327020",
  "recipient_name": "PT Fliptech Lentera IP",
  "sender_bank": "mandiri",
  "remark": "test disburse",
  "receipt": "",
  "time_served": "(not set)",
  "bundle_id": 0,
  "company_id": 45529,
  "recipient_city": 0,
  "created_from": "API",
  "direction": "DOMESTIC_TRANSFER",
  "sender": null,
  "fee": 2400,
  "beneficiary_email": "",
  "idempotency_key": "your-unique-id-12344"
}
API Reference

Refer to this page for more information about the Money Transfer API Reference.

6. Handling Disbursement Callback​

When there is transaction status update/change for Money Transfer, Flip will send a request to your specified webhook URL in your Flip for Business dashboard. This type of asynchronous request is known as a Callback. Flip will send an HTTP POST request to the callback URL you configured. This callback is critical for confirming the success of the transaction and updating your system accordingly.

We will hit your URL using POST request with content type application/x-www-form-urlencoded and payload as described below:

AttributeDescription
dataJSON object string with content exactly the same as the response of disbursement (see example below)
tokenValidation token to ensure that the callback is coming from our server. You can get your token in your Flip for Business dashboard.

Sample CURL:​

curl -X POST 'https://your-domain-callback-url.com/flip/disbursement/callback' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'data={"id": 210108, "user_id": 12950853, "amount": 100000, "status": "PENDING", "reason": "", "timestamp": "2024-08-28 11:40:29", "bank_code": "bca", "account_number": "5465327020", "recipient_name": "PT Fliptech Lentera IP", "sender_bank": "mandiri", "remark": "test disburse", "receipt": "", "time_served": "(not set)", "bundle_id": 0, "company_id": 45529, "recipient_city": 0, "created_from": "API", "direction": "DOMESTIC_TRANSFER", "sender": null, "fee": 2400, "beneficiary_email": "", "idempotency_key": "your-unique-id-12344"}&token=YOUR_VALIDATION_TOKEN_KEY'

Steps to Handle the Callback:

  1. Receive the Callback:
    • The callback will include various transaction details such as the transaction ID, user ID, amount transferred, status, bank code, account number, recipient details, and other relevant information. 
      data={
        "id": 210108,
        "user_id": 12950853,
        "amount": 100000,
        "status": "DONE",
        "reason": "",
        "timestamp": "2024-08-28 11:40:29",
        "bank_code": "bca",
        "account_number": "5465327020",
        "recipient_name": "PT Fliptech Lentera IP",
        "sender_bank": "bsm",
        "remark": "test disburse",
        "receipt": "https://receipt.flip.id/receipt/view?transaction_id=W439365229!2e5e87a2623ffff",
        "time_served": "2024-08-28 11:43:11",
        "bundle_id": 0,
        "company_id": 45529,
        "recipient_city": 0,
        "created_from": "API",
        "direction": "DOMESTIC_TRANSFER",
        "sender": null,
        "fee": 2400,
        "beneficiary_email": "",
        "idempotency_key": "your-unique-id-12344"
      }&token=$2y$13$UsffNb9Y69sU4r5PzWgPwu038C28EUTM8wxSe4COTImnKbtQMnjzKxxsd
  2. Verify the Disbursement Status:
    • The status field will indicate the outcome of the transaction. For example:
      • DONE signifies that the transaction was completed successfully.
    • Based on the status, you can determine whether to finalize the transaction on your end.
    • Additionally, you can verify the callback status by using Flip's Get Disbursement API. You can retrieve the transaction details either by the idempotency_key or by the transaction id to get the latest status transaction.
  3. Process the Transaction:
    • If the transaction was successful (status: DONE), you can:
      • Confirm the transaction with your customer.
      • Update your internal records to reflect the successful transfer.
    • If the transaction status CANCELLED, review the reason to understand the cause and take appropriate corrective actions.
  4. Respond to the Callback:
    • It is mandatory to respond to the callback. If the webhook URL returns a non-200 HTTP Status Code or if Flip doesn’t receive any response within 30 seconds (timeout), Flip will retry the request 5 times, with a 2-minute interval between retries.
    • You may choose to respond immediately to Flip and then process the callback data asynchronously to ensure timely acknowledgment.

Complete the User Acceptance Testing (UAT) documentation for Money Transfer​

To ensure that your integration with the Money Transfer API meets all requirements and functions as expected, you need to complete the User Acceptance Testing (UAT) documentation. Follow the steps below to finalize your UAT process:

  1. Review the UAT Scenarios
    • The scenarios for UAT can be found here. Review these scenarios thoroughly to ensure you understand the testing requirements.
  2. Complete the UAT Documentation
    • Perform the UAT according to the provided scenarios.
    • Document your test results, including request and response logs for each test scenario to provide a comprehensive view of the API interactions and responses.
  3. Submit UAT Results
    • Once you have completed and documented your UAT, submit the documentation via email to: b2b-api-integration@flip.id with following format:
      • Subject: Merchant UAT - Money Transfer
      • Body Contains:
        • Flip Company ID
        • Merchant name
    • Ensure that your email includes all relevant UAT documentation, including the request and response logs, and any additional information required.
  4. Review Process
    • We will review your UAT submission within max 2x24 working hours. During this time, our team will assess your testing results and provide feedback if necessary.
  5. Integration in Live Production
    • After your UAT has been reviewed and approved, we will send you detailed instructions for integrating the Money Transfer API into Live Production via email.

Important Notes​

  • Postman Collection: For easier integration and testing, download our Postman Collection here: Flip Postman Collection.

  • Idempotency Key: Implementing the idempotency key is mandatory for Money Transfer operations. Please refer to the documentation here: Idempotent Request Documentation.

  • IP Address: The IP address that will be used to send requests to Flip must be listed in the UAT document (link provided above).

  • Subscribe to Flip Status Page to receive real-time updates on maintenance and system status.

    If you have any further questions, please reach out to B2B API Integration team. Thank you!

Last updated on