Overview

Within this section you will find a set of APIs to have your Agent KYC-ed by Flip prior to creating disbursement with Agent Money Transfer disbursement type. Unlike Special Money Transfer, the KYC done by Flip for Agent Money Transfer is required as non-PJP licensed companies usually don’t conduct KYC on their end as mandated by Bank Indonesia.

Step for Integration

To ensure a smooth integration with Flip's Agent Verification 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. To integrate with Money Transfer, please follow the steps given below:

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

2. Create Agent Identity

Request Details

Environment	Method	URL
Test Mode	POST	https://bigflip.id/big_sandbox_api/v2/agents
Live Mode	POST	https://bigflip.id/api/v2/agents

Requirement	Description
API Secret Key	The api key that will be used to authenticate the request. For more details, refer to Retrieving API Access Keys.
`name`	Agent’s full name.
`identity_type`	Type of identity.
`identity_number`	Identity number based on the type chosen.
`birth_date`	Agent’s birth date.
`birth_place`	Agent’s birth place.
`country_id`	Agent’s country code based on the identity chosen.
`province_id`	Agent’s province code based on the identity chosen.
`city_id`	Agent’s city code based on the identity chosen.
`district_id`	Agent’s district code based on the identity chosen.
`address`	Agent’s address based on the identity chosen.
`gender`	Agent’s gender.
`occupation`	Agent’s job.
`phone_number`	Agent’s phone number. It must be the one that has been verified by the company.

info

Identity number and phone number must be unique for an Agent. You can’t create duplicated agents with the same identity number or the same phone number under one company account.
Phone number must have been verified by the company before creating agent in Flip.

Sample Request:

curl -X POST 'https://bigflip.id/big_sandbox_api/v2/agents' \
-H 'Content-Type: application/x-www-form-urlencoded' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>' \
-d 'name=lalalalili' \
-d 'identity_type=ktp' \
-d 'identity_number=1243564789875643' \
-d 'birth_date=04-06-1998' \
-d 'birth_place=jakarta' \
-d 'country_id=1' \
-d 'province_id=1' \
-d 'city_id=1' \
-d 'district_id=1' \
-d 'address=jakarta' \
-d 'gender=female' \
-d 'occupation=government_employee' \
-d 'phone_number=085674563456' 

Sample Response:

Success

{
  "id": 497,
  "company_id": 45529,
  "name": "lililalalulu",
  "identity_type": "ktp",
  "identity_number": "1243564789875643",
  "birth_place": "jakarta",
  "birth_date": "04-06-1998",
  "gender": "male",
  "country_id": 1,
  "country_name": "Indonesia",
  "province_id": 1,
  "province_name": "Aceh",
  "city_id": 1,
  "city_name": "Kabupaten Simeulue",
  "district_id": 1,
  "district_name": "Teupah Selatan",
  "address": "jakarta selatan",
  "residence_country_id": null,
  "residence_country_name": "",
  "residence_province_id": null,
  "residence_province_name": "",
  "residence_city_id": null,
  "residence_city_name": "",
  "residence_district_id": null,
  "residence_district_name": "",
  "residence_address": "",
  "occupation": "GOVERNMENT_EMPLOYEE",
  "phone_number": "+6285674563456",
  "email": "johndoe3eee3@gmail.com",
  "kyc_status": "BASIC_DATA"
}

API Reference

Refer to this page for more information about the Create Agent Identity API Reference.

2. Upload Agent Identity Data

Request Details

Environment	Method	URL
Test Mode	PUT	https://api.flip.id/kyc-sandbox/api/v1/users/[agent_id]/identities
Live Mode	PUT	https://api.flip.id/kyc/api/v1/users/[agent_id]/identities

info

This endpoint uses a different base URL than the other Flip for Business endpoints, i.e: https://api.flip.id/kyc/api/v1.
You must hit this API twice, first to upload the ID image and second to upload selfie with ID image

Requirement	Description
API Secret Key	The api key that will be used to authenticate the request. For more details, refer to Retrieving API Access Keys.
`Request-ID`	Key Header with unique identifier for the request, used for tracking and troubleshooting purposes.
`agent_id`	Agent ID from Create Agent Identity response
`user_type`	Type of user. Agent = 1
`image`	Image file that wants to be uploaded.
`identity_type`	Type of identity. KTP = 1, Passport = 2
`selfie`	Flag denotes the uploaded file is the identity image or selfie with identity image. 0 = False, 1 = True

info

You need to add a Request-ID header option when using this endpoint.
A unique identifier for the request, used for tracking and troubleshooting purposes. In case of any errors, Flip can use this value to trace and investigate the specific request. The Request-ID will be formed of bigflip-[uuid], where the “uuid” (Universally unique identifier) has to be generated on your end.
Example: "Request-ID: bigflip-47EB7F57-5565-4BF0-B9DD-46C6268CEE71"

Sample Request:

curl -X PUT 'https://api.flip.id/kyc-sandbox/api/v1/users/497/identities' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>' \
-H 'Request-ID: bigflip-E23CDB10-6684-11EF-8664-0800200C9A66' \
-d 'user_type=1' \
-d 'image=@"/path-to-your-file"' \
-d 'identity_type=1243564789875643' \
-d 'birth_date=1' \
-d 'selfie=0' 

Sample Response:

Success

{
  "image_url": "https://flip.id/path/url/image.png"
}

3. Handling Upload Data Callback

A callback notification will be sent to your Agent Verification callback URL after you upload identity image and selfie with identity image. 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 (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.

Steps to Handle the Callback:

Receive the Callback:

The callback will include data such as the agent id , agent name, kyc status, and other relevant details. Parse this data to extract the necessary information.

UPLOAD_IDENTITY_SELFIE_SUCCESS
UPLOAD_IDENTITY_SELFIE_FAILED

data={
  "agent_id": 1,
  "agent_name": "John Doe",
  "kyc_status": "UPLOAD_IDENTITY_SELFIE_SUCCESS",
  "rejected_reason_code": null,
  "rejected_reason": null,
  "created_at": "2022-02-18 05:03:32",
  "updated_at": "2022-03-17 09:48:58",
  "submitted_at": null,
  "verified_at": null
}&token=YOUR_VALIDATION_TOKEN_KEY

data={
  "agent_id": 2,
  "agent_name": "John ",
  "kyc_status": "UPLOAD_IDENTITY_SELFIE_FAILED",
  "rejected_reason_code": 10,
  "rejected_reason": "The data that is filled in does not match with identity card",
  "created_at": "2022-02-18 05:03:32",
  "updated_at": "2022-03-17 09:48:58",
  "submitted_at": null,
  "verified_at": null
}&token=YOUR_VALIDATION_TOKEN_KEY

Extract and process the necessary data to update your records and trigger any follow-up actions.

Verify the KYC Status:
- Check the status field in the callback to determine whether upload selfie image is successful or not. The status will typically indicate SUCCESS UPLOAD_IDENTITY_SELFIE_SUCCESS, or UPLOAD_IDENTITY_SELFIE_FAILED for failure.
Process the Response:
- Based on the KYC status, you can proceed with your desired action. For instance:
  - If the upload data is success which means with status UPLOAD_IDENTITY_SELFIE_SUCCESS you may proceed with KYC Submission.
  - If the upload data is failed which can with status UPLOAD_IDENTITY_SELFIE_FAILED, you need to Upload Supporting Document.
Respond to the Callback:
- For this Agent’s KYC status callback, we will only send the callback once, so you have to make sure that your callback URL is always in good condition.
- It is mandatory to respond to the callback with HTTP Status Code 200 which Flip mark as success delivery.
- You can respond immediately to Flip and then process the callback data asynchronously to ensure prompt acknowledgement.

4. KYC Submission

After you received KYC status UPLOAD_IDENTITY_SELFIE_SUCCESS callback, you can continue to submit the KYC of your Agent to Flip.

Environment	Method	URL
Test Mode	PUT	https://api.flip.id/kyc-sandbox/api/v1/users/[agent_id]/submit
Live Mode	PUT	https://api.flip.id/kyc/api/v1/users/[agent_id]/submit

Requirement	Description
API Secret Key	The api key that will be used to authenticate the request. For more details, refer to Retrieving API Access Keys.
`user_type`	Type of user. Agent = 1
`agent_id`	Agent ID from Create Agent Identity response.

Sample Request:

curl -X PUT 'https://api.flip.id/kyc-sandbox/api/v1/users/[agent_id]/submit' \
-H 'Content-Type: multipart/form-data' \
-H 'Accept: application/json; charset=UTF-8' \
-H 'Authorization: Basic <Base64(Your-API-SecretKey + :)>' \
-H 'Request-ID: bigflip-32487iweurwer44534' \
-d 'user_type=1' 

Sample Response:

Success

{
  "message": "Submit success"
}

5. Handling KYC Status Callback

After you perform KYC Submission, Flip will send a callback to your designated webhook URL that you set on Flip Dashboard with the KYC result. This callback contains crucial information about the KYC status that you need to process befoe make disbursement.

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 content exactly the same as Upload Data Callback (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.

Steps to Handle the Callback:

Receive the Callback:

The callback will include data such as the account number, bank code, inquiry status, and other relevant details. Parse this data to extract the necessary information.

APPROVED
REJECTED

data={
  "agent_id": 1,
  "agent_name": "John Doe",
  "kyc_status": "APPROVED",
  "rejected_reason_code": null,
  "rejected_reason": null,
  "created_at": "2022-02-18 05:03:32",
  "updated_at": "2022-02-18 09:48:58",
  "submitted_at": "2022-02-18 09:50:32",
  "verified_at": "2022-02-18 10:01:00"
}&token=YOUR_VALIDATION_TOKEN_KEY

data={
  "agent_id": 1,
  "agent_name": "John Doe",
  "kyc_status": "REJECTED",
  "rejected_reason_code": "17",
  "rejected_reason": "Part of the data on the photo ID card is missing so it can’t be read in its entirety",
  "created_at": "2022-02-18 05:03:32",
  "updated_at": "2022-02-18 09:48:58",
  "submitted_at": null,
  "verified_at": null
}&token=YOUR_VALIDATION_TOKEN_KEY

Verify the KYC Status:
- Check the status field in the callback to determine whether the KYC is approved ot not. The status will typically indicate SUCCESS APPROVED, or REJECTED for failure.
Process the Response:
- Based on the KYC status, you can proceed with your desired action. For instance:
  - If the KYC submission is success which means with status APPROVED you may proceed with the money transfer.
  - If the KYC submission is failed which means with status REJECTED,you will need to upload or repair the data based on the rejection reason provided in the callback.
Respond to the Callback:
- For this Agent’s KYC status callback, we will only send the callback once, so you have to make sure that your callback URL is always in good condition.
- It is mandatory to respond to the callback with HTTP Status Code 200 which Flip mark as success delivery.
- You can respond immediately to Flip and then process the callback data asynchronously to ensure prompt acknowledgement.

If you have any further questions, please reach out to B2B API Integration team. Thank you!

Overview

Step for Integration​

1. Preparation Steps Before Integration​

2. Create Agent Identity​

Request Details​

Sample Request:​

Sample Response:​

2. Upload Agent Identity Data​

Request Details​

Sample Request:​

Sample Response:​

3. Handling Upload Data Callback​

4. KYC Submission​

Sample Request:​

Sample Response:​

5. Handling KYC Status Callback​

Step for Integration

1. Preparation Steps Before Integration

2. Create Agent Identity

Request Details

Sample Request:

Sample Response:

2. Upload Agent Identity Data

Request Details

Sample Request:

Sample Response:

3. Handling Upload Data Callback

4. KYC Submission

Sample Request:

Sample Response:

5. Handling KYC Status Callback