Azupay website
Guides
Help CentreService DeskStatus PageDashboard | ProductionDashboard | UATTest Bank

Payment initiation - Batch

Suggest Edits

Request File

Specification

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

  1. Header
  2. Body
  3. Footer

Each row belongs 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

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.

## Request File### SpecificationThe file content is separated into 3 sections that is identified by a Record Type:1. Header
2. Body
3. FooterEach row belongs to a section based on a Record Type as the prefix of the row followed by comma (,) and the values| Record Type | Section | Example |
| ----------- | ------- | ---------------------------------------------------------------------------------------------------- |
| 1 | Header | 1,DDPAYTO,20230706 |
| 2 | Body | 2,PaymentInitiation.clientId,PaymentInitiation.paymentAmount,PaymentInitiation.clientTransactionId |
| | | 2,AZUPAYMENT,100.00,5a62d22d-f264-40ee-92cc-9ba5c09187cf |
| 3 | Footer | 3,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.### Exampletext 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 ## Response FilesOnce a request file is processed, a response file will be generated.### FilenameThe response filename format is defined in the File Type section aboveExample filename:- payment-initiation-20211027115901-1-response.csv### ContentSee the specification section above for the expected response file content.Example:```text
      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 
> 
> You can also use Azupay Dashboard's **Transactions** page to view the submitted transactions.![](https://files.readme.io/fc5e76d-image.png)## 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:```text
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:<table>
    <tr>
        <th>Description</th>
        <th>Example</th>
    </tr>
    <tr>
        <td>Header is not in the correct format. See <a href="#specification-3">specification</a>.</td>
        <td>
          <pre><code>
ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Invalid header
          </code></pre>
        </td>
    </tr>
    <tr>
        <td>Body is not in the correct format. See <a href="#specification-3">specification</a>.</td>
        <td>
          <pre><code>
ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Data rows must start with 2,
          </code></pre>
        </td>
    </tr>
    <tr>
        <td>Body is empty.</td>
        <td>
          <pre><code>
ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Body is empty
          </code></pre>
        </td>
    </tr>
    <tr>
        <td>Body is an invalid CSV.</td>
        <td>
          <pre><code>
ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Row length does not match headers
          </code></pre>
        </td>
    </tr>
    <tr>
        <td>Footer is not in the correct format. See <a href="#specification-3">specification</a>.</td>
        <td>
          <pre><code>
ERROR: Un-parseable file - payment-initiation-20230726000000-request.csv
Invalid footer
          </code></pre>
        </td>
    </tr>
    <tr>
        <td>Transaction count and amount in footer not matching the body. See <a href="#specification-3">specification</a>.</td>
        <td>
          <pre><code>
ERROR: Transaction or Amount mismatch - payment-initiation-20230726000000-request.csv
          </code></pre>
        </td>
    </tr>
</table>

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

```text
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

Updated 6 months ago