Fraud Management

Fraud Management is a real-time fraud prevention solution tailored to the needs of merchants, PSP,acquirers and everyone else processing payment transaction. In order to get a live configuration and account, please contact your account manager.

You can integrate Fraud Management in three ways:

• As a standalone risk service
• As a standalone risk service on stored payment data
• In combination with a payment request
• Information on how to implement the tieback message can be found here

---

Fraud Management as a standalone risk service

There is a special endpoint for sending a fraud check against the Fraud Management API independent of a payment:

https://test.onlinepayments.pt/v2/redShield

A minimal request to the Fraud Management would look like this:

If you compare this to an ordinary server-to-server credit card request, you'll find that the two are almost the same: the only field that isn't mandatory for a payment anyway is the merchantTransactionId.

Depending on your business's needs and your Fraud Management account setup, you want to send in much more data. These are the parameter groups that are relevant for a Fraud Management transaction, see the API reference for an extensive explanation of the single parameters:

• customer
• billing
• shipping
• cart
• threeDSecure
• giftcard
• risk

Therefore a full requests that uses all parameters for Fraud Management would rather look like this:

The Response will contain the results of the fraud check as well as echo back the parameters you sent in with the requests.

Fraud Management as a standalone risk service for stored payment data

A Fraud Management scan on already registered payment data can also be made against the registration.id as a stand-alone request (i.e. without requesting a payment).

Fraud Management in combination with a payment request

The integration even becomes easier if you send in a payment and want to add Fraud Management fraud check capabilities on top of it. You only have to send one request and based on your system configuration both the risk check and the payment are executed.
In essence, you're sending the same request with the same parameters, only the parameter paymentType has to be added compared to a risk-only request.
These are the different endpoints you can use:

As part of a COPYandPAY payment

Depending on where and when you collect the data necessary for the Fraud Management request you can either send the parameters in your initial call as shown in step 1 of the COPYandPAY checkout to this Url:

https://test.onlinepayments.pt/v1/checkouts

. As an alternative you can also send the parameters in a following POST call by referencing the checkout's ID you got back in the response to your first call:

https://test.onlinepayments.pt/v1/checkouts/{checkout's ID}

As part of a Server-to-Server payment

Using the interactive editor on the Server-to-Server API's tutorial, you can send the additional parameters together with the full payment account data from this Url:

https://test.onlinepayments.pt/v1/payments

As part of a payment that references a registration

You can also make use of registrations by sending your payment to this endpoint:

https://test.onlinepayments.pt/v1/registrations/{registration's ID}/payments

Any data you've already registered will automatically be reused and sent to Fraud Management for a risk assessment.
The interactive editor at the bottom of the Server-to-Server one-click-payment tutorial lets you try that out easily.
The same applies to the interactive editor of the COPYandPAY one-click-payment tutorial.
As for the other payment endpoints, the prerequisite is that Fraud Management is configured on the entity you're sending to.

Response evaluation for combined payment and risk requests

For your combined payment and risk request you will receive a response that still contains only one response code: In the case of a successful risk check and payment this will be just one of the success codes.
Anything other than an Accept from Fraud Management could alter the Result Code to values starting with 100.400. This means the transaction was highlighted by Fraud Management and could warrant further investigation. The payment itself will not have been executed for result codes for result codes of the 100.400-group.

Simulate Fraud Management rejection

You can simulate three responses from the Fraud Management simulator by passing the following two parameters with the request:

• customer.givenName=simulate
• customer.surname, which can be one of the three values listed in the table below

Value	Response
red	Deny by Fraud Management
yellow	Payment void and transaction challenged by Fraud Management
error	Error on the Fraud Management risk system

Case Manager Tieback

If enabled, the Tieback feature of Case Manager will automatically send each Approve and Cancel command, and research notes, to a URL (provided by the merchant or PSP) to integrate the decision with your native systems. Case Manager also allows Administrators to set up Auto Analysts that automatically process transactions, that meet specified criteria, at scheduled times.

The tieback message is sent via HTTP or HTTPS to the merchant/PSPs web server.

Implementing Tieback

Creating the Tieback Message Request

The Tieback Message Request consists of an HTTP POST message which includes standard headers (ContentLength, Content-Type, Host, Connection, User-Agent, and Expect), optional user-defined headers, and a custom message body. The message body contains transaction-related data that the merchant requests. A typical message body in a Tieback Request is in the format Client key= Fraud Management value. All key/value pairs are delimited by an ampersand. You must provide your keys to us. For example, if your key for Transaction ID is TID, you must let us know, so that the message can be created as you will expect it.

Tieback Keys

Tiebacks are standalone requests which need to be mapped to the transaction in the merchant system. Therefore we and the merchant must agree a specific end-to-end ID, which identifies the transaction in the merchant system and our system. The configuration of the tieback keys will be done during the implementation phase together with the implementation manager. For nearly every key that you can send in a transaction, we can send the associated value back to you in Tieback. Some examples of keys that you might want to receive are: TransactionID, ClientID, SubClientID, Decision, CancelCode, Notes, ProcessbyUserID and ProcessDateTime. You can also include your own data, such as username and password. To do this, provide the key/value pair to your account manager and it will be appended to your Tieback message body, as shown (bold) in the example below.

client=000000&subclientid=100001&transactionid=ABC123&acitransactionid=000000100001ABC20160914090137168&decision=CANCEL&userid=ANUser&cancelreason=216¬e=lorem+ipsum&processdate=2016-09-14 13:00:00.000&password=NX436T&username=test1

Sample Tieback Message Request

POST /CallbackRequestSvc/v4.0/CallBackRequestService.svc HTTP/1.1
Content-Length: 221
Content-Type: application/x-www-form-urlencoded
Host: qa.redworldwide.com
Connection: Keep-Alive
User-Agent: Apache-HttpClient/4.0 (java 1.5)
Expect: 100-Continue
client=000000&subclientid=100001&transactionid=ABC123&acitransactionid=000000100001ABC20160914090137168&decision=CANCEL&userid=ANUser&cancelreason=216¬e=Lorem+ipsum+dolor+sit+amet&processdate=2016-09-14+13%3A00%3A00.0

Sample Message Content

Note: Not all keys will be returned in your message. For example, in the Approve message, there is no cancel reason, since the transaction was approved and not cancelled and therefore the cancel reason key will not be returned.

• Approve: client=000000&subclientid=100001&transactionid=ABC123&acitransactionid=000000100001ABC20160914090137168&decision=APPROVE&userid=ANUser&note=Lorem+ipsum+dolor+sit+amet&processdate=2016-09-14 13:00:00.000
• Cancel: client=000000&subclientid=100001&transactionid=ABC123&acitransactionid=000000100001ABC20160914090137168&decision=CANCEL&userid=ANUser&cancelreason=216&note=Lorem+ipsum+dolor+sit+amet&processdate=2016-09-14 13:00:00.000
• Pend: client=000000&subclientid=100001&transactionid=ABC123&acitransactionid=000000100001ABC20160914090137168&decision=PENDING&userid=ANUser&note=Lorem+ipsum+dolor+sit+amet&processdate=2016-09-14 13:00:00.000

Response

You should respond to a tieback message using HTTP status codes. Populating the HTTP response body is optional

Note: Any success response should not have the response body populated.

Description	HTTP Status Code	HTTP Response Body Text	Pass/Fail
Success	200		Pass
Accepted	200		Pass
Bad Request	400	Bad Request	Fail
Unauthorized	401	Unauthorized	Fail
Forbidden	403	Forbidden	Fail
Not Found	404	Not Found	Fail

Additional HTTP codes can be used.

Configuration

In order to setup tieback the merchant/PSP needs to do the following:

• Provide a destination URL that can receive HTTP or HTTPS POST messages.

Note: Up to three URLs can be provided but only one can be active at a time. If a non-standard port (80 for HTTP or 443 for HTTPS) needs to be used, provide the IP address and port.

• Ensure your Content-Type header is set to application/x-www-form-urlencoded;
• Provide the optional tieback header to send in the POST message.

Note: All standard headers will be received in addition to these user-defined headers

• Communicate which keys (fields) to pass in the tieback request;
• Provide the time in minutes (up to 5) that we shall wait before retrying a failed tieback message and the number of retries (up to 5);
• Provide a list of HTTP responses you will respond with.

Tieback Testing

For initial testing, we recommend you use HTTP protocol so that in the need for any troubleshooting, the messages are not encrypted and the content can be seen. Once testing confirmed the connection and message flow is successful and correct, change to HTTPS.
When you are ready to test Tieback, an Analyst must process a Case Manager transaction.
To process a Case Manager transaction

1. Choose Actions area, use the Pend, or Cancel options to take action on a transaction; or, click Approve.

• • If you want the transaction to be Pended (held for a specific time frame until you can review it further), either leave the default date and time shown or use the calendar picker and time drop down menu to select a date and time. The pend time will be based on your time zone, and Customer Services will recalculate the server's time to your time zone and add the pend time. Click the Go button. Customer Services moves the transaction to the appropriate place in the queue based on the specified date and time.
  • If you want to Cancel the transaction, select a reason for cancellation, and click the Go button. Customer Services removes the transaction from all queues.
    OR
  • Click Approve to accept the transaction and release it from its holding state. The Transaction Details page for the next transaction in the queue opens automatically.

When the transaction is processed, the system immediately sends a Tieback Request (via HTTP POST), to your Web Server via a URL. This Tieback message passes the keys and values that you requested. Then your system sends a response message to CSI indicating success or failure.
Customer Services will wait for a response from your Web Server for each Tieback message. If the Tieback fails for any reason, the Client Administrator can view (and resubmit) the failed Tieback from the Failed Tiebacks window.

Failed Tiebacks

The Customer Service sends transaction information to your web server when an Analyst Approves or Cancels a transaction.
When the web server receives the information, you can access the transaction information to integrate with other native systems. Your web server also generates a message and response code and sends it back to the Customer Service. When a failure occurs, Customer Service is not able to deposit the transaction information to your web server location.
Customer Service attempts to send the transaction information to your web server several times before considering the data exchange a true failure.
Once Customer Service exhausts all attempts, the transaction appears in the Failed Tiebacks list. It is from this list that the Client Administrator can resubmit the Tieback for a one-time attempt. If the Tieback fails again, it will reappear on the Failed Tieback list. Alternatively, the Client Administrator can delete the Tieback from the list.

To resubmit a tieback message, navigate to the failure list

Setup > View my list of queues > Failed Tiebacks

Select the transaction from the list by using the check box and then click Resubmit.