Skip to main content
DocsNational Fraud PortalOnboarding Guide

We've Launched a New Documentation Website (Beta Launch)

The documentation for DuitNow is now available on our newly launched documentation platform. This is an initial beta rollout of our new documentation site, designed to become the long-term home for all documentation moving forward.

You'll find the familiar content you're used to—now hosted on a new platform that will progressively receive updates and enhancements.

We encourage you to start accessing DuitNow materials there to explore the new experience and ensure you're viewing the latest documentation updates. If you have any feedback, please reach out to us.

Visit the New Documentation Website
info

v1.0

  • Initial Mule-check API Release.

v1.1

  • Standardise nationalities based on ISO 1366.

v1.2

  • Introduced a new API endpoint to support v1.2 enhancement. Added isMuleIdFlagged to the response payload, with the value true / false. Mule IDs that are classified as Tier 4 OR Not Matched, now return HTTP 200 with isMuleIdFlagged: false instead of a 404 Bad Request response.

Introduction

This document provides a comprehensive guide for onboarding to the NFP Public 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 Public 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 Public API credential and usage flow ‌

NFP Public API

NFP Public API

Integrates your system with our fraud data to strengthen and empower safeguarding processes within your financial services.

NFP API

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 role.
  • You have a secure method for storing sensitive credentials.

Onboarding Workflow​

Step 1: User Login​

1. Navigate to the NFP Portal.

2. Log in using your assigned credentials.

3. Confirm that your account is assigned with the Team Manager role.

info

If not, contact the system administrator or the NFP Support Team at nfp-support@paynet.my 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 Public 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 Public API.

Endpoint

GET https://openapi.nfp.uat.inet.paynet.my/nfp-api/v1/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/v1/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",
  "isMuleIdFlagged": true,
  "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",
  "isMuleIdFlagged": true,
  "muleCheck": {
    "idSignature": "...",
    "idType": "mykad",
    "idNo": "700131011234",
    "muleTier": "3",
    "muleTierDescription": "Watchlist"
  }
}
If the request/query result is categorized under Tier 4 or NOT matched, the response will show a 200 status, and isMuleIdFlagged returns false, without the muleCheck object.
{
  "httpStatusCode": "OK",
  "status": 200,
  "message": "success",
  "isMuleIdFlagged": false
}
403 ForbiddenApplication Level
{
  "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."
}
API Gateway Level
{
  "Message": "User is not authorized to access this resource with an explicit deny in an identity-based policy"
}
400 Bad Request
{
  "httpStatusCode": "BAD_REQUEST",
  "status": 400,
  "message": "Invalid ID signature"
}
400 Bad Request
{
  "httpStatusCode": "BAD_REQUEST",
  "status": 400,
  "message": "Missing nationality code"
}
400 Bad Request
{
  "httpStatusCode": "BAD_REQUEST",
  "status": 400,
  "message": "Unsupported nationality code"
}
401 Unauthorized
{
  "message": "Unauthorized"
}

Appendix​

Revised Mule Flag Indicator​

The new isMuleIdFlagged field will indicate the mule flag outcome as follows. This allows Participants to determine the mule flag outcome directly from the response body, instead of relying on HTTP status codes to interpret business outcomes.

Mule ID Check OutcomeisMuleIdFlagged Value
ID matched as the below:
T1 - Confirmed
T2 - Suspected
T3 - Watchlist		true
ID matches as the below:
T4 - Reference Only		false
ID not found in PayNet's mule recordsfalse

Nationality Codes & Phone Code​

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):

NationalityCodePhone Code
AfghanAF+93
AlbanianAL+355
AlgerianDZ+213
AmericanUS+1
AndorranAD+376
AngolanAO+244
Antiguans or BarbudansAG+1268
ArgentineanAR+54
ArmenianAM+374
AustralianAU+61
AustrianAT+43
AzerbaijaniAZ+994
BahamianBS+1242
BahrainiBH+973
BangladeshiBD+880
BarbadianBB+1246
BelarusianBY+375
BelgianBE+32
BelizeanBZ+501
BenineseBJ+229
BhutaneseBT+975
BolivianBO+591
Bosnian or HerzegovinianBA+387
BrazilianBR+55
BritishGB+44
BruneianBN+673
BulgarianBG+359
BurkinabeBF+226
BurmeseMM+95
BurundianBI+257
CambodianKH+855
CameroonianCM+237
CanadianCA+1
Cape VerdeanCV+238
Central AfricanCF+236
ChadianTD+235
ChileanCL+56
ChineseCN+86
ColombianCO+57
ComoranKM+269
CongoleseCG+242
Costa RicanCR+506
CroatianHR+385
CubanCU+53
CypriotCY+357
CzechCZ+420
DanishDK+45
DjiboutiDJ+253
DominicanDO+1809
DutchNL+31
East TimoreseTL+670
EcuadoreanEC+593
EgyptianEG+20
EmirianAE+971
Equatorial GuineanGQ+240
EritreanER+291
EstonianEE+372
EthiopianET+251
FijianFJ+679
FilipinoPH+63
FinnishFI+358
FrenchFR+33
GaboneseGA+241
GambianGM+220
GeorgianGE+995
GermanDE+49
GhanaianGH+233
GreekGR+30
GrenadianGD+1473
GuatemalanGT+502
Guinea-BissauanGW+245
GuineanGN+224
GuyaneseGY+592
HaitianHT+509
HonduranHN+504
HungarianHU+36
I-KiribatiKI+686
IcelanderIS+354
IndianIN+91
IndonesianID+62
IranianIR+98
IraqiIQ+964
IrishIE+353
IsraeliIL+972
ItalianIT+39
IvorianCI+225
JamaicanJM+1876
JapaneseJP+81
JordanianJO+962
KazakhstaniKZ+7
KenyanKE+254
Kittian and NevisianKN+1869
KuwaitiKW+965
KyrgyzKG+996
LaotianLA+856
LatvianLV+371
LebaneseLB+961
LiberianLR+231
LibyanLY+218
LiechtensteinerLI+423
LithuanianLT+370
LuxembourgerLU+352
MacedonianMK+389
MalagasyMG+261
MalawianMW+265
MalaysianMY+60
MaldivanMV+960
MalianML+223
MalteseMT+356
MarshalleseMH+692
MauritanianMR+222
MauritianMU+230
MexicanMX+52
MicronesianFM+691
MoldovanMD+373
MonacanMC+377
MongolianMN+976
MoroccanMA+212
Mosotho (Losotho)LS+266
Motswana (Batswana)BW+267
MozambicanMZ+258
NamibianNA+264
NauruanNR+674
NepaleseNP+977
New ZealanderNZ+64
NicaraguanNI+505
NigerianNG+234
NigerienNE+227
Northern IrishGB+44
North KoreanKP+850
NorwegianNO+47
OmaniOM+968
PakistaniPK+92
PalauanPW+680
PanamanianPA+507
Papua New GuineanPG+675
ParaguayanPY+595
PeruvianPE+51
PolishPL+48
PortuguesePT+351
QatariQA+974
RomanianRO+40
RussianRU+7
RwandanRW+250
Saint LucianLC+1758
SalvadoranSV+503
SamoanWS+685
San MarineseSM+378
Sao TomeanST+239
SaudiSA+966
ScottishGB+44
SenegaleseSN+221
SerbianRS+381
SeychelloisSC+248
Sierra LeoneanSL+232
SingaporeanSG+65
SlovakianSK+421
SlovenianSI+386
Solomon IslanderSB+677
SomaliSO+252
South AfricanZA+27
South KoreanKR+82
SpanishES+34
Sri LankanLK+94
SudaneseSD+249
SurinamerSR+597
SwaziSZ+268
SwedishSE+46
SwissCH+41
SyrianSY+963
TaiwaneseTW+886
TajikTJ+992
TanzanianTZ+255
ThaiTH+66
TogoleseTG+228
TonganTO+676
Trinidadian or TobagonianTT+1868
TunisianTN+216
TurkishTR+90
TurkmenTM+993
TuvaluanTV+688
UgandanUG+256
UkrainianUA+380
UruguayanUY+598
UzbekistaniUZ+998
VenezuelanVE+58
VietnameseVN+84
YemeniteYE+967
ZambianZM+260
ZimbabweanZW+263

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