Discover_Image Fraud Alerts > Documentation

Overview

Discover Fraud Alerts provides early notification of customer-confirmed fraudulent activity to a merchant. It can provide an additional layer of defense against fraud prior to shipment of a Card-Not-Present order. Once the merchant receives an alert, they have the ability to take corrective action, such as stopping an order before they ship, calling back an order, or using data to build a negative file to reduce future fraud or chargebacks. The Discover Fraud Alerts API also speeds notification, which allows for near real-time alerts and customized reporting.

Authentication-Making the first API request is only few steps away


  1. All projects start in Sandbox mode. Sign up to create a project and get Client Application ID (API Key) Client Application Secret, Consumer Application Secret and API Plan name.

  2. All API requests must be authenticated with an OAuth token. To get the OAuth token, follow these simple steps

    1. Make a HTTP POST request to the endpoint /auth/oauth/v2/token with HTTP Authorization Header as Basic base64encoded(client_application_id:client_application_secret), Content-Type as application/x-www-form-urlencoded and Cache-Control as no-cache

    2. The response would contain an OAuth token along with token type and token expiry in seconds

    SAMPLE OAuth TOKEN REQUEST

    POST /auth/oauth/v2/token?grant_type=xyz&scope=RWDS_xyz HTTP/1.1
    Authorization: sdlfsdf0dskladfk123456
    Content-Type: application/json
    Cache-Control: no-cache

    SAMPLE RESPONSE

    Response-Status: HTTP/1.1 200 OK
    Cache-Control: no-store
    Content-Type: application/json;charset=UTF-8
    Pragma: no-cache
    {
    "access_token": "sdlfsdf0dskladfk123456",
    "token_type": "xyz",
    "expires_in": 00000,
    "scope": "RWDS_xyz"
    }

  3. Once an OAuth token is obtained, you can use the token along with Consumer Application Secret and API Plan name provided during Sandbox access in the HTTP Header of an API to make your first call. The same OAuth can be used for multiple API calls as long as it is not expired.

Access Error


The service authenticates and authorizes the client, and provides the following status codes when errors occur:

  1. 401 Unauthorized. The authorization credentials are either missing or incorrect. The caller has to provide the right credentials to be authenticated in order to access the service.
  2. 403 Forbidden. The request sent by the client was correct, but access to the resource identified by the URL is forbidden for some reason. The server understood the request, but is refusing to fulfill it.

API Structure


A typical API request would contain the sections HTTP Header, Request Header, Request Body as part of the request and HTTP Header, Response Header and Response Body as part of the response with some exception due to the nature of the API. Refer the individual end points to know more.

HTTP Header


We follow a robust standard for HTTP Header which includes the following parameters to be supplied while you are making an API request
Accept
Content-Type
Cache-Control
Authorization
X-DFS-C-APP-CERT
X-DFS-API-PLAN
While Accept, Content-Type and Cache-Control values are standard, Authorization which is the xAuth token obtained while authenticating, X-DFS-C-APP-CERT which is Consumer Application Certificate and X-ABC-API-PLAN which is API Plan name given to you at the time of registration to the Sandbox.
Our HTTP Header in the response will include Access, Content-Type and Cache-Control.

HTTP Status Codes


The HTTP Status Code returned in the response follows an industry API standard and designed to help you better interpret the underlying error.

  • Status code 200 to indicate the success of a service invocation; and the following HTTP status codes to assert error scenarios.
  • Status code 400 Bad Request. The request is submitted in malformed OR could not be completed due to a conflict with the current state of the resource.
  • Status code 401 UnAuthorized. The authorization credentials are either missing or incorrect. The caller has to provide the right credentials to be authenticated in order to access the service.
  • Status code 403 Forbidden. The request sent by the client was correct, but access to the resource identified by the URL is forbidden for some reason. The server understood the request, but is refusing to fulfill it.
  • Status code 500 Internal Server Error. The server/service is experiencing internal errors.
  • Status code 503 Service Unavailable. The request has been understood but has been refused. The System is in maintenance mode and maintenance window information is present in body.

Encrypted Content


For enhanced security, the card number must be encrypted before putting them into response body of getAlerts methods. Here are the steps.

  1. For the methods, which have the card number in the response body, the card number must be encrypted with a public key retrieved from certificate uploaded as part of registerPublicKey method, using the RSA encryption algorithm. Encryption is followed by Base64 encoding as detailed below :
    • Encrypt the Card Number JSON string by using RSA encryption algorithm where the key is obtained from certificate uploaded as part of registerPublicKey method and is kept safely by the partner.
    • Use base 64 url safe encoder to encode the encrypted Card Number JSON string and the initial vector. Concatenate both encoded string in form of Base64UrlSafeEncode(Number). Base64UrlSafeEncode (InitialVector).
    • Put the concatenated encoded card Number string into response JSON payload.
  2. The card number in the response from Discover needs to be decoded by the participant.

alerts/orgid

https://abc/access/product/v1/alerts/xxxxx/{ xxxxx}?fromDate=YY-MM-DD&toDate=YYYY-MMDD&PageResultCount=1&PageIndex=1 HTTP/1.1


Example of Get Alerts by date call

REQUEST ARGUMENTS


fraudTxnSentDate: string

The fraud transaction send date shows the last transaction date of format as MM/dd/YYYY

merchNbr: string | 16

Merchant Number assigned by Discover

Nrid: string | 15

Network Reference Identification number assigned by Discover

orderId: string | 16

Merchant's Order ID number

Postdate: string

Date transaction posted to Cardholder's Account

txnDesc: string | present | 43

Alphanumeric description

responseMessage: string | 20

Response Message

fraudTxnSentTime: string

Fraud transaction sent time is given as the transaction received time and the time limit format as hh:mm aa

LastFeedBackDate: string

Last date feedback was submitted for fraud alerts. LastFeedBackDate Format as MM/dd/YYYY

statusCode: string | present | 1

Status Codes defined for: 'C', 'I', 'F', 'P'

  • Confirmed Loss ( C)
  • Loss prevented - internal controls (I)
  • Loss prevented - due to fraud alerts (F)
  • Partial loss prevented (P)

savedAmount: string

Amount Saved. Maximum value of savedAmount is 999999999.99

statusCode: string | required | Length must be equal to 1

Should be one of the value from Array of items like

  • Confirmed loss (C)
  • Loss prevented - internal controls (I)
  • Loss prevented - due to fraud alerts (F)
  • Partial loss prevented (P)

suspectName: string | 40

Suspect Name can be alphanumeric

shippingAddress1: string | 40

Shipping address1 can be alphanumeric

shippingAddress2: string | 40

Shipping address2 can be alphanumeric

City: string | 30

City field can be alphanumeric

State: string | 3

State field can be alphanumeric

Country: string | 3

Country field can be alphanumeric

Zipcode: string | 15

Zip code field can be numeric

amountSaved: string

Optional or if null populates with original amount automatically

Notes: 250

Open field with no restriction or required format like a comment field

lastFeedBackDate: string

Last Feedback Date should be in format "YYYY/MM/dd"

fraudTranId: string | present | 16

Fraud alerts transaction Id is a Required field

REQUEST HTTP HEADERS


Accept:

Only accept application/json type

Content-Type:

Only accept application/json type

Cache-Control:

no-store

Authorization:

access token

X-DFS-C-APP-CERT:

< consumer application certificate >

X-DFS-API-PLAN:

< intended API Plan >

SAMPLE CURL REQUEST

curl -X GET\ '/pci/network/fraudalerts/v1/alerts/orgid/1235678?fromDate=2016-02-01&toDate=2016-03-01&PageResultCount=1&PageIndex=1'\
-H'authorization:sampletoken\
-H'cache-control:no-cache'\
-H'content-type:application/json'\
-H'x-dfs-api-plan:sampleapiplan'\
-H'x-dfs-c-app-cert:sampleappcert'

RESPONSE VALUES


statusCode: string | required | Length must be equal to 1

Should be one of the value from Array of items like
Confirmed loss (C),
Loss prevented - internal controls (I),
Loss prevented - due to fraud alerts (F),
Partial loss prevented (P)

suspectName: string | 40

Suspect Name can be alphanumeric

shippingAddress1: string | 40

Shipping address1 can be alphanumeric

shippingAddress2: string | 40

Shipping address2 can be alphanumeric

City: string | 30

City field can be alphanumeric

State: string | 3

State field can be alphanumeric

Country: string | 3

Country field can be alphanumeric

Zipcode: string | 15

Zip code field can be numeric

amountSaved: string

Optional or if null populates with original amount automatically

Notes: 250

Open field with no restriction or required format like a comment field

lastFeedBackDate: string

Last Feedback Date should be in format "YYYY/MM/dd"

fraudTranId: string | present | 16

Fraud alerts transaction Id is a Required field

SAMPLE RESPONSE

{
"responseHeader": {
"statusCode": "200"
},
"alertDetails": [
{

"cardNum": "c8OhKwSbH4EKnBzkgpQNFiGggRmsODLtV1uIUU/tTl7JDJWnc
SKw2LzjBZqglH/HPUkrWYq0f6yKOajR
ytB9+sVwUFmKVkAr1k8k3SUJEK3YMFxpkWHq976eYI4gYWygzwtVWU7wrgS2Uw37L4QrYa7NeUAJn
OW54ihUuiaRq4F9Loi4aO4hkwskG/Xc+Oq2fQ7x50m0o7w5kHGUKxjy1SrvB1TPAEin6ghvUlc802EeQy/
GImTIx3EBoJSA+RaPBm3PMgPwpn5wucHGpoOiAfUguvKDpOA4yyMsj7GTnI5GjrjCPpaG832lgr69O7x
EH/PU+IX2lTx9Tgq7CG4CsQ== "
,

"amount": "1",

"authDate": "03/27/2015",

"confrmfraudId": "1001395161",

"dbaName": "asdf",

"feedbckUpdtDate": "02/25/2016",

"fraudTxnSentDate": "06/19/2015",

"fraudTxnSentTime": "12:00 AM",

"merchNbr": "< orgid > 222222",

"nrid": null,

"orderId": null,

"postDate": null,

"txnDesc": "Apple",

"responseMessage": "Decline",

"statusCode": "P",

"savedAmount": "45.00",

"suspectName": "1234",

"shippingAddress1": "for july 20th House No-5",

"shippingAddress2": "USA Springfield",

"city": "Phoeni",

"state": "TN",

"country": "IND",

"zipCode": "803101",

"Notes": "july 20th changeUpdated"
},
{

"cardNum": "TCYfv5JsLmz1h7+TepjGLOJeLED+/mvQx62y3HcpiYQ+txUxNZpTWjRBkDN1xfYyLsWoBkmJqIdjCqnLj VH8DM3nCaVMfpfUUGdNi9Mdk6UQQtjAgzY1WgtusGgEbNKPGMBPV5IdRPWTcoAutHWfwMo1hxtlbe8HzpDd8nI2DUg3CDj1qr7amXKY8LIsrUrJgc4riCliOcAdHWeBC+ENsYB7SsQyBflv2kfvqyxr6MbdwDQ26Y F8qtmClPTlqY73NFfdnNTpzNTrnjVr7h+EMxa2rPTQmZRp4fOkDJUmNj1rSYNuBkqzmdpwkt0Q/ABOWyR6u8Q+QEjA6/egyudiYA== ",

"amount": "1",

"authDate": "05/13/2015",

"confrmfraudId": "1001395162",

"dbaName": "asdf",

"feedbckUpdtDate": "01/18/2016",

"fraudTxnSentDate": "06/19/2015",

"fraudTxnSentTime": "12:00 AM",

"merchNbr": "< orgid > 222222",

"nrid": "65115223969448",

"orderId": null,

"postDate": null,

"txnDesc": "Apple",

"responseMessage": "Decline",

"statusCode": "P",

"savedAmount": "1.00",

"suspectName": "1234",

"shippingAddress1": "House No-5",

"shippingAddress2": "USA Springfield",

"city": "Phoeni",

"state": "TN",

"country": "IND",

"zipCode": "803101",

"Notes": "Updated"
} ,
{

"cardNum": "Q9vkoIPyPfrOdUtSQpw1023PNg92Kuug3IFnl1s64f543zRVz5HDzPs++TKmcRlCgKjvweYk/ctUigRn/dkjx +YjrmxIAy5MtGSe2mYrJB1SXj0ASbOSkhX6A4ccCdS9+hf+0vfa8WVd+lNJqtjvFJlDDrNBz0Oa0rP1s8zid4XLl0Klyqn+R7QP1v82m1HLAGV5IA1tiwHS9OhMi3e47oMqxetYnMinrfLNXidoPo4l/JqTeF08fO2t+oPopf WWdaKiO9aMfpF/m2YANkyMmY/Dh8sBacXYmG6IL4BBF3aHrvnyDL07eLjnPs07UZr6pVnQclYThlJU63U97fGWqg==",

"amount": "1",

"authDate": "04/16/2015",

"confrmfraudId": "1001395163",

"dbaName": "asdf",

"feedbckUpdtDate": "01/27/2016",

"fraudTxnSentDate": "06/19/2015",

"fraudTxnSentTime": "12:00 AM",

"merchNbr": "222222",

"nrid": null,

"orderId": null,

"postDate": null,

"txnDesc": "Apple",

"responseMessage": "Decline",

"statusCode": "P",

"savedAmount": "45.00",

"suspectName": "1234",

"shippingAddress1": "House No-5",

"shippingAddress2": "USA Springfield",

"city": "Phoeni",

"state": "TN",

"country": "IND",

"zipCode": "803101",

"Notes": "Updated"
}
],

"pageIndex": 1,

"noOfAlerts": 12,

"pageCount": 4
}

Errors


Error Code Error Description HTTP Status Code
1001 User authentication failed 401
1003 Not authorized to access the resource! 403
6 The system has difficulty to process the request 500
2 Bad request 400
3101 Organization authentication failed 401
3102 Not authorized to access the resource! 403
3103 The System is maintenance mode 503
3104 Validation Error: Incorrect format for Pagination Alert count 400
3104 Validation Error: Value of Pagination Alert count should be between 1 and 100 intenance mode 506
3105 Service is facing issue in processing request
400
3105 There is an issue with the URL, method type (GET/POST), or media type. Please confirm the correct url, method type, and media type are being used.
400
3106 Business Service Exceptions 400
3107 Expired Certificate - Re-register new certificate 400