Upgrade Account KYC Detail

Get approved KYC data for a Finpay Money user.

Technical Specification

Environment	Method	URL	Version
Development	POST	https://snapstag.finnet.co.id/api/v1.0/kyc/details	V 1.0.0
Production	POST	https://snap.finnet.co.id/api/v1.0/kyc/details	V 1.0.0

Header

No	Name	Type	Mandatory	Description
1	Authorization	String	M	Bearer B2B access token. Format: Bearer <access_token>.
2	X-TIMESTAMP	String	M	ISO 8601 timestamp. Format: YYYY-MM-DDTHH:mm:ss+07:00.
3	X-SIGNATURE	String	M	HMAC-SHA512 signature of the request payload.
4	X-PARTNER-ID	String	M	Merchant ID provided by Finnet. Example: SNAPDEVPSD.
5	Content-Type	String	M	Always application/json.

Body Request

No	Name	Type	Mandatory	Min Length	Max Length	Description
1	partnerReferenceNo	String	M	10	64	Unique partner-side reference. Must match the value used for the account upgrade.
2	merchantId	String	M	—	128	Registered and user-bound merchant ID. Finnet provides this during onboarding.
3	merchantPass	String	M	—	—	Merchant password provided by Finnet. Encrypt it with AES-128. Example: 123456 becomes 1jdzWuniG6UMtoa3T6uNLA==.
4	phoneNo	String	M	10	15	Finpay Money user phone number. Use 62xx or 08xx. This identifies the KYC record.

Sample Request

{
  "partnerReferenceNo": "3891230000000000029",
  "merchantId": "SNAPDEVPSD",
  "merchantPass": "1jdzWuniG6UMtoa3T6uNLA==",
  "phoneNo": "628123456789"
}

Body Response

No	Name	Type	Mandatory	Description
1	responseCode	String	M	Response code. See Response Code List.
2	responseMessage	String	M	Request result description.
3	partnerReferenceNo	String	M	Echoes the partnerReferenceNo sent in the request.
4	kycData	Object	C	KYC data object. Returned only when responseCode is 2001200.
5	kycData.encryptedData	String	C	All KYC fields encrypted as an AES-256-CBC Base64 string.
6	kycData.checksum	String	C	SHA-256 hash of the plaintext JSON. Use it to validate data integrity after decryption.

Decrypted KYC data

Decrypt kycData.encryptedData with AES-256-CBC. Use the secret key and IV provided during onboarding. The decrypted plaintext is JSON with the following fields.

No	Field	Type	Sample Value	Description
1	phoneNumber	String	628123456789	Active user phone number in 62xx format.
2	fullName	String	nabil nur	Full name from the KTP.
3	birthPlace	String	bogor	Place of birth.
4	birthDate	String	1979-04-23	Date of birth in YYYY-MM-DD format.
5	gender	String	P	L for male or P for female.
6	nationalId	String	1536216304290001	16-digit NIK.
7	address	String	kp. tolenjeng RT/RW 007/002, SUKAGALIH, SUKARATU, KAB. TASIKMALAYA 46415	Full KTP address.
8	occupation	String	KARYAWAN SWASTA	Current occupation.
9	nationality	String	WNI	WNI or WNA.
10	email	String	[e-mail]	Registered email address.

Sample Response

KYC approved — HTTP 200

{
  "responseCode": "2001200",
  "responseMessage": "Request has been processed successfully",
  "partnerReferenceNo": "3891230000000000029",
  "kycData": {
    "encryptedData": "U2FsdGVkX1+vX8k3...base64encodedstring...==",
    "checksum": "a3f5c8e2d4b7910f2c3e6a8d1b4f7c0e9a2d5b8e1c4f7a0d3b6e9c2f5a8d1b4"
  }
}

KYC not approved — HTTP 403

{
  "responseCode": "4031200",
  "responseMessage": "KYC not approved. Current status: In Process",
  "partnerReferenceNo": "3891230000000000029"
}

Merchant not bound — HTTP 403

{
  "responseCode": "4031201",
  "responseMessage": "Merchant not bound to this user",
  "partnerReferenceNo": "3891230000000000029"
}

User not found — HTTP 404

{
  "responseCode": "4041200",
  "responseMessage": "User not found with provided phoneNo",
  "partnerReferenceNo": "3891230000000000029"
}

Bad request — HTTP 400

{
  "responseCode": "4001200",
  "responseMessage": "Bad request. Missing or invalid parameter: phoneNo",
  "partnerReferenceNo": "3891230000000000029"
}

Response Code List

No	HTTP Code	Response Code	Description
1	200	2001200	KYC data retrieved successfully.
2	400	4001200	Bad request. A parameter is missing or invalid.
3	401	4011200	Unauthorized. The token is invalid or expired.
4	403	4031200	KYC is not approved. Status: In Process, Rejected, or Not Found.
5	403	4031201	Merchant is not bound to this user.
6	404	4041200	No user matches the provided phoneNo.
7	500	5001200	Internal server error.