Bulk/Batch Payments
- CBB Admin
1. Version Control
Version | Date | Description of Changes |
Bahrain OBF v1.0.0 | 28th Oct 2020 | Initial Release |
2. Overview
The File Payment resource is used by a PISP to initiate a File Payment.
This resource description should be read in conjunction with a compatible Payment Initiation API Profile. The terminology Bulk/Batch payment and file-payment is used interchangeably.
3. Endpoints
Endpoints for the resources are defined below
S. No. | Resource | HTTP Operation | Endpoint | Mandatory | Scope | Grant Type | Message Signing | Idempotency Key | Request Object | Response Object |
3.1 | file-payments | POST | POST /file-payments | Conditional | payments | Authorisation Code | Signed Request Signed Response | Yes | OBWriteFile | OBWriteFileResponse |
3.2 | file-payments | GET | GET /file-payments/{FilePaymentId} | Mandatory (if resource POST implemented) | payments | Client Credentials | Signed Response | No | NA | OBWriteFileResponse |
3.3 | file-payments | GET | GET /file-payments/{FilePaymentId}/report-file | Conditional | payments | Client Credentials | Signed Response | No | NA | File |
3.4 | payment-details | GET | GET /file-payments/{FilePaymentId}/payment-details | Optional | payments | Client Credentials | Signed Response | No | NA | OBWritePaymentDetailsResponse |
3.1 POST/file-payments
Once the file-payment-consents has been authorised by the user/customer, the PISP can proceed to submitting the file-payments for processing:
This is done by making a POST request to the file-payments endpoint
This request is an instruction to the ASPSP to begin the file-payments journey. The PISP must submit the file-payments immediately, however, there are some scenarios where the ASPSP may not warehouse the file-payments immediately (e.g., busy periods at the ASPSP, may involve different payment execution dates, currencies and payment schemes)
The PISP must ensure that the Initiation section of the file-payments match the Initiation section of the file-payment-consents resource. If the two do not match, the ASPSP must not process the request and must respond with a 400 (Bad Request)
3.1.1 Status
The file-payments resource must have one of the following Status codes:
Status |
InitiationPending |
InitiationFailed |
InitiationCompleted |
3.2 GET/file-payments/{FilePaymentId}
A PISP can retrieve the file-payments to check its status.
3.2.1 Status
The file-payments resource must have one of the following Status codes:
Status |
InitiationPending |
InitiationFailed |
InitiationCompleted |
3.3 GET /file-payments/{FilePaymentId}/report-file
The API endpoint allows the PISP to download a payment report file from an ASPSP.
This endpoint enables ASPSP 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-consents request
HTTP headers (e.g. Content-Type) are used to describe the file
3.4 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 to return richer list of Payment Statuses, and if available payment scheme related statuses.
3.4.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 |
3.5 State Model
3.5.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 | Status Definition |
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 |
4. Data Model
The data dictionary section gives the detail on the payload content for the File Payment API flows.
4.1 OBFileInitiation
The OBFileInitiation class is defined in the file-payment-consents page.
4.2 File Payment - Request
The OBWriteFile object will be used for a call to:
POST /file-payments
4.2.1 UML Diagram
4.2.2 Notes
The file-payments request object contains the:
ConsentId
The full Initiation object from the file-payment-consents request
The Initiation section of the file-payments request must match the Initiation section of the corresponding file-payment-consents request.
4.2.3 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | 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 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. It is used to request movement of funds using a payment file | OBFileInitiation |
|
|
4.3 File Payment - Response
The OBWriteFileResponse object will be used for a response to a call to:
POST /file-payments
GET /file-payments/{FilePaymentId}
4.3.1 UML Diagram
4.3.2 Notes
The file-payments response object contains the:
FilePaymentId
ConsentId
CreationDateTime the file-payments resource was created
Status and StatusUpdateDateTime of the file-payments resource
Charges array is used for the breakdown of applicable ASPSP charges
The Initiation object from the file-payment-consent
An ASPSP should conditionally provide Debtor/Name in the Payment Order Response, even when the user/customer did not provide the Debtor Account via PISP
4.3.3 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes | Pattern |
OBWriteFileResponse |
| OBWriteFileResponse |
| OBWriteFileResponse |
|
|
Data | 1..1 | OBWriteFileResponse/Data |
| OBWriteFileResponse/Data |
|
|
FilePaymentId | 1..1 | OBWriteFileResponse/Data/FilePaymentId | Unique identification as assigned by the ASPSP to uniquely identify the file payment resource | String |
|
|
ConsentId | 1..1 | OBWriteFileResponse/Data/ConsentId | Unique identification as assigned by the ASPSP 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. 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 online channels | String |
|
|
4.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
4.4.1 UML Diagram
4.4.2 Data Dictionary
Name | Occurrence | XPath | Enhanced Definition | Class/ Datatype | Codes | Pattern |
OBWritePaymentDetailsResponse |
| OBWritePaymentDetailsResponse |
| OBWritePaymentDetailsResponse |
|
|
Data | 1..1 | OBWritePaymentDetailsResponse/Data |
| OBWritePaymentDetailsResponse/Data |
|
|
PaymentStatus | 0..n | OBWritePaymentDetailsResponse/Data/PaymentStatus | Payment status details | OBWritePaymentDetails |
|
|
5. Usage Examples
5.1 POST /file-payments
5.1.1 Request
|
|
5.1.2 Response
|
|
CENTRAL BANK OF BAHRAIN © 2020