This article is a supplementary reference topic for integrating Verifi's Cardholder Dispute Resolution Network (CDRN) with Smart Dispute for Issuers. For more information about implementing Smart Dispute for Issuers, see the Implementation Guide.

Verifi's cases represent the dispute created by Smart Dispute for Issuers when the card issuer is contacted. The Verifi case is created by the issuer through a POST into the CDRN API. An issuer is able to use the GET and PUT HTTP methods to poll and retrieve case information, then close the case.

CDRN cases flow through a status life cycle as they are handled and processed by the issuer, partner, and the CDRN platform. Once a Verifi case is created, it is managed by the network for resolution. The issuer can revoke a case request by updating the case status to REVOKED. When this occurs, a notification is sent to the partner to ensure that any resolution steps can be reverted. Both the Dispute and Cancel case types can be involved in a revoke notification.

If the merchant is Verifi-eligible, the Verifi API Create case is initiated using the InitiateCreateVerifiCase activity rule.

All required entries, such as case data, request XML body, REST service headers, and signature generation, are completed in the activity before the REST connector is invoked.

Authentication and authorization

API requests use basic authorization. The header parameter contains a Base64 encoded representation of the issuer's assigned username/password credentials. These credentials are allocated during account setup and are provided to the issuer.

Signature generation

To validate the authenticity of messages, a message signature is generated. The Hash-based Message Authentication Code (HMAC) is constructed using a HMAC-SHA1(RFC 2104) hash algorithm, formatted with Base64 encoding, and passed in the x-verifi-signature header parameter on each request.

The request signature is validated prior to processing to ensure that the request payload has not been manipulated in transit. Signature generation uses a shared secret in combination of canonicalized message parameters.

GET/DELETE Signature generation

The Signature generation process of the GET and DELETE methods uses the following request attributes in the following order, with each value separated by "\n":

• HTTP method
• Host header value
• Resource URI (everything after the host and before the query string parameters)
• Byte-sorted, unencoded query string parameters, which are separated by "&" when more than one pair is used (<parameter>=<value>)
• x-verifi-api-version header value
• x-verifi-timestamp header value

GET Signature example request

GET https://api.cdrn.com/issuers/cases/1234

Assumptions:

• UTC Time of 2012-03-01T17:00:00Z
• Issuer ID of 888

Generate a string to sign:

StringToSign ="GET" + "\n" +

"api.cdrn.com" + "\n" +

"/issuers/cases/1234" + "\n" +

"" + "\n" +

"1.0" + "\n" +

"2012-03-01T17:00:00Z" + "\n";

Signature = Base64.Encode(HMAC-SHA1(UTF8.Encode(StringToSign)));

Pass the signature value on the request in the x-verifi-signature header.

POST/PUT Signature generation

Signature generation of POST and PUT methods use the following request attributes in the following order, with each attribute separated by "\n":

• HTTP method
• Host header value
• Resource URI (everything after the host and before the query string parameters)
• Canonicalized XML request body with whitespace removed
• x-verifi-api-version header value
• x-verifi-timestamp header value

PUT Signature example request

PUT https://api.cdrn.com/issuers/cases/1234

<?xml version="1.0" encoding="utf-8"?>

<case xmlns="http://api.issuer.cdrn.com/domain" id="12345">

<status>CLOSED</status>

</case>

Assumptions:

• UTC Time of 2012-03-01T17:00:00Z
• API Version 1.0

Generate a string to sign:

StringToSign = "PUT" + "\n" + "api.cdrn.com" + "\n" +

"/issuers/cases/1234" + "\n" +

"<case xmlns=\"http://api.issuer.cdrn.com/domain\" "

"id=\"12345\"><status>CLOSED</status></case>" + "\n" +

"1.0" + "\n" + "2015-03-01T17:00:00Z" + "\n";

Signature = Base64.Encode(HMAC-SHA1(UTF8.Encode(StringToSign)));

Pass the signature value on the request in the x-verifi-signature header.

The above logic is achieved by the following rules:

• Data transform rule: GenerateVerifiSignature

  In the second step of the data transform, the HMACSHA1Encode function is called to generate the signature.

• Data Page Rule: D_CreateVerifiCase
• Connect REST rule: CreateVerifiCase

REST connector construction

The Verifi API enables synchronous and asynchronous processing of requests leveraging the HTTP status codes to indicate how the system is handling the request. The CDRN Issuer API follows a RESTful API implementation. It supports HTTP/1.1 calls only.

Each request must be created with the following attributes:

• API URL (Ex: https://api.cdrn.com/issuers/)
• API Version (Version 1.0)
• Encoding (UTF-8)
• Request Headers

• Response headers