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: InitiationCompleted InitiationFailed InitiationPending
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

POST /file-payments

Authorisation: Bearer 4ZopnFZFKjr5zDsicSQpLL

x-idempotency-key: XYZ.51403.MLT.30

x-jws-signature: LMlmPSqzISEpar72ce5deMGue4RsZMDnZYG1bW6hdPlvriZ=..G1rrM18vVYBmdmRurS6nIR1yFHR8bGZyIJdvaB5nKGRvm35hTr==

x-fapi-auth-date: Tue, 18 Mar 2020 19:43:31 GMT+03:00

x-fapi-customer-ip-address: 204.35.213.15

x-fapi-interaction-id: 75bdc714-b2dg-7676-c759-780d6815689f

Content-Type: application/json

Accept: application/json

{
  "Data": {
    "ConsentId": "565656",
    "Initiation": {
      "FileContextFormat": "BH.OBF.pain.001.001.08",
      "FileHash": "jhkgas5768a/s78as",
      "FileReference": "41536789",
      "NumberOfTransactions": "10",
      "ControlSum": “10”,
      "RequestedExecutionDateTime": "2020-03-20T09:14:32.115+03:00",
      "LocalInstrument": "BH.OBF.DNS",
      "DebtorAccount": {
        "SchemeName": "BH.OBF.IBAN",
        "Identification": "BH10CBBU00100000008876",
        "Name": "Khalid Ahmed Ali",
      },
      "RemittanceInformation": {
        "RemittanceDescription": "External Ops Code 34251",
        "Reference": "XYZ-101"
      }
    }
  }
}

5.1.2 Response

201 Created

x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K

x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d

Content-Type: application/json

{
  "Data": {
    "FilePaymentId": "764356",
    "ConsentId": "565656",
    "CreationDateTime": "2020-03-20T11:07:04.048+03:00",
    "Status": "InitiationCompleted",
    "StatusUpdateDateTime": "2020-03-20T11:07:04.048+03:00",
    "Charges": [
      {
        "ChargeBearer": "BorneByCreditor",
        "Type": " ",
        "Amount": {
          "Amount": "2.38",
          "Currency": "BHD"
        }
      }
    ],
    "Initiation": {
      "FileContextFormat": "BH.OBF.pain.001.001.08",
      "FileHash": "jhkgas5768a/s78as",
      "FileReference": "41536789",
      "NumberOfTransactions": "10",
      "ControlSum": 2,
      "RequestedExecutionDateTime": "2020-03-20T09:14:32.115+03:00",
      "LocalInstrument": "BH.OBF.DNS",
      "DebtorAccount": {
        "SchemeName": "BH.OBF.IBAN",
        "Identification": "BH10CBBU00100000008876",
        "Name": "Khalid Ahmed Ali",
      },
      "RemittanceInformation": {
        "RemittanceDescription": "External Ops Code 34251",
        "Reference": "XYZ-101"
      },
    },

  "Links": {
    "Self": "www.TBC.com"
  },
  "Meta": {
    "TotalPages": 1,
    "FirstAvailableDateTime": "2020-03-20T09:10:17.596+03:00",
    "LastAvailableDateTime": "2020-03-20T09:10:17.596+03:00"
  }
}

Bulk/Batch Payments

1. Version Control

2. Overview

3. Endpoints

3.1 POST/file-payments

3.1.1 Status

3.2 GET/file-payments/{FilePaymentId}

3.2.1 Status

3.3 GET /file-payments/{FilePaymentId}/report-file

3.4 GET /file-payments/{FilePaymentId}/payment-details

3.4.1 Status

3.5 State Model

3.5.1 Payment Order

4. Data Model

4.1 OBFileInitiation

4.2 File Payment - Request

4.2.1 UML Diagram

4.2.2 Notes

4.2.3 Data Dictionary

4.3 File Payment - Response

4.3.1 UML Diagram

4.3.2 Notes

4.3.3 Data Dictionary

4.4 File Payment - Payment Details - Response

4.4.1 UML Diagram

4.4.2 Data Dictionary

5. Usage Examples

5.1 POST /file-payments

5.1.1 Request

5.1.2 Response