Payments
      Back to home
      1. Choice Digital Knowledge Base
      2. Payments

      Payment File Field Mapping Guide

      When uploading a payment file to create payments, the following fields are available for mapping. Here's what you need to know:

      • Required Fields: Fields that must be included in your file are clearly marked in the table below.
      • Optional Fields: You don’t need to provide all the listed fields—only the ones relevant to your program.
      • Custom Data: Any fields in your file that aren’t mapped to the standard fields will still be captured. These will be stored as JSON data within the payment record for future reference.

      Custom Check Attachments 

      If your program uses custom content on check attachments, you may need to include specific columns and data in your payment files. This will be reviewed and finalized during the onboarding process to ensure all necessary details are captured.

       

      Field Name Description Example Required? Character Limits & Special Characters Validation Rules
      Program ID Indicates the Choice Digital program the payment should be assigned to. ID is provided by CDCO. CLIENT_Program Y N/A Must match the program ID provided by CDCO. Field is case sensitive.
      Amount The amount of the payment 50 Y Numeric value only, no dollar signs allowed N/A
      First Name Recipient's first name Alex Review rules Must be 25 characters or less and contain digits 0-9, alpha (a-z, A-Z), space, period, comma and hyphen. First Name and Last Name or Company Name is required.
      Last Name Recipient's last name Smith Review rules Must be 25 characters or less and contain digits 0-9, alpha (a-z, A-Z), space, period, comma and hyphen. First Name and Last Name or Company Name is required.
      Company Name Recipient's company name ABC Company Review rules Must be 25 characters or less and contain digits 0-9, alpha (a-z, A-Z), space, period, comma and hyphen. First Name and Last Name or Company Name is required.
      Email Address Recipient's email address alexsmith@cdco.io Review rules Must be formatted as an email address. Required for Direct program digital prepaid cards, digital gift cards, and Choice program payments
      Address Line 1 Recipient's address line 1 123 Anything St Review rules Must be 50 characters or less and contain digits 0-9, alpha (a-z, A-Z), space, period, comma and hyphen. Required for:
      - Direct program physical prepaid cards, physical gift cards, and checks
      - All SurePay Direct and SurePay Choice payments
      - All payments with a physical backup payment method
      Address Line 2 Recipient's address line 2 Suite 100 N Must be 50 characters or less and contain digits 0-9, alpha (a-z, A-Z), space, period, comma and hyphen. N/A
      Address Line 3 Recipient's address line 3 ATTN: Joan Smith N Must be 50 characters or less and contain digits 0-9, alpha (a-z, A-Z), space, period, comma and hyphen. N/A
      City Recipient's address City Anywhere Review rules Must be 50 characters or less and contain digits 0-9, alpha (a-z, A-Z), space, period, comma and hyphen. Required for:
      - Direct program physical prepaid cards, physical gift cards, and checks
      - All SurePay Direct and SurePay Choice payments
      - All payments with a physical backup payment method
      State, Province, or Region Recipient's address State CO Review rules 2-character state (US) Must match an existing State or Province code and formatted in all caps.

      Required for:
      - Direct program physical prepaid cards, physical gift cards, and checks
      - All SurePay Direct and SurePay Choice payments
      - All payments with a physical backup payment method
      ZIP or Postal Code Recipient's ZIP or postal code 80302 Review rules Must be 10 characters or less and contain digits 0-9, alpha (a-z, A-Z), and space. Do not use hyphen. Must be a valid state code based on the state/province provided.

      Required for:
      - Direct program physical prepaid cards, physical gift cards, and checks
      - All SurePay Direct and SurePay Choice payments
      - All payments with a physical backup payment method
      Additional 4-Digit ZIP Code Additional 4-Digit ZIP Code for US payments, or country code for international payments 1234 N Must be 10 characters or less and contain digits 0-9, alpha (a-z, A-Z), and space. Do not use hyphen. N/A
      Phone Number Recipient's phone number 1112223333 N Must be 10 characters and contain digits 0-9. Do not use hyphen or any special characters. N/A
      Digital Wallet ID PayPal email or phone number; or Venmo email, phone number, or username username-123 Review rules N/A Required for PayPal and Venmo payments
      Client Unique ID A unique ID assigned to a specific payment. Can be used to search for payments within the CDCO Client App. ABC12345 N N/A Used to prevent duplicates, so must be unique across all payments for a single client
      Client Recipient ID An ID for the recipient that can be applied to multiple payments. Can be used to send the same recipient multiple payments. Also used to roll up line items into a single payment 123ABCDEF N N/A If the same Client Recipient ID is provided on multiple lines in a single file, the recipient details must match across all rows.
      Card Message A message that can be printed on a Direct program physical prepaid card. Message can be the same or different for each person receiving a card. Not available for SurePay Choice, SurePay Direct, or Choice program payments. Thank you N Must be 21 characters or less and contain alphanumeric characters, spaces, periods and dashes only. N/A
      Payment Method Code Defines the payment method a customer will receive if different from the default setting on the program. mmu_prepaid N N/A Must match an existing payment method name assigned to the program.
      Email Template Name Defines the email a customer will receive if different from the default setting on the program. MMU Digital Card Confirmation Email N N/A Must match an existing email template name assigned to the program.
      Client Additional Data Flexible JSON field to store additional data that clients may need for reporting purposes or for customization of content. {"job_id":"12345"} N N/A Must be valid JSON
      Check Number Used only if CDCO is writing checks against the client's bank account; the check number that should be printed on the recipient's check 60789 N N/A N/A
      Line Item Description Used for consolidated payments Site: 1234 Main St Joan Smith N N/A N/A

       

      Updated December '24