1. Overview
The Bulk/Batch Payment resource is used by a PISP to initiate a Bulk/Batch Payment.
This resource description should be read in conjunction with a compatible Payment Initiation API Profile.
2. Endpoints
Endpoints for the resource - and available methods.
S. No. | Resource | HTTP Operation | Endpoint | Mandatory | Scope | Grant Type | Message Signing | Idempotency Key | Request Object | Response Object |
2.1 | file-payments | POST | POST /file-payments | Conditional | payments | Authorisation Code | Signed Request Signed Response | Yes | OBWriteFile | OBWriteFileResponse |
2.2 | file-payments | GET | GET /file-payments/{FilePaymentId} | Mandatory (if resource POST implemented) | payments | Client Credentials | Signed Response | No | NA | OBWriteFileResponse |
2.3 | file-payments | GET | GET /file-payments/{FilePaymentId}/report-file | Conditional | payments | Client Credentials | Signed Response | No | NA | File |
2.4 | payment-details | GET | GET /file-payments/{FilePaymentId}/payment-details | Optional | payments | Client Credentials | Signed Response | No | NA | OBWritePaymentDetailsResponse |
2.1 GET/file-payments/{FilePaymentId}
A PISP can retrieve the file-payment to check its status.
2.1.1 Status
The file-payments resource must have one of the following Status codes:
Status |
InitiationPending |
InitiationFailed |
InitiationCompleted |
2.2 GET /file-payments/{FilePaymentId}/report-file
The API endpoint allows the PISP to download a payment report file from an ASPSP (Bank).
This endpoint enables ASPSP (Bank) to return a report on the processing results of Payments in the file
The file is sent in the HTTP response body.
The file structure may match a payment execution report for the corresponding FileContextFormat in the file-payment-consent request.
HTTP headers (e.g. Content-Type) are used to describe the file.
2.3 GET /file-payments/{FilePaymentId}/payment-details
A PISP can retrieve the Details of the underlying payment transaction(s) via this endpoint. This resource allows ASPSPs (Banks)to return richer list of Payment Statuses, and if available payment scheme related statuses.
2.3.1 Status
The file-payments - payment-details must have one of the following PaymentStatusCode code-set enumerations:
Status |
Accepted |
AcceptedCancellationRequest |
AcceptedTechnicalValidation |
AcceptedCustomerProfile |
AcceptedFundsChecked |
AcceptedWithChange |
Pending |
Rejected |
AcceptedSettlementInProcess |
AcceptedSettlementCompleted |
AcceptedWithoutPosting |
AcceptedCreditSettlementCompleted |
Cancelled |
NoCancellationProcess |
PartiallyAcceptedCancellationRequest |
PartiallyAcceptedTechnicalCorrect |
PaymentCancelled |
PendingCancellationRequest |
Received |
RejectedCancellationRequest |
2.4 State Model
2.4.1 Payment Order
The state model for the file-payments resource describes the initiation status only. I.e., not the subsequent execution of the file-payments.
The definitions for the Status:
S. No. | Status | Payment Status Description |
1 | InitiationPending | The initiation of the payment order is pending. |
2 | InitiationFailed | The initiation of the payment order has failed. |
3 | InitiationCompleted | The initiation of the payment order is complete. |
3. Data Model
The data dictionary section gives the detail on the payload content for the File Payment API flows.
3.1 Reused Classes
3.1.1 OBFileInitiation
The OBFileInitiation class is defined in the file-payment-consents page.
3.2 File Payment - Request
The OBWriteFile object will be used for a call to:
POST /file-payments
3.2.1 UML Diagram
3.2.2 Notes
The file-payment request object contains the:
ConsentId.
The full Initiation object from the file-payment-consent request.
The Initiation section of the file-payment request must match the Initiation section of the corresponding file-payment-consent request
3.2.3 Data Dictionary
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
OBWriteFile |
| OBWriteFile |
| OBWriteFile |
|
|
Data | 1..1 | OBWriteFile/Data |
| OBWriteFile/Data |
|
|
ConsentId | 1..1 | OBWriteFile/Data/ConsentId | OB: Unique identification as assigned by the ASPSP (Bank) to uniquely identify the consent resource. | String |
|
|
Initiation | 1..1 | OBWriteFile/Data/Initiation | The Initiation payload is sent by the initiating party to the ASPSP (Bank). It is used to request movement of funds using a payment file. | OBFileInitiation |
|
|
3.3 File Payment - Response
The OBWriteFileResponse object will be used for a response to a call to:
POST /file-payments
GET /file-payments/{FilePaymentId}
3.3.1 UML Diagram
3.3.2 Notes
The file-payment response object contains the:
FilePaymentId.
ConsentId.
CreationDateTime the file-payment resource was created.
Status and StatusUpdateDateTime of the file-payment resource.
Charges array is used for the breakdown of applicable ASPSP (Bank) charges.
The Initiation object from the file-payment-consent.
An ASPSP (Bank) should conditionally provide Debtor/Name in the Payment Order Response, even when the Payer did not provide the Debtor Account via PISP
3.3.3 Data Dictionary
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
OBWriteFileResponse |
| OBWriteFileResponse |
| OBWriteFileResponse |
|
|
Data | 1..1 | OBWriteFileResponse/Data |
| OBWriteFileResponse/Data |
|
|
FilePaymentId | 1..1 | OBWriteFileResponse/Data/FilePaymentId | OB: Unique identification as assigned by the ASPSP (Bank) to uniquely identify the file payment resource. | String |
|
|
ConsentId | 1..1 | OBWriteFileResponse/Data/ConsentId | OB: Unique identification as assigned by the ASPSP (Bank) to uniquely identify the consent resource. | String |
|
|
CreationDateTime | 1..1 | OBWriteFileResponse/Data/CreationDateTime | Date and time at which the message was created. | DateTime |
|
|
Status | 1..1 | OBWriteFileResponse/Data/Status | Specifies the status of the payment order resource. | String | Enum:
|
|
StatusUpdateDateTime | 1..1 | OBWriteFileResponse/Data/StatusUpdateDateTime | Date and time at which the resource status was updated. | DateTime |
|
|
Charges | 0..n | OBWriteFileResponse/Data/Charges | Set of elements used to provide details of a charge for the payment initiation. | OBCharge |
|
|
Initiation | 1..1 | OBWriteFileResponse/Data/Initiation | The Initiation payload is sent by the initiating party to the ASPSP (Bank). It is used to request movement of funds using a payment file. | OBFileInitiation |
|
|
Debtor | 0..1 | OBWriteFileResponse/Data/Debtor | Set of elements used to identify a person or an organisation | OBWriteFileResponse/Data/Debtor |
|
|
Name | 1..1 | OBWriteFileResponse/Data/Debtor/Name | The account name is the name or names of the account owner(s) represented at an account level, as displayed by the ASPSP’s (Bank's)online channels. Note: The account name is not the product name or the nickname of the account. | String |
|
|
3.4 File Payment - Payment Details - Response
The OBWritePaymentDetailsResponse object will be used for a response to a call to:
GET /file-payments/{FilePaymentId}/payment-details
3.4.1 UML Diagram
3.4.2 Data Dictionary
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
OBWritePaymentDetailsResponse |
| OBWritePaymentDetailsResponse |
| OBWritePaymentDetailsResponse |
|
|
Data | 1..1 | OBWritePaymentDetailsResponse/Data |
| OBWritePaymentDetailsResponse/Data |
|
|
PaymentStatus | 0..n | OBWritePaymentDetailsResponse/Data/PaymentStatus | Payment status details. | OBWritePaymentDetails |
|
|
4. Swagger Code
The swagger code for the Bulk/Batch Payment API can be found on this link.
5. Usage Examples
5.1 POST /file-payments
5.1.1 Request
|
|
5.1.2 Response
|
|