ReD Shield Integration Guide

ReD Shield Integration Guide

ACI ReD Shield is a real-time fraud prevention solution tailored to the needs of eCommerce merchants and payment service providers (PSPs).
In order to get a live configuration and account, please contact your account manager.
More information on ReD Shield

NOTE: The examples in this guide are here to support technical integration, however to get the best from ReD Shield fraud screening we recommend working with the ReD Shield fraud screening experts to define the best data and fraud rules for your business..

You can use the ReD Shield in two ways:


ReD Shield as a standalone risk service

There is a special endpoint for sending a fraud check against the ReD Shield independent of a payment:

https://test.planetpaymentgateway.com/v1/redShield

A minimal request to the ReD Shield 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 ReD Shield account setup you want to send in much more data. These are the parameter groups that are relevant for a ReD Shield 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 ReD Shield 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.

ReD Shield in combination with a payment request

The integration even becomes easier if you send in a payment and want to add Red Shield's 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 PIPE payment

Depending on where and when you collect the data necessary for the ReD shield request you can either send the parameters in your initial call as shown in step 1 of the PIPE checkout to this Url:
https://test.planetpaymentgateway.com/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.planetpaymentgateway.com/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.planetpaymentgateway.com/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.planetpaymentgateway.com/v1/registrations/{registration's ID}/payments
Any data you've already registered will automatically be reused and sent to the ReD Shield for a risk check.
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 PIPE one-click-payment tutorial.
As for the other payment endpoints, the prerequisite is that ReD shield 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 ReD Shield could alter the Result Code to values starting with 100.400. This means the transaction was highlighted by ReD Shield 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 ReD rejection

You can simulate three responses from the ReD Shield 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
ValueResponse
redPayment void and transaction denied by ReD Shield
yellowPayment void and transaction challenged by ReD Shield
errorPayment void and data error by ReD Shield

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= ReD 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.