openapi: 3.0.1
servers:
- url: https://{your-cm-server}
description: Consent manager for the tenant
<your-ozone-connect-server>
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 Financial Institution so that Ozone can deliver Service Initiation capabilities to TPPs
#### Changes in Release 2024.34.1
Introduced new* endpointRemoved Get /payment-consents/{consentId}/refund.
Cosmetic changes - Request Response Changes
contact:
propagateError field from the Error object.
* Update exchangeRate and rateType properties
name: Ozone Financial* TechnologyRefactored LimitedSecurity Scheme Objects to version:use Releasecommon 2024.34definitions across tags:all API Hub -APIs
name: payments
description: | * Implemented the correct Security Requirements APIsfor thatthis shouldAPI bedescription, implementedreflecting bysecurity Financialpatterns Institutionsavailable toin exposeAPI ServiceHub
Initiation
capability to TPPs. paths:#### Changes in /payments:
Release 2024.34
post: * Introduced new endpoint tags:Get /payment-consents/{consentId}/refund.
* Cosmetic changes - paymentsRequest Response Changes
summarycontact:
Make a payment name: Ozone Financial Technology Limited
description:
| version: Release 2024.34.1
tags:
This- APIname: ispayments
called by Ozone Connect todescription: instruct|
a Financial Institution to initiate a paymentAPIs oncethat itshould hasbe receivedimplemented aby paymentFinancial Institutions to expose Service Initiation capability to TPPs.
instruction
fromsecurity:
a TPP that- has{}
passed all local- validations.OzoneConnectApiKey: []
- OzoneConnectClientCredentials: [
The Financial Institution must"placeholder"
process the payment and indicate]
a failure response- (if the payment fails technical validation) or aOzoneConnectJwtAuth: []
paths:
/payments:
post:
success response (iftags:
the payment passess technical validation and is submitted to- thepayments
payment rails for processing) summary: Make a payment
The Financial Institution mustdescription: 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 headerThis API is called by Ozone Connect to instruct a Financial Institution to initiate a payment once it has received a payment
instruction from a TPP that has passed all local validations.
operationId: makePayment The Financial Institution must process the parameters:payment and indicate a failure response (if the payment #fails commontechnical headervalidation) parametersor thata
set context success response -(if $ref: "#/components/parameters/providerId"
- $ref: "#/components/parameters/aspspId"
the payment passess technical validation and is submitted to the payment rails for processing)
- $ref: "#/components/parameters/callerOrgId"
- $ref: "#/components/parameters/callerClientId"
- $ref: "#/components/parameters/callerSoftwareStatementId" The Financial Institution must generate a unique `PaymentId` that can be sent on to the TPP as a reference for the payment.
If the -underlying $ref: "#/components/parameters/apiUri"
- $ref: "#/components/parameters/apiOperation"
consent has been patched with a `bankConnectToken`, then the token is passed in as the authorization header.
- $ref: "#/components/parameters/consentId" operationId: makePayment
parameters:
# common header parameters that set context
- $ref: "#/components/parameters/callerInteractionIdproviderId"
- $ref: "#/components/parameters/ozoneInteractionIdaspspId"
- $ref: "#/components/parameters/psuIdentifiercallerOrgId"
requestBody- $ref: "#/components/parameters/callerClientId"
- required: true$ref: "#/components/parameters/callerSoftwareStatementId"
- content$ref: "#/components/parameters/apiUri"
- application/json$ref: "#/components/parameters/apiOperation"
- schema$ref: "#/components/parameters/consentId"
- $ref: "#/components/schemasparameters/PaymentPostRequestcallerInteractionId"
responses: - $ref: "#/components/parameters/ozoneInteractionId"
- '201':$ref: "#/components/parameters/psuIdentifier"
security:
description: successful operation
- {}
- contentOzoneConnectApiKey: []
- OzoneConnectClientCredentials: [
application/json: "placeholder"
schema: ]
- $refOzoneConnectJwtAuth: "#/components/schemas/AEPaymentIdResponse" []
- '400':OzoneConnectServiceInitiationToken: []
requestBody:
description: failed operation required: true
content:
application/json:
schema:
$ref: "#/components/schemas/ErrorPaymentPostRequest"
securityresponses:
- bearerAuth: []'201':
/payments/:paymentId: getdescription: successful operation
operationId: getPayment content:
tags: - payments application/json:
summary: Get a payment descriptionschema:
| Ozone can call this API from Financial Institutions to retrieve payment information.$ref: "#/components/schemas/AEPaymentIdResponse"
parameters'400':
# common headerdescription: parametersfailed that setoperation
context - $refcontent: "#/components/parameters/providerId"
- $ref: "#/components/parameters/aspspId"application/json:
- $ref: "#/components/parameters/callerOrgId" schema:
- $ref: "#/components/parameters/callerClientId" - $ref: "#/components/parametersschemas/callerSoftwareStatementIdError"
/payments/{paymentId}:
- $refget:
"#/components/parameters/apiUri" operationId: getPayment
- $ref: "#/components/parameters/apiOperation" tags:
- $ref: "#/components/parameters/consentId"
- payments
- $refsummary: "#/components/parameters/callerInteractionId"
Get a payment
- $refdescription: "#/components/parameters/ozoneInteractionId"|
-Ozone $ref: "#/components/parameters/psuIdentifier"
responses:
can call this API from Financial Institutions to retrieve payment information.
'200'parameters:
# common header description:parameters successfulthat operationset context
- content$ref: "#/components/parameters/providerId"
- application/json:$ref: "#/components/parameters/aspspId"
- $ref: "#/components/parameters/callerOrgId"
schema: - $ref: "#/components/parameters/callerClientId"
- $ref: "#/components/schemasparameters/AEPaymentIdResponsecallerSoftwareStatementId"
- '400'$ref: "#/components/parameters/apiUri"
- description$ref: failed operation"#/components/parameters/apiOperation"
- content$ref: "#/components/parameters/consentId"
- application/json:$ref: "#/components/parameters/callerInteractionId"
- $ref: "#/components/parameters/ozoneInteractionId"
schema: - $ref: "#/components/parameters/psuIdentifier"
- $ref: "#/components/schemasparameters/ErrorpaymentId"
/payments/:paymentId/report-file:responses:
get'200':
tags: description: successful operation
- payments summarycontent:
report file for bulk payments descriptionapplication/json:
| This API is called by Ozoneschema:
Bank Connect to get a report file for a set of bulk payments $ref: "#/components/schemas/AEPaymentIdResponse"
operationId: reportFile '400':
parameters: #description: commonfailed headeroperation
parameters that set context content:
- $ref: "#/components/parameters/providerId" - $refapplication/json:
"#/components/parameters/aspspId" - $ref: "#/components/parameters/callerOrgId" schema:
- $ref: "#/components/parameters/callerClientId"
- $ref: "#/components/parametersschemas/callerSoftwareStatementIdError"
/payments/{paymentId}/report-file:
-get:
$ref: "#/components/parameters/apiUri" tags:
- $ref: "#/components/parameters/apiOperation" - payments
- $refsummary: "#/components/parameters/consentId"
report file for bulk payments
- $refdescription: "#/components/parameters/callerInteractionId"|
-This $ref: "#/components/parameters/ozoneInteractionId"
- $ref: "#/components/parameters/psuIdentifier"
responses:
'200':
API is called by Ozone Bank Connect to get a report file for a set of bulk payments
operationId: reportFile
descriptionparameters:
successful operation # common header parameters content:that set context
- '*/*':$ref: "#/components/parameters/providerId"
- $ref: "#/components/parameters/aspspId"
schema: - $ref: "#/components/parameters/callerOrgId"
- type$ref: string"#/components/parameters/callerClientId"
- $ref: "#/components/parameters/callerSoftwareStatementId"
description: Any content type. '400':
- $ref: "#/components/parameters/apiUri"
- description$ref: failed operation"#/components/parameters/apiOperation"
- content$ref: "#/components/parameters/consentId"
- application/json:$ref: "#/components/parameters/callerInteractionId"
- $ref: "#/components/parameters/ozoneInteractionId"
schema: - $ref: "#/components/parameters/psuIdentifier"
- $ref: "#/components/schemasparameters/ErrorpaymentId"
securityresponses:
'200':
- bearerAuth: [] /payment-consents/{consentId}/refund: description: successful get:operation
tags: content:
- payments summary'*/*':
Retrieve a Payment Consent description: | schema:
Ozone can call this API from Financial Institutions to retrieve payment information.type: string
parameters: # common headerdescription: parametersAny thatcontent settype.
context
- $ref'400':
"#/components/parameters/providerId" - $refdescription: "#/components/parameters/aspspId" failed operation
- $refcontent: "#/components/parameters/callerOrgId"
- $refapplication/json:
"#/components/parameters/callerClientId" - $ref: "#/components/parameters/callerSoftwareStatementId" schema:
- $ref: "#/components/parameters/apiUri" - $ref: "#/components/parametersschemas/apiOperationError"
/payment-consents/{consentId}/refund:
get:
- $ref: "#/components/parameters/consentId" tags:
- $ref: "#/components/parameters/callerInteractionId" - payments
- $refsummary: "#/components/parameters/ozoneInteractionId"
Retrieve a Payment Consent
- $refdescription: "#/components/parameters/psuIdentifier"|
Ozone -can name:call consentIdthis API from Financial Institutions to retrieve payment information.
in: path operationId: getRefund
schemaparameters:
# common header parameters type:that stringset context
- required$ref: true"#/components/parameters/providerId"
- description$ref: |"#/components/parameters/aspspId"
- $ref: "#/components/parameters/callerOrgId"
Identifies the consent by an id - $ref: "#/components/parameters/callerClientId"
responses: '200':
- $ref: "#/components/parameters/callerSoftwareStatementId"
- description$ref: successful operation"#/components/parameters/apiUri"
- content$ref: "#/components/parameters/apiOperation"
- $ref: application/json:
"#/components/parameters/consentId"
- $ref: "#/components/parameters/callerInteractionId"
schema: - $ref: "#/components/parameters/ozoneInteractionId"
- $ref: "#/components/schemasparameters/RefundGetResponsepsuIdentifier"
- '400'name: consentId
descriptionin: failedpath
operation contentschema:
application/jsontype: string
required: true
schema: description: |
$ref: "#/components/schemas/Error" components: schemas:Identifies the consent by an id
PaymentPostRequest:
typeresponses:
object properties'200':
requestUrldescription: successful operation
typecontent:
string descriptionapplication/json:
| The (Ozone)schema:
URL at which the TPP requested for the payment
paymentType: $ref: "#/components/schemas/PaymentTypeRefundGetResponse"
request'400':
$refdescription: "#/components/schemas/AEPaymentAndFilePaymentRequest"
failed operation
requestHeaders: content:
$ref: "#/components/schemas/PaymentRequestHeaders" application/json:
tpp: $ref: "#/components/schemas/tpp"
schema:
supplementaryInformation: $ref: "#/components/schemas/SupplementaryInformationError"
components:
schemas:
requiredPaymentPostRequest:
type: object
- paymentType properties:
- request requestUrl:
- requestHeaders type: string
- tpp additionalPropertiesdescription: false|
AEPaymentAndFilePaymentRequest: description: The payment(Ozone) request body as received from the TPPURL at which the TPP requested for the payment
oneOfpaymentType:
- $ref: "#/components/schemas/AEPaymentRequest"PaymentType"
request:
- $ref: "#/components/schemas/AEFilePaymentRequestAEPaymentAndFilePaymentRequest"
AEPaymentRequest: requestHeaders:
description: | $ref: Payment Request Schema"#/components/schemas/PaymentRequestHeaders"
typetpp:
"object" additionalProperties: false $ref: "#/components/schemas/tpp"
required: supplementaryInformation:
- "Data" properties$ref: "#/components/schemas/SupplementaryInformation"
Datarequired:
- paymentType
type: "object" - request
additionalProperties: false - requestHeaders
required: - tpp
- "ConsentId"additionalProperties: false
AEPaymentAndFilePaymentRequest:
- "Instruction"
description: The payment request body as received from the TPP
- "PersonalIdentifiableInformation" oneOf:
- -$ref: "PaymentPurposeCode#/components/schemas/AEPaymentRequest"
- properties:$ref: "#/components/schemas/AEFilePaymentRequest"
AEPaymentRequest:
ConsentIddescription: |
Payment Request Schema
$ref type: "#/components/schemas/AEConsentId"object"
additionalProperties: false
Instructionrequired:
- "Data"
$refproperties: "#/components/schemas/AEPaymentInstruction"
Data:
CurrencyRequest: type: "object"
$ref: "#/components/schemas/AECurrencyRequest"
additionalProperties: false
PersonalIdentifiableInformationrequired:
- $ref: "#/components/schemas/AEJWEPaymentPII"ConsentId"
- "Instruction"
PaymentPurposeCode:- "PersonalIdentifiableInformation"
- $ref: "#/components/schemas/AEPaymentPurposeCode""PaymentPurposeCode"
properties:
DebtorReference ConsentId:
$ref: "#/components/schemas/AEStructuredDebtorReferenceAEConsentId"
CreditorReferenceInstruction:
$ref: "#/components/schemas/AEStructuredCreditorReferenceAEPaymentInstruction"
AEJWEPaymentPII: typeCurrencyRequest:
string description: |2- $ref: "#/components/schemas/AECurrencyRequest"
A JSON Web Encryption (JWE) object, which encapsulatesPersonalIdentifiableInformation:
a JWS. The value is a compact serialization $ref: "#/components/schemas/AEJWEPaymentPII"
of a JWE, which is a string consisting ofPaymentPurposeCode:
five base64url-encoded parts joined by dots. It encapsulates encrypted content using JSON data structures. $ref: "#/components/schemas/AEPaymentPurposeCode"
The decryptedDebtorReference:
JWS content has the structure of the AEPaymentPII schema. AEConsentId$ref: "#/components/schemas/AEStructuredDebtorReference"
type: string minLengthCreditorReference: 1
maxLength: 128 description$ref: >-"#/components/schemas/AEStructuredCreditorReference"
AEJWEPaymentPII:
Unique identification assigned by thetype: TPPstring
to identify the consent description: |2-
resource. AEFilePaymentRequest: A JSON Web Encryption description: |
File Payment Request Schema(JWE) object, which encapsulates a JWS. The value is a compact serialization
type: "object" of a JWE, which is a additionalProperties:string falseconsisting of five base64url-encoded parts joined required:
- "Data"by dots. It encapsulates encrypted content using JSON data structures.
properties: The decrypted JWS content has Data:the structure of the AEPaymentPII schema.
typeAEConsentId:
"object" type: string
additionalPropertiesminLength: false1
maxLength: 128
required: description: >-
- "ConsentId"Unique identification assigned by the TPP to identify the consent
- "PaymentPurposeCode" resource.
propertiesAEFilePaymentRequest:
description: |
ConsentId: File Payment Request Schema
$reftype: "#/components/schemas/AEConsentIdobject"
additionalProperties: false
Instruction: required:
$ref:- "#/components/schemas/AEFilePaymentConsentData"
properties:
PaymentPurposeCode: Data:
$reftype: "#/components/schemas/AEPaymentPurposeCodeobject"
DebtorReferenceadditionalProperties: false
$ref: "#/components/schemas/AEStructuredDebtorReference"required:
AEFilePaymentConsent: type:- "objectConsentId"
description: | - "PaymentPurposeCode"
A file based payment consent. properties:
A Consent definition for defining Multi Payments ConsentId:
required: -$ref: "FileType#/components/schemas/AEConsentId"
- "FileHash" Instruction:
- "NumberOfTransactions" $ref: - "ControlSum""#/components/schemas/AEFilePaymentConsent"
properties: PaymentPurposeCode:
FileType: $ref: "#/components/schemas/AEFileTypeAEPaymentPurposeCode"
FileHashDebtorReference:
$ref: "#/components/schemas/AEFileHashAEStructuredDebtorReference"
FileReferenceAEFilePaymentConsent:
$reftype: "#/components/schemas/AEReferenceobject"
description: |
NumberOfTransactions: A file based $ref: "#/components/schemas/AEFileNumberOfTransactions"payment consent.
ControlSum:A Consent definition for defining Multi Payments
$ref: "#/components/schemas/AEControlSum"
required:
RequestedExecutionDate: - "FileType"
$ref:- "#/components/schemas/AERequestedExecutionDateFileHash"
additionalProperties: false - "NumberOfTransactions"
AERequestedExecutionDate: - "ControlSum"
description: | properties:
The date when the TPPFileType:
expects the LFI to execute the payment. $ref: "#/components/schemas/AEFileType"
The date must be in theFileHash:
future and cannot be on the same day or a day in the past.$ref: "#/components/schemas/AEFileHash"
FileReference:
The maximum date in the future that can be specified is 1 year from the day of the consent of the User to the TPP.$ref: "#/components/schemas/AEReference"
NumberOfTransactions:
$ref: "#/components/schemas/AEFileNumberOfTransactions"
All dates in the JSON payloads are representedControlSum:
in ISO 8601 date format. type$ref: "string"#/components/schemas/AEControlSum"
RequestedExecutionDate:
format$ref: "date"#/components/schemas/AERequestedExecutionDate"
AEFileNumberOfTransactionsadditionalProperties: false
typeAERequestedExecutionDate: "integer"
description: |
NumberThe ofdate individualwhen transactionsthe containedTPP inexpects the paymentLFI informationto group.execute the payment.
AEControlSum: The description:date |must be in the future and cannot be on Totalthe ofsame allday individualor amountsa includedday in the past.
group, irrespective of currencies. The maximum type: "string"
pattern: "^\\d{1,16}\\.\\d{2}$"
example: "100.00"
AEReference:date in the future that can be specified is 1 year from the day of the consent of the User to the TPP.
description: |All dates in the JSON payloads are represented in AISO reason8601 ordate referenceformat.
in relation to a payment. type: "string"
Reason or reference for the beneficiary regarding the Paymentformat: "date"
AEFileNumberOfTransactions:
type: "stringinteger"
minLengthdescription: 1|
maxLength: 120 Number of individual transactions contained AEFileType:in the payment information group.
typeAEControlSum:
"string" description: "Specifies|
the payment file type" Total of minLength:all 1individual amounts included in the group, irrespective maxLength: 40
AEFileHash:of currencies.
type: "string"
descriptionpattern: "A base64 encoding of a SHA256 hash of the file to be uploaded.^\\d{1,16}\\.\\d{2}$"
minLengthexample: 1"100.00"
maxLength: 44
AEStructuredCreditorReferenceAEReference:
description: |
A reason or reference in relation to a payment,.
set to facilitate a structured Creditor reference consisting of:Reason or reference for the beneficiary regarding the Payment
* TPP ID and BIC for the Debtor Account, followed by freeform text to a maximum of 120 characters.
type: "string"
minLength: 1
maxLength: 120
TheAEFileType:
TPP ID value will match the organization ID value from the Trust Framework, and therefore will be a v4 UUID.type: "string"
description: "Specifies the payment file type"
minLength: 1
A BIC is specific according tomaxLength: the40
standard format for ISO 20022,AEFileHash:
and can therefore be either 8 or 11 characters in length.type: "string"
description: "A base64 encoding of a IfSHA256 thehash value of the concatenatedfile stringto exceedsbe 120uploaded."
characters, the TPP must first omit or truncate the freeform element of the reference. minLength: 1
maxLength: 44
AEStructuredCreditorReference:
description: |
A reason or reference in relation to a payment, set to facilitate a structured Creditor reference consisting of:
type: "string" * TPP ID and BIC minLength: 1
maxLength: 120for the Debtor Account, followed by freeform text to a maximum of 120 characters.
pattern: "^TPP=[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12},BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}($|,.+$)"
AEPaymentInstruction:
type: "object"
additionalProperties: false The TPP ID value will match the organization ID value from the Trust Framework, and therefore will be a v4 UUID.
A required:BIC is specific according to the standard format for - "Amount"
- "PaymentSequenceNumber"ISO 20022, and can therefore be either 8 or 11 characters in length.
description: "The Initiation payloadIf isthe sentvalue byof the concatenated string initiatingexceeds party120 tocharacters, the LFI.TPP Itmust isfirst usedomit toor requesttruncate movementthe offreeform fundselement fromof the debtorreference.
account to a creditor for a single payment.type: "string"
propertiesminLength: 1
AmountmaxLength: 120
pattern: $ref: "#/components/schemas/AEActiveCurrencyAmount"
"^TPP=[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12},BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}($|,.+$)"
AEPaymentInstruction:
PaymentSequenceNumbertype: "object"
additionalProperties: false
$ref: "#/components/schemas/AEPaymentSequenceNumber" required:
AEPaymentSequenceNumber: type:- "stringAmount"
description: |- "PaymentSequenceNumber"
description: This"The indicatesInitiation thepayload underlyingis sequencesent ofby the recurringinitiating paymentparty thatto isthe being instructedLFI. It is used to request movement of funds Forfrom example:the debtor account to a creditor for a single *payment."
1 can represent the first payment instructionproperties:
*Amount:
12 can represent the twelfth payment instruction $ref: "#/components/schemas/AEActiveCurrencyAmount"
minLength: 1 PaymentSequenceNumber:
maxLength: 10 pattern$ref: "^[1-9]\\d*$#/components/schemas/AEPaymentSequenceNumber"
RequestHeadersAEPaymentSequenceNumber:
type: object"string"
description: |
The entire setThis indicates the underlying sequence of HTTPthe requestrecurring headerspayment that wasis receivedbeing byinstructed.
Ozone from the TPP For additionalPropertiesexample:
true Request: * 1 can represent the type:first objectpayment instruction
description: | * 12 can represent the twelfth payment Theinstruction
entire HTTP request body that was receivedminLength: by1
Ozone from the TPP. maxLength: 10
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
pattern: "^[1-9]\\d*$"
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,
- cbuae-payment (Single Instant Payment, Multi Payment - Fixed and Variable Recurring Payment, Future Dated Payment etc)
- cbuae-file-payment
PaymentRequestHeaders:
type: object
description: |
The entire set of HTTP request headers that was received by Ozone from the TPP
additionalProperties: true
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 in base 64 encoded format.
required:
- clientId
- orgId
- softwareStatementId
- tppName
properties:
clientId:
type: string
description: The clientId for the TPP as issued by Ozone
orgId:
type: string
description: The organization id for the TPP
softwareStatementId:
type: string
description: The organization id for the TPP
tppName:
type: string
description: The name of the TPP
directoryRecord:
type: string
description: The latest copy of the TPP directory record if the TPP has registered with a directory
additionalProperties: false
SupplementaryInformation:
type: object
description: |
The `SupplementaryInformation` object may have arbitrary custom fields that a Financial Institution may use
additionalProperties: true
AEPaymentIdResponse:
description: |
The payment response to be passed on to the TPP.
The structure of this response is aligned to the structure of the response for the CBUAE payment initiation API.
type: "object"
additionalProperties: false
required:
- "data"
properties:
data:
type: "object"
description: "Required fields are common for all the payments including file payment. Apart from that, paymentTransactionId is required for all payments except file payments"
additionalProperties: false
required:
- "id"
- "status"
- "statusUpdateDateTime"
- "creationDateTime"
- "paymentPurposeCode"
properties:
id:
type: string
consentId:
type: string
paymentTransactionId:
type: string
status:
type: string
enum:
- "Pending"
- "AcceptedSettlementCompleted"
- "AcceptedCreditSettlementCompleted"
- "AcceptedWithoutPosting"
- "Rejected"
- "Received"
statusUpdateDateTime:
type: string
format: date-time
creationDateTime:
type: string
format: date-time
charges:
$ref: "#/components/schemas/AECharges"
exchangeRate:
$ref: "#/components/schemas/AEExchangeRateInformation"
currencyRequest:
$ref: "#/components/schemas/AECurrencyRequest"
instruction:
$ref: "#/components/schemas/AEPaymentInstruction"
paymentPurposeCode:
$ref: "#/components/schemas/AEPaymentPurposeCode"
debtorReference:
$ref: "#/components/schemas/AEStructuredDebtorReference"
meta:
$ref: "#/components/schemas/Meta"
AECharges:
type: "array"
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 Debtor.
required:
- "chargeBearer"
- "type"
- "amount"
properties:
chargeBearer:
$ref: "#/components/schemas/AEChargeBearerType1Code"
type:
$ref: "#/components/schemas/AEExternalPaymentChargeTypeCode"
amount:
$ref: "#/components/schemas/AEActiveCurrencyAmount"
AEChargeBearerType1Code:
description: "Specifies which party/parties will bear the charges associated with the processing of the payment transaction."
type: "string"
enum:
- "BorneByCreditor"
- "BorneByDebtor"
- "FollowingServiceLevel"
- "Shared"
AEExternalPaymentChargeTypeCode:
description: "Charge type, in a coded form."
type: "string"
enum:
- "VAT"
- "Fees"
AEActiveCurrencyAmount:
description: |
The Currency and Amount relating to the Payment, Refund or Request to Pay
type: "object"
required:
- "amount"
- "currency"
properties:
amount:
$ref: "#/components/schemas/AEActiveOrHistoricAmount"
currency:
$ref: "#/components/schemas/AEActiveOrHistoricCurrencyCode"
AEActiveOrHistoricAmount:
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"
AEActiveOrHistoricCurrencyCode:
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: "AED"
AEExchangeRateInformation:
type: "object"
additionalProperties: false
required:
- "unitCurrency"
- "ExchangeRateexchangeRate"
- "RateTyperateType"
description: "Further detailed information on the exchange rate that has been used in the payment transaction."
properties:
unitCurrency:
description: "Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP."
type: "string"
pattern: "^[A-Z]{3,3}$"
exchangeRate:
description: "The factor used for conversion of an amount from one currency to another. This reflects the price at which one currency was bought with another currency."
type: "number"
rateType:
description: "Specifies the type used to complete the currency exchange."
type: "string"
enum:
- "Actual"
- "Agreed"
- "Indicative"
contractIdentification:
description: "Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent."
type: "string"
minLength: 1
maxLength: 256
expirationDateTime:
description: "Specified date and time the exchange rate agreement will expire.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:\n2017-04-05T10:43:07+00:00"
type: "string"
format: "date-time"
AECurrencyRequest:
description: |
The details of the non-local currency or FX request that has been agreed between the User and the TPP.
The requested ChargeBearer and ExchangeRateInformation are included in this object may be overwritten by the LFI in the returned Consent object.
type: "object"
additionalProperties: false
required:
- "currencyOfTransfer"
properties:
instructionPriority:
description: "Indicator of the urgency or order of importance that the instructing party would like the instructed party to apply to the processing of the instruction."
type: "string"
enum:
- "Normal"
- "Urgent"
extendedPurpose:
description: "Specifies the purpose of an international payment, when there is no corresponding 4 character code available in the ISO20022 list of Purpose Codes."
type: "string"
minLength: 1
maxLength: 140
chargeBearer:
$ref: "#/components/schemas/AEChargeBearerType1Code"
currencyOfTransfer:
description: "Specifies the currency of the to be transferred amount, which is different from the currency of the debtor's account."
type: "string"
pattern: "^[A-Z]{3,3}$"
destinationCountryCode:
description: "Country in which Credit Account is domiciled. Code to identify a country, a dependency, or another area of particular geopolitical interest, on the basis of country names obtained from the United Nations (ISO 3166, Alpha-2 code)."
type: "string"
pattern: "[A-Z]{2,2}"
exchangeRateInformation:
type: "object"
additionalProperties: false
required:
- "unitCurrency"
- "rateType"
description: "Provides details on the currency exchange rate and contract."
properties:
unitCurrency:
description: "Currency in which the rate of exchange is expressed in a currency exchange. In the example 1GBP = xxxCUR, the unit currency is GBP."
type: "string"
pattern: "^[A-Z]{3,3}$"
exchangeRate:
description: "The factor used for conversion of an amount from one currency to another. This reflects the price at which one currency was bought with another currency."
type: "number"
rateType:
description: "Specifies the type used to complete the currency exchange."
type: "string"
enum:
- "Actual"
- "Agreed"
- "Indicative"
contractIdentification:
description: "Unique and unambiguous reference to the foreign exchange contract agreed between the initiating party/creditor and the debtor agent."
type: "string"
minLength: 1
maxLength: 256
AEPaymentPurposeCode:
description: A category code that relates to the type of services or goods that corresponds to the underlying purpose of the payment. The code must conform to the published AANI payment purpose code list.
type: "string"
minLength: 1
maxLength: 4
pattern: "^[A-Z]{3}$"
AEStructuredDebtorReference:
description: |
A reason or reference in relation to a payment, set to facilitate a structured Debtor reference consisting of:
* For payments to Merchants: TPP ID, Merchant ID, BIC for the Creditor Account, followed by freeform text to a maximum of 120 characters.
* For other payments: TPP ID and BIC for the Creditor Account, followed by freeform text to a maximum of 120 characters.
The TPP ID value will match the organization ID value from the Trust Framework, and therefore will be a v4 UUID.
The Merchant ID wil be as per the existing IPP rules for the Merchant identification, and will incorporate the Trade License number for the Merchant.
A BIC is specific according to the standard format for ISO 20022, and can therefore be either 8 or 11 characters in length.
If the value of the concatenated string exceeds 120 characters, the TPP must omit or truncate the freeform element of the reference.
oneOf:
- type: "string"
minLength: 1
maxLength: 120
pattern: "^TPP=[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12},Merchant=[A-Z0-9]{3}-[A-Z]{4}-TL.+-[0-9]{4},BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}($|,.+$)"-9]{3}){0,1}($|,.+$)"
- type: "string"
minLength: 1
maxLength: 120
pattern: "^TPP=[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12},BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}($|,.+$)"
RefundGetResponse:
type: object
properties:
data:
$ref: "#/components/schemas/RefundGetResponseBody"
meta:
$ref: "#/components/schemas/Meta"
RefundGetResponseBody:
type: object
required:
- refundAccount
properties:
consentId:
description: |
Unique identification assigned by the TPP to identify the consent resource.
type: "string"
minLength: 1
maxLength: 128
refundAccount:
$ref: "#/components/schemas/AEDebtorAccount"
AEDebtorAccount:
description: "Unambiguous identification of the account of the debtor to which a debit entry will be made."
type: "object"
required:
- "schemeName"
- "identification"
- "name"
properties:
schemeName:
description: "Name of the identification scheme, in a coded form as published in an external list."
- type: "string"
minLength: 1enum:
- "IBAN"
- "AccountNumber"
identification:
maxLengthdescription: 120
pattern: "^TPP=[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12},BIC=[A-Z0-9]{4}[A-Z0-9]{2}[A-Z0-9]{2}([A-Z0-9]{3}){0,1}($|,.+$)" |
Identification for the account assigned by the LFI based on the Account Scheme Name.
RefundGetResponse: This identification type:is objectknown by the User account owner.
properties: datatype: "string"
$refminLength: "#/components/schemas/RefundGetResponseBody"1
metaname:
$ref: "#/components/schemas/MetaAEName"
RefundGetResponseBodyAEName:
type: "object"
requireddescription: |
- refundAccountThe Account Holder Name is the name properties:or names of the Account owner(s) represented at the consentId:account level
descriptionproperties:
| en:
Unique identification assigned by the TPP to identify the consent resource.type: "string"
typedescription: "string"English value of the string"
minLength: 1 maxLength: 12870
refundAccountar:
$reftype: "#/components/schemas/AEDebtorAccount"
string"
AEDebtorAccount: description: "UnambiguousArabic identificationvalue of the accountstring"
of the debtor to which a debit entry will be made."
type: "object" maxLength: 70
requiredadditionalProperties: false
#
- "schemeName" # Common types
- "identification"#
- "name"Meta:
propertiestype: object
schemeNameadditionalProperties: false
descriptionError:
"Name of the identification scheme, in atype: codedobject
form as published in an external list."properties:
typeerrorCode:
"string" type: enum:string
description: Error -code "IBAN"identifying the problem occured
errorMessage:
- "AccountNumber" identificationtype: string
description: Message |describing what problem has occured
parameters:
IdentificationproviderId:
for the account assigned by the LFI based on the Account Scheme Name.name: o3-provider-id
in: header
schema:
This identification is knowntype: bystring
the User account owner. required: true
typedescription: "string"Identifier for the Financial Institution that the request is targetted to
minLength: 1 aspspId:
name: o3-aspsp-id
in: header
$ref: "#/components/schemas/AEName" schema:
AEName: type: "object"string
descriptionrequired: true
| deprecated: true
The Account Holder Name isdescription:
the name or names of the Account owner(s) representedIdentifier atfor the accountfinancial levelinstitution that the request is targetted to.
properties: This en:header is deprecated and will be removed in a future version type: "string"
of Ozone Connect. Use `o3-provider-id` instead.
descriptioncallerOrgId:
"English value of the string" name: o3-caller-org-id
maxLengthin: 70header
arschema:
type: "string"
descriptionrequired: "Arabic valuetrue
of the string" description: An identifier for the organization maxLength:calling 70the API
additionalPropertiescallerClientId:
false #name: o3-caller-client-id
# Common typesin: header
# schema:
Meta: type: objectstring
additionalPropertiesrequired: true
false Errordescription: An identifier for the OIDC clientId type:calling objectthe API
propertiescallerSoftwareStatementId:
name: errorCode:o3-caller-software-statement-id
in: header
type: string schema:
descriptiontype: Errorstring
code identifying the problem occured required: true
errorMessage description: An identifier for the software statement calling the API
type: string apiUri:
descriptionname: Messageo3-api-uri
describing what problem has occured in: header
propagateError: schema:
type: string
boolean required: true
description: The optionalparameterised fieldURL ifof errorthe wantAPI tobeing propagatecalled by the caller
parameters:
providerIdapiOperation:
name: o3-providerapi-idoperation
in: header
schema:
type: string
required: true
description: IdentifierThe forAPI theoperation Financialcarried Institutionout thatby the request is targetted to caller (e.g. GET, POST, PUT, DELETE, PATCH)
aspspIdconsentId:
name: o3-aspspconsent-id
in: header
schema:
type: string
required: true
description: The consentId for deprecated: truewhich this call is being made
callerInteractionId:
name: o3-caller-interaction-id
descriptionin: header
schema:
Identifier for the financial institution that the request istype: targettedstring
to. required: true
This header is deprecated and willdescription: beThe removedinteraction inID apassed futurein versionby ofthe Ozonecaller, Connect. Use `o3-provider-id` instead.if any
callerOrgIdozoneInteractionId:
name: o3-callerozone-orginteraction-id
in: header
schema:
type: string
required: true
description: An identifier for the organization calling the API interaction ID generated by Ozone if the caller did not send in one. If the callerInteractionId is specified, this takes the same value.
callerClientIdpsuIdentifier:
name: o3-callerpsu-client-ididentifier
in: header
schema:
type: string
required: true
description: A Base64 Anencoded identifierrepresentation forof the OIDC clientId calling the API psuIdentifier JSON object.
paymentId:
callerSoftwareStatementIdname: paymentId
name: o3-caller-software-statement-iddescription: The identifier for a given payment instruction
in: path
required: headertrue
schema:
type: string
securitySchemes:
requiredOzoneConnectApiKey: true
description: An identifier for the software statement calling the API
apiUri: Communications between the API Hub and the LFI Ozone Connect implementation are secured using an API Key, which is a secret shared between the API Hub and the LFI.
nametype: o3-api-uriapiKey
in: header
schemaname: Authorization
OzoneConnectClientCredentials:
type: stringoauth2
requireddescription: true|
description: The parameterisedCommunications URLbetween of the API beingHub called byand the callerLFI Ozone Connect implementation are secured apiOperation:using a Client Credentials grant type.
name: o3-api-operation
in: header LFIs schema:must host an OAuth 2.0 Authorization Server to utilise type:this stringsecurity pattern. Scope values are set during required:the trueonboarding process, and represented by a placeholder description:in Thethis API operationdescription.
carried out by the caller (e.g. GET, POST, PUT, DELETE, PATCH)
flows:
clientCredentials:
consentId: name: o3-consent-idtokenUrl: "https://example.lfi.ae/token"
in: header scopes:
schema: typeplaceholder: stringPlaceholder for scopes, which are set by required:the trueLFI during onboarding
descriptionOzoneConnectJwtAuth:
The consentIddescription: for| which
this call is being made Communications between callerInteractionId:the API Hub and the LFI Ozone name: o3-caller-interaction-id
in: header
schema:
Connect implementation are secured using the "JWT Auth" mechanism, where the Client presents a signed JSON Web Token as a credential.
type: string
required: true The Server MUST description:verify Thethe interactionsignature IDin passedorder into byauthenticate the Client.
caller,
if any ozoneInteractionId: Please note that the value of name: o3-ozone-interaction-id
in: header
schema:
type: stringthe `scheme` parameter is not a registered HTTP Authentication Scheme, to indicate it is specific to Ozone Connect. Please refer to API Hub documentation for further details.
requiredtype: truehttp
descriptionscheme: 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: headerOzone-Connect-JWT-Auth
OzoneConnectServiceInitiationToken:
description: |
Communications between the API Hub and the LFI Ozone Connect implementation are secured using a Service Initiation Token.
schema: The API type:Hub stringwill set an Access Token based on required:a truevalue set by the LFI, which has description:been Apatched Base64onto encodedthe representationassociated ofconsent. theThe psuIdentifiervalue JSONwill object.be transmitted in the securitySchemes:`Authorization` header, which is represented bearerAuth:as a `Bearer` in this Security Scheme type:Object.
http
schemetype: bearerhttp
bearerFormatscheme: JWTBearer |
