Bulk payments (PayByFile API)

Introduction

PayByFile allows Merchants to make bulk payments by uploading a file onto a SFTP server. The file contains multi rows of payment requests in a proper format.

The merchant will be provided with their own credentials to upload bulk payments file onto a SFTP server. After the processing time, which might take a while, a report will be generated.

The report provides information of successful or failed transaction requests, and the reason of such.

Processing flow

  1. Merchant uses given SSH key to login onto SFTP server via domain paybyfile.unzer.cloud

Request

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

Response

sftp>
  1. Merchant starts uploading bulk payment file.
  2. Merchant can exit sftp or wait for report to be generated.

Security

In order to be able to upload bulk payment file, merchant needs a credentials to login our SFTP server.

Login credential
Please contact our support team or sale team to register a new credential. Merchant will be provided a SSH key to connect to SFTP server.
SSH key
Merchant must not expose SSH key to others. One SSH key can only be used by one merchant.

Each credential will have its own folder. Each credential can only access, upload & modify files in its folder.

Upload bulk payment file

Bulk payment file is a file of payment requests, such as authorization, charge or cancel. Merchant uploads this file onto SFTP server and wait for it to be processed.

Bulk payment file extension
Bulk payment file must meet all of below requirements:
- Must be in CSV extension.
- Must be delimited by comma.
- File name must not contain "report" string in any cases.
Must include "#" as file trailer. "#" must be repeated fit to columns.
Validation
Limit file size under 10MB

File format

Field name Mandatory Description Note
publicKey Y merchant’s public key Example: s-pub-xxxxxxxxxx
typeId Y Payment type resource ID that was registered before. Must not be once time usage payment type resource.
Example: s-crd-evuhknrt2fvh
orderId N Order ID Must be unique in merchant’s system.
Example: order-65gfgf-220
operation Y
Values: authorize / charges / cancels
Transaction type
amount Y Transaction amount Must be numeric & positive value.
Example: 10.0
currency Y Transaction currency Must be supported by public key.
paymentReference N Payment reference Example: random-paymentReference-675765ggf-1
customerId N Customer ID Must be customer resource that has been created in MGW system.
Example: s-cst-d9bf18c354c4
invoiceId N Invoice ID
paymentId Y* (Optional mandatory) Payment ID Must be payment resource ID that has been created in MGW system. This field is required when doing charge for authorization or cancel payment. Example: s-pay-24343
chargeId Y* (Optional mandatory) Charge ID Must be charge resource ID that has been created in MGW system.
This field is required when doing cancel charge.
Example: s-chg-1
authorizeId Y* (Optional mandatory) Authorize ID Must be authorization resource ID that has been created in MGW system.
This field is required when doing cancel authorize.
Example: s-aut-1

Example

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,,,,,
#,#,#,#,#,#,#,#,#,#,#,#