Initiating Payments via Batch File

See instructions here for submitting via SFTP

Processing

• Batch files are processed immediately upon receipt.

• TodayPay will attempt to process each payment contained in a submitted batch file.

• If an individual payment fails (e.g., due to an invalid phone number), the remaining valid payments will still be processed.

• For SFTP Submission

  • All Submission Files will receive an Acknowledgment File in response

  • If no file-level errors are present, a Response File will also be returned

  • If file-level errors are present and file can't be processed, no Response File will be returned and no payments will be initiated

Submission File

• File format: .csv

• Naming convention: see method-specific docs (varies based on SFTP, API, etc)

606B

Submission File Sample.csv

Field Name	Required?	Constraints / Notes
first_name	yes	str
last_name	yes	str
email	see method	str
phone_number	see method	str(E.164 format) e.g. [phone] Only +1US country code supported
address_line_1	see method
address_line_2	see method
address_state	see method
address_city	see method
address_zip	see method
method	yes	str[DIGITAL | CHECK] DIGITAL - Standard payment to TodayPay digital wallet. Required: phone_number or email. CHECK - Paper check issued directly to address. Required: full address (except line 2) Partial or complete address data may still be included on DIGITAL payments for fraud detection and paper check failsafe purposes
amount	yes	float(2 decimal precision) e.g. 10.00 = $10 Note: line item may fail if this field exceeds risk limits
idempotency_key	yes	str This is a globally unique ID generated by integrator. This prevents accidental double-initiation of payments and can serve as an internal integrator reference. Re-trying failed payments should use the same idempotency_key Recommend UUID or similar globally unique identifier.
notes	no	str(<= 256 chars, [A-Za-z0-9])

Acknowledgment File (SFTP only)

Each SFTP Submission File will result in a manifest file that details file-level processing status and file-level processing errors if applicable.

• Guaranteed return for every Submission File uploaded via SFTP

• File format: .csv

• Naming convention: see SFTP docs

193B

Acknowledgment File Sample.csv

Field Name	Required?	Constraints / Notes
Field name		Notes
file_name	yes	str Mirrors client input file name
upload_id	yes	str e.g. 2DP3768065998 (TodayPay id)
status	yes	str[ACCEPTED, REJECTED] ACCEPTED - file will be processed and Response file will be returned. REJECTED - file will not be processed. This is usually due to file-level error such as incorrect headers.
response_file_name	no	str e.g. processed_abc.csv
number_of_disbursements	no	int Null if status = REJECTED
error_message	no	str Not machine readable, for debugging only

Response File (SFTP only)

Receipt of Response File entry with corresponding SUCCESS status is only way to confirm a payment has been successfully initiated

Successfully-processed SFTP Submission Files will also result in a Response file that details payment-level status and details (e.g. confirmation of each disbursement)

• Only returned if Submission File processing can be completed

• File format: .csv

• Naming convention: see SFTP docs

752B

Response File Sample.csv

Field Name	Required?	Constraints / Notes
payment_id	no	str TodayPay id Null if status=FAILED
email	see method	str
phone_number	see method	str(E.164 format)
address_line_1	see method
address_line_2	see method
address_city	see method
address_state	see method
address_zip	see method
method	yes	str[DIGITAL | CHECK] DIGITAL - Standard payment to TodayPay digital wallet. Required: phone_number or email. CHECK - Paper check issued directly to address. Required: full address (except line 2).
amount	yes	float(2 decimal precision) e.g. 10.00 = $10
status	yes	str[DIGITAL | CHECK] DIGITAL - Standard payment to TodayPay digital wallet. Required: phone_number or email. CHECK - Paper check issued directly to address. Required: full address (except line 2) Partial or complete address data may still be included on DIGITAL payments for fraud detection and paper check failsafe purposes
idempotency_key	yes	str This is a globally unique ID generated by integrator. This prevents accidental double-initiation of payments and can serve as an internal integrator reference. Re-trying failed payments should use the same idempotency_key Recommend UUID or similar globally unique identifier.
error_message	no
notes	no	str