Updating Contacts via SFTP

You can update your Contacts by sending a Contact file to Payreq via SFTP. This method is generally used where you supply Contact data as part of an automated or recurring process from a billing, rating, payroll, or other source system, whether you do this yourself or through a Print Service Provider.

A complete technical overview is available in the Payreq Interface Specification.

How the SFTP process works

1. You prepare a Contact file.
2. The file is uploaded to Payreq's SFTP server.
3. Payreq processes the file.
4. Contact records are added, updated, or replaced according to the file and its header instructions.
5. Payreq generates an acknowledgement file once processing is complete.
6. You review the acknowledgement file, and review any Subscriptions flagged Deregister?

File requirements

Contact files must be supplied in CSV format. Each file must contain:

• One header record
• One or more Contact records
• One trailer record

You can choose the file name, provided that:

• Each file name is unique
• The file extension is .csv
• The file name uses only standard US ASCII characters
• Accented characters and control characters are not used in the file name

Header record: choosing the correct file type identifier

The first row in the file must be the header record. It identifies the file and tells Payreq how to process it. The file type identifier controls how the Contact file is processed.

Use ADD_CONTACTS when the file should:

• Add new Contacts
• Update matching existing Contacts
• Leave other existing Contacts unchanged

Use REPLACE_CONTACTS only when the file contains the full Contact list that should remain in Payreq Delivery. Use a replacement file carefully, because Contacts not included in the file may no longer remain available in the same way after processing.

Before sending a replacement file, confirm that:

• The file contains all required Contacts
• Existing Contact IDs have been retained where appropriate
• The possible effect on active Subscriptions has been considered
• The file has been reviewed by the appropriate person in your organisation

Contact fields

The Contact file includes several configurable Contact fields. These matter because they are used to match Subscription requests to the correct Contact record. The mandatory Contact fields are:

Confirm the required values and field usage during onboarding. You can review them in the Payreq Delivery console Settings. For more detail, see Understanding Contact Field Settings.

Uploading the file

1. Prepare the Contact file in the agreed CSV format.
2. Connect to Payreq's SFTP server using the credentials provided to your organisation.
3. Place the file in the /incoming directory.
4. Allow Payreq to process the file.
5. Review the acknowledgement file once processing is complete.

Do not upload the same file more than once unless Payreq Support asks you to.

Acknowledgement files

After Payreq processes the Contact file, an acknowledgement file is placed in the Payreq SFTP outbound folder. It gives the overall result of the Contact load, and includes:

• The file name Payreq received
• The overall processing status
• A message confirming the result or explaining the failure
• The original header you provided in the Contact file
• The trailer count

The overall status indicates whether the file processed successfully:

• OK: the file was processed successfully
• ERR: the file failed processing and needs investigation

If your organisation does not need acknowledgement files, you can discuss this with Payreq during onboarding, or by contacting Payreq Support.