Open Payment Platform

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:

Construct the token themselves as described above.
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}

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}

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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| UNKNOWN
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
merchantTransactionId	The merchant-provided reference number. It must be unique for the merchant’s transactions.	Required	ANS255 [\s\S]{8,255}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false
deferredAuthorization	When this flag is set to true, it indicates that this is a Deferred Authorization transaction.	Optional	true\|false

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

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

merchantTransactionId

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

Required

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

deferredAuthorization

When this flag is set to true, it indicates that this is a Deferred Authorization transaction.

Optional

true|false

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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| UNKNOWN
pos.storeId	The store identifier assigned by the acquirer.	Required	ANS15 [\s\S]{1,15}
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
merchantTransactionId	The merchant-provided reference number. It must be unique for the merchant’s transactions.	Required	ANS255 [\s\S]{8,255}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false
deferredAuthorization	When this flag is set to true, it indicates that this is a Deferred Authorization transaction.	Optional	true\|false

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

amount

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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

pos.storeId

The store identifier assigned by the acquirer.

Required

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

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

merchantTransactionId

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

Required

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

deferredAuthorization

When this flag is set to true, it indicates that this is a Deferred Authorization transaction.

Optional

true|false

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.ledgerBalance	Indicates the ledger balance for the account.	Optional	N8.N4 [0-9]{1,8}(\.[0-9]{1,4})?
additionalAmounts.approvedAmount	Indicates the approved amount for the account.	Optional	N8.N4 [0-9]{1,8}(\.[0-9]{1,4})?

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.ledgerBalance

Indicates the ledger balance for the account.

Optional

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

additionalAmounts.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",
        "ledgerBalance": "110.00"
    },
    "additionalAmounts"
    {
         "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

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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| UNKNOWN
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
merchantTransactionId	The merchant-provided reference number. It must be unique for the merchant’s transactions.	Required	ANS255 [\s\S]{8,255}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

merchantTransactionId

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

Required

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| UNKNOWN
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
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}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false
deferredAuthorization	When this flag is set to true, it indicates that this is a Deferred Authorization transaction.	Optional	true\|false

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

amount

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

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}

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

deferredAuthorization

When this flag is set to true, it indicates that this is a Deferred Authorization transaction.

Optional

true|false

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"
	-d "memoPost=true"
	-d "deferredAuthorization=true"

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}
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
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}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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}

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

paymentType

The payment type indicator.

Required

referencedPaymentId

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

Conditional

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

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}
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
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}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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

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.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

paymentType

The payment type indicator.

Required

referencedPaymentId

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

Conditional

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

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

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}
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
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}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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}

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

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}

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

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}

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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| 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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

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})?
balances.ledgerBalance	Indicates the ledger balance for the account.	Optional	N8.N4 [0-9]{1,8}(\.[0-9]{1,4})?

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.ledgerBalance

Indicates the ledger 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",
        "ledgerBalance": "110.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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| 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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM

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.

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

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| 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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM

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.

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

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| 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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM

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.

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

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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 Adjustment

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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| UNKNOWN
pos.storeId	The store identifier assigned by the acquirer.	Required	ANS15 [\s\S]{1,15}
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
merchantTransactionId	The merchant-provided reference number. It must be unique for the merchant’s transactions.	Required	ANS255 [\s\S]{8,255}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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

amount

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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

pos.storeId

The store identifier assigned by the acquirer.

Required

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

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

merchantTransactionId

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

Required

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

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

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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| UNKNOWN
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
merchantTransactionId	The merchant-provided reference number. It must be unique for the merchant’s transactions.	Required	ANS255 [\s\S]{8,255}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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

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.

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

merchantTransactionId

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

Required

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

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

Please note this payment operation has been deprecated and replaced by: Credit Adjustment. The Refund payment operation will remain present, but will be considered inactive and unsupported until it is re-purposed for any future endeavors.

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

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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| UNKNOWN
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
merchantTransactionId	The merchant-provided reference number. It must be unique for the merchant’s transactions.	Required	ANS255 [\s\S]{8,255}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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

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.

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

merchantTransactionId

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

Required

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

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.1.15. Card Verification

This payment operation is used to verify the details of a user’s card.

A Card Verification 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 CV 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}
paymentType	The payment type indicator.	Required	CV
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.	Required	N4 [0-9]{3,4}
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| UNKNOWN
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
merchantTransactionId	The merchant-provided reference number. It must be unique for the merchant’s transactions.	Required	ANS255 [\s\S]{8,255}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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

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.

Required

N4
[0-9]{3,4}

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

merchantTransactionId

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

Required

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

Example

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=CV"
  -d "card.number=4444444444444448"
  -d "card.cvv=123"
  -d "card.expiryMonth=10"
  -d "card.expiryYear=2025"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

2.1.16. Credit Adjustment

The Credit Adjustment is a payment operation issued towards the correction of a transaction. This adjustment credits the customer’s account.

A Credit 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 CA message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.

Parameter name Description Required Regex

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	CA
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})
card.track1Data	The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813.	Optional	[\s\S]{0,76}
serviceRestrictionCode.area	The area of usage and whether the card has additional read facilities.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	INT_CARD\| INT_CARD_IC_FACILITIES\| NAT_USE_ONLY\| NAT_USE_ONLY_IC_FACILITIES\| TEST_CARD
serviceRestrictionCode.authorization	The authorization processing requirements for this card.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	NORMAL_AUTH\| ONLINE_AUTH_MANDATORY\| ONLINE_AUTH_GEN_MANDATORY
serviceRestrictionCode.range	The range of services available and PIN requirements.	Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.	PIN_REQUIRED\| NO_RESTRICTIONS\| GOODS_AND_SERVICES_ONLY\| PIN_REQUIRED_ATM\| PIN_REQUIRED_GOODS_AND_SERVICES_POS_ATM\| PIN_REQUIRED_PIN_PAD_PRESENT\| PIN_REQUIRED_PIN_PAD_PRESENT_GOODS_AND_SERVICES_POS_ATM
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\| MAGSTRIPE_CVV_UNRELIABLE\| BARCODE\| OCR\| UNKNOWN
pos.terminalRestrictions	The field indicates specific rules or limitations applied to a terminal.	Optional	NONE\| CHIP_BASED\| HOST_BASED\| BOTH
merchantTransactionId	The merchant-provided reference number. It must be unique for the merchant’s transactions.	Required	ANS255 [\s\S]{8,255}
memoPost	When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.	Optional	true\|false

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

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.

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})

card.track1Data

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

Optional

[\s\S]{0,76}

serviceRestrictionCode.area

The area of usage and whether the card has additional read facilities.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

INT_CARD|
INT_CARD_IC_FACILITIES|
NAT_USE_ONLY|
NAT_USE_ONLY_IC_FACILITIES|
TEST_CARD

serviceRestrictionCode.authorization

The authorization processing requirements for this card.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

NORMAL_AUTH|
ONLINE_AUTH_MANDATORY|
ONLINE_AUTH_GEN_MANDATORY

serviceRestrictionCode.range

The range of services available and PIN requirements.

Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present.

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

pos.terminalRestrictions

The field indicates specific rules or limitations applied to a terminal.

Optional

NONE|
CHIP_BASED|
HOST_BASED|
BOTH

merchantTransactionId

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

Required

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

memoPost

When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes.

Optional

true|false

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=CA"
  -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:

Pre-Authorization Request
Debit Request
Credit Request
Capture Notification
Reversal
Reversal Request
Card Verification
Balance Inquiry
Credit Adjustment
Stored-Value Activate
Stored-Value Deactivate
Stored-Value Load

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}
pos.localDateTime	The local date and time at which the transaction took place. For linked transactions, this field indicates the local time set by the initiator of the first message in the chain. If this field has not been set then the current local date and time is used. The format of the parameter is in the form of MM-dd HH:mm:ss.	Optional	(0[1-9]\|1[0-2])-(0[1-9]\|1[0-9]\|2[0-9]\|3[0-1]) ([0-1][0-9]\|2[0-3]):([0-5][0-9]):([0-5][0-9])

Parameter name

Description

Required

Regex

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

resultDetails.AcquirerResponse

The raw host network response code.

Conditional

resultDetails.AcquirerAvsResponse

The raw host network AVS response code.

Conditional

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

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Conditional

amount

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}

pos.localDateTime

The local date and time at which the transaction took place. For linked transactions, this field indicates the local time set by the initiator of the first message in the chain. If this field has not been set then the current local date and time is used. The format of the parameter is in the form of MM-dd HH:mm:ss.

Optional

(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]) ([0-1][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])

Example

{
	"id" : "e8f59d02a466f35a7ece785d3e137e50",
	"tokenId" : "JYO7rdR5UjK61111",
	"amount" : "92.00",
	"currency" : "USD",
	"pos":{"localDateTime":"08-30 10:21:29"}
	"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:

Pre-Authorization Request
Debit Request
Debit adjustment
Capture Notification

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 (ECI) is a value used to indicate the level of authentication that occurred during the payment process. The ECI value can vary depending on the card network and payment method utilized.+ Possible values are: 00 - Non 3-D Secure Transaction (MasterCard) 01 - Attempted Authentication Transaction (MasterCard) 02 - Fully Authenticated Transaction (MasterCard) 05 - Fully Authenticated Transaction (Visa, Amex, JCB, Diners) 06 - Attempted Authentication Transaction (Visa, Amex, JCB, Diners) 07 - Non 3-D Secure Transaction (Visa, Amex, JCB, Diners)	Required	N2 0[0\|1\|2\|6\|5\|7]{1}
threeDSecure.dsTransactionId	The dsTransactionId field represents the unique transaction identifier assigned by the Directory Server (DS). It is used to identify a single transaction within the 3-D Secure (3DS) authentication process.	Conditional	ANS36 [\s\S]{1,36}
threeDSecure.version	The version field indicates the specific version of the 3-D Secure protocol that is being used for authentication during the transaction. Only version 2 is supported. For example, valid version values could include "2", "2.0", "2.1", "2.1.1", etc., representing different iterations of the 3-D Secure version 2 protocol.	Conditional	ANS5 [2].?[0-9]?.?[0-9]?{1,5}
threeDSecure.xid	The XID (Unique Transaction Identifier) represents the unique identifier generated by the 3-D Secure provider. It is a Base64 encoded string. It should be included, if available, in the payments request to provide additional transaction identification.	Conditional	AN64 (Base64 encoded) [0-9a-zA-Z/+=]{64}
threeDSecure.verificationId	The VerificationID field contains the base64 encoded: Cardholder Authentication Verification Value (CAVV) Authentication Verification Value (AVV) Universal Cardholder Authentication (UCAF) Field (MasterCard) This field is mandatory if a third-party MPI (merchant plug-in) performed the 3d Secure authentication.	Conditional	AN28 (Base64 encoded)+ [0-9a-zA-Z/+=]{1,28}
threeDSecure.ucafCollectionIndicator	The ucafCollectionIndicator field represents the MasterCard UCAF Collection Indicator. This field describes the UCAF collection status. If no UCAF Collection Indicator value is provided, a derived value will be set based on the supplied ECI (Electronic commerce indicator) value. Possible values are: 0 - No Authentication: UCAF data collection is not supported at the merchant. 1 - Attempted Authentication: UCAF data collection is supported by the merchant, but was unable to complete the authentication. 2 - Full Authentication: UCAF data collection is supported by the merchant and the UCAF data was populated. 3 - Static Authentication: UCAF data collection is supported by the merchant and UCAF data is present as the Mastercard assigned Static Accountholder Authentication Value (AAV). 4 - Insights Authentication: Merchant has chosen to share authentication data within authorization and UCAF data is present as the Insights AAV for Mastercard Identity Check. 5 - Issuer Risk Based Decisioning. 6 - Merchant Risk Based Decisioning. 7 - Partial shipment or recurring payment (Liability will depend on the original UCAF values provided).	Optional	N1 [0-7]{1}
threeDSecure.authenticationMethod	The authenticationMethod field represents the specific method or approach used for 3-D Secure authentication during a transaction. It provides information about how the cardholder was authenticated. 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	The exemptionFlag field indicates whether an exemption from 3-D Secure authentication has been applied to the transaction. It provides information about whether the transaction qualifies for an exemption based on specific criteria defined by regulatory requirements or card network rules. 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}
threeDSecure.tavv	The Token Authentication Verification Value (TAVV). This value is associated with 3-D Secure (3DS) validation for token-based card-on-file and E-Commerce transactions.	Conditional	AN28 (Base64 encoded) [0-9a-zA-Z/+=]{1,28}

Parameter name

Description

Required

Regex

threeDSecure.eci

The Electronic Commerce Indicator (ECI) is a value used to indicate the level of authentication that occurred during the payment process. The ECI value can vary depending on the card network and payment method utilized.+
Possible values are:
00 - Non 3-D Secure Transaction (MasterCard)
01 - Attempted Authentication Transaction (MasterCard)
02 - Fully Authenticated Transaction (MasterCard)
05 - Fully Authenticated Transaction (Visa, Amex, JCB, Diners)
06 - Attempted Authentication Transaction (Visa, Amex, JCB, Diners)
07 - Non 3-D Secure Transaction (Visa, Amex, JCB, Diners)

Required

N2
0[0|1|2|6|5|7]{1}

threeDSecure.dsTransactionId

The dsTransactionId field represents the unique transaction identifier assigned by the Directory Server (DS). It is used to identify a single transaction within the 3-D Secure (3DS) authentication process.

Conditional

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

threeDSecure.version

The version field indicates the specific version of the 3-D Secure protocol that is being used for authentication during the transaction. Only version 2 is supported. For example, valid version values could include "2", "2.0", "2.1", "2.1.1", etc., representing different iterations of the 3-D Secure version 2 protocol.

Conditional

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

threeDSecure.xid

The XID (Unique Transaction Identifier) represents the unique identifier generated by the 3-D Secure provider. It is a Base64 encoded string. It should be included, if available, in the payments request to provide additional transaction identification.

Conditional

AN64 (Base64 encoded)
[0-9a-zA-Z/+=]{64}

threeDSecure.verificationId

The VerificationID field contains the base64 encoded:
Cardholder Authentication Verification Value (CAVV) Authentication Verification Value (AVV)
Universal Cardholder Authentication (UCAF) Field (MasterCard)
This field is mandatory if a third-party MPI (merchant plug-in) performed the 3d Secure authentication.

Conditional

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

threeDSecure.ucafCollectionIndicator

The ucafCollectionIndicator field represents the MasterCard UCAF Collection Indicator. This field describes the UCAF collection status. If no UCAF Collection Indicator value is provided, a derived value will be set based on the supplied ECI (Electronic commerce indicator) value.

Possible values are:
0 - No Authentication: UCAF data collection is not supported at the merchant.
1 - Attempted Authentication: UCAF data collection is supported by the merchant, but was unable to complete the authentication. 2 - Full Authentication: UCAF data collection is supported by the merchant and the UCAF data was populated.
3 - Static Authentication: UCAF data collection is supported by the merchant and UCAF data is present as the Mastercard assigned Static Accountholder Authentication Value (AAV).
4 - Insights Authentication: Merchant has chosen to share authentication data within authorization and UCAF data is present as the Insights AAV for Mastercard Identity Check. 5 - Issuer Risk Based Decisioning. 6 - Merchant Risk Based Decisioning. 7 - Partial shipment or recurring payment (Liability will depend on the original UCAF values provided).

Optional

N1
[0-7]{1}

threeDSecure.authenticationMethod

The authenticationMethod field represents the specific method or approach used for 3-D Secure authentication during a transaction. It provides information about how the cardholder was authenticated.

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

The exemptionFlag field indicates whether an exemption from 3-D Secure authentication has been applied to the transaction. It provides information about whether the transaction qualifies for an exemption based on specific criteria defined by regulatory requirements or card network rules.

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}

threeDSecure.tavv

The Token Authentication Verification Value (TAVV). This value is associated with 3-D Secure (3DS) validation for token-based card-on-file and E-Commerce transactions.

Conditional

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

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.ucafCollectionIndicator=3"
   -d "threeDSecure.eci=05"
   -d "threeDSecure.dsTransactionId=c5b808e7-1de1-4069-a17b-f70d3b3b1645"
   -d "threeDSecure.version=2.0.0"
   -d "threeDSecure.authenticationMethod=0"
   -d "threeDSecure.tavv=c2FtZSBhcyBvdGhlciB2YWx1ZXM="

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

Parameter name

Description

Required

Regex

threeDSecure.result

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

Optional

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Credit Adjustment

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\| CHECK_MONEY_MARKET\| CREDIT\| CREDIT_LINE_OF_CREDIT\| CREDIT_INSTALLMENT_LOAN\| CREDIT_MORTGAGE_LOAN\| CREDIT_HOME_EQUITY_LOAN\| CREDIT_COMMERCIAL_LOAN\| UNIVERSAL\| UINVESTMENT\| UINVESTMENT_STOCK_OR_BOND\| UINVESTMENT_RETIREMENT_ACCOUNT\| UINVESTMENT_REVOLVING_LOAN_ACCOUNT\| SAVINGS\| SAVINGS_MONEY_MARKET\| SAVINGS_CERTIFICATE_OF_DEPOSIT\| ELECTRONIC_PURSE_DEFAULT\| EBT_CASH_BENEFIT\| EBT_FOOD_STAMP\| STORED_VALUE\| STORED_VALUE_SINGLE_DEPOSIT_SINGLE_USE\| STORED_VALUE_SINGLE_DEPOSIT_MULTI_USE\| STORED_VALUE_MULTI_DEPOSIT_MULTI_USE

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

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. To Account Type

To Account Type is compatible with the following message types:

Capture Notification

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

Parameter name	Description	Required	Regex
card.toAccountType	A value indicating the type of the to account affected by the transaction. If no value is provided, the DEFAULT account type is used.	Optional	DEFAULT\| CHECK\| CHECK_MONEY_MARKET\| CREDIT\| CREDIT_LINE_OF_CREDIT\| CREDIT_INSTALLMENT_LOAN\| CREDIT_MORTGAGE_LOAN\| CREDIT_HOME_EQUITY_LOAN\| CREDIT_COMMERCIAL_LOAN\| UNIVERSAL\| UINVESTMENT\| UINVESTMENT_STOCK_OR_BOND\| UINVESTMENT_RETIREMENT_ACCOUNT\| UINVESTMENT_REVOLVING_LOAN_ACCOUNT\| SAVINGS\| SAVINGS_MONEY_MARKET\| SAVINGS_CERTIFICATE_OF_DEPOSIT\| ELECTRONIC_PURSE_DEFAULT\| EBT_CASH_BENEFIT\| EBT_FOOD_STAMP\| STORED_VALUE\| STORED_VALUE_SINGLE_DEPOSIT_SINGLE_USE\| STORED_VALUE_SINGLE_DEPOSIT_MULTI_USE\| STORED_VALUE_MULTI_DEPOSIT_MULTI_USE

Parameter name

Description

Required

Regex

card.toAccountType

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

Optional

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.toAccountType=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.4. Additional POS Data

Additional POS Data is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Credit Adjustment

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 POS - Point of Sale ATM - ATM HOME - Home terminal ECR - Electronic cash register DIAL - Dial terminal TRAVELERS_CHECK - Travelers check machine FUEL - Fuel machine SCRIP - Scrip machine COUPON - Coupon machine TICKET - Ticket machine POINT_OF_BANKING - Point-of-banking terminal TELLER - Teller FRANCHISE_TELLER - Franchise teller PERSONAL_BANKING - Personal banking PUBLIC_UTILITY - Public utility VENDING - Vending SELF_SERVICE - Self-service AUTHORIZATION - Authorization PAYMENT - Payment VRU - Voice Recognition Unit SMART_PHONE - Smart Phone INTERACTIVE_TELEVISION - Interactive television PERSONAL_DIGITAL_ASSISTANT - Personal digital assistant SCREEN_PHONE - Screen phone MOBILE_POS - Mobile Point of Sale ECOM - E-commerce (no encryption, no authentication) ECOM_SET_NO_CRDHLDR_AUTH - E-commerce (SET/3-D Secure encryption, no cardholder authentication) ECOM_SET_CRDHLDR_AUTH - E-commerce (SET/3-D Secure encryption, cardholder authentication) ECOM_SET_CHIP_NO_CRDHLDR_AUTH - E-commerce (SET encryption, chip cryptogram, no cardholder authentication) ECOM_SET_CHIP_CRDHLDR_AUTH - E-commerce (SET encryption, chip cryptogram, cardholder authentication) ECOM_SECURE_NO_CRDHLDR_AUTH - E-commerce (secure channel, no cardholder authentication) ECOM_SECURE_CHIP_NO_CRDHLDR_AUTH - E-commerce (secure channel, chip cryptogram , cardholder authentication)	Optional	ADMIN\| POS\| ATM\| HOME\| ECR\| DIAL\| TRAVELLERS_CHECK\| FUEL\| SCRIP\| COUPON\| TICKET\| POINT_OF_BANKING\| TELLER\| FRANCHISE_TELLER\| PERSONAL_BANKING\| PUBLIC_UTILITY\| VENDING\| SELF_SERVICE\| AUTHORIZATION\| PAYMENT\| VRU\| SMART_PHONE\| INTERACTIVE_TELEVISION\| PERSONAL_DIGITAL_ASSISTANT\| SCREEN_PHONE\| BUSINESS_BANKING\| MOBILE_POS\| ECOM\| ECOM_SET_NO_CRDHLDR_AUTH\| ECOM_SET_CRDHLDR_AUTH\| ECOM_SET_CHIP_NO_CRDHLDR_AUTH\| ECOM_SET_CHIP_CRDHLDR_AUTH\| ECOM_SECURE_NO_CRDHLDR_AUTH\| ECOM_SECURE_CHIP_NO_CRDHLDR_AUTH
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}

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
POS - Point of Sale
ATM - ATM
HOME - Home terminal
ECR - Electronic cash register
DIAL - Dial terminal
TRAVELERS_CHECK - Travelers check machine
FUEL - Fuel machine
SCRIP - Scrip machine
COUPON - Coupon machine
TICKET - Ticket machine
POINT_OF_BANKING - Point-of-banking terminal
TELLER - Teller
FRANCHISE_TELLER - Franchise teller
PERSONAL_BANKING - Personal banking
PUBLIC_UTILITY - Public utility
VENDING - Vending
SELF_SERVICE - Self-service
AUTHORIZATION - Authorization
PAYMENT - Payment
VRU - Voice Recognition Unit
SMART_PHONE - Smart Phone
INTERACTIVE_TELEVISION - Interactive television
PERSONAL_DIGITAL_ASSISTANT - Personal digital assistant
SCREEN_PHONE - Screen phone
MOBILE_POS - Mobile Point of Sale
ECOM - E-commerce (no encryption, no authentication)
ECOM_SET_NO_CRDHLDR_AUTH - E-commerce (SET/3-D Secure encryption, no cardholder authentication)
ECOM_SET_CRDHLDR_AUTH - E-commerce (SET/3-D Secure encryption, cardholder authentication)
ECOM_SET_CHIP_NO_CRDHLDR_AUTH - E-commerce (SET encryption, chip cryptogram, no cardholder authentication)
ECOM_SET_CHIP_CRDHLDR_AUTH - E-commerce (SET encryption, chip cryptogram, cardholder authentication)
ECOM_SECURE_NO_CRDHLDR_AUTH - E-commerce (secure channel, no cardholder authentication)
ECOM_SECURE_CHIP_NO_CRDHLDR_AUTH - E-commerce (secure channel, chip cryptogram , cardholder authentication)

Optional

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.5. 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 - Data visible on the card
Magnetic Stripe Data - Data encoded in the card magnetic stripe
ICC Data - Data stored within the card EMV chip
Token Card Data - A token representing the card
Apple Pay Data - An Apple Pay encrypted payment token representing the card
Google Pay Data - A Google Pay encrypted payment token representing or containing the card data
P2PE Cardholder Data - Point-to-point encrypted (P2PE) cardholder data
Payment Identifier - A payment identifier used when PAN or Track2Data are not appropriate

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Credit Adjustment

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

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Credit Adjustment

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

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Credit Adjustment

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	ICC\| ICC_CVV_UNRELIABLE\| CONTACTLESS_TO_ICC\| NFC_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}

Parameter name

Description

Required

Regex

pos.entryMode

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

Required

ICC|
ICC_CVV_UNRELIABLE|
CONTACTLESS_TO_ICC|
NFC_ICC|

pos.iccDataRequest

Required

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

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Balance Inquiry
Credit Adjustment

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

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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

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}

paymentBrand

The payment brand used to identify alternative payment method transactions.

Required

APPLEPAY

currency

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

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 the threeDSecure.tavv field instead.	Conditional	AN56 (Base64 encoded)+ [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}
threeDSecure.tavv	The Token Authentication Verification Value (TAVV). This value is associated with 3-D Secure (3DS) validation for token-based card-on-file and E-Commerce transactions.	Conditional	AN28 (Base64 encoded) [0-9a-zA-Z/+=]{1,28}

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

Required

A3
[A-Z]{3}

amount

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 the threeDSecure.tavv field instead.

Conditional

AN56 (Base64 encoded)+ [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}

threeDSecure.tavv

The Token Authentication Verification Value (TAVV). This value is associated with 3-D Secure (3DS) validation for token-based card-on-file and E-Commerce transactions.

Conditional

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

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"
	-d "threeDSecure.tavv=c2FtZSBhcyBvdGhlciB2YWx1ZXM="

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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}

Parameter name

Description

Required

Regex

paymentBrand

The payment brand used to identify alternative payment method transactions.

Required

GOOGLEPAY

currency

Required

A3
[A-Z]{3}

amount

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 XID (Unique Transaction Identifier) represents the unique identifier generated by the 3-D Secure provider. It is a Base64 encoded string. It should be included, if available, in the payments request to provide additional transaction identification. This must be provided, if available.	Conditional	AN64 (Base64 encoded) [0-9a-zA-Z/+=]{64}
threeDSecure.verificationId	The VerificationID field contains the base64 encoded: Cardholder Authentication Verification Value (CAVV) Authentication Verification Value (AVV) Universal Cardholder Authentication (UCAF) Field (MasterCard) This field is mandatory if a third-party MPI (merchant plug-in) performed the 3d Secure authentication. This must be provided, if available.	Conditional	AN28 (Base64 encoded)+ [0-9a-zA-Z/+=]{1,28}
threeDSecure.eci	The Electronic Commerce Indicator (ECI) is a value used to indicate the level of authentication that occurred during the payment process. The ECI value can vary depending on the card network and payment method utilized.+ Possible values are: 00 - Non 3-D Secure Transaction (MasterCard) 01 - Attempted Authentication Transaction (MasterCard) 02 - Fully Authenticated Transaction (MasterCard) 05 - Fully Authenticated Transaction (Visa, Amex, JCB, Diners) 06 - Attempted Authentication Transaction (Visa, Amex, JCB, Diners) 07 - Non 3-D Secure Transaction (Visa, Amex, JCB, Diners) This must be provided, if available.	Conditional	N2 0[0\|1\|2\|6\|5\|7]{1}
threeDSecure.tavv	The Token Authentication Verification Value (TAVV). This value is associated with 3-D Secure (3DS) validation for token-based card-on-file and E-Commerce transactions. This must be provided, if available.	Conditional	AN28 (Base64 encoded) [0-9a-zA-Z/+=]{1,28}

Parameter name

Description

Required

Regex

paymentBrand

The payment brand used to identify alternative payment method transactions.

Required

GOOGLEPAY

currency

Required

A3
[A-Z]{3}

amount

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

Conditional

AN64 (Base64 encoded)
[0-9a-zA-Z/+=]{64}

threeDSecure.verificationId

Conditional

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

threeDSecure.eci

Conditional

N2
0[0|1|2|6|5|7]{1}

threeDSecure.tavv

The Token Authentication Verification Value (TAVV). This value is associated with 3-D Secure (3DS) validation for token-based card-on-file and E-Commerce transactions. This must be provided, if available.

Conditional

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

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"
   -d "threeDSecure.tavv=c2FtZSBhcyBvdGhlciB2YWx1ZXM="

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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.	Optional	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.	Optional	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.	Optional	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.	Optional	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).	Optional	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}

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.

Optional

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.

Optional

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.

Optional

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.

Optional

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).

Optional

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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}

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.6. Card Verification Value / Card ID (CVV/CID)

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

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Credit Adjustment

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}

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}

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.7. CVV2 Availability

CVV2 Availability is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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

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.8. Encrypted Pin

Encrypted Pin is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Credit Adjustment

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}

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.9. Alternative Currency

Alternative Currency is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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}

Parameter name

Description

Required

Regex

amount

Required

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

currency

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.10. Address Verification System

Address Verification System is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Capture Notification

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}

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.11. Billing Contact

Billing Contact is compatible with the following message types:

Pre-Authorization Request
Capture Notification

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.12. Bill Payments

Bill Payments is compatible with the following message types:

Pre-Authorization Request
Debit Request
Capture Notification

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.mcc

Merchant Category Code (MCC) is used to classify the business by the type of goods or services it provides.

Required

N4
[0-9]{4}

merchant.street

The street address and/or name 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

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

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.mcc=1234"
 	-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.13. Cashback

Cashback is compatible with the following message types:

Pre-Authorization Request
Debit Request
Capture Notification

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

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.

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.14. Convenience Fee

Convenience Fee is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Credit Adjustment

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

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.

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.15. Custom Parameters

Custom Parameters is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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

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.16. Debt Repayment

Debt Repayment is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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.17. Deferred Authorization

Compatible with the following message types:

Pre-Authorization Request
Debit Request
Capture Notification

To flag the transaction as Deferred Authorization, add the following parameter to your payment message.

Note	If `deferredAuthorization` is set to false, the parameter will have no effect on the payment.

Parameter Name

Description

Required

Regex

deferredAuthorization

When this flag is set to true, it indicates that this is a Deferred Authorization transaction.

Required

true|false

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 "deferredAuthorization=true"

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

2.3.18. Deferred Payment

Deferred Payment is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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.19. Incremental Authorizations

Compatible with the following message types:

Pre-Authorization Request

To declare a PA transaction as Incremental Auth, add the following parameters to your payment message. This includes the referencedPaymentId field to link an Incremental Auth to its predecessor in the incremental authorization chain/sequence.

Parameter Name

Description

Required

Regex

incrementalAuth.identifier

When this flag is set to true, it indicates that this is an Incremental Authorization transaction. Also used in the identification of the Partial or Full Reversal of an Incremental Authorization sequence/chain.

Required

true|false

incrementalAuth.totalAuthorizedAmount

The total authorized/hold amount requested for the entire sequence/chain.

Required

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

Example

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "amount=30.00"
  -d "currency=USD"
  -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"
  -d "referencedPaymentId=1b8cd7b6c81c9883e8926f04985fa7b5"
  -d "incrementalAuth.identifier=true"
  -d "incrementalAuth.totalAuthorizedAmount=80.00"

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

2.3.20. Incremental Authorization Partial Reversal

Compatible with the following message types:

Reversal
Reversal Request

To partially reverse an incremental authorization transaction, add the following parameters to your payment message.

Parameter Name

Description

Required

Regex

incrementalAuth.identifier

Required

true|false

incrementalAuth.totalAuthorizedAmount

The total authorized/hold amount requested for the entire sequence/chain.

Required

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

incrementalAuth.partialReversalReplacementAmount

Associated with a partial reversal of an incremental authorization sequence/chain and contains the corrected, actual amount of the customer’s transaction, in the currency of the transaction.

Required

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

Example

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=RV"
  -d "amount=10.00"
  -d "currency=USD"
  -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 "referencedPaymentId=1b8cd7b6c81c9883e8926f04985fa7b5"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "incrementalAuth.identifier=true"
  -d "incrementalAuth.partialReversalReplacementAmount=90.00"
  -d "incrementalAuth.totalAuthorizedAmount=100.00"

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

2.3.21. Incremental Authorization Full Reversal

Compatible with the following message types:

Reversal
Reversal Request

To fully reverse an incremental authorization sequence/chain, add the following parameters to your payment message.

Parameter Name

Description

Required

Regex

incrementalAuth.identifier

Required

true|false

incrementalAuth.totalAuthorizedAmount

The total authorized/hold amount requested for the entire sequence/chain.

Required

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

Example

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=RV"
  -d "amount=100.00"
  -d "currency=USD"
  -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 "referencedPaymentId=1b8cd7b6c81c9883e8926f04985fa7b5"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "incrementalAuth.identifier=true"
  -d "incrementalAuth.totalAuthorizedAmount=100.00"

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

2.3.22. Delayed Charges

Delayed Charges is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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.23. Fallback

Fallback is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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

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.24. Level 2 and Level 3 Data (L2/L3)

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

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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}

merchant.streetAddress

A street address associated with the merchant or card acceptor.

Optional

ANS48 [\s\S]{1,48}

merchant.countrySubDivisionCode

A state or province code for the retailer associated with the merchant or card acceptor.

Optional

ANS3 [a-zA-Z0-9]{3}

merchant.url

A website address for the retailer associated with the merchant or card acceptor. This field should be present for e-commerce transactions if available.

Optional

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

merchant.taxTreatment

A customer service phone number for the retailer associated with the merchant or card acceptor.

Optional

ANS16 [\s\S]{1,16}

merchant.additionalContactInformation

May contain additional information, such as secondary phone numbers, customer service operation hours, and contact name.

Optional

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

merchant.partnerIdCode

A partner ID established between the merchant or card acceptor and the issuer.

Optional

ANS6 [\s\S]{1,6}

merchant.serviceLocationCityName

The city of the location of the physical interaction with the customer.

Optional

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

merchant.serviceLocationCountrySubdivisionCode

The state or province of the location of the physical interaction with the customer.

Optional

ANS3 [a-zA-Z0-9]{2,3}

merchant.serviceLocationCountryCode

The country code of the location of the physical interaction with the customer.

Optional

ANS2 [A-Za-z]{2}

merchant.serviceLocationPostalCode

The postal code of the location of the physical interaction with the customer.

Optional

ANS10 [\s\S]{1,10}

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}

{merch_taxTreatment}

{merch_taxTreatment_desc}

Optional

{merch_taxTreatment_regex}

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

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

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.25. Fleet Data

Fleet Data is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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

Optional

A1
P|B

fleet.odometer

The reading of the total distance travelled by the vehicle.

Optional

N9
[0-9]{1,9}

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

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

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

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

fleet.prompts[n].vehicleId

The vehicle identification number.

Optional

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

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].customerData1

Any customer data.

Optional

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

fleet.prompts[n].customerData2

Any additional customer data.

Optional

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

fleet.prompts[n].cashBackAmount

The cash back amount.

Optional

N12
[0-9]{12}

fleet.prompts[n].siteTransactionNumber

The site transaction number.

Optional

N12
[0-9]{12}

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

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

fleet.prompts[n].trailerId

The fleet trailer identification.

Optional

ANS16
[\s\S]{1,16}

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

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

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=112277889"
	-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=CD5546444346646"
	-d "fleet.prompts[0].customerData1=DATA23:45;4;5;234234"
	-d "fleet.prompts[0].customerData2=DATA25:403294,234234"
	-d "fleet.prompts[0].cashBackAmount=000000000000"
	-d "fleet.prompts[0].siteTransactionNumber=123345346645"
	-d "fleet.prompts[0].jobId=JOBID55555666D3"
	-d "fleet.prompts[0].contractNumber=CNUMBER888FRT664AADF"
	-d "fleet.prompts[0].PIN= P!n#24"
	-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}

fleet.hostBasedPurchaseRestriction

The host-based purchase restriction data.

Optional

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

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.26. Linked Capture

Linked Capture is compatible with the following message type:

Capture Notification

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

Required

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

Example

An example scenario follows:

An initial PA request is submitted for the transaction.
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.27. Merchant-Initiated Transaction (MIT)/Customer-Initiated Transaction (CIT)

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

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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.

Optional

INITIAL|REPEATED

standingInstruction.source

The Standing Instruction source identifying whether a Customer- or Merchant-Initiated Transaction has been received.

Optional

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.28. Multiple Clearing (Captures)

Multiple Clearing (Captures) is compatible with the following message type:

Capture Notification

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:

Send an initial authorization request for the total amount intended for the transaction.
Fulfill half the order and partially capture one half the original initial authorization.
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.29. Partial Approval

Compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Capture Notification

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.30. Payment Identifier

Payment Identifier is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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.31. PIN-less Debit

PIN-less Debit is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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.32. Point-of-Sale (POS) Data Fields

Point-of-Sale (POS) Data Fields is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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.cardDataInputMode

Indicates the method used to retrieve 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

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

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

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

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

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

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|UNKNOWN

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

Optional

pos.localDateTime

Optional

(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]) ([0-1][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9])

pos.terminalOutputCapability

Indicates the ability of the terminal to print or display messages.

Optional

UNKNOWN|
NONE|
PRINT|
DISPLAY|
PRINT_AND_DISPLAY

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 "pos.localDateTime=01-01 10:30:30"
  -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.33. Receiving Institution Code

Receiving Institution Code is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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.34. Capture Reason

Capture Reason is compatible with the following message type:

Capture Notification

The reason field can be used to indicate why a transaction is being captured.

Parameter name

Description

Required

Regex

reason

Indicates the reason for the Capture.

Optional

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 "reason=TIMEOUT"
	-d "amount=75.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"

2.3.35. Reversal Reason

Reversal Reason is compatible with the following message type:

Reversal
Reversal Request

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

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.36. Reversal using referencedMerchantTransactionId

Reversals using referencedMerchantTransactionId are compatible with the following message type:

Reversal
Reversal Request

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.37. Strong Customer Authentication (SCA)

Strong Customer Authentication (SCA) is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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:

A standard contactless pre-authorization message is sent with pos.scaExemptionFlag = TAP_AND_PIN_SUPPORTED.
The upstream entity responds with the 300.100.190: Transaction declined (Issuer Requires PIN [SCA]) result code.
The terminal updates the message with the provided PIN.
A new payment message with PIN is sent to ConnectUP.
The pos.scaExemptionFlag field is updated to PIN_PROVIDED
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.38. Shipping Contact

Shipping Contact is compatible with the following message types:

Pre-Authorization Request
Capture Notification

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

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.39. Transaction Category

Transaction Category is compatible with the following message types:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

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)
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|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

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

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

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

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)

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

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

resultDetails.*

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

Optional

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

ANS8
[\s\S]{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

merchant.mcc

Merchant Category Code (MCC) is used to classify the business by the type of goods or services it provides.

Optional

N4
[0-9]{4}

merchant.street

The street address and/or name 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

Example

curl http://[hostname]:[port]/opp/v1/vp2pe/devicedata -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "merchant.mcc=1234"
  -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

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

resultDetails.*

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

Optional

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 and/or name 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

Deprecated and replaced by threeDSecure.tavv.

Conditional

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

threeDSecure.tavv

The Online Payment Cryptogram contained within the token.

Conditional

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

threeDSecure.eci

An optional ECI indicator contained within the token.

Optional

N2
0[0|1|2|6|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

The terminal operator.

Optional

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

pos.encryptedPin.ksn

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

AN11
^[a-zA-Z0-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

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

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:

Pre-Authorization Request
Debit Request
Debit adjustment
Credit Request
Deposit
Capture Notification
Reversal
Reversal Request
Credit Adjustment

ConnectUP supports sending EMV File Download data. All EMV File Download fields are optional.

Parameter name

Description

Required

Regex

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

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.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

emvFileDownload.caPkf

Contain a partial CA PKF file in the eSocket.POS EMV Download file format.

Optional

ANS9999
[\s\S]{1,9999}

Sample Response Containing EMV File Download 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"
}

8. Batch Management Service

8.1. Batch Management

This service is used to send batch management request messages.

A batch management request is created by sending a POST request over HTTPS to https://[hostname]:[port]/paymentsapi/opp/v1/batch

8.1.1. Batch Management Request

The minimum requirements for sending a Batch 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}

settlementDate

The month and day for which financial totals are reconciled. Should be in MMDD format.

Optional

N4
(?:0[1-9]|1[0-2])(?:0[1-9]|[12][0-9]|3[01])

remoteBatchNr

Used to fetch the aggregate totals for a specific batch from a store.

Optional

N10
^[1-9][0-9]{0,9}$

messageType

The batch message type:
RR - Reconciliation Request: These messages allow you to retrieve the totals for either the most recent batch or a specific batch.
RN - Reconciliation Notification: These messages serve the purpose of closing the current batch and providing details about its transaction amounts and totals.

Required

A2
RR|RN

currency

The currency code of the settlement amount (ISO 4217).

Optional

A3
[A-Z]{3}

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.

Optional

AN11
^[a-zA-Z0-9]{1,11}$

terminal.terminalId

Terminal identifier assigned by the acquirer.

Optional

ANS8
[\s\S]{8}

terminal.storeId

Store identifier assigned by the acquirer.

Optional

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

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Optional

totals.creditTrans

The total number of credit transactions, excluding reversals, that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.creditReversalTrans

The total number of credit reversal transactions, having a credit effect on the cardholder’s account, that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.debitTrans

The total number of debit transactions that have resulted in a financial change since the last settlement cutover, not including any reversals.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.debitReversalTrans

The total number of debit reversal transactions ,having a debit effect on the cardholder’s account, that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.transferTrans

The total number of transfer transactions, excluding reversals, that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.transferReversalTrans

The total number of transfer reversal transactions that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.inquiryTrans

The total number of inquiries that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.authTrans

The total number of authorization transactions that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.creditProcessingFees

Indicates the total amount of all credit processing fees. 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.

Optional

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

totals.creditTransactionFees

Indicates the total amount of all credit transaction fees. 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.

Optional

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

totals.debitProcessingFees

Indicates the total amount of all debit processing fees. 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.

Optional

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

totals.debitTransactionFees

Indicates the total amount of all debit transaction fees. 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.

Optional

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

totals.creditAmount

The total amount of all credit transactions, excluding reversals, that have been processed since the most recent settlement transition. 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

Optional

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

totals.creditReversalAmount

The total amount of all credit reversal transactions that have been processed since the most recent settlement transition. 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.

Optional

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

totals.debitAmount

The total amount of all debit transactions, excluding reversals, that have been processed since the most recent settlement transition. 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.

Optional

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

totals.debitReversalAmount

The total amount of all debit reversal transactions that have been processed since the most recent settlement transition. 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.

Optional

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

totals.paymentTrans

The total number of payment transactions that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.paymentReversalTrans

The total number of payment reversal transactions that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.netSettlement.indicator

Indicates whether the net settlement amount is debit or credit.

Optional

DEBIT|CREDIT

totals.netSettlement.amount

The net settlement amount. 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.

Optional

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

Example Reconciliation Request (RR)

curl http://[hostname]:[port]/opp/v1/batch -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "messageType=RR"
  -d "settlementDate=1020"
  -d "remoteBatchNr=12343"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78123753"
  -d "merchant.acquiringInstitutionCode=12345678901"

Example Reconciliation Notification (RN)

curl http://[hostname]:[port]/opp/v1/batch -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "messageType=RN"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78123753"
  -d "merchant.acquiringInstitutionCode=12345678901"
  -d "totals.creditTrans": "30000",
  -d "totals.creditReversalTrans": "30000",
  -d "totals.debitTrans": "30000",
  -d "totals.debitReversalTrans": "30000",
  -d "totals.transferTrans": "333",
  -d "totals.transferReversalTrans": "3332",
  -d "totals.inquiryTrans": "4444",
  -d "totals.authTrans": "30000",
  -d "totals.creditProcessingFees": "30000.00",
  -d "totals.creditTransactionFees": "23433.00",
  -d "totals.debitProcessingFees": "234522.00",
  -d "totals.debitTransactionFees": "44200.00",
  -d "totals.creditAmount": "2333.00",
  -d "totals.creditReversalAmount": "23344.00",
  -d "totals.debitAmount": "234355.00",
  -d "totals.debitReversalAmount": "2334.00",
  -d "totals.netSettlement.indicator": "DEBIT",
  -d "totals.netSettlement.amount": "2334.64",
  -d "totals.netSettlement.paymentTrans": "2334",
  -d "totals.netSettlement.paymentReversalTrans": "2334"

8.1.2. Batch Management Response

The following fields reflect the possible response values returned for a Batch Management request message.

Parameter name

Description

Required

Regex

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.remoteBatchNr

Contains the aggregate totals form a specific batch from a store.

Optional

N10
^[1-9][0-9]{0,9}$

result.settlementDate

The month and day for which financial totals are reconciled. Should be in MMDD format.

Optional

N4
(?:0[1-9]|1[0-2])(?:0[1-9]|[12][0-9]|3[01])

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

settlementCode

Indicates the result of a reconciliation.

Optional

UNKNOWN|IN_BALANCE|OUT_OF_BALANCE|ERROR"

totals.creditTrans

The total number of credit transactions, excluding reversals, that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.creditReversalTrans

The total number of credit reversal transactions, having a credit effect on the cardholder’s account, that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.debitTrans

The total number of debit transactions that have resulted in a financial change since the last settlement cutover, not including any reversals.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.debitReversalTrans

The total number of debit reversal transactions ,having a debit effect on the cardholder’s account, that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.transferTrans

The total number of transfer transactions, excluding reversals, that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.transferReversalTrans

The total number of transfer reversal transactions that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.inquiryTrans

The total number of inquiries that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.authTrans

The total number of authorization transactions that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.creditProcessingFees

Optional

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

totals.creditTransactionFees

Optional

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

totals.debitProcessingFees

Optional

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

totals.debitTransactionFees

Optional

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

totals.creditAmount

Optional

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

totals.creditReversalAmount

Optional

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

totals.debitAmount

Optional

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

totals.debitReversalAmount

Optional

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

totals.paymentTrans

The total number of payment transactions that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.paymentReversalTrans

The total number of payment reversal transactions that have been processed since the most recent settlement transition.

Optional

N10
^0|^[1-9]\d{0,9}$

totals.netSettlement.indicator

Indicates whether the net settlement amount is debit or credit.

Optional

DEBIT|CREDIT

totals.netSettlement.amount

Optional

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

Example

{
    "id": "d79db48246884c0e82fc404bb518b4aa",
    "result": {
      "code": "000.000.000",
     "description": "Transaction succeeded",
      "remoteBatchNr":  "2344",
      "settlementDate": "1224"
    },
    "timestamp": "2024-03-07 18:39:54",
    "resultDetails": {
      "iso8583ResponseCode": "00"
    },
    "settlementCode": "IN_BALANCE",
    "totals": {
      "creditTrans": "30000",
      "debitTrans": "30000",
      "debitReversalTrans": "30000",
      "transferTrans": "333",
      "transferReversalTrans": "3332",
      "inquiryTrans": "4444",
      "authTrans": "30000",
      "creditProcessingFees": "30000.00",
      "creditTransactionFees": "23433.00",
      "debitProcessingFees": "234522.00",
      "debitTransactionFees": "44200.00",
      "creditAmount": "2333.00",
      "creditReversalAmount": "23344.00",
      "debitAmount": "234355.00",
      "debitReversalAmount": "2334.00",
      "netSettlement": {
        "indicator": "CREDIT",
        "amount": "233.00"
      },
      "paymentTrans": "22222234",
      "paymentReversalTrans": "2222"
    }
}

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.

Appendix A: Format Element Descriptions

A.1. Format Explanation

Format element

Description

Alphabetic characters, A through Z, and a through z

Numeric digits, 0 through 9

Special characters, including the ASCII printable characters (character codes 32-127) and the extended ASCII codes (character codes 128-255)

Alphabetic and numeric characters

Alphabetic and special characters

Numeric and special characters

ANS

Alphabetic, numeric, and special characters

Year, 00 through 99

Month, 01 through 12

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.

9. ConnectUP OpenAPI Specification

Current publication date: 2024-04-15

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.1. Version 1.0.7

ConnectUP YAML

10. Publication history

Current publication date: 2024-04-15

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.41

Added new pos.terminalRestrictions field to basic payment requests.
Added new fleet response field fleet.hostBasedPurchaseRestriction

10.1. Version 1.40

Fleet Field Updates

Fleet fields length updates.
New Fleet prompt cashBackAmount
New Fleet prompt customerData1
New Fleet prompt customerData2
New Fleet prompt siteTransactionNumber

Version 1.39

Batch Management Service

Added the Batch Management Service

Version 1.38

serviceRestrictionCode and card.track1Data Support

serviceRestrictionCode and card.track1Data fields are now supported on all payment transactions.

Version 1.37

incrementalAuthorization support

An incrementalAuth field is now supported for PA, RR and RV payment transactions.
The incrementalAuth field contains subfields to construct incremental auth related indicators and amounts.

Version 1.36

deferredAuthorization flag support

A deferredAuthorization field is now supported for PA, CP and DB payment transactions.

Version 1.35

fleet.prompts[n].userId format update

Field fleet.prompts[n].userId now supports spaces

Version 1.34

memoPost flag support

A memoPost field is now supported for payment transactions

Version 1.33

customParameters field formatting

customParameter keys now support spaces

10.2. Version 1.32

Payment Service

Added new Payment Type CA: Credit Adjustment.
Payment Type RF (Refund) is now deprecated and replaced by CA (Credit Adjustment).
Added several new sub-fields to the merchant field.

Version 1.31

threeDSecure.ucafCollectionIndicator support

Introducing new field threeDSecure.ucafCollectionIndicator.
Also applied multiple updates to the threeDSecure field.

Version 1.30

Payment Service

Clarified the definition of the merchant street field.
Added support for the reason field value COMPLETED_PARTIALLY.

Version 1.29

Payment Service

Added support for specifying the to account type for cards for CP messages.
Added support for the reason field for CP messages.
Added new field pos.localDateTime for CP messages.
- pos.localDateTime is now returned on all payment response messages.
Added support for the following new POS fields in request messages:
- pos.cardDataInputMode
- pos.terminalOutputCapability

Version 1.28

Listed merchant.mcc under the field definitions for Device Data Request and Bill Payments.
Changed the format of Network Management Request field pos.terminalOperator from a set of values to any string value.
Elaborating on the definition for special characters.

Version 1.27

balances.ledgerBalance and balances.availableBalance are now returned on all payments responses.
additionalAmounts.approvedAmount are now returned on all payments responses.

Version 1.26

TAVV Support

Separating CAVV and TAVV values by introducing a new threeDSecure.tavv field.

Version 1.25

Card Verification support. availableBalance in BI response messages

Card Verification (CV message) support. Added support for balances.ledgerBalance in BI response messages.

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.

ConnectUP API Interface Specification: ACI Worldwide, Inc.

Example

Example

Example

Example

Debit Request

Debit Request Response

Example

Example

Example

Example

Example

ICC Data Result Response

Example

Balance Inquiry Request

Balance Inquiry Response

Example

Stored-Value Activate Request

Stored-Value Activate Response

Example

Stored-Value Load Request

Stored-Value Load Response

Example

Stored-Value Deactivate Request

Stored-Value Deactivate Response

Example

Example

Example

Example

Example

Example

Example

Response

Sample Response Containing the 3-D Secure Result

Example

Example

Example

Example

Example

Example

Example

Response

Example

Example

Response

Example

Example

Response

Example

Example

Example

Example

Response

Response containing the result.avsResponse field

Example

Example

Example

Response

Example

Sample $21.00 transaction with a $0.50 convenience fee

Example

Response

Example

Example

Example

Example

Example

Example

Example

Example

Example

Example

Response

Sample Response Containing fleet response data

Example

Initial Pre-Authorization Request

Pre-Authorization Response

Linked Capture Request using referencedPaymentId

Example

Response containing the `result.avsResponse` field

Linked Capture Request using `referencedPaymentId`