ConnectIn Integration Guide

Integration very much depends on the brands and workflows that you would like to enable. ConnectIn supports all our currently supported brands and the following online workflows:

Real-time workflows
  • Pre-Authorization
  • Capture
  • Debit / Sale
  • Reversal/Void
  • Refund
  • Credit (Stand-alone refund)
Redirect workflows
  • Pre-Authorization with redirect
  • Debit / Sale with redirect
  • Receipt
  • Async Notification

NOTE: ConnectIn does not support any offline/batch processes/workflows.

Real-time workflows

We will send requests that will be formatted as URL encoded parameters in the HTTP body, such as:

authentication.userId={userId}&authentication.password={password}&authentication.entityId={entityId}&amount=92.00&currency=EUR&paymentBrand=VISA&card.number={cardNum}&card.expiryMonth=12&card.expiryYear=2018&card.holder=Test Holder

Your application will parse the request parameters and after processing will need to return a JSON string in response, such as:

{
  "id":"{id}",
  "paymentType":"DB",
  "paymentBrand":"VISA",
  "amount":"92.00",
  "currency":"EUR",
  "descriptor":"example_descriptor",
  "result":{
    "code":"{our result code format}",
    "description":"{result description}"
  },
  "resultDetails":{
    "AcquirerResponse":"{your response code format}"
  },
  "card":{
    "bin":"420000",
    "last4Digits":"0000",
    "holder":"Jane Jones",
    "expiryMonth":"05",
    "expiryYear":"2018"
  },
  "timestamp":"2017-05-22 10:07:21+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_d77cdfc5ec77455c843972d197c57f1d"
}

Redirect workflows

For redirection workflows, where the shopper is sent to an external page to make the payment, the shopperResultUrl is populated with the URL that the shopper should be redirected to after payment is made (or attempted). The notificationUrl is also populated in case you will be using async notifications to update the transaction status (see below for more details).

authentication.userId={userId}&authentication.password={password}&authentication.entityId={entityId}&amount=92.00&currency=EUR&paymentBrand=VISA&card.number={cardNum}&card.expiryMonth=12&card.expiryYear=2018&card.holder=Test Holder&shopperResultUrl={shopperResultUrl}&notificationUrl={notificationUrl}

You should reply with the details of where to redirect the shopper and store the shopperResultUrl for returning the shopper later.

{
  "id":"{id}",
  "paymentType":"DB",
  "paymentBrand":"VISA",
  "amount":"92.00",
  "currency":"EUR",
  "descriptor":"example_descriptor",
  "result":{
    "code":"{our result code format}",
    "description":"{result description}"
  },
  "resultDetails":{
    "AcquirerResponse":"{your response code format}"
  },
  "card":{
    "bin":"420000",
    "last4Digits":"0000",
    "holder":"Jane Jones",
    "expiryMonth":"05",
    "expiryYear":"2018"
  },
  "redirect":{
    "url":"{redirectUrl}",
    "method":"POST",
    "parameters":[
      {
        "name":"examplepostparam",
        "value":"examplevalue"
      }
    ]
  },
  "timestamp":"2017-05-22 10:07:21+0000",
  "ndc":"8a8294174b7ecb28014b9699220015ca_d77cdfc5ec77455c843972d197c57f1d"
}

Redirecting the shopper and updating the transaction status

Once the payment / pre-payment is completed you should return the shopper to the shopperResultUrl (if applicable) and notify us of the status of the payment attempt. There are two ways to tell us the status:

  1. Pass the status with the redirection to the shopperResultUrl as a querystring parameter status.
  2. Pass the status by sending a separate asynchronous notification with the status parameter to the notificationUrl

Additionally to the status, by using the resultDetails object, it is possible to enrich the response with specific information related to the acquirer or APM. There is not limit in the number of parameters that can be returned in the resultDetails. These parameters will be send back to the merchant in the response.

Passing the status with the shopper redirection

The shopperResultUrl has the format https://{test.}ppipe.net/connectors/asyncresponse;jsessionid={sessionId}?asyncsource=UCONNECT&type=redirect&method={method}&data={data}&uuid={id}&ndcid={id}.

To inform us of the status at the same time as redirecting the shopper you should append a querystring parameter status e.g. https://test.ppipe.net/connectors/asyncresponse;jsessionid={sessionId}?asyncsource=UCONNECT&type=redirect&method={method}&data={data}&uuid={id}&ndcid={id}&status={status}&resultDetails.{name}={value}

Passing the status with an asynchronous notifications

The notificationUrl has the format https://test.ppipe.net/connectors/asyncresponse;jsessionid={sessionId}?asyncsource=UCONNECT&type=notification&method={method}&data={data}&uuid={id}&ndcid={id}

To inform us of the status process POST a request using the notificationURL and append a parameter status e.g. https://test.ppipe.net/connectors/asyncresponse;jsessionid={sessionId}?asyncsource=UCONNECT&type=notification&method={method}&data={data}&uuid={id}&ndcid={id}&status={status}&resultDetails.{name}={value}

Signature in the PASS THROUGH mode

In the PASS THROUGH mode the shopperResultUrl and notificationUrl must be digitally signed.
The signature is HMACSHA256 hash calculated with secret value configured in the ACI back office system.

  • All parameters must be used in the following format to calculate hash: name1=value1|name2=value2|...nameN=valueN
  • All parameters must be put in alphabetical order before hashing.
  • The signature must be appended to the URL as query parameter called signature: asyncsource=UCONNECT&type=redirect&method={method}&data={data}&uuid={id}&ndcid={id}&status={status}&resultDetails.{name}={value}&signature={signature}