openapi: 3.1.0 info: title: DPP Gateway Experience 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: batches - name: customers - name: emv - name: events - name: paymentlinks - name: paymentmethods - name: payments - name: refunds - name: subscriptions 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.' /emv/payment: post: operationId: emvPayments summary: EMV Payments tags: - emv description: 'Initiates a sale or authorization on a physical EMV device by sending the ``deviceId``, ``amount``, and a ``callbackUrl``. The terminal processes the transaction and returns a simple in‑API response, while the detailed transaction result is delivered to the callback URL. Use this endpoint for chip‑based, card‑present transactions on supported devices. Begin your integration with the Overview and Get Started pages under **API Reference > EMV Payments**, accessible through the main menu via **Payments › Merchant Services**. Use these endpoint details when implementing specific calls.' requestBody: required: true content: application/json: schema: description: Request to hold EMV based transaction attributes. type: object properties: transactionType: description: Identifies if the transaction type is of SALE/AUTHORIZE. type: string enum: - SALE - AUTHORIZE examples: - SALE deviceId: description: Unique identifier of the EMV payment device. type: string minLength: 1 maxLength: 50 examples: - '10' callbackUrl: description: Webhook URL to get the updated response details, if any. type: string minLength: 5 maxLength: 100 examples: - https://webhook.site/63b65a42-6012-49ea-b98f-d01d46283018 amount: description: Sale amount of the transaction done through cloud EMV device payment method type: object properties: amount: description: Amount of the transaction type: number minimum: 0.01 examples: - 19.99 currency: description: Type of currency in which transaction is done. type: string enum: - USD examples: - USD required: - amount required: - callbackUrl - deviceId - transactionType example: transactionType: SALE deviceId: '2' callbackUrl: https://webhook.site/63b65a42-6012-49ea-b98f-d01d46283018 amount: amount: 19.99 currency: USD responses: '200': description: Successful response content: application/json: schema: description: Response DataType type: object properties: paymentId: description: Unique identifier for the payment done. 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: - 63748a11-312d-456e-b55d-2008f8deea90 requestId: description: Unique identifier for the API request. 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: - bb75b884-e7a7-4510-aabc-3fdade625654 responseMessage: description: Response message type: string examples: - Sale completed successfully. example: paymentId: 63748a11-312d-456e-b55d-2008f8deea90 requestId: bb75b884-e7a7-4510-aabc-3fdade625654 responseMessage: Your transaction is currently being processed. For more details, please check the callback URL in sometime. '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /emv/refund: post: operationId: emvRefunds summary: EMV Refunds tags: - emv description: 'Initiates a stand‑alone refund on a physical EMV device by providing the ``deviceId``, ``amount``, and a ``callbackUrl``. The terminal processes the refund and returns a simple in‑API response, while the detailed transaction result is sent to your callback URL. Use this endpoint to handle chip‑based, card‑present refund transactions on supported devices. Begin your integration with the Overview and Get Started pages under **API Reference > EMV Payments**, accessible through the main menu via **Payments › Merchant Services**. Use these endpoint details when implementing specific calls.' requestBody: required: true content: application/json: schema: description: Request to hold EMV based transaction attributes. type: object properties: deviceId: description: Unique identifier of the EMV payment device. type: string minLength: 1 maxLength: 50 examples: - '10' callbackUrl: description: Webhook URL to get the updated response details, if any. type: string minLength: 5 maxLength: 100 examples: - https://webhook.site/63b65a42-6012-49ea-b98f-d01d46283018 amount: description: Refund amount of the transaction done through cloud EMV device payment method type: object properties: amount: description: Amount of the transaction type: number minimum: 0.01 examples: - 19.99 currency: description: Type of currency in which transaction is done. type: string enum: - USD examples: - USD required: - amount required: - callbackUrl - deviceId example: deviceId: '2' callbackUrl: https://webhook.site/63b65a42-6012-49ea-b98f-d01d46283018 amount: amount: 19.99 currency: USD responses: '200': description: Successful response content: application/json: schema: description: Response DataType type: object properties: paymentId: description: Unique identifier for the payment done. 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: - 63748a11-312d-456e-b55d-2008f8deea90 requestId: description: Unique identifier for the API request. 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: - bb75b884-e7a7-4510-aabc-3fdade625654 responseMessage: description: Response message type: string examples: - Refund completed successfully. example: paymentId: 63748a11-312d-456e-b55d-2008f8deea90 requestId: bb75b884-e7a7-4510-aabc-3fdade625654 responseMessage: Your transaction is currently being processed. For more details, please check the callback URL in sometime. '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /emv/devices: get: operationId: emvDevicesList summary: EMV Devices List tags: - emv description: Retrieves a list of all devices associated with the partnerToken provided in the request. responses: '200': description: Successful response content: application/json: schema: description: Response DataType type: object properties: devices: description: 'Object that holds the required device-related details. **Device-specific fields** **CLOUD** - `merchantId` - `terminalId` - `deviceType` - `deviceDisplayName` - `terminalStatus` - `deviceId` - `terminalName` - `deviceSerialNumber` - `multiMIDSharing` - `cloudStatus` - `sharedMerchantIds` - `primaryMerchantId` - `terminalConnectionId` - `terminalAccessKey` - `merchantAccessKey` - `posAccessKey` **STANDALONE** - `merchantId` - `terminalId` - `deviceType` - `deviceDisplayName` - `terminalStatus` **GATEWAY** - `merchantId` - `terminalId` - `deviceType` - `deviceDisplayName` - `terminalStatus`' type: array items: description: Object that holds the required device related details type: object properties: deviceId: description: Unique identifier of the EMV payment device. type: string minLength: 1 maxLength: 50 examples: - '10' terminalName: description: Name of the terminal through which EMV type payment is done. type: string minLength: 1 maxLength: 250 examples: - QA D3500 WIFI deviceDisplayName: description: Display name of the device through which EMV type payment is done. type: string minLength: 1 maxLength: 250 examples: - QA D3500 WIFI test deviceSerialNumber: description: Serial number of the device through which EMV type payment is done. type: string minLength: 0 maxLength: 250 examples: - QA1234 multiMIDSharing: description: This value indicates whether device is shared for linked merchant or not. type: string minLength: 1 maxLength: 250 examples: - Disabled terminalStatus: description: Indicates whether the device is online or offline. type: string minLength: 1 maxLength: 250 examples: - Online cloudStatus: description: Indicates whether cloud integration for the device is active. type: string minLength: 1 maxLength: 250 examples: - Online sharedMerchantIds: description: List of merchant IDs associated with the device when multi-MID sharing is enabled. Each merchant ID represents a merchant that can process transactions through the shared device. type: array items: {} examples: - - '6280490007617228' - '6280490007617244' - '6280490007617210' primaryMerchantId: description: Primary merchant ID assigned to the device and used as the default merchant account for transaction processing. type: string examples: - '6280490007617228' merchantId: description: Unique identifier of the merchant registered within the EMV Device Cloud platform. Used to associate devices, terminals, and transactions with a specific merchant account. type: string examples: - '6280490007617228' terminalId: description: Type or model of the EMV device registered in the EMV Device Cloud, used to determine supported capabilities and device-specific configurations. type: string examples: - '001' deviceType: description: Type or model of the EMV device registered in the EMV Device Cloud, used to determine supported capabilities and device-specific configurations. type: string examples: - Cloud posAccessKey: description: Authentication credential used by the Point-of-Sale (POS) application to securely connect and exchange information with the EMV Device Cloud. type: string examples: - 36b3607d96584290f5aad1175f94a351 terminalAccessKey: description: Authentication credential used to authorize communication between an EMV terminal and the EMV Device Cloud. type: string examples: - 204f3b9dde011ede53664c089fa30b88 merchantAccessKey: description: Authentication credential used to authorize merchant-level access to EMV Device Cloud services and resources. type: string examples: - v4123d6e4ecac9b57a9f34bce9144fce3 terminalConnectionId: description: The unique identifier of the terminal connection associated with an EMV device. type: string examples: - gUNNN-5hFQAYKEj_3A== example: devices: - merchantId: '6289980008342008' terminalId: '004' deviceType: Gateway deviceDisplayName: 001 Proddev terminalStatus: Active - deviceId: '10' deviceName: XUAT DESK3500 terminalName: XUAT DESK3500 terminalConnectionId: gTbF1-5XwQAYKEhuDA== deviceSerialNumber: '221197303251060424702233' multiMIDSharing: Enabled cloudStatus: Offline sharedMerchantIds: - '6289980008340630' - '6289980008342010' primaryMerchantId: '6289980008342008' posAccessKey: 36b3607d96584290f5aad1175f94a351 terminalAccessKey: 204f3b9dde011ede53664c089fa30b88 merchantAccessKey: 4123d6e4ecac9b57a9f34bce9144fce3 merchantId: '6289980008342008' terminalId: '001' deviceType: Cloud deviceDisplayName: New Test terminalStatus: Active - merchantId: '6289980008342008' terminalId: '001' deviceType: Standalone deviceDisplayName: Ingenico terminalStatus: Active - merchantId: '6289980008342008' terminalId: '001' deviceType: Gateway deviceDisplayName: QA D3500 Latest terminalStatus: Active - merchantId: '6289980008342008' terminalId: '003' deviceType: Standalone deviceDisplayName: QA D3500 WiFi RS terminalStatus: Active - deviceId: '9' deviceName: QA GD test WIFI terminalName: QA D3500 WIFI terminalConnectionId: gTbF1-5XwQAYKEhuDA=+ deviceSerialNumber: '24702233' multiMIDSharing: Enabled cloudStatus: Offline sharedMerchantIds: - '6289980008340630' - '6289980008342008' primaryMerchantId: '6289980008342010' posAccessKey: 36b3607d96584290f5aad1175f94a351 terminalAccessKey: 204f3b9dde011ede53664c089fa30b88 merchantAccessKey: '' merchantId: '6289980008342010' terminalId: '001' deviceType: Cloud deviceDisplayName: QA D3500 WIFI terminalStatus: Inactive '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /emv/devices/{deviceId}/refresh: post: operationId: emvDeviceRefreshById summary: EMV Device Refresh By Id tags: - emv description: Refreshes the device of the specified deviceId along with the associated partnerToken provided in the request. parameters: - name: deviceId in: path required: true schema: type: string description: Path parameter deviceId. requestBody: required: true content: application/json: schema: description: 'Request containing EMV transaction attributes **Note:** - A valid `terminalConnectionId` is required and must not be null or empty. - The `terminalConnectionId` can be retrieved from the **EMV Devices List** API or the **EMV Device Details By Id** API. - Device refresh is dependent on external services and may not complete immediately. - If the refresh fails, retry the request after a short interval. - A successful refresh generates a new `terminalConnectionId`. - Device refresh is applicable only for **Cloud** devices, not for **Standalone** or **Gateway**.' type: object properties: terminalConnectionId: description: A unique identifier assigned to the terminal connection associated with an EMV device. type: string examples: - gTbF1-5XwQAYKEhuDA== required: - terminalConnectionId example: terminalConnectionId: gWRUYC74KQAYKEhkeA== responses: '200': description: Successful response content: application/json: schema: description: Response DataType type: object properties: deviceId: description: Unique identifier of the EMV payment device. type: string minLength: 1 maxLength: 50 examples: - '10' terminalStatus: description: Indicates whether the device is online or offline. type: string minLength: 1 maxLength: 250 examples: - Online cloudStatus: description: Indicates whether cloud integration for the device is active. type: string minLength: 1 maxLength: 250 examples: - Online terminalAccessKey: description: Authentication credential used to authorize communication between an EMV terminal and the EMV Device Cloud. type: string examples: - 204f3b9dde011ede53664c089fa30b88 terminalConnectionId: description: The unique identifier of the terminal connection associated with an EMV device. type: string examples: - gTbF1-5XwQAYKEhuDA== requestId: description: Unique identifier for the API request. 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: - bb75b884-e7a7-4510-aabc-3fdade625654 responseMessage: description: Response message type: string examples: - Device refreshed successfully. example: deviceId: '10' terminalAccessKey: 204f3b9dde011ede53664c089fa30b88 terminalConnectionId: gTbF1-5XwQAYKEhuDA== cloudStatus: Online terminalStatus: Active responseMessage: Device refreshed successfully. requestId: 4fd7a890-83ec-11f1-8a76-7c1e523b13df '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /emv/devicedetails/{deviceId}: get: operationId: emvDeviceDetailsById summary: EMV Device Details By Id tags: - emv description: Retrieves the details of the specified deviceId along with the associated partnerToken provided in the request. parameters: - name: deviceId in: path required: true schema: type: string description: Path parameter deviceId. responses: '200': description: Successful response content: application/json: schema: description: 'Object to hold EMV device details **Note:** Response attributes are available for the following EMV device types: - Cloud - Standalone - Gateway' oneOf: - description: EMV payment device registered with a cloud-hosted platform, enabling remote terminal management, secure communication, transaction processing, and device monitoring. type: object properties: deviceId: description: Unique identifier of the EMV payment device. type: string minLength: 1 maxLength: 50 examples: - '10' deviceName: description: Name assigned to the EMV payment device. type: string minLength: 1 maxLength: 250 examples: - PROD DESK3500 cloudStatus: description: Indicates whether cloud integration for the device is active. type: string minLength: 1 maxLength: 250 examples: - Online sharedMerchantIds: description: List of merchant IDs associated with the device when multi-MID sharing is enabled. Each merchant ID represents a merchant that can process transactions through the shared device. type: array items: {} examples: - - '6280490007617228' - '6280490007617244' - '6280490007617210' primaryMerchantId: description: Primary merchant ID assigned to the device and used as the default merchant account for transaction processing. type: string examples: - '6280490007617228' posAccessKey: description: Authentication credential used by the Point-of-Sale (POS) application to securely connect and exchange information with the EMV Device Cloud. type: string examples: - 36b3607d96584290f5aad1175f94a351 terminalAccessKey: description: Authentication credential associated with a specific EMV terminal, used to authorize terminal-level communication with the EMV Device Cloud. type: string examples: - 204f3b9dde011ede53664c089fa30b88 merchantAccessKey: description: Authentication credential used to authorize merchant-level access to EMV Device Cloud services and resources. type: string examples: - v4123d6e4ecac9b57a9f34bce9144fce3 terminalConnectionId: description: The unique identifier of the terminal connection associated with an EMV device. type: string examples: - gUNNN-5hFQAYKEj_3A== merchantId: description: Unique identifier of the merchant registered within the EMV Device Cloud platform. Used to associate devices, terminals, and transactions with a specific merchant account. type: string examples: - '6280490007617228' terminalId: description: Type or model of the EMV device registered in the EMV Device Cloud, used to determine supported capabilities and device-specific configurations. type: string examples: - '001' deviceType: description: Type or model of the EMV device registered in the EMV Device Cloud, used to determine supported capabilities and device-specific configurations. type: string examples: - Cloud deviceDisplayName: description: Display name of the device through which EMV type payment is done. type: string minLength: 1 maxLength: 250 examples: - Prod Cloud 3500 terminalStatus: description: Indicates whether the device is online or offline. type: string minLength: 1 maxLength: 250 examples: - Active - description: EMV payment device that communicates directly with the Point-of-Sale (POS) application over a local network or physical connection, without relying on cloud-based terminal management or connectivity services. type: object properties: merchantId: description: Unique identifier of the merchant registered within the EMV Device Cloud platform. Used to associate devices, terminals, and transactions with a specific merchant account. type: string examples: - '6280490007617228' terminalId: description: Type or model of the EMV device registered in the EMV Device Cloud, used to determine supported capabilities and device-specific configurations. type: string examples: - '001' deviceType: description: Type or model of the EMV device registered in the EMV Device Cloud, used to determine supported capabilities and device-specific configurations. type: string examples: - Standalone deviceDisplayName: description: Display name of the device through which EMV type payment is done. type: string minLength: 1 maxLength: 250 examples: - Ingenicos terminalStatus: description: Indicates whether the device is online or offline. type: string minLength: 1 maxLength: 250 examples: - Active - description: EMV payment device integrated through a payment gateway, where transaction requests and terminal communications are routed via the gateway for authorization, processing, and device management. type: object properties: merchantId: description: Unique identifier of the merchant registered within the EMV Device Cloud platform. Used to associate devices, terminals, and transactions with a specific merchant account. type: string examples: - '6280490007617228' terminalId: description: Type or model of the EMV device registered in the EMV Device Cloud, used to determine supported capabilities and device-specific configurations. type: string examples: - '004' deviceType: description: Type or model of the EMV device registered in the EMV Device Cloud, used to determine supported capabilities and device-specific configurations. type: string examples: - Gateway deviceDisplayName: description: Display name of the device through which EMV type payment is done. type: string minLength: 1 maxLength: 250 examples: - 001 Proddev terminalStatus: description: Indicates whether the device is online or offline. type: string minLength: 1 maxLength: 250 examples: - Active example: deviceId: '10' deviceName: XUAT DESK3500 terminalConnectionId: gTbF1-5XwQAYKEhuDA== deviceSerialNumber: '221197303251060424702233' cloudStatus: Offline sharedMerchantIds: - '6289980008340630' - '6289980008342010' primaryMerchantId: '6289980008342008' posAccessKey: 36b3607d96584290f5aad1175f94a351 terminalAccessKey: 204f3b9dde011ede53664c089fa30b88 merchantAccessKey: 4123d6e4ecac9b57a9f34bce9144fce3 merchantId: '6289980008342008' terminalId: '001' deviceType: Cloud deviceDisplayName: New Test terminalStatus: Active '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /refunds: post: operationId: createRefund summary: Create Refund tags: - refunds description: Processes refunds through a single endpoint supporting multiple use cases. For standard refunds, provide the paymentId and refund amount. For standalone refunds, specify the refund amount and payment method details, such as card information (cardNumber, expirationDate, CVV) or ACH/Credit details (accountNumber, routingNumber, accountType). For vault refunds, use the paymentMethodId of a stored payment method along with the refund amount. This endpoint ensures flexibility and secure handling of all refund scenarios. requestBody: required: true content: application/json: schema: description: 'Refund endpoint supports 3 request types such as Refund, Credit, and Standalone Refund - **Refund**: Initiates a full or partial refund for an original transaction that has already settled. - **Credit**: Initiates a new credit(refund) transaction by providing ACH details. - **Standalone Refund**: Initiates a new refund transaction by providing payment method details such as Card or paymentMethodId.' oneOf: - description: Object represents the details for transaction reversal and includes the original payment ID, the amount to be refunded, and associated order details such as the order ID. It is used to process partial or full refunds against completed payments for specific orders. 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 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 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 required: - orderId required: - amount - paymentId - description: Object to hold the details to initiates a refund directly to ACH payment method without referencing a prior payment. It includes the refund amount, payment method details. type: object properties: amount: description: Object to hold amount details such as amount value and currency 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 the details of ACH payment method. 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 required: - amount - paymentMethod - description: Object to hold the details to initiates a refund directly to a payment method such as a card or a stored payment method ID without referencing a prior payment. It includes the refund amount, payment method details. type: object properties: amount: description: Object to hold amount details such as amount value and currency 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 the details of payment methods such as a card or vault. 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 vault information such as payment method identifier. type: object properties: paymentMethodId: description: Unique identifier for vaultID 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 required: - paymentMethodId additionalProperties: false required: - amount - paymentMethod example: paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 isACH: false amount: amount: 19.99 currency: USD responses: '200': description: Successful response content: application/json: schema: description: 'Refund endpoint returns one of three response types upon successful processing: Refund, Credit, or Standalone Refund. - **Refund:** Indicates a full or partial refund has been issued for a previously settled transaction. - **Credit:** Confirms a new credit (refund) transaction has been created using ACH details. - **Standalone Refund:** Confirms a new refund transaction has been processed using payment method details such as a card or paymentMethodId.' oneOf: - type: object properties: amountApproved: description: Approved payment amount type: number examples: - 99.95 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 orderId: description: Merchant order ID type: string examples: - Order123 parentPaymentId: description: The original transaction ID generated by the payment gateway 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 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: - amountApproved - authResponse - batchNumber - orderId - parentPaymentId - paymentId - requestId - responseCode - responseMessage - description: Object to hold the refund response 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 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 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 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: - '441248' 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 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: - accountResponseData - amountApproved - authResponse - batchNumber - customerId - fee - isPartial - orderId - paymentId - requestId - responseCode - responseMessage - subscriptionId - token - description: Object to hold the refund response 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 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 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 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: - '441248' 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 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: - accountResponseData - amountApproved - authResponse - batchNumber - customerId - fee - isPartial - orderId - paymentId - requestId - responseCode - responseMessage - subscriptionId - token example: amountApproved: 99.95 authResponse: ABC123 batchNumber: 1234 responseCode: 0 orderId: '471292130777329807' parentPaymentId: 1cb354f8-e7fb-44b5-a1d2-084625d208a6 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.' /refunds/batch: post: operationId: createBatchRefunds summary: Create Batch Refunds tags: - refunds description: The Batch refund end point allows you to send multiple refund or credit transctions in a single API call. This feature is useful when processing multiple refunds 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: - 04/14/2021 transactions: description: Array to hold refund and standalone refund transaction details type: array items: description: Union of Refund and StandaloneRefund oneOf: - description: Object to hold refund request 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: 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 required: - amount - paymentId - description: Object to hold standalone refund request type: object properties: 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: Card details type: object properties: card: 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 additionalProperties: false required: - amount - paymentMethod minItems: 1 required: - startDate - transactions example: startDate: 09/25/2025 transactions: - paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 amount: amount: 9.6 currency: USD - paymentId: f08c5b03-e175-4fba-a03e-d8e4c0ba0f64 amount: amount: 23.6 currency: USD responses: '200': description: Successful response content: application/json: schema: description: Response DataType type: array items: type: object properties: batchNumber: description: Unique identifier to identify the batch. All transactions with the same batch number will be processed together 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: - amountApproved - authResponse - batchNumber - paymentId - requestId - responseCode - responseMessage example: - batchNumber: 12345 amountApproved: 99.95 authResponse: '10' responseCode: 0 responseMessage: Amount Approved paymentId: d290f1ee-6c54-4b01-90e6-d701748f0851 requestId: a2406639-8692-4e1c-978d-1805eb13efdf - batchNumber: 45321 amountApproved: 21.95 authResponse: '10' responseCode: 0 responseMessage: Amount Approved paymentId: e290f1ee-6c54-4b01-90e6-d701748f0851 requestId: b4406639-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.' /subscriptions: post: operationId: createSubscription summary: Create Subscription tags: - subscriptions description: This API endpoint creates a new subscription for a customer with the specified payment and billing details. You need to provide the following information payment type, amount (including currency), payment method (such as credit card details and billing address), and subscription details (such as start and end dates, frequency, and payment schedule). Additionally, you can specify shipping address, tax information, itemized details (Level 2 and Level 3 data), custom data, merchant category, and any alternate fees. Upon successful subscription creation, a unique subscription identifier and order details will be generated, and the subscription will be scheduled according to the provided parameters. requestBody: required: true content: application/json: schema: description: Request object to hold details to create a subscription, including payment method, subscription specifics, billing and shipping addresses, and tax information. 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 to handle surcharges. 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: 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 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 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 subscription: description: Object to hold subscription details type: object properties: startDate: description: Specifies the starting date from which recurring billing begins. The startDate must either match the subscription transaction date or be set to a future date. type: string examples: - 10/25/2023 endDate: description: Defines the termination date of the subscription period. type: string examples: - 10/25/2025 frequency: description: Indicates how often billing occurs e.g., Monthly, Quarterly, or Annually type: string enum: - Daily - Weekly - BiWeekly - TriWeekly - Monthly - BiMonthly - Quarterly - Annually - Custom - SemiAnnually examples: - Monthly active: description: Boolean flag to reflect whether the subscription is currently active or not type: boolean default: true examples: - true paymentDay: description: Specifies the designated day of the week (e.g., Sunday) when payment is scheduled to process; useful for weekly plans. type: string enum: - Monday - Tuesday - Wednesday - Thursday - Friday - Saturday - Sunday examples: - Sunday paymentMonth: description: Defines the month (1 to 12) when payment is intended to occur, relevant for annual billing cycles. type: integer minimum: 1 maximum: 12 examples: - 10 custom: description: Object to hold the custom subscription details. type: object properties: interval: description: Specifies the frequency of the billing cycle based on the defined interval type. type: number minimum: 1 examples: - 5 intervalType: description: Defines the unit of time used for the billing interval (for example, daily, weekly, monthly, or yearly). type: string enum: - DAY - WEEK - MONTH - YEAR examples: - DAY duration: description: 'Specifies how long the subscription will continue. - **FIXED_PAYMENTS:** Runs for a limited number of payments. - **UNTIL_END_DATE:** The subscription continues indefinitely until end date. - **UNTIL_CANCELLED:** The subscription continues indefinitely until manually cancelled.' type: string enum: - UNTIL_CANCELLED - UNTIL_END_DATE - FIXED_PAYMENTS examples: - FIXED_PAYMENTS numberOfPayments: description: Specifies the total number of billing cycles for the subscription. This field is required when duration is set to FIXED and is ignored when duration is UNTIL_CANCELLED. type: number minimum: 1 examples: - 5 required: - endDate - frequency - startDate shippingAddress: description: Shipping Information object 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 merchantCategory: description: Industry in which merchant operates type: string maxLength: 100 examples: - E-Commerce 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 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. 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 deviceId: description: Fleet data capturing deviceId type: string maxLength: 50 examples: - '1' required: - amount - paymentMethod - paymentType - subscription example: paymentType: Sale 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 subscription: startDate: 10/25/2023 endDate: 10/25/2025 frequency: Monthly active: true paymentDay: Sunday paymentMonth: 10 custom: interval: 1 intervalType: MONTH duration: UNTIL_CANCELLED numberOfPayments: 5 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 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: '9875612345' customData: - name: Invoice Number value: inv1234 merchantCategory: E-Commerce deviceId: '1' paymentCompleteDate: 09/25/2023 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: Object to hold the subscription response 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 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 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 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 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: - '441248' 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 - paymentMethodId - requestId - responseMessage - subscriptionId - token example: isPartial: false orderId: Order123 customerId: 7896 batchNumber: 1234 subscriptionId: 9a2cb7fe-119c-48ef-973e-8299246df7c2 paymentMethodId: d10f860c-ab05-4002-86b3-b4a707d9a999 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.' /subscriptions/{subscriptionId}: patch: operationId: modifySubscription summary: Modify Subscription tags: - subscriptions description: This API endpoint modifies an existing subscription identified by the subscriptionId passed in the URL. You must provide the customer’s ID, the payment method ID, and updated subscription details including frequency, paymentDay, startDate, endDate, paymentMonth, amount, and active. Upon successful modification, the subscription is updated accordingly, and a confirmation with the updated details is returned. parameters: - name: subscriptionId in: path required: true schema: type: string description: Path parameter subscriptionId. - name: partnerToken in: header required: true schema: 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: - 80ae9a4a-5efd-412e-89b9-532f2ab2f817 description: Unique Merchant Identifier for API Calls example: 80ae9a4a-5efd-412e-89b9-532f2ab2f817 - name: requestId in: header required: false schema: 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: - 56ae9a4a-5efd-412e-89b9-532f2ab2f275 description: 'Unique request identifier in GUID format included in the header, used to trace and correlate API calls across systems. > **Note:** We strongly recommend including the `requestId` header in every API request. This unique GUID helps trace and correlate API calls across systems, ensuring better observability and troubleshooting.' example: 56ae9a4a-5efd-412e-89b9-532f2ab2f275 requestBody: required: true content: application/json: schema: description: Request DataType type: object properties: customer: description: Object to hold customer details type: object properties: customerId: description: Unique identifier for a customer type: number examples: - 5687 required: - customerId paymentMethod: description: Object to hold payment details type: object properties: 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 required: - paymentMethodId subscription: description: Subscription details type: object properties: startDate: description: Specifies the starting date from which recurring billing begins. The startDate must either match the subscription transaction date or be set to a future date. type: string examples: - 10/25/2023 endDate: description: Defines the termination date of the subscription period. type: string examples: - 10/25/2025 frequency: description: Indicates how often billing occurs e.g., Monthly, Quarterly, or Annually type: string enum: - Daily - Weekly - BiWeekly - TriWeekly - Monthly - BiMonthly - Quarterly - Annually - Custom - SemiAnnually examples: - Monthly active: description: Boolean flag to reflect whether the subscription is currently active or not type: boolean default: true examples: - true paymentDay: description: Specifies the designated day of the week (e.g., Sunday) when payment is scheduled to process; useful for weekly plans. type: string enum: - Monday - Tuesday - Wednesday - Thursday - Friday - Saturday - Sunday examples: - Sunday paymentMonth: description: Defines the month (1 to 12) when payment is intended to occur, relevant for annual billing cycles. type: integer minimum: 1 maximum: 12 examples: - 10 custom: description: Object to hold the custom subscription details. type: object properties: interval: description: Specifies the frequency of the billing cycle based on the defined interval type. type: number minimum: 1 examples: - 5 intervalType: description: Defines the unit of time used for the billing interval (for example, daily, weekly, monthly, or yearly). type: string enum: - DAY - WEEK - MONTH - YEAR examples: - DAY duration: description: 'Specifies how long the subscription will continue. - **FIXED_PAYMENTS:** Runs for a limited number of payments. - **UNTIL_END_DATE:** The subscription continues indefinitely until end date. - **UNTIL_CANCELLED:** The subscription continues indefinitely until manually cancelled.' type: string enum: - UNTIL_CANCELLED - UNTIL_END_DATE - FIXED_PAYMENTS examples: - FIXED_PAYMENTS numberOfPayments: description: Specifies the total number of billing cycles for the subscription. This field is required when duration is set to FIXED and is ignored when duration is UNTIL_CANCELLED. type: number minimum: 1 examples: - 5 amount: description: Amount of the subscription type: number examples: - 19.99 required: - amount - endDate - frequency - startDate example: customer: customerId: 5687 paymentMethod: paymentMethodId: d10f860c-ab05-4002-86b3-b4a707d9a999 subscription: amount: 19.99 startDate: 10/25/2023 endDate: 10/25/2025 frequency: Monthly active: true paymentDay: Sunday paymentMonth: 10 custom: interval: 1 intervalType: MONTH duration: UNTIL_CANCELLED numberOfPayments: 5 responses: '200': description: Successful response content: application/json: schema: description: Subscription response. type: object properties: 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 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: - null 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 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: - d290f1ee-6c54-4b01-90e6-d701748f0851 customerId: description: Unique identifier for a customer type: number examples: - 5678 required: - authResponse - customerId - paymentMethodId - requestId - responseCode - responseMessage - subscriptionId example: subscriptionId: 9a2cb7fe-119c-48ef-973e-8299246df7c2 authResponse: ABC123 responseCode: 0 responseMessage: null requestId: a2406639-8692-4e1c-978d-1805eb13efdf paymentMethodId: d290f1ee-6c54-4b01-90e6-d701748f0851 customerId: 5678 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /paymentmethods: post: operationId: createPaymentMethod summary: Create Payment Method tags: - paymentmethods description: This API endpoint allows you to create a new payment method for a customer. You need to provide details including a nickname for the payment method, its active status, ACH information (such as account number and routing number), and the billing address. Additionally, you must specify the customer ID associated with the payment method. The API will store these details securely for future transactions. requestBody: required: true content: application/json: schema: description: Request DataType type: object properties: customerId: description: Unique identifier for a customer type: number examples: - 4321 paymentMethod: description: payment method details oneOf: - description: Object to hold card details type: object properties: card: description: Object to hold card details 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 required: - card - expiry 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 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 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 token details type: object properties: token: description: Object to hold token details 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 required: - expiry - token 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 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 required: - customerId - paymentMethod example: customerId: 11989 paymentMethod: accNickName: anusha isActive: false card: card: '374245455400126' expiry: 05/26 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' responses: '200': description: Successful response content: application/json: schema: description: Response parameters for the API type: object properties: 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 customerId: description: Unique identifier for a customer type: number examples: - 4321 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: - customerId - paymentMethodId - requestId example: customerId: 123 paymentMethodId: dc4017fd-5b14-1496-3274-298337c01289 requestId: 056e9055-cf2d-48c3-93db-918e3ec583d0 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /paymentmethods/{paymentMethodId}: patch: operationId: modifyPaymentMethod summary: Modify Payment Method tags: - paymentmethods description: This API endpoint allows you to update an existing payment method for a customer. You can modify details such as the payment method nickname, its active status, ACH information (including account number and routing number), and the billing address. Additionally, you need to provide the customer ID to identify which payment method to update. The API ensures that all changes are applied securely to the specified payment method. parameters: - name: paymentMethodId in: path required: true schema: type: string description: Path parameter paymentMethodId. - name: partnerToken in: header required: true schema: 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: - 80ae9a4a-5efd-412e-89b9-532f2ab2f817 description: Unique Merchant Identifier for API Calls example: 80ae9a4a-5efd-412e-89b9-532f2ab2f817 - name: requestId in: header required: false schema: 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: - 56ae9a4a-5efd-412e-89b9-532f2ab2f275 description: 'Unique request identifier in GUID format included in the header, used to trace and correlate API calls across systems. > **Note:** We strongly recommend including the `requestId` header in every API request. This unique GUID helps trace and correlate API calls across systems, ensuring better observability and troubleshooting.' example: 56ae9a4a-5efd-412e-89b9-532f2ab2f275 requestBody: required: true content: application/json: schema: description: Request DataType type: object properties: customerId: description: Unique identifier for a customer type: number examples: - 4321 paymentMethod: description: Payment method details oneOf: - description: Object to hold card details type: object properties: card: description: Card details 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 required: - expiry 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 payment information type: object properties: ach: description: ACH details 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 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 - type: object properties: cryptogram: description: cryptogram details type: object properties: cryptogram: description: Tokenized string that passes Card or Bank details for transaction type: string examples: - 6cd3ef836ce141b789b5755ca3f353f1 required: - cryptogram 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 account token details type: object properties: token: description: Token details 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 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 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 - description: Object to hold fleet card details type: object properties: fleetCard: type: object properties: card: description: Fleet Card Number type: string minLength: 12 maxLength: 19 examples: - '6900460430001234566' expiry: description: Fleet Card Expiration Month and Year type: string pattern: ^(0[1-9]|1[0-2])\/\d{2}$ examples: - 11/26 additionalProperties: false sequenceNumber: description: Sequence number of the fleet card transaction type: string minLength: 5 maxLength: 5 examples: - '76545' odometer: description: Odometer reading of the fleet card transaction type: string minLength: 1 maxLength: 9 examples: - '87655' driversLicenseNumber: description: Driving Licence number of the fleet card transaction type: string minLength: 1 maxLength: 15 examples: - '234667' 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 required: - customerId - paymentMethod example: customerId: 11996 paymentMethod: card: card: '378282246310005' expiry: 05/26 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' accNickName: test isActive: false responses: '200': description: Successful response content: application/json: schema: description: Response parameters for the API type: object properties: 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 customerId: description: Unique identifier for a customer type: number examples: - 4321 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: - customerId - paymentMethodId - requestId example: customerId: 1234 paymentMethodId: b7a04890-231c-f71c-62bf-6a910a45c2fd requestId: 142de31d-8f8f-4ba0-a2c2-29265b501c89 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /paymentmethods/token: post: operationId: generateToken summary: Generate Token tags: - paymentmethods description: This API endpoint generates a secure token for a payment method, which can be used for future transactions without storing sensitive payment details directly. The input requires credit card information, including the card number, expiry date, and CVV. The API responds with a token that represents the payment method, along with a response code, payment ID, and request ID. This token can then be used in subsequent API calls to process payments securely. requestBody: required: true content: application/json: schema: description: Request DataType type: object properties: paymentMethod: description: Object to hold payment details oneOf: - description: Object to hold card details type: object properties: card: description: Object to hold card details 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 additionalProperties: false - description: Object to hold payment information type: object properties: ach: description: Object to hold payment information 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 required: - paymentMethod example: paymentMethod: card: card: '4111111111111110' expiry: 11/26 cvv: '245' responses: '200': description: Successful response content: application/json: schema: type: object properties: token: description: Payment token used type: string examples: - '1556778677451110' responseCode: description: Authorizer response code type: number examples: - 0 responseMessage: description: Description of response code type: - string - 'null' 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: - paymentId - requestId - responseCode - responseMessage - token example: token: '1556778677451110' 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.' /paymentmethods/avs: post: operationId: verifyAddress summary: Verify Address tags: - paymentmethods description: Initiates an Address Verification Service (AVS) check for the provided billing address.This request will validate the address details (e.g., street address, zip code) and return a response indicating whether the address matches the records on file with the payment provider. requestBody: required: true content: application/json: schema: description: Request details used to get avs. type: object properties: paymentMethod: description: Payment method details used to get avs. 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 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 required: - paymentMethod example: paymentMethod: card: card: '4141414141414141' expiry: 12/25 billingAddress: firstName: Narthana lastName: Chepyala address: 1331 LAKE FOREST DR address2: San city: Fort Worth state: TX country: US postalCode: '12345' phone: '+18985683254' email: narthana.chepyala@email.com responses: '200': description: Successful response content: application/json: schema: description: Object to hold avs response details. type: object properties: accountResponseData: description: Object to hold account response data. 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 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 examples: - Success 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 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 required: - accountResponseData - authResponse - paymentId - requestId - responseCode - responseMessage example: accountResponseData: avs: Y cvv: Y authResponse: ABC123 responseCode: 0 responseMessage: response message requestId: 7f9a96d2-d60f-41d3-b34c-05dd01298618 paymentId: 7a0afa41-9c13-4a80-a7d3-9f5c8eb62a36 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /paymentmethods/verification/ach: post: operationId: verifyAch summary: Verify ACH tags: - paymentmethods description: Initiates an ACH Verification requestBody: required: true content: application/json: schema: description: Request details used for ACH verification. type: object properties: paymentMethod: description: Payment method details used to get avs. type: object properties: ach: description: Card details used to get avs. 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' required: - accountNumber - routingNumber currency: description: Currency type: string enum: - USD - CAD examples: - USD example: paymentMethod: ach: routingNumber: '123456789' accountNumber: '987654321' currency: USD responses: '200': description: Successful response content: application/json: schema: description: Object to hold avs response details. type: object properties: status: description: ACH Verification status type: string enum: - INVALID - VALID - BLOCKED isValidRoutingNumber: description: Boolean flag that specifies if the routing number is valid. type: boolean examples: - true responseMessage: description: Description of response code type: string examples: - Success 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: - isValidRoutingNumber - requestId - responseMessage - status example: status: INVALID isValidRoutingNumber: true responseMessage: Success 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.' /paymentmethods/surcharge: post: operationId: checkSurcharge summary: Check Surcharge tags: - paymentmethods description: This API endpoint allows you to verify the surcharge associated to merchant for the given payment methods such as card, token, vault and cryptogram. The input requires a payment method and optional amount and currency and you will get surcharge rate/percentage and surcharge amount in response. This will help merchants to check the applicable surcharge rate before actual transaction. requestBody: required: true content: application/json: schema: description: Request details to get Surcharge type: object properties: paymentMethod: description: Object to hold the payment method details that are using to get Surcharge oneOf: - description: Object to hold card details type: object properties: card: description: Card object containing card number type: object properties: card: description: Card Number type: string minLength: 12 maxLength: 19 examples: - '4111111111111110' required: - card - type: object properties: token: type: object properties: token: description: Tokenized string for Card details type: string maxLength: 20 examples: - '1234567890123450' required: - token additionalProperties: false - type: object properties: vault: 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 required: - paymentMethodId additionalProperties: false - type: object properties: cryptogram: type: object properties: cryptogram: description: Tokenized string that passes Card or Bank details type: string examples: - 6cd3ef836ce141b789b5755ca3f353f1 required: - cryptogram additionalProperties: false amount: description: Object to hold the 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 required: - paymentMethod example: paymentMethod: card: card: '4141414141414141' amount: amount: 10 currency: USD responses: '200': description: Successful response content: application/json: schema: type: object properties: surchargeRate: description: Applicable rate or percentage of the surcharge for a given payment method type: number examples: - 3 surchargeAmount: description: Applicable amount of the surcharge for a given payment method type: number examples: - 0.3 cardType: description: Type of the card that surcharge is retriving. i.e DEBIT or CREDIT type: string examples: - Card isSurchargeEnabled: description: Flag to tell if the surcharge is enabled or not type: boolean examples: - true 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: - cardType - isSurchargeEnabled - requestId - surchargeRate example: surchargeRate: 3 surchargeAmount: 0.3 cardType: CREDIT isSurchargeEnabled: true requestId: fe4e03ad-b047-4bbd-a7ba-b8a136785b58 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /paymentmethods/binlookup: get: operationId: binLookup summary: BIN Lookup tags: - paymentmethods description: Verify BIN lookup retrieves details by passing the first 6 to 8 digits of the card number. It returns information such as whether the cardholder is eligible for Level 2 or Level 3 surcharges, the card type, brand, and country. parameters: - name: partnerToken in: header required: true schema: 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: - 80ae9a4a-5efd-412e-89b9-532f2ab2f817 description: Unique Merchant Identifier for API Calls example: 80ae9a4a-5efd-412e-89b9-532f2ab2f817 - name: requestId in: header required: false schema: 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: - 56ae9a4a-5efd-412e-89b9-532f2ab2f275 description: 'Unique request identifier in GUID format included in the header, used to trace and correlate API calls across systems. > **Note:** We strongly recommend including the `requestId` header in every API request. This unique GUID helps trace and correlate API calls across systems, ensuring better observability and troubleshooting.' example: 56ae9a4a-5efd-412e-89b9-532f2ab2f275 - name: bin in: query required: true schema: type: string minLength: 6 maxLength: 8 examples: - '411111' description: BIN used to retrieve details. example: '411111' responses: '200': description: Successful response content: application/json: schema: type: object properties: bin: description: BIN used to retrieve card details. type: string examples: - '411111' cardType: description: Indicates the type of card associated with the provided BIN (Bank Identification Number), such as CREDIT,DEBIT. type: string enum: - CREDIT - DEBIT examples: - CREDIT brand: description: The brand of the card. type: string examples: - VISA country: description: Full country name where the card was issued. type: object properties: name: description: Full country name where the card was issued. type: string examples: - UNITED STATES abbreviation: description: ISO or short-form code of the country. type: string examples: - USA required: - abbreviation - name prepaid: description: Indicates whether the card is a prepaid card. type: boolean examples: - false qualifications: description: Indicates whether the BIN qualifies for Level 2 or Level 3 processing along with surcharge eligibility details. type: object properties: level2: description: Indicates if the card qualifies for Level 2 processing. type: boolean examples: - true level3: description: Indicates if the card qualifies for Level 3 processing. type: boolean examples: - true surcharge: description: Indicates whether a surcharge can be applied to the card. type: boolean examples: - false required: - level2 - level3 - surcharge required: - bin - brand - cardType - country - prepaid - qualifications example: bin: '411111' cardType: CREDIT brand: VISA prepaid: false country: name: UNITED STATES abbreviation: USA qualifications: level2: true level3: true surcharge: false '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /customers: post: operationId: createCustomer summary: Create Customer tags: - customers description: The Create Customer API allows you to add a new customer to the system by providing their personal and contact information, including name, address, phone number, and email. Additionally, you can also crate a payment method using card, ACH, token, ACHToken and Cryptograms while creating customer with optional billing address details. requestBody: required: true content: application/json: schema: description: Object to hold customer's 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: 10 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: - +1-212-456-7890 email: description: Customer's email address type: string maxLength: 250 examples: - john@email.com companyName: description: Customer's company or organization name. type: string maxLength: 75 examples: - Deluxe Corp paymentMethods: description: Payment Methods type: array items: description: Payment method details such as Card, ACH, Token, ACHToken and Cryptogram. oneOf: - description: Object to hold card details type: object properties: card: 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 required: - card - expiry additionalProperties: false accNickName: description: Convenient name for stored payment method type: string examples: - Visa-Debit isActive: description: Flag to tell if customer vault is active type: boolean examples: - true 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 - 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 accNickName: description: Convenient name for stored payment method type: string examples: - Visa-Debit isActive: description: Flag to tell if customer vault is active type: boolean examples: - true 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 - description: Object to hold tokenized card details type: object properties: token: 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 required: - expiry - token additionalProperties: false accNickName: description: Convenient name for stored payment method type: string examples: - token isActive: description: Flag to tell if customer vault is active type: boolean examples: - true 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 - description: Object to hold ACH Token details 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 isActive: description: Flag to tell if customer vault is active type: boolean examples: - true accNickName: description: Convenient name for stored payment method type: string examples: - ach token - description: Object to hold Cryptogram details 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 accNickName: description: Convenient name for stored payment method type: string examples: - cryptogram isActive: description: Flag to tell if customer vault is active type: boolean examples: - true - description: Object to hold fleet card details type: object properties: fleetCard: type: object properties: card: description: Card Number type: string minLength: 12 maxLength: 19 examples: - '869420240004455' expiry: description: Card Expiration Month and Year type: string pattern: ^(0[1-9]|1[0-2])\/\d{2}$ examples: - 11/26 required: - card - expiry additionalProperties: false accNickName: description: Convenient name for stored payment method type: string examples: - Wex Card isActive: description: Flag to tell if customer vault is active type: boolean examples: - true sequenceNumber: description: Sequence number of the fleet card transaction type: string minLength: 5 maxLength: 5 examples: - '56432' odometer: description: Odometer reading of the fleet card transaction type: string minLength: 1 maxLength: 9 examples: - '4354235' driversLicenseNumber: description: Driving Licence number of the fleet card transaction type: string minLength: 1 maxLength: 15 examples: - '2346' 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 required: - driversLicenseNumber - odometer - sequenceNumber minItems: 1 required: - firstName example: firstName: Narayana lastName: Konuri address: 123 east Main St postalCode: '94111' city: San Francisco state: CA country: USA phone: '9866812622' email: narayana.konuri@email.com companyName: Deluxe Corp paymentMethods: - accNickName: Shopping Account isActive: true ach: accountNumber: '987654321' routingNumber: '123456789' accountType: Checking 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 responses: '200': description: Successful response content: application/json: schema: description: Response parameters for the API type: object properties: customerId: description: Unique identifier for a customer type: number examples: - 4321 paymentMethodId: type: - array - 'null' items: type: string description: Unique identifier for a payment methods (ACH or Card) 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 examples: - a2406639-8692-4e1c-978d-1805eb13efdf required: - customerId - paymentMethodId - requestId example: customerId: 24582 paymentMethodId: - dc4017fd-5b14-1496-3274-298337c01289 requestId: 3a1a75ce-00b0-4c87-bed5-fc97007ebef6 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' get: operationId: getAllCustomers summary: Get All Customers tags: - customers description: The Get Customers API retrieves a list of all customers along with their associated details. Each customer record includes basic information such as name, address, contact details, and email. Additionally, the response provides information about the customer’s shipping address, payment methods stored in the vault, and any active subscriptions. Payment methods include details like card type, masked PAN, and account information, while subscription details include the start and end dates, frequency, and status. responses: '200': description: Successful response content: application/json: schema: type: array example: - customerId: 27573 phone: +1-8973452344 city: New York address2: '' postalCode: '10022' state: NY address: 9011 1234 Block lastName: TestOFLHM firstName: Automation country: US email: DPPAutomationTestUser@gmail.com companyName: Deluxe Corp shippingAddress: state: '' address: '' lastName: '' firstName: '' email: test@gmail.com country: '' phone: '1234567890' city: '' address2: '' postalCode: '' vaults: - vaultCreated: '2024-04-22T00:20:44.757' accNickName: Visa-Debit isActive: true sequenceNumber: '34521' odometer: '675437' driversLicenseNumber: '87654' paymentMethodId: 474a4400-9114-4950-957d-4da198c307ed cardType: Mastercard maskedPan: 555555******4444 expiry: 12/35 token: '2632418387214444' accountNumber: '' routingNumber: '' accountType: Checking billingAddress: firstName: Jane lastName: Doe address: 123 Main St26 address2: Apt 5 city: San Francisco state: CA country: USA postalCode: '94111' phone: 650-555-1234 email: jane@email.com subscription: - frequency: null amount: '0' paymentDay: null endDate: '0001-01-01T00:00:00' paymentMonth: null startDate: '0001-01-01T00:00:00' active: false subscriptionId: 00000000-0000-0000-0000-000000000000 - customerId: 27583 phone: +1-8973452344 city: New York address2: '' postalCode: '10022' state: NY address: 1922 1234 Block lastName: TestLEEGY firstName: Automation country: US email: DPPAutomationTestUser@gmail.com shippingAddress: state: '' address: '' lastName: '' firstName: '' email: test@gmail.com country: '' phone: '1234567890' city: '' address2: '' postalCode: '' vaults: - vaultCreated: '2024-04-22T00:38:41.8' accNickName: Account-Debit isActive: false sequenceNumber: '77653' odometer: '987645' driversLicenseNumber: '123454' paymentMethodId: a61103cb-934d-4855-97cb-5fc913460bdd cardType: Mastercard maskedPan: 555555******4444 expiry: 12/35 token: '2632418387214444' accountNumber: '' routingNumber: '' accountType: Checking billingAddress: firstName: Jane lastName: Doe address: 123 Main St26 address2: Apt 5 city: San Francisco state: CA country: USA postalCode: '94111' phone: 650-555-1234 email: jane@email.com subscription: - frequency: null amount: '0' paymentDay: null endDate: '0001-01-01T00:00:00' paymentMonth: null startDate: '0001-01-01T00:00:00' active: false subscriptionId: 00000000-0000-0000-0000-000000000000 - customerId: 27589 phone: +1-8973452344 city: New York address2: '' postalCode: '10022' state: NY address: 9653 1234 Block lastName: TestGLCEJ firstName: Automation country: US email: DPPAutomationTestUser@gmail.com shippingAddress: state: '' address: '' lastName: '' firstName: '' email: test@gmail.com country: '' phone: '1234567890' city: '' address2: '' postalCode: '' vaults: - vaultCreated: '2024-04-22T00:46:34.227' accNickName: Visa-Debit isActive: true sequenceNumber: '64563' odometer: '987654' driversLicenseNumber: '134576' paymentMethodId: 631c3879-e006-49f0-9a11-6ebf6a721f7c cardType: ACH Checking maskedPan: '**8654' expiry: '' token: '' accountNumber: '' routingNumber: '122105155' accountType: Checking billingAddress: firstName: Jane lastName: Doe address: 123 Main St26 address2: Apt 5 city: San Francisco state: CA country: USA postalCode: '94111' phone: 650-555-1234 email: jane@email.com subscription: - frequency: null amount: '0' paymentDay: null endDate: '0001-01-01T00:00:00' paymentMonth: null startDate: '0001-01-01T00:00:00' active: false subscriptionId: 00000000-0000-0000-0000-000000000000 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /customers/{customerId}: patch: operationId: modifySpecificCustomer summary: Modify Specific Customer tags: - customers description: The Modify Customer API allows you to update the details of an existing customer. You can modify the customer’s personal information, such as their first and last name, address, phone number, and email. This ensures that all customer records remain accurate and up-to-date. parameters: - name: customerId in: path required: true schema: type: string description: Path parameter customerId. requestBody: required: true content: application/json: schema: description: Object to hold customer's 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: 10 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: - +1-212-456-7890 email: description: Customer's email address type: string maxLength: 250 examples: - john@email.com companyName: type: string maxLength: 75 examples: - Deluxe Corp required: - firstName example: firstName: Jane lastName: Doe address: 123 Main St address2: 123 Main St city: San Francisco state: CA country: USA postalCode: '94111' email: john@email.com companyName: Deluxe Corp phone: +1-212-456-7890 responses: '200': description: Successful response content: application/json: schema: description: Response parameters for the API type: object properties: customerId: description: Unique identifier for a customer type: number examples: - 4321 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: - customerId - requestId example: customerId: 24582 requestId: fe4e03ad-b047-4bbd-a7ba-b8a136785b58 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' get: operationId: getSpecificCustomer summary: Get Specific Customer tags: - customers description: This API retrieves the details of a specific customer using their unique identifier, including name, address, contact details, and email. It also returns the customer's shipping address, stored payment methods, and any active subscriptions. Payment methods include details such as card type, masked PAN, and account information, while subscription details cover start and end dates, frequency, and status. parameters: - name: customerId in: path required: true schema: type: string description: Path parameter customerId. responses: '200': description: Successful response content: application/json: schema: type: object properties: customerId: type: number examples: - 4321 firstName: type: string maxLength: 100 examples: - John lastName: type: string maxLength: 100 examples: - Doe address: type: string maxLength: 250 examples: - 123 Main St address2: type: string maxLength: 100 examples: - Apt 5 city: type: string maxLength: 50 examples: - San Francisco postalCode: type: string maxLength: 10 examples: - '94111' state: type: string maxLength: 25 examples: - CA country: type: string maxLength: 25 examples: - USA phone: type: string maxLength: 50 examples: - +1-650-555-1234 email: type: string maxLength: 250 examples: - john@email.com companyName: type: string maxLength: 75 examples: - Deluxe Corp shippingAddress: description: Object to hold the shipping address. 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 vaults: description: Vault(s) details associated to this cutomer. type: array items: description: Vault details type: object properties: accNickName: description: Convenient name for stored payment method type: string examples: - Visa-Debit vaultCreated: type: string examples: - '2021-11-26T00:00:00' isActive: type: boolean examples: - true sequenceNumber: description: Sequence number of the fleet card transaction type: string examples: - '12345' odometer: description: Odometer reading of the fleet card transaction type: string examples: - '4354235' driversLicenseNumber: description: Driving Licence number of the fleet card transaction type: string examples: - '2346' paymentMethodId: 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 cardType: type: string examples: - Visa maskedPan: type: string examples: - 4111********4321 expiry: type: string examples: - 11/25 token: type: string maxLength: 16 examples: - '8791230000000000' accountNumber: type: string examples: - '987654321' routingNumber: type: string examples: - '123456789' accountType: type: string enum: - Checking - Savings examples: - Checking billingAddress: description: Billing address details associated to this vault. 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 subscriptions: description: Subscription(s) details associated to this vault. type: array items: description: Subscription details type: object properties: 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 startDate: type: string examples: - 10/25/2023 endDate: type: string examples: - 10/25/2025 frequency: type: string enum: - Daily - Weekly - BiWeekly - TriWeekly - Monthly - BiMonthly - Quarterly - Annually examples: - Monthly active: type: boolean default: true examples: - true paymentDay: type: string enum: - Monday - Tuesday - Wednesday - Thursday - Friday - Saturday - Sunday examples: - Sunday paymentMonth: type: integer minimum: 1 maximum: 12 examples: - 10 required: - subscriptionId required: - accNickName required: - customerId - firstName example: customerId: 24582 phone: '9866812622' city: San Francisco address2: '' postalCode: '' state: CA address: 123 east Main St lastName: name firstName: test country: USA email: sowndarrajan@email.com companyName: Deluxe Corp shippingAddress: state: '' address: '' lastName: '' firstName: '' email: test123@gmail.com country: '' phone: '1234567890' city: '' address2: '' postalCode: '' vaults: - vaultCreated: '2024-03-15T01:32:45.653' accNickName: Visa-Debit isActive: true sequenceNumber: '65486' odometer: '2456546' driversLicenseNumber: '98766' paymentMethodId: ee0b82f2-5682-ec0c-f75a-12270d6a1f78 cardType: '' maskedPan: '' expiry: '' token: '' accountNumber: '' routingNumber: '' accountType: Checking billingAddress: firstName: Jane lastName: Doe address: 123 Main St26 address2: Apt 5 city: San Francisco state: CA country: USA postalCode: '94111' phone: 650-555-1234 email: jane@email.com subscription: - frequency: null amount: '0' paymentDay: null endDate: '0001-01-01T00:00:00' paymentMonth: null startDate: '0001-01-01T00:00:00' active: false subscriptionId: 00000000-0000-0000-0000-000000000000 - vaultCreated: '2024-04-11T10:09:46.193' accNickName: Account-Debit isActive: false sequenceNumber: '87657' odometer: '9875587' dlNumber: '45345' paymentMethodId: 10fdca6f-a446-1e18-0a24-219c6c1ff0e6 cardType: '' maskedPan: '' expiry: '' token: '' accountNumber: '' routingNumber: '' accountType: Savings billingAddress: firstName: Jane lastName: Doe address: 123 Main St26 address2: Apt 5 city: San Francisco state: CA country: USA postalCode: '94111' phone: 650-555-1234 email: jane@email.com subscription: - frequency: null amount: '0' paymentDay: null endDate: '0001-01-01T00:00:00' paymentMonth: null startDate: '0001-01-01T00:00:00' active: false subscriptionId: 00000000-0000-0000-0000-000000000000 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' delete: operationId: deleteSpecificCustomer summary: Delete Specific Customer tags: - customers description: 'Deletes the customer identified by the given customer ID and permanently removes all associated records, including personal details,contact information,email,payment methods and subscriptions. >**Note:** > - The customer will be permanently removed from the Vault. > - All upcoming payments will be cancelled. > - All associated transactions will no longer be linked to the customer. > - Perform an impact or dependency check before deletion using the endpoint:"https://api.deluxe.com/dpp/v1/customers/{customerId}"' parameters: - name: customerId in: path required: true schema: type: string description: Path parameter customerId. responses: '200': description: Successful response content: application/json: schema: description: Response details type: object properties: customerId: type: number examples: - 4321 responseMessage: description: Description of response code type: - string - 'null' examples: - Customer deleted successfully 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: - customerId - requestId - responseMessage example: customerId: 12345 responseMessage: Customer deleted successfully 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.' /customers/{customerId}/paymentmethods/{paymentMethodId}: get: operationId: getCustomerSPaymentMethod summary: Get Customer's Payment Method tags: - customers description: This API endpoint allows you to get an existing payment method for a customer. The payment details such as orderId, batchNumber, SubscriptionId (if applicable), fee, token details, account response data, paymentId etc details can be seen as part of this response. parameters: - name: customerId in: path required: true schema: type: string description: Path parameter customerId. - name: paymentMethodId in: path required: true schema: type: string description: Path parameter paymentMethodId. - name: partnerToken in: header required: true schema: 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: - 80ae9a4a-5efd-412e-89b9-532f2ab2f817 description: Unique Merchant Identifier for API Calls example: 80ae9a4a-5efd-412e-89b9-532f2ab2f817 - name: requestId in: header required: false schema: 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: - 56ae9a4a-5efd-412e-89b9-532f2ab2f275 description: 'Unique request identifier in GUID format included in the header, used to trace and correlate API calls across systems. > **Note:** We strongly recommend including the `requestId` header in every API request. This unique GUID helps trace and correlate API calls across systems, ensuring better observability and troubleshooting.' example: 56ae9a4a-5efd-412e-89b9-532f2ab2f275 responses: '200': description: Successful response content: application/json: schema: description: Response parameters for the API type: object properties: accNickName: description: Convenient name for stored payment method type: string examples: - Visa-Debit vaultCreated: description: The date and time when the vault record was first created. type: string examples: - '2021-11-26T00:00:00' vaultUpdated: description: The date and time when the vault record was last updated. type: string examples: - '2021-11-26T00:00:00' vaultExpires: description: The date on which the vault record is scheduled to expire. type: string examples: - '2021-11-26T00:00:00' isActive: description: Indicates whether the vault record is currently active. type: boolean examples: - true paymentMethodId: 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 accountResponseData: description: Object to hold account verification responses such as AVS (Address Verification Service) and CVV check results. These fields indicate the outcome of address and card security code validations, typically returned by the payment processor. type: object properties: avs: description: Address verification response type: string maxLength: 1 examples: - Y avsDate: description: Date that verify address ran on specific payment method type: string examples: - '2021-11-26T00:00:00' cardType: description: Specifies the type of card being used for the transaction (e.g., credit, debit, prepaid). type: string examples: - Visa maskedPan: description: Masked Primary Account Number (PAN) used for display and logging. Only the last few digits are visible for security purposes. type: string examples: - 4111********4321 expiry: description: Card expiration date (in MMYY format). type: string examples: - 11/25 token: description: Used for processing transactions without exposing the actual PAN. type: string maxLength: 16 examples: - '8791230000000000' accountNumber: description: The full Primary Account Number (PAN) associated with the card. type: string examples: - '987654321' routingNumber: description: Bank routing number used to identify the financial institution for ACH or domestic fund transfers. type: string examples: - '123456789' accountType: type: string enum: - Checking - Savings examples: - Checking sequenceNumber: description: Sequence number of the fleet card transaction type: string examples: - '12345' odometer: description: Odometer reading of the fleet card transaction type: string examples: - '4354235' driversLicenseNumber: description: Driving Licence number of the fleet card transaction type: string examples: - '2346' required: - accNickName example: paymentMethodId: ee0b82f2-5682-ec0c-f75a-12270d6a1f78 accNickName: Visa-Debit isActive: true cardType: Discover maskedPan: 601178******7242 expiry: 12/30 token: '8791230000000000' accountResponseData: avs: Y avsDate: '2001-01-01T00:00:00' accountNumber: '12345678' routingNumber: '123123123' accountType: Checking createdDate: '2024-03-15T01:32:45.653' updatedDate: '2024-04-15T01:32:45.653' sequenceNumber: '65486' odometer: '2456546' driversLicenseNumber: '98766' '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' delete: operationId: deleteCustomerSPaymentMethod summary: Delete Customer's Payment Method tags: - customers description: "Delete an existing payment method for a customer.All upcoming payments linked to this payment method will\ \ also be deleted.\n> **Note:** \n> - Once a payment method is deleted, all the upcoming payments linked to that payment\ \ method will be deleted. \n> - To modify a payment method use \"https://api.deluxe.com/dpp/v1/paymentmethods/{paymentMethodId}\"" parameters: - name: customerId in: path required: true schema: type: string description: Path parameter customerId. - name: paymentMethodId in: path required: true schema: type: string description: Path parameter paymentMethodId. - name: forceDelete in: query required: false schema: type: boolean default: false examples: - true description: Indicates whether the payment method should be deleted forcefully. When set to true, the payment method will be deleted even if there are associated upcoming or recurring payments. example: true responses: '200': description: Successful response content: application/json: schema: description: Response details type: object properties: paymentMethodId: description: Unique identifier for the payment done. 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: - 63748a11-312d-456e-b55d-2008f8deea90 responseMessage: description: Description of response code type: - string - 'null' examples: - Payment Method deleted successfully 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: - requestId - responseMessage example: paymentMethodId: E23EAC1B-FB07-4A2B-916A-FAA6E57EF440 responseMessage: Payment Method deleted successfully 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.' /batches: post: operationId: closeBatch summary: Close Batch tags: - batches description: The Close Batch API endpoint finalizes and closes a transaction batch, sending notifications based on the provided email addresses. Input includes emails for success notifications, failure notifications, and general notifications to ensure relevant stakeholders are informed of the batch status. requestBody: required: true content: application/json: schema: description: Request details type: object properties: successEmail: description: Email address for batch close successful notification type: string examples: - ops@example.com failEmail: type: array items: type: array items: type: string description: Email address for batch close failure notification examples: - - ops@example.com - dev@example.com notifyEmail: type: array items: type: array items: type: string description: Email address for all batch close notification examples: - - ops@example.com - dev@example.com example: successEmail: ops@example.com failEmail: - ops@example.com - dev@example.com notifyEmail: - ops@example.com - dev@example.com responses: '200': description: Successful response content: application/json: schema: description: Response details type: object properties: authResponse: description: Authorizer response code and BatchID type: string examples: - '1556780000000000' responseCode: description: Authorizer response code type: number examples: - 0 responseMessage: description: Description of response code type: - string - 'null' examples: - null 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: - paymentId - requestId - responseCode - responseMessage example: authResponse: NOBATCH responseCode: 0 responseMessage: null paymentId: 9e8e1c75-5454-46fc-9970-74e9aa3726a0 requestId: 9ccd0e1a-9a0e-4b56-bac5-0b118c0279bc '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /paymentlinks: post: operationId: createPaymentLink summary: Create Payment Link tags: - paymentlinks description: The Create Payment Link API endpoint generates a customized URL that can be shared with customers to accept online payments. It allows the specification of payment details, customer information, order data, itemized purchases, and additional custom data. The generated payment link can be configured with various options like payment method acceptance, billing, and contact requirements. The link can be sent to the customer via email and includes a personalized confirmation message. Upon successful creation, the API returns a unique payment link ID, the URL for the payment link, and a payment ID for tracking. requestBody: required: true content: application/json: schema: description: Request details to create payment link 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 firstName: description: The first name of the customer for whom the payment link is generated. type: string examples: - Jane lastName: description: The last name of the customer for whom the payment link is generated. type: string examples: - Doe orderData: description: Object to hold order details type: object properties: orderId: description: Unique identifier of Order type: string examples: - abc12345 required: - orderId 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 sale items (level 3) data. - Ensure a non-zero tax amount 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: Custom fields and values specified for the payment link, allowing for additional transaction details. 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 paymentLinkExpiry: description: Specifies how long the payment link remains valid before expiring. type: string pattern: ^([0-9]{1,3} ([Dd][Aa][Yy][Ss]?|[Mm][Oo][Nn][Tt][Hh][Ss]?|[Ww][Ee][Ee][Kk][Ss]?|[Yy][Ee][Aa][Rr][Ss]?)|[Nn][Oo] [Ee][Xx][Pp][Ii][Rr][Aa][Tt][Ii][Oo][Nn])$ examples: - 2 Months acceptPaymentMethod: type: array items: type: array items: type: string enum: - Card - ACH description: Indicates whether card payments,ACH (Automated Clearing House) are accepted via this payment link. enum: - Card - ACH minItems: 1 examples: - - Card acceptBillingAddress: description: Whether the payment form will display a field for the billing address. type: boolean examples: - false requiredBillingAddress: description: Whether providing a billing address is mandatory for completing the payment. type: boolean examples: - false acceptPhone: description: If set to true, the payment form will include a field for the customer's phone number. type: boolean examples: - false requiredPhone: description: Determines if entering a phone number is compulsory for the customer. type: boolean examples: - false deliveryMethod: description: The method by which the payment link will be delivered to the customer (e.g., EMAIL or SMS). oneOf: - description: The email address to which the payment link will be sent, if delivery via email is selected. type: object properties: email: type: string examples: - customer@test.com - description: The mobile number to which the payment link will be sent, if delivery via sms is selected. type: object properties: sms: type: string examples: - +1 1234567890 confirmationMessage: description: An optional message to display on the payment link page upon completion of the form by the customer. type: string examples: - Thank you for your payment! required: - acceptPaymentMethod - amount - deliveryMethod - firstName - lastName - paymentLinkExpiry example: amount: amount: 19.99 currency: USD firstName: Jane lastName: Doe orderData: orderId: abc12345 level2: shippingZip: '94002' taxAmount: 2 purchaseCard: false customerRefNumber: '7898654' localTaxFlag: 2 level3: - description: Apple skuCode: SKU1234 quantity: 4 commodityCode: '39028' unitCost: 11 freightAmount: 1.5 dutyAmount: 0.3 price: 40 unitOfMeasure: Dozen itemDiscountAmount: 4 itemDiscountRate: 10 taxAmount: 2 customData: - name: Invoice Number value: inv1234 paymentLinkExpiry: 9 DAYS acceptPaymentMethod: - Card acceptBillingAddress: false requiredBillingAddress: false acceptPhone: false requiredPhone: false deliveryMethod: email: customer@test.com confirmationMessage: Thank you for your payment! responses: '200': description: Successful response content: application/json: schema: description: Response details type: object properties: paymentLinkId: description: Unique identifier for the newly created payment link. type: string examples: - 75C99BAE-E843-412F-89A5-AC6177A101D7 paymentLinkURL: description: URL to the payment link that can be sent to the customer for payment. type: string examples: - https://payments.deluxe.com/gateway/paymentlink/75C99BAE-E843-412F-89A5-AC6177A101D7 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 required: - paymentLinkId - paymentLinkURL example: paymentLinkId: E23EAC1B-FB07-4A2B-916A-FAA6E57EF440 paymentLinkURL: https://payments2.deluxe.com/gateway/paymentlink/E23EAC1B-FB07-4A2B-916A-FAA6E57EF440 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /paymentlinks/{paymentLinkId}: delete: operationId: deletePaymentLink summary: Delete Payment Link tags: - paymentlinks description: The Delete Payment Link operation allows you to remove an existing payment link that is no longer needed. This action permanently deletes the specified payment link. parameters: - name: paymentLinkId in: path required: true schema: type: string description: Path parameter paymentLinkId. responses: '200': description: Successful response content: application/json: schema: description: Response details type: object properties: paymentLinkId: description: Unique identifier for the newly created payment link. type: string examples: - 75C99BAE-E843-412F-89A5-AC6177A101D7 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 responseMessage: description: Description of response code type: - string - 'null' examples: - Successfully Deleted PaymentLink required: - paymentLinkId - requestId - responseMessage example: paymentLinkId: E23EAC1B-FB07-4A2B-916A-FAA6E57EF440 responseMessage: PaymentLink deleted successfully 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.' /events/subscribe: post: operationId: subscribeEvent summary: Subscribe Event tags: - events description: This endpoint allows you to subscribe to specific events by providing a URL where event notifications will be sent. Upon successful subscription, you will receive notifications based on the specified event types at the provided webhook URL. requestBody: required: true content: application/json: schema: type: object properties: userName: description: Username for the developer account. Note- Submitting Username will result in a subscription for all accounts available under that user’s portfolio. Submitting Access Token will result in a subscription for that merchant account only. type: string examples: - johndoe events: description: Array to hold event details type: array items: type: object properties: eventUri: description: The URL where the webhook will send data type: string pattern: ^https:\/\/([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(\/[a-zA-Z0-9\-_]+)*(\/)? examples: - https://www.yourwebhookurl.com eventType: description: 'Type of webhook event to subscribe 1. **MERCHANT BOARDED** – Triggered when a new merchant account is successfully created (boarded) into the system 2. **MERCHANT UPDATED** – Sent when an existing merchant’s information (e.g., address, contact, banking details) has been modified. 3. **CC BATCH** – Sent when a credit card batch is processed, summarizing a group of card transactions settled together. 4. **ACH BATCH** – Fires when an ACH (Automated Clearing House) batch is processed, indicating grouped electronic payments or transfers. 5. **ACH REJECT** – Triggered when an ACH transaction fails or is rejected (e.g., due to insufficient funds, closed account, or invalid details). 6. **TRANSACTION** – A real-time webhook for individual transaction activity (e.g., authorization, capture, refund, void). 7. **VAULT** – Fires when there are updates to the customer vault (e.g., customer profile or stored payment methods are added, updated, or deleted). 8. **CC CHARGEBACK** – Triggered when a cardholder disputes a transaction, and a chargeback request is initiated by the issuing bank.' type: string enum: - MERCHANT BOARDED - MERCHANT UPDATED - CC BATCH - ACH BATCH - ACH REJECT - TRANSACTION - VAULT - CC CHARGEBACK examples: - MERCHANT BOARDED required: - eventType - eventUri required: - userName example: userName: test@first-american.net events: - eventUri: https://apitran2.deluxe.com/listener/api/logging/PluginError eventType: TRANSACTION - eventUri: https://apitran2.deluxe.com/listener/api/logging/PluginError eventType: ACH REJECT responses: '200': description: Successful response content: application/json: schema: type: object properties: events: description: Array to hold event details type: array items: type: object properties: eventSubscriptionId: description: Identifier for the webhook subscription type: string examples: - '101' eventType: description: 'Type of webhook event to subscribe 1. **MERCHANT BOARDED** – Triggered when a new merchant account is successfully created (boarded) into the system 2. **MERCHANT UPDATED** – Sent when an existing merchant’s information (e.g., address, contact, banking details) has been modified. 3. **CC BATCH** – Sent when a credit card batch is processed, summarizing a group of card transactions settled together. 4. **ACH BATCH** – Fires when an ACH (Automated Clearing House) batch is processed, indicating grouped electronic payments or transfers. 5. **ACH REJECT** – Triggered when an ACH transaction fails or is rejected (e.g., due to insufficient funds, closed account, or invalid details). 6. **TRANSACTION** – A real-time webhook for individual transaction activity (e.g., authorization, capture, refund, void). 7. **VAULT** – Fires when there are updates to the customer vault (e.g., customer profile or stored payment methods are added, updated, or deleted). 8. **CC CHARGEBACK** – Triggered when a cardholder disputes a transaction, and a chargeback request is initiated by the issuing bank.' type: string enum: - MERCHANT BOARDED - MERCHANT UPDATED - CC BATCH - ACH BATCH - ACH REJECT - TRANSACTION - VAULT - CC CHARGEBACK examples: - MERCHANT BOARDED success: description: Status of the operation type: boolean examples: - true message: description: Descriptive message about the response type: array items: {} examples: - - Subscribed successfully required: - eventSubscriptionId - eventType - message - success example: events: - eventSubscriptionId: '1319' eventType: TRANSACTION success: true message: - Subscribed successfully. - eventSubscriptionId: '1320' eventType: ACH REJECT success: true message: - Subscribed successfully. '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /events/unsubscribe: post: operationId: unsubscribeEvent summary: Unsubscribe Event tags: - events description: This endpoint allows you to unsubscribe from specific events by providing the associated subscription details, including the email address and eventSubscriptionId. Upon successful unsubscription, you will no longer receive notifications for the specified events. requestBody: required: true content: application/json: schema: type: object properties: events: description: Array to hold event details type: array items: type: object properties: email: description: Email address to send the webhook notification type: string pattern: ^([a-zA-Z0-9.!#$\%&'*+-=?^_`{|}~]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,})$ examples: - sample@email.com eventSubscriptionId: description: Identifier for the webhook subscription type: number examples: - 101 required: - email - eventSubscriptionId example: events: - email: anusha.test@deluxe.com eventSubscriptionId: 1319 responses: '200': description: Successful response content: application/json: schema: type: object properties: events: description: Array to hold event details type: array items: type: object properties: eventSubscriptionId: description: Identifier for the webhook subscription type: string examples: - '101' success: description: Status of the operation type: boolean examples: - true message: description: Descriptive message about the response type: array items: {} examples: - - subscribed succesfully required: - eventSubscriptionId - message - success example: events: - eventSubscriptionId: '1319' success: true message: - Unsubscribed successfully. '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /events/resend: post: operationId: resendEvent summary: Resend Event tags: - events description: The Resend Event API endpoint allows you to resend a previously triggered event, enabling the system to reprocess the event's associated actions or notifications. This is useful for scenarios where the original event processing may have failed or needs to be re-triggered for verification purposes. requestBody: required: true content: application/json: schema: type: object properties: eventId: description: Identifier for the webhook subscription type: number examples: - 1787191 required: - eventId example: eventId: 1320 responses: '200': description: Successful response content: application/json: schema: type: object properties: eventId: description: Identifier for the webhook subscription type: string examples: - '1787191' eventType: description: Type of webhook event type: string enum: - MERCHANT BOARDED - MERCHANT UPDATED - CC BATCH - ACH BATCH - ACH REJECT - TRANSACTION examples: - MERCHANT BOARDED success: description: Status of the operation type: boolean examples: - true message: description: Descriptive message about the response type: array items: {} examples: - - Resend successfully. partnerToken: description: Unique Merchant Identifier for API Calls 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: - 80ae9a4a-5efd-412e-89b9-532f2ab2f817 required: - eventId - eventType - message - partnerToken - success example: eventId: '2952690' eventType: MERCHANT BOARDED success: true message: - Resend successfully. partnerToken: B3D50B55-65CE-4B7B-8FE5-AB1B4F5CEDA7 '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /events/report: post: operationId: retrieveEventsReports summary: Retrieve Events Reports tags: - events description: This call is related to reports for different kinds of webhooks such as Merchant Boarded, Merchant Updated, CC Batch, ACH Batch, ACH Reject, Vault, CC chargeback. The result has all kinds of webhooks requests and responses along with their report statuses. parameters: - name: pageNumber in: query required: false schema: type: number examples: - 1 description: Specifies the page of results to retrieve. This is useful for navigating large datasets by retrieving data in manageable chunks. example: 1 - name: pageSize in: query required: false schema: type: number examples: - 1 description: Defines the number of records to be returned in a single response. This helps control response size and optimize performance. example: 1 requestBody: required: true content: application/json: schema: description: Object to hold search parameters like date range and event type. type: object properties: eventType: description: This indicates the type of event report for which you can see the requests and responses triggered in a specified date range type: string examples: - TRANSACTION reportStartDate: description: The start date from which user wants to see the event report. type: string pattern: ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4}$ examples: - 01/31/2025 reportEndDate: description: The end date from which user wants to see the event report. type: string pattern: ^(0[1-9]|1[0-2])/(0[1-9]|[12][0-9]|3[01])/[0-9]{4}$ examples: - 01/31/2025 required: - eventType - reportEndDate - reportStartDate example: eventType: TRANSACTION reportStartDate: 08/25/2024 reportEndDate: 08/24/2025 responses: '200': description: Successful response content: application/json: schema: description: Object to hold the event report that contains event type, event id, event uri and its respective requests and responses. type: object example: response: recordCount: 1 report: - webhookType: Transaction webhookId: 3586311 webhookUri: https://webhook.site/bb9bb726-ad5b-4214-9125-abf826d7931f webhookRequest: EventType: Transaction TransactionType: AUTHORIZE PaymentType: CREDITCARD AccessToken: F0D79985-E3AC-48D4-AF72-F999518B1ADA DbaName: 6/15 ZENTRO TEST FOR ROBERT OPT BLUE Currency: USD MID: '6280490007617210' MerNo: '6280490007617210' TerminalId: '001' TransactionId: B4A3D923-8A3E-423D-B698-5F340698CED3 DateTime: '2026-04-30 07:34:59' TransactionAmount: '16.00' InvoiceNumber: '269894454946778227' CardType: VISA CardNumber: 411111****1111 CardExpiration: '**33' AchAccountNumber: '' AchRoutingNumber: '' AchAccountType: '' Discount: '0.00' ProcessingFee: '0.00' Tip: '0.00' Tax: '2.33' Surcharge: '0.00' BatchNumber: '20260430731' Status: APPROVED AuthCode: 24414A AuthResponse: '' AvsResponse: Y CvvResponse: M CustomerId: '' RecurringId: '' RecurringType: '' RecurringAmount: '0.00' RecurringStartDate: '' RecurringEndDate: '' RecurringDayDetail: '' RecurringMonthDetail: '' VaultId: '' VaultKey: '' Customer: Name: SyedMuleTest AuthorizewithCard Address: 123 Main St City: San Francisco State: CA PostalCode: '94111' Country: USA EmailAddress: jane@email.com Phone: 650-555-1234 CompanyName: '' Shipping: Name: Jane Doe Address: 123 Main St City: San Francisco State: CA PostalCode: '94111' Country: USA EmailAddress: '' Phone: 650-555-1234 CompanyName: '' Level2Data: CustomerRefNo: '7898654' Level2TaxAmount: '' LocalTaxFlag: '0' PurchaseCard: 'false' ShippingZip: '94002' TaxAmount: '2.33' SaleItems: - Name: Banana Sku: SKU1234 Price: '0.0' Quantity: '2' Total: '2.0' TaxAmount: '0.0' CommodityCode: '' UnitOfMeasure: Dozen FreightAmount: '0.0' DutyAmount: '0.0' ItemDiscountAmount: '0.99' ItemDiscountRate: '0.1' CustomFields: - Name: Invoice Number Value: inv123423 - Name: Invoice Number Value: inv1234 SubmissionMethod: DPP API webhookResponse: 429 webhookStatus: Failed webhooksentDateTime: '2026-04-30T07:35:11.497' '401': description: 'Unauthorized: invalid token, expired token, or connection error when connecting to the authorization server.' '403': description: 'Forbidden: invalid client application credentials.' /events/performTest: post: operationId: performTestEvent summary: Perform Test Event tags: - events description: This API endpoint allows you to test the webhook endpoint. This endpoint posts a sample/test data as payload based on the webhook type to the URL provided in the request. requestBody: required: true content: application/json: schema: type: object properties: eventType: description: Type of webhook event to subscribe type: string maxLength: 50 examples: - Transaction testEndPoint: description: Test end point to receive on the listening/target URL type: string pattern: ^https:\/\/([a-zA-Z0-9-]+\.)+[a-zA-Z]{2,}(\/[a-zA-Z0-9\-_]+)*(\/)? maxLength: 500 examples: - https://webhook.site/acc3f0bb-27d9-4a19-98ec-33af9c56741b required: - eventType - testEndPoint example: eventType: Transaction testEndPoint: https://webhook.site/acc3f0bb-27d9-4a19-98ec-33af9c56741b responses: '200': description: Successful response content: application/json: schema: type: object properties: response: description: response of webhook event to subscribe type: string examples: - This URL has no default content configured. View in Webhook.site. statusCode: description: statusCode to receive on the listening/target URL type: number examples: - 200 required: - response - statusCode example: response: This URL has no default content configured. View in Webhook.site. statusCode: 200 '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.