openapi: 3.2.0 info: title: DPP Gateway Experience Payments API version: '1' description: This application will be useful to perform payments with multiple payment methods, Creating customers with in DPP x-provenance: method: derived derived_from: RAML 1.0 published by Deluxe at https://developer.deluxe.com/api-ref/api/merchant-services/ derived_on: '2026-08-13' note: Faithful mechanical conversion of the provider-published RAML 1.0 definition and its rendered request/response parameter and example documents. No operation, field, schema or example in this file was authored by API Evangelist. servers: - url: https://api.deluxe.com/dpp/v1 description: Production (default routing path) - url: https://api.deluxe.com/dpp/v1/gateway description: Production (legacy routing path) - url: https://sandbox.api.deluxe.com/dpp/v1 description: Sandbox / test environment security: - bearerAuth: [] tags: - name: payments paths: /payments: post: operationId: createPayment summary: Create Payment tags: - payments description: The Payments resource in the API is a comprehensive service that manages essential payment operations, processing sales, handling recurring payments, authorizing transactions, capturing funds, and voiding payments. This resource ensures seamless and secure payment processing, supporting various transaction types and providing the necessary flexibility for managing payment workflows efficiently. requestBody: required: true content: application/json: schema: description: Request object to hold details for payment processing, including payment method, billing and shipping addresses, and tax details. It supports Level 2 and Level 3 processing for sale items and fleet products, and also includes optional customer data, order information, and alternate fees. type: object properties: paymentType: description: Identifies if the payment method is Credit (ACH Refund) or Debit for ACH Payments, or Sale for Card payment. type: string enum: - Sale - Debit - Credit examples: - Sale amount: description: Object to hold the total transaction amount and currency. Make sure the amount matches the sum of sale items or products in Level 3 transactions, and includes any applicable fees. type: object properties: amount: description: Amount of the transaction type: number examples: - 150 currency: description: Currency of transaction type: string enum: - USD - CAD examples: - USD required: - amount paymentMethod: description: Payment method details oneOf: - description: Object to hold card details such as card number, expiration date, and CVV. Includes billing address for verification purposes. Supports secure, PCI-compliant card-based transactions while reducing exposure of sensitive payment data across digital checkout and payment authorization flows. type: object properties: card: description: Object to hold card details such as card number, expiration date, and CVV. Includes billing address for verification purposes. Supports secure, PCI-compliant card-based transactions while reducing exposure of sensitive payment data across digital checkout and payment authorization flows. type: object properties: card: description: Card Number type: string minLength: 12 maxLength: 19 examples: - '4111111111111110' expiry: description: Card Expiration Month and Year type: string pattern: ^(0[1-9]|1[0-2])\/\d{2}$ examples: - 11/26 cvv: description: Card CVV/Security Code type: string minLength: 3 maxLength: 4 examples: - '245' required: - card - expiry billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold ACH information such as bank account number, routing number, and account type (e.g., Checking or Savings). Includes optional billing address to support verification and regulatory compliance. Enables secure account-based transactions for direct debit payments. type: object properties: ach: description: Object to hold ACH information such as bank account number, routing number, and account type (e.g., Checking or Savings). Includes optional billing address to support verification and regulatory compliance. Enables secure account-based transactions for direct debit payments. type: object properties: accountNumber: description: Bank account number type: string minLength: 1 maxLength: 20 examples: - '987654321' routingNumber: description: Bank Routing Number type: string minLength: 8 maxLength: 9 examples: - '123456789' accountType: description: Account Type - Checking/Savings type: string enum: - Checking - Savings examples: - Checking required: - accountNumber - routingNumber billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold tokenized card information such as card number, expiration date, and CVV. Includes billing address for validation. Supports secure, PCI-compliant digital transactions with minimal exposure of sensitive data, enabling efficient payment processing across web, mobile, and in-store environments. type: object properties: token: description: Object to hold tokenized card information such as card number, expiration date, and CVV. Includes billing address for validation. Supports secure, PCI-compliant digital transactions with minimal exposure of sensitive data, enabling efficient payment processing across web, mobile, and in-store environments. type: object properties: token: description: Tokenized string for Card details type: string maxLength: 20 examples: - '1234567890123450' expiry: description: Card Expiration Month and Year type: string examples: - 10/25 cvv: description: Card CVV/Security Code type: string minLength: 3 maxLength: 4 examples: - '245' required: - expiry - token billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold payment method details such as stored payment ID and optional CVV. It enables secure retrieval of tokenized payment credentials for recurring billing or one-click checkout scenarios. Includes billing address to support verification, fraud prevention, and transaction accuracy while aligning with compliance requirements in digital payment flows. type: object properties: vault: description: Object to hold payment method details such as stored payment ID and optional CVV. It enables secure retrieval of tokenized payment credentials for recurring billing or one-click checkout scenarios. Includes billing address to support verification, fraud prevention, and transaction accuracy while aligning with compliance requirements in digital payment flows. type: object properties: paymentMethodId: description: Unique identifier for stored payment method type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - 99c33585-a62f-45bb-a733-5720dd69ab1e cvv: description: CVV/Security Code type: string minLength: 3 maxLength: 4 examples: - '245' required: - paymentMethodId billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold cryptogram data such as tokenized transaction values and billing address. It supports secure transmission of card or bank details using encrypted strings, enabling safe, compliant digital payments across banking and e-commerce environments. Ideal for tokenization workflows requiring enhanced data protection and minimal exposure of sensitive financial information. type: object properties: cryptogram: description: Object to hold cryptogram data such as tokenized transaction values and billing address. It supports secure transmission of card or bank details using encrypted strings, enabling safe, compliant digital payments across banking and e-commerce environments. Ideal for tokenization workflows requiring enhanced data protection and minimal exposure of sensitive financial information. type: object properties: cryptogram: description: Tokenized string that passes Card or Bank details for transaction type: string examples: - 6cd3ef836ce141b789b5755ca3f353f1 required: - cryptogram billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold secured network token data such as token string, expiration details, cryptographic authentication values, and token source (e.g., ApplePay, GooglePay, Paze). It enhances payment security and enables streamlined digital transactions. Includes billing address and other identifiers to support robust authorization, risk mitigation, and regulatory compliance in tokenized payment ecosystems. type: object properties: networkToken: description: Object to hold secured network token data such as token string, expiration details, cryptographic authentication values, and token source (e.g., ApplePay, GooglePay, Paze). It enhances payment security and enables streamlined digital transactions. Includes billing address and other identifiers to support robust authorization, risk mitigation, and regulatory compliance in tokenized payment ecosystems. type: object properties: token: description: Network token string type: string minLength: 13 maxLength: 20 examples: - '4895370017589737' expiryMonth: description: Expiry month type: string pattern: ^(0?[1-9]|1[0-2])$ examples: - '05' expiryYear: description: Expiry Year type: string pattern: ^(202[4-9]|20[3-9]\d|2[1-9]\d{2})$ examples: - '2032' secureCavvData: description: Secure cavv data type: string examples: - AwAAAAAAmCjhPZYp4s7YQHwAAAA= eci: description: Electronic commerce indicator type: string maxLength: 2 examples: - '07' tokenType: description: Token type flag type: number minimum: 1 maximum: 9 examples: - 1 tokenSource: description: Token Source - ApplePay/GooglePay/Paze type: string enum: - APPLEPAY - GOOGLEPAY - PAZE - VISA examples: - PAZE required: - expiryMonth - expiryYear - secureCavvData - token - tokenSource billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold ACH token information such as a tokenized string representing bank details. Includes billing address for validation and compliance support. Useful for secure ACH transactions in digital payment workflows, enabling reduced exposure of sensitive banking information and streamlined account-based processing. type: object properties: achToken: description: Object to hold ACH token information such as a tokenized string representing bank details. Includes billing address for validation and compliance support. Useful for secure ACH transactions in digital payment workflows, enabling reduced exposure of sensitive banking information and streamlined account-based processing. type: object properties: token: description: Tokenized string for ACH details type: string maxLength: 40 examples: - k|1235673473|4567890123450 required: - token billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false shippingAddress: description: Shipping Information type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com level2: description: Level 2 data enhances transactions by adding contextual fields like customer reference numbers, tax indicators, shipping ZIP codes, and purchase card flags. This additional metadata improves reporting accuracy, simplifies reconciliation, and supports compliance and audit readiness while offering better visibility into spending behavior. type: object properties: customerRefNumber: description: Reference number for customer type: string examples: - '7898654' localTaxFlag: description: "Indicator, if local taxes apply.\n> Note: On `localTaxFlag` behavior, user can send the acceptable values 1 and 2.\n- If `taxAmount = 0.00`, set **`localTaxFlag = 2`**, which indicates it is an tax exempted item. \n- If `taxAmount > 0.00`, set **`localTaxFlag = 1`**." type: integer examples: - 1 purchaseCard: description: Indicates if purchase card type: boolean examples: - false shippingZip: description: Zip/Postal code of the shipping address type: string examples: - '94002' taxAmount: description: Total Tax Amount is the sum of all individual tax amounts applied to each sale item in a transaction. It represents the overall tax charged on the entire purchase. type: number examples: - 2 level3: description: 'Level 3 data provides detailed line-item information for each sale item in a transaction, including descriptions, quantities, pricing, and discounts. This level of detail enhances transparency, improves financial reporting and reconciliation, and supports compliance with procurement policies. It also enables more efficient processing for corporate and government transactions, often resulting in lower interchange fees and stronger vendor relationships. Recommendations for Level 3 Transactions: - Use a Level 3-enabled card and provide detailed line-item data. - Ensure a non-zero tax amount is included for Level 2 and Level 3 transactions.' type: array items: description: 'Level 3 data provides detailed line-item information for each sale item in a transaction, including descriptions, quantities, pricing, and discounts. This level of detail enhances transparency, improves financial reporting and reconciliation, and supports compliance with procurement policies. It also enables more efficient processing for corporate and government transactions, often resulting in lower interchange fees and stronger vendor relationships. Recommendations for Level 3 Transactions: - Use a Level 3-enabled card and provide detailed line-item data. - Ensure a non-zero tax amount is included for Level 2 and Level 3 transactions.' type: object properties: description: description: Description or name of the sale item type: string maxLength: 250 examples: - Apple skuCode: description: Stock Keeping Unit Code type: string maxLength: 100 examples: - SKU1234 unitCost: description: The cost per single unit of the item being purchased. type: number examples: - 5 price: description: Represents the total price of the item sold. type: number examples: - 5 quantity: description: Quantity of item sold type: number examples: - 4 commodityCode: description: Code used to classify the type of goods or services involved in transaction. DPP APIs do not enforce validations for commodity codes. It is recommended to use standardized lists by referring the [link](https://www.mpiprocessing.com/level-3-and-level-2-credit-card-processing-commodity-codes/) type: string maxLength: 12 examples: - '39028' unitOfMeasure: description: Unit of measuring the item. The API do not enforce validations for units of measure, it is recommended to use standardized lists by referring the [link](https://help.usaepay.info/developer/reference/umcodes/) type: string maxLength: 50 examples: - Dozen freightAmount: description: The cost of shipping or transportation for the item. type: number examples: - 0 dutyAmount: description: The cost of customs duties or import taxes (especially for international purchases). type: number examples: - 0 itemDiscountAmount: description: Discount amount applied on sale item type: number examples: - 0 itemDiscountRate: description: Discount rate of the sale item type: number examples: - 0 taxAmount: description: Tax amount applied on the sale item. type: number examples: - 2 customData: description: Custom data allows integrators to pass additional, customizable information related to a transaction when it does not fit into any predefined fields. This feature supports sending data as name–value pairs (e.g., Invoice Number and its corresponding value). type: array items: description: Custom data allows integrators to pass additional, customizable information related to a transaction when it does not fit into any predefined fields. This feature supports sending data as name–value pairs (e.g., Invoice Number and its corresponding value). type: object properties: name: description: Custom Data field name or key type: string examples: - Invoice Number value: description: Custom Data field value type: string examples: - inv1234 productData: description: Product data contains key details about the products or services involved in a fleet transaction. This information supports accurate billing, expense tracking, and reporting. However, product data fields do not enforce validations by themselves. Therefore, always refer to the product master data before initiating any transaction to ensure accuracy and consistency. type: array items: description: Product data contains key details about the products or services involved in a fleet transaction. This information supports accurate billing, expense tracking, and reporting. However, product data fields do not enforce validations by themselves. Therefore, always refer to the product master data before initiating any transaction to ensure accuracy and consistency. type: object properties: productCode: description: Unique code used to identify the product. type: string maxLength: 50 examples: - '036' serviceCode: description: Code that represents the service associated with the product. type: string maxLength: 50 examples: - S unitMeasurement: description: The unit in which the product is measured. type: string maxLength: 50 examples: - K unitQuantity: description: The number of smaller units contained within the product. type: number examples: - 2 unitPrice: description: The price per single unit of the product. type: number examples: - 3 price: description: The total value of the single product. type: number examples: - 6 quantity: description: The total number of products. type: number examples: - 5 cost: description: The cost for the product. type: number examples: - 30 required: - cost - price - productCode - quantity - serviceCode - unitMeasurement - unitPrice - unitQuantity customerData: description: 'Customer data includes critical details such as odometer readings, sequence numbers, and driver license information. Capturing this data during fleet transactions ensures accuracy and accountability. It also provides valuable context on vehicle usage and driver activity, supporting improved tracking, reporting, and regulatory compliance. > We recommend using **customer data object** instead of array to ensure better data structure, easier validation, and improved extensibility.' oneOf: - description: Customer data includes critical details such as odometer readings, sequence numbers, and driver license information. Capturing this data during fleet transactions ensures accuracy and accountability. It also provides valuable context on vehicle usage and driver activity, supporting improved tracking, reporting, and regulatory compliance. type: object properties: sequenceNumber: description: Sequence number of the fleet card transaction type: string minLength: 5 maxLength: 5 examples: - '56432' odometer: description: Odometer reading of the vehicle captured during transaction type: string minLength: 1 maxLength: 9 examples: - '4354235' driversLicenseNumber: description: Driving Licence number of the driver captured during transaction type: string minLength: 1 maxLength: 15 examples: - '934564354235' required: - driversLicenseNumber - odometer - sequenceNumber - description: Customer data includes critical details such as odometer readings, sequence numbers, and driver license information. Capturing this data during fleet transactions ensures accuracy and accountability. It also provides valuable context on vehicle usage and driver activity, supporting improved tracking, reporting, and regulatory compliance. type: array items: type: object properties: customerCode: description: 'Please ensure that the correct value is provided in this field based on the intended identifier type. - **DS** - Indicates `sequenceNumber` - **04** - Indicates `odometer` - **05** - Indicates `driversLicenseNumber`' type: string maxLength: 50 examples: - DS customerValue: description: 'Ensure the correct value is passed in this field based on the identifier type. - Send exactly 5 digts for `sequenceNumber(DS)` - Send 9 digits(max) for `odometer(04)` - Send 15 digits(max) for `driversLicenseNumber(05)`' type: string maxLength: 50 examples: - '10022' required: - customerCode - customerValue merchantCategory: description: Industry in which merchant operates type: string maxLength: 100 examples: - E-Commerce isSavePaymentMethod: description: Flag to tell if the transaction should be processed and the payment method saved using the billing address type: boolean examples: - false isCustomRecurring: description: Flag to tell if the customer wants custom recurring type: boolean examples: - false isReturnCustomData: description: Flag to tell if the customer wants custom data in the response type: boolean examples: - false deviceId: description: Fleet data capturing deviceId type: string maxLength: 50 examples: - '1' paymentCompleteDate: description: Date on which payment has to be captured/completed. Format MM/dd/yyyy type: string examples: - 09/25/2023 orderData: description: Object to hold order details type: object properties: autoGenerateOrderId: description: Flag to tell if Order Id is to be automatically generated type: boolean examples: - true orderId: description: Unique identifier of Order type: string examples: - abc12345 orderIdIsUnique: description: Flag to tell if Order Id is unique type: boolean examples: - true alternateFee: description: Object to hold additional fee passed by integrator type: object properties: feeType: description: Alternate fee description type: string examples: - Surcharge feePercent: description: Percentage of surcharge to be charged type: number examples: - 3 amount: description: Amount of surcharge calculated based on type: number examples: - 4.5 waived: description: Flag to tell if the fee is to be waived or not type: boolean examples: - true addedToTotalAmount: description: Flag to tell if the fee is to be added to the total amount type: boolean examples: - true required: - amount - paymentMethod - paymentType example: paymentType: Sale amount: amount: 99.99 currency: USD paymentMethod: card: card: '4111111111111110' expiry: 11/26 cvv: '245' billingAddress: state: CA address: 123 Main St lastName: Doe firstName: Jane email: jane@email.com country: USA phone: 650-555-1234 city: San Francisco address2: Apt 5 postalCode: '94111' shippingAddress: state: CA address: 123 Main St lastName: Doe firstName: Jane email: jane@email.com country: USA phone: 650-555-1234 city: San Francisco address2: Apt 5 postalCode: '94111' level2: customerRefNumber: '7898654' localTaxFlag: 1 purchaseCard: false shippingZip: '94002' taxAmount: 4.5 level3: - description: Apple skuCode: SKU1234 commodityCode: '39028' unitOfMeasure: Dozen quantity: 4 unitCost: 11 itemDiscountRate: 10 itemDiscountAmount: 4 price: 40 taxAmount: 2 freightAmount: 1.5 dutyAmount: 0.3 - description: Banana skuCode: SKU4321 commodityCode: '39028' unitOfMeasure: Dozen quantity: 10 unitCost: 5 itemDiscountRate: 0 itemDiscountAmount: 0 price: 50 taxAmount: 2.5 freightAmount: 1.5 dutyAmount: 0.3 customData: - name: Invoice Number value: inv1234 productData: - productCode: '001' serviceCode: S unitMeasurement: G unitQuantity: 2 unitPrice: 3 price: 6 quantity: 5 cost: 30 - productCode: '036' serviceCode: S unitMeasurement: G unitQuantity: 5 unitPrice: 4 price: 20 quantity: 3 cost: 60 customerData: sequenceNumber: '56432' odometer: '4354235' driversLicenseNumber: '9754612345' orderData: autoGenerateOrderId: true orderId: abc12345 orderIdIsUnique: true alternateFee: amount: 10 feePercent: 80 feeType: Surcharge waived: true addedToTotalAmount: true merchantCategory: E-Commerce isSavePaymentMethod: false isCustomRecurring: false isReturnCustomData: false deviceId: '1' paymentCompleteDate: 09/25/2023 responses: '200': description: Successful response content: application/json: schema: description: Response DataType type: object properties: isPartial: description: Indicates if partial payment type: boolean examples: - false orderId: description: Merchant order ID type: string examples: - Order123 customerId: description: Unique identifier for a customer type: number examples: - 4321 subscriptionId: description: Unique identifier for a recurring payment type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - 9a2cb7fe-119c-48ef-973e-8299246df7c2 batchNumber: description: The batch number associated with the transaction for settlement purposes. type: number examples: - 131001 fee: description: Object to hold fee details type: object properties: feeAmount: description: Amount of fee applied type: number examples: - 1.99 feeAuthResponse: description: Authorizer's response code for fee payment type: - string - 'null' examples: - '441257' token: description: Payment token used type: string examples: - '1556778677451110' accountResponseData: description: Object to hold account response details type: object properties: avs: description: Address verification response type: string maxLength: 1 examples: - Y cvv: description: CVV verification response type: string examples: - Y amountApproved: description: Approved payment amount type: number examples: - 99.95 authResponse: description: Authorization code from issuer type: string examples: - ABC123 responseCode: description: Authorizer response code type: number examples: - 0 responseMessage: description: Description of response code type: - string - 'null' examples: - string paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: description: Unique identifier for an API call type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - a2406639-8692-4e1c-978d-1805eb13efdf customData: description: Object to hold a specific custom data model type: array items: description: Custom data allows integrators to pass additional, customizable information related to a transaction when it does not fit into any predefined fields. This feature supports sending data as name–value pairs (e.g., Invoice Number and its corresponding value). type: object properties: name: description: Custom Data field name or key type: string examples: - Invoice Number value: description: Custom Data field value type: string examples: - inv1234 required: - accountResponseData - amountApproved - authResponse - batchNumber - paymentId - requestId - responseCode - responseMessage example: isPartial: false orderId: Order123 customerId: 4321 batchNumber: 131001 subscriptionId: 9a2cb7fe-119c-48ef-973e-8299246df7c2 fee: feeAuthResponse: string feeAmount: 1.99 token: '1556778677451110' accountResponseData: avs: Y cvv: Y amountApproved: 99.95 authResponse: ABC123 responseCode: 0 responseMessage: null paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: a2406639-8692-4e1c-978d-1805eb13efdf customData: - name: Invoice Number value: inv123423 - name: Policy Number value: 110-123-1467 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /payments/cancel: post: operationId: cancelPayment summary: Cancel Payment tags: - payments description: Use this API to cancel a payment that is still in process and has not yet been settled. This endpoint is typically used to void transactions on the same day they are initiated, before the batch closure occurs. By utilizing this API, you can halt a payment before it enters the settlement phase, effectively preventing the transfer of funds. This is particularly useful in scenarios where a payment needs to be stopped due to errors, cancellations, or changes in the transaction. requestBody: required: true content: application/json: schema: type: object properties: paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 isACH: description: Flag to indicate whether the original sale or debit transaction was processed via ACH. type: boolean examples: - false required: - paymentId example: paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 isACH: true responses: '200': description: Successful response content: application/json: schema: type: object properties: authResponse: description: Authorization code from issuer type: string examples: - ABC123 batchNumber: description: Indicated batch number in which the transaction will be settled type: number examples: - 1234 responseCode: description: Authorizer response code type: number examples: - 0 responseMessage: description: Description of any code returned type: - string - 'null' examples: - success paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: description: Unique identifier for an API call type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - a2406639-8692-4e1c-978d-1805eb13efdf required: - authResponse - batchNumber - paymentId - requestId - responseCode - responseMessage example: authResponse: ABC123 batchNumber: 1234 responseCode: 0 responseMessage: null paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: a2406639-8692-4e1c-978d-1805eb13efdf '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /payments/authorize: post: operationId: authorizePayment summary: Authorize Payment tags: - payments description: Submits a payment authorization request to reserve the specified amount on the customer's payment method. This authorization process ensures that the funds are available but does not complete the transaction until a capture is performed. The endpoint supports authorizations using a direct card, a tokenized payment method, or a card stored in a secure vault. This process is crucial for scenarios where the payment needs to be confirmed or adjusted before finalizing the charge. requestBody: required: true content: application/json: schema: description: Request object to hold details for payment authorization, including payment method, billing and shipping addresses, and tax details. It supports Level 2 and Level 3 processing for sale items and fleet products, and also includes optional customer data, order information, and alternate fees. type: object properties: amount: description: Object to hold the total transaction amount and currency. Make sure the amount matches the sum of sale items or products in Level 3 transactions, and includes any applicable fees. type: object properties: amount: description: Amount of the transaction type: number examples: - 150 currency: description: Currency of transaction type: string enum: - USD - CAD examples: - USD required: - amount paymentMethod: description: Payment method details oneOf: - description: Object to hold card details such as card number, expiration date, and CVV. Includes billing address for verification purposes. Supports secure, PCI-compliant card-based transactions while reducing exposure of sensitive payment data across digital checkout and payment authorization flows. type: object properties: card: description: Object to hold card details such as card number, expiration date, and CVV. Includes billing address for verification purposes. Supports secure, PCI-compliant card-based transactions while reducing exposure of sensitive payment data across digital checkout and payment authorization flows. type: object properties: card: description: Card Number type: string minLength: 12 maxLength: 19 examples: - '4111111111111110' expiry: description: Card Expiration Month and Year type: string pattern: ^(0[1-9]|1[0-2])\/\d{2}$ examples: - 11/26 cvv: description: Card CVV/Security Code type: string minLength: 3 maxLength: 4 examples: - '245' required: - card - expiry billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold tokenized card information such as card number, expiration date, and CVV. Includes billing address for validation. Supports secure, PCI-compliant digital transactions with minimal exposure of sensitive data, enabling efficient payment processing across web, mobile, and in-store environments. type: object properties: token: description: Object to hold tokenized card information such as card number, expiration date, and CVV. Includes billing address for validation. Supports secure, PCI-compliant digital transactions with minimal exposure of sensitive data, enabling efficient payment processing across web, mobile, and in-store environments. type: object properties: token: description: Tokenized string for Card details type: string maxLength: 20 examples: - '1234567890123450' expiry: description: Card Expiration Month and Year type: string examples: - 10/25 cvv: description: Card CVV/Security Code type: string minLength: 3 maxLength: 4 examples: - '245' required: - expiry - token billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold secured network token data such as token string, expiration details, cryptographic authentication values, and token source (e.g., ApplePay, GooglePay, Paze). It enhances payment security and enables streamlined digital transactions. Includes billing address and other identifiers to support robust authorization, risk mitigation, and regulatory compliance in tokenized payment ecosystems. type: object properties: networkToken: description: Object to hold secured network token data such as token string, expiration details, cryptographic authentication values, and token source (e.g., ApplePay, GooglePay, Paze). It enhances payment security and enables streamlined digital transactions. Includes billing address and other identifiers to support robust authorization, risk mitigation, and regulatory compliance in tokenized payment ecosystems. type: object properties: token: description: Network token string type: string minLength: 13 maxLength: 20 examples: - '4895370017589737' expiryMonth: description: Expiry month type: string pattern: ^(0?[1-9]|1[0-2])$ examples: - '05' expiryYear: description: Expiry Year type: string pattern: ^(202[4-9]|20[3-9]\d|2[1-9]\d{2})$ examples: - '2032' secureCavvData: description: Secure cavv data type: string examples: - AwAAAAAAmCjhPZYp4s7YQHwAAAA= eci: description: Electronic commerce indicator type: string maxLength: 2 examples: - '07' tokenType: description: Token type flag type: number minimum: 1 maximum: 9 examples: - 1 tokenSource: description: Token Source - ApplePay/GooglePay/Paze type: string enum: - APPLEPAY - GOOGLEPAY - PAZE - VISA examples: - PAZE required: - expiryMonth - expiryYear - secureCavvData - token - tokenSource billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold payment method details such as stored payment ID and optional CVV. It enables secure retrieval of tokenized payment credentials for recurring billing or one-click checkout scenarios. Includes billing address to support verification, fraud prevention, and transaction accuracy while aligning with compliance requirements in digital payment flows. type: object properties: vault: description: Object to hold payment method details such as stored payment ID and optional CVV. It enables secure retrieval of tokenized payment credentials for recurring billing or one-click checkout scenarios. Includes billing address to support verification, fraud prevention, and transaction accuracy while aligning with compliance requirements in digital payment flows. type: object properties: paymentMethodId: description: Unique identifier for stored payment method type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - 99c33585-a62f-45bb-a733-5720dd69ab1e cvv: description: CVV/Security Code type: string minLength: 3 maxLength: 4 examples: - '245' required: - paymentMethodId billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold cryptogram data such as tokenized transaction values and billing address. It supports secure transmission of card or bank details using encrypted strings, enabling safe, compliant digital payments across banking and e-commerce environments. Ideal for tokenization workflows requiring enhanced data protection and minimal exposure of sensitive financial information. type: object properties: cryptogram: description: Object to hold cryptogram data such as tokenized transaction values and billing address. It supports secure transmission of card or bank details using encrypted strings, enabling safe, compliant digital payments across banking and e-commerce environments. Ideal for tokenization workflows requiring enhanced data protection and minimal exposure of sensitive financial information. type: object properties: cryptogram: description: Tokenized string that passes Card or Bank details for transaction type: string examples: - 6cd3ef836ce141b789b5755ca3f353f1 required: - cryptogram billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false shippingAddress: description: Shipping Information type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com level2: description: Level 2 data enhances transactions by adding contextual fields like customer reference numbers, tax indicators, shipping ZIP codes, and purchase card flags. This additional metadata improves reporting accuracy, simplifies reconciliation, and supports compliance and audit readiness while offering better visibility into spending behavior. type: object properties: customerRefNumber: description: Reference number for customer type: string examples: - '7898654' localTaxFlag: description: "Indicator, if local taxes apply.\n> Note: On `localTaxFlag` behavior, user can send the acceptable values 1 and 2.\n- If `taxAmount = 0.00`, set **`localTaxFlag = 2`**, which indicates it is an tax exempted item. \n- If `taxAmount > 0.00`, set **`localTaxFlag = 1`**." type: integer examples: - 1 purchaseCard: description: Indicates if purchase card type: boolean examples: - false shippingZip: description: Zip/Postal code of the shipping address type: string examples: - '94002' taxAmount: description: Total Tax Amount is the sum of all individual tax amounts applied to each sale item in a transaction. It represents the overall tax charged on the entire purchase. type: number examples: - 2 level3: description: 'Level 3 data provides detailed line-item information for each sale item in a transaction, including descriptions, quantities, pricing, and discounts. This level of detail enhances transparency, improves financial reporting and reconciliation, and supports compliance with procurement policies. It also enables more efficient processing for corporate and government transactions, often resulting in lower interchange fees and stronger vendor relationships. Recommendations for Level 3 Transactions: - Use a Level 3-enabled card and provide detailed line-item data. - Ensure a non-zero tax amount is included for Level 2 and Level 3 transactions.' type: array items: description: 'Level 3 data provides detailed line-item information for each sale item in a transaction, including descriptions, quantities, pricing, and discounts. This level of detail enhances transparency, improves financial reporting and reconciliation, and supports compliance with procurement policies. It also enables more efficient processing for corporate and government transactions, often resulting in lower interchange fees and stronger vendor relationships. Recommendations for Level 3 Transactions: - Use a Level 3-enabled card and provide detailed line-item data. - Ensure a non-zero tax amount is included for Level 2 and Level 3 transactions.' type: object properties: description: description: Description or name of the sale item type: string maxLength: 250 examples: - Apple skuCode: description: Stock Keeping Unit Code type: string maxLength: 100 examples: - SKU1234 unitCost: description: The cost per single unit of the item being purchased. type: number examples: - 5 price: description: Represents the total price of the item sold. type: number examples: - 5 quantity: description: Quantity of item sold type: number examples: - 4 commodityCode: description: Code used to classify the type of goods or services involved in transaction. DPP APIs do not enforce validations for commodity codes. It is recommended to use standardized lists by referring the [link](https://www.mpiprocessing.com/level-3-and-level-2-credit-card-processing-commodity-codes/) type: string maxLength: 12 examples: - '39028' unitOfMeasure: description: Unit of measuring the item. The API do not enforce validations for units of measure, it is recommended to use standardized lists by referring the [link](https://help.usaepay.info/developer/reference/umcodes/) type: string maxLength: 50 examples: - Dozen freightAmount: description: The cost of shipping or transportation for the item. type: number examples: - 0 dutyAmount: description: The cost of customs duties or import taxes (especially for international purchases). type: number examples: - 0 itemDiscountAmount: description: Discount amount applied on sale item type: number examples: - 0 itemDiscountRate: description: Discount rate of the sale item type: number examples: - 0 taxAmount: description: Tax amount applied on the sale item. type: number examples: - 2 customData: description: Custom data allows integrators to pass additional, customizable information related to a transaction when it does not fit into any predefined fields. This feature supports sending data as name–value pairs (e.g., Invoice Number and its corresponding value). type: array items: description: Custom data allows integrators to pass additional, customizable information related to a transaction when it does not fit into any predefined fields. This feature supports sending data as name–value pairs (e.g., Invoice Number and its corresponding value). type: object properties: name: description: Custom Data field name or key type: string examples: - Invoice Number value: description: Custom Data field value type: string examples: - inv1234 productData: description: Product data contains key details about the products or services involved in a fleet transaction. This information supports accurate billing, expense tracking, and reporting. However, product data fields do not enforce validations by themselves. Therefore, always refer to the product master data before initiating any transaction to ensure accuracy and consistency. type: array items: description: Product data contains key details about the products or services involved in a fleet transaction. This information supports accurate billing, expense tracking, and reporting. However, product data fields do not enforce validations by themselves. Therefore, always refer to the product master data before initiating any transaction to ensure accuracy and consistency. type: object properties: productCode: description: Unique code used to identify the product. type: string maxLength: 50 examples: - '036' serviceCode: description: Code that represents the service associated with the product. type: string maxLength: 50 examples: - S unitMeasurement: description: The unit in which the product is measured. type: string maxLength: 50 examples: - K unitQuantity: description: The number of smaller units contained within the product. type: number examples: - 2 unitPrice: description: The price per single unit of the product. type: number examples: - 3 price: description: The total value of the single product. type: number examples: - 6 quantity: description: The total number of products. type: number examples: - 5 cost: description: The cost for the product. type: number examples: - 30 required: - cost - price - productCode - quantity - serviceCode - unitMeasurement - unitPrice - unitQuantity customerData: description: 'Customer data includes critical details such as odometer readings, sequence numbers, and driver license information. Capturing this data during fleet transactions ensures accuracy and accountability. It also provides valuable context on vehicle usage and driver activity, supporting improved tracking, reporting, and regulatory compliance. > We recommend using **customer data object** instead of array to ensure better data structure, easier validation, and improved extensibility.' oneOf: - description: Customer data includes critical details such as odometer readings, sequence numbers, and driver license information. Capturing this data during fleet transactions ensures accuracy and accountability. It also provides valuable context on vehicle usage and driver activity, supporting improved tracking, reporting, and regulatory compliance. type: object properties: sequenceNumber: description: Sequence number of the fleet card transaction type: string minLength: 5 maxLength: 5 examples: - '56432' odometer: description: Odometer reading of the vehicle captured during transaction type: string minLength: 1 maxLength: 9 examples: - '4354235' driversLicenseNumber: description: Driving Licence number of the driver captured during transaction type: string minLength: 1 maxLength: 15 examples: - '934564354235' required: - driversLicenseNumber - odometer - sequenceNumber - description: Customer data includes critical details such as odometer readings, sequence numbers, and driver license information. Capturing this data during fleet transactions ensures accuracy and accountability. It also provides valuable context on vehicle usage and driver activity, supporting improved tracking, reporting, and regulatory compliance. type: array items: type: object properties: customerCode: description: 'Please ensure that the correct value is provided in this field based on the intended identifier type. - **DS** - Indicates `sequenceNumber` - **04** - Indicates `odometer` - **05** - Indicates `driversLicenseNumber`' type: string maxLength: 50 examples: - DS customerValue: description: 'Ensure the correct value is passed in this field based on the identifier type. - Send exactly 5 digts for `sequenceNumber(DS)` - Send 9 digits(max) for `odometer(04)` - Send 15 digits(max) for `driversLicenseNumber(05)`' type: string maxLength: 50 examples: - '10022' required: - customerCode - customerValue merchantCategory: description: Industry in which merchant operates type: string maxLength: 100 examples: - E-Commerce isSavePaymentMethod: description: Flag to tell if the transaction should be processed and the payment method saved using the billing address type: boolean examples: - false isCustomRecurring: description: Flag to tell if the customer wants custom recurring type: boolean examples: - false deviceId: description: Fleet data capturing deviceId type: string maxLength: 50 examples: - '1' orderData: description: Order details type: object properties: autoGenerateOrderId: description: Flag to tell if Order Id is to be automatically generated type: boolean examples: - true orderId: description: Unique identifier of Order type: string examples: - abc12345 orderIdIsUnique: description: Flag to tell if Order Id is unique type: boolean examples: - true alternateFee: description: Object to hold additional fee passed by integrator oneOf: - description: Object to hold additional fee details passed by the integrator, such as the fee amount, percentage, fee type (e.g., Surcharge), and optional flags indicating whether the fee is waived or added to the total transaction amount. type: object properties: feeType: description: Alternate fee description type: string examples: - Surcharge feePercent: description: Percentage of surcharge to be charged type: number examples: - 3 amount: description: Amount of surcharge calculated based on type: number examples: - 4.5 waived: description: Flag to tell if the fee is to be waived or not type: boolean examples: - true addedToTotalAmount: description: Flag to tell if the fee is to be added to the total amount type: boolean examples: - true - description: Object to hold additional fee details passed by the integrator, such as the fee amount, percentage, fee type (e.g., Processing Fee). type: object properties: amount: description: Amount of fee applied type: number examples: - 10 feePercent: description: Alternate fee percentage type: number examples: - 80 feeType: description: Alternate fee description type: string examples: - Processing Fee - description: Object to hold additional fee details passed by the integrator, such as the fee percentage, fee type (e.g., Partner Fee). type: object properties: amount: description: Amount of fee applied type: number examples: - 10 feeType: description: Alternate fee description type: string examples: - Partner Fee required: - amount - paymentMethod example: amount: amount: 99.99 currency: USD paymentMethod: card: card: '4111111111111110' expiry: 11/26 cvv: '245' billingAddress: firstName: Jane lastName: Doe address: 123 Main St address2: Apt 5 postalCode: '94111' city: San Francisco state: CA country: USA phone: 650-555-1234 email: jane@email.com shippingAddress: firstName: Jane lastName: Doe address: 123 Main St address2: Apt 5 postalCode: '94111' city: San Francisco state: CA country: USA phone: 650-555-1234 email: jane@email.com level2: customerRefNumber: '7898654' localTaxFlag: 2 purchaseCard: false shippingZip: '94002' taxAmount: 4.5 level3: - description: Apple skuCode: SKU1234 commodityCode: '39028' unitOfMeasure: Dozen quantity: 4 unitCost: 11 itemDiscountRate: 10 itemDiscountAmount: 4 price: 40 taxAmount: 2 freightAmount: 1.5 dutyAmount: 0.3 - description: Banana skuCode: SKU4321 commodityCode: '39028' unitOfMeasure: Dozen quantity: 10 unitCost: 5 itemDiscountRate: 0 itemDiscountAmount: 0 price: 50 taxAmount: 2.5 freightAmount: 1.5 dutyAmount: 0.3 customData: - name: Invoice Number value: inv1234 productData: - productCode: '001' serviceCode: S unitMeasurement: G unitQuantity: 2 unitPrice: 3 price: 6 quantity: 5 cost: 30 - productCode: '036' serviceCode: S unitMeasurement: G unitQuantity: 5 unitPrice: 4 price: 20 quantity: 3 cost: 60 customerData: sequenceNumber: '56432' odometer: '4354235' driversLicenseNumber: '976557612345' merchantCategory: E-Commerce isSavePaymentMethod: false isCustomRecurring: false deviceId: '1' orderData: autoGenerateOrderId: true orderId: abc12345 orderIdIsUnique: true alternateFee: amount: 10 feePercent: 80 feeType: Surcharge waived: true addedToTotalAmount: true responses: '200': description: Successful response content: application/json: schema: description: Response DataType type: object properties: isPartial: description: Indicates if partial payment type: boolean orderId: description: Merchant order ID type: string examples: - Order123 customerId: description: Unique identifier for a customer type: number examples: - 4321 batchNumber: description: Indicated batch number in which the transaction will be settled type: number examples: - 1234 subscriptionId: description: Unique identifier for a recurring payment type: string examples: - 9a2cb7fe-119c-48ef-973e-8299246df7c2 fee: description: Object to hold fee details type: object properties: feeAmount: description: Amount of fee applied type: number examples: - 1.99 feeAuthResponse: description: Authorizer's response code for fee payment type: - string - 'null' examples: - '441247' required: - feeAmount - feeAuthResponse token: description: Payment token used type: string examples: - '1556778677451110' accountResponseData: description: Object to hold account response details type: object properties: avs: description: Address verification response type: string maxLength: 1 examples: - Y cvv: description: CVV verification response type: string examples: - Y required: - avs - cvv amountApproved: description: Approved payment amount type: number examples: - 99.95 authResponse: description: Authorization code from issuer type: string examples: - ABC123 responseCode: description: Authorizer response code type: number examples: - 0 responseMessage: description: Description of response code type: - string - 'null' examples: - success paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: description: Unique identifier for an API call type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - a2406639-8692-4e1c-978d-1805eb13efdf required: - accountResponseData - amountApproved - authResponse - batchNumber - customerId - fee - isPartial - orderId - paymentId - requestId - responseCode - responseMessage - subscriptionId - token example: isPartial: false orderId: Order123 customerId: 4321 batchNumber: 1234 subscriptionId: 9a2cb7fe-119c-48ef-973e-8299246df7c2 fee: feeAuthResponse: '' feeAmount: 1.99 token: '1556778677451110' accountResponseData: avs: Y cvv: Y amountApproved: 99.95 authResponse: ABC123 responseCode: 0 responseMessage: null paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: a2406639-8692-4e1c-978d-1805eb13efdf '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /payments/complete: post: operationId: completePayment summary: Complete Payment tags: - payments description: Use this API to finalize a previously authorized payment or to add a tip to the original transaction. This endpoint allows you to capture or complete an amount that is either equal to or less than the initially authorized amount. Partial captures are supported, enabling flexibility in payment processing. Any remaining authorized funds that are not captured will be automatically released by the bank after a specified period. This feature is particularly useful for scenarios like tip adjustments or when the final amount is determined after the initial authorization. requestBody: required: true content: application/json: schema: description: Request data type details for complete the payment type: object properties: paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 amount: description: Amount details type: object properties: amount: description: Amount of the transaction type: number examples: - 150 currency: description: Currency of transaction type: string enum: - USD - CAD examples: - USD required: - amount tipAmount: description: Object to hold the tip amount details if any type: object properties: amount: description: Amount of the transaction type: number examples: - 150 currency: description: Currency of transaction type: string enum: - USD - CAD examples: - USD required: - amount required: - amount - paymentId example: paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 amount: amount: 19.99 currency: USD tipAmount: amount: 1.99 currency: USD responses: '200': description: Successful response content: application/json: schema: description: Response data type details for complete the payment type: object properties: batchNumber: description: Indicated batch number in which the transaction will be settled type: number examples: - 4321 amountApproved: description: Approved payment amount type: number examples: - 99.95 authResponse: description: Authorization code from issuer type: string examples: - ABC123 responseCode: description: Authorizer response code type: number examples: - 0 responseMessage: description: Description of response code type: - string - 'null' examples: - success paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: description: Unique identifier for an API call type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - a2406639-8692-4e1c-978d-1805eb13efdf required: - amountApproved - authResponse - batchNumber - paymentId - requestId - responseCode - responseMessage example: batchNumber: 4321 amountApproved: 99.95 authResponse: ABC123 responseCode: 0 responseMessage: null paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: a2406639-8692-4e1c-978d-1805eb13efdf '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /payments/search: post: operationId: searchPayments summary: Search Payments tags: - payments description: This API endpoint is used to search and retrieve a list of payments, providing details about each payment for a given data range. The response indicates whether the search was successful or if there were errors or validation issues. requestBody: required: true content: application/json: schema: description: Request DataType type: object properties: startDate: description: The start date for the search type: string pattern: ^\d{1,2}\/\d{1,2}\/\d{4}$ examples: - 05/23/2024 endDate: description: The end date for the search type: string pattern: ^\d{1,2}\/\d{1,2}\/\d{4}$ examples: - 05/25/2024 paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 orderId: description: Unique identifier of Order type: string examples: - '486383174009532227' searchName: description: The name of the search type: string examples: - Card Payments Only customerId: description: Unique identifier for a customer type: number minimum: 1 examples: - 24582 paymentMethodId: description: Unique identifier for a payment method (ACH or Card) type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d10f860c-ab05-4002-86b3-b4a707d9a999 subscriptionId: description: Unique identifier for a recurring payment type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 isAmex: description: Boolean flag to include American Express card transactions type: boolean examples: - true isDiscover: description: Boolean flag to include Discover card transactions type: boolean examples: - false isMastercard: description: Boolean flag to include MasterCard transactions type: boolean examples: - false isVisa: description: Boolean flag to include Visa card transactions type: boolean examples: - true isACH: description: Boolean flag to include ACH transactions type: boolean examples: - false isWex: description: Boolean flag to include Wex transactions type: boolean examples: - false isVoyager: description: Boolean flag to include Voyager transactions type: boolean examples: - false isRecurring: description: Boolean flag to include recurring transactions type: boolean examples: - false isInactiveRecurring: description: Boolean flag to include disabled recurring transactions type: boolean examples: - false isCash: description: Boolean flag to include cash transactions type: boolean examples: - false isCheck: description: Boolean flag to include check transactions type: boolean examples: - false batchNumber: description: Indicated batch number in which the transaction will be settled type: number examples: - 1234 cardCategory: description: Card category to search. you can search with either personal card or corporate card. type: string enum: - PERSONAL - CORPORATE examples: - PERSONAL example: startDate: 05/23/2024 endDate: 05/25/2024 paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 orderId: '486383174009532227' searchName: Card Payments Only customerId: 24582 paymentMethodId: ee0b82f2-5682-ec0c-f75a-12270d6a1f78 subscriptionId: 9a2cb7fe-119c-48ef-973e-8299246df7c2 isAmex: true isDiscover: false isMastercard: false isVisa: true isACH: false isWex: false isVoyager: false isRecurring: false isInactiveRecurring: false isCash: false isCheck: false batchNumber: 1234 cardCategory: PERSONAL responses: '200': description: Successful response content: application/json: schema: description: Response DataType type: object properties: data: description: Container for order information. type: object properties: payments: type: array items: description: List of transactions/payments type: object properties: paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 isAch: description: Indicates whether the transaction is an ACH transaction. type: boolean examples: - true customerId: description: Unique identifier for a customer type: number examples: - 24582 paymentMethodId: description: Unique identifier for a payment method (ACH or Card) type: string examples: - d10f860c-ab05-4002-86b3-b4a707d9a999 referenceNumber: description: The reference number for the transaction. type: string examples: - '12345' subscription: description: Container for recurring transaction information. type: object properties: isParent: description: Indicates if the transaction is a recurring parent transaction. type: boolean examples: - false isChild: description: Indicates if the transaction is a recurring child transaction. type: boolean examples: - false parentRefNumber: description: The reference number of the parent transaction. type: string parentPaymentId: description: The order ID of the parent transaction. type: string subscriptionId: description: Unique identifier for a recurring payment type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 parentAmount: description: The amount of the parent transaction. type: number examples: - 0 startDate: description: The start date of the recurring transaction. type: string endDate: description: The end date of the recurring transaction. type: string required: - endDate - isChild - isParent - parentAmount - parentPaymentId - parentRefNumber - startDate - subscriptionId payment: description: Container for order payment information. type: object properties: paymentType: description: The type of transaction (e.g., SALE, REFUND). type: string authResponse: description: The authorization response message from the payment gateway. type: string examples: - APPROVED 004131 responseCode: description: The authorization code provided by the payment processor. type: string examples: - '4131' orderId: description: The unique identifier for the order. type: string examples: - '2.6921E+17' avs: description: The Address Verification Service (AVS) response indicating the result of address check. type: string examples: - Y cvv: description: The CVV2 response indicating the result of the CVV check. type: string examples: - P isSuccessful: description: Indicates whether the transaction was successful. type: boolean examples: - true isPartial: description: Indicates whether the transaction was partially approved. type: boolean examples: - false partialPaymentId: description: The identifier for the partial transaction if applicable. type: string originalAmount: description: The original amount of the transaction. type: number examples: - 1 amount: description: The amount processed in the transaction. type: number examples: - 1 gratuityAmount: description: The gratuity amount included in the transaction. type: number examples: - 0 tipAmount: description: The tip amount included in the transaction. type: number examples: - 0 paymentDateTime: description: The date and time when the transaction was processed. type: string examples: - 5/23/2024 14:57 paymentDate: description: The date of the transaction. type: string examples: - 5/23/2024 paymentTime: description: The time of the transaction. type: string examples: - 2:57 PM batchNumber: description: The batch number associated with the transaction for settlement purposes. type: string examples: - '131001' cimRefNumber: description: The reference number provided by the Customer Information Management (CIM) system. type: string examples: - '123' batchCloseDate: description: The date when the transaction batch was closed. type: string examples: - 5/24/2024 batchCloseTime: description: The time when the transaction batch was closed. type: string examples: - 1:00 PM settled: description: Indicates whether the transaction has been settled. type: boolean examples: - false settledDate: description: The date when the transaction was settled. type: string processingFee: description: The processing fee applied to the transaction. type: number required: - amount - authResponse - avs - batchCloseDate - batchCloseTime - batchNumber - cimRefNumber - cvv - gratuityAmount - isPartial - isSuccessful - orderId - originalAmount - partialPaymentId - paymentDate - paymentDateTime - paymentTime - paymentType - processingFee - responseCode - settled - settledDate - tipAmount ach: description: Container for order ACH information. type: object properties: salesTax: description: The sales tax applied to the ACH transaction. type: string aba: description: The American Bankers Association (ABA) routing number for the bank. type: string examples: - '123123123' dda: description: The Demand Deposit Account (DDA) number for the ACH transaction. type: string examples: - '123123123' bankNumber: description: The bank number associated with the ACH transaction. type: string examples: - '1234567' transitNumber: description: The transit number associated with the ACH transaction. type: string accountType: description: The type of account (e.g., checking, savings) for the ACH transaction. type: string examples: - ACH/EFT - Checking accountNumber: description: The account number for the ACH transaction. type: string categoryText: description: The category or description of the ACH transaction. type: string classCode: description: The classification code for the ACH transaction. type: string entry: description: The entry description for the ACH transaction. type: string required: - aba - accountNumber - accountType - bankNumber - categoryText - classCode - dda - entry - salesTax - transitNumber billingAddress: description: Container for order information. type: object properties: address: description: The billing address of the customer. type: string examples: - 100 Throckmorton St city: description: The city of the billing address. type: string examples: - Fort Worth state: description: The state of the billing address. type: string examples: - TX postalCode: description: The postal code of the billing address. type: string examples: - '76102' country: description: The country of the billing address. type: string examples: - US phone: description: The phone number associated with the billing address. type: string examples: - '7026100029' email: description: The email address associated with the billing address. type: string examples: - ACH/EFT - CheckingVaultActiondemo@gmail.com paymentOrigin: description: The origin of the transaction. type: string examples: - DPP required: - address - city - country - email - paymentOrigin - phone - postalCode - state card: description: Container for order card information. type: object properties: card: description: The last four digits of the credit card number. type: string examples: - '8674' cardType: description: The type of credit card (e.g., VISA, MASTER, AMEX). type: string examples: - Visa cardholderName: description: The name on the credit card. type: string examples: - Automation VaultImportCVGQOM expiry: description: The expiration date of the credit card. type: string examples: - '**/25' cardCategory: description: Card category to search. you can search with either personal card or corporate card. type: string enum: - PERSONAL - CORPORATE examples: - PERSONAL required: - card - cardCategory - cardType - cardholderName - expiry level2: description: Level 2 data enhances payment transactions by including customer reference numbers, local tax indicators, tax amounts, shipping ZIP codes, and purchase card flags. The Search Payment endpoint returns this enriched information to provide better context for each transaction, improving financial reporting accuracy, simplifying reconciliation, and strengthening compliance and audit readiness. type: object properties: customerRefNumber: description: Reference number for customer type: string examples: - '7898654' localTaxFlag: description: "Indicator, if local taxes apply.\n> Note: On `localTaxFlag` behavior, user can send the acceptable values 1 and 2.\n- If `taxAmount = 0.00`, set **`localTaxFlag = 2`**, which indicates it is an tax exempted item. \n- If `taxAmount > 0.00`, set **`localTaxFlag = 1`**." type: integer examples: - 1 purchaseCard: description: Indicates if purchase card type: boolean examples: - false shippingZip: description: Zip/Postal code of the shipping address type: string examples: - '94002' taxAmount: description: Total Tax Amount is the sum of all individual tax amounts applied to each sale item in a transaction. It represents the overall tax charged on the entire purchase. type: number examples: - 2 level3: description: 'Level 3 data provides detailed information about each item within a transaction, such as descriptions, quantities, pricing, and discounts. By including this granular data in search payments, businesses gain greater transparency into what was purchased—not just the total amount spent. This enhanced visibility improves financial reporting, streamlines reconciliation, and supports compliance with procurement policies. Additionally, it enables more efficient processing of corporate and government transactions, often resulting in lower interchange fees and stronger vendor relationships. Recommendations for Level 3 Transactions: - Use an L3-enabled card and provide supplemental data, including Quick Items - Ensure a non-zero tax is included for Level 2/Level 3 transactions' type: array items: description: 'Level 3 data provides detailed line-item information for each sale item in a transaction, including descriptions, quantities, pricing, and discounts. This level of detail enhances transparency, improves financial reporting and reconciliation, and supports compliance with procurement policies. It also enables more efficient processing for corporate and government transactions, often resulting in lower interchange fees and stronger vendor relationships. Recommendations for Level 3 Transactions: - Use a Level 3-enabled card and provide detailed line-item data. - Ensure a non-zero tax amount is included for Level 2 and Level 3 transactions.' type: object properties: description: description: Description or name of the sale item type: string maxLength: 250 examples: - Apple skuCode: description: Stock Keeping Unit Code type: string maxLength: 100 examples: - SKU1234 unitCost: description: The cost per single unit of the item being purchased. type: number examples: - 5 price: description: Represents the total price of the item sold. type: number examples: - 5 quantity: description: Quantity of item sold type: number examples: - 4 commodityCode: description: Code used to classify the type of goods or services involved in transaction. DPP APIs do not enforce validations for commodity codes. It is recommended to use standardized lists by referring the [link](https://www.mpiprocessing.com/level-3-and-level-2-credit-card-processing-commodity-codes/) type: string maxLength: 12 examples: - '39028' unitOfMeasure: description: Unit of measuring the item. The API do not enforce validations for units of measure, it is recommended to use standardized lists by referring the [link](https://help.usaepay.info/developer/reference/umcodes/) type: string maxLength: 50 examples: - Dozen freightAmount: description: The cost of shipping or transportation for the item. type: number examples: - 0 dutyAmount: description: The cost of customs duties or import taxes (especially for international purchases). type: number examples: - 0 itemDiscountAmount: description: Discount amount applied on sale item type: number examples: - 0 itemDiscountRate: description: Discount rate of the sale item type: number examples: - 0 taxAmount: description: Tax amount applied on the sale item. type: number examples: - 2 customData: description: Object to hold a specific custom data. type: array items: description: Custom data allows integrators to pass additional, customizable information related to a transaction when it does not fit into any predefined fields. This feature supports sending data as name–value pairs (e.g., Invoice Number and its corresponding value). type: object properties: name: description: Custom Data field name or key type: string examples: - Invoice Number value: description: Custom Data field value type: string examples: - inv1234 customerData: description: Object to hold a specific customer data. type: object properties: sequenceNumber: description: Sequence number of the fleet card transaction type: string minLength: 5 maxLength: 5 examples: - '56432' odometer: description: Odometer reading of the vehicle captured during transaction type: string minLength: 1 maxLength: 9 examples: - '4354235' driversLicenseNumber: description: Driving Licence number of the driver captured during transaction type: string minLength: 1 maxLength: 15 examples: - '934564354235' required: - driversLicenseNumber - odometer - sequenceNumber productData: description: Object to hold a specific product data. type: array items: description: Product data contains key details about the products or services involved in a fleet transaction. This information supports accurate billing, expense tracking, and reporting. However, product data fields do not enforce validations by themselves. Therefore, always refer to the product master data before initiating any transaction to ensure accuracy and consistency. type: object properties: productCode: description: Unique code used to identify the product. type: string maxLength: 50 examples: - '036' serviceCode: description: Code that represents the service associated with the product. type: string maxLength: 50 examples: - S unitMeasurement: description: The unit in which the product is measured. type: string maxLength: 50 examples: - K unitQuantity: description: The number of smaller units contained within the product. type: number examples: - 2 unitPrice: description: The price per single unit of the product. type: number examples: - 3 price: description: The total value of the single product. type: number examples: - 6 quantity: description: The total number of products. type: number examples: - 5 cost: description: The cost for the product. type: number examples: - 30 required: - cost - price - productCode - quantity - serviceCode - unitMeasurement - unitPrice - unitQuantity required: - ach - billingAddress - card - customData - customerData - customerId - isAch - payment - paymentId - paymentMethodId - productData - referenceNumber - subscription isError: description: Indicates if there's an error type: boolean examples: - false validationFailed: description: Indicates if validation has failed type: boolean examples: - false errorMessages: description: List of error messages type: string validationFailures: description: Details of validation failures type: string isSuccess: description: Indicates if the request succeeded type: boolean examples: - true action: description: The action taken type: string examples: - Query required: - action - data - isError - isSuccess - validationFailed example: data: payments: - paymentId: 28d3194b-1ac4-4222-a942-7c3edd7561b5 isAch: false customerId: 24582 paymentMethodId: ee0b82f2-5682-ec0c-f75a-12270d6a1f78 referenceNumber: '' subscription: isParent: false isChild: false parentRefNumber: '' parentPaymentId: '484553569996941798' subscriptionId: 9a2cb7fe-119c-48ef-973e-8299246df7c2 parentAmount: 0 startDate: '' endDate: '' payment: paymentType: SALE authResponse: APPROVED 004698 responseCode: 004698 orderId: '484553569996941798' avs: Y (Address and zip both match) cvv: P (Card verification not performed (not processed)) isSuccessful: true isPartial: false partialPaymentId: '' originalAmount: 55 amount: 55 gratuityAmount: 0 tipAmount: 0 paymentDateTime: 05/24/2024 09:53 AM paymentDate: 05/24/2024 paymentTime: 9:53 AM batchNumber: '132001' cimRefNumber: '' batchCloseDate: 10/24/2024 batchCloseTime: 5:00 PM settled: false settledDate: '' processingFee: 1234 ach: salesTax: '' aba: '' dda: '1234' bankNumber: '' transitNumber: '' accountType: '' accountNumber: '' categoryText: '' classCode: '' entry: '' billingAddress: address: 146 Test Ln city: Fort Worth state: TX postalCode: '76126' country: '' phone: '8889991234' email: parveen.syed@first-american.net paymentOrigin: API card: card: '6782' cardType: VISA cardholderName: Syed Parveen expiry: '**/29' cardCategory: PERSONAL level2: customerRefNumber: '5698123' localTaxFlag: 2 purchaseCard: false shippingZip: '94002' taxAmount: 3 level3: - description: Eggs skuCode: SKU2341 commodityCode: '78654' unitOfMeasure: Dozen quantity: 4 unitCost: 11 itemDiscountRate: 10 itemDiscountAmount: 4 price: 40 taxAmount: 2 freightAmount: 1.5 dutyAmount: 0.3 - description: Banana skuCode: SKU9876 commodityCode: '39023' unitOfMeasure: Dozen quantity: 5 unitCost: 10 itemDiscountRate: 0 itemDiscountAmount: 0 price: 50 taxAmount: 1 freightAmount: 0.75 dutyAmount: 0.15 customData: - name: Invoice Number value: inv123423 - name: Policy Number value: 110-123-1467 productData: - productCode: '036' serviceCode: S unitMeasurement: K quantity: 1 cost: 2 price: 2 unitQuantity: 2 unitPrice: 3 customerData: sequenceNumber: '56432' odometer: '4354235' driversLicenseNumber: '12345' isError: false validationFailed: false errorMessages: '' validationFailures: '' isSuccess: true action: Query '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /payments/batch: post: operationId: createBatchPayments summary: Create Batch Payments tags: - payments description: The Create Batch Payments end point allows you to send multiple transctions in a single API call and process all of them in single batch in a given date. This feature is useful for processing multiple payment transactions in one batch. requestBody: required: true content: application/json: schema: description: Request DataType type: object properties: startDate: description: Date at which the batch processing should start for processing. type: string pattern: ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4}$ examples: - 09/25/2023 transactions: description: Array to hold transaction details to process in this batch request. type: array items: type: object properties: paymentType: description: Identifies if the payment method is Debit for ACH Payments, or Sale for Card payment. type: string enum: - Sale - Debit examples: - Sale amount: description: Object to hold amount details type: object properties: amount: description: Amount of the transaction type: number examples: - 150 currency: description: Currency of transaction type: string enum: - USD - CAD examples: - USD required: - amount paymentMethod: description: Object to hold payment method details oneOf: - description: Object to hold card details such as card number, expiration date, and CVV. Includes billing address for verification purposes. Supports secure, PCI-compliant card-based transactions while reducing exposure of sensitive payment data across digital checkout and payment authorization flows. type: object properties: card: description: Object to hold card details such as card number, expiration date, and CVV. Includes billing address for verification purposes. Supports secure, PCI-compliant card-based transactions while reducing exposure of sensitive payment data across digital checkout and payment authorization flows. type: object properties: card: description: Card Number type: string minLength: 12 maxLength: 19 examples: - '4111111111111110' expiry: description: Card Expiration Month and Year type: string pattern: ^(0[1-9]|1[0-2])\/\d{2}$ examples: - 11/26 cvv: description: Card CVV/Security Code type: string minLength: 3 maxLength: 4 examples: - '245' required: - card - expiry billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold ACH payment information type: object properties: ach: type: object properties: accountNumber: description: Bank account number type: string minLength: 1 maxLength: 20 examples: - '987654321' routingNumber: description: Bank Routing Number type: string minLength: 8 maxLength: 9 examples: - '123456789' accountType: description: Account Type - Checking/Savings type: string enum: - Checking - Savings examples: - Checking required: - accountNumber - accountType - routingNumber additionalProperties: false billingAddress: description: Billing Information type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false - description: Object to hold cryptogram data such as tokenized transaction values and billing address. It supports secure transmission of card or bank details using encrypted strings, enabling safe, compliant digital payments across banking and e-commerce environments. Ideal for tokenization workflows requiring enhanced data protection and minimal exposure of sensitive financial information. type: object properties: cryptogram: description: Object to hold cryptogram data such as tokenized transaction values and billing address. It supports secure transmission of card or bank details using encrypted strings, enabling safe, compliant digital payments across banking and e-commerce environments. Ideal for tokenization workflows requiring enhanced data protection and minimal exposure of sensitive financial information. type: object properties: cryptogram: description: Tokenized string that passes Card or Bank details for transaction type: string examples: - 6cd3ef836ce141b789b5755ca3f353f1 required: - cryptogram billingAddress: description: Billing Address details includes name, street address, city, postal code, country, and optional contact information like phone and email. These fields support payment verification, fraud prevention, and customer record enrichment, making it easier to integrate with billing, invoicing, compliance systems. type: object properties: firstName: description: Customer's first name type: string maxLength: 100 examples: - Jane lastName: description: Customer's last name type: string maxLength: 100 examples: - Doe address: description: Customer's address type: string maxLength: 250 examples: - 123 Main St address2: description: Customer's address line 2 type: string maxLength: 100 examples: - Apt 5 postalCode: description: Customer's postal/zip code type: string maxLength: 50 examples: - '94111' city: description: Customer's city type: string maxLength: 50 examples: - San Francisco state: description: Customer's state/province type: string maxLength: 25 examples: - CA country: description: Customer's country type: string maxLength: 25 examples: - USA phone: description: Customer's phone number type: string pattern: ^(\+\d{1,3}[\s-]?)?\(?\d{3}\)?[\s-]?\d{3}[\s-]?\d{4}$ maxLength: 17 examples: - 650-555-1234 email: description: Customer's email address type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ maxLength: 250 examples: - jane@email.com additionalProperties: false required: - amount - paymentMethod - paymentType minItems: 1 required: - startDate - transactions example: startDate: 09/25/2023 transactions: - paymentType: Sale amount: amount: 19.99 currency: USD paymentMethod: card: card: '4111111111111110' expiry: 11/26 cvv: '245' billingAddress: firstName: Jane lastName: Doe address: 123 Main St address2: Apt 5 postalCode: '94111' city: San Francisco state: CA country: USA phone: 650-555-1234 email: jane@email.com - paymentType: Sale amount: amount: 21.95 currency: USD paymentMethod: card: card: '4111411141114123' expiry: 12/34 cvv: '123' billingAddress: state: CA address: 123 Main St firstName: Narayana lastName: Konuri email: narayana@deluxe.com country: US phone: +1-898-568-3254 city: San Francisco address2: Apt 5 postalCode: '94111' responses: '200': description: Successful response content: application/json: schema: description: Response DataType type: array items: type: object properties: isPartial: description: Indicates if partial payment type: boolean examples: - false token: description: Payment token used type: string examples: - '1556778677451110' accountResponseData: description: Object to hold account response details type: object properties: avs: description: Address verification response type: string maxLength: 1 examples: - Y cvv: description: CVV verification response type: string examples: - Y batchNumber: description: Unique identifier to identify the batch. All the transcations with same batch number will be processed in the same batch type: number examples: - 12345 amountApproved: description: Approved payment amount type: number examples: - 99.95 authResponse: description: Authorization code from issuer type: string examples: - ABC123 responseCode: description: Authorizer response code type: number examples: - 0 responseMessage: description: Description of response code type: - string - 'null' examples: - Transaction successful paymentId: description: Payment gateway transaction ID type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: description: Unique identifier for an API call type: string pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$ examples: - a2406639-8692-4e1c-978d-1805eb13efdf required: - accountResponseData - amountApproved - authResponse - batchNumber - paymentId - requestId - responseCode - responseMessage example: - isPartial: false token: '1556778677451110' accountResponseData: avs: Y cvv: Y batchNumber: 12345 amountApproved: 99.95 authResponse: '10' responseCode: 0 responseMessage: Amount Approved paymentId: f1ced290-6c54-4b01-90e6-d701748f0851 requestId: 6639a240-8692-4e1c-978d-1805eb13efdf - isPartial: false token: '1556778697451110' accountResponseData: avs: Y cvv: Y batchNumber: 78654 amountApproved: 21.95 authResponse: '10' responseCode: 0 responseMessage: Amount Approved paymentId: f490f1ea-6c54-4b01-90e6-d701748f0851 requestId: b5406639-8692-4e1c-878d-1805eb13efdf '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' components: securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: 'This API supports OpenID Connect OAuth 2.0 for authenticating all API requests. Bearer tokens are obtained from the Deluxe security service token endpoint using client credentials and expire after 60 minutes.' basicAuth: type: http scheme: basic description: This API supports Anypoint's Client ID Enforcement authentication policy.