Domestic Standing Order Payments

Owned by CBB Admin
Last updated: Feb 16, 2021
7 min read

1. Version Control

Version

Date

Description of Changes

Bahrain OBF v1.0.0

25th Aug 2020

Initial Release

2. Overview

The Domestic Standing Orders resource is used by a PISP to initiate a Domestic Standing Order.

This resource description should be read in conjunction with a compatible Payment Initiation API Profile.

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

domestic-standing-orders

POST

POST /domestic-standing-orders

Conditional

payments

Authorization Code

Signed Request Signed Response

Yes

OBWriteDomesticStandingOrder

OBWriteDomesticStandingOrderResponse

3.2

domestic-standing-orders

GET

GET /domestic-standing-orders/{DomesticStandingOrderId}

Mandatory (if resource POST implemented)

payments

Client Credentials

Signed Response

No

NA

OBWriteDomesticStandingOrderResponse

3.3

payment-details

GET

GET /domestic-standing-orders/{DomesticStandingOrderId}/payment-details

Optional

payments

Client Credentials

Signed Response

No

NA

OBWritePaymentDetailsResponse

3.1  POST /domestic-standing-orders

Once the domestic-standing-order-consent has been authorised by the user/customer, the PISP can proceed to submitting the domestic-standing-order for processing:

  • This is done by making a POST request to the domestic-standing-orders endpoint.

  • This request is an instruction to the ASPSP to begin the domestic standing order journey. The PISP must submit the domestic standing order immediately, however, there are some scenarios where the ASPSP may not warehouse the domestic standing order immediately (e.g. busy periods at the ASPSP).

  • The PISP must ensure that the Initiation and Risk sections of the domestic-standing-order match the corresponding Initiation and Risk sections of the domestic-standing-order-consent resource. If the two do not match, the ASPSP must not process the request and must respond with a 400 (Bad Request).

  • Any operations on the domestic-standing-order resource will not result in a Status change for the domestic-standing-order resource.

3.1.1 Status

A domestic-standing-order can only be created if its corresponding domestic-standing-order-consent resource has the status of "Authorised".

The domestic-standing-order resource that is created successfully must have one of the following Status codes:

Status

InitiationPending

InitiationFailed

InitiationCompleted

 

3.2  GET /domestic-standing-orders /{DomesticStandingOrderId}

A PISP can retrieve the domestic-standing-order to check its status.

3.2.1 Status

The domestic-standing-order resource must have one of the following Status codes:

Status

InitiationPending

InitiationFailed

InitiationCompleted

Cancelled

3.3 GET /domestic-standing-orders/{DomesticStandingOrderId}/payment-details

A PISP can retrieve the Details of the underlying payment transaction via this endpoint. This resource allows ASPSPs to return richer list of Payment Statuses, and if available payment scheme related statuses.

3.3.1 Status

The domestic-standing-orders - 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 domestic-standing-order resource describes the initiation status only. i.e., not the subsequent execution of the domestic-standing-order.

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

Cancelled

Payment initiation has been successfully cancelled after having received a request for cancellation.

 

4. Data Model

The Data Dictionary section gives the detail on the payload content for the Domestic Standing Order API flows.

4.1 OBDomesticStandingOrderInitiation (Reused Classes)

The OBDomesticStandingOrderInitiation class is defined in the domestic-standing-order-consents page.

4.2 Domestic Standing Order– Request

The OBWriteDomesticStandingOrder object will be used for the call to:

  • POST /domestic-standing-orders

4.2.1 UML Diagram

4.2.2 Notes

The domestic-standing-order request object contains the:

  • ConsentId.

  • The full Initiation and Risk objects from the domestic-standing-order-consent request.

  • The Initiation and Risk sections of the domestic-standing-order request must match the Initiation and Risk sections of the corresponding domestic-standing-order-consent request.

4.2.3 Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class/ Datatype

Codes

Pattern

OBWriteDomesticStandingOrder

 

OBWriteDomesticStandingOrder

 

OBWriteDomesticStandingOrder

 

 

Data

1..1

OBWriteDomesticStandingOrder/Data

 

OBWriteDomesticStandingOrder/Data

 

 

ConsentId

1..1

OBWriteDomesticStandingOrder/Data/ConsentId

Unique identification as assigned by the ASPSP to uniquely identify the consent resource.

String

 

 

Initiation

1..1

OBWriteDomesticStandingOrder/Data/Initiation

The Initiation payload is sent by the initiating party to the ASPSP. It is used to request movement of funds from the debtor account to a creditor for a domestic standing order.

OBDomesticStandingOrderInitiation

 

 

Risk

1..1

OBWriteDomesticStandingOrder/Risk

The Risk section is sent by the initiating party to the ASPSP. It is used to specify additional details for risk scoring for Payments.

OBRisk

 

 

 

4.3 Domestic Standing Order - Response

The OBWriteDomesticStandingOrderResponse object will be used for a response to a call to:

  • POST /domestic-standing-orders.

  • GET /domestic-standing-orders/{DomesticStandingOrderId}.

4.3.1 UML Diagram

 

4.3.2 Notes

The domestic-standing-order response object contains the:

  • DomesticStandingOrderId.

  • ConsentId.

  • CreationDateTime the domestic-standing-order resource was created.

  • Status and StatusUpdateDateTime of the domestic-standing-order resource.

  • Refund account details, if requested by PISP as part of the domestic-payment-consents resource.

  • Charges array - for the breakdown of applicable ASPSP charges.

  • The Initiation object from the domestic-standing-order-consent.

  • An ASPSP should conditionally provide Debtor/Name in the Payment Order Response, even when the Payer didn't provide the Debtor Account via PISP.

4.3.3 Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class/ Datatype

Codes

Pattern

OBWriteDomesticStandingOrderResponse

 

OBWriteDomesticStandingOrderResponse

 

OBWriteDomesticStandingOrderResponse

 

 

Data

1..1

OBWriteDomesticStandingOrderResponse/Data

 

OBWriteDomesticStandingOrderResponse/Data

 

 

DomesticStandingOrderId

1..1

OBWriteDomesticStandingOrderResponse/Data/DomesticStandingOrderId

Unique identification as assigned by the ASPSP to uniquely identify the domestic standing order resource.

String

 

 

ConsentId

1..1

OBWriteDomesticStandingOrderResponse/Data/ConsentId

Unique identification as assigned by the ASPSP to uniquely identify the consent resource.

String

 

 

CreationDateTime

1..1

OBWriteDomesticStandingOrderResponse/Data/CreationDateTime

Date and time at which the resource was created.

DateTime

 

 

Status

1..1

OBWriteDomesticStandingOrderResponse/Data/Status

Specifies the status of the payment order resource.

String

Enum:

  • InitiationCompleted

  • InitiationFailed

  • InitiationPending

  • Cancelled

 

StatusUpdateDateTime

1..1

OBWriteDomesticStandingOrderResponse/Data/StatusUpdateDateTime

Date and time at which the resource status was updated.

DateTime

 

 

Refund

0..1

OBWriteDomesticStandingOrderResponse/Data/Refund

Unambiguous identification of the refund account to which a refund will be made as a result of the transaction.

OBDomesticRefundAccount

 

 

Charges

0..n

OBWriteDomesticStandingOrderResponse/Data/Charges

Set of elements used to provide details of a charge for the payment initiation.

OBCharge

 

 

Initiation

1..1

OBWriteDomesticStandingOrderResponse/Data/Initiation

The Initiation payload is sent by the initiating party to the ASPSP. It is used to request movement of funds from the debtor account to a creditor for a domestic standing order.

OBDomesticStandingOrderInitiation

 

 

 

4.4 Domestic Standing Order - Payment Details - Response

The OBWritePaymentDetailsResponse object will be used for a response to a call to:

  • GET /domestic-standing-orders/{DomesticStandingOrderId}/payment-details.

4.4.1 UML Diagram

4.4.2 Notes

The domestic payment detail response object contains the:

  • PaymentStatus.

4.4.3 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.

OBWritePaymentDetailsResponse/Data/PaymentStatus

 

 

PaymentTransactionId

1..1

OBWritePaymentDetailsResponse/Data/PaymentStatus/PaymentTransactionId

Unique identifier for the transaction within a servicing institution. This identifier is both unique and immutable.

 

String

 

 

Status

1..1

OBWritePaymentDetailsResponse/Data/PaymentStatus/Status

Status of a transfer, as assigned by the transaction administrator.

String

Enum:

  • Accepted

  • AcceptedCancellationRequest

  • AcceptedCreditSettlementCompleted

  • AcceptedCustomerProfile

  • AcceptedFundsChecked

  • AcceptedSettlementCompleted

  • AcceptedSettlementInProcess

  • AcceptedTechnicalValidation

  • AcceptedWithChange

  • AcceptedWithoutPosting

  • Cancelled

  • NoCancellationProcess

  • PartiallyAcceptedCancellationRequest

  • PartiallyAcceptedTechnicalCorrect

  • PaymentCancelled

  • Pending

  • PendingCancellationRequest

  • Received

  • Rejected

  • RejectedCancellationRequest

 

StatusUpdateDateTime

1..1

OBWritePaymentDetailsResponse/Data/PaymentStatus/StatusUpdateDateTime

Date and time at which the status was assigned to the transfer. All dates in the JSON payloads are represented in ISO 8601 date-time format.

DateTime

 

 

StatusDetail

0..1

OBWritePaymentDetailsResponse/Data/PaymentStatus/StatusDetail

Payment status details as per underlying Payment Rail.

 

OBWritePaymentDetailsResponse/Data/PaymentStatus/StatusDetail

 

 

LocalInstrument

1..1

OBWritePaymentDetailsResponse/Data/PaymentStatus/StatusDetail/LocalInstrument

This element is used to specify a local instrument, local clearing option and/or further qualify the service or service level.

 

String

Enum:

  • BH.OBF.DNS

 

Status

1..1

OBWritePaymentDetailsResponse/Data/PaymentStatus/StatusDetail/Status

Status of a transfer, as assigned by the transaction administrator.

 

String

 

 

StatusReason

 

0..1

OBWritePaymentDetailsResponse/Data/PaymentStatus/StatusDetail/StatusReason

 

Reason Code provided for the status of a transfer.

String

Enum:

  • Cancelled

  • PendingFailingSettlement

  • PendingSettlement

  • Proprietary

  • ProprietaryRejection

  • Suspended

  • Unmatched 

 

StatusReasonDescription

0..1

OBWritePaymentDetailsResponse/Data/PaymentStatus/StatusDetail/ StatusReasonDescription

Reason provided for the status of a transfer.

 

String

 

 

 

5. Usage Example

5.1 POST /domestic-standing-orders

5.1.1 Request

POST /domestic-standing-orders

Authorization: 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": "56565656",

    "Initiation": {

      "Frequency": " WkInMnthDay:02:03",

      "Reference": " ",

      "NumberOfPayments": "6",

      "FirstPaymentDateTime": "2020-03-18T08:26:39.976+03:00",

      "RecurringPaymentDateTime": "2020-03-18T08:26:39.976+03:00",

      "FinalPaymentDateTime": "2020-08-18T08:26:39.976+03:00",

      "FirstPaymentAmount": {

        "Amount": "80.54",

        "Currency": "BHD"

      },

      "RecurringPaymentAmount": {

        "Amount": "64.30",

        "Currency": "BHD"

      },

      "FinalPaymentAmount": {

        "Amount": "64.30",

        "Currency": "BHD"

      },

      "DebtorAccount": {

        "SchemeName": "IBAN",

        "Identification": "BH10BBKU00100000008876",

        "Name": " Khalid Ahmed Ali "

      },

      "CreditorAccount": {

        "SchemeName": "BH.OBF.IBAN",

        "Identification": "BH89ABIC00000987654321",

        "Name": " Mohammed Ahmed Abdulla ”

      },

    },

  "Risk": {

    "PaymentContextCode": "BillPayment",

    "MerchantCategoryCode": "002345",

    "MerchantCustomerIdentification": "0023456789",

    "DeliveryAddress": {

      "AddressLine": "Block 317, Road 1800, Building 5”,

      "SubDepartment": " ",

      "StreetName": "Route 1888",

      "BuildingNumber": "27",

      "PostCode": "317",

      "TownName": "Manama",

      "CountySubDivision": "Manama”      

      "Country": "BH",   

         }

  }

}

 

5.1.2 Response

201 Created

x-jws-signature: LMlmPSqzISEpar72ce5deMGue4RsZMDnZYG1bW6hdPlvriZ=

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

Content-Type: application/json

 

{z

  "Data": {

    "DomesticStandingOrderId": "839424",

    "ConsentId": "56565656",

    "CreationDateTime": "2020-03-18T08:52:53.879+03:00",

    "Status": "Cancelled",

    "StatusUpdateDateTime": "2020-03-18T08:52:53.879+03:00",

    },

    "Charges": [

      {

        "ChargeBearer": "BorneByCreditor",

        "Type": "BH.OBF.DNS",

        "Amount": {

          "Amount": "19.94",

          "Currency": "BHD"

        }

      }

    ],

    "Initiation": {

      "Frequency": " WkInMnthDay:02:03",

      "Reference": " ",

      "NumberOfPayments": "6",

      "FirstPaymentDateTime": "2020-03-18T08:26:39.976+03:00",

      "RecurringPaymentDateTime": "2020-03-18T08:26:39.976+03:00",

      "FinalPaymentDateTime": "2020-08-18T08:26:39.976+03:00",

      "FirstPaymentAmount": {

        "Amount": "80.54",

        "Currency": "BHD"

      },

      "RecurringPaymentAmount": {

        "Amount": "64.30",

        "Currency": "BHD"

      },

 

"FinalPaymentAmount": {

        "Amount": "64.30",

        "Currency": "BHD"

      },

      "DebtorAccount": {

        "SchemeName": "BH.OBF.IBAN",

        "Identification": "BH10BBKU00100000008876",

        "Name": " Khalid Ahmed Ali "

      },

      "CreditorAccount": {

        "SchemeName": "BH.OBF.IBAN",

        "Identification": "BH89ABIC00000987654321",

        "Name": "Mohammed Ahmed Abdulla "

      }

    }

  },

  "Links": {

    "Self": "www.TBC.com",

  },

  "Meta": {

    "TotalPages": 02,

    "FirstAvailableDateTime": "2020-03-18T08:52:53.879+03:00",

    "LastAvailableDateTime": "2020-03-18T08:52:53.879+03:00"

  }

}

 

 

CENTRAL BANK OF BAHRAIN Âİ 2020