Skip to main content

Flip Checkout - PopUp

1. Overview​

To ensure a smooth integration with Flip checkout pop-up, 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.

NOT AVAILABLE in Test Mode/Sandbox Environment

Currently, the API is available only in our staging environment. Please contact your Flip PIC or the Flip B2B API Integration team to request staging access

You can access the previous version of the technical documentation (v2) for Accept Payment here.

To receive payments through Flip for Business using the Pop-Up Mode, you need to embed a payment pop-up on your website or application. This pop-up allows your customers to complete their payments directly on your site, using a variety of available payment methods.

2. Backend Integration​

Flip Checkout Steps​

  1. checkout: In this step, the customer is required to enter their information, such as name, email, and other details, before selecting a payment method on the Flip Checkout page. This ensures the necessary data is collected directly from the customer.
  2. checkout_seamless: With this step, the merchant can pre-fill customer information like name, email, and phone number on your request for Flip Checkout PopUp. When the PopUp is show, customer can proceed directly to choose the payment method without needing to input their details again.

For popup, there are two integration that you need to do on merchant side, backend and frontend Integration. Please follow the steps bellow:

Prepare API Secret Key​

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. Due to this API is not ready yet in our TestMode/Sandbox environment. For development make sure you use Flip Staging 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...

Create Company Code and Product Code​

STAGING DOMAIN URL

Currently, the API is only available in our staging environment. To get access Flip staging domain, please contact your Flip PIC or the Flip B2B API Integration team to request staging access

API Endpoint​

EnvironmentMethodURL
Test ModePOSThttps://bigflip.id/big_sandbox_api/v3/pwf/bill *still not available
Staging ModePOST[Flip-Staging-Domain]/big_api/v3/pwf/bill
Live ModePOSThttps://bigflip.id/api/v3/pwf/bill

Request Header​

KeyValueDescription
AuthorizationBasic Base64(<FLIP_API_SECRET_KEY + :>)The API key used to authenticate the request. For more details, refer to this.
Content-Typeapplication/jsonSpecifies the media type of the request body, ensuring it is in JSON format.

Request Details​

In this step, after the Flip Payment checkout page show on your website/app, the customer is required to enter their information, such as name, email, and other details, before selecting a payment method on the Flip Checkout page. This ensures the necessary data is collected directly from the customer.

RequirementRequiredDescription
titleYesThe title of the bill, displayed on the Flip payment checkout page.
typeYesBill type. Acceptable values: SINGLE or MULTIPLE.
stepYesSpecifies the step when Flip Checkout pop up show on merchant web/app. More details here.
amountNoPayment amount, minimum Rp10,000. For the checkout step, leave blank for a flexible amount. The amount is required for the checkout-seamless step.
redirect_urlNoThe merchant's redirect URL, used after successful customer payment.
reference_idNoA field to store your transaction identifier.
expired_dateNoBill expiry date. The bill cannot be used beyond this date. Format: YYYY-MM-DD HH:mm.
is_phone_number_requiredNoflag with boolean value if user required to input their phone number before select payment method in the Flip checkout page. Default: false
is_address_requiredNoflag with boolean value if user required to input their address before select payment method in the Flip checkout page. Default: false
item_detailsNoAn array of objects that contains details of each item. Details item object
sub_merchant_codeNoThe unique identifier for your sub-merchant. Note: This code must be obtained from your Sales Representative prior to making the API call. If the code is not registered or is inactive, the transaction will be processed as a standard bill under your parent account without splitting logic. Learn more about Sub-Merchant Settlement

Minimum Sample Request:​

curl --location 'https://<flip-staging-domain>/big_api/v3/pwf/bill' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic <Base64(YOUR_FLIP_SECRET_KEY + :)>' \
--data '{
  "title": "Orderan Dinda",
  "type": "single",
  "step": "checkout",
  "amount": 7000000,
}'

Sample Response:​

Here is the sample API response for the checkout step with a minimal request. To display the payment pop-up, you need to pass the company_code and product_code values retrieved from the API response into your frontend. Below is an example of response API you can use company_code and product_code to trigger the pop-up. The customer will need to enter their name and email before proceeding to the next page to select a payment method.

{
  "link_id": 2502091430251230005,
  "link_url": "https://<flip-staging-domain>/$staticva/#billv3testing5324694598-4860",
  "title": "Orderan Dinda",
  "type": "SINGLE",
  "amount": 7000000,
  "redirect_url": "",
  "expired_date": null,
  "created_from": "API",
  "status": "ACTIVE",
  "is_address_required": false,
  "is_phone_number_required": false,
  "step": "checkout",
  "company_code": "YOUR_FLIP_COMPANY_CODE",
  "product_code": "FLIP_UNIQUE_PRODUCT_CODE",
  "reference_id": "",
  "sub_merchant_code": ""
}

3. Frontend Integration​

After obtaining the company_code and product_code from your backend, you can integrate the Flip Checkout Pop-Up modal into your website. Follow these steps to embed the Flip Checkout functionality:

Embed the Flip Checkout Script​

Include the Flip Checkout script in your HTML file. Add the following <script> tag in the <head> section or just before the closing </body> tag:

<script src="https://storage.googleapis.com/flip-prod-pay-checkout-popup-assets/checkout.iife.js"></script>

This script enables Flip Checkout functionality on your site.

Add the Checkout Button​

Create a button on your website that users can click to open the Flip Checkout modal:

<button id="checkout-button">Pay Now</button>

This button will be linked to the function that triggers the Flip Checkout modal.

Open the Checkout Modal​

In your JavaScript, write the logic to open the checkout modal using the company_code and product_code retrieved from your backend API. Here’s an example implementation:

document.getElementById('checkout-button').addEventListener('click', () => {
    const companyCode = 'your_company_code'; // Replace with value from backend
    const productCode = 'your_product_code'; // Replace with value from backend

    FlipCheckout.pay(companyCode, productCode, {
        onSuccess: (params) => {
            console.log('Payment Success:', params);
        },
        onPending: (params) => {
            console.log('Payment Pending:', params);
        },
        onClose: (params) => {
            console.log('Modal Closed:', params);
        },
        successClosePopupDuration: 5000, // Optional: Modal closes 5 seconds after success
    });
});
Click here’s the full example code for integrating the Flip Checkout Pop-Up modal:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title>Flip Checkout Integration</title>
<!-- Embed the Flip Checkout Script -->
<script src="https://storage.googleapis.com/flip-prod-pay-checkout-popup-assets/checkout.iife.js"></script>
</head>
<body>
<!-- Add the Checkout Button -->
<button id="checkout-button">Pay Now</button>

<script>
  document.getElementById('checkout-button').addEventListener('click', function () {
    // Start the loading spinner
    FlipCheckout.start();

    // Call the create bill API to retrieve companyCode and productCode
    fetch('https://merchant-backend-api-endpoint.com/create/flip/bill', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
      },
    })
      .then((response) => response.json())
      .then((data) => {
        if (data.company_code && data.product_code) {
          // Open the Flip checkout modal with the retrieved data
          FlipCheckout.pay(data.company_code, data.product_code, {
            onSuccess: (params) => {
              console.log('Payment Success:', params);
            },
            onPending: (params) => {
              console.log('Payment Pending:', params);
            },
            onClose: (params) => {
              console.log('Modal Closed:', params);
            },
            successClosePopupDuration: 5000, // Optional: Modal closes 5 seconds after success
          });
        } else {
          console.error('Invalid response:', data);
        }
      })
      .catch((error) => {
        console.error('Error creating bill:', error);
      });
  });
</script>
</body>
</html>

Whitelisting Merchant Domains​

Since the checkout modal is embedded as an iframe, merchant domain must be whitelisted by Flip to prevent CORS (Cross-Origin Resource Sharing) issues both for development and production. Whitelisting ensures that the checkout modal functions securely and seamlessly on your website.

Request Domain Whitelisting to Flip
To whitelist your domain, send a request to Flip’s support team with the following details:

  1. Flip Id: Provide your flip id, may you can retrieve this value from Flip Dashboard
  2. Merchant Name: Your business name.
  3. Domain(s): The full URL of the website where Flip Checkout will be integrated. For example: https://www.yourwebsite.com
  4. Contact Information: Your contact email or phone number.

You can reach out to [email protected] to initiate the whitelisting process. Once your domain is approved, you can embed the Flip Checkout iframe without encountering CORS issues.

Javascript Function Callback Options and Parameters​

When integrating the Flip Checkout pop-up using FlipCheckout.pay(), you can define callback functions to handle various payment events. These callbacks allow you to customize the behavior of your application based on the transaction's progress or user actions.

Callback Parameters:
All callback functions (onSuccess, onPending, onClose) share the same parameter structure, which includes:

  • companyCode: The company code associated with the transaction.
  • productCode: The product code for the specific transaction.
  • status: The payment status (e.g., 'success', 'pending', etc.).

Available Options:
You can configure the following callbacks when calling FlipCheckout.pay():

  1. onSuccess:
    Triggered when the payment is successfully completed. Example:
onSuccess: (params) => {
    console.log('Payment Success:', params);
}
  1. onPending:
    Triggered when the payment is created and is in a pending state. Example:
  onPending: (params) => {
      console.log("Payment Pending:", params);
  }
  1. onClose:
    Triggered when the user closes the modal, regardless of the payment status. Example:
onClose: (params) => {
    console.log('Modal Closed:', params);
}

4. Handling Accept Payment Callback​

When customer already paid the bill or the bill is expired, 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 details of the transaction (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":"FT1","bill_link":"flip.id/$<company_code>/#<product_code>","bill_link_id":2502091430251230005,"bill_title":"Cimol Goreng","reference_id": "","sender_name":"Jon Doe","sender_bank":"bni","sender_email":"[email protected]","amount":10000,"status":"SUCCESSFUL","sender_bank_type":"bank_account","created_at":"2021-11-29 10:10:10"}&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, customer data, amount transferred, status, bank code, and other relevant information. 
      data={
        "id": "PGPWF10117252588865176637",
        "bill_link_id": 2502091430251230005,
        "bill_link": "flip.id/pwf-sandbox/$fliptechlenterainspirasipertiwi-1/#testnewbill-2536",
        "bill_title": "Test New Bill ",
        "reference_id": "",
        "sender_name": "nisa",
        "sender_email": "[email protected]",
        "sender_bank": "mandiri",
        "sender_bank_type": "virtual_account",
        "amount": 45000,
        "status": "SUCCESSFUL",
        "created_at": "2024-09-02 13:34:46"
      }&token=$2y$13$UsffNb9Y69sU4r5PzWgPwu038C28EUTM8wxSe4COTImnKbtQMnjzKxxsd

  2. Verify the Accept Payment Status:

    • The status field will indicate the outcome of the transaction. For example:
      • SUCCESSFUL 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 Payment API. You can retrieve the transaction details by the link id from Create Bill response to get the latest status transaction.

  3. Process the Transaction:

    • If the transaction status is SUCCESSFUL, you should update your internal records to indicate the transaction was completed.
    • If the transaction status is CANCELLED, it means the bill has expired, and your customer can no longer make the payment.
    • If the transaction status is FAILED, this can only occur if the customer selected the Bank Transfer payment method. This failure happens when Flip is unable to transfer the funds to the merchant's bank account.

  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.

Important Notes​

  • IP Address: Kindly provide the IP address that will be used to send requests to Flip for whitelisting purposes by sending it to email [email protected] with following format :

    • Subject : Whitelist IP - Accept Payment
    • Body Contains :
      • Flip for Business company ID
      • List of IPs to be whitelisted

  • 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

Did this answer your question?