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
- 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>
- Merchant starts uploading bulk payment file.
- 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.
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.
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 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.
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,,,,,
#,#,#,#,#,#,#,#,#,#,#,#