1. Version Control

Version	Date	Description of Changes
Bahrain OBF v1.0.0	28th Oct 2020	Initial Release

2. Overview

The International Payments resource is used by a PISP to initiate an International Payment.

These API Specifications should be read in conjunction with a Payment Initiation API Profile.

3. 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
3.1	international-payments	POST	POST /international-payments	Conditional	payments	Authorisation Code	Signed Request Signed Response	Yes	OBWriteInternational	OBWriteInternationalPaymentResponse
3.2	international-payments	GET	GET /international-payments/{InternationalPaymentId}	Mandatory (if resource POST implemented)	payments	Client Credentials	Signed Response	No	NA	OBWriteInternationaPaymentlResponse
3.3	payment-details	GET	GET /international-payments/{InternationalPaymentId}/payment-details	Optional	payments	Client Credentials	Signed Response	No	NA	OBWritePaymentDetailsResponse

3.1 POST/international-payments

Once the international-payment-consents has been authorised by the user/customer, the PISP can proceed to submit the international-payments for processing:

This is done by making a POST request to the international-payments endpoint
This request is an instruction to the ASPSP to begin the international single immediate payment journey. The international payment must be submitted immediately, however, there are some scenarios where the international payment may not be executed immediately (e.g. busy periods at the ASPSP)
The PISP must ensure that the Initiation and Risk sections of the international-payments match the corresponding Initiation and Risk sections of the international-payment-consents 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 international-payments resource will not result in a Status change for the international-payments resource

3.1.1 Status

An international-payments can only be created if its corresponding international-payment-consents resource has the status of "Authorised".

The international-payments resource that is created successfully must have one of the following PaymentStatusCode code-set enumerations:

Status

Pending

Rejected

AcceptedSettlementInProcess

AcceptedSettlementCompleted

AcceptedWithoutPosting

AcceptedCreditSettlementCompleted

3.2 GET /international-payments/{InternationalPaymentId}

A PISP can retrieve the international-payment to check its status.

3.2.1 Status

The international-payments resource must have one of the following PaymentStatusCode code-set enumerations:

Status

Pending

Rejected

AcceptedSettlementInProcess

AcceptedSettlementCompleted

AcceptedWithoutPosting

AcceptedCreditSettlementComplete

3.3 GET /international-payments /{InternationalPaymentId}/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 international-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.4 State Model

3.4.1 Payment Order

The state model for the international-payments resource follows the behaviour and definitions for the ISO 20022 PaymentStatusCode code-set.

The definitions for the Status:

S.No.	Status	Status Definition
1	Pending	Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed
2	Rejected	Payment initiation or individual transaction included in the payment initiation has been rejected
3	AcceptedSettlementInProcess	All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution
4	AcceptedSettlementCompleted	Settlement on the debtor's account has been completed
5	AcceptedWithoutPosting	Payment instruction included in the credit transfer is accepted without being posted to the creditor customer’s account
6	AcceptedCreditSettlementCompleted	Settlement on the creditor's account has been completed

4. Data Model

The Data Dictionary section gives the detail on the payload content for the International Payment API flows.

4.1 OBInternationalPaymentIntiation

The OBInternationalPaymentInitiation class is defined in the international-payment-consents page.

4.2 OBExchangeRateResponse

The OBExchangeRateResponse class is defined in the international-payment-consents page.

4.3 OBInternationalRefundAccount

This section describes the OBInternationalRefundAccount class which is used in the response payloads of International Payment.

4.3.1 UML Diagram

4.3.2 Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class/ Datatype	Codes	Pattern
OBInternationalRefundAccount		OBInternationalRefundAccount	Unambiguous identification of the refund account to which a refund will be made as a result of the transaction	OBInternationalRefundAccount
Creditor	0..1	OBInternationalRefundAccount/Creditor	Party to which an amount of money is due	OBInternationalRefundAccount/Creditor
Name	0..1	OBInternationalRefundAccount/Creditor/Name	Name by which a party is known and which is usually used to identify that party	String
PostalAddress	0..1	OBInternationalRefundAccount/Creditor/PostalAddress	Information that locates and identifies a specific address, as defined by postal services	OBPostalAddress
AddressType	0..1	OBInternationalRefundAccount/Creditor/PostalAddress/AddressType	Identifies the nature of the postal address	String	Enum: Business Correspondence DeliveryTo MailTo POBox Postal Residential Statement
Department	0..1	OBInternationalRefundAccount/Creditor/PostalAddress/Department	Identification of a division of a large organisation or building	String
SubDepartment	0..1	OBInternationalRefundAccount/Creditor/PostalAddress/SubDepartment	Identification of a sub-division of a large organisation or building	String
AddressLine	0..7	OBInternationalRefundAccount/Creditor/PostalAddress/AddressLine	Information that locates and identifies a specific address, as defined by postal services, presented in free format text	String
StreetName	0..1	OBInternationalPaymentInitiation/Creditor/PostalAddress/StreetName	Name of a street or thoroughfare	String
BuildingNumber	0..1	OBInternationalPaymentInitiation/Creditor/PostalAddress/BuildingNumber	Number that identifies the position of a building on a street	String
PostCode	0..1	OBInternationalPaymentInitiation/Creditor/PostalAddress/PostCode	Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail	String
TownName	0..1	OBInternationalPaymentInitiation/Creditor/PostalAddress/TownName	Name of a built-up area, with defined boundaries, and a local government	String
CountrySubDivision	0..1	OBInternationalPaymentInitiation/Creditor/PostalAddress/CountrySubDivision	Identifies a subdivision of a country such as state, region, country	String
Country	0..1	OBInternationalPaymentInitiation/Creditor/PostalAddress/Country	Nation with its own government	String		^[A-Z]{2,2}$
Agent	0..1	OBInternationalRefundAccount/Agent	Financial institution servicing an account for the creditor	OBInternationalRefundAccount/Agent
SchemeName	0..1	OBInternationalRefundAccount/Agent/SchemeName	Name of the identification scheme, in a coded form as published in an external list	String	Enum: BH.OBF.BICFI BH.OBF.NCC
Identification	0..1	OBInternationalRefundAccount/Agent/Identification	Unique and unambiguous identification of a financial institution or a branch of a financial institution	String
Name	0..1	OBInternationalRefundAccount/Agent/Name	Name by which an agent is known and which is usually used to identify that agent	String
PostalAddress	0..1	OBInternationalRefundAccount/Agent/PostalAddress	Information that locates and identifies a specific address, as defined by postal services	OBPostalAddress
AddressType	0..1	OBInternationalRefundAccount/Agent/PostalAddress/AddressType	Identifies the nature of the postal address	String	Enum: Business Correspondence DeliveryTo MailTo POBox Postal Residential Statement
Department	0..1	OBInternationalRefundAccount/Agent/PostalAddress/Department	Identification of a division of a large organisation or building	String
SubDepartment	0..1	OBInternationalRefundAccount/Agent/PostalAddress/SubDepartment	Identification of a sub-division of a large organisation or building	String
AddressLine	0..7	OBInternationalRefundAccount/Agent/PostalAddress/AddressLine	Information that locates and identifies a specific address, as defined by postal services, presented in free format text	String
StreetName	0..1	OBInternationalRefundAccount/Agent/PostalAddress/StreetName	Name of a street or thoroughfare	String
BuildingNumber	0..1	OBInternationalRefundAccount/Agent/PostalAddress/BuildingNumber	Number that identifies the position of a building on a street	String
PostCode	0..1	OBInternationalRefundAccount/Agent/PostalAddress/PostCode	Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail	String
TownName	0..1	OBInternationalRefundAccount/Agent/PostalAddress/TownName	Name of a built-up area, with defined boundaries, and a local government	String
CountrySubDivision	0..1	OBInternationalRefundAccount/Agent/PostalAddress/CountrySubDivision	Identifies a subdivision of a country such as state, region, country	String
Country	0..1	OBInternationalRefundAccount/Agent/PostalAddress/Country	Nation with its own government	String		^[A-Z]{2,2}$
Account	1..1	OBInternationalRefundAccount/Account	Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction	OBInternationalRefundAccount/Account
SchemeName	1..1	OBInternationalRefundAccount/Account/SchemeName	Name of the identification scheme, in a coded form as published in an external list	String	Enum: BH.OBF.IBAN BH.OBF.PAN
Identification	1..1	OBInternationalRefundAccount/Account/Identification	Identification assigned by an institution to identify an account. This identification is known by the account owner	String
Name	1..1	OBInternationalRefundAccount/Account/Name	The account name is the name or names of the account owner(s) represented at an account level. Note, the account name is not the product name or the nickname of the account	String

4.4 International Payment - Request

The OBWriteInternational object will be used for a call to:

POST /international-payments

4.4.1 UML Diagram

4.4.2 Notes

The international-payments request object contains the:

ConsentId
The full Initiation and Risk objects from the international-payments request
The Initiation and Risk sections of the international-payments request must match the Initiation and Risk sections of the corresponding international-payment-consents request

4.4.3 Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class/ Datatype	Codes	Pattern
OBWriteInternational	OBWriteInternational		OBWriteInternational
Data	1..1	OBWriteInternational/Data		OBWriteInternational/Data
ConsentId	1..1	OBWriteInternational/Data/ConsentId	Unique identification as assigned by the ASPSP to uniquely identify the consent resource	String
Initiation	1..1	OBWriteInternational/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 Single International Payment	OBInternationalPaymentInitiation
Risk	1..1	OBWriteInternational/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.5 International Payment – Response

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

POST /international-payments
GET /international-payments/{InternationalPaymentId}

4.5.1 UML Diagram

4.5.2 Notes

The international-payments response object contains the:

InternationalPaymentId
ConsentId
CreationDateTime of the international-payments resource
Status and StatusUpdateDateTime of the international-payments resource
ExpectedExecutionDateTime for the international-payments resource
ExpectedSettlementDateTime for the international-payments resource
Refund account details, if requested by PISP as part of the international-payment-consents resource
The Charges and ExchangeRateInformation in the international-payment-consents response from the ASPSP
The Initiation object from the international-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.5.3 Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class/ Datatype	Codes	Pattern
OBWriteInternationalPaymentResponse		OBWriteInternationalPaymentResponse		OBWriteInternationalPaymentResponse
Data	1..1	OBWriteInternationalPaymentResponse/Data		OBWriteInternationalPaymentResponse/Data
InternationalPaymentId	1..1	OBWriteInternationalPaymentResponse/Data/InternationalPaymentId	OB: Unique identification as assigned by the ASPSP to uniquely identify the international payment resource	String
ConsentId	1..1	OBWriteInternationalPaymentResponse/Data/ConsentId	OB: Unique identification as assigned by the ASPSP to uniquely identify the consent resource	String
CreationDateTime	1..1	OBWriteInternationalPaymentResponse/Data/CreationDateTime	Date and time at which the message was created	DateTime
Status	1..1	OBWriteInternationalPaymentResponse/Data/Status	Specifies the status of the payment information group	String	Enum: AcceptedCreditSettlementCompleted AcceptedWithoutPosting AcceptedSettlementCompleted AcceptedSettlementInProcess Pending Rejected
StatusUpdateDateTime	1..1	OBWriteInternationalPaymentResponse/Data/StatusUpdateDateTime	Date and time at which the resource status was updated	DateTime
ExpectedExecutionDateTime	0..1	OBWriteInternationalPaymentResponse/Data/ExpectedExecutionDateTime	Expected execution date and time for the payment resource	DateTime
ExpectedSettlementDateTime	0..1	OBWriteInternationalPaymentResponse/Data/ExpectedSettlementDateTime	Expected settlement date and time for the payment resource	DateTime
Refund	0..1	OBWriteInternationalPaymentResponse/Data/Refund	Unambiguous identification of the refund account to which a refund will be made as a result of the transaction	OBInternationalRefundAccount
Charges	0..n	OBWriteInternationalPaymentResponse/Data/Charges	Set of elements used to provide details of a charge for the payment initiation	OBCharge
ExchangeRateInformation	0..1	OBWriteInternationalPaymentResponse/Data/ExchangeRateInformation	Further detailed information on the exchange rate that has been used in the payment transaction	OBExchangeRateResponse
Initiation	1..1	OBWriteInternationalPaymentResponse/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 Single International Payment	OBInternationalPaymentInitiation
Debtor	0..1	OBWriteInternationalPaymentResponse/Data/Debtor	Set of elements used to identify a person or an organisation	OBWriteInternationalPaymentResponse/Data/Debtor
Name	1..1	OBWriteInternationalPaymentResponse/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.6 International Payment Order –Payment Details - Response

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

GET /international-payments/{InternationalPaymentId}/payment-details

4.6.1 UML Diagram

4.6.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 /international-payments

5.1.1 Request

POST /international-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": {
    "InstructionIdentification": "0616I029",
      "EndToEndIdentification": "20190616B002",
      "LocalInstrument": " BH.OBF.SWIFT ",
      "InstructionPriority": "Normal",
      "Purpose": " ",
      "ExtendedPurpose": " ",
      "ChargeBearer": "BorneByCreditor",
      "CurrencyOfTransfer": "BHD",
      "DestinationCountryCode": "BH",
      "InstructedAmount": {
        "Amount": "5.60",
        "Currency": "BHD"
      },
      "ExchangeRateInformation": {
        "UnitCurrency": "USD",
        "ExchangeRate": 2.65,
        "RateType": "Actual",
        "ContractIdentification": "FEC"
      },
      "DebtorAccount": {
        "SchemeName": "BH.OBF.IBAN",
        "Identification": "BH10CBBU00100000008876",
        "Name": "Khalid Ahmed Ali",
      },
      "Creditor": {
        "Name": "Ali Hassan Mohammed",
        "PostalAddress": {
          "AddressType": "Business",

"AddressLine": "XYZBank, Diplomatic Area”

“StreetName”: “Al Barsha”

          "BuildingNumber": "27",
          "PostCode": "317",
          "TownName": "Manama",
          "CountySubDivision": "Manama”

          "Country": "BH",
        }
      },

       "CreditorAgent": {
        "SchemeName": "BH.OBF.BICFI",
        "Identification": "BOBFBICFXYZ",
        "Name": "Faisal Hassan Mohammed",
        "PostalAddress": {

"AddressType": "Business",

"AddressLine": "XYZ Bank, Diplomatic Area”

“StreetName”: “Acacia Avenue”

          "BuildingNumber": "27",
          "PostCode": "3122",
          "TownName": "Manama",
          "CountySubDivision": "Manama”

          "Country": "BH",
        }
      },
      "CreditorAccount": {
        "SchemeName": "BH.OBF.BBAN",
        "Identification": "USU0010000000667346",
        "Name": "Ali Hassan Mohammed",
      },
      "RemittanceInformation": {
        "RemittanceDescription": "External Ops Code 34251",
        "Reference": "XYZ-101"
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "BillPayment",
    "MerchantCategoryCode": "002345",
    "MerchantCustomerIdentification": "0023456789",
    "DeliveryAddress": {
      "AddressLine": "XYZ Bank, Diplomatic Area”

“StreetName”: “Al Barsha”

      "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

{
  "Data": {
    "InternationalPaymentId": "763498",
    "ConsentId": "565656",
    "CreationDateTime": "2020-03-20T06:32:01.575+03:00",
    "Status": "AcceptedCreditSettlementCompleted",
    "StatusUpdateDateTime": "2020-03-20T06:32:01.575+03:00",
    "ExpectedExecutionDateTime": "2020-03-20T06:32:01.575+03:00",
    "ExpectedSettlementDateTime": "2020-03-20T06:32:01.575+03:00",
    "Refund": {
      "Creditor": {
        "Name": "Ali Hassan Mohammed",
        "PostalAddress": {
          "AddressType": "Business",

"AddressLine": "XYZ Bank, Diplomatic Area”

“StreetName”: “Al Barsha”

          "BuildingNumber": "27",
          "PostCode": "317",
          "TownName": "Manama",
          "CountySubDivision": "Manama”

          "Country": "BH",
        }
      },
      "Agent": {
        "SchemeName": "BH.OBF.BICFI",
        "Identification": "BOBFBICFXYZ",
        "Name": "Faisal Hassan Mohammed",
        "PostalAddress": {
          "AddressType": "Business",
          "AddressLine": "Batelco Headquarters”

“StreetName”: “Acacia Avenue”

          "BuildingNumber": "27",
          "PostCode": "3122",
          "TownName": "Manama",
          "CountySubDivision": "Manama”

          "Country": "BH",
        }
      },

      "Account": {
        "SchemeName": "BH.OBF.IBAN",
        "Identification": " USU0010000000667346",
        "Name": "Ali Hassan Mohammed",
      }
    },
    "Charges": [
      {
        "ChargeBearer": "BorneByCreditor",
        "Type": " ",
        "Amount": {
          "Amount": "2.41",
          "Currency": "BHD"
        }
      }
    ],
    "ExchangeRateInformation": {
      "UnitCurrency": "USD",
      "ExchangeRate": 2.65,
      "RateType": "Actual",
      "ContractIdentification": "FEC",
      "ExpirationDateTime": "2020-03-20T06:17:39.598+03:00"
    },
    "Initiation": {
    "InstructionIdentification": "0616I029",
      "EndToEndIdentification": "20190616B002",
      "LocalInstrument": " BH.OBF.SWIFT",
      "InstructionPriority": "Normal",
      "Purpose": " ",
      "ExtendedPurpose": " ",
      "ChargeBearer": "BorneByCreditor",
      "CurrencyOfTransfer": "BHD",
      "DestinationCountryCode": "BH",
      "InstructedAmount": {
        "Amount": "5.60",
        "Currency": "BHD"
      },
"ExchangeRateInformation": {
        "UnitCurrency": "USD",
        "ExchangeRate": 2.65,
        "RateType": "Actual",
        "ContractIdentification": "FEC"
      },
      "DebtorAccount": {
        "SchemeName": "BH.OBF.IBAN",
        "Identification": "BH10CBBU00100000008876",
        "Name": "Khalid Ahmed Ali",
      },
      "Creditor": {
        "Name": "Ali Hassan Mohammed",
        "PostalAddress": {
          "AddressType": "Business",

"AddressLine": "XYZ Bank, Diplomatic Area”

“StreetName”: “Al Barsha”

          "BuildingNumber": "27",
          "PostCode": "317",
          "TownName": "Manama",
          "CountySubDivision": "Manama”

          "Country": "BH",
        }
      },

      "CreditorAgent": {
        "SchemeName": "BH.OBF.BICFI",
        "Identification": "BOBFBICFXYZ",
        "Name": "Faisal Hassan Mohammed",
        "PostalAddress": {
          "AddressType": "Business",
          "AddressLine": "Batelco Headquarters”

“StreetName”: “Acacia Avenue”

          "BuildingNumber": "27",
          "PostCode": "3122",
          "TownName": "Manama",
          "CountySubDivision": "Manama”

          "Country": "BH",
        }
      },
      "CreditorAccount": {
        "SchemeName": "BH.OBF.BBAN",
        "Identification": " USU0010000000667346",
        "Name": "Ali Hassan Mohammed",
      },
      "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"
  }
}