Skip to main content
DocsNfpOnboarding Guide

Changelog

Document VersionDateDescription
v 1.020 Oct 2025Initial release
v 1.113 Nov 2025Updated the formatting
v 1.214 Nov 2025Improved document formatting and structure for clarity. Added official versioning to the nationality codes list. Updated all support contact references to use nfp-support@paynet.my. Enhanced API request/response examples with explicit JSON formatting. Clarified required user roles (now specifying "Team Manager"). Expanded troubleshooting section with detailed error codes and solutions. Added and addressed inline comments for collaborative feedback and documentation tracking. Corrected grammar and improved English throughout the document.
v 1.314 Nov 2025- Improved document formatting and structure for clarity.
- Added official versioning to the nationality codes list.
- Updated all support contact references to use nfp-support@paynet.my.
- Enhanced API request/response examples with explicit JSON formatting.
- Clarified required user roles (now specifying "Team Manager").
- Expanded troubleshooting section with detailed error codes and solutions.
- Added and addressed inline comments for collaborative feedback and documentation tracking.
- Corrected grammar and improved English throughout the document.
v 1.427 Nov 2025Updated API Base URL from openapigw.nfp.uat.inet.paynet.my to openapi.nfp.uat.inet.paynet.my

Introduction

This document provides a comprehensive guide for onboarding to the Open API platform. It details the process for generating API credentials, authenticating with the platform, and validating access through test endpoints. The guide is intended for technical teams responsible for integrating with the NFP Open API and assumes a basic familiarity with RESTful APIs and authentication mechanisms. The Sequence Diagram below is illustrating the service journey from request submission to getting response.

NFP Open API credential and usage flow ‌

Prerequisites

Before proceeding, ensure the following prerequisites are met:

  • You have access to the NFP Portal (UAT).
  • Your user account is assigned the Team Manager permission.
  • You have a secure method for storing sensitive credentials.

Onboarding Workflow

Step 1: User Login​

  1. Navigate to the NFP Portal (UAT).
  2. Log in using your assigned credentials.
  3. Confirm that your account is assigned with the Team Manager permission.

If not, contact the system administrator to request the appropriate access level.

Step 2: Generate API Credentials​

Important
API credentials are sensitive and will be displayed only once.
Please copy and store them immediately in a secure password manager or any other secure storage solution.

  1. After logging in, click your profile icon and navigate to the Settings section Guide 1

  2. Select the Client Credentials tab. Guide 2

  3. Click Generate button to create a new set of API credentials.

  4. The system will display the following credentials one time only:

    • APIKEYID
    • APIKEYSECRET
    • CLIENTID
    • CLIENTSECRET

Make sure to store all values securely before leaving the page.

Guide 3

Step 3: Authentication​

Before calling any Open API endpoint, you must first obtain an Access Token using your API credentials. This token authorises your requests and must be included with every API call.

Obtain Access Token​

Use your CLIENTID and CLIENTSECRET to request a new access token.

Endpoint

POST https://openapi.nfp.uat.inet.paynet.my/oauth2/token

Headers

x-api-key: <APIKEYSECRET>

Request Body

{
  "username": "<CLIENTID>",
  "password": "<CLIENTSECRET>"
}

Sample Response

{
  "AuthenticationResult": {
    "AccessToken": "eyJraWQiOiJmRzZ6Z25YOGcz...m8Jd6Jg",
    "ExpiresIn": 3600,
    "IdToken": "eyJraWQiOiJ2b2NYUThOcFdqWDJXVDMzdE...AiHBlre2yZzQ",
    "RefreshToken": "eyJjdHkiOiJKV1QiLCJlbmMiOiJBM...ma_RvA",
    "TokenType": "Bearer"
  },
  "ChallengeParameters": {}
}

Refresh Token​

When your access token expires, you can request a new one using the Refresh Token provided in the initial response.

Endpoint

POST https://openapi.nfp.uat.inet.paynet.my/oauth2/token/refresh

Headers

x-api-key: <APIKEYSECRET>

Request Body

{
  "refreshToken": "<RefreshToken>"
}

Sample Response

{
  "AuthenticationResult": {
    "AccessToken": "eyJraWQiOiI4RHZLU2JLSHdlQXh...u5O7zNw",
    "ExpiresIn": 3600,
    "IdToken": "yJraWQiOiJEbzJPM1ZnREpYdTUrQ3...SfnkQNT1ukLEg",
    "TokenType": "Bearer"
  },
  "ChallengeParameters": {}
}

Step 4: API Validation​

After obtaining your access token, validate your connectivity and credentials by calling the testing and functional endpoints.

Ping Endpoint (Connectivity Check)​

Verify your credentials and token by calling the Ping endpoint.

Use the Ping endpoint to confirm that your authentication token is valid and that you can successfully connect to the Open API.

Endpoint

GET https://openapi.nfp.uat.inet.paynet.my/nfp-api/v2/server/ping

Headers

authorization: Bearer <AccessToken>

Sample Response:

{
  "message": "pong"
}

Mule Check Endpoint​

Use this endpoint to validate an individual's identification information.

Endpoint

GET https://openapi.nfp.uat.inet.paynet.my/nfp-api/v2/server/mule-check

Headers

authorization: Bearer <AccessToken>

Request Body Parameters

KeyRequiredDescription
idSignature (string)MandatorySHA256 signature of idNo and idType
idType (string)Mandatorymykad - Malaysian Identity Card. passport - Passport. bric - BRIC. police_id - Police ID. army_id - Army ID.
idNo (string)MandatoryThe id number of the person
nationality (string)ConditionalONLY required for passport and bric. Use the two-letter ISO 3166-1 alpha-2 nationality code (e.g., MY for Malaysian, SG for Singaporean).
purpose (string)Mandatory01 - Account Opening 02 - CDD 03 - Database Update

For example,

ID TypeSample Request
Passport

{
  "idSignature": "e5345875986f1160c9bde7c7ec2de0a0c37319d3edeefb8290a68878f817e2b0",
  "idType": "passport",
  "idNo": "K1234567",
  "nationality": "KR",
  "purpose": "01"
}
MyKad

{
  "idSignature": "e5345875986f1160c9bde7c7ec2de0a0c37319d3edeefb8290a68878f817e2b0",
  "idType": "mykad",
  "idNo": "700131011234",
  "purpose": "01"
}

Sample Responses

Response CodeSample Response
200 SuccessFor `passport` and `bric` ID types, the `nationality` field is required. In the response, the `nationality` returned corresponds to the value used in the search query to validate the individual. It does not represent all nationalities associated with the person.
{
  "httpStatusCode": "OK",
  "status": 200,
  "message": "success",
  "muleCheck": {
    "idSignature": "...",
    "idType": "passport",
    "idNo": "A1234567",
    "nationality": "MY",
    "muleTier": "2",
    "muleTierDescription": "Suspected"
  }
}
For other ID types that do not support nationality-based searches (e.g., `mykad`, `police_id`, `army_id`), the response will **NOT** include a `nationality` field.
{
  "httpStatusCode": "OK",
  "status": 200,
  "message": "success",
  "muleCheck": {
    "idSignature": "...",
    "idType": "mykad",
    "idNo": "700131011234",
    "muleTier": "3",
    "muleTierDescription": "Watchlist"
  }
}
403 Forbidden
{
  "status": 403,
  "httpStatusCode": "FORBIDDEN",
  "message": "The authenticated user does not have the required permissions to perform this operation. Please contact the administrator to access this resource."
}
404 Not Found
{
  "httpStatusCode": "NOT_FOUND",
  "status": 404,
  "message": "Record not found",
  "muleCheck": null
}
400 Bad Request
{
  "httpStatusCode": "BAD_REQUEST",
  "status": 400,
  "message": "Invalid ID signature",
  "muleCheck": null
}
400 Bad Request
{
  "httpStatusCode": "BAD_REQUEST",
  "status": 400,
  "message": "Missing nationality code",
  "muleCheck": null
}
400 Bad Request
{
  "httpStatusCode": "BAD_REQUEST",
  "status": 400,
  "message": "Unsupported nationality code",
  "muleCheck": null
}

Appendix

Mule Tier​

TierDescription
1Confirmed
2Suspected
3Watchlist
4Reference

Nationality Codes​

Note: The nationality field is mandatory for passport and bric ID types. Use the two-letter ISO 3166-1 alpha-2 country code.

Below is the list of supported nationality codes (Version: 1.0):

NationalityCode
AfghanAF
AlbanianAL
AlgerianDZ
AmericanUS
AndorranAD
AngolanAO
Antiguans or BarbudansAG
ArgentineanAR
ArmenianAM
AustralianAU
AustrianAT
AzerbaijaniAZ
BahamianBS
BahrainiBH
BangladeshiBD
BarbadianBB
BelarusianBY
BelgianBE
BelizeanBZ
BenineseBJ
BhutaneseBT
BolivianBO
Bosnian or HerzegovinianBA
BrazilianBR
BritishGB
BruneianBN
BulgarianBG
BurkinabeBF
BurmeseMM
BurundianBI
CambodianKH
CameroonianCM
CanadianCA
Cape VerdeanCV
Central AfricanCF
ChadianTD
ChileanCL
ChineseCN
ColombianCO
ComoranKM
CongoleseCG
Costa RicanCR
CroatianHR
CubanCU
CypriotCY
CzechCZ
DanishDK
DjiboutiDJ
DominicanDO
DutchNL
East TimoreseTL
EcuadoreanEC
EgyptianEG
EmirianAE
Equatorial GuineanGQ
EritreanER
EstonianEE
EthiopianET
FijianFJ
FilipinoPH
FinnishFI
FrenchFR
GaboneseGA
GambianGM
GeorgianGE
GermanDE
GhanaianGH
GreekGR
GrenadianGD
GuatemalanGT
Guinea-BissauanGW
GuineanGN
GuyaneseGY
HaitianHT
HonduranHN
HungarianHU
I-KiribatiKI
IcelanderIS
IndianIN
IndonesianID
IranianIR
IraqiIQ
IrishIE
IsraeliIL
ItalianIT
IvorianCI
JamaicanJM
JapaneseJP
JordanianJO
KazakhstaniKZ
KenyanKE
Kittian and NevisianKN
KuwaitiKW
KyrgyzKG
LaotianLA
LatvianLV
LebaneseLB
LiberianLR
LibyanLY
LiechtensteinerLI
LithuanianLT
LuxembourgerLU
MacedonianMK
MalagasyMG
MalawianMW
MalaysianMY
MaldivanMV
MalianML
MalteseMT
MarshalleseMH
MauritanianMR
MauritianMU
MexicanMX
MicronesianFM
MoldovanMD
MonacanMC
MongolianMN
MoroccanMA
Mosotho (Losotho)LS
Motswana (Batswana)BW
MozambicanMZ
NamibianNA
NauruanNR
NepaleseNP
New ZealanderNZ
NicaraguanNI
NigerianNG
NigerienNE
North KoreanKP
NorwegianNO
OmaniOM
PakistaniPK
PalauanPW
PanamanianPA
Papua New GuineanPG
ParaguayanPY
PeruvianPE
PolishPL
PortuguesePT
QatariQA
RomanianRO
RussianRU
RwandanRW
Saint LucianLC
SalvadoranSV
SamoanWS
San MarineseSM
Sao TomeanST
SaudiSA
SenegaleseSN
SerbianRS
SeychelloisSC
Sierra LeoneanSL
SingaporeanSG
SlovakianSK
SlovenianSI
Solomon IslanderSB
SomaliSO
South AfricanZA
South KoreanKR
SpanishES
Sri LankanLK
SudaneseSD
SurinamerSR
SwaziSZ
SwedishSE
SwissCH
SyrianSY
TaiwaneseTW
TajikTJ
TanzanianTZ
ThaiTH
TogoleseTG
TonganTO
Trinidadian or TobagonianTT
TunisianTN
TurkmenTM
TurkishTR
TuvaluanTV
UgandanUG
UkrainianUA
UruguayanUY
UzbekistaniUZ
VenezuelanVE
VietnameseVN
YemeniteYE
ZambianZM
ZimbabweanZW

Troubleshooting​

Error CodeRecommended Action
403 ForbiddenYour account may not have the necessary permissions to access the API.
Verify your access level, and contact the system administrator if the issue persists.
400 Bad RequestOne or more required fields may be missing or incorrectly formatted.
Check that all parameters are included and follow the expected data types and formats.
Token IssuesIf you receive authentication-related errors:
-Ensure your access token has not expired.
-Confirm that you are using the correct CLIENTID, CLIENTSECRET, and API key.
-Refresh the token if needed.
Credential LossAPI credentials cannot be recovered once generated.
If they are lost or not recorded, generate a new set from the Client Credentials section in the National Fraud Portal.

info

For further assistance, please contact the system administrator or the NFP Support Team at nfp-support@paynet.my.