openapi: 3.0.1
servers:
- url: https://{your-cm-server}/v2024.07
description: OzoneConsent Connect - Service Initiation APIs
variables:
server:
default: rs1.*
description: The server that the API is hosted on.manager for the tenant
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 a anFinancial LFIInstitution so that Ozone
can deliver Service Initiation capabilities to TPPs
version:#### VersionComing 2.2soon
Release 2022.39.1 tags: The following -changes name:can paymentsbe expected in the next descriptionrelease:
| - some enumeration APIsand thatobject shoulddefinitions beremain implementedto bybe LFIsaligned towith exposeCBUAE Servicespecifications. InitiationThese capabilitywill tobe TPPs.updated
paths: /payment-consent/action/validate: specific changes expected in post:the next release have been marked tags:
as ***TODO*** in the document
- paymentsreview support for `SupplementaryInformation` field and remove summary:if Paymentrequired
action
validation contact:
descriptionname: |Ozone Financial Technology Limited
version: Release The2024.31
API
istags:
called by Ozone- toname: allowpayments
an LFI to carry outdescription: additional|
validations APIs that should beforebe aimplemented paymentby consentFinancial isInstitutions created.to expose Service Initiation capability to TPPs.
paths:
The request/payments:
body contains the entire paymentpost:
consent along with contextual information. tags:
Typically this- couldpayments
be used for situations like: summary: Make a payment
- soft validation ofdescription: the|
debtor account (e.g. to ensure that it is aThis debtorAPI accountis managedcalled by theOzone LFI)Connect to instruct a Financial Institution to initiate a -payment populatingonce chargesit andhas exchangereceived ratea informationpayment
(in future versions) instruction from a NoteTPP that anhas LFIpassed onlyall needlocal tovalidations.
implement
this API where it needs to correlate information inThe theFinancial consentInstitution payloadmust process the payment and indicate a failure response with(if datathe heldpayment infails itstechnical systems.validation) Ifor thisa
is not the case, "local" validations can be configuredsuccess inresponse Ozone(if thatthe dopayment notpassess technical validation and is submitted to the payment requirerails afor remoteprocessing)
call.
The TheFinancial LFIInstitution must returngenerate a `PaymentConsentValidateResponse`unique which`PaymentId` includesthat acan status.be If the status is setsent on to `valid`, the TPP as a reference for consent is saved and processing continuesthe payment.
If the statusunderlying isconsent sethas tobeen `invalid`patched thewith processinga fails`bankConnectToken`, andthen anthe errortoken responseis ispassed sentin toas the authorization TPPheader.
operationId: validatePaymentConsent
makePayment
parameters:
# common header parameters that set context
- $ref: "#/components/parameters/providerId"
- $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/PaymentConsentValidateRequestPaymentPostRequest"
responses:
200'201':
description: successful operation
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentConsentValidateResponsePaymentPostResponse"
'400':
description: failed operation
content:
application/json:
schema:
$ref: "#/components/schemas/Error"
/payments: postsecurity:
tags: - bearerAuth: []
/payments/:paymentId:
- payments get:
summary: Make aoperationId: paymentgetPayment
descriptiontags:
| - Thispayments
API is called by Ozone Connect tosummary: instructGet ana LFIpayment
to initiate a payment once it hasdescription: received|
a payment Ozone can instructioncall fromthis aAPI TPPfrom thatFinancial hasInstitutions passedto allretrieve localpayment validationsinformation.
parameters:
The LFI must process the payment and# indicatecommon aheader failureparameters responsethat (ifset thecontext
payment fails technical validation) or a - $ref: "#/components/parameters/providerId"
success response (if the payment passess- technical validation and is submitted to the payment rails for processing)
$ref: "#/components/parameters/aspspId"
- $ref: "#/components/parameters/callerOrgId"
The LFI- must generate a unique `PaymentId` that can be sent on to the TPP as a reference for the payment.
$ref: "#/components/parameters/callerClientId"
- $ref: "#/components/parameters/callerSoftwareStatementId"
- $ref: "#/components/parameters/apiUri"
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/apiOperation"
- $ref: "#/components/parameters/consentId"
- $ref: "#/components/parameters/aspspIdcallerInteractionId"
- $ref: "#/components/parameters/callerOrgIdozoneInteractionId"
- $ref: "#/components/parameters/callerClientIdpsuIdentifier"
- $refresponses:
"#/components/parameters/callerSoftwareStatementId" '200':
- $ref: "#/components/parameters/apiUri" description: -successful $ref: "#/components/parameters/apiOperation"operation
- $refcontent: "#/components/parameters/consentId"
- $ref: "#/components/parameters/callerInteractionId"application/json:
- $ref: "#/components/parameters/ozoneInteractionId"schema:
- $ref: "#/components/parametersschemas/psuIdentifierPaymentGetResponse"
requestBody'400':
requireddescription: truefailed operation
content:
application/json:
schema:
$ref: "#/components/schemas/PaymentRequestError"
/payments/:paymentId/report-file:
responsesget:
tags:
201: - payments
description: successful operation summary: report file for bulk payments
content: description: |
This application/json:API is called by Ozone Bank Connect to get a report file for a set schema:of bulk payments
operationId: reportFile
$ref parameters:
"#/components/schemas/PaymentResponse" # 400:common header parameters that set context
description: failed operation - $ref: "#/components/parameters/providerId"
- content$ref: "#/components/parameters/aspspId"
- application/json:$ref: "#/components/parameters/callerOrgId"
- $ref: "#/components/parameters/callerClientId"
schema: - $ref: "#/components/parameters/callerSoftwareStatementId"
- $ref: "#/components/schemasparameters/ErrorapiUri"
security: - $ref: "#/components/parameters/apiOperation"
- bearerAuth: [] - $ref: "#/payments/:paymentId:components/parameters/consentId"
- get:$ref: "#/components/parameters/callerInteractionId"
- tags$ref: "#/components/parameters/ozoneInteractionId"
- payments $ref: "#/components/parameters/psuIdentifier"
summaryresponses:
Get a payment description'200':
| Ozone candescription: callsuccessful thisoperation
API from LFIs to retrieve payment information. content:
parameters: # common header parameters that set context '*/*':
- $refschema:
"#/components/parameters/aspspId" - $ref: "#/components/parameters/callerOrgId" type: string
- $ref: "#/components/parameters/callerClientId" - $refdescription: "#/components/parameters/callerSoftwareStatementId" Any content type.
- $ref'400':
"#/components/parameters/apiUri" - $refdescription: "#/components/parameters/apiOperation" failed operation
- $refcontent: "#/components/parameters/consentId"
- $ref: "#/components/parameters/callerInteractionId"application/json:
- $ref: "#/components/parameters/ozoneInteractionId"schema:
- $ref: "#/components/parametersschemas/psuIdentifierError"
security:
responses: - 200bearerAuth: []
components:
schemas:
description: successful operationPaymentPostRequest:
type: object
content: properties:
application/jsonrequestUrl:
type: string
schema: description: |
$ref: "#/components/schemas/PaymentGetResponse" The (Ozone) URL at which 400:the TPP requested for the payment
description: failed operation paymentType:
content: $ref: "#/components/schemas/PaymentType"
application/jsonrequest:
$ref: "#/components/schemas/PaymentRequestBody"
schema: requestHeaders:
$ref: "#/components/schemas/ErrorPaymentRequestHeaders"
/payments/:paymentId/details: gettpp:
tags: $ref: "#/components/schemas/tpp"
- payments supplementaryInformation:
summary: Get payment details description$ref: |"#/components/schemas/SupplementaryInformation"
required:
In situations where an API supports retrieval of detailed- paymentpaymentType
information, - Ozonerequest
can call this API from LFIs to retrieve detailed- information.requestHeaders
parameters: - tpp
# commonadditionalProperties: headerfalse
parameters
that set context PaymentRequestBody:
-type: $ref: "#/components/parameters/aspspId"object
description: |
- $ref: "#/components/parameters/callerOrgId" The entire HTTP request -body $ref: "#/components/parameters/callerClientId"
that was received by Ozone from the TPP.
- $ref: "#/components/parameters/callerSoftwareStatementId" The type can be -used $ref: "#/components/parameters/apiUri"
to identify the schema
- $ref: "#/components/parameters/apiOperation"
- $ref: "#/components/parameters/consentId" that should be used to validate the request.
•••TODO•••: This field -will $ref: "#/components/parameters/callerInteractionId"
- $ref: "#/components/parameters/ozoneInteractionId"be updated in the next release to include the CBUAE payment request schema.
- $refadditionalProperties: "#/components/parameters/psuIdentifier"true
responsesPaymentRequestHeaders:
type: object
200description: |
The entire description:set successfulof operationHTTP request headers that was received by Ozone from the TPP
content: additionalProperties: true
application/jsontpp:
type: object
schemadescription: |
The TPP record as held by Ozone.
$ref: "#/components/schemas/PaymentDetailsResponse" If Ozone 400:TPP Connect has been integrated into a directory, the `directoryRecord` provides description: failed operation
content:the TPP's directory record as held by Ozone in base 64 encoded format.
required:
application/json: - clientId
- orgId
schema: - softwareStatementId
$ref: "#/components/schemas/Error"
components: - tppName
schemasproperties:
PaymentConsentValidateRequest: clientId:
type: object oneOftype: string
- $ref: "#/components/schemas/ConsentGetResponse"
ConsentGetResponse:
type: object description: The clientId for the TPP as issued by Ozone
orgId:
description: | type: Astring
consent in its current state. description: The organization id Iffor the consentTPP
has
been authorised, then it can be expected that thesoftwareStatementId:
LFI would havetype: patchedstring
in `accountIds` and `psuIdentifier` fields. description: The organization id Additionally,for the LFITPP
may
also patch in an arbitrary set of fields alongtppName:
with consent type: instring
the `supplementaryInformation` field. properties:description: The name of the TPP
iddirectoryRecord:
type: string
description: |
A unique identifier for the consent in uuid-v4 format.
The latest copy of the TPP directory record if the TPP has registered with a directory
additionalProperties: false
SupplementaryInformation:
type: object
This is distinct fromdescription: the|
ConsentId that is communicated back to PSUs and TPPs.The `SupplementaryInformation` object may have arbitrary custom fields that a consentType:Financial Institution may use
$refadditionalProperties: "#/components/schemas/ConsentType"true
PaymentType:
request: type: string
$refdescription: "#/components/schemas/Request"|
The requestHeaders:type of the payment that is being created.
$ref: "#/components/schemas/RequestHeaders" ***TODO***: This field will consist consentBody:of the enumeration of payment types supported by CBUAE. This will $ref: "#/components/schemas/ConsentBody"
be updated in the next release.
tppPaymentPostResponse:
type: object
$ref: "#/components/schemas/TPP"
properties:
psuIdentifiersdata:
$ref: "#/components/schemas/PSUIdentifiersCbuaePaymentPostResponseBody"
accountIdsmeta:
$ref: "#/components/schemas/AccountIdsMeta"
requiredCbuaePaymentPostResponseBody:
description: |
- id The payment -response consentTypeto be passed on to the TPP.
- request The structure of -this requestHeadersresponse is aligned to the structure of the response -for tppthe CBUAE payment initiation API.
additionalProperties: false ConsentType***TODO***: This field will be updated in type:the stringnext release to include the CBUAE payment description:response |schema.
type: object
The type of the consent that isadditionalProperties: beingtrue
created.
PaymentGetResponse:
Each LFI's instancetype: mayobject
support a different set of consent typesproperties:
Thedata:
Consent Manager supports the creation of consents of different consent types
$ref: "#/components/schemas/PaymentGetResponseBody"
depending onmeta:
the standards supported. $ref: For example, for the UK OBIE standards, the following consent types are available:
"#/components/schemas/Meta"
PaymentGetResponseBody:
description: |
A - account-access-consents
descriptor for a Payment.
- domestic-payment-consentsThe structure of this response is aligned to the structure of - future-dated-payment-consents
the response for the CBUAE payment initiation API.
- standing-order-consents ***TODO***: This field will be updated in - 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"the next release to include the CBUAE payment response schema.
type: "object"
requiredadditionalProperties: true
#
- "en" # Common types
properties: #
enMeta:
type: object
type: "string" additionalProperties: false
descriptionError: "English
value of the string" type: object
minLengthproperties:
1 errorCode:
maxLength: 500 type: string
ar: typedescription: "string"Error code identifying the problem occured
description: "Arabic value oferrorMessage:
the string" type: string
minLength: 1 description: Message maxLength:describing 500what problem has occured
additionalProperties: false propagateError:
# # Common types type: boolean
# Meta: description: optional field type:if objecterror want to propagate
additionalPropertiesparameters:
false ErrorproviderId:
typename: objecto3-provider-id
propertiesin: header
errorCodeschema:
type: string
required: true
description: Error code identifying Identifier for the Financial Institution that the problemrequest occuredis targetted to
errorMessageaspspId:
name: o3-aspsp-id
type: string in: header
descriptionschema:
Message describing what problem has occured type: string
parameters: aspspIdrequired: true
namedeprecated: o3-aspsp-idtrue
indescription:
header Identifier schema:for the financial institution that the request is targetted type:to.
string required: trueThis header is deprecated and will be description:removed Identifierin fora thefuture LFIversion thatof theOzone requestConnect. is targetted toUse `o3-provider-id` instead.
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
|
