About the ConnectUP API

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

Message flow

ConnectUP accepts both HTTP POST messages with a URL-encoded body or JSON request messages. ConnectUP will return 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.

  • Network Management service - The Network Management service performs and runs network management related operations.

About this publication

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

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

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

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

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

1. Authentication

1.1. Authorization Bearer Token

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

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

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

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

  1. Construct the token themselves as described above.

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

Parameter name Description Required Regex

Authorization: Bearer <access-token>

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

Required

ANS110
[\x20-\xFF]{0,110}

entityId

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

Required

AN32
[a-f0-9]{32}
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUxNDJmOWV..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  [...]

1.2. Legacy Authentication

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

Parameter name Description Required Regex

authentication.userId (Deprecated)

The user ID for the entity.

Required

AN32
[a-f0-9]{32}

authentication.entityId (Deprecated)

The entity ID for the entity.

Required

AN32
[a-f0-9]{32}

authentication.password (Deprecated)

The password for the entity.

Required

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

2. Payment Service

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

2.1. Base Payment Operations

2.1.1. Pre-Authorization Request

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

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

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

Parameter name Description Required Regex

Authorization: Bearer <access-token>

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

Conditionally Required

ANS110
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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})?

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

Authorization: Bearer <access-token>

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

Conditionally Required

ANS110
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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

ANP6
[a-zA-Z0-9 ]{1,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=2050"
	-d "amount=21.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "referencedPaymentId=yd6b3d18bgd0db9aa7efhtabe8f098d2"
	-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
[\x20-\xFF]{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. For full reversals no amount is expected or can be zero-filled.
​
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.

Conditional

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, CP or stored value transaction that is to be reversed.

Conditional

ANS32
[\x20-\xFF]{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
[\x20-\xFF]{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. For full reversals no amount is expected or can be zero-filled.
​
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, CP or stored value transaction that is to be reversed.

Conditional

ANS32
[\x20-\xFF]{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

Authorization: Bearer <access-token>

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

Conditionally Required

ANS110
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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}
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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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

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

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. Mini Statement Request

This payment operation can be used to retrieve the mini statement (transaction history) for an associated account.

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

The minimum requirements for sending a Mini Statement 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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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

statement.range.startDate

The requested statement start date in YYYYMMdd format. Transactions occurring prior to this date should not be included in the statement transaction list.

Optional

N8
\d{4}\d{2}\d{2}

statement.range.endDate

The requested statement end date in YYYYMMdd format. Transactions occurring after this date should not be included in the statement transaction list.

Optional

N8
\d{4}\d{2}\d{2}

statement.range.transactionCount

The maximum number of transactions to be included in the transaction list. Must be a number between 1 and 9999.

Optional

..N4
^[1-9][0-9]{0,3}$

statement.range.lastBlockReference

This token is returned in the statement.transactionList field if all the transactions that fall within the specified range could not be sent in a single message (i.e. the value for statement.transactionList.isComplete is set to Y). To receive the remaining transactions in the range, the client should include the token in another request that otherwise has the same range as the initial request.

Optional

ANS16
[\x20-\xFF]{1,16}

statement.range.nextBlock

BACK if the block before the block identified by the LastBlockReference field is requested or FORWARD if the block after the block identified by the LastBlockReference field is requested.

Optional

BACK|FORWARD

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.

Mini Statement Response

ConnectUP supports sending mini statement (or transaction history) data. Some of the data is considered mandatory and other optional.

The following fields reflect the possible response values for a Mini Statement response message:

Parameter name Description Required Regex

statement.range.startDate

The posting date of the first transaction included in the statement in YYYYMMdd format.

Optional

N8
\d{4}\d{2}\d{2}

statement.range.endDate

The posting date of the last transaction included in the statement in YYYYMMdd format.

Optional

N8
\d{4}\d{2}\d{2}

statement.range.transactionCount

The actual number of transactions included in the response.

Mandatory

..N4
^[1-9][0-9]{0,3}$

statement.range.blockReference

This token is returned in the statement.transactions field if all the transactions that fall within the specified range could not be sent in a single message (i.e. the value for statement.complete is set to Y). To receive the remaining transactions in the range, the client should include the token in another request that otherwise has the same range as the initial request.

Optional

ANS16
[\x20-\xFF]{1,16}

statement.currencyCode

The alpha currency code to cater for multiple languages. This is the currency of the account for which the statement is returned.

Optional

A3
[A-Z]{3}

statement.complete

TRUE if there are no more transactions that fall within the range specified in the statement request message, FALSE otherwise.

Mandatory

TRUE:FALSE

statement.transactions[n].type

The Transaction Type.

Optional

GOODS_AND_SERVICES|​
CASH_WITHDRAWAL|​
DEBIT_ADJUSTMENT|​
CHECK_GUARANTEE|​
CHECK_VERIFICATION|​
EUROCHEQUE|​
TRAVELER_CHECK|​
LETTER_OF_CREDIT|​
GIRO|​
GOODS_AND_SERVICES_WITH_CASHBACK|​
NON_CASH|​
QUASI_CASH_AND_SCRIP|​
GENERAL_DEBIT|​
FEE_COLLECTION|​
RETURNS|​
DEPOSIT|​
CREDIT_ADJUSTMENT|​
CHECK_DEPOSIT_GUARANTEE|​
CHECK_DEPOSIT|​
GENERAL_CREDIT|​
MERCHANDISE_DISPATCH|​
FUNDS_DISBURSEMENT|​
AVAILABLE_FUNDS_INQUIRY|​
BALANCE_INQUIRY|​
GENERAL_INQUIRY|​
FULL_STATEMENT_INQUIRY|​
MERCHANDISE_INQUIRY|​
CARD_VERIFICATION_INQUIRY|​
MINI_STATEMENT_INQUIRY|​
LINKED_ACCOUNT_INQUIRY|​
CARDHOLDER_ACCOUNTS_TRANSFER|​
GENERAL_TRANSFER|​
PAYMENT_FROM_ACCOUNT|​
PAYMENT_BY_DEPOSIT|​
GENERAL_PAYMENT|​
PAYMENT_TO_ACCOUNT|​
PAYMENT_FROM_ACCOUNT_TO_ACCOUNT|​
PLACE_HOLD_ON_CARD|​
GENERAL_ADMIN|​
CHANGE_PIN|​
DEAD_END_GENERAL_ADMIN

statement.transactions[n].fromAccountType

This is the type of the account from which funds were transferred to this account.

Optional

DEFAULT|​
UNKNOWN|​
CHECK|​
CHECK_MONEY_MARKET|​
CREDIT|​
CREDIT_LINE_OF_CREDIT|​
CREDIT_INSTALLMENT_LOAN|​
CREDIT_MORTGAGE_LOAN|​
CREDIT_HOME_EQUITY_LOAN|​
CREDIT_COMMERCIAL_LOAN|​
UNIVERSAL|​
INVESTMENT|​
INVESTMENT_STOCK_OR_BOND|​
INVESTMENT_RETIREMENT_ACCOUNT|​
INVESTMENT_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

statement.transactions[n].fromAccountID

The ID of the account from which funds were transferred to this account.

Optional

ANS28
[\x20-\xFF]{0,28}

statement.transactions[n].toAccountType

This is the type of the account to which funds were transferred from this account.

Optional

DEFAULT|​
UNKNOWN|​
CHECK|​
CHECK_MONEY_MARKET|​
CREDIT|​
CREDIT_LINE_OF_CREDIT|​
CREDIT_INSTALLMENT_LOAN|​
CREDIT_MORTGAGE_LOAN|​
CREDIT_HOME_EQUITY_LOAN|​
CREDIT_COMMERCIAL_LOAN|​
UNIVERSAL|​
INVESTMENT|​
INVESTMENT_STOCK_OR_BOND|​
INVESTMENT_RETIREMENT_ACCOUNT|​
INVESTMENT_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

statement.transactions[n].toAccountID

The ID of the account to which funds were transferred from this account.

Optional

ANS28
[\x20-\xFF]{0,28}

statement.transactions[n].date

The date at which the transaction was performed originally. The format should be CCYYMMDD. The time can optionally be appended to the date in the format hhmmss.

Optional

N8 or N14
[0-9]{8} or [0-9]{14}

statement.transactions[n].postDate

The date at which the transaction was posted against the account. The format should be CCYYMMDD. The time can optionally be appended to the date in the format hhmmss.

Mandatory

N8 or N14
[0-9]{8} or [0-9]{14}

statement.transactions[n].transactionAmount.amount

The transaction amount.

Mandatory

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

statement.transactions[n].transactionAmount.indicator

Credit or Debit.

Mandatory

CREDIT|DEBIT

statement.transactions[n].transactionAmount.currencyCode

This is the alpha currency in which the transaction was done originally.

Mandatory

A3
[A-Z]{3}

statement.transactions[n].postAmount.amount

The transaction amount in currency of the account.

Mandatory

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

statement.transactions[n].postAmount.indicator

Credit or Debit.

Mandatory

CREDIT|DEBIT

statement.transactions[n].surcharge.amount

The surcharge amount.

Mandatory subfield when a surcharge is present

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

statement.transactions[n].surcharge.indicator

Credit or Debit.

Mandatory subfield when a surcharge is present

CREDIT|DEBIT

statement.transactions[n].fees[n].description

The fee description.

Optional

ANS20
[\x20-\xFF]{0,20}

statement.transactions[n].fees[n].amount

The fee amount.

Mandatory subfield when a fee list is present

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

statement.transactions[n].fees[n].indicator

Credit or Debit.

Mandatory subfield when a fee list is present

CREDIT|DEBIT

statement.transactions[n].description

The transaction description.

Optional

ANS40
[\x20-\xFF]{0,40}

statement.transactions[n].referenceNumber

The transaction reference number.

Optional

ANS20
[\x20-\xFF]{0,20}

statement.transactions[n].balance.type

The value of this tag must contain the type of balance that is being reported.

Mandatory subfield when a balance is present

LEDGER|​
AVAILABLE|​
AMOUNT_OWING|​
AMOUNT_DUE|​
REMAINING_THIS_CYCLE|​
CASH|​
AMOUNT_GOODS_AND_SERVICES|​
APPROVED|​
TIP|​
AVAILABLE_CREDIT|​
CREDIT_LIMIT

statement.transactions[n].balance.amount

The transaction amount in currency of the account.

Mandatory subfield when a balance is present

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

statement.transactions[n].balance.indicator

CREDIT or DEBIT

Mandatory subfield when a balance is present

CREDIT|DEBIT

statement.transactions[n].cardAcceptorAddress

The street address of the card acceptor.

Optional

ANS50
[\x20-\xFF]{0,50}

statement.transactions[n].cardAcceptorCity

The city of the card acceptor.

Optional

ANS40
[\x20-\xFF]{0,40}

statement.openingBalances[n].type

The value of this tag must contain a description of the type of balance that is being reported.

Optional

LEDGER|​
AVAILABLE|​
AMOUNT_OWING|​
AMOUNT_DUE|​
REMAINING_THIS_CYCLE|​
CASH|​
AMOUNT_GOODS_AND_SERVICES|​
APPROVED|​
TIP|​
AVAILABLE_CREDIT|​
CREDIT_LIMIT

statement.openingBalances[n].amount

The numerical value of the transaction (i.e. the quantity of funds).

Mandatory subfield when an openingBalance list is present

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

statement.openingBalances[n].indicator

CREDIT or DEBIT.

Mandatory subfield when an openingBalance list is present

CREDIT|DEBIT

statement.closingBalances[n].type

The value of this tag must contain a description of the type of balance that is being reported.

Optional

LEDGER|​
AVAILABLE|​
AMOUNT_OWING|​
AMOUNT_DUE|​
REMAINING_THIS_CYCLE|​
CASH|​
AMOUNT_GOODS_AND_SERVICES|​
APPROVED|​
TIP|​
AVAILABLE_CREDIT|​
CREDIT_LIMIT

statement.closingBalances[n].amount

The numerical value of the transaction (i.e. the quantity of funds).

Mandatory subfield when a closingBalance list is present

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

statement.closingBalances[n].indicator

CREDIT or DEBIT

Mandatory subfield when a closingBalance list is present

CREDIT|DEBIT

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

Example
Mini Statement Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/ministatement -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"
  -d "statement.range.startDate=20250227"
  -d "statement.range.endDate=20250228"
  -d "statement.range.transactionCount=0005"
  -d "statement.range.lastBlockReference=lbr123"
  -d "statement.range.nextBlock=FORWARD"
Mini Statement Response
{
  "statement": {
    "range": {
      "startDate": "20250226",
      "endDate": "20250227",
      "transactionCount": "4",
      "blockReference": "Block Ref"
    },
    "transactions": [
      {
        "type": "GOODS_AND_SERVICES",
        "date": "20250101",
        "fromAccountType": "DEFAULT",
        "fromAccountID": "FromAccID1",
        "toAccountType": "SAVINGS",
        "toAccountID": "ToAccID1",
        "postDate": "20250102",
        "description": "Transaction 1's description",
        "referenceNumber": "Transaction 1's reference number",
        "cardAcceptorCity": "Cape Town",
        "cardAcceptorAddress": "42 Church Street, Cape Town, 1002",
        "transactionAmount": {
          "indicator": "DEBIT",
          "amount": "10.00",
          "currencyCode": "UYU"
        },
        "postAmount": {
          "amount": "10.30",
          "indicator": "DEBIT"
        },
        "surcharge": {
          "amount": "10.31",
          "indicator": "DEBIT"
        },
        "balance": {
          "type": "LEDGER",
          "indicator": "DEBIT",
          "amount": "1122.00"
        },
        "fees": [
          {
            "description": "Tip",
            "amount": "0.01",
            "indicator": "DEBIT"
          },
          {
            "description": "Gratuity",
            "amount": "0.02",
            "indicator": "DEBIT"
          }
        ]
      },
      {
        "type": "GENERAL_ADMIN",
        "date": "20250201",
        "fromAccountType": "SAVINGS_CERTIFICATE_OF_DEPOSIT",
        "fromAccountID": "FromAccID2",
        "toAccountType": "CHECK",
        "toAccountID": "ToAccID2",
        "postDate": "20250202",
        "description": "Transaction 2's description",
        "referenceNumber": "Transaction 2's reference number",
        "transactionAmount": {
          "indicator": "DEBIT",
          "amount": "20.00",
          "currencyCode": "UZS"
        },
        "postAmount": {
          "amount": "20.30",
          "indicator": "DEBIT"
        },
        "surcharge": {
          "amount": "20.31",
          "indicator": "DEBIT"
        },
        "balance": {
          "type": "AVAILABLE",
          "indicator": "DEBIT",
          "amount": "2222.00"
        },
        "fees": [
          {
            "description": "Gratuity",
            "amount": "0.02",
            "indicator": "DEBIT"
          },
          {
            "description": "Tip",
            "amount": "0.03",
            "indicator": "DEBIT"
          }
        ]
      },
      {
        "type": "GENERAL_CREDIT",
        "date": "20250301",
        "fromAccountType": "CREDIT",
        "fromAccountID": "FromAccID3",
        "toAccountType": "CREDIT_LINE_OF_CREDIT",
        "toAccountID": "ToAccID3",
        "postDate": "20250302",
        "description": "Transaction 3's description",
        "referenceNumber": "Transaction 3's reference number",
        "transactionAmount": {
          "indicator": "DEBIT",
          "amount": "30.00",
          "currencyCode": "WST"
        },
        "postAmount": {
          "amount": "30.30",
          "indicator": "DEBIT"
        },
        "surcharge": {
          "amount": "30.31",
          "indicator": "DEBIT"
        },
        "balance": {
          "type": "AMOUNT_OWING",
          "indicator": "DEBIT",
          "amount": "3322.00"
        },
        "fees": [
          {
            "description": "Gratuity",
            "amount": "0.03",
            "indicator": "DEBIT"
          },
          {
            "description": "Tip",
            "amount": "0.04",
            "indicator": "DEBIT"
          }
        ]
      },
      {
        "type": "GOODS_AND_SERVICES_WITH_CASHBACK",
        "date": "20250401",
        "fromAccountType": "UNIVERSAL",
        "fromAccountID": "FromAccID4",
        "toAccountType": "INVESTMENT",
        "toAccountID": "ToAccID4",
        "postDate": "20250402",
        "description": "Transaction 4's description",
        "referenceNumber": "Transaction 4's reference number",
        "transactionAmount": {
          "indicator": "DEBIT",
          "amount": "40.00",
          "currencyCode": "YER"
        },
        "postAmount": {
          "amount": "40.30",
          "indicator": "DEBIT"
        },
        "surcharge": {
          "amount": "40.41",
          "indicator": "DEBIT"
        },
        "balance": {
          "type": "AMOUNT_DUE",
          "indicator": "DEBIT",
          "amount": "4422.00"
        },
        "fees": [
          {
            "description": "Other",
            "amount": "0.04",
            "indicator": "CREDIT"
          }
        ]
      }
    ],
    "openingBalances": [
      {
        "type": "REMAINING_THIS_CYCLE",
        "indicator": "CREDIT",
        "amount": "10000.00"
      },
      {
        "type": "CASH",
        "indicator": "DEBIT",
        "amount": "1.00"
      }
    ],
    "closingBalances": [
      {
        "type": "AMOUNT_GOODS_AND_SERVICES",
        "indicator": "CREDIT",
        "amount": "9000.00"
      },
      {
        "type": "AVAILABLE_CREDIT",
        "indicator": "DEBIT",
        "amount": "2.00"
      },
      {
        "type": "CREDIT_LIMIT",
        "indicator": "DEBIT",
        "amount": "3.00"
      }
    ],
    "currencyCode": "USD",
    "complete": true
  }
}

2.1.10. 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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{8,255}

card.number

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

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

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

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

Example
Stored-Value Activate Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/activate -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=55.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MANUAL"
	-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.11. 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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{8,255}

card.number

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

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

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

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

Example
Stored-Value Load Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/load -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=55.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MANUAL"
	-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.12. 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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{8,255}

card.number

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

Conditionally Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

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

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

Example
Stored-Value Deactivate Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/deactivate -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=55.00"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MANUAL"
	-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.13. Stored-Value Reversal Request

This service is used to reverse stored-value transactions.

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

The minimum requirements for sending a Stored-Value Reversal 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
[\x20-\xFF]{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
[\x20-\xFF]{1,15}

referencedMerchantTransactionId

The supplied "merchantTransactionId" of the original PA, DB, CD, CP or stored value transaction that is to be reversed.

Conditionally Required

ANS255
[\x20-\xFF]{8,255}

referencedPaymentId

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

Conditionally Required

ANS32
[\x20-\xFF]{1,32}

reason

Indicates the reason for the capture/reversal.

Optional

VOID|TIMEOUT|MAC|STORE_CONTROLLER|STANDIN_PROCESSING|CARD_ISSUER_UNAVAILABLE|UNDER_FLOOR_LIMIT|PIN_RELATED_FAILURE|CHANGE_DISPENSED|IOU_RECEIPT_PRINTED|MANUAL_ADJUSTMENT_REQUIRED|ACQUIRER_VOICE_AUTH_REQUIRED|FORCED_TRANSACTION_ACCEPTANCE|EMV_APPROVED_AFTER_ONLINE|FRAUD_SERVICE_BLOCK|OVER_FLOOR_LIMIT|NEGATIVE_CARD|UNSPECIFIED|COMPLETED_PARTIALLY|UNABLE_TO_DELIVER|SUSPECTED_MALFUNCTION|INVALID_RESPONSE|INVALID_CVV2|INVALID_ADDRESS|MERCHANT_CANCELLATION|BLOCKED_DEVICE|DEVICE_UNIDENTIFIABLE|DECRYPTION_FAILURE|UNEXPECTED_TRANSACTION_DATA|DECLINED_AFTER_RISK_ANALYSIS
Example
Stored-Value Reversal Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/reversal -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "referencedPaymentId=ce6b3d18b660db9aa7ef667be8f098d2"
Stored-Value Reversal Response
{
    "amount": "0.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.14. 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
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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.15. Deposit

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

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

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

Parameter name Description Required Regex

Authorization: Bearer <access-token>

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

Conditionally Required

ANS110
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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.16. 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

Authorization: Bearer <access-token>

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

Conditionally Required

ANS110
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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.17. 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
[\x20-\xFF]{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}

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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.18. 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

Authorization: Bearer <access-token>

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

Conditionally Required

ANS110
[\x20-\xFF]{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})

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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.1.19. Check Authorization

This payment operation is used to authorize personal checks.

A Check 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 CC 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
[\x20-\xFF]{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

CC

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

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{8,255}

check[n].formattedMicr.checkNr

The check number (from the MICR data).

Required

N10
[0-9]{1,10}

check[n].formattedMicr.transitNr

The code of the institution that issued the check (from the MICR data). In the USA this is the ABA number, also called the routing-and-transit number.

Required

N8
[0-9]{1,8}

check[n].formattedMicr.accountNr

The account number (from the MICR data).

Required

N28
[0-9]{1,28}

check[n].driversLicense.nr

The driver’s license number.

Required

ANS24
[\x20-\xFF]{1,24}

check[n].genericId.idNr

The ID number of the customer.

Required

ANS24
[\x20-\xFF]{1,24}

check[n].genericId.idType

The ID type of the customer

Required

PASSPORT|​
IDENTITY_DOCUMENT|​
SOCIAL_SECURITY_NUMBER|​
NATIONAL_INSURANCE_NUMBER​
Check Authorization Response

The following fields reflect the possible response values for a Check Authorization response message:

Parameter name Description Required Regex

check.serviceCharge

The service charge of the transaction. Values are expressed in the minor denomination (e.g. cents).

Optional

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

check.proprietaryResponseInfo

The information provided by the Proprietor.

Optional

N12
[0-9]{0,12}

check.ecaTransactionStatus

Indicator for processing checks via check truncation. Returned in response.

Optional

KEEP_PAPER_CHECK|​
PRINT_ECA_RECEIPT

check.denialRecordNr

Denial Number or level of risk received by the processing bank for declined transactions. Returned in the response by processor.

Optional

AN7
^[A-Za-z0-9]{0,7}$

check.telecheckMicrSequenceNr

The MICR Sequence Number received in the response from the processor.

Optional

AN3
^[A-Za-z0-9]{0,7}$

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

Example
Check Authorization Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=CC"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "check[0].formattedMicr.checkNr=123456"
  -d "check[0].formattedMicr.transitNr=21212121"
  -d "check[0].formattedMicr.accountNr=3388257"
  -d "check[0].driversLicense.nr=LC1235452154"
  -d "check[0].genericId.idNr=77777777777"
  -d "check[0].genericId.idType=PASSPORT"
Check Authorization Response
{
    "amount": "200.00",
    "currency": "USD",
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded"
        "authorizationId": "071797"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    },
    "check":
    {
        "serviceCharge": "11.5"
        "propritaryResponseInfo": "123456789105"
        "ecaTransactionStatus": "KEEP_PAPER_CHECK"
        "denialRecordNr": "1245245"
        "telecheckMicrSequenceNr": "123"
    }
}

2.1.20. Admin Request

This is an admin request operation

An Admin 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 AR 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
[\x20-\xFF]{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

AR

extendedPaymentType

The extended payment type is used to enrich the payment type with additional context.

Optional

A2
REG_DEV|​ADV_ENC_KEY|​ELEC_CHK_AUTH|​EBT

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
[\x20-\xFF]{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.

Required

N11
[0-9]{1,11}

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=AR"
  -d "extendedPaymentType=REG_DEV"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "merchant.receivingInstitutionCode=11111111111"

2.1.21. Admin Notification

This is an admin notification operation.

An Admin Notification 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 AN 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
[\x20-\xFF]{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

AN

extendedPaymentType

The extended payment type is used to enrich the payment type with additional context.

Optional

A2
REG_DEV|​ADV_ENC_KEY|​ELEC_CHK_AUTH|​EBT

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
[\x20-\xFF]{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.

Required

N11
[0-9]{1,11}

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=AN"
  -d "extendedPaymentType=REG_DEV"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "merchant.receivingInstitutionCode=11111111111"

2.1.22. Pre-Authorization Credit Request

This payment operation requests authorization to credit the account of the customer and debit the merchant’s account.

A Pre-Authorization 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 PC 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
[\x20-\xFF]{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

PC

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

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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=PC"
  -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.23. Credit Notification

This payment operation captures a previous Pre-Authorization Credit request.

A Credit Notification 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 CN 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
[\x20-\xFF]{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

CN

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

serviceRestrictionCode.area

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

Optional. Required if other serviceRestrictionCode \ subfields are 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 are 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 are 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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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

ANP6
[a-zA-Z0-9 ]{1,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=CN"
  -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 "referencedPaymentId=yd6b3d18bgd0db9aa7efhtabe8f098d2"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "authorizationId=114547"
  -d "memoPost=true"
  -d "deferredAuthorization=true"

2.2. Base Payment Operation Responses

2.2.1. Standard Response

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

Parameter name Description Required Regex

id

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

Always

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

timestamp

The timestamp generated by the response in UTC.

Always

date
yyyy-MM-dd hh:mm:ss

result.code

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

Always

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

result.description

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

Always

AN255
[\x20-\xFF]{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
[\x20-\xFF]{0,2048}

resultDetails.iso8583ResponseCode

Provides more detailed information about transactions processed using the ISO8583 standard. The unmodified value of ISO8583 field 39 is returned. The existing result code remains the primary status of the request, with the iso8583ResponseCode field providing additional context and detail about the transaction outcome.

Conditional

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

resultDetails.AcquirerResponse

The raw host network response code.

Conditional

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

resultDetails.AcquirerAvsResponse

The raw host network AVS response code.

Conditional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\x20-\xFF]{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.level3InterchangeEligible

Indicates that the card eligible for Level 3. This enables the merchant to send Level 3 transaction data to qualify for the best possible interchange rate. ​
Possible values:
Y - Yes
N - No
X - Not applicable / unknown

Conditional

Y|N|X

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}

resultDetails.retrievalReferenceNumber

A reference number supplied by the system retaining the original source information and used to assist in locating that information or a copy thereof.

Conditional

ANS12
[\x20-\xFF]{12}

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Conditional

name: AN64
[a-zA-Z0-9\.:_ ]{3,64}
value: AN2048
[\x20-\xFF]{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

ANP6
[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
[\x20-\xFF]{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])

card.accountType

A value indicating the type of account affected by the transaction. The response account type may differ from the request account type.

Optional

DEFAULT|​
UNKNOWN|​
CHECK|​
CHECK_MONEY_MARKET|​
CREDIT|​
CREDIT_LINE_OF_CREDIT|​
CREDIT_INSTALLMENT_LOAN|​
CREDIT_MORTGAGE_LOAN|​
CREDIT_HOME_EQUITY_LOAN|​
CREDIT_COMMERCIAL_LOAN|​
UNIVERSAL|​
INVESTMENT|​
INVESTMENT_STOCK_OR_BOND|​
INVESTMENT_RETIREMENT_ACCOUNT|​
INVESTMENT_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

cart.items[n].productCodeType

The type of code printed on the product.

Optional

UPC|​
PLU|​
SERVICE_OR_DELIVERY_CHARGES|​
PRODUCT_GROUP|​
DEPARTMENT

cart.items[n].merchantItemId

The universal product code (UPC) of this item.

Optional

ANS20
[\x20-\xFF]{1,20}

cart.items[n].classificationCode

The item classification code.

Optional

UNKNOWN|​
SNAP_ELIGIBLE|​
ALCOHOL|​
TOBACCO

cart.items[n].categoryCode

A code used to identify the product/produce item at a macro level (eg milk).

Optional

AN10
[a-zA-Z0-9]{1,10}

cart.items[n].subCategoryCode

A code used to identify the product/produce item at a micro level (eg skim).

Optional

AN10
[a-zA-Z0-9]{1,10}

cart.items[n].quantity

The decimalized quantity of the product. (e.g. 2.37 or 27.00).

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
[\x20-\xFF]{1,12}

cart.items[n].quantityOfPackageMeasure

Used to indicate the quantity within a package when the line item refers to a set of items, eg. for one dental floss package where the package contains a set of 4 dental flosses, this field should be 4.

Optional

N12
[1-9][0-9]{0,11}

cart.items[n].price

The decimalized unit price of the product (e.g. 2.37 or 27.00).

Optional

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

cart.items[n].totalAmount.indicator

DEBIT indicates a debit (negative balance) and CREDIT indicates a credit (positive balance)

Optional

DEBIT|CREDIT

cart.items[n].totalAmount.amount

The decimalized total amount. A period (.) is used as a decimal separator in all cases.

Optional

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

taxAmounts[n].taxType

The type of tax.

Optional

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

taxAmounts[n].taxDescription

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

Optional

ANS20
[\x20-\xFF]{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
[\x20-\xFF]{1,20}

cart.items[n].number

The line number of this item on the invoice.

Optional

N3
[0-9]{3}

cart.items[n].actionCode

In response messages, it reflects the action taken by the host with regards to this line item.

Optional

APPROVED|​
NOT_APPROVED|​
EXCEEDS_AVAILABLE

cart.items[n].purseType

The purse type value.

Optional

OTC|​
FOOD|​
OTHER

cart.items[n].limitedSpendEligibilityFlag

Identifies the item as eligible for spend for the associated account.

Optional

true|false

cart.items[n].amountPaidByTheProcessor

In response messages this is the amount paid by the processor for this item.

Optional

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

cart.items[n]itemizedDiscounts[n].label

Short description for the discount.

Optional

..ANS10
[\x20-\xFF]{1,10}

cart.items[n]itemizedDiscounts[n].purseCount

The number of purses applied for this discount.

Optional

..N2
[1-9][0-9]?

cart.items[n]itemizedDiscounts[n].type

The discount type.

Optional

MANUFACTURER|​
STORE

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

The discount tax amount (in the minor denomination).

Optional

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

cart.items[n]itemizedDiscounts[n].quantity

The number of times the discount is to be applied at the POS

Optional

..N3
[1-9][0-9]{0,2}

cart.items[n]itemizedDiscounts[n].eligibility

Indicates whether this line item is eligible for the discount.

Optional

true|false

cart.items[n].purseId

A numeric identifier of the purse used for this line item.

Optional

..N10
[0-9]{1,10}

purseData[n].purseId

A numeric identifier for the purse.

Optional

..n10
[0-9]{1,10}

purseData[n].description

A description of the purse.

Optional

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

purseData[n].balance.indicator

Indicates whether the purse balance is debit or credit.

Optional

DEBIT|​
CREDIT

purseData[n].balance.amount

The 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

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

purseData[n].amountAuthorized

The amount authorized from the purse. 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})?

purseData[n].responseCode

A response code providing additional information about a purse decline.

Optional

..AN10
[a-zA-Z0-9]{1,10}

promotionData[n].promotionCode

A promotion code that identifies the applied promotion.

Optional

..n30
[\x20-\xFF]{1,30}

promotionData[n].promotionNumber

The promotion ID.

Optional

..N10
[0-9]{1,10}

promotionData[n].promotionType

The promotion type.

Optional

PURSE

promotionData[n].appliedPromotionAmount

The decimalized sum of the transaction promotions applied to products per product cod

Optional

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

promotionData[n].promotionDescription

The promotion description to be printed on purchase receipt for each corresponding transaction

Optional

..ANS30
[\x20-\xFF]{1,30}

benefitData.expirationDate

OTC expiration date in YYYYMMdd format.

Optional

n8
^[0-9]{8}$

benefitData.expirationTime

OTC expiration time in HHmmss format.

Optional

n6
^[0-9]{6}$

benefitData.balances[n].ordinalNumber

Assigned by host in response. Will be returned in order of most restrictive benefit to least restrictive benefit.

Optional

..n10
[0-9]{1,10}

benefitData.balances[n].programCode

The program code for the benefit.

Optional

..ANS10
[\x20-\xFF]{1,10}

benefitData.balances[n].programName

The program name for the benefit.

Optional

..ANS50
[\x20-\xFF]{1,50}

benefitData.balances[n].promotionCode

The promotion code for the benefit.

Optional

..ANS30
[\x20-\xFF]{1,30}

benefitData.balances[n].balance.indicator

Indicates the units the promotion is distributed in.

Optional

UNITS|DOLLARS

benefitData.balances[n].balance.amount

The amount, or number of units available to the card holder for this benefit. 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})?

benefitData.balances[n].promotionName

A short description of the benefit.

Optional

..ANS30
[\x20-\xFF]{1,30}
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",
  "cart": [
    {
      "productCodeType": "UPC",
      "merchantItemId": "genericItemId",
      "classificationCode": "ALCOHOL",
      "categoryCode": "milk",
      "subCategoryCode": "skim",
      "quantity": "1",
      "unitOfMeasure": "lbs",
      "quantityOfPackageMeasure": 5,
      "price": "15.00",
      "totalAmount": {
        "indicator": "DOLLARS",
        "amount": "850.00"
      },
      "taxAmounts": [
        {
          "taxType": "UNKNOWN",
          "taxDescription": "State GS",
          "totalTaxAmount": "1.50",
          "tax": 80.97,
          "taxId": "us_taxes"
        }
      ],
      "number": 5,
      "actionCode": "APPROVED",
      "purseType": "OTC",
      "limitedSpendEligibilityFlag": false,
      "amountPaidByTheProcessor": "15.00",
      "itemizedDiscounts": [
        {
          "label": "345345",
          "purseCount": "10",
          "type": "STORE",
          "amount": "156.46",
          "taxAmount": "156.46",
          "quantity": "300",
          "eligibility": true
        }
      ],
      "purseId": "stringID"
    }
  ],
  "purseData": [
    {
      "purseId": 234234324,
      "description": "purse description.",
      "balance": {
        "indicator": "CREDIT",
        "amount": "850.00"
      },
      "amountAuthorized": "850.00",
      "responseCode": "AVC_234234"
    }
  ],
  "promotionData": [
    {
      "promotionCode": "IUSHU_234422q2_$1",
      "promotionNumber": 123155234,
      "promotionType": "PURSE",
      "appliedPromotionAmount": "15.00",
      "promotionDescription": "promotion description."
    }
  ],
  "benefitData": {
    "expirationDate": 20251231,
    "expirationTime": 125510,
    "balances": [
      {
        "ordinalNumber": 234234324,
        "programCode": "code1234.",
        "programName": "program name123$.",
        "promotionCode": "promotion code123$.",
        "balance": {
          "indicator": "DOLLARS",
          "amount": "850.00"
        },
        "promotionName": "promotion name 1234%$."
      }
    ]
  }
}
Note
 Optional fields will only be returned when the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

2.3. Specialized Payment Use Cases

2.3.1. 3-D Secure

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

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

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

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

threeDSecure.eci

The Electronic Commerce Indicator (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
[\x20-\xFF]{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
Sample Response Containing the 3-D Secure Result
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "50.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "threeDSecure":{
        "result" : "VALIDATION_PASSED_AUTHENTICATION"
    },
    "customParameters":{
        "MY_KEY1":"MY_VALUE1",
        "MY_KEY2":"MY_VALUE2"
    },
    "timestamp" : "2019-09-06 12:00:00"
}

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

2.3.2. Account Type

Account Type is compatible with the following message types:

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

Parameter name Description Required Regex

card.accountType

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

Required

DEFAULT|​
UNKNOWN|​
CHECK|​
CHECK_MONEY_MARKET|​
CREDIT|​
CREDIT_LINE_OF_CREDIT|​
CREDIT_INSTALLMENT_LOAN|​
CREDIT_MORTGAGE_LOAN|​
CREDIT_HOME_EQUITY_LOAN|​
CREDIT_COMMERCIAL_LOAN|​
UNIVERSAL|​
INVESTMENT|​
INVESTMENT_STOCK_OR_BOND|​
INVESTMENT_RETIREMENT_ACCOUNT|​
INVESTMENT_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
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:

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|​
UNKNOWN|​
CHECK|​
CHECK_MONEY_MARKET|​
CREDIT|​
CREDIT_LINE_OF_CREDIT|​
CREDIT_INSTALLMENT_LOAN|​
CREDIT_MORTGAGE_LOAN|​
CREDIT_HOME_EQUITY_LOAN|​
CREDIT_COMMERCIAL_LOAN|​
UNIVERSAL|​
INVESTMENT|​
INVESTMENT_STOCK_OR_BOND|​
INVESTMENT_RETIREMENT_ACCOUNT|​
INVESTMENT_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
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:

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
[\x20-\xFF]{1,35}

pos.posId

Identifies the device that initiated the transaction.

Optional

ANS35
[\x20-\xFF]{1,35}

pos.transactionSequenceNumber

Identifies the transaction on the device that initiated the transaction.

Optional

ANS35
[\x20-\xFF]{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

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

Manual Card Data is compatible with the following message types:

Parameter name Description Required Regex

card.number

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

Required

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Required

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

card.cvv

The card security code or CVV.

Optional

N4
[0-9]{3,4}

card.sequenceNumber

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

Optional

N3
[0-9]{3}

pos.entryMode

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

Required

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

Magstripe Card Data is compatible with the following message types:

ConnectUP supports transactions using magnetic stripe data. Either card.track1Data, card.track2Data or both must be set. The pos.entryMode must be set to MAGSTRIPE.

Parameter name Description Required Regex

card.track1Data

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

Conditional

ANS..76
[\x20-\xFF]{0,76}

card.track2Data

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

Conditional

ANS..37
[\x20-\xFF]{1,37}

pos.entryMode

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

Required

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

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

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

Parameter name Description Required Regex

pos.entryMode

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

Required

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

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

Token Card Data

Token Card Data is compatible with the following message types:

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

Parameter name Description Required Regex

tokenId

A token representing sensitive cardholder data.

Required

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

pos.entryMode

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

Required

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

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

Apple Pay Data

Apple Pay Data is compatible with the following message types:

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

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

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

paymentBrand

The payment brand used to identify alternative payment method transactions.

Required

APPLEPAY

currency

The currency code of the payment request’s amount (ISO 4217).
​
The default currency used is "USD".
​
For a Reversal, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction.

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

Conditional

A3
[A-Z]{3}

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).
​
If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.
​
If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.
​
A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

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

Conditional

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

applePay.paymentToken

The encrypted payment token provided by Apple.

Required

ANS8192
[\x20-\xFF]{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}
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:

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
[\x20-\xFF]{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}
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

Point-to-Point Encryption (P2PE) is a payment security standard that encrypts sensitive cardholder data directly at the payment terminal.

ConnectUP supports multiple P2PE schemes from leading terminal manufacturers, allowing merchants to securely transmit encrypted card data without exposing sensitive information.

Point-to-Point-Encryption (P2PE) Card Data is compatible with all payment types:

Parameter name Description Required Regex

pos.p2peEncrypted.type

Indicates the Point-to-Point Encryption (P2PE) solution implemented on the terminal device. This field is mandatory and must match the P2PE scheme configured for the terminal device. ​
​
Supported Schemes: ​
​
- ACI P2PE scheme: (ACI) ​
- ACI AES P2PE scheme: (ACI_AES) ​
- Ingenico On-Guard P2PE scheme: (INGENICO_ONGUARD) ​
- PAX P2PE scheme: (PAX) ​
- Presto P2PE scheme: (PRESTO) ​
- Verifone P2PE scheme: (VERIFONE_VSD)

Required

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

pos.p2peEncrypted.ksn

The Key Serial Number (KSN) is a unique value provided by the terminal that is mandatory when P2PE encryption is used. The KSN is used to identify or derive which Base Derivation Key (BDK) to use for decryption. Must be provided to the API unmodified as a hexadecimal representation. Each P2PE scheme has specific KSN length and structure requirements. Please refer to the terminal manufacturer’s documentation. ​
​
Example (PAX): `F8765432100000000077`

Required

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

pos.p2peEncrypted.sensitiveData

Hex string containing the ACI SensitiveDataKeyBlockFormat data structure. It carries scheme-specific auxiliary information that allows the host to identify or derive the decryption key(s) as well as any other data items required to decrypt the card data. Only used by the ACI, ACI_AES and VERIFONE_VSD P2PE schemes. Please contact an ACI representative for the ACI P2PE Interface Specification for PED Manufacturers. It explains the format and structure of the SensitiveDataKeyBlockFormat v1. ​
​
ACI and ACI_AES: (required when) ​
​
(1) A store-and-forward transaction, pos.p2peEncrypted.persistableData, was encrypted with a secondary key. The terminal embeds the secondary KSN inside this block. ​
​
(2) `pos.p2peEncrypted.maxReliableBinLength` is not supplied - the obfuscation scheme may be retrieved from this block if set. ​
​
Example:​
`3130303139303030381231232468A004D2303231313138303031303132333132​
3332343638413030344433313030365331`​
​
VERIFONE_VSD: (required when) ​
​
(1) LRC byte handling: Signals whether the terminal appends a trailing LRC byte to its encrypted output. If omitted, an LRC is assumed present and the system strips the last decrypted byte. ​
​
(2) A store-and-forward transaction, pos.p2peEncrypted.persistableData, was encrypted with a secondary key. The terminal embeds the secondary KSN inside this block. ​
​
Example:​
`323030334130303041ffff123ace000440046030323131314330303134464646​
46313233414345303030343430303436313031303946414c5345'​

Conditional

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

pos.p2peEncrypted.persistableData

This field is used for store-and-forward scenarios and contains
encrypted card data that can be safely stored for later processing. ​
​
Either `pos.p2peEncrypted.persistableData` or `pos.p2peEncrypted.volatileData` must be present, however, if both fields are set, `volatileData` takes precedence. 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. ​
​
The content contained in the field is P2PE scheme dependent. See the P2PE section below for per scheme details.

Conditional

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

pos.p2peEncrypted.volatileData

This field is used for real-time transactions. It contains encrypted card data that may not be persisted. ​
​
Either `pos.p2peEncrypted.persistableData` or `pos.p2peEncrypted.volatileData` must be present, however, if both fields are set, `volatileData` takes precedence. If card details are received in addition to `pos.p2peEncrypted.volatileData`, it is assumed that the particular card used is subject to whitelisting and that `pos.p2peEncrypted.whitelistFileName` is present. ​
​
The content contained in the field is P2PE scheme dependent. See the P2PE section below for per scheme details.

Conditional

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

pos.p2peEncrypted.whitelistFileName

The filename of the BIN whitelist file installed on the terminal device. Certain card types are legitimately exempt from P2PE encryption. The whitelist defines the approved BIN (Bank Identification Number) ranges for those cards. When a clear-text card number is received, this filename is used to locate the correct whitelist and confirm that the card’s BIN is permitted to arrive unencrypted. If the filename is unrecognised, the hash does not match, or the card’s BIN is not on the list, the transaction is rejected. ​
​
Only required when whitelist validation is in use.

Conditional

ANS100
[\x20-\xFF]{1,100}

pos.p2peEncrypted.tlvMapping[name]

Describes how to interpret the data of each named TLV tag within `pos.p2peEncrypted.persistableData` and `pos.p2peEncrypted.volatileData`. ​
​
Key (name): ​
The hexadecimal TLV tag code, e.g. `5A`, `57`, `DFDB02`. ​
​
Valid values: ​
`B` - The tag value contains raw binary bytes. ​
`ANS` - Alphanumeric special.
`AN` / `N` (or any other value) - The field value is used as-is with no transformation. ​
​
Default when `tlvMapping` is absent: ​
INGENICO_ONGUARD: AN (as-is). ​
ACI, ACI_AES: `B` auto-applied to tags `57`, `9F6B`, `9F20`, `5A`; AN for all others. ​
VERIFONE_VSD: `B` (binary) for all tags. ​
PAX, PRESTO: Not used. ​
​
Tags not explicitly set when `tlvMapping` is partially provided: ​
INGENICO_ONGUARD, ACI, ACI_AES: AN (as-is).
VERIFONE_VSD: `B` (binary). ​
​
Example:
`pos.p2peEncrypted.tlvMapping[5A]=B` ​
`pos.p2peEncrypted.tlvMapping[57]=B`

Conditional

name: AN64
[a-zA-Z0-9\._]{2,64}
value: AN2048
[\x20-\xFF]{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. ​
​
Example: `pos.p2peEncrypted.maxReliableBinLength=6`

Conditional

N99999
[0-9]{1,99999}

pos.p2peEncrypted.whitelistHash

A cryptographic hash of the BIN whitelist file currently loaded on the terminal, encoded as a hexadecimal string. When whitelist validation is active, this value is used to confirm that the terminal’s whitelist file is the authorised version. ​
​
PRESTO: ​
Required when whitelist validation is enabled. Provide the SHA-256 hex hash of the whitelist file as reported by the terminal. Must be accompanied by `pos.p2peEncrypted.whitelistFileName`. ​
​
ACI, ACI_AES: ​
Not required. The hash is carried inside the terminal’s encrypted data block. ​
​
VERIFONE_VSD, PAX, INGENICO_ONGUARD: ​
Not required.

Conditional

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

The following examples demonstrate P2PE integration with different terminal schemes.

Example 1: ACI Online transaction. 
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment \
  -H "Authorization: Bearer MDhkNDVhYmNkZTEzYmQyNzZlMmEwNWNkN2IwYTlhYjM2RUE0OTM3QTA0NzE1N0RFOUZBQjlENkREMEExRjc5NA==" \
  -d "entityId=entity1pcx8d4abde3b7e205d70a9ab3" \
  -d "paymentType=DB" \
  -d "amount=100.00" \
  -d "currency=USD" \
  -d "pos.storeId=78123753" \
  -d "pos.terminalId=12195611" \
  -d "pos.entryMode=ICC" \
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" \
  -d "pos.p2peEncrypted.type=ACI" \
  -d "pos.p2peEncrypted.ksn=1231232468A004D2" \
  -d "pos.p2peEncrypted.volatileData=35303038323030303034386F7EE2484791F17474D4702096D719429CA6211BD1
  ED5314FF9A294240A2702D7C9F8A7CBB4B98C8681009632C204ACB0032BE464D2F32C70B00C622421C738471E442F5F1407
  C0532323068E656B251E67E8358BEF8483AB0D51C6619F3E7A1A9F0E75838D41FF368F728303130387C582315F8A21EA4"
Example 2: ACI Store and Forward Transaction

A secondary key contained in 'pos.p2peEncrypted.sensitiveData' is used to encrypt the persisted data.

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment \
  -H "Authorization: Bearer MDhkNDVhYmNkZTEzYmQyNzZlMmEwNWNkN2IwYTlhYjM2RUE0OTM3QTA0NzE1N0RFOUZBQjlENkREMEExRjc5NA==" \
  -d "entityId=entity1pcx8d4abde3b7e205d70a9ab3" \
  -d "paymentType=DB" \
  -d "amount=100.00" \
  -d "currency=USD" \
  -d "pos.storeId=78123753" \
  -d "pos.terminalId=12195611" \
  -d "pos.entryMode=ICC" \
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" \
  -d "pos.p2peEncrypted.type=ACI" \
  -d "pos.p2peEncrypted.ksn=1231232468A004D2" \
  -d "pos.p2peEncrypted.sensitiveData=3130303139303030381231232468a004d2303231313138303031303132333132
  3332343638413030344433313030365331" \
  -d "pos.p2peEncrypted.persistableData=31303034423038010101010101010130303330033aa13cb37f8781ad43e6d08c
  7f3ef3e98b9c7812677b6c8cc41ab4f1f72bd3b4faf3abf3b956779b0ad00f0b02b1472c26940e41872910"
Example 3: Verifone VSD Online Transaction

LRC byte flag set in 'pos.p2peEncrypted.sensitiveData'.

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment \
  -H "Authorization: Bearer MDhkNDVhYmNkZTEzYmQyNzZlMmEwNWNkN2IwYTlhYjM2RUE0OTM3QTA0NzE1N0RFOUZBQjlENkREMEExRjc5NA==" \
  -d "entityId=entity1pcx8d4abde3b7e205d70a9ab3" \
  -d "paymentType=DB" \
  -d "amount=100.00" \
  -d "currency=USD" \
  -d "pos.storeId=78123753" \
  -d "pos.terminalId=12195611" \
  -d "pos.entryMode=ICC" \
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" \
  -d "pos.p2peEncrypted.type=VERIFONE_VSD" \
  -d "pos.p2peEncrypted.ksn=FFFF123ACE0004400460" \
  -d "pos.p2peEncrypted.sensitiveData=323030334130303041FFFF123ACE000440046030323131314330303134464646
  46313233414345303030343430303436313031303946414C5345" \
  -d "pos.p2peEncrypted.volatileData=34303033323038FB5018734EE1DE8A30423331342D3435312D34343030303030
  3130D2F732FE5E50BA2B9D3FEA3CCEBC172D"
Example 4: Verifone VSD Store and Forward Transaction

LRC byte flag and a secondary key set in 'pos.p2peEncrypted.sensitiveData'.

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment \
  -H "Authorization: Bearer MDhkNDVhYmNkZTEzYmQyNzZlMmEwNWNkN2IwYTlhYjM2RUE0OTM3QTA0NzE1N0RFOUZBQjlENkREMEExRjc5NA==" \
  -d "entityId=entity1pcx8d4abde3b7e205d70a9ab3" \
  -d "paymentType=DB" \
  -d "amount=100.00" \
  -d "currency=USD" \
  -d "pos.storeId=78123753" \
  -d "pos.terminalId=12195611" \
  -d "pos.entryMode=ICC" \
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" \
  -d "pos.p2peEncrypted.type=VERIFONE_VSD" \
  -d "pos.p2peEncrypted.ksn=FFFF123ACE0004400460" \
  -d "pos.p2peEncrypted.sensitiveData=323030334130303041FFFF123ACE000440046030323131314330303134464646
  46313233414345303030343430303436313031303946414C5345" \
  -d "pos.p2peEncrypted.persistableData=343030333230384D554309AA284B5A30423331342D3435312D34343030303030
  313079D21330CF35205D25CC533F232FA56F"
Example 5: Presto Online Transaction 
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment \
  -H "Authorization: Bearer MDhkNDVhYmNkZTEzYmQyNzZlMmEwNWNkN2IwYTlhYjM2RUE0OTM3QTA0NzE1N0RFOUZBQjlENkREMEExRjc5NA==" \
  -d "entityId=entity1pcx8d4abde3b7e205d70a9ab3" \
  -d "paymentType=DB" \
  -d "amount=100.00" \
  -d "currency=USD" \
  -d "pos.storeId=78123753" \
  -d "pos.terminalId=12195611" \
  -d "pos.entryMode=ICC" \
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" \
  -d "pos.p2peEncrypted.type=PRESTO" \
  -d "pos.p2peEncrypted.ksn=FFFFFFFF6572A4000015" \
  -d "pos.p2peEncrypted.volatileData=e060ca0affffffff6572a4000015cb30451739cf99c6ccccfecd373901cb1a1a
  9b76cf24754a2a75173755561e25d674db0358d50bc7908b063108afa10721f2
  cc20f0dd4b56ecd31e9411b452efbf135bf7573de2eefdda2d118e40441892c789e9"
Example 6: Ingenico OnGuard Online Transaction 
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment \
  -H "Authorization: Bearer MDhkNDVhYmNkZTEzYmQyNzZlMmEwNWNkN2IwYTlhYjM2RUE0OTM3QTA0NzE1N0RFOUZBQjlENkREMEExRjc5NA==" \
  -d "entityId=entity1pcx8d4abde3b7e205d70a9ab3" \
  -d "paymentType=DB" \
  -d "amount=100.00" \
  -d "currency=USD" \
  -d "pos.storeId=78123753" \
  -d "pos.terminalId=12195611" \
  -d "pos.entryMode=ICC" \
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" \
  -d "pos.p2peEncrypted.type=INGENICO_ONGUARD" \
  -d "pos.p2peEncrypted.ksn=FFFF98765400020002340500060000" \
  -d "pos.p2peEncrypted.volatileData=333030374330303030364644464442303231334929496658862016D140820184
  84309142177F444644423031344342343932393439303732343839323031365E
  4241524B45522F442020202020202020202020202020202020205E3134303832
  30313130383231313538393131333931363938313236383231333030" \
  -d "pos.p2peEncrypted.tlvMapping[DFDB02]=B"
Example 7: PAX Online Transaction 
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment \
  -H "Authorization: Bearer MDhkNDVhYmNkZTEzYmQyNzZlMmEwNWNkN2IwYTlhYjM2RUE0OTM3QTA0NzE1N0RFOUZBQjlENkREMEExRjc5NA==" \
  -d "entityId=entity1pcx8d4abde3b7e205d70a9ab3" \
  -d "paymentType=DB" \
  -d "amount=100.00" \
  -d "currency=USD" \
  -d "pos.storeId=78123753" \
  -d "pos.terminalId=12195611" \
  -d "pos.entryMode=ICC" \
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" \
  -d "pos.p2peEncrypted.type=PAX" \
  -d "pos.p2peEncrypted.ksn=F8765432100000000077" \
  -d "pos.p2peEncrypted.volatileData=DFDB041049C1994C3431D45DCAC5D4492BE1D0A0DFDB022049C1994C3431D45D
  CAC5D4492BE1D0A0B4A1A14903478ADAC8820BCB0AC8DBF9DFDB0140FE0E366F
  F616E7C383274282EE75A85ACC2E35F89B2F71BD19F402D2F0A27CC5CF3BAD65
  D0EE94ABE461C83638B464E03D5E7CFFE151A955284CC4B120EB8DF1"

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

Payment Identifier

Payment Identifier is compatible with the following message types:

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

  • card numbers longer than 19 numeric digits

  • gift cards

  • voucher numbers

  • loyalty card numbers

  • fleet card numbers

Parameter name Description Required Regex

card.paymentIdentifier

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

Required

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

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

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

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

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

Parameter name Description Required Regex

card.cvv

The card security code or CVV.

Required

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

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

Parameter name Description Regex

result.cvvResponse

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

A1
[A-Z]{1}

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

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

2.3.7. CVV2 Availability

CVV2 Availability is compatible with the following message types:

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

Parameter name Description Required Regex

pos.cvv2Availability

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

Required

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

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

2.3.8. Encrypted Pin

Encrypted Pin is compatible with the following message types:

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

Parameter name Description Required Regex

pos.encryptedPin.data

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

Required

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

pos.encryptedPin.ksn

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

Required

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

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

2.3.9. Alternative Currency

Alternative Currency is compatible with the following message types:

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

Parameter name Description Required Regex

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).
​
If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.
​
If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.
​
A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

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

currency

The currency code of the payment request’s amount (ISO 4217).
​
The default currency used is "USD".
​
For a Reversal, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction.

Required

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

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

2.3.10. Address Verification System

Address Verification System is compatible with the following message types:

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

Parameter name Description Required Regex

billing.street1

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

Required

ANS50
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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:

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
[\x20-\xFF]{1,50}

billing.street2

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

Optional

ANS50
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{1,50}

billing.from.street2

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

Optional

ANS50
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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:

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
[\x20-\xFF]{1,23}

merchant.city

The city of the merchant.

Required

ANS13
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{1,35}

merchant.phone

The phone number of the merchant.

Required

ANS35
[\x20-\xFF]{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:

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

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

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).
​
If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.
​
If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.
​
A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

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

cashbackAmount

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

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

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

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

2.3.14. Convenience Fee

Convenience Fee is compatible with the following message types:

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

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

amount

Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts).
​
If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount.
​
If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration.
​
A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

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

convenienceFee

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

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?
Example
Sample $21.00 transaction with a $0.50 convenience fee
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=PA"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2020"
	-d "amount=21.50"
	-d "convenienceFee=0.50"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"

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

2.3.15. Custom Parameters

Custom Parameters is compatible with the following message types:

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

Parameter name Description Required Regex

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Required

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

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

2.3.16. Debt Repayment

Debt Repayment is compatible with the following message types:

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

Parameter name Description Required Regex

debtRepayment

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

Required

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

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

2.3.17. Deferred Authorization

Compatible with the following message types:

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:

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:

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.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -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:

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

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.

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

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.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -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:

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

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.

A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator.
​
For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50.

Required

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -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:

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:

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

Parameter name Description Required Regex

pos.entryMode

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

Required

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

pos.fallbackReason

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

Optional

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

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

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

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

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

For example:

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

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

For example:

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

customer.orderNumber

The customer’s purchase order number.

Optional

ANS22
[\x20-\xFF]{1,22}

customer.customerCode

A code identifying the customer.

Optional

ANS20
[\x20-\xFF]{1,20}

merchant.vatNr

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

Optional

ANS20
[\x20-\xFF]{1,20}

merchant.refNr

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

Optional

ANS20
[\x20-\xFF]{1,20}

merchant.taxId

The merchant’s national tax number.

Optional

ANS20
[\x20-\xFF]{1,20}

merchant.streetAddress

A street address associated with the merchant or card acceptor.

Optional

ANS48 [\x20-\xFF]{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 [\x20-\xFF]{1,255}

merchant.customerServicePhoneNumber

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

Optional

ANS16 [\x20-\xFF]{1,16}

merchant.additionalContactInformation

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

Optional

ANS25 [\x20-\xFF]{1,25}

merchant.partnerIdCode

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

Optional

ANS6 [\x20-\xFF]{1,6}

merchant.serviceLocationCityName

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

Optional

ANS13 [\x20-\xFF]{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 [\x20-\xFF]{1,10}

merchant.geographicCoordinates

The geographic coordinates of the merchant/card acceptor.

Optional

NS20 ^[0-9., -]{1,20}$

merchant.serviceLocationGeographicCoordinates

The geographic coordinates of the location of the physical interaction with the customer.

Optional

NS20 ^[0-9., -]{1,20}$

customer.corporationVatNr

The merchant’s VAT number.

Optional

ANS20
[\x20-\xFF]{1,20}

customer.vatNr

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

Optional

ANS20
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{1,20}

taxCollected

Indicates whether tax was collected.

Optional

TRUE|FALSE|Y|N

card.commercialCardType

This field indicates the type of commercial card used.

Optional

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

discountAmountSign

Discount amount interpretation.

Optional

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

shippingAmountSign

Shipping amount interpretation.

Optional

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

dutyAmountSign

Duty amount interpretation.

Optional

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

customer.provincialSalesTaxRegistrationNr

Provincial Sales Tax Registration Number.

Optional

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

merchant.invoiceDiscountTreatment

Indicates how the merchant is managing discounts.

Optional

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

card.commercialCardType

This field indicates the type of commercial card used.

Optional

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

merchant.taxTreatment

Indicates how the merchant is handling taxes.

Optional

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

merchantOrderNumber

The merchant’s purchase order number.

Optional

ANS25
[\x20-\xFF]{1,25}

merchantInvoiceId

A unique invoice number associated with a transaction and supplied by the card acceptor.

Optional

ANS25
[\x20-\xFF]{1,30}

totalShippingAmount

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

Optional

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

shippingAmountSign

Shipping amount interpretation.

Optional

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

totalDutyAmount

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

Optional

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

dutyAmountSign

Duty amount interpretation.

Optional

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

totalDiscountAmount

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

Optional

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

discountAmountSign

Discount amount interpretation.

Optional

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

customer.provincialSalesTaxRegistrationNr

Provincial Sales Tax Registration Number.

Optional

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

taxAmounts[n].taxType

The type of tax.

Optional

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

taxAmounts[n].taxDescription

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

Optional

ANS20
[\x20-\xFF]{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
[\x20-\xFF]{1,20}

itemizedDiscounts[n].amount

The decimalized discount amount (e.g. 45.78).

Optional

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

itemizedDiscounts[n].rate

The discount rate. Three decimal places are implied.

Optional

ANS5
[\x20-\xFF]{1,5}

itemizedDiscounts[n].discountCode

The discount code supplied by the merchant.

Optional

ANS20
[\x20-\xFF]{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
[\x20-\xFF]{1,20}

cart.items[n].vatReferenceNr

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

Optional

ANS20
[\x20-\xFF]{1,20}

cart.items[n].supplyType

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

Optional

00|01

cart.items[n].sign

This sign applies a debit or credit sign.

Optional

CREDIT|DEBIT

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
[\x20-\xFF]{1,40}

cart.items[n].merchantItemId

The universal product code (UPC) of this item.

Optional

ANS20
[\x20-\xFF]{1,20}

cart.items[n].quantity

The decimalized quantity of the product. (e.g. 2.37 or 27.00).

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
[\x20-\xFF]{1,12}

cart.items[n].totalAmount

The decimalized total amount (e.g. 45.78).

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
[\x20-\xFF]{1,20}

cart.items[n].price

The decimalized unit price of the product (e.g. 2.37 or 27.00).

Optional

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

cart.items[n].discountAmount

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

Optional

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

cart.items[n].discount

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

Optional

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

The type of tax.

Optional

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

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

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

Optional

ANS20
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{1,5}

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

The discount code supplied by the merchant.

Optional

ANS20
[\x20-\xFF]{1,20}

cart.items[n]itemizedDiscounts[n].type

The discount type.

Optional

MANUFACTURER|​
STORE

cart.items[n].productCodeType

The type of code printed on the product.

Optional

UPC|​
PLU|​
SERVICE_OR_DELIVERY_CHARGES|​
PRODUCT_GROUP|​
DEPARTMENT

cart.items[n].classificationCode

The item classification code.

Optional

UNKNOWN|​
SNAP_ELIGIBLE|​
ALCOHOL|​
TOBACCO

cart.items[n].categoryCode

A code used to identify the product/produce item at a macro level (eg milk).

Optional

AN10
[a-zA-Z0-9]{1,10}

cart.items[n].subCategoryCode

A code used to identify the product/produce item at a micro level (eg skim).

Optional

AN10
[a-zA-Z0-9]{1,10}

cart.items[n].quantityOfPackageMeasure

Used to indicate the quantity within a package when the line item refers to a set of items, eg. for one dental floss package where the package contains a set of 4 dental flosses, this field should be 4.

Optional

N12
[1-9][0-9]{0,11}

cart.items[n].additionalData[n].key

The additional data key.

Optional

ANS99
[\x20-\xFF]{1,99}

cart.items[n].additionalData[n].value

The additional data value.

Optional

ANS999
[\x20-\xFF]{1,999}
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 "merchant.geographicCoordinates=5.78381,0.72175"
	-d "merchant.serviceLocationGeographicCoordinates=6.78381,0.72176"
	-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].productCodeType=UPC"
	-d "cart.items[0].classificationCode=SNAP_ELIGIBLE"
	-d "cart.items[0].categoryCode=Milk"
	-d "cart.items[0].subCategoryCode=Skim"
	-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"
	-d "cart.items[0].itemizedDiscounts[0].type=MANUFACTURER"
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:

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]{1,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
[\x20-\xFF]{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_]{1,17}

fleet.driverId

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

Optional

..ANS20
[\x20-\xFF]{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
[\x20-\xFF]{1,3}

fleet.privateData

Any data proprietary to the system for this item.

Optional

..ANS999
[\x20-\xFF]{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
[\x20-\xFF]{1,20}

fleet.prompts[n].vehicleId

The vehicle identification number.

Optional

..ANS20
[\x20-\xFF]{1,20}

fleet.prompts[n].department

The department number.

Optional

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

fleet.prompts[n].driverLicense

The driver license number.

Optional

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

fleet.prompts[n].customerData

Any customer data.

Optional

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

fleet.prompts[n].customerData1

Any customer data.

Optional

..ANS20
[\x20-\xFF]{1,20}

fleet.prompts[n].customerData2

Any additional customer data.

Optional

..ANS20
[\x20-\xFF]{1,20}

fleet.prompts[n].cashBackAmount

Represents the cashback amount in the minor denomination of the currency. For example, a value of 4544 denotes 45.44 in a currency with two decimal places.

Optional

..N12
[0-9]{1,12}

fleet.prompts[n].siteTransactionNumber

The site transaction number.

Optional

..N12
[0-9]{1,12}

fleet.prompts[n].jobId

The job identification number.

Optional

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

fleet.prompts[n].contractNumber

The contract number.

Optional

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

fleet.prompts[n].PIN

The vehicle PIN number.

Optional

..ANS6
[\x20-\xFF]{1,6}

fleet.prompts[n].tripNumber

The fleet trip number.

Optional

..ANS15
[\x20-\xFF]{1,15}

fleet.prompts[n].unitNumber

The fleet unit number.

Optional

..ANS15
[\x20-\xFF]{1,15}

fleet.prompts[n].trailerId

The fleet trailer identification.

Optional

..ANS16
[\x20-\xFF]{1,16}

fleet.prompts[n].trailerHours

The fleet trailer hours number.

Optional

..N6
[0-9]{1,6}

fleet.prompts[n].maintenanceId

The fleet maintenance identification.

Optional

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

fleet.prompts[n].hubometer

The fleet hubometer number.

Optional

..N9
[0-9]{1,9}

fleet.prompts[n].employeeNumber

The fleet employee number.

Optional

..N20
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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:

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

Parameter name Description Required Regex

referencedPaymentId

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

Required

ANS32
[\x20-\xFF]{1,32}
Example
An example scenario follows:

  1. An initial PA request is submitted for the transaction.

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

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

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

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

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

ConnectUP supports sending the following CIT and MIT transactions:

Initiated transaction type Required parameters

CIT First Transaction

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

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

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to CIT.

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

CIT First Recurring Transaction

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

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

  • Set standingInstruction.type to RECURRING.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to CIT.

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

CIT First Recurring Installment Transaction

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

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

  • Set standingInstruction.type to INSTALLMENT.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to CIT.

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

CIT Subsequent Transaction

(The cardholder is using a stored credential.)

  • Set pos.entryMode to CREDENTIAL_ON_FILE.

  • Set standingInstruction.mode to REPEATED.

  • Set standingInstruction.source to CIT.

  • Provide the saved bank-specific fields in the request customParameters field.

MIT Unscheduled Transaction

(The merchant using a stored credential as needed.)

  • Set pos.entryMode set to CREDENTIAL_ON_FILE.

  • Set standingInstruction.type to UNSCHEDULED.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to MIT.

  • Provide the saved bank-specific fields in the request customParameters field.

MIT First Recurring Transaction

(The merchant initiating a series of recurring transactions.)

  • Set pos.entryMode to CREDENTIAL_ON_FILE.

  • Set standingInstruction.type to RECURRING.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to MIT.

  • Provide the saved bank-specific fields in the request customParameters field.

MIT first recurring installment transaction

(The merchant initiating a series of recurring installment transactions.)

  • Set pos.entryMode to CREDENTIAL_ON_FILE.

  • Set standingInstruction.type to INSTALLMENT.

  • Set standingInstruction.mode to INITIAL.

  • Set standingInstruction.source to MIT.

  • Provide the saved bank-specific fields in the request customParameters fields.

Industry practice of Delayed Charges

  • Set pos.entryMode to CREDENTIAL_ON_FILE.

  • Set standingInstruction.source to MIT.

  • Set standingInstruction.industryPractice to DELAYED_CHARGES.

The following fields are supported for previously listed MIT/CIT features:

Parameter name Description Required Regex

standingInstruction.mode

The Standing Instruction mode identifying whether this is the first transaction or a subsequent transaction in a series.
​
This field must be set to INITIAL for CIT Initial requests and Unscheduled MIT requests.
​
This field must be set to REPEATED for CIT Subsequent (pos.entryMode is set to CREDENTIAL_ON_FILE) and Recurring/Installment MIT requests.

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

standingInstruction.amountType

The Standing Instruction recurring payment amount type, which indicates whether the amount is at a fixed rate, a variable rate or at its maximum.

Optional

FIXED|VARIABLE|MAXIMUM_AMOUNT
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"
	-d "standingInstruction.amountType=FIXED"
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 "standingInstruction.amountType=FIXED"
	-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:

ConnectUP supports sending multiple capture (CP) messages for a single authorization (PA). It is used to incrementally capture an authorization.

Merchants are able to submit multiple, partially-clearing capture notifications for the single authorization by adding a Capture Sequence number. This value indicates the number of the CP message in a sequence of multiple CP messages.

Note
 Subsequent captures must reference the original PA message’s id in the referencedPaymentId field.
Parameter name Description Required Regex

captureSequence

Used to indicate the sequence number for a capture in a chain of linked captures or completions.

Required

N2
[0-9]{2}

lastCapture

When this flag is set to true, it indicates that the last capture or completion in the chain is being sent.

Optional

true
Example

An example for a Multiple Capture sequence might be an order that contains multiple items to ship. For each shipment, the merchant can perform a partial capture on the original pre-authorization message for the goods being delivered.

A multiple capture scenario follows:

  1. Send an initial authorization request for the total amount intended for the transaction.

  2. Fulfill half the order and partially capture one half the original initial authorization.

  3. Fulfill the remainder of the order and partially capture the remaining amount of the original authorization.

Initial Authorization Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=PA"
	-d "card.track2Data=5416389123456786D22021010000081315000"
	-d "amount=100.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Response of the Initial Authorization
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "100.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "783276"
    },
    "timestamp" : "2019-09-06 12:00:00"
}
First Partial Capture Request

This is the first CP request referencing the PA’s `id in the referencedPaymentId field; specifying 25.00 USD. The captureSequence field is set to 01 indicating that this is the first CP in a chain.

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=CP"
	-d "card.track2Data=5416389123456786D22021010000081315000"
	-d "amount=25.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "captureSequence=01"
	-d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50"
Response of the First Capture Request
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "50.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "456464"
    },
    "timestamp" : "2019-09-07 12:00:00"
}
Final Partial Capture Request

This is the last CP request, again referencing the PA’s `id in the referencedPaymentId field, this time specifying 75.00 USD. The captureSequence field is set to 02, indicating that this is the second CP in the chain. The lastCapture field is set to true, indicating that this is the final CP message in the chain.

curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
 	-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
 	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "paymentType=CP"
	-d "card.track2Data=5416389123456786D22021010000081315000"
	-d "amount=75.00"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-d "captureSequence=02"
	-d "lastCapture=true"
	-d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50"
Response of the Final Capture Request
{
    "id" : "e8f59d02a466f35a7ece785d3e137e50",
    "amount" : "75.00",
    "currency" : "USD",
    "result": {
        "code" : "000.000.000",
        "description" : "Transaction succeeded",
        "authorizationId" : "7698987"
    },
    "timestamp" : "2019-09-10 12:00:00"
}

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

2.3.29. Partial Approval

Compatible with the following message types:

To allow partially approved transactions, add the following parameter to your payment message.

Note
 If partialApprovalAllowed is set to false, the parameter will have no effect on the payment.
Parameter Name Description Required Regex

partialApprovalAllowed

When this flag is set to true, it indicates that partially approved authorizations are acceptable to the client.

Required

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

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

2.3.30. Payment Identifier

Payment Identifier is compatible with the following message types:

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

  • card numbers longer than 19 numeric digits

  • gift cards

  • voucher numbers

  • loyalty card numbers

  • fleet card numbers

Parameter name Description Required Regex

card.paymentIdentifier

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

Required

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

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

2.3.31. PIN-less Debit

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

PIN-less debit attempts to route debit card transactions as debit transactions at the processor level without requiring cardholders to enter their PIN. This is typically applicable to signature debit and bill pay credit transactions and offers merchants an alternative method of accepting debit card payments.

Parameter name Description Required Regex

card.pinlessDebit

A flag that is used to attempt to route a transaction as debit at the processor level.

Required

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

The PIN-less debit response parameter will contain the route (DEBIT or CREDIT) used by the processor for the transaction.

Parameter name Description Regex

card.pinlessDebit

Indicates whether the transaction was processed as a credit or a debit transaction by the processor.

CREDIT|DEBIT
Response containing the PIN-less Debit response parameter
{
  "id" : "e8f59d02a466f35a7ece785d3e137e50",
  "amount" : "75.00",
  "currency" : "USD",
  "result": {
    "code" : "000.000.000",
    "description" : "Transaction succeeded",
    "authorizationId" : "783276"
  },
  "card" : {
    "pinlessDebit": "DEBIT"
  },
  "timestamp" : "2019-09-06 12:22:44"
}

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

2.3.32. Point-of-Sale (POS) Data Fields

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

ConnectUP provides the functionality to indicate specific conditions that were present at the time a transaction took place at the point-of-service (POS).

If present, the lower-level POS fields that are listed here will override any POS conditions that might have otherwise been inferred when constructing any standard ConnectUP message.

Parameter name Description Required Regex

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

UNKNOWN|​
MANUAL|​
MAGSTRIPE|​
OCR|​
BARCODE|​
ICC|​
KEY_ENTRY|​
NFC_ICC|​
NFC_MAGSTRIPE

pos.cardDataInputCapability

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

Optional

UNKNOWN|​
MANUAL_NO_TERMINAL|​
MAGSTRIPE|​
BARCODE|​
OCR|​
MAGSTRIPE_MANUAL_ICC|​
MANUAL|​
MAGSTRIPE_MANUAL|​
MAGSTRIPE_ICC|​
ICC|​
NFC_ICC|​
MAGSTRIPE_MANUAL_ICC_NFC|​
NFC_MAGSTRIPE

pos.cardholderAuthenticationCapability

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

Optional

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

pos.cardCaptureCapability

Indicates if the point-of-service can capture cards. If not sent in the request, it is assumed that the point-of-service cannot capture cards.

Optional

NONE|CAPTURE

pos.operatingEnvironment

Indicates the environment in which the point-of-service is operating. If not inferred by pos.entryMode, transactionCategory or set to a value directly, the MERCHANT_UNATTENDED value is used.

Optional

NO_TERMINAL|​
MERCHANT_ATTENDED|​
MERCHANT_UNATTENDED|​
OFFSITE_ATTENDED|​
OFFSITE_UNATTENDED|​
CUSTOMER_UNATTENDED

pos.cardholderPresent

Indicates if the cardholder is present at the time the transaction is performed. If not inferred by pos.entryMode or transactionCategory, CARD_HOLDER_PRESENT is used.

Optional

CARD_HOLDER_PRESENT|​
CARD_HOLDER_NOT_PRESENT

pos.cardPresent

Indicates if the card is present at the time the transaction is performed. If not inferred by pos.entryMode or transactionCategory, CARD_PRESENT is used.

Optional

CARD_PRESENT|​
CARD_NOT_PRESENT

pos.cardholderAuthenticationMethod

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

Optional

NONE|​
PIN|​
ELECTRONIC_SIGNATURE|​
BIOMETRIC|​
INOPERATIVE|​
OTHER|​
CDCVM|​
CDCVM_CODE|​
CDCVM_PATTERN|​
CDCVM_BIOMETRIC|​
UNKNOWN|​

pos.cardholderAuthenticationEntity

Indicates the entity that authenticated the cardholder at the point-of-service. If not inferred to AUTHORIZING_AGENT by pos.cardholderAuthenticationMethod or by the presence of PIN data, NOT_AUTHENTICATED is used.

Optional

NOT_AUTHENTICATED|​
ICC|​
TERMINAL|​
AUTHORIZING_AGENT|​
MERCHANT|​
OTHER

pos.cardDataOutputCapability

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

Optional

MAGSTRIPE|​NONE|​ICC|​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

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

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:

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:

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

Optional

VOID|TIMEOUT|MAC|STORE_CONTROLLER|STANDIN_PROCESSING|CARD_ISSUER_UNAVAILABLE|UNDER_FLOOR_LIMIT|PIN_RELATED_FAILURE|CHANGE_DISPENSED|IOU_RECEIPT_PRINTED|MANUAL_ADJUSTMENT_REQUIRED|ACQUIRER_VOICE_AUTH_REQUIRED|FORCED_TRANSACTION_ACCEPTANCE|EMV_APPROVED_AFTER_ONLINE|FRAUD_SERVICE_BLOCK|OVER_FLOOR_LIMIT|NEGATIVE_CARD|UNSPECIFIED|COMPLETED_PARTIALLY|UNABLE_TO_DELIVER|SUSPECTED_MALFUNCTION|INVALID_RESPONSE|INVALID_CVV2|INVALID_ADDRESS|MERCHANT_CANCELLATION|BLOCKED_DEVICE|DEVICE_UNIDENTIFIABLE|DECRYPTION_FAILURE|UNEXPECTED_TRANSACTION_DATA|DECLINED_AFTER_RISK_ANALYSIS
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:

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 capture/reversal.

Required

VOID|TIMEOUT|MAC|STORE_CONTROLLER|STANDIN_PROCESSING|CARD_ISSUER_UNAVAILABLE|UNDER_FLOOR_LIMIT|PIN_RELATED_FAILURE|CHANGE_DISPENSED|IOU_RECEIPT_PRINTED|MANUAL_ADJUSTMENT_REQUIRED|ACQUIRER_VOICE_AUTH_REQUIRED|FORCED_TRANSACTION_ACCEPTANCE|EMV_APPROVED_AFTER_ONLINE|FRAUD_SERVICE_BLOCK|OVER_FLOOR_LIMIT|NEGATIVE_CARD|UNSPECIFIED|COMPLETED_PARTIALLY|UNABLE_TO_DELIVER|SUSPECTED_MALFUNCTION|INVALID_RESPONSE|INVALID_CVV2|INVALID_ADDRESS|MERCHANT_CANCELLATION|BLOCKED_DEVICE|DEVICE_UNIDENTIFIABLE|DECRYPTION_FAILURE|UNEXPECTED_TRANSACTION_DATA|DECLINED_AFTER_RISK_ANALYSIS
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:

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, CP or stored value transaction that is to be reversed.

Required

ANS255
[\x20-\xFF]{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:

SCA is required when certain limits are exceeded for contactless payments. An issuer will decide if SCA must be applied. If SCA is required, the transaction will be declined.

Merchants can apply for an exemption by specifying an SCA exemption flag in request messages which informs upstream entities of a terminal’s single tap with PIN capabilities. This field is also used when a PIN is provided to satisfy an SCA request.

Parameter name Description Required Regex

pos.scaExemptionFlag

Used for NFC transactions. Upstream entities decide whether the cardholder must provide alternative authentication to complete the transaction based on the value set in this field, along with other transaction data.
​
Possible values are:
PIN_PROVIDED (PIN Provided for SCA request)​
TAP_AND_PIN_SUPPORTED (Single Tap with PIN supported)

Required

PIN_PROVIDED|​
TAP_AND_PIN_SUPPORTED
SCA Response

If SCA is required, the following result codes can be expected in the response body result.code parameter:

Parameter name Description Required Regex

result.code

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

See the SCA Result Code table for details.

Required

AN11
[0-9\.]{2,11}
SCA Result Code Listing
Result code Description

300.100.100

Transaction declined (additional customer authentication required)

300.100.190

Transaction declined (Issuer Requires PIN [SCA])

300.100.191

Transaction declined (SCA exemption is invalid)

300.100.192

Transaction declined (additional customer authentication required)
Tip
 See the standard response fields for a list of possible response parameters that ConnectUP can return for this request type.
Example

An example scenario for SCA for terminals that support Single Tap and PIN, where the customer withdrawal frequency has been exceeded, follows:

  1. A standard contactless pre-authorization message is sent with pos.scaExemptionFlag = TAP_AND_PIN_SUPPORTED.

  2. The upstream entity responds with the 300.100.190: Transaction declined (Issuer Requires PIN [SCA]) result code.

  3. The terminal updates the message with the provided PIN.

  4. A new payment message with PIN is sent to ConnectUP.

  5. The pos.scaExemptionFlag field is updated to PIN_PROVIDED

  6. No further exemption will be applied to transactions that contain PIN data.

Initial contactless request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=10000000.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=NFC_ICC"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "pos.scaExemptionFlag=TAP_AND_PIN_SUPPORTED"
Response indicating the declined transaction due to the issuer requesting SCA
{
  "id" : "e8f59d02a466f35a7ece785d3e137e50",
  "amount" : "0.00",
  "currency" : "USD",
  "result": {
    "code" : "300.100.190",
    "description" : "Transaction declined (Issuer Requires PIN [SCA])",
    "authorizationId" : "783276"
  },
  "timestamp" : "2019-09-06 12:22:44"
}
Secondary contactless request with PIN data to satisfy the exemption
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=PA"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2050"
  -d "amount=10000000.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=NFC_ICC"
  -d "pos.encryptedPin.data=A3929E6A25E8E32C"
  -d "pos.encryptedPin.ksn=*"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "pos.scaExemptionFlag=PIN_PROVIDED"
Note
 For terminals that do not support single tap and PIN, the customer will have to re-present their card and enter a PIN. This data must be present in the second payment message with pos.scaExemptionFlag set to PIN_PROVIDED, as previously illustrated.

2.3.38. Shipping Contact

Shipping Contact is compatible with the following message types:

To specify the contact details of the shipping sender or receiver, use the following fields.

The shipping.* fields must be used for the customer which receiving the shipment. The shipping.from.* fields must be used for the merchant/retailer which is sending the shipment.

Parameter name Description Required Regex

shipping.street1

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

Optional

ANS50
[\x20-\xFF]{1,50}

shipping.street2

The adjoining road or locality (if required) of the shipping address.

Optional

ANS50
[\x20-\xFF]{1,50}

shipping.method

The shipping method.

Optional

CARRIER_DESIGNATED_BY_CUSTOMER|​
ELECTRONIC_DELIVERY|​
EXPEDITED|​
GROUND|​
INTERNATIONAL|​
LOWEST_COST|​
MILITARY|​
NEXT_DAY_OVERNIGHT|​
OTHER, STORE_PICKUP|​
PUDO|​
SAME_DAY_SERVICE|​
TWO_DAY_SERVICE|​
THREE_DAY_SERVICE

shipping.warehouse

The warehouse that received the order.

Optional

ANS100
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{1,50}

shipping.customer.middleName

The middle name of the shipping customer.

Optional

{shipping_customer_middleName_regex}

shipping.customer.surname

The last name or surname of the shipping customer.

Optional

ANS50
[\x20-\xFF]{1,50}

shipping.customer.idType

The type of identification associated with the identification number of the billing/shipping customer.

Optional

ANS50
[\x20-\xFF]{1,50}

shipping.customer.idNumber

The identification number of the billing/shipping customer.

Optional

ANS24
[\x20-\xFF]{1,24}

shipping.customer.email

The shipping customer’s email address. This is required for some risk checks and transmission of direct debit mandates.

Optional

ANS128
[\x20-\xFF]{6,128}

shipping.customer.companyName

The company name to contact.

Optional

ANS50
[\x20-\xFF]{1,50}

shipping.from.street1

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

Optional

ANS50
[\x20-\xFF]{1,50}

shipping.from.street2

The adjoining road or locality (if required) of the shipping address.

Optional

ANS50
[\x20-\xFF]{1,50}

shipping.from.warehouse

The warehouse that received the order.

Optional

ANS100
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{1,50}

shipping.from.customer.middleName

The middle name of the shipping customer.

Optional

{shipping_customer_middleName_regex}

shipping.from.customer.surname

The last name or surname of the shipping customer.

Optional

ANS50
[\x20-\xFF]{1,50}

shipping.from.customer.idType

The type of identification associated with the identification number of the billing/shipping customer.

Optional

ANS50
[\x20-\xFF]{1,50}

shipping.from.customer.idNumber

The identification number of the billing/shipping customer.

Optional

ANS24
[\x20-\xFF]{1,24}

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
[\x20-\xFF]{6,128}

shipping.from.customer.companyName

The company name to contact.

Optional

ANS50
[\x20-\xFF]{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.middleName=M"
  -d "shipping.customer.surname=Smith"
  -d "shipping.customer.idType=SSN"
  -d "shipping.customer.idNumber=537-48-9216"
  -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.middleName=P"
  -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:

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.

2.3.40. Electronic Benefits Transfer (EBT)

EBT is compatible with the following message types:

ConnectUP supports sending and receiving EBT data. The card.accountType should be set to either EBT_CASH_BENEFIT or EBT_FOOD_STAMP. When sending ebt data, ebt.incentives must be specified using an indexed-number [n], starting with 0.

Parameter name Description Required Regex

card.accountType

card.accountType

Required

EBT_CASH_BENEFIT|​
EBT_FOOD_STAMP

ebt.voucherNumber

A unique identifier assigned to the EBT voucher or transaction.

Optional

ANS..15
[\x20-\xFF]{1,15}

ebt.caseNumber

The unique identifier for the case.

Optional

ANS..27
[\x20-\xFF]{1,27}

ebt.incentives[n].type

The type of incentive earned for this transaction, e.g. HIP.

Optional

ANS..20
[\x20-\xFF]{1,20}

ebt.incentives[n].eligibleAmount.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.incentives[n].eligibleAmount.amount

The 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

N7.N4
[0-9]{1,7}(\.[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= 6012345678901234"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "card.accountType=EBT_CASH_BENEFIT"
	-d "amount=16.50"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MAGSTRIPE"
	-d "ebt.voucherNumber=V_73737"
	-d "ebt.caseNumber=283746_fjf3r121"
	-d "ebt.incentives[0].type=HIP"
	-d "ebt.incentives[0].eligibleAmount.indicator=CREDIT"
	-d "ebt.incentives[0].eligibleAmount.amount=16.50"
	-d "ebt.incentives[1].type=TBD"
	-d "ebt.incentives[1].eligibleAmount.indicator=CREDIT"
	-d "ebt.incentives[1].eligibleAmount.amount=34.50"
Response

The payment response may contain EBT related data.

Parameter name Description Required Regex

ebt.text

The full response text sent by the EBT provider.

Optional

ANS..65
[\x20-\xFF]{1,65}

ebt.traceData

Trace data sent by the EBT provider.

Optional

ANS..22
[\x20-\xFF]{1,22}

ebt.caseNumber

The unique identifier for the case.

Optional

ANS..27
[\x20-\xFF]{1,27}

ebt.voucherNumber

A unique identifier assigned to the EBT voucher or transaction.

Optional

ANS..15
[\x20-\xFF]{1,15}

ebt.beginningFoodStampAccountBalance.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.beginningFoodStampAccountBalance.amount

The 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

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

ebt.endingFoodStampAccountBalance.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.endingFoodStampAccountBalance.amount

The 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

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

ebt.availableFoodStampAccountBalance.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.availableFoodStampAccountBalance.amount

The 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

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

ebt.beginningCashBenefitsAccountBalance.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.beginningCashBenefitsAccountBalance.amount

The 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

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

ebt.endingCashBenefitsAccountBalance.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.endingCashBenefitsAccountBalance.amount

The 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

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

ebt.availableCashBenefitsAccountBalance.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.availableCashBenefitsAccountBalance.amount

The 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

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

ebt.incentives[n].type

The type of incentive earned for this transaction, e.g. HIP.

Optional

ANS..20
[\x20-\xFF]{1,20}

ebt.incentives[n].balance.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.incentives[n].balance.amount

The 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

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

ebt.incentives[n].earned.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.incentives[n].earned.amount

The 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

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

ebt.incentives[n].earnedMTD.indicator

Indicates whether the amount is debit, credit or unknown.

Optional

DEBIT | CREDIT | UNKNOWN

ebt.incentives[n].earnedMTD.amount

The 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

N7.N4
[0-9]{1,7}(\.[0-9]{1,4})?
Sample Response Containing EBT 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"
  },
  "ebt": {
    "text": "Dear customer, your EBT balance is $123.45.",
    "traceData": "Transaction succ(00)",
    "beginningFoodStampAccountBalance": {
      "indicator": "CREDIT",
      "amount": "850.00"
    },
    "endingFoodStampAccountBalance": {
      "indicator": "CREDIT",
      "amount": "850.00"
    },
    "availableFoodStampAccountBalance": {
      "indicator": "CREDIT",
      "amount": "850.00"
    },
    "beginningCashBenefitsAccountBalance": {
      "indicator": "CREDIT",
      "amount": "850.00"
    },
    "endingCashBenefitsAccountBalance": {
      "indicator": "CREDIT",
      "amount": "850.00"
    },
    "availableCashBenefitsAccountBalance": {
      "indicator": "CREDIT",
      "amount": "850.00"
    },
    "caseNumber": "EBT123456",
    "voucherNumber": "ABC123_567890",
    "incentives": [
      {
        "balance": {
          "indicator": "CREDIT",
          "amount": "850.00"
        },
        "earned": {
          "indicator": "CREDIT",
          "amount": "850.00"
        },
        "earnedMTD": {
          "indicator": "CREDIT",
          "amount": "850.00"
        },
        "type": "HIP"
      },
      {
       "balance": {
          "indicator": "CREDIT",
          "amount": "850.00"
        },
        "earned": {
          "indicator": "CREDIT",
          "amount": "850.00"
        },
        "earnedMTD": {
          "indicator": "CREDIT",
          "amount": "850.00"
        },
        "type": "TBD"
      }
    ]
  },
  "resultDetails": {
    "iso8583ResponseCode": "00"
  },
  "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.41. Check Data

Check Data is compatible with the following message types:

ConnectUP supports check data, which includes check.*, check.customer.*, check.genericId.*, check.driversLicense.*, check.formattedMicr.* . A check authorization can have more than one check. When sending Check data, check must be specified using an indexed-number [n], starting with 0.

For example:

check[0].type = PERSONAL
Parameter Name Description Required Regex

check[n].type

The check type (typically entered manually).

Optional

PERSONAL|​
PAYROLL|​
BUSINESS|​
GOVERNMENT|​
BANK|​
OTHER

check[n].idCard

Indicates whether the info in the card field pertains to a check ID card or not.

Optional

TRUE|FALSE

check[n].idCrossChecked

Indicates whether the original ID produced by the customer was cross checked with a second ID.

Optional

TRUE|FALSE

check[n].supervisorId

The ID of the supervisor.

Optional

ANS24
[\x20-\xFF]{24}

check[n].formattedMicr.checkNr

The check number (from the MICR data).

Required

N10
[0-9]{1,10}

check[n].formattedMicr.transitNr

The code of the institution that issued the check (from the MICR data). In the USA this is the ABA number, also called the routing-and-transit number.

Required

N8
[0-9]{1,8}

check[n].formattedMicr.transitNrCheckDigit

The check digit of the institution code (from the MICR data).

Optional

N1
[0-9]{0,1}

check[n].formattedMicr.accountNr

The account number (from the MICR data).

Required

N28
[0-9]{1,28}

check[n].unformattedMicr

The MICR data as present on the check, including the separator characters.

Optional

ANS65
[\x20-\xFF]{0,65}

check[n].micrKeydOrScanned

Indicates whether the magnetic ink character recognition (MICR) data is keyed or scanned.

Optional

KEYED|SCANNED

check[n].micrLineFormatCode

Indicates the format of the magnetic ink character recognition (MICR) data.

Optional

N2
[0-9]{0,2}

check[n].micrSequenceNr

The sequence number of the magnetic ink character recognition (MICR).

Optional

ANS3
[\x20-\xFF]{0,3}

check[n].driversLicense.nr

The driver’s license number.

Required

ANS24
[\x20-\xFF]{1,24}

check[n].driversLicense.stateCode

Driver’s license numbers are unique per region code. In the USA, driver’s licenses are issued by states, so this will be the state code

Optional

ANS2
[\x20-\xFF]{0,2}

check[n].driversLicense.dateOfBirth

The date of birth as seen on the driver’s license.

Optional

YYYY-MM-DD

check[n].driversLicense.expirationDate

The expiration date of the driver’s license.

Optional

YY-MM

check[n].driversLicense.KeyedOrScanned

Indicates whether the driver’s license information was keyed or scanned.

Optional

KEYED|​
SCANNED

check[n].genericId.idNr

The ID number of the customer.

Required

ANS24
[\x20-\xFF]{1,24}

check[n].genericId.idType

The ID type of the customer

Required

PASSPORT|​
IDENTITY_DOCUMENT|​
SOCIAL_SECURITY_NUMBER|​
NATIONAL_INSURANCE_NUMBER​

check[n].issueDate

The date the transaction was issued.

Optional

YYYY-MM-DD

check[n].timeProcessed

The time which the transaction was processed.

Optional

hh:mm

check[n].clerkId

The identification of the clerk who processed the transaction.

Optional

ANS9
[\x20-\xFF]{0,9}

check[n].truncationTransactionId

The truncation transaction identifier of the check.

Optional

ANS12
[\x20-\xFF]{0,12}

check[n].truncationIndicator

Indicates whether check processing should happen via check truncation.

Optional

A1

check[n].denialNr

The denial number, or level of risk received by the processing bank for declined transactions.

Optional

ANS7
[\x20-\xFF]{0,7}

check[n].settlementCode

Settlement Code returned by Visa to indicate if the transaction is to be settled. Used for Visa eChecks.

Optional

VISA|ACH

check[n].name

A descriptive name for the check.

Optional

ANS32
[\x20-\xFF]{0,32}

check[n].customer.name

The full name of the customer, as found on the check.

Optional

ANS30
[\x20-\xFF]{0,30}

check[n].customer.firstName

The first name of the customer, as found on the check.

Optional

ANS30
[\x20-\xFF]{0,30}

check[n].customer.lastName

The last name of the customer, as found on the check.

Optional

ANS30
[\x20-\xFF]{0,30}

check[n].customer.middleInitial

The middle initial of the customer, as found on the check.

Optional

ANS1
[\x20-\xFF]{0,1}

check[n].customer.initials

The full initials of the customer, as found on the check.

Optional

ANS4
[\x20-\xFF]{0,4}

check[n].customer.phoneNumber

The phone number of the customer, as found on the check.

Optional

N10
[0-9]{0,10}

check[n].customer.address

The street address of the customer, as found on the check.

Optional

ANS24
[\x20-\xFF]{0,24}

check[n].customer.city

The city of the customer, as found on the check.

Optional

ANS20
[\x20-\xFF]{0,20}

check[n].customer.state

The state of the customer, as found on the check.

Optional

A2
[A-Z]{2}

check[n].customer.zip

The zip code of the customer, as found on the check.

Optional

ANS10
[\x20-\xFF]{0,10}

check[n].traceId

A 6-digit value that is unique within the location and business day. Format: left justified with spaces on the right.

Optional

N22
[0-9]{0,22}

check[n].ecaAction

This value describes the Electronic Check Acceptance (ECA) Action.

Optional

ACCEPT|​
CHANGE|​
DECLINE|​
ID_FREE|​
PAYMENT_ON_ACCOUNT|​
RETURN|​
SALE|​
CHECKRITE_TWO_PARTY_PAYROLL|​
VOID|​
CHECKRITE_CROSS_REFERENCE

check[n].issuanceDate

This field contains the date the check was written on.
Required for Payroll checks.

Optional

YYYY-MM-DD

check[n].terminalEntryCapability

This value describes the entry mode of the terminal.

Optional

MICR_SCANNED|​
MICR_SCANNED_IMAGE_CAPABILITY
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=CC"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "check[0].type=PERSONAL"
  -d "check[0].idCard=TRUE"
  -d "check[0].idCrossChecked=TRUE"
  -d "check[0].supervisorId=SVI1248"
  -d "check[0].formattedMicr.checkNr=123456"
  -d "check[0].formattedMicr.transitNr=21212121"
  -d "check[0].formattedMicr.transitNrCheckDigit=3"
  -d "check[0].formattedMicr.accountNr=3388257"
  -d "check[0].unformattedMicr=12456"
  -d "check[0].micrKeydOrScanned=KEYED"
  -d "check[0].micrLineFormatCode=12"
  -d "check[0].micrSequenceNr=A12"
  -d "check[0].driversLicense.nr=80807985"
  -d "check[0].driversLicense.stateCode=ZA"
  -d "check[0].driversLicense.dateOfBirth=1989-06-15"
  -d "check[0].driversLicense.expirationDate=26-05"
  -d "check[0].driversLicense.KeyedOrScanned=KEYED"
  -d "check[0].genericId.idNr=PASS30895785"
  -d "check[0].genericId.idType=PASSPORT"
  -d "check[0].issueDate=2024-04-30"
  -d "check[0].timeProcessed=11:35"
  -d "check[0].clerkId=CLR12"
  -d "check[0].truncationTransactionId=895645895645"
  -d "check[0].truncationIndicator=A"
  -d "check[0].denialNr=0000078"
  -d "check[0].settlementCode=VISA"
  -d "check[0].name=ABCDBK CAPE"
  -d "check[0].customer.name=John Smith"
  -d "check[0].customer.firstName=John"
  -d "check[0].customer.lastName=Smith"
  -d "check[0].customer.middleInitial=S"
  -d "check[0].customer.initials=JSS"
  -d "check[0].customer.phoneNumber=8888888888"
  -d "check[0].customer.address=MG Road"
  -d "check[0].customer.city=CAPE TOWN"
  -d "check[0].customer.state=ZZ"
  -d "check[0].customer.zip=444444"
  -d "check[0].traceId=878787"
  -d "check[0].ecaAction=ACCEPT"
  -d "check[0].issuanceDate=2024-04-30"
  -d "check[0].terminalEntryCapability=MICR_SCANNED"
Response

The payment response may contain CHECK related data.

Parameter name Description Required Regex

check.serviceCharge

The service charge of the transaction. Values are expressed in the minor denomination (e.g. cents).

Optional

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

check.proprietaryResponseInfo

The information provided by the Proprietor.

Optional

N12
[0-9]{0,12}

check.ecaTransactionStatus

Indicator for processing checks via check truncation. Returned in response.

Optional

KEEP_PAPER_CHECK|​
PRINT_ECA_RECEIPT

check.denialRecordNr

Denial Number or level of risk received by the processing bank for declined transactions. Returned in the response by processor.

Optional

AN7
^[A-Za-z0-9]{0,7}$

check.telecheckMicrSequenceNr

The MICR Sequence Number received in the response from the processor.

Optional

AN3
^[A-Za-z0-9]{0,7}$
Response
{
    "amount": "200.00",
    "currency": "USD",
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded",
        "authorizationId": "071797"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    },
    "check":
    {
            "serviceCharge": "11.5",
            "proprietaryResponseInfo": "123456789105",
            "ecaTransactionStatus": "KEEP_PAPER_CHECK",
            "denialRecordNr": "1245245",
            "telecheckMicrSequenceNr": "123"
    }
}

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

2.3.42. Create/Add Bulk Card Order Request Request

This service is used to create an administrative bulk stored-value card order.

A Create/Add Bulk Card Order Request request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/createbulkcardorder resource.

Bulk stored-value card orders are automatically associated with the Admin Request message type. ConnectUP supports a bulkCardOrder field, which is required for a Create/Add Bulk Card Order Request message. bulkCardOrder can have more than one set of cards in the order. When sending cards, subfield bulkCardOrder.cards[n] must be specified using an indexed-number [n], starting with 0.

For example:

bulkCardOrder.cards[0].type = FIXED_VALUE

The minimum requirements for sending a Create/Add Bulk Card Order 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
[\x20-\xFF]{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
[\x20-\xFF]{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.

Required

N11
[0-9]{1,11}

bulkCardOrder

Wraps the add/activate/look up bulk stored-value card order sub-fields.

Required

bulkCardOrder.orderType

The type of order. Required for the create stored-value bulk card order request.

Required

STORE_CARD_ORDER_FOR_REPLENISHMENT|​
CUSTOMER_ORDER_TO_STORE|​
CUSTOMER_ORDER_TO_CUSTOMER|​
CUSTOMER_ORDER_TO_CORPORATE|​
CORPORATE_ORDER

bulkCardOrder.memo

A memo to be associated with the order request. Optional for create stored-value bulk card order request.

Optional

ANS100 + [\x20-\xFF]{0,100}

bulkCardOrder.cards[n]

Wraps data on the cards being ordered. Required for the create stored-value bulk card order request. Returned in the look up stored-value bulk card order response.

Required

bulkCardOrder.cards[n].type

The type of card in the bulk order.

Required

FIXED_VALUE|​
VARIABLE_VALUE|​
ONE_TIME_USE|​
ONE_TIME_USE_WITH_CASHBACK|​
EMPLOYEE_CREDIT_LINE|​
LIMITED_TIME_REPLENISHMENT

bulkCardOrder.cards[n].designName

The card design name.

Optional

ANS40 + [\x20-\xFF]{1,40}

bulkCardOrder.cards[n].quantity

The quantity of cards for the given type, amount and design set being ordered.

Required

N5 + [0-9]{1,5}

bulkCardOrder.cards[n].amount

The decimalized amount to be loaded on all the cards of the given type and design set. A period (.) is used as a decimal separator.

Required

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

shipping.customer.surname

The last name or surname of the shipping customer.

Optional. Required when bulkCardOrder.orderType has a value of CUSTOMER_ORDER_TO_CUSTOMER.

ANS50
[\x20-\xFF]{1,50}

shipping.street1

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

Optional. Required when bulkCardOrder.orderType has a value of CUSTOMER_ORDER_TO_CUSTOMER.

ANS50
[\x20-\xFF]{1,50}

shipping.street2

The adjoining road or locality (if required) of the shipping address.

Optional. Conditionally required when bulkCardOrder.orderType has a value of CUSTOMER_ORDER_TO_CUSTOMER.

ANS50
[\x20-\xFF]{1,50}

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. Conditionally required when bulkCardOrder.orderType has a value of CUSTOMER_ORDER_TO_CUSTOMER.

ANS50
[\x20-\xFF]{1,50}

shipping.city

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

Optional. Required when bulkCardOrder.orderType has a value of CUSTOMER_ORDER_TO_CUSTOMER.

ANS20
[\x20-\xFF]{1,20}

shipping.state

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

Optional. Required when bulkCardOrder.orderType has a value of CUSTOMER_ORDER_TO_CUSTOMER.

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

shipping.postcode

The postal code or zip code of the shipping address.

Optional. Required when bulkCardOrder.orderType has a value of CUSTOMER_ORDER_TO_CUSTOMER.

AN9
[A-Za-z0-9]{1,9}
Example
Create/Add Bulk Card Order Request Request
curl https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/createbulkcardorder -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "merchant.receivingInstitutionCode=11111111111"
	-d 'bulkCardOrder.orderType=CUSTOMER_ORDER_TO_STORE'
	-d 'bulkCardOrder.memo=Please include the business logo.'
	-d 'bulkCardOrder.cards[0].type=FIXED_VALUE'
	-d 'bulkCardOrder.cards[0].quantity=5'
	-d 'bulkCardOrder.cards[0].amount=50.00'
	-d 'bulkCardOrder.cards[0].designName=FUEL_AND_MERCHANDISE'
	-d 'bulkCardOrder.cards[1].type=VARIABLE_VALUE'
	-d 'bulkCardOrder.cards[1].quantity=2'
	-d 'bulkCardOrder.cards[1].amount=100.00'
	-d 'bulkCardOrder.cards[1].designName=FUEL_ONLY'
Create/Add Bulk Card Order Request Response
{
    "bulkCardOrder": {
        "orderNumber": "0000001226",
        "orderStatus": "NOT_PROCESSED"
    },
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded",
        "authorizationId": "432457"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    }
}

2.3.43. Activate Bulk Card Order Request Request

This service is used to activate a previously created bulk stored-value card order.

A Activate Bulk Card Order Request request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/activatebulkcardorder resource.

Bulk stored-value card orders are automatically associated with the Admin Request message type.

The minimum requirements for sending a Activate Bulk Card Order 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
[\x20-\xFF]{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
[\x20-\xFF]{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.

Required

N11
[0-9]{1,11}

bulkCardOrder

Wraps the add/activate/look up bulk stored-value card order sub-fields.

Required

bulkCardOrder.orderNumber

The identifier for the bulk card order. Returned in the create stored-value bulk card order response message. Required in the activate and look up bulk stored-value card order request messages.

Required

AN16 + [\x20-\xFF]{1,16}
Example
Activate Bulk Card Order Request Request
curl https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/activatebulkcardorder -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "merchant.receivingInstitutionCode=11111111111"
	-d 'bulkCardOrder.orderNumber=0000001226'
Activate Bulk Card Order Request Response
{
    "bulkCardOrder": {
        "orderNumber": "0000001226",
        "orderStatus": "IN_PROGRESS"
    },
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded",
        "authorizationId": "432457"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    }
}

2.3.44. Look Up Bulk Card Order Request Request

This service is used to look up the status and details of an administrative bulk stored-value card order.

A Look Up Bulk Card Order Request request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/lookupbulkcardorder resource.

Bulk stored-value card orders are automatically associated with the Admin Request message type.

The minimum requirements for sending a Look Up Bulk Card Order 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
[\x20-\xFF]{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
[\x20-\xFF]{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.

Required

N11
[0-9]{1,11}

bulkCardOrder

Wraps the add/activate/look up bulk stored-value card order sub-fields.

Required

bulkCardOrder.orderNumber

The identifier for the bulk card order. Returned in the create stored-value bulk card order response message. Required in the activate and look up bulk stored-value card order request messages.

Required

AN16 + [\x20-\xFF]{1,16}
Example
Look Up Bulk Card Order Request Request
curl https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/lookupbulkcardorder -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "pos.terminalId=34056111"
	-d "pos.storeId=78919753"
	-d "merchant.receivingInstitutionCode=11111111111"
	-d 'bulkCardOrder.orderNumber=0000001226'
Look Up Bulk Card Order Request Response
{
    "bulkCardOrder": {
        "orderNumber": "0000001226",
        "orderStatus": "ACTIVATED",
        "cards": [
            {
                "type": "FIXED_VALUE",
                "quantity": "5",
                "amount": "50.00",
                "designName": "FUEL_AND_MERCHANDISE"
            },
            {
                "type": "VARIABLE_VALUE",
                "quantity": "2",
                "amount": "100.00",
                "designName": "FUEL_ONLY"
            }
        ]
    },
    "id": "13844078f145407bad00e2c9e028ab1c",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded",
        "authorizationId": "432457"
    },
    "timestamp": "2020-10-28 15:24:22",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363"
    }
}

2.3.45. Registart

Registart messages are compatible with the following message types:

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
[\x20-\xFF]{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

AR

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
[\x20-\xFF]{1,15}

pos.entryMode

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

Required

MAGSTRIPE

merchantTransactionId

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

Required

ANS255
[\x20-\xFF]{8,255}

extendedPaymentType

The extended payment type is used to enrich the payment type with additional context.

Required

REG_DEV

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

UNKNOWN

card.track2Data

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

Required

ANS..37
[\x20-\xFF]{1,37}

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}

customParameters[TRANSARMOR_SEC_LVL_IND]

The trans armor security level indicator.

Required

1
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "paymentType=AR"
  -d "pos.terminalId=00000004"
  -d "pos.storeId=0232"
  -d "pos.entryMode=MAGSTRIPE"
  -d "merchantTransactionId=1234565123234"
  -d "extendedPaymentType=REG_DEV"
  -d "card.accountType=UNKNOWN"
  -d "card.track2Data=605830280880005=610192680334960944503"
  -d "merchant.receivingInstitutionCode=34000000001"
  -d "customParameters[TRANSARMOR_SEC_LVL_IND]=1"

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
[\x20-\xFF]{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})

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)

Optional

EC|MO|PM|PO|TO

pos.storeId

The store identifier assigned by the acquirer.

Optional

ANS15
[\x20-\xFF]{1,15}

pos.terminalId

The terminal identifier assigned by the acquirer.

Optional

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

pos.entryMode

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

Optional

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

Indicates if the point-of-service can accept PINs. If not inferred to PIN_ENTRY_AVAILALBLE by pos.cardholderAuthenticationMethod, pos.pinEntryCapability, or the presence of PIN data, UNKNOWN is used.

Optional

UNKNOWN| ​
PIN_ENTRY_AVAILABLE| ​
PIN_ENTRY_UNAVAILABLE

pos.cardDataInputCapability

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

Optional

UNKNOWN|​
MANUAL_NO_TERMINAL|​
MAGSTRIPE|​
BARCODE|​
OCR|​
MAGSTRIPE_MANUAL_ICC|​
MANUAL|​
MAGSTRIPE_MANUAL|​
MAGSTRIPE_ICC|​
ICC|​
NFC_ICC|​
MAGSTRIPE_MANUAL_ICC_NFC|​
NFC_MAGSTRIPE

pos.cardholderAuthenticationCapability

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

Optional

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

pos.cardCaptureCapability

Indicates if the point-of-service can capture cards. If not sent in the request, it is assumed that the point-of-service cannot capture cards.

Optional

NONE|CAPTURE

pos.operatingEnvironment

Indicates the environment in which the point-of-service is operating. If not inferred by pos.entryMode, transactionCategory or set to a value directly, the MERCHANT_UNATTENDED value is used.

Optional

NO_TERMINAL|​
MERCHANT_ATTENDED|​
MERCHANT_UNATTENDED|​
OFFSITE_ATTENDED|​
OFFSITE_UNATTENDED|​
CUSTOMER_UNATTENDED

pos.cardholderPresent

Indicates if the cardholder is present at the time the transaction is performed. If not inferred by pos.entryMode or transactionCategory, CARD_HOLDER_PRESENT is used.

Optional

CARD_HOLDER_PRESENT|​
CARD_HOLDER_NOT_PRESENT

pos.cardPresent

Indicates if the card is present at the time the transaction is performed. If not inferred by pos.entryMode or transactionCategory, CARD_PRESENT is used.

Optional

CARD_PRESENT|​
CARD_NOT_PRESENT

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

UNKNOWN|​
MANUAL|​
MAGSTRIPE|​
OCR|​
BARCODE|​
ICC|​
KEY_ENTRY|​
NFC_ICC|​
NFC_MAGSTRIPE

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

NONE|​
PIN|​
ELECTRONIC_SIGNATURE|​
BIOMETRIC|​
INOPERATIVE|​
OTHER|​
CDCVM|​
CDCVM_CODE|​
CDCVM_PATTERN|​
CDCVM_BIOMETRIC|​
UNKNOWN|​

pos.cardholderAuthenticationEntity

Indicates the entity that authenticated the cardholder at the point-of-service. If not inferred to AUTHORIZING_AGENT by pos.cardholderAuthenticationMethod or by the presence of PIN data, NOT_AUTHENTICATED is used.

Optional

NOT_AUTHENTICATED|​
ICC|​
TERMINAL|​
AUTHORIZING_AGENT|​
MERCHANT|​
OTHER

pos.cardDataOutputCapability

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

Optional

MAGSTRIPE|​NONE|​ICC|​UNKNOWN

pos.terminalOutputCapability

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

Optional

UNKNOWN|​
NONE|​
PRINT|​
DISPLAY|​
PRINT_AND_DISPLAY

pos.pinCaptureCapability

The maximum number of PIN characters that can be accepted by the point-of-service device. This field is required when a PIN was entered at the point-of-service but not verified offline. If not specified, but PIN data is provided, 4 characters are used. If not specified and no PIN data is available, UNKNOWN is used.

Optional

NONE|UNKNOWN|​
4|5|6|7|8|9|10|11|12

pos.terminalOperator

Indicates who is operating the point-of-service. If not inferred by pos.entryMode or transactionCategory, CUSTOMER is used.

Optional

CUSTOMER|​
MERCHANT|​
ADMIN

pos.terminalType

The type of terminal used to initiate the transaction. If no value is provided, the value is determined from the Transaction Category, if possible.
​
Possible values are:
ADMIN - Administrative terminal
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.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.

Optional

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.

Optional

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

merchant.street

The street address and/or name of the merchant.

Optional

ANS23
[\x20-\xFF]{1,23}

merchant.city

The city of the merchant.

Optional

ANS13
[\x20-\xFF]{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}

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)

Optional

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.

Optional

ANS36
[\x20-\xFF]{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.

Optional

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.

Optional

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.

Optional

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.

Optional

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

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

standingInstruction.amountType

The Standing Instruction recurring payment amount type, which indicates whether the amount is at a fixed rate, a variable rate or at its maximum.

Optional

FIXED|VARIABLE|MAXIMUM_AMOUNT

partialApprovalAllowed

When this flag is set to true, it indicates that partially approved authorizations are acceptable to the client.

Optional

true
Note
 The card expiry fields (card.expiryMonth and card.expiryYear) must either both be set, or neither must be set. A token created without expiry data can be used in a payment request only if the expiry data is sent with the payment request.
Example
curl http://[hostname]:[port]/opp/v1/token/tokenize -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "card.number=2222333344442226"
  -d "card.expiryMonth=12"
  -d "card.expiryYear=2020"

3.1.2. Tokenization Response

The following fields reflect the possible response values for Tokenization service requests.

Parameter name Description Required Regex

id

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

Required

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

tokenId

A token representing sensitive cardholder data.

Optional

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

result.code

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

See common result codes for this type of request.

Required

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

result.description

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

Optional

AN255
[\x20-\xFF]{0,255}

resultDetails.*

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

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\x20-\xFF]{0,2048}
Example
{
   "id" : "e8f59d02a466f35a7ece785d3e137e50",
   "tokenId" : "JYO7rdR5UjK61111",
   "result": {
      "code" : "000.000.000",
      "description" : "Transaction successful",
   },
   "resultDetails": {
      "Field1": "Value1",
      "Field2": "Value2"
   },
   "timestamp" : "2018-02-20 12:00:00"
}
Common result codes for tokenization requests:
Result code Description

000.000.000

Transaction succeeded

800.900.303

No token created

800.900.304

Token or token data could not be found

800.900.305

Token server or service is not available

800.900.306

Token operation failure occurred while processing the request

800.900.307

Token request is invalid

800.900.308

Token server or NID error occurred while processing the request

800.900.309

Requested token operation is not permitted

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
[\x20-\xFF]{0,110}

entityId

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

Conditionally Required

AN32
[a-f0-9]{32}

tokenId

A token representing sensitive cardholder data.

Required

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

The tokenId parameter is a token that has previously been returned by a tokenization request or returned in the payment request response.

Example
curl http://[hostname]:[port]/opp/v1/token/detokenize -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "tokenId=JYO7rdR5UjK61111"

3.2.2. Detokenization Response

The following fields reflect the possible response values for de-tokenization service requests.

The De-tokenization service supports response msg encryption. Please read the Configuring Encryption section of the PaymentsAPI user guide for more information.

Parameter name Description Required Regex

id

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

Required

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

tokenId

A token representing sensitive cardholder data.

Optional

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

result.code

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

See common result codes for this request type.

Required

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

result.description

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

Optional

AN255
[\x20-\xFF]{0,255}

card.number

The Primary Account Number (PAN) of the physical card. This field is always returned for successful de-tokenization requests.

Conditional

N19
[0-9]{12,19}

card.expiryMonth

The month that the card expires.

Optional

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Optional

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

resultDetails.*

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

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\x20-\xFF]{0,2048}
Note
 The card.expiryMonth and card.expiryYear fields will only be populated if they were included in the original tokenization request for this tokenId.
Example
{
   "id" : "e8f59d02a466f35a7ece785d3e137e50",
   "tokenId" : "JYO7rdR5UjK61111",
   "result": {
      "code" : "000.000.000",
      "description" : "Transaction successful",
   },
   "card": {
      "number": "1234567890123456"
      "expiryMonth": "12"
      "expiryYear": "2020"
   },
   "resultDetails": {
      "Field1": "Value1",
      "Field2": "Value2"
   },
   "timestamp" : "2018-02-20 12:00:00"
}
Common result codes for de-tokenization requests:
Result code Description

000.000.000

Transaction Succeeded

800.900.303

Token operation error

800.900.304

Token or token data could not be found

800.900.305

Token server or service is not available

800.900.306

Token operation failure occurred while processing the request

800.900.307

Token request is invalid

800.900.308

Token server or NID error occurred while processing the request

800.900.309

Requested token operation is not permitted

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

4.1. P2PE Schemes

The following sections explain each supported P2PE scheme’s use of transmitting encrypted card elements via pos.p2peEncrypted.persistableData and pos.p2peEncrypted.volatileData.

4.1.1. ACI and ACI_AES

The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields expect a hex string containing the ACI Encrypted Sensitive Data Block v1-5.

Note
 For full field specifications, contact your ACI representative to obtain the latest ACI P2PE Interface Specification for PED Manufacturers.
Note
 The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields share the same block structure described here.
Note
 The KSN (Key Serial Number) is not included inside this block — it is sent separately in pos.p2peEncrypted.ksn.

Encrypted Sensitive Data Block Structure

Populated Encrypted Sensitive Data Block v5

35303038323030303034386F7EE2484791F17474D4702096D719429CA6211BD
1ED5314FF9A294240A2702D7C9F8A7CBB4B98C8681009632C204ACB0032BE46
4D2F32C70B00C622421C738471E442F5F1407C0532323068E656B251E67E8358
BEF8483AB0D51C6619F3E7A1A9F0E75838D41FF368F728303130387C582315F8A21EA4

Field Breakdown (Encrypted Sensitive Data Block v5)

# Field Name Format Length M/O Value

1

Encrypted Sensitive Data Block Version

1AN

001

M

5

2

Encrypted Sensitive Data Block Length

4H

004

M

0082 (130 bytes — version through MAC inclusive)

3

Initialization Vector Length

2H

002

M

00 (no IV)

4

Initialization Vector

nB

000

O

(absent — IV Length is 00)

5

Encrypted Sensitive Data Length

4H

004

M

0048 (72 bytes)

6

Encrypted Sensitive Data

nB

072

O

6F7EE2484791F17474D4702096D71942
9CA6211BD1ED5314FF9A294240A2702D
7C9F8A7CBB4B98C8681009632C204ACB
0032BE464D2F32C70B00C622421C7384
71E442F5F1407C05

7

Whitelist Hash Algorithm

1H

001

M

2 (SHA-256)

8

Whitelist Hash Length

2H

002

M

20 (32 bytes)

9

Whitelist Hash

nB

032

M

68E656B251E67E8358BEF8483AB0D51C
6619F3E7A1A9F0E75838D41FF368F728

10

Encryption Algorithm

2AN

002

M

01 (3DES)

11

MAC Length

2H

002

M

08 (8 bytes)

12

MAC

nB

008

O

7C582315F8A21EA4
Note
 Total: 1+4+2+0+4+72+1+2+32+2+2+8 = 130 bytes = 0082 hex, matching the Block Length field.

Encrypted Sensitive Data Content

Each card data element requiring encryption is placed in a cleartext BER-TLV structure.

The BER-TLV payload is constructed using the available tags from the ACI tags table below. Tag availability is transaction dependent. Keep in mind PCI DSS rules on what tags are permitted for store and forward.

The entire BER-TLV cleartext string is then encrypted using the scheme’s configured algorithm — 3DES-CBC DUKPT for ACI, AES-CBC DUKPT for ACI_AES — with 0x00 padding (padding method 1 of [ISO9797-1] algorithm 3) applied to the cipher’s block boundary prior to encryption.

Parsing Example

The example below shows 3 tags set — DFDB01, DFDB02, and DFDB03 — in the cleartext BER-TLV:

DFDB010C547261636B20312064617461DFDB0223313131313232323233333333
343434343D323830393130313132333435363738393031DFDB030A3132333435
3637383930000000
Tag Value

DFDB01

Track 1 data

DFDB02

1111222233334444=280910112345678901

DFDB03

1234567890
Note
 The trailing 000000 is 0x00 padding to align the plaintext to the 8-byte 3DES block boundary. For ACI_AES, the same padding logic applies but targets the 16-byte AES block boundary instead.
Note
 Any unlisted tags like DFDB03 may be included in the BER-TLV but are ignored during decryption.

The BER-TLV encoded data structure is then encrypted (3DES-CBC DUKPT for this ACI example), producing:

6F7EE2484791F17474D4702096D719429CA6211BD1ED5314FF9A294240A2702D
7C9F8A7CBB4B98C8681009632C204ACB0032BE464D2F32C70B00C622421C7384
71E442F5F1407C05

This encrypted value is placed into the ACI Encrypted Sensitive Data Block under the Encrypted Sensitive Data field.

Available ACI and ACI_AES Tags

Note
 ACI encrypts each element using 3DES-CBC DUKPT; ACI_AES uses AES-CBC DUKPT instead. All supported tags and fallback behaviour are otherwise identical.
Tag Name Purpose

5A

PAN

Primary Account Number (primary); fallback: DFDB04

DFDB04

PAN (fallback)

Manually keyed PAN; used when tag 5A is absent

57

Track 2 Equivalent Data

EMV Track 2 (primary); fallbacks: 9F6B, DFDB02

9F6B

Track 2 Data

Track 2 alternate (1st fallback after tag 57)

DFDB02

Track 2 Data

Proprietary Track 2 (2nd fallback after 9F6B)

56

Track 1 Data

EMV Track 1 (primary); fallback: DFDB01

DFDB01

Track 1 Data (fallback)

Proprietary Track 1; used when tag 56 is absent

DFDB05

Manually Keyed CVV2

CVV2 for manual card-entry transactions

DFDB06

Manually Keyed AMEX CID

American Express CID for manual card-entry

DFDB11

Whitelist Hash Algorithm

0x01 (SHA-1) or 0x02 (SHA-256); block v1–v3 only — v4/v5 carry this in the outer block structure (see field 7 above)

DFDB12

Whitelist Hash

SHA-1 or SHA-256 hash of the loaded whitelist; block v1–v3 only — v4/v5 carry this in the outer block structure (see field 9 above)

4.1.2. Verifone VSD

The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields expect a hex string containing a Verifone VSD Encrypted Sensitive Data Block.

This block is a container for encrypted card data received from a Verifone terminal, supporting both online and store-and-forward transactions.

Important

This block format is specific to the Verifone VSD P2PE Scheme. It is NOT the standard ACI P2PE protocol.

The Verifone terminal provides the Initialization Vector (IV), PED Serial Number, KSN, and encrypted data according to the Verifone VSD specification. The encrypted data from the terminal is placed directly into the Encrypted Sensitive Data field within this block.

Note
 The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields share the same block structure described here.
Note
 The KSN (Key Serial Number) is not included inside this block — it is sent separately in pos.p2peEncrypted.ksn.

Encrypted Sensitive Data Block Structure

┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│  [1 byte ]  Version                ◄─ ASCII char ('4')           │
│  [4 bytes]  Block Length           ◄─ hex-ASCII (total bytes)    │
│  [2 bytes]  IV Length              ◄─ hex-ASCII (byte count)     │
│  [n bytes]  Initialization Vector  ◄─ RAW BINARY                 │
│  [2 bytes]  PED Serial Nr Length   ◄─ hex-ASCII ("00" if absent) │
│  [n bytes]  PED Serial Number      ◄─ RAW BINARY (optional)      │
│  [2 bytes]  Whitelist Hash Length  ◄─ hex-ASCII ("00" if none)   │
│  [n bytes]  Whitelist Hash         ◄─ RAW BINARY                 │
│  [4 bytes]  ESD Length             ◄─ hex-ASCII (4 chars)        │
│  [n bytes]  ESD                    ◄─ RAW BINARY                 │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
Field Length Prefix Encoding

Version

—

Single ASCII character. 4 for Verifone VSD.

Block Length

—

4 hex-ASCII characters. Counts all bytes in the block including the Block Length field itself.

IV Length

2 hex-ASCII chars

Number of raw binary bytes that follow.

Initialization Vector

—

Raw binary. Length specified by the preceding IV Length field.

PED Serial Nr Length

2 hex-ASCII chars

Number of raw binary bytes that follow. 00 if no PED serial number is available.

PED Serial Number

—

Raw binary. Optional — omitted when PED Serial Nr Length is 00.

Whitelist Hash Length

2 hex-ASCII chars

Number of raw binary bytes that follow. 00 if no hash is provided.

Whitelist Hash

—

Raw binary. Omitted when Whitelist Hash Length is 00.

ESD Length

4 hex-ASCII chars

Number of raw binary bytes that follow. Note: this field uses 4 characters.

ESD (Encrypted Sensitive Data)

—

Raw binary. The actual encrypted card data payload.

Constructing the Block

The following guide demonstrates how to build a Verifone VSD Encrypted Sensitive Data Block from terminal-provided values.

Input values from the terminal:

Initialization Vector

FB5018734EE1DE8A

PED Serial Number

314-451-440

Encrypted Sensitive Data

D2F732FE5E50BA2B9D3FEA3CCEBC172D

Step 1 — Version

Write the version byte. The Verifone VSD scheme uses version 4.

Hex:  34

Step 2 — Block Length (placeholder)

The final length is not yet known. Write a placeholder of 0000 (4 hex-ASCII characters) and return to fill it in at the end.

Hex:  30 30 30 30   ("0000")

Step 3 — IV Length

The Initialization Vector (FB5018734EE1DE8A) is 8 bytes long. 8 decimal = 08 hex. Write two hex-ASCII characters:

Hex:  30 38   ("08")

Step 4 — Initialization Vector (raw binary)

Write the IV as raw binary bytes — not as hex-ASCII characters:

Hex:  FB 50 18 73 4E E1 DE 8A

Step 5 — PED Serial Number Length

The PED serial number 314-451-440 is 11 ASCII characters = 11 bytes. 11 decimal = 0B hex. Write two hex-ASCII characters:

Hex:  30 42   ("0B")
Note
 If no PED serial number is available, write 30 30 ("00").

Step 6 — PED Serial Number (raw binary)

Write the PED serial number as raw ASCII bytes:

3

1

4

-

4

5

1

-

4

4

0

33

31

34

2D

34

35

31

2D

34

34

30

 
Hex:  33 31 34 2D 34 35 31 2D 34 34 30

Step 7 — Whitelist Hash Length

No whitelist hash is provided in this example. Write 00:

Hex:  30 30   ("00")

Step 8 — Encrypted Sensitive Data Length

The encrypted payload (D2F732FE…​172D) is 16 bytes. 16 decimal = 10 hex. The ESD Length field uses 4 hex-ASCII characters, so zero-pad to 4 digits:

Hex:  30 30 31 30   ("0010")

Step 9 — Compute the Block Length

The Block Length counts every byte in the block including the 4-byte Block Length field itself.

Field Bytes

Version

1

Block Length

4

IV Length

2

IV

8

PED Serial Nr Length

2

PED Serial Number

11

Whitelist Hash Length

2

Whitelist Hash

0

ESD Length

4

ESD

16

Total

50

50 decimal = 32 hex. Padded to 4 hex-ASCII characters: 0032.

Replace the placeholder from Step 2:

Hex:  30 30 33 32   ("0032")

Final assembled block:

Step Field Hex

1

Version

34

2

Block Length

30 30 33 32

3

IV Length

30 38

4

IV

FB 50 18 73 4E E1 DE 8A

5

PED Ser Nr Length

30 42

6

PED Serial Nr

33 31 34 2D 34 35 31 2D 34 34 30

7

WL Hash Length

30 30

8

Whitelist Hash

(empty — length is 00)

9

ESD Length

30 30 31 30

10

ESD

D2 F7 32 FE 5E 50 BA 2B 9D 3F EA 3C CE BC 17 2D

Complete block as a single hex string:

34303033323038FB5018734EE1DE8A30423331342D3435312D343430303030303130D2F732FE5E50BA2B9D3FEA3CCEBC172D

Encrypted Sensitive Data Content

The Encrypted Sensitive Data (ESD) payload contains a BER-TLV encoded string constructed by the terminal from the available Verifone VSD tags listed in the Verifone VSD Tags table. The BER-TLV string is padded using ISO 7816 padding and encrypted with 3DES-CBC DUKPT.

Parsing Example

The following example shows two tags — 5A and DFDB02 — after decryption:

5A085337665800622998DFDB0202445F
Tag Value Description

5A

5337665800622998

PAN

DFDB02

445F

Manual CVV (trailing F is ISO 7816 padding)

Available Verifone VSD Tags

The following table lists all BER-TLV tags supported by the Verifone VSD P2PE Scheme.

Note

Several Verifone-proprietary tags (DFDBxx) have different semantics in the Verifone VSD context compared to their standard definitions. The descriptions below reflect their meaning within this scheme.
Tag Name Description Notes

5A

PAN

Primary Account Number (primary source).

Fallback: DFDB01

DFDB01

PAN (Verifone Magstripe)

Verifone magstripe PAN. Used when tag 5A is absent.

In Verifone VSD context, DFDB01 = PAN (not Track 1).

57

Track 2 Equivalent Data

EMV Track 2 data (primary source).

Fallback chain: DFDB06 → 9F6B → 5F22

DFDB06

Track 2 (Verifone Magstripe)

Verifone magstripe Track 2. First fallback when tag 57 is absent.

In Verifone VSD context, DFDB06 = Track 2 (not AMEX CID).

9F6B

Track 2 Data

Track 2 alternate. Second fallback after DFDB06.

5F22

Track 2 Data (Verifone Alt)

Verifone-specific Track 2 alternate. Third fallback.

56

Track 1 Data

EMV Track 1 data (primary source).

Fallback chain: DFDB05 → 5F21

DFDB05

Track 1 (Verifone Magstripe)

Verifone magstripe Track 1. First fallback when tag 56 is absent.

In Verifone VSD context, DFDB05 = Track 1 (not CVV2).

5F21

Track 1 Data (Verifone Alt)

Verifone-specific Track 1 alternate. Second fallback.

DFDB02

Manual CVV (Verifone)

Manual CVV entry from the terminal.

In Verifone VSD context, DFDB02 = CVV (not Track 2).

4.1.3. Ingenico OnGuard

The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields expect a hex string containing the ACI Encrypted Sensitive Data Block v3, as defined in the ACI P2PE Interface Specification for PED Manufacturers.

Note
 For full field specifications, contact your ACI representative to obtain the latest ACI P2PE Interface Specification for PED Manufacturers.
Important

The ACI P2PE v3 block format is used only as a transport container for the terminal’s encrypted sensitive data. The Ingenico OnGuard scheme does not leverage the full ACI Encrypted Data Block field set — the Initialization Vector and MAC fields are always empty.

The Ingenico terminal provides the encrypted data according to the Ingenico OnGuard specification. The encrypted card data in BER-TLV format is placed directly into the Encrypted Sensitive Data field, supporting both online and store-and-forward transactions.

Note
 The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields share the same block structure described here.
Note
 The KSN (Key Serial Number) is not included inside this block — it is sent separately in pos.p2peEncrypted.ksn.

Encrypted Sensitive Data Block Structure

┌──────────────────────────────────────────────────────────────────┐
│                                                                  │
│  [1 byte ]  Version                ◄─ ASCII char ('3')           │
│  [4 bytes]  Block Length           ◄─ hex-ASCII                  │
│  [2 bytes]  IV Length              ◄─ hex-ASCII ("00" for OG)    │
│  [n bytes]  Initialization Vector  ◄─ RAW BINARY (empty for OG)  │
│  [4 bytes]  ESD Length             ◄─ hex-ASCII (byte count)     │
│  [n bytes]  ESD                    ◄─ RAW BINARY (BER-TLV)       │
│  [2 bytes]  MAC Length             ◄─ hex-ASCII ("00" for OG)    │
│  [n bytes]  MAC                    ◄─ RAW BINARY (empty for OG)  │
│                                                                  │
└──────────────────────────────────────────────────────────────────┘
Field Encoding

Version

Single ASCII character. 3 for ACI Encrypted Sensitive Data Block v3.

Block Length

4 hex-ASCII characters. Overall block size.

IV Length

2 hex-ASCII characters. Always 00 for Ingenico OnGuard.

Initialization Vector

Empty.

ESD Length

4 hex-ASCII characters. Number of raw binary bytes that follow. Specifies the exact byte count of the encrypted BER-TLV payload.

ESD (Encrypted Sensitive Data)

Raw binary. The OnGuard BER-TLV encoded card data.

MAC Length

2 hex-ASCII characters. Always 00 for Ingenico OnGuard.

MAC

Empty.

Constructing the Block

The following example walks through constructing the ACI Encrypted Sensitive Data Block v3 containing the Ingenico OnGuard BER-TLV payload.

Input values from the terminal:

Ingenico OnGuard BER-TLV payload

44464442303231334929496658862016D14082018484309142177F4446444230 31344342343932393439303732343839323031365E4241524B45522F44202020202020202020 2020202020202020205E31343038323031313038323131353839313133393136393831323638323133

Step 1 — Version

Write the first byte.

Hex:  33   →   ASCII '3'

Version 3 identifies the ACI Encrypted Sensitive Data Block v3.

Step 2 — Block Length

The Block Length field holds the total byte count of the complete block. This value is computed in Step 7 after all other fields are known. Write 0000 (0 bytes) as a 4 hex-ASCII character placeholder.

Hex:  30 30 30 30   →   "0000"   →   0 decimal

See Step 7 for the full byte-count derivation.

Step 3 — Initialization Vector Length

Write the next 2 bytes.

Hex:  30 30   →   "00"   →   0 bytes

An IV length of 00 means no Initialization Vector data follows.

Step 4 — Encrypted Sensitive Data Length

Write the next 4 bytes.

The encrypted payload (444644423032313349…​638323133) is 111 bytes. 111 decimal = 6F hex. The ESD Length field uses 4 hex-ASCII characters, so zero-pad to 4 digits:

Hex:  30 30 36 46   →   "006F"   →   111 bytes

Step 5 — Encrypted Sensitive Data (111 bytes)

Write the next 111 bytes as raw binary (not hex-ASCII).

44 46 44 42 30 32 31 33  49 29 49 66 58 86 20 16
D1 40 82 01 84 84 30 91  42 17 7F 44 46 44 42 30
31 34 43 42 34 39 32 39  34 39 30 37 32 34 38 39
32 30 31 36 5E 42 41 52  4B 45 52 2F 44 20 20 20
20 20 20 20 20 20 20 20  20 20 20 20 20 20 20 5E
31 34 30 38 32 30 31 31  30 38 32 31 31 35 38 39
31 31 33 39 31 36 39 38  31 32 36 38 32 31 33

Step 6 — MAC Length

Write the next 2 bytes after the ESD.

Hex:  30 30   →   "00"   →   0 bytes

A MAC length of 00 means no MAC data follows.

Step 7 — Compute the Block Length

The Block Length counts every byte in the block.

Field Bytes

Version

1

Block Length

4

IV Length

2

Initialization Vector

0

ESD Length

4

Encrypted Sensitive Data

111

MAC Length

2

MAC

0

Total

124

124 decimal = 7C hex. Padded to 4 hex-ASCII characters: 007C.

Replace the placeholder from Step 2:

Hex:  30 30 37 43   ("007C")

Block summary:

Field Hex Bytes Value

Version

33

'3' (v3)

Block Length

30 30 37 43

"007C" (124)

IV Length

30 30

"00" (no IV)

ESD Length

30 30 36 46

"006F" (111 bytes)

ESD

(111 bytes)

BER-TLV payload

MAC Length

30 30

"00" (no MAC)

Complete ACI Encrypted Sensitive Data Block v3 as a single hex string:

This hex string is ready to be supplied to either pos.p2peEncrypted.persistableData or pos.p2peEncrypted.volatileData depending on the tags contained.

333030374330303030364644464442303231334929496658862016D140820184
84309142177F444644423031344342343932393439303732343839323031365E
4241524B45522F442020202020202020202020202020202020205E3134303832
30313130383231313538393131333931363938313236383231333030

Encrypted Sensitive Data Content

The Encrypted Sensitive Data (ESD) payload contains BER-TLV entries constructed by the Ingenico terminal containing the tag(s) from the Ingenico OnGuard tags table. If additional tags are present, they are included in the BER-TLV but ignored during decryption.

Important

Ingenico OnGuard TLV encoding differs from standard binary BER-TLV:

  • Tags and length indicators are written as hex-ASCII text.

  • Values are raw binary bytes.

  • It is critical to set pos.p2peEncrypted.tlvMapping[tag] to binary encoding if needed. The default is ANS.

Parsing Example

Each TLV value is encrypted using OnGuard format-preserving encryption, so the decrypted values retain the same format and length as the plaintext.

Tag (hex-ASCII) Length Value (hex)

DFDB02 (Track 2)

13 (19 bytes)

4929496658862016D14082018484309142177F

DFDB01 (Track 1)

4C (76 bytes)

42343932393439303732343839323031365E4241524B
45522F44202020202020202020202020202020202020
5E313430383230313130383231313538393131333931
36393831323638323133

Available Ingenico OnGuard Tags

Tag Name tlvMapping Description Notes

5A

PAN

B

Primary Account Number (chip card).

5F24

Application Expiry Date

B

Card expiry date; read alongside tag 5A.

YYMMDD binary BCD; not encrypted

57

Track 2 Equivalent Data

B

EMV Track 2 equivalent (primary source).

Fallback chain: DFDB02 → 9F6B

DFDB02

Track 2 Data

B

Ingenico proprietary Track 2. First fallback when tag 57 is absent.

9F6B

Track 2 Data

B

Alternate Track 2 format. Second fallback after DFDB02.

56

Track 1 Data

—

EMV Track 1 (primary source). ASCII text; default ANS encoding applies.

Fallback: DFDB01

DFDB01

Track 1 Data

—

Ingenico proprietary Track 1. ASCII text; default ANS encoding applies.

DFDB04

Manually Keyed PAN

—

PAN from manual card-entry mode. ASCII digits; default ANS encoding applies.

DFDB05

Manually Keyed CVV2

—

CVV2 from manual card-entry; present only with DFDB04. ASCII digits.

DFDB06

Manually Keyed AMEX CID

—

American Express CID; present only with DFDB04. ASCII digits.

4.1.4. PAX

The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields expect a hex string containing BER-TLV encoded data.

The PAX terminal provides the encrypted card data as concatenated BER-TLV fields. Each card data field is encrypted individually using 3DES ECB DUKPT.

Note
 The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields share the same BER-TLV format described here.
Note
 Do not include pos.p2peEncrypted.tlvMapping, pos.p2peEncrypted.sensitiveData entries for PAX requests.

Example Payload

The following hex string is a complete PAX P2PE data payload. The tags are concatenated directly — encrypted PAN (DFDB04), encrypted Track 2 (DFDB02), and encrypted Track 1 (DFDB01):

DFDB041049C1994C3431D45DCAC5D4492BE1D0A0DFDB022049C1994C3431D45D
CAC5D4492BE1D0A0B4A1A14903478ADAC8820BCB0AC8DBF9DFDB0140FE0E366F
F616E7C383274282EE75A85ACC2E35F89B2F71BD19F402D2F0A27CC5CF3BAD65
D0EE94ABE461C83638B464E03D5E7CFFE151A955284CC4B120EB8DF1

TLV breakdown:

Tag Name Value (hex)

DFDB04

PAN

49C1994C3431D45DCAC5D4492BE1D0A0

DFDB02

Track 2

49C1994C3431D45DCAC5D4492BE1D0A0B4A1A14903478ADAC8820BCB0AC8DBF9

DFDB01

Track 1

FE0E366FF616E7C383274282EE75A85ACC2E35F89B2F71BD19F402D2F0A27CC5 CF3BAD65D0EE94ABE461C83638B464E03D5E7CFFE151A955284CC4B120EB8DF1

Decrypted Tag Content

Each tag value is independently decrypted by the HSM using 3DES ECB DUKPT. After decryption of the example payload above, the tags contain cleartext card data:

Tag Decrypted Value (example) Description

DFDB04

5337665800622998

PAN

DFDB02

5337665800622998D2512…​

Track 2 Data

DFDB01

B5337665800622998^DOE/JOHN\^…​

Track 1 Data

Available PAX Tags

The following table lists all BER-TLV tags supported by the PAX P2PE Scheme.

Note
 Each tag is optional. The terminal may include any combination of these tags depending on the entry mode and available card data.
Tag Name Description

DFDB04

PAN

Primary Account Number, encrypted using 3DES ECB DUKPT.

DFDB02

Track 2 Data

Track 2 Equivalent Data, encrypted using 3DES ECB DUKPT.

DFDB01

Track 1 Data

Track 1 Data, encrypted using 3DES ECB DUKPT.

4.1.5. Presto

The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields expect a hex string containing BER-TLV encoded data.

The Presto terminal provides the encrypted card data as BER-TLV fields nested inside an E0 wrapper tag. Each card data field is encrypted individually.

Note
 The pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields share the same BER-TLV format described here.
Note
 Do not include pos.p2peEncrypted.tlvMapping, pos.p2peEncrypted.sensitiveData entries for Presto requests.

Example Payload

The following hex string is a complete Presto P2PE data payload. The E0 tag is a container for the other tags. The inner tags include an embedded KSN (CA), which is ignored, encrypted Track 1 (CB), and encrypted Track 2 (CC):

e060ca0affffffff6572a4000015cb30451739cf99c6ccccfecd373901cb1a1
a9b76cf24754a2a75173755561e25d674db0358d50bc7908b063108afa10721
f2cc20f0dd4b56ecd31e9411b452efbf135bf7573de2eefdda2d118e4044189
2c789e9

TLV breakdown:

Tag Name Value (hex)

E0

Container

CA0AFFFFFFFF6572A4000015CB30451739CF99C6CCCCFECD373901CB1A1A9B76 CF24754A2A75173755561E25D674DB0358D50BC7908B063108AFA10721F2CC20 F0DD4B56ECD31E9411B452EFBF135BF7573DE2EEFDDA2D118E40441892C789E9

CA

KSN (embedded and ignored)

ffffffff6572a4000015

CB

Track 1

451739cf99c6ccccfecd373901cb1a1a9b76cf24754a2a75173755561e25d674db0358d50bc7908b063108afa10721f2

CC

Track 2

f0dd4b56ecd31e9411b452efbf135bf7573de2eefdda2d118e40441892c789e9

Decrypted Tag Content

Each inner tag value (CB, CC, CE) is independently decrypted by the HSM using 3DES-CBC DUKPT with an all-zero IV.

Parsing Example

After decryption of the example payload above, the inner tags contain cleartext card data:

Tag Decrypted Value (example) Description

CB

B4321000000001119DUALTRACK/VISA251200012512300

Track 1 Data

CC

4321000000001119=251200012512300

Track 2 Data

Available Presto Tags

The following table lists all BER-TLV tags supported by the Presto P2PE Scheme.

Tag Name Description

E0

Encrypted Data Container

Outer BER-TLV wrapper. Its value bytes contain the nested encrypted card data tags listed below.

CA

KSN (embedded)

Key Serial Number embedded by the terminal. Present in the TLV data but ignored — the KSN is sourced from pos.p2peEncrypted.ksn instead.

CB

Track 1 Data

Encrypted Track 1 data, nested inside E0. 3DES-CBC DUKPT encrypted with all-zero IV.

CC

Track 2 Data

Encrypted Track 2 data, nested inside E0. 3DES-CBC DUKPT encrypted with all-zero IV.

CE

PAN

Encrypted Primary Account Number, nested inside E0. 3DES-CBC DUKPT encrypted with all-zero IV.

4.2. 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.2.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
[\x20-\xFF]{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

ACI|​
VERIFONE_VSD|​
VERIFONE_VRK|{zswp}
INGENICO|​
PAX|​

rkdRequestData

Data associated with the key request. The field format is dependent on the type of Remote Key Distribution scheme used (the value of rkdScheme). For more information on formatting this field, refer to the respective vendor’s RKD documentation. The field contains binary data encoded as a hex string.

Required

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

keyStatus

Indicates the status of the current P2PE key.
Possible values:
COMPROMISED - The P2PE key on the PED has been compromised.
EXPIRED - The P2PE key on the PED has expired.
INVALID - The P2PE key on the PED is invalid.
NOT_PRESENT - There is currently no P2PE key available on the PED.
REVOKED - The P2PE key on the PED has been revoked.
VALID - The P2PE key available on the PED is valid.

Conditionally required. Depends on the type of Remote Key Distribution scheme used (the value of rkdScheme)

COMPROMISED|​
EXPIRED|​
INVALID|​
NOT_PRESENT|​
REVOKED|​
VALID|​

deviceName

An identifiable name for the PED involved in the key exchange. Examples include Ingenico_RBA, Verifone_FORMAGENT, SC5000, and VX810.

Conditionally required. Depends on the type of Remote Key Distribution scheme used (the value of rkdScheme)

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

The following fields reflect the possible response values for the RKD Exchange Request service.

Parameter name Description Required Regex

resultDetails.rkdKeyData

New (encrypted) P2PE key. The field format is dependent on the type of Remote Key Distribution used (the value of rkdScheme in the request message). For more information on formatting this field, refer to the respective vendor’s RKD documentation. The field contains binary data encoded as a hex string.

Conditional

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

resultDetails.rkdEchoData

A value that must be sent back by the PED in an RKD confirmation request after applying the new P2PE key.

Conditional

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

See the Standard RKD Exchange Response fields for an extended listing of the possible response parameters ConnectUP can return for this request type.

4.2.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
[\x20-\xFF]{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

ACI|​
VERIFONE_VSD|​
VERIFONE_VRK|{zswp}
INGENICO|​
PAX|​

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.2.3. Standard RKD Exchange Response

The following fields reflect the possible response values for request messages sent to either the https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdrequest or https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm resources.

Parameter name Description Required Regex

id

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

Required

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

result.code

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

Required

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

result.description

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

Required

AN255
[\x20-\xFF]{0,255}

timestamp

The timestamp generated by the response in UTC.

Required

date
yyyy-MM-dd hh:mm:ss

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Conditional

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

resultDetails.*

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

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\x20-\xFF]{0,2048}
Note
 Optional fields will only be returned if the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

5. VP2PE Service

Warning
 The VP2PE Service is not officially supported as of this release and is subject to change.

5.1. Device Data

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

For Device Data requests, use https://[hostname]:[port]/paymentsapi/opp/v1/vp2pe/devicedata

5.1.1. Device Data Request

The minimum requirements for sending a Device Data Capture message are listed here.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

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

Conditionally Required

ANS110
[\x20-\xFF]{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
[\x20-\xFF]{8}

terminal.devices[n].id

The device’s ID.

Required

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].capabilities[n].capability

The device’s capability.

Required

ATM|​
CARDREADER|​
CHECKREADER|​
DISPLAY|​
KEYPAD|​
PINPAD|​
POS|​
PRINTER|​
SIGCAP

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
[\x20-\xFF]{1,23}

merchant.city

The city of the merchant.

Optional

ANS13
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{0,2048}

terminal.devices[n].hardware.components[n].type

The type of hardware component used by the device.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.components[n].version

The hardware component version used by the device.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.components[n].iss

The hardware component issue used by the device.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.components[n].ass

The hardware component assembly used by the device.

Optional

ANS2048
[\x20-\xFF]{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
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.manufacturer

The device’s hardware manufacturer.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.manufacturerSerial

The device’s hardware manufacturing serial number.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.serial

The device’s hardware serial.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.series

The device’s hardware series.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.modelName

The device’s hardware model name.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.modelNumber

The device’s hardware model number.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].hardware.version

The device’s hardware version.

Optional

ANS2048
[\x20-\xFF]{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
[\x20-\xFF]{1,39}

terminal.devices[n].hardware.macAddress

The device’s hardware MAC address.

Optional

ANS17
[\x20-\xFF]{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
[\x20-\xFF]{0,2048}

terminal.devices[n].software.modules[n].component.type

The software module component type used by the device.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].software.modules[n].component.version

The software module component version used by the device.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].software.modules[n].component.iss

The software module component issue used by the device.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].software.modules[n].component.ass

The software module component assembly used by the device.

Optional

ANS2048
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{1,2048}

terminal.devices[n].software.modules[n].version

The device’s software module version.

Optional

ANS2048
[\x20-\xFF]{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
[\x20-\xFF]{1,2048}

terminal.devices[n].software.modules[n].hash

The device’s software module hash.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].software.modules[n].prov

The device’s software module provision.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].software.modules[n].minorVersion

The device’s software module minor version.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].software.modules[n].majorVersion

The device’s software module major version.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].properties[n].name

The device’s property name.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.devices[n].properties[n].value

The device’s property value.

Optional

ANS2048
[\x20-\xFF]{1,2048}

terminal.additionalAttributes[key]

Additional attributes sent as key-value pairs.

Optional

key: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\x20-\xFF]{0,2048}

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Optional

name: AN64
[a-zA-Z0-9\.:_ ]{3,64}
value: AN2048
[\x20-\xFF]{0,2048}
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

id

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

Required

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

result.code

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

Required

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

result.description

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

Required

AN255
[\x20-\xFF]{0,255}

timestamp

The timestamp generated by the response in UTC.

Required

date
yyyy-MM-dd hh:mm:ss

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Optional

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

resultDetails.*

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

Optional

name: AN64
[a-zA-Z0-9\._]{3,64}
value: AN2048
[\x20-\xFF]{0,2048}
Example
{
  "id" : "e8f59d02a466f35a7ece785d3e137e50",
  "result": {
    "code" : "000.000.000",
    "description" : "Transaction succeeded",
    "authorizationId" : "783276"
  },
  "timestamp" : "2019-09-06 12:22:44"
}
Note
 Optional fields will only be returned if the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

6. APM Token Decrypt Service

6.1. APM Token Decrypt

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

  • For Apple Pay token decrypt requests, use https://[hostname]:[port]/paymentsapi/opp/v1/apm/decrypt/applepay

  • For Google Pay token decrypt requests, use https://[hostname]:[port]/paymentsapi/opp/v1/apm/decrypt/googlepay

Note
 The Payment service supports accepting an encrypted payment token and decrypting it as part of a normal Payment request. The response fields returned in this service call can be used to perform a pre-decrypted APM Payment request. See Alternative Card Data for more details on how to perform both either of these Payment requests using an APM.

6.1.1. APM Token Decrypt Request

The minimum requirements for sending a APM Token Decrypt message are listed here. To use this service, either an Apple Pay or Google Pay payment token must be supplied in the request. Only one APM token type should be supplied for any APM Token Decrypt Request sent to ConnectUP.

Parameter name Description Required Regex

Authorization: Bearer <access-token>

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

Conditionally Required

ANS110
[\x20-\xFF]{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
[\x20-\xFF]{1,8192}

googlePay.paymentToken

The encrypted payment token provided by Google.

Conditionally Required

ANS8192
[\x20-\xFF]{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
[\x20-\xFF]{1,15}

merchant.street

The street address and/or name of the merchant.

Optional

ANS23
[\x20-\xFF]{1,23}

merchant.city

The city of the merchant.

Optional

ANS13
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{1,15}

pos.transactionSequenceNumber

Identifies the transaction on the device that initiated the transaction.

Optional

ANS35
[\x20-\xFF]{1,35}

pos.terminalOperator

The terminal operator.

Optional

ANS999
[\x20-\xFF]{1,999}

pos.encryptedPin.ksn

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

Optional

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

merchant.receivingInstitutionCode

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

Required

N11
[0-9]{1,11}

merchant.acquiringInstitutionCode

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

Optional

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
[\x20-\xFF]{1,99}

emvFileDownload.blockNumber

Indicates the block number or offset of the current download.

Optional

ANS50
[\x20-\xFF]{1,50}

emvFileDownload.downloadIndicator

Indicates download status.

Optional

REQUIRED|NOT_REQUIRED|IN_PROGRESS|COMPLETED|ERROR|SUCCESSFUL
Example
curl http://[hostname]:[port]/opp/v1/nwrkmng -v
  -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "infoCode=107"
  -d "settlementDate=0522"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78123753"
  -d "pos.transactionSequenceNumber=66611234"
  -d "pos.terminalOperator=12345678"
  -d "pos.encryptedPin.ksn=FFFF12345612342000..."
  -d "merchant.receivingInstitutionCode=12345678901"
  -d "merchant.acquiringInstitutionCode=12345678901"
  -d "merchant.forwardingInstitutionCode=12345678901"

7.1.2. Network Management Response

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

Parameter name Description Required Regex

id

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

Always

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

result.code

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

Required

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

result.description

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

Always

AN255
[\x20-\xFF]{0,255}

result.authorizationId

The code assigned by the authorizing institution indicating approval.

Optional

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

result.remoteBatchNr

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

Optional

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

emvFileDownload

Contains information regarding EMV Filed Downloads which can be used to retrieve EMV CA Public Key data.

Conditional

ANS9999
[\x20-\xFF]{9999}

timestamp

The timestamp generated by the response in UTC.

Required

date
yyyy-MM-dd hh:mm:ss
Example
{
  "id" : "e8f59d02a466f35a7ece785d3e137e50",
  "result": {
    "code" : "000.000.000",
    "description" : "Transaction succeeded",
    "authorizationId" : "783276"
  },
  "timestamp" : "2019-09-06 12:22:44"
}
Note
 Optional fields will only be returned if the request could be processed (no validation errors occurred on the fields in the request). The request result.code must always be evaluated with the HTTP status code to determine the overall status of the request.

7.1.3. EmvFileDownload

EmvFileDownload is compatible with the following message types:

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

Parameter name Description Required Regex

emvFileDownload.fileVersion

Free form field containing the file version information.

Optional

ANS99
[\x20-\xFF]{1,99}

emvFileDownload.blockNumber

Indicates the block number or offset of the current download.

Optional

ANS50
[\x20-\xFF]{1,50}

emvFileDownload.downloadIndicator

Indicates download status.

Optional

REQUIRED|NOT_REQUIRED|IN_PROGRESS|COMPLETED|ERROR|SUCCESSFUL
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
[\x20-\xFF]{1,99}

emvFileDownload.blockNumber

Indicates the block number or offset of the current download.

Optional

ANS50
[\x20-\xFF]{1,50}

emvFileDownload.downloadIndicator

Indicates download status.

Optional

REQUIRED|NOT_REQUIRED|IN_PROGRESS|COMPLETED|ERROR|SUCCESSFUL

emvFileDownload.caPkf

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

Optional

ANS9999
[\x20-\xFF]{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
[\x20-\xFF]{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
[\x20-\xFF]{8}

terminal.storeId

Store identifier assigned by the acquirer.

Optional

ANS15
[\x20-\xFF]{1,15}

customParameters[name]

Used to send additional information required for certain transaction scenarios.

Optional

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

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

id

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

Always

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

result.code

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

Required

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

result.description

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

Always

AN255
[\x20-\xFF]{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

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

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

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
{
    "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

A

Alphabetic characters, A through Z, and a through z

N

Numeric digits, 0 through 9

S

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

P

Pad character, space

AN

Alphabetic and numeric characters

AS

Alphabetic and special characters

NS

Numeric and special characters

ANS

Alphabetic, numeric, and special characters

ANP

Alphabetic, numeric, and pad characters

YY

Year, 00 through 99

MM

Month, 01 through 12

DD

Day, 01 through 31

Appendix B: Result Code Explanation

B.1. Result Codes

Result codes are part of the response body’s JSON (field result) containing a code and a description explaining the code.

A result code has the format ddd.ddd.ddd, that is, 3 groups of 3-digit numbers. The codes are split into rough groups by the first number, then into more detailed sub-groups by the second number, then into the exact code by the third number.

Example:

800.100.153 means:

800: bank declined

100: it declined the authorization

153: it declined authorization because the CVV is wrong

The currently supported result codes are listed below.

Result Code Result Description Special Notes

000.000.000

Transaction succeeded

000.000.099

Transaction Succeeded (partial approval)

000.100.201

Account or Bank Details Incorrect

000.100.206

Revocation or Dispute

000.100.220

Fraudulent Transaction

000.200.000

Transaction pending

100.100.101

Invalid credit card, bank account number, or bank name

100.100.305

Invalid expiration date format

100.150.200

Registration does not exist

100.150.202

Registration is already deregistered

100.300.501

Invalid response ID

100.300.600

Invalid or missing user login

100.396.101

Cancelled by user

100.396.106

User did not agree to payment method terms

100.550.401

Invalid currency

100.800.501

Invalid country

200.100.501

Invalid or missing customer

200.100.603

Alternative payment method token (ApplePay/GooglePay) could not be decrypted Cryptographic configuration might be outdated.

200.200.106

Duplicate transaction. Please verify that the UUID is unique.

200.300.404

Invalid or missing parameter

300.100.100

Transaction declined (additional customer authentication required)

300.100.190

Transaction declined (Issuer Requires PIN [SCA])

300.100.191

Transaction declined (SCA exemption is invalid)

300.100.192

Transaction declined (additional customer authentication required)

500.100.401

Connector is unavailable (no processing possible)

600.100.100

Unexpected Integrator Error (Request could not be processed)

600.200.400

Unsupported Payment Type

600.200.500

Invalid payment data. You are not configured for this currency or sub-type (country or brand).

700.100.200

Non-matching reference amount

800.100.100

Transaction declined for unknown reason

800.100.151

Transaction declined (invalid card)

800.100.153

Transaction declined (invalid CVV)

800.100.154

Transaction declined (transaction marked as invalid)

800.100.155

Transaction declined (amount exceeds credit)

800.100.156

Transaction declined (format error)

800.100.157

Transaction declined (wrong expiry date)

800.100.159

Transaction declined (stolen card)

800.100.160

Transaction declined (card blocked)

800.100.161

Transaction declined (too many invalid tries)

800.100.162

Transaction declined (limit exceeded)

800.100.163

Transaction declined (maximum transaction frequency exceeded)

800.100.165

Transaction declined (card lost)

800.100.166

Transaction declined (incorrect personal identification number)

800.100.167

Transaction declined (referencing transaction does not match)

800.100.168

Transaction declined (restricted card)

800.100.170

Transaction declined (transaction not permitted)

800.100.174

Transaction declined (invalid amount)

800.100.178

Transaction declined (PIN entered incorrectly too many times)

800.100.180

Transaction declined (contact acquirer)

800.100.190

Transaction declined (invalid configuration data)

800.100.199

Transaction declined (routing error)

800.100.200

Transaction declined (refer to card issuer)

800.100.402

CC/bank account holder not valid

800.900.303

No token created

800.900.304

Token or token data could not be found

800.900.305

Token server or service is not available

800.900.306

Token operation failure occurred while processing the request

800.900.307

Token request is invalid

800.900.308

Token server or NID error occurred while processing the request

800.900.309

Requested token operation is not permitted

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 ConnectUP 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 status code indicates that ConnectUP successfully received, understood, and processed the request. However, it does not necessarily mean the transaction was approved or completed successfully.

The 200 status code may be returned in the following scenarios:

* The transaction was successful and approved.

* The upstream host declined the transaction.

* There was a timeout between ConnectUP and the upstream host.

To determine the specific outcome of the request, always refer to the result.code and result.description fields in the response body. These fields will provide more detailed information about the transaction status and any issues that may have occurred during processing.

400 Declined / Bad Request

This means that ConnectUP cannot process the request. The status code indicates that the request message contains invalid field values or ConnectUP failed to unpack the request/response messages. 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: 2026-03-09

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

ConnectUP YAML

10. Publication history

Current publication date: 2026-03-09

Version 1.63

P2PE Documentation Uplift

  • Added detailed P2PE field descriptions with examples.

  • Documented the usage of pos.p2peEncrypted.volatileData and pos.p2peEncrypted.persistableData fields across all P2PE schemes.

10.1. Version 1.62

  • Added support for Point-to-Point-Encryption (P2PE) card data in Stored-Value payment types.

10.2. Version 1.61

  • Moved track1Data to the MAGSTRIPE example section.

  • Updated geographicCoordinates and serviceLocationGeographicCoordinates regex to support negative values.

10.3. Version 1.60

  • Adding mandatory shipping fields for Create Bulk Card Order with orderType CUSTOMER_ORDER_TO_CUSTOMER

10.4. Version 1.59

  • Adding merchant, transactionCategory, threeDSecure, standingInstruction and partialApprovalAllowed to Tokenization Requests

10.5. Version 1.58

  • Updating the values for the reason field

10.6. Version 1.57

  • Introducing merchant fields geographicCoordinates and serviceLocationGeographicCoordinates

10.7. Version 1.56

  • Introducing Bulk Stored-value Card Order services

10.8. Version 1.55

  • Relaxing authorizationId validation

10.9. Version 1.54

ACI AES P2PE support

  • Added support for ACI AES P2PE.

Version 1.53

  • Adding field payment.request.StandingInstruction.amountType.

10.10. Version 1.52

  • All common result detail fields are now listed.

10.11. Version 1.51

  • Field check[n].formattedMicr.checkNr now supports up to 10 digits.

10.12. Version 1.50

  • Adding the Mini Statement service and accompanying statementData fields.

10.13. Version 1.49

  • merchantInvoiceId length increased to 30 characters.

10.14. Version 1.48

  • Adding Response Result Code 800.100.180 - Transaction declined (contact acquirer).

10.15. Version 1.47

  • Payment Service: Added Healthy Benefit fields to the payment request and response.

  • Network Management Service: The settlement date is now mapped in response messages.

10.16. Version 1.46

  • The amount field is conditional for reversals.

  • Added information on the merchantInvoiceId field.

10.17. Version 1.45

Tokenization and Detokenization Response Result Codes

  • Additional Response Result Code mappings are added for Tokenization and Detokenization.

10.18. Version 1.44

Http Status Code Updates

  • PaymentsAPI will no longer send HTTP status code 400 for timeouts or declines.

RemoteBatchNr

  • RemoteBatchNr will be returned in network management responses.

10.19. Version 1.43

Fleet Field Updates

  • Fleet fields have been updated to allow variable-length values.

Version 1.42

  • Check Authorization support for basic payment requests.

Version 1.41

  • Added new pos.terminalRestrictions field to basic payment requests.

  • Added new fleet response field fleet.hostBasedPurchaseRestriction

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

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.