- Get Started
- Guides
- Integrations
- References
- API Reference
- Basic Payment
- Forex
- Authentication
- Card Account
- Apple Pay
- Virtual Account
- Bank Account
- Token Account
- Customer
- Billing Address
- Merchant Billing Address
- Shipping Address
- Merchant Shipping Address
- Merchant
- Corporate
- Recipient
- Marketplace & Cart
- Airline
- Lodging
- Passenger
- Tokenization
- Recurring Migration
- 3D Secure
- Custom Parameters
- Async Payments
- Webhook notifications
- Job
- Risk
- Point of Sale
- Response Parameters
- Card On File
- Chargeback
- Result Codes
- Payment Methods
- Transaction Flows
- Regression Testing
- Data Retention Policy
- API Reference
- Support
- Impressum
ConnectUP API Interface Specification: ACI Worldwide, Inc.
April 2024
Table of Contents
- About the ConnectUP API
- About this publication
- 1. Authentication
- 2. Payment Service
- 2.1. Base Payment Operations
- 2.1.1. Pre-Authorization Request
- 2.1.2. Debit Request
- 2.1.3. Credit Request
- 2.1.4. Capture Notification
- 2.1.5. Reversal
- 2.1.6. Reversal Request
- 2.1.7. Integrated Circuit Chip (ICC) Data Result Request
- 2.1.8. Balance Inquiry Request
- 2.1.9. Stored-Value Activate Request
- 2.1.10. Stored-Value Load Request
- 2.1.11. Stored-Value Deactivate Request
- 2.1.12. Debit Adjustment
- 2.1.13. Deposit
- 2.1.14. Refund
- 2.1.15. Card Verification
- 2.1.16. Credit Adjustment
- 2.2. Base Payment Operation Responses
- 2.3. Specialized Payment Use Cases
- 2.3.1. 3-D Secure
- 2.3.2. Account Type
- 2.3.3. To Account Type
- 2.3.4. Additional POS Data
- 2.3.5. Alternative Card Data
- 2.3.6. Card Verification Value / Card ID (CVV/CID)
- 2.3.7. CVV2 Availability
- 2.3.8. Encrypted Pin
- 2.3.9. Alternative Currency
- 2.3.10. Address Verification System
- 2.3.11. Billing Contact
- 2.3.12. Bill Payments
- 2.3.13. Cashback
- 2.3.14. Convenience Fee
- 2.3.15. Custom Parameters
- 2.3.16. Debt Repayment
- 2.3.17. Deferred Authorization
- 2.3.18. Deferred Payment
- 2.3.19. Incremental Authorizations
- 2.3.20. Incremental Authorization Partial Reversal
- 2.3.21. Incremental Authorization Full Reversal
- 2.3.22. Delayed Charges
- 2.3.23. Fallback
- 2.3.24. Level 2 and Level 3 Data (L2/L3)
- 2.3.25. Fleet Data
- 2.3.26. Linked Capture
- 2.3.27. Merchant-Initiated Transaction (MIT)/Customer-Initiated Transaction (CIT)
- 2.3.28. Multiple Clearing (Captures)
- 2.3.29. Partial Approval
- 2.3.30. Payment Identifier
- 2.3.31. PIN-less Debit
- 2.3.32. Point-of-Sale (POS) Data Fields
- 2.3.33. Receiving Institution Code
- 2.3.34. Capture Reason
- 2.3.35. Reversal Reason
- 2.3.36. Reversal using referencedMerchantTransactionId
- 2.3.37. Strong Customer Authentication (SCA)
- 2.3.38. Shipping Contact
- 2.3.39. Transaction Category
- 2.1. Base Payment Operations
- 3. Token Service
- 4. P2PE Service
- 5. VP2PE Service
- 6. APM Token Decrypt Service
- 7. Network Management Service
- 8. Batch Management Service
- Appendix A: Format Element Descriptions
- Appendix B: Result Code Explanation
- 9. ConnectUP OpenAPI Specification
- 10. Publication history
About the ConnectUP API
ConnectUP is a RESTful web API that exposes various payments-related services.
Message flow
ConnectUP accepts HTTP POST messages with a URL-encoded body and returns an HTTP response with a JSON body.
Supported services
ConnectUP supports the following major services:
-
Payment - The Payments service performs payments and runs other payment-related operations.
-
Tokenization - The Tokenization service creates a token based on card data and retrieves card data based on a token.
-
Point-to-Point Encryption (P2PE) - The P2PE service provides Point-to-Point Encryption related operations like Remote Key Distribution.
-
Validated P2PE (VP2PE) - The Validated P2PE service submits terminal data for reporting and record keeping purposes as part of a validated P2PE solution.
-
APM Token Decrypt - The APM (Alternative Payment Method) Decrypt service is used to decrypt payment tokens generated by alternative payment methods such as Apple Pay and Google Pay. The decrypted content of the token is returned in the response. This can be useful for systems where validation of the contents of the token is required before the financial leg of the transaction is attempted.
About this publication
This document details how to use ConnectUP relating to services and parameters. The descriptions are separated by use-case so that granular explanation is possible.
Each parameter is described as Mandatory, Conditional, or Optional for each explained use-case. The distinction between these is as follows:
Mandatory
The parameter must be present in the request message for the given use-case to occur.
The request can be rejected without this parameter.
Conditional
The parameter is required in combination with other parameters for the given use-case to be possible, but there can be more than one set of parameters which can enable this use-case.
The request can be rejected if one of the combinations of parameters is not present.
Optional
The presence or absence of this parameter will not affect the use-case.
The request will never be rejected if this parameter is not present.
1. Authentication
1.1. Authorization Bearer Token
To align with authentication changes to the Open Payment Platform API specification,
support for the new Authorization: Bearer <access-token>
header, and related entityId
field, have been added to all services to authenticate requests.
Currently, the value of the access-token is the result of
concatenating the existing authentication.userId (Deprecated)
and authentication.password (Deprecated)
fields (as provided during user creation), and Base64-encoding the result.
Note
|
The now deprecated authentication.* fields can still be
used in requests but cannot be combined with the Authorization header
and related entityId field. If these fields are combined in any way,
authentication will fail.
|
Existing clients that wish to use the new authentication fields can:
-
Construct the token themselves as described above.
-
Request new user credentials from ACI, which will include the access-token.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
Required |
ANS110 |
entityId |
The entity associated with the request. |
Required |
AN32 |
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 |
authentication.entityId (Deprecated) |
The entity ID for the entity. |
Required |
AN32 |
authentication.password (Deprecated) |
The password for the entity. |
Required |
AN32 |
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. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
paymentType |
The payment type indicator. |
Required |
PA |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). |
Required |
N8.N4 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
deferredAuthorization |
When this flag is set to true, it indicates that this is a Deferred Authorization transaction. |
Optional |
true|false |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=PA"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2018"
-d "amount=21.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
2.1.2. Debit Request
This payment operation debits the account of the customer and credits the merchant account.
A Debit request is created by sending a POST request over
HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment
resource.
The minimum requirements for sending a DB message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
paymentType |
The payment type indicator. |
Required |
DB |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). |
Required |
N8.N4 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
deferredAuthorization |
When this flag is set to true, it indicates that this is a Deferred Authorization transaction. |
Optional |
true|false |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Debit Response
The following fields reflect the possible response values for a Debit Request response message:
Parameter name | Description | Required | Regex |
---|---|---|---|
balances.availableBalance |
Indicates the available balance for the account. |
Optional |
N8.N4 |
balances.ledgerBalance |
Indicates the ledger balance for the account. |
Optional |
N8.N4 |
additionalAmounts.approvedAmount |
Indicates the approved amount for the account. |
Optional |
N8.N4 |
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. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
paymentType |
The payment type indicator. |
Required |
CD |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). If the If the 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. |
Required |
N8.N4 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=CD"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=21.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
2.1.4. Capture Notification
This payment operation can be used to capture a Pre-authorization (PA) amount or capture a stand-alone request.
A Capture notification for this, or a previous pre-authorization request, is created by sending a POST request over
HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment
resource.
The minimum requirements for sending a CP message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
paymentType |
The payment type indicator. |
Required |
CP |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). |
Required |
N8.N4 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
referencedPaymentId |
The identifier of the transaction being completed (the Id from the original PA response). |
Optional |
ANS32 |
statusCode |
Indicates the status code of a CP transaction. |
Optional |
SUCCESSFUL|INVALID_AMOUNT |
authorizationId |
A code assigned by the authorizing institution indicating approval. |
Optional |
ANS6 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
deferredAuthorization |
When this flag is set to true, it indicates that this is a Deferred Authorization transaction. |
Optional |
true|false |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=CP"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2018"
-d "amount=21.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "authorizationId=114547"
-d "memoPost=true"
-d "deferredAuthorization=true"
2.1.5. Reversal
This payment operation reverses an already processed Pre-Authorization Request, Debit Request, or Credit Request.
A Reversal for a previous pre-authorization request, debit request, credit request, or capture notification is created by sending a POST request over
HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment
resource.
A Reversal for a previous pre-authorization request, debit request, credit request, or capture notification is placed onto the Store and Forward Queue (SAFQ) and is generally always automatically approved.
The minimum requirements for sending an RV message are listed here.
See Reversals using referencedMerchantTransactionId for cases where a referencedPaymentId value is not available.
See Result Code Special Notes for cases where an explicit Reversal must be performed.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
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. |
Required |
N8.N4 |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
paymentType |
The payment type indicator. |
Required |
RV |
referencedPaymentId |
The "Id" response of the original PA, DB, CD, or CP transaction that is to be reversed. |
Conditional |
ANS32 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"`
-d "paymentType=RV"
-d "amount=15.00"
-d "pos.terminalId=38956111"
-d "referencedPaymentId=1b8cd7b6c81c9883e8926f04985fa7b5"
2.1.6. Reversal Request
This payment operation reverses an already processed Pre-Authorization Request, Debit Request, or Credit Request.
A Reversal Request for a previous pre-authorization request, debit request, credit request, or capture notification is created by sending a POST request over
HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment
resource.
A Reversal Request for a previous pre-authorization request, debit request, credit request, or capture notification and can be declined by the host.
The minimum requirements for sending an RR message are listed here.
See Reversals using referencedMerchantTransactionId for cases where a referencedPaymentId value is not available.
See Result Code Special Notes for cases where an explicit Reversal Request must be performed.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
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. |
Required |
N8.N4 |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
paymentType |
The payment type indicator. |
Required |
RR |
referencedPaymentId |
The "Id" response of the original PA, DB, CD, or CP transaction that is to be reversed. |
Conditional |
ANS32 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"`
-d "paymentType=RR"
-d "amount=15.00"
-d "pos.terminalId=38956111"
-d "referencedPaymentId=1b8cd7b6c81c9883e8926f04985fa7b5"
2.1.7. Integrated Circuit Chip (ICC) Data Result Request
An ICC Data Result Request is created by sending a POST request
over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment/iccresult
resource.
The ICC Data Result Request is used to send ICC transaction results to the card issuer as part of the payment transaction flow (if required).
When a payment is performed with an ICC card, the card calculates two separate cryptograms. The first calculation occurs prior to initiating the payment request and is sent together with the payment request. The second calculation occurs after the issuer (or other authorizer) approved the payment request. The second cryptogram (a TC or Transaction Certificate) needs to be sent to the issuer.
When using a dual message pre-authorization/capture transaction
flow (paymentType PA
and CP
), the TC can be sent with the capture
message. If using a single message debit/credit transaction flow
(paymentType DB
or CD
), this service must be used to send the
TC.
Additionally, the issuer can send scripts to the card to run in a payment response. The issuer script results must be sent back to the issuer in a follow-up request.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
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 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
referencedPaymentId |
The identifier of the transaction for which the ICC results
are being sent. This field is the |
Required |
ANS32 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
ICC Data Result Response
The following field reflects the possible response for an ICC Data Result Request message:
Parameter name | Description | Required | Regex |
---|---|---|---|
result.iccDataResponse |
This field contains BER-TLV data from the issuer, as defined by the EMV specifications, and is hex-encoded. |
Optional |
AN2048 |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment/iccresult -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "card.track2Data=5301250070000191"
-d "pos.storeId=posStoreID10000"
-d "pos.terminalId=term_1aB"
-d "pos.iccDataRequest=9F3303E0F0C89F03060202..."
-d "referencedPaymentId=1b9e311efa074b9e92048c44de58b1e7"
ICC Data Result Response
{
"amount": "0.00",
"currency": "USD",
"id": "13844078f145407bad00e2c9e028ab1c",
"result": {
"code": "000.000.000",
"description": "Transaction succeeded"
"authorizationId": "071797"
"iccDataResponse": "6F1A840E3150411025F2D02..."
},
"timestamp": "2020-10-28 15:24:22",
"resultDetails": {
"retrievalReferenceNumber": "000000001363"
}
}
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.1.8. Balance Inquiry Request
This payment operation can be used to retrieve the remaining balance for an associated account.
A Balance Inquiry request is created by sending a POST
request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/balanceinquiry
resource.
The minimum requirements for sending a Balance Inquiry message are listed here:
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Balance Inquiry Response
The following field reflects the possible response values for a Balance Inquiry response message:
Parameter name | Description | Required | Regex |
---|---|---|---|
balances.availableBalance |
Indicates the available balance for the account. |
Optional |
N8.N4 |
balances.ledgerBalance |
Indicates the ledger balance for the account. |
Optional |
N8.N4 |
See the standard response fields for an extended listing of the possible response parameters ConnectUP can return for this request type.
Example
Balance Inquiry Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/balanceinquiry -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=UNKNOWN"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Balance Inquiry Response
{
"amount": "0.00",
"currency": "USD",
"balances": {
"availableBalance": "100.00",
"ledgerBalance": "110.00"
},
"id": "13844078f145407bad00e2c9e028ab1c",
"result": {
"code": "000.000.000",
"description": "Transaction succeeded"
"authorizationId": "071797"
},
"timestamp": "2020-10-28 15:24:22",
"resultDetails": {
"retrievalReferenceNumber": "000000001363"
}
}
2.1.9. Stored-Value Activate Request
This service is used to activate a stored-value card whilst simultaneously loading the card with a specified balance.
A Stored-Value Activate request is created by sending a POST
request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/activate
resource.
The minimum requirements for sending a Stored-Value Activate message are listed here.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
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. |
Required |
N8.N4 |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
Stored-Value Activate Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/activate -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=55.00"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=UNKNOWN"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Stored-Value Activate Response
{
"amount": "55.00",
"currency": "USD",
"id": "13844078f145407bad00e2c9e028ab1c",
"result": {
"code": "000.000.000",
"description": "Transaction succeeded"
"authorizationId": "432457"
},
"timestamp": "2020-10-28 15:24:22",
"resultDetails": {
"retrievalReferenceNumber": "000000001363"
}
}
2.1.10. Stored-Value Load Request
This service is used to load additional funds to an already activated stored-value card balance.
A Stored-Value Load request is created by sending a POST
request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/load
resource.
The minimum requirements for sending a Stored-Value Load message are listed here.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
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. |
Required |
N8.N4 |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
Stored-Value Load Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/load -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=55.00"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=UNKNOWN"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Stored-Value Load Response
{
"amount": "55.00",
"currency": "USD",
"id": "13844078f145407bad00e2c9e028ab1c",
"result": {
"code": "000.000.000",
"description": "Transaction succeeded"
"authorizationId": "078897"
},
"timestamp": "2020-10-28 15:24:22",
"resultDetails": {
"retrievalReferenceNumber": "000000001363"
}
}
2.1.11. Stored-Value Deactivate Request
This service is used to deactivate a stored-value card and simultaneously retrieve the available balance remaining on the card.
A Stored-Value Deactivate request is created by sending a POST
request over HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/deactivate
resource.
The minimum requirements for sending a Stored-Value Deactivate message are listed here.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
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. |
Conditionally Required |
N8.N4 |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
Stored-Value Deactivate Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/storedvalue/deactivate -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmYTdjZWUx..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=55.00"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=UNKNOWN"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Stored-Value Deactivate Response
{
"amount": "55.00",
"currency": "USD",
"id": "13844078f145407bad00e2c9e028ab1c",
"result": {
"code": "000.000.000",
"description": "Transaction succeeded"
},
"timestamp": "2020-10-28 15:24:22",
"resultDetails": {
"retrievalReferenceNumber": "000000001363"
}
}
2.1.12. Debit Adjustment
This payment operation Debit adjustment is issued towards correction of an transaction. This adjustment debits the customer’s account.
A Debit adjustment is created by sending a POST request over
HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment
resource.
The minimum requirements for sending a DA message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
paymentType |
The payment type indicator. |
Required |
DA |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). |
Required |
N8.N4 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DA"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2018"
-d "amount=21.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
2.1.13. Deposit
This payment operation is used to credit the customer’s account.
A Deposit is created by sending a POST request over
HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment
resource.
The minimum requirements for sending a DP message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
paymentType |
The payment type indicator. |
Required |
DP |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). If the If the 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. |
Required |
N8.N4 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DP"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=21.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
2.1.14. Refund
Please note this payment operation has been deprecated and replaced by: Credit Adjustment. The Refund payment operation will remain present, but will be considered inactive and unsupported until it is re-purposed for any future endeavors.
This payment operation is used to credit the account of the end customer for an already processed Debit Request, or Credit Request.
A Refund is created by sending a POST request over
HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment
resource.
The minimum requirements for sending a RF message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
paymentType |
The payment type indicator. |
Required |
RF |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). If the If the 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. |
Required |
N8.N4 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=RF"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=21.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
2.1.15. Card Verification
This payment operation is used to verify the details of a user’s card.
A Card Verification request is created by sending a POST request over
HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment
resource.
The minimum requirements for sending a CV message are listed here:
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
paymentType |
The payment type indicator. |
Required |
CV |
card.number |
The Primary Account Number (PAN) of the physical card. |
Required |
N19 |
card.expiryMonth |
The month that the card expires. |
Required |
N2 |
card.expiryYear |
The year that the card expires. |
Required |
N4 |
card.cvv |
The card security code or CVV. |
Required |
N4 |
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=CV"
-d "card.number=4444444444444448"
-d "card.cvv=123"
-d "card.expiryMonth=10"
-d "card.expiryYear=2025"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
2.1.16. Credit Adjustment
The Credit Adjustment is a payment operation issued towards the correction of a transaction. This adjustment credits the customer’s account.
A Credit adjustment is created by sending a POST request over
HTTPS to the https://[hostname]:[port]/paymentsapi/opp/v1/payment
resource.
The minimum requirements for sending a CA message are listed here. See the Specialized Payment Use Cases section for use cases that required additional fields.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
paymentType |
The payment type indicator. |
Required |
CA |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). If the If the 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. |
Required |
N8.N4 |
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
N2 |
|
card.expiryYear |
The year that the card expires. |
N4 |
|
card.track1Data |
The information encoded on Track 1 of the magnetic stripe as defined in ISO 7813. |
Optional |
[\s\S]{0,76} |
serviceRestrictionCode.area |
The area of usage and whether the card has additional read facilities. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
INT_CARD| |
serviceRestrictionCode.authorization |
The authorization processing requirements for this card. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
NORMAL_AUTH| |
serviceRestrictionCode.range |
The range of services available and PIN requirements. |
Optional. Required if other serviceRestrictionCode \ subfields and/or card.track1Data is present. |
PIN_REQUIRED| |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
CREDENTIAL_ON_FILE| |
pos.terminalRestrictions |
The field indicates specific rules or limitations applied to a terminal. |
Optional |
NONE| |
merchantTransactionId |
The merchant-provided reference number. It must be unique for the merchant’s transactions. |
Required |
ANS255 |
memoPost |
When this flag is set to true, it indicates that this is a memoPost transaction, which is only captured for memo/reporting purposes. |
Optional |
true|false |
ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data.
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdmOGVmyODA0NEY0Rj..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=CA"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=21.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
2.2. Base Payment Operation Responses
2.2.1. Standard Response
The fields listed in the table here reflect the possible response values for the following request messages:
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 |
timestamp |
The timestamp generated by the response in UTC. |
Always |
date |
result.code |
The unique code that indicates the result status of the request. |
Always |
AN11 |
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 |
result.avsResponse |
Contains the AVS response returned by the acquirer. |
Conditional |
A1 |
result.cvvResponse |
Contains the CVV response returned by the acquirer. |
Conditional |
A1 |
resultDetails.* |
A container for name-value pairs used for enriching the response with bank-specific response details. |
Conditional |
name: AN64 |
resultDetails.AcquirerResponse |
The raw host network response code. |
Conditional |
name: AN64 |
resultDetails.AcquirerAvsResponse |
The raw host network AVS response code. |
Conditional |
name: AN64 |
resultDetails.commercialCardIndicator |
Indicates whether the card type is commercial (Level 2 eligible). |
Conditional |
Y|N|X |
resultDetails.FleetDataRsp |
A container for fleet data response details. |
Conditional |
name: ANS255 |
customParameters[name] |
Used to send additional information required for certain transaction scenarios. |
Conditional |
name: AN64 |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). |
Optional |
N8.N4 |
tokenId |
A token representing sensitive cardholder data. |
Optional |
AN255 |
currency |
The currency code of the payment request’s amount (ISO 4217). |
Optional |
A3 |
result.authorizationId |
The code assigned by the authorizing institution indicating approval. |
Optional |
AN6 |
fleet |
Contains information regarding fleet data which can be used to send data to the pump from the acquirer. |
Optional |
ANS255 |
pos.localDateTime |
The local date and time at which the transaction took place. For linked transactions, this field indicates the local time set by the initiator of the first message in the chain. If this field has not been set then the current local date and time is used. The format of the parameter is in the form of MM-dd HH:mm:ss. |
Optional |
(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1]) ([0-1][0-9]|2[0-3]):([0-5][0-9]):([0-5][0-9]) |
Example
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"tokenId" : "JYO7rdR5UjK61111",
"amount" : "92.00",
"currency" : "USD",
"pos":{"localDateTime":"08-30 10:21:29"}
"result": {
"code" : "000.000.000",
"description" : "Transaction succeeded",
"authorizationId" : "783276"
},
"customParameters":{
"CUSTOM_KEY1":"CUSTOM_VALUE1",
"CUSTOM_KEY2":"CUSTOM_VALUE2"
},
"resultDetails" : {
"bankField1": "1234"
},
"timestamp" : "2019-09-06 12:22:44"
}
Note
|
Optional fields will only be returned when the
request could be processed (no validation
errors occurred on the fields in the request). The
request result.code must always be evaluated
with the HTTP status code
to determine the overall status of the request.
|
2.3. Specialized Payment Use Cases
2.3.1. 3-D Secure
3-D Secure (3DS) is compatible with the following message types:
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.+ |
Required |
N2 |
threeDSecure.dsTransactionId |
The dsTransactionId field represents the unique transaction identifier assigned by the Directory Server (DS). It is used to identify a single transaction within the 3-D Secure (3DS) authentication process. |
Conditional |
ANS36 |
threeDSecure.version |
The version field indicates the specific version of the 3-D Secure protocol that is being used for authentication during the transaction. Only version 2 is supported. For example, valid version values could include "2", "2.0", "2.1", "2.1.1", etc., representing different iterations of the 3-D Secure version 2 protocol. |
Conditional |
ANS5 |
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) |
threeDSecure.verificationId |
The VerificationID field contains the base64 encoded: |
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. |
Optional |
N1 |
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. |
Optional |
ANS1 |
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. |
Optional |
N2 |
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) |
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| |
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| |
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| |
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. |
Optional |
ADMIN| |
pos.operatorId |
Identifies the operator that initiated the transaction. |
Optional |
ANS35 |
pos.posId |
Identifies the device that initiated the transaction. |
Optional |
ANS35 |
pos.transactionSequenceNumber |
Identifies the transaction on the device that initiated the transaction. |
Optional |
ANS35 |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DB"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=75.00"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=MAGSTRIPE"
-d "pos.terminalType=ADMIN"
-d "pos.operatorId=123321"
-d "pos.posId=98778912"
-d "pos.transactionSequenceNumber=66611234"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.3.5. Alternative Card Data
ConnectUP supports receiving card data in various formats. Any message within the Payment Service or Token Service can accept card information in the following ways. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data.
Card data input formats
-
Manual Card Data - Data visible on the card
-
Magnetic Stripe Data - Data encoded in the card magnetic stripe
-
ICC Data - Data stored within the card EMV chip
-
Token Card Data - A token representing the card
-
Apple Pay Data - An Apple Pay encrypted payment token representing the card
-
Google Pay Data - A Google Pay encrypted payment token representing or containing the card data
-
P2PE Cardholder Data - Point-to-point encrypted (P2PE) cardholder data
-
Payment Identifier - A payment identifier used when PAN or Track2Data are not appropriate
Manual Card Data
ConnectUP supports transactions using the card details available on the physical card. For this, the fields listed here are available in the request:
Manual Card Data is compatible with the following message types:
Parameter name | Description | Required | Regex |
---|---|---|---|
card.number |
The Primary Account Number (PAN) of the physical card. |
Required |
N19 |
card.expiryMonth |
The month that the card expires. |
Required |
N2 |
card.expiryYear |
The year that the card expires. |
Required |
N4 |
card.cvv |
The card security code or CVV. |
Optional |
N4 |
card.sequenceNumber |
A number distinguishing between separate cards with the same primary account number or extended primary account number. |
Optional |
N3 |
pos.entryMode |
The interface that was used by the terminal for the transaction. |
Required |
MANUAL |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=PA"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2018"
-d "amount=21.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Magstripe Card Data
Magstripe Card Data is compatible with the following message types:
ConnectUP supports transactions using magnetic stripe data. For this, the fields listed here are required in the request.
Parameter name | Description | Required | Regex |
---|---|---|---|
card.track2Data |
The information encoded on Track 2 of the magnetic stripe, as defined in ISO 7813. |
Required |
ANS37 |
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| |
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 |
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 |
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). If you provide this field, |
Conditional |
A3 |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). If you provide this field, |
Conditional |
N8.N4 |
applePay.paymentToken |
The encrypted payment token provided by Apple. |
Required |
ANS8192 |
Payments using Pre-Decrypted Payment Token Fields
Parameter name | Description | Required | Regex |
---|---|---|---|
paymentBrand |
The payment brand used to identify alternative payment method transactions. |
Required |
APPLEPAY |
card.number |
The Device Primary Account Number (DPAN). |
Required |
N19 |
card.expiryMonth |
The month that the card expires. |
Required |
N2 |
card.expiryYear |
The year that the card expires. |
Required |
N4 |
currency |
The currency code of the payment request’s amount (ISO 4217). |
Required |
A3 |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). |
Required |
N8.N4 |
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) |
Example
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\"
}
}
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
{
"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"
}
{
"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). |
Required |
A3 |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). |
Required |
N8.N4 |
googlePay.paymentToken |
The encrypted payment token provided by Google. |
Required |
ANS8192 |
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). |
Required |
A3 |
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). |
Required |
N8.N4 |
card.number |
The Primary Account Number (PAN) of the physical card, or the Device Primary Account Number (DPAN). |
Required |
N19 |
card.expiryMonth |
The month that the card expires. |
Required |
N2 |
card.expiryYear |
The year that the card expires. |
Required |
N4 |
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) |
threeDSecure.verificationId |
The VerificationID field contains the base64 encoded: |
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.+ |
Conditional |
N2 |
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) |
Example
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\"
}\"
}"
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DB"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=21.00"
-d "currency=USD"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "paymentBrand=GOOGLEPAY"
-d "threeDSecure.xid=VGhpcyBpcyBhIHNhbXBsZSB4aWQ="
-d "threeDSecure.verificationId=c2FtZSBhcyBvdGhlciB2YWx1ZXM="
-d "threeDSecure.eci=05"
-d "threeDSecure.tavv=c2FtZSBhcyBvdGhlciB2YWx1ZXM="
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
Point-to-Point-Encryption (P2PE) Card Data
Warning
|
Currently unsupported feature subject to change |
Point-to-Point-Encryption (P2PE) Card Data is compatible with the following message types:
Point-to-point encryption (P2PE) is an encryption standard that secures cardholder data at the terminal or point-of-sale (POS) level. This standard requires that cardholder information, including PAN and track data, is encrypted at the point of interaction, and is therefore safeguarded in transit or at rest.
Parameter name | Description | Required | Regex |
---|---|---|---|
pos.p2peEncrypted.type |
Indicates the scheme of point-to-point encryption (P2PE) used to encrypt the account data at the PIN entry device (PED). |
Required |
ACI| |
pos.p2peEncrypted.ksn |
The key serial number used to determine decryption key for Encrypted P2PE account data. This field is encoded as a hex representation of the binary P2PE key serial number value. |
Optional |
AN2048 |
pos.p2peEncrypted.sensitiveData |
The sensitive key block contains data items allowing the host to identify or derive the decryption keys, as well as any other data items required to decrypt the sensitive data. This field is encoded as a hex representation of the binary P2PE sensitive data block value. |
Optional |
AN65535 |
pos.p2peEncrypted.persistableData |
The persistable encrypted point-to-point encryption (P2PE) account data (PAN/EXPIRY). When P2PE functionality is used, and the card details were encrypted, this field is required instead of the card.number, card.track2data, card.expiryMonth, card.expiryYear, and card.cvv fields. If card details are received in addition to pos.p2peEncrypted.persistableData, it is assumed that the particular card used is subject to whitelisting and that pos.p2peEncrypted.whitelistFileName is present. This field is encoded as a hex representation of the binary P2PE sensitive data block value. |
Optional |
AN65535 |
pos.p2peEncrypted.volatileData |
The volatile (must not be stored) encrypted point-to-point encryption (P2PE) account data (PAN/TRACK2/EXPIRY). When P2PE functionality is used and the card details were encrypted, this field is required instead of the card.number, card.track2data, card.expiryMonth, card.expiryYear, and card.cvv fields. |
Optional |
AN65535 |
pos.p2peEncrypted.whitelistFileName |
The symbolic name given to the white-listed BIN file. When P2PE is in use, a file consisting of white-listed BINs might be supplied to the PED. Such a file must first be digitally signed by the DataSigner tool in the decrypting entity. This parameter is used by the decrypting entity to check that the PED is using the current version of the whitelist. |
Conditionally Required |
ANS100 |
pos.p2peEncrypted.tlvMapping[name] |
These fields describe the encoding used for the TLV fields in the Persisted Encrypted Sensitive Data Block (pos.p2peEncrypted.persistableData), as well as the Volatile Encrypted Sensitive Data Block (pos.p2peEncrypted.volatileData). |
Optional |
name: AN64 |
pos.p2peEncrypted.maxReliableBinLength |
This field is set to the number of starting digits of the PAN that are visible based on the obfuscation scheme. |
Conditionally Required |
N99999 |
pos.p2peEncrypted.whitelistHash |
A SHA-1 or SHA-256 hash value calculated over the content of the whitelist file loaded on the terminal. |
Conditionally Required |
AN255 |
pos.p2peEncrypted.whitelistSignature |
A base 64 encoded PKCS#7 signature of the whitelist file object using SHA-1 or SHA-256 for the signature algorithm, consisting of the following, Whitelist file data content, SHA-1 or SHA-256 signature of the data content, using the host private key and Verification certificate chain, including the host public key certificate. |
Conditionally Required |
AN99999 |
Example
sensitiveData
, persistableData
, and volatileData
fieldscurl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DB"
-d "amount=100.00"
-d "pos.storeId=78919753"
-d "pos.terminalId=34056111"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "pos.p2peEncrypted.type=INGENICO_ONGUARD"
-d "pos.p2peEncrypted.ksn=FFFF98765400020002280500060000"
-d "pos.p2peEncrypted.sensitiveData=2805000600003031313030364e47..."
-d "pos.p2peEncrypted.persistableData=41303854133380862400453030..."
-d "pos.p2peEncrypted.volatileData=3040431234f354130385410..."
-d "pos.p2peEncrypted.tlvMapping[DFDB02]=B"
-d "pos.p2peEncrypted.tlvMapping[57]=B"
-d "pos.p2peEncrypted.tlvMapping[5A]=B"
-d "pos.p2peEncrypted.tlvMapping[9F6B]=B"
-d "pos.p2peEncrypted. whitelistHash=58372014DHAE0431234f354130385410..."
-d "pos.p2peEncrypted. whitelistSignature=AEHUFAB571823502AHEANFAJ19400823423480..."
-d "pos.p2peEncrypted. maxReliableBinLength=124734918324789109842361048234861764329..."
Response
{
"id" : "e8f59d02a466f35a7ece785343e137e50",
"amount" : "100.00",
"currency" : "USD",
"result": {
"code" : "000.000.000",
"description" : "Transaction succeeded",
"authorizationId" : "783276"
},
"timestamp" : "2019-09-06 12:00:00"
}
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
Payment Identifier
Payment Identifier is compatible with the following message types:
The card.paymentIdentifier
field can be used to represent any payment identifier,
for example:
-
card numbers longer than 19 numeric digits
-
gift cards
-
voucher numbers
-
loyalty card numbers
-
fleet card numbers
Parameter name | Description | Required | Regex |
---|---|---|---|
card.paymentIdentifier |
The payment identifier used when card.number or card.track2Data are not appropriate, either due to limiting field formats/lengths, or not being an account based transaction. |
Required |
N28 |
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 |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DB"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2018"
-d "card.cvv=999"
-d "amount=21.00"
-d "pos.storeId=78919753"
-d "pos.terminalId=34056111"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Response
The following parameter will be present in the response if a Card Verification Result is received from the upstream entity.
Parameter name | Description | Regex |
---|---|---|
result.cvvResponse |
Contains the CVV response returned by the acquirer. |
A1 |
{
"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| |
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 |
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 |
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). |
Required |
N8.N4 |
currency |
The currency code of the payment request’s amount (ISO 4217). |
Required |
A3 |
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 |
billing.houseNumber1 |
Primary house number (door number or building number) of the billing address. |
Required |
ANS50 |
billing.postcode |
The postal code or zip code of the billing address. |
Required |
AN9 |
billing.city |
The town, district, or city of the billing address. |
Optional |
ANS20 |
billing.state |
The county, state, or region of the billing address. |
Optional |
AN20 |
billing.country |
The country of the billing address (ISO 3166-1). |
Optional |
A2 |
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 |
billing.street2 |
Additional address data of the company, or authorized person to contact. |
Optional |
ANS50 |
billing.houseNumber1 |
Primary house number (door number or building number) of the billing address. |
Optional |
ANS50 |
billing.postcode |
The postal code or zip code of the billing address. |
Optional |
AN9 |
billing.city |
The town, district, or city of the billing address. |
Optional |
ANS20 |
billing.state |
The county, state, or region of the billing address. |
Optional |
AN20 |
billing.country |
The country of the billing address (ISO 3166-1). |
Optional |
A2 |
billing.from.street1 |
The door number, floor, building number, building name, and/or street name of the billing address. |
Optional |
ANS50 |
billing.from.street2 |
Additional address data of the company, or authorized person to contact. |
Optional |
ANS50 |
billing.from.houseNumber1 |
Primary house number (door number or building number) of the billing address. |
Optional |
ANS50 |
billing.from.postcode |
The postal code or zip code of the billing address. |
Optional |
AN9 |
billing.from.city |
The town, district, or city of the billing address. |
Optional |
ANS20 |
billing.from.state |
The county, state, or region of the billing address. |
Optional |
AN20 |
billing.from.country |
The country of the billing address (ISO 3166-1). |
Optional |
A2 |
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 |
merchant.street |
The street address and/or name of the merchant. |
Required |
ANS23 |
merchant.city |
The city of the merchant. |
Required |
ANS13 |
merchant.country |
The country of the merchant. |
Required |
AN2 |
merchant.state |
The county, state, or region of the merchant. |
Required |
AN2 |
merchant.postcode |
The postal code of the merchant. |
Required |
ANS20 |
merchant.name |
The name of the merchant. |
Required |
ANS35 |
merchant.phone |
The phone number of the merchant. |
Required |
ANS35 |
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 |
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 |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DB"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=75.00"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=MAGSTRIPE"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
-d "merchant.mcc=1234"
-d "merchant.street=Century Avenue"
-d "merchant.city=Cape Town"
-d "merchant.country=ZA"
-d "merchant.state=WC"
-d "merchant.name=ACI Canteen"
-d "merchant.postcode=7441"
-d "merchant.phone=2721522500"
-d "merchant.submerchantId=112233445566789"
-d "merchant.recievingInstitutionCode=48265712347"
-d "billPayment=true"
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.3.13. Cashback
Cashback is compatible with the following message types:
Cashback refers to the money that is paid back to a customer after a
transaction has been completed. ConnectUP supports specifying a cashback
amount in requests. The cashbackAmount
is the
cash amount intended to be withdrawn at the point-of-sale (POS).
Note
|
The cashbackAmount amount must be included in the amount
field. ConnectUP does not perform any calculations to ensure this.
|
Parameter name | Description | Required | Regex |
---|---|---|---|
amount |
Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). 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. |
Required |
N8.N4 |
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. |
Required |
N8.N4 |
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). |
Required |
N8.N4 |
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. |
Required |
N8.N4 |
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 |
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. |
Required |
N8.N4 |
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. |
Required |
N8.N4 |
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. |
Required |
N8.N4 |
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. |
Required |
N8.N4 |
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| |
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| |
pos.fallbackReason |
Indicates the reason for a fallback transaction when pos.entryMode is set to a fallback value. |
Optional |
CARD_UNREADABLE| |
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 |
customer.customerCode |
A code identifying the customer. |
Optional |
ANS20 |
merchant.vatNr |
The card acceptor’s VAT number, used to identify the card acceptor when reporting taxes. |
Optional |
ANS20 |
merchant.refNr |
A reference number supplied by the card acceptor to facilitate communication and record keeping. |
Optional |
ANS20 |
merchant.taxId |
The merchant’s national tax number. |
Optional |
ANS20 |
merchant.streetAddress |
A street address associated with the merchant or card acceptor. |
Optional |
ANS48 [\s\S]{1,48} |
merchant.countrySubDivisionCode |
A state or province code for the retailer associated with the merchant or card acceptor. |
Optional |
ANS3 [a-zA-Z0-9]{3} |
merchant.url |
A website address for the retailer associated with the merchant or card acceptor. This field should be present for e-commerce transactions if available. |
Optional |
ANS255 [\s\S]{1,255} |
merchant.taxTreatment |
A customer service phone number for the retailer associated with the merchant or card acceptor. |
Optional |
ANS16 [\s\S]{1,16} |
merchant.additionalContactInformation |
May contain additional information, such as secondary phone numbers, customer service operation hours, and contact name. |
Optional |
ANS25 [\s\S]{1,25} |
merchant.partnerIdCode |
A partner ID established between the merchant or card acceptor and the issuer. |
Optional |
ANS6 [\s\S]{1,6} |
merchant.serviceLocationCityName |
The city of the location of the physical interaction with the customer. |
Optional |
ANS13 [\s\S]{1,13} |
merchant.serviceLocationCountrySubdivisionCode |
The state or province of the location of the physical interaction with the customer. |
Optional |
ANS3 [a-zA-Z0-9]{2,3} |
merchant.serviceLocationCountryCode |
The country code of the location of the physical interaction with the customer. |
Optional |
ANS2 [A-Za-z]{2} |
merchant.serviceLocationPostalCode |
The postal code of the location of the physical interaction with the customer. |
Optional |
ANS10 [\s\S]{1,10} |
customer.corporationVatNr |
The merchant’s VAT number. |
Optional |
ANS20 |
customer.vatNr |
The customer’s VAT number, used to identify the customer when reporting taxes. |
Optional |
ANS20 |
customer.orderDate |
The date when the order was placed. |
Optional |
AN10 |
customer.orderTime |
The time when the order was placed. |
Optional |
N6 |
customer.purchaseDate |
The date of the purchase/invoice. |
Optional |
AN10 |
customer.billingCode |
A customer code supplied by the merchant. |
Optional |
ANS20 |
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 |
Optional |
ANS20 |
taxCollected |
Indicates whether tax was collected. |
Optional |
TRUE|FALSE|Y|N |
card.commercialCardType |
This field indicates the type of commercial card used. |
Optional |
AN2 |
discountAmountSign |
Discount amount interpretation. |
Optional |
AN1 |
shippingAmountSign |
Shipping amount interpretation. |
Optional |
AN1 |
dutyAmountSign |
Duty amount interpretation. |
Optional |
AN1 |
customer.provincialSalesTaxRegistrationNr |
Provincial Sales Tax Registration Number. |
Optional |
AN15 [a-zA-Z0-9]{15} |
merchant.invoiceDiscountTreatment |
Indicates how the merchant is managing discounts. |
Optional |
AN1 [a-zA-Z0-9]{1} |
card.commercialCardType |
This field indicates the type of commercial card used. |
Optional |
AN2 |
{merch_taxTreatment} |
{merch_taxTreatment_desc} |
Optional |
{merch_taxTreatment_regex} |
merchantOrderNumber |
The merchant’s purchase order number. |
Optional |
ANS25 |
totalShippingAmount |
The freight, shipping, or delivery amount (in the major denomination) to be paid on the total purchase. |
Optional |
N8.N4 |
shippingAmountSign |
Shipping amount interpretation. |
Optional |
AN1 |
totalDutyAmount |
The duty amount (in the major denomination) to be paid on the total purchase. |
Optional |
N8.N4 |
dutyAmountSign |
Duty amount interpretation. |
Optional |
AN1 |
totalDiscountAmount |
The discount amount (in the major denomination) of the total purchase. |
Optional |
N8.N4 |
discountAmountSign |
Discount amount interpretation. |
Optional |
AN1 |
customer.provincialSalesTaxRegistrationNr |
Provincial Sales Tax Registration Number. |
Optional |
AN15 [a-zA-Z0-9]{15} |
taxAmounts[n].taxType |
The type of tax. |
Optional |
CITY_SALES| |
taxAmounts[n].taxDescription |
A description of the type of tax, for example, "Freight". |
Optional |
ANS20 |
taxAmounts[n].totalTaxAmount |
A tax amount (in the minor denomination) applied to this purchase. |
Optional |
N8.N4 |
taxAmounts[n].tax |
The tax rate to be applied to calculate this tax amount. |
Optional |
AN6 |
taxAmounts[n].taxId |
An ID number used by the card acceptor with the tax authority in connection with this type of tax. |
Optional |
ANS20 |
itemizedDiscounts[n].amount |
The discount amount (in the minor denomination). |
Optional |
N8.N4 |
itemizedDiscounts[n].rate |
The discount rate. Three decimal places are implied. |
Optional |
ANS5 |
itemizedDiscounts[n].discountCode |
The discount code supplied by the merchant. |
Optional |
ANS20 |
cart.items[n].number |
The line number of this item on the invoice. |
Optional |
N3 |
cart.items[n].customerCode |
A customer-supplied code relating to this item. |
Optional |
ANS20 |
cart.items[n].vatReferenceNr |
The reference number used to identify the VAT invoice or |
Optional |
ANS20 |
cart.items[n].supplyType |
The supply type. Valid values: 00 - Goods, 01 - Services |
Optional |
00|01 |
cart.items[n].totalAmountSign |
This sign applies to the totalAmount field of this item |
Optional |
C|D |
cart.items[n].invoiceDiscountTreatment |
Indicates how the merchant is managing discounts. |
Optional |
AN1 [0-9\.]{1} |
cart.items[n].lineItemDetailIndicator |
Indicates type of line item detail record. |
Optional |
AN1 [0-9\.]{1} |
cart.items[n].discountAmountSign |
Discount amount interpretation. |
Optional |
AN1 [0-9\.]{1} |
cart.items[n].description |
A description of this item. |
Optional |
ANS40 |
cart.items[n].merchantItemId |
The universal product code (UPC) of this item. |
Optional |
ANS20 |
cart.items[n].quantity |
The quantity of this item. |
Optional |
N9.N3 |
cart.items[n].unitOfMeasure |
The unit of measure pertaining to the items[n].quantity field, as defined by the card acceptor. |
Optional |
ANS12 |
cart.items[n].totalAmount |
The total amount (in the minor denomination) for this item. |
Optional |
N8.N4 |
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 |
cart.items[n].price |
The price (in the minor denomination) of one unit of the |
Optional |
[0-9]{1,8}(\.[0-9]{1,4})? |
cart.items[n].discountAmount |
The discount amount (in the minor denomination) applied |
Optional |
N8.N4 |
cart.items[n].discount |
The discount rate applied to this item. Three decimal |
Optional |
|
cart.items[n].taxAmounts[n].taxType |
The type of tax. |
Optional |
CITY_SALES| |
cart.items[n].taxAmounts[n].taxDescription |
A description of the type of tax, for example, "Freight". |
Optional |
ANS20 |
cart.items[n].taxAmounts[n].totalTaxAmount |
A tax amount (in the minor denomination) applied to this item. |
Optional |
N8.N4 |
cart.items[n].taxAmounts[n].tax |
The tax rate to be applied to calculate this tax amount. |
Optional |
AN6 |
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 |
cart.items[n]itemizedDiscounts[n].amount |
The discount amount (in the minor denomination). |
Optional |
N8.N4 |
cart.items[n]itemizedDiscounts[n].rate |
The discount rate. Three decimal places are |
Optional |
ANS5 |
cart.items[n]itemizedDiscounts[n].discountCode |
The discount code supplied by the merchant. |
Optional |
ANS20 |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=CP"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "card.accountType=DEFAULT"
-d "amount=16.50"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=MAGSTRIPE"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
-d "merchantOrderNumber=123456"
-d "customer.orderNumber=8423794"
-d "customer.customerCode=8423794"
-d "customer.corporationVatNr=987654456789"
-d "customer.vatNr=123456654321"
-d "customer.orderTime=120106"
-d "customer.purchaseDate=2021-05-19"
-d "customer.billingCode=9988771122339911"
-d "customer.fuelTaxExempt=TRUE"
-d "customer.nonFuelTaxExempt=FALSE"
-d "customer.provincialSalesTaxRegistrationNr="999994444477777"
-d "customer.taxExempt=true"
-d "merchant.taxId=8423794"
-d "merchant.vatNr=6664446646"
-d "merchant.refNr=7774447747"
-d "merchant.invoiceDiscountTreatment=3"
-d "merchant.taxTreatment=2"
-d "totalShippingAmount=0.00"
-d "totalDutyAmount=15.00"
-d "totalDiscountAmount=15.00"
-d "commodityCode=CC5456456456"
-d "taxCollected=Y"
-d "discountAmountSign=C"
-d "shippingAmountSign=D"
-d "dutyAmountSign=G"
-d "card.commercialCardType=MC"
-d "taxAmounts[0].taxType=GOODS_AND_SERVICES"
-d "taxAmounts[0].totalTaxAmount=1.50"
-d "taxAmounts[0].tax=00.10"
-d "taxAmounts[0].taxId=G&S_taxes"
-d "taxAmounts[0].taxDescription=State GS"
-d "itemizedDiscounts[0].amount=156.46"
-d "itemizedDiscounts[0].rate=57"
-d "itemizedDiscounts[0].discountCode=j857684576846"
-d "cart.items[0].description=genericDescription"
-d "cart.items[0].merchantItemId=genericItemId"
-d "cart.items[0].quantity=1"
-d "cart.items[0].unitOfMeasure=lbs"
-d "cart.items[0].totalAmount=15.00"
-d "cart.items[0].totalAmountType=NET"
-d "cart.items[0].sku=11125455"
-d "cart.items[0].price=15.00"
-d "cart.items[0].discountAmount=1.50"
-d "cart.items[0].discount=10"
-d "cart.items[0].taxAmounts[0].taxType=FEDERAL_NATIONAL_SALES"
-d "cart.items[0].taxAmounts[0].totalTaxAmount=1.50"
-d "cart.items[0].taxAmounts[0].tax=00.10"
-d "cart.items[0].taxAmounts[0].taxId=us_taxes"
-d "cart.items[0].taxAmounts[0].taxDescription=State TX"
-d "cart.items[0].itemizedDiscounts[0].amount=156.46"
-d "cart.items[0].itemizedDiscounts[0].rate=57"
-d "cart.items[0].itemizedDiscounts[0].discountCode=j857684576846"
Note
|
The amount field in the message must indicate
the total amount of the payment request, which includes all tax,
duty, shipping, and other discount amounts.
ConnectUP does not perform any calculations to ensure this.
|
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.3.25. Fleet Data
Fleet Data is compatible with the following message types:
ConnectUP supports sending fleet data, including prompt and batch data.
All fleet fields are optional. When sending fleet data, fleet.prompts
and
fleet.fleetBatchDataList
must be specified using an indexed-number [n],
starting with 0.
For example:
fleet.prompts[0].tractorNumber = "TRACT5554433546"
Parameter name | Description | Required | Regex |
---|---|---|---|
fleet.oilBrandName |
The acquirer’s abbreviation for the brand name of the card acceptor’s oil company. |
Optional |
N4 |
fleet.serviceType |
The type of service received at the card acceptor location. Valid values: 1 - Self-service |
Optional |
ANS1 |
fleet.vehicleUsage |
Valid values: |
Optional |
A1 |
fleet.odometer |
The reading of the total distance travelled by the vehicle. |
Optional |
N9 |
fleet.vehicleReg |
The registration number of the rented or fleet vehicle. |
Optional |
AN17 |
fleet.driverId |
The number assigned to the driver by the employer for purposes of tracking fuel purchases. |
Optional |
ANS20 |
fleet.promptCode |
Contains a code read from a card that indicates terminal prompts that occur at the point-of-service. Valid values: |
Optional |
N1 |
fleet.restrictionCode |
Contains the restriction code that applies to the transaction. |
Optional |
ANS3 |
fleet.privateData |
Any data proprietary to the system for this item. |
Optional |
ANS999 |
fleet.purchaseType |
The type of products purchased. Valid values: |
Optional |
A1 |
fleet.prompts[n].userId |
The user identification number. |
Optional |
ANS20 |
fleet.prompts[n].vehicleId |
The vehicle identification number. |
Optional |
ANS20 |
fleet.prompts[n].department |
The department number. |
Optional |
AN15 |
fleet.prompts[n].driverLicense |
The driver license number. |
Optional |
AN12 |
fleet.prompts[n].customerData |
Any customer data. |
Optional |
AN15 |
fleet.prompts[n].customerData1 |
Any customer data. |
Optional |
ANS20 |
fleet.prompts[n].customerData2 |
Any additional customer data. |
Optional |
ANS20 |
fleet.prompts[n].cashBackAmount |
The cash back amount. |
Optional |
N12 |
fleet.prompts[n].siteTransactionNumber |
The site transaction number. |
Optional |
N12 |
fleet.prompts[n].jobId |
The job identification number. |
Optional |
AN15 |
fleet.prompts[n].contractNumber |
The contract number. |
Optional |
AN20 |
fleet.prompts[n].PIN |
The vehicle PIN number. |
Optional |
ANS6 |
fleet.prompts[n].tripNumber |
The fleet trip number. |
Optional |
ANS15 |
fleet.prompts[n].unitNumber |
The fleet unit number. |
Optional |
ANS15 |
fleet.prompts[n].trailerId |
The fleet trailer identification. |
Optional |
ANS16 |
fleet.prompts[n].trailerHours |
The fleet trailer hours number. |
Optional |
N6 |
fleet.prompts[n].maintenanceId |
The fleet maintenance identification. |
Optional |
AN15 |
fleet.prompts[n].hubometer |
The fleet hubometer number. |
Optional |
N9 |
fleet.prompts[n].employeeNumber |
The fleet employee number. |
Optional |
N20 |
fleet.prompts[n].driverLicenseState |
The driver license state code. |
Optional |
AN2 |
fleet.prompts[n].vehicleLicense |
The vehicle license number. |
Optional |
ANS20 |
fleet.prompts[n].vehicleLicenseState |
The vehicle license state code. |
Optional |
AN2 |
fleet.prompts[n].trailerLicense |
The trailer license number. |
Optional |
AN12 |
fleet.prompts[n].trailerLicenseState |
The trailer license state code. |
Optional |
AN2 |
fleet.prompts[n].fleetId |
The ID that is defined to the fleet authorizer. |
Optional |
AN6 |
fleet.prompts[n].customData |
This could carry fleet authorizer specific data like 'VoyagerData'. |
Optional |
ANS260 |
fleet.prompts[n].vehicleTag |
The fleet vehicle tag. |
Optional |
AN99 |
fleet.prompts[n].driverLicenseLocation |
This is used to carry the state/province or other location data. |
Optional |
AN3 |
fleet.prompts[n].driverLicenseName |
The driver license name. |
Optional |
ANS22 |
fleet.prompts[n].driverDateOfBirth |
The driver date of birth. |
Optional |
N8 |
fleet.prompts[n].vehicleVINNumber |
The vehicle identification number. |
Optional |
AN17 |
fleet.prompts[n].pumpNumber |
The petrol pump number. |
Optional |
AN99 |
fleet.prompts[n].tractorNumber |
The tractor number. |
Optional |
AN15 |
fleet.fleetBatchDataList[n].batchDate |
The fleet batch date. |
Optional |
N8 |
fleet.fleetBatchDataList[n].transactionCount |
The transaction count for a batch. |
Optional |
AN99 |
fleet.fleetBatchDataList[n].total |
The total fuel quantity. |
Optional |
N99 |
fleet.fleetBatchDataList[n].totalUnit |
The total units ('Gallons' or 'Liters'). |
Optional |
Gallons|Liters |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=CP"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "card.accountType=DEFAULT"
-d "amount=16.50"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=MAGSTRIPE"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
-d "fleet.oilBrandName=9988"
-d "fleet.serviceType=3"
-d "fleet.vehicleUsage=B"
-d "fleet.odometer=112277889"
-d "fleet.vehicleReg=VREG543377FFGG444"
-d "fleet.driverId=11147741"
-d "fleet.promptCode=6"
-d "fleet.restrictionCode= 1 "
-d "fleet.privateData= Private Data 123"
-d "fleet.purchaseType=B"
-d "fleet.prompts[0].userId=UID5656MFNNNFF7"
-d "fleet.prompts[0].vehicleId=VID88558HB"
-d "fleet.prompts[0].department=DEP88555jjdd123"
-d "fleet.prompts[0].driverLicense=DL666HHAAFFT"
-d "fleet.prompts[0].customerData=CD5546444346646"
-d "fleet.prompts[0].customerData1=DATA23:45;4;5;234234"
-d "fleet.prompts[0].customerData2=DATA25:403294,234234"
-d "fleet.prompts[0].cashBackAmount=000000000000"
-d "fleet.prompts[0].siteTransactionNumber=123345346645"
-d "fleet.prompts[0].jobId=JOBID55555666D3"
-d "fleet.prompts[0].contractNumber=CNUMBER888FRT664AADF"
-d "fleet.prompts[0].PIN= P!n#24"
-d "fleet.prompts[0].tripNumber=TRIP NUMBER 123"
-d "fleet.prompts[0].unitNumber=FLEETUNIT5"
-d "fleet.prompts[0].trailerId=TRAILER ID 12 "
-d "fleet.prompts[0].trailerHours=000008"
-d "fleet.prompts[0].maintenanceId=MAINTID12312312"
-d "fleet.prompts[0].hubometer=000000009"
-d "fleet.prompts[0].employeeNumber=666"
-d "fleet.prompts[0].driverLicenseState=CA"
-d "fleet.prompts[0].vehicleLicense=VEHLIC123"
-d "fleet.prompts[0].vehicleLicenseState=CW"
-d "fleet.prompts[0].trailerLicense=TL555"
-d "fleet.prompts[0].trailerLicenseState=CR"
-d "fleet.prompts[0].fleetId=FID123"
-d "fleet.prompts[0].customData= THIS IS CUSTOM DATA "
-d "fleet.prompts[0].vehicleTag=VEHTAG177"
-d "fleet.prompts[0].driverLicenseLocation=CAQ"
-d "fleet.prompts[0].driverLicenseName=This is my name"
-d "fleet.prompts[0].driverDateOfBirth=19850212"
-d "fleet.prompts[0].vehicleVINNumber=VINNUM12366"
-d "fleet.prompts[0].pumpNumber=PUMPNUM3"
-d "fleet.prompts[0].tractorNumber=TRACT5554433546"
-d "fleet.fleetBatchDataList[0].batchDate=20210607"
-d "fleet.fleetBatchDataList[0].transactionCount=0000001112"
-d "fleet.fleetBatchDataList[0].total=00000111155544"
-d "fleet.fleetBatchDataList[0].totalUnit=Liters"
Response
The response may contain fleet data which can be sent to the pump. Fleet data may be present in the fleet field of the response.
Parameter name | Description | Required | Regex |
---|---|---|---|
fleet.promptForOdometer |
The prompt is required to complete the transaction or not. |
Optional |
N1 |
fleet.printPricePerGallon |
This field identifies if price per gallon needs to be printed on customer receipt. |
Optional |
AN1 |
fleet.maximumPurchaseAmount |
The maximum purchase amount in minor denomination in the currency of the transaction. |
Optional |
N12 |
fleet.maximumOilAmount |
The maximum oil amount in minor denomination in the currency of the transaction. |
Optional |
N12 |
fleet.maximumPartsAmount |
The maximum parts amount in minor denomination in the currency of the transaction. |
Optional |
N12 |
fleet.maximumAmountOther |
The maximum other amount in minor denomination in the currency of the transaction. |
Optional |
N12 |
fleet.hostBasedPurchaseRestriction |
The host-based purchase restriction data. |
Optional |
ans32 |
Sample Response Containing fleet response data
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"tokenId" : "JYO7rdR5UjK61111",
"amount" : "92.00",
"currency" : "USD",
"result": {
"code" : "000.000.000",
"description" : "Transaction succeeded",
"authorizationId" : "783276"
},
"customParameters":{
"CUSTOM_KEY1":"CUSTOM_VALUE1",
"CUSTOM_KEY2":"CUSTOM_VALUE2"
},
"fleet":{
"promptForOdometer":"1",
"printPricePerGallon":"2",
"maximumPurchaseAmount":"000000001111",
"maximumOilAmount":"000000002222",
"maximumPartsAmount":"000000003333",
"maximumAmountOther":"000000004444"
},
"resultDetails" : {
"FleetDataRsp": "<FleetDataRsp MaximumAmountOther=\"000000004444\" MaximumOilAmount=\"000000002222\" MaximumPartsAmount=\"000000003333\" MaximumPurchaseAmount=\"000000001111\" PrintPricePerGallon=\"2\" PromptForOdometer=\"1\"></FleetDataRsp>"
},
"timestamp" : "2019-09-06 12:22:44"
}
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.3.26. Linked Capture
Linked Capture is compatible with the following message type:
A linked capture notification (CP)
enables a merchant to capture a previously submitted
pre-authorization message by
providing the id
of the original authorization in the
linked capture request.
Parameter name | Description | Required | Regex |
---|---|---|---|
referencedPaymentId |
The identifier of the transaction being completed (the Id from the original PA response). |
Required |
ANS32 |
Example
An example scenario follows:
Initial Pre-Authorization Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=PA"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=46.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78119753"
-d "pos.entryMode=MANUAL"
Pre-Authorization Response
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"amount" : "46.00",
"currency" : "USD",
"result": {
"code" : "000.000.000",
"description" : "Transaction succeeded",
"authorizationId" : "783276"
},
"timestamp" : "2019-09-06 12:22:44"
}
Linked Capture Request using referencedPaymentId
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=CP"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=46.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78119753"
-d "pos.entryMode=MANUAL"
-d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50"
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.3.27. Merchant-Initiated Transaction (MIT)/Customer-Initiated Transaction (CIT)
Merchant-Initiated Transaction (MIT)/Customer-Initiated Transaction (CIT) is compatible with the following message types:
ConnectUP supports sending the following CIT and MIT transactions:
Initiated transaction type | Required parameters |
---|---|
CIT First Transaction (The cardholder is storing a credential for a subsequent transaction.) |
|
CIT First Recurring Transaction (The cardholder is storing a credential for a subsequent transaction.) |
|
CIT First Recurring Installment Transaction (The cardholder is storing a credential for a series of recurring installment transactions.) |
|
CIT Subsequent Transaction (The cardholder is using a stored credential.) |
|
MIT Unscheduled Transaction (The merchant using a stored credential as needed.) |
|
MIT First Recurring Transaction (The merchant initiating a series of recurring transactions.) |
|
MIT first recurring installment transaction (The merchant initiating a series of recurring installment transactions.) |
|
Industry practice of 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. |
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| |
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| |
Example
CIT Initial Transaction
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DB"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2018"
-d "amount=21.00"
-d "pos.storeId=78919753"
-d "pos.terminalId=34056111"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "standingInstruction.mode=INITIAL"
-d "standingInstruction.source=CIT"
MIT Subsequent Transaction
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DB"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2018"
-d "amount=21.00"
-d "pos.storeId=78919753"
-d "pos.terminalId=34056111"
-d "pos.entryMode=CREDENTIAL_ON_FILE"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "standingInstruction.type=RECURRING"
-d "standingInstruction.mode=REPEATED"
-d "standingInstruction.source=MIT"
-d "customParamters[bankField1]=bankValue1"
Response
Note
|
For cases where standingInstruction.mode is set to INITIAL ,
and standingInstruction.source is set to CIT , the upstream entity
will return field data in resultDetails that will allow any
subsequent messages to link back to the initial message as long
as they are provided in the subsequent transaction as customParameters .
|
Sample Response from an INITIAL CIT transaction
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"amount" : "50.00",
"currency" : "USD",
"result": {
"code" : "000.000.000",
"description" : "Transaction succeeded",
"authorizationId" : "783276"
},
"resultDetails":{
"bankField1":"bankValue1",
},
"timestamp" : "2019-09-06 12:00:00"
}
Note
|
For a subsequent transaction, the value in resultDetails
must be present as a customParameter in the subsequent message.
|
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.3.28. Multiple Clearing (Captures)
Multiple Clearing (Captures) is compatible with the following message type:
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 |
lastCapture |
When this flag is set to true, it indicates that the last capture or completion in the chain is being sent. |
Optional |
true |
Example
An example for a Multiple Capture sequence might be an order that contains multiple items to ship. For each shipment, the merchant can perform a partial capture on the original pre-authorization message for the goods being delivered.
A multiple capture scenario follows:
-
Send an initial authorization request for the total amount intended for the transaction.
-
Fulfill half the order and partially capture one half the original initial authorization.
-
Fulfill the remainder of the order and partially capture the remaining amount of the original authorization.
Initial Authorization Request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=PA"
-d "card.track2Data=5416389123456786D22021010000081315000"
-d "amount=100.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MAGSTRIPE"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
Response of the Initial Authorization
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"amount" : "100.00",
"currency" : "USD",
"result": {
"code" : "000.000.000",
"description" : "Transaction succeeded",
"authorizationId" : "783276"
},
"timestamp" : "2019-09-06 12:00:00"
}
First Partial Capture Request
This is the first CP
request referencing the PA’s `id
in the
referencedPaymentId
field; specifying 25.00 USD.
The captureSequence
field is set to 01
indicating
that this is the first CP
in a chain.
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=CP"
-d "card.track2Data=5416389123456786D22021010000081315000"
-d "amount=25.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MAGSTRIPE"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "captureSequence=01"
-d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50"
Response of the First Capture Request
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"amount" : "50.00",
"currency" : "USD",
"result": {
"code" : "000.000.000",
"description" : "Transaction succeeded",
"authorizationId" : "456464"
},
"timestamp" : "2019-09-07 12:00:00"
}
Final Partial Capture Request
This is the last CP
request, again
referencing the PA’s `id
in the referencedPaymentId
field, this time specifying
75.00 USD. The captureSequence
field is set to 02
,
indicating that this is the second CP
in the chain. The lastCapture
field is set to true
, indicating
that this is the final CP
message in the chain.
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=CP"
-d "card.track2Data=5416389123456786D22021010000081315000"
-d "amount=75.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MAGSTRIPE"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "captureSequence=02"
-d "lastCapture=true"
-d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50"
Response of the Final Capture Request
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"amount" : "75.00",
"currency" : "USD",
"result": {
"code" : "000.000.000",
"description" : "Transaction succeeded",
"authorizationId" : "7698987"
},
"timestamp" : "2019-09-10 12:00:00"
}
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.3.29. Partial Approval
Compatible with the following message types:
To allow partially approved transactions, add the following parameter to your payment message.
Note
|
If partialApprovalAllowed is set to false, the
parameter will have no effect on the payment.
|
Parameter Name | Description | Required | Regex |
---|---|---|---|
partialApprovalAllowed |
When this flag is set to true, it indicates that partially approved authorizations are acceptable to the client. |
Required |
true |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=PA"
-d "amount=21.00"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=MANUAL"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "partialApprovalAllowed=true"
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this type of request.
2.3.30. Payment Identifier
Payment Identifier is compatible with the following message types:
The card.paymentIdentifier
field can be used to represent any payment identifier,
for example:
-
card numbers longer than 19 numeric digits
-
gift cards
-
voucher numbers
-
loyalty card numbers
-
fleet card numbers
Parameter name | Description | Required | Regex |
---|---|---|---|
card.paymentIdentifier |
The payment identifier used when card.number or card.track2Data are not appropriate, either due to limiting field formats/lengths, or not being an account based transaction. |
Required |
N28 |
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| |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DB"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "card.pinlessDebit=true"
-d "amount=75.00"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=MAGSTRIPE"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
Responses
The PIN-less debit response parameter will contain the route
(DEBIT
or CREDIT
) used by the processor for the transaction.
Parameter name | Description | Regex |
---|---|---|
card.pinlessDebit |
Indicates whether the transaction was processed as a credit or a debit transaction by the processor. |
CREDIT|DEBIT |
Response containing the PIN-less Debit response parameter
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"amount" : "75.00",
"currency" : "USD",
"result": {
"code" : "000.000.000",
"description" : "Transaction succeeded",
"authorizationId" : "783276"
},
"card" : {
"pinlessDebit": "DEBIT"
},
"timestamp" : "2019-09-06 12:22:44"
}
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.3.32. Point-of-Sale (POS) Data Fields
Point-of-Sale (POS) Data Fields is compatible with the following message types:
ConnectUP provides the functionality to indicate specific conditions that were present at the time a transaction took place at the point-of-service (POS).
If present, the lower-level POS fields that are listed here will override any POS conditions that might have otherwise been inferred when constructing any standard ConnectUP message.
Parameter name | Description | Required | Regex |
---|---|---|---|
pos.cardDataInputMode |
Indicates the method used to retrieve the card details at the point-of-service. When this field is not supplied, it is assumed that it is the same as the value for pos.entryMode. |
Optional |
UNKNOWN| |
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| |
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| |
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| |
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| |
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| |
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| |
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| |
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| |
pos.terminalOperator |
Indicates who is operating the point-of-service. If not inferred by pos.entryMode or transactionCategory, CUSTOMER is used. |
Optional |
CUSTOMER| |
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. |
Optional |
ADMIN| |
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| |
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 |
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. |
Optional |
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|VOID|UNSPECIFIED|COMPLETED_PARTIALLY|UNABLE_TO_DELIVER|SUSPECTED_MALFUNCTION|INVALID_RESPONSE|TIMEOUT|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 reversal. |
Required |
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|VOID|UNSPECIFIED|COMPLETED_PARTIALLY|UNABLE_TO_DELIVER|SUSPECTED_MALFUNCTION|INVALID_RESPONSE|TIMEOUT|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, or CP transaction that is to be reversed. |
Required |
ANS255 |
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. |
Required |
PIN_PROVIDED| |
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 the SCA Result Code table for details. |
Required |
AN11 |
SCA Result Code Listing
Result code | Description |
---|---|
300.100.100 |
Transaction declined (additional customer authentication required) |
300.100.190 |
Transaction declined (Issuer Requires PIN [SCA]) |
300.100.191 |
Transaction declined (SCA exemption is invalid) |
300.100.192 |
Transaction declined (additional customer authentication required) |
Tip
|
See the standard response fields for a list of possible response parameters that ConnectUP can return for this request type. |
Example
An example scenario for SCA for terminals that support Single Tap and PIN, where the customer withdrawal frequency has been exceeded, follows:
-
A standard contactless pre-authorization message is sent with
pos.scaExemptionFlag = TAP_AND_PIN_SUPPORTED
. -
The upstream entity responds with the
300.100.190: Transaction declined (Issuer Requires PIN [SCA])
result code. -
The terminal updates the message with the provided PIN.
-
A new payment message with PIN is sent to ConnectUP.
-
The
pos.scaExemptionFlag
field is updated toPIN_PROVIDED
-
No further exemption will be applied to transactions that contain PIN data.
Initial contactless request
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=PA"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=10000000.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=NFC_ICC"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "pos.scaExemptionFlag=TAP_AND_PIN_SUPPORTED"
Response indicating the declined transaction due to the issuer requesting SCA
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"amount" : "0.00",
"currency" : "USD",
"result": {
"code" : "300.100.190",
"description" : "Transaction declined (Issuer Requires PIN [SCA])",
"authorizationId" : "783276"
},
"timestamp" : "2019-09-06 12:22:44"
}
Secondary contactless request with PIN data to satisfy the exemption
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=PA"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=10000000.00"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "pos.entryMode=NFC_ICC"
-d "pos.encryptedPin.data=A3929E6A25E8E32C"
-d "pos.encryptedPin.ksn=*"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
-d "pos.scaExemptionFlag=PIN_PROVIDED"
Note
|
For terminals that do not support single tap and PIN, the customer will have to
re-present their card and enter a PIN. This data must be present in the second payment message
with pos.scaExemptionFlag set to PIN_PROVIDED , as previously illustrated.
|
2.3.38. Shipping Contact
Shipping Contact is compatible with the following message types:
To specify the contact details of the shipping sender or receiver, use the following fields.
The shipping.*
fields must be used for the customer
which receiving the shipment. The shipping.from.*
fields must be used for the merchant/retailer which is
sending the shipment.
Parameter name | Description | Required | Regex |
---|---|---|---|
shipping.street1 |
The door number, floor, building number, building name, and/or street name of the shipping address. |
Optional |
ANS50 |
shipping.street2 |
The adjoining road or locality (if required) of the shipping address. |
Optional |
ANS50 |
shipping.method |
The shipping method. |
Optional |
CARRIER_DESIGNATED_BY_CUSTOMER| |
shipping.warehouse |
The warehouse that received the order. |
Optional |
ANS100 |
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 |
shipping.postcode |
The postal code or zip code of the shipping address. |
Optional |
AN9 |
shipping.city |
The town, district, or city of the shipping address. |
Optional |
ANS20 |
shipping.state |
The county, state, or region of the shipping address. |
Optional |
AN20 |
shipping.country |
The country of the shipping address (ISO 3166-1). |
Optional |
A2 |
shipping.customer.givenName |
The first name or given name of the shipping customer. |
Optional |
ANS50 |
shipping.customer.surname |
The last name or surname of the shipping customer. |
Optional |
ANS50 |
shipping.customer.email |
The shipping customer’s email address. This is required for some risk checks and transmission of direct debit mandates. |
Optional |
ANS128 |
shipping.customer.companyName |
The company name to contact. |
Optional |
ANS50 |
shipping.from.street1 |
The door number, floor, building number, building name, and/or street name of the shipping address. |
Optional |
ANS50 |
shipping.from.street2 |
The adjoining road or locality (if required) of the shipping address. |
Optional |
ANS50 |
shipping.from.warehouse |
The warehouse that received the order. |
Optional |
ANS100 |
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 |
shipping.from.postcode |
The postal code or zip code of the shipping address. |
Optional |
AN9 |
shipping.from.city |
The town, district, or city of the shipping address. |
Optional |
ANS20 |
shipping.from.state |
The county, state, or region of the shipping address. |
Optional |
AN20 |
shipping.from.country |
The country of the shipping address (ISO 3166-1). |
Optional |
A2 |
shipping.from.customer.givenName |
The first name or given name of the shipping customer. |
Optional |
ANS50 |
shipping.from.customer.surname |
The last name or surname of the shipping customer. |
Optional |
ANS50 |
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 |
shipping.from.customer.companyName |
The company name to contact. |
Optional |
ANS50 |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=PA"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2050"
-d "amount=75.00"
-d "pos.terminalId=12195611"
-d "pos.storeId=78123753"
-d "pos.entryMode=MAGSTRIPE"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d2"
-d "shipping.street1=Receiver Park"
-d "shipping.street2=123 Main Street"
-d "shipping.houseNumber1=1"
-d "shipping.postcode=7500"
-d "shipping.city=Cape Town"
-d "shipping.state=WC"
-d "shipping.country=ZA"
-d "shipping.method=NEXT_DAY_OVERNIGHT"
-d "shipping.warehouse=Receiving Warehouse"
-d "shipping.customer.givenName=John"
-d "shipping.customer.surname=Smith"
-d "shipping.customer.email=johnsmith@receivingemail.com"
-d "shipping.customer.company=The Receiving Company"
-d "shipping.from.street1=Sender Complex"
-d "shipping.from.street2=13 West Street"
-d "shipping.from.houseNumber1=1"
-d "shipping.from.postcode=7500"
-d "shipping.from.city=Cape Town"
-d "shipping.from.state=WC"
-d "shipping.from.country=ZA"
-d "shipping.from.warehouse=Sending Warehouse"
-d "shipping.from.customer.givenName=Jeffrey"
-d "shipping.from.customer.surname=Zebos"
-d "shipping.from.customer.email=jeffzebos@sendingemail.com"
-d "shipping.from.customer.companyName=The Sending Company"
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
2.3.39. Transaction Category
Transaction Category is compatible with the following message types:
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. |
Required |
EC|MO|PM|PO|TO |
Example
curl http://[hostname]:[port]/paymentsapi/opp/v1/payment
-H "Authorization: Bearer NjAyNTYzYjdmOGVmYT...."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "paymentType=DB"
-d "card.number=4444444444444448"
-d "card.expiryMonth=05"
-d "card.expiryYear=2018"
-d "amount=95.00"
-d "pos.storeId=78919753"
-d "pos.terminalId=34056111"
-d "pos.entryMode=MANUAL"
-d "transactionCategory=EC"
-d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1"
See the standard response fields for a listing of the possible response parameters ConnectUP can return for this request type.
3. Token Service
The Tokenization service creates a token based on card data and retrieves card data based on a token.
A Tokenization Request is created by sending a POST request over HTTPS to:
https://[hostname]:[port]/paymentsapi/opp/v1/token/tokenize
A De-tokenization Request is created by sending a POST request over HTTPS to:
https://[hostname]:[port]/paymentsapi/opp/v1/token/detokenize
3.1. Tokenization
Tokenization is the process whereby sensitive card details are substituted with a token, a value which in and of itself holds no identifiable or exploitable information.
3.1.1. Tokenization Request
A tokenization request stores sensitive card data fields and returns a token. This token can be used to initiate payments in place of the card details associated with the token.
Note
|
Either card.number ,
card.track2Data , or P2PE card data fields must be
specified for a tokenization request.
|
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
card.number |
The Primary Account Number (PAN) of the physical card. |
N19 |
|
card.expiryMonth |
The month that the card expires. |
Optional |
N2 |
card.expiryYear |
The year that the card expires. |
Optional |
N4 |
Note
|
The card expiry fields (card.expiryMonth and card.expiryYear )
must either both be set, or neither must be set. A token created without
expiry data can be used in a payment request only if the expiry data
is sent with the payment request.
|
Example
curl http://[hostname]:[port]/opp/v1/token/tokenize -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "card.number=2222333344442226"
-d "card.expiryMonth=12"
-d "card.expiryYear=2020"
3.1.2. Tokenization Response
The following fields reflect the possible response values for Tokenization service requests.
Parameter name | Description | Required | Regex |
---|---|---|---|
id |
The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client. |
Required |
AN32 |
tokenId |
A token representing sensitive cardholder data. |
Optional |
AN255 |
result.code |
The unique code that indicates the result status of the request. See common result codes for this type of request. |
Required |
AN11 |
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 |
resultDetails.* |
A container for name-value pairs used for enriching the response with bank-specific response details. |
Optional |
name: AN64 |
Example
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"tokenId" : "JYO7rdR5UjK61111",
"result": {
"code" : "000.000.000",
"description" : "Transaction successful",
},
"resultDetails": {
"Field1": "Value1",
"Field2": "Value2"
},
"timestamp" : "2018-02-20 12:00:00"
}
Common result codes for tokenization requests:
Result code | Description |
---|---|
000.000.000 |
Transaction succeeded |
800.900.303 |
No token created |
000.000.099 |
Transaction Succeeded (partial approval) |
200.300.404 |
Invalid or missing parameter |
800.100.190 |
Token generation not permitted |
800.100.190 |
Token set invalid or not permitted |
800.100.190 |
Multi-use token collision |
800.100.190 |
Single-use token collision |
800.100.190 |
Token operation not permitted or supported |
800.100.190 |
Transaction declined (invalid configuration data) |
900.100.400 |
Token service unavailable |
900.100.600 |
Token server malfunction |
900.100.600 |
Connector/acquirer currently down |
Note
|
Optional fields will only be returned if the request could be processed (no validation
errors occurred on the fields in the request). The
request result.code must always be evaluated
with the HTTP status code
to determine the overall status of the request.
|
3.2. De-tokenization
De-tokenization is the process where a token value is used to retrieve the original tokenized card details through a secure tokenization system.
3.2.1. De-tokenization Request
A de-tokenization request retrieves sensitive card-data fields associated with the supplied token.
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
tokenId |
A token representing sensitive cardholder data. |
Required |
AN255 |
The tokenId parameter is a token that has previously been returned by a tokenization request or returned in the payment request response.
Example
curl http://[hostname]:[port]/opp/v1/token/detokenize -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "tokenId=JYO7rdR5UjK61111"
3.2.2. Detokenization Response
The following fields reflect the possible response values for de-tokenization service requests.
The De-tokenization service supports response msg encryption. Please read the Configuring Encryption section of the PaymentsAPI user guide for more information.
Parameter name | Description | Required | Regex |
---|---|---|---|
id |
The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client. |
Required |
AN32 |
tokenId |
A token representing sensitive cardholder data. |
Optional |
AN255 |
result.code |
The unique code that indicates the result status of the request. See common result codes for this request type. |
Required |
AN11 |
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 |
card.number |
The Primary Account Number (PAN) of the physical card. This field is always returned for successful de-tokenization requests. |
Conditional |
N19 |
card.expiryMonth |
The month that the card expires. |
Optional |
N2 |
card.expiryYear |
The year that the card expires. |
Optional |
N4 |
resultDetails.* |
A container for name-value pairs used for enriching the response with bank-specific response details. |
Optional |
name: AN64 |
Note
|
The card.expiryMonth and card.expiryYear fields will only
be populated if they were included in the original tokenization request
for this tokenId.
|
Example
{
"id" : "e8f59d02a466f35a7ece785d3e137e50",
"tokenId" : "JYO7rdR5UjK61111",
"result": {
"code" : "000.000.000",
"description" : "Transaction successful",
},
"card": {
"number": "1234567890123456"
"expiryMonth": "12"
"expiryYear": "2020"
},
"resultDetails": {
"Field1": "Value1",
"Field2": "Value2"
},
"timestamp" : "2018-02-20 12:00:00"
}
Common result codes for de-tokenization requests:
Result code | Description |
---|---|
000.000.000 |
Transaction Succeeded |
800.900.303 |
Token operation error |
100.150.200 |
Token not found |
100.150.202 |
Attempted to detokenize a deactivated token |
900.100.400 |
Token service unavailable |
900.100.600 |
Token server malfunction |
900.100.600 |
Connector/acquirer currently down |
Note
|
Optional fields will only be returned if the request
could be processed (no validation
errors occurred on the fields in the request). The
request result.code must always be evaluated
with the HTTP status code
to determine the overall status of the request.
|
4. P2PE Service
Warning
|
The P2PE Service is not officially supported as of this release and is subject to change. |
4.1. Remote Key Distribution (RKD)
The RKD service distributes cryptographic material (P2PE encryption keys) to terminals.
For RKD Exchange Request messages, use https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdrequest
For RKD Exchange Confirmation Request messages, use https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm
4.1.1. RKD Exchange Request
The minimum requirements for sending an RKD Exchange Request message are listed here:
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
rkdScheme |
Indicates the Remote Key Distribution (RKD) scheme in use. |
Required |
[\s\S]{1,32} |
rkdRequestData |
Data associated with the key request. The field format is dependent on the type of Remote Key Distribution scheme used (the value of rkdScheme). For more information on formatting this field, refer to the respective vendor’s RKD documentation. The field contains binary data encoded as a hex string. |
Required |
AN65535 |
keyStatus |
Indicates the status of the current P2PE key. |
Conditionally required. Depends on the type of Remote Key Distribution scheme used (the value of rkdScheme) |
COMPROMISED| |
deviceName |
An identifiable name for the PED involved in the key exchange. Examples include Ingenico_RBA, Verifone_FORMAGENT, SC5000, and VX810. |
Conditionally required. Depends on the type of Remote Key Distribution scheme used (the value of rkdScheme) |
AN32 |
RKD Exchange Response
The following fields reflect the possible response values for the RKD Exchange Request service.
Parameter name | Description | Required | Regex |
---|---|---|---|
resultDetails.rkdKeyData |
New (encrypted) P2PE key. The field format is dependent on the type of Remote Key Distribution used (the value of rkdScheme in the request message). For more information on formatting this field, refer to the respective vendor’s RKD documentation. The field contains binary data encoded as a hex string. |
Conditional |
AN65535 |
resultDetails.rkdEchoData |
A value that must be sent back by the PED in an RKD confirmation request after applying the new P2PE key. |
Conditional |
AN32 |
See the Standard RKD Exchange Response fields for an extended listing of the possible response parameters ConnectUP can return for this request type.
4.1.2. RKD Exchange Confirmation Request
The minimum requirements for sending an RKD Exchange Confirmation Request message are listed here:
Parameter name | Description | Required | Regex |
---|---|---|---|
Authorization: Bearer <access-token> |
An HTTP header access-token for this request. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
rkdScheme |
Indicates the Remote Key Distribution (RKD) scheme in use. |
Required |
[\s\S]{1,32} |
rkdKeyConfirmationData |
Key confirmation data from the PED after attempting to apply a key supplied in a previous RKD exchange. |
Required |
AN65535 |
rkdEchoData |
The echo data value sent in the RKD exchange response. |
Required |
AN32 |
deviceName |
An identifiable name for the PED involved in the key exchange. Examples include Ingenico_RBA, Verifone_FORMAGENT, SC5000, and VX810. |
Conditionally required. Depends on the type of Remote Key Distribution scheme used (the value of rkdScheme) |
AN32 |
RKD Confirmation Response
See the Standard RKD Exchange Response fields for a listing of the possible response parameters ConnectUP can return for this request type.
4.1.3. Standard RKD Exchange Response
The following fields reflect the possible response values for request
messages sent to either the https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdrequest
or https://[hostname]:[port]/paymentsapi/opp/v1/p2pe/rkdconfirm
resources.
Parameter name | Description | Required | Regex |
---|---|---|---|
id |
The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client. |
Required |
AN32 |
result.code |
The unique code that indicates the result status of the request. |
Required |
AN11 |
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 |
timestamp |
The timestamp generated by the response in UTC. |
Required |
date |
customParameters[name] |
Used to send additional information required for certain transaction scenarios. |
Conditional |
name: AN64 |
resultDetails.* |
A container for name-value pairs used for enriching the response with bank-specific response details. |
Optional |
name: AN64 |
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. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
terminal.terminalId |
Terminal identifier assigned by the acquirer. |
Required |
ANS8 |
terminal.devices[n].id |
The device’s ID. |
Required |
ANS2048 |
terminal.devices[n].capabilities[n].capability |
The device’s capability. |
Required |
ATM| |
merchant.mcc |
Merchant Category Code (MCC) is used to classify the business by the type of goods or services it provides. |
Optional |
N4 |
merchant.street |
The street address and/or name of the merchant. |
Optional |
ANS23 |
merchant.city |
The city of the merchant. |
Optional |
ANS13 |
merchant.state |
The county, state, or region of the merchant. |
Optional |
AN2 |
merchant.country |
The country of the merchant. |
Optional |
AN2 |
terminal.storeId |
Store identifier assigned by the acquirer. |
Optional |
ANS15 |
terminal.devices[n].additionalAttributes[key] |
Additional attributes sent as key-value pairs. |
Optional |
key: AN64 |
terminal.devices[n].hardware.components[n].type |
The type of hardware component used by the device. |
Optional |
ANS2048 |
terminal.devices[n].hardware.components[n].version |
The hardware component version used by the device. |
Optional |
ANS2048 |
terminal.devices[n].hardware.components[n].iss |
The hardware component issue used by the device. |
Optional |
ANS2048 |
terminal.devices[n].hardware.components[n].ass |
The hardware component assembly used by the device. |
Optional |
ANS2048 |
terminal.devices[n].hardware.components[n].effDate |
The hardware component effective date used by the device. |
Optional |
{term_device_hw_cmpnnt__effDate_regex} |
terminal.devices[n].hardware.components[n].expDate |
The hardware component expiry date used by the device. |
Optional |
YYYY-MM-DD |
terminal.devices[n].hardware.components[n].ref |
The hardware component reference used by the device. |
Optional |
ANS2048 |
terminal.devices[n].hardware.manufacturer |
The device’s hardware manufacturer. |
Optional |
ANS2048 |
terminal.devices[n].hardware.manufacturerSerial |
The device’s hardware manufacturing serial number. |
Optional |
ANS2048 |
terminal.devices[n].hardware.serial |
The device’s hardware serial. |
Optional |
ANS2048 |
terminal.devices[n].hardware.series |
The device’s hardware series. |
Optional |
ANS2048 |
terminal.devices[n].hardware.modelName |
The device’s hardware model name. |
Optional |
ANS2048 |
terminal.devices[n].hardware.modelNumber |
The device’s hardware model number. |
Optional |
ANS2048 |
terminal.devices[n].hardware.version |
The device’s hardware version. |
Optional |
ANS2048 |
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 |
terminal.devices[n].hardware.macAddress |
The device’s hardware MAC address. |
Optional |
ANS17 |
terminal.devices[n].hardware.additionalAttributes[key] |
Additional attributes sent as key-value pairs. |
Optional |
key: AN64 |
terminal.devices[n].software.modules[n].component.type |
The software module component type used by the device. |
Optional |
ANS2048 |
terminal.devices[n].software.modules[n].component.version |
The software module component version used by the device. |
Optional |
ANS2048 |
terminal.devices[n].software.modules[n].component.iss |
The software module component issue used by the device. |
Optional |
ANS2048 |
terminal.devices[n].software.modules[n].component.ass |
The software module component assembly used by the device. |
Optional |
ANS2048 |
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 |
terminal.devices[n].software.modules[n].moduleType |
The device’s software module type. |
Optional |
APP|CNTCTLS_KERNEL|EMV_KERNEL| |
terminal.devices[n].software.modules[n].name |
The device’s software module name. |
Optional |
ANS2048 |
terminal.devices[n].software.modules[n].version |
The device’s software module version. |
Optional |
ANS2048 |
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 |
terminal.devices[n].software.modules[n].hash |
The device’s software module hash. |
Optional |
ANS2048 |
terminal.devices[n].software.modules[n].prov |
The device’s software module provision. |
Optional |
ANS2048 |
terminal.devices[n].software.modules[n].minorVersion |
The device’s software module minor version. |
Optional |
ANS2048 |
terminal.devices[n].software.modules[n].majorVersion |
The device’s software module major version. |
Optional |
ANS2048 |
terminal.devices[n].properties[n].name |
The device’s property name. |
Optional |
ANS2048 |
terminal.devices[n].properties[n].value |
The device’s property value. |
Optional |
ANS2048 |
terminal.additionalAttributes[key] |
Additional attributes sent as key-value pairs. |
Optional |
key: AN64 |
customParameters[name] |
Used to send additional information required for certain transaction scenarios. |
Optional |
name: AN64 |
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 |
result.code |
The unique code that indicates the result status of the request. |
Required |
AN11 |
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 |
timestamp |
The timestamp generated by the response in UTC. |
Required |
date |
customParameters[name] |
Used to send additional information required for certain transaction scenarios. |
Optional |
name: AN64 |
resultDetails.* |
A container for name-value pairs used for enriching the response with bank-specific response details. |
Optional |
name: AN64 |
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. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
applePay.paymentToken |
The encrypted payment token provided by Apple. |
Conditionally Required |
ANS8192 |
googlePay.paymentToken |
The encrypted payment token provided by Google. |
Conditionally Required |
ANS8192 |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Required |
ANS15 |
merchant.street |
The street address and/or name of the merchant. |
Optional |
ANS23 |
merchant.city |
The city of the merchant. |
Optional |
ANS13 |
merchant.country |
The country of the merchant. |
Optional |
AN2 |
merchant.state |
The county, state, or region of the merchant. |
Optional |
AN2 |
Example
Example using Apple Pay token
curl http://[hostname]:[port]/opp/v1/apm/decrypt/applepay -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "merchant.street=Century Avenue"
-d "merchant.city=Cape Town"
-d "merchant.country=ZA"
-d "merchant.state=WC"
-d "applePay.paymentToken= {
\"version\": \"EC_v1\",
\"data\": \"pthEHTJcEDAQ4MLi[...]Zw9edDA==\",
\"signature\": \"MIAGCSqGSIb[...]fZWNjL==\",
\"header\": {
\"ephemeralPublicKey\": \"MFkwEwYHKoZIzj0[...]Fku50liog==\",
\"publicKeyHash\": \"sGhAH2fo79Jdp[...]NbSc7wfmGNgDwcXpc=\",
\"transactionId\": \"c5b71840e7fa9374d31d5b560dace7550f47\"
}
}"
Example using Google Pay token
curl http://[hostname]:[port]/opp/v1/apm/decrypt/googlepay -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "pos.terminalId=34056111"
-d "pos.storeId=78919753"
-d "googlePay.paymentToken={
\"signature\":\"MEYCIQCwmJ[...]RWgG8c\",
\"intermediateSigningKey\":{
\"signedKey\":\"{
\"keyValue\":\"MFkwEwYHKo[...]LdekAQ\\u003d\\u003d\",
\"keyExpiration\":\"1585761306143\"
}\",
\"signatures\":[\"MEYCIQDb+L[...]JHwEhF\"]
},
\"protocolVersion\":\"ECv2\",
\"signedMessage\":\"{
\"encryptedMessage\":\"mJVt1VLA[...]prXv3g\\u003d\",
\"ephemeralPublicKey\":\"BK9KRS[...]Wyy9LU\\u003d\",
\"tag\":\"KVHidXy9ur[...]g15Sjw\\u003d\"
}\"
}"
6.1.2. APM Token Decrypt Response
The following fields reflect the possible response values for the APM Token Decrypt service requests.
Parameter name | Description | Required | Regex |
---|---|---|---|
card.numberType |
Indicates if the Apple payment token card number was a PAN or DPAN (device PAN). |
Required |
PAN|DPAN |
card.number |
The Device Primary Account Number (DPAN). |
Required |
N19 |
card.expiryMonth |
The month that the card expires. |
Required |
N2 |
card.expiryYear |
The year that the card expires. |
Required |
N4 |
currency |
Indicates the currency present in the payment token (ISO 4217). |
Required |
A3 |
amount |
Indicates the amount present in the payment token. |
Required |
N8.N4 |
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) |
threeDSecure.eci |
An optional ECI indicator contained within the token. |
Optional |
N2 |
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. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
infoCode |
The code that defines the type of network management needed. |
Required |
SIGN_ON|SIGN_OFF|NEW_KEY|PW_CHANGE|SEC_ALERT|INIT_CUTOFF|ECHO_TEST|CUTOFF_DONE|DEV_AUTH||INIT_ALT_ROUTING|SPEC_INST|FILE_DL|FILE_STATUS|FILE_COMPLETION |
settlementDate |
The month and day for which financial totals are reconciled between the acquirer and the issuer. |
Optional |
N4 |
pos.terminalId |
The terminal identifier assigned by the acquirer. |
Required |
AN8 |
pos.storeId |
The store identifier assigned by the acquirer. |
Optional |
ANS15 |
pos.transactionSequenceNumber |
Identifies the transaction on the device that initiated the transaction. |
Optional |
ANS35 |
pos.terminalOperator |
The terminal operator. |
Optional |
ANS999 |
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 |
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 |
merchant.acquiringInstitutionCode |
A code identifying the financial institution acting as the acquirer of this customer transaction. |
Optional |
AN11 |
merchant.forwardingInstitutionCode |
A code identifying the institution that forwards the transaction in an interchange system en route to the card issuer. |
Optional |
N11 |
emvFileDownload.fileVersion |
Free form field containing the file version information. |
Optional |
ANS99 |
emvFileDownload.blockNumber |
Indicates the block number or offset of the current download. |
Optional |
ANS50 |
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 |
result.code |
The unique code that indicates the result status of the request. |
Required |
AN11 |
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 |
result.authorizationId |
The code assigned by the authorizing institution indicating approval. |
Optional |
AN6 |
emvFileDownload |
Contains information regarding EMV Filed Downloads which can be used to retrieve EMV CA Public Key data. |
Conditional |
ANS9999 |
timestamp |
The timestamp generated by the response in UTC. |
Required |
date |
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 |
emvFileDownload.blockNumber |
Indicates the block number or offset of the current download. |
Optional |
ANS50 |
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 |
emvFileDownload.blockNumber |
Indicates the block number or offset of the current download. |
Optional |
ANS50 |
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 |
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. |
ANS110 |
|
entityId |
The entity associated with the request. |
AN32 |
|
settlementDate |
The month and day for which financial totals are reconciled. Should be in MMDD format. |
Optional |
N4 |
remoteBatchNr |
Used to fetch the aggregate totals for a specific batch from a store. |
Optional |
N10 |
messageType |
The batch message type: |
Required |
A2 |
currency |
The currency code of the settlement amount (ISO 4217). |
Optional |
A3 |
merchant.acquiringInstitutionCode |
A code identifying the financial institution acting as the acquirer of this customer transaction. |
Optional |
AN11 |
terminal.terminalId |
Terminal identifier assigned by the acquirer. |
Optional |
ANS8 |
terminal.storeId |
Store identifier assigned by the acquirer. |
Optional |
ANS15 |
customParameters[name] |
Used to send additional information required for certain transaction scenarios. |
Optional |
name: AN64 |
totals.creditTrans |
The total number of credit transactions, excluding reversals, that have been processed since the most recent settlement transition. |
Optional |
N10 |
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 |
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 |
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 |
totals.transferTrans |
The total number of transfer transactions, excluding reversals, that have been processed since the most recent settlement transition. |
Optional |
N10 |
totals.transferReversalTrans |
The total number of transfer reversal transactions that have been processed since the most recent settlement transition. |
Optional |
N10 |
totals.inquiryTrans |
The total number of inquiries that have been processed since the most recent settlement transition. |
Optional |
N10 |
totals.authTrans |
The total number of authorization transactions that have been processed since the most recent settlement transition. |
Optional |
N10 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
totals.paymentTrans |
The total number of payment transactions that have been processed since the most recent settlement transition. |
Optional |
N10 |
totals.paymentReversalTrans |
The total number of payment reversal transactions that have been processed since the most recent settlement transition. |
Optional |
N10 |
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 |
Example Reconciliation Request (RR)
curl http://[hostname]:[port]/opp/v1/batch -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "messageType=RR"
-d "settlementDate=1020"
-d "remoteBatchNr=12343"
-d "pos.terminalId=34056111"
-d "pos.storeId=78123753"
-d "merchant.acquiringInstitutionCode=12345678901"
Example Reconciliation Notification (RN)
curl http://[hostname]:[port]/opp/v1/batch -v
-H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..."
-d "entityId=b964f0e254a717c1524355a6149b575d"
-d "messageType=RN"
-d "pos.terminalId=34056111"
-d "pos.storeId=78123753"
-d "merchant.acquiringInstitutionCode=12345678901"
-d "totals.creditTrans": "30000",
-d "totals.creditReversalTrans": "30000",
-d "totals.debitTrans": "30000",
-d "totals.debitReversalTrans": "30000",
-d "totals.transferTrans": "333",
-d "totals.transferReversalTrans": "3332",
-d "totals.inquiryTrans": "4444",
-d "totals.authTrans": "30000",
-d "totals.creditProcessingFees": "30000.00",
-d "totals.creditTransactionFees": "23433.00",
-d "totals.debitProcessingFees": "234522.00",
-d "totals.debitTransactionFees": "44200.00",
-d "totals.creditAmount": "2333.00",
-d "totals.creditReversalAmount": "23344.00",
-d "totals.debitAmount": "234355.00",
-d "totals.debitReversalAmount": "2334.00",
-d "totals.netSettlement.indicator": "DEBIT",
-d "totals.netSettlement.amount": "2334.64",
-d "totals.netSettlement.paymentTrans": "2334",
-d "totals.netSettlement.paymentReversalTrans": "2334"
8.1.2. Batch Management Response
The following fields reflect the possible response values returned for a Batch Management request message.
Parameter name | Description | Required | Regex |
---|---|---|---|
id |
The identifier of the request that can be used to reference the transaction later. This value must be persisted by the client when the response is processed by the client. |
Always |
AN32 |
result.code |
The unique code that indicates the result status of the request. |
Required |
AN11 |
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 |
result.remoteBatchNr |
Contains the aggregate totals form a specific batch from a store. |
Optional |
N10 |
result.settlementDate |
The month and day for which financial totals are reconciled. Should be in MMDD format. |
Optional |
N4 |
timestamp |
The timestamp generated by the response in UTC. |
Required |
date |
customParameters[name] |
Used to send additional information required for certain transaction scenarios. |
Optional |
name: AN64 |
settlementCode |
Indicates the result of a reconciliation. |
Optional |
UNKNOWN|IN_BALANCE|OUT_OF_BALANCE|ERROR" |
totals.creditTrans |
The total number of credit transactions, excluding reversals, that have been processed since the most recent settlement transition. |
Optional |
N10 |
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 |
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 |
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 |
totals.transferTrans |
The total number of transfer transactions, excluding reversals, that have been processed since the most recent settlement transition. |
Optional |
N10 |
totals.transferReversalTrans |
The total number of transfer reversal transactions that have been processed since the most recent settlement transition. |
Optional |
N10 |
totals.inquiryTrans |
The total number of inquiries that have been processed since the most recent settlement transition. |
Optional |
N10 |
totals.authTrans |
The total number of authorization transactions that have been processed since the most recent settlement transition. |
Optional |
N10 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
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 |
totals.paymentTrans |
The total number of payment transactions that have been processed since the most recent settlement transition. |
Optional |
N10 |
totals.paymentReversalTrans |
The total number of payment reversal transactions that have been processed since the most recent settlement transition. |
Optional |
N10 |
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 |
Example
{
"id": "d79db48246884c0e82fc404bb518b4aa",
"result": {
"code": "000.000.000",
"description": "Transaction succeeded",
"remoteBatchNr": "2344",
"settlementDate": "1224"
},
"timestamp": "2024-03-07 18:39:54",
"resultDetails": {
"iso8583ResponseCode": "00"
},
"settlementCode": "IN_BALANCE",
"totals": {
"creditTrans": "30000",
"debitTrans": "30000",
"debitReversalTrans": "30000",
"transferTrans": "333",
"transferReversalTrans": "3332",
"inquiryTrans": "4444",
"authTrans": "30000",
"creditProcessingFees": "30000.00",
"creditTransactionFees": "23433.00",
"debitProcessingFees": "234522.00",
"debitTransactionFees": "44200.00",
"creditAmount": "2333.00",
"creditReversalAmount": "23344.00",
"debitAmount": "234355.00",
"debitReversalAmount": "2334.00",
"netSettlement": {
"indicator": "CREDIT",
"amount": "233.00"
},
"paymentTrans": "22222234",
"paymentReversalTrans": "2222"
}
}
Note
|
Optional fields will only be returned if the
request could be processed (no validation errors
occurred on the fields in the request). The
request result.code must always be evaluated
with the HTTP status code
to determine the overall status of the request.
|
Appendix A: Format Element Descriptions
A.1. Format Explanation
Format element | Description |
---|---|
A |
Alphabetic characters, A through Z, and a through z |
N |
Numeric digits, 0 through 9 |
S |
Special characters, including the ASCII printable characters (character codes 32-127) and the extended ASCII codes (character codes 128-255) |
AN |
Alphabetic and numeric characters |
AS |
Alphabetic and special characters |
NS |
Numeric and special characters |
ANS |
Alphabetic, numeric, and special characters |
YY |
Year, 00 through 99 |
MM |
Month, 01 through 12 |
DD |
Day, 01 through 31 |
Appendix B: Result Code Explanation
B.1. Result Codes
Result codes are part of the response body’s JSON (field result) containing a code and a description explaining the code.
A result code has the format ddd.ddd.ddd
, that is, 3
groups of 3-digit numbers. The codes are split into
rough groups by the first number, then into more
detailed sub-groups by the second number, then into
the exact code by the third number.
Example:
800.100.153
means:
800: bank declined 100: it declined the authorization 153: it declined authorization because the CVV is wrong
The currently supported result codes are listed below.
Result Code | Result Description | Special Notes |
---|---|---|
000.000.000 |
Transaction succeeded |
|
000.000.099 |
Transaction Succeeded (partial approval) |
|
000.100.201 |
Account or Bank Details Incorrect |
|
000.100.206 |
Revocation or Dispute |
|
000.100.220 |
Fraudulent Transaction |
|
000.200.000 |
Transaction pending |
|
100.100.101 |
Invalid credit card, bank account number, or bank name |
|
100.100.305 |
Invalid expiration date format |
|
100.150.200 |
Registration does not exist |
|
100.150.202 |
Registration is already deregistered |
|
100.300.501 |
Invalid response ID |
|
100.300.600 |
Invalid or missing user login |
|
100.396.101 |
Cancelled by user |
|
100.396.106 |
User did not agree to payment method terms |
|
100.550.401 |
Invalid currency |
|
100.800.501 |
Invalid country |
|
200.100.501 |
Invalid or missing customer |
|
200.100.603 |
Alternative payment method token (ApplePay/GooglePay) could not be decrypted Cryptographic configuration might be outdated. |
|
200.200.106 |
Duplicate transaction. Please verify that the UUID is unique. |
|
200.300.404 |
Invalid or missing parameter |
|
300.100.100 |
Transaction declined (additional customer authentication required) |
|
300.100.190 |
Transaction declined (Issuer Requires PIN [SCA]) |
|
300.100.191 |
Transaction declined (SCA exemption is invalid) |
|
300.100.192 |
Transaction declined (additional customer authentication required) |
|
500.100.401 |
Connector is unavailable (no processing possible) |
|
600.100.100 |
Unexpected Integrator Error (Request could not be processed) |
|
600.200.400 |
Unsupported Payment Type |
|
600.200.500 |
Invalid payment data. You are not configured for this currency or sub-type (country or brand). |
|
700.100.200 |
Non-matching reference amount |
|
800.100.100 |
Transaction declined for unknown reason |
|
800.100.151 |
Transaction declined (invalid card) |
|
800.100.153 |
Transaction declined (invalid CVV) |
|
800.100.154 |
Transaction declined (transaction marked as invalid) |
|
800.100.155 |
Transaction declined (amount exceeds credit) |
|
800.100.156 |
Transaction declined (format error) |
|
800.100.157 |
Transaction declined (wrong expiry date) |
|
800.100.159 |
Transaction declined (stolen card) |
|
800.100.160 |
Transaction declined (card blocked) |
|
800.100.161 |
Transaction declined (too many invalid tries) |
|
800.100.162 |
Transaction declined (limit exceeded) |
|
800.100.163 |
Transaction declined (maximum transaction frequency exceeded) |
|
800.100.165 |
Transaction declined (card lost) |
|
800.100.166 |
Transaction declined (incorrect personal identification number) |
|
800.100.167 |
Transaction declined (referencing transaction does not match) |
|
800.100.168 |
Transaction declined (restricted card) |
|
800.100.170 |
Transaction declined (transaction not permitted) |
|
800.100.174 |
Transaction declined (invalid amount) |
|
800.100.178 |
Transaction declined (PIN entered incorrectly too many times) |
|
800.100.190 |
Transaction declined (invalid configuration data) |
|
800.100.199 |
Transaction declined (routing error) |
|
800.100.402 |
CC/bank account holder not valid |
|
800.900.303 |
No token created |
|
800.800.800 |
The payment system is currently unavailable, please contact support in case this happens again. |
|
900.100.300 |
Timeout, uncertain result |
Send a Reversal to reverse the request |
900.100.400 |
Timeout at the connectors/acquirer side |
|
900.100.600 |
Connector/acquirer currently down |
|
999.999.999 |
Undefined connector/acquirer error |
Tip
|
For a categorized list of result codes, refer to the OPP Result Codes page. |
B.2. HTTP Response Status Codes
The HTTP response status code are issued by the upstream server in response to a client request.
Tip
|
The request result.code must always be evaluated
with the HTTP status code to determine the overall status
of the request.
|
HTTP Status Code | Description |
---|---|
200 OK |
This is the standard response for a successful request. Check
the |
400 Declined / Bad Request |
This means that the server cannot process the request. This might
either point to invalid field values or processing/connectivity
failures. It is also returned if the payment failed, for example, because
the acquirer declined the request. Check the |
403 Auth Error / Forbidden |
This means that the request contained valid data, but the server is refusing action. This usually means incorrect authentication information was provided. One or more of the authentication parameters are incorrect or not supplied. It is also returned if the user has been disabled on the system. |
9. ConnectUP OpenAPI Specification
Current publication date: 2024-04-15
The ConnectUP OpenAPI specification(OAS) fully describes all available ConnectUP RESTful APIs. The specification is programming language agnostic and enables third-party users to interact, understand and develop against the ConnectUP API with minimal implementation logic. The specification adheres to OAS version 3.0.3 and is published in the YAML file format. The latest version of the specification may be downloaded from the link below.
10. Publication history
Current publication date: 2024-04-15
Version 1.x
Warning
|
Currently unsupported features subject to change |
P2PE Service
-
Added the P2PE Service
Alternative Card Data
-
Added P2PE Cardholder Data input
VP2PE Service
-
Added the VP2PE Service
Version 1.41
-
Added new pos.terminalRestrictions field to basic payment requests.
-
Added new fleet response field fleet.hostBasedPurchaseRestriction
10.1. Version 1.40
Fleet Field Updates
-
Fleet fields length updates.
-
New Fleet prompt cashBackAmount
-
New Fleet prompt customerData1
-
New Fleet prompt customerData2
-
New Fleet prompt siteTransactionNumber
Version 1.39
Batch Management Service
-
Added the Batch Management Service
Version 1.38
serviceRestrictionCode and card.track1Data Support
-
serviceRestrictionCode and card.track1Data fields are now supported on all payment transactions.
Version 1.37
incrementalAuthorization support
-
An incrementalAuth field is now supported for PA, RR and RV payment transactions.
-
The incrementalAuth field contains subfields to construct incremental auth related indicators and amounts.
Version 1.36
deferredAuthorization flag support
-
A deferredAuthorization field is now supported for PA, CP and DB payment transactions.
Version 1.35
fleet.prompts[n].userId format update
-
Field fleet.prompts[n].userId now supports spaces
Version 1.34
memoPost flag support
-
A memoPost field is now supported for payment transactions
Version 1.33
customParameters field formatting
-
customParameter keys now support spaces
10.2. Version 1.32
Payment Service
-
Added new Payment Type CA: Credit Adjustment.
-
Payment Type RF (Refund) is now deprecated and replaced by CA (Credit Adjustment).
-
Added several new sub-fields to the merchant field.
Version 1.31
threeDSecure.ucafCollectionIndicator support
-
Introducing new field threeDSecure.ucafCollectionIndicator.
-
Also applied multiple updates to the threeDSecure field.
Version 1.30
Payment Service
-
Clarified the definition of the merchant street field.
-
Added support for the
reason
field value COMPLETED_PARTIALLY.
Version 1.29
Payment Service
-
Added support for specifying the to account type for cards for CP messages.
-
Added support for the
reason
field for CP messages. -
Added new field
pos.localDateTime
for CP messages.-
pos.localDateTime
is now returned on all payment response messages.
-
-
Added support for the following new POS fields in request messages:
-
pos.cardDataInputMode
-
pos.terminalOutputCapability
-
Version 1.28
-
Listed merchant.mcc under the field definitions for Device Data Request and Bill Payments.
-
Changed the format of Network Management Request field pos.terminalOperator from a set of values to any string value.
-
Elaborating on the definition for special characters.
Version 1.27
-
balances.ledgerBalance and balances.availableBalance are now returned on all payments responses.
-
additionalAmounts.approvedAmount are now returned on all payments responses.
Version 1.26
TAVV Support
-
Separating CAVV and TAVV values by introducing a new threeDSecure.tavv field.
Version 1.25
Card Verification support. availableBalance in BI response messages
-
Card Verification (CV message) support. Added support for balances.ledgerBalance in BI response messages.
Version 1.24
availableBalance in DB response messages
-
Added support for balances.availableBalance and new field balances.approvedAmount in DB response messages.
Version 1.23
Presto P2PE support
-
Added support for Presto P2PE
CP Status Code
-
Added support for a statusCode parameter for CP messages.
Version 1.22
EMV File Download support
-
Added support for EMV File Download messages
Version 1.21
Basic Fuel Support
-
Added base support for fuel and fleet transactions
Version 1.20
Network Management Service
-
Added the Network Management Service
Version 1.19
De-tokenization Service
-
Added support for AES-256 encrypting de-tokenize response messages
Version 1.18
Payments and ICC Result Service
-
Added support for the following fields:
-
card.paymentIdentifier
-
paymentAccountReference
-
-
Added the following values to the
standingInstruction.industryPractice
field:-
INCREMENTAL_AUTH
-
RESUBMISSION
-
REAUTHORIZATION
-
NO_SHOW
-
Version 1.17
Payments and ICC Result Service
-
Added support for the Google Pay APM
-
Added support for the following values to the pos.entryMode field to indicate that fallback from one PAN entry mode to another has occurred:
-
MAGSTRIPE_AS_FALLBACK
-
MAGSTRIPE_TO_MANUAL
-
CONTACTLESS_TO_ICC
-
CONTACTLESS_TO_MAGSTRIPE
-
-
Added the
pos.fallbackReason
field to indicate why fallback from onepos.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), andRC
(Recurring) values in thetransactionCategory
field in payment request messages. Specifying these values will result in the request being rejected. Set the newbillPayment
field to true to indicate that the transaction is a bill payment. Continue using theCRENDENTIAL_ON_FILE
pos.entryMode
value in combination with thestandingInstruction
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 relatedentityId
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
inRV
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
andresultDetails.level3InterchangeEligible
fields in response messages -
Added support for raw host network response values
resultDetails.AcquirerResponse
andresultDetails.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
, andstandingInstruction.source
in requests to support Customer-Initiated Transactions (CIT) and Merchant-Initiated Transactions (MIT) functionality -
Added support for value
'CREDENTIAL_ON_FILE'
in fieldpos.entryMode
-
Added the
resultDetails[]
field to responses and added back support for thecustomParameters[]
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 fieldreferencedPaymentId
conditional) -
Added support for
pos.operatorId
,pos.posId
, andpos.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
andpos.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.