Jump to

• Request
• Response
• Examples

Process Batch Payments

post

/bcws/webresources/v1.0/batchpayments/process

Processes batch payment files and submits the payments upon successful validation.

Request

Query Parameters

• overrideThreshold: boolean
  What to do when the number of suspended payments in a batch file has exceeded a pre-configured threshold:

  • true specifies to override the threshold checkpoint and proceed with submitting the payments.
  • false specifies to stop processing the batch file and roll back any successful allocations in the payment batch.
• retry: boolean
  Whether to automatically retry processing the batch payments if a failure occurs (true) or not (false).

Supported Media Types

• application/xml
• application/json

Request Body - application/xml ()

Root Schema : schema

Type: object

Show Source

• currency(required): string
  The currency of all payments in the batch payment file.
• extension: object extension
  The extended attributes.
• fileCreationDate(required): string (date-time)
  The date and time the batch payment file was created.
• fileName(required): string
  The file name for the batch payment file.
• fileSize: number (double)
  The size of the batch payment file.
• institutionName(required): string
  The name of the institution that created the batch payment file.
• lockBoxId(required): string
  The lockbox's ID.
• lockBoxName: string
  The lockbox's name.
• noOfPayments: integer (int64)
  The number of payments in the batch payment file.
• status: integer (int32)
  The status of the batch payment file. Can be one of the following:

  • 1: New
  • 2: Format error
  • 3: Unknown template
  • 4: Processing error
  • 5: Threshold exceeded
  • 6: Processing
• templateName(required): string
  The template name.

{
    "required":[
        "currency",
        "fileCreationDate",
        "fileName",
        "institutionName",
        "lockBoxId",
        "templateName"
    ],
    "type":"object",
    "properties":{
        "extension":{
            "type":"object",
            "description":"The extended attributes."
        },
        "lockBoxName":{
            "type":"string",
            "description":"The lockbox's name."
        },
        "lockBoxId":{
            "type":"string",
            "description":"The lockbox's ID."
        },
        "institutionName":{
            "type":"string",
            "description":"The name of the institution that created the batch payment file."
        },
        "templateName":{
            "type":"string",
            "description":"The template name."
        },
        "currency":{
            "type":"string",
            "description":"The currency of all payments in the batch payment file."
        },
        "fileName":{
            "type":"string",
            "description":"The file name for the batch payment file."
        },
        "fileCreationDate":{
            "type":"string",
            "description":"The date and time the batch payment file was created.",
            "format":"date-time"
        },
        "fileSize":{
            "type":"number",
            "description":"The size of the batch payment file.",
            "format":"double"
        },
        "noOfPayments":{
            "type":"integer",
            "description":"The number of payments in the batch payment file.",
            "format":"int64"
        },
        "status":{
            "type":"integer",
            "description":"The status of the batch payment file. Can be one of the following: <ul><li><b>1</b>: New</li><li><b>2</b>: Format error</li><li><b>3</b>: Unknown template</li><li><b>4</b>: Processing error</li><li><b>5</b>: Threshold exceeded</li><li><b>6</b>: Processing</li></ul>",
            "format":"int32"
        }
    },
    "xml":{
        "name":"paymentBatchFileHeader"
    }
}

Nested Schema : extension

Type: object

The extended attributes.

Request Body - application/json ()

Root Schema : schema

Type: object

Show Source

• currency(required): string
  The currency of all payments in the batch payment file.
• extension: object extension
  The extended attributes.
• fileCreationDate(required): string (date-time)
  The date and time the batch payment file was created.
• fileName(required): string
  The file name for the batch payment file.
• fileSize: number (double)
  The size of the batch payment file.
• institutionName(required): string
  The name of the institution that created the batch payment file.
• lockBoxId(required): string
  The lockbox's ID.
• lockBoxName: string
  The lockbox's name.
• noOfPayments: integer (int64)
  The number of payments in the batch payment file.
• status: integer (int32)
  The status of the batch payment file. Can be one of the following:

  • 1: New
  • 2: Format error
  • 3: Unknown template
  • 4: Processing error
  • 5: Threshold exceeded
  • 6: Processing
• templateName(required): string
  The template name.

{
    "required":[
        "currency",
        "fileCreationDate",
        "fileName",
        "institutionName",
        "lockBoxId",
        "templateName"
    ],
    "type":"object",
    "properties":{
        "extension":{
            "type":"object",
            "description":"The extended attributes."
        },
        "lockBoxName":{
            "type":"string",
            "description":"The lockbox's name."
        },
        "lockBoxId":{
            "type":"string",
            "description":"The lockbox's ID."
        },
        "institutionName":{
            "type":"string",
            "description":"The name of the institution that created the batch payment file."
        },
        "templateName":{
            "type":"string",
            "description":"The template name."
        },
        "currency":{
            "type":"string",
            "description":"The currency of all payments in the batch payment file."
        },
        "fileName":{
            "type":"string",
            "description":"The file name for the batch payment file."
        },
        "fileCreationDate":{
            "type":"string",
            "description":"The date and time the batch payment file was created.",
            "format":"date-time"
        },
        "fileSize":{
            "type":"number",
            "description":"The size of the batch payment file.",
            "format":"double"
        },
        "noOfPayments":{
            "type":"integer",
            "description":"The number of payments in the batch payment file.",
            "format":"int64"
        },
        "status":{
            "type":"integer",
            "description":"The status of the batch payment file. Can be one of the following: <ul><li><b>1</b>: New</li><li><b>2</b>: Format error</li><li><b>3</b>: Unknown template</li><li><b>4</b>: Processing error</li><li><b>5</b>: Threshold exceeded</li><li><b>6</b>: Processing</li></ul>",
            "format":"int32"
        }
    },
    "xml":{
        "name":"paymentBatchFileHeader"
    }
}

Nested Schema : extension

Type: object

The extended attributes.

Back to Top

Response

Supported Media Types

• application/xml
• application/json

200 Response

The batch payments were processed successfully.

Body ()

Root Schema : paymentBatchStatistics

Type: object

Show Source

• batchCurrency: integer (int32)
  The currency of all payments in the batch payment file.
• batchRef: object ResourceRef
• durationInQueue: integer (int32)
  The amount of time that the batch payment file was in the BRM queue.
• durationProcessed: integer (int32)
  The amount of time that the batch payment file was being processed by BRM.
• extension: object extension
  The extended attributes.
• fileCreationDate(required): string (date-time)
  The date and time the batch payment file was created.
• fileName(required): string
  The name of the batch payment file.
• fileSize: number (double)
  The size of the batch payment file.
• institutionName(required): string
  The name of the institution, such as a commercial bank, that processed the batch payment.
• lockBoxId(required): string
  The lockbox's ID.
• lockBoxName(required): string
  The lockbox's name.
• processCompletionDate(required): string (date-time)
  The date BRM completed processing the batch payment file.
• processedBy(required): string
  The company that processed the lockbox payments.
• processEndDate(required): string (date-time)
  The date BRM stopped processing the batch payment file.
• processStartDate(required): string (date-time)
  The date BRM started processing the batch payment file.
• totalAmount(required): number
  The total amount of all payments in the batch payment file.
• totalPayments: integer (int32)
  The total number of payments in the batch payment file.
• totalPaymentsProcessed: integer (int32)
  The total number of payments that have been processed.
• totalPaymentsSuspended: integer (int32)
  The total number of payments that were suspended.

{
    "required":[
        "fileCreationDate",
        "fileName",
        "institutionName",
        "lockBoxId",
        "lockBoxName",
        "processCompletionDate",
        "processEndDate",
        "processStartDate",
        "processedBy",
        "totalAmount"
    ],
    "type":"object",
    "properties":{
        "extension":{
            "type":"object",
            "description":"The extended attributes."
        },
        "batchRef":{
            "$ref":"#/components/schemas/ResourceRef"
        },
        "lockBoxName":{
            "type":"string",
            "description":"The lockbox's name."
        },
        "processedBy":{
            "type":"string",
            "description":"The company that processed the lockbox payments."
        },
        "lockBoxId":{
            "type":"string",
            "description":"The lockbox's ID."
        },
        "institutionName":{
            "type":"string",
            "description":"The name of the institution, such as a commercial bank, that processed the batch payment."
        },
        "totalPaymentsProcessed":{
            "type":"integer",
            "description":"The total number of payments that have been processed.",
            "format":"int32"
        },
        "totalPayments":{
            "type":"integer",
            "description":"The total number of payments in the batch payment file.",
            "format":"int32"
        },
        "totalPaymentsSuspended":{
            "type":"integer",
            "description":"The total number of payments that were suspended.",
            "format":"int32"
        },
        "processStartDate":{
            "type":"string",
            "description":"The date BRM started processing the batch payment file.",
            "format":"date-time"
        },
        "processEndDate":{
            "type":"string",
            "description":"The date BRM stopped processing the batch payment file.",
            "format":"date-time"
        },
        "processCompletionDate":{
            "type":"string",
            "description":"The date BRM completed processing the batch payment file.",
            "format":"date-time"
        },
        "durationInQueue":{
            "type":"integer",
            "description":"The amount of time that the batch payment file was in the BRM queue.",
            "format":"int32"
        },
        "durationProcessed":{
            "type":"integer",
            "description":"The amount of time that the batch payment file was being processed by BRM.",
            "format":"int32"
        },
        "batchCurrency":{
            "type":"integer",
            "description":"The currency of all payments in the batch payment file.",
            "format":"int32"
        },
        "fileName":{
            "type":"string",
            "description":"The name of the batch payment file."
        },
        "fileCreationDate":{
            "type":"string",
            "description":"The date and time the batch payment file was created.",
            "format":"date-time"
        },
        "fileSize":{
            "type":"number",
            "description":"The size of the batch payment file.",
            "format":"double"
        },
        "totalAmount":{
            "type":"number",
            "description":"The total amount of all payments in the batch payment file."
        }
    },
    "xml":{
        "name":"paymentBatchStatistics"
    }
}

Nested Schema : ResourceRef

Type: object

Show Source

• id(required): string
  The ID.
• uri: string
  The Uniform Resource Identifier (URI) associated with the resource.

{
    "required":[
        "id"
    ],
    "type":"object",
    "properties":{
        "id":{
            "type":"string",
            "description":"The ID."
        },
        "uri":{
            "type":"string",
            "description":"The Uniform Resource Identifier (URI) associated with the resource."
        }
    }
}

Nested Schema : extension

Type: object

The extended attributes.

201 Response

The batch payments were processed successfully.

500 Response

An internal server error occurred.

Back to Top

Examples

This example shows how to process a batch payment file by submitting a POST request on the REST resource using cURL. For more information about cURL, see "Use cURL".

cURL Command

curl -X POST 'http://hostname:port/bcws/webresources/v1.0/batchpayments/process' -H 'content-type: application/json' -d @batchProcess.json

where:

• hostname is the URL for the Billing Care REST server.
• port is the port for the Billing Care REST server.
• version is the version of the API you're using, such as v1.0.
• batchProcess.json is the JSON file that specifies the batch payment file to process.

Example of Response Body

This example shows the contents of the batchprocess.json file sent as the request body.

{
   "extension": null,
   "lockBoxName": null,
   "lockBoxId": null,
   "institutionName": "Cash Payment Batch",
   "templateName": null,
   "currency": "840",
   "fileName": "samplePmt2.pmt",
   "fileCreationDate": 1612361936090,
   "fileSize": 0.578125,
   "noOfPayments": 1,
   "status": 6
}

Example of Response Body

This example shows the contents of the response body in JSON format.

{
   "extension": null,
   "batchRef": null,
   "lockBoxName": null,
   "processedBy": null,
   "lockBoxId": null,
   "institutionName": "Cash Payment Batch",
   "totalPaymentsProcessed": 1,
   "totalPayments": 0,
   "totalPaymentsSuspended": 0,
   "processStartDate": 1612362027802,
   "processEndDate": 1612362032727,
   "processCompletionDate": 1612362032727,
   "durationInQueue": 2,
   "durationProcessed": 4925,
   "batchCurrency": 840,
   "fileName": "samplePmt2.pmt",
   "fileCreationDate": 1612361936090,
   "fileSize": 0.578125,
   "totalAmount": 1.50
}

Back to Top