File transfer guide - Batch

What is Batch?

Batch is an app that provides a file based interface to our products. Customers can make a file available to Azupay via their own self-hosted sftp server. A file contains multiple records that will be used to create PaymentRequests or PaymentInitiations.

Easy to integrate

Leverage your existing sftp infrastructure and file generation applications to integrate with our Batch App.

Secure

Well known, reliable, and secure technology using SFTP (Secure File Transfer Protocol). Using private/public key based authentication, you can be sure that the transfer process is secure.

PayID based payments are inherently secure. Files do not require the inclusion of any customer identification data. No file level or encryption at rest required.

Super fast

We have built a streaming, highly parallelised system for consuming files and invoking the same API’s that we offer you.

Enabling Batch

  1. Login to Client Portal and navigate to Apps
  2. Click the Manage button to open the Azupay Batch configuration
  3. Click or switch the Enable Batch to On and fill in the SFTP server details.
  4. Copy and paste the Public SSH Key to your SFTP server's authorized_keys file.

📘

Batch app polling behaviour

Batch app will poll your sftp server every minute, process a single file and then stop. So, if you place 10 files on your sftp server, it will take at least 10 minutes to process them all.

File Name Specification

Example

  • Example file names:
    • payment-initiation-20211027115901-1-request.csv
    • payment-request-2021102711590100001-request.csv

Specification

AttributeValue
Filename - Inbound File<file-type>-<unique-file-identifier>-request.csv
Filename - Processed<file-type>-<unique-file-identifier>-response.csv
File EncodingUTF-8
New Line CharacterUNIX new line (i.e. \n )
File SizeMaximum 256 MB
Field DelimiterComma character (i.e. , )
Field Value Enclosing CharacterDouble quote (“) or ASCII decimal 34

File Types

We have the following file types

Transaction Typefile-typesuffixdelimitersample request file
Payment Initiationpayment-initiation-request.csvComma (,)payment-initiation-202202120001-request.csv
Payment Initiationpayment-initiation-response.csvComma (,)payment-initiation-202202120001-response.csv
Payment Initiation Refundpayment-initiation-refund-request.csvComma (,)payment-initiation-refund-202202120001-request.csv
Payment Initiation Refundpayment-initiation-refund-response.csvComma (,)payment-initiation-refund-202202120001-response.csv
Payment Requestpayment-request-request.csvCaret (^)payment-request-202202120001-request.csv

Request Files

Payment Request File

Specification

Additional details of the field specifications can be found in API documentation for Create a Payment Request..

Field Type and Length Description
clientId string [ 5 .. 50 ] characters Id of the client creating the request for payment. This is supplied by azupay and only changes between environments. For example, you might be allocated CLIENT1TEST for the UAT environment and CLIENT1 for production.
clientTransactionId string [ 5 .. 100 ] characters Unique Id for the transaction created by the merchant system
payID string [ 5 .. 50 ] characters Unique email PayID for this transaction. Value supplied here is the PayID used by your customer to make payment. If not supplied, Azupay will generate one automatically. The PayID's domain must match one of the configured domains for the client.
paymentExpiryDatetime string <date-time> Timestamp when the payment request expires and is no longer able to accept payments. The associated PayID is also de-registered at this time. Cannot be set if multiPayment is set to true.
paymentAmount number Amount in AUD requested to pay for the transaction. Not mandatory if multiPayment is true. If multiPayment is true then it can be set to accept adhoc payments up to this amount.
paymentDescription string [ 5 .. 140 ] characters Description of this transaction. First 140 characters becomes the PayID name that appears in the customer's OLB when they lookup the PayID. Must not contain any of the customer's personal information.
multiPayment boolean When set to true, allows adhoc payments to a PayID. If true paymentExpiryDatetime can not be set. Defaults to false.

Sample

clientId^clientTransactionId^payID^paymentExpiryDatetime^paymentAmount^paymentDescription^multiPayment
CLIENT1^INV3442345^[email protected]^2021-09-31T10:00:00Z^123.45^Water bill April to July 2021^True
CLIENT1^INV3442346^[email protected]^2021-09-31T10:00:00Z^166.45^Water bill April to July 2021^True
CLIENT1^INV3442347^[email protected]^^178.95^Water bill April to July 2021^False

Payment Initiation File

Specification

The file content is separated into 3 sections that is identified by a Record Type:

  1. Header
  2. Body
  3. Footer

Each rows belong to a section based on a Record Type as the prefix of the row followed by comma (,) and the values

Record TypeSectionExample
1Header1,DDPAYTO,20230706
2Body2,PaymentInitiation.clientId,PaymentInitiation.paymentAmount,PaymentInitiation.clientTransactionId
2,AZUPAYMENT,100.00,5a62d22d-f264-40ee-92cc-9ba5c09187cf
3Footer3,15,1950.75
  • Header contains 3 columns

    • first column is the RecordType (1)
    • second column is the source code (string DDPAYTO)
    • third column is the timestamp when the response file is generated in the YYYYMMDD (Year, Month, and Day) format
  • Body contains a dynamic numbers of columns based on the request

    • The first row is the heading of the body (see example)
    • First column is the RecordType (2)
    • Following columns are the content of the body

    The body specification is as followed:

    Field Type Description
    PaymentInitiation.paymentAgreementId string ID of the payment agreement to initiate payment
    PaymentInitiation.clientTransactionId string Unique Id for the transaction created by the merchant system
    PaymentInitiation.clientId string Id of the client initiating the transaction
    PaymentInitiation.paymentAmount string Amount in AUD to be requested from the Payee
    PaymentInitiation.reference string Unique identification to unambiguously identify the transaction
    PaymentInitiation.description string Optional remittance information used to unambiguously refer to the payment transaction

    Fields are separated by comma.

    The first line of the content must be the header (e.g. PaymentInitiation.paymentAgreementId).

    Additional details of the field specifications can be found in API documentation for Initiate a Payment.

  • Footer contains 3 columns

    • First column is the RecordType (3)
    • Second column is the record count of content of the body (or number of transactions in the batch)
    • Third column is the sum of the PaymentInitiation.paymentAmount for the successful transactions.

Example:

1,DDPAYTO,20230706                                     
2,PaymentInitiation.clientId,PaymentInitiation.paymentAmount,PaymentInitation.clientTransactionId,...
2,AZUPAYMENT,100.00,5a62d22d-f264-40ee-92cc-9ba5c09187cf,...
2,AZUPAYMENT,200.00,1b46be44-df27-4c7a-a98f-4c9fc5f7b07b,...
3,2,300.00                                          

Payment Initiation Refund File

📘

What refunds can Azupay Batch app process?

Azupay Batch app can only process refunds for Payment Initiations that were created by Azupay Batch app.

Specification

The structure of the file is the same as the Payment Initiation File Payment Initiation File.

The body specification is as followed:

Field Type Description
PaymentInitiationRefund.id string The ID for the Payment Initiation
PaymentInitiationRefund.refundAmount number The refund amount

Fields are separated by comma.

The first line of the content must be the header (e.g. PaymentInitiationRefund.id).

Additional details of the field specifications can be found in API documentation for Refund for Payment Initiation.

Sample

1,DDPAYTO,20230706    
2,PaymentInitiationRefund.id,PaymentInitiationRefund.refundAmount
2,paymentInitiationId1, 100.00
2,paymentInitiationId2, 300.00
3,1,300.00     

Response Files

Once a request file is processed, a response file will be generated.

Filename

The response filename format is defined in the File Type section above

Example filename:

  • payment-initiation-20211027115901-1-response.csv

Content

See the specification section above for the expected response file content.

Example:

1,DDPAYTO,20230706                                     
2,PaymentInitiation.clientId,PaymentInitiation.paymentAmount,PaymentInitation.clientTransactionId,...
2,AZUPAYMENT,100.00,5a62d22d-f264-40ee-92cc-9ba5c09187cf,...
2,AZUPAYMENT,200.00,1b46be44-df27-4c7a-a98f-4c9fc5f7b07b,...
3,2,300.00                                          

📘

Viewing Transactions

You can also use Azupay Dashboard's Transactions page to view the submitted transactions.

Error Handling

Row Error

Row Error defines errors that were encountered when creating Payment Initiation for any of the rows in the request file.

  • The response file has the records of the errors that led to a particular payment initiation to fail.
    These reasons can be internal to Azupay or external, i.e. issues with customers' account/bank.
  • These failure codes will be added to attribute failureCode. See 'Failure Codes and Failure Reasons' section within the guide for each API for listing of failure codes.
  • The reasons for the failure will be added under failureReason
  • Note that the payments initiations will be retried 6 times before deemed as failure.

Example of response file with error:

1,DDPAYTO,20230706    
2,PaymentInitiationRefund.id,PaymentInitiationRefund.refundAmount,...,failureCode,failureReason
2,paymentInitiationId1,100.00,...,AZP5.4,"[""additionalDetails"" object must contain ([""ipAddress""]) when ([""channelType""]) is BROWSER or MOBILE]"
2,paymentInitiationId2,300.00
3,1,300.00     

File Error

File Error defines errors that were encountered when parsing the request file.

  • The response file will be generated with the error messages in the content.
  • No payment initiations will be created.

Possible errors and examples:

Description Example
Header is not in the correct format. See specification.

ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Invalid header
          
Body is not in the correct format. See specification.

ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Data rows must start with 2,
          
Body is empty.

ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Body is empty
          
Body is an invalid CSV.

ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Row length does not match headers
          
Footer is not in the correct format. See specification.

ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Invalid footer
          
Transaction count and amount in footer not matching the body. See specification.

ERROR: Transaction or Amount mismatch - payment-initiation-20230726000000-request.csv