ConnectIn Integration Guide

ConnectIn Integration Guide

Quick links

The Payment Initiation Message (PIM) – PA, DB, CD

Independently of whether the payment workflow is asynchronous or synchronous (See workflows), the payment initiation message, PIM, contains always the same parameters specified in the table below. Payments can be initiated with the following payment methods: PA, DB or CD, amongst others.

The PIM message is sent to {name-of-your-endpoint}/v1/payments, except for referenced payments that are described later.

Column ACI API parameter of the table contains the names of the parameters sent to the integrator. Column Origin states where the value of the parameter was originated

  • Merchant Account: Parameter is set in the merchant account in BIP system.
  • Merchant Request: Merchant sets the value in the request to ACI.
  • System: ACI platform is appending automatically this parameter to the merchant request and merchant account parameters.
ACI API parameter Origin Description
amount amount ACI Payments API Amount of the payment order.
authentication.entityId Merchant Account Free usage for merchant authentication/credentials. on Integrator side.
authentication.password Merchant Account Free usage for merchant authentication/credentials. on Integrator side.
authentication.userId Merchant Account Free usage for merchant authentication/credentials. on Integrator side.
currency ACI Payments API Currency of the payment order.
customParameters[CUSTOM_DATA] Merchant Account Free usage for merchant authentication/credentials. on Integrator side.
customParameters[ShortId] System Internal ACI identifier
customParameters[UUID] System Internal ACI identifier
descriptor System or Merchant Request description of the payment order.
merchant.mcc Merchant Request or Merchant Account Merchant Category Code
merchantTransactionId Merchant Request Merchant Transaction ID
notificationUrl System Used by integrator to update status of payment order.
paymentBrand Merchant Request Payment brand of the payment order. E.g. ‘PAYPAL’, ‘VISA’, ‘MASTER’, etc.
paymentType Merchant Request Payment Type: PA, DB or CD
shopperResultUrl System Used by Integrator to redirect shopper to external payment system.
transactionCategory ACI Payments API or Merchant Account Transaction Category. E.g. Ecommerce, MailOrder, MOTO, etc.

NOTE: notificationUrl and shopperResultUrl are only intended for asynchronous workflows but are also forwarded to the integrator for synchronous payments like credit cards. In the latter case you can just ignore them.

Messages to the integrator for Credit Cards (CC) will also include following fields:

card.cvv Merchant Request
card.expiryMonth Merchant Request
card.expiryYear Merchant Request
card.holder Merchant Request
card.number Merchant Request

Only if the payment initiation message is originated in ACI test environment, it contains the parameter testMode

testMode [only present in stage] Merchant Request. Values={INTERNAL|EXTERNAL}

PIM for Referenced payments – Backoffice

Examples of backoffice operations are: Refund (RF), Reversal (RV) and Capture (CP). It contains same fields as the PIM except the following that are not present: paymentBrand. In case of referenced payments like capture, refund or recurring transactions you should expect the message at {endpoint-url}/v1/payments/{UUID-of-referenced-transaction}. Where the referenced transaction is a previous PA, DB, RF or other pay-in or pay-out payment orders.

PIM for Recurring Payments

Repeated payments are supported only for credit cards. Recurring or Repeated payments are merchant initiated payment orders that reference an initial shopper-present payment. This brings the advantage that merchants can perform the recurring payments with simplified workflows where the CVV or 3DS authentication is not required. The mechanism that ACI implemented to handle recurring payments requires tokenization of the credit card details. Therefore the initial payment request from the merchant will instruct ACI platform to save CC details for subsequent payments -except the CVV, which cannot be stored. For Repeated Payments the CVV won’t be provided.


Initial Payment – Shopper is present:

Integrator receives all PIM parameters and credit card details – also CVV - and additionally: 
recurringPayment=INITIAL

Repeated Payment – Merchant Initiated Transaction – Shopper NOT present:

Integrator receives all PIM parameters and credit card details, except CVV. In addition:

recurrintPayment=REPEATED
customParameters[initial.uuid] //where the value of this parameter is the uuid of the initial payment order.
For more information see diagram Recurring Payments S2S

Integrator responses

PIM Response for synchronous workflow

Credit Cards is one of the most representative cases of synchronous workflows CC-Synchronous workflow. It is important to include the CC-details field in the response:

	"card": {
		"bin": "420000",
		"last4Digits": "0000",
		"holder": "Antonio Lopez",
		"expiryMonth": "12",
		"expiryYear": "2023"
	}

The following JSON object is a complete response for credit cards:


{
	"id": "8ac7a49f6c09c68c016c0aa239be491e",
	"paymentBrand": "VISA",
	"descriptor": "2147.9402.1474",
	"paymentType": "DB",
	"amount": "99.78",
	"currency": "EUR",
	"card": {
		"card.bin": "420000",
		"card.last4Digits": "0000",
		"card.holder": "Roberto Méndez",
		"card.expiryMonth": "12",
		"card.expiryYear": "2023"
	},
	"result": {
		"code": "000.000.000",
	},
	"resultDetails": {
		"AcquirerResponse": "33",
		"ExtendedDescription": "someExtendedDescription"
	}
	"timestamp": "yyyy-mm-dd hh:mm:ss ZZZZ",
}

For the following key-value pairs you should just mirror the same values assigned in the PIM:

  • id maps to customParameters[UUID] received in PIM.
  • paymentBrand, descriptor, paymentType, amount, currency map to the fields with same name in PIM.

result.code can be any of the return codes from section Result codes for rejections by the external bank or similar payment system that start with ‘800’.

resultDetails should contain all meaningful information coming from the system of the APM/acquirer that may be relevant for merchants, i.e. details that can help merchants understanding the reason of a rejection. You can add customized fields, resultDetails.{name-of-new-field}

resultDetails.AcquirerResponse is the response code, if any, sent by the system of the APM/acquirer.

resultDetails.ExtendedDescription is the description corresponding to the AcquirerResponse. It is very important to include this description specially in the rejection cases, recommended for all cases.

Prepayment (PP) / Invoice payment (IV) / Online Transfer (OT) methods are also examples of synchronous workflows. Here is one sample response for a prepayment:

{
	"id": "8ac7a49f6c09c68c016c0a6f43d64575",
	"paymentBrand": "NAME_OF_BRAND",
	"descriptor": "5463.8835.5741",
	"paymentType": "PA",
	"amount": "40.00",
	"currency": "EUR",
	"result": {
		"code": "000.000.000",
	},
	"resultDetails": {
		"AcquirerResponse": "0033",
		"ExtendedDescription": "someExtendedDescription"
	}
	"timestamp": "yyyy-mm-dd hh:mm:ss ZZZZ",
}

Note: Unlike Credit Card Payments, PP/IV workflows use the notificationUrl in the PIM to generate a Receipt. See PP-IV-OT Sync workflow.

PIM Response for asynchronous workflow

The most remarkable difference with respect to synchronous workflows is that the integrator must respond with a redirection URL to the PIM message. See one example of asynchronous workflow: VA Server to Server.

{
    "id": "8ac7a4a26e339cd6969e0372fb1a0ede",
    "paymentType": "PA",
    "paymentBrand": "PAY_FAWRY",
    "amount": "1.00",
    "currency": "EUR",
    "descriptor": "4768.3788.2506 Fawry_channel ",
    "merchantTransactionId": "MA1231231",
    "result": {
        "code": "000.200.000",
    },
    "resultDetails": {
        "ExtendedDescription": "someExtendedDescription",
        "AcquirerResponse": "33",
    },
    "redirect": {
        "url": "https://somepaymentsystem.com",
        "method": "GET",	// Can also be a POST
        "parameters": [
			{
				"name":"param1",
		        		"value":"someValue"
			}
		]
    },
    "timestamp": "yyyy-mm-dd hh:mm:ss ZZZZ",
}

PIM Response for backoffice payments

Remember that for backoffice payments the request to the integrator is sent to the endpoint:

{endpoint-name}/v1/payments/99933a49f6c09c68c016c0a6f434aaaa

Notice that the UUID of the URL is not the same you should send in the response. In the response you should send the ID of the refund itself back, that you get in the PIM, whereas the last component of the URL is the UUID of the referenced payment to be refunded/reverted/etc, usually a PA, DB

Sample response for a Refund: 
{
	"id": "8ac7a49f6c09c68c016c0a6f43d64575",
	"descriptor": "3196.1806.7009",
	"paymentType": "RF",
	"amount": "40.00",
	"currency": "EUR",
	"result": {
		"code": "000.000.000",
	},
	"resultDetails": {
		"AcquirerResponse": "33",
		"ExtendedDescription": "someExtendedDescription"
	}
}
Sample response for a Reversal: 
{
	"id": "8ac7a49f6c03456c016c0a6f43d64575",
	"descriptor": "3196.2206.7009",
	"paymentType": "RF",
	"amount": "10.00",
	"currency": "EUR",
	"result": {
		"code": "000.000.000",
	},
	"resultDetails": {
		"AcquirerResponse": "33",
		"ExtendedDescription": "someExtendedDescription"
	}
}

PIM Response for recurring payments

No special response required. Same as described for synchronous payments – credit cards.

Asynchronous workflow

Status Notification and redirection call

There are two types of calls that may be used after the shopper is redirected to an external payment system: Status update notification and Redirection call. You can invoke both methods through the URLs that are contained in the Payment Initiation Message: notificationUrl and shopperResultUrl.

Status update Notification

Using the URL from the parameter notificationUrl you can update the state of the transaction in ACI payment system, for example, from pending to non-instant, or any other intermediate state; or from pending to successful, rejected or any other final state.

The format of notificationUrl is as follows:

https://{test.}ppipe.net/connectors/asyncresponse;jsessionid={sessionId}?asyncsource=UCONNECT&type=notification&method={method}&data={data}&uuid={id}&additional={additonal-data}&ndcid={id}

where,

  • asyncsource, always with value UCONNECT indicates the name of the connector;
  • method, can have values in the set {VA, CC, IV, OT, CT}, which represents the payment method, e.g. Virtual Account
  • type, always with value “notification” for update-status calls.
  • jsessionid, data and additional are ACI-specific variables for internal operations.

How to update the status

Append to the end of notificationUrl the parameter status with value, any code from ACI result codes and add the signature as described in this step Calculate notification signature. After that, send a POST or GET request using the resulting URL.

For example:

https://{test.}ppipe.net/connectors/asyncresponse;jsessionid={sessionId}?asyncsource=UCONNECT&type=notification&method={method}&data={data}&uuid={id}&additional={additonal-data}&ndcid={id}&status=000.000.000&signature={calculated-signature}

Choose the code with the closest description for the reason you are accepting or rejecting a payment operation. If you don’t find a good match you can always use a generic code, for example 800.100.152 ‘transaction declined by authorization system’, and add a customized description as explained below.

Add a customized description

It is highly recommended to provide a customized description with the status update notification because ACI system will include the description in the response to the merchant. All you must do is adding the parameter resultDetails.ExtendedDescription to the notificationUrl

https://{test.}ppipe.net/connectors/asyncresponse;jsessionid={sessionId}?asyncsource=UCONNECT&type=notification&method={method}&data={data}&uuid={id}&additional={additonal-data}&ndcid={id}&status=000.000.000&resultDetails.ExtendedDescription=some%20problem%20occured

Calculate notification signature

The signature is calculated with a HMACSHA256 hash function that receives two arguments: one is the secret configured in the merchant account in BIP, and the other is a string composed out of the notificationUrl arguments as follows:

  • Extract all pairs name-value from notificationUrl: asyncsource, type, method, data, uuid, additional, ndcid, status and optionally resultDetails.ExtendedDescription, resultDetails.{any-field};
  • Create a string by chaining all the pairs in alphabetical order like this: name1=value1|name2=value2|...nameN=valueN. Note you must use the separator “|”.
  • 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}

    • Example of signature calculation:

    Given the following notificationUrl:

    https://test.ppipe.net/connectors/asyncresponse;jsessionid=4B7962B9F42C60E8D665A13BF5715B3C.uat01-vm-con04?asyncsource=UCONNECT&type=notification&method=CDK_VA&data=99tm8ZwvLZpFbwcbq%2FMVUA____mxGf%2FOlqJkaGzeWCIuRVrJHGcb5zdV4uvqMIBez6J2e2Ak6Wau1EbGQGPejMjagY%2FH9EbQDph&uuid=8ac7a4a06ded6694016df9aa6e9c631e&additional=K24qHu%2FRR7wQRZS7PnQvxo____G%2FpEkT4yKG7fmKlQ4TxYYQ6y2RNJ3rqmSdfKyUB7y&ndcid=8ac7a4c968cca59c0169068054c0651f_2b5b6d18465141688580a5602f38f7e9

    The parameters are listed below:

    asyncsource=UCONNECT
type=notification
method=CDK_VA
data=99tm8ZwvLZpFbwcbq%2FMVUA____mxGf%2FOlqJkaGzeWCIuRVrJHGcb5zdV4uvqMIBez6J2e2Ak6Wau1EbGQGPejMjagY%2FH9EbQDph
uuid=8ac7a4a06ded6694016df9aa6e9c631e
additional=K24qHu%2FRR7wQRZS7PnQvxo____G%2FpEkT4yKG7fmKlQ4TxYYQ6y2RNJ3rqmSdfKyUB7y
ndcid=8ac7a4c968cca59c0169068054c0651f_2b5b6d18465141688580a5602f38f7e9

    After decoding the HTML entities, in this case there is only %2F, which decoded is /, you would obtain:

    asyncsource=UCONNECT
type=notification
method=CDK_VA
data=99tm8ZwvLZpFbwcbq/MVUA____mxGf/OlqJkaGzeWCIuRVrJHGcb5zdV4uvqMIBez6J2e2Ak6Wau1EbGQGPejMjagY/H9EbQDph
uuid=8ac7a4a06ded6694016df9aa6e9c631e
additional=K24qHu/RR7wQRZS7PnQvxo____G/pEkT4yKG7fmKlQ4TxYYQ6y2RNJ3rqmSdfKyUB7y
ndcid=8ac7a4c968cca59c0169068054c0651f_2b5b6d18465141688580a5602f38f7e9

    Now you have to include the status and, optionally, the resultDetails.ExtendedDescription to the list of parameters. additional=K24qHu/RR7wQRZS7PnQvxo____G/pEkT4yKG7fmKlQ4TxYYQ6y2RNJ3rqmSdfKyUB7y asyncsource=UCONNECT data=99tm8ZwvLZpFbwcbq/MVUA____mxGf/OlqJkaGzeWCIuRVrJHGcb5zdV4uvqMIBez6J2e2Ak6Wau1EbGQGPejMjagY/H9EbQDph method=CDK_VA ndcid=8ac7a4c968cca59c0169068054c0651f_2b5b6d18465141688580a5602f38f7e9 resultDetails.ExtendedDescription=accepted by acquirer status=000.000.000 type=notification uuid=8ac7a4a06ded6694016df9aa6e9c631e

    You are ready to execute the method HMAC method with digest algorithm SHA256 passing also the secret (in this case secret was 123).

    This is:

    HMAC256(‘123’, additional=K24qHu/RR7wQRZS7PnQvxo____G/pEkT4yKG7fmKlQ4TxYYQ6y2RNJ3rqmSdfKyUB7y|asyncsource=UCONNECT|data=99tm8ZwvLZpFbwcbq/MVUA____mxGf/OlqJkaGzeWCIuRVrJHGcb5zdV4uvqMIBez6J2e2Ak6Wau1EbGQGPejMjagY/H9EbQDph|method=CDK_VA|ndcid=8ac7a4c968cca59c0169068054c0651f_2b5b6d18465141688580a5602f38f7e9|resultDetails.ExtendedDescription=accepted by acquirer|status=000.000.000|type=notification|uuid=8ac7a4a06ded6694016df9aa6e9c631e)

    The resulting signature is 9f853b24d1f6af27a7136d865bfe3ef32559d335be723913c8aee0996c890083

    In order to send the notification execute a GET with all parameters and the signature appended to them. Remember that the HTML entities should be encoded again:

    https://test.ppipe.net/connectors/asyncresponse;jsessionid=4B7962B9F42C60E8D665A13BF5715B3C.uat01-vm-con04?asyncsource=UCONNECT&type=notification&method=CDK_VA&data=99tm8ZwvLZpFbwcbq%2FMVUA____mxGf%2FOlqJkaGzeWCIuRVrJHGcb5zdV4uvqMIBez6J2e2Ak6Wau1EbGQGPejMjagY%2FH9EbQDph&uuid=8ac7a4a06ded6694016df9aa6e9c631e&additional=K24qHu%2FRR7wQRZS7PnQvxo____G%2FpEkT4yKG7fmKlQ4TxYYQ6y2RNJ3rqmSdfKyUB7y&ndcid=8ac7a4c968cca59c0169068054c0651f_2b5b6d18465141688580a5602f38f7e9&status=000.000.000&resultDetails.ExtendedDescription=accepted%20by%20acquirer&signature=9f853b24d1f6af27a7136d865bfe3ef32559d335be723913c8aee0996c890083


    Redirection call

    Once the status of the transaction has been updated through the notification URL – this is a precondition -, you MUST redirect the shopper back from the external payment system to ACI so that ACI redirects the shopper to the merchant’s result page, which is only known to ACI.

    Redirect the shopper using the parameter shopperResultUrl contained in the PIM. You don’t need to manipulate the URL; just use the URL as you received it.

    https://{test.}ppipe.net/connectors/asyncresponse;jsessionid={sessionId}?asyncsource=UCONNECT&type=redirect&method={method}&data={data}&uuid={id}&additional={additonal-data}&ndcid={id}

    where,

    • asyncsource, always with value UCONNECT indicates the name of the connector;
    • method, can have values in the set {VA, CC, IV, OT, CT}, which represent the payment method, e.g. Virtual Account
    • type, always with value redirect for redirection calls.
    • jsessionid, data and additional are ACI-specific variables for internal operations

    ApplePay and GooglePay

    In case of ApplePay or GooglePay transactions, the request will contain an additional field, based on which one can determine if the transaction is made via ApplePay or a GooglePay.

    The field name is walletProvider, and can have 2 values: APPLE_PAY or GOOGLE_PAY