Flip Direct API - Static Virtual Account

1. Overview

The Flip Direct API also offers a static virtual account option. A Static Virtual Account (Static VA) is a type of virtual account where the account number is fixed and does not change across transactions. Static VAs are generally associated with a specific customer or purpose and are commonly used for recurring payments, such as subscription services, school or corporate payment collections, or utility bill payments like IPL.

However, the API for static virtual accounts is different from the Accept Payment API. To ensure a successful integration with the Flip Static VA API, please follow the steps below. These steps will guide you from initial testing to production, ensuring your system is ready for smooth and efficient operations.

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

Important: Link ID Format Change - Action Required before April 10, 2026

The link_id and bill_link_id fields will change from variable-length (1-10 digits) to exactly 19 digits on April 10, 2026.

All partners are expected to comply with this change no later than April 10, 2026. If your system uses INT or 32-bit integer types, you must update to BIGINT or VARCHAR before the deadline to avoid service disruptions.

Read the full announcement and migration guide →

2. 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...

3. Create Static Virtual Account Trasaction

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

Environment	Method	URL
Test Mode	POST	https://bigflip.id/big_sandbox_api/payment-gateway/static-va *still not available
Staging Mode	POST	[Flip-Staging-Domain]/big_api/payment-gateway/static-va
Live Mode	POST	https://bigflip.id/api/payment-gateway/static-va

Request Header

Key	Value	Description
Authorization	Basic Base64(<FLIP_API_SECRET_KEY + :>)	The API key used to authenticate the request. For more details, refer to this.
Content-Type	application/x-www-form-urlencoded	Specifies the media type of the request body.

Request Details

Requirement	Required	Description
email	Yes	Email of the customer. The email should be unique per customer.
customer_name	Yes	Name of the customer (No special chars allowed).
payment_method_name	Yes	Payment channel for the VA. Possible values : bca, mandiri, bsm, bri, cimb, permata, bni.
amount_type	No	Amount type of the VA. fixed will have a fixed amount while the custom will have a custom amount for the VA. You can see each VA type availability here.
amount	No	Amount of the VAN. If type is fixed then this value must be filled.
reference_id	No	Reference ID of the static VA transaction. Max length is limited to 255 characters.
type	No	Possible values : single or multiple
expired_date	No	Static VA expiration date. VA can’t be inquired or receive payments any more. Format: YYYY-MM-DD HH:mm.
customized_va_unique_numbers	No	Customized unique number to be appended at the end of generated VA. Please check the unique number format here

info

For the type parameter, if the VA type is set to single, it means the Static VA can only be used for a single payment. Once the payment is completed, the VA will be automatically deactivated. However, deactivated VA numbers can be reactivated using the Update VA Status API. The Update Static VA API is designed to modify the status or details of the VA without changing the VA number. Flip will always return the same VA number as long as the associated email remains unchanged.

On the other hand, a multiple type Static VA allows customers to make repeated payments to the same VA. The VA remains active after each successful payment and can continue receiving payments.

By default, the VA type is set to single.

Minimum Sample Request:

  curl --location 'https://<flip-staging-domain>/big_api/payment-gateway/static-va' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -H 'Accept: application/json; charset=UTF-8' \
  -H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>' \
  -d '[email protected]' \
  -d 'customer_name=user test' \
  -d 'payment_method_name=mandiri' \
  -d 'amount_type=fixed' \
  -d 'amount=250000'

Sample Response:

Here is an example of the API response for the Create Static VA API.

{
 "email": "[email protected]",
 "customer_name": "user test",
 "virtual_account_number": "8902290272268882",
 "payment_method_name": "mandiri",
 "amount_type": "fixed",
 "amount": 250000,
 "type": "single",
 "expired_date": null,
 "status": "active"
 }

Currently our Static Virtual Accounts do not support custom VA numbers. The VA numbers are generated by Flip and are unique to each email. The VA number remains consistent, so a unique email is required for each VA transaction.

Customer Payment Journey for Virtual Account payment

For Static VA, you can provide the Virtual Account number to your customers or display it on your website or app. Customers can then make payments directly using their mobile banking, internet banking, or ATM.

Payment instruction are available here.

info

Refer to this page for more information about the Static VA API Reference.

4. Handling Accept Payment - Static VA Callback

When customer already paid the VA or the VA Number 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:

Attribute	Description
data	JSON object string with details of the transaction (see example below)
token	Validation 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/static-va/callback' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'data={"id":"PGPWF10117333832606873768","bill_link":"flip.id\/$staticva\/#8902290272268882-1733383260575","bill_link_id":2502091430251230005,"bill_title":"8902290272268882-1733383260575","sender_name":"user test","sender_email":"[email protected]","sender_bank":"mandiri","sender_bank_type":"virtual_account","amount":250000,"status":"SUCCESSFUL","created_at":"2024-12-05 14:21:00"}&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.
     SUCCESSFUL

     data={
     "id": "PGPWF10117333832606873768",
     "bill_link": "flip.id/$staticva/#8902290272268882-1733383260575",
     "bill_link_id": 2502091430251230005,
     "bill_title": "8902290272268882-1733383260575",
     "sender_name": "user test",
     "sender_email": "[email protected]",
     "sender_bank": "mandiri",
     "sender_bank_type": "virtual_account",
     "amount": 250000,
     "status": "SUCCESSFUL",
     "created_at": "2024-12-05 14:21:00"
     }&token=$2y$13$UsffNb9Y69sU4r5PzWgPwu038C28EUTM8wxSe4COTImnKbtQMnjzKxxsd

     CANCELLED

     A callback with a CANCELLED status can only occur when the Virtual Account number is expired. This happens when your customer haven't finish the transaction until the expiry time.

     data={
     "id": "PGPWF1011688450285522",
     "bill_link": "flip.id/$pengguna/#8856505853867619-1688450285495",
     "bill_link_id": 2502091430251230005,
     "bill_title": "8856505853867619-1688450285495",
     "sender_name": "Rian F",
     "sender_email": "[email protected]",
     "sender_bank": "permata",
     "sender_bank_type": "virtual_account",
     "amount": 15000,
     "status": "CANCELLED",
     "created_at": "2023-07-04 12:58:05",
     "reference_id": "abc"
     }&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 All Payment API. You can retrieve the transaction details by the reference id from Create Static VA request 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.

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.

Static Virtual Account Amount Type

payment_method_name	Fixed Amount	Custom Amount
bca	Yes	Yes
bri	Yes	Yes
mandiri	Yes	Yes
permata	Yes	Yes
bni	Yes	No
bsm	Yes	No
cimb	Yes	Yes

Custom VA Number

The Virtual Account number consists of 16–18 digits, formatted as:

(5–9 digits bank_code) + (7–9 digits unique number)

For example:

• BCA VA: (190081044)(543674658)
• Mandiri VA: (890229027)(5436746)

The list of unique numbers supported by each bank can be seen in the table below.

Bank	Unique Number	Total VA Number
bca	9	18
bri	9	18
mandiri	7	16
permata	8	16
bni	8	18
bsm	8	16
cimb	7	15

Reusing Virtual Account Number

To reuse the same unique number for a specific customer and bank combination, you must either complete the initial transaction successfully or set the Virtual Account status to inactive using the Update Status VA API.

Once either condition is met, you can generate a new Virtual Account with the same unique number.

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!