Deluxe Corporation Customers API

openapi: 3.2.0
info:
  title: DPP Gateway Experience Customers 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: customers
paths:
  /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
                              p

# --- truncated at 32 KB (78 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/deluxe/refs/heads/main/openapi/deluxe-customers-api-openapi.yml