- Get Started
- Guides
- Integrations
- References
- API Reference
- Basic Payment
- Forex
- Authentication
- Card Account
- Apple Pay
- Virtual Account
- Bank Account
- Token Account
- Customer
- Billing Address
- Merchant Billing Address
- Shipping Address
- Merchant Shipping Address
- Corporate
- Sender
- Recipient
- Merchant
- Marketplace & Cart
- Airline
- Lodging
- Passenger
- Tokenization
- Recurring Migration
- 3D Secure
- Custom Parameters
- Async Payments
- Webhook notifications
- Job
- Risk
- Point of Sale
- Response Parameters
- Card On File
- Chargeback
- Result Codes
- Payment Methods
- Transaction Flows
- Regression Testing
- Data Retention Policy
- Release Notes
- API Reference
- Support
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
Refund (RF), Reversal (RV) and Capture (CP)
.{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
Initial Payment – Shopper is present:
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 tocustomParameters[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
{ "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
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 optionallyresultDetails.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