ConnectUp

About the ConnectUP API

ConnectUP is a RESTful web API that exposes various payments-related services.

Message flow

ConnectUP accepts HTTP POST messages with a URL-encoded body and returns an HTTP response with a JSON body.

Supported services

ConnectUP supports the following major services:

  • Payment - The Payments service performs payments and runs other payment-related operations.

  • Tokenization - The Tokenization service creates a token based on card data and retrieves card data based on a token.

  • Point-to-Point Encryption (P2PE) - The P2PE service provides Point-to-Point Encryption related operations like Remote Key Distribution.

  • Validated P2PE (VP2PE) - The Validated P2PE service submits terminal data for reporting and record keeping purposes as part of a validated P2PE solution.

  • APM Token Decrypt - The APM (Alternative Payment Method) Decrypt service is used to decrypt payment tokens generated by alternative payment methods such as Apple Pay and Google Pay. The decrypted content of the token is returned in the response. This can be useful for systems where validation of the contents of the token is required before the financial leg of the transaction is attempted.

About this publication

This document details how to use ConnectUP relating to services and parameters. The descriptions are separated by use-case so that granular explanation is possible.

Each parameter is described as Mandatory, Conditional, or Optional for each explained use-case. The distinction between these is as follows:

Mandatory
The parameter must be present in the request message for the given use-case to occur. The request can be rejected without this parameter.

Conditional
The parameter is required in combination with other parameters for the given use-case to be possible, but there can be more than one set of parameters which can enable this use-case. The request can be rejected if one of the combinations of parameters is not present.

Optional
The presence or absence of this parameter will not affect the use-case. The request will never be rejected if this parameter is not present.

1. Authentication

1.1. Authorization Bearer Token

To align with authentication changes to the Open Payment Platform API specification, support for the new Authorization: Bearer <access-token> header, and related entityId field, have been added to all services to authenticate requests.

Currently, the value of the access-token is the result of concatenating the existing authentication.userId (Deprecated) and authentication.password (Deprecated) fields (as provided during user creation), and Base64-encoding the result.

Note
The now deprecated authentication.* fields can still be used in requests but cannot be combined with the Authorization header and related entityId field. If these fields are combined in any way, authentication will fail.

Existing clients that wish to use the new authentication fields can:

  1. Construct the token themselves as described above.

  2. Request new user credentials from ACI, which will include the access-token.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Required

AN32
[a-f0-9]{32}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUxNDJmOWV..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  [...]

1.2. Legacy Authentication

The legacy authentication fields remain a supported method for authenticating ConnectUP requests. It is recommended that you use the Authorization Bearer Token to authenticate requests. The fields listed here are deprecated and will be removed in a future release.

Parameter name Description Required Regex

authentication.userId (Deprecated)

The user ID for the entity.

Required

AN32
[a-f0-9]{32}

authentication.entityId (Deprecated)

The entity ID for the entity.

Required

AN32
[a-f0-9]{32}

authentication.password (Deprecated)

The password for the entity.

Required

AN32
[a-f0-9]{32}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -d "authentication.userId=602563b7f8efa7cee142f9eea51e7850"
  -d "authentication.password=28044F4F0973DBF6364BFFE114D3C118"
  -d "authentication.entityId=b964f0e254a717c1524355a6149b575d"
  [...]

2. Payment Service

The Payments service performs payments and runs other payment-related operations.

2.1. Base Payment Operations

2.1.1. Pre-Authorization Request

This payment operation places an authorization hold on funds for a future payment transaction. The funds reserved can then either be captured, or reversed at a later stage by referencing this authorization payment request.

A Pre-Authorization request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment resource.

The minimum requirements for sending a PA message are listed below. See the Specialized Payment Use Cases section for use cases that required additional fields.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

paymentType

The payment type indicator.

Required

PA

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2018"
  -d "amount=21.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

2.1.2. Debit Request

This payment operation debits the account of the customer and credits the merchant account.

A Debit request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment resource.

The minimum requirements for sending a DB message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

paymentType

The payment type indicator.

Required

DB

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Debit Response

The following fields reflect the possible response values for a Debit Request response message:

Parameter name Description Required Regex

balances.availableBalance

Indicates the available balance for the account.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

balances.approvedAmount

Indicates the approved amount for the account.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

See the standard response fields for an extended listing of the possible response parameters ConnectUP can return for this request type.

Example
Debit Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2018"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Debit Request Response
{
    "amount": "200.00",
    "currency": "USD",
    "balances": {
        "availableBalance": "100.00"
        "approvedAmount": "200.00"
    },
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded"
        "authorizationId": "071797"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    }
}

2.1.3. Credit Request

This payment operation credits the account of the customer and debits the merchant account.

A Credit request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment resource.

The minimum requirements for sending a CD message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

paymentType

The payment type indicator.

Required

CD

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee parameter is provided, this must be included in this amount.

If the applePay.paymentToken parameter is provided, this field (amount) is used for comparison with the value stored in the token, or it is used to override the token amount. This behavior is determined by upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=CD"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=21.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

2.1.4. Capture Notification

This payment operation can be used to capture a Pre-authorization (PA) amount or capture a stand-alone request.

A Capture notification for this, or a previous pre-authorization request, is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment resource.

The minimum requirements for sending a CP message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

paymentType

The payment type indicator.

Required

CP

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

referencedPaymentId

The identifier of the transaction being completed (the Id from the original PA response).
This field is conditional for completions. If present, then a linked-capture is performed, if absent then a stand-alone capture is performed.

Optional

ANS32
[\s\S]{1,32}

statusCode

Indicates the status code of a CP transaction.

Optional

SUCCESSFUL|INVALID_AMOUNT

authorizationId

A code assigned by the authorizing institution indicating approval.

Optional

ANS6
[\s\S]{6}

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=CP"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2018"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "authorizationId=114547"

2.1.5. Reversal

This payment operation reverses an already processed Pre-Authorization Request, Debit Request, or Credit Request.

A Reversal for a previous pre-authorization request, debit request, credit request, or capture notification is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment resource.

A Reversal for a previous pre-authorization request, debit request, credit request, or capture notification is placed onto the Store and Forward Queue (SAFQ) and is generally always automatically approved.

The minimum requirements for sending an RV message are listed here.

See Reversals using referencedMerchantTransactionId for cases where a referencedPaymentId value is not available.

See Result Code Special Notes for cases where an explicit Reversal must be performed.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

amount

Indicates the corrected amount (including all tax, duty, shipping, and discount amounts) for the original transaction in major denomination. This is not an amount that must be subtracted from the original transaction, but rather the corrected (replacement) amount for the original transaction. This field is only required for partial reversals.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

paymentType

The payment type indicator.

Required

RV

referencedPaymentId

The "Id" response of the original PA, DB, CD, or CP transaction that is to be reversed.

Conditional

ANS32
[\s\S]{1,32}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"`
  -d "paymentType=RV"
  -d "amount=15.00"
  -d "pos.terminalId=38956111"
  -d "referencedPaymentId=1b8cd7b6c81c9883e8926f04985fa7b5"

2.1.6. Reversal Request

This payment operation reverses an already processed Pre-Authorization Request, Debit Request, or Credit Request.

A Reversal Request for a previous pre-authorization request, debit request, credit request, or capture notification is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment resource.

A Reversal Request for a previous pre-authorization request, debit request, credit request, or capture notification and can be declined by the host.

The minimum requirements for sending an RR message are listed here.

See Reversals using referencedMerchantTransactionId for cases where a referencedPaymentId value is not available.

See Result Code Special Notes for cases where an explicit Reversal Request must be performed.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

amount

Indicates the corrected amount (including all tax, duty, shipping, and discount amounts) for the original transaction in major denomination. This is not an amount that must be subtracted from the original transaction, but rather the corrected (replacement) amount for the original transaction. This field is only required for partial reversals.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

paymentType

The payment type indicator.

Required

RR

referencedPaymentId

The "Id" response of the original PA, DB, CD, or CP transaction that is to be reversed.

Conditional

ANS32
[\s\S]{1,32}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"`
  -d "paymentType=RR"
  -d "amount=15.00"
  -d "pos.terminalId=38956111"
  -d "referencedPaymentId=1b8cd7b6c81c9883e8926f04985fa7b5"

2.1.7. Integrated Circuit Chip (ICC) Data Result Request

An ICC Data Result Request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment/iccresult resource.

The ICC Data Result Request is used to send ICC transaction results to the card issuer as part of the payment transaction flow (if required).

When a payment is performed with an ICC card, the card calculates two separate cryptograms. The first calculation occurs prior to initiating the payment request and is sent together with the payment request. The second calculation occurs after the issuer (or other authorizer) approved the payment request. The second cryptogram (a TC or Transaction Certificate) needs to be sent to the issuer.

When using a dual message pre-authorization/capture transaction flow (paymentType PA and CP), the TC can be sent with the capture message. If using a single message debit/credit transaction flow (paymentType DB or CD), this service must be used to send the TC.

Additionally, the issuer can send scripts to the card to run in a payment response. The issuer script results must be sent back to the issuer in a follow-up request.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

pos.iccDataRequest

Integrated Circuit Card data generated by an EMV transaction. This field is required if pos.entryMode is ICC or NFC_ICC. This field contains BER-TLV data, as defined by the EMV specifications, and is hex-encoded.

Required

ANS2048
[a-fA-F0-9]{1,20000}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

referencedPaymentId

The identifier of the transaction for which the ICC results are being sent. This field is the id value from the original PA, DB, CD, or CP response.

Required

ANS32
[\s\S]{1,32}

ICC Data Result Response

The following field reflects the possible response for an ICC Data Result Request message:

Parameter name Description Required Regex

result.iccDataResponse

This field contains BER-TLV data from the issuer, as defined by the EMV specifications, and is hex-encoded.

Optional

AN2048
[a-fA-F0-9]{1-20000}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment/iccresult -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "card.track2Data=5301250070000191"
  -d "pos.storeId=posStoreID10000"
  -d "pos.terminalId=term_1aB"
  -d "pos.iccDataRequest=9F3303E0F0C89F03060202..."
  -d "referencedPaymentId=1b9e311efa074b9e92048c44de58b1e7"
ICC Data Result Response
{
    "amount": "0.00",
    "currency": "USD",
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded"
        "authorizationId": "071797"
        "iccDataResponse": "6F1A840E3150411025F2D02..."
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    }
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.1.8. Balance Inquiry Request

This payment operation can be used to retrieve the remaining balance for an associated account.

A Balance Inquiry request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/balanceinquiry resource.

The minimum requirements for sending a Balance Inquiry message are listed here:

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Balance Inquiry Response

The following field reflects the possible response values for a Balance Inquiry response message:

Parameter name Description Required Regex

balances.availableBalance

Indicates the available balance for the account.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

See the standard response fields for an extended listing of the possible response parameters ConnectUP can return for this request type.

Example
Balance Inquiry Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/balanceinquiry -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "pos.terminalId=12195611"
  -d "pos.storeId=78123753"
  -d "pos.entryMode=UNKNOWN"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Balance Inquiry Response
{
    "amount": "0.00",
    "currency": "USD",
    "balances": {
        "availableBalance": "100.00"
    },
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded"
        "authorizationId": "071797"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    }
}

2.1.9. Stored-Value Activate Request

This service is used to activate a stored-value card whilst simultaneously loading the card with a specified balance.

A Stored-Value Activate request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/activate resource.

The minimum requirements for sending a Stored-Value Activate message are listed here.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

amount

Indicates the total amount to be loaded onto the card when first activated.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Example
Stored-Value Activate Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/activate -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=55.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=UNKNOWN"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Stored-Value Activate Response
{
    "amount": "55.00",
    "currency": "USD",
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded"
        "authorizationId": "432457"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    }
}

2.1.10. Stored-Value Load Request

This service is used to load additional funds to an already activated stored-value card balance.

A Stored-Value Load request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/load resource.

The minimum requirements for sending a Stored-Value Load message are listed here.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

amount

Indicates the total amount to be loaded onto the associated card.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Example
Stored-Value Load Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/load -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=55.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=UNKNOWN"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Stored-Value Load Response
{
    "amount": "55.00",
    "currency": "USD",
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded"
        "authorizationId": "078897"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    }
}

2.1.11. Stored-Value Deactivate Request

This service is used to deactivate a stored-value card and simultaneously retrieve the available balance remaining on the card.

A Stored-Value Deactivate request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/deactivate resource.

The minimum requirements for sending a Stored-Value Deactivate message are listed here.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

amount

Indicates the remaining balance on the card. Therefore, a common flow would be to do a balance inquiry request before sending a deactivation request.

Note: For deactivation requests, this field is optional for some stored-value acquirers.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Conditionally Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Example
Stored-Value Deactivate Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/deactivate -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=55.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=UNKNOWN"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Stored-Value Deactivate Response
{
    "amount": "55.00",
    "currency": "USD",
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    }
}

2.1.12. Debit Request

This payment operation Debit adjustment is issued towards correction of an transaction. This adjustment debits the customer’s account.

A Debit adjustment is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment resource.

The minimum requirements for sending a DA message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

paymentType

The payment type indicator.

Required

DA

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DA"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2018"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

2.1.13. Deposit

This payment operation is used to credit the customer’s account.

A Deposit is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment resource.

The minimum requirements for sending a DP message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

paymentType

The payment type indicator.

Required

DP

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee parameter is provided, this must be included in this amount.

If the applePay.paymentToken parameter is provided, this field (amount) is used for comparison with the value stored in the token, or it is used to override the token amount. This behavior is determined by upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=DP"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=21.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

2.1.14. Refund

This payment operation is used to credit the account of the end customer for an already processed Debit Request, or Credit Request.

A Refund is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment resource.

The minimum requirements for sending a RF message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

paymentType

The payment type indicator.

Required

RF

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee parameter is provided, this must be included in this amount.

If the applePay.paymentToken parameter is provided, this field (amount) is used for comparison with the value stored in the token, or it is used to override the token amount. This behavior is determined by upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

card.number

The Primary Account Number (PAN) of the physical card.

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

N4
(20|21)([0-9]{2})

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

merchantTransactionId

The merchant-provided reference number. It must be unique for the merchant’s transactions.

Required

ANS255
[\s\S]{8,255}

ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=RF"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=21.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

2.2. Base Payment Operation Responses

2.2.1. Standard Response

The fields listed in the table here reflect the possible response values for the following request messages:

Parameter name Description Required Regex

id

The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client.

Always

AN32
[a-zA-Z0-9]{1,32}

timestamp

The timestamp generated by the response in UTC.

Always

date
yyyy-MM-dd hh:mm:ss

result.code

The unique code that indicates the result status of the request.
See Result Codes for more details.

Always

AN11
[0-9\.]{2,11}

result.description

A textual description explaining the result.code meaning. If a field validation exception occurs, this field will also indicate the name of the field or fields that failed validation.

Always

AN255
[\s\S]{0,255}

result.avsResponse

Contains the AVS response returned by the acquirer.
See OPP Response Parameters for more details about avsResponse.

Conditional

A1
[A-Z]{1}

result.cvvResponse

Contains the CVV response returned by the acquirer.
See OPP Response Parameters for more details about cvvResponse.

Conditional

A1
[A-Z]{1}

resultDetails.*

A container for name-value pairs used for enriching the response with bank-specific response details.

Conditional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

resultDetails.AcquirerResponse

The raw host network response code.

Conditional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

resultDetails.AcquirerAvsResponse

The raw host network AVS response code.

Conditional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

resultDetails.commercialCardIndicator

Indicates whether the card type is commercial (Level 2 eligible). ​
Possible values:
Y - Yes
N - No
X - Not applicable / unknown

Conditional

Y|N|X

resultDetails.FleetDataRsp

A container for fleet data response details.

Conditional

name: ANS255
[\s\S]{0,255}

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Conditional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

tokenId

A token representing sensitive cardholder data.

Optional

AN255
[a-zA-Z0-9]{255}

currency

The currency code of the payment request’s amount (ISO 4217).

The default currency used is "USD".

For a Reversal, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction.

Optional

A3
[A-Z]{3}

result.authorizationId

The code assigned by the authorizing institution indicating approval.

Optional

AN6
[a-zA-Z0-9]{1,6}

fleet

Contains information regarding fleet data which can be used to send data to the pump from the acquirer.

Optional

ANS255
[\s\S]{255}

Example
{
	"id" : "e8f59d02a466f35a7ece785d3e137e50",
	"tokenId" : "JYO7rdR5UjK61111",
	"amount" : "92.00",
	"currency" : "USD",
	"result": {
		"code" : "000.000.000",
		"description" : "Transaction succeeded",
		"authorizationId" : "783276"
	},
	"customParameters":{
		"CUSTOM_KEY1":"CUSTOM_VALUE1",
		"CUSTOM_KEY2":"CUSTOM_VALUE2"
	},
	"resultDetails" : {
		"bankField1": "1234"
	},
	"timestamp" : "2019-09-06 12:22:44"
}
Note
Optional fields will only be returned when the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

2.3. Specialized Payment Use Cases

2.3.1. 3-D Secure

3-D Secure (3DS) is compatible with the following message types:

ConnectUP supports sending transactions that have already been authenticated by a third-party 3-D Secure version 2 provider. In this scenario, ConnectUP will send the authentication data obtained from the third-party provider to complete the 3-D Secure authorization flow.

To authorize a 3-D Secure transaction, add the parameters listed here to your payment message.

Note
Only 3-D Secure version 2 is currently supported.
Parameter name Description Required Regex

threeDSecure.eci

The Electronic Commerce Indicator flag that is placed on the transaction to indicate the results of the attempt to authenticate the Cardholder.

Required

N2
0[5|7]{1}

threeDSecure.dsTransactionId

The universally unique transaction identifier assigned by the directory server to identify a single transaction.

Required

ANS36
[\s\S]{1,36}

threeDSecure.version

The 3-D Secure version used.

Required

ANS5
[2].?[0-9]?.?[0-9]?{1,5}

threeDSecure.xid

The unique transaction identifier (XID) from your 3-D Secure provider.

Conditional

AN64
[0-9a-zA-Z/+=]{64}

threeDSecure.verificationId

The Cardholder Authentication Verification Value (CAVV). This value is generated by your 3-D Secure provider after the cardholder has been authenticated during a card-not-present transaction.

For MasterCard 3-D Secured transactions, this field contains the MasterCard UCAF (Universal Cardholder Authentication Field) value.

Conditional

AN28
[0-9a-zA-Z/+=]{1,28}

threeDSecure.authenticationMethod

This value indicates the 3-D Secure Authentication Method

Possible values are:
0 - All authentication methods
1 - Challenge flow using static passcode
2 - Challenge flow using OTP via SMS method
3 - Challenge flow using OTP via key fob or card reader method
4 - Challenge flow using OTP via App method
5 - Challenge flow using OTP via any other method
6 - Challenge flow using KBA method
7 - Challenge flow using OOB with biometric method
8 - Challenge flow using OOB with App login method
9 - Challenge flow using OOB with any other method
A - Challenge flow using any other authentication method
D - Frictionless flow, RBA review
E - Attempts server responding
F - Frictionless flow, RBA

Optional

ANS1
[0-9A-Z]{1}

threeDSecure.exemptionFlag

Flags the transaction as an exemption during authorization.

Possible values are:
01 - Low value transaction exemption
02 - Low risk transaction exemption
03 - Trusted Beneficiary exemption
04 - Secure Corporate Payment transaction exemption

Optional

N2
0[1-4]{1}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
   -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
   -d "entityId=b964f0e254a717c1524355a6149b575d"
   -d "paymentType=DB"
   -d "card.track2Data=5416389123456786D22021010000081315000"
   -d "amount=75.00"
   -d "pos.terminalId=12195611"
   -d "pos.storeId=78123753"
   -d "pos.entryMode=MAGSTRIPE"
   -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
   -d "threeDSecure.xid=VGhpcyBpcyBhIHNhbXBsZSB4aWQ="
   -d "threeDSecure.verificationId=c2FtZSBhcyBvdGhlciB2YWx1ZXM="
   -d "threeDSecure.eci=05"
   -d "threeDSecure.dsTransactionId=c5b808e7-1de1-4069-a17b-f70d3b3b1645"
   -d "threeDSecure.version=2.0.0"
   -d "threeDSecure.authenticationMethod=0"
Response

If an authorizer wants to send acknowledgement of authenticating the provided 3-D Secure parameters, this value must be present in the threeDSecure.result field in the response.

Parameter name Description Required Regex

threeDSecure.result

Contains the 3-D Secure result (for example, CAVV or AAV).

Optional

UNABLE_TO_VALIDATE_RESULTS_INVALID|​
VALIDATION_FAILED_AUTHENTICATION|​
VALIDATION_PASSED_AUTHENTICATION|​
VALIDATION_PASSED_ATTEMPTED_AUTH|​
VALIDATION_FAILED_ATTEMPTED_AUTH|​
NOT_VALIDATED_ISSUER_NOT_PARTICIPATING|​
VALIDATION_FAILED_ATTEMPTED_AT_ACS|​
VALIDATION_PASSED_ATTEMPTED_AT_ACS|​
VALIDATION_FAILED_ATTEMPTED_AT_STAND_IN|​
VALIDATION_PASSED_ATTEMPTED_AT_STAND_IN|​
VALIDATION_PASSED_NO_LIABILITY_SHIFT|​
NOT_VALIDATED_ATTEMPTED_AUTH|​
NOT_VALIDATED_AUTHENTICATION

Sample Response Containing the 3-D Secure Result
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "50.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "threeDSecure":{
        "result" : "VALIDATION_PASSED_AUTHENTICATION"
    },
    "customParameters":{
        "MY_KEY1":"MY_VALUE1",
        "MY_KEY2":"MY_VALUE2"
    },
    "timestamp" : "2019-09-06 12:00:00"
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.2. Account Type

Account Type is compatible with the following message types:

The card.accountType field can be used to indicate the account type of the card used in a transaction. When this field is not specified, the DEFAULT value is inferred.

Parameter name Description Required Regex

card.accountType

A value indicating the type of account affected by the transaction. If no value is provided, the DEFAULT account type is used.

Required

DEFAULT|​
CHECK|​
CREDIT|​
SAVINGS|​
STORED_VALUE|​
STORED_VALUE_SINGLE_DEPOSIT_SINGLE_USE|​
STORED_VALUE_SINGLE_DEPOSIT_MULTI_USE|​
STORED_VALUE_MULTI_DEPOSIT_MULTI_USE

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "card.accountType=CREDIT"
	-d "amount=75.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.3. Additional POS Data

Additional POS Data is compatible with the following message types:

If more information about the POS device is needed in a payment request, the following fields can be used.

Parameter name Description Required Regex

pos.terminalType

The type of terminal used to initiate the transaction. If no value is provided, the value is determined from the Transaction Category, if possible.

Possible values are:
ADMIN - Administrative terminal
ECOM_SECURE_NO_CRDHLDR_AUTH - E-commerce (secure channel, no cardholder authentication)
MOBILE_POS - Mobile Point of Sale
POS - Point of Sale
SMART_PHONE - Smart Phone
VRU - Voice Recognition Unit

Optional

ADMIN|​
ECOM_SECURE_NO_CRDHLDR_AUTH|​
MOBILE_POS|​
POS|​
SMART_PHONE|​
VRU

pos.operatorId

Identifies the operator that initiated the transaction.

Optional

ANS35
[\s\S]{1,35}

pos.posId

Identifies the device that initiated the transaction.

Optional

ANS35
[\s\S]{1,35}

pos.transactionSequenceNumber

Identifies the transaction on the device that initiated the transaction.

Optional

ANS35
[\s\S]{1,35}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
 	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
 	-d "amount=75.00"
 	-d "pos.terminalId=12195611"
 	-d "pos.storeId=78123753"
 	-d "pos.entryMode=MAGSTRIPE"
 	-d "pos.terminalType=ADMIN"
 	-d "pos.operatorId=123321"
 	-d "pos.posId=98778912"
 	-d "pos.transactionSequenceNumber=66611234"
 	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.4. Alternative Card Data

ConnectUP supports receiving card data in various formats. Any message within the Payment Service or Token Service can accept card information in the following ways. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data.

Card data input formats

Manual Card Data

ConnectUP supports transactions using the card details available on the physical card. For this, the fields listed here are available in the request:

Manual Card Data is compatible with the following message types:

Parameter name Description Required Regex

card.number

The Primary Account Number (PAN) of the physical card.

Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Required

N4
(20|21)([0-9]{2})

card.cvv

The card security code or CVV.

Optional

N4
[0-9]{3,4}

card.sequenceNumber

A number distinguishing between separate cards with the same primary account number or extended primary account number.

Optional

N3
[0-9]{3}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

MANUAL

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=PA"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2018"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Magstripe Card Data

Magstripe Card Data is compatible with the following message types:

ConnectUP supports transactions using magnetic stripe data. For this, the fields listed here are required in the request.

Parameter name Description Required Regex

card.track2Data

The information encoded on Track 2 of the magnetic stripe, as defined in ISO 7813.

Required

ANS37
[\s\S]{1,37}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

MAGSTRIPE

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=PA"
	-d "card.track2Data=5416389123456786D22021010000081315000"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Integrated Circuit Chip (ICC) Data

Integrated Circuit Chip (ICC) Data is compatible with the following message types:

ConnectUP supports transactions containing Integrated Circuit Chip (ICC) data. For this, the fields listed here are available in the request:

Parameter name Description Required Regex

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

​NFC_ICC|​ICC

pos.iccDataRequest

Integrated Circuit Card data generated by an EMV transaction. This field is required if pos.entryMode is ICC or NFC_ICC. This field contains BER-TLV data, as defined by the EMV specifications, and is hex-encoded.

Required

ANS2048
[a-fA-F0-9]{1,20000}

pos.cardDataInputCapability

Indicates the supported methods for retrieving the card details at the point-of-service. When this field is not supplied, it is assumed that it is the same as the value for pos.entryMode.

Optional

​MAGSTRIPE_MANUAL_ICC|​MAGSTRIPE_ICC|​ICC|​NFC_ICC |​MAGSTRIPE_MANUAL_ICC_NFC

pos.cardDataOutputCapability

Indicates the point-of-service’s ability to update card data. If not sent in a request, it is assumed that the point-of-service has no capability to update card data.

Optional

ICC

pos.cardholderAuthenticationCapability

Indicates the mode of authentication of the cardholder that can be performed at the point-of-service. If not sent in a request, it is assumed that the point-of-service has no capability to authenticate the cardholder.

Optional

NONE|​
PIN|​
ELECTRONIC_SIGNATURE|​
BIOMETRIC|​
BIOGRAPHIC|​
INOPERATIVE|​
OTHER

pos.cardholderAuthenticationMethod

Indicates the mode of authentication of the cardholder that was performed at the point-of-service. If not sent in a request, it is assumed that the point-of-service did not perform any authentication.

Optional

NFC_ICC|ICC

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=PA"
	-d "card.track2Data=2222222222333333333=2020201"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=ICC"
	-d "pos.iccDataRequest=9F3303E0F0C89F03060000000000009F020..."

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

Token Card Data

Token Card Data is compatible with the following message types:

ConnectUP supports making payment requests using a token instead of card or Track 2 data. To perform a payment using a token, supply a token value in the tokenId field and set the pos.entryMode to UNKNOWN.

Parameter name Description Required Regex

tokenId

A token representing sensitive cardholder data.

Required

AN255
[a-zA-Z0-9]{255}

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

UNKNOWN

Note
Depending on the information stored when the token was created, additional card information such as the expiry month and year might be required alongside the token when performing payment requests.
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=DB"
  -d "amount=46.00"
  -d "tokenId=Tj9e10lduQiVm7"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78119753"
  -d "pos.entryMode=UNKNOWN"
  -d "merchantTransactionId=5a6149b575d60db9aa7ef667e8f09898"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

Apple Pay Data

Apple Pay Data is compatible with the following message types:

Apple Pay provides a virtual wallet that allows for a seamless payment experience using an Apple device’s built-in authentication features such as Touch ID or Face ID to authenticate a payment. To perform an Apple Pay payment, add the following parameters to your payment message.

ConnectUP supports receiving an encrypted payment token bundle. Alternatively, ConnectUP can process an Apple Pay request where the merchant has pre-decrypted the payment token bundle themselves.

Note
Apple Pay is not supported in China.
Payments using an Encrypted Payment Token
Parameter name Description Required Regex

paymentBrand

The payment brand used to identify alternative payment method transactions.

Required

APPLEPAY

currency

The currency code of the payment request’s amount (ISO 4217).

The default currency used is "USD".

For a Reversal, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction.

If you provide this field, amount must also be present. By providing this field, it will override the currency present in the encrypted applePay.paymentToken field. This behavior is determined by upstream configuration.

Conditional

A3
[A-Z]{3}

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

If you provide this field, currency must also be present. By providing this field, it will override the amount present in the encrypted applePay.paymentToken field. This behavior is determined by upstream configuration.

Conditional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

applePay.paymentToken

The encrypted payment token provided by Apple.

Required

ANS8192
[\s\S]{1,8192}

Payments using Pre-Decrypted Payment Token Fields
Parameter name Description Required Regex

paymentBrand

The payment brand used to identify alternative payment method transactions.

Required

APPLEPAY

card.number

The Device Primary Account Number (DPAN).

Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Required

N4
(20|21)([0-9]{2})

currency

The currency code of the payment request’s amount (ISO 4217).

The default currency used is "USD".

For a Reversal, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction.

Required

A3
[A-Z]{3}

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

threeDSecure.verificationId

If the Apple Pay token contains an online payment cryptogram, its value must be provided in this field.

Conditional

AN56
[0-9a-zA-Z/+=]{1,56}

threeDSecure.eci

If the Apple Pay token contains an Electronic Commerce Indicator (ECI), its value must be provided in this field.

Conditional

{3DS_eci_Apple_regex}

Example
Payment Using an Encrypted Payment Token
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "paymentBrand=APPLEPAY"
	-d "applePay.paymentToken= {
		\"version\": \"EC_v1\",
		\"data\": \"pthEHTJcEDAQ4MLi[...]Zw9edDA==\",
		\"signature\": \"MIAGCSqGSIb[...]fZWNjL==\",
		\"header\": {
			\"ephemeralPublicKey\": \"MFkwEwYHKoZIzj0[...]Fku50liog==\",
			\"publicKeyHash\": \"sGhAH2fo79Jdp[...]NbSc7wfmGNgDwcXpc=\",
			\"transactionId\": \"c5b71840e7fa9374d31d5b560dace7550f47\"
		}
	}
Payment Using Pre-Decrypted Payment Token Fields
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "card.number=503615955234"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2025"
	-d "amount=125.00"
	-d "currency=USD"
	-d "paymentBrand=APPLEPAY"
	-d "threeDSecure.verificationId=c2FtZSBhcyBvdGhlciB2YWx1ZXM="
	-d "threeDSecure.eci=05"
Response
Response for a Payment Made with an Encrypted Payment Token
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "50.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "card":{
        "number" : "6504840209544524",
        "expiryMonth" : "01",
        "expiryYear" : "2021",
        "numberType" : "DPAN",
    },
    "timestamp" : "2019-09-06 12:00:00"
}
Response for a Payment Made with a Pre-Decrypted Payment Token
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "125.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "timestamp" : "2019-09-06 12:00:00"
}
Google Pay

Google Pay is compatible with the following message types:

Google Pay provides a virtual wallet that allows for in-app purchases using the payment methods saved to a customer’s Google account. To perform a Google Pay payment, add the parameters listed here to your payment message.

ConnectUP supports receiving an encrypted payment token bundle. Alternatively, ConnectUP can process an Google Pay request where the merchant has pre-decrypted the payment token bundle themselves.

Payments using an Encrypted Payment Token
Parameter name Description Required Regex

paymentBrand

The payment brand used to identify alternative payment method transactions.

Required

GOOGLEPAY

currency

The currency code of the payment request’s amount (ISO 4217).

The default currency used is "USD".

For a Reversal, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction.

Required

A3
[A-Z]{3}

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

googlePay.paymentToken

The encrypted payment token provided by Google.

Required

ANS8192
[\s\S]{1,8192}

Payments using Pre-Decrypted Payment Token Fields
Parameter name Description Required Regex

paymentBrand

The payment brand used to identify alternative payment method transactions.

Required

GOOGLEPAY

currency

The currency code of the payment request’s amount (ISO 4217).

The default currency used is "USD".

For a Reversal, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction.

Required

A3
[A-Z]{3}

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

card.number

The Primary Account Number (PAN) of the physical card, or the Device Primary Account Number (DPAN).

Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Required

N4
(20|21)([0-9]{2})

threeDSecure.xid

The unique transaction identifier (XID) from your 3-D Secure provider. This must be provided, if available.

Conditional

AN64
[0-9a-zA-Z/+=]{64}

threeDSecure.verificationId

The Cardholder Authentication Verification Value (CAVV). This value is generated by your 3-D Secure provider after the cardholder has been authenticated during a card-not-present transaction.

For MasterCard 3-D Secured transactions, this field contains the MasterCard UCAF (Universal Cardholder Authentication Field) value. This must be provided, if available.

Conditional

AN28
[0-9a-zA-Z/+=]{1,28}

threeDSecure.eci

The Electronic Commerce Indicator flag that is placed on the transaction to indicate the results of the attempt to authenticate the Cardholder. This must be provided, if available.

Conditional

N2
0[5|7]{1}

Example
Payment Using Encrypted Payment Token
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
   -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
   -d "entityId=b964f0e254a717c1524355a6149b575d"
   -d "paymentType=DB"
   -d "amount=21.00"
   -d "currency=USD"
   -d "pos.terminalId=34056111"
   -d "pos.storeId=78919753"
   -d "pos.entryMode=MANUAL"
   -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
   -d "paymentBrand=GOOGLEPAY"
   -d "googlePay.paymentToken={
      \"signature\":\"MEYCIQCwmJ[...]RWgG8c\",
      \"intermediateSigningKey\":{
         \"signedKey\":\"{
            \"keyValue\":\"MFkwEwYHKo[...]LdekAQ\\u003d\\u003d\",
            \"keyExpiration\":\"1585761306143\"
         }\",
         \"signatures\":[\"MEYCIQDb+L[...]JHwEhF\"]
      },
      \"protocolVersion\":\"ECv2\",
      \"signedMessage\":\"{
            \"encryptedMessage\":\"mJVt1VLA[...]prXv3g\\u003d\",
            \"ephemeralPublicKey\":\"BK9KRS[...]Wyy9LU\\u003d\",
            \"tag\":\"KVHidXy9ur[...]g15Sjw\\u003d\"
      }\"
   }"
Payment Using Pre-Decrypted Token Fields
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
   -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
   -d "entityId=b964f0e254a717c1524355a6149b575d"
   -d "paymentType=DB"
   -d "card.number=4444444444444448"
   -d "card.expiryMonth=05"
   -d "card.expiryYear=2050"
   -d "amount=21.00"
   -d "currency=USD"
   -d "pos.terminalId=34056111"
   -d "pos.storeId=78919753"
   -d "pos.entryMode=MANUAL"
   -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
   -d "paymentBrand=GOOGLEPAY"
   -d "threeDSecure.xid=VGhpcyBpcyBhIHNhbXBsZSB4aWQ="
   -d "threeDSecure.verificationId=c2FtZSBhcyBvdGhlciB2YWx1ZXM="
   -d "threeDSecure.eci=05"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

Point-to-Point-Encryption (P2PE) Card Data
Warning
Currently unsupported feature subject to change

Point-to-Point-Encryption (P2PE) Card Data is compatible with the following message types:

Point-to-point encryption (P2PE) is an encryption standard that secures cardholder data at the terminal or point-of-sale (POS) level. This standard requires that cardholder information, including PAN and track data, is encrypted at the point of interaction, and is therefore safeguarded in transit or at rest.

Parameter name Description Required Regex

pos.p2peEncrypted.type

Indicates the scheme of point-to-point encryption (P2PE) used to encrypt the account data at the PIN entry device (PED). ​

Possible values are:
- ACI - The ACI P2PE scheme (not supported) ​
- INGENICO_ONGUARD - The Ingenico On-Guard P2PE scheme
- PAX - The PAX P2PE scheme ​
- VERIFONE_VSD - The Verifone P2PE scheme ​
- PRESTO - The Presto P2PE scheme

Required

ACI|​
INGENICO_ONGUARD|​
PAX|​
VERIFONE_VSD|​
PRESTO

pos.p2peEncrypted.ksn

The key serial number used to determine decryption key for Encrypted P2PE account data. This field is encoded as a hex representation of the binary P2PE key serial number value.

Required

AN2048
[a-fA-F0-9]{1,2048}

pos.p2peEncrypted.sensitiveData

The sensitive key block contains data items allowing the host to identify or derive the decryption keys, as well as any other data items required to decrypt the sensitive data. This field is encoded as a hex representation of the binary P2PE sensitive data block value.

Required

AN65535
[a-fA-F0-9]{1,65535}

pos.p2peEncrypted.persistableData

The persistable encrypted point-to-point encryption (P2PE) account data (PAN/EXPIRY). When P2PE functionality is used, and the card details were encrypted, this field is required instead of the card.number, card.track2data, card.expiryMonth, card.expiryYear, and card.cvv fields. If card details are received in addition to pos.p2peEncrypted.persistableData, it is assumed that the particular card used is subject to whitelisting and that pos.p2peEncrypted.whitelistFileName is present. This field is encoded as a hex representation of the binary P2PE sensitive data block value.

Conditionally Required

AN65535
[a-fA-F0-9]{1,65535}

pos.p2peEncrypted.volatileData

The volatile (must not be stored) encrypted point-to-point encryption (P2PE) account data (PAN/TRACK2/EXPIRY). When P2PE functionality is used and the card details were encrypted, this field is required instead of the card.number, card.track2data, card.expiryMonth, card.expiryYear, and card.cvv fields.

If card details are received in addition to pos.p2peEncrypted.persitableData, it is assumed that the particular card used is subject to whitelisting and that pos.p2peEncrypted.whitelistFileName is present. This field is encoded as a hex representation of the binary P2PE sensitive data block value.

Conditionally Required

AN65535
[a-fA-F0-9]{1,65535}

pos.p2peEncrypted.whitelistFileName

The symbolic name given to the white-listed BIN file. When P2PE is in use, a file consisting of white-listed BINs might be supplied to the PED. Such a file must first be digitally signed by the DataSigner tool in the decrypting entity. This parameter is used by the decrypting entity to check that the PED is using the current version of the whitelist.

Conditionally Required

ANS100
[\s\S]{1,100}

pos.p2peEncrypted.tlvMapping[name]

These fields describe the encoding used for the TLV fields in the Persisted Encrypted Sensitive Data Block (pos.p2peEncrypted.persistableData), as well as the Volatile Encrypted Sensitive Data Block (pos.p2peEncrypted.volatileData).

Conditionally Required

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

pos.p2peEncrypted.maxReliableBinLength

This field is set to the number of starting digits of the PAN that are visible based on the obfuscation scheme.

Conditionally Required

N99999
[0-9]{1,99999}

pos.p2peEncrypted.whitelistHash

A SHA-1 or SHA-256 hash value calculated over the content of the whitelist file loaded on the terminal.

Conditionally Required

AN255
[a-fA-F0-9]{1,255}

pos.p2peEncrypted.whitelistSignature

A base 64 encoded PKCS#7 signature of the whitelist file object using SHA-1 or SHA-256 for the signature algorithm, consisting of the following, Whitelist file data content, SHA-1 or SHA-256 signature of the data content, using the host private key and Verification certificate chain, including the host public key certificate.

Conditionally Required

AN99999
[a-fA-F0-9]{1,99999}

Example
Request containing sensitiveData, persistableData, and volatileData fields
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=DB"
  -d "amount=100.00"
  -d "pos.storeId=78919753"
  -d "pos.terminalId=34056111"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "pos.p2peEncrypted.type=INGENICO_ONGUARD"
  -d "pos.p2peEncrypted.ksn=FFFF98765400020002280500060000"
  -d "pos.p2peEncrypted.sensitiveData=2805000600003031313030364e47..."
  -d "pos.p2peEncrypted.persistableData=41303854133380862400453030..."
  -d "pos.p2peEncrypted.volatileData=3040431234f354130385410..."
  -d "pos.p2peEncrypted.tlvMapping[DFDB02]=B"
  -d "pos.p2peEncrypted.tlvMapping[57]=B"
  -d "pos.p2peEncrypted.tlvMapping[5A]=B"
  -d "pos.p2peEncrypted.tlvMapping[9F6B]=B"
  -d "pos.p2peEncrypted. whitelistHash=58372014DHAE0431234f354130385410..."
  -d "pos.p2peEncrypted. whitelistSignature=AEHUFAB571823502AHEANFAJ19400823423480..."
  -d "pos.p2peEncrypted. maxReliableBinLength=124734918324789109842361048234861764329..."
Response
{
    "id" : "e8f59d02a466f35a7ece785343e137e50",
    "amount" : "100.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "timestamp" : "2019-09-06 12:00:00"
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

Payment Identifier

Payment Identifier is compatible with the following message types:

The card.paymentIdentifier field can be used to represent any payment identifier, for example:

  • card numbers longer than 19 numeric digits

  • gift cards

  • voucher numbers

  • loyalty card numbers

  • fleet card numbers

Parameter name Description Required Regex

card.paymentIdentifier

The payment identifier used when card.number or card.track2Data are not appropriate, either due to limiting field formats/lengths, or not being an account based transaction.

Required

N28
[a-zA-Z0-9]{0,28}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "card.paymentIdentifier=0123456789abcdefghiJKLMNOPQR"
	-d "amount=75.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.5. Card Verification Value / Card ID (CVV/CID)

Card Verification Value/Card ID (CVV/CID) is compatible with the following message types:

A CVV/CID value is the three- or four-digit number on a physical credit or debit card. To verify that a customer is in possession of their card, this CVV or CID value can be added to a payment request.

Parameter name Description Required Regex

card.cvv

The card security code or CVV.

Required

N4
[0-9]{3,4}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2018"
	-d "card.cvv=999"
	-d "amount=21.00"
	-d "pos.storeId=78919753"
	-d "pos.terminalId=34056111"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Response

The following parameter will be present in the response if a Card Verification Result is received from the upstream entity.

Parameter name Description Regex

result.cvvResponse

Contains the CVV response returned by the acquirer.
See OPP Response Parameters for more details about cvvResponse.

A1
[A-Z]{1}

{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "21.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276",
        "cvvResponse": "M"
    },
    "timestamp" : "2019-09-06 12:22:44"
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.6. CVV2 Availability

CVV2 Availability is compatible with the following message types:

If a customer cannot provide a CVV/CVV2 value of the card used in the transaction, the pos.cvv2Availability value can be added to the payment request to justify the absence of the card.cvv value.

Parameter name Description Required Regex

pos.cvv2Availability

The CVV2 availability indicator applies to card-not-present transactions. It is used to explain why a CVV2 value is not provided by the merchant, usually in situations where the card does have a CVV2 value.

Required

NO_CVV2_ON_CARD|​
NOT_PROVIDED|​
ILLEGIBLE

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2018"
	-d "amount=21.00"
	-d "pos.storeId=78919753"
	-d "pos.terminalId=34056111"
	-d "pos.entryMode=MANUAL"
	-d "pos.cvv2Availability=ILLEGIBLE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.7. Encrypted Pin

Encrypted Pin is compatible with the following message types:

To indicate that a PIN was entered at the point-of-service, but not verified offline, add the following parameters to your payment message.

Parameter name Description Required Regex

pos.encryptedPin.data

Encrypted online PIN data. This field is required when a PIN was entered at the point-of-service but was not verified offline. This field is encoded as a hex representation of the binary encrypted PIN value.

Required

AN2048
[a-fA-F0-9]{1,2048}

pos.encryptedPin.ksn

Key serial number used to determine PIN key for online PIN. This field is required when a PIN was entered at the point-of-service, but it was not verified offline, and the DUKPT PIN encryption scheme is used. This field is encoded as a hex representation of the binary key serial number value.

Required

AN2048
[a-fA-F0-9]{1,2048}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=DB"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=21.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=456c0znbjv885ml6q15hakjdhj2276oh"
  -d "pos.encryptedPin.data=A3929E6A25E8E32C"
  -d "pos.encryptedPin.ksn=FFFF12345612342000..."

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.8. Alternative Currency

Alternative Currency is compatible with the following message types:

Every user is configured with a default currency (usually USD). Should a transaction be required in a different currency to the default, the currency must be specified in the request. All financially linked transactions must use the same currency.

Parameter name Description Required Regex

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

currency

The currency code of the payment request’s amount (ISO 4217).

The default currency used is "USD".

For a Reversal, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction.

Required

A3
[A-Z]{3}

Note
The amount is always required if currency is specified in the request, and the amount needs to use the correct decimal formatting for the specified currency. ConnectUP will validate the currency and decimals specified on all requests.
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
 	-d "paymentType=DB"
 	-d "card.track2Data=5416389123456786D22021010000081315000"
 	-d "amount=7500"
 	-d "currency=YEN"
 	-d "pos.terminalId=12195611"
 	-d "pos.storeId=78123753"
 	-d "pos.entryMode=MAGSTRIPE"
 	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.9. Address Verification System

Address Verification System is compatible with the following message types:

To verify that a customer is in possession of their card, add the following parameters to the payment request.

Parameter name Description Required Regex

billing.street1

The door number, floor, building number, building name, and/or street name of the billing address.

Required

ANS50
[\s\S]{1,50}

billing.houseNumber1

Primary house number (door number or building number) of the billing address.

If present, then billing.street1 is assumed to contain only the name of the street.

Required

ANS50
[\s\S]{1,50}

billing.postcode

The postal code or zip code of the billing address.

Required

AN9
[A-Za-z0-9]{1,9}

billing.city

The town, district, or city of the billing address.

Optional

ANS20
[\s\S]{1,20}

billing.state

The county, state, or region of the billing address.

Optional

AN20
[a-zA-Z0-9\.]{1,20}

billing.country

The country of the billing address (ISO 3166-1).

Optional

A2
[A-Z]{2}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2020"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "billing.street1=Estuaries Avenue"
	-d "billing.houseNumber1=Century City Building A"
	-d "billing.postcode=7441"
Response
Response containing the result.avsResponse field
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "21.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276",
        "avsResponse": "U"
    },
    "timestamp" : "2019-09-06 12:22:44"
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.10. Billing Contact

Billing Contact is compatible with the following message types:

To specify the contact details of the bill payer or bill payee, use the following fields.

The billing.* fields must be used for the customer who is paying the bill, and the billing.from.* fields must be used for the merchant/retailer which issued the customer with the bill.

Parameter name Description Required Regex

billing.street1

The door number, floor, building number, building name, and/or street name of the billing address.

Optional

ANS50
[\s\S]{1,50}

billing.street2

Additional address data of the company, or authorized person to contact.

Optional

ANS50
[\s\S]{1,50}

billing.houseNumber1

Primary house number (door number or building number) of the billing address.

If present, then billing.street1 is assumed to contain only the name of the street.

Optional

ANS50
[\s\S]{1,50}

billing.postcode

The postal code or zip code of the billing address.

Optional

AN9
[A-Za-z0-9]{1,9}

billing.city

The town, district, or city of the billing address.

Optional

ANS20
[\s\S]{1,20}

billing.state

The county, state, or region of the billing address.

Optional

AN20
[a-zA-Z0-9\.]{1,20}

billing.country

The country of the billing address (ISO 3166-1).

Optional

A2
[A-Z]{2}

billing.from.street1

The door number, floor, building number, building name, and/or street name of the billing address.

Optional

ANS50
[\s\S]{1,50}

billing.from.street2

Additional address data of the company, or authorized person to contact.

Optional

ANS50
[\s\S]{1,50}

billing.from.houseNumber1

Primary house number (door number or building number) of the billing address.

If present, then billing.street1 is assumed to contain only the name of the street.

Optional

ANS50
[\s\S]{1,50}

billing.from.postcode

The postal code or zip code of the billing address.

Optional

AN9
[A-Za-z0-9]{1,9}

billing.from.city

The town, district, or city of the billing address.

Optional

ANS20
[\s\S]{1,20}

billing.from.state

The county, state, or region of the billing address.

Optional

AN20
[a-zA-Z0-9\.]{1,20}

billing.from.country

The country of the billing address (ISO 3166-1).

Optional

A2
[A-Z]{2}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=75.00"
  -d "pos.terminalId=12195611"
  -d "pos.storeId=78123753"
  -d "pos.entryMode=MAGSTRIPE"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
  -d "billing.street1=The Cape Estate"
  -d "billing.street2=456 Main Street"
  -d "billing.houseNumber1=123"
  -d "billing.postcode=7500"
  -d "billing.city=Cape Town"
  -d "billing.state=WC"
  -d "billing.country=ZA"
  -d "billing.from.street1=The Retailer Industrial Park"
  -d "billing.from.street2=12 West Street"
  -d "billing.from.houseNumber1=1"
  -d "billing.from.postcode=7500"
  -d "billing.from.city=Cape Town"
  -d "billing.from.state=WC"
  -d "billing.from.country=ZA"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.11. Bill Payments

Bill Payments is compatible with the following message types:

Bill Payments require that the billPayment field be set. The merchant (payee) data must also be provided. Optionally, the merchant.submerchantId field can be specified if a payment facilitator arrangement is in place between a merchant and a sub-merchant.

Parameter name Description Required Regex

billPayment

When this flag is set to true, it indicates that this is a bill payment transaction.

Required

true

merchant.street

The street address of the merchant.

Required

ANS23
[\s\S]{1,23}

merchant.city

The city of the merchant.

Required

ANS13
[\s\S]{1,13}

merchant.country

The country of the merchant.

Required

AN2
[A-Za-z]{2}

merchant.state

The county, state, or region of the merchant.

Required

AN2
[a-zA-Z0-9]{1,2}

merchant.postcode

The postal code of the merchant.

Required

ANS20
[\s\S]{1,20}

merchant.name

The name of the merchant.
Based on upstream configuration, this could make up the first line on the cardholder statement for this transaction.

Required

ANS35
[\s\S]{1,35}

merchant.phone

The phone number of the merchant.

Required

{merch_phone_regex}

merchant.submerchantId

The sub-merchant ID of the merchant. Required when a payment facilitator arrangement is in place between a merchant and a sub-merchant. It is only applicable to Bill Payment transactions.

Optional

AN15
[a-zA-Z0-9]{1,15}

merchant.receivingInstitutionCode

A code identifying the financial institution that must receive a message. When present, this value is used to calculate the route for a message in upstream systems.

Optional

N11
[0-9]{1,11}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
 	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
 	-d "amount=75.00"
 	-d "pos.terminalId=12195611"
 	-d "pos.storeId=78123753"
 	-d "pos.entryMode=MAGSTRIPE"
 	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
 	-d "merchant.street=Century Avenue"
 	-d "merchant.city=Cape Town"
 	-d "merchant.country=ZA"
 	-d "merchant.state=WC"
 	-d "merchant.name=ACI Canteen"
 	-d "merchant.postcode=7441"
 	-d "merchant.phone=2721522500"
 	-d "merchant.submerchantId=112233445566789"
 	-d "merchant.recievingInstitutionCode=48265712347"
 	-d "billPayment=true"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.12. Cashback

Cashback is compatible with the following message types:

Cashback refers to the money that is paid back to a customer after a transaction has been completed. ConnectUP supports specifying a cashback amount in requests. The cashbackAmount is the cash amount intended to be withdrawn at the point-of-sale (POS).

Note
The cashbackAmount amount must be included in the amount field. ConnectUP does not perform any calculations to ensure this.
Parameter name Description Required Regex

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

cashbackAmount

The amount specified to allow a customer to withdraw cash along with their purchase.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2018"
	-d "amount=121.00"
	-d "pos.storeId=78919753"
	-d "pos.terminalId=34056111"
	-d "pos.entryMode=MANUAL"
	-d "cashbackAmount=100.00"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Response
{
    "id" : "e8f59d02a466f35a7ece785343e137e50",
    "amount" : "121.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "timestamp" : "2019-09-06 12:00:00"
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.13. Convenience Fee

Convenience Fee is compatible with the following message types:

A convenience fee is an amount in addition to the total payment request amount that the customer will incur for the convenience of using a more favorable payment method.

Note
The convenienceFee amount must be included in the amount field. ConnectUP does not perform any calculations to ensure this.
Parameter name Description Required Regex

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).

If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.

If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

convenienceFee

A fee charged by the merchant for providing a more convenient alternative payment channel to the customer. If present, this value must be included in the amount field.
A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator. For example, to specify one dollar and fifty cents, the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

Example
Sample $21.00 transaction with a $0.50 convenience fee
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=PA"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2020"
	-d "amount=21.50"
	-d "convenienceFee=0.50"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.14. Custom Parameters

Custom Parameters is compatible with the following message types:

ConnectUP supports sending non-standard custom parameter fields. These will always be forwarded to the upstream host and echoed back in the response message. These custom parameters are sent as key-value pairs.

Parameter name Description Required Regex

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Required

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "customParameters[MY_KEY1]=MY_VALUE1"
	-d "customParameters[MY_KEY2]=MY_VALUE2"
Response
{
	"id" : "e8f59d02a466f35a7ece785d3e137e50",
	"amount" : "21.00",
	"currency" : "USD",
	"result": {
		"code" : "000.000.000",
		"description" : "Transaction succeeded",
		"authorizationId" : "783276"
	},
	"customParameters":{
		"MY_KEY1":"MY_VALUE1",
		"MY_KEY2":"MY_VALUE2"
	},
	"timestamp" : "2019-09-06 12:22:44"
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.15. Debt Repayment

Debt Repayment is compatible with the following message types:

Some interchange fees attract a lower rate schedule over other card transactions for debt repayment transactions. To indicate a debt repayment transaction, add debtRepayment to the payment request.

Parameter name Description Required Regex

debtRepayment

When this flag is set to true, it indicates that this is a debt repayment transaction.

Required

true

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "debtRepayment=true"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.16. Deferred Payment

Deferred Payment is compatible with the following message types:

To indicate that a transaction is a deferred payment, add the deferredPayment field to the request.

Note
Currently, this feature cannot be combined with CIT/MIT transactions.
Parameter name Description Required Regex

deferredPayment

Setting this flag indicates that the payment was deferred (a future dated payment that is submitted now).

Required

true

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "deferredPayment=true"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.17. Delayed Charges

Delayed Charges is compatible with the following message types:

To indicate that a transaction is a delayed charge payment, add the following parameter to your payment message.

Parameter name Description Required Regex

standingInstruction.industryPractice

This field is used to specify if an industry practice applies to the transaction. This field cannot be specified in addition to standingInstruction.type.

Required

INCREMENTAL_AUTH|RESUBMISSION|​
REAUTHORIZATION|DELAYED_CHARGES|NO_SHOW

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "standingInstruction.industryPractice=DELAYED_CHARGES"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.18. Fallback

Fallback is compatible with the following message types:

The pos.entryMode with a fallback value and pos.fallbackReason field and can be used to indicate whether fallback occurred and the reason that fallback occurred.

Parameter name Description Required Regex

pos.entryMode

The interface that was used by the terminal for the transaction.

Required

CREDENTIAL_ON_FILE|​
ICC|​
ICC_CVV_UNRELIABLE|​
MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​
SAME_AS_ORIGINAL|​
MAGSTRIPE_AS_FALLBACK|​
MAGSTRIPE_TO_MANUAL|​
CONTACTLESS_TO_ICC|​
CONTACTLESS_TO_MAGSTRIPE
UNKNOWN|​

pos.fallbackReason

Indicates the reason for a fallback transaction when pos.entryMode is set to a fallback value.

Optional

CARD_UNREADABLE|​
CHIP_ERROR|​
NO_SUPPORTED_APPLICATION

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "card.paymentIdentifier=0123456789abcdefghiJKLMNOPQR"
	-d "amount=75.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=CONTACTLESS_TO_ICC"
	-d "pos.fallbackReason=NO_SUPPORTED_APPLICATION"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.19. Level 2 and Level 3 Data (L2/L3)

Level 2 and Level 3 Data (L2/L3) is compatible with the following message types:

ConnectUP supports sending invoice data, known as Level 2 (L2) data, and line item detail, known as Level 3 (L3) data. All L2/L3 fields are optional. When sending L3 data, cart.items, taxAmounts and itemizedDiscounts must be specified using an indexed-number [n], starting with 0.

For example:

cart.items[0].description = "First Cart Item"

Tax amounts and itemized discounts are indexed in the same way, but these can be included at the transaction level in L2 data and/or on individual line items in L3 data.

For example:

taxAmounts[0].tax = "100.00"
cart.items[0].taxAmounts[0].tax = "100.00"
itemizedDiscounts[0].amount = "1.50"
cart.items[0].itemizedDiscounts[0].amount = "1.50"
Note
For certain host networks, the values in response fields resultDetails.commercialCardIndicator and resultDetails.level3InterchangeEligible present in the initial PA message response can be used as indicators for when to send L2 or L3 data in the linked CP message.
Parameter name Description Required Regex

customer.orderNumber

The customer’s purchase order number.

Optional

ANS22
[\s\S]{1,22}

customer.customerCode

A code identifying the customer.

Optional

ANS20
[\s\S]{1,20}

merchant.vatNr

The card acceptor’s VAT number, used to identify the card acceptor when reporting taxes.

Optional

ANS20
[\s\S]{1,20}

merchant.refNr

A reference number supplied by the card acceptor to facilitate communication and record keeping.

Optional

ANS20
[\s\S]{1,20}

merchant.taxId

The merchant’s national tax number.

Optional

ANS20
[\s\S]{1,20}

customer.corporationVatNr

The merchant’s VAT number.

Optional

ANS20
[\s\S]{1,20}

customer.vatNr

The customer’s VAT number, used to identify the customer when reporting taxes.

Optional

ANS20
[\s\S]{1,20}

customer.orderDate

The date when the order was placed.

Optional

AN10
(19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1])

customer.orderTime

The time when the order was placed.

Optional

N6
[0-9]{6}

customer.purchaseDate

The date of the purchase/invoice.

Optional

AN10
(19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1])

customer.billingCode

A customer code supplied by the merchant.

Optional

ANS20
[\s\S]{1,20}

customer.taxExempt

Indicates whether the purchaser is tax-exempt.

Optional

true|false

customer.fuelTaxExempt

Indicates whether the fuel line items are tax exempt.

Optional

TRUE|FALSE|Y|N

customer.nonFuelTaxExempt

Indicates whether the non-fuel line items are tax exempt.

Optional

TRUE|FALSE|Y|N

commodityCode

A code assigned by the card acceptor, which best
categorizes the goods or services purchased.

Optional

ANS20
[\s\S]{1,20}

taxCollected

Indicates whether tax was collected.

Optional

TRUE|FALSE|Y|N

card.commercialCardType

This field indicates the type of commercial card used.

Optional

AN2
[a-zA-Z0-9]{2}

discountAmountSign

Discount amount interpretation.

Optional

AN1
[a-zA-Z0-9]{1}

shippingAmountSign

Shipping amount interpretation.

Optional

AN1
[a-zA-Z0-9]{1}

dutyAmountSign

Duty amount interpretation.

Optional

AN1
[a-zA-Z0-9]{1}

customer.provincialSalesTaxRegistrationNr

Provincial Sales Tax Registration Number.

Optional

AN15 [a-zA-Z0-9]{15}

merchant.invoiceDiscountTreatment

Indicates how the merchant is managing discounts.

Optional

AN1 [a-zA-Z0-9]{1}

card.commercialCardType

This field indicates the type of commercial card used.

Optional

AN2
[a-zA-Z0-9]{2}

merchant.taxTreatment

Indicates how the merchant is handling taxes.

Optional

AN1 [a-zA-Z0-9]{1}

merchantOrderNumber

The merchant’s purchase order number.

Optional

ANS25
[\s\S]{1,25}

totalShippingAmount

The freight, shipping, or delivery amount (in the major denomination) to be paid on the total purchase.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

shippingAmountSign

Shipping amount interpretation.

Optional

AN1
[a-zA-Z0-9]{1}

totalDutyAmount

The duty amount (in the major denomination) to be paid on the total purchase.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

dutyAmountSign

Duty amount interpretation.

Optional

AN1
[a-zA-Z0-9]{1}

totalDiscountAmount

The discount amount (in the major denomination) of the total purchase.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

discountAmountSign

Discount amount interpretation.

Optional

AN1
[a-zA-Z0-9]{1}

customer.provincialSalesTaxRegistrationNr

Provincial Sales Tax Registration Number.

Optional

AN15 [a-zA-Z0-9]{15}

taxAmounts[n].taxType

The type of tax.

Optional

CITY_SALES|​
ENERGY|​
FEDERAL_NATIONAL_SALES|​
GOODS_AND_SERVICES|​
LOCAL_SALES|​
MUNICIPAL_SALES|​
OCCUPANCY|​
OTHER|​
PROVINCIAL_SALES|​
ROOM|​
STATE_SALES|​
UNKNOWN|​
VALUE_ADDED

taxAmounts[n].taxDescription

A description of the type of tax, for example, "Freight".

Optional

ANS20
[\s\S]{1,20}

taxAmounts[n].totalTaxAmount

A tax amount (in the minor denomination) applied to this purchase.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

taxAmounts[n].tax

The tax rate to be applied to calculate this tax amount.

Optional

AN6
(100(\.00?)?)|​([0-9]{1,2}(\.[0-9]{1,2})?)

taxAmounts[n].taxId

An ID number used by the card acceptor with the tax authority in connection with this type of tax.

Optional

ANS20
[\s\S]{1,20}

itemizedDiscounts[n].amount

The discount amount (in the minor denomination).

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

itemizedDiscounts[n].rate

The discount rate. Three decimal places are implied.

Optional

ANS5
[\s\S]{1,5}

itemizedDiscounts[n].discountCode

The discount code supplied by the merchant.

Optional

ANS20
[\s\S]{1,20}

cart.items[n].number

The line number of this item on the invoice.

Optional

N3
[0-9]{3}

cart.items[n].customerCode

A customer-supplied code relating to this item.

Optional

ANS20
[\s\S]{1,20}

cart.items[n].vatReferenceNr

The reference number used to identify the VAT invoice or
tax receipt.

Optional

ANS20
[\s\S]{1,20}

cart.items[n].supplyType

The supply type. Valid values: 00 - Goods, 01 - Services

Optional

00|01

cart.items[n].totalAmountSign

This sign applies to the totalAmount field of this item
and to all the taxAmount fields of this item. If this
field is not present, D is assumed.

Optional

C|D

cart.items[n].invoiceDiscountTreatment

Indicates how the merchant is managing discounts.

Optional

AN1 [0-9\.]{1}

cart.items[n].lineItemDetailIndicator

Indicates type of line item detail record.

Optional

AN1 [0-9\.]{1}

cart.items[n].discountAmountSign

Discount amount interpretation.

Optional

AN1 [0-9\.]{1}

cart.items[n].description

A description of this item.

Optional

ANS40
[\s\S]{1,40}

cart.items[n].merchantItemId

The universal product code (UPC) of this item.

Optional

ANS20
[\s\S]{1,20}

cart.items[n].quantity

The quantity of this item.

Optional

N9.N3
[0-9]{1,10}(\.[0-9]{1,2})?

cart.items[n].unitOfMeasure

The unit of measure pertaining to the items[n].quantity field, as defined by the card acceptor.

Optional

ANS12
[\s\S]{1,12}

cart.items[n].totalAmount

The total amount (in the minor denomination) for this item.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

cart.items[n].totalAmountType

Indicates whether tax is included in, or excluded from, the cart.items[n].totalAmount field.

Optional

NET|GROSS

cart.items[n].sku

A merchant-supplied code or stock-keeping unit (SKU) relating to this item.

Optional

ANS20
[\s\S]{1,20}

cart.items[n].price

The price (in the minor denomination) of one unit of the
product.

Optional

[0-9]{1,8}(\.[0-9]{1,4})?

cart.items[n].discountAmount

The discount amount (in the minor denomination) applied
to this item.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

cart.items[n].discount

The discount rate applied to this item. Three decimal
places are implied.

Optional

cart.items[n].taxAmounts[n].taxType

The type of tax.

Optional

CITY_SALES|​
ENERGY|​
FEDERAL_NATIONAL_SALES|​
GOODS_AND_SERVICES|​
LOCAL_SALES|​
MUNICIPAL_SALES|​
OCCUPANCY|​
OTHER|​
PROVINCIAL_SALES|​
ROOM|​
STATE_SALES|​
UNKNOWN|​
VALUE_ADDED

cart.items[n].taxAmounts[n].taxDescription

A description of the type of tax, for example, "Freight".

Optional

ANS20
[\s\S]{1,20}

cart.items[n].taxAmounts[n].totalTaxAmount

A tax amount (in the minor denomination) applied to this item.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

cart.items[n].taxAmounts[n].tax

The tax rate to be applied to calculate this tax amount.

Optional

AN6
(100(\.00?)?)|([0-9]{1,2}(\.[0-9]{1,2})?)

cart.items[n].taxAmounts[n].taxId

An ID number used by the card acceptor with the tax authority in connection with this type of tax.

Optional

ANS20
[\s\S]{1,20}

cart.items[n]itemizedDiscounts[n].amount

The discount amount (in the minor denomination).

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

cart.items[n]itemizedDiscounts[n].rate

The discount rate. Three decimal places are
implied.

Optional

ANS5
[\s\S]{1,5}

cart.items[n]itemizedDiscounts[n].discountCode

The discount code supplied by the merchant.

Optional

ANS20
[\s\S]{1,20}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
 	-d "paymentType=CP"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
 	-d "card.accountType=DEFAULT"
 	-d "amount=16.50"
 	-d "pos.terminalId=12195611"
 	-d "pos.storeId=78123753"
 	-d "pos.entryMode=MAGSTRIPE"
 	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
 	-d "merchantOrderNumber=123456"
	-d "customer.orderNumber=8423794"
	-d "customer.customerCode=8423794"
	-d "customer.corporationVatNr=987654456789"
	-d "customer.vatNr=123456654321"
	-d "customer.orderTime=120106"
	-d "customer.purchaseDate=2021-05-19"
	-d "customer.billingCode=9988771122339911"
	-d "customer.fuelTaxExempt=TRUE"
	-d "customer.nonFuelTaxExempt=FALSE"
	-d "customer.provincialSalesTaxRegistrationNr="999994444477777"
	-d "customer.taxExempt=true"
	-d "merchant.taxId=8423794"
	-d "merchant.vatNr=6664446646"
	-d "merchant.refNr=7774447747"
	-d "merchant.invoiceDiscountTreatment=3"
	-d "merchant.taxTreatment=2"
	-d "totalShippingAmount=0.00"
	-d "totalDutyAmount=15.00"
	-d "totalDiscountAmount=15.00"
	-d "commodityCode=CC5456456456"
	-d "taxCollected=Y"
	-d "discountAmountSign=C"
	-d "shippingAmountSign=D"
	-d "dutyAmountSign=G"
	-d "card.commercialCardType=MC"
	-d "taxAmounts[0].taxType=GOODS_AND_SERVICES"
	-d "taxAmounts[0].totalTaxAmount=1.50"
	-d "taxAmounts[0].tax=00.10"
	-d "taxAmounts[0].taxId=G&S_taxes"
	-d "taxAmounts[0].taxDescription=State GS"
	-d "itemizedDiscounts[0].amount=156.46"
	-d "itemizedDiscounts[0].rate=57"
	-d "itemizedDiscounts[0].discountCode=j857684576846"
	-d "cart.items[0].description=genericDescription"
	-d "cart.items[0].merchantItemId=genericItemId"
	-d "cart.items[0].quantity=1"
	-d "cart.items[0].unitOfMeasure=lbs"
	-d "cart.items[0].totalAmount=15.00"
	-d "cart.items[0].totalAmountType=NET"
	-d "cart.items[0].sku=11125455"
	-d "cart.items[0].price=15.00"
	-d "cart.items[0].discountAmount=1.50"
	-d "cart.items[0].discount=10"
	-d "cart.items[0].taxAmounts[0].taxType=FEDERAL_NATIONAL_SALES"
	-d "cart.items[0].taxAmounts[0].totalTaxAmount=1.50"
	-d "cart.items[0].taxAmounts[0].tax=00.10"
	-d "cart.items[0].taxAmounts[0].taxId=us_taxes"
	-d "cart.items[0].taxAmounts[0].taxDescription=State TX"
	-d "cart.items[0].itemizedDiscounts[0].amount=156.46"
	-d "cart.items[0].itemizedDiscounts[0].rate=57"
	-d "cart.items[0].itemizedDiscounts[0].discountCode=j857684576846"
Note
The amount field in the message must indicate the total amount of the payment request, which includes all tax, duty, shipping, and other discount amounts. ConnectUP does not perform any calculations to ensure this.

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.20. Fleet Data

Fleet Data is compatible with the following message types:

ConnectUP supports sending fleet data, including prompt and batch data. All fleet fields are optional. When sending fleet data, fleet.prompts and fleet.fleetBatchDataList must be specified using an indexed-number [n], starting with 0.

For example:

fleet.prompts[0].tractorNumber = "TRACT5554433546"
Parameter name Description Required Regex

fleet.oilBrandName

The acquirer’s abbreviation for the brand name of the card acceptor’s oil company.

Optional

N4
[0-9]{4}

fleet.serviceType

The type of service received at the card acceptor location. Valid values: 1 - Self-service ​
2 - Full service ​
3 - Only non-fuel products purchased

Optional

ANS1
[\s\S]{1}

fleet.vehicleUsage

Valid values: ​
P - Private ​
B - Business :fleet_vehicleUsage_regex: A1
P|B

Optional

{fleet_vehicleUsage_regex}

fleet.odometer

The reading of the total distance travelled by the vehicle.

Optional

N8
[0-9]{8}

fleet.vehicleReg

The registration number of the rented or fleet vehicle.

Optional

AN17
[a-zA-Z0-9_]{17}

fleet.driverId

The number assigned to the driver by the employer for purposes of tracking fuel purchases.

Optional

AN17
[0-9]{1,17}

fleet.promptCode

Contains a code read from a card that indicates terminal prompts that occur at the point-of-service. Valid values: ​
1 - Prompts for identification number and odometer reading ​
2 - Prompts for vehicle number and odometer
reading ​
3 - Prompts for driver number and odometer reading ​
4 - Prompts for odometer reading only ​
5 - No prompts issued

Optional

N1
[0-9]{1}

fleet.restrictionCode

Contains the restriction code that applies to the transaction.

Optional

ANS3
[\s\S]{1,3}

fleet.privateData

Any data proprietary to the system for this item.

Optional

ANS999
[\s\S]{1,999}

fleet.purchaseType

The type of products purchased. Valid values: ​
F - Fuel ​
N - Non-fuel ​
B - Both

Optional

A1
F|N|B

fleet.prompts[n].userId

The user identification number.

Optional

AN15
[a-zA-Z0-9_]{15}

fleet.prompts[n].vehicleId

The vehicle identification number.

Optional

AN10
[a-zA-Z0-9_]{10}

fleet.prompts[n].department

The department number.

Optional

AN15
[a-zA-Z0-9_]{15}

fleet.prompts[n].driverLicense

The driver license number.

Optional

AN12
[a-zA-Z0-9_]{12}

fleet.prompts[n].customerData

Any customer data.

Optional

AN15
[a-zA-Z0-9_]{15}

fleet.prompts[n].jobId

The job identification number.

Optional

AN15
[a-zA-Z0-9_]{15}

fleet.prompts[n].contractNumber

The contract number.

Optional

AN20
[a-zA-Z0-9_]{20}

fleet.prompts[n].PIN

The vehicle PIN number.

Optional

ANS6
[\s\S]{6}

fleet.prompts[n].tripNumber

The fleet trip number.

Optional

ANS15
[\s\S]{15}

fleet.prompts[n].unitNumber

The fleet unit number.

Optional

AN10
[a-zA-Z0-9_]{10}

fleet.prompts[n].trailerId

The fleet trailer identification.

Optional

ANS15
[\s\S]{15}

fleet.prompts[n].trailerHours

The fleet trailer hours number.

Optional

N6
[0-9]{6}

fleet.prompts[n].maintenanceId

The fleet maintenance identification.

Optional

AN15
[a-zA-Z0-9_]{15}

fleet.prompts[n].hubometer

The fleet hubometer number.

Optional

N9
[0-9]{9}

fleet.prompts[n].employeeNumber

The fleet employee number.

Optional

N10
[0-9]{1,10}

fleet.prompts[n].driverLicenseState

The driver license state code.

Optional

AN2
[a-zA-Z0-9_]{2}

fleet.prompts[n].vehicleLicense

The vehicle license number.

Optional

ANS20
[\s\S]{1,20}

fleet.prompts[n].vehicleLicenseState

The vehicle license state code.

Optional

AN2
[a-zA-Z0-9_]{2}

fleet.prompts[n].trailerLicense

The trailer license number.

Optional

AN12
[a-zA-Z0-9_]{1,12}

fleet.prompts[n].trailerLicenseState

The trailer license state code.

Optional

AN2
[a-zA-Z0-9_]{1,2}

fleet.prompts[n].fleetId

The ID that is defined to the fleet authorizer.

Optional

AN6
[a-zA-Z0-9_]{1,6}

fleet.prompts[n].customData

This could carry fleet authorizer specific data like 'VoyagerData'.

Optional

ANS260
[\s\S]{1,260}

fleet.prompts[n].vehicleTag

The fleet vehicle tag.

Optional

AN99
[a-zA-Z0-9_]{1,99}

fleet.prompts[n].driverLicenseLocation

This is used to carry the state/province or other location data.

Optional

AN3
[a-zA-Z0-9_]{1,3}

fleet.prompts[n].driverLicenseName

The driver license name.

Optional

ANS22
[\s\S]{1,20}

fleet.prompts[n].driverDateOfBirth

The driver date of birth.

Optional

N8
[0-9]{1,8}

fleet.prompts[n].vehicleVINNumber

The vehicle identification number.

Optional

AN17
[a-zA-Z0-9_]{1,17}

fleet.prompts[n].pumpNumber

The petrol pump number.

Optional

AN99
[a-zA-Z0-9_]{1,99}

fleet.prompts[n].tractorNumber

The tractor number.

Optional

AN15
[a-zA-Z0-9_]{1,15}

fleet.fleetBatchDataList[n].batchDate

The fleet batch date.

Optional

N8
[0-9]{8}

fleet.fleetBatchDataList[n].transactionCount

The transaction count for a batch.

Optional

AN99
[a-zA-Z0-9_]{1,99}

fleet.fleetBatchDataList[n].total

The total fuel quantity.

Optional

N99
[0-9]{1,99}

fleet.fleetBatchDataList[n].totalUnit

The total units ('Gallons' or 'Liters').

Optional

Gallons|Liters

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=CP"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "card.accountType=DEFAULT"
	-d "amount=16.50"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
	-d "fleet.oilBrandName=9988"
	-d "fleet.serviceType=3"
	-d "fleet.vehicleUsage=B"
	-d "fleet.odometer=11227788"
	-d "fleet.vehicleReg=VREG543377FFGG444"
	-d "fleet.driverId=11147741"
	-d "fleet.promptCode=6"
	-d "fleet.restrictionCode= 1 "
	-d "fleet.privateData= Private Data 123"
	-d "fleet.purchaseType=B"
	-d "fleet.prompts[0].userId=UID5656MFNNNFF7"
	-d "fleet.prompts[0].vehicleId=VID88558HB"
	-d "fleet.prompts[0].department=DEP88555jjdd123"
	-d "fleet.prompts[0].driverLicense=DL666HHAAFFT"
	-d "fleet.prompts[0].customerData=CD55444IIIUUDDD6664446646"
	-d "fleet.prompts[0].jobId=JOBID55555666D3"
	-d "fleet.prompts[0].contractNumber=CNUMBER888FRT664AADF"
	-d "fleet.prompts[0].PIN= PIN  "
	-d "fleet.prompts[0].tripNumber=TRIP NUMBER 123"
	-d "fleet.prompts[0].unitNumber=FLEETUNIT5"
	-d "fleet.prompts[0].trailerId=TRAILER ID 12  "
	-d "fleet.prompts[0].trailerHours=000008"
	-d "fleet.prompts[0].maintenanceId=MAINTID12312312"
	-d "fleet.prompts[0].hubometer=000000009"
	-d "fleet.prompts[0].employeeNumber=666"
	-d "fleet.prompts[0].driverLicenseState=CA"
	-d "fleet.prompts[0].vehicleLicense=VEHLIC123"
	-d "fleet.prompts[0].vehicleLicenseState=CW"
	-d "fleet.prompts[0].trailerLicense=TL555"
	-d "fleet.prompts[0].trailerLicenseState=CR"
	-d "fleet.prompts[0].fleetId=FID123"
	-d "fleet.prompts[0].customData= THIS IS CUSTOM DATA "
	-d "fleet.prompts[0].vehicleTag=VEHTAG177"
	-d "fleet.prompts[0].driverLicenseLocation=CAQ"
	-d "fleet.prompts[0].driverLicenseName=This is my name"
	-d "fleet.prompts[0].driverDateOfBirth=19850212"
	-d "fleet.prompts[0].vehicleVINNumber=VINNUM12366"
	-d "fleet.prompts[0].pumpNumber=PUMPNUM3"
	-d "fleet.prompts[0].tractorNumber=TRACT5554433546"
	-d "fleet.fleetBatchDataList[0].batchDate=20210607"
	-d "fleet.fleetBatchDataList[0].transactionCount=0000001112"
	-d "fleet.fleetBatchDataList[0].total=00000111155544"
	-d "fleet.fleetBatchDataList[0].totalUnit=Liters"
Response

The response may contain fleet data which can be sent to the pump. Fleet data may be present in the fleet field of the response.

Parameter name Description Required Regex

fleet.promptForOdometer

The prompt is required to complete the transaction or not.

Optional

N1
[0-9]{1}

fleet.printPricePerGallon

This field identifies if price per gallon needs to be printed on customer receipt.

Optional

AN1
[a-zA-Z0-9_]{1}

fleet.maximumPurchaseAmount

The maximum purchase amount in minor denomination in the currency of the transaction.

Optional

N12
[0-9]{1,12}

fleet.maximumOilAmount

The maximum oil amount in minor denomination in the currency of the transaction.

Optional

N12
[0-9]{1,12}

fleet.maximumPartsAmount

The maximum parts amount in minor denomination in the currency of the transaction.

Optional

N12
[0-9]{1,12}

fleet.maximumAmountOther

The maximum other amount in minor denomination in the currency of the transaction.

Optional

N12
[0-9]{1,12}

Sample Response Containing fleet response data
{
	"id" : "e8f59d02a466f35a7ece785d3e137e50",
	"tokenId" : "JYO7rdR5UjK61111",
	"amount" : "92.00",
	"currency" : "USD",
	"result": {
		"code" : "000.000.000",
		"description" : "Transaction succeeded",
		"authorizationId" : "783276"
	},
	"customParameters":{
		"CUSTOM_KEY1":"CUSTOM_VALUE1",
		"CUSTOM_KEY2":"CUSTOM_VALUE2"
	},
	"fleet":{
		"promptForOdometer":"1",
		"printPricePerGallon":"2",
		"maximumPurchaseAmount":"000000001111",
		"maximumOilAmount":"000000002222",
		"maximumPartsAmount":"000000003333",
		"maximumAmountOther":"000000004444"
	},
	"resultDetails" : {
		"FleetDataRsp": "<FleetDataRsp MaximumAmountOther=\"000000004444\" MaximumOilAmount=\"000000002222\" MaximumPartsAmount=\"000000003333\" MaximumPurchaseAmount=\"000000001111\" PrintPricePerGallon=\"2\" PromptForOdometer=\"1\"></FleetDataRsp>"
	},
	"timestamp" : "2019-09-06 12:22:44"
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.21. Linked Capture

Linked Capture is compatible with the following message type:

A linked capture notification (CP) enables a merchant to capture a previously submitted pre-authorization message by providing the id of the original authorization in the linked capture request.

Parameter name Description Required Regex

referencedPaymentId

The identifier of the transaction being completed (the Id from the original PA response).
This field is conditional for completions. If present, then a linked-capture is performed, if absent then a stand-alone capture is performed.

Required

ANS32
[\s\S]{1,32}

Example
An example scenario follows:
  1. An initial PA request is submitted for the transaction.

  2. At the end of a business period, the original PA is captured by referencing its id in the referencedPaymentId field for the CP message.

Initial Pre-Authorization Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=PA"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=46.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78119753"
	-d "pos.entryMode=MANUAL"
Pre-Authorization Response
{
	"id" : "e8f59d02a466f35a7ece785d3e137e50",
	"amount" : "46.00",
	"currency" : "USD",
	"result": {
		"code" : "000.000.000",
		"description" : "Transaction succeeded",
		"authorizationId" : "783276"
	},
	"timestamp" : "2019-09-06 12:22:44"
}
Linked Capture Request using referencedPaymentId
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=CP"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=46.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78119753"
	-d "pos.entryMode=MANUAL"
	-d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.22. Merchant-Initiated Transaction (MIT)/Customer-Initiated Transaction (CIT)

Merchant-Initiated Transaction (MIT)/Customer-Initiated Transaction (CIT) is compatible with the following message types:

ConnectUP supports sending the following CIT and MIT transactions:

Initiated transaction type Required parameters

CIT First Transaction

(The cardholder is storing a credential for a subsequent transaction.)

  • Set pos.entryMode to any value other than CREDENTIAL_ON_FILE.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to CIT.

  • Save the bank-specific fields in the resultDetails response for future use.

CIT First Recurring Transaction

(The cardholder is storing a credential for a subsequent transaction.)

  • Set pos.entryMode to any value other than CREDENTIAL_ON_FILE.

  • Set standingInstruction.type to RECURRING.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to CIT.

  • Save the bank-specific fields in the resultDetails response for future use.

CIT First Recurring Installment Transaction

(The cardholder is storing a credential for a series of recurring installment transactions.)

  • Set pos.entryMode to any value other than CREDENTIAL_ON_FILE.

  • Set standingInstruction.type to INSTALLMENT.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to CIT.

  • Save the bank-specific fields in the resultDetails response for future use.

CIT Subsequent Transaction

(The cardholder is using a stored credential.)

  • Set pos.entryMode to CREDENTIAL_ON_FILE.

  • Set standingInstruction.mode to REPEATED.

  • Set standingInstruction.source to CIT.

  • Provide the saved bank-specific fields in the request customParameters field.

MIT Unscheduled Transaction

(The merchant using a stored credential as needed.)

  • Set pos.entryMode set to CREDENTIAL_ON_FILE.

  • Set standingInstruction.type to UNSCHEDULED.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to MIT.

  • Provide the saved bank-specific fields in the request customParameters field.

MIT First Recurring Transaction

(The merchant initiating a series of recurring transactions.)

  • Set pos.entryMode to CREDENTIAL_ON_FILE.

  • Set standingInstruction.type to RECURRING.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to MIT.

  • Provide the saved bank-specific fields in the request customParameters field.

MIT first recurring installment transaction

(The merchant initiating a series of recurring installment transactions.)

  • Set pos.entryMode to CREDENTIAL_ON_FILE.

  • Set standingInstruction.type to INSTALLMENT.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to MIT.

  • Provide the saved bank-specific fields in the request customParameters fields.

Industry practice of Delayed Charges

  • Set pos.entryMode to CREDENTIAL_ON_FILE.

  • Set standingInstruction.source to MIT.

  • Set standingInstruction.industryPractice to DELAYED_CHARGES.

The following fields are supported for previously listed MIT/CIT features:

Parameter name Description Required Regex

standingInstruction.mode

The Standing Instruction mode identifying whether this is the first transaction or a subsequent transaction in a series.

This field must be set to INITIAL for CIT Initial requests and Unscheduled MIT requests.

This field must be set to REPEATED for CIT Subsequent (pos.entryMode is set to CREDENTIAL_ON_FILE) and Recurring/Installment MIT requests. ​
This field is required if standingInstruction.type is specified.

Required

INITIAL|REPEATED

standingInstruction.source

The Standing Instruction source identifying whether a Customer- or Merchant-Initiated Transaction has been received.

When this field is present, standingInstruction.mode must be present.

Required

CIT|MIT

standingInstruction.type

The Standing Instruction type identifying whether the transaction is a recurring payment, installment payment, or unscheduled payment.

Optional

UNSCHEDULED|​
RECURRING|​
INSTALLMENT

standingInstruction.industryPractice

This field is used to specify if an industry practice applies to the transaction. This field cannot be specified in addition to standingInstruction.type.

Optional

INCREMENTAL_AUTH|RESUBMISSION|​
REAUTHORIZATION|DELAYED_CHARGES|NO_SHOW

Example
CIT Initial Transaction
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2018"
	-d "amount=21.00"
	-d "pos.storeId=78919753"
	-d "pos.terminalId=34056111"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "standingInstruction.mode=INITIAL"
	-d "standingInstruction.source=CIT"
MIT Subsequent Transaction
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2018"
	-d "amount=21.00"
	-d "pos.storeId=78919753"
	-d "pos.terminalId=34056111"
	-d "pos.entryMode=CREDENTIAL_ON_FILE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "standingInstruction.type=RECURRING"
	-d "standingInstruction.mode=REPEATED"
	-d "standingInstruction.source=MIT"
	-d "customParamters[bankField1]=bankValue1"
Response
Note
For cases where standingInstruction.mode is set to INITIAL, and standingInstruction.source is set to CIT, the upstream entity will return field data in resultDetails that will allow any subsequent messages to link back to the initial message as long as they are provided in the subsequent transaction as customParameters.
Sample Response from an INITIAL CIT transaction
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "50.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "resultDetails":{
        "bankField1":"bankValue1",
    },
    "timestamp" : "2019-09-06 12:00:00"
}
Note
For a subsequent transaction, the value in resultDetails must be present as a customParameter in the subsequent message.

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.23. Multiple Clearing (Captures)

Multiple Clearing (Captures) is compatible with the following message type:

ConnectUP supports sending multiple capture (CP) messages for a single authorization (PA). It is used to incrementally capture an authorization.

Merchants are able to submit multiple, partially-clearing capture notifications for the single authorization by adding a Capture Sequence number. This value indicates the number of the CP message in a sequence of multiple CP messages.

Note
Subsequent captures must reference the original PA message’s id in the referencedPaymentId field.
Parameter name Description Required Regex

captureSequence

Used to indicate the sequence number for a capture in a chain of linked captures or completions.

Required

N2
[0-9]{2}

lastCapture

When this flag is set to true, it indicates that the last capture or completion in the chain is being sent.

Optional

true

Example

An example for a Multiple Capture sequence might be an order that contains multiple items to ship. For each shipment, the merchant can perform a partial capture on the original pre-authorization message for the goods being delivered.

A multiple capture scenario follows:
  1. Send an initial authorization request for the total amount intended for the transaction.

  2. Fulfill half the order and partially capture one half the original initial authorization.

  3. Fulfill the remainder of the order and partially capture the remaining amount of the original authorization.

Initial Authorization Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=PA"
	-d "card.track2Data=5416389123456786D22021010000081315000"
	-d "amount=100.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Response of the Initial Authorization
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "100.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "timestamp" : "2019-09-06 12:00:00"
}
First Partial Capture Request

This is the first CP request referencing the PA’s `id in the referencedPaymentId field; specifying 25.00 USD. The captureSequence field is set to 01 indicating that this is the first CP in a chain.

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=CP"
	-d "card.track2Data=5416389123456786D22021010000081315000"
	-d "amount=25.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "captureSequence=01"
	-d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50"
Response of the First Capture Request
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "50.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "456464"
    },
    "timestamp" : "2019-09-07 12:00:00"
}
Final Partial Capture Request

This is the last CP request, again referencing the PA’s `id in the referencedPaymentId field, this time specifying 75.00 USD. The captureSequence field is set to 02, indicating that this is the second CP in the chain. The lastCapture field is set to true, indicating that this is the final CP message in the chain.

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=CP"
	-d "card.track2Data=5416389123456786D22021010000081315000"
	-d "amount=75.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "captureSequence=02"
	-d "lastCapture=true"
	-d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50"
Response of the Final Capture Request
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "75.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "7698987"
    },
    "timestamp" : "2019-09-10 12:00:00"
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.24. Partial Approval

Compatible with the following message types:

To allow partially approved transactions, add the following parameter to your payment message.

Note
If partialApprovalAllowed is set to false, the parameter will have no effect on the payment.
Parameter Name Description Required Regex

partialApprovalAllowed

When this flag is set to true, it indicates that partially approved authorizations are acceptable to the client.

Required

true

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "amount=21.00"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "partialApprovalAllowed=true"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this type of request.

2.3.25. Payment Identifier

Payment Identifier is compatible with the following message types:

The card.paymentIdentifier field can be used to represent any payment identifier, for example:

  • card numbers longer than 19 numeric digits

  • gift cards

  • voucher numbers

  • loyalty card numbers

  • fleet card numbers

Parameter name Description Required Regex

card.paymentIdentifier

The payment identifier used when card.number or card.track2Data are not appropriate, either due to limiting field formats/lengths, or not being an account based transaction.

Required

N28
[a-zA-Z0-9]{0,28}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=DB"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "card.paymentIdentifier=0123456789abcdefghiJKLMNOPQR"
	-d "amount=75.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.26. PIN-less Debit

PIN-less Debit is compatible with the following message types:

PIN-less debit attempts to route debit card transactions as debit transactions at the processor level without requiring cardholders to enter their PIN. This is typically applicable to signature debit and bill pay credit transactions and offers merchants an alternative method of accepting debit card payments.

Parameter name Description Required Regex

card.pinlessDebit

A flag that is used to attempt to route a transaction as debit at the processor level.

Required

true|​
false

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=DB"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "card.pinlessDebit=true"
  -d "amount=75.00"
  -d "pos.terminalId=12195611"
  -d "pos.storeId=78123753"
  -d "pos.entryMode=MAGSTRIPE"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Responses

The PIN-less debit response parameter will contain the route (DEBIT or CREDIT) used by the processor for the transaction.

Parameter name Description Regex

card.pinlessDebit

Indicates whether the transaction was processed as a credit or a debit transaction by the processor.

CREDIT|DEBIT

Response containing the PIN-less Debit response parameter
{
  "id" : "e8f59d02a466f35a7ece785d3e137e50",
  "amount" : "75.00",
  "currency" : "USD",
  "result": {
    "code" : "000.000.000",
    "description" : "Transaction succeeded",
    "authorizationId" : "783276"
  },
  "card" : {
    "pinlessDebit": "DEBIT"
  },
  "timestamp" : "2019-09-06 12:22:44"
}

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.27. Point-of-Sale (POS) Data Fields

Point-of-Sale (POS) Data Fields is compatible with the following message types:

ConnectUP provides the functionality to indicate specific conditions that were present at the time a transaction took place at the point-of-service (POS).

If present, the lower-level POS fields that are listed here will override any POS conditions that might have otherwise been inferred when constructing any standard ConnectUP message.

Parameter name Description Required Regex

pos.cardDataInputCapability

Indicates the supported methods for retrieving the card details at the point-of-service. When this field is not supplied, it is assumed that it is the same as the value for pos.entryMode.

Optional

UNKNOWN|​
MANUAL_NO_TERMINAL|​
MAGSTRIPE|​
BARCODE|​
OCR|​
MAGSTRIPE_MANUAL_ICC|​
MANUAL|​
MAGSTRIPE_MANUAL|​
MAGSTRIPE_ICC|​
ICC|​
NFC_ICC|​
MAGSTRIPE_MANUAL_ICC_NFC|​
NFC_MAGSTRIPE

pos.cardholderAuthenticationCapability

Indicates the mode of authentication of the cardholder that can be performed at the point-of-service. If not sent in a request, it is assumed that the point-of-service has no capability to authenticate the cardholder.

Optional

NONE|​
PIN|​
ELECTRONIC_SIGNATURE|​
BIOMETRIC|​
BIOGRAPHIC|​
INOPERATIVE|​
OTHER

pos.cardCaptureCapability

Indicates if the point-of-service can capture cards. If not sent in the request, it is assumed that the point-of-service cannot capture cards.

Optional

NONE|CAPTURE

pos.operatingEnvironment

Indicates the environment in which the point-of-service is operating. If not inferred by pos.entryMode, transactionCategory or set to a value directly, the MERCHANT_UNATTENDED value is used.

Optional

NO_TERMINAL|​
MERCHANT_ATTENDED|​
MERCHANT_UNATTENDED|​
OFFSITE_ATTENDED|​
OFFSITE_UNATTENDED|​
CUSTOMER_UNATTENDED

pos.cardholderPresent

Indicates if the cardholder is present at the time the transaction is performed. If not inferred by pos.entryMode or transactionCategory, CARD_HOLDER_PRESENT is used.

Optional

CARD_HOLDER_PRESENT|​
CARD_HOLDER_NOT_PRESENT

pos.cardPresent

Indicates if the card is present at the time the transaction is performed. If not inferred by pos.entryMode or transactionCategory, CARD_PRESENT is used.

Optional

CARD_PRESENT|​
CARD_NOT_PRESENT

pos.cardholderAuthenticationMethod

Indicates the mode of authentication of the cardholder that was performed at the point-of-service. If not sent in a request, it is assumed that the point-of-service did not perform any authentication.

Optional

MANUAL|​
MAGSTRIPE|​
NFC_MAGSTRIPE|​
NFC_ICC|​

pos.cardholderAuthenticationEntity

Indicates the entity that authenticated the cardholder at the point-of-service. If not inferred to AUTHORIZING_AGENT by pos.cardholderAuthenticationMethod or by the presence of PIN data, NOT_AUTHENTICATED is used.

Optional

NOT_AUTHENTICATED|​
ICC|​
TERMINAL|​
AUTHORIZING_AGENT|​
MERCHANT|​
OTHER

pos.cardDataOutputCapability

Indicates the point-of-service’s ability to update card data. If not sent in a request, it is assumed that the point-of-service has no capability to update card data.

Optional

MAGSTRIPE|​NONE|​ICC

pos.pinCaptureCapability

The maximum number of PIN characters that can be accepted by the point-of-service device. This field is required when a PIN was entered at the point-of-service but not verified offline. If not specified, but PIN data is provided, 4 characters are used. If not specified and no PIN data is available, UNKNOWN is used.

Optional

NONE|UNKNOWN|​
4|5|6|7|8|9|10|11|12

pos.terminalOperator

Indicates who is operating the point-of-service. If not inferred by pos.entryMode or transactionCategory, CUSTOMER is used.

Optional

CUSTOMER|​
MERCHANT|​
ADMIN

pos.terminalType

The type of terminal used to initiate the transaction. If no value is provided, the value is determined from the Transaction Category, if possible.

Possible values are:
ADMIN - Administrative terminal
ECOM_SECURE_NO_CRDHLDR_AUTH - E-commerce (secure channel, no cardholder authentication)
MOBILE_POS - Mobile Point of Sale
POS - Point of Sale
SMART_PHONE - Smart Phone
VRU - Voice Recognition Unit

Optional

ADMIN|​
ECOM_SECURE_NO_CRDHLDR_AUTH|​
MOBILE_POS|​
POS|​
SMART_PHONE|​
VRU

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "amount=21.00"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "pos.cardDataInputCapability=BARCODE"
  -d "pos.cardDataOutputCapability=ICC"
  -d "pos.cardholderAuthenticationCapability=PIN"
  -d "pos.cardholderAuthenticationMethod=NONE"
  -d "pos.cardCaptureCapability=NONE"
  -d "pos.operatingEnvironment=NONE"
  -d "pos.cardholderPresent=CARD_HOLDER_PRESENT"
  -d "pos.terminalType=POS"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.28. Receiving Institution Code

Receiving Institution Code is compatible with the following message types:

To identify the financial institution that must receive the transaction, add the following parameter to your payment message.

Parameter name Description Required Regex

merchant.receivingInstitutionCode

A code identifying the financial institution that must receive a message. When present, this value is used to calculate the route for a message in upstream systems.

Required

N11
[0-9]{1,11}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "amount=21.00"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "merchant.receivingInstitutionCode=12345678901"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.29. Reversal Reason

Reversal Reason is compatible with the following message type:

The reason field can be used to indicate why a transaction is being reversed.

Parameter name Description Required Regex

reason

Indicates the reason for the reversal.

Possible values are:
VOID - Customer Cancellation
TIMEOUT - Timeout Reversal
MAC - MAC Reversal
STORE_CONTROLLER - Store Controller Reversal

Required

VOID|TIMEOUT|MAC|STORE_CONTROLLER

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"`
	-d "paymentType=RV"
	-d "pos.terminalId=38956111"
	-d "referencedPaymentId=1b8cd7b6c81c9883e8926f04985fa7b5"
	-d "reason=VOID"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.30. Reversal using referencedMerchantTransactionId

Reversals using referencedMerchantTransactionId are compatible with the following message type:

If a value for the referencedPaymentId parameter is not available, the merchantTransactionId value from the original request being reversed can be provided for the referencedMerchantTransactionId parameter instead.

Reasons for not having the referencedPaymentId parameter available include:

  • the merchant timed out waiting for ConnectUP to return a response

  • the connection between the merchant and ConnectUP was broken before the response could be delivered

  • application failures during response processing at the merchant or ConnectUP

Parameter Name Description Required Regex

referencedMerchantTransactionId

The supplied "merchantTransactionId" of the original PA, DB, CD, or CP transaction that is to be reversed.

Required

ANS255
[\s\S]{8,255}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=RV"
  -d "pos.terminalId=34056111"
  -d "referencedMerchantTransactionId=12548896257"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.31. Strong Customer Authentication (SCA)

Strong Customer Authentication (SCA) is compatible with the following message types:

SCA is required when certain limits are exceeded for contactless payments. An issuer will decide if SCA must be applied. If SCA is required, the transaction will be declined.

Merchants can apply for an exemption by specifying an SCA exemption flag in request messages which informs upstream entities of a terminal’s single tap with PIN capabilities. This field is also used when a PIN is provided to satisfy an SCA request.

Parameter name Description Required Regex

pos.scaExemptionFlag

Used for NFC transactions. Upstream entities decide whether the cardholder must provide alternative authentication to complete the transaction based on the value set in this field, along with other transaction data.

Possible values are:
PIN_PROVIDED (PIN Provided for SCA request)​
TAP_AND_PIN_SUPPORTED (Single Tap with PIN supported)

Required

PIN_PROVIDED|​
TAP_AND_PIN_SUPPORTED

SCA Response

If SCA is required, the following result codes can be expected in the response body result.code parameter:

Parameter name Description Required Regex

result.code

The unique code that indicates the result status of the request.
See Result Codes for more details.

See the SCA Result Code table for details.

Required

AN11
[0-9\.]{2,11}

SCA Result Code Listing
Result code Description

300.100.100

Transaction declined (additional customer authentication required)

300.100.190

Transaction declined (Issuer Requires PIN [SCA])

300.100.191

Transaction declined (SCA exemption is invalid)

300.100.192

Transaction declined (additional customer authentication required)

Tip
See the standard response fields for a list of possible response parameters that ConnectUP can return for this request type.
Example

An example scenario for SCA for terminals that support Single Tap and PIN, where the customer withdrawal frequency has been exceeded, follows:

  1. A standard contactless pre-authorization message is sent with pos.scaExemptionFlag = TAP_AND_PIN_SUPPORTED.

  2. The upstream entity responds with the 300.100.190: Transaction declined (Issuer Requires PIN [SCA]) result code.

  3. The terminal updates the message with the provided PIN.

  4. A new payment message with PIN is sent to ConnectUP.

  5. The pos.scaExemptionFlag field is updated to PIN_PROVIDED

  6. No further exemption will be applied to transactions that contain PIN data.

Initial contactless request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=10000000.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=NFC_ICC"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "pos.scaExemptionFlag=TAP_AND_PIN_SUPPORTED"
Response indicating the declined transaction due to the issuer requesting SCA
{
  "id" : "e8f59d02a466f35a7ece785d3e137e50",
  "amount" : "0.00",
  "currency" : "USD",
  "result": {
    "code" : "300.100.190",
    "description" : "Transaction declined (Issuer Requires PIN [SCA])",
    "authorizationId" : "783276"
  },
  "timestamp" : "2019-09-06 12:22:44"
}
Secondary contactless request with PIN data to satisfy the exemption
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=10000000.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=NFC_ICC"
  -d "pos.encryptedPin.data=A3929E6A25E8E32C"
  -d "pos.encryptedPin.ksn=*"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "pos.scaExemptionFlag=PIN_PROVIDED"
Note
For terminals that do not support single tap and PIN, the customer will have to re-present their card and enter a PIN. This data must be present in the second payment message with pos.scaExemptionFlag set to PIN_PROVIDED, as previously illustrated.

2.3.32. Shipping Contact

Shipping Contact is compatible with the following message types:

To specify the contact details of the shipping sender or receiver, use the following fields.

The shipping.* fields must be used for the customer which receiving the shipment. The shipping.from.* fields must be used for the merchant/retailer which is sending the shipment.

Parameter name Description Required Regex

shipping.street1

The door number, floor, building number, building name, and/or street name of the shipping address.

Optional

ANS50
[\s\S]{1,50}

shipping.street2

The adjoining road or locality (if required) of the shipping address.

Optional

ANS50
[\s\S]{1,50}

shipping.method

The shipping method.

Optional

CARRIER_DESIGNATED_BY_CUSTOMER|​
ELECTRONIC_DELIVERY|​
EXPEDITED|​
GROUND|​
INTERNATIONAL|​
LOWEST_COST|​
MILITARY|​
NEXT_DAY_OVERNIGHT|​
OTHER, STORE_PICKUP|​
PUDO|​
SAME_DAY_SERVICE|​
TWO_DAY_SERVICE|​
THREE_DAY_SERVICE

shipping.warehouse

The warehouse that received the order.

Optional

ANS100
[\s\S]{1,100}

shipping.houseNumber1

Primary house number (door number or building number) of the shipping address. If present, then shipping.street1 is assumed to contain only the name of the street.

Optional

ANS50
[\s\S]{1,50}

shipping.postcode

The postal code or zip code of the shipping address.

Optional

AN9
[A-Za-z0-9]{1,9}

shipping.city

The town, district, or city of the shipping address.

Optional

ANS20
[\s\S]{1,20}

shipping.state

The county, state, or region of the shipping address.

Optional

AN20
[a-zA-Z0-9\.]{1,20}

shipping.country

The country of the shipping address (ISO 3166-1).

Optional

A2
[A-Z]{2}

shipping.customer.givenName

The first name or given name of the shipping customer.

Optional

ANS50
[\s\S]{1,50}

shipping.customer.surname

The last name or surname of the shipping customer.

Optional

ANS50
[\s\S]{1,50}

shipping.customer.email

The shipping customer’s email address. This is required for some risk checks and transmission of direct debit mandates.

Optional

ANS128
[\s\S]{6,128}

shipping.customer.companyName

The company name to contact.

Optional

ANS50
[\s\S]{1,50}

shipping.from.street1

The door number, floor, building number, building name, and/or street name of the shipping address.

Optional

ANS50
[\s\S]{1,50}

shipping.from.street2

The adjoining road or locality (if required) of the shipping address.

Optional

ANS50
[\s\S]{1,50}

shipping.from.warehouse

The warehouse that received the order.

Optional

ANS100
[\s\S]{1,100}

shipping.from.houseNumber1

Primary house number (door number or building number) of the shipping address. If present, then shipping.from.street1 is assumed to contain only the name of the street.

Optional

ANS50
[\s\S]{1,50}

shipping.from.postcode

The postal code or zip code of the shipping address.

Optional

AN9
[A-Za-z0-9]{1,9}

shipping.from.city

The town, district, or city of the shipping address.

Optional

ANS20
[\s\S]{1,20}

shipping.from.state

The county, state, or region of the shipping address.

Optional

AN20
[a-zA-Z0-9\.]{1,20}

shipping.from.country

The country of the shipping address (ISO 3166-1).

Optional

A2
[A-Z]{2}

shipping.from.customer.givenName

The first name or given name of the shipping customer.

Optional

ANS50
[\s\S]{1,50}

shipping.from.customer.surname

The last name or surname of the shipping customer.

Optional

ANS50
[\s\S]{1,50}

shipping.from.customer.email

The shipping customer’s email address. This is required for some risk checks and transmission of direct debit mandates.

Optional

ANS128
[\s\S]{6,128}

shipping.from.customer.companyName

The company name to contact.

Optional

ANS50
[\s\S]{1,50}

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=75.00"
  -d "pos.terminalId=12195611"
  -d "pos.storeId=78123753"
  -d "pos.entryMode=MAGSTRIPE"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
  -d "shipping.street1=Receiver Park"
  -d "shipping.street2=123 Main Street"
  -d "shipping.houseNumber1=1"
  -d "shipping.postcode=7500"
  -d "shipping.city=Cape Town"
  -d "shipping.state=WC"
  -d "shipping.country=ZA"
  -d "shipping.method=NEXT_DAY_OVERNIGHT"
  -d "shipping.warehouse=Receiving Warehouse"
  -d "shipping.customer.givenName=John"
  -d "shipping.customer.surname=Smith"
  -d "shipping.customer.email=johnsmith@receivingemail.com"
  -d "shipping.customer.company=The Receiving Company"
  -d "shipping.from.street1=Sender Complex"
  -d "shipping.from.street2=13 West Street"
  -d "shipping.from.houseNumber1=1"
  -d "shipping.from.postcode=7500"
  -d "shipping.from.city=Cape Town"
  -d "shipping.from.state=WC"
  -d "shipping.from.country=ZA"
  -d "shipping.from.warehouse=Sending Warehouse"
  -d "shipping.from.customer.givenName=Jeffrey"
  -d "shipping.from.customer.surname=Zebos"
  -d "shipping.from.customer.email=jeffzebos@sendingemail.com"
  -d "shipping.from.customer.companyName=The Sending Company"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

2.3.33. Transaction Category

Transaction Category is compatible with the following message types:

If required, a transaction category, which identifies the type of transaction being constructed, can be specified in payment request messages sent to ConnectUP.

Enriching a request message with a transactionCategory value helps determine whether the transaction is either a card-present or card-not-present message.

Parameter name Description Required Regex

transactionCategory

The category of the transaction. Used to identify the transaction as card-not-present and/or cardholder-not- present (among other parameters). By default, the card and cardholder are presumed to be present.

Possible values are:
EC - eCommerce (Card-holder not present, electronic order and Card not present)
IN - Installment (Card-holder not present, standing authorization/recurring transaction and Card not present)
MO - Mail order (Card-holder not present, mail order and Card not present)
PM - Mobile POS (Card-holder present and Card Present)
PO - POS (Card-holder present and Card Present)
TO - Telephone order (Card-holder not present, telephone and Card not present)

Required

EC|IN|MO|PM|PO|TO

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmYT...."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=DB"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2018"
  -d "amount=95.00"
  -d "pos.storeId=78919753"
  -d "pos.terminalId=34056111"
  -d "pos.entryMode=MANUAL"
  -d "transactionCategory=EC"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.

3. Token Service

The Tokenization service creates a token based on card data and retrieves card data based on a token.

A Tokenization Request is created by sending a POST request over HTTPS to:

https://[hostname]:[port]/paymentsapi/opp/v1/token/tokenize

A De-tokenization Request is created by sending a POST request over HTTPS to:

https://[hostname]:[port]/paymentsapi/opp/v1/token/detokenize

3.1. Tokenization

Tokenization is the process whereby sensitive card details are substituted with a token, a value which in and of itself holds no identifiable or exploitable information.

3.1.1. Tokenization Request

A tokenization request stores sensitive card data fields and returns a token. This token can be used to initiate payments in place of the card details associated with the token.

Note
Either card.number, card.track2Data, or P2PE card data fields must be specified for a tokenization request.
Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

card.number

The Primary Account Number (PAN) of the physical card.

Conditional

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Optional

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Optional

N4
(20|21)([0-9]{2})

Note
The card expiry fields (card.expiryMonth and card.expiryYear) must either both be set, or neither must be set. A token created without expiry data can be used in a payment request only if the expiry data is sent with the payment request.
Example
curl http://[hostname]:[port]/opp/v1/token/tokenize -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "card.number=2222333344442226"
  -d "card.expiryMonth=12"
  -d "card.expiryYear=2020"

3.1.2. Tokenization Response

The following fields reflect the possible response values for Tokenization service requests.

Parameter name Description Required Regex

id

The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client.

Required

AN32
[a-zA-Z0-9]{1,32}

tokenId

A token representing sensitive cardholder data.

Optional

AN255
[a-zA-Z0-9]{255}

result.code

The unique code that indicates the result status of the request.
See Result Codes for more details.

See common result codes for this type of request.

Required

AN11
[0-9\.]{2,11}

result.description

A textual description explaining the result.code meaning. If a field validation exception occurs, this field will also indicate the name of the field or fields that failed validation.

Optional

AN255
[\s\S]{0,255}

resultDetails.*

A container for name-value pairs used for enriching the response with bank-specific response details.

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

Example
{
   "id" : "e8f59d02a466f35a7ece785d3e137e50",
   "tokenId" : "JYO7rdR5UjK61111",
   "result": {
      "code" : "000.000.000",
      "description" : "Transaction successful",
   },
   "resultDetails": {
      "Field1": "Value1",
      "Field2": "Value2"
   },
   "timestamp" : "2018-02-20 12:00:00"
}
Common result codes for tokenization requests:
Result code Description

000.000.000

Transaction succeeded

800.900.303

No token created

000.000.099

Transaction Succeeded (partial approval)

200.300.404

Invalid or missing parameter

800.100.190

Token generation not permitted

800.100.190

Token set invalid or not permitted

800.100.190

Multi-use token collision

800.100.190

Single-use token collision

800.100.190

Token operation not permitted or supported

800.100.190

Transaction declined (invalid configuration data)

900.100.400

Token service unavailable

900.100.600

Token server malfunction

900.100.600

Connector/acquirer currently down

Note
Optional fields will only be returned if the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

3.2. De-tokenization

De-tokenization is the process where a token value is used to retrieve the original tokenized card details through a secure tokenization system.

3.2.1. De-tokenization Request

A de-tokenization request retrieves sensitive card-data fields associated with the supplied token.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

tokenId

A token representing sensitive cardholder data.

Required

AN255
[a-zA-Z0-9]{255}

The tokenId parameter is a token that has previously been returned by a tokenization request or returned in the payment request response.

Example
curl http://[hostname]:[port]/opp/v1/token/detokenize -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "tokenId=JYO7rdR5UjK61111"

3.2.2. Detokenization Response

The following fields reflect the possible response values for de-tokenization service requests.

The De-tokenization service supports response msg encryption. Please read the Configuring Encryption section of the PaymentsAPI user guide for more information.

Parameter name Description Required Regex

id

The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client.

Required

AN32
[a-zA-Z0-9]{1,32}

tokenId

A token representing sensitive cardholder data.

Optional

AN255
[a-zA-Z0-9]{255}

result.code

The unique code that indicates the result status of the request.
See Result Codes for more details.

See common result codes for this request type.

Required

AN11
[0-9\.]{2,11}

result.description

A textual description explaining the result.code meaning. If a field validation exception occurs, this field will also indicate the name of the field or fields that failed validation.

Optional

AN255
[\s\S]{0,255}

card.number

The Primary Account Number (PAN) of the physical card. This field is always returned for successful de-tokenization requests.

Conditional

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Optional

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Optional

N4
(20|21)([0-9]{2})

resultDetails.*

A container for name-value pairs used for enriching the response with bank-specific response details.

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

Note
The card.expiryMonth and card.expiryYear fields will only be populated if they were included in the original tokenization request for this tokenId.
Example
{
   "id" : "e8f59d02a466f35a7ece785d3e137e50",
   "tokenId" : "JYO7rdR5UjK61111",
   "result": {
      "code" : "000.000.000",
      "description" : "Transaction successful",
   },
   "card": {
      "number": "1234567890123456"
      "expiryMonth": "12"
      "expiryYear": "2020"
   },
   "resultDetails": {
      "Field1": "Value1",
      "Field2": "Value2"
   },
   "timestamp" : "2018-02-20 12:00:00"
}
Common result codes for de-tokenization requests:
Result code Description

000.000.000

Transaction Succeeded

800.900.303

Token operation error

100.150.200

Token not found

100.150.202

Attempted to detokenize a deactivated token

900.100.400

Token service unavailable

900.100.600

Token server malfunction

900.100.600

Connector/acquirer currently down

Note
Optional fields will only be returned if the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

4. P2PE Service

Warning
The P2PE Service is not officially supported as of this release and is subject to change.

4.1. Remote Key Distribution (RKD)

The RKD service distributes cryptographic material (P2PE encryption keys) to terminals.

For RKD Exchange Request messages, use https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdrequest

For RKD Exchange Confirmation Request messages, use https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm

4.1.1. RKD Exchange Request

The minimum requirements for sending an RKD Exchange Request message are listed here:

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

rkdScheme

Indicates the Remote Key Distribution (RKD) scheme in use.
Please contact ACI for this value.

Required

[\s\S]{1,32}

rkdRequestData

Data associated with the key request. The field format is dependent on the type of Remote Key Distribution scheme used (the value of rkdScheme). For more information on formatting this field, refer to the respective vendor’s RKD documentation. The field contains binary data encoded as a hex string.

Required

AN65535
[a-fA-F0-9]{1,65535}

keyStatus

Indicates the status of the current P2PE key.
Possible values:
COMPROMISED - The P2PE key on the PED has been compromised.
EXPIRED - The P2PE key on the PED has expired.
INVALID - The P2PE key on the PED is invalid.
NOT_PRESENT - There is currently no P2PE key available on the PED.
REVOKED - The P2PE key on the PED has been revoked.
VALID - The P2PE key available on the PED is valid.

Conditionally required. Depends on the type of Remote Key Distribution scheme used (the value of rkdScheme)

COMPROMISED|​
EXPIRED|​
INVALID|​
NOT_PRESENT|​
REVOKED|​
VALID|​

deviceName

An identifiable name for the PED involved in the key exchange. Examples include Ingenico_RBA, Verifone_FORMAGENT, SC5000, and VX810.

Conditionally required. Depends on the type of Remote Key Distribution scheme used (the value of rkdScheme)

AN32
[a-zA-Z0-9]{1,32}

RKD Exchange Response

The following fields reflect the possible response values for the RKD Exchange Request service.

Parameter name Description Required Regex

resultDetails.rkdKeyData

New (encrypted) P2PE key. The field format is dependent on the type of Remote Key Distribution used (the value of rkdScheme in the request message). For more information on formatting this field, refer to the respective vendor’s RKD documentation. The field contains binary data encoded as a hex string.

Conditional

AN65535
[a-fA-F0-9]{1,65535}

resultDetails.rkdEchoData

A value that must be sent back by the PED in an RKD confirmation request after applying the new P2PE key.

Conditional

AN32
[a-zA-Z0-9]{1,32}

See the Standard RKD Exchange Response fields for an extended listing of the possible response parameters ConnectUP can return for this request type.

4.1.2. RKD Exchange Confirmation Request

The minimum requirements for sending an RKD Exchange Confirmation Request message are listed here:

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

rkdScheme

Indicates the Remote Key Distribution (RKD) scheme in use.
Please contact ACI for this value.

Required

[\s\S]{1,32}

rkdKeyConfirmationData

Key confirmation data from the PED after attempting to apply a key supplied in a previous RKD exchange.
The field format is dependent on the type of Remote Key Distribution scheme used (the value of rkdScheme).
For more information on formatting this field, refer to the respective vendor’s RKD documentation.
The field contains binary data encoded as a hex string.

Required

AN65535
[a-fA-F0-9]{1,65535}

rkdEchoData

The echo data value sent in the RKD exchange response.

Required

AN32
[a-zA-Z0-9]{1,32}

deviceName

An identifiable name for the PED involved in the key exchange. Examples include Ingenico_RBA, Verifone_FORMAGENT, SC5000, and VX810.

Conditionally required. Depends on the type of Remote Key Distribution scheme used (the value of rkdScheme)

AN32
[a-zA-Z0-9]{1,32}

RKD Confirmation Response

See the Standard RKD Exchange Response fields for a listing of the possible response parameters ConnectUP can return for this request type.

4.1.3. Standard RKD Exchange Response

The following fields reflect the possible response values for request messages sent to either the https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdrequest or https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm resources.

Parameter name Description Required Regex

id

The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client.

Required

AN32
[a-zA-Z0-9]{1,32}

result.code

The unique code that indicates the result status of the request.
See Result Codes for more details.

Required

AN11
[0-9\.]{2,11}

result.description

A textual description explaining the result.code meaning. If a field validation exception occurs, this field will also indicate the name of the field or fields that failed validation.

Required

AN255
[\s\S]{0,255}

timestamp

The timestamp generated by the response in UTC.

Required

date
yyyy-MM-dd hh:mm:ss

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Conditional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

resultDetails.*

A container for name-value pairs used for enriching the response with bank-specific response details.

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

Note
Optional fields will only be returned if the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

5. VP2PE Service

Warning
The VP2PE Service is not officially supported as of this release and is subject to change.

5.1. Device Data

The Validated P2PE service submits terminal data for reporting and record keeping purposes as part of a validated P2PE solution.

For Device Data requests, use https://[hostname]:[port]/paymentsapi/opp/v1/vp2pe/devicedata

5.1.1. Device Data Request

The minimum requirements for sending a Device Data Capture message are listed here.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

terminal.terminalId

Terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

terminal.devices[n].id

The device’s ID.

Required

ANS2048
[\s\S]{1,2048}

terminal.devices[n].capabilities[n].capability

The device’s capability.

Required

ATM|​
CARDREADER|​
CHECKREADER|​
DISPLAY|​
KEYPAD|​
PINPAD|​
POS|​
PRINTER|​
SIGCAP

merchant.street

The street address of the merchant.

Optional

ANS23
[\s\S]{1,23}

merchant.city

The city of the merchant.

Optional

ANS13
[\s\S]{1,13}

merchant.state

The county, state, or region of the merchant.

Optional

AN2
[a-zA-Z0-9]{1,2}

merchant.country

The country of the merchant.

Optional

AN2
[A-Za-z]{2}

terminal.storeId

Store identifier assigned by the acquirer.

Optional

ANS15
[\s\S]{1,15}

terminal.devices[n].additionalAttributes[key]

Additional attributes sent as key-value pairs.

Optional

key: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

terminal.devices[n].hardware.components[n].type

The type of hardware component used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.components[n].version

The hardware component version used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.components[n].iss

The hardware component issue used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.components[n].ass

The hardware component assembly used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.components[n].effDate

The hardware component effective date used by the device.

Optional

{term_device_hw_cmpnnt__effDate_regex}

terminal.devices[n].hardware.components[n].expDate

The hardware component expiry date used by the device.

Optional

YYYY-MM-DD

terminal.devices[n].hardware.components[n].ref

The hardware component reference used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.manufacturer

The device’s hardware manufacturer.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.manufacturerSerial

The device’s hardware manufacturing serial number.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.serial

The device’s hardware serial.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.series

The device’s hardware series.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.modelName

The device’s hardware model name.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.modelNumber

The device’s hardware model number.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.version

The device’s hardware version.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].hardware.date

The device’s hardware date.

Optional

YYYY-MM-DD

terminal.devices[n].hardware.ipAddress

The device’s hardware IP address.

Optional

ANS39
[\s\S]{1,39}

terminal.devices[n].hardware.macAddress

The device’s hardware MAC address.

Optional

ANS17
[\s\S]{1,17}

terminal.devices[n].hardware.additionalAttributes[key]

Additional attributes sent as key-value pairs.

Optional

key: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

terminal.devices[n].software.modules[n].component.type

The software module component type used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].component.version

The software module component version used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].component.iss

The software module component issue used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].component.ass

The software module component assembly used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].component.effDate

The software module component effective date used by the device.

Optional

YYYY-MM-DD

terminal.devices[n].software.modules[n].component.expDate

The software module component expiry date used by the device.

Optional

YYYY-MM-DD

terminal.devices[n].software.modules[n].component.ref

The software module component reference used by the device.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].moduleType

The device’s software module type.

Optional

APP|CNTCTLS_KERNEL|EMV_KERNEL|​
FILE|LIB|OS|

terminal.devices[n].software.modules[n].name

The device’s software module name.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].version

The device’s software module version.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].date

The device’s software module date.

Optional

YYYY-MM-DD

terminal.devices[n].software.modules[n].build

The device’s software module build.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].hash

The device’s software module hash.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].prov

The device’s software module provision.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].minorVersion

The device’s software module minor version.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].software.modules[n].majorVersion

The device’s software module major version.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].properties[n].name

The device’s property name.

Optional

ANS2048
[\s\S]{1,2048}

terminal.devices[n].properties[n].value

The device’s property value.

Optional

ANS2048
[\s\S]{1,2048}

terminal.additionalAttributes[key]

Additional attributes sent as key-value pairs.

Optional

key: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

Example
curl http://[hostname]:[port]/opp/v1/vp2pe/devicedata -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "merchant.street=street"
  -d "merchant.city=city"
  -d "merchant.state=WC"
  -d "merchant.country=ZA"
  -d "terminal.storeId=123456789112345"
  -d "terminal.terminalId=12345678"
  -d "terminal.additionalAttributes[termAAkey]=termAAValue"
  -d "terminal.additionalAttributes[termAAkey2]=termAAValue2"
  -d "terminal.devices[0].id=222"
  -d "terminal.devices[0].capabilities[0].capability=SIGCAP"
  -d "terminal.devices[0].capabilities[1].capability=ATM"
  -d "terminal.devices[0].hardware.components[0].type=compType"
  -d "terminal.devices[0].hardware.components[0].version=version"
  -d "terminal.devices[0].hardware.components[0].iss=issue1"
  -d "terminal.devices[0].hardware.components[0].ass=assemblyB"
  -d "terminal.devices[0].hardware.components[0].effDate=2020-12-31"
  -d "terminal.devices[0].hardware.components[0].expDate=2028-12-31"
  -d "terminal.devices[0].hardware.components[0].ref=12345"
  -d "terminal.devices[0].hardware.manufacturer=INGENICO"
  -d "terminal.devices[0].hardware.serial=3878035089745"
  -d "terminal.devices[0].hardware.modelName=ip3500"
  -d "terminal.devices[0].hardware.modelNumber=3500c"
  -d "terminal.devices[0].hardware.version=1.0"
  -d "terminal.devices[0].hardware.date=2020-01-30"
  -d "terminal.devices[0].hardware.macAddress=F7-08-67-EC-01-98"
  -d "terminal.devices[0].hardware.ipAddress=10.0.0.1"
  -d "terminal.devices[0].hardware.series=series"
  -d "terminal.devices[0].software.modules[0].moduleType=FILE"
  -d "terminal.devices[0].software.modules[0].component.type=type"
  -d "terminal.devices[0].software.modules[0].component.version=34523"
  -d "terminal.devices[0].software.modules[0].component.iss=iss4"
  -d "terminal.devices[0].software.modules[0].component.ass=412"
  -d "terminal.devices[0].software.modules[0].component.effDate=2020-01-31"
  -d "terminal.devices[0].software.modules[0].component.expDate=2020-01-31"
  -d "terminal.devices[0].software.modules[0].component.ref=987454"
  -d "terminal.devices[0].software.modules[0].name=FileServ"
  -d "terminal.devices[0].software.modules[0].version=1"
  -d "terminal.devices[0].software.modules[0].build=1"
  -d "terminal.devices[0].software.modules[0].hash=ea783427hf0e"
  -d "terminal.devices[0].software.modules[0].prov=1"
  -d "terminal.devices[0].software.modules[0].minorVersion=1"
  -d "terminal.devices[0].software.modules[0].majorVersion=2"
  -d "terminal.devices[0].software.modules[0].date=2020-11-11"
  -d "terminal.devices[0].properties[0].name=some-property"
  -d "terminal.devices[0].properties[0].value=123"
  -d "terminal.devices[0].properties[1].name=some-property"
  -d "terminal.devices[0].properties[1].value=321"
  -d "terminal.devices[1].id=2"
  -d "terminal.devices[1].capabilities[0].capability=SIGCAP"
  -d "terminal.devices[1].capabilities[1].capability=ATM"
  -d "terminal.devices[1].hardware.components[0].type=compType"
  -d "terminal.devices[1].hardware.components[0].version=version"
  -d "terminal.devices[1].hardware.components[0].iss=iss"
  -d "terminal.devices[1].hardware.components[0].ass=ass"
  -d "terminal.devices[1].hardware.components[0].effDate=2020-12-31"
  -d "terminal.devices[1].hardware.components[0].expDate=2028-12-31"
  -d "terminal.devices[1].hardware.components[0].ref=ref"
  -d "terminal.devices[1].hardware.components[1].type=compType"
  -d "terminal.devices[1].hardware.components[1].version=version"
  -d "terminal.devices[1].hardware.components[1].iss=iss"
  -d "terminal.devices[1].hardware.components[1].ass=ass"
  -d "terminal.devices[1].hardware.components[1].effDate=2020-12-31"
  -d "terminal.devices[1].hardware.components[1].expDate=2028-12-31"
  -d "terminal.devices[1].hardware.components[1].ref=ref"
  -d "terminal.devices[1].hardware.additionalAttributes[hwAAkey]=hwAAValue"
  -d "terminal.devices[1].hardware.additionalAttributes[hwAAkey2]=hwAAValue2"
  -d "terminal.devices[1].hardware.modelName=modelName"
  -d "terminal.devices[1].hardware.serial=serial"
  -d "terminal.devices[1].hardware.manufacturer=manufacturer"
  -d "terminal.devices[1].hardware.modelNumber=modelNumber"
  -d "terminal.devices[1].hardware.version=version"
  -d "terminal.devices[1].hardware.date=2020-01-30"
  -d "terminal.devices[1].hardware.macAddress=F7-08-67-EC-01-98"
  -d "terminal.devices[1].hardware.ipAddress=10.0.0.1"
  -d "terminal.devices[1].hardware.series=series"
  -d "terminal.devices[1].software.modules[0].moduleType=FILE"
  -d "terminal.devices[1].software.modules[0].component.type=type"
  -d "terminal.devices[1].software.modules[0].component.version=version"
  -d "terminal.devices[1].software.modules[0].component.iss=iss"
  -d "terminal.devices[1].software.modules[0].component.ass=ass"
  -d "terminal.devices[1].software.modules[0].component.effDate=2020-01-31"
  -d "terminal.devices[1].software.modules[0].component.expDate=2020-01-31"
  -d "terminal.devices[1].software.modules[0].component.ref=ref"
  -d "terminal.devices[1].software.modules[0].name=name"
  -d "terminal.devices[1].software.modules[0].version=version"
  -d "terminal.devices[1].software.modules[0].build=build"
  -d "terminal.devices[1].software.modules[0].hash=hash"
  -d "terminal.devices[1].software.modules[0].prov=prov"
  -d "terminal.devices[1].software.modules[0].minorVersion=minorVersion"
  -d "terminal.devices[1].software.modules[0].majorVersion=majorVersion"
  -d "terminal.devices[1].software.modules[0].date=2020-11-11"
  -d "terminal.devices[1].software.modules[1].moduleType=FILE"
  -d "terminal.devices[1].software.modules[1].component.type=type"
  -d "terminal.devices[1].software.modules[1].component.version=version"
  -d "terminal.devices[1].software.modules[1].component.iss=iss"
  -d "terminal.devices[1].software.modules[1].component.expDate=2020-01-31"
  -d "terminal.devices[1].software.modules[1].component.effDate=2020-01-31"
  -d "terminal.devices[1].software.modules[1].component.ref=ref"
  -d "terminal.devices[1].software.modules[1].name=name"
  -d "terminal.devices[1].software.modules[1].version=version"
  -d "terminal.devices[1].software.modules[1].build=build"
  -d "terminal.devices[1].software.modules[1].hash=hash"
  -d "terminal.devices[1].software.modules[1].prov=prov"
  -d "terminal.devices[1].software.modules[1].minorVersion=minorVersion"
  -d "terminal.devices[1].software.modules[1].majorVersion=majorVersion"
  -d "terminal.devices[1].software.modules[1].component.ass=ass"
  -d "terminal.devices[1].software.modules[1].date=2020-11-11"
  -d "terminal.devices[1].properties[0].name=name"
  -d "terminal.devices[1].properties[0].value=value"
  -d "terminal.devices[1].properties[1].name=name2"
  -d "terminal.devices[1].properties[1].value=value2"
  -d "terminal.devices[1].additionalAttributes[devAAkey]=devAAValue"
  -d "terminal.devices[1].additionalAttributes[devAAkey2]=devAAValue2"
  -d "customParameters[MY_KEY2]=MY_VALUE2"

5.1.2. Device Data Response

The following fields reflect the possible response values returned for a Device Data request message.

Parameter name Description Required Regex

id

The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client.

Required

AN32
[a-zA-Z0-9]{1,32}

result.code

The unique code that indicates the result status of the request.
See Result Codes for more details.

Required

AN11
[0-9\.]{2,11}

result.description

A textual description explaining the result.code meaning. If a field validation exception occurs, this field will also indicate the name of the field or fields that failed validation.

Required

AN255
[\s\S]{0,255}

timestamp

The timestamp generated by the response in UTC.

Required

date
yyyy-MM-dd hh:mm:ss

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

resultDetails.*

A container for name-value pairs used for enriching the response with bank-specific response details.

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\s\S]{0,2048}

Example
{
  "id" : "e8f59d02a466f35a7ece785d3e137e50",
  "result": {
    "code" : "000.000.000",
    "description" : "Transaction succeeded",
    "authorizationId" : "783276"
  },
  "timestamp" : "2019-09-06 12:22:44"
}
Note
Optional fields will only be returned if the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

6. APM Token Decrypt Service

6.1. APM Token Decrypt

The APM (Alternative Payment Method) Decrypt service is used to decrypt payment tokens generated by alternative payment methods such as Apple Pay and Google Pay. The decrypted content of the token is returned in the response. This can be useful for systems where validation of the contents of the token is required before the financial leg of the transaction is attempted.

  • For Apple Pay token decrypt requests, use https://[hostname]:[port]/paymentsapi/opp/v1/apm/decrypt/applepay

  • For Google Pay token decrypt requests, use https://[hostname]:[port]/paymentsapi/opp/v1/apm/decrypt/googlepay

Note
The Payment service supports accepting an encrypted payment token and decrypting it as part of a normal Payment request. The response fields returned in this service call can be used to perform a pre-decrypted APM Payment request. See Alternative Card Data for more details on how to perform both either of these Payment requests using an APM.

6.1.1. APM Token Decrypt Request

The minimum requirements for sending a APM Token Decrypt message are listed here. To use this service, either an Apple Pay or Google Pay payment token must be supplied in the request. Only one APM token type should be supplied for any APM Token Decrypt Request sent to ConnectUP.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

applePay.paymentToken

The encrypted payment token provided by Apple.

Conditionally Required

ANS8192
[\s\S]{1,8192}

googlePay.paymentToken

The encrypted payment token provided by Google.

Conditionally Required

ANS8192
[\s\S]{1,8192}

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Required

ANS15
[\s\S]{1,15}

merchant.street

The street address of the merchant.

Optional

ANS23
[\s\S]{1,23}

merchant.city

The city of the merchant.

Optional

ANS13
[\s\S]{1,13}

merchant.country

The country of the merchant.

Optional

AN2
[A-Za-z]{2}

merchant.state

The county, state, or region of the merchant.

Optional

AN2
[a-zA-Z0-9]{1,2}

Example
Example using Apple Pay token
curl http://[hostname]:[port]/opp/v1/apm/decrypt/applepay -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "merchant.street=Century Avenue"
  -d "merchant.city=Cape Town"
  -d "merchant.country=ZA"
  -d "merchant.state=WC"
  -d "applePay.paymentToken= {
		\"version\": \"EC_v1\",
		\"data\": \"pthEHTJcEDAQ4MLi[...]Zw9edDA==\",
		\"signature\": \"MIAGCSqGSIb[...]fZWNjL==\",
		\"header\": {
			\"ephemeralPublicKey\": \"MFkwEwYHKoZIzj0[...]Fku50liog==\",
			\"publicKeyHash\": \"sGhAH2fo79Jdp[...]NbSc7wfmGNgDwcXpc=\",
			\"transactionId\": \"c5b71840e7fa9374d31d5b560dace7550f47\"
		}
	}"
Example using Google Pay token
curl http://[hostname]:[port]/opp/v1/apm/decrypt/googlepay -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "googlePay.paymentToken={
      \"signature\":\"MEYCIQCwmJ[...]RWgG8c\",
      \"intermediateSigningKey\":{
         \"signedKey\":\"{
            \"keyValue\":\"MFkwEwYHKo[...]LdekAQ\\u003d\\u003d\",
            \"keyExpiration\":\"1585761306143\"
         }\",
         \"signatures\":[\"MEYCIQDb+L[...]JHwEhF\"]
      },
      \"protocolVersion\":\"ECv2\",
      \"signedMessage\":\"{
            \"encryptedMessage\":\"mJVt1VLA[...]prXv3g\\u003d\",
            \"ephemeralPublicKey\":\"BK9KRS[...]Wyy9LU\\u003d\",
            \"tag\":\"KVHidXy9ur[...]g15Sjw\\u003d\"
      }\"
   }"

6.1.2. APM Token Decrypt Response

The following fields reflect the possible response values for the APM Token Decrypt service requests.

Parameter name Description Required Regex

card.numberType

Indicates if the Apple payment token card number was a PAN or DPAN (device PAN).

Required

PAN|DPAN

card.number

The Device Primary Account Number (DPAN).

Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Required

N4
(20|21)([0-9]{2})

currency

Indicates the currency present in the payment token (ISO 4217).

Required

A3
[A-Z]{3}

amount

Indicates the amount present in the payment token.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.

For example, for one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. For zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?

threeDSecure.verificationId

The Online Payment Cryptogram contained within the token.

Conditional

AN56
[0-9a-zA-Z/+=]{1,56}

threeDSecure.eci

An optional ECI indicator contained within the token.

Optional

N2
0[5|7]{1}

Example
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "50.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "card":{
        "number" : "6504840209544524",
        "expiryMonth" : "01",
        "expiryYear" : "2021",
        "numberType" : "DPAN",
    },
    "threeDSecure":{
        "verificationId": "1234ABCD"
        "eci" : "05"
    }
    "timestamp" : "2019-09-06 12:00:00"
}

7. Network Management Service

7.1. Network Management

The Network Management service performs and runs network management related operations.

For Network Management requests, use https://[hostname]:[port]/paymentsapi/opp/v1/nwrkmng

7.1.1. Network Management Request

The minimum requirements for sending a Network Management message are listed here.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

An HTTP header access-token for this request.
To be used with the root entityId field only.

Conditionally Required

ANS110
[\s\S]{0,110}

entityId

The entity associated with the request.
To be used with the HTTP Authorization header only.

Conditionally Required

AN32
[a-f0-9]{32}

infoCode

The code that defines the type of network management needed.

Required

SIGN_ON|SIGN_OFF|NEW_KEY|PW_CHANGE|SEC_ALERT|INIT_CUTOFF|ECHO_TEST|CUTOFF_DONE|DEV_AUTH||INIT_ALT_ROUTING|SPEC_INST|FILE_DL|FILE_STATUS|FILE_COMPLETION

settlementDate

The month and day for which financial totals are reconciled between the acquirer and the issuer.

Optional

N4
[0-9]{4}

pos.terminalId

The terminal identifier assigned by the acquirer.

Required

AN8
[a-zA-Z0-9_]{8}

pos.storeId

The store identifier assigned by the acquirer.

Optional

ANS15
[\s\S]{1,15}

pos.transactionSequenceNumber

Identifies the transaction on the device that initiated the transaction.

Optional

ANS35
[\s\S]{1,35}

pos.terminalOperator

Indicates who is operating the point-of-service. If not inferred by pos.entryMode or transactionCategory, CUSTOMER is used.

Optional

CUSTOMER|​
MERCHANT|​
ADMIN

pos.encryptedPin.ksn

Key serial number used to determine PIN key for online PIN. This field is required when a PIN was entered at the point-of-service, but it was not verified offline, and the DUKPT PIN encryption scheme is used. This field is encoded as a hex representation of the binary key serial number value.

Optional

AN2048
[a-fA-F0-9]{1,2048}

merchant.receivingInstitutionCode

A code identifying the financial institution that must receive a message. When present, this value is used to calculate the route for a message in upstream systems.

Required

N11
[0-9]{1,11}

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.

Optional

N11
[0-9]{1,11}

merchant.forwardingInstitutionCode

A code identifying the institution that forwards the transaction in an interchange system en route to the card issuer.

Optional

N11
[0-9]{1,11}

emvFileDownload.fileVersion

Free form field containing the file version information.

Optional

ANS99
[\s\S]{1,99}

emvFileDownload.blockNumber

Indicates the block number or offset of the current download.

Optional

ANS50
[\s\S]{1,50}

emvFileDownload.downloadIndicator

Indicates download status.

Optional

REQUIRED|NOT_REQUIRED|IN_PROGRESS|COMPLETED|ERROR|SUCCESSFUL

Example
curl http://[hostname]:[port]/opp/v1/nwrkmng -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "infoCode=107"
  -d "settlementDate=0522"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78123753"
  -d "pos.transactionSequenceNumber=66611234"
  -d "pos.terminalOperator=12345678"
  -d "pos.encryptedPin.ksn=FFFF12345612342000..."
  -d "merchant.receivingInstitutionCode=12345678901"
  -d "merchant.acquiringInstitutionCode=12345678901"
  -d "merchant.forwardingInstitutionCode=12345678901"

7.1.2. Network Management Response

The following fields reflect the possible response values returned for a Network Management request message.

Parameter name Description Required Regex

id

The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client.

Always

AN32
[a-zA-Z0-9]{1,32}

result.code

The unique code that indicates the result status of the request.
See Result Codes for more details.

Required

AN11
[0-9\.]{2,11}

result.description

A textual description explaining the result.code meaning. If a field validation exception occurs, this field will also indicate the name of the field or fields that failed validation.

Always

AN255
[\s\S]{0,255}

result.authorizationId

The code assigned by the authorizing institution indicating approval.

Optional

AN6
[a-zA-Z0-9]{1,6}

emvFileDownload

Contains information regarding EMV Filed Downloads which can be used to retrieve EMV CA Public Key data.

Conditional

ANS9999
[\s\S]{9999}

timestamp

The timestamp generated by the response in UTC.

Required

date
yyyy-MM-dd hh:mm:ss

Example
{
  "id" : "e8f59d02a466f35a7ece785d3e137e50",
  "result": {
    "code" : "000.000.000",
    "description" : "Transaction succeeded",
    "authorizationId" : "783276"
  },
  "timestamp" : "2019-09-06 12:22:44"
}
Note
Optional fields will only be returned if the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

7.1.3. EmvFileDownload

EmvFileDownload is compatible with the following message types:

ConnectUP supports sending EMV File Download data. All EMV File Download fields are optional.

Parameter name Description Required Regex

emvFileDownload_versionId

emvFileDownload_versionId_desc

Optional

emvFileDownload_versionId_regex

emvFileDownload_blockNumber

emvFileDownload_blockNumber_desc

Optional

emvFileDownload_blockNumber_regex

emvFileDownload_downloadIndicator

emvFileDownload_downloadIndicator_desc

Optional

emvFileDownload_downloadIndicator_regex

Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/nwrkmng
	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "infoCode=FILE_DL"
    -d "pos.terminalId=term_1aB"
    -d "pos.storeId=posStoreID10000"
    -d "merchant.receivingInstitutionCode=11111111111"
    -d "emvFileDownload.fileVersion=OldFile1.0"
Response
Parameter name Description Required Regex

emvFileDownload_versionId

emvFileDownload_versionId_desc

Optional

emvFileDownload_versionId_regex

emvFileDownload_blockNumber

emvFileDownload_blockNumber_desc

Optional

emvFileDownload_blockNumber_regex

emvFileDownload_downloadIndicator

emvFileDownload_downloadIndicator_desc

Optional

emvFileDownload_downloadIndicator_regex

emvFileDownload_caPkf

emvFileDownload_caPkf_desc

Optional

emvFileDownload_caPkf_regex

Sample Response Containing fleet response data
{
	"id" : "e8f59d02a466f35a7ece785d3e137e50",
	"tokenId" : "JYO7rdR5UjK61111",
	"amount" : "92.00",
	"currency" : "USD",
	"result": {
		"code" : "000.000.000",
		"description" : "Transaction succeeded",
		"authorizationId" : "783276"
	},
	"customParameters":{
		"CUSTOM_KEY1":"CUSTOM_VALUE1",
		"CUSTOM_KEY2":"CUSTOM_VALUE2"
	},
	"emvFileDownload":{
		"versionId":"NewFile1.1",
		"blockNumber":"1",
		"downloadIndicator":"IN_PROGRESS",
		"caPkf":"20251212,01,01,A000001000,02,AB9A23F8H32D5E327CFF;2024",
	},
	"timestamp" : "2019-09-06 12:22:44"
}

Appendix A: Format Element Descriptions

A.1. Format Explanation

Format element Description

A

Alphabetic characters, A through Z, and a through z

N

Numeric digits, 0 through 9

S

Special characters, that is other printable characters

AN

Alphabetic and numeric characters

AS

Alphabetic and special characters

NS

Numeric and special characters

ANS

Alphabetic, numeric, and special characters

YY

Year, 00 through 99

MM

Month, 01 through 12

DD

Day, 01 through 31

Appendix B: Result Code Explanation

B.1. Result Codes

Result codes are part of the response body’s JSON (field result) containing a code and a description explaining the code.

A result code has the format ddd.ddd.ddd, that is, 3 groups of 3-digit numbers. The codes are split into rough groups by the first number, then into more detailed sub-groups by the second number, then into the exact code by the third number.

Example:

800.100.153 means:

800: bank declined

100: it declined the authorization

153: it declined authorization because the CVV is wrong

The currently supported result codes are listed below.

Result Code Result Description Special Notes

000.000.000

Transaction succeeded

000.000.099

Transaction Succeeded (partial approval)

000.100.201

Account or Bank Details Incorrect

000.100.206

Revocation or Dispute

000.100.220

Fraudulent Transaction

000.200.000

Transaction pending

100.100.101

Invalid credit card, bank account number, or bank name

100.100.305

Invalid expiration date format

100.150.200

Registration does not exist

100.150.202

Registration is already deregistered

100.300.501

Invalid response ID

100.300.600

Invalid or missing user login

100.396.101

Cancelled by user

100.396.106

User did not agree to payment method terms

100.550.401

Invalid currency

100.800.501

Invalid country

200.100.501

Invalid or missing customer

200.100.603

Alternative payment method token (ApplePay/GooglePay) could not be decrypted Cryptographic configuration might be outdated.

200.200.106

Duplicate transaction. Please verify that the UUID is unique.

200.300.404

Invalid or missing parameter

300.100.100

Transaction declined (additional customer authentication required)

300.100.190

Transaction declined (Issuer Requires PIN [SCA])

300.100.191

Transaction declined (SCA exemption is invalid)

300.100.192

Transaction declined (additional customer authentication required)

500.100.401

Connector is unavailable (no processing possible)

600.100.100

Unexpected Integrator Error (Request could not be processed)

600.200.400

Unsupported Payment Type

600.200.500

Invalid payment data. You are not configured for this currency or sub-type (country or brand).

700.100.200

Non-matching reference amount

800.100.100

Transaction declined for unknown reason

800.100.151

Transaction declined (invalid card)

800.100.153

Transaction declined (invalid CVV)

800.100.154

Transaction declined (transaction marked as invalid)

800.100.155

Transaction declined (amount exceeds credit)

800.100.156

Transaction declined (format error)

800.100.157

Transaction declined (wrong expiry date)

800.100.159

Transaction declined (stolen card)

800.100.160

Transaction declined (card blocked)

800.100.161

Transaction declined (too many invalid tries)

800.100.162

Transaction declined (limit exceeded)

800.100.163

Transaction declined (maximum transaction frequency exceeded)

800.100.165

Transaction declined (card lost)

800.100.166

Transaction declined (incorrect personal identification number)

800.100.167

Transaction declined (referencing transaction does not match)

800.100.168

Transaction declined (restricted card)

800.100.170

Transaction declined (transaction not permitted)

800.100.174

Transaction declined (invalid amount)

800.100.178

Transaction declined (PIN entered incorrectly too many times)

800.100.190

Transaction declined (invalid configuration data)

800.100.199

Transaction declined (routing error)

800.100.402

CC/bank account holder not valid

800.900.303

No token created

800.800.800

The payment system is currently unavailable, please contact support in case this happens again.

900.100.300

Timeout, uncertain result

Send a Reversal to reverse the request

900.100.400

Timeout at the connectors/acquirer side

900.100.600

Connector/acquirer currently down

999.999.999

Undefined connector/acquirer error

Tip
For a categorized list of result codes, refer to the OPP Result Codes page.

B.2. HTTP Response Status Codes

The HTTP response status code are issued by the upstream server in response to a client request.

Tip
The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.
HTTP Status Code Description

200 OK

This is the standard response for a successful request. Check the result.code and result.description response fields for the reason the request succeeded.

400 Declined / Bad Request

This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed.

403 Auth Error / Forbidden

This means that the request contained valid data, but the server is refusing action. This usually means incorrect authentication information was provided. One or more of the authentication parameters are incorrect or not supplied. It is also returned if the user has been disabled on the system.

8. ConnectUP OpenAPI Specification

Current publication date: 2022-03-14

The ConnectUP OpenAPI specification(OAS) fully describes all available ConnectUP RESTful APIs. The specification is programming language agnostic and enables third-party users to interact, understand and develop against the ConnectUP API with minimal implementation logic. The specification adheres to OAS version 3.0.3 and is published in the YAML file format. The latest version of the specification may be downloaded from the link below.

9. Publication history

Current publication date: 2022-03-14

Version 1.x

Warning
Currently unsupported features subject to change

P2PE Service

  • Added the P2PE Service

Alternative Card Data

  • Added P2PE Cardholder Data input

VP2PE Service

  • Added the VP2PE Service

Version 1.24

availableBalance in DB response messages

  • Added support for balances.availableBalance and new field balances.approvedAmount in DB response messages.

Version 1.23

Presto P2PE support

  • Added support for Presto P2PE

CP Status Code

  • Added support for a statusCode parameter for CP messages.

Version 1.22

EMV File Download support

  • Added support for EMV File Download messages

Version 1.21

Basic Fuel Support

  • Added base support for fuel and fleet transactions

Version 1.20

Network Management Service

  • Added the Network Management Service

Version 1.19

De-tokenization Service

  • Added support for AES-256 encrypting de-tokenize response messages

Version 1.18

Payments and ICC Result Service

  • Added support for the following fields:

    • card.paymentIdentifier

    • paymentAccountReference

  • Added the following values to the standingInstruction.industryPractice field:

    • INCREMENTAL_AUTH

    • RESUBMISSION

    • REAUTHORIZATION

    • NO_SHOW

Version 1.17

Payments and ICC Result Service

  • Added support for the Google Pay APM

  • Added support for the following values to the pos.entryMode field to indicate that fallback from one PAN entry mode to another has occurred:

    • MAGSTRIPE_AS_FALLBACK

    • MAGSTRIPE_TO_MANUAL

    • CONTACTLESS_TO_ICC

    • CONTACTLESS_TO_MAGSTRIPE

  • Added the pos.fallbackReason field to indicate why fallback from one pos.entryMode to another has occurred

APM Token Decrypt Service

  • Added support for the Google Pay APM

Version 1.16

APM Token Decrypt Service

  • Added the APM Token Decrypt service that allows for the decryption and retrieval of fields within encrypted APM tokens

  • Added support for the Apple Pay APM

Version 1.15

Payments and ICC Result Service

  • Added support for the Apple Pay APM (Alternative Payment Method)

  • Added support for 3-D Secure authorization fields

Version 1.14

Payments and ICC Result Service

  • Added support for the pin-less debit routing indicator

  • Added support for indicating why a CVV value was not provided in a request

  • Added support for customer related fields:

    • customer.customerCode

    • customer.merchantReferenceNumber

  • Added support for merchant related fields:

    • merchant.taxId

  • Added support for billing-from and shipping-from address data: *` customer.from.`

    • billing.from.*

    • shipping.from.*

Version 1.13

Payments and ICC Result Service

  • Removed the requirement for standingInstruction.type=UNSCHEDULED for all CIT request messages

  • Added support for the reason field in reversal payment requests

Version 1.12

Payment Service

  • Added support to request messages to indicate if a transaction is part of a multiple-clearing sequence

  • Added support for ICC data in payment request and response messages

  • Added support for the ICC Result message

  • Added support for the customer.orderDate field

  • Expanded the width of field merchantOrderNumber to 25 characters

  • Updated card.accountType to support Stored Value card account types

  • Added support for the cashbackAmount field in request messages

  • Added support for the following new POS fields in request messages:

    • pos.cardDataInputCapability

    • pos.cardDataOutputCapability

    • pos.cardholderAuthenticationCapability

    • pos.cardholderAuthenticationMethod

    • pos.terminalOperator

    • pos.operatingEnvironment

    • pos.cardholderAuthenticationEntity

    • pos.cardholderPresent

    • pos.cardPresent

    • pos.cardCaptureCapability

    • pos.pinEntryCapability

    • pos.encryptedPin.data

    • pos.encryptedPin.ksn

    • pos.pinCaptureCapability

Balance Inquiry Service

  • Added the Balance Inquiry service

Stored-Value Service

  • Added the following stored-value services: stored-value card activation, stored-value card deactivation, stored-value card load

Version 1.11

Token Service

  • Added support for the customParameters[] field in request and response messages

Version 1.10

Payment Service

  • Added support for Level 2 merchantInvoiceId field in payment request messages

  • Added support for the following new fields in payment request messages:

    • shipping.street2

    • shipping.warehouse

    • shipping.customer.companyName

    • customer.companyName

  • Updated Level 3 cart.items[n].quantity field to support three decimal places

Version 1.9

Payment Service

  • Added support for the billPayment field in payment requests messages to indicate if a transaction is a bill payment

  • Removed support for the BP (Bill Payment), IN (Installment), and RC (Recurring) values in the transactionCategory field in payment request messages. Specifying these values will result in the request being rejected. Set the new billPayment field to true to indicate that the transaction is a bill payment. Continue using the CRENDENTIAL_ON_FILE pos.entryMode value in combination with the standingInstruction field for MIT/CIT functionality

  • Added support for resultDetails.retrievalReferenceNumber field in payment response messages

Version 1.8

Token Service

  • Added support for additional error response mappings

  • Added support for mapping error responses on unsuccessful de-tokenization calls

Version 1.7

Payment Service

  • Added support for the Authorization: Bearer <access-token> header and related entityId field

  • Added support for initiating a payment with a token

  • Added support for specifying a Soft/Dynamic Descriptor in payment request messages (see the updated description of the merchant.name field)

Token Service

  • Added tokenization and de-tokenization services

Version 1.6

Payments Service

  • Added support for specifying a convenience fee

Version 1.5

Payments Service

  • Clarified the description of the amount field in RV request and response messages

  • Added support for mapping pos.storeId in RV messages

  • Added support for the deferredPayment field in requests messages

  • Added support for additional merchant fields:

    • merchant.name

    • merchant.phone

    • merchant.postcode

    • merchant.submerchantId

    • merchant.receivingInstitutionCode

  • Added support for resultDetails.commercialCardIndicator and resultDetails.level3InterchangeEligible fields in response messages

  • Added support for raw host network response values resultDetails.AcquirerResponse and resultDetails.AcquirerAvsResponse fields in response messages

  • Added support for field pos.terminalType in requests messages

  • Added support for field card.accountType in requests messages

  • Added support for the debtRepayment field in requests messages

  • Added support for field partialApprovalAllowed in requests messages

  • Added support for standing instruction fields standingInstruction.type, standingInstruction.mode, and standingInstruction.source in requests to support Customer-Initiated Transactions (CIT) and Merchant-Initiated Transactions (MIT) functionality

  • Added support for value 'CREDENTIAL_ON_FILE' in field pos.entryMode

  • Added the resultDetails[] field to responses and added back support for the customParameters[] field in request messages

  • Added support for billing address and customer fields in requests messages

  • Added support for shipping address and customer fields in request messages

  • Added support for field transactionCategory in requests to support the identification of Card-Not-Present and Cardholder-Not-Present messages. This includes the Bill Payment transaction category

  • Added support for Level 2 and Level 3 (L2/L3) fields in requests messages

  • Added support for the result.cvvResponse field in responses to support Card Verification Value (CVV) functionality

  • Added support for the result.avsResponse field in responses to support Address Verification System (AVS) functionality

  • Added support for stand-alone CP requests (made field referencedPaymentId conditional)

  • Added support for pos.operatorId, pos.posId, and pos.transactionSequenceNumber in all request messages

Version 1.4

Payments Service

  • Removed support for customParameters[]

  • Minor inconsistencies have been fixed in the documentation

Version 1.3

Payments Service

  • Added support for merchant fields:

    • merchant.mcc

    • merchant.street

    • merchant.city

    • merchant.state

    • merchant.country

  • Added unofficial support for field pos.transactionSequenceNumber

  • Added unofficial support for new Payments API specific fields pos.operatorId and pos.posId

Version 1.2

Payments Service

  • Relaxed validation for referencedPaymentId parameter to allow for special characters and variable length

  • Relaxed validation for the pos.storeId parameter to allow for special characters

Version 1.1

Payments Service

  • Added support for PA and CP Messages

  • Added support for the customParameters[] field to enable passing Postilion-specific parameters to the Payments API

Version 1.0

Payments Service

  • Officially released v1.0 of the ConnectUP API Interface Specification along with the initial release of this product

Command Service

  • Officially released v1.0 of the ConnectUP API Interface Specification along with the initial release of this product. This service is documented in the User Guide.

Notices

ACI Worldwide
Offices in principal cities throughout the world.
www.aciworldwide.com
Americas +1 402 390 7600
Asia Pacific +65 6334 4843
Europe, Middle East, Africa +44 (0) 1923 816393

© Copyright ACI Worldwide, Inc. 2021
ACI, ACI Worldwide, ACI Payments, Inc., ACI Pay, Speedpay and all ACI product/solution names are trademarks or registered trademarks of ACI Worldwide, Inc., or one of its subsidiaries, in the United States, other countries or both. Other parties’ trademarks referenced are the property of their respective owners.