ConnectIn Integration

This guide explains how to implement the endpoints required to receive and process payment requests from the ACI Payment Orchestration Platform through ConnectIn.

Before starting the integration, make sure that your ConnectIn configuration is complete and your test environment is available.

Integration overview

ConnectIn uses the ACI payment request structure to exchange payment information between the ACI Payment Orchestration Platform and your payment service.

For each payment operation, ACI sends a Payment Initiation Message (PIM) to your configured endpoint. Your integration processes the request using the external payment system and returns the corresponding ConnectIn response.

Depending on the payment method and transaction flow, processing can be synchronous or asynchronous.

  • Synchronous: Your endpoint processes the payment and returns the payment result directly in the response.
  • Asynchronous: Your endpoint returns the information required to continue the payment journey. Your integration subsequently updates the payment status using the notification URL supplied by ACI.

See the ConnectIn Workflow guide for detailed transaction flows.

↑ Back to top

Endpoints

Your ConnectIn implementation must expose endpoints that ACI can use to send payment requests.

Payment initiation endpoint

https://{your-host}/v1/payments

This endpoint is used for payment initiation requests such as:

  • Preauthorization (PA)
  • Debit (DB)
  • Credit (CD)

Referenced payment endpoint

https://{your-host}/v1/payments/{id}

This endpoint is used for operations that reference an existing payment, such as:

  • Capture (CP)
  • Refund (RF)
  • Reversal (RV)
↑ Back to top

Payment Initiation Message

The Payment Initiation Message contains the payment information sent by ACI to your ConnectIn endpoint. The same base request structure is used for synchronous and asynchronous payment workflows.

The Origin column indicates where each value originates:

  • ACI Payments API: The value originates from the payment request submitted to ACI.
  • Merchant Account: The value is configured for the merchant account.
  • System: The value is automatically added by the ACI Payment Orchestration Platform.
ACI API parameter Origin Description
amount ACI Payments API Amount of the payment.
authentication.entityId Merchant Account Entity identifier available to the ConnectIn integration for authentication or credential mapping.
authentication.password Merchant Account Password available for authentication with the external payment service.
authentication.userId Merchant Account User identifier available for authentication with the external payment service.
authorization Merchant Account Authorization information used to authenticate requests sent to your endpoint.
currency ACI Payments API Currency of the payment.
customParameters[CUSTOM_DATA] Merchant Account Additional data configured for the ConnectIn integration.
customParameters[ShortId] System ACI internal payment identifier.
customParameters[UUID] System ACI payment identifier used to correlate the ConnectIn request and response.
descriptor System or Merchant Request Descriptor associated with the payment.
merchant.mcc Merchant Request or Merchant Account Merchant Category Code.
merchantTransactionId Merchant Request Merchant-provided transaction identifier.
notificationUrl System URL used by the ConnectIn integration to update the payment status.
paymentBrand Merchant Request Payment brand used for the transaction, for example VISA, MASTER or PAYPAL.
paymentType Merchant Request Payment operation, for example PA, DB or CD.
shopperResultUrl System URL used to return the shopper to ACI after completing an external payment journey.
transactionCategory ACI Payments API or Merchant Account Transaction category, for example Ecommerce, Mail Order or MOTO.

Note: notificationUrl and shopperResultUrl are primarily used for asynchronous processing. These parameters may also be included in requests for synchronous payment methods.

Authentication parameters

The authentication parameters can supply the credentials required by the external payment service.

When bearer authorization is used, the authorization parameter is populated. Bearer authorization should not be used together with authentication.userId and authentication.password.

Card payment parameters

For card payments, the Payment Initiation Message can additionally contain the following parameters:

Parameter Origin Description
card.cvv Merchant Request Card verification value, when applicable.
card.expiryMonth Merchant Request Card expiry month.
card.expiryYear Merchant Request Card expiry year.
card.holder Merchant Request Cardholder name.
card.number Merchant Request Card number.
PCI compliance: If your ConnectIn integration receives cardholder data, your environment must meet the applicable PCI DSS requirements.

Test mode

Requests originating from the ACI test environment can contain the following parameter:

Parameter Possible values Description
testMode INTERNAL or EXTERNAL Indicates the test mode applicable to the payment request.
↑ Back to top

Referenced payments

Referenced operations use an existing payment as the basis for a new payment operation.

Examples include:

  • Capture (CP)
  • Refund (RF)
  • Reversal (RV)

ACI sends referenced payment requests to: 

https://{your-host}/v1/payments/{UUID-of-referenced-transaction}

The identifier in the endpoint URL represents the payment being referenced. The current operation has a separate identifier in: 

customParameters[UUID]

Important: The identifier in the endpoint URL and the identifier of the new payment operation represent different transactions. Return the identifier of the current operation in the response.

The Payment Initiation Message for a referenced operation contains the applicable common payment parameters. The paymentBrand parameter might not be included for referenced operations.

↑ Back to top

Standing Instructions

Standing Instruction payments use stored payment credentials. The Payment Initiation Message for these transactions contains the common parameters from the ACI Payments API request, together with the Standing Instruction parameters described below.

Standing Instruction parameters describe how payment credentials are stored and used across initial and subsequent transactions.

Parameter Description
standingInstruction.mode Identifies how the stored payment credentials are used for the transaction.
standingInstruction.source Identifies the party or event that initiated the transaction.
standingInstruction.type Identifies the type of Standing Instruction associated with the transaction.

Initial payment

An initial transaction establishes the payment credentials that can be used for subsequent payments. 

standingInstruction.mode={applicable-mode}
standingInstruction.source={applicable-source}
standingInstruction.type={applicable-type}

Use the Standing Instruction parameters together with the other information in the Payment Initiation Message when processing the transaction.

Subsequent payment

A subsequent payment uses credentials established by an earlier transaction. The Standing Instruction parameters identify the context in which the stored credentials are being used. 

standingInstruction.mode={applicable-mode}
standingInstruction.source={applicable-source}
standingInstruction.type={applicable-type}

Where the transaction references an initial payment, the request can also contain: 

customParameters[initial.uuid]={UUID-of-initial-payment}

Important: Process the Standing Instruction parameters exactly as provided in the ConnectIn request. These parameters define the stored-credential context and the relationship between the initial and subsequent transactions.

For card payments, the CVV is not provided for subsequent merchant-initiated transactions.

Refer to the API Reference for the supported Standing Instruction values and parameter specifications.

See the Standing Instruction payment workflow for the corresponding transaction flow.

↑ Back to top

Responding to payment requests

Your ConnectIn endpoint must return a response that identifies the payment operation and its processing result.

The following response values should correspond to the values received in the Payment Initiation Message:

  • id corresponds to customParameters[UUID].
  • paymentBrand
  • descriptor
  • paymentType
  • amount
  • currency

Synchronous response

For synchronous workflows, return the payment result directly to ACI. 

{
    "id": "8ac7a49f6c09c68c016c0aa239be491e",
    "paymentBrand": "VISA",
    "descriptor": "2147.9402.1474",
    "paymentType": "DB",
    "amount": "99.78",
    "currency": "EUR",
    "card": {
        "bin": "420000",
        "last4Digits": "0000",
        "holder": "Example Cardholder",
        "expiryMonth": "12",
        "expiryYear": "2028"
    },
    "result": {
        "code": "000.000.000"
    },
    "resultDetails": {
        "AcquirerResponse": "33",
        "ExtendedDescription": "Example response description"
    },
    "timestamp": "yyyy-mm-dd hh:mm:ss ZZZZ"
}

Use resultDetails to return meaningful information received from the external payment system.

  • resultDetails.AcquirerResponse can contain the response code returned by the external payment system.
  • resultDetails.ExtendedDescription can contain additional information describing the result.
  • Additional information can be returned using resultDetails.{field-name}.

Asynchronous response

For payment methods that require the consumer to continue the payment journey on an external payment system, include the applicable redirection information in the response. 

{
    "id": "8ac7a4a26e339cd6969e0372fb1a0ede",
    "paymentType": "PA",
    "paymentBrand": "PAYMENT_BRAND",
    "amount": "1.00",
    "currency": "EUR",
    "descriptor": "Example descriptor",
    "merchantTransactionId": "MA1231231",
    "result": {
        "code": "000.200.000"
    },
    "resultDetails": {
        "AcquirerResponse": "33",
        "ExtendedDescription": "Example response description"
    },
    "redirect": {
        "url": "https://example-payment-system.com",
        "method": "GET",
        "parameters": [
            {
                "name": "param1",
                "value": "exampleValue"
            }
        ]
    },
    "timestamp": "yyyy-mm-dd hh:mm:ss ZZZZ"
}

The redirect object contains the information required to continue the consumer journey with the external payment system.

Referenced payment response

For referenced operations, return the identifier of the new payment operation, not the identifier of the transaction referenced in the endpoint URL.

Example refund response:

{
    "id": "8ac7a49f6c09c68c016c0a6f43d64575",
    "descriptor": "3196.1806.7009",
    "paymentType": "RF",
    "amount": "40.00",
    "currency": "EUR",
    "result": {
        "code": "000.000.000"
    },
    "resultDetails": {
        "AcquirerResponse": "33",
        "ExtendedDescription": "Example response description"
    }
}
↑ Back to top

Asynchronous processing

Some payment methods require processing to continue after the initial Payment Initiation Message response.

ConnectIn provides two URLs in the Payment Initiation Message:

  • notificationUrl: Used to update the payment status.
  • shopperResultUrl: Used to return the consumer to ACI after the external payment journey is complete.

Status notification

Use the notificationUrl supplied in the Payment Initiation Message to update the payment when its status changes. 

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

The URL contains the following parameters:

  • asyncsource: Identifies the connector. The value is UCONNECT.
  • type: Identifies the request type. The value is notification for a status update.
  • method: Identifies the payment method.
  • uuid: Identifies the payment.
  • jsessionid, data, additional and ndcid: ACI-generated values required to process the notification.

Pending payment statuses

The following result codes indicate that payment processing is still pending:

Result code Status Description
000.200.000 Pending for consumer The payment is pending an action or completion of the payment journey by the consumer.
000.200.001 Pending for acquirer The payment has been submitted and is pending a response or final status from the acquirer or external payment system.

When the payment reaches a final status, use the notificationUrl provided in the Payment Initiation Message to send the final result code.

Update the payment status

Append the applicable ACI result code to the notificationUrl using the status parameter. 

{notificationUrl}&status={result-code}&signature={calculated-signature}

Refer to the Result Codes reference for the available ACI result codes.

Add result details

Where available, provide additional information received from the external payment system using: 

resultDetails.ExtendedDescription={description}

Additional result information can be supplied using: 

resultDetails.{field-name}={value}

Calculate the notification signature

Status notifications must include a signature. The signature is calculated using HMAC-SHA256 with the secret configured for the integration.

  1. Extract all name-value pairs from the notificationUrl.
  2. URL-decode parameter values before creating the signature.
  3. Add the status parameter.
  4. Add any resultDetails parameters included in the notification.
  5. Sort all parameters alphabetically by parameter name.
  6. Join the name-value pairs using the pipe character (|).
  7. Calculate the HMAC-SHA256 value using the configured secret.
  8. Append the calculated value as the signature parameter.
Important: The parameters used to calculate the signature must exactly match the parameters included in the notification. URL-decode values before calculating the signature and URL-encode the applicable values again when constructing the final request URL.

Complete signature example

Assume the following notificationUrl was received in the Payment Initiation Message: 

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

Step 1: Extract the parameters

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

Step 2: URL-decode the parameter values

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

Step 3: Add the status and result details

status=000.000.000
resultDetails.ExtendedDescription=accepted by acquirer

Step 4: Sort the parameters alphabetically

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

Step 5: Build the signing string

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

Step 6: Calculate the HMAC-SHA256 signature

Using 123 as the example secret, calculate the HMAC-SHA256 value using the signing string. 

HMAC-SHA256(
    secret = "123",
    message = "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

Step 7: Construct the final notification URL

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

Send the resulting notification request to ACI using the supported HTTP method.

Shopper redirection

After the consumer completes the payment journey with the external payment system, return the consumer using the shopperResultUrl supplied in the Payment Initiation Message.

The transaction status must be updated before the consumer is returned to ACI.

Important: Use the shopperResultUrl exactly as provided by ACI. Do not construct, replace or modify the URL.

ACI uses the request to continue the payment journey and redirect the consumer to the merchant's result page.

↑ Back to top

Digital wallets

For Apple Pay and Google Pay transactions, the request contains the walletProvider parameter.

walletProvider Wallet
APPLE_PAY Apple Pay
GOOGLE_PAY Google Pay
↑ Back to top

Next steps

After implementing your ConnectIn endpoints, review the ConnectIn Workflow guide to understand how synchronous, asynchronous, referenced and Standing Instruction payment flows are processed.

↑ Back to top