Skip to main content

Overview

The International Transfer API solution is designed for businesses, particularly money transfer operators, seeking to offer their users a cost-effective, secure, and swift way to handle international transfers.

C2C (Consumer to Consumer) and C2B (Consumer to Business) For consumer-focused transactions, the API supports both C2C (Consumer to Consumer) and C2B (Consumer to Business) transfers, allowing individuals to send money directly to other individuals or businesses.

B2B (Business to Business) and B2C (Business to Consumer) For business transactions, the API provides support for B2B (Business to Business) and B2C (Business to Consumer) transfers, enabling businesses to send funds to other businesses or directly to consumers.

The API currently covers several international corridors, and we are continuously expanding to include more options.

Step for Integration​

To ensure a smooth integration with Flip's International 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 International 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. Get Exchange Rate​

Before initiating an international transfer, it's essential to know the applicable rates for the destination country. You can use the Get Exchange Rates API, which provides not only the exchange rates but also key details for the destination corridors, such as the minimum and maximum transfer amounts, cut-off times, estimated arrival times, and transfer fees. This information will help you understand the requirements and costs associated with the transfer.

Request Details​

EnvironmentMethodURL
Test ModeGEThttps://bigflip.id/api/v2/international-disbursement/exchange-rates?country_iso_code=country_iso_code&transaction_type=transaction_type
Live ModeGEThttps://bigflip.id/v2/disbursement/exchange-rates?country_iso_code=country_iso_code&transaction_type=transaction_type
RequirementDescription
API Secret KeyThe api key that will be used to authenticate the request. For more details, refer to Retrieving API Access Keys.
country_iso_codeCountry code using ISO 3166 (Alpha-3). You can choose multiple countries separate by comma. See supported Country ISO Codes.
transaction_typeTransaction type information. C2C, C2B, B2B, B2C

Sample Request:​

curl -L 'https://bigflip.id/big_sandbox_api/v2/international-disbursement/exchange-rates?country_iso_code=SGP&transaction_type=C2C' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>'

Sample Response:​

[
{
    "currency_code": "SGD",
    "country_code": "SG",
    "country_name": "Singapore",
    "country_iso_code": "SGP",
    "flip_exchange_rate": 11886.6,
    "flip_transfer_fee": 85000,
    "minimum_amount": 1,
    "maximum_amount": 200000,
    "payment_speed": "Real Time",
    "arrival_message": "Uang diperkirakan sampai dalam hitungan detik.",
    "notes": null,
    "transaction_type": "C2C",
    "flip_cutoff_time": "2024-08-30 15:41:54+0700",
    "flip_arrival_time": "2024-08-30 15:41:54+0700",
    "is_active": true
}
]
API Reference

Refer to this page for more information about the Get Exchange Rate API Reference.

4. Get Form Data​

This endpoint retrieves a form with all the required fields needed to create a transaction, including details like the remittance purpose, source of funds, relationship with the beneficiary, and the beneficiary’s bank account information.

Request Details​

EnvironmentMethodURL
Test ModeGEThttps://bigflip.id/api/v2/international-disbursement/form-data?country_iso_code=country_iso_code&transaction_type=transaction_type
Live ModeGEThttps://bigflip.id/api/v2/international-disbursement/form-data?country_iso_code=country_iso_code&transaction_type=transaction_type
RequirementDescription
API Secret KeyThe api key that will be used to authenticate the request. For more details, refer to Retrieving API Access Keys.
country_iso_codeCountry code using ISO 3166 (Alpha-3). You can choose multiple countries separate by comma. See supported Country ISO Codes.
transaction_typeTransaction type information. C2C, C2B, B2B, B2C

Sample Request:​

curl -L 'https://bigflip.id/big_sandbox_api/v2/international-disbursement/form-data?country_iso_code=SGP&transaction_type=C2C' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>' \

Sample Response:​

{
"country_iso_code": "SGP",
"currency_code": "SGD",
"beneficiary_relationships": {
    "SELF": "Diri Sendiri",
    "FATHER": "Orang Tua",
    "BROTHER": "Keluarga",
    "FRIEND": "Teman"
},
"source_of_funds": {
    "BUSINESS": "Bisnis",
    "SALARY": "Gaji",
    "SAVINGS": "Tabungan",
    "GIFT": "Hadiah"
},
"remittance_purposes": {
    "FAMILY_SUPPORT": "Bantuan Keluarga",
    "PERSONAL_TRANSFER": "Pengiriman Pribadi",
    "EDUCATION": "Pendidikan",
    "GIFT_AND_DONATION": "Hadiah Dan Donasi",
    "SALARY_PAYMENT": "Pembayaran Gaji",
    "MEDICAL_TREATMENT": "Perawatan Medis",
    "MAINTENANCE_EXPENSES": "Beban Pemeliharaan",
    "TRAVEL": "Perjalanan",
    "SMALL_VALUE_REMITTANCE": "Remitansi Nilai Kecil",
    "LIBERALIZED_REMITTANCE": "Remitansi Liberal",
    "CONSTRUCTION_EXPENSES": "Beban Konstruksi",
    "HOTEL_ACCOMMODATION": "Akomodasi Penginapan",
    "ADVERTISING_EXPENSES": "Beban Iklan",
    "ADVISORY_FEES": "Biaya Konsultan",
    "BUSINESS_INSURANCE": "Asuransi Bisnis",
    "INSURANCE_CLAIMS": "Klaim Asuransi",
    "DELIVERY_FEES": "Biaya Pengiriman",
    "EXPORTED_GOODS": "Pembayaran Barang Ekspor",
    "SERVICE_CHARGES": "Biaya Layanan",
    "LOAN_PAYMENT": "Pembayaran Pinjaman",
    "OFFICE_EXPENSES": "Beban Kantor",
    "PROPERTY_PURCHASE": "Pembelian Properti",
    "PROPERTY_RENTAL": "Pembayaran Sewa Properti",
    "ROYALTY_FEES": "Biaya Royalti Dan Hak Cipta",
    "SHARES_INVESTMENT": "Investasi Saham",
    "FUND_INVESTMENT": "Investasi Dana",
    "TAX_PAYMENT": "Pembayaran Pajak",
    "TRANSPORTATION_FEES": "Biaya Transportasi",
    "UTILITY_BILLS": "Tagihan Utilitas",
    "COMPUTER_SERVICES": "Layanan Komputer",
    "REWARD_PAYMENT": "Pembayaran Hadiah",
    "INFLUENCER_PAYMENT": "Pembayaran Influencer",
    "OTHER_FEES": "Biaya Komitmen Dan Garansi"
},
"banks": {
    "848": "Australia And New Zealand Banking Group Limited",
    "859": "Bank Of China Limited",
    "865": "Bank Of Tokyo-mitsubishi Ufj, Ltd., The",
    "868": "Bnp Paribas - Singapore Branch",
    "884": "Cimb Bank Berhad",
    "885": "Citibank Singapore Ltd",
    "886": "Citibank,n.a.",
    "901": "Dbs Bank Ltd.",
    "904": "Deutsche Bank Ag",
    "931": "Hl Bank, Singapore",
    "2669": "Hsbc (corporate)",
    "2668": "Hsbc (personal)",
    "939": "Icici Bank Limited",
    "942": "Industrial And Commercial Bank Of China",
    "1665": "Malayan Banking Berhad",
    "2666": "Malayan Singapore Limited",
    "2667": "Mizuho Bank Limited",
    "954": "Oversea-chinese Banking Corporation Limited",
    "963": "Rhb Bank Berhad",
    "2670": "Sing Investments & Finance Limited",
    "980": "Standard Chartered Bank Limited",
    "983": "Sumitomo Mitsui Banking Corporation",
    "1007": "United Overseas Bank Limited"
},
"special_identifiers": [],
"regions": [],
"nationality_countries": []
}
API Reference

Refer to this page for more information about the Get Form Data API Reference.

5. Perform International Transfer​

After you finish check the exchange rates and completed the required form data, you can proceed to create an International Transfer transactions.

Request Details​

EnvironmentMethodURL
Test ModePOSThttps://bigflip.id/api/v2/international-disbursement
Live ModePOSThttps://bigflip.id/big_sandbox_api/v2/international-disbursement
RequirementDescription
API Secret KeyThe api key that will be used to authenticate the request. For more details, refer to Retrieving API Access Keys.
idempotency-keyUnique identifier for each request. Please see more detail on Idempotent Request section.
id_numberId number.
id_expiration_dateID expiration date using YYYY-MM-DD format.
amountId number.
source_countrySource country code using ISO 3166 (Alpha-3). Currently possible value is IDN.
destination_countryDestination country code using ISO 3166 (Alpha-3). See supported Destination Countries.
beneficiary_full_nameFull name of the beneficiary
beneficiary_account_numberAccount number of the beneficiary bank
beneficiary_bank_idID of beneficiary bank
beneficiary_msisdnA number used to identify a phone number internationally
beneficiary_nationalityCountry code using ISO 3166 (Alpha-3) of beneficiary nationality
beneficiary_provinceProvince or state of the beneficiary
beneficiary_cityCity of the beneficiary
beneficiary_addressAddress of the beneficiary
beneficiary_relationshipRelationship of beneficiary
beneficiary_source_of_fundsSource of funds
beneficiary_remittance_purposesPurpose of remittance
beneficiary_ibanIdentifier of individual account involved in the international transaction
beneficiary_swift_bic_codeIdentifier of specific bank during an international transaction
beneficiary_sort_codeDigits of code which is used by British and Irish banks
beneficiary_ifs_codeIndian financial system code
beneficiary_bsb_numberIdentifier of banks and branches across Australia
beneficiary_branch_numberIdentifier of banks and branches across Japan
beneficiary_document_reference_numberReference number of document related to the transaction
beneficiary_registration_numberRegistration number
beneficiary_regionRequired for destination country China code.
sender_nameThe name of the user of the Money Transfer Company that act as a sender
sender_countryCountry code of the sender’s residence. Available value can be retrieved from country list.
sender_place_of_birthCity/country code of the sender’s place of birth. Use city code if the sender’s place of birth is in Indonesia, and country code if outside Indonesia
sender_date_of_birthSender’s date of birth with YYYY-MM-DD format
sender_addressSender’s address
sender_identity_typeSender’s ID type.
sender_identity_numberSender’s ID number
sender_jobSender’s job.
sender_emailSender’s email. Only accept one email.
sender_citySender’s city.
sender_phone_numberSender’s phone number. Start with country phone code.
info

To perform a C2B transaction, simply set the transaction_type to C2B in the Create International Transfer Request.

Sample Request:​

curl -X POST 'https://bigflip.id/big_sandbox_api/v2/international-disbursement' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'idempotency-key: Test523489832' \
-d 'amount=1000' \
-d 'source_country=IDN' \
-d 'destination_country=SGP' \
-d 'transaction_type=C2C' \
-d 'beneficiary_full_name=felicia' \
-d 'beneficiary_account_number=67462374939049' \
-d 'beneficiary_bank_id=859' \
-d 'beneficiary_nationality=SGP' \
-d 'beneficiary_province=Singapore' \
-d 'beneficiary_city=Singapore' \
-d 'beneficiary_address=Singapore' \
-d 'beneficiary_relationships=FRIEND' \
-d 'beneficiary_source_of_funds=SALARY' \
-d 'beneficiary_remittance_purposes=FAMILY_SUPPORT' \
-d 'sender_name=Lala' \
-d 'sender_country=100252' \
-d 'sender_place_of_birth=122' \
-d 'sender_date_of_birth=1996-07-09' \
-d 'sender_address=Jakarta%20' \
-d 'sender_identity_type=nat_id' \
-d 'sender_identity_number=4536748275648882' \
-d 'sender_job=private_employee' \
-d 'sender_email=test%40gmail.com' \
-d 'sender_city=Jakarta' \
-d 'sender_phone_number=6285463746357'

Sample Response:​

{
"id": 261,
"user_id": 12950853,
"company_id": 45529,
"exchange_rate": 11886.6,
"fee": 85000,
"amount": 1188660,
"source_country": "SGP",
"destination_country": "IDN",
"beneficiary_amount": 100,
"beneficiary_currency_code": "SGD",
"status": "PENDING",
"timestamp": "(not set)",
"time_served": "(not set)",
"created_from": "API",
"receipt": "",
"transaction_type": "C2C",
"idempotency_key": "test656435989906",
"beneficiary": {
    "full_name": "felicia bc",
    "bank_account_number": "67462374939049",
    "email": "",
    "bank": "BANK OF CHINA LIMITED",
    "msisdn": "",
    "nationality": "",
    "country": "SGP",
    "province": "Singapore",
    "city": "Singapore",
    "address": "",
    "postal_code": "",
    "relationship": "FRIEND",
    "source_of_funds": "SALARY",
    "remittance_purpose": "FAMILY_SUPPORT",
    "iban": null,
    "swift_bic_code": null,
    "sort_code": null,
    "ifs_code": null,
    "bsb_number": null,
    "branch_number": null,
    "document_reference_number": null,
    "registration_number": null,
    "id_number": "",
    "id_expiration_date": "",
    "ach_code": ""
},
"sender": {
    "name": "Lala",
    "place_of_birth": 122,
    "date_of_birth": "1996-07-09",
    "address": "Jakarta ",
    "identity_type": "nat_id",
    "identity_number": "4536748275648882",
    "country": 100252,
    "job": "private_employee",
    "email": "test@gmail.com",
    "city": "Jakarta",
    "phone_number": "+6285463746357"
},
"reason": ""
}
API Reference

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

6. Handling International Transfer Callback​

When there is transaction status update/change for International 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.

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": 261,
        "user_id": 12950853,
        "company_id": 45529,
        "exchange_rate": 11886.6,
        "fee": 85000,
        "amount": 1188660,
        "source_country": "SGP",
        "destination_country": "IDN",
        "beneficiary_amount": 100,
        "beneficiary_currency_code": "SGD",
        "status": "DONE",
        "timestamp": "2024-08-29 17:01:53",
        "time_served": "2024-08-29 17:49:19",
        "created_from": "API",
        "receipt": "https://flip-receipt.oss-ap-southeast-5.aliyuncs.com/debit_receipt/",
        "transaction_type": "C2C",
        "idempotency_key": "test656435989906",
        "beneficiary": {
          "full_name": "felicia bc",
          "bank_account_number": "67462374939049",
          "email": "",
          "bank": "BANK OF CHINA LIMITED",
          "msisdn": "",
          "nationality": null,
          "country": "SGP",
          "province": "Singapore",
          "city": "Singapore",
          "address": "",
          "postal_code": "",
          "relationship": "FRIEND",
          "source_of_funds": "SALARY",
          "remittance_purpose": "FAMILY_SUPPORT",
          "iban": null,
          "swift_bic_code": null,
          "sort_code": null,
          "ifs_code": null,
          "bsb_number": null,
          "branch_number": null,
          "document_reference_number": null,
          "registration_number": null,
          "id_number": null,
          "id_expiration_date": null
        },
        "sender": null,
        "reason": ""
      }&token=$2y$13$UsffNb9Y69sU4r5PzWgPwu038C28EUTM8wxSe4COTImnKbtQMnjzKxxsd

  2. Verify the International Transfer 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 International Transfer API. You can retrieve the transaction details 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.
  • After your UAT has been reviewed and approved, we will provide detailed instructions for the Live Production integration via email.

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

To ensure that your integration with the International 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 - International 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