Unzer Docs

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