Skip to main content

API Security & Integration Best Practices

A Guide for Merchant

Ensuring a secure and reliable connection is our top priority. As you prepare to integrate with our API, this one-pager outlines the mandatory security protocols and operational best practices required to protect transaction data and maintain system stability.

1. Authentication & IP Whitelisting​

To safeguard your integration, we employ strict access controls.

  1. Mandatory IP Whitelisting: In our production environment API access is restricted to pre-approved IP addresses. You must provide a list of static public IP addresses (or NAT Gateway IPs) for your production servers. Requests originating from non-whitelisted IPs will be rejected.

  2. Troubleshooting 401 Unauthorized Errors: If you receive a 401 Unauthorized error, the two most common causes are:

    1. The request is originating from an IP address that has not been whitelisted.
    2. The Secret Key provided in the header is invalid, expired, or missing.

  3. Credential Management & Key Security: Treat your API Secret Key like a critical production password.

    1. No Hardcoding: Never hardcode your Secret Keys in client-side applications or commit them to version control repositories (e.g., GitHub, GitLab, Bitbucket). Instead, strictly utilize secure environment variables or dedicated Secrets Management tools (e.g., AWS Secrets Manager, Google Secrets Manager, HashiCorp Vault).
    2. Secure Handling: Store your credentials in a highly secure environment and never share them over unsecure communication channels (e.g., plain text emails, standard messaging apps, or public forums).
    3. Assumption of Liability: Your organization is solely responsible for maintaining the confidentiality of your API credentials. Flip is not liable for any unauthorized transactions, data breaches, or financial losses resulting from a leaked or mismanaged Secret Key.
    4. Incident Response: Rotate your keys periodically and immediately notify your flip PIC if you suspect any credential compromise so we can help secure your account.
    5. How to Rotate Your API Secret Key: We recommend rotating your keys periodically or immediately if you suspect a compromise. May you can also check our documentation page on how to rotate API Secret Key
    info

    Generating a new key will invalidate the old one, so plan this rotation during a maintenance window if possible.*

  4. Network & Connection Security: All data transmitted between your servers and our API must be encrypted.

    1. TLS Requirements: We require TLS 1.2 or higher for all API communications. Please ensure your backend infrastructure and networking libraries are up to date to prevent SSL/TLS handshake errors during connection establishment.
    2. Payload Signatures: For webhook events and callbacks, always validate the validation token to verify that the payload genuinely originated from our system and has not been tampered with.

  5. Disbursement Signatures (Recommended): For an additional layer of security specifically on disbursement-related APIs, we highly recommend enabling payload signatures. This prevents attackers from intercepting and altering your transaction payload in transit.

    1. How it works: You generate an RSA 2048-bit key pair, provide your Public Key to the Flip Sales PIC or Flip API Integration PIC, and use your Private Key to sign the request payload.
    2. Implementation: The generated Base64 encoded string must be passed in the X-Signature header for every disbursement request. For code snippets and cryptographic details, refer to the Signature Generation Guide.
FAQ: What if our infrastructure uses dynamic IPs and we cannot provide a static IP?

While highly discouraged, you can formally request an exemption to disable the IP whitelisting requirement. However, please be aware that bypassing this feature removes a critical, secondary layer of security. If you choose to opt out, your organization assumes full responsibility for any unauthorized access or transactions resulting from a compromised API Secret Key. Flip cannot be held liable for, nor intervene in, security breaches on accounts that have disabled IP protections.

2. How to Request IP Whitelisting​

To initiate the IP whitelisting process, please follow these steps:

  1. Compile your IPs: Prepare the exact list of static public IP addresses (or NAT Gateway IPs) that your production servers will use to connect to our API.
  2. Submit your request:
    • Send an email to [email protected]. Please ensure you include your registered Flip account email address in the request so we can accurately identify your merchant account.
  3. Wait for activation: Allow time for our team to process the request and apply the network rules.
  4. Verify the connection: Once our team confirms the IPs have been whitelisted, you must perform a test from your side to ensure the connection is working properly before routing live traffic. (See Section 3 below for testing instructions).

3. How to Verify Your IP Whitelist Status​

Once you have submitted your IPs and allowed time for the network rules to propagate, you should verify that the security feature is actively protecting your account before initiating live transactions. We recommend performing both a negative and positive test.

Step 1: The Negative Test (Verify Protection is Active) First, try making an API request from an IP address that has not been whitelisted (e.g., your local developer machine or standard office Wi-Fi).

  • ✅ Expected Result (401 Unauthorized): The system successfully blocked the unrecognized IP. This confirms the whitelist security feature is active on your account.
  • ❌ Warning Result (200 OK): If the request succeeds from a non-whitelisted IP, the IP Whitelist feature is not yet active. Your account is not currently restricted by IP. Please contact our support team before routing live traffic.

Step 2: The Positive Test (Verify Connectivity) Once you confirm the whitelist is active, run the same test directly from the production server or NAT gateway whose IP address you submitted for whitelisting.

Access your server's terminal (e.g., via SSH) and use a tool like curl to call a safe, read-only endpoint—such as retrieving your account balance. You will need to use Basic Authentication with a Base64 encoded Secret Key.

Sample CURL:

curl -X GET 'https://bigflip.id/api/v2/general/balance' \     
   -H 'Accept: application/json' \   
   -H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>'

(Note: To generate the correct Authorization string, append a colon : to the end of your Secret Key and encode the entire string in Base64. If you are testing in a non-production environment, ensure you replace the URL with the staging/sandbox endpoint).

Step 3: Analyze the Positive Test Response

  • ✅ 200 OK: Your IP is successfully whitelisted, your credentials are valid, and your server can establish a secure TLS connection. You are ready to route traffic.
  • ❌ 401 Unauthorized: If your Negative Test (Step 1) correctly returned a 401, but you also receive a 401 here, double-check your server's outbound IP to ensure it exactly matches the one you submitted to us.
  • ❌ Connection Timeout / Connection Refused: This usually indicates a firewall block on your side. Ensure your server's outbound rules allow external traffic to our API domain.

Did this answer your question?