Data File
The payout data file is the source of truth for new payouts. The payout process starts when a data file is received and successfully processed by Latitude.
Latitude supports two file formats for the data file:
Excel file format
Naming convention
<YOUR_COMPANY_NAME>_ReadyRemit_TransferRequest_Data_YYYYMMDDhhmmss.xlsx
YOUR_COMPANY_NAME must be confirmed by Brightwell prior to the first file landing in the SFTP folder. All files sent to Brightwell must follow the naming convention and start with YOUR_COMPANY_NAME. For company names with multiple words, underscores must be used in place of spaces. Each file you submit must be unique and any duplicate file names will fail to ingest.
Examples:
| Company name | Date | Data File name |
|---|---|---|
| Acme | 01 Jan 2023 6:00:00 AM EST | Acme_ReadyRemit_TransferRequest_Data_20230101110000.xlsx |
| Acme Tech | 01 Jan 2023 6:30:00 PM EST | Acme_Tech_ReadyRemit_TransferRequest_Data_20230101233000.xlsx |
NoteThe timestamp on the file is ISO-8601 compliant and always converted to UTC (GMT-0) time. All uploaded filenames must be unique. Uploading a duplicate filename will result in an error.
Excel File Specification
Acme_ReadyRemit_TransferRequest_Data_20230101110000.xlsx
| Row Identifier | Reference Number | Sender ID | Recipient First Name | Recipient Last Name | Recipient Second Last Name | Recipient email address | Recipient Phone Number | Recipient Mailing Address Line 1 | Recipient Mailing Address Line 2 | Recipient Mailing Address City | Recipient Mailing Address State | Recipient Mailing Address Postal Code | Recipient Mailing Address Country | Transfer Request amount | Transfer Request Amount Currency | Send or receive | Supplemental Information 1 | Supplemental Information 2 | Verification Code |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| D | Latitude01 | d82df35w-4723-3s09-9se7-d23hc3hes5a2 | Jane | Doe | [email protected] | 5551234567 | USA | 25.00 | USD | SEND_AMOUNT | resnum12843 | confirmnum123487 | |||||||
| D | Latitude02 | d82df35w-4723-3s09-9se7-d23hc3hes5a2 | John | Doe | [email protected] | 5551234569 | MEX | 5472.23 | MXN | RECEIVE_AMOUNT | refund21837432 | confirmnum373263 | 3098sfDSi8e9a8 | ||||||
| D | Latitude03 | d82df35w-4723-3s09-9se7-d23hc3hes5a2 | Jim | Smith | [email protected] | 5555837343 | USA | 100.70 | USD | SEND_AMOUNT | Jim Smith | 37832464583 |
Header Row
Every Excel data file must include the header row with the field names as shown in the example above. Do not modify any values in the header row.
Data Row
A data row should be added to the Data File for every unique payout. The data elements of the data row are defined in the table below:
Column | Description | Data type | Required | Example |
|---|---|---|---|---|
Row identifier | Single character identifier used to determine the type of row: D = data | Text (1) | ✔️ | D |
Reference Number | Unique ID used by you to reference the payout in within the Latitude product. This value is generated by you. This value is also the ID value used by the end user in the event they need customer support. Note: It is recommended to select a value that is already being used to reference this payment in your system however it must be unique for all transfer requests. | Text (1-50) | ✔️ | ABC123456 |
Sender ID | Unique ID provided by the Latitude Integrations team referencing a specific sender configuration and account as the source of funds. | Text(1-50) | ✔️ | d82df35w-4723-3s09-9se7-d23hc3hes5a2 |
Recipient First Name | Given name of the recipient | Text (1-50) | ✔️ | Josef |
Recipient Last Name | Surname of the recipient | Text (1-50) | ✔️ | Martinez |
Recipient Second Last Name | Maternal or second last name of the recipient | Text (1-50) | Jiminez | |
Recipient Email Address | Email address of the recipient (this will determine where notification emails are sent) | Text (1-50) | ✔️ | |
Recipient Phone Number | Phone number of the recipient (last 4 of this phone number used for verification by user by default) | Text (4-50) | ✔️ | 555812345678 |
Recipient Mailing Address Line 1 | Address line 1 of the recipient mailing address | Text (1-50) | PRIVADA UNIÓN 10 | |
Recipient Mailing Address Line 2 | Address line 2 of the recipient mailing address | Text (1-50) | COL. AGRÍCOLA PANTITLÁN | |
Recipient Mailing Address City | City of the recipient mailing address | Text (1-50) | CIUDAD DE MÉXICO | |
Recipient Mailing Address State | State/Province of the recipient mailing address | Text (1-50) | IZTACALCO | |
Recipient Mailing Address Postal Code | Zip/Postal code of the recipient mailing address | Text (1-10) | 30339 or | |
Recipient Mailing Address Country | Country of the recipient mailing address | ISO-3 | ✔️ | MEX |
Payout amount | Total amount of the payout in a decimal format (minimum amount = $1.00) | Decimal (1-9999999) | ✔️ | 150.99 |
Payout Amount Currency | Currency of the payout | ISO-3 | ✔️ | USD |
Send or Receive | Quote by send or receive amount: SEND_AMOUNT specifies the amount the user is able to collect before any fees or FX rates (foreign exchange). RECEIVE_AMOUNT is the amount the user will collect in a desired currency irregardless of fees or FX rates. User will not be able to receive funds in a different currency than specified when using RECEIVE_AMOUNT. Any fees or FX rates will be calculated in the background with the applicable amount in USD deducted from the funding account in order to meet the RECEIVE_AMOUNT specified. | Text (1-50) | ✔️ | SEND_AMOUNT |
Supplemental Information 1 | Additional field for notes for cross reference | Text (1-50) | This is an example | |
Supplemental Information 2 | Additional field for notes for cross reference | Text (1-50) | This is an example | |
Verification Code | Alternate verification method to the default last 4 digits of their phone number. This value should be a unique, private, and hard to guess string that only the end user recipient will know. Supplying a value in this field will disable the default verification method of using the last 4 of the phone number. | Text (4-50) | 3098sfDSi8e9a8 | |
Supplemental Information 3 | Additional field for notes for cross reference | Text (1-50) | This is an example | |
Supplemental Information 4 | Additional field for notes for cross reference | Text (1-50) | This is an example | |
User ID | Indicator that can associate multiple payouts to a single user through a unique ID. | Text (1-50) | XYZ789 | |
Recipient Type | Whether the payout is being sent to a person (B2C) or a business (B2B) entity. | "PERSON" or "BUSINESS" | PERSON |
Pipe delimited flat file
Naming convention
Your_Company_Name_ReadyRemit_TransferRequest_Data_YYYYMMDDhhmmss.txt
Examples:
| Company name | Date | Data File name |
|---|---|---|
| Acme | 01 Jan 2023 6:00:00 AM EST | Acme_ReadyRemit_TransferRequest_Data_20230101110000.txt |
| Acme Tech | 01 Jan 2023 6:30:00 PM EST | Acme_Tech_ReadyRemit_TransferRequest_Data_20230101233000.txt |
NoteThe timestamp on the file is ISO-8601 compliant and always converted to UTC (GMT-0) time.
Pipe Delimited Flat File Specification
H|58a2ab39-a7be-45db-acc7-2a268c118241|2022-02-15T10:00:00.000Z|2
D|ABC123456|c44778aa-9be7-48b4-9e29-416bb24c4a99|Josef|Martinez||[email protected]|525512545678|PRIVADA UNIÓN 10|COL. AGRÍCOLA PANTITLÁN|CIUDAD DE MÉXICO|IZTACALCO|8100|MEX|30010|USD|SEND_AMOUNT|238372ABD|DHS3827|
D|XYZ098765|c44778aa-9be7-48b4-9e29-416bb24c4a99|Jane|Smith||[email protected]|15551234567|100 Main St||Atlanta|GA|30339|USA|1050|USD|SEND_AMOUNT|2D8KDE73|8747DHKL|3729734DSH||The data file is a pipe-delimited file consisting of two types of rows: header and data.
Header Row
Every data file must contain one (1) header row. The data elements of the header row are defined in the table below:
Element | Description | Data type | Required | Example |
|---|---|---|---|---|
Row identifier | Single character identifier used to determine the type of row: H = header | Text (1) | ✔️ | H |
Customer ID | ID of the customer provided by the Latitude integrations team | Text (1-50) | ✔️ | 58a2ab39-a7be-45db-acc7-2a268c118241 |
Date | Date that the Data File was created in UTC time (GMT-0) | ISO-8601 | ✔️ | 2022-02-15T16:00:00.000Z |
Row count | Number of total data rows in the file | Integer | ✔️ | 2 |
Data Row
A data row should be added to the Data File for every unique Transfer Request. The data elements of the header row are defined in the table below:
Column | Description | Data type | Required | Example |
|---|---|---|---|---|
Row identifier | Single character identifier used to determine the type of row: D = data | Text (1) | ✔️ | D |
Reference Number | Unique ID used to reference the payout in future Status reports. This value is generated by you. Note: It is recommended to select a value that is already being used to reference this payment in your system. | Text (1-50) | ✔️ | ABC123456 |
Sender ID | Unique ID provided by the Latitude Integrations team referencing a specific sender configuration and account as the source of funds. | Text(1-50) | ✔️ | 58a2ab39-a7be-45db-acc7-2a268c118241 |
Recipient First Name | Given name of the recipient | Text (1-50) | ✔️ | Josef |
Recipient Last Name | Surname of the recipient | Text (1-50) | ✔️ | Martinez |
Recipient Second Last Name | Maternal or second last name of the recipient | Text (1-50) | Jiminez | |
Recipient Email Address | Email address of the recipient (this will determine where notification emails are sent) | Text (1-50) | ✔️ | |
Recipient Phone Number | Phone number of the recipient | Text (1-50) | 555812345678 | |
Recipient Mailing Address Line 1 | Address line 1 of the recipient mailing address | Text (1-50) | PRIVADA UNIÓN 10 | |
Recipient Mailing Address Line 2 | Address line 2 of the recipient mailing address | Text (1-50) | COL. AGRÍCOLA PANTITLÁN | |
Recipient Mailing Address City | City of the recipient mailing address | Text (1-50) | CIUDAD DE MÉXICO | |
Recipient Mailing Address State | State/Province of the recipient mailing address | Text (1-50) | IZTACALCO | |
Recipient Mailing Address Postal Code | Zip/Postal code of the recipient mailing address | Text (1-10) | 08100 | |
Recipient Mailing Address Country | Country of the recipient mailing address | ISO-3 | ✔️ | MEX |
Transfer Request amount | Total amount of the payout in a decimal normalized format | Decimal (1-9999999) | ✔️ | 150.99 |
Transfer Request Amount Currency | Currency of the payout | ISO-3 | ✔️ | USD |
Send or Receive | Quoting by send or receive amount | Text (1-50) | ✔️ | SEND_AMOUNT |
Supplemental Information 1 | Additional field for notes for cross reference | Text (1-50) | This is an example. | |
Supplemental Information 2 | Additional field for notes for cross reference | Text (1-50) | This is an example. | |
Verification Code | Alternate verification method to the default last 4 digits of their phone number. This value should be a unique, private, and hard to guess string that only the end user recipient will know. Supplying a value in this field will disable the default verification method of using the last 4 of the phone number. | Text (4-50) | 3098sfDSi8e9a8 | |
Supplemental Information 3 | Additional field for notes for cross reference | Text (1-50) | This is an example. | |
Supplemental Information 4 | Additional field for notes for cross reference | Text (1-50) | This is an example. |
Response File
Every payout data file that is sent to Latitude will be followed by a corresponding Payout Response File sent back to your system.
FAQ
Q: How often should I send data files?
A: Data files can be sent as frequently or infrequently as is appropriate for your use case. Files can be sent on-demand or as a part of a regularly scheduled background job.
Q: What if I want to send multiple transfers to the same recipient user?
A: Payouts are isolated to a single transfer. A unique payout should be submitted to Latitude for each individual transfer to be made. The recipient user will then need to complete each payout individually to collect all of their funds.
Q: What if my data contains the delimiter character(|)?
A: The pipe bar character is not supported in any data fields and will never be returned in the response file. If your data contains a pipe bar, please consider replacing it with a different character.
Q: What if I need to re-submit a file because I got errors on the response file?
A: If the file was a partial success, remove any successful payouts from the new file and update the file name so that it is not a duplicate. It is recommended to update the HHmmss timestamp portion of the naming convention to the current time to avoid a duplicate filename. Make any necessary corrections to any individual payouts in the file based on the errors you encountered. Re-upload the file to SFTP.
Updated about 21 hours ago