Skip to main content

Flip Checkout Redirection

1. Overview​

To ensure a smooth integration with Flip checkout redirection, 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 Accept Payment, please follow the steps given below:

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 by Redirection Link, you need to create the payment redirection link that can be redirected customer from your website/application to Flip checkout payment page. Where your customer can complete the payment using a variety of available payment methods.

For redirection, Flip checkout offers several integration flows or steps. Here are the differences between these flows:

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 payment redirection link. When the customer is redirected to the Flip Checkout page, they can proceed directly to choose the payment method without needing to input their details again.

2. 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...
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 customer redirected to Flip Payment checkout page, 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 customers are redirected to when opening the payment redirection link. 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 checkout step with minimum request. You can redirect the customer from your web/app by using link provided in the link_url, where they 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": ""
}

Customer Payment Journey for checkout step​

Customers can pay their bill by opening the payment link, entering their name and email, and then selecting their preferred payment method. You can simulate a payment using the following this sample the payment redirection link.

Image 1Image 2Image 3
info

If your customer chooses to use bank transfer, they will need to log in to their personal Flip account before completing the payment.

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?