openapi: 3.0.3 info: title: ConnectUP API Interface Specification description: | # Introduction ConnectUP is a RESTful web API that exposes various payments-related services. This API is documented in **OpenAPI format**. # Authentication ConnectUP utilizes a secure authentication mechanism that combines a bearer token and entityID to verify incoming requests. When requesting new user credentials from ACI, the access-token and its corresponding entityID are included. version: 1.0.5 servers: - url: '{protocol}://{hostname}:{port}/paymentsapi' variables: protocol: enum: - http - https default: http hostname: enum: - localhost - api.aciworldwide.com - api.uat.aciworldwide.com - api.ist.aciworldwide.com default: localhost port: enum: - '443' - '8443' - '80' - '8080' default: '8080' tags: - name: Remote Key Distribution description: >- The RKD service distributes cryptographic material (P2PE encryption keys) to terminals. - name: Tokenization description: The Tokenization service creates a token based on card data and retrieves card data based on a token. - name: APM Decryption description: >- 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. - name: Payments Service description: >- The Payments service performs payments and runs other payment-related operations. - name: Network Management description: This service is used for network management operations. - name: Appendix A- Format Element Descriptions description: >-
Format 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
- name: Appendix B- Result/Response Code Explanation description: >- B1.Result Code Explanation

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
B.2. HTTP Response Status Codes
The HTTP response status code are issued by the upstream server in response to a client request.
HTTP Status Code Description
200 OK
This is the standard response for a successful request. Check the result.code and result.description response fields for the reason the request succeeded.
400 Declined / Bad Request
This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed.
403 Auth Error / Forbidden
This means that the request contained valid data, but the server is refusing action. This usually means incorrect authentication information was provided. One or more of the authentication parameters are incorrect or not supplied. It is also returned if the user has been disabled on the system.
x-tagGroups: - name: Services tags: - Payments Service - Network Management - Tokenization - APM Decryption - Remote Key Distribution - name: Appendixes tags: - Appendix A- Format Element Descriptions - Appendix B- Result/Response Code Explanation paths: /opp/v1/payment: post: security: - bearer: [] tags: - Payments Service summary: Basic Payment description: ConnectUP's payments service is responsible for handling various payment-related operations and transactions. It provides a set of functionalities that enable users to initiate payments and process transactions. operationId: processPaymentRequest requestBody: content: application/json: schema: $ref: '#/components/schemas/PaymentRequest' examples: Authorization Bearer Token: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: PA amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: |- ### Authorization Bearer Token To align with authentication changes to the Open Payment Platform API specification, support for the new ***Authorization: Bearer *** 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. The now deprecated authentication.* fields can still be used in requests but cannot be combined with the ***Authorization*** header and related ***entityId*** field. If these fields are combined in any way, authentication will fail. Existing clients that wish to use the new authentication fields can: 1) Construct the token themselves as described above. 2) Request new user credentials from ACI, which will include the access-token. PA - Pre-Auth: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: PA amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### 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. Specialized payment Use cases will require additional fields. DB - Debit: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### 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. Specialized payment use cases will require additional fields. CD - Credit: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: CD amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### 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. Specialized payment use cases will require additional fields. CP - Capture: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: CP amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### 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. Specialized payment use cases will require additional fields. RV - Reversal: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: RV amount: '21.00' pos: terminalId: '12345678' referencedPaymentId: PA|DB|CD or CP tranID description: >- ### Reversal This payment operation reverses an already processed Pre-Authorization, Debit, 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. See the *Reversals using referencedMerchantTransactionId* example for cases where a referencedPaymentId value is not available. The minimum requirements for sending a RV message are listed. Specialized payment use cases will require additional fields. CV - Card Verification: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: CV merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" cvv: "123" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### Card Verification Request 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. CA - Credit Adjustment: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: CA amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### 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 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 ***CA*** message are listed. Specialized payment use cases will require additional fields. 3-D Secure: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' card: track2Data: 5416389123456786D22021010000081315000 pos: terminalId: '12195611' storeId: '78123753' entryMode: MAGSTRIPE merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 threeDSecure: xid: VGhpcyBpcyBhIHNhbXBsZSB4aWQ= verificationId: c2FtZSBhcyBvdGhlciB2YWx1ZXM= ucafCollectionIndicator: 3 tavv: c2FtZSBhcyBvdGhlciB2YWx1ZXM= eci: '05' dsTransactionId: c5b808e7-1de1-4069-a17b-f70d3b3b1645 version: 2.0.0 authenticationMethod: '0' description: >- ### 3-D Secure 3-D Secure (3DS) is compatible with the following message types: * Pre-Authorization Request * Debit Request * Capture Notification ConnectUP supports sending transactions that have already been authenticated by a third-party 3-D Secure version 2 provider. In this scenario, ConnectUP will send the authentication data obtained from the third-party provider to complete the 3-D Secure authorization flow. Only 3-D Secure version 2 is currently supported. The minimum requirements for sending 3DS are listed. Account Type: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" accountType: CREDIT pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### Account Type Account Type is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification 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. Additional POS Data: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: track2Data: 5416389123456786D22021010000081315000 pos: storeId: '78123753' terminalId: '12195611' entryMode: MAGSTRIPE terminalType: ADMIN operatorId: '123321' posId: '98778912' transactionSequenceNumber: '66611234' description: >- ### Additional POS Data Additional POS Details compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification Manual Card Data: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" cvv: "1234" sequenceNumber: "123" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### Manual Card Data Any message within the Payment Service or Token Service can accept card information in in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. ConnectUP supports transactions using the card details available on the physical card. For this, the fields listed here are available in the request: ***Manual Card Data*** is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification Magnetic Stripe Data: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MAGSTRIPE description: >- ### Magnetic Stripe Data Any message within the Payment Service or Token Service can accept card information in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. ***Magstripe Card Data*** is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification ICC Data: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: track2Data: 2222222222333333333=2025201 pos: storeId: '78123753' terminalId: '12195611' entryMode: ICC cardDataInputCapability: MAGSTRIPE_ICC cardDataOutputCapability: ICC cardholderAuthenticationCapability: PIN cardholderAuthenticationMethod: PIN iccDataRequest: >- 9F3303E0F0C89F03060000000000009F02060000000101008407A000000003101082025C009F260891927070405962B15F2A0207109F1A0207109C01009A031406279F100706010A03A00000950500800088009F3704ECB178479F3602028C67010F description: >- ### Integrated Circuit Chip (ICC) Data Any message within the Payment Service or Token Service can accept card information in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. ***Integrated Circuit Chip (ICC) Data*** is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification Token Card Data: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' tokenId: Tj9e10lduQiVm7 merchantTransactionId: 5a6149b575d60db9aa7ef667e8f09898 pos: storeId: '78123753' terminalId: '12195611' entryMode: UNKNOWN description: >- ### Token Card Data Any message within the Payment Service or Token Service can accept card information in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. **Token Card Data is compatible with the following message types**: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Balance Inquiry Apple Pay Encrypted Payment Token: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 currency: USD pos: storeId: '78123753' terminalId: '12195611' paymentBrand: APPLEPAY applePay: paymentToken: APPLEPAY_TOKEN description: >- ### Apple Pay Data Any message within the Payment Service or Token Service can accept card information in in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. Apple Pay Data is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. Apple Pay is not supported in China. Apple Pay Pre-Decrypted Payment Token Fields: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 currency: USD card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL paymentBrand: APPLEPAY threeDSecure: verificationId: c2FtZSBhcyBvdGhlciB2YWx1ZXM= tavv: c2FtZSBhcyBvdGhlciB2YWx1ZXM= eci: '05' description: >- ### Apple Pay Data Any message within the Payment Service or Token Service can accept card information in in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. Apple Pay Data is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. Apple Pay is not supported in China. Google Pay Encrypted Payment Token: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 currency: USD pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL paymentBrand: GOOGLEPAY googlePay: paymentToken: googlePay_TOKEN description: >- ### Google Pay Any message within the Payment Service or Token Service can accept card information in in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. Google Pay is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. Google PayPre-Decrypted Payment Token Fields: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 currency: USD card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL paymentBrand: GOOGLEPAY threeDSecure: verificationId: c2FtZSBhcyBvdGhlciB2YWx1ZXM= tavv: c2FtZSBhcyBvdGhlciB2YWx1ZXM= eci: '05' xid: VGhpcyBpcyBhIHNhbXBsZSB4aWQ= description: >- ### Google Pay Any message within the Payment Service or Token Service can accept card information in in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. Google Pay is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. (P2PE) Card Data: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL p2peEncrypted: type: INGENICO_ONGUARD ksn: FFFF98765400020002280500060000 sensitiveData: '2805000600003031313030364e47' persistableData: '41303854133380862400453030.' volatileData: 3040431234f354130385410 tlvMapping: '57': B DFDB02: B 5A: B 9F6B: B description: >- ### Point-to-Point-Encryption (P2PE) Card Data ***WARNING*** Currently unsupported feature subject to change ***WARNING*** Any message within the Payment Service or Token Service can accept card information in in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. Point-to-Point-Encryption (P2PE) Card Data is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. Payment Identifier: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: paymentIdentifier: 0123456789abcdefghiJKLMNOPQR number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### Payment Identifier Any message within the Payment Service or Token Service can accept card information in in various formats. Should more than one of these input formats be sent in the same request, ConnectUP will attempt to process all card data. ***Payment Identifier*** is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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 CVV/CID: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: cvv: '999' number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### Card Verification Value / Card ID (CVV/CID) Card Verification Value/Card ID (CVV/CID) is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request 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. CVV2 Availability: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL cvv2Availability: ILLEGIBLE description: >- ### CVV2 Availability CVV2 Availability is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. Encrypted Pin: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL encryptedPin: data: A3929E6A25E8E32C ksn: FFFF12345612342000 description: |- ### Encrypted Pin Encrypted Pin is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request Alternative Currency: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '75.00' currency: ZAR merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: track2Data: 5416389123456786D22021010000081315000 pos: storeId: '78123753' terminalId: '12195611' entryMode: MAGSTRIPE description: >- ### Alternative Currency Alternative Currency is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. 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. Address Verification System: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL billing: street1: Estuaries Avenue houseNumber1: Century City Building A postcode: 7441 city: CapeTown state: WC country: SA description: >- ### Address Verification System Address Verification System is compatible with the following message types: * Pre-Authorization Request * Debit Request * Capture Notification Billing Contact: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL billing: street1: Estuaries Avenue street2: Estuaries Avenue2 houseNumber1: Century City Building A postcode: 7441 city: CapeTown state: WC country: ZA from: street1: The Retailer Industrial Park street2: 12 West Street houseNumber1: 1 postcode: 7500 city: Cape Town state: WC country: ZA description: >- ### Billing Contact Billing Contact is compatible with the following message types: * Pre-Authorization Request * Capture Notification To specify the contact details of the bill payer or bill payee, use the following fields. The billing.* fields must be used for the customer who is paying the bill, and the billing.from.* fields must be used for the merchant/retailer which issued the customer with the bill. Bill Payments: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL merchant: mcc: 1234 street: Century Avenue city: Cape Town country: ZA state: WC name: ACI Canteen postcode: '7441' phone: '2721522500' submerchantId: '112233445566789' recievingInstitutionCode: '48265712347' billPayment: 'true' description: >- ### Bill Payments Bill Payments is compatible with the following message types: * Pre-Authorization Request * Debit Request * Capture Notification Bill Payments require that the ***billPayment*** field be set. The merchant (payee) data must also be provided. Optionally, the ***merchant.submerchantId*** field can be specified if a payment facilitator arrangement is in place between a merchant and a sub-merchant. Cashback: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '121.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL cashbackAmount: '21.00' description: >- ### Cashback Cashback is compatible with the following message types: * Pre-Authorization Request * Debit Request * Capture Notification Cashback refers to the money that is paid back to a customer after a transaction has been completed. ConnectUP supports specifying a cashback amount in requests. The cashbackAmount is the cash amount intended to be withdrawn at the point-of-sale (POS). The cashbackAmount amount must be included in the amount field. ConnectUP does not perform any calculations to ensure this. Convenience Fee: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL convenienceFee: '0.50' description: |- ### Convenience Fee Convenience Fee is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification 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. The ***convenienceFee*** amount must be included in the ***amount*** field. ConnectUP does not perform any calculations to ensure this. Custom Parameters: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL customParameters: MYKEY1: MYvalue1 MYKEY2: MYvalue2 description: >- ### Custom Parameters Custom Parameters is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. Debt Repayment: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL debtRepayment: 'true' description: >- ### Debt Repayment Debt Repayment is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. Deferred Payment: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL deferredPayment: 'true' description: >- ### Deferred Payment Deferred Payment is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification To indicate that a transaction is a deferred payment, add the ***deferredPayment*** field to the request. ***Currently, this feature cannot be combined with CIT/MIT transactions.*** Delayed Charges: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL standingInstruction: industryPractice: DELAYED_CHARGES source: MIT mode: INITIAL description: >- ### Delayed Charges Delayed Charges is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification EmvFileDownload: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: CONTACTLESS_TO_ICC emvFileDownload: fileVersion: 'OldFile1.0' description: >- ### EmvFileDownload EmvFileDownload is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification Fallback: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: CONTACTLESS_TO_ICC fallbackReason: NO_SUPPORTED_APPLICATION description: >- ### Fallback Fallback is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. L2/L3: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 merchantOrderNumber: '123456' card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" commercialCardType: "MC" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL customer: orderNumber: '8423794' customerCode: '8423794' taxExempt: 'false' merchant: taxId: '8423794' vatNr: '6664446646' refNr: '7774447747' invoiceDiscountTreatment: '3' taxTreatment: '2' streetAddress: 'Century Avenue, Century City, Cape Town, 7441' countrySubDivisionCode: '123' url: 'https://www.mymerchantsite.com/' customerServicePhoneNumber: '2721522500' additionalContactInformation: 'Contact Name: Sven Blackbeard' partnerIdCode: '665544' serviceLocationCityName: 'Century City' serviceLocationCountrySubdivisionCode: '655' serviceLocationCountryCode: 'ZA' serviceLocationPostalCode: '7441' totalShippingAmount: '0.00' totalDutyAmount: '15.00' totalDiscountAmount: '15.00' shippingAmountSign: 'D' discountAmountSign: 'D' dutyAmountSign: 'D' commodityCode: 'CC5456456456' taxCollected: 'Y' taxAmounts: '0': taxType: UNKNOWN taxDescription: State GS totalTaxAmount: '1.50' tax: 00.10 taxId": us_taxes itemizedDiscounts: '0': amount: '156.46' rate: '57' discountCode: 'j857684576846' cart: items: '0': description: This item is nice. number: 858 customerCode: 858 vatReferenceNr: 64545645456454221 merchantItemId: genericItemId quantity: '1' unitOfMeasure: lbs totalAmount: '15.00' totalAmountType: NET totalAmountSign: C sku: '11125455' price: '15.00' discountAmount: '1.50' discountAmountSign: 'C' invoiceDiscountTreatment: '8' lineItemDetailIndicator: '9' discount: '00010' supplyType: '10' taxAmounts: '0': taxType: FEDERAL_NATIONAL_SALES taxDescription: State TX totalTaxAmount: '1.50' tax": 00.10 taxId": us_taxes itemizedDiscounts: '0': amount: '156.46' rate: '57' discountCode: 'j857684576846' description: >- ### Level 2 and Level 3 Data (L2/L3) Level 2 and Level 3 Data (L2/L3) is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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 = "100.00" cart.items[0].itemizedDiscounts[0].amount = "100.00" ```` 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. 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. Fleet: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" commercialCardType: "MC" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL fleet: oilBrandName: 9988 serviceType: 3 vehicleUsage: B odometer: 11227788 vehicleReg: VREG543377FFGG444 driverId: 11147741 promptCode: 6 restrictionCode: 1 privateData: Private Data 123 purchaseType: B prompts: '0': userId: UID5656MFNNNFF7 vehicleId: VID88558HB driverLicense: DL666HHAAFFT customerData: CD55444IIIUUDDD jobId: JOBID55555666D3 contractNumber: CNUMBER888FRT664AADF PIN: 885125 tripNumber: TRIP NUMBER 123 unitNumber: FLEETUNIT5 trailerId: TRAILER ID 12 trailerHours: 000008 maintenanceId: MAINTID12312312 hubometer: 000000009 employeeNumber: 666 driverLicenseState: CA vehicleLicense: VEHLIC123 vehicleLicenseState: CW trailerLicense: TL555 trailerLicenseState: CR fleetId: FID123 customData: THIS IS CUSTOM DATA vehicleTag: VEHTAG177 driverLicenseLocation: CAQ driverLicenseName: This is my name driverDateOfBirth: 19850212 vehicleVINNumber: VINNUM12366 pumpNumber: PUMPNUM3 tractorNumber: TRACT5554433546 '1': userId: UID44886655JJYH vehicleId: VID66653GH department: DEP6664hgggtt44 fleetBatchDataList: '0': batchDate: 20210607 transactionCount: 0000001112 total: 00000111155544 totalUnit: Liters '1': batchDate: 20210809 transactionCount: 0000001113 total: 000007775354 totalUnit: Gallons description: >- ### Fleet Data Fleet Data is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification ConnectUP supports sending fleet data. All fleet data fields are optional. When sending fleet data, ***fleet.prompts*** and ***fleetBatchDataList*** must be specified using an indexed-number [n], starting with 0. For example: ```` fleet.prompts[0].userId = "UID5656MFNNNFF7" ```` Linked Capture: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: CP amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL referencedPaymentId: e8f59d02a466f35a7ece785d3e137e50 description: >- ### Linked Capture Linked Capture is compatible with the following message type: * Capture Notification A linked capture notification (CP) enables a merchant to capture a previously submitted pre-authorization message by providing the ***id*** of the original authorization in the linked capture request. #### Example An example scenario follows: * An initial ***PA*** request is submitted for the transaction. * At the end of a business period, the original PA is captured by referencing its ***id*** in the ***referencedPaymentId*** field for the ***CP*** message. ##### Initial Pre-Authorization Request ```` curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..." -d "entityId=b964f0e254a717c1524355a6149b575d" -d "paymentType=PA" -d "card.number=4444444444444448" -d "card.expiryMonth=05" -d "card.expiryYear=2050" -d "amount=46.00" -d "pos.terminalId=34056111" -d "pos.storeId=78119753" -d "pos.entryMode=MANUAL" ```` ##### Pre-Authorization Response ```` { "id" : "e8f59d02a466f35a7ece785d3e137e50", "amount" : "46.00", "currency" : "USD", "result": { "code" : "000.000.000", "description" : "Transaction succeeded", "authorizationId" : "783276" }, "timestamp" : "2019-09-06 12:22:44" } ```` #### Linked Capture Request using referencedPaymentId ```` curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..." -d "entityId=b964f0e254a717c1524355a6149b575d" -d "paymentType=CP" -d "card.number=4444444444444448" -d "card.expiryMonth=05" -d "card.expiryYear=2050" -d "amount=46.00" -d "authorizationId=783276" -d "pos.terminalId=34056111" -d "pos.storeId=78119753" -d "pos.entryMode=MANUAL" -d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50" -d "statusCode=SUCCESSFUL" -d "memoPost=true" ```` MIT: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL standingInstruction: mode: REPEATED source: MIT type: RECURRING description: >- ### Merchant-Initiated Transaction (MIT) Merchant-Initiated Transaction (MIT)/Customer-Initiated Transaction (CIT) is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification ConnectUP supports sending the following MIT transactions: | Initiated transaction type | Required parameters | | ----------- | ----------- | | **MIT Unscheduled Transaction**
(The merchant using a stored credential as needed.) | * Set *pos.entryMode* set to *CREDENTIAL_ON_FILE*.
* Set *standingInstruction.type* to *UNSCHEDULED*.
* Set *standingInstruction.mode* to *INITIAL*.
* Set *standingInstruction.source* to *MIT*.
* Provide the saved bank-specific fields in the request *customParameters* field. | | **MIT First Recurring Transaction**
(The merchant initiating a series of recurring transactions.) | * Set *pos.entryMode* to *CREDENTIAL_ON_FILE* .
* Set *standingInstruction.type* to *RECURRING*.
* Set *standingInstruction.mode* to *INITIAL*.
* Set *standingInstruction.source* to *MIT*.
* Provide the saved bank-specific fields in the request *customParameters* field. | | **MIT first recurring installment transaction**
(The merchant initiating a series of recurring installment transactions.) | * Set *pos.entryMode* to *CREDENTIAL_ON_FILE* .
* Set *standingInstruction.type* to *INSTALLMENT*.
* Set *standingInstruction.mode* to *INITIAL*.
* Set *standingInstruction.source* to *MIT*.
* Provide the saved bank-specific fields in the request *customParameters* fields. | | **Industry practice of Delayed Charges** | * Set *pos.entryMode* to *CREDENTIAL_ON_FILE* .
* Set *standingInstruction.source* to *MIT*.
* Set *standingInstruction.industryPractice* to *DELAYED_CHARGES*. | CIT: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL standingInstruction: mode: INITIAL source: CIT description: >- ### Customer-Initiated Transaction (CIT) Customer-Initiated Transaction (CIT) is compatible with the following message types: * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification ConnectUP supports sending the following CIT transactions: | Initiated transaction type | Required parameters | | ----------- | ----------- | | **CIT First Transaction**
(The cardholder is storing a credential for a subsequent transaction.) | * Set *pos.entryMode* to any value other than *CREDENTIAL_ON_FILE*.
* Set *standingInstruction.mode* to *INITIAL*.
* Set *standingInstruction.source* to *CIT*.
* Save the bank-specific fields in the *resultDetails* response for future use. | | **CIT First Recurring Transaction**
(The cardholder is storing a credential for a subsequent transaction.) | * Set *pos.entryMode* to any value other than *CREDENTIAL_ON_FILE*.
* Set *standingInstruction.type* to *RECURRING*.
* Set *standingInstruction.mode* to *INITIAL*.
* Set *standingInstruction.source* to *CIT*.
* Save the bank-specific fields in the *resultDetails* response for future use. | | **CIT First Recurring Installment Transaction**
(The cardholder is storing a credential for a series of recurring installment transactions.) | * Set *pos.entryMode* to any value other than *CREDENTIAL_ON_FILE*.
* Set *standingInstruction.type* to *INSTALLMENT*.
* Set *standingInstruction.mode* to *INITIAL*.
* Set *standingInstruction.source* to *CIT*.
* Save the bank-specific fields in the *resultDetails* response for future use. | | **CIT Subsequent Transaction**
(The cardholder is using a stored credential.) | * Set *pos.entryMode* to *CREDENTIAL_ON_FILE*.
* Set *standingInstruction.mode* to *REPEATED*.
* Set *standingInstruction.source* to *CIT*.
* Provide the saved bank-specific fields in the request *customParameters* field. | Multiple Clearing: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: CP amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: track2Data: 5416389123456786D22021010000081315000 pos: storeId: '78123753' terminalId: '12195611' entryMode: MAGSTRIPE captureSequence: '02' lastCapture: 'true' referencedPaymentId: e8f59d02a466f35a7ece785d3e137e50 description: >- ### Multiple Clearing (Captures) Multiple Clearing (Captures) is compatible with the following message type: * Capture Notification ConnectUP supports sending multiple ***capture (CP)*** messages for a single ***authorization (PA)***. It is used to incrementally capture an authorization. Merchants are able to submit multiple, partially-clearing capture notifications for the single authorization by adding a Capture Sequence number. This value indicates the number of the CP message in a sequence of multiple CP messages. Subsequent captures must reference the original PA message’s id in the referencedPaymentId field. #### Example An example for a Multiple Capture sequence might be an order that contains multiple items to ship. For each shipment, the merchant can perform a partial capture on the original pre-authorization message for the goods being delivered. *A multiple capture scenario follows:* 1) Send an initial authorization request for the total amount intended for the transaction. 2) Fulfill half the order and partially capture one half the original initial authorization. 3) Fulfill the remainder of the order and partially capture the remaining amount of the original authorization. #### Initial Authorization Request ```` ``` curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..." -d "entityId=b964f0e254a717c1524355a6149b575d" -d "paymentType=PA" -d "card.track2Data=5416389123456786D22021010000081315000" -d "amount=100.00" -d "pos.terminalId=34056111" -d "pos.storeId=78919753" -d "pos.entryMode=MAGSTRIPE" -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" ``` ```` #### Response of the Initial Authorization ```` { "id" : "e8f59d02a466f35a7ece785d3e137e50", "amount" : "100.00", "currency" : "USD", "result": { "code" : "000.000.000", "description" : "Transaction succeeded", "authorizationId" : "783276" }, "timestamp" : "2019-09-06 12:00:00" } ```` #### First Partial Capture Request This is the first ***CP*** request referencing the ***PA’s id*** in the ***referencedPaymentId*** field; specifying 25.00 USD. The ***captureSequence*** field is set to ***01*** indicating that this is the first ***CP*** in a chain. ```` curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..." -d "entityId=b964f0e254a717c1524355a6149b575d" -d "paymentType=CP" -d "card.track2Data=5416389123456786D22021010000081315000" -d "amount=25.00" -d "pos.terminalId=34056111" -d "pos.storeId=78919753" -d "pos.entryMode=MAGSTRIPE" -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" -d "captureSequence=01" -d "referencedPaymentId=e8f59d02a466f35a7ece785d3e137e50" -d "statusCode=SUCCESSFUL" ```` #### 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" -d "statusCode=SUCCESSFUL" ```` #### 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" } ```` Partial Approval: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: PA amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL partialApprovalAllowed: 'true' description: >- ### Partial Approval *Compatible with the following message types:* * Pre-Authorization Request * Debit Request * Capture Notification If ***partialApprovalAllowed*** is set to false, the parameter will have no effect on the payment. PIN-less Debit: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pinlessDebit: 'true' pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### PIN-less Debit *PIN-less Debit is compatible with the following message types:* * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. (POS) Data Fields: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL cardDataInputCapability: BARCODE cardDataOutputCapability: ICC cardholderAuthenticationCapability: PIN cardholderAuthenticationMethod: NONE cardCaptureCapability: NONE operatingEnvironment: MERCHANT_ATTENDED cardholderPresent: CARD_HOLDER_PRESENT terminalType: POS terminalOutputCapability: PRINT description: >- ### Point-of-Sale (POS) Data Fields *Point-of-Sale (POS) Data Fields is compatible with the following message types:* * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. Receiving Institution Code: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL merchant: receivingInstitutionCode: '12345678901' description: >- ### Receiving Institution Code *Receiving Institution Code is compatible with the following message types:* * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification To identify the financial institution that must receive the transaction, add the following parameter to your payment message. Reversal Reason: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: RV referencedPaymentId: 1b8cd7b6c81c9883e8926f04985fa7b5 reason: VOID pos: terminalId: '12195611' description: >- ### Reversal Reason *Reversal Reason is compatible with the following message type:* * Reversal Request * Reversal Notification The ***reason*** field can be used to indicate why a transaction is being reversed. Reversal using referenced merchant transaction id: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: RV referencedMerchantTransactionId: 1b8cd7b6c81c9883e8926f04985fa7b5 reason: VOID pos: terminalId: '12195611' description: >- ### Reversal using referencedMerchantTransactionId *Reversals using referencedMerchantTransactionId are compatible with the following message type:* * Reversal Request * Reversal Notification 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. SCA: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL description: >- ### Strong Customer Authentication (SCA) *Strong Customer Authentication (SCA) is compatible with the following message types:* * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. ### Example An example scenario for SCA for terminals that support Single Tap and PIN, where the customer withdrawal frequency has been exceeded, follows: 1) A standard contactless pre-authorization message is sent with pos.scaExemptionFlag = TAP_AND_PIN_SUPPORTED. 2) The upstream entity responds with the 300.100.190: Transaction declined (Issuer Requires PIN [SCA]) result code. 3) The terminal updates the message with the provided PIN. 4) A new payment message with PIN is sent to ConnectUP. 5) The ***pos.scaExemptionFlag*** field is updated to ***PIN_PROVIDED***. 6) No further exemption will be applied to transactions that contain PIN data. #### Initial contactless request ````` curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..." -d "entityId=b964f0e254a717c1524355a6149b575d" -d "paymentType=PA" -d "card.number=4444444444444448" -d "card.expiryMonth=05" -d "card.expiryYear=2050" -d "amount=10000000.00" -d "pos.terminalId=34056111" -d "pos.storeId=78919753" -d "pos.entryMode=NFC_ICC" -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" -d "pos.scaExemptionFlag=TAP_AND_PIN_SUPPORTED" ````` #### Response indicating the declined transaction due to the issuer requesting SCA ````` { "id" : "e8f59d02a466f35a7ece785d3e137e50", "amount" : "0.00", "currency" : "USD", "result": { "code" : "300.100.190", "description" : "Transaction declined (Issuer Requires PIN [SCA])", "authorizationId" : "783276" }, "timestamp" : "2019-09-06 12:22:44" } ````` #### Secondary contactless request with PIN data to satisfy the exemption ````` curl http://[hostname]:[port]/paymentsapi/opp/v1/payment -v -H "Authorization: Bearer NjAyNTYzYjdNEY0RjA5NzNEQ..." -d "entityId=b964f0e254a717c1524355a6149b575d" -d "paymentType=PA" -d "card.number=4444444444444448" -d "card.expiryMonth=05" -d "card.expiryYear=2050" -d "amount=10000000.00" -d "pos.terminalId=34056111" -d "pos.storeId=78919753" -d "pos.entryMode=NFC_ICC" -d "pos.encryptedPin.data=A3929E6A25E8E32C" -d "pos.encryptedPin.ksn=*" -d "merchantTransactionId=ce6b3d18b660db9aa7ef667be8f098d1" -d "pos.scaExemptionFlag=PIN_PROVIDED" ````` 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. Shipping Contact: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL shipping: street1: Receiver Park street2: 123 Main Street houseNumber1: '1' postcode: '7500' city: Cape Town state: WC country: ZA method: NEXT_DAY_OVERNIGHT warehouse: Receiving Warehouse customer: givenName: John surname: Smith email: johnsmith@receivingemail.com companyName: The Receiving Company telephone: 021 567 5842 from: street1: Sender Complex street2: 13 West Street houseNumber1: '1' postcode: '7500' city: Cape Town state: WC country: ZA warehouse: Sending Warehouse customer: givenName: Jeffrey surname: Zebos email: jeffzebos@sendingemail.com companyName: The Sending Company telephone: 021 567 5813 description: >- ### Shipping Contact *Shipping Contact is compatible with the following message types:* * Pre-Authorization Request * Capture Notification To specify the contact details of the shipping sender or receiver, use the following fields. The shipping.* fields must be used for the customer which receiving the shipment. The shipping.from.* fields must be used for the merchant/retailer which is sending the shipment. Transaction Category: value: entityId: entity1pbx08d4bdeb27e205d70a9ab3 paymentType: DB amount: '21.00' merchantTransactionId: ce6b3d18b660db9aa7ef667be8f098d2 card: number: "4444444444444448" expiryMonth: "10" expiryYear: "2025" pos: storeId: '78123753' terminalId: '12195611' entryMode: MANUAL transactionCategory: EC description: >- ### Transaction Category *Transaction Category is compatible with the following message types:* * Pre-Authorization Request * Debit Request * Credit Request * Capture Notification * Reversal Request * Reversal Notification 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. responses: 200: description: Successful payment response. content: application/json: schema: $ref: '#/components/schemas/PaymentResponse' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/token/tokenize: post: security: - bearer: [] tags: - Tokenization summary: Tokenization Request description: |- 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. Either ***card.number***, ***card.track2Data***, or ***P2PE card data fields*** must be specified for a tokenization request. operationId: processTokenizationRequest requestBody: description: The tokenization request details. content: application/json: schema: $ref: '#/components/schemas/TokenRequest' example: entityId: entity1pcx8d4abde3b7e205d70a9ab3 card: number: "2222333344442226" expiryMonth: "12" expiryYear: "2025" required: true responses: 200: description: |- ### Standard Tokenization Response 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. #### 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| content: application/json: schema: $ref: '#/components/schemas/TokenResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 tokenId: JYO7rdR5UjK61111 result: code: 000.000.000 description: Transaction succeeded customParameters: CUSTOM_KEY1: CUSTOM_VALUE1 CUSTOM_KEY2: CUSTOM_VALUE2 resultDetails: Field1: Value1 Field2: Value2 timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/token/detokenize: post: security: - bearer: [] tags: - Tokenization summary: De-tokenization Request description: |- De-tokenization is the process where a token value is used to retrieve the original tokenized card details through a secure tokenization system. A de-tokenization request retrieves sensitive card-data fields associated with the supplied token. operationId: processDetokenizationRequest requestBody: description: The de-tokenization request details. content: application/json: schema: $ref: '#/components/schemas/TokenRequest' example: entityId: entity1pcx8d4abde3b7e205d70a9ab3 tokenId: JYO7rdR5UjK61111 required: true responses: 200: description: |- ### Standard Detokenization Response The ***card.expiryMonth*** and ***card.expiryYear*** fields will only be populated if they were included in the original tokenization request for this tokenId. 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. #### 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| content: application/json: schema: $ref: '#/components/schemas/TokenResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 tokenId: JYO7rdR5UjK61111 result: code: 000.000.000 description: Transaction succeeded card: number: "1234567890123456" expiryMonth: "12" expiryYear: "2025" customParameters: CUSTOM_KEY1: CUSTOM_VALUE1 CUSTOM_KEY2: CUSTOM_VALUE2 resultDetails: Field1: Value1 Field2: Value2 timestamp: '2019-09-06 12:22:44' '400': description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. '403': description: >- 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. /opp/v1/storedvalue/load: post: security: - bearer: [] tags: - Payments Service summary: Stored-Value Load Request description: |- 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. operationId: processGiftLoadResultRequest requestBody: description: |- The minimum requirements for sending a ***stored-value load*** message are listed in the example. content: application/json: schema: $ref: '#/components/schemas/PaymentRequest' example: entityId: "b964f0e254a717c1524355a6149b575d" amount: "55.00" card: number: "1234567890123456" expiryMonth: "12" expiryYear: "2025" pos: terminalId: "12195611" storeId: "78123753" entryMode: UNKNOWN merchantTransactionId: "ce6b3d18b660db9aa7ef667be8f098d2" required: true responses: 200: description: Successful stored-value load response. content: application/json: schema: $ref: '#/components/schemas/PaymentResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 amount: "55.00" result: code: 000.000.000 description: Transaction succeeded authorizationId: "078897" resultDetails: retrievalReferenceNumber: "000000001363" timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/storedvalue/deactivate: post: security: - bearer: [] tags: - Payments Service summary: Stored-Value Deactivate Request description: |- 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. ConnectUP supports receiving card data in other formats. For more details on sending card information, see Alternative Card Data examples. operationId: processGiftDeactivateResultRequest requestBody: description: The minimum requirements for sending a stored-value deactivate request message are listed in the example. content: application/json: schema: $ref: '#/components/schemas/PaymentRequest' example: entityId: "b964f0e254a717c1524355a6149b575d" amount: "55.00" card: number: "1234567890123456" expiryMonth: "12" expiryYear: "2025" pos: terminalId: "12195611" storeId: "78123753" entryMode: UNKNOWN merchantTransactionId: "ce6b3d18b660db9aa7ef667be8f098d2" required: true responses: 200: description: Successful stored-value load response. content: application/json: schema: $ref: '#/components/schemas/PaymentResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 amount: "55.00" currency: "USD" result: code: 000.000.000 description: Transaction succeeded resultDetails: retrievalReferenceNumber: "000000001363" timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/storedvalue/activate: post: security: - bearer: [] tags: - Payments Service summary: Stored-Value Activate Request description: |- 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. operationId: processGiftActivateResultRequest requestBody: description: The minimum requirements for sending a ***stored-value activate*** message are listed in the example. content: application/json: schema: $ref: '#/components/schemas/PaymentRequest' example: entityId: "b964f0e254a717c1524355a6149b575d" amount: "55.00" card: number: "1234567890123456" expiryMonth: "12" expiryYear: "2025" pos: terminalId: "12195611" storeId: "78123753" entryMode: UNKNOWN merchantTransactionId: "ce6b3d18b660db9aa7ef667be8f098d2" required: true responses: 200: description: Successful stored-value load response. content: application/json: schema: $ref: '#/components/schemas/PaymentResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 amount: "55.00" currency: "USD" result: code: 000.000.000 description: Transaction succeeded authorizationId: "078897" resultDetails: retrievalReferenceNumber: "000000001363" timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/payment/iccresult: post: security: - bearer: [] tags: - Payments Service summary: Integrated Circuit Chip (ICC) Data Result Request description: |- 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. operationId: processIccResultRequest requestBody: description: The minimum requirements for sending a ***ICC Data Result*** message are listed in the example. content: application/json: schema: $ref: '#/components/schemas/PaymentRequest' example: entityId: "b964f0e254a717c1524355a6149b575d" card: track2Data: "5301250070000191" pos: terminalId: "12195611" storeId: "78123753" iccDataRequest: "9F3303E0F0C89F03060202" referencedPaymentId: "1b9e311efa074b9e92048c44de58b1e7" required: true responses: 200: description: |- Successful ICC Data Result response. content: application/json: schema: $ref: '#/components/schemas/PaymentResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 amount: "0.00" currency: "USD" result: code: 000.000.000 description: Transaction succeeded authorizationId: "078897" iccDataResponse: "6F1A840E3150411025F2D02" resultDetails: retrievalReferenceNumber: "000000001363" timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/p2pe/rkdrequest: post: security: - bearer: [] tags: - Remote Key Distribution summary: RKD Exchange Request description: >- This request retrieves new P2PE keys for a PIN entry device (PED). The request message contains details on the key request and the PED initiating the request. A successful response contains the new P2PE key. operationId: processRkdExchangeRequest requestBody: description: The minimum requirements for sending a RKD exchange request are listed in the example. content: application/json: schema: $ref: '#/components/schemas/RkdExchangeRequest' example: entityId: entity1pcx8d4abde3b7e205d70a9ab3 rkdScheme: "MyrkdScheme" rkdRequestData: "uuuuuuuuuuuuduususu12323" keyStatus: VALID deviceName: "VX810" pos: terminalId: "12195611" required: true responses: 200: description: Standard RKD exchange response content: application/json: schema: $ref: '#/components/schemas/RkdExchangeResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 result: code: 000.000.000 description: Transaction succeeded customParameters: CUSTOM_KEY1: CUSTOM_VALUE1 CUSTOM_KEY2: CUSTOM_VALUE2 resultDetails: rkdKeyData: oTRrSghgjghjghjhgj=="; rkdEchoData: '1234567890' timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/p2pe/rkdconfirm: post: security: - bearer: [] tags: - Remote Key Distribution summary: RKD Exchange Confirmation Request description: >- The request message contains details on the outcome of applying a key that was provided in an RKD exchange response. operationId: processRkdConfirmRequest requestBody: description: The minimum requirements for sending a RKD exchange confirmation request are listed in the example. content: application/json: schema: $ref: '#/components/schemas/RkdExchangeRequest' example: entityId: entity1pcx8d4abde3b7e205d70a9ab3 rkdScheme: "MyrkdScheme" rkdKeyConfirmationData: "3238333131323435347c4b45595f554e5041434b5f53554343455353" rkdEchoData: '1234567890' deviceName: "VX810" pos: terminalId: "12195611" required: true responses: 200: description: Standard RKD exchange response content: application/json: schema: $ref: '#/components/schemas/RkdExchangeResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 result: code: 000.000.000 description: Transaction succeeded customParameters: CUSTOM_KEY1: CUSTOM_VALUE1 CUSTOM_KEY2: CUSTOM_VALUE2 resultDetails: rkdKeyData: gjhgjghjghjghjhg=== rkdEchoData: '1234567890' timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/nwrkmng: post: security: - bearer: [] tags: - Network Management summary: Network Management Request. description: |- This service is used to send a ***network management request***. A ***network management request*** is created by sending a POST request over HTTPS to the ***https://[hostname]:[port]/paymentsapi/opp/v1/nwrkmng*** resource. operationId: processNwrkManagementRequest requestBody: content: application/json: schema: $ref: '#/components/schemas/NwrkManagementRequest' example: entityId: "b964f0e254a717c1524355a6149b575d" infoCode: NEW_KEY settlementDate: "0522" merchant: receivingInstitutionCode: "11111111111" forwardingInstitutionCode: "22222222222" acquiringInstitutionCode: "33333333333" pos: terminalId: "12195611" storeId: "78123753" terminalOperator: MERCHANT encryptedPin: ksn: "FFFF12345612342000" required: true responses: 200: description: Successful network management response. content: application/json: schema: $ref: '#/components/schemas/NwrkManagementResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 result: code: 000.000.000 description: Transaction succeeded authorizationId: "078897" timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/balanceinquiry: post: security: - bearer: [] tags: - Payments Service summary: Balance Inquiry Request. description: |- 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. ConnectUP supports receiving card data in other formats. For more details on sending card information, see the ***Alternative Card Data*** examples. operationId: processBalanaceInquiryResultRequest requestBody: description: "The minimum requirements for sending a ***balance inquiry*** message are listed in the example:" content: application/json: schema: $ref: '#/components/schemas/PaymentRequest' example: entityId: "b964f0e254a717c1524355a6149b575d" card: number: "1234567890123456" expiryMonth: "12" expiryYear: "2025" pos: terminalId: "12195611" storeId: "78123753" entryMode: UNKNOWN merchantTransactionId: "ce6b3d18b660db9aa7ef667be8f098d2" required: true responses: 200: description: Successful balance inquiry request response. content: application/json: schema: $ref: '#/components/schemas/PaymentResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 amount: "0.00" currency: "USD" balances: availableBalance: "100.00" ledgerBalance: "110.00" result: code: 000.000.000 description: Transaction succeeded authorizationId: "078897" resultDetails: retrievalReferenceNumber: "000000001363" timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/apm/decrypt/googlepay: post: security: - bearer: [] tags: - APM Decryption summary: Google Token Decrypt Request description: |- To use this service only a Google Pay payment token must be supplied in the request. Only one APM token type may be supplied for any APM Token Decrypt Request sent to ConnectUP. 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 examples for more details on how to perform both either of these Payment requests using an APM. operationId: processGoogleTokenRequest requestBody: description: Example using Google Pay token content: application/json: schema: $ref: '#/components/schemas/APMDecryptRequest' example: entityId: entity1pcx8d4abde3b7e205d70a9ab3 pos: terminalId: "34056111" storeId: "78919753" googlePay: paymentToken: "paymentTokenXYZ" required: true responses: 200: description: Successful Google Pay Token Decrypt response. content: application/json: schema: $ref: '#/components/schemas/APMDecryptResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 amount: "50.00" currency : "USD" result: code: 000.000.000 description: Transaction succeeded authorizationId : "783276" card: number: "1234567890123456" expiryMonth: "12" expiryYear: "2025" numberType : "DPAN" customParameters: CUSTOM_KEY1: CUSTOM_VALUE1 CUSTOM_KEY2: CUSTOM_VALUE2 resultDetails: Field1: Value1 Field2: Value2 threeDSecure: verificationId: "1234ABCD" tavv: "1234ABCD" eci: "05" timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403: description: >- 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. /opp/v1/apm/decrypt/applepay: post: security: - bearer: [] tags: - APM Decryption summary: Apple Token Decrypt Request description: |- To use this service only a Apple Pay payment token must be supplied in the request. Only one APM token type may be supplied for any APM Token Decrypt Request sent to ConnectUP. 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 examples for more details on how to perform both either of these Payment requests using an APM. operationId: processAppleTokenRequest requestBody: description: Example using Apple Pay token content: application/json: schema: $ref: '#/components/schemas/APMDecryptRequest' example: entityId: entity1pcx8d4abde3b7e205d70a9ab3 pos: terminalId: "34056111" storeId: "78919753" merchant: street: "Century Avenue" city: "Cape Town" country: "ZA" state: "WC" applePay: paymentToken: "paymentTokenXYZ" required: true responses: 200: description: Successful Apple Pay Token Decrypt response. content: application/json: schema: $ref: '#/components/schemas/APMDecryptResponse' example: id: e8f59d02a466f35a7ece785d3e137e50 amount: "50.00" currency : "USD" result: code: 000.000.000 description: Transaction succeeded authorizationId : "783276" card: number: "1234567890123456" expiryMonth: "12" expiryYear: "2025" numberType : "DPAN" customParameters: CUSTOM_KEY1: CUSTOM_VALUE1 CUSTOM_KEY2: CUSTOM_VALUE2 resultDetails: Field1: Value1 Field2: Value2 threeDSecure: verificationId: "1234ABCD" tavv: "1234ABCD" eci: "05" timestamp: '2019-09-06 12:22:44' 400: description: >- This means that the server cannot process the request. This might either point to invalid field values or processing/connectivity failures. It is also returned if the payment failed, for example, because the acquirer declined the request. Check the result.code and result.description fields for the reason the request failed. 403 : description: >- 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. components: securitySchemes: bearer: type: http scheme: bearer schemas: TlvMapping: type: object additionalProperties: type: string format: AN2048 pattern: '[\s\S]{0,2048}' example: tlvFieldName1: someValue tlvFieldName2: someValue2 CustomParameters: type: object description: >- Custom parameters allow you to include additional information in the form of key-value pairs. By leveraging custom parameters, you can enhance the transaction process by including any custom data not natively supported by the API. additionalProperties: type: string format: AN2048 pattern: '[\s\S]{0,2048}' example: custParmName: someValue custParmName2: someValue2 ResultDetails: type: object description: >- A data structure containing dynamic key/value response related fields. additionalProperties: type: string format: AN2048 pattern: '[\s\S]{0,2048}' example: retrievalReferenceNumber: 000000000044 iso8583ResponseCode: 00 Result: type: object description: A data structure containing various response related fields. properties: code: type: string format: AN11 pattern: '[0-9\.]{2,11}' description: The unique code that indicates the result status of the request. example: 000.000.000 description: type: string format: AN255 pattern: '[\\s\\S]{0,255}' 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. example: Transaction succeeded authorizationId: type: string format: AN6 pattern: '[a-zA-Z0-9]{1,6}' description: >- The code assigned by the authorizing institution indicating approval. example: '783276' cvvResponse: type: string format: A1 pattern: '[A-Z]{1}' description: >- Contains the CVV response returned by the acquirer. It may include one the following result: * M - CVV2 Match Indicates that the issuer was able to verify the CVV2 value provided by the merchant. * N - CVV2, CVC2, Discover CID or AMEX CID do not match Indicates that the issuer was not able to verify the CVV2 value provided by the merchant. * P - Not Processed Indicates that the issuer was unable to verify the CVV2 value provided by the merchant because either their verification system was not functioning, or not all of the information needed to verify the CVV2 value (such as the expiration date) was included in the request. * S - CVV2, CVC2, Discover CID or AMEX CID data is not present on the card, but the issuer indicated it should be present Indicates that the issuer was unable to perform CVV2 verification, and notifies the merchant that the card should contain a CVV2 value. * U - Unsupported by issuer or issuer is unable to process request Indicates that the issuer is not participating in the CVV2 service, or that the issue has not provided the card Brand with the required encryption keys needed to perform verification, or that STIP has responded with unavailable response. example: M avsResponse: type: string format: A1 pattern: '[A-Z]{1}' description: >- Contains the AVS response returned by the acquirer. See OPP Response Parameters for more details about avsResponse. example: U iccDataResponse: type: string format: AN2048 pattern: '[a-fA-F0-9]{1-20000}' description: >- This field contains BER-TLV data from the issuer, as defined by the EMV specifications, and is hex-encoded. example: 9F3303E0F0C89F03060202 TokenRequest: type: object properties: customParameters: $ref: '#/components/schemas/CustomParameters' entityId: type: string description: >- The entityId is used in conjunction with the HTTP Authorization header to specify the entity associated with the request. When requesting new user credentials from ACI, the entityID will be provided to you. format: AN32 pattern: '[a-f0-9]{32}' example: entity1pbx08d4bdeb27e205d70a9ab3 card: $ref: '#/components/schemas/token.Card' pos: $ref: '#/components/schemas/token.Pos' tokenId: pattern: '[a-zA-Z0-9]{1,255}' type: string description: A token representing sensitive cardholder data. format: AN255 example: JYO7rdR5UjK61111 token.Card: type: object properties: track2Data: pattern: '[\s\S]{1,37}' format: ANS37 type: string description: >- The information encoded on Track 2 of the magnetic stripe, as defined in ISO 7813. example: 5416389123456786D22021010000081315000 number: pattern: '[0-9]{12,19}' type: string format: N19 description: The Primary Account Number (PAN) of the physical card. example: "4444444444444448" expiryMonth: pattern: '[0-9]{2}' type: string format: N2 example: "10" description: The month that the card expires. expiryYear: pattern: '(20|21)([0-9]{2})' format: N4 type: string description: The year that the card expires. example: "2025" token.Pos: type: object properties: p2peEncrypted: $ref: '#/components/schemas/P2peEncrypted' P2peEncrypted: type: object properties: type: pattern: ACI|INGENICO_ONGUARD|PAX|VERIFONE_VSD|PRESTO type: string description: >- Indicates the scheme of point-to-point encryption (P2PE) used to encrypt the account data at the PIN entry device (PED). enum: - ACI - INGENICO_ONGUARD - PAX - VERIFONE_VSD - PRESTO example: INGENICO_ONGUARD ksn: pattern: '[a-fA-F0-9]{1,2048}' type: string description: >- 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. format: AN2048 example: FFFF98765400020002280500060000 sensitiveData: pattern: '[a-zA-Z0-9]{1,65535}' type: string description: >- 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. format: AN65535 example: '2805000600003031313030364e47' persistableData: pattern: '[a-fA-F0-9]{1,65535}' type: string description: >- 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. format: AN65535 example: '41303854133380862400453030' volatileData: pattern: '[a-fA-F0-9]{1,65535}' type: string description: >- The volatile (must not be stored) encrypted point-to-point encryption (P2PE) account data (PAN/TRACK2/EXPIRY). When P2PE functionality is used and the card details were encrypted, this field is required instead of the card.number, card.track2data, card.expiryMonth, card.expiryYear, and card.cvv fields. If card details are received in addition to pos.p2peEncrypted.persitableData, it is assumed that the particular card used is subject to whitelisting and that pos.p2peEncrypted.whitelistFileName is present. This field is encoded as a hex representation of the binary P2PE sensitive data block value. format: AN65535 example: 3040431234f354130385410 WhitelistFileName: pattern: '[\s\S]{1,100}' type: string description: >- 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. format: ANS100 example: DFGHJKLRTYUIOPFGHJKL tlvMapping: $ref: '#/components/schemas/TlvMapping' whitelistHash: pattern: '[a-fA-F0-9]{1,255}' type: string description: >- A SHA-1 or SHA-256 hash value calculated over the content of the whitelist file loaded on the terminal. format: AN2555 example: 1B7HAETAKFAI08 whitelistSignature: pattern: '[a-fA-F0-9]{1,99999}' type: string description: >- 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. format: AN99999 example: 1B7HAETAKFAI0818141298AEBABDAEKLAKJNFJA41824998741275610948091270942170 maxReliableBinLength: pattern: '[0-9]{1,99999}' type: string description: >- This field is set to the number of starting digits of the PAN that are visible based on the obfuscation scheme. format: N99999 example: 108498126712012489127125190751957501-8917286125091 TokenResponse: type: object properties: id: type: string example: 'e8f59d02a466f35a7ece785d3e137e50' format: AN32 pattern: '[a-zA-Z0-9]{1,32}' description: 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. result: $ref: '#/components/schemas/Result' timestamp: type: string example: '2025-10-28 15:24:22' pattern: '(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])' description: The timestamp generated by the response in UTC. customParameters: $ref: '#/components/schemas/CustomParameters' resultDetails: $ref: '#/components/schemas/ResultDetails' tokenId: pattern: '[a-zA-Z0-9]{1,255}' type: string description: A token representing sensitive cardholder data. format: AN255 example: JYO7rdR5UjK61111 card: $ref: '#/components/schemas/token.Card' ACustomer: type: object properties: givenName: type: string description: The customer's name. surname: type: string description: The customer's surname. email: type: string description: The customer's e-mail address. companyName: type: string description: The customer's company name. telephone: type: string description: The customer's telephone number. BillPayment: type: object description: The bill payment data structure holds information regarding bill payments. properties: billPayment: type: boolean pattern: true|false example: true description: >- When this flag is set to true, it indicates that this is a bill payment transaction. Only true is valid. Billing: type: object description: The billing data structure holds billing address related information. properties: street1: pattern: '[\s\S]{1,50}' type: string description: >- The door number, floor, building number, building name, and/or street name of the billing address. format: ANS50 example: The Cape Estate street2: pattern: '[\s\S]{1,50}' type: string description: >- Additional address data of the company, or authorized person to contact. format: ANS50 example: 456 Main Street houseNumber1: pattern: '[\s\S]{1,50}' type: string description: >- Primary house number (door number or building number) of the billing address. If present, then billing.street1 is assumed to contain only the name of the street. format: ANS50 example: 123 city: pattern: '[\s\S]{1,20}' type: string description: 'The town, district, or city of the billing address.' format: ANS20 example: Cape Town state: pattern: '[a-zA-Z0-9\.]{1,20}' type: string description: 'The county, state, or region of the billing address.' format: ANS20 example: WC postcode: pattern: '[a-zA-Z0-9]{1,9}' type: string description: The postal code or zip code of the billing address. format: ANS9 example: 7500 country: pattern: '[A-Z]{2}' type: string description: The country of the billing address (ISO 3166-1). format: A2 example: ZA from: $ref: '#/components/schemas/Billing' example: street1: The Cape Estate street2: 456 Main Street houseNumber1: 123 city: Cape Town state: WC postcode: 7500 country: ZA DeferredPayment: type: object description: Deferred payment related fields. properties: deferredPayment: type: boolean description: >- Setting this flag indicates that the payment was deferred (a future dated payment that is submitted now). pattern: true|false example: false EmvFileDownload: type: object description: Contains EMV file download related fields. properties: fileVersion: pattern: '[\\s\\S]{1,99}' type: string format: ANS99S example: "OldFile_1.0" description: Free form field containing the file version information. blockNumber: pattern: '[\\s\\S]{1,50}' type: string format: ANS50S example: "1" description: Indicates the block number or offset of the current download. downloadIndicator: type: string description: Indicates download status. pattern: REQUIRED|NOT_REQUIRED|IN_PROGRESS|COMPLETED|ERROR|SUCCESSFUL example: REQUIRED enum: [REQUIRED,NOT_REQUIRED,IN_PROGRESS,COMPLETED,ERROR,SUCCESSFUL] caPkf: pattern: '[\\s\\S]{1,9999}' type: string format: ANS9999 example: "20251212,01,01,A000001000,02,AB9A23F8H32D5E327CFF;2024" description: Contain a partial CA PKF file in the eSocket.POS EMV Download file format. EncryptedPin: type: object properties: data: pattern: '[a-fA-F0-9]{1,2048}' type: string format: AN2048 example: A3929E6A25E8E32C description: >- 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. ksn: pattern: '[a-fA-F0-9]{1,2048}' type: string format: AN2048 example: >- FFFF12345612342000010000000000000000000000000000000000000000000000000000000000000000000000000000 description: >- 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. Item: type: object description: Represents an item in the cart. properties: description: pattern: '[\s\S]{1,40}' type: string description: A description of this item. format: ANS40 example: This item is nice. number: pattern: '[0-9]{3}' type: string description: The line number of this item on the invoice. format: N3 example: 005 customerCode: pattern: '[\s\S]{1,20}' type: string description: A customer-supplied code relating to this item. format: ANS20 example: 45454545646464 vatReferenceNr: pattern: '[\s\S]{1,20}' type: string description: The reference number used to identify the VAT invoice or tax receipt. format: ANS20 example: 64545645456454221 merchantItemId: pattern: '[\s\S]{1,20}' type: string description: The universal product code (UPC) of this item. format: ANS20 example: genericItemId quantity: pattern: '^[0-9]{1,9}(\.[0-9]{0,3})?$' type: string description: The quantity of this item. format: N9.N3 example: '1' unitOfMeasure: pattern: '[\s\S]{1,12}' type: string description: >- The unit of measure pertaining to the items[n].quantity field, as defined by the card acceptor. format: ANS12 example: lbs totalAmount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: The total amount (in the minor denomination) for this item. format: N8.N4 example: '15.00' totalAmountType: pattern: NET|GROSS type: string description: >- Indicates whether tax is included in, or excluded from, the cart.items[n].totalAmount field. enum: - NET - GROSS example: NET totalAmountSign: pattern: 'C|D' type: string description: This sign applies to the totalAmount field of this item and to all the taxAmount fields of this item. If this field is not present, D is assumed. enum: - C - D example: C sku: pattern: '[\s\S]{1,20}' type: string description: >- A merchant-supplied code or stock-keeping unit (SKU) relating to this item. format: ANS20 example: '11125455' price: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string format: N8.N4 description: The price (in the minor denomination) of one unit of the product. example: '15.00' discountAmount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: >- The discount amount (in the minor denomination) applied to this item. format: N8.N4 example: '1.50' discountAmountSign: pattern: '[0-9\.]{1}' type: string description: Discount amount interpretation. format: AN1 example: 'C' discount: pattern: '[0-9]{5}' type: string description: >- The discount rate applied to this item. Three decimal places are implied. format: N5 example: "100" supplyType: pattern: 00|01 type: string description: >- The supply type. Valid values: * 00 - Goods * 01 - Services enum: - "00" - "01" example: 01 taxAmounts: type: object description: >- The tax amounts data structure holds tax amount related information. The tax amount items are identified by incrementing keys starting at 0 for each item.
Example:
"taxAmounts":{"0":{"taxType":"OTHER","fieldX":"123"},"1":{"taxType":"UNKNOWN","fieldY":"123"}} additionalProperties: $ref: '#/components/schemas/TaxAmount' example: '0': taxType: UNKNOWN taxDescription: State GS totalTaxAmount: 1.5 tax": 00.10 taxId": us_taxes '1': taxType: OTHER taxDescription: State ff totalTaxAmount: 2.5 tax: 00.510 taxId: us_taxes itemizedDiscounts: type: object additionalProperties: $ref: '#/components/schemas/ItemizedDiscount' example: '0': amount: 156.46 rate: 57 discountCode: j857684576846 '1': amount: 200.00 rate: 1 discountCode: dc567567567f PromptData: type: object properties: userId: pattern: '[\s\S]{15}' type: string description: The user identification number. format: ANS15 example: UID5656MFNNNFF7 vehicleId: pattern: '[a-zA-Z0-9_]{10}' type: string description: The vehicle identification number. format: AN10 example: VID88558HB department: pattern: '[a-zA-Z0-9_]{15}' type: string description: The department number. format: AN15 example: DEP88555jjdd123 driverLicense: pattern: '[a-zA-Z0-9_]{12}' type: string description: The driver license number. format: AN12 example: DL666HHAAFFT customerData: pattern: '[a-zA-Z0-9_]{15}' type: string description: Any customer data. format: AN15 example: CD55444IIIUUDDD jobId: pattern: '[a-zA-Z0-9_]{15}' type: string description: The job identification number. format: AN15 example: JOBID55555666D3 contractNumber: pattern: '[a-zA-Z0-9_]{20}' type: string description: The contract number. format: AN20 example: CNUMBER888FRT664AADF PIN: pattern: '[\s\S]{6}' type: string description: The vehicle PIN number. format: ANS6 example: 558845 tripNumber: pattern: '[\s\S]{15}' type: string description: The fleet trip number. format: ANS15 example: TRIP NUMBER 123 unitNumber: pattern: '[a-zA-Z0-9_]{10}' type: string description: The fleet unit number. format: AN10 example: FLEETUNIT5 trailerId: pattern: '[\s\S]{15}' type: string description: The fleet trailer identification. format: ANS15 example: TRAILER ID 12 trailerHours: pattern: '[0-9]{6}' type: string description: The fleet trailer hours number. format: N6 example: 000008 maintenanceId: pattern: '[a-zA-Z0-9_]{15}' type: string description: The fleet maintenance identification. format: AN15 example: MAINTID12312312 hubometer: pattern: '[0-9]{9}' type: string description: The fleet hubometer number. format: N9 example: 000000009 employeeNumber: pattern: '[0-9]{1,10}' type: string description: The fleet employee number. format: N10 example: 666 driverLicenseState: pattern: '[a-zA-Z0-9_]{2}' type: string description: The driver license state code. format: AN2 example: CA vehicleLicense: pattern: '[\s\S]{1,20}' type: string description: The vehicle license number. format: ANS20 example: VEHLIC123 vehicleLicenseState: pattern: '[a-zA-Z0-9_]{2}' type: string description: The vehicle license state code. format: AN2 example: CW trailerLicense: pattern: '[a-zA-Z0-9_]{1,12}' type: string description: The trailer license number. format: AN12 example: TL555 trailerLicenseState: pattern: '[a-zA-Z0-9_]{1,2}' type: string description: The trailer license state code. format: AN2 example: CR fleetId: pattern: '[a-zA-Z0-9_]{1,6}' type: string description: The ID that is defined to the fleet authorizer. format: AN6 example: FID123 customData: pattern: '[\s\S]{1,260}' type: string description: This could carry fleet authorizer specific data like 'VoyagerData'. format: ANS260 example: THIS IS CUSTOM DATA vehicleTag: pattern: '[a-zA-Z0-9_]{1,99}' type: string description: The fleet vehicle tag. format: AN99 example: VEHTAG177 driverLicenseLocation: pattern: '[a-zA-Z0-9_]{1,3}' type: string description: This is used to carry the state/province or other location data. format: AN3 example: CAQ driverLicenseName: pattern: '[\s\S]{1,20}' type: string description: The driver license name. format: ANS20 example: John Smith driverDateOfBirth: pattern: '[0-9]{1,8}' type: string description: The driver date of birth. format: N8 example: 19850212 vehicleVINNumber: pattern: '[a-zA-Z0-9_]{1,17}' type: string description: The vehicle identification number. format: AN17 example: VINNUM12366 pumpNumber: pattern: '[a-zA-Z0-9_]{1,99}' type: string description: The petrol pump number. format: AN99 example: PUMPNUM3 tractorNumber: pattern: '[a-zA-Z0-9_]{1,15}' type: string description: The tractor number. format: AN15 example: PUMPNUM3 FleetBatchDataItem: type: object properties: batchDate: pattern: '[0-9]{8}' type: string description: The fleet batch date. format: N8 example: 20210607 transactionCount: pattern: '[a-zA-Z0-9_]{1,99}' type: string description: The transaction count for a batch. format: AN99 example: 0000001112 total: pattern: '[0-9]{1,99}' type: string description: The total fuel quantity. format: N99 example: 00000111155544 totalUnit: pattern: 'Gallons|Liters' type: string description: The total units ('Gallons' or 'Liters'). enum: - Gallons - Liters example: Gallons PartialApprovalAllowed: type: object description: >- The partial approval allowed data structure holds information about the availability of partial approvals. properties: partialApprovalAllowed: type: boolean pattern: true|false example: false description: >- When this value is set to true, it indicates that partially approved authorizations are acceptable to the client. Will be ignored for paymentType values other than PA and DB. PaymentRequest: type: object properties: customParameters: $ref: '#/components/schemas/CustomParameters' entityId: type: string description: >- The entityId is used in conjunction with the HTTP Authorization header to specify the entity associated with the request. When requesting new user credentials from ACI, the entityID will be provided to you. format: AN32 pattern: '[a-f0-9]{32}' example: entity1pbx08d4bdeb27e205d70a9ab3 card: $ref: '#/components/schemas/payment.request.Card' merchant: $ref: '#/components/schemas/payment.request.Merchant' pos: $ref: '#/components/schemas/payment.request.Pos' billing: $ref: '#/components/schemas/Billing' shipping: $ref: '#/components/schemas/Shipping' debtRepayment: $ref: '#/components/schemas/DebtRepayment' cart: $ref: '#/components/schemas/payment.request.Cart' customer: $ref: '#/components/schemas/payment.request.Customer' standingInstruction: $ref: '#/components/schemas/payment.request.StandingInstruction' taxAmounts: type: object description: >- The tax amounts data structure holds tax amount related information. The tax amount items are identified by incrementing keys starting at 0 for each item.
Example:
"taxAmounts":{"0":{"taxType":"OTHER","fieldX":"123"},"1":{"taxType":"UNKNOWN","fieldY":"123"}} additionalProperties: $ref: '#/components/schemas/TaxAmount' example: '0': taxType: UNKNOWN taxDescription: State GS totalTaxAmount: 1.5 tax": 00.10 taxId": us_taxes '1': taxType: UNKNOWN taxDescription: State ff totalTaxAmount: 2.5 tax: 00.510 taxId: us_taxes itemizedDiscounts: type: object additionalProperties: $ref: '#/components/schemas/ItemizedDiscount' example: '0': amount: 156.46 rate: 57 discountCode: j857684576846 '1': amount: 200.00 rate: 1 discountCode: dc567567567f partialApprovalAllowed: $ref: '#/components/schemas/PartialApprovalAllowed' deferredPayment: $ref: '#/components/schemas/DeferredPayment' billPayment: $ref: '#/components/schemas/BillPayment' threeDSecure: $ref: '#/components/schemas/payment.request.ThreeDSecure' emvFileDownload: $ref: '#/components/schemas/payment.request.EmvFileDownload' applePay: $ref: '#/components/schemas/payment.request.ApplePay' googlePay: $ref: '#/components/schemas/payment.request.GooglePay' paymentType: pattern: DB|CD|CP|RV|PA|IR|GL|GD|GA|BI|DA|DP|RR|CV|CA type: string description: >- The payment type indicator. * DB - Debit Request * CD - Credit Request * CP - Capture Notification * RV - Reversal Notification * PA - Pre-Authorization Request * IR - ICC Data Submission * GD - Stored Value Deactivation * GL - Stored Value Load * GA - Stored Value Activation * BI - Balance Inquiry * DA - Debit Adjustment * DP - Deposit * RR - Reversal Request * CV - Card Verification * CA - Credit Adjustment enum: - DB - CD - CP - RV - PA - IR - GL - GD - GA - BI - DA - DP - RR - CV - CA example: PA merchantTransactionId: pattern: '[\s\S]{8,255}' type: string description: >- The merchant-provided reference number. It must be unique for the merchant’s transactions. format: ANS255 example: ce6b3d18b660db9aa7ef667be8f098d2 currency: pattern: '[A-Z]{3}' type: string format: A3 example: USD description: >- The currency code of the payment request’s amount (ISO 4217). The default currency used is "USD". For a Reversal Request, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction. amount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: >- Indicates the amount of the payment request. The period (.) is used as a decimal separator. format: N8.N4 example: '21.00' referencedPaymentId: pattern: '[\s\S]{1,32}' type: string description: >- The identifier of a transaction being completed. This field is the id value from the original PA response. This field is required when paymentType is set to CP and is linked to a previous PA. This field is ignored when paymentType is set to PA, DB or CD. format: ANS32 example: 1b8cd7b6c81c9883e8926f04985fa7b5 statusCode: pattern: SUCCESSFUL|INVALID_AMOUNT type: string enum: - SUCCESSFUL - INVALID_AMOUNT description: >- Indicates the status code of a CP transaction. memoPost: pattern: true|false type: string enum: - true description: >- Indicates this is a memoPost transaction, which is captured for memo/reporting purposes. referencedMerchantTransactionId: pattern: '[\s\S]{8,255}' type: string description: >- The supplied "merchantTransactionId" of the original PA, DB, CD or CP transaction that is to be reversed. format: ANS255 example: 12548896257 transactionCategory: pattern: EC|MO|TO|RC|PO|PM|BP type: string enum: - EC - MO - TO - RC - PO - PM - BP description: >- The category of the transaction. Used to identify the transaction as card-not-present and/or cardholder-not- present (among other parameters). By default, the card and cardholder are presumed to be present. Possible values are: * EC - eCommerce (Card-holder not present, electronic order and Card not present) * MO - Mail order (Card-holder not present, mail order and Card not present) * PM - Mobile POS (Card-holder present and Card Present) * PO - POS (Card-holder present and Card Present) * TO - Telephone order (Card-holder not present, telephone and Card not present) * BP - Bill Payment fleet: $ref: '#/components/schemas/payment.request.Fleet' merchantOrderNumber: pattern: '[\s\S]{1,25}' type: string description: The merchant’s purchase order number. format: ANS25 example: 123456 merchantInvoiceId: pattern: '[\s\S]{1,20}' type: string description: The merchant invoice ID. format: ANS20 example: 1234567890 totalShippingAmount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: >- The freight, shipping, or delivery amount (in the major denomination) to be paid on the total purchase. format: N8.N4 example: '10.00' totalDiscountAmount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: >- The discount amount (in the major denomination) of the total purchase. format: N8.N4 example: '15.00' totalDutyAmount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: >- The duty amount (in the major denomination) to be paid on the total purchase. format: N8.N4 example: '13.00' shippingAmountSign: pattern: '[a-zA-Z0-9]{1}' type: string description: Shipping amount interpretation. format: AN1 example: 'C' discountAmountSign: pattern: '[a-zA-Z0-9]{1}' type: string description: Discount amount interpretation. format: AN1 example: 'C' dutyAmountSign: pattern: '[a-zA-Z0-9]{1}' type: string description: Duty amount interpretation. format: AN1 example: 'C' commodityCode: pattern: '[\s\S]{1,20}' type: string description: A code assigned by the card acceptor, which best categorizes the goods or services purchased. format: ANS20 example: CC5456456456 taxCollected: pattern: 'TRUE|FALSE|Y|N' type: string description: Indicates whether tax was collected. enum: - TRUE - FALSE - Y - N format: ANS20 example: Y tokenId: pattern: '[a-zA-Z0-9]{1,255}' type: string description: A token representing sensitive cardholder data. format: AN255 example: JYO7rdR5UjK61111 authorizationId: pattern: '[\s\S]{6}' type: string description: >- The code assigned by the authorizing institution indicating approval. This field is required if offline stand-in occurred for a transaction and only a completion (paymentType set to CP) is sent. This field is ignored when paymentType is set to PA, DB, or CD. It is optional in request messages of paymentType CP. format: ANS6 example: 783276 paymentBrand: pattern: APPLEPAY|GOOGLEPAY type: string description: >- The payment brand used to identify alternative payment method transactions. enum: - APPLEPAY - GOOGLEPAY example: APPLEPAY convenienceFee: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: >- A fee charged by the merchant for providing a more convenient alternative payment channel to the customer. If present, this value must be included in the amount field. A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator. For example, to specify one dollar and fifty cents, the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50. A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator. For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50. format: N8.N4 example: '10.00' captureSequence: pattern: '[0-9]{1,2}' type: string description: >- Used to indicate the sequence number for a capture in a chain of linked captures or completions. format: N2 example: '01' lastCapture: pattern: true|false type: string description: >- When this flag is set to true, it indicates that the last capture or completion in the chain is being sent. example: false cashbackAmount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: >- The amount specified to allow a customer to withdraw cash along with their purchase. A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator. ​ For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50. format: N8.N4 example: '100.00' reason: pattern: VOID|TIMEOUT|MAC|STORE_CONTROLLER|COMPLETED_PARTIALLY type: string description: Indicates the reason for the reversal or capture. enum: - VOID - TIMEOUT - MAC - STORE_CONTROLLER - COMPLETED_PARTIALLY example: VOID paymentAccountReference: pattern: '[a-zA-Z0-9]{0,29}' type: string description: The payment account reference. format: AN29 example: 1234567890 Shipping: description: The shipping data structure holds the location and recipient of ordered goods. type: object properties: street1: pattern: '[\s\S]{1,50}' type: string description: >- The door number, floor, building number, building name, and/or street name of the shipping address. format: ANS50 example: Receiver Park street2: pattern: '[\s\S]{1,50}' type: string description: >- The adjoining road or locality (if required) of the shipping address. address. format: ANS50 example: 123 Main Street houseNumber1: pattern: '[\s\S]{1,50}' type: string description: >- 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. format: ANS50 example: 1 city: pattern: '[\s\S]{1,20}' type: string description: 'The town, district, or city of the shipping address.' format: ANS20 example: Cape Town state: pattern: '[a-zA-Z0-9\.]{1,20}' type: string description: 'The county, state, or region of the shipping address.' format: AN20 example: WC postcode: pattern: '[a-zA-Z0-9]{1,9}' type: string description: The postal code or zip code of the shipping address. format: AN9 example: 7500 country: pattern: '[A-Z]{2}' type: string description: The country of the shipping address (ISO 3166-1). format: A2 example: ZA customer: $ref: '#/components/schemas/ACustomer' warehouse: pattern: '[\s\S]{1,100}' type: string description: The warehouse that received the order. format: ANS100 example: Receiving Warehouse method: pattern: >- LOWEST_COST|CARRIER_DESIGNATED_BY_CUSTOMER|ELECTRONIC_DELIVERY|GROUND|INTERNATIONAL|MILITARY|NEXT_DAY_OVERNIGHT|OTHER|STORE_PICKUP|SAME_DAY_SERVICE|TWO_DAY_SERVICE|THREE_DAY_SERVICE|PUDO|EXPEDITED type: string description: The shipping method. enum: - LOWEST_COST - CARRIER_DESIGNATED_BY_CUSTOMER - ELECTRONIC_DELIVERY - GROUND - INTERNATIONAL - MILITARY - NEXT_DAY_OVERNIGHT - OTHER - STORE_PICKUP - SAME_DAY_SERVICE - TWO_DAY_SERVICE - THREE_DAY_SERVICE - PUDO - EXPEDITED example: NEXT_DAY_OVERNIGHT from: $ref: '#/components/schemas/Shipping' example: street1: Receiver Park street2: 123 Main Street houseNumber1: 1 city: Cape Town state: WC postcode: 7500 country: ZA customer: givenName: Jeffrey surname: Zebos email: jeffzebos@sendingemail.com companyName: MyCompName telephone: 021 567 5815 warehouse: Receiving Warehouse method: NEXT_DAY_OVERNIGHT TaxAmount: type: object properties: taxType: pattern: >- UNKNOWN|FEDERAL_NATIONAL_SALES|STATE_SALES|CITY_SALES|LOCAL_SALES|MUNICIPAL_SALES|OTHER|VALUE_ADDED|GOODS_AND_SERVICES|PROVINCIAL_SALES|ROOM|OCCUPANCY|ENERGY type: string description: The type of tax. enum: - UNKNOWN - FEDERAL_NATIONAL_SALES - STATE_SALES - CITY_SALES - LOCAL_SALES - MUNICIPAL_SALES - OTHER - VALUE_ADDED - GOODS_AND_SERVICES - PROVINCIAL_SALES - ROOM - OCCUPANCY - ENERGY example: UNKNOWN taxDescription: pattern: '[\s\S]{1,20}' type: string description: A description of the type of tax format: ANS20 example: State GS totalTaxAmount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: A tax amount (in the minor denomination) applied to this purchase. format: N8.N4 example: '1.50' tax: pattern: '^(100(\.00?)?)|([0-9]{1,2}(\.[0-9]{1,2})?)$' type: string description: The tax rate to be applied to calculate this tax amount. format: AN6 example: 00.10 taxId: pattern: '[\s\S]{1,20}' type: string description: >- An ID number used by the card acceptor with the tax authority in connection with this type of tax. format: ANS20 example: us_taxes ItemizedDiscount: type: object properties: amount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: The discount amount (in the minor denomination). format: N8.N4 example: '156.46' rate: pattern: '[\\s\\S]{1,5}' type: string description: The discount rate. Three decimal places are implied. format: ANS5 example: '1' discountCode: pattern: '[\s\S]{1,20}' type: string description: The discount code supplied by the merchant. format: ANS20 example: 'j857684576846' payment.request.ApplePay: type: object description: When ApplePay is used as payment method. properties: paymentToken: pattern: '[\s\S]{1,8192}' type: string description: The encrypted payment token provided by Apple. format: ANS8192 example: ApplePayPaymentToken nullable: true payment.request.Card: type: object description: >- When a credit or debit card is used as payment method. properties: cvv: pattern: '[0-9]{3,4}' type: string format: N4 description: The Card Security Code (CSC), also known as the Card Verification Value (CVV) is a three or four-digit code printed on the back or front of a credit or debit card. example: 1234 sequenceNumber: pattern: '[0-9]{3}' format: N3 type: string description: >- The card sequence number is a unique identifier that distinguishes between separate cards that have the same primary account number (PAN) or extended primary account number. example: 005 track2Data: pattern: '[\s\S]{1,37}' format: ANS37 type: string description: >- The information encoded on Track 2 of the magnetic stripe, as defined in ISO 7813. example: 5416389123456786D22021010000081315000 number: pattern: '[0-9]{12,19}' type: string format: N19 description: The Primary Account Number (PAN) of the physical card. example: "4444444444444448" expiryMonth: pattern: '[0-9]{2}' type: string format: N2 example: "10" description: The expiry month refers to the month in which a credit or debit card is set to expire. expiryYear: pattern: '(20|21)([0-9]{2})' format: N4 type: string description: The expiry year refers to the year in which a credit or debit card is set to expire. example: "2028" accountType: pattern: >- DEFAULT| SAVINGS| CHECK| CREDIT| STORED_VALUE| STORED_VALUE_SINGLE_DEPOSIT_SINGLE_USE| STORED_VALUE_SINGLE_DEPOSIT_MULTI_USE| STORED_VALUE_MULTI_DEPOSIT_MULTI_USE| SAVINGS_MONEY_MARKET| SAVINGS_CERTIFICATE_OF_DEPOSIT| CHECK_MONEY_MARKET| CREDIT_LINE_OF_CREDIT| CREDIT_INSTALLMENT_LOAN| CREDIT_MORTGAGE_LOAN| CREDIT_HOME_EQUITY_LOAN| CREDIT_COMMERCIAL_LOAN| UNIVERSAL| INVESTMENT| INVESTMENT_STOCK_OR_BOND| INVESTMENT_RETIREMENT_ACCOUNT| INVESTMENT_REVOLVING_LOAN_ACCOUNT| ELECTRONIC_PURSE_DEFAULT| EBT_CASH_BENEFIT| EBT_FOOD_STAMP type: string description: >- A value indicating the type of account affected by the transaction. If no value is provided, the DEFAULT account type is used. enum: - DEFAULT - SAVINGS - SAVINGS_MONEY_MARKET - SAVINGS_CERTIFICATE_OF_DEPOSIT - CHECK - CHECK_MONEY_MARKET - CREDIT - CREDIT_LINE_OF_CREDIT - CREDIT_INSTALLMENT_LOAN - CREDIT_MORTGAGE_LOAN - CREDIT_HOME_EQUITY_LOAN - CREDIT_COMMERCIAL_LOAN - UNIVERSAL - INVESTMENT - INVESTMENT_STOCK_OR_BOND - INVESTMENT_RETIREMENT_ACCOUNT - INVESTMENT_REVOLVING_LOAN_ACCOUNT - ELECTRONIC_PURSE_DEFAULT - STORED_VALUE - STORED_VALUE_SINGLE_DEPOSIT_SINGLE_USE - STORED_VALUE_SINGLE_DEPOSIT_MULTI_USE - STORED_VALUE_MULTI_DEPOSIT_MULTI_USE - EBT_CASH_BENEFIT - EBT_FOOD_STAMP example: DEFAULT toAccountType: pattern: >- DEFAULT| SAVINGS| CHECK| CREDIT| STORED_VALUE| STORED_VALUE_SINGLE_DEPOSIT_SINGLE_USE| STORED_VALUE_SINGLE_DEPOSIT_MULTI_USE| STORED_VALUE_MULTI_DEPOSIT_MULTI_USE| SAVINGS_MONEY_MARKET| SAVINGS_CERTIFICATE_OF_DEPOSIT|CHECK_MONEY_MARKET| CREDIT_LINE_OF_CREDIT| CREDIT_INSTALLMENT_LOAN| CREDIT_MORTGAGE_LOAN| CREDIT_HOME_EQUITY_LOAN| CREDIT_COMMERCIAL_LOAN| UNIVERSAL| INVESTMENT| INVESTMENT_STOCK_OR_BOND| INVESTMENT_RETIREMENT_ACCOUNT| INVESTMENT_REVOLVING_LOAN_ACCOUNT| ELECTRONIC_PURSE_DEFAULT| EBT_CASH_BENEFIT| EBT_FOOD_STAMP description: >- A value indicating the type of to account affected by the transaction. This is for capture(CP) transactions only. If no value is provided, the DEFAULT account type is used. enum: - DEFAULT - SAVINGS - SAVINGS_MONEY_MARKET - SAVINGS_CERTIFICATE_OF_DEPOSIT - CHECK - CHECK_MONEY_MARKET - CREDIT - CREDIT_LINE_OF_CREDIT - CREDIT_INSTALLMENT_LOAN - CREDIT_MORTGAGE_LOAN - CREDIT_HOME_EQUITY_LOAN - CREDIT_COMMERCIAL_LOAN - UNIVERSAL - INVESTMENT - INVESTMENT_STOCK_OR_BOND - INVESTMENT_RETIREMENT_ACCOUNT - INVESTMENT_REVOLVING_LOAN_ACCOUNT - ELECTRONIC_PURSE_DEFAULT - STORED_VALUE - STORED_VALUE_SINGLE_DEPOSIT_SINGLE_USE - STORED_VALUE_SINGLE_DEPOSIT_MULTI_USE - STORED_VALUE_MULTI_DEPOSIT_MULTI_USE - EBT_CASH_BENEFIT - EBT_FOOD_STAMP example: DEFAULT paymentIdentifier: pattern: '[a-zA-Z0-9]{0,28}' type: string format: AN28 description: >- 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. example: 0123456789abcdefghiJKLMNOPQR pinlessDebit: type: string pattern: true|false description: >- A flag that is used to attempt to route a transaction as debit at the processor level. example: 'true' enum: - true - false commercialCardType: pattern: '[a-zA-Z0-9]{2}' format: AN2 type: string description: This field indicates the type of commercial card used. example: CC payment.request.Cart: type: object description: >- The cart data structure holds product information about the shopping cart such as the product's ID, name, quantity and price. The cart items are identified by incrementing keys starting at 0 for each item.
Example:
"cart": {"items": {"0": {"xxxx": "yyy"},"1": {"xxxx": "yyy"}}} properties: items: type: object additionalProperties: $ref: '#/components/schemas/Item' example: '0': description: This item is nice. number: '001' customerCode: '45454545646464' vatReferenceNr: '64545645456454221' merchantItemId: genericItemId quantity: '1' unitOfMeasure: lbs totalAmount: '15.00' totalAmountType: NET totalAmountSign: 'C' sku: '11125455' price: '15.00' discountAmount: '1.50' discountAmountSign: 'C' discount: 100 supplyType: 01 payment.request.Fleet: description: >- The fleet data structure contain various fleet related fields. type: object properties: oilBrandName: pattern: '[0-9]{4}' type: string description: >- The acquirer's abbreviation for the brand name of the card acceptor's oil company. format: N4 example: 9988 serviceType: pattern: '[\s\S]{1}' type: string description: >- The type of service received at the card acceptor location. Valid values: * 1 - Self-service * 2 - Full service * 3 - Only non-fuel products purchased. format: ANS1 example: 1 vehicleUsage: pattern: 'P|B' type: string description: >- Valid values: * P - Private * B - Business format: ANS1 example: P enum: - P - B odometer: pattern: '[0-9]{8}' type: string description: The reading of the total distance travelled by the vehicle. format: N8 example: 11227788 vehicleReg: pattern: '[a-zA-Z0-9_]{17}' type: string description: The registration number of the rented or fleet vehicle. format: AN17 example: VREG543377FFGG444 driverId: pattern: '[a-zA-Z0-9_]{17}' type: string description: >- The number assigned to the driver by the employer for purposes of tracking fuel purchases. format: AN17 example: VREG543377FFGG444 promptCode: pattern: '[0-9]{1}' type: string description: >- Contains a code read from a card that indicates terminal prompts that occur at the point-of-service. Valid values: * 1 - Prompts for identification number and odometer reading * 2 - Prompts for vehicle number and odometer reading * 3 - Prompts for driver number and odometer reading * 4 - Prompts for odometer reading only * 5 - No prompts issued format: N1 example: 4 restrictionCode: pattern: '[\s\S]{1,3}' type: string description: Contains the restriction code that applies to the transaction. format: ANS3 example: 1 privateData: pattern: '[\s\S]{1,999}' type: string description: Any data proprietary to the system for this item. format: ANS999 example: This is private purchaseType: pattern: 'F|N|B' type: string description: >- The type of products purchased. Valid values: * F - Fuel * N - Non-fuel * B - Both format: A1 example: F enum: - F - N - B prompts: type: array items: $ref: '#/components/schemas/PromptData' example: '0': userId: UID5656MFNNNFF7 vehicleId: VID88558HB driverLicense: DL666HHAAFFT customerData: CD55444IIIUUDDD jobId: JOBID55555666D3 contractNumber: CNUMBER888FRT664AADF PIN: 885125 tripNumber: TRIP NUMBER 123 unitNumber: FLEETUNIT5 trailerId: TRAILER ID 12 trailerHours: 000008 maintenanceId: MAINTID12312312 hubometer: 000000009 employeeNumber: 666 driverLicenseState: CA vehicleLicense: VEHLIC123 vehicleLicenseState: CW trailerLicense: TL555 trailerLicenseState: CR fleetId: FID123 customData: THIS IS CUSTOM DATA vehicleTag: VEHTAG177 driverLicenseLocation: CAQ driverLicenseName: This is my name driverDateOfBirth: 19850212 vehicleVINNumber: VINNUM12366 pumpNumber: PUMPNUM3 tractorNumber: TRACT5554433546 '1': userId: UID44886655JJYH vehicleId: VID66653GH department: DEP6664hgggtt44 fleetBatchDataList: type: array items: $ref: '#/components/schemas/FleetBatchDataItem' example: '0': batchDate: 20210607 transactionCount: 0000001112 total: 00000111155544 totalUnit: Liters '1': batchDate: 20210809 transactionCount: 0000001113 total: 000007775354 totalUnit: Gallons payment.request.Customer: type: object description: The customer data structure holds information about the customer/shopper. properties: givenName: pattern: '[\s\S]{1,50}' type: string description: The first name or given name of the billing customer format: ANS50 example: Peter surname: pattern: '[\s\S]{1,50}' type: string description: The last name or surname of the billing customer. format: ANS50 example: Piper email: pattern: '[\s\S]{6,128}' type: string description: The customer's e-mail address. format: ANS128 example: Peter.Piper@email.com telephone: pattern: '[a-zA-Z0-9\.]{1,20}' type: string description: The customer's telephone number. The telephone number should be a string with a maximum length of 20 characters, allowing alphanumeric characters and periods. format: AN20 example: 021 567 5814 companyName: pattern: '[\s\S]{1,50}' type: string description: The customer's company name. format: ANS50 example: SomeCorp corporationVatNr: pattern: '[\s\S]{1,20}' type: string description: The merchant's VAT number. format: ANS20 example: 987654456789 vatNr: pattern: '[\s\S]{1,20}' type: string description: The customer's VAT number, used to identify the customer when reporting taxes. format: ANS20 example: 987654456789 provincialSalesTaxRegistrationNr: pattern: '[a-zA-Z0-9]{15}' type: string description: Provincial Sales Tax Registration Number. format: AN15 example: 999994444477777 orderNumber: pattern: '[\s\S]{1,25}' type: string description: The customer's purchase order number. format: ANS25 example: '12645' orderDate: pattern: '(19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1])' type: string description: The date when the order was placed. The date should be represented in the format YYYY-MM-DD, where YYYY represents the four-digit year, MM represents the two-digit month (01-12), and DD represents the two-digit day (01-31). format: AN10 example: '1912-06-23' orderTime: pattern: '[0-9]{6}' type: string description: The time when the order was placed should be represented as a 6-digit value in the format HHMMSS, where HH represents the hour in a 24-hour clock, MM represents the minutes, and SS represents the seconds. For example, the time 12:01:06 would be represented as 120106. format: N6 example: '120106' purchaseDate: pattern: '(19|20)([0-9]{2})-(0[1-9]|1[0-2])-(0[1-9]|1[0-9]|2[0-9]|3[0-1])' type: string description: The date of the purchase/invoice. The date should be represented in the format YYYY-MM-DD, where YYYY represents the four-digit year, MM represents the two-digit month (01-12), and DD represents the two-digit day (01-31). format: AN10 example: '2021-05-19' billingCode: pattern: '[\s\S]{1,20}' type: string description: A customer code supplied by the merchant. format: ANS20 example: '9988771122339911' taxExempt: pattern: true|false type: string description: Indicates whether the purchaser is tax-exempt. example: 'false' enum: - true - false fuelTaxExempt: pattern: TRUE|FALSE|Y|N type: string description: Indicates whether the fuel line items are tax exempt. example: 'FALSE' enum: - TRUE - FALSE - Y - N nonFuelTaxExempt: pattern: TRUE|FALSE|Y|N type: string description: Indicates whether the non-fuel line items are tax exempt. example: 'FALSE' enum: - TRUE - FALSE - Y - N from: $ref: '#/components/schemas/payment.request.Customer' example: givenName: Bettie surname: Black email: Bettie.Black@email.com telephone: '021 567 5814' companyName: SomeCorp orderNumber: '54321' orderDate: '1912-06-23' orderTime: '120106' purchaseDate: '2021-05-19' billingCode: '9988771122339911' taxExempt: 'false' fuelTaxExempt: 'Y' nonFuelTaxExempt: 'N' customerCode: FGHJKGT727950 merchantReferenceNumber: 4567yDGGFDrrrtw corporationVatNr: 987654456789 vatNr: 123456654321 provincialSalesTaxRegistrationNr: 999994444477777 customerCode: pattern: '[\s\S]{1,20}' type: string description: A code identifying the customer. format: ANS20 example: FGHJKGT727934 merchantReferenceNumber: pattern: '[\s\S]{1,28}' type: string description: >- Defines the payer account ID or some other form of reference information which will be provided to the payee. This information will typically appear on the payee's bank statement. format: ANS28 example: 4567yDGGFDrtttw DebtRepayment: type: object description: Contains debt repayment related information. properties: debtRepayment: type: boolean example: false description: >- When this flag is set to true, it indicates that this is a debt repayment transaction. payment.request.GooglePay: type: object description: When GooglePay is used as payment method. properties: paymentToken: pattern: '[\s\S]{1,8192}' type: string description: The encrypted payment token provided by Google. format: ANS8192 example: GooglePayPaymentToken nullable: true payment.request.Merchant: type: object description: Represents a business or seller that offers goods or services. properties: mcc: pattern: '[0-9]{4}' type: string format: N4 description: >- The Merchant Category Code (MCC) is used to classify the business by the type of goods or services it provides. example: 0234 street: pattern: '[\s\S]{1,23}' type: string format: ANS23 description: The street address and/or name of the merchant. example: Century Avenue city: pattern: '[\s\S]{1,13}' type: string format: ANS13 description: The city of the merchant. example: Cape Town state: pattern: '[A-Za-z0-9]{1,2}' type: string description: 'The county, state or region of the merchant.' format: AN2 example: WC country: pattern: '[A-Za-z]{2}' type: string description: The country of the merchant. format: AN2 example: ZA name: pattern: '[\s\S]{1,35}' type: string description: >- The name of the merchant. Based on upstream configuration, this could make up the first line on the cardholder statement for this transaction. format: ANS35 example: ACI Worldwide postcode: pattern: '[\s\S]{1,20}' type: string description: The post/zip code of the merchant. format: ANS20 example: 7441 phone: pattern: '[\s\S]{1,35}' type: string description: The phone number of the merchant. format: ANS35 example: 2721522500 submerchantId: pattern: '[a-zA-Z0-9]{1,15}' type: string description: >- 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. format: AN15 example: 112233445566789 receivingInstitutionCode: pattern: '[0-9]{1,11}' type: string format: N11 description: >- 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. example: 12345678901 taxId: pattern: '[\s\S]{1,20}' type: string description: The merchant’s national tax number. format: ANS20 example: 8423794 vatNr: pattern: '[\s\S]{1,20}' type: string description: The card acceptor's VAT number, used to identify the card acceptor when reporting taxes. format: ANS20 example: 6664446646 refNr: pattern: '[\s\S]{1,20}' type: string description: A reference number supplied by the card acceptor to facilitate communication and record keeping. format: ANS20 example: 7774447747 invoiceDiscountTreatment: pattern: '[a-zA-Z0-9]{1}' type: string description: Indicates how the merchant is managing discounts. format: AN1 example: 3 taxTreatment: pattern: '[a-zA-Z0-9]{1}' type: string description: Indicates how the merchant is handling taxes. format: AN1 example: 3 streetAddress: pattern: '[\s\S]{1,48}' type: string description: A street address associated with the merchant or card acceptor. format: ANS48 example: Century Avenue, Century City, Cape Town, 7441 countrySubDivisionCode: pattern: '[a-zA-Z0-9]{3}' type: string description: A state or province code for the retailer associated with the merchant or card acceptor. format: ANS3 example: 123 url: pattern: '[\s\S]{1,255}' type: string description: A website address for the retailer associated with the merchant or card acceptor. This field should be present for e-commerce transactions if available. format: ANS255 example: https://www.mymerchantsite.com/ customerServicePhoneNumber: pattern: '[\s\S]{1,16}' type: string description: A customer service phone number for the retailer associated with the merchant or card acceptor. format: ANS16 example: 2721522500 additionalContactInformation: pattern: '[\s\S]{1,25}' type: string description: May contain additional information, such as secondary phone numbers, customer service operation hours, and contact name. format: ANS25 example: Contact Name - Sven Blackbeard partnerIdCode: pattern: '[\s\S]{1,6}' type: string description: A partner ID established between the merchant or card acceptor and the issuer. format: ANS6 example: 665544 serviceLocationCityName: pattern: '[\s\S]{1,13}' type: string description: The city of the location of the physical interaction with the customer. format: ANS13 example: Century City serviceLocationCountrySubdivisionCode: pattern: '[a-zA-Z0-9]{2,3}' type: string description: The state or province of the location of the physical interaction with the customer. format: ANS3 example: 655 serviceLocationCountryCode: pattern: '[A-Za-z]{2}' type: string description: The country code of the location of the physical interaction with the customer. format: ANS2 example: ZA serviceLocationPostalCode: pattern: '[\s\S]{1,10}' type: string description: The postal code of the location of the physical interaction with the customer. format: ANS10 example: 7441 payment.request.Pos: type: object description: Defines a system or device used by merchants to facilitate transactions with customers at the physical point of sale. properties: storeId: pattern: '[\s\S]{1,15}' type: string description: Store identifier assigned by the acquirer. format: ANS15 example: 78123753 terminalId: pattern: '[\s\S]{8}' type: string description: The terminal identifier assigned by the acquirer. format: ANS8 example: 12195611 cvv2Availability: pattern: NOT_PROVIDED|ILLEGIBLE|NO_CVV2_ON_CARD type: string description: >- 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. enum: - NOT_PROVIDED - ILLEGIBLE - NO_CVV2_ON_CARD example: ILLEGIBLE entryMode: pattern: >- MAGSTRIPE|MANUAL|CREDENTIAL_ON_FILE|UNKNOWN|NFC_ICC|NFC_MAGSTRIPE|ICC|SAME_AS_ORIGINAL|ICC_CVV_UNRELIABLE|MAGSTRIPE_AS_FALLBACK|MAGSTRIPE_TO_MANUAL|CONTACTLESS_TO_ICC|CONTACTLESS_TO_MAGSTRIPE|MAGSTRIPE_CVV_UNRELIABLE|BARCODE|OCR type: string enum: - MAGSTRIPE - MANUAL - CREDENTIAL_ON_FILE - UNKNOWN - NFC_ICC - NFC_MAGSTRIPE - ICC - SAME_AS_ORIGINAL - ICC_CVV_UNRELIABLE - MAGSTRIPE_AS_FALLBACK - MAGSTRIPE_TO_MANUAL - CONTACTLESS_TO_ICC - CONTACTLESS_TO_MAGSTRIPE - MAGSTRIPE_CVV_UNRELIABLE - BARCODE - OCR example: MANUAL description: The interface that was used by the terminal for the transaction. pinEntryCapability: pattern: UNKNOWN|PIN_ENTRY_AVAILABLE|PIN_ENTRY_UNAVAILABLE type: string enum: - UNKNOWN - PIN_ENTRY_AVAILABLE - PIN_ENTRY_UNAVAILABLE example: UNKNOWN description: >- Indicates if the point-of-service can accept PINs. If not inferred to PIN_ENTRY_AVAILALBLE by pos.cardholderAuthenticationMethod, pos.pinEntryCapability, or the presence of PIN data, UNKNOWN is used. cardDataInputMode: pattern: >- UNKNOWN|MANUAL|MAGSTRIPE|BARCODE|OCR|ICC|KEY_ENTRY|NFC_ICC|NFC_MAGSTRIPE type: string enum: - UNKNOWN - MANUAL - MAGSTRIPE - BARCODE - OCR - ICC - KEY_ENTRY - NFC_ICC - NFC_MAGSTRIPE example: KEY_ENTRY description: >- 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. cardDataInputCapability: pattern: >- UNKNOWN|MANUAL_NO_TERMINAL|MAGSTRIPE|BARCODE|OCR|MAGSTRIPE_MANUAL_ICC|MANUAL|MAGSTRIPE_MANUAL|MAGSTRIPE_ICC|ICC|NFC_ICC|MAGSTRIPE_MANUAL_ICC_NFC|NFC_MAGSTRIPE type: string enum: - UNKNOWN - MANUAL_NO_TERMINAL - MAGSTRIPE - BARCODE - OCR - MAGSTRIPE_MANUAL_ICC - MANUAL - MAGSTRIPE_MANUAL - MAGSTRIPE_ICC - ICC - NFC_ICC - MAGSTRIPE_MANUAL_ICC_NFC - NFC_MAGSTRIPE example: BARCODE description: >- 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. cardholderAuthenticationCapability: pattern: NONE|PIN|ELECTRONIC_SIGNATURE|BIOMETRIC|BIOGRAPHIC|INOPERATIVE|OTHER type: string enum: - NONE - PIN - ELECTRONIC_SIGNATURE - BIOMETRIC - BIOGRAPHIC - INOPERATIVE - OTHER example: PIN description: >- 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. cardCaptureCapability: pattern: NONE|CAPTURE type: string enum: - NONE - CAPTURE example: NONE description: >- 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. operatingEnvironment: pattern: >- NO_TERMINAL|MERCHANT_ATTENDED|MERCHANT_UNATTENDED|OFFSITE_ATTENDED|OFFSITE_UNATTENDED|CUSTOMER_UNATTENDED type: string enum: - NO_TERMINAL - MERCHANT_ATTENDED - MERCHANT_UNATTENDED - OFFSITE_ATTENDED - OFFSITE_UNATTENDED - CUSTOMER_UNATTENDED example: NO_TERMINAL description: >- 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. cardholderPresent: pattern: CARD_HOLDER_PRESENT|CARD_HOLDER_NOT_PRESENT type: string example: CARD_HOLDER_PRESENT enum: - CARD_HOLDER_PRESENT - CARD_HOLDER_NOT_PRESENT description: >- 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. cardPresent: pattern: CARD_PRESENT|CARD_NOT_PRESENT type: string example: CARD_PRESENT enum: - CARD_PRESENT - CARD_NOT_PRESENT description: >- 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. cardholderAuthenticationMethod: pattern: >- NONE|PIN|ELECTRONIC_SIGNATURE|BIOMETRIC|BIOGRAPHIC|INOPERATIVE|OTHER|CDCVM|CDCVM_CODE|CDCVM_PATTERN|CDCVM_BIOMETRIC|UNKNOWN type: string enum: - NONE - PIN - ELECTRONIC_SIGNATURE - BIOMETRIC - BIOGRAPHIC - INOPERATIVE - OTHER - CDCVM - CDCVM_CODE - CDCVM_PATTERN - CDCVM_BIOMETRIC - UNKNOWN example: NONE description: >- 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. cardholderAuthenticationEntity: pattern: NOT_AUTHENTICATED|ICC|TERMINAL|AUTHORIZING_AGENT|MERCHANT|OTHER type: string example: NOT_AUTHENTICATED enum: - NOT_AUTHENTICATED - ICC - TERMINAL - AUTHORIZING_AGENT - MERCHANT - OTHER description: >- 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. cardDataOutputCapability: pattern: NONE|MAGSTRIPE|ICC|UNKNOWN type: string example: NONE enum: - NONE - MAGSTRIPE - ICC - UNKNOWN description: >- 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. terminalOperator: pattern: CUSTOMER|MERCHANT|ADMIN type: string description: >- Indicates who is operating the point-of-service. If not inferred by pos.entryMode or transactionCategory, CUSTOMER is used. enum: - CUSTOMER - MERCHANT - ADMIN example: MERCHANT terminalType: pattern: ADMIN|ATM|AUTHORIZATION|BUSINESS_BANKING|COUPON|DIAL|ECOM|ECOM_SECURE_CHIP_NO_CRDHLDR_AUTH|ECOM_SECURE_NO_CRDHLDR_AUTH|ECOM_SET_CHIP_CRDHLDR_AUTH|ECOM_SET_CHIP_NO_CRDHLDR_AUTH|ECOM_SET_CRDHLDR_AUTH|ECOM_SET_NO_CRDHLDR_AUTH|ECR|FRANCHISE_TELLER|FUEL|HOME|INTERACTIVE_TELEVISION|MOBILE_POS|PAYMENT|PERSONAL_BANKING|PERSONAL_DIGITAL_ASSISTANT|POINT_OF_BANKING|POS|PUBLIC_UTILITY|SCREEN_PHONE|SCRIP|SELF_SERVICE|SMART_PHONE|TELLER|TICKET|TRAVELERS_CHECK|VENDING|VRU| type: string description: >- The type of terminal used to initiate the transaction. If no value is provided, the value is determined from the Transaction Category, if possible. enum: - ADMIN - ATM - AUTHORIZATION - BUSINESS_BANKING - COUPON - DIAL - ECOM - ECOM_SECURE_CHIP_NO_CRDHLDR_AUTH - ECOM_SECURE_NO_CRDHLDR_AUTH - ECOM_SET_CHIP_CRDHLDR_AUTH - ECOM_SET_CHIP_NO_CRDHLDR_AUTH - ECOM_SET_CRDHLDR_AUTH - ECOM_SET_NO_CRDHLDR_AUTH - ECR - FRANCHISE_TELLER - FUEL - HOME - INTERACTIVE_TELEVISION - MOBILE_POS - PAYMENT - PERSONAL_BANKING - PERSONAL_DIGITAL_ASSISTANT - POINT_OF_BANKING - POS - PUBLIC_UTILITY - SCREEN_PHONE - SCRIP - SELF_SERVICE - SMART_PHONE - TELLER - TICKET - TRAVELERS_CHECK - VENDING - VRU example: POS terminalOutputCapability: pattern: UNKNOWN|NONE|PRINT|DISPLAY|PRINT_AND_DISPLAY type: string description: >- Indicates the ability of the terminal to print or display messages. enum: - UNKNOWN - NONE - PRINT - DISPLAY - PRINT_AND_DISPLAY example: PRINT pinCaptureCapability: pattern: NONE|UNKNOWN|4|5|6|7|8|9|10|11|12 type: string enum: - NONE - UNKNOWN - 4 - 5 - 6 - 7 - 8 - 9 - 10 - 11 - 12 example: UNKNOWN description: >- 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. scaExemptionFlag: pattern: PIN_PROVIDED|TAP_AND_PIN_SUPPORTED type: string example: PIN_PROVIDED enum: - PIN_PROVIDED - TAP_AND_PIN_SUPPORTED description: >- 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. iccDataRequest: pattern: '[a-fA-F0-9]{1,20000}' type: string description: >- 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. format: ANS2048 example: >- 9F3303E0F0C89F03060000000000009F02060000000101008407A000000003101082025C009F260891927070405962B15F2A0207109F1A0207109C01009A031406279F100706010A03A00000950500800088009F3704ECB178479F3602028C67010F encryptedPin: $ref: '#/components/schemas/EncryptedPin' p2peEncrypted: $ref: '#/components/schemas/P2peEncrypted' fallbackReason: pattern: CARD_UNREADABLE|CHIP_ERROR|NO_SUPPORTED_APPLICATION type: string description: >- Indicates the reason for a fallback transaction when pos.entryMode is set to a fallback value. enum: - CARD_UNREADABLE - CHIP_ERROR - NO_SUPPORTED_APPLICATION example: CARD_UNREADABLE operatorId: pattern: '[\s\S]{1,35}' type: string description: Identifies the operator that initiated the transaction. format: ANS35 example: '123321' posId: pattern: '[\s\S]{1,35}' type: string description: Identifies the device that initiated the transaction. format: ANS35 example: '98778912' transactionSequenceNumber: pattern: '[\s\S]{1,35}' type: string description: >- Identifies the transaction on the device that initiated the transaction. format: ANS35 example: '66611234' localDateTime: pattern: '(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])' type: string description: >- 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. format: 'MM-dd HH:mm:ss' example: '01-01 10:30:30' payment.request.StandingInstruction: type: object description: Standing instruction related fields used to facilitate recurring, installment or unscheduled payments. properties: type: pattern: UNSCHEDULED|RECURRING|INSTALLMENT type: string description: >- The Standing Instruction type identifying whether the transaction is a recurring payment, installment payment, or unscheduled payment. enum: - UNSCHEDULED - RECURRING - INSTALLMENT example: UNSCHEDULED mode: pattern: INITIAL|REPEATED type: string description: >- The Standing Instruction mode identifying whether this is the first transaction or a subsequent transaction in a series. This field must be set to INITIAL for CIT Initial requests and Unscheduled MIT requests. This field must be set to REPEATED for CIT Subsequent (pos.entryMode is set to CREDENTIAL_ON_FILE) and Recurring/Installment MIT requests. enum: - INITIAL - REPEATED example: INITIAL source: pattern: CIT|MIT type: string description: >- The Standing Instruction source identifying whether a Customer- or Merchant-Initiated Transaction has been received. enum: - CIT - MIT example: CIT industryPractice: pattern: >- INCREMENTAL_AUTH|RESUBMISSION|REAUTHORIZATION|DELAYED_CHARGES|NO_SHOW type: string description: >- This field is used to specify if an industry practice applies to the transaction. This field cannot be specified in addition to standingInstruction.type. enum: - INCREMENTAL_AUTH - RESUBMISSION - REAUTHORIZATION - DELAYED_CHARGES - NO_SHOW example: INCREMENTAL_AUTH payment.request.EmvFileDownload: type: object description: Contains EMV file download related fields. properties: fileVersion: pattern: '[\\s\\S]{1,99}' type: string format: ANS99S example: "12345678" description: Free form field containing the file version information. payment.request.ThreeDSecure: type: object description: >- The 3D secure data structure is used to hold authentication data generated by the 3D secure MPI when an external MPI is being used, or additional information about the authentication. If 3D data is present which indicates the usage of an external MPI (xid, eci, verificationId), the payment gateway will just pass through these values to the acquiring system. properties: xid: pattern: '[0-9a-zA-Z/+=]{1,64}' type: string description: >- 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. format: AN64 (Base64 encoded) example: VGhpcyBpcyBhIHNhbXBsZSB4aWQ= verificationId: pattern: '[0-9a-zA-Z/+=]{1,56}' type: string description: >- The VerificationID field contains the base64 encoded Cardholder Authentication Verification Value (CAVV), Authentication Verification Value (AVV), or Universal Cardholder Authentication (UCAF) Field (MasterCard). This field is mandatory if a third-party MPI (merchant plug-in) performed the 3d Secure authentication. format: AN56 (Base64 encoded) example: c2FtZSBhcyBvdGhlciB2YWx1ZXM= ucafCollectionIndicator: pattern: '[0-7]{1}' type: string description: |- The ucafCollectionIndicator field represents the Mastercard UCAF Collection Indicator. This field describes the UCAF collection status. If no UCAF Collection Indicator value is provided a derived value will be set based on the supplied ECI (Electronic commerce indicator) value. Possible values are: * 0 - No Authentication: UCAF data collection is not supported at the merchant. * 1 - Attempted Authentication: UCAF data collection is supported by the merchant, but was unable to complete the authentication. * 2 - Full Authentication: UCAF data collection is supported by the merchant and the UCAF data was populated. * 3 - Static Authentication: UCAF data collection is supported by the merchant and UCAF data is present as the Mastercard assigned Static Accountholder Authentication Value (AAV). * 4 - Insights Authentication: Merchant has chosen to share authentication data within authorization and UCAF data is present as the Insights AAV for Mastercard Identity Check. * 5 - Issuer Risk Based Decisioning. * 6 - Merchant Risk Based Decisioning. * 7 - Partial shipment or recurring payment (Liability will depend on the original UCAF values provided). format: N1 enum: ["0","1","2","3","4","5","6","7"] example: '3' tavv: pattern: '[0-9a-zA-Z/+=]{1,56}' type: string description: >- 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. format: AN56 (Base64 encoded) example: c2FtZSBhcyBvdGhlciB2YWx1ZXM= eci: pattern: '0[0|1|2|3|5|6|7]{1}' type: string description: |- The Electronic Commerce Indicator (ECI) is a value used to indicate the level of authentication that occurred during the payment process. The ECI value can vary depending on the card network and payment method utilized. Possible values are: * 00 - Non 3-D Secure Transaction (MasterCard) * 01 - Attempted Authentication Transaction (MasterCard) * 02 - Fully Authenticated Transaction (MasterCard) * 05 - Fully Authenticated Transaction (Visa, Amex, JCB, Diners) * 06 - Attempted Authentication Transaction (Visa, Amex, JCB, Diners) * 07 - Non 3-D Secure Transaction (Visa, Amex, JCB, Diners) format: N2 example: '05' enum: ["00","01","02","05","06","07"] dsTransactionId: pattern: '[\s\S]{1,36}' type: string description: >- 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. format: ANS36 example: c5b808e7-1de1-4069-a17b-f70d3b3b1645 version: pattern: '[2].?[0-9]?.?[0-9]?' type: string description: >- 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. format: ANS5 example: 2.0.0 authenticationMethod: pattern: '[0-9A-Z]{1}' type: string description: |- The authenticationMethod field represents the specific method or approach used for 3-D Secure authentication during a transaction. It provides information about how the cardholder was authenticated. Possible values are: * 0 - All authentication methods * 1 - Challenge flow using static passcode * 2 - Challenge flow using OTP via SMS method * 3 - Challenge flow using OTP via key fob or card reader method * 4 - Challenge flow using OTP via App method * 5 - Challenge flow using OTP via any other method * 6 - Challenge flow using KBA method * 7 - Challenge flow using OOB with biometric method * 8 - Challenge flow using OOB with App login method * 9 - Challenge flow using OOB with any other method * A - Challenge flow using any other authentication method * D - Frictionless flow, RBA review * E - Attempts server responding * F - Frictionless flow, RBA format: ANS1 example: 0 enum: ["0","1","2","3","4","5","6","7","8","9","A","D","E","F"] exemptionFlag: pattern: '0[1-4]{1}' type: string description: |- The exemptionFlag field indicates whether an exemption from 3-D Secure authentication has been applied to the transaction. It provides information about whether the transaction qualifies for an exemption based on specific criteria defined by regulatory requirements or card network rules. ​ Possible values are: * 01 - Low value transaction exemption * 02 - Low risk transaction exemption * 03 - Trusted Beneficiary exemption * 04 - Secure Corporate Payment transaction exemption format: N2 example: '01' enum: ["01","02","03","04"] Balances: description: >- The balances data structure. type: object properties: availableBalance: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: Indicates the available balance for the account. The available balance is is the amount available for withdrawal at any given moment. The available balance changes with any transaction that has financial impact. This is an optional field in all payment response messages. format: N8.N4 example: '100.00' ledgerBalance: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: Indicates the ledger balance for the account. The ledger balance is the remaining balance at the end of the business day. The ledger balance will only reflect financial transactions processed during the business day.This is an optional field in all payment response messages. format: N8.N4 example: '100.00' AdditionalAmounts: description: >- The additional amounts response data structure. type: object properties: approvedAmount: pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' type: string description: Indicates the approved amount for the account. This is an optional field in all payment response messages. format: N8.N4 example: '100.00' PaymentResponse: type: object properties: id: type: string example: 'e8f59d02a466f35a7ece785d3e137e50' format: AN32 pattern: '[a-zA-Z0-9]{1,32}' description: 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. result: $ref: '#/components/schemas/Result' timestamp: type: string example: '2025-10-28 15:24:22' pattern: '(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])' description: The timestamp generated by the response in UTC. customParameters: $ref: '#/components/schemas/CustomParameters' resultDetails: $ref: '#/components/schemas/ResultDetails' amount: type: string description: >- Indicates the total amount of the payment request (including all tax, duty, shipping, and discount amounts). If the convenienceFee or cashbackAmount parameters are also provided, they must be included in this amount. If the applePay.paymentToken parameter is provided, the amount within the token is compared to this field, or this field overrides the token amount. This is based on upstream configuration. A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator. For example, to specify one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. To specify zero dollars and 50 cents, the following value would be supplied: 0.50. pattern: '[0-9]{1,8}(\.[0-9]{1,4})?' format: N8.N4 example: '100.00' currency: type: string description: >- The currency code of the payment request’s amount (ISO 4217).The default currency used is "USD".For a Reversal Request, this field is only required for partial reversals. If provided, this field must match the currency of the original transaction. pattern: '[A-Z]{3}' format: A3 example: USD tokenId: pattern: '[a-zA-Z0-9]{1,255}' type: string description: A token representing sensitive cardholder data. format: AN255 example: JYO7rdR5UjK61111 paymentAccountReference: type: string description: The payment account reference number pattern: '[a-zA-Z0-9]{0,29}' format: AN29 example: 123456789ljhtf balances: $ref: '#/components/schemas/Balances' additionalAmounts: $ref: '#/components/schemas/AdditionalAmounts' threeDSecure: $ref: '#/components/schemas/payment.response.ThreeDSecure' pos: $ref: '#/components/schemas/payment.response.Pos' card: $ref: '#/components/schemas/payment.response.Card' fleet: $ref: '#/components/schemas/payment.response.FleetResponse' emvFileDownload: $ref: '#/components/schemas/payment.response.EmvFileDownload' ThreeDSecure: type: object properties: result: type: string description: 'Contains the 3-D Secure result (for example, CAVV or AAV).' pattern: >- UNABLE_TO_VALIDATE_RESULTS_INVALID|VALIDATION_FAILED_AUTHENTICATION|VALIDATION_PASSED_AUTHENTICATION|VALIDATION_PASSED_ATTEMPTED_AUTH|VALIDATION_FAILED_ATTEMPTED_AUTH|NOT_VALIDATED_ISSUER_NOT_PARTICIPATING|VALIDATION_FAILED_ATTEMPTED_AT_ACS|VALIDATION_PASSED_ATTEMPTED_AT_ACS|VALIDATION_FAILED_ATTEMPTED_AT_STAND_IN|VALIDATION_PASSED_ATTEMPTED_AT_STAND_IN|VALIDATION_PASSED_NO_LIABILITY_SHIFT|NOT_VALIDATED_ATTEMPTED_AUTH|NOT_VALIDATED_AUTHENTICATION enum: - UNABLE_TO_VALIDATE_RESULTS_INVALID - VALIDATION_FAILED_AUTHENTICATION - VALIDATION_PASSED_AUTHENTICATION - VALIDATION_PASSED_ATTEMPTED_AUTH - VALIDATION_FAILED_ATTEMPTED_AUTH - NOT_VALIDATED_ISSUER_NOT_PARTICIPATING - VALIDATION_FAILED_ATTEMPTED_AT_ACS - VALIDATION_PASSED_ATTEMPTED_AT_ACS - VALIDATION_FAILED_ATTEMPTED_AT_STAND_IN - VALIDATION_PASSED_ATTEMPTED_AT_STAND_IN - VALIDATION_PASSED_NO_LIABILITY_SHIFT - NOT_VALIDATED_ATTEMPTED_AUTH - NOT_VALIDATED_AUTHENTICATION example: VALIDATION_PASSED_AUTHENTICATION payment.response.Card: description: >- The card response data structure. type: object properties: pinlessDebit: type: string pattern: CREDIT|DEBIT description: >- Indicates whether the transaction was processed as a credit or a debit transaction by the processor. enum: - CREDIT - DEBIT example: DEBIT payment.response.Pos: description: >- The pos response data structure contains pos response fields. type: object properties: localDateTime: type: string pattern: '(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])' description: >- 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. example: "12-31 23:59:59" iccDataResponse: type: string format: AN2048 pattern: '[a-fA-F0-9]{1-20000}' description: >- 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. example: 9F3303E0F0C89F03060202 payment.response.FleetResponse: description: >- The fleet response data structure contains various response fields. type: object properties: promptForOdometer: type: string format: N1 pattern: '[0-9]{1}' description: The prompt is required to complete the transaction or not. example: 1 printPricePerGallon: type: string format: AN1 pattern: '[a-zA-Z0-9_]{1}' description: >- This field identifies if price per gallon needs to be printed on customer receipt. example: 2 maximumPurchaseAmount: type: string format: N12 pattern: '[0-9]{1,12}' description: >- The maximum purchase amount in minor denomination in the currency of the transaction. example: 000000001111 maximumOilAmount: type: string format: N12 pattern: '[0-9]{1,12}' description: >- The maximum oil amount in minor denomination in the currency of the transaction. example: 000000002222 maximumPartsAmount: type: string format: N12 pattern: '[0-9]{1,12}' description: >- The maximum parts amount in minor denomination in the currency of the transaction. example: 000000003333 maximumAmountOther: type: string format: N12 pattern: '[0-9]{1,12}' description: >- The maximum other amount in minor denomination in the currency of the transaction. example: 000000004444 payment.response.EmvFileDownload: description: >- The EMV file download response data structure. type: object properties: fileVersion: pattern: '[\\s\\S]{1,99}' type: string format: ANS99S example: "12345678" description: Free form field containing the file version information. blockNumber: pattern: '[\\s\\S]{1,50}' type: string format: ANS50S example: "ABC1234567890" description: Indicates the block number or offset of the current download. downloadIndicator: type: string description: Indicates download status. pattern: REQUIRED|NOT_REQUIRED|IN_PROGRESS|COMPLETED|ERROR|SUCCESSFUL example: REQUIRED enum: [REQUIRED,NOT_REQUIRED,IN_PROGRESS,COMPLETED,ERROR,SUCCESSFUL] caPkf: pattern: '[\\s\\S]{1,9999}' type: string format: ANS9999 example: "20251212,01,01,A000001000,02,AB9A23F8H32D5E327CFF;2024" description: Contain a partial CA PKF file in the eSocket.POS EMV Download file format. RkdExchangeRequest: type: object properties: customParameters: $ref: '#/components/schemas/CustomParameters' entityId: type: string description: >- The entityId is used in conjunction with the HTTP Authorization header to specify the entity associated with the request. When requesting new user credentials from ACI, the entityID will be provided to you. format: AN32 pattern: '[a-f0-9]{32}' example: entity1pbx08d4bdeb27e205d70a9ab3 rkdScheme: pattern: '[\s\S]{1,32}' type: string description: >- Indicates the Remote Key Distribution (RKD) scheme in use. Please contact ACI for this value. format: AN32 example: SCHEME_NAME keyStatus: pattern: VALID|NOT_PRESENT|EXPIRED|COMPROMISED|REVOKED|INVALID enum: - VALID - NOT_PRESENT - EXPIRED - COMPROMISED - REVOKED - INVALID type: string description: |- Indicates the status of the current P2PE key. Possible values: * COMPROMISED - The P2PE key on the PED has been compromised. * EXPIRED - The P2PE key on the PED has expired. * INVALID - The P2PE key on the PED is invalid. * NOT_PRESENT - There is currently no P2PE key available on the PED. * REVOKED - The P2PE key on the PED has been revoked. * VALID - The P2PE key available on the PED is valid. example: VALID rkdRequestData: pattern: '[a-fA-F0-9]{1,65535}' type: string description: >- 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. format: AN65535 example: '323833313132343534' deviceName: pattern: '[\s\S]{1,32}' type: string description: >- An identifiable name for the PED involved in the key exchange. Examples include Ingenico_RBA, Verifone_FORMAGENT, SC5000, and VX810 format: AN32 example: VERIFONE rkdEchoData: pattern: '[a-zA-Z0-9]{1,32}' type: string description: The echo data value sent in the RKD exchange response. format: AN32 example: '1234567890' rkdKeyConfirmationData: pattern: '[a-fA-F0-9]{1,65535}' type: string description: >- Key confirmation data from the PED after attempting to apply a key supplied in a previous RKD exchange. The field format is dependent on the type of Remote Key Distribution scheme used (the value of rkdScheme). For more information on formatting this field, refer to the respective vendor’s RKD documentation. The field contains binary data encoded as a hex string format: AN65535 example: 3238333131323435347c4b45595f554e5041434b5f53554343455353 pos: $ref: '#/components/schemas/rkd.request.Pos' rkd.request.Pos: description: Defines a system or device used by merchants to facilitate transactions with customers at the physical point of sale. type: object properties: terminalId: pattern: '[\s\S]{8}' type: string description: The terminal identifier assigned by the acquirer. format: ANS8 example: 12195611 RkdExchangeResponse: type: object properties: id: type: string example: 'e8f59d02a466f35a7ece785d3e137e50' format: AN32 pattern: '[a-zA-Z0-9]{1,32}' description: 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. result: $ref: '#/components/schemas/Result' timestamp: type: string example: '2025-10-28 15:24:22' pattern: '(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])' description: The timestamp generated by the response in UTC. customParameters: $ref: '#/components/schemas/CustomParameters' resultDetails: $ref: '#/components/schemas/ResultDetails' NwrkManagementRequest: type: object properties: customParameters: $ref: '#/components/schemas/CustomParameters' entityId: type: string description: >- The entityId is used in conjunction with the HTTP Authorization header to specify the entity associated with the request. When requesting new user credentials from ACI, the entityID will be provided to you. format: AN32 pattern: '[a-f0-9]{32}' example: entity1pbx08d4bdeb27e205d70a9ab3 pos: $ref: '#/components/schemas/nwrkmng.request.Pos' merchant: $ref: '#/components/schemas/nwrkmng.request.Merchant' settlementDate: pattern: '[0-9]{4}' type: string description: The month and day for which financial totals are reconciled. format: N4 example: "1012" infoCode: pattern: >- 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 type: string enum: [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] description: The network management information code associated with the request. example: NEW_KEY emvFileDownload: $ref: '#/components/schemas/nwrkmng.request.EmvFileDownload' nwrkmng.request.EncryptedPin: type: object properties: ksn: pattern: '[a-fA-F0-9]{1,2048}' type: string format: AN2048 description: The key serial number. example: >- FFFF12345612342000010000000000000000000000000000000000000000000000000000000000000000000000000000 nwrkmng.request.Merchant: description: Represents a business or seller that offers goods or services. type: object properties: receivingInstitutionCode: pattern: '[0-9]{1,11}' type: string format: N11 description: >- A code identifying the financial institution that should receive a message. When present, this value is used to calculate the route for a message. example: "11111111111" forwardingInstitutionCode: pattern: '[0-9]{1,11}' format: N11 type: string example: "22222222222" description: >- A code identifying the financial institution that forwards the transaction to the card issuer. When present, this value is used to calculate the route for a message. acquiringInstitutionCode: pattern: '[0-9]{1,11}' type: string format: N11 example: "33333333333" description: >- A code identifying the financial institution acting as the acquirer of the transaction. When present, this value is used to calculate the route for a message. nwrkmng.request.Pos: description: Defines a system or device used by merchants to facilitate transactions with customers at the physical point of sale. type: object properties: encryptedPin: $ref: '#/components/schemas/nwrkmng.request.EncryptedPin' terminalId: pattern: '[\s\S]{8}' type: string format: ANS8 example: "12345678" description: The terminal identifier assigned by the acquirer. storeId: pattern: '[\s\S]{1,15}' type: string format: ANS15 example: "ABC1234567890" description: The store identifier assigned by the acquirer. terminalOperator: pattern: '[\s\S]{1,999}' type: string format: ANS999 example: 12345678 description: The terminal operator. nwrkmng.request.EmvFileDownload: type: object properties: fileVersion: pattern: '[\\s\\S]{1,99}' type: string format: ANS99S example: "12345678" description: Free form field containing the file version information. blockNumber: pattern: '[\\s\\S]{1,50}' type: string format: ANS50S example: "ABC1234567890" description: Indicates the block number or offset of the current download. downloadIndicator: type: string description: Indicates download status. pattern: REQUIRED|NOT_REQUIRED|IN_PROGRESS|COMPLETED|ERROR|SUCCESSFUL example: REQUIRED enum: [REQUIRED,NOT_REQUIRED,IN_PROGRESS,COMPLETED,ERROR,SUCCESSFUL] NwrkManagementResponse: type: object properties: id: type: string example: 'e8f59d02a466f35a7ece785d3e137e50' format: AN32 pattern: '[a-zA-Z0-9]{1,32}' description: 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. result: $ref: '#/components/schemas/Result' timestamp: type: string example: '2025-10-28 15:24:22' pattern: '(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])' description: The timestamp generated by the response in UTC. emvFileDownload: $ref: '#/components/schemas/EmvFileDownload' customParameters: $ref: '#/components/schemas/CustomParameters' resultDetails: $ref: '#/components/schemas/ResultDetails' APMDecryptRequest: type: object properties: customParameters: $ref: '#/components/schemas/CustomParameters' entityId: type: string description: >- The entityId is used in conjunction with the HTTP Authorization header to specify the entity associated with the request. When requesting new user credentials from ACI, the entityID will be provided to you. format: AN32 pattern: '[a-f0-9]{32}' example: entity1pbx08d4bdeb27e205d70a9ab3 applePay: $ref: '#/components/schemas/apmdecrypt.request.ApplePay' googlePay: $ref: '#/components/schemas/apmdecrypt.request.GooglePay' merchant: $ref: '#/components/schemas/apmdecrypt.request.Merchant' pos: $ref: '#/components/schemas/apmdecrypt.request.Pos' paymentBrand: pattern: APPLEPAY|GOOGLEPAY type: string description: >- The payment brand used to identify alternative payment method transactions. enum: - APPLEPAY - GOOGLEPAY example: APPLEPAY apmdecrypt.request.ApplePay: type: object properties: paymentToken: pattern: '[\s\S]{1,8192}' type: string description: The encrypted payment token provided by Apple. format: ANS8192 example: ApplePayTokenXYZ apmdecrypt.request.GooglePay: type: object properties: paymentToken: pattern: '[\s\S]{1,8192}' type: string description: The encrypted payment token provided by Google format: ANS8192 example: GooglePayTokenXYZ apmdecrypt.request.Merchant: description: Represents a business or seller that offers goods or services. type: object properties: street: pattern: '[\s\S]{1,23}' type: string format: ANS23 description: The street address and/or name of the merchant. example: Century Avenue city: pattern: '[\s\S]{1,13}' type: string format: ANS13 description: The city of the merchant. example: Cape Town state: pattern: '[A-Za-z0-9]{1,2}' type: string description: 'The county, state or region of the merchant.' format: AN2 example: WC country: pattern: '[A-Za-z]{2}' type: string description: The country of the merchant. format: AN2 example: ZA apmdecrypt.request.Pos: type: object properties: storeId: pattern: '[\s\S]{1,15}' type: string description: Store identifier assigned by the acquirer. format: ANS15 example: 78123753 terminalId: pattern: '[\s\S]{8}' type: string description: The terminal identifier assigned by the acquirer. format: ANS8 example: 12195611 APMDecryptResponse: type: object properties: id: type: string example: 'e8f59d02a466f35a7ece785d3e137e50' format: AN32 pattern: '[a-zA-Z0-9]{1,32}' description: 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. result: $ref: '#/components/schemas/Result' timestamp: type: string example: '2025-10-28 15:24:22' pattern: '(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])' description: The timestamp generated by the response in UTC. customParameters: $ref: '#/components/schemas/CustomParameters' resultDetails: $ref: '#/components/schemas/ResultDetails' amount: type: string format: N8.N4 example: "10.00" pattern: "[0-9]{1,8}(\\.[0-9]{1,4})?" description: |- Indicates the amount present in the payment token.A period (.) is used as a decimal separator in all cases. Based on the currency of the transaction, the correct number of decimals must be provided after the decimal separator. For example, for one dollar and fifty cents , the following value would be supplied (USD uses two decimals after the separator): 1.50. For zero dollars and 50 cents, the following value would be supplied: 0.50. currency: type: string description: Indicates the currency present in the payment token (ISO 4217). pattern: '[A-Z]{3}' format: A3 example: USD threeDSecure: $ref: '#/components/schemas/apmdecrypt.response.ThreeDSecure' card: $ref: '#/components/schemas/apmdecrypt.response.Card' apmdecrypt.response.Card: type: object properties: number: type: string description: The Device Primary Account Number (DPAN). format: N19 example: "1234567890123456" pattern: "[0-9]{12,19}" expiryMonth: pattern: '[0-9]{2}' type: string format: N2 example: "10" description: The month that the card expires. expiryYear: type: string description: The year that the card expires. pattern: '(20|21)([0-9]{2})' format: N4 example: "2025" numberType: type: string description: Indicates if the payment token card number was a PAN or DPAN (device PAN). enum: [PAN,DPAN] example: DPAN pattern: PAN|DPAN apmdecrypt.response.ThreeDSecure: description: >- The 3d secure response data structure. type: object properties: verificationId: type: string description: Deprecated and replaced by the tavv field. pattern: '[0-9a-zA-Z/+=]{1,56}' format: AN56 (Base64 encoded) example: c2FtZSBhcyBvdGhlciB2YWx1ZXM= tavv: type: string description: The Online Payment Cryptogram contained within the token. pattern: '[0-9a-zA-Z/+=]{1,56}' format: AN56 (Base64 encoded) example: c2FtZSBhcyBvdGhlciB2YWx1ZXM= eci: pattern: '0[5|7]{1}' type: string description: >- An optional ECI indicator contained within the token. format: N2 example: '05' payment.response.ThreeDSecure: description: >- The 3d secure response data structure. type: object properties: result: type: string description: Contains the 3-D Secure result (for example, CAVV or AAV) pattern: 'UNABLE_TO_VALIDATE_RESULTS_INVALID|VALIDATION_FAILED_AUTHENTICATION|VALIDATION_PASSED_AUTHENTICATION|VALIDATION_PASSED_ATTEMPTED_AUTH|VALIDATION_FAILED_ATTEMPTED_AUTH|NOT_VALIDATED_ISSUER_NOT_PARTICIPATING|VALIDATION_FAILED_ATTEMPTED_AT_ACS|VALIDATION_PASSED_ATTEMPTED_AT_ACS|VALIDATION_FAILED_ATTEMPTED_AT_STAND_IN|VALIDATION_PASSED_ATTEMPTED_AT_STAND_IN|VALIDATION_PASSED_NO_LIABILITY_SHIFT|NOT_VALIDATED_ATTEMPTED_AUTH|NOT_VALIDATED_AUTHENTICATION' enum: [UNABLE_TO_VALIDATE_RESULTS_INVALID,VALIDATION_FAILED_AUTHENTICATION,VALIDATION_PASSED_AUTHENTICATION,VALIDATION_PASSED_ATTEMPTED_AUTH,VALIDATION_FAILED_ATTEMPTED_AUTH,NOT_VALIDATED_ISSUER_NOT_PARTICIPATING,VALIDATION_FAILED_ATTEMPTED_AT_ACS,VALIDATION_PASSED_ATTEMPTED_AT_ACS,VALIDATION_FAILED_ATTEMPTED_AT_STAND_IN,VALIDATION_PASSED_ATTEMPTED_AT_STAND_IN,VALIDATION_PASSED_NO_LIABILITY_SHIFT,NOT_VALIDATED_ATTEMPTED_AUTH,NOT_VALIDATED_AUTHENTICATION] example: VALIDATION_FAILED_AUTHENTICATION