Bulk payment (PayByFile API)

With bulk payments, you can accept multiple payments at once.

About bulk payments

A bulk payment is realized through a file containing multiple payment requests, such as:

  • Payment authorization
  • Charge
  • Payment cancellation

The customer uploads the bulk payment file to an SFTP server.

After the file is processed, the system generates a report with successful and failed transaction requests.

Accept a bulk payment

To accept a bulk payment, follow the steps below.

Step 1: Request SFTP username and SSH key

To upload a bulk payment file, the customer needs:

  • Their unique SFTP username
  • Their unique SSH key

To obtain a new SFTP username and SSH key, contact the Unzer support team.

Never expose SSH keys.

Each SFTP user can access, upload and modify files only in their own dedicated folder.

Step 2: Log in to the SFTP server

The customer uses their SFTP username and their SSH key to log in to the SFTP server via the following domain: paybyfile.unzer.cloud.

sftp -i <path_to_ssh_key_file> <sftp_username>@paybyfile.unzer.cloud
sftp>

The customer uploads the bulk payment file and can exit sftp or wait for the report to be generated.

Step 3: Upload the bulk payment file

The customer uploads the file to the SFTP server and waits for it to be processed.

The bulk payment file must meet all of the following requirements:

  • The file must be in the CSV extension.
  • The file size must be less than 10MB.
  • Data must be comma-delimited.
  • The file name must contain this string: report.
  • The file must include # as a file trailer.
  • "#" must be repated to fit to columns.
publicKey,typeId,orderId,operation,amount,currency,paymentReference,customerId,invoiceId,paymentId,chargeId,authorizeId
s-pub-xxxxxxxxxx,s-crd-evuhknrt2fvh,order-65gfgf-220,authorize,10,EUR,random-paymentReference-675765ggf-1,,,,,
s-pub-xxxxxxxxxx,s-crd-evuhknrt2fvh,order-65gfgf-1100,charges,10,EUR,random-paymentReference-5465hghjg-1,,,,,
#,#,#,#,#,#,#,#,#,#,#,#
Parameter Required Description Example
publicKey Yes The public key of the customer. s-pub-xxxxxxxxxx
typeId Yes The payment type resource ID that you registered earlier. s-crd-evuhknrt2fvh
orderId No A unique order ID that identifies the payment on your side. order-65gfgf-220
operation Yes The transaction type of the payment. The values are authorize, charges, and cancels authorize
amount Yes The transaction amount. The value entered must be a numeric and positive value 10.0
currency Yes The transaction currency, in the ISO 4217 alpha-3 format. EUR
paymentReference No The payment reference. random-paymentReference-675765ggf-1
customerId No The ID of the customers resource. s-cst-d9bf18c354c4
invoiceId No The Invoice ID.
paymentId Optional The Payment ID.
This field is required when making a charge for authorization or cancel payment.
s-pay-24343
chargeId Optional The charge resource ID.
This field is required when making a cancel charge.
s-chg-1
authorizeId Optional The authorization resource ID.
This field is required when making a cancel authorization.
s-aut-1