Service Overview
In addition to its HTTP endpoints for uploading invoice and supplier files, PaymentWorks also offers SFTP access to upload or download those same files. We prefer our customers use our SFTP endpoints versus our existing FTPS (FTP over SSL) since SFTP can support a more secure authentication via SSH public keys. This document provides information on getting started with our SFTP service and how you can use it to securely access your files or upload new data.
Preparing Your Public Key File
Our SFTP server currently accepts public key authentication (with or without passphrases) and in order to facilitate this stronger authentication mechanism, PaymentWorks will need to store your public key on our servers, as is standard with public/private key communication.
It's important that this command be run against your *public* key (ending in .pub), not the private key file. The ability to give away your public key file to anyone or even publish it on the internet is one of the key tenets of what makes RSA cryptography so useful for this application. Once you've successfully generated your public, you can then email this content to our support staff and we'll make sure it's installed properly for your account.
We can support multiple public key files for your user, if desired. For more information about creating SSH keypairs, see https://www.digitalocean.com/community/tutorials/how-to-set-up-ssh-keys--2
Authentication
Our SFTP endpoints are locked down by IP address, so even before you attempt to connect via SFTP, PaymentWorks support will need to know the IP address of where your SFTP session will originate. A website you can use to determine this information is: http://whatismyipaddress.com/ Once you've determined this information, send your origin IP address and your RFC4716-formatted public key file to PaymentWorks support. If you don't perform this step first, your attempts to connect to our SFTP endpoint will simply hang, never even get to the authentication stage and eventually time out.
Once we have your origin IP address and public key file installed, you can test your authentication credentials by SFTPing to the following host:
hostname: transfers.paymentworks.com
username: <your paymentworks email address>
port: 22
If you attempt to connect to that host/port combination, you'll first see a challenge to view and/or accept the host's server key, since it will be your first time connecting. Once you accept the server's key, it's stored permanently in your known_hosts file on your server:
[Macbook-Pro:]$ sftp melgart+p11\@paymentworks.com@transfers.paymentworks.com
The authenticity of host 'transfers.paymentworks.com (54.80.44.237)' can't be established.
RSA key fingerprint is SHA256:R5ZBhj/EEQiIlxUajGJGKBF4MXAe9PnmQc1Sy50KdzQ.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added 'transfers.paymentworks.com' (RSA) to the list of known hosts.
<paymentworks SFTP banner removed for brevity>
Connected to transfers.paymentworks.com.
sftp>
Note: for unix-like command lines, you'll need to escape ('\@') the '@' symbol in your email/username, since the '@' is a special shell symbol.
Troubleshooting
As mentioned, if our SFTP endpoints don't have your SFTP origin address IP whitelisted, your attempts to connect will simply hang and eventually time out. The website http://whatismyipaddress.com/ can be useful if you're testing authentication from your local laptop, but if you're setting this up for an enterprise deployment, you should probably work with your IT staff to determine the IP addresses of your proxy servers, if you use them. In fact, your IT staff will surely have the IP address and public key files needed to make this connection. If you *are* the IT staff, you might want to generate a new public/private key pair just for SFTP communication with PaymentWorks. Our SFTP endpoints don't support public key authentication with DSA-type keys, only RSA. We recommend key sizes greater than or equal to 2048 bits.
Another common problem users run into is not having their public keys formatted in RFC4716 format. Again, this can be done on the command line using the ssh-keygen command with -e (with no additional argument).
Accessing Files and Directories, Uploading New Data
Once connected, you'll have a limited set of commands that you can perform, very much like an FTP session. You can list the files and directories in the top-level directory once you've logged in using the 'ls -l' command:
sftp> ls -l
drwxr-xr-x 2 melgart+p11@gmail.com 504 4096 Mar 22 13:04 blast-attachments
drwxr-xr-x 2 melgart+p11@gmail.com 504 4096 Mar 22 13:04 invoice_discounts
drwxr-xr-x 2 melgart+p11@gmail.com 504 4096 Mar 22 13:04 invoices
drwxr-xr-x 2 melgart+p11@gmail.com 504 4096 Mar 22 13:04 new_vendor_requests
drwxr-xr-x 2 melgart+p11@gmail.com 504 4096 Mar 22 13:04 suppliers
drwxr-xr-x 2 melgart+p11@gmail.com 504 4096 Mar 22 13:04 updates
sftp>
You can change the working directory to the 'invoices' directory:
sftp> cd invoices
sftp> ls -l
drwxr-xr-x 2 melgart+p11@gmail.com 504 4096 Mar 22 13:04 processed
sftp>
Once in the invoices directory, you can upload a new invoices files with the PUT command:
sftp> put invoices.csv
Uploading invoices.csv to /invoices/invoices.csv
invoices.csv 100% 300 5.1KB/s 00:00
sftp>
After processing, your uploaded file will be moved from the current directory where it was uploaded into the 'processed' directory and your processed file will be prefixed with a timestamp to mark its processing date. You'll also receive an email within several minutes with processing status and statistics.
To learn more about setting up SFTP view the comprehensive PaymentWorks Integration Guide- Part 6: SFTP Setup