openapi: 3.0.1
servers:
- url: https://{server}/v2024.07
description: Ozone Connect - Service Initiation APIs
variables:
server:
default: rs1.*
description: The server that the API is hosted on.
info:
title: Ozone Connect - Service Initiation APIs
description: |
This document provides the OAS3 specification for Service Initiation APIs for Ozone Connect.
These APIs should be implemented by an LFI so that Ozone
can deliver Service Initiation capabilities to TPPs
version: Version 2.2 Release 2022.39.1
tags:
- name: payments
description: |
APIs that should be implemented by LFIs to expose Service Initiation capability to TPPs.
paths:
/payment-consent/action/validate:
post:
tags:
- payments
summary: Payment action validation
description: |
The API is called by Ozone to allow an LFI to carry out additional validations
before a payment consent is created.
The request body contains the entire payment consent along with contextual information.
Typically this could be used for situations like:
- soft validation of the debtor account (e.g. to ensure that it is a debtor account managed by the LFI)
- populating charges and exchange rate information (in future versions)
Note that an LFI only need to implement this API where it needs to correlate information in the consent payload
with data held in its systems. If this is not the case, "local" validations can be configured in Ozone that do not
require a remote call.
The LFI must return a `PaymentConsentValidateResponse` which includes a status. If the status is set to `valid`, the
consent is saved and processing continues.
If the status is set to `invalid` the processing fails and an error response is sent to the TPP.
operationId: validatePaymentConsent
parameters:
# common header parameters that set context
- $ref: "#/components/parameters/aspspId"
- $ref: "#/components/parameters/callerOrgId"
- $ref: "#/components/parameters/callerClientId"
- $ref: "#/components/parameters/callerSoftwareStatementId"
- $ref: "#/components/parameters/apiUri"
- $ref: "#/components/parameters/apiOperation"
- $ref: "#/components/parameters/consentId"
- $ref: "#/components/parameters/callerInteractionId"
- $ref: "#/components/parameters/ozoneInteractionId"
- $ref: "#/components/parameters/psuIdentifier"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentConsentValidateRequest"
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentConsentValidateResponse"
400:
description: failed operation
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/payments:
post:
tags:
- payments
summary: Make a payment
description: |
This API is called by Ozone Connect to instruct an LFI to initiate a payment once it has received a payment
instruction from a TPP that has passed all local validations.
The LFI must process the payment and indicate a failure response (if the payment fails technical validation) or a
success response (if the payment passess technical validation and is submitted to the payment rails for processing)
The LFI must generate a unique `PaymentId` that can be sent on to the TPP as a reference for the payment.
If the underlying consent has been patched with a `bankConnectToken`, then the token is passed in as the authorization header.
operationId: makePayment
parameters:
# common header parameters that set context
- $ref: "#/components/parameters/aspspId"
- $ref: "#/components/parameters/callerOrgId"
- $ref: "#/components/parameters/callerClientId"
- $ref: "#/components/parameters/callerSoftwareStatementId"
- $ref: "#/components/parameters/apiUri"
- $ref: "#/components/parameters/apiOperation"
- $ref: "#/components/parameters/consentId"
- $ref: "#/components/parameters/callerInteractionId"
- $ref: "#/components/parameters/ozoneInteractionId"
- $ref: "#/components/parameters/psuIdentifier"
requestBody:
required: true
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentRequest"
responses:
201:
description: successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentResponse"
400:
description: failed operation
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
security:
- bearerAuth: []
/payments/:paymentId:
get:
tags:
- payments
summary: Get a payment
description: |
Ozone can call this API from LFIs to retrieve payment information.
parameters:
# common header parameters that set context
- $ref: "#/components/parameters/aspspId"
- $ref: "#/components/parameters/callerOrgId"
- $ref: "#/components/parameters/callerClientId"
- $ref: "#/components/parameters/callerSoftwareStatementId"
- $ref: "#/components/parameters/apiUri"
- $ref: "#/components/parameters/apiOperation"
- $ref: "#/components/parameters/consentId"
- $ref: "#/components/parameters/callerInteractionId"
- $ref: "#/components/parameters/ozoneInteractionId"
- $ref: "#/components/parameters/psuIdentifier"
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentGetResponse"
400:
description: failed operation
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/payments/:paymentId/details:
get:
tags:
- payments
summary: Get payment details
description: |
In situations where an API supports retrieval of detailed payment information,
Ozone can call this API from LFIs to retrieve detailed information.
parameters:
# common header parameters that set context
- $ref: "#/components/parameters/aspspId"
- $ref: "#/components/parameters/callerOrgId"
- $ref: "#/components/parameters/callerClientId"
- $ref: "#/components/parameters/callerSoftwareStatementId"
- $ref: "#/components/parameters/apiUri"
- $ref: "#/components/parameters/apiOperation"
- $ref: "#/components/parameters/consentId"
- $ref: "#/components/parameters/callerInteractionId"
- $ref: "#/components/parameters/ozoneInteractionId"
- $ref: "#/components/parameters/psuIdentifier"
responses:
200:
description: successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentDetailsResponse"
400:
description: failed operation
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
components:
schemas:
PaymentConsentValidateRequest:
type: object
oneOf:
- $ref: "#/components/schemas/ConsentGetResponse"
ConsentGetResponse:
type: object
description: |
A consent in its current state.
If the consent has been authorised, then it can be expected that the LFI
would have patched in `accountIds` and `psuIdentifier` fields.
Additionally, the LFI may also patch in an arbitrary set of fields along with consent
in the `supplementaryInformation` field.
properties:
id:
type: string
description: |
A unique identifier for the consent in uuid-v4 format.
This is distinct from the ConsentId that is communicated back to PSUs and TPPs.
consentType:
$ref: "#/components/schemas/ConsentType"
request:
$ref: "#/components/schemas/Request"
requestHeaders:
$ref: "#/components/schemas/RequestHeaders"
consentBody:
$ref: "#/components/schemas/ConsentBody"
tpp:
$ref: "#/components/schemas/TPP"
psuIdentifiers:
$ref: "#/components/schemas/PSUIdentifiers"
accountIds:
$ref: "#/components/schemas/AccountIds"
required:
- id
- consentType
- request
- requestHeaders
- tpp
additionalProperties: false
ConsentType:
type: string
description: |
The type of the consent that is being created.
Each LFI's instance may support a different set of consent types
The Consent Manager supports the creation of consents of different consent types
depending on the standards supported.
For example, for the UK OBIE standards, the following consent types are available:
- account-access-consents
- domestic-payment-consents
- future-dated-payment-consents
- standing-order-consents
- international-payment-consents
- international-future-dated-payment-consents
- international-standing-order-consents
Request:
type: object
description: |
The entire HTTP request body that was received by Ozone from the TPP.
The type can be used to identify the schema
that should be used to validate the request. (These schemas are defined by the
underlying standard)
additionalProperties: true
RequestHeaders:
type: object
description: |
The entire set of HTTP request headers that was received by Ozone from the TPP
additionalProperties: true
ConsentBody:
type: object
description: |
An object representing the current state of the consent.
This includes the entire request, augmented by additional computed properties
(e.g. ids, charges etc)
The Ozone Consent Manager caters to consents from various standards. The actual schema
for each consentBody would be determined by the underlying standard.
oneOf:
- $ref: "#/components/schemas/OBIEConsentBody"
OBIEConsentBody:
type: object
description: |
A representation of a consent body for a consent from the OBIE RW-API standards.
It should be noted that the entire content payload (not just the fields listed below) is stored.
The list of fields below identifies the common fields across all OBIE consents.
properties:
Data:
type: object
properties:
ConsentId:
type: string
description: |
A ConsentId generated by the LFI for the consent.
This is different from the top-level `id` field which is used by Consent Manager.
CreationDateTime:
type: string
format: date-time
description: An ISO date-time representing when the consent was created
Status:
$ref: "#/components/schemas/ConsentStatusEnum"
StatusUpdateDateTime:
type: string
format: date-time
description: An ISO date-time representing when the consent status was last updated
required:
- ConsentId
- CreationDateTime
- Status
- StatusUpdateDateTime
additionalProperties: true
required:
- Data
additionalProperties: true
ConsentStatusEnum:
type: string
enum:
- AwaitingAuthorisation
- Authorised
- Consumed
- Rejected
- Revoked
description: The current status of the consent
TPP:
type: object
description: |
The TPP record as held by Ozone.
If Ozone TPP Connect has been integrated into a directory, the `directoryRecord`
provides the TPP's directory record as held by Ozone.
properties:
clientId:
type: string
orgId:
type: string
softwareStatementId:
type: string
directoryRecord:
additionalProperties: true
PSUIdentifiers:
type: object
description: |
The PSU that is associated with this consent.
The `PSUIdentifiers` object may have artitrary custom fields that an LFI may use to
identify the PSU.
However, all `PSUIdentifiers` must have a mandatory `userId` field that provides a unique
user id for the PSU.
The consent is initially created without a PSU identified.
The value must be specified once the consent is authorised.
properties:
userId:
type: string
required:
- userId
additionalProperties: true
SupplementaryInformation:
type: object
description: |
The `SupplementaryInformation` object may have artitrary custom fields that an LFI may use
additionalProperties: true
AccountIds:
type: array
items:
type: string
minItems: 1
description: |-
An array of account ids associated with the consent. The array must be populated once consent has been authorised.
For payment consents, the array must always have one element - the debtor account from which the payment will be made
For CBPII consents, the array must always have one element - the account for which CoF requests will be answered
For AIS requests, the array may contain multiple values, representing each of the payment accounts for which an AIS service will be provided.
PaymentConsentValidateResponse:
type: object
properties:
data:
type: object
properties:
status:
$ref: "#/components/schemas/ValidateResponseStatusEnum"
code:
type: string
description:
type: string
meta:
$ref: "#/components/schemas/Meta"
ValidateResponseStatusEnum:
type: string
enum:
- valid
- invalid
PaymentRequest:
type: object
properties:
requestUrl:
type: string
description: |
The (Ozone) URL at which the TPP requested for the payment
paymentType:
$ref: "#/components/schemas/PaymentType"
request:
$ref: "#/components/schemas/Request"
requestHeaders:
$ref: "#/components/schemas/RequestHeaders"
tpp:
$ref: "#/components/schemas/TPP"
supplementaryInformation:
$ref: "#/components/schemas/SupplementaryInformation"
required:
- paymentType
- request
- requestHeaders
- tpp
additionalProperties: false
PaymentType:
type: string
description: |
The type of the payment that is being created.
Each LFI's instance may support a different set of payment types
depending on the standards supported.
For example,
For the UK OBIE standards, the following payment types are available:
- domestic-payment
- domestic-scheduled-payment
- domestic-standing-order
- domestic-vrp
- file-payment
- international-payment
- international-scheduled-payments
- international-standing-order
PaymentResponse:
type: object
properties:
data:
$ref: "#/components/schemas/Payment"
meta:
$ref: "#/components/schemas/Meta"
PaymentGetResponse:
type: object
properties:
data:
$ref: "#/components/schemas/GetPayment"
meta:
$ref: "#/components/schemas/Meta"
Payment:
type: object
description: |
A descriptor for a Payment.
This is a composite object that may be expanded in the future to support
additional payment types for new API standards and payment types.
oneOf:
- $ref: "#/components/schemas/GenericPaymentResponse"
GetPayment:
type: object
description: |
A descriptor for a Payment.
This is a composite object that may be expanded in the future to support
additional payment types for new API standards and payment types.
oneOf:
- $ref: "#/components/schemas/GenericGetPaymentResponse"
GenericPaymentResponse:
type: object
properties:
id:
type: string
endToEndId:
type: string
rejectionReason:
$ref: '#/components/schemas/RejectionReason'
status:
$ref: "#/components/schemas/PaymentStatusEnum"
creationDateTime:
type: string
format: date-time
statusUpdateDateTime:
type: string
format: date-time
refundAccount:
$ref: "#/components/schemas/RefundAccount"
transactionId:
description: This is mandatory for KSA.
type: string
charges:
$ref: "#/components/schemas/Charges"
instruction:
type: object
description: The current status of the payment. This is mandatory for KSA. The data will be passed without any validations.
oneOf:
- $ref: "#/components/schemas/KSAOBRefundInitiationInstructionResponse"
- $ref: "#/components/schemas/KSAOBRequestToPayInitiationInstructionResponse"
transactionType:
$ref: "#/components/schemas/TransactionType"
debtorAgentStatus:
$ref: "#/components/schemas/DebtorAgentStatus"
creditorAgentStatus:
$ref: "#/components/schemas/CreditorAgentStatus"
required:
- id
- status
- creationDateTime
- statusUpdateDateTime
additionalProperties: false
GenericGetPaymentResponse:
type: object
properties:
id:
type: string
endToEndId:
type: string
rejectionReason:
$ref: '#/components/schemas/RejectionReason'
status:
$ref: "#/components/schemas/PaymentStatusEnum"
creationDateTime:
type: string
format: date-time
statusUpdateDateTime:
type: string
format: date-time
paymentTransactionId:
type: string
paymentStatusDetails:
$ref: "#/components/schemas/PaymentStatusDetail"
transactionId:
type: string
description: This is mandatory for KSA.
charges:
$ref: "#/components/schemas/Charges"
instruction:
type: object
description: The current status of the payment. This is mandatory for KSA. The data will be passed without any validations.
oneOf:
- $ref: "#/components/schemas/KSAOBRefundInitiationInstructionResponse"
- $ref: "#/components/schemas/KSAOBRequestToPayInitiationInstructionResponse"
transactionType:
$ref: '#/components/schemas/TransactionType'
debtorAgentStatus:
$ref: '#/components/schemas/DebtorAgentStatus'
creditorAgentStatus:
$ref: '#/components/schemas/CreditorAgentStatus'
required:
- id
- status
- creationDateTime
- statusUpdateDateTime
additionalProperties: false
RefundAccount:
type: object
required:
- schemeName
- identification
properties:
schemeName:
type: string
identification:
type: string
name:
type: string
secondaryIdentification:
type: string
PaymentDetails:
type: object
properties:
id:
type: string
status:
$ref: "#/components/schemas/PaymentStatusEnum"
statusUpdateDateTime:
type: string
format: date-time
statusDetails:
type: array
items:
$ref: "#/components/schemas/PaymentStatusDetails"
required:
- id
- status
- statusUpdateDateTime
PaymentStatusDetails:
type: object
properties:
localInstrument:
type: string
status:
$ref: "#/components/schemas/PaymentStatusEnum"
statusReason:
type: string
statusReasonDescription:
type: string
required:
- status
additionalProperties: false
PaymentStatusEnum:
type: string
enum:
- Pending
- Rejected
- AcceptedSettlementInProcess
- AcceptedSettlementCompleted
- AcceptedWithoutPosting
- AcceptedCreditSettlementCompleted
RejectionReason:
type: object
properties:
code:
type: string
description: code that identifies the error
detail:
type: string
description: message detail with information about the error
PaymentDetailsResponse:
type: object
properties:
data:
type: array
items:
$ref: "#/components/schemas/PaymentDetails"
meta:
$ref: "#/components/schemas/Meta"
PaymentStatusDetail:
title: "PaymentStatusDetail"
description: |
This attribute SHOULD only be returned when the resource Status represents a failed state e.g. : Rejected. Only applicable for KSA
type: "object"
required:
- "reason"
properties:
reason:
type: "object"
description: |
A Placeholder for any responses that support a Status
required:
- "code"
properties:
code:
type: string
description: |
The reason code that represents the downstream System Error.
**Payments**
|Status|Reason Code|Description|
|----------|--|--|
|Rejected|KSAOB.Originator.InsufficientFunds|The PASP Debtor Account does not have sufficient funds to complete the payment|
|Rejected|KSAOB.Originator.AccountIssue|The Originator Account has an issue in sending the payment e.g. Account is inactive, locked, dormant|
|Rejected|KSAOB.Receiver.AccountIssue|The Receiver Account has an issue in receiving the payment e.g. Account is inactive, locked, dormant|
|Rejected|KSAOB.Originator.TransactionNotPermitted|The Originator Account is not permitted to perform the requested transaction|
|Rejected|KSAOB.Originator.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
|Rejected|KSAOB.Receiver.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
|Rejected|KSAOB.Receiver.Timeout |A timeout has occurred on the payment rails|
|Rejected|KSAOB.Receiver.SystemUnavailable|The payment rails or downstream system is unavailable|
|Rejected|KSAOB.Originator.Other|Any other reason not specified and applicable to the Originator; details MUST be provided in the Detail field|
|Rejected|KSAOB.Receiver.Other|Any other reason not specified and applicable to the Receiver; details MUST be provided in the Detail field|
|Rejected|KSAOB.Originator.SuspectedFraud|The Originator Account has been suspended due to suspected fraud|
|Rejected|KSAOB.Receiver.SuspectedFraud|The Receiver Account has been suspended due to suspected fraud|
enum:
- "KSAOB.Originator.InsufficientFunds"
- "KSAOB.Originator.AccountIssue"
- "KSAOB.Receiver.AccountIssue"
- "KSAOB.Originator.TransactionNotPermitted"
- "KSAOB.Originator.DuplicateTransaction"
- "KSAOB.Receiver.DuplicateTransaction"
- "KSAOB.Receiver.Timeout"
- "KSAOB.Receiver.SystemUnavailable"
- "KSAOB.Originator.Other"
- "KSAOB.Receiver.Other"
- "KSAOB.Originator.SuspectedFraud"
- "KSAOB.Receiver.SuspectedFraud"
detail:
type: "string"
description: "Further details that are specific to the Reason Code"
additionalProperties: false
message:
$ref: "#/components/schemas/Message"
additionalProperties: false
Charges:
title: "Charges"
type: "array"
description: |
Applicable only for KSA
items:
type: "object"
additionalProperties: false
description: |
Set of elements used to provide details of a charge for the payment initiation.
* For Payments, these Charges are on the Payer.
required:
- "Type"
- "Amount"
properties:
Type:
$ref: "#/components/schemas/ExternalPaymentChargeTypeCode"
Amount:
$ref: "#/components/schemas/ActiveCurrencyAmount"
TransactionType:
type: string
minLength: 5
maxLength: 6
enum:
- OFF-US
- ON-US
example: OFF-US
DebtorAgentStatus:
type: string
minLength: 4
maxLength: 4
example: RJCT
CreditorAgentStatus:
type: string
minLength: 4
maxLength: 4
example: ACCP
KSAOBRequestToPayInitiationInstructionResponse:
title: "KSAOBRequestToPayInitiationInstructionResponse"
description: |
(Array) of Single or Multiple Request To Pay Instructions
* Please refer to the Business Rules, PIS Limits and Constants, Maximum RTPs per Message for the limit.
type: "array"
minItems: 1
maxItems: 10
items:
allOf:
- type: "object"
required:
- "RequestToPayStatus"
- "RequestToPayStatusUpdateDateTime"
- "CreationDateTime"
- "Amount"
- "RequestToPayPurposeCode"
- "RequestToPayTransactionId"
- "DebtorAccount"
properties:
RequestToPayTransactionId:
$ref: "#/components/schemas/OBRequestToPayTransactionId"
Amount:
$ref: "#/components/schemas/OBActiveCurrencyAmount"
RequestToPayStatus:
$ref: "#/components/schemas/OBRequestToPayStatus"
RequestToPayStatusUpdateDateTime:
$ref: "#/components/schemas/OBStatusUpdateDateTime"
RequestToPayStatusDetail:
$ref: "#/components/schemas/OBRequestToPayStatusDetail"
IsPendingCancellation:
$ref: "#/components/schemas/OBPendingCancellation"
CreationDateTime:
$ref: "#/components/schemas/OBCreationDateTime"
Charges:
$ref: "#/components/schemas/Charges"
DebtorAgent:
$ref: "#/components/schemas/OBCreditorAgent"
DebtorAccount:
$ref: "#/components/schemas/OBDebtorAccount"
RequestToPayPurposeCode:
$ref: "#/components/schemas/OBPaymentPurposeCode"
NoteToPayer:
$ref: "#/components/schemas/OBRTPPayerNote"
RequestToPayExpiryWindow:
$ref: "#/components/schemas/OBRTPExpiryWindow"
additionalProperties: false
OBRTPExpiryWindow:
title: "OBRTPExpiryWindow"
type: "string"
description: |
Specifies the Requests to Pay Expiration Window.
The time window is based on a custom time format hhh:mm:ss. e.g. 720:00:00 represents a time window of 720 hours, 00 minutes, 00 seconds (30 days).
* Please refer to the Business Rules, PIS Limits and Constants, RTP Expiry Window for the limit.
pattern: '^(00[0-9]|0[1-9][0-9]|[1-6][0-9]{2}|7[01][0-9]|720):[0-5][0-9]:[0-5][0-9]$'
example: "48:00:00"
OBRTPPayerNote:
title: "OBRTPPayerNote"
type: "string"
description: |
Notes for the Payer
minLength: 1
maxLength: 256
OBDebtorAccount:
title: "OBDebtorAccount"
description: "Unambiguous identification of the account of the debtor to which a debit entry will be made."
type: "object"
required:
- "IdentificationType"
- "Identification"
- "Name"
properties:
IdentificationType:
$ref: "#/components/schemas/OBExternalAccountIdentificationCode"
Identification:
$ref: "#/components/schemas/OBIdentification"
Name:
$ref: "#/components/schemas/OBName"
OBName:
title: "OBName"
type: "object"
description: |
The Account Holder Name is the name or names of the Account owner(s) represented at the account level
properties:
en:
type: "string"
description: "English value of the string"
ar:
type: "string"
description: "Arabic value of the string"
additionalProperties: false
OBIdentification:
title: "OBIdentification"
description: |
Identification for the account assigned by the PASP based on the Account Scheme Name.
This identification is known by the PSU account owner.
type: "string"
minLength: 1
OBExternalAccountIdentificationCode:
title: "OBExternalAccountIdentificationCode"
description: "Name of the identification scheme, in a coded form as published in an external list."
type: "string"
enum:
- "KSAOB.IBAN"
- "KSAOB.AccountNumber"
- "KSAOB.UnifiedCommercialNumber"
- "KSAOB.Email"
- "KSAOB.MobileNumber"
- "KSAOB.NationalID"
- "KSAOB.IqamaNumber"
OBCreditorAgent:
title: "OBCreditorAgent"
description: |
Refers to the Financial Institution.
type: "object"
required:
- "IdentificationType"
- "Identification"
properties:
IdentificationType:
type: "string"
description: |
Refers to the Identification scheme for uniquely identifying the Agent.
* KSAOB.OTHER: The ID; A Country Code followed by a Bank Code (KSAOB 4 character code). The full list of PASP names and 6 digits IDs are as follows:
enum:
- "KSAOB.OTHER"
Identification:
description: |
The Agent is the Country Code followed by a Bank Code (KSAOB 4 character code). The full list of PASP names and 6 digits IDs are as follows"
| PASP NAME|ID|
|----------|--|
|ALINMA BANK|SAINMA|
|AL RAJHI BANK|SARJHI|
|ARAB NATIONAL BANK|SAARNB|
|BANK AL BILAD|SAALBI|
|BANK AL-JAZIRA|SABJAZ|
|BANK MUSCAT|SABMUS|
|BANQUE SAUDI FRANSI|SABSFR|
|BNP PARIBAS SAUDI ARABIA|SABNPA|
|CREDIT SUISSE SAUDI ARABIA|SACRES|
|DEUTSCHE BANK AG, RIYADH BRANCH|SADEUT|
|EMIRATES NBD PJSC|SAEBIL|
|FIRST ABU DHABI BANK|SAFABM|
|GULF INTERNATIONAL BANK B.S.C., RIYADH|SAGULF|
|INDUSTRIAL AND COMMERCIAL BANK OF CHINA RIYADH BRANCH, SA|SAICBK|
|ISLAMIC DEVELOPMENT BANK|SAISLD|
|J.P.MORGAN SAUDI ARABIA LIMITED|SAJPMG|
|J.P MORGAN CHASE BANK, N.A RIYADH|SACHAS|
|MERILL LYNCH KINGDOM OF SAUDIA ARABIA|SAMLSA|
|NATIONAL BANK OF BAHRAIN|SANBOB|
|NATIONAL BANK OF KUWAIT|SANBOK|
|NATIONAL BANK OF PAKISTAN|SANBPA|
|NEOLEAP|SANEOL|
|RIYAD BANK|SARIBL|
|SAUDI NATIONAL BANK|SANCBK|
|SAUDI ARABIAN MONETARY AUTHORITY|SASAMA|
|SAUDI BRITISH BANK|SASABB|
|SAUDI INVESTMENT BANK|SASIBC|
|STANDARD CHARTERED CAPITAL (SAUDI ARABIA)|SASCBL|
|STC PAY|SASTCP|
|STC Bank|SASTCJ|
|T.C. ZIRAAT BANKASI A.S|SATCZB|
type: "string"
enum:
- "SAINMA"
- "SARJHI"
- "SAALBI"
- "SABJAZ"
- "SABMUS"
- "SABSFR"
- "SABNPA"
- "SACRES"
- "SADEUT"
- "SAEBIL"
- "SAGULF"
- "SAICBK"
- "SAISLD"
- "SAJPMG"
- "SACHAS"
- "SAMLSA"
- "SANBOB"
- "SANBOK"
- "SANBPA"
- "SANCBK"
- "SARIBL"
- "SASAMA"
- "SASABB"
- "SASIBC"
- "SASCBL"
- "SATCZB"
- "SASTCP"
- "SANEOL"
- "SASTCJ"
- "SAFABM"
minLength: 6
maxLength: 6
example: SASAMA
OBRequestToPayTransactionId:
title: "OBRequestToPayTransactionId"
type: "string"
description: |
The TransactionId associated with a payment generated from the Payment Rails.
example: "oz2c8wpre1vy34tx7q"
OBRequestToPayTypeResponse:
type: "string"
description: |
The type of Request To Pay being instructed which must match against the Request To Pay Type(s) set under the Consent Schedule
enum:
- KSAOB.SingleRequestToPay
- KSAOB.LongLivedRequestToPay
OBPendingCancellation:
type: boolean
description: |
This boolean flag is only set to True when:
* The PISP initiates an RTP Cancellation with the PASP
* The current RTP Status is: Pending
OBRequestToPayStatus:
title: "OBRequestToPayStatus"
description: |
Specifies the status of the Request To Pay information group
* Initiated: The Request To Pay has been received by the Receiving PASP but not delivered to Payer.
* Pending: The Request To Pay is pending a response from the Payer.
* Cancelled: The Request To Pay Cancellation request has been accepted by the Receiving PASP.
* Accepted: The Request To Pay has been accepted by the Payer.
* Expired: The Request to Pay has expired due to no action from the Payer.
* Paid: The Payer has fulfilled and paid the Request To Pay.
* Rejected: The Payer has rejected the Request To Pay.
* Failed: The Request to Pay has failed (either from the Originating PASP or Receiving PASP).
* NotSubmitted: The Sender cancels the Request To Pay before submitting it to the Payer.
type: "string"
enum:
- "Initiated"
- "Pending"
- "Cancelled"
- "Accepted"
- "Expired"
- "Paid"
- "Rejected"
- "Failed"
- "NotSubmitted"
example: Initiated
KSAOBRefundInitiationInstructionResponse:
title: "KSAOBRefundInitiationInstruction"
description: |
(Array) of Refund Instructions
* Please refer to the Business Rules, PIS Limits and Constants, Maximum Refunds per Message for the limit.
type: "array"
minItems: 1
maxItems: 500
items:
required:
- "RefundStatus"
- "RefundStatusUpdateDateTime"
- "Type"
- "CreationDateTime"
- "OriginalPayment"
- "Amount"
properties:
Amount:
$ref: "#/components/schemas/OBActiveCurrencyAmount"
OriginalPayment:
$ref: "#/components/schemas/OBSingleRefundPayment"
RefundPurposeCode:
$ref: "#/components/schemas/OBPaymentPurposeCode"
RefundStatus:
$ref: "#/components/schemas/OBRefundStatus"
RefundStatusUpdateDateTime:
$ref: "#/components/schemas/OBStatusUpdateDateTime"
RefundStatusDetail:
$ref: "#/components/schemas/OBRefundStatusDetail"
CreationDateTime:
$ref: "#/components/schemas/OBCreationDateTime"
Charges:
$ref: "#/components/schemas/Charges"
additionalProperties: false
OBCreationDateTime:
title: "OBCreationDateTime"
description: "Date and time at which the message was created. All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2023-04-05T10:43:07+00:00"
type: "string"
format: "date-time"
OBStatusUpdateDateTime:
title: "OBStatusUpdateDateTime"
description: "Date and time at which the resource status was updated.All dates in the JSON payloads are represented in ISO 8601 date-time format. \nAll date-time fields in responses must include the timezone. An example is below:\n2023-04-05T10:43:07+00:00"
type: "string"
format: "date-time"
OBRefundStatusDetail:
title: "OBRefundStatusDetail"
description: |
This attribute SHOULD only be returned when the resource Status represents a failed state e.g. : Rejected.
type: "object"
required:
- "Reason"
properties:
Reason:
type: "object"
description: |
A Placeholder for any responses that support a Status
required:
- "Code"
properties:
Code:
type: string
description: |
The reason code that represents the downstream System Error.
**Refunds**
|Status|Reason Code|Description|
|----------|--|--|
|Rejected|KSAOB.Originator.InsufficientFunds|The PASP Debtor Account does not have sufficient funds to complete the refund|
|Rejected|KSAOB.Originator.AccountIssue|The Originator Account has an issue in sending the refund e.g. Account is inactive, locked, dormant|
|Rejected|KSAOB.Receiver.AccountIssue|The Receiver Account has an issue in receiving the refund e.g. Account is inactive, locked, dormant|
|Rejected|KSAOB.Originator.TransactionNotPermitted|The Originator Account is not permitted to perform the requested transaction|
|Rejected|KSAOB.Originator.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
|Rejected|KSAOB.Receiver.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
|Rejected|KSAOB.Receiver.Timeout |A timeout has occurred on the payment rails|
|Rejected|KSAOB.Receiver.SystemUnavailable|The payment rails or downstream system is unavailable|
|Rejected|KSAOB.Originator.Other|Any other reason not specified and applicable to the Originator; details MUST be provided in the Detail field|
|Rejected|KSAOB.Receiver.Other|Any other reason not specified and applicable to the Receiver; details MUST be provided in the Detail field|
enum:
- "KSAOB.Originator.InsufficientFunds"
- "KSAOB.Originator.AccountIssue"
- "KSAOB.Receiver.AccountIssue"
- "KSAOB.Originator.TransactionNotPermitted"
- "KSAOB.Originator.DuplicateTransaction"
- "KSAOB.Receiver.DuplicateTransaction"
- "KSAOB.Receiver.Timeout"
- "KSAOB.Receiver.SystemUnavailable"
- "KSAOB.Originator.Other"
- "KSAOB.Receiver.Other"
Detail:
type: "string"
description: "Further details that are specific to the Reason Code"
additionalProperties: false
Message:
$ref: "#/components/schemas/OBMessage"
additionalProperties: false
OBMessage:
title: "OBMessage"
description: "A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDateTime must be in future'\nKSAOB doesn't standardise this field"
type: "object"
required:
- "en"
properties:
en:
type: "string"
description: "English value of the string"
minLength: 1
maxLength: 500
ar:
type: "string"
description: "Arabic value of the string"
minLength: 1
maxLength: 500
additionalProperties: false
OBRequestToPayStatusDetail:
title: "OBRequestToPayStatusDetail"
description: |
This attribute SHOULD only be returned when the resource Status represents a failed state e.g. : Rejected, Failed, Cancelled, Expired.
type: "object"
required:
- "Reason"
properties:
Reason:
type: "object"
description: |
A Placeholder for any responses that support a Status
required:
- "Code"
properties:
Code:
type: string
description: |
The reason code that represents the downstream System Error.
**Requests To Pay (RTP)**
|Status|Reason Code|Description|
|----------|--|--|
|Failed|KSAOB.Originator.AccountIssue|The Originator Account has an issue in processing the RTP request e.g. Account is inactive, locked, dormant|
|Failed|KSAOB.Receiver.AccountIssue|The Receiver Account has an issue in processing the RTP request e.g. Account is inactive, locked, dorman|
|Rejected|KSAOB.Originator.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
|Rejected|KSAOB.Receiver.DuplicateTransaction|The requested transaction is a duplicate of a previous successfully processed transaction|
|Failed|KSAOB.Receiver.Timeout|A timeout has occurred on the payment rails|
|Failed|KSAOB.Receiver.SystemUnavailable|The payment rails or downstream system is unavailable|
|Failed|KSAOB.Originator.SystemUnavailable|The payment rails or downstream system is unavailable|
|Failed, Cancelled|KSAOB.Originator.Other|Any other reason not specified and applicable to the Originator; details MUST be provided in the Detail field|
|Rejected, Failed, Cancelled|KSAOB.Receiver.Other|Any other reason not specified and applicable to the Receiver; details MUST be provided in the Detail field|
|Cancelled|KSAOB.Receiver.CancellationAccepted|The cancellation request has been accepted by the Receiver|
|Expired|KSAOB.Originator.Expired|The Originator requested window for an RTP response has expired|
|Failed|KSAOB.Originator.CancelledBeforeSubmission|The Originator PASP has not submitted the RTP request to the Receiver PASP due to invalid information|
enum:
- "KSAOB.Originator.AccountIssue"
- "KSAOB.Receiver.AccountIssue"
- "KSAOB.Originator.DuplicateTransaction"
- "KSAOB.Receiver.DuplicateTransaction"
- "KSAOB.Receiver.Timeout"
- "KSAOB.Receiver.SystemUnavailable"
- "KSAOB.Originator.SystemUnavailable"
- "KSAOB.Originator.Other"
- "KSAOB.Receiver.Other"
- "KSAOB.Receiver.CancellationAccepted"
- "KSAOB.Originator.Expired"
- "KSAOB.Originator.CancelledBeforeSubmission"
Detail:
type: "string"
description: "Further details that are specific to the Reason Code"
additionalProperties: false
Message:
$ref: "#/components/schemas/OBMessage"
additionalProperties: false
OBRefundStatus:
title: "OBRefundStatus"
description: |
Specifies the status of the Refund information group
* Pending: Refund initiation or individual transaction included in the Refund initiation is pending. Further checks and status update will be performed.
* Rejected: The Refund initiation has been rejected
* AcceptedSettlementCompleted: Settlement of the Debtors account has been completed
* AcceptedCreditSettlementCompleted: When the Payee account has been credited with the funds of the Refund initiated via the PISP
* AcceptedWithoutPosting: When the Recipient Bank has accepted the Refund but has not applied the credit to the Payee account yet.
type: "string"
enum:
- "Pending"
- "AcceptedSettlementCompleted"
- "AcceptedCreditSettlementCompleted"
- "AcceptedWithoutPosting"
- "Rejected"
example: Pending
OBPaymentPurposeCode:
title: "OBPaymentPurposeCode:"
description: |
A Category code, related to the type of services or goods that corresponds to the underlying purpose of the Payment, Refund, RTP.
The Purpose Codes can be based on either:
* The SARIE IPS Message Implementation Guide - Section 21.4 - Category Purpose Codes
* The ISO20022 External code sets
type: "string"
minLength: 1
maxLength: 4
pattern: "^[A-Z]{3,4}$"
OBSingleRefundPayment:
title: "OBSingleRefundPayment"
type: "object"
description: |
Placeholder for single payment Refund Data.
required:
- "Amount"
- "Date"
- "PaymentTransactionId"
properties:
Amount:
$ref: "#/components/schemas/ActiveCurrencyAmount"
Date:
description: |
Date of the Original Payment
type: "string"
format: "date"
PaymentTransactionId:
$ref: "#/components/schemas/OBPaymentTransactionId"
additionalProperties: false
OBPaymentTransactionId:
title: "OBPaymentTransactionId"
type: "string"
description: |
This is an end to end TransactionId that is associated with a payment when it is sent from an Originating PASP to a Receiving PASP.
This identifier is also used for Refunds.
This applies to:
* Same Bank Transfer (Within the same bank)
* Local Bank Transfer (Between 2 banks)
**IPS**
Transaction Identification field (2.4) as defined in the Payment Identification block (2.1) of the Credit Transfer pacs.008 message
(e.g) 20201122SAABCD00002BXXX20730997766
**ON-US**
MUST prefix with a 6 digit bank codes (as per the OBCreditorAgent schema):
SA + 4 char code. (e.g. SASAMA)
minimum: 1
maximum: 35
ExternalPaymentChargeTypeCode:
title: "OBExternalPaymentChargeTypeCode"
description: "Charge type, in a coded form."
type: "string"
enum:
- "VAT"
- "Fees"
OBActiveCurrencyAmount:
title: "ActiveCurrencyAmount"
description: |
The Currency and Amount relating to the Payment, Refund or Request to Pay
type: "object"
required:
- "Amount"
- "Currency"
properties:
Amount:
$ref: "#/components/schemas/ActiveOrHistoricAmount"
Currency:
$ref: "#/components/schemas/ActiveOrHistoricCurrencyCode"
ActiveCurrencyAmount:
title: "ActiveCurrencyAmount"
description: |
The Currency and Amount relating to the Payment, Refund or Request to Pay
type: "object"
required:
- "amount"
- "currency"
properties:
amount:
$ref: "#/components/schemas/ActiveOrHistoricAmount"
currency:
$ref: "#/components/schemas/ActiveOrHistoricCurrencyCode"
ActiveOrHistoricAmount:
title: "ActiveOrHistoricAmount"
description: "A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217."
type: "string"
pattern: "^\\d{1,16}\\.\\d{2}$"
example: "100.00"
ActiveOrHistoricCurrencyCode:
title: "ActiveOrHistoricCurrencyCode"
description: "A 3 character alphabetic code allocated to a currency under an international currency identification scheme, as described in the latest edition of the international standard ISO 4217 'Codes for the representation of currencies and funds'."
type: "string"
pattern: "^[A-Z]{3,3}$"
example: "SAR"
Message:
title: "Message"
description: "A description of the error that occurred. e.g., 'A mandatory field isn't supplied' or 'RequestedExecutionDateTime must be in future'\nKSAOB doesn't standardise this field"
type: "object"
required:
- "en"
properties:
en:
type: "string"
description: "English value of the string"
minLength: 1
maxLength: 500
ar:
type: "string"
description: "Arabic value of the string"
minLength: 1
maxLength: 500
additionalProperties: false
#
# Common types
#
Meta:
type: object
additionalProperties: false
Error:
type: object
properties:
errorCode:
type: string
description: Error code identifying the problem occured
errorMessage:
type: string
description: Message describing what problem has occured
parameters:
aspspId:
name: o3-aspsp-id
in: header
schema:
type: string
required: true
description: Identifier for the LFI that the request is targetted to
callerOrgId:
name: o3-caller-org-id
in: header
schema:
type: string
required: false
description: An identifier for the organization calling the API
callerClientId:
name: o3-caller-client-id
in: header
schema:
type: string
required: false
description: An identifier for the OIDC clientId calling the API
callerSoftwareStatementId:
name: o3-caller-software-statement-id
in: header
schema:
type: string
required: false
description: An identifier for the software statement calling the API
apiUri:
name: o3-api-uri
in: header
schema:
type: string
required: true
description: The parameterised URL of the API being called by the caller
apiOperation:
name: o3-api-operation
in: header
schema:
type: string
required: true
description: The API operation carried out by the caller (e.g. GET, POST, PUT, DELETE, PATCH)
consentId:
name: o3-consent-id
in: header
schema:
type: string
required: false
description: The consentId for which this call is being made
callerInteractionId:
name: o3-caller-interaction-id
in: header
schema:
type: string
required: false
description: The interaction ID passed in by the caller, if any
ozoneInteractionId:
name: o3-ozone-interaction-id
in: header
schema:
type: string
required: true
description: An interaction ID generated by Ozone if the caller did not send in one. If the callerInteractionId is specified, this takes the same value.
psuIdentifier:
name: o3-psu-identifier
in: header
schema:
type: string
required: false
description: A Base64 encoded representation of the psuIdentifier JSON object.
pageNumber:
name: page
in: query
schema:
type: string
required: false
description: Page number to be returned
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
|
