Flip Direct API - Retail (Convenience Store)

1. Overview

To ensure a smooth integration with Flip direct 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.

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.

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 →

With Flip Direct API, you can offer various payment options, like Retail (Alfamart). This integration lets you customize the user interface and avoids redirecting customers to Flip’s checkout page.

To accept payments through Flip for Business, use the Create Bill API to set up transactions by sending the customer details such as name, email, phone number, and chosen payment method.

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 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/v3/pwf/bill~~ *still not available
Staging Mode	POST	[Flip-Staging-Domain]/big_api/v3/pwf/bill
Live Mode	POST	https://bigflip.id/api/v3/pwf/bill

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/json`	Specifies the media type of the request body, ensuring it is in JSON format.

Request Details

Requirement	Required	Description
`title`	Yes	The title of the bill, displayed on the Flip payment checkout page.
`type`	Yes	Bill type. Acceptable values: `SINGLE` or `MULTIPLE`.
`step`	Yes	Integration type, for Flip Direct API, please use `direct_api`
`amount`	Yes	Payment amount, minimum Rp10,000.
`sender_name`	Yes	Name of the Customer.
`sender_email`	Yes	Email of the Customer.
`sender_bank`	Yes	Bank that is used for the payment. Value will be bank_code of Flip.
`sender_bank_type`	Yes	Payment type, possible value can be seen here.
`redirect_url`	No	The merchant's redirect URL, used after successful customer payment.
`reference_id`	No	A field to store your transaction identifier.
`expired_date`	No	Bill expiry date. The bill cannot be used beyond this date. Format: YYYY-MM-DD HH:mm.
`is_phone_number_required`	No	flag with boolean value if user required to input their phone number before select payment method in the Flip checkout page. Default: `false`
`is_address_required`	No	flag with boolean value if user required to input their address before select payment method in the Flip checkout page. Default: `false`
`item_details`	No	An array of objects that contains details of each item. Details item object
`sub_merchant_code`	No	The 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": "Test Payment #1984587",
      "type": "single",
      "step": "direct_api",
      "amount": 50000,
      "sender_name": "User Test",
      "sender_email": "[email protected]",
      "sender_bank": "alfamart",
      "sender_bank_type": "online_to_offline_account",
      "reference_id": "MerchantRefId03",
  }'

Sample Response:

Here is an example of the API response for the direct_api step with a minimal request. You can either share the Payment Code from account_number parameter to your customer or display it on your platform. For direct_api the bill status in the response will be inactive.

{
"link_id": 2502091430251230005,
"link_url": "https://<flip-staging-domain>/$testcompanyid1/#testpayment19845875544-8142",
"title": "Test Payment #19845875544",
"type": "SINGLE",
"amount": 50000,
"redirect_url": "https://flip.id",
"expired_date": null,
"created_from": "API",
"status": "INACTIVE",
"is_address_required": true,
"is_phone_number_required": true,
"step": "direct_api",
"customer": {
    "name": "User Test",
    "email": "[email protected]",
    "address": "Foo Bar",
    "phone": "085780244353"
},
"bill_payment": {
    "id": "PGPWF10117313007299842782",
    "amount": 50000,
    "unique_code": 0,
    "status": "PENDING",
    "sender_bank": "alfamart",
    "sender_bank_type": "online_to_offline_account",
    "receiver_bank_account": {
        "account_number": "99737",
        "account_type": "online_to_offline_account",
        "bank_code": "alfamart",
        "account_holder": "User Test"
    },
    "user_address": "Foo Bar",
    "user_phone": "085780244353",
    "created_at": 1731300730
},
"payment_url": "https://<flip-staging-domain>/pwf/transaction/consolidated?redirected_from=internal&id=69f13d81a5904a58a02e684b3da1722a",
"charge_fee": false,
"company_code": "testcompanyid1",
"product_code": "testpayment19845875544-8142",
"reference_id": "MerchantRefId02",
"sub_merchant_code": ""

}

Customer Payment Journey for `direct_api` step

CUSTOMIZE UI
REDIRECT TO FLIP'S PAYMENT PAGE

If you completely customize the checkout process in your app, customers can view the payment code directly on the checkout page of your app or website. You can retrieve the payment code from the account_number parameter in the API response.

If you choose to redirect your customers to Flip's checkout page instead, you can redirect your customer to payment_url in the API Response.

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:

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/accept-payment/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": "MerchantRefId03","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:

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
CANCELLED

data={
  "id": "PGPWF10117252588865176637",
  "bill_link_id": 2502091430251230005,
  "bill_link": "flip.id/pwf-sandbox/$fliptechlenterainspirasipertiwi-1/#testnewbill-2536",
  "bill_title": "Test New Bill ",
  "reference_id": "MerchantRefId03",
  "sender_name": "nisa",
  "sender_email": "[email protected]",
  "sender_bank": "alfamart",
  "sender_bank_type": "online_to_offline_account",
  "amount": 45000,
  "status": "SUCCESSFUL",
  "created_at": "2024-09-02 13:34:46"
}&token=$2y$13$UsffNb9Y69sU4r5PzWgPwu038C28EUTM8wxSe4COTImnKbtQMnjzKxxsd

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

data={
  "id": "PGPWF22595173324048856",
  "bill_link_id": 2502091430251230005,
  "bill_link": "flip.id/pwf-sandbox/$fliptechlenterainspirasipertiwi-1/#testnewbill-2536",
  "bill_title": "Test New Bill ",
  "reference_id": "MerchantRefId03",
  "sender_name": "nisa",
  "sender_email": "[email protected]",
  "sender_bank": "alfamart",
  "sender_bank_type": "online_to_offline_account",
  "amount": 45000,
  "status": "CANCELLED",
  "created_at": "2024-09-02 14:17:13"
}&token=$2y$13$UsffNb9Y69sU4r5PzWgPwu038C28EUTM8wxSe4COTImnKbtQMnjzKxxsd

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

1. Overview​

2. Preparation Steps Before Integration​

3. Create Trasaction​

API Endpoint​

Request Header​

Request Details​

Minimum Sample Request:​

Sample Response:​

Customer Payment Journey for direct_api step​

4. Handling Accept Payment Callback​

Sample CURL:​

Important Notes​