ConnectUP API Interface Specification

ACI Worldwide, Inc

2026-10-27

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.

  • Batch Management service - This service is used to send batch management request messages.

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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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})

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

fee.amount

The transaction fee amount (for example surcharge amount) in major denomination. A period (.) is used as the decimal separator. 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 twenty-five cents, the following value would be supplied (USD uses two decimals after the separator): 1.25.

Optional

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

fee.indicator

Indicates whether the transaction fee amount is a DEBIT or CREDIT to the acquirer.
​
Possible values are:
DEBIT - The fee is debited from the cardholder.
CREDIT - The fee is credited to the cardholder.

Optional. Required when fee.amount is present.

ANS6
DEBIT|CREDIT

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 "correlationId=0aec0a35-1db7-4604-b6c5-1bcec197b6de"
  -d "amount=21.00"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
  -d "merchant.acquiringInstitutionCode=12345678901"
  -d "merchant.marketplaceId=12345678901"
  -d "fee.amount=1.25"
  -d "fee.indicator=DEBIT"

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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

fee.amount

The transaction fee amount (for example surcharge amount) in major denomination. A period (.) is used as the decimal separator. 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 twenty-five cents, the following value would be supplied (USD uses two decimals after the separator): 1.25.

Optional

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

fee.indicator

Indicates whether the transaction fee amount is a DEBIT or CREDIT to the acquirer.
​
Possible values are:
DEBIT - The fee is debited from the cardholder.
CREDIT - The fee is credited to the cardholder.

Optional. Required when fee.amount is present.

ANS6
DEBIT|CREDIT

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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

fee.amount

The transaction fee amount (for example surcharge amount) in major denomination. A period (.) is used as the decimal separator. 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 twenty-five cents, the following value would be supplied (USD uses two decimals after the separator): 1.25.

Optional

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

fee.indicator

Indicates whether the transaction fee amount is a DEBIT or CREDIT to the acquirer.
​
Possible values are:
DEBIT - The fee is debited from the cardholder.
CREDIT - The fee is credited to the cardholder.

Optional. Required when fee.amount is present.

ANS6
DEBIT|CREDIT

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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

fee.amount

The transaction fee amount (for example surcharge amount) in major denomination. A period (.) is used as the decimal separator. 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 twenty-five cents, the following value would be supplied (USD uses two decimals after the separator): 1.25.

Optional

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

fee.indicator

Indicates whether the transaction fee amount is a DEBIT or CREDIT to the acquirer.
​
Possible values are:
DEBIT - The fee is debited from the cardholder.
CREDIT - The fee is credited to the cardholder.

Optional. Required when fee.amount is present.

ANS6
DEBIT|CREDIT

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

Credit Application request messages are created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/creditapplication resource.

The endpoint sets paymentType to CL. The optional creditApplicationType field selects the operation. When it is omitted, the request is treated as a CREDIT_APPLICATION; MEMBERSHIP_SIGNUP is also supported.

The minimum request fields are listed below. Authentication fields are conditionally required according to the authentication method in use.

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}

merchantTransactionId

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

Required

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

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

Identifies the transaction on the device that initiated the transaction.

Optional

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

pos.operatorId

Identifies the operator that initiated the transaction.

Optional

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

creditApplicationType

Identifies the Credit Application operation. If omitted, the request is treated as a CREDIT_APPLICATION. MEMBERSHIP_SIGNUP is also supported.

Optional

CREDIT_APPLICATION|MEMBERSHIP_SIGNUP

The request may include the following account, customer, and billing fields. These fields are sent in the request. The accountData container may be supplied when the application is associated with an existing application or account.

Parameter name Description Required Regex

accountData.applicationReferenceNo

The application reference number. It is used on both request and response messages. This field is conditionally required for existing, pre-screened, or pre-approved credit applications.

Conditionally Required

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

accountData.paymentPlanCode

The account payment plan code or credit plan.

Optional

N5
[0-9]{1,5}

accountData.paymentPurchaseIndicator

The payment or purchase frequency: WEEKLY, MONTHLY, or ANNUALLY.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

accountData.promoCode

The promotional code associated with the account application. For SVS, a value of 'Y' in this field enables promotional gift cards.

Optional

A1
[A-Za-z]{1}

accountData.transactionBillingMethodIndicator

The transaction billing method: RECURRING, INSTALLMENT_BILLING, or DEFERRED_BILLING.

Optional

RECURRING|​
INSTALLMENT_BILLING|​
DEFERRED_BILLING

customer.givenName

The first name or given name of the billing customer.

Optional

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

customer.middleName

The customer’s middle name or initial.

Optional

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

customer.surname

The last name or surname of the billing customer.

Optional

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

customer.email

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

Optional

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

customer.companyName

The customer’s company name.

Optional

ANS60
[\x20-\xFF]{1,60}

customer.telephone

The telephone number of the company or authorized person to contact.

Optional

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

customer.idType

The type of identification associated with the identification number of the customer.

Optional

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

customer.idNumber

The identification number of the customer.

Optional

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

customer.driverLicenseData

The scanned driver’s license information encoded in Base64 format.

Optional

ANS2000
[\x20-\xFF]{1,2000}

customer.additionalId1

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId2

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId3

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId4

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.cardHolderName

The actual customer name as embossed on the payment card.

Optional

ANS45
[\x20-\xFF]{1,45}

customer.dateOfBirth

The customer’s date of birth in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.suffix

The customer’s name suffix.

Optional

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

customer.gender

The customer’s gender.

Optional

A1
[a-zA-Z]{1}

customer.motherMaidenName

The customer’s mother’s maiden name.

Optional

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

customer.lengthAtAddress

The length of time the customer has lived at the current address, in YYMM format.

Optional

N4
[0-9]{4}

customer.businessTelephone

The customer’s business telephone number.

Optional

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

customer.previousAddress

The customer’s previous address, including street number and name.

Optional

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

customer.previousCity

The city of the customer’s previous address.

Optional

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

customer.previousState

The state or region of the customer’s previous address.

Optional

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

customer.previousPostcode

The postal code of the customer’s previous address.

Optional

AN9
[a-zA-Z0-9]{1,9}

customer.previousLengthAtAddress

The length of time at the customer’s previous address, in YYMM format.

Optional

N4
[0-9]{4}

customer.previousBusinessTelephone

The business telephone number associated with the customer’s previous address.

Optional

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

customer.housingCode

The customer’s housing status for the credit application.

Optional

RENT|​
OWN|​
OTHER

customer.occupationCode

The customer’s occupation code used for the credit application.

Optional

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

customer.yearlyIncome

The customer’s yearly income.

Optional

N8
[0-9]{1,8}

customer.primaryIncomeFrequency

The frequency of the customer’s primary income.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

customer.panderFlag

Indicates whether mail may be sent to the customer.

Optional

MAY_SEND_MAIL|​
SHOULD_NOT_SEND_MAIL

customer.insuranceIndicator

Indicates whether the customer selected insurance for card debt. This is used by authorizers that support online credit applications.

Optional

NOT_APPLICABLE|​
PURCHASING_INSURANCE|​
NO_PURCHASING_INSURANCE

customer.patriotPlace

The state or country code of the identification document supplied in the Credit Application request. For example, a passport uses a country code and a US driver’s license uses a state code.

Optional

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

customer.patriotIssueDate

The issue date of the identification document supplied in the Credit Application request, in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.patriotExpirationDate

The expiration date of the identification document supplied in the Credit Application request, in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.authorizedUser

Identifies an authorized user associated with the application.

Optional

ANS64
[\x20-\xFF]{1,64}

customer.jointAuthFlag

Indicates whether the application includes a joint applicant or an authorized buyer.

Optional

JOINT_APPLICATION|​
AUTHORIZED_BUYER

customer.relativeCode

Identifies the authorized buyer’s relationship to the primary customer.

Optional

OTHER|​
SPOUSE

customer.secondaryCustomerFirstName

The first name of the secondary customer.

Optional

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

customer.secondaryCustomerMiddleName

The middle name or initial of the secondary customer.

Optional

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

customer.secondaryCustomerSurname

The surname/last name of the secondary customer.

Optional

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

customer.secondaryCustomerDateOfBirth

The secondary customer’s date of birth in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.secondaryCustomerHomeTelephone

The secondary customer’s home telephone number.

Optional

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

customer.secondaryCustomerBusinessTelephone

The secondary customer’s business telephone number.

Optional

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

customer.secondaryCustomerYearlyIncome

The secondary customer’s yearly income.

Optional

N8
[0-9]{1,8}

customer.secondaryCustomerIncomeFrequency

The frequency of the secondary customer’s income.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

customer.cardIssuanceLevel

Indicates the number of times the card has been reissued.

Optional

N1
[0-9]{1}

customer.textFlag

Indicates whether the customer can be contacted via text messaging.

Optional

YES|​
NO

customer.ipAddress

The customer’s IP address.

Optional

ANS45
[\x20-\xFF]{1,45}

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

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

Optional

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

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

The postal code or zip code of the billing address.

Optional

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

billing.country

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

Optional

A2
[A-Z]{2}
Example request
curl {url_payment_credit_application} -v
  -H "Authorization: ******"
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "merchantTransactionId=CL-20260819-0001"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=UNKNOWN"
  -d "creditApplicationType=CREDIT_APPLICATION"
  -d "accountData.applicationReferenceNo=984456789012"
  -d "accountData.paymentPlanCode=12345"
  -d "customer.givenName=John"
  -d "customer.middleName=A"
  -d "customer.surname=Smith"
  -d "customer.dateOfBirth=19850123"
  -d "customer.additionalId1=010212345678"
  -d "customer.primaryIncomeFrequency=MONTHLY"
Credit Application response

The response contains the standard response fields documented in the Base Payment Operation Responses section. The following fields are specific to the credit application/account response data and are returned when supplied by the upstream service.

Parameter name Description Required Regex

accountData.applicationReferenceNo

The application reference number. It is used on both request and response messages. This field is conditionally required for existing, pre-screened, or pre-approved credit applications.

Conditional

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

accountData.referenceNo

The account reference number returned in the response.

Conditional

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

accountData.accountExpirationDateTime

The account expiration date and time in UTC, in YYYYMMDDTHHMMZ format.

Conditional

AN14
^\d{8}T\d{4}Z$

accountData.serialNumber

The account serial number returned in the response. For SVS this is returned in the response. This could be a primary account number.

Conditional

N16
[0-9]{1,16}

customer.givenName

The first name or given name of the billing customer.

Optional

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

customer.middleName

The customer’s middle name or initial.

Optional

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

customer.surname

The last name or surname of the billing customer.

Optional

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

customer.email

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

Optional

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

customer.companyName

The customer’s company name.

Optional

ANS60
[\x20-\xFF]{1,60}

customer.telephone

The telephone number of the company or authorized person to contact.

Optional

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

customer.idType

The type of identification associated with the identification number of the customer.

Optional

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

customer.idNumber

The identification number of the customer.

Optional

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

customer.driverLicenseData

The scanned driver’s license information encoded in Base64 format.

Optional

ANS2000
[\x20-\xFF]{1,2000}

customer.additionalId1

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId2

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId3

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId4

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.cardHolderName

The actual customer name as embossed on the payment card.

Optional

ANS45
[\x20-\xFF]{1,45}

customer.dateOfBirth

The customer’s date of birth in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.suffix

The customer’s name suffix.

Optional

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

customer.gender

The customer’s gender.

Optional

A1
[a-zA-Z]{1}

customer.motherMaidenName

The customer’s mother’s maiden name.

Optional

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

customer.lengthAtAddress

The length of time the customer has lived at the current address, in YYMM format.

Optional

N4
[0-9]{4}

customer.businessTelephone

The customer’s business telephone number.

Optional

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

customer.previousAddress

The customer’s previous address, including street number and name.

Optional

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

customer.previousCity

The city of the customer’s previous address.

Optional

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

customer.previousState

The state or region of the customer’s previous address.

Optional

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

customer.previousPostcode

The postal code of the customer’s previous address.

Optional

AN9
[a-zA-Z0-9]{1,9}

customer.previousLengthAtAddress

The length of time at the customer’s previous address, in YYMM format.

Optional

N4
[0-9]{4}

customer.previousBusinessTelephone

The business telephone number associated with the customer’s previous address.

Optional

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

customer.housingCode

The customer’s housing status for the credit application.

Optional

RENT|​
OWN|​
OTHER

customer.occupationCode

The customer’s occupation code used for the credit application.

Optional

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

customer.yearlyIncome

The customer’s yearly income.

Optional

N8
[0-9]{1,8}

customer.primaryIncomeFrequency

The frequency of the customer’s primary income.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

customer.panderFlag

Indicates whether mail may be sent to the customer.

Optional

MAY_SEND_MAIL|​
SHOULD_NOT_SEND_MAIL

customer.insuranceIndicator

Indicates whether the customer selected insurance for card debt. This is used by authorizers that support online credit applications.

Optional

NOT_APPLICABLE|​
PURCHASING_INSURANCE|​
NO_PURCHASING_INSURANCE

customer.patriotPlace

The state or country code of the identification document supplied in the Credit Application request. For example, a passport uses a country code and a US driver’s license uses a state code.

Optional

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

customer.patriotIssueDate

The issue date of the identification document supplied in the Credit Application request, in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.patriotExpirationDate

The expiration date of the identification document supplied in the Credit Application request, in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.authorizedUser

Identifies an authorized user associated with the application.

Optional

ANS64
[\x20-\xFF]{1,64}

customer.jointAuthFlag

Indicates whether the application includes a joint applicant or an authorized buyer.

Optional

JOINT_APPLICATION|​
AUTHORIZED_BUYER

customer.relativeCode

Identifies the authorized buyer’s relationship to the primary customer.

Optional

OTHER|​
SPOUSE

customer.secondaryCustomerFirstName

The first name of the secondary customer.

Optional

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

customer.secondaryCustomerMiddleName

The middle name or initial of the secondary customer.

Optional

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

customer.secondaryCustomerSurname

The surname/last name of the secondary customer.

Optional

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

customer.secondaryCustomerDateOfBirth

The secondary customer’s date of birth in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.secondaryCustomerHomeTelephone

The secondary customer’s home telephone number.

Optional

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

customer.secondaryCustomerBusinessTelephone

The secondary customer’s business telephone number.

Optional

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

customer.secondaryCustomerYearlyIncome

The secondary customer’s yearly income.

Optional

N8
[0-9]{1,8}

customer.secondaryCustomerIncomeFrequency

The frequency of the secondary customer’s income.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

customer.cardIssuanceLevel

Indicates the number of times the card has been reissued.

Optional

N1
[0-9]{1}

customer.textFlag

Indicates whether the customer can be contacted via text messaging.

Optional

YES|​
NO

customer.ipAddress

The customer’s IP address.

Optional

ANS45
[\x20-\xFF]{1,45}

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

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

Optional

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

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

The postal code or zip code of the billing address.

Optional

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

billing.country

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

Optional

A2
[A-Z]{2}

{displayData_text}

{displayData_text_desc}

Optional

{displayData_text_regex}

printData.text

Print Data returns additional information that can be printed at the POS device. For Credit Application transactions, this field is sent back in the response. It contains current information about the account, such as card number, card expiration date, credit limit, and temporary credit limit. Each print message consists of three elements:
​
Length of the print message, excluding the length field, expressed as `LLLL`.
The print destination field, which contains the `<Number of Print Destination Codes>`, `<Print Designation Code>`, and `<Printer Number>`.
The print message data.
When present, printData.receiptLines[n] provides receipt text as individual lines.
​
Supported print destination codes are:
`A1` Customer receipt
`A2` Customer check
`C2` Register journal
`D3` Register slip
`P1` Account number
`P2` Expiration date, formatted as YYMM
`P3` Credit line, formatted as DDDDDDDDDDDDCC+. For example, $500 = 00000000050000+
`P4` Temporary credit line
`P5` Payment purchase indicator
`P6` Customer service phone number
`P7` POS status description
`P8` Current account balance, formatted as DDDDDDDDDDDDCC+
`P9` Last statement balance, formatted as DDDDDDDDDDDDCC+
`Q0` Open to buy, formatted as DDDDDDDDDDDDCC+
`Q1` Minimum payment due, formatted as DDDDDDDDDDDDCC+
`Q2` Payment due date
`Q3` Customer name
`Q4` Product name
`Q5` In-store payment allowed
`Q6` APR, formatted as XX.XX
​
For a check response, a print line can be represented as `00321D3Day Store Total Cash Num…​`. In this example, the length field is `0032`, the print destination field is `1D3`, and the print message data is `Day Store Total Cash Num`.
​
For a declined response caused by invalid purchased items, a print message can be represented as `00281D3Account is restricted to:00111D3Beverage`. The length field is `LLLL`, the print destination field is `1D3`, and subsequent records contain the description of each item that can be purchased. A maximum of 20 items can be displayed.

Optional

an..9999 LLLLVAR
ANS9999
[\x20-\xFF]{1,9999}

printData.receiptLines[n]

A structured, line-by-line representation of receipt text. Each receiptLines element contains one line.

Optional

ANS999
[\x20-\xFF]{1,999}
Example response
{
  "id": "e8f59d02a466f35a7ece785d3e137e50",
  "result": {
    "code": "000.000.000",
    "description": "Transaction succeeded"
  },
  "accountData": {
    "applicationReferenceNo": "984456789012",
    "referenceNo": "123456789012",
    "serialNumber": "5201300002123456"
  },
  "customer": {
    "givenName": "JOHN",
    "middleName": "A",
    "surname": "SMITH",
    "additionalId1": "010212345678"
  },
  "displayData": {
    "text": "Approved"
  },
  "printData": {
    "text": "00151Q3JOHN A SMITH00181P300000000100000+00191P15201300002123456",
    "receiptLines": [
      "JOHN A SMITH",
      "00000000100000+",
      "5201300002123456"
    ]
  },
  "timestamp": "2026-08-19 12:00:00"
}

See the standard response section for the complete list of response fields.

2.1.6. Account Lookup

Account Lookup request messages are created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/accountlookup resource.

The Account Lookup endpoint identifies an account using card, customer, or account data. Requests to this endpoint are processed with paymentType set to AL. The request performs an account inquiry and does not require a transaction amount; the endpoint uses a zero transaction amount for the upstream request.

The minimum request fields are listed below. Authentication fields are conditionally required according to the authentication method in use.

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}

merchantTransactionId

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

Required

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

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

Identifies the transaction on the device that initiated the transaction.

Optional

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

pos.operatorId

Identifies the operator that initiated the transaction.

Optional

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

card.number

The Primary Account Number (PAN) of the physical card. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[0-9]{12,19})$

card.expiryMonth

The month that the card expires.

Conditionally Required

N2
[0-9]{2}

card.expiryYear

The year that the card expires.

Conditionally Required

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

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

Optional

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

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}

An account lookup can identify the customer using card data, an alternate cardholder locator, or the account, customer, and billing fields below. The customer and accountData fields shared with Credit Application use the same definitions as the Credit Application request.

Parameter name Description Required Regex

accountData.applicationReferenceNo

The application reference number. It is used on both request and response messages. This field is conditionally required for existing, pre-screened, or pre-approved credit applications.

Conditionally Required

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

accountData.paymentPlanCode

The account payment plan code or credit plan.

Optional

N5
[0-9]{1,5}

accountData.paymentPurchaseIndicator

The payment or purchase frequency: WEEKLY, MONTHLY, or ANNUALLY.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

accountData.promoCode

The promotional code associated with the account application. For SVS, a value of 'Y' in this field enables promotional gift cards.

Optional

A1
[A-Za-z]{1}

accountData.transactionBillingMethodIndicator

The transaction billing method: RECURRING, INSTALLMENT_BILLING, or DEFERRED_BILLING.

Optional

RECURRING|​
INSTALLMENT_BILLING|​
DEFERRED_BILLING

customer.driverLicenseData

The scanned driver’s license information encoded in Base64 format.

Optional

ANS2000
[\x20-\xFF]{1,2000}

customer.givenName

The first name or given name of the billing customer.

Optional

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

customer.middleName

The customer’s middle name or initial.

Optional

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

customer.surname

The last name or surname of the billing customer.

Optional

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

customer.email

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

Optional

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

customer.companyName

The customer’s company name.

Optional

ANS60
[\x20-\xFF]{1,60}

customer.telephone

The telephone number of the company or authorized person to contact.

Optional

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

customer.idType

The type of identification associated with the identification number of the customer.

Optional

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

customer.idNumber

The identification number of the customer.

Optional

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

customer.additionalId1

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId2

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId3

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId4

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.cardHolderName

The actual customer name as embossed on the payment card.

Optional

ANS45
[\x20-\xFF]{1,45}

customer.dateOfBirth

The customer’s date of birth in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.suffix

The customer’s name suffix.

Optional

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

customer.gender

The customer’s gender.

Optional

A1
[a-zA-Z]{1}

customer.motherMaidenName

The customer’s mother’s maiden name.

Optional

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

customer.lengthAtAddress

The length of time the customer has lived at the current address, in YYMM format.

Optional

N4
[0-9]{4}

customer.businessTelephone

The customer’s business telephone number.

Optional

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

customer.previousAddress

The customer’s previous address, including street number and name.

Optional

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

customer.previousCity

The city of the customer’s previous address.

Optional

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

customer.previousState

The state or region of the customer’s previous address.

Optional

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

customer.previousPostcode

The postal code of the customer’s previous address.

Optional

AN9
[a-zA-Z0-9]{1,9}

customer.previousLengthAtAddress

The length of time at the customer’s previous address, in YYMM format.

Optional

N4
[0-9]{4}

customer.previousBusinessTelephone

The business telephone number associated with the customer’s previous address.

Optional

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

customer.housingCode

The customer’s housing status for the credit application.

Optional

RENT|​
OWN|​
OTHER

customer.occupationCode

The customer’s occupation code used for the credit application.

Optional

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

customer.yearlyIncome

The customer’s yearly income.

Optional

N8
[0-9]{1,8}

customer.primaryIncomeFrequency

The frequency of the customer’s primary income.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

customer.panderFlag

Indicates whether mail may be sent to the customer.

Optional

MAY_SEND_MAIL|​
SHOULD_NOT_SEND_MAIL

customer.insuranceIndicator

Indicates whether the customer selected insurance for card debt. This is used by authorizers that support online credit applications.

Optional

NOT_APPLICABLE|​
PURCHASING_INSURANCE|​
NO_PURCHASING_INSURANCE

customer.patriotPlace

The state or country code of the identification document supplied in the Credit Application request. For example, a passport uses a country code and a US driver’s license uses a state code.

Optional

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

customer.patriotIssueDate

The issue date of the identification document supplied in the Credit Application request, in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.patriotExpirationDate

The expiration date of the identification document supplied in the Credit Application request, in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.authorizedUser

Identifies an authorized user associated with the application.

Optional

ANS64
[\x20-\xFF]{1,64}

customer.jointAuthFlag

Indicates whether the application includes a joint applicant or an authorized buyer.

Optional

JOINT_APPLICATION|​
AUTHORIZED_BUYER

customer.relativeCode

Identifies the authorized buyer’s relationship to the primary customer.

Optional

OTHER|​
SPOUSE

customer.secondaryCustomerFirstName

The first name of the secondary customer.

Optional

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

customer.secondaryCustomerMiddleName

The middle name or initial of the secondary customer.

Optional

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

customer.secondaryCustomerSurname

The surname/last name of the secondary customer.

Optional

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

customer.secondaryCustomerDateOfBirth

The secondary customer’s date of birth in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.secondaryCustomerHomeTelephone

The secondary customer’s home telephone number.

Optional

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

customer.secondaryCustomerBusinessTelephone

The secondary customer’s business telephone number.

Optional

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

customer.secondaryCustomerYearlyIncome

The secondary customer’s yearly income.

Optional

N8
[0-9]{1,8}

customer.secondaryCustomerIncomeFrequency

The frequency of the secondary customer’s income.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

customer.cardIssuanceLevel

Indicates the number of times the card has been reissued.

Optional

N1
[0-9]{1}

customer.textFlag

Indicates whether the customer can be contacted via text messaging.

Optional

YES|​
NO

customer.ipAddress

The customer’s IP address.

Optional

ANS45
[\x20-\xFF]{1,45}

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

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

Optional

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

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

The postal code or zip code of the billing address.

Optional

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

billing.country

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

Optional

A2
[A-Z]{2}
Example request
curl {url_payment_account_lookup} -v
  -H "Authorization: ******"
  -d "entityId=b964f0e254a717c1524355a6149b575d"
  -d "card.number=4444444444444448"
  -d "card.expiryMonth=05"
  -d "card.expiryYear=2018"
  -d "card.paymentIdentifier=ID5656555555"
  -d "merchantTransactionId=AL-20260819-0001"
  -d "pos.terminalId=34056111"
  -d "pos.storeId=78919753"
  -d "pos.entryMode=MANUAL"
  -d "accountData.applicationReferenceNo=984456789012"
  -d "customer.givenName=John"
  -d "customer.middleName=A"
  -d "customer.surname=Smith"
  -d "customer.additionalId1=010212345678"
  -d "customer.ipAddress=192.0.2.10"
Account Lookup response

The response contains the standard response fields documented in the Base Payment Operation Responses section. The following fields are specific to the account lookup response data and are returned when supplied by the upstream service.

Parameter name Description Required Regex

accountData.applicationReferenceNo

The application reference number. It is used on both request and response messages. This field is conditionally required for existing, pre-screened, or pre-approved credit applications.

Conditional

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

accountData.referenceNo

The account reference number returned in the response.

Conditional

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

accountData.accountExpirationDateTime

The account expiration date and time in UTC, in YYYYMMDDTHHMMZ format.

Conditional

AN14
^\d{8}T\d{4}Z$

accountData.serialNumber

The account serial number returned in the response. For SVS this is returned in the response. This could be a primary account number.

Conditional

N16
[0-9]{1,16}

customer.driverLicenseData

The scanned driver’s license information encoded in Base64 format.

Optional

ANS2000
[\x20-\xFF]{1,2000}

customer.givenName

The first name or given name of the billing customer.

Optional

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

customer.middleName

The customer’s middle name or initial.

Optional

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

customer.surname

The last name or surname of the billing customer.

Optional

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

customer.email

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

Optional

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

customer.companyName

The customer’s company name.

Optional

ANS60
[\x20-\xFF]{1,60}

customer.telephone

The telephone number of the company or authorized person to contact.

Optional

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

customer.idType

The type of identification associated with the identification number of the customer.

Optional

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

customer.idNumber

The identification number of the customer.

Optional

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

customer.additionalId1

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId2

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId3

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.additionalId4

AdditionalID identifies an additional customer value. Its format is `XXDDVV…​V`, where `XX` identifies the ID owner, `DD` identifies the ID type, and `VV…​V` is the ID value. For example: `010212345678`.
​
The ID owner is `01` for the primary card holder or `02` for the secondary card holder. The ID type is one of the following:
`00` Unspecified
`01` Credit
`02` Driver’s license
`03` Checking account
`04` Debit card
`05` Preferred shopper’s card
`06` State ID
`07` Social security number
`08` Student ID
`09` Employee ID
`10` Passport number
`11` Military ID
`12` Senior citizens ID
`50` Alternate value card
`51` Alternate credit card
`90` EBT card
`91` Calling card
`92` Value card
`93` Prepaid cellular
`94` eWIC card

Optional

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

customer.cardHolderName

The actual customer name as embossed on the payment card.

Optional

ANS45
[\x20-\xFF]{1,45}

customer.dateOfBirth

The customer’s date of birth in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.suffix

The customer’s name suffix.

Optional

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

customer.gender

The customer’s gender.

Optional

A1
[a-zA-Z]{1}

customer.motherMaidenName

The customer’s mother’s maiden name.

Optional

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

customer.lengthAtAddress

The length of time the customer has lived at the current address, in YYMM format.

Optional

N4
[0-9]{4}

customer.businessTelephone

The customer’s business telephone number.

Optional

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

customer.previousAddress

The customer’s previous address, including street number and name.

Optional

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

customer.previousCity

The city of the customer’s previous address.

Optional

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

customer.previousState

The state or region of the customer’s previous address.

Optional

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

customer.previousPostcode

The postal code of the customer’s previous address.

Optional

AN9
[a-zA-Z0-9]{1,9}

customer.previousLengthAtAddress

The length of time at the customer’s previous address, in YYMM format.

Optional

N4
[0-9]{4}

customer.previousBusinessTelephone

The business telephone number associated with the customer’s previous address.

Optional

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

customer.housingCode

The customer’s housing status for the credit application.

Optional

RENT|​
OWN|​
OTHER

customer.occupationCode

The customer’s occupation code used for the credit application.

Optional

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

customer.yearlyIncome

The customer’s yearly income.

Optional

N8
[0-9]{1,8}

customer.primaryIncomeFrequency

The frequency of the customer’s primary income.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

customer.panderFlag

Indicates whether mail may be sent to the customer.

Optional

MAY_SEND_MAIL|​
SHOULD_NOT_SEND_MAIL

customer.insuranceIndicator

Indicates whether the customer selected insurance for card debt. This is used by authorizers that support online credit applications.

Optional

NOT_APPLICABLE|​
PURCHASING_INSURANCE|​
NO_PURCHASING_INSURANCE

customer.patriotPlace

The state or country code of the identification document supplied in the Credit Application request. For example, a passport uses a country code and a US driver’s license uses a state code.

Optional

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

customer.patriotIssueDate

The issue date of the identification document supplied in the Credit Application request, in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.patriotExpirationDate

The expiration date of the identification document supplied in the Credit Application request, in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.authorizedUser

Identifies an authorized user associated with the application.

Optional

ANS64
[\x20-\xFF]{1,64}

customer.jointAuthFlag

Indicates whether the application includes a joint applicant or an authorized buyer.

Optional

JOINT_APPLICATION|​
AUTHORIZED_BUYER

customer.relativeCode

Identifies the authorized buyer’s relationship to the primary customer.

Optional

OTHER|​
SPOUSE

customer.secondaryCustomerFirstName

The first name of the secondary customer.

Optional

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

customer.secondaryCustomerMiddleName

The middle name or initial of the secondary customer.

Optional

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

customer.secondaryCustomerSurname

The surname/last name of the secondary customer.

Optional

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

customer.secondaryCustomerDateOfBirth

The secondary customer’s date of birth in YYYYMMDD format.

Optional

N8
[0-9]{8}

customer.secondaryCustomerHomeTelephone

The secondary customer’s home telephone number.

Optional

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

customer.secondaryCustomerBusinessTelephone

The secondary customer’s business telephone number.

Optional

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

customer.secondaryCustomerYearlyIncome

The secondary customer’s yearly income.

Optional

N8
[0-9]{1,8}

customer.secondaryCustomerIncomeFrequency

The frequency of the secondary customer’s income.

Optional

WEEKLY|​
MONTHLY|​
ANNUALLY

customer.cardIssuanceLevel

Indicates the number of times the card has been reissued.

Optional

N1
[0-9]{1}

customer.textFlag

Indicates whether the customer can be contacted via text messaging.

Optional

YES|​
NO

customer.ipAddress

The customer’s IP address.

Optional

ANS45
[\x20-\xFF]{1,45}

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

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

Optional

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

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

The postal code or zip code of the billing address.

Optional

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

billing.country

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

Optional

A2
[A-Z]{2}

{displayData_text}

{displayData_text_desc}

Optional

{displayData_text_regex}

printData.text

Print Data returns additional information that can be printed at the POS device. For Credit Application transactions, this field is sent back in the response. It contains current information about the account, such as card number, card expiration date, credit limit, and temporary credit limit. Each print message consists of three elements:
​
Length of the print message, excluding the length field, expressed as `LLLL`.
The print destination field, which contains the `<Number of Print Destination Codes>`, `<Print Designation Code>`, and `<Printer Number>`.
The print message data.
When present, printData.receiptLines[n] provides receipt text as individual lines.
​
Supported print destination codes are:
`A1` Customer receipt
`A2` Customer check
`C2` Register journal
`D3` Register slip
`P1` Account number
`P2` Expiration date, formatted as YYMM
`P3` Credit line, formatted as DDDDDDDDDDDDCC+. For example, $500 = 00000000050000+
`P4` Temporary credit line
`P5` Payment purchase indicator
`P6` Customer service phone number
`P7` POS status description
`P8` Current account balance, formatted as DDDDDDDDDDDDCC+
`P9` Last statement balance, formatted as DDDDDDDDDDDDCC+
`Q0` Open to buy, formatted as DDDDDDDDDDDDCC+
`Q1` Minimum payment due, formatted as DDDDDDDDDDDDCC+
`Q2` Payment due date
`Q3` Customer name
`Q4` Product name
`Q5` In-store payment allowed
`Q6` APR, formatted as XX.XX
​
For a check response, a print line can be represented as `00321D3Day Store Total Cash Num…​`. In this example, the length field is `0032`, the print destination field is `1D3`, and the print message data is `Day Store Total Cash Num`.
​
For a declined response caused by invalid purchased items, a print message can be represented as `00281D3Account is restricted to:00111D3Beverage`. The length field is `LLLL`, the print destination field is `1D3`, and subsequent records contain the description of each item that can be purchased. A maximum of 20 items can be displayed.

Optional

an..9999 LLLLVAR
ANS9999
[\x20-\xFF]{1,9999}

printData.receiptLines[n]

A structured, line-by-line representation of receipt text. Each receiptLines element contains one line.

Optional

ANS999
[\x20-\xFF]{1,999}

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

Indicates the credit limit amount for the account.

Optional

N8.N4
[0-9]{1,8}(\.[0-9]{1,4})?
Example response
{
  "id": "e8f59d02a466f35a7ece785d3e137e50",
  "amount": "0.00",
  "currency": "USD",
  "result": {
    "code": "000.000.000",
    "description": "Transaction succeeded"
  },
  "accountData": {
    "applicationReferenceNo": "984456789012",
    "referenceNo": "123456789012"
  },
  "customer": {
    "givenName": "JOHN",
    "middleName": "A",
    "surname": "SMITH",
    "additionalId1": "010212345678"
  },
  "displayData": {
    "text": "Approved"
  },
  "printData": {
    "text": "00151Q3JOHN A SMITH00181P300000000100000+00191P15201300002123456",
    "receiptLines": [
      "JOHN A SMITH",
      "00000000100000+",
      "5201300002123456"
    ]
  },
  "timestamp": "2026-08-19 12:00:00"
}

See the standard response section for the complete list of response fields.

2.1.7. 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

Required

RV

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-9]{1,11}
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.8. 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-9]{1,11}
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.9. 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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-9]{1,11}
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.10. 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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

card.number

The Primary Account Number (PAN) of the physical card. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

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|​PREPAY

merchant.marketplaceId

The marketplace ID.

Optional

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

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"
  -d "extendedPaymentType=PREPAY"
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.11. Fuel Price Update Request

This operation updates one configured fuel product for one service type.

A fuel price update request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/fleet/fuelpriceupdate resource.

The request must contain exactly one cart item, which identifies the configured fuel product in merchantItemId and supplies its decimal selling price in price. If fleet.serviceType is omitted, the request means self-service. Use SELF or 1 for self-service and FULL or 2 for full service.

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}

merchantTransactionId

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

Required

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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. At least six characters are required.

Required

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

fleet.serviceType

The type of service received at the card acceptor location. Named values are preferred; a single-character legacy value is also accepted. Named values: SELF, FULL, NON_FUEL_ONLY If omitted, the request means self-service.

Optional

ANS1..13
[\x20-\xFF]{1}|SELF|FULL|NON_FUEL_ONLY

cart.items[n].merchantItemId

The configured numeric fuel product code.

Required

N1..20
[0-9]{1,20}

cart.items[n].price

The decimalized selling price for the selected service type.

Required for each item

N2.N3
Maximum value: 99.994

cart.items[n].cashPrice

The cash-price. If omitted, it defaults to `price`.

Optional

N2.N3
Maximum value: 99.994

See the standard response fields for the response parameters returned for this request type.

JSON Example
{
  "entityId": "b964f0e254a717c1524355a6149b575d",
  "merchantTransactionId": "FUEL-PRICE-20260922-0001",
  "pos": {
    "terminalId": "12195611",
    "storeId": "78123753"
  },
  "fleet": {
    "serviceType": "SELF"
  },
  "cart": {
    "items": {
      "0": {
        "merchantItemId": "020",
        "price": "3.559",
        "cashPrice": "3.459"
      }
    }
  }
}
URL-encoded cURL Example
curl {url_payment_fuel_price_update} -v \
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..." \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "entityId=b964f0e254a717c1524355a6149b575d" \
  -d "merchantTransactionId=FUEL-PRICE-20260922-0001" \
  -d "pos.terminalId=12195611" \
  -d "pos.storeId=78123753" \
  -d "fleet.serviceType=SELF" \
  -d "cart.items[0].merchantItemId=020" \
  -d "cart.items[0].price=3.559" \
  -d "cart.items[0].cashPrice=3.459"

2.1.12. Check Stock Update Request

This operation tells the acquirer which pre-printed check number the terminal will print next.

A check stock update request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/fleet/checkstockupdate resource. The paymentType field is not required for this endpoint.

The request must contain exactly one check object, which supplies the next check number in check[n].formattedMicr.checkNr.

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}

merchantTransactionId

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

Required

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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. At least six characters are required.

Required

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

check[n].formattedMicr.checkNr

The pre-printed number of the next check the terminal will print.

Required

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

See the standard response fields for the response parameters returned for this request type.

JSON Example
{
  "entityId": "b964f0e254a717c1524355a6149b575d",
  "merchantTransactionId": "CHKSTOCK-20260922-0001",
  "pos": {
    "terminalId": "12195611",
    "storeId": "78123753"
  },
  "check": {
    "0": {
      "formattedMicr": {
        "checkNr": "1234567"
      }
    }
  }
}
URL-encoded cURL Example
curl {url_payment_check_stock_update} -v \
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..." \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "entityId=b964f0e254a717c1524355a6149b575d" \
  -d "merchantTransactionId=CHKSTOCK-20260922-0001" \
  -d "pos.terminalId=12195611" \
  -d "pos.storeId=78123753" \
  -d "check[0].formattedMicr.checkNr=1234567"

2.1.13. Check Reprint Request

This operation retrieves the check that was already authorized, so that it can be printed again.

A check reprint request is created by sending a POST request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/fleet/checkreprint resource. The paymentType field is not required for this endpoint. Requests support the application/x-www-form-urlencoded and application/json content types.

The request must contain exactly one check object, which identifies the check to reprint in check[n].formattedMicr.checkNr.

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}

merchantTransactionId

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

Required

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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. At least six characters are required.

Required

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

check[n].formattedMicr.checkNr

The number of the check to reprint.

Required

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

check[n].authorizationCode

The authorization code returned when the check was originally authorized.

Optional

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

When the acquirer holds the print image for the supplied check number, it is returned in the check.printData structure. See Check Data for these response parameters, and the standard response fields for the remaining response parameters. If the acquirer holds no print image for the supplied check number, the response carries an advice to contact the acquirer instead.

JSON Example
{
  "entityId": "b964f0e254a717c1524355a6149b575d",
  "merchantTransactionId": "CHKRPRT-20260922-0001",
  "pos": {
    "terminalId": "12195611",
    "storeId": "78123753"
  },
  "check": {
    "0": {
      "formattedMicr": {
        "checkNr": "1234567"
      },
      "authorizationCode": "987654"
    }
  }
}
URL-encoded cURL Example
curl {url_payment_check_reprint} -v \
  -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..." \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "entityId=b964f0e254a717c1524355a6149b575d" \
  -d "merchantTransactionId=CHKRPRT-20260922-0001" \
  -d "pos.terminalId=12195611" \
  -d "pos.storeId=78123753" \
  -d "check[0].formattedMicr.checkNr=1234567" \
  -d "check[0].authorizationCode=987654"

2.1.14. 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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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})

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

N..4
^[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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

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

N..4
^[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.15. 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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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})

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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})

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

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.17. 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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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})

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

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

Conditional

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.

Conditional

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-9]{1,11}
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.19. Stored-Value Top-up Request

This service is used to top-up or add minutes/airtime to a prepaid phone or other prepaid stored-value products. The top-up transaction allows customers to reload their prepaid account with additional funds or minutes.

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

The minimum requirements for sending a Stored-Value Top-up 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 during the Top-up operation.

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.

Optional

A3
[A-Z]{3}

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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})

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

prepaidMerchandise.productId

The product identifier for the prepaid merchandise being topped up.

Optional

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

prepaidMerchandise.productType

The type of prepaid merchandise product.
​
Possible values are:
TELEPHONE_PREPAY - Telephone prepaid top-up
CALLING_PLAN - Calling plan activation
ELECTRICITY - Electricity prepayment
OTHER - Other merchandise types

Optional

TELEPHONE_PREPAY|​
CALLING_PLAN|​
ELECTRICITY|​
OTHER

prepaidMerchandise.userId

The user identifier associated with the prepaid merchandise (e.g., mobile phone number for telephone prepaid top-up).

Optional

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

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

Example
Stored-Value Top-up Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/topup -v
	-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
	-d "entityId=b964f0e254a717c1524355a6149b575d"
	-d "card.number=4444444444444448"
	-d "card.expiryMonth=05"
	-d "card.expiryYear=2050"
	-d "amount=25.00"
	-d "currency=USD"
	-d "pos.terminalId=12195611"
	-d "pos.storeId=78123753"
	-d "pos.entryMode=MANUAL"
	-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
	-d "prepaidMerchandise.productId=7675012422"
	-d "prepaidMerchandise.productType=TELEPHONE_PREPAY"
	-d "prepaidMerchandise.userId=5551234567"
Stored-Value Top-up Response
{
    "amount": "25.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.20. Debit Adjustment

This payment operation Debit adjustment is issued towards correction of a 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

fee.amount

The transaction fee amount (for example surcharge amount) in major denomination. A period (.) is used as the decimal separator. 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 twenty-five cents, the following value would be supplied (USD uses two decimals after the separator): 1.25.

Optional

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

fee.indicator

Indicates whether the transaction fee amount is a DEBIT or CREDIT to the acquirer.
​
Possible values are:
DEBIT - The fee is debited from the cardholder.
CREDIT - The fee is credited to the cardholder.

Optional. Required when fee.amount is present.

ANS6
DEBIT|CREDIT

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.21. 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

fee.amount

The transaction fee amount (for example surcharge amount) in major denomination. A period (.) is used as the decimal separator. 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 twenty-five cents, the following value would be supplied (USD uses two decimals after the separator): 1.25.

Optional

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

fee.indicator

Indicates whether the transaction fee amount is a DEBIT or CREDIT to the acquirer.
​
Possible values are:
DEBIT - The fee is debited from the cardholder.
CREDIT - The fee is credited to the cardholder.

Optional. Required when fee.amount is present.

ANS6
DEBIT|CREDIT

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

Please note this payment operation has been deprecated and replaced by: Credit Request. 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.

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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

merchantTransactionId

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

Required

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

merchant.marketplaceId

The marketplace ID.

Optional

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

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.23. 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

Required

CV

card.number

The Primary Account Number (PAN) of the physical card. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Required

N6 or N12..19
^([0-9]{6}|[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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-9]{1,11}
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.24. 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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})

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

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

fee.amount

The transaction fee amount (for example surcharge amount) in major denomination. A period (.) is used as the decimal separator. 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 twenty-five cents, the following value would be supplied (USD uses two decimals after the separator): 1.25.

Optional

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

fee.indicator

Indicates whether the transaction fee amount is a DEBIT or CREDIT to the acquirer.
​
Possible values are:
DEBIT - The fee is debited from the cardholder.
CREDIT - The fee is credited to the cardholder.

Optional. Required when fee.amount is present.

ANS6
DEBIT|CREDIT

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.25. 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 require 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Optional

N6 or N12..19
^([0-9]{6}|[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})

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​

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-9]{1,11}
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 major denomination.

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",
        "proprietaryResponseInfo": "123456789105",
        "ecaTransactionStatus": "KEEP_PAPER_CHECK",
        "denialRecordNr": "1245245",
        "telecheckMicrSequenceNr": "123"
    }
}

2.1.26. Check Guarantee

This payment operation is used to guarantee personal checks.

A Check Guarantee 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 CG message are listed here. See the Specialized Payment Use Cases section for use cases that require 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

Required

CG

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Optional

N6 or N12..19
^([0-9]{6}|[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})

card.track1Data

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

Optional

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

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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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[n].feeExcluded

Indicates whether the check fee is excluded.
Valid values:
true - fee is excluded
false - fee is not excluded

Optional

true|false

check[n].singlePurpose

Indicates whether the draft can only be used for a single, designated purpose (e.g. one fuel stop, one repair job).
Valid values:
true - single purpose
false - not single purpose

Optional

true|false

check[n].authorizationCode

This code is used for authorization and tracking in financial transactions. These codes are typically provided by the authorizing agency and must be entered by the vendor or service provider to process or verify the transaction.

Optional

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

check[n].electronic

Indicates whether the check is an electronic check.
Valid values:
true - electronic check
false - not an electronic check

Optional

true|false
Check Guarantee Response

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

Parameter name Description Required Regex

check.serviceCharge

The service charge of the transaction. Values are expressed in the major denomination.

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 Guarantee Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v \
    -H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..." \
    -d "entityId=b964f0e254a717c1524355a6149b575d" \
    -d "paymentType=CG" \
    -d "amount=200.00" \
    -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" \
    -d "check[0].feeExcluded=false" \
    -d "check[0].singlePurpose=true" \
    -d "check[0].authorizationCode=AUTH1234567890" \
    -d "check[0].electronic=true"
Check Guarantee 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"
    }
}

2.1.27. 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 an 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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|​PREPAY

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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-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.28. 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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|​PREPAY

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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-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.29. 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-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=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.30. 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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditionally Required

N6 or N12..19
^([0-9]{6}|[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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

merchant.acquiringInstitutionCode

A code identifying the financial institution acting as the acquirer of this customer transaction.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-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=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.originalIso8583ResponseCode

Contains the response code of the original response message. Used when responding to duplicate transactions.

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

The new encrypted key material to be applied by the PED. Returned as a hex string. The content is scheme-specific: ​
​
ACI: ​
A signed PKI response block containing an HSM-derived IPEK encrypted under the PED’s public key, a host nonce, and supporting certificate data, as defined in the ACI RKD Interface Specification for PED Manufacturers. ​
VERIFONE_VRK, VERIFONE_VSD, INGENICO, PAX (offline schemes):​
A binary blob pre-provisioned by ACI operations. The PED handles decryption and key loading for its own scheme.

Conditional

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

resultDetails.rkdEchoData

Session correlation token generated by the server. It must be stored by the client and returned unchanged in the `rkdEchoData` field of the confirmation request. The session expires 10 minutes after the exchange response.

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}

result.authorizationIdExtended

The code assigned by the authorizing institution indicating approval. This field is used when the assigned code is longer than the standard result.authorizationId field.

Optional

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

printData.text

Print Data returns additional information that can be printed at the POS device. For Credit Application transactions, this field is sent back in the response. It contains current information about the account, such as card number, card expiration date, credit limit, and temporary credit limit. Each print message consists of three elements:
​
Length of the print message, excluding the length field, expressed as `LLLL`.
The print destination field, which contains the `<Number of Print Destination Codes>`, `<Print Designation Code>`, and `<Printer Number>`.
The print message data.
When present, printData.receiptLines[n] provides receipt text as individual lines.
​
Supported print destination codes are:
`A1` Customer receipt
`A2` Customer check
`C2` Register journal
`D3` Register slip
`P1` Account number
`P2` Expiration date, formatted as YYMM
`P3` Credit line, formatted as DDDDDDDDDDDDCC+. For example, $500 = 00000000050000+
`P4` Temporary credit line
`P5` Payment purchase indicator
`P6` Customer service phone number
`P7` POS status description
`P8` Current account balance, formatted as DDDDDDDDDDDDCC+
`P9` Last statement balance, formatted as DDDDDDDDDDDDCC+
`Q0` Open to buy, formatted as DDDDDDDDDDDDCC+
`Q1` Minimum payment due, formatted as DDDDDDDDDDDDCC+
`Q2` Payment due date
`Q3` Customer name
`Q4` Product name
`Q5` In-store payment allowed
`Q6` APR, formatted as XX.XX
​
For a check response, a print line can be represented as `00321D3Day Store Total Cash Num…​`. In this example, the length field is `0032`, the print destination field is `1D3`, and the print message data is `Day Store Total Cash Num`.
​
For a declined response caused by invalid purchased items, a print message can be represented as `00281D3Account is restricted to:00111D3Beverage`. The length field is `LLLL`, the print destination field is `1D3`, and subsequent records contain the description of each item that can be purchased. A maximum of 20 items can be displayed.

Optional

an..9999 LLLLVAR
ANS9999
[\x20-\xFF]{1,9999}

printData.receiptLines[n]

A structured, line-by-line representation of receipt text. Each receiptLines element contains one line.

Optional

ANS999
[\x20-\xFF]{1,999}

fleet

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

Optional

ANS255
[\x20-\xFF]{255}

fleet.truckingCompanyName

The trucking company name returned by the upstream processor.

Optional

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

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

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}
Known values for Healthy Benefits:
00 - Gallons
01 - Kilograms
02 - Liters
03 - Pounds
04 - Quarts
05 - Units
06 - Ounces
07 - Container
08 - Dozen
09 - Each
10 - Package
11 - Pair
12 - Tube
13 - Bottle
14 - Box
15 - Case or Carton
16 - Other

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, including tax (e.g. 2.37 or 27.00).

Optional

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

cart.items[n].netPrice

The decimalized unit price of the product, excluding tax (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

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

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

The number of purses applied for this discount.

Optional

N..2
[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

N..3
[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

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

cart.items[n].departmentCode

A merchant-specific code for the item.

Optional

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

cart.items[n].responseReason

In response messages, it reflects the response reason given by the host with regard to this line item.

Optional

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

purseData[n].purseId

A numeric identifier for the purse.

Optional

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

purseData[n].description

A description of the purse.

Optional

AN..20
[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

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

purseData[n].purseCode

The purse code returned by the processor in the response.

Optional

AN..16
[a-zA-Z0-9]{1,16}

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

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

benefitData.balances[n].programCode

The program code for the benefit.

Optional

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

benefitData.balances[n].programName

The program name for the benefit.

Optional

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

benefitData.balances[n].promotionCode

The promotion code for the benefit.

Optional

ANS..30
[\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

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

merchant.marketplaceId

The marketplace ID.

Optional

AN11
[a-zA-Z0-9]{1,11}
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",
    "authorizationIdExtended": "783276123456"
  },
  "customParameters": {
    "CUSTOM_KEY1": "CUSTOM_VALUE1",
    "CUSTOM_KEY2": "CUSTOM_VALUE2"
  },
  "resultDetails": {
    "bankField1": "1234"
  },
  "timestamp": "2019-09-06 12:22:44",
  "cart": {
    "items": [
      {
      "productCodeType": "UPC",
      "merchantItemId": "genericItemId",
      "classificationCode": "ALCOHOL",
      "categoryCode": "milk",
      "subCategoryCode": "skim",
      "quantity": "1",
      "unitOfMeasure": "lbs",
      "quantityOfPackageMeasure": 5,
      "price": "15.00",
      "netPrice": "15.50",
      "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",
      "responseReason": "Approved, and sufficient funds in purse"
      }
    ]
  },
  "purseData": [
    {
      "purseId": 234234324,
      "description": "purse description.",
      "balance": {
        "indicator": "CREDIT",
        "amount": "850.00"
      },
      "amountAuthorized": "850.00",
      "responseCode": "AVC_234234",
      "purseCode": "PC8857365"
    }
  ],
  "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%$."
      }
    ]
  },
  "correlationId": "0aec0a35-1db7-4604-b6c5-1bcec197b6de",
  "merchant": {
    "marketplaceId": "12345678901"
  }
}
Note
 Optional fields will only be returned when the request could be processed (no validation errors occurred on the fields in the request). The response 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)

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.

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
SOFTWARE_POS_DEVICE - Software Point of Sale Device
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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Required

N6 or N12..19
^([0-9]{6}|[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

N6 or N12..19
^([0-9]{6}|[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

N6 or N12..19
^([0-9]{6}|[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 Required Regex

result.cvvResponse

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

Optional

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 location information and/or name of merchant ,exclusive of city, state/region and country.

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.receivingInstitutionCode=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}

merchant.taxTreatment

Indicates how the merchant is handling taxes.

Optional

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

merchant.billingType

The billing type. Valid values:
DIRECT_BILL - Direct bill.
DIRECT_BILL_FUEL_ONLY - Direct bill, fuel only.
SETTLED - Settled.

Optional

DIRECT_BILL|​DIRECT_BILL_FUEL_ONLY|​SETTLED

merchant.billingCompanyName

The billing company name from the POS for loyalty sale transactions.

Optional

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

merchant.corporateTender

Indicates whether the POS requested that the transaction be processed as a corporate tender.

Optional

true|false

merchant.vatDocumentationIndicator

Indicates whether the merchant agrees for the issuer to "invoice on behalf of" the merchant (IOB) for VAT documentation.
Valid values:
AGREE - Merchant agrees for the issuer to invoice on its behalf.
AGREE_WITH_INCREMENTAL_CERTIFICATION - Merchant agrees for the issuer to invoice on its behalf and confirms incremental certification.
DO_NOT_AGREE - Merchant does not agree to VAT invoice on behalf.

Optional

AGREE|​AGREE_WITH_INCREMENTAL_CERTIFICATION|​DO_NOT_AGREE

customer.vatDocumentationIndicatorIssuer

Indicates whether the issuer agrees to provide VAT IOB ("invoice on behalf of") for the merchant.
Valid values:
AGREE - Issuer agrees to provide VAT IOB for the merchant.
AGREE_WITH_INCREMENTAL_CERTIFICATION_NON_EU - Issuer outside the Europe region agrees to provide VAT IOB for the merchant and confirms incremental certification.
DO_NOT_AGREE - Issuer does not agree to provide VAT IOB.

Optional

AGREE|​AGREE_WITH_INCREMENTAL_CERTIFICATION_NON_EU|​DO_NOT_AGREE

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

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

totalDiscountAmount

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

Optional

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

participantDiscountAmount

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

Optional

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

totalNonFuelAmount

The decimalized total gross amount (in the major denomination) of this purchase transaction related to non-fuel items.

Optional

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

totalNetNonFuelAmount

The decimalized total net amount (in the major denomination) of this purchase transaction related to non-fuel items.

Optional

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

totalNetAmount

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

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}

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

The decimalized discount tax amount (e.g. 46.89).

Optional

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

itemizedDiscounts[n].discountCode

The discount code supplied by the merchant.

Optional

ANS20
[\x20-\xFF]{1,20}
Known values for Healthy Benefits:
P - Paper coupon
E - Electronic coupon
M - Mixed: both paper and electronic coupons
X - Additional discounts are not allowed

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}
Known values for Healthy Benefits:
00 - Gallons
01 - Kilograms
02 - Liters
03 - Pounds
04 - Quarts
05 - Units
06 - Ounces
07 - Container
08 - Dozen
09 - Each
10 - Package
11 - Pair
12 - Tube
13 - Bottle
14 - Box
15 - Case or Carton
16 - Other

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, including tax (e.g. 2.37 or 27.00).

Optional

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

cart.items[n].netPrice

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

Optional

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

cart.items[n].corporate

Indicates whether the item is a corporate item.
Valid values:
true - corporate item
false - not a corporate item

Optional

true|false

cart.items[n].timeInfo[n].type

The type of time measurement.
Valid values:
TOTAL_TIME_PLUGGED_IN - Total time plugged in.
TOTAL_CHARGING_TIME - Total time actively charging.
START_TIME_OF_CHARGE - The time at which charging started.
FINISH_TIME_OF_CHARGE - The time at which charging finished.

Optional

TOTAL_TIME_PLUGGED_IN|​TOTAL_CHARGING_TIME|​START_TIME_OF_CHARGE|​FINISH_TIME_OF_CHARGE

cart.items[n].timeInfo[n].time

A six-digit value in hhmmss format. For TOTAL_TIME_PLUGGED_IN and TOTAL_CHARGING_TIME, hh represents elapsed hours (00-99). For START_TIME_OF_CHARGE and FINISH_TIME_OF_CHARGE, the value represents the local time at the card acceptor location, with hh as the hour (00-23). In all cases, mm represents minutes (00-59) and ss represents seconds (00-59).

Optional

hhmmss
[0-9]{2}([0-5][0-9])([0-5][0-9])

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}
Known values for Healthy Benefits:
P - Paper coupon
E - Electronic coupon
M - Mixed: both paper and electronic coupons
X - Additional discounts are not allowed

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

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

A merchant-specific code for the item.

Optional

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

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=PA" \
	-d "card.number=4444444444444448" \
	-d "card.expiryMonth=05" \
	-d "card.expiryYear=2050" \
	-d "card.accountType=DEFAULT" \
	-d "amount=21.00" \
	-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.billingType=SETTLED" \
	-d "merchant.billingCompanyName=Acme Fleet Services" \
	-d "merchant.corporateTender=true" \
	-d "merchant.vatDocumentationIndicator=AGREE" \
	-d "customer.vatDocumentationIndicatorIssuer=AGREE" \
	-d "merchant.geographicCoordinates=5.78381,0.72175" \
	-d "merchant.serviceLocationGeographicCoordinates=6.78381,0.72176" \
	-d "totalShippingAmount=0.00" \
	-d "totalDutyAmount=0.00" \
	-d "totalDiscountAmount=1.00" \
	-d "participantDiscountAmount=1.00" \
	-d "totalNonFuelAmount=22.00" \
	-d "totalNetNonFuelAmount=20.00" \
	-d "totalNetAmount=21.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=2.00" \
	-d "taxAmounts[0].tax=00.10" \
	-d "taxAmounts[0].taxId=G&S_taxes" \
	-d "taxAmounts[0].taxDescription=State GS" \
	-d "itemizedDiscounts[0].amount=1.00" \
	-d "itemizedDiscounts[0].rate=500" \
	-d "itemizedDiscounts[0].discountCode=LOYALTY5" \
	-d "cart.items[0].description=EV charging session" \
	-d "cart.items[0].merchantItemId=CHARGE-001" \
	-d "cart.items[0].quantity=1" \
	-d "cart.items[0].unitOfMeasure=EACH" \
	-d "cart.items[0].totalAmount=22.00" \
	-d "cart.items[0].totalAmountType=GROSS" \
	-d "cart.items[0].sku=EV-CHARGE" \
	-d "cart.items[0].price=22.00" \
	-d "cart.items[0].netPrice=20.00" \
	-d "cart.items[0].corporate=true" \
	-d "cart.items[0].timeInfo[0].type=TOTAL_CHARGING_TIME" \
	-d "cart.items[0].timeInfo[0].time=003000" \
	-d "cart.items[0].timeInfo[1].type=START_TIME_OF_CHARGE" \
	-d "cart.items[0].timeInfo[1].time=120000" \
	-d "cart.items[0].discountAmount=1.00" \
	-d "cart.items[0].discount=00500" \
	-d "cart.items[0].productCodeType=SERVICE_OR_DELIVERY_CHARGES" \
	-d "cart.items[0].classificationCode=SNAP_ELIGIBLE" \
	-d "cart.items[0].categoryCode=Milk" \
	-d "cart.items[0].subCategoryCode=Skim" \
	-d "cart.items[0].departmentCode=EVCHARGING" \
	-d "cart.items[0].taxAmounts[0].taxType=STATE_SALES" \
	-d "cart.items[0].taxAmounts[0].totalTaxAmount=2.00" \
	-d "cart.items[0].taxAmounts[0].tax=00.10" \
	-d "cart.items[0].taxAmounts[0].taxId=state_tax" \
	-d "cart.items[0].taxAmounts[0].taxDescription=State sales tax" \
	-d "cart.items[0].itemizedDiscounts[0].amount=1.00" \
	-d "cart.items[0].itemizedDiscounts[0].rate=500" \
	-d "cart.items[0].itemizedDiscounts[0].discountCode=LOYALTY5" \
	-d "cart.items[0].itemizedDiscounts[0].type=STORE"
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.
Response

The payment response may contain Level 2 and Level 3 data.

Parameter name Description Required Regex

customer.vatDocumentationIndicatorIssuer

Indicates whether the issuer agrees to provide VAT IOB ("invoice on behalf of") for the merchant.
Valid values:
AGREE - Issuer agrees to provide VAT IOB for the merchant.
AGREE_WITH_INCREMENTAL_CERTIFICATION_NON_EU - Issuer outside the Europe region agrees to provide VAT IOB for the merchant and confirms incremental certification.
DO_NOT_AGREE - Issuer does not agree to provide VAT IOB.

Optional

AGREE|​AGREE_WITH_INCREMENTAL_CERTIFICATION_NON_EU|​DO_NOT_AGREE

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

The decimalized price of one unit of the product from the original request, echoed back in the response as originally submitted.

Optional

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

cart.items[n].originalQuantity

The decimalized quantity of the product from the original request. Can be sent in response messages, and contains the original quantity value as submitted, even if it differs from the quantity field in the response.

Optional

N9.N3
[0-9]{1,9}(\.[0-9]{1,3})?
Example Response
{
	"amount": "21.00",
    "currency": "USD",
    "id": "ce6b3d18b660db9aa7ef667be8f098d2",
    "result": {
        "code": "000.000.000",
        "description": "Transaction succeeded",
        "authorizationId": "071797"
    },
    "timestamp": "2021-05-19 12:01:06",
    "resultDetails": {
        "retrievalReferenceNumber": "000000001363",
        "commercialCardIndicator": "Y",
        "level3InterchangeEligible": "Y"
    },
    "customer": {
        "vatDocumentationIndicatorIssuer": "AGREE"
    },
	"cart": {
		"items": [
			{
				"actionCode": "APPROVED",
				"originalPrice": "22.00",
				"originalQuantity": "1",
				"merchantItemId": "CHARGE-001",
				"quantity": "1",
				"unitOfMeasure": "EACH",
				"totalAmount": {
					"indicator": "DEBIT",
					"amount": "22.00"
				},
				"price": "22.00",
				"netPrice": "20.00"
			}
		]
	}
}

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, fleet.additionalPrompts, fleet.receiptLine, fleet.fleetBatchDataList, and fleet.commercialPromptResult 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

N..4
[0-9]{1,4}

fleet.serviceType

The type of service received at the card acceptor location. Named values are preferred; a single-character legacy value is also accepted. Named values: SELF, FULL, NON_FUEL_ONLY

Optional

ANS1..13
[\x20-\xFF]{1}|SELF|FULL|NON_FUEL_ONLY

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

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

fleet.vehicleReg

The registration number of the rented or fleet vehicle.

Optional

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

fleet.driverId

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

Optional

ANS..20
[\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

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

fleet.privateData

Any data proprietary to the system for this item.

Optional

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

fleet.purchaseType

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

Optional

A1
F|N|B|M

fleet.receiptText

The receipt text.

Optional

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

fleet.receiptLine[n]

The lines of text to be printed on the receipt.

Optional

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

fleet.promptForOdometer

Indicates whether the odometer prompt is required to complete the transaction.
Valid values:
false - Odometer is not required to complete transaction
true - Odometer is required to complete transaction

Optional

true|false

fleet.printPricePerGallon

Indicates whether the price per gallon is printed or displayed on the customer receipt.
Valid values:
true - Print price per gallon on customer receipt
false - Do not print price per gallon on customer receipt

Optional

true|false

fleet.maximumAmount

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

Optional

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

fleet.maximumOilAmount

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

Optional

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

fleet.maximumPartsAmount

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

Optional

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

fleet.maximumAmountOther

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

Optional

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

fleet.chargingPowerOutputCapacity

The charging station power output capacity in kW.

Optional

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

fleet.chargingReasonCode

Identifies the outcome or error that ended the electric vehicle charging session. Valid values:
`OTHER_ERROR` - Charging ended abnormally for an error not represented by another value.
`CONNECTOR_LOCK_FAILURE` - The charge point could not lock or unlock the connector.
`EV_COMMUNICATION_ERROR` - Communication between the charge point and vehicle failed.
`GROUND_FAILURE` - The ground-fault protection circuit was activated.
`HIGH_TEMPERATURE` - The temperature inside the charge point exceeded its acceptable limit.
`INTERNAL_ERROR` - An internal hardware or software component failed.
`OVER_CURRENT_FAILURE` - The over-current protection device was activated.
`OVER_VOLTAGE` - The voltage exceeded its acceptable level.
`POWER_METER_FAILURE` - The charge point could not read its power meter.
`POWER_SWITCH_FAILURE` - The charge point could not control its power switch.
`READER_FAILURE` - The identification tag reader failed.
`RESET_FAILURE` - The charge point could not complete a reset.
`UNDER_VOLTAGE` - The voltage dropped below its acceptable level.
`WEAK_SIGNAL` - The wireless communication device reported a weak signal.
`NO_ERROR` - No charging error was reported.
`PAYMENT_RELATED_ERROR` - Charging ended abnormally because of a payment-related error.

Optional

OTHER_ERROR|​CONNECTOR_LOCK_FAILURE|​EV_COMMUNICATION_ERROR|​GROUND_FAILURE|​HIGH_TEMPERATURE|​INTERNAL_ERROR|​OVER_CURRENT_FAILURE|​OVER_VOLTAGE|​POWER_METER_FAILURE|​POWER_SWITCH_FAILURE|​READER_FAILURE|​RESET_FAILURE|​UNDER_VOLTAGE|​WEAK_SIGNAL|​NO_ERROR|​PAYMENT_RELATED_ERROR

fleet.estimatedKmOrMilesAdded

The estimated driving distance added by the charging session, based on the energy delivered in kWh and the vehicle type.

Optional

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

fleet.carbonFootprintAvoidance

The carbon footprint avoidance measurement, i.e. how much was saved from this charge, measured in grams of carbon dioxide equivalent (CO2e).

Optional

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

fleet.estimatedVehicleKmOrMilesAvailable

After charge completion, provides the estimated mileage the car will have once it leaves the EV charging station.

Optional

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

fleet.maximumPowerDispensed

The maximum power dispensed during the charging session, in kW.

Optional

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

fleet.chargingConnectorType

Identifies the physical connector used for the electric vehicle charging session. Valid values:
`AC_J1772_TYPE_1` - AC charging using an SAE J1772 Type 1 connector.
`AC_MENNEKES_TYPE_2` - AC charging using an IEC 62196 Type 2 (Mennekes) connector.
`AC_GB_T` - AC charging using a connector defined by the Chinese GB/T standard.
`DC_CCS1` - DC fast charging using a CCS Combo 1 connector.
`DC_CHADEMO` - DC fast charging using a CHAdeMO connector.
`DC_CCS2` - DC fast charging using a CCS Combo 2 connector.
`DC_GB_T` - DC fast charging using a connector defined by the Chinese GB/T standard.
`NACS` - AC or DC charging using the North American Charging Standard (SAE J3400) connector.
`DC_MCS` - High-power DC charging using the Megawatt Charging System (MCS) connector.

Optional

AC_J1772_TYPE_1|​AC_MENNEKES_TYPE_2|​AC_GB_T|​DC_CCS1|​DC_CHADEMO|​DC_CCS2|​DC_GB_T|​NACS|​DC_MCS

fleet.pumpNumber

The fuel pump number. This attribute is used when the pump number is sent from the POS.

Optional

AN..99
[a-zA-Z0-9]{1,99}

fleet.siteTransactionNumber

The POS transaction number or original transaction number. This attribute is used when the transaction number is not a prompt value.

Optional

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

fleet.truckingCompanyName

The trucking company name provided by the POS.

Optional

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

fleet.fuelPrePay

Indicates whether the transaction is a pre-pay fuel transaction, which is paid prior to dispensing and the dispenser automatically stops at the prepaid amount.
Valid values:
true - fuel pre-pay
false - not fuel pre-pay

Optional

true|false

fleet.prompts[n].userId

The user identification number.

Optional

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

fleet.prompts[n].vehicleId

The vehicle identification number.

Optional

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

fleet.prompts[n].department

The department number.

Optional

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

fleet.prompts[n].driverLicense

The driver license number.

Optional

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

fleet.prompts[n].customerData

Any customer data.

Optional

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

fleet.prompts[n].customerData1

Any customer data.

Optional

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

fleet.prompts[n].customerData2

Any additional customer data.

Optional

ANS..20
[\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

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

fleet.prompts[n].siteTransactionNumber

The site transaction number.

Optional

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

fleet.prompts[n].jobId

The job identification number.

Optional

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

fleet.prompts[n].contractNumber

The contract number.

Optional

AN..25
[a-zA-Z0-9_]{1,25}

fleet.prompts[n].PIN

The vehicle PIN number.

Optional

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

fleet.prompts[n].tripNumber

The fleet trip number.

Optional

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

fleet.prompts[n].unitNumber

The fleet unit number.

Optional

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

fleet.prompts[n].trailerId

The fleet trailer identification.

Optional

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

fleet.prompts[n].trailerHours

The fleet trailer hours number.

Optional

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

fleet.prompts[n].maintenanceId

The fleet maintenance identification.

Optional

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

fleet.prompts[n].hubometer

The fleet hubometer number.

Optional

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

fleet.prompts[n].employeeNumber

The fleet employee number.

Optional

N..20
[\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

ANS..20
[\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

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

fleet.prompts[n].trailerLicenseState

The trailer license state code.

Optional

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

fleet.prompts[n].fleetId

The ID that is defined to the fleet authorizer.

Optional

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

fleet.prompts[n].customData

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

Optional

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

fleet.prompts[n].vehicleTag

The fleet vehicle tag.

Optional

AN..99
[a-zA-Z0-9]{1,99}

fleet.prompts[n].driverLicenseLocation

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

Optional

AN..3
[a-zA-Z0-9]{1,3}

fleet.prompts[n].driverLicenseName

The driver license name.

Optional

ANS..22
[\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

AN..17
[a-zA-Z0-9]{1,17}

fleet.prompts[n].pumpNumber

The fuel pump number.

Optional

AN..99
[a-zA-Z0-9]{1,99}

fleet.prompts[n].tractorNumber

The tractor number.

Optional

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

fleet.additionalPrompts[n].type

The type of prompt.
Valid values:
ADDITIONAL_CARD_DATA
ADDITIONAL_VEHICLE_DATA
BATTERY_VOLTAGE
BILLING_ID
CHECK_ENGINE_STATUS
CONTROL_NUMBER
COOLANT_TEMPERATURE
CUSTOMER_NUMBER
DELIVERY_TICKET_NUMBER
DRIVER_OR_VEHICLE_CARD
DRIVER_PASSPORT
ENGINE_HOURS
ENGINE_LOAD
ENGINE_OIL_LIFE
ENGINE_OIL_PRESSURE
ENGINE_OIL_TEMPERATURE
ENGINE_RPM
ENGINE_TIME_TOTAL
ENTERED_DATA_ALPHA
ENTERED_DATA_NUM
FUEL_ECONOMY
FUEL_GAUGE_LEVEL
HARD_ACCELERATION
HARD_BRAKING
IDLE_TIME
REEFER_TEMPERATURE
REPLACEMENT_CAR
SUB_FLEET_NUMBER
TANK_LEVEL_START
TOTAL_IDLE_TIME
TRANSACTION_NUMBER
WEB_PORTAL_DATA
ZIP_CODE_OR_POSTAL_CODE

Optional

ADDITIONAL_CARD_DATA|​
ADDITIONAL_VEHICLE_DATA|​
BATTERY_VOLTAGE|​
BILLING_ID|​
CHECK_ENGINE_STATUS|​
CONTROL_NUMBER|​
COOLANT_TEMPERATURE|​
CUSTOMER_NUMBER|​
DELIVERY_TICKET_NUMBER|​
DRIVER_OR_VEHICLE_CARD|​
DRIVER_PASSPORT|​
ENGINE_HOURS|​
ENGINE_LOAD|​
ENGINE_OIL_LIFE|​
ENGINE_OIL_PRESSURE|​
ENGINE_OIL_TEMPERATURE|​
ENGINE_RPM|​
ENGINE_TIME_TOTAL|​
ENTERED_DATA_ALPHA|​
ENTERED_DATA_NUM|​
FUEL_ECONOMY|​
FUEL_GAUGE_LEVEL|​
HARD_ACCELERATION|​
HARD_BRAKING|​
IDLE_TIME|​
REEFER_TEMPERATURE|​
REPLACEMENT_CAR|​
SUB_FLEET_NUMBER|​
TANK_LEVEL_START|​
TOTAL_IDLE_TIME|​
TRANSACTION_NUMBER|​
WEB_PORTAL_DATA|​
ZIP_CODE_OR_POSTAL_CODE

fleet.additionalPrompts[n].value

The value for the specific prompt type. The prompt type determines the meaning, format, and unit of measure. For measurement types, use the unit configured by the upstream processor.

Optional

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

fleet.fleetBatchDataList[n].batchDate

The fleet batch date.

Optional

N8
[0-9]{8}

fleet.fleetBatchDataList[n].transactionCount

The transaction count for a batch.

Optional

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

fleet.fleetBatchDataList[n].total

The total fuel quantity.

Optional

N..99
[0-9]{1,99}

fleet.fleetBatchDataList[n].totalUnit

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

Optional

Gallons|Liters

fleet.commercialPromptResult[n].name

The name of the prompt.

Optional

ADDITIONAL_PRODUCTS|​ADDL_DATA_1|​ADDL_DATA_2|​ADDRESS|​AMOUNT|​APPROVAL_NUMBER|​BDAY|​BILLER|​CARD_TOKEN|​CASH_ADVANCE|​CHECK_CASH|​CHECK_DIGIT|​CHECK_NUMBER|​CODE|​CVV|​CVV2|​DATA|​DEPT_NUM|​DL_NUMBER|​DLSSN|​DLST|​DL_STATE|​DOB|​DRAFT_NUMBER|​DRIVER_ID|​DRIVER_INITIAL|​DRIVER_LAST_NAME|​DRIVER_FNAME|​DRIVER_NAME|​EMPLOYEE_NUM|​EXPRESS_CODE|​FIRST_INITIAL|​FIRST_NAME|​FSTI|​FLEET_NUMBER|​HUB_ODOMETER|​ID_NUMBER|​JOB_NUMBER|​LAST_NAME|​LOYALTY_CARD|​MONEY_CODE|​NC_FIRST_NAME|​NC_LAST_NAME|​ODOMETER|​ONE_CHECK|​QCODE|​PDSN|​PIN_DATA|​PIN|​PIN_KEY_SEQUENCE_NUMBER|​PO_NUMBER|​POSTAL_CODE|​PROCESSING_OPTION|​RESTRICTION_CODE|​START_CODE|​SWITCH_KEY|​TRAILER_NUMBER|​TRIP_NUMBER|​USER_ID|​VEHICLE_ID|​ZIP_CODE|​PIN_NUM|​STORE_PHONE|​TRAILER_HOURS|​TL_STATE|​TL_NUMBER|​TRAILER_ID|​PRE_AUTH_NUM|​TRAILER_HUB|​LICENSE_PLATE|​BILLING_ID|​VEHICLE_NUMBER|​DELIVERY_TICKET_NR|​CARRIER_ID|​VIN|​ACTIVE_FAULTS|​ENGINE_ODOMETER|​FUEL_LEVEL|​TOTAL_FUEL_USED|​IDLE_TIME|​ISNB|​TRNB|​REAL_PAN|​RTMP|​SSUB|​PPIN|​LSTN|​CNTN|​LCST

fleet.commercialPromptResult[n].value

The value entered for the prompt.

Optional

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

fleet.commercialPromptResult[n].verified

Indicates whether the entered value was verified. Valid values: true - the value has been verified; false - the value has not been verified.

Optional

true|false
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=2" \
	-d "fleet.restrictionCode= 1 " \
	-d "fleet.privateData= Private Data 123" \
	-d "fleet.purchaseType=B" \
	-d "fleet.receiptText=Receipt text line 1" \
	-d "fleet.receiptLine[0]=Store: Main Street Location" \
	-d "fleet.receiptLine[1]=Thank you for your business" \
	-d "fleet.receiptLine[2]=Visit us again soon" \
	-d "fleet.promptForOdometer=true" \
	-d "fleet.printPricePerGallon=true" \
	-d "fleet.maximumAmount=50000" \
	-d "fleet.maximumOilAmount=10000" \
	-d "fleet.maximumPartsAmount=20000" \
	-d "fleet.maximumAmountOther=15000" \
	-d "fleet.chargingPowerOutputCapacity=150" \
	-d "fleet.chargingReasonCode=NO_ERROR" \
	-d "fleet.estimatedKmOrMilesAdded=320" \
	-d "fleet.carbonFootprintAvoidance=12500" \
	-d "fleet.estimatedVehicleKmOrMilesAvailable=450" \
	-d "fleet.maximumPowerDispensed=120" \
	-d "fleet.chargingConnectorType=DC_CCS2" \
	-d "fleet.pumpNumber=PUMP05" \
	-d "fleet.siteTransactionNumber=234234324" \
	-d "fleet.truckingCompanyName=ABC Trucking Inc" \
	-d "fleet.fuelPrePay=true" \
	-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.additionalPrompts[0].type=BATTERY_VOLTAGE" \
	-d "fleet.additionalPrompts[0].value=12.6 V" \
	-d "fleet.additionalPrompts[1].type=FUEL_ECONOMY" \
	-d "fleet.additionalPrompts[1].value=PROCESSOR_FORMATTED_VALUE" \
	-d "fleet.fleetBatchDataList[0].batchDate=20210607" \
	-d "fleet.fleetBatchDataList[0].transactionCount=0000001112" \
	-d "fleet.fleetBatchDataList[0].total=00000111155544" \
	-d "fleet.fleetBatchDataList[0].totalUnit=Liters" \
	-d "fleet.commercialPromptResult[0].name=VEHICLE_NUMBER" \
	-d "fleet.commercialPromptResult[0].value=TRUCK12345" \
	-d "fleet.commercialPromptResult[0].verified=true" \
	-d "fleet.commercialPromptResult[1].name=DRIVER_ID" \
	-d "fleet.commercialPromptResult[1].value=DRV789" \
	-d "fleet.commercialPromptResult[1].verified=false"
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. Fleet restriction entries are returned using an indexed array [n], starting with 0.

Parameter name Description Required Regex

fleet.promptForOdometer

The prompt is required to complete the transaction or not.

Optional

N1
[0-9]{1}

fleet.printPricePerGallon

Indicates whether the price per gallon is printed or displayed on the 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

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

fleet.maximumOilAmount

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

Optional

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

fleet.maximumPartsAmount

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

Optional

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

fleet.maximumAmountOther

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

Optional

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

fleet.hostBasedPurchaseRestriction

The host-based purchase restriction data.

Optional

ans..32
[\x20-\xFF]{1,32}

fleet.restriction[n].cashLimit

The cash limit, expressed in the major denomination of the transaction currency. A period is used as the decimal separator.

Optional

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

fleet.restriction[n].invoiceTotalLimit

The invoice total limit, expressed in the major denomination of the transaction currency. A period is used as the decimal separator.

Optional

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

fleet.restriction[n].miscellaneousTotalLimit

The miscellaneous total limit, expressed in the major denomination of the transaction currency. A period is used as the decimal separator.

Optional

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

fleet.restriction[n].additiveTotalLimit

The additive total limit, expressed in the major denomination of the transaction currency. A period is used as the decimal separator.

Optional

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

fleet.restriction[n].repairAmountLimit

The repair amount limit, expressed in the major denomination of the transaction currency. A period is used as the decimal separator.

Optional

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

fleet.restriction[n].customerName

The name of the customer.

Optional

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

fleet.restriction[n].customerCity

The city of the customer.

Optional

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

fleet.restriction[n].customerState

The state of the customer.

Optional

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

reAuthRequired

Indicates whether a reauthorization of the transaction is required.

Optional

true|false

fleet.restriction[n].code

The restriction code.

Optional

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

fleet.restriction[n].amount

The restriction code amount, expressed in the major denomination of the transaction currency. A period is used as the decimal separator.

Optional

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

fleet.restriction[n].quantity

The restriction code quantity without leading zero padding.

Optional

N..5
[0-9]{1,5}

fleet.restriction[n].unitOfMeasure

The unit in which the restriction quantity is expressed.

Optional

CASE_OR_CARTON|​GALLONS|​KILOGRAMS|​LITERS|​OTHER|​POUNDS|​QUARTS|​UNITS|​OUNCES|​DIESEL_GALLON_EQUIVALENT|​GASOLINE_GALLON_EQUIVALENT|​DIESEL_LITER_EQUIVALENT|​GASOLINE_LITER_EQUIVALENT|​PERCENTAGE

fleet.commercialRequestedPrompt[n].name

The name of the prompt.

Optional

ADDITIONAL_PRODUCTS|​ADDL_DATA_1|​ADDL_DATA_2|​ADDRESS|​AMOUNT|​APPROVAL_NUMBER|​BDAY|​BILLER|​CARD_TOKEN|​CASH_ADVANCE|​CHECK_CASH|​CHECK_DIGIT|​CHECK_NUMBER|​CODE|​CVV|​CVV2|​DATA|​DEPT_NUM|​DL_NUMBER|​DLSSN|​DLST|​DL_STATE|​DOB|​DRAFT_NUMBER|​DRIVER_ID|​DRIVER_INITIAL|​DRIVER_LAST_NAME|​DRIVER_FNAME|​DRIVER_NAME|​EMPLOYEE_NUM|​EXPRESS_CODE|​FIRST_INITIAL|​FIRST_NAME|​FSTI|​FLEET_NUMBER|​HUB_ODOMETER|​ID_NUMBER|​JOB_NUMBER|​LAST_NAME|​LOYALTY_CARD|​MONEY_CODE|​NC_FIRST_NAME|​NC_LAST_NAME|​ODOMETER|​ONE_CHECK|​QCODE|​PDSN|​PIN_DATA|​PIN|​PIN_KEY_SEQUENCE_NUMBER|​PO_NUMBER|​POSTAL_CODE|​PROCESSING_OPTION|​RESTRICTION_CODE|​START_CODE|​SWITCH_KEY|​TRAILER_NUMBER|​TRIP_NUMBER|​USER_ID|​VEHICLE_ID|​ZIP_CODE|​PIN_NUM|​STORE_PHONE|​TRAILER_HOURS|​TL_STATE|​TL_NUMBER|​TRAILER_ID|​PRE_AUTH_NUM|​TRAILER_HUB|​LICENSE_PLATE|​BILLING_ID|​VEHICLE_NUMBER|​DELIVERY_TICKET_NR|​CARRIER_ID|​VIN|​ACTIVE_FAULTS|​ENGINE_ODOMETER|​FUEL_LEVEL|​TOTAL_FUEL_USED|​IDLE_TIME|​ISNB|​TRNB|​REAL_PAN|​RTMP|​SSUB|​PPIN|​LSTN|​CNTN|​LCST

fleet.commercialRequestedPrompt[n].text

The text displayed at the terminal.

Optional

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

fleet.commercialRequestedPrompt[n].verificationType

The method used to verify the entered value. Valid values: DATATYPE - the value is verified against a data type; MASK - the value is verified against an edit mask; RANGE - the value is verified against a minimum and maximum range; OPTIONS - the value is verified against a list of options.

Optional

DATATYPE|​MASK|​RANGE|​OPTIONS

fleet.commercialRequestedPrompt[n].editMask

The edit mask used to validate the entered value.

Optional

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

fleet.commercialRequestedPrompt[n].lengthMin

The minimum permitted input length.

Optional

N..2
^(0|​[1-9][0-9]?)$

fleet.commercialRequestedPrompt[n].lengthMax

The maximum permitted input length.

Optional

N..2
^(0|​[1-9][0-9]?)$

fleet.commercialRequestedPrompt[n].rangeMin

The minimum permitted input value, returned as a string without leading zero padding. Zero is represented as "0".

Optional

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

fleet.commercialRequestedPrompt[n].rangeMax

The maximum permitted input value, returned as a string without leading zero padding. Zero is represented as "0".

Optional

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

fleet.commercialRequestedPrompt[n].dataType

Specifies the permitted input characters.

Optional

ALPHANUMERIC|NUMERIC

fleet.commercialRequestedPrompt[n].inputType

Specifies the input handling: CLEAR transmits the entered value as clear text; MASKED masks the value during entry and transmits it as clear text; ENCRYPTED masks and encrypts the value; DO_NOT_PRINT transmits it as clear text but omits it from the receipt.

Optional

CLEAR|MASKED|ENCRYPTED|DO_NOT_PRINT

fleet.commercialRequestedPrompt[n].optional

Indicates whether the prompt may be skipped. Valid values: true - the prompt is optional; false - the prompt is not optional.

Optional

true|false

fleet.commercialRequestedPrompt[n].simpleInputVerification

Indicates whether simple input verification is allowed. Valid values: true - the prompt allows for simple input verification; false - the prompt does not allow for simple input verification.

Optional

true|false

fleet.commercialRequestedPrompt[n].promptSource

The source of the prompt.

Optional

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

fleet.commercialRequestedPrompt[n].promptOrder

The order in which the prompt is presented.

Optional

N..2
^(0|​[1-9][0-9]?)$

fleet.commercialRequestedPrompt[n].screenNumber

The screen on which the prompt is presented.

Optional

N..2
^(0|​[1-9][0-9]?)$

fleet.commercialRequestedPrompt[n].deviceFormName

The device form associated with the prompt.

Optional

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

fleet.commercialRequestedPrompt[n].devicePromptIndex

The prompt index within the device form.

Optional

N..2
^(0|​[1-9][0-9]?)$

fleet.commercialRequestedPrompt[n].deviceFormatIndex

The format index within the device form.

Optional

N..2
^(0|​[1-9][0-9]?)$

fleet.commercialRequestedPrompt[n].options[n]

The permitted input values when verificationType is OPTIONS.

Optional

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

fleet.productLimits.totalAmountLimit

The total amount limit for the transaction, expressed in the major denomination of the transaction currency. A period is used as the decimal separator.

Optional

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

fleet.productLimits.includesCash

Indicates whether a cash amount is included.

Optional

true|false

fleet.productLimits.limit[n].unitOfMeasure

The unit in which the product quantity limit is expressed.

Optional

CASE_OR_CARTON|​GALLONS|​KILOGRAMS|​LITERS|​OTHER|​POUNDS|​QUARTS|​UNITS|​OUNCES|​DIESEL_GALLON_EQUIVALENT|​GASOLINE_GALLON_EQUIVALENT|​DIESEL_LITER_EQUIVALENT|​GASOLINE_LITER_EQUIVALENT|​PERCENTAGE

fleet.productLimits.limit[n].quantityLimit

The quantity limit for the product specified in the productCode subfield. The value may include the decimal point to express fractional quantities (e.g. "1.23"). If not provided, no quantity limit applies to the product.

Optional

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

fleet.productLimits.limit[n].amountLimit

The amount limit for the product specified in the productCode subfield, expressed in the major denomination of the transaction currency. A period is used as the decimal separator. If not provided, no amount limit applies to the product.

Optional

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

fleet.productLimits.limit[n].productCode

Identifies the product to which the limits apply.

Optional

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

display.onApprove

Indicates whether the text should be displayed for approved transactions.

Optional

true|false

display.cash

Indicates whether the cash amount should be displayed.

Optional

true|false

display.text

The text to be displayed. May also contain a description that further describes the transaction result, whether it was approved or declined, appended after a space. For Credit Application transactions, this appended text contains the reason why the transaction was declined, if a declined response is sent.

Optional

ANS..10050
[\x20-\xFF]{1,10050}
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"
	},
	"printData":{
		"receiptLines":[
			"Store: Main Street Location",
			"Thank you for your business",
			"Visit us again soon"
		]
	},
	"reAuthRequired":false,
	"fleet":{
		"promptForOdometer":"1",
		"printPricePerGallon":"0",
		"maximumPurchaseAmount":"1111",
		"maximumOilAmount":"2222",
		"maximumPartsAmount":"3333",
		"maximumAmountOther":"4444",
		"restriction":[
			{
				"code":"01",
				"amount":"100.00",
				"quantity":"50",
				"unitOfMeasure":"GALLONS",
				"cashLimit":"50.00",
				"invoiceTotalLimit":"250.00",
				"miscellaneousTotalLimit":"20.00",
				"additiveTotalLimit":"20.00",
				"repairAmountLimit":"30.00",
				"customerName":"JOHN DOE TRUCKING",
				"customerCity":"SAN FRANCISCO",
				"customerState":"CA"
			},
			{
				"code":"02",
				"amount":"150.00",
				"unitOfMeasure":"LITERS"
			}
		],
		"productLimits":{
			"totalAmountLimit":"100.00",
			"includesCash":false,
			"limit":[
				{
					"productCode":"001",
					"unitOfMeasure":"GALLONS",
					"quantityLimit":"25.00",
					"amountLimit":"75.00"
				},
				{
					"productCode":"019",
					"amountLimit":"20.00"
				}
			]
		},
		"commercialRequestedPrompt":[
			{
				"name":"ODOMETER",
				"text":"Enter Odometer",
				"verificationType":"DATATYPE",
				"lengthMin":"1",
				"lengthMax":"7",
				"dataType":"NUMERIC"
			},
			{
				"name":"VEHICLE_NUMBER",
				"text":"Enter Vehicle Number",
				"verificationType":"MASK",
				"editMask":"#########################",
				"lengthMin":"25",
				"lengthMax":"25"
			},
			{
				"name":"DRIVER_ID",
				"text":"Enter Driver ID",
				"verificationType":"RANGE",
				"rangeMin":"20",
				"rangeMax":"1200",
				"dataType":"NUMERIC",
				"inputType":"DO_NOT_PRINT"
			},
			{
				"name":"RESTRICTION_CODE",
				"text":"Select restriction code",
				"verificationType":"OPTIONS",
				"optional":false,
				"options":["CAR", "TRUCK", "VAN"]
			}
		]
	},
	"display":{
		"onApprove":true,
		"cash":false,
		"text":"Thank you for your purchase"
	},
	"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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}
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",
	"correlationId": "0aec0a35-1db7-4604-b6c5-1bcec197b6de",
	"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 "correlationId=0aec0a35-1db7-4604-b6c5-1bcec197b6de"
	-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 all payment 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

standingInstruction.frequency

The Standing Instruction frequency indicates how often the recurring payment occurs.

Optional

DAYS|​
WEEKS|​
MONTHS|​
YEARS|​
BI_WEEKLY|​
QUARTERLY|​
BI_ANNUALLY|​
ANNUALLY|​
UNSCHEDULED|​
FORTNIGHTLY|​
TWICE_WEEKLY|​
TEN_DAYS|​
EVERY_TWO_MONTHS|​
TRIMESTER

standingInstruction.iteration

The Standing Instruction iteration specifies the current number of the recurring payment iteration agreed with the merchant.

Optional

01 - 99|​
ND (Not Defined)|​
UC (Until Cancelled)
^(0[1-9]|[1-9][0-9]|ND|UC)$

standingInstruction.validationFlag

The Standing Instruction validation flag. Known values include 0 (Not Validated) and 1 (Validated).

Optional

N1
^\\d$

standingInstruction.uniqueId

The Standing Instruction unique id contains an unique reference number for recurring payment transactions.

Optional

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

standingInstruction.maximumAmount

The Standing Instruction maximum amount agreed to by the cardholder.

Optional

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

standingInstruction.numberOfPayments

The Standing Instruction number of recurring payment debits with leading zeros. A value of 99 means that recurring payments are authorized until cancelled or that the number of recurring payments is not indicated.

Optional

N2
[0-9]{2}
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. When this flag is set to false, it indicates that partially approved authorizations are not accepted.

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 "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 Required Regex

card.pinlessDebit

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

Optional

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
SOFTWARE_POS_DEVICE - Software Point of Sale Device
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 who is 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

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

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

Deprecated: use `result.authorizationIdExtended` instead.

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

Indicates whether the check fee is excluded.
Valid values:
true - fee is excluded
false - fee is not excluded

Optional

true|false

check[n].singlePurpose

Indicates whether the draft can only be used for a single, designated purpose (e.g. one fuel stop, one repair job).
Valid values:
true - single purpose
false - not single purpose

Optional

true|false

check[n].authorizationCode

This code is used for authorization and tracking in financial transactions. These codes are typically provided by the authorizing agency and must be entered by the vendor or service provider to process or verify the transaction.

Optional

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

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

check[n].electronic

Indicates whether the check is an electronic check.
Valid values:
true - electronic check
false - not an electronic check

Optional

true|false
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"
  -d "check[0].feeExcluded=false"
  -d "check[0].singlePurpose=true"
  -d "check[0].authorizationCode=AUTH1234567890"
  -d "check[0].electronic=true"
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 major denomination.

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

check.printData.numberOfChecks

The number of checks included in the print data.

Optional

N..2
[1-9][0-9]?

check.printData.authNumber

The auth number.

Optional

N..5
[0-9]{1,5}

check.printData.controlNumber

The control number used to identify the original purchase.

Optional

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

check.printData.totalAmount

The total order amount, expressed in the major denomination of the transaction currency. A period is used as the decimal separator.

Optional

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

check.printData.incrementAmount

The incremental amount, expressed in the major denomination of the transaction currency. A period is used as the decimal separator.

Optional

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

check.printData.date

The date in the format: mm/dd/yy.

Optional

mm/dd/yy
^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{2}$

check.printData.time

The time in the format: HH:mm:ss (24-hour).

Optional

HH:mm:ss
([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]

check.printData.payee

The Payee name.

Optional

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

check.printData.companyName

The company name.

Optional

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

check.printData.additionalData1

Optional data provided by the acquirer.

Optional

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

check.printData.additionalData2

Additional optional data provided by the acquirer.

Optional

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

check.printData.checkInfo[n].checkNumber

The check number.

Optional

N..10
^(0|[1-9][0-9]{0,9})$

check.printData.checkInfo[n].formattedPrintData

The formatted print data.

Optional

ANS..999
[\x20-\xFF]{1,999}
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",
            "printData": {
                "numberOfChecks": "2",
                "authNumber": "12345",
                "controlNumber": "123456789",
                "totalAmount": "400.00",
                "incrementAmount": "50.00",
                "date": "04/30/24",
                "time": "15:24:22",
                "payee": "John Smith",
                "companyName": "Acme Corp",
                "additionalData1": "Optional data 1",
                "additionalData2": "Optional data 2",
                "checkInfo": [
                    {
                        "checkNumber": "12345",
                        "formattedPrintData": "PAY TO THE ORDER OF..."
                    },
                    {
                        "checkNumber": "12346",
                        "formattedPrintData": "PAY TO THE ORDER OF..."
                    }
                ]
            }
    }
}

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}

merchantTransactionId

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

Required

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

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 "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-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}

merchantTransactionId

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

Required

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

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 "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-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}

merchantTransactionId

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

Required

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

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 "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
	-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.
AR - Admin Request
AN - Admin Notification
DB - Debit Request
CD - Credit Request
CP - Capture Notification
RV - Reversal Notification
PA - Pre-Authorization Request
PC - Pre-Authorization Credit Request
CN - Credit Notification
IR - ICC Data Submission
GD - Stored Value Deactivation
GL - Stored Value Load
GA - Stored Value Activation
GT - Stored Value Top-up
BI - Balance Inquiry
DA - Debit Adjustment
DP - Deposit
RR - Reversal Request
CV - Card Verification
CA - Credit Adjustment
CC - Check Authorization
CG - Check Guarantee
MS - Mini Statement

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. For check transactions (paymentType CC and CG) a 6-digit Check Card Number may be supplied instead of a full PAN; all other transactions require a 12-19 digit PAN.

Conditional

N6 or N12..19
^([0-9]{6}|[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})

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

tokenVault

The token vault to use for this request.
When omitted the default vault (POSTILION) is used.
Set to `RCS` to perform a token request or token card number lookup from the RCS Token Vault.

Optional

POSTILION|RCS

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
SOFTWARE_POS_DEVICE - Software Point of Sale Device
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 location information and/or name of merchant ,exclusive of city, state/region and country.

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. When this flag is set to false, it indicates that partially approved authorizations are not accepted.

Optional

true|false
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"
Example: Request token from the RCS Token Vault
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"
  -d "tokenVault=RCS"

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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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.

Fields associated with a Postilion De-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}

tokenId

A token representing sensitive cardholder data.

Required

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

tokenVault

The token vault to use for this request.
When omitted the default vault (POSTILION) is used.
Set to `RCS` to perform a token request or token card number lookup from the RCS Token Vault.

Optional

POSTILION|RCS

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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"
Fields associated with an RCS De-tokenization / Token Card Number Lookup 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}

tokenId

A token representing sensitive cardholder data.

Required

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

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

tokenVault

The token vault to use for this request.
When omitted the default vault (POSTILION) is used.
Set to `RCS` to perform a token request or token card number lookup from the RCS Token Vault.

Required (value of RCS)

POSTILION|RCS

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
SOFTWARE_POS_DEVICE - Software Point of Sale Device
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 location information and/or name of merchant ,exclusive of city, state/region and country.

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. When this flag is set to false, it indicates that partially approved authorizations are not accepted.

Optional

true|false

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"
  -d "tokenVault=RCS"
  -d "pos.storeId=0012          "
  -d "pos.terminalId=1       "

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

N6 or N12..19
^([0-9]{6}|[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})

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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 provisions cryptographic keys onto PIN Entry Devices (PEDs). Key distribution is a two-step protocol:

  1. Step 1 — Key Exchange: The client sends a key exchange request to POST https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdrequest.

  2. Step 2 — Key Confirmation: After the PED has applied the key, the client sends a confirmation to POST https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm, including the rkdEchoData value received in Step 1’s response. This confirms successful key injection.

Important
 The rkdEchoData value from the key exchange response is the session token linking both calls. It must be stored by the client and returned unchanged in the rkdEchoData field of the subsequent confirmation request. The confirmation request must be sent within 10 minutes else the key exchange flow must be restarted.

4.2.1. RKD Schemes

The rkdScheme field selects the key distribution protocol. The supported RKD schemes all fall into two categories:

Online — the server and PED negotiate and derive the key at exchange time using a public key infrastructure (PKI) based protocol.
Offline — pre-encrypted key bundles are loaded in advance and retrieved by PED serial number at exchange time. For all offline schemes, rkdRequestData is the hex-encoded PED serial number.

rkdScheme value Category Description

ACI

Online

ACI’s mutual-authentication protocol based on RSA certificate exchange and HSM-backed key derivation. The rkdRequestData and rkdKeyData fields carry binary structures defined in the ACI RKD Interface Specification for PED Manufacturers. Contact your ACI representative to obtain this document.

VERIFONE_VRK

Offline

Verifone VeriShield Remote Key. Uses the PED serial number to look up the pre-provisioned key bundle. Use this scheme for new Verifone integrations.

VERIFONE_VSD (deprecated)

Offline

Deprecated Verifone scheme. Identical behaviour to VERIFONE_VRK — use VERIFONE_VRK for new integrations.

INGENICO

Offline

Ingenico scheme. Uses the PED serial number to look up the pre-provisioned key bundle.

PAX

Offline

PAX scheme. Uses the PED serial number to look up the pre-provisioned key bundle.

4.2.2. RKD Exchange Request

Initiates a RKD Exchange Request message.

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
See Authentication

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

entityId

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

Conditionally Required
See Authentication

AN32
[a-f0-9]{32}

pos.terminalId

The terminal identifier assigned by the acquirer.

Required
All schemes

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

rkdScheme

Selects the RKD protocol. Must match the scheme configured on the server for this terminal. Only the following schemes are supported: ACI, VERIFONE_VSD, VERIFONE_VRK, INGENICO, PAX. See the RKD Schemes table for a description of each value.

Required
All schemes

ACI|​
VERIFONE_VSD|​
VERIFONE_VRK|​
INGENICO|​
PAX

rkdRequestData

Key request payload from the PED, encoded as a hex string (binary data represented as pairs of hexadecimal digits). The content is scheme-specific: ​
​
ACI: ​
A multi-block binary structure carrying the PED’s X.509 certificate chain, RSA key-agreement parameters, and a device nonce. Full field and format definitions are in the ACI RKD Interface Specification for PED Manufacturers. Contact your ACI representative to obtain this document. ​
​
VERIFONE_VRK, VERIFONE_VSD, INGENICO, PAX (offline schemes): ​
The hex-encoded ASCII representation of the PED serial number only. No other data is included. Example: serial `283112454` encodes to `323833313132343534`. Serials containing dashes are also accepted (e.g. serial `283-112-454` encodes to `3238332d3131322d343534`).

Required
All schemes

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional
All schemes

ANS36
[\x20-\xFF]{1,36}

keyStatus

Reports the current state of the P2PE key on the PED.
Allowed values:
`COMPROMISED` - The key has been compromised.
`EXPIRED` - The key has expired.
`INVALID` - The key is present but invalid.
`NOT_PRESENT` - No key is currently loaded on the PED.
`REVOKED` - The key has been revoked.
`VALID` - The key is present and within its valid period.
​
Strongly recommended for the ACI scheme. The server uses this value to determine whether a new key should be issued. If the current key is still `VALID` and within its configured retention period, the server will decline the exchange to prevent unnecessary key replacement.
​
Optional for VERIFONE_VRK, VERIFONE_VSD, INGENICO and PAX although clients may include the field if available.

Optional
All schemes

Strongly recommended for ACI

COMPROMISED|​
EXPIRED|​
INVALID|​
NOT_PRESENT|​
REVOKED|​
VALID|​

deviceName

A human-readable identifier for the PED model or agent involved in the key exchange, forwarded to the server for traceability and logging. This field is not used for key lookup or scheme routing. Examples:
`Ingenico_RBA`, `SC5000`, `VX810`, `Verifone_FORMAGENT`.

Optional
All schemes

ANS32
[\x20-\xFF]{1,32}
Examples — Exchange Request

Offline scheme (VERIFONE_VRK, INGENICO, or PAX) — send the PED serial number as the request data:

# PED serial "283112454" hex-encodes to "323833313132343534"
curl -X POST https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdrequest \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "pos.terminalId=TERM0001" \
  -d "rkdScheme=VERIFONE_VRK" \
  -d "rkdRequestData=323833313132343534" \
  -d "keyStatus=NOT_PRESENT" \
  -d "deviceName=VX810"

ACI scheme — request data is a PKI binary structure:

curl -X POST https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdrequest \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "pos.terminalId=TERM0001" \
  -d "rkdScheme=ACI" \
  -d "rkdRequestData=<hex-encoded binary from PED>" \
  -d "keyStatus=NOT_PRESENT"
RKD Exchange Response

Response-specific fields returned on a successful key exchange. See 4.2.3 Standard RKD Exchange Response for the full common response parameter set.

Parameter name Description Presence Regex

resultDetails.rkdKeyData

The new encrypted key material to be applied by the PED. Returned as a hex string. The content is scheme-specific: ​
​
ACI: ​
A signed PKI response block containing an HSM-derived IPEK encrypted under the PED’s public key, a host nonce, and supporting certificate data, as defined in the ACI RKD Interface Specification for PED Manufacturers. ​
VERIFONE_VRK, VERIFONE_VSD, INGENICO, PAX (offline schemes):​
A binary blob pre-provisioned by ACI operations. The PED handles decryption and key loading for its own scheme.

Present on success

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

resultDetails.rkdEchoData

Session correlation token generated by the server. It must be stored by the client and returned unchanged in the `rkdEchoData` field of the confirmation request. The session expires 10 minutes after the exchange response.

Present on success

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

Example exchange response (offline scheme, success):

{
  "id": "a3f8c1d290e44b7f8a12cd34ef567890",
  "result": {
    "code": "000.000.000",
    "description": "Successful Request"
  },
  "timestamp": "2026-03-19 10:45:22",
  "resultDetails": {
    "rkdKeyData": "1f8b0808f6f12f5600...",
    "rkdEchoData": "1234567890"
  }
}

4.2.3. RKD Exchange Confirmation Request

Confirms that the PED successfully applied the key from the key exchange response. Send to POST https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm. Must be sent within 10 minutes of receiving the key exchange response.

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
See Authentication

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

entityId

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

Conditionally Required
See Authentication

AN32
[a-f0-9]{32}

pos.terminalId

The terminal identifier assigned by the acquirer.

Required
All schemes

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

rkdScheme

Selects the RKD protocol. Must match the scheme configured on the server for this terminal. Only the following schemes are supported: ACI, VERIFONE_VSD, VERIFONE_VRK, INGENICO, PAX. See the RKD Schemes table for a description of each value.

Required
All schemes

ACI|​
VERIFONE_VSD|​
VERIFONE_VRK|​
INGENICO|​
PAX

rkdEchoData

Session correlation token received in `resultDetails.rkdEchoData` of the key exchange response. It is used to match this confirmation to the prior key exchange. Send this value verbatim - do not modify it.

Required
All schemes

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

rkdKeyConfirmationData

Confirmation payload from the PED after applying the key from the key exchange response, encoded as a hex string. The content is scheme-specific: ​
​
ACI:​
A signed confirmation block produced by the PED, containing the echoed host nonce and a device RSA signature, as defined in the ACI RKD Interface Specification for PED Manufacturers. ​
​
VERIFONE_VRK, VERIFONE_VSD, INGENICO, PAX (offline \ schemes):​
The hex-encoded ASCII string `<serial>|KEY_UNPACK_SUCCESS` on successful key application, or `<serial>|KEY_UNPACK_FAILURE` if the PED could not apply the key. The serial is the same value sent in the key exchange `rkdRequestData`.
​
Example - serial `283112454`:
Success (`283112454|KEY_UNPACK_SUCCESS`): `3238333131323435347c4b45595f554e5041434b5f53554343455353` ​
Failure (`283112454|KEY_UNPACK_FAILURE`): `3238333131323435347c4b45595f554e5041434b5f4641494c555245`

Required
All schemes

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional
All schemes

ANS36
[\x20-\xFF]{1,36}

deviceName

A human-readable identifier for the PED model or agent involved in the key exchange, forwarded to the server for traceability and logging. This field is not used for key lookup or scheme routing. Examples:
`Ingenico_RBA`, `SC5000`, `VX810`, `Verifone_FORMAGENT`.

Optional
All schemes

ANS32
[\x20-\xFF]{1,32}
Examples — Confirmation Request

Offline scheme (VERIFONE_VRK, INGENICO, or PAX) — PED reports successful key application:

# "283112454|KEY_UNPACK_SUCCESS" hex-encoded
curl -X POST https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "pos.terminalId=TERM0001" \
  -d "rkdScheme=VERIFONE_VRK" \
  -d "rkdEchoData=1234567890" \
  -d "rkdKeyConfirmationData=3238333131323435347c4b45595f554e5041434b5f53554343455353"

Offline scheme — PED reports key application failure:

# "283112454|KEY_UNPACK_FAILURE" hex-encoded
curl -X POST https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "pos.terminalId=TERM0001" \
  -d "rkdScheme=VERIFONE_VRK" \
  -d "rkdEchoData=1234567890" \
  -d "rkdKeyConfirmationData=3238333131323435347c4b45595f554e5041434b5f4641494c555245"

ACI scheme — confirmation data is a signed binary block produced by the PED:

Note
 For the ACI scheme, the rkdKeyConfirmationData content is produced by the PED firmware per the ACI RKD Interface Specification for PED Manufacturers. Contact your ACI representative to obtain this document.
RKD Confirmation Response

On a successful confirmation, the standard response fields are returned. There are no confirmation-specific resultDetails fields. See 4.2.3 Standard RKD Exchange Response for the full parameter set.

{
  "id": "b7e2d5c3a1f048a983cd12ef456789ab",
  "result": {
    "code": "000.000.000",
    "description": "Successful Request"
  },
  "timestamp": "2026-03-19 10:45:35"
}

4.2.4. Standard RKD Exchange Response

The following fields are returned in all responses from both POST https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdrequest and POST https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm. For exchange-specific response fields (resultDetails.rkdKeyData and resultDetails.rkdEchoData), see RKD Exchange Response above.

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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 location information and/or name of merchant ,exclusive of city, state/region and country.

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

YYYY-MM-DD

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

merchant.street

The location information and/or name of merchant ,exclusive of city, state/region and country.

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

N6 or N12..19
^([0-9]{6}|[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})?

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

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}

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

result.remoteBatchNr

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

Optional

N..10
^[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

N..10
^[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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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.
This field is supported in payment, batch, and network management messages. For payment messages, if this field is not provided, the system will fall back to the `PSTLN_ACQUIRING_INSTITUTION_CODE` customParameter if present.

Optional

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

pos.terminalId

The terminal identifier assigned by the acquirer.

Optional

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

pos.storeId

The store identifier assigned by the acquirer.

Optional

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

pos.localDateTime

The local date and time when the batch reconciliation request was initiated. If not provided, the system will use the current local date and time.

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

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 "pos.localDateTime=01-01 13:00:00"
  -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 "pos.localDateTime=01-01 13:00:00"
  -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

N..10
^[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

correlationId

An originator identifier of a transaction that is to be used throughout a multiple server system. This identifier should be transparently transmitted to upstream entities. It can be used to collate related transactions together, such as an authorization and its completion or reversal. A new ID is generated for request messages when an ID is not supplied. A correlation ID supplied on subsequent linked messages must match the ID of the original message.

Optional

ANS36
[\x20-\xFF]{1,36}

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"

pos.localDateTime

The local date and time when the batch reconciliation was processed. If not provided in the request, the system determines this value.

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

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"
    },
    "pos": {
      "localDateTime": "01-01 13:00: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-10-27

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

ConnectUP YAML

10. Publication history

Current publication date: 2026-10-27

Version 1.74

Commercial fuel transaction support

  • Added support for commercial fuel transactions

  • Added a new CG (Check Guarantee) payment type

  • Added the following services and endpoints:

    • FU (Fuel Price Update): /paymentsapi/opp/v1/fleet/fuelpriceupdate

    • CS (Check Stock Update): /paymentsapi/opp/v1/fleet/checkstockupdate

    • CK (Check Reprint): /paymentsapi/opp/v1/fleet/checkreprint

  • Added response field result.authorizationIdExtended for extended authorization identifiers

  • Added a new display response object for host-directed receipt/display text and flags

Version 1.73

  • Added CL (Credit Application) and AL (Account Lookup) messages along with their associated fields.

  • The maximum character length limit for field fleet.prompts[n].contractNumber has been increased from 20 to 25 characters.

Version 1.72

  • Added support for correlationId in request and response messages for all services.

  • Added support for merchant.marketplaceId in payment request and response messages.

  • Added support for new standingInstruction subfield standingInstruction.numberOfPayments in payment request messages.

Version 1.71

  • Added support for new standingInstruction subfields standingInstruction.frequency, standingInstruction.iteration, standingInstruction.validationFlag, standingInstruction.uniqueId and standingInstruction.maximumAmount in payment request messages.

  • The partialApprovalAllowed field now accepts a value of false.

Version 1.70

  • Added support for fee.amount and fee.indicator fields in payment request message.

Version 1.69

  • Adding new response field 'originalIso8583ResponseCode'

Version 1.68

  • Adding new terminalType SOFTWARE_POS_DEVICE.

  • Adding support for tokenization requests and lookups via RCS.

Version 1.67

Stored-Value top-up Support

  • Added support for Stored-Value top-up (GT) payment type.

  • Introduced prepaidMerchandise fields for top-up transactions:

    • prepaidMerchandise.productId - Product identifier

    • prepaidMerchandise.productType - Product type (TELEPHONE_PREPAY, CALLING_PLAN, ELECTRICITY, OTHER)

    • prepaidMerchandise.userId - User identifier (e.g., phone number)

  • Added new endpoint: /paymentsapi/opp/v1/storedvalue/topup

  • Added support to receive merchant.acquiringInstitutionCode in Payment request.

Version 1.66

Batch Service Enhancement

  • Added pos.localDateTime field to Batch Management requests and responses. This field represents the local date and time when the batch reconciliation request was initiated or processed.

Version 1.65

  • Payment Service: Adding additional Healthy Benefits fields to the payment request and response

Version 1.64

RKD Documentation Uplift

  • Added improved RKD field descriptions with examples.

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.

Version 1.62

  • Added support for Point-to-Point-Encryption (P2PE) card data in Stored-Value payment types.

Version 1.61

  • Moved track1Data to the MAGSTRIPE example section.

  • Updated geographicCoordinates and serviceLocationGeographicCoordinates regex to support negative values.

Version 1.60

  • Adding mandatory shipping fields for Create Bulk Card Order with orderType CUSTOMER_ORDER_TO_CUSTOMER

Version 1.59

  • Adding merchant, transactionCategory, threeDSecure, standingInstruction and partialApprovalAllowed to Tokenization Requests

Version 1.58

  • Updating the values for the reason field

Version 1.57

  • Introducing merchant fields geographicCoordinates and serviceLocationGeographicCoordinates

Version 1.56

  • Introducing Bulk Stored-value Card Order services

Version 1.55

  • Relaxing authorizationId validation

Version 1.54

ACI AES P2PE support

  • Added support for ACI AES P2PE.

Version 1.53

  • Adding field payment.request.StandingInstruction.amountType.

Version 1.52

  • All common result detail fields are now listed.

Version 1.51

  • Field check[n].formattedMicr.checkNr now supports up to 10 digits.

Version 1.50

  • Adding the Mini Statement service and accompanying statementData fields.

Version 1.49

  • merchantInvoiceId length increased to 30 characters.

Version 1.48

  • Adding Response Result Code 800.100.180 - Transaction declined (contact acquirer).

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.

Version 1.46

  • The amount field is conditional for reversals.

  • Added information on the merchantInvoiceId field.

Version 1.45

Tokenization and Detokenization Response Result Codes

  • Additional Response Result Code mappings are added for Tokenization and Detokenization.

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.

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.