diff --git a/SUMMARY.md b/SUMMARY.md index 5ade4e2f..a5cdf8f7 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -3,7 +3,9 @@ ### Documents * [Mojaloop Specifications Overview](README.md) * [Glossary](documents/Glossary.md) + * [Generic Transaction Patterns](documents/Generic Transaction Patterns.md) * [API Definition v1.0](documents/API Definition v1.0.md) + * [JSON Binding Rules](documents/JSON Binding Rules.md) * [Encryption](documents/Encryption.md) ### Change Control Board * [Change Control Board Overview](ccb-meetings/README.md) diff --git a/assets/diagrams/sequence/figure63.plantuml b/assets/diagrams/sequence/figure63.plantuml index c86e3cef..c46a4971 100644 --- a/assets/diagrams/sequence/figure63.plantuml +++ b/assets/diagrams/sequence/figure63.plantuml @@ -129,7 +129,7 @@ activate Switch autonumber stop PayerFSP <<-- Switch: **HTTP 202** (Accepted) autonumber resume -Switch ->> ALS: **GET /parties/MSISDN/123456789** +Switch ->> ALS: **GET /participants/MSISDN/123456789** activate ALS autonumber stop Switch <<-- ALS: **HTTP 202** (Accepted) diff --git a/assets/diagrams/sequence/figure63a.plantuml b/assets/diagrams/sequence/figure63a.plantuml new file mode 100644 index 00000000..b4abfa6b --- /dev/null +++ b/assets/diagrams/sequence/figure63a.plantuml @@ -0,0 +1,212 @@ +/'***** +License +-------------- +Copyright © 2017 Bill & Melinda Gates Foundation +The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at +http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. +Contributors +-------------- +This is the official list of the Mojaloop project contributors for this file. +Names of the original copyright holders (individuals or organizations) +should be listed with a '*' in the first column. People who have +contributed from an organization can be listed under the organization +that actually holds the copyright for their contributions (see the +Gates Foundation organization for an example). Those individuals should have +their names indented and be marked with a '-'. Email address can be added +optionally within square brackets . +* Gates Foundation +- Name Surname + +* Henk Kodde +-------------- +******'/ + +@startuml + +' define actor image +sprite $actor [25x48/16] { + 0000000000010000000000000 + 0000000006CAC910000000000 + 0000000095101292000000000 + 0000000651000119000000000 + 0000000B10000018400000000 + 0000001A10000016600000000 + 0000000B10000017510000000 + 000000083100001A210000000 + 0000000191000176110000000 + 000000003A866A61100000000 + 0000000000466211100000000 + 0003333333334443333310000 + 0088888888888888888892000 + 0821111111111111111118200 + 8311111111111111111111A00 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111551111111111138111A20 + A111661111111111139111A20 + A211661111111111139111A20 + A211661111111111139111A20 + A211661111161111139111A20 + A2116611111A2111139111A20 + A2116611111A2111139111A20 + A2116611111A2111139111A20 + A7669611111A211113A666B20 + 36669611111A211113A666610 + 00016611111A2111139111110 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006966666B7666679100000 + 0000266666666666664100000 + 0000000111111111111100000 + 0000000000000000000000000 +} + +' declaring skinparam +skinparam sequenceMessageAlign center +skinparam shadowing false +skinparam defaultFontName Verdana +skinparam monochrome true +skinparam SequenceLifeLineBackgroundColor WhiteSmoke +skinparam SequenceLifeLineBorderColor Black +skinparam ActorFontStyle Bold +skinparam ActorFontSize 20 +skinparam ParticipantFontStyle Bold +skinparam ParticipantFontSize 20 +skinparam ParticipantBackgroundColor WhiteSmoke +skinparam ArrowColor Black + +skinparam actor { + Bordercolor none + Backgroundcolor none + shadowing false +} + +skinparam participant { + shadowing true +} + +hide footbox + +' declare title +' title Payer-Initiated Transaction + +' Actor Keys: +' participant - FSP(Payer/Payee), Switch and Account Lookup +' actor - Payer/Payee(s) + +' declare actors +actor "<$actor>\nPayer" as Payer +participant "Payer\nFSP" as PayerFSP +participant "Optional\nSwitch" as Switch +participant "Account\nLookup" as ALS +participant "Payee\nFSP" as PayeeFSP +actor "<$actor>\nPayee" as Payee + +' start flow +autonumber 1 1 "[0]" +Payer -> PayerFSP: I would like to\npay 100 USD\nto +123456789 +activate PayerFSP +PayerFSP -> PayerFSP: Payee not within\nPayer FSP system +autonumber stop +PayerFSP ->> Switch: **Lookup Party Information**\n(MSISDN 123456789) +activate Switch +autonumber resume +Switch ->> ALS: **Lookup Participant Information**\n(MSISDN 123456789) +activate ALS +ALS -> ALS: Lookup which\nFSP MSISDN\n+123456789\nbelongs to +autonumber stop +Switch <<- ALS: **Return Participant Information**\n(FSP ID) +deactivate ALS +autonumber resume +Switch ->> PayeeFSP: **Lookup Party Information**\n(MSISDN 123456789) +activate PayeeFSP +PayeeFSP -> PayeeFSP: Lookup party\ninformation\nregarding\nMSISDN\n+123456789 +autonumber stop +Switch <<- PayeeFSP: **Return Party Information**\n(Party Information) +deactivate PayeeFSP +autonumber resume +PayerFSP <<- Switch: **Return Party Information**\n(Party Information) +deactivate Switch +deactivate PayerFSP +PayerFSP -> PayerFSP: Rate Payer FSP quote\n(depending on fee model) +activate PayerFSP +PayerFSP ->> Switch: **Calculate Quote**\n(Transaction details) +activate Switch +Switch ->> PayeeFSP: **Calculate Quote**\n(Transaction details) +activate PayeeFSP +PayeeFSP -> PayeeFSP: Rate Payee FSP\nfee/commission,\ngenerate condition +group #OldLace Optional + hnote left of PayeeFSP #OldLace + Confirm quote + end hnote + PayeeFSP -> Payee: Here is the\nquote and\nPayer name + autonumber stop + PayeeFSP <- Payee: I confirm +end +autonumber resume +Switch <<- PayeeFSP: **Return Quote Information**\n(Payee FSP fee/commission,\ncondition) +deactivate PayeeFSP +PayerFSP <<- Switch: **Return Quote Information**\n(Payee FSP fee/commission,\ncondition) +deactivate Switch +PayerFSP -> PayerFSP: Rate Payer FSP quote\n(depending on fee model) +autonumber stop +Payer <- PayerFSP: Present fees and\noptionally payee name +deactivate PayerFSP +autonumber resume +Payer -> PayerFSP: I approve the\ntransaction +activate PayerFSP +autonumber stop +PayerFSP -> PayerFSP: Reserve transfer from Payer\naccount to Switch account +autonumber resume +PayerFSP -> Switch: **Preform Transfers**\n(Transfer ID, condition, ILP packet\nincluding transaction ID) +activate Switch +Switch -> Switch: Reserve transfer from\nPayer FSP to Payee FSP +autonumber stop +Switch ->> PayeeFSP: **Perform Transfer**\n(Transfer ID, condition, ILP packet\nincluding transaction ID) +activate PayeeFSP +autonumber resume +PayeeFSP -> PayeeFSP: Perform transfer\nfrom Switch\naccount to Payee\naccount, generate\nfulfilment +PayeeFSP -> Payee: Transaction notification +autonumber stop +Switch <<- PayeeFSP: **Return Transfer Information**\n(Fulfilment) +deactivate PayeeFSP +autonumber resume +Switch -> Switch: Commit transfer from\nPayer FSP to Payee FSP +autonumber stop +PayerFSP <<- Switch: **Return Transfer Information**\n(Fulfilment) +deactivate Switch +autonumber resume +PayerFSP -> PayerFSP: Commit transfer from Payer\naccount to Switch account +group #OldLace Optional + hnote left of PayerFSP #OldLace + Get transaction data + end hnote + PayerFSP ->> Switch: **Retrieve Transaction Information**\n(Transaction ID) + activate Switch + Switch <<- PayeeFSP: **Retrieve Transaction Information**\n(Transaction ID) + activate PayeeFSP + PayeeFSP -> PayeeFSP: Lookup\ntransaction\ninformation + Switch <<- PayeeFSP: **Return Transaction Information**\n(Transaction details) + deactivate PayeeFSP + PayerFSP <<- Switch: **Return Transaction Information**\n(Transaction details) + deactivate Switch +end +Payer <- PayerFSP: Transaction notification\nincluding optional\ntransaction data\n(e.g. token ID) +deactivate PayerFSP +autonumber stop +@enduml diff --git a/assets/diagrams/sequence/figure64.plantuml b/assets/diagrams/sequence/figure64.plantuml index 9737041e..3a549cf6 100644 --- a/assets/diagrams/sequence/figure64.plantuml +++ b/assets/diagrams/sequence/figure64.plantuml @@ -127,7 +127,7 @@ ALS <<- PayeeFSP: **GET /participants/MSISDN/123456789** activate ALS ALS -->> PayeeFSP: **HTTP 202** (Accepted) autonumber resume -ALS -> ALS: Lookup which FSP MSISDN\n+123456789 belongins to +ALS -> ALS: Lookup which FSP MSISDN\n+123456789 belongs to ALS ->> PayeeFSP: **PUT /participants/MSISDN/123456789**\n(FSP ID) autonumber stop ALS <<-- PayeeFSP: **HTTP 200** (OK) diff --git a/assets/diagrams/sequence/figure64a.plantuml b/assets/diagrams/sequence/figure64a.plantuml new file mode 100644 index 00000000..889066cc --- /dev/null +++ b/assets/diagrams/sequence/figure64a.plantuml @@ -0,0 +1,235 @@ +/'***** +License +-------------- +Copyright © 2017 Bill & Melinda Gates Foundation +The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at +http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. +Contributors +-------------- +This is the official list of the Mojaloop project contributors for this file. +Names of the original copyright holders (individuals or organizations) +should be listed with a '*' in the first column. People who have +contributed from an organization can be listed under the organization +that actually holds the copyright for their contributions (see the +Gates Foundation organization for an example). Those individuals should have +their names indented and be marked with a '-'. Email address can be added +optionally within square brackets . +* Gates Foundation +- Name Surname + +* Henk Kodde +-------------- +******'/ + +@startuml + +' define actor image +sprite $actor [25x48/16] { + 0000000000010000000000000 + 0000000006CAC910000000000 + 0000000095101292000000000 + 0000000651000119000000000 + 0000000B10000018400000000 + 0000001A10000016600000000 + 0000000B10000017510000000 + 000000083100001A210000000 + 0000000191000176110000000 + 000000003A866A61100000000 + 0000000000466211100000000 + 0003333333334443333310000 + 0088888888888888888892000 + 0821111111111111111118200 + 8311111111111111111111A00 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111551111111111138111A20 + A111661111111111139111A20 + A211661111111111139111A20 + A211661111111111139111A20 + A211661111161111139111A20 + A2116611111A2111139111A20 + A2116611111A2111139111A20 + A2116611111A2111139111A20 + A7669611111A211113A666B20 + 36669611111A211113A666610 + 00016611111A2111139111110 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006966666B7666679100000 + 0000266666666666664100000 + 0000000111111111111100000 + 0000000000000000000000000 +} + +' declaring skinparam +skinparam sequenceMessageAlign center +skinparam shadowing false +skinparam defaultFontName Verdana +skinparam monochrome true +skinparam SequenceLifeLineBackgroundColor WhiteSmoke +skinparam SequenceLifeLineBorderColor Black +skinparam ActorFontStyle Bold +skinparam ActorFontSize 20 +skinparam ParticipantFontStyle Bold +skinparam ParticipantFontSize 20 +skinparam ParticipantBackgroundColor WhiteSmoke +skinparam ArrowColor Black + +skinparam actor { + Bordercolor none + Backgroundcolor none + shadowing false +} + +skinparam participant { + shadowing true +} + +hide footbox + +' declare title +' title Payee Initiated Transaction + +' Actor Keys: +' participant - FSP(Payer/Payee), Switch and Account Lookup +' actor - Payer/Payee(s) + +' declare actors +actor "<$actor>\nPayer" as Payer +participant "Payer\nFSP" as PayerFSP +participant "Optional\nSwitch" as Switch +participant "Account\nLookup" as ALS +participant "Payee\nFSP" as PayeeFSP +actor "<$actor>\nPayee" as Payee + +' start flow +autonumber 1 1 "[0]" +PayeeFSP <- Payee: I would like\nto receive\n100 USD from\n+123456789 +activate PayeeFSP +PayeeFSP <- PayeeFSP: Payer not\nwithin Payee\nFSP system +autonumber stop +ALS <<- PayeeFSP: **Lookup Participant Information**\n(MSISDN 123456789) +activate ALS +autonumber resume +ALS -> ALS: Lookup which FSP MSISDN\n+123456789 belongs to +ALS ->> PayeeFSP: **Returns Participant Information**\n(FSP ID) +deactivate ALS +deactivate PayeeFSP +Switch <<- PayeeFSP: **Perform Transaction Request**\n(Payee information, transaction details) +activate PayeeFSP +activate Switch +PayerFSP <<- Switch: **Perform Transaction Request**\n(Payee information,\ntransaction details) +activate PayerFSP +deactivate Switch +PayerFSP -> PayerFSP: Perform optional validation +PayerFSP ->> Switch: **Return Transaction**\n**Request Information**\n(Received status) +activate Switch +deactivate PayerFSP +Switch ->> PayeeFSP: **Return Transaction Request Information**\n(Received status) +deactivate PayeeFSP +deactivate Switch +activate PayerFSP +PayerFSP -> PayerFSP: Rate Payer FSP quote\n(depending on fee model) +autonumber stop +PayerFSP ->> Switch: **Calculate Quote**\n(Transaction detail) +activate Switch +autonumber resume +Switch ->> PayeeFSP: **Calculate Quote**\n(Transaction details) +activate PayeeFSP +PayeeFSP -> PayeeFSP: Rate Payee FSP\nfees/commission,\ngenerate condition +group #OldLace Optional + hnote left of PayeeFSP #OldLace + Confirm quote + end hnote + PayeeFSP -> Payee: Here is the\nquote and\nPayer name + autonumber stop + PayeeFSP <- Payee: I confirm +end +autonumber resume +Switch <<- PayeeFSP: **Return Quote Information**\n(Payee FSP fee/commission,condition) +deactivate PayeeFSP +PayerFSP <<- Switch: **Return Quote Information**\n(Payee FSP\nfee/commission,condition) +deactivate Switch +PayerFSP -> PayerFSP: Rate Payer FSP quote\n(depending on the fee model) +Payer <- PayerFSP: Will you approve\ntransaction\nrequest for\n100 USD(plusfees)\nto Payee? +deactivate PayerFSP +Alt #OldLace Alternatives + hnote over of Payer #OldLace + User rejects + transaction request + end hnote + Payer -> PayerFSP: I reject the\ntransaction request + activate PayerFSP + PayerFSP ->> Switch: **Return Transaction**\n**Request Information**\n(Rejected state) + activate Switch + deactivate PayerFSP + Switch ->> PayeeFSP: **Return Transaction Request Information**\n(Rejected state) + activate PayeeFSP + deactivate Switch + PayeeFSP -> Payee: Transaction failed\ndue to user\nrejection + deactivate PayeeFSP + autonumber stop +else + hnote over of Payer #OldLace + User rejects + transaction request + end hnote + Payer -> PayerFSP: I approve the\ntransaction request + activate PayerFSP + autonumber resume + PayerFSP -> PayerFSP: Reserve transfer from Payer\naccount to Switch account + autonumber stop + PayerFSP ->> Switch: **Perform Transfer**\n(Transfer ID, condition, ILP packet\nincluding transaction ID) + activate Switch + autonumber resume + Switch -> Switch: Reserve transfer\nfrom Payer\nFSP to Payee FSP + autonumber stop + Switch ->> PayeeFSP: **Perform Transfer**\n(Transfer ID, condition, ILP packet\nincluding transaction ID) + activate PayeeFSP + autonumber resume + PayeeFSP -> PayeeFSP: Perform transfer\nfrom Switch account\nto Payee account,\ngenerate fulfilment + PayeeFSP -> Payee: Transaction\nnotification + autonumber stop + Switch <<- PayeeFSP: **Retrun Transfer Information**\n(Fulfilment) + deactivate PayeeFSP + autonumber resume + Switch -> Switch: Commit transfer\nfrom Payer FSP\nto Payee FSP + autonumber stop + PayerFSP <<- Switch: **Return Transfer Information**\n(Fulfilment) + deactivate Switch + autonumber resume + PayerFSP -> PayerFSP: Commit transfer from Payer\naccount to Payee FSP account + group #LightGrey Optional + hnote over PayerFSP #LightGrey + Get transaction data + end hnote + PayerFSP ->> Switch: **Retrieve Transaction Information**\n(Transaction ID) + activate Switch + Switch ->> PayeeFSP: **Retrieve Transaction Information**\n(Transaction ID) + activate PayeeFSP + PayeeFSP -> PayeeFSP: Looksup transaction\ninformation + Switch <<- PayeeFSP: **Return Transaction Information**\n(Transaction detail) + deactivate PayeeFSP + PayerFSP <<- Switch: **Return Transaction Information**\n(Transaction detail) + deactivate Switch + end + Payer <- PayerFSP: Transaction\nnotification + deactivate PayerFSP +end +autonumber stop +@enduml diff --git a/assets/diagrams/sequence/figure65.plantuml b/assets/diagrams/sequence/figure65.plantuml index 396d1bc0..8d20d218 100644 --- a/assets/diagrams/sequence/figure65.plantuml +++ b/assets/diagrams/sequence/figure65.plantuml @@ -176,12 +176,12 @@ activate PayerFSP PayerFSP ->> Switch: **POST /qoutes**\n(Transaction details) activate Switch autonumber stop -PayerFSP <<-- Switch: **HTTL 202**\n(Accepted) +PayerFSP <<-- Switch: **HTTP 202**\n(Accepted) autonumber resume Switch ->> PayeeFSP: **POST /qoutes**\n(Transaction details) activate PayeeFSP autonumber stop -Switch <<-- PayeeFSP: **HTTL 202**\n(Accepted) +Switch <<-- PayeeFSP: **HTTP 202**\n(Accepted) PayeeFSP -> PayeeFSP: Rate Payee FSP\nfees/commission,\ngenerate condition Group #Oldlace Optional hnote left of PayeeFSP #Oldlace @@ -194,7 +194,7 @@ Group #Oldlace Optional PayeeFSP <- Payee: I confirm end autonumber resume -Switch <<- PayeeFSP: **PUT /authorizations/** \n(Amount and fees) +Switch <<- PayeeFSP: **PUT /quote/**\n(Payee FSP fee/commission,\ncondition) autonumber stop Switch -->> PayeeFSP: **HTTP 200** (OK) deactivate PayeeFSP @@ -276,13 +276,13 @@ else autonumber 33 1 PayerFSP -> PayerFSP: Reserve transfer from Payer\naccount to Switch account autonumber stop - PayerFSP ->> Switch: **POST /transfers**\n(Transfer ID, condition,\nILP packet including transaction ID)\n + PayerFSP ->> Switch: **POST /transfers**\n(Transfer ID, condition,\nILP packet including transaction ID) activate Switch PayerFSP <<-- Switch: **HTTP 202** (Accepted) autonumber resume Switch -> Switch: Reserve transfer\nfrom Payer FSP\nto Payee FSP autonumber stop - Switch ->> PayeeFSP: **POST /transfers**\n(Transfer ID, condition, \nILP packet including transaction ID)\n + Switch ->> PayeeFSP: **POST /transfers**\n(Transfer ID, condition, \nILP packet including transaction ID) activate PayeeFSP Switch <<-- PayeeFSP: **HTTP 202** (Accepted) autonumber resume @@ -318,9 +318,9 @@ else autonumber resume PayeeFSP -> PayeeFSP: Lookup\ntransaction\ninformation autonumber resume - Switch ->> PayeeFSP: **PUT /transactions/**\n(Transaction detail) + Switch <<- PayeeFSP: **PUT /transactions/**\n(Transaction detail) autonumber stop - Switch <<-- PayeeFSP: **HTTP 200** (OK) + Switch -->> PayeeFSP: **HTTP 200** (OK) deactivate PayeeFSP autonumber resume PayerFSP ->> Switch: **PUT /transactions/**\n(Transaction detail) diff --git a/assets/diagrams/sequence/figure65a.plantuml b/assets/diagrams/sequence/figure65a.plantuml new file mode 100644 index 00000000..849e705f --- /dev/null +++ b/assets/diagrams/sequence/figure65a.plantuml @@ -0,0 +1,278 @@ +/'***** +License +-------------- +Copyright © 2017 Bill & Melinda Gates Foundation +The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at +http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. +Contributors +-------------- +This is the official list of the Mojaloop project contributors for this file. +Names of the original copyright holders (individuals or organizations) +should be listed with a '*' in the first column. People who have +contributed from an organization can be listed under the organization +that actually holds the copyright for their contributions (see the +Gates Foundation organization for an example). Those individuals should have +their names indented and be marked with a '-'. Email address can be added +optionally within square brackets . +* Gates Foundation +- Name Surname + +* Henk Kodde +-------------- +******'/ + +@startuml + +' define actor image +sprite $actor [25x48/16] { + 0000000000010000000000000 + 0000000006CAC910000000000 + 0000000095101292000000000 + 0000000651000119000000000 + 0000000B10000018400000000 + 0000001A10000016600000000 + 0000000B10000017510000000 + 000000083100001A210000000 + 0000000191000176110000000 + 000000003A866A61100000000 + 0000000000466211100000000 + 0003333333334443333310000 + 0088888888888888888892000 + 0821111111111111111118200 + 8311111111111111111111A00 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111551111111111138111A20 + A111661111111111139111A20 + A211661111111111139111A20 + A211661111111111139111A20 + A211661111161111139111A20 + A2116611111A2111139111A20 + A2116611111A2111139111A20 + A2116611111A2111139111A20 + A7669611111A211113A666B20 + 36669611111A211113A666610 + 00016611111A2111139111110 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006966666B7666679100000 + 0000266666666666664100000 + 0000000111111111111100000 + 0000000000000000000000000 +} + +' declaring skinparam +skinparam sequenceMessageAlign center +skinparam shadowing false +skinparam defaultFontName Verdana +skinparam monochrome true +skinparam SequenceLifeLineBackgroundColor WhiteSmoke +skinparam SequenceLifeLineBorderColor Black +skinparam ActorFontStyle Bold +skinparam ActorFontSize 20 +skinparam ParticipantFontStyle Bold +skinparam ParticipantFontSize 20 +skinparam ParticipantBackgroundColor WhiteSmoke +skinparam ArrowColor Black + +skinparam actor { + Bordercolor none + Backgroundcolor none + shadowing false +} + +skinparam participant { + shadowing true +} + +hide footbox + +' declare title +' title Payee-Initiated Transaction using OTP + +' Actor Keys: +' participant - FSP(Payer/Payee), Switch and Account Lookup +' actor - Payer/Payee(s) + +' declare actors +actor "<$actor>\nPayer" as Payer +participant "Payer\nFSP" as PayerFSP +participant "Optional\nSwitch" as Switch +participant "Account\nLookup" as ALS +participant "Payee\nFSP" as PayeeFSP +actor "<$actor>\nPayee" as Payee + +' start flow +autonumber 1 1 "[0]" +Group #Oldlace Option #1 + hnote left of Payer #Oldlace + User + initiated + OTP + end hnote + Payer -> PayerFSP: Generate\nOTP for me + activate PayerFSP + PayerFSP -> PayerFSP: Generate OTP + Payer <- PayerFSP: Your OTP\nis 12345 + deactivate PayerFSP +end +PayeeFSP <- Payee: I would like\nto receive\n100 USD from\n+123456789 +activate PayeeFSP +autonumber stop +PayeeFSP <- PayeeFSP: MSISDN not within\nPayee FSP system +autonumber resume +ALS <<- PayeeFSP: **Lookup Participant Information**\n(MSISDN 123456789) +activate ALS +ALS <- ALS: Lookup which FSP MSISDN\n+123456789 belongs to +ALS -> PayeeFSP: **Return Participant Information**\n(FSP ID) +deactivate ALS +deactivate PayeeFSP +Switch <<- PayeeFSP: **Perform Transaction Request**\n(Payee information, transaction details, OTP authorization) +activate PayeeFSP +activate Switch +PayerFSP <<- Switch: **Perform Transaction Request**\n(Payee information,\ntransaction details, OTP authorization) +activate PayerFSP +autonumber stop +autonumber resume +PayerFSP -> PayerFSP: Perform optional validation +PayerFSP ->> Switch: **Return Transaction**\n**Request Information**\n(Received status) +deactivate PayerFSP +autonumber resume +Switch ->> PayeeFSP: **Return Transaction Request Information**\n(Received status) +deactivate Switch +deactivate PayeeFSP +PayerFSP -> PayerFSP: Rate Payer FSP quote\n(depending on fee model) +activate PayerFSP +autonumber stop +PayerFSP ->> Switch: **Calculate Quote**\n(Transaction details) +activate Switch +autonumber resume +Switch ->> PayeeFSP: **Calculate Quote**\n(Transaction details) +activate PayeeFSP +PayeeFSP -> PayeeFSP: Rate Payee FSP\nfees/commission,\ngenerate condition +Group #Oldlace Optional + hnote left of PayeeFSP #Oldlace + Confirm + quote + end hnote + autonumber resume + PayeeFSP -> Payee: Her is the\nquote and\nPayer name + autonumber stop + PayeeFSP <- Payee: I confirm +end +autonumber resume +Switch <<- PayeeFSP: **Return Quote Information**\n(Payee FSP fee/commision, condition) +deactivate PayeeFSP +PayerFSP <<- Switch: **Return Quote Information**\n(Payee FSP fee/commission,\ncondition) +deactivate Switch +PayerFSP -> PayerFSP: Rate Payer FSP quote\n(depending on fee model) +deactivate PayerFSP +Group #Oldlace Option #2 + hnote left of Payer #Oldlace + Automatic + generated + OTP + end hnote + autonumber resume + PayerFSP -> PayerFSP: Generate OTP + activate PayerFSP + Payer <- PayerFSP: Use OTP\nto confirm +end +PayerFSP ->> Switch: **Perform Authorization**\n(Amount and fees) +activate Switch +Switch ->> PayeeFSP: **Perform Authorization**\n(Amount and fees) +activate PayeeFSP +PayeeFSP -> Payee: Show fees\non POS +Payee -> Payee: Payer\napproves/rejects\ntransaction\nusing OTP +autonumber stop +PayeeFSP <<-- Payee: Entered OTP +autonumber resume +Switch <<- PayeeFSP: **Return Authorization Result**\n(OTP) +deactivate PayeeFSP +PayerFSP <<- Switch: **Return Authorization Result**\n(OTP) +autonumber stop +PayerFSP -->> Switch: **HTTP 200** (OK) +deactivate Switch +autonumber resume +PayerFSP -> PayerFSP: Validate OTP sent by Payee FSP +deactivate PayerFSP +Group #Oldlace Alternatives + hnote left of Payer #Oldlace + OTP + validation + failed + end hnote + PayerFSP ->> Switch: **Return Transaction Request Information**\n(Rejected state) + activate PayerFSP + activate Switch + deactivate PayerFSP + Switch ->> PayeeFSP: **Return Transaction Request Information**\n(Rejected state) + activate PayeeFSP + deactivate Switch + PayeeFSP -> Payee: Transaction\nfailed due to\nincorrect OTP + deactivate PayeeFSP + autonumber stop +else + hnote left of Payer #Oldlace + OTP + validation + successful + end hnote + autonumber 33 1 + PayerFSP -> PayerFSP: Reserve transfer from Payer\naccount to Switch account + activate PayerFSP + autonumber stop + PayerFSP ->> Switch: **Perform Transfer**\n(Transfer ID, condition, ILP packet\nincluding transaction ID) + activate Switch + autonumber resume + Switch -> Switch: Reserve transfer\nfrom Payer FSP\nto Payee FSP + autonumber stop + Switch ->> PayeeFSP: **Perform Transfer**\n(Transfer ID, condition, \nILP packet including transaction ID)\n + activate PayeeFSP + autonumber resume + PayeeFSP -> PayeeFSP: Perform transfer\nfrom Switch account\nto Payee account,\ngenerate fulfilment + PayeeFSP -> Payee: Transaction\nnotification + autonumber stop + Switch <<- PayeeFSP: **Return Transfer Information**\n(Fulfilment) + deactivate PayeeFSP + autonumber resume + Switch -> Switch: Commit transfer\nfrom Payer FSP\nto Payee FSP + autonumber stop + PayerFSP <<- Switch: **Return Transfer Information**\n(Fulfilment) + deactivate Switch + autonumber resume + PayerFSP -> PayerFSP: Commits transfer from Payer\naccount to Payee FSP account + Group #Lightgrey Optional + hnote left of PayerFSP #Lightgrey + Get transaction + data + end hnote + PayerFSP ->> Switch: **Retrieve Transaction Information**\n(Transaction ID) + activate Switch + Switch ->> PayeeFSP: **Retrieve Transaction Information**\n(Transaction ID) + activate PayeeFSP + PayeeFSP -> PayeeFSP: Lookup\ntransaction\ninformation + Switch <<- PayeeFSP: **Return Transaction Information**\n(Transaction details) + deactivate PayeeFSP + PayerFSP ->> Switch: Return Transaction Information**\n(Transaction details) + deactivate Switch + end + Payer <- PayerFSP: Transaction\nnotification + deactivate PayerFSP +end +@enduml diff --git a/assets/diagrams/sequence/figure66.plantuml b/assets/diagrams/sequence/figure66.plantuml index 96267f8f..4ac3ad2a 100644 --- a/assets/diagrams/sequence/figure66.plantuml +++ b/assets/diagrams/sequence/figure66.plantuml @@ -127,18 +127,19 @@ Loop #Oldlace transaction in bulk file end hnote + PayerFSP -> PayerFSP: Locate Payee, if not\nwithin Payer FSP\nuse Account Lookup PayerFSP ->> ALS: **GET /participants/** **/** activate ALS autonumber stop PayerFSP <<-- ALS: **HTTP 202** (Accepted) autonumber resume ALS -> ALS: Lookup FSP for\nrequested Type/ID - PayerFSP ->> ALS: **GET /participants/** **/** autonumber stop + PayerFSP ->> ALS: **PUT /participants/** **/** PayerFSP <<-- ALS: **HTTP 202** (Accepted) deactivate ALS autonumber resume - PayerFSP -> PayerFSP: Placetransaction\nin bulk file\nper Payee FSP + PayerFSP -> PayerFSP: Place transaction\nin bulk file\nper Payee FSP autonumber stop end Loop ... @@ -162,18 +163,19 @@ Loop #Oldlace activate Switch autonumber resume PayeeFSP -> PayeeFSP: Rate Payee FSP\nfee/commission and\ngenerate condition per\nindividual transfer - Switch <<- PayeeFSP: PUT /bulkQuotes/\n(List of individual quote results\nand condition per transfer) autonumber stop + Switch <<- PayeeFSP: **PUT /bulkQuotes/**\n(List of individual quote results\nand condition per transfer) Switch -->> PayeeFSP: **HTTP 200** (OK) deactivate PayeeFSP autonumber resume - PayerFSP <<- Switch: PUT /bulkQuotes/\n(List of individual quote results\nand condition per transfer) + PayerFSP <<- Switch: **PUT /bulkQuotes/**\n(List of individual quote results\nand condition per transfer) autonumber stop PayerFSP -->> Switch: **HTTP 200** (OK) deactivate Switch + autonumber resume PayerFSP -> PayerFSP: Rate Payer FSP bulk quote\n(depending on fee model) end Loop -autonumber resume + PayerFSP -> PayerFSP: Calculate total fee for Payer Payer <- PayerFSP: Bulk has finished processing,\npresent fees deactivate PayerFSP @@ -187,31 +189,31 @@ Loop #Oldlace Payee FSP end hnote PayerFSP -> PayerFSP: Reserve each individual\ntransfer from Payer\naccount to Payee FSP account + autonumber stop PayerFSP ->> Switch: **POST /bulkTransfers**\n(List of individual transfers\nincluding ILP packet and condition) activate Switch - autonumber stop PayerFSP <<-- Switch: **HTTP 202** (Accepted) - Switch -> Switch: Reserve each individual\ntransfer from Payer FSP\nto Payee FSP autonumber resume + Switch -> Switch: Reserve each individual\ntransfer from Payer FSP\nto Payee FSP + autonumber stop Switch ->> PayeeFSP: **POST /bulkTransfers**\n(List of individual transfers\nincluding ILP packet and condition) activate PayeeFSP - autonumber stop Switch <<-- PayeeFSP: **HTTP 202** (Accepted) - PayeeFSP -> PayeeFSP: Perform each transaction from\nPayer FSP account to Payee\naccount, generate fulfilments autonumber resume + PayeeFSP -> PayeeFSP: Perform each transaction from\nPayer FSP account to Payee\naccount, generate fulfilments PayeeFSP -> Payee: Transaction notification\nfor each Payee - Switch <<- PayeeFSP: **PUT /bulkTransfers**\n(List of fulfilments) + Switch <<- PayeeFSP: **PUT /bulkTransfers/**\n(List of fulfilments) autonumber stop Switch -->> PayeeFSP: **HTTP 200** (OK) deactivate PayeeFSP Switch -> Switch: Commit each successful\ntransfer from Payer\nFSP to Payee FSP autonumber resume - PayerFSP <<- Switch: **PUT /bulkTransfers**\n(List of fulfilments) + PayerFSP <<- Switch: **PUT /bulkTransfers/**\n(List of fulfilments) autonumber stop PayerFSP -->> Switch: **HTTP 200** (OK) deactivate Switch - PayerFSP -> PayerFSP: Commit each successful\ntransfer from Payer account\nto Payee FSP account autonumber resume + PayerFSP -> PayerFSP: Commit each successful\ntransfer from Payer account\nto Payee FSP account end Loop Payer <- PayerFSP: Your bulk has been executed deactivate PayerFSP diff --git a/assets/diagrams/sequence/figure66a.plantuml b/assets/diagrams/sequence/figure66a.plantuml new file mode 100644 index 00000000..587538d5 --- /dev/null +++ b/assets/diagrams/sequence/figure66a.plantuml @@ -0,0 +1,198 @@ +/'***** +License +-------------- +Copyright © 2017 Bill & Melinda Gates Foundation +The Mojaloop files are made available by the Bill & Melinda Gates Foundation under the Apache License, Version 2.0 (the "License") and you may not use these files except in compliance with the License. You may obtain a copy of the License at +http://www.apache.org/licenses/LICENSE-2.0 +Unless required by applicable law or agreed to in writing, the Mojaloop files are distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. +Contributors +-------------- +This is the official list of the Mojaloop project contributors for this file. +Names of the original copyright holders (individuals or organizations) +should be listed with a '*' in the first column. People who have +contributed from an organization can be listed under the organization +that actually holds the copyright for their contributions (see the +Gates Foundation organization for an example). Those individuals should have +their names indented and be marked with a '-'. Email address can be added +optionally within square brackets . +* Gates Foundation +- Name Surname + +* Henk Kodde +-------------- +******'/ + +@startuml + +' define actor image +sprite $actor [25x48/16] { + 0000000000010000000000000 + 0000000006CAC910000000000 + 0000000095101292000000000 + 0000000651000119000000000 + 0000000B10000018400000000 + 0000001A10000016600000000 + 0000000B10000017510000000 + 000000083100001A210000000 + 0000000191000176110000000 + 000000003A866A61100000000 + 0000000000466211100000000 + 0003333333334443333310000 + 0088888888888888888892000 + 0821111111111111111118200 + 8311111111111111111111A00 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111111111111111111111A20 + A111551111111111138111A20 + A111661111111111139111A20 + A211661111111111139111A20 + A211661111111111139111A20 + A211661111161111139111A20 + A2116611111A2111139111A20 + A2116611111A2111139111A20 + A2116611111A2111139111A20 + A7669611111A211113A666B20 + 36669611111A211113A666610 + 00016611111A2111139111110 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006611111A2111139100000 + 00006966666B7666679100000 + 0000266666666666664100000 + 0000000111111111111100000 + 0000000000000000000000000 +} + +' declaring skinparam +skinparam sequenceMessageAlign center +skinparam shadowing false +skinparam defaultFontName Verdana +skinparam monochrome true +skinparam SequenceLifeLineBackgroundColor WhiteSmoke +skinparam SequenceLifeLineBorderColor Black +skinparam ActorFontStyle Bold +skinparam ActorFontSize 20 +skinparam ParticipantFontStyle Bold +skinparam ParticipantFontSize 20 +skinparam ParticipantBackgroundColor WhiteSmoke +skinparam ArrowColor Black + +skinparam actor { + Bordercolor none + Backgroundcolor none + shadowing false +} + +skinparam participant { + shadowing true +} + +hide footbox + +' declare title +' title Bulk Transaction + +' Actor Keys: +' participant - FSP(Payer/Payee(s)), Switch and Account Lookup Services (ALS) +' actor - Payer/Payee(s) + +' declare actors +actor "<$actor>\nPayer\n" as Payer +participant "\nPayer\nFSP" as PayerFSP +participant "\nOptional\nSwitch" as Switch +participant "\nAccount\nLookup" as ALS +participant "\nPayee\nFSP(s)" as PayeeFSP +actor "<$actor>\nPayees\n(multiple)" as Payee + +' start flow +autonumber 1 1 "[0]" +Payer -> PayerFSP: I would like to upload\na file of bulk transactions +activate PayerFSP +Loop #Oldlace + hnote left of PayerFSP #Oldlace + For each + transaction + in bulk file + end hnote + PayerFSP -> PayerFSP: Locate Payee, if not\nwithin Payer FSP\nuse Account Lookup + PayerFSP ->> ALS: **Lookup Participant Information**\n(Payee Party ID Type and Party ID) + activate ALS + ALS -> ALS: Lookup FSP for\nrequested Type/ID + PayerFSP ->> ALS: **Return Participant Information**\n(FSP ID) + autonumber stop + deactivate ALS + PayerFSP -> PayerFSP: Place transaction\nin bulk file\nper Payee FSP +end Loop +... +Loop #Oldlace + hnote left of PayerFSP #Oldlace + For each + created bulk + file per + Payee FSP + end hnote + PayerFSP -> PayerFSP: Rate Payer FSP bulk quote\n(depending on fee model) + autonumber resume + PayerFSP ->> Switch: **Calculate Bulk Quote**\n(Bulk info and list\nof individual quotes) + Switch ->> PayeeFSP: **Calculate Bulk Quote**\n(Bulk info and list of individual quotes) + activate PayeeFSP + activate Switch + PayeeFSP -> PayeeFSP: Rate Payee FSP\nfee/commission and\ngenerate condition per\nindividual transfer + autonumber stop + Switch <<- PayeeFSP: **Return Bulk Quote Information**\n(List of individual quote results\nand condition per transfer) + deactivate PayeeFSP + autonumber resume + PayerFSP <<- Switch: **Return Bulk Quote Information**\n(List of individual quote results\nand condition per transfer) + deactivate Switch + PayerFSP -> PayerFSP: Rate Payer FSP bulk quote\n(depending on fee model) +end Loop +autonumber resume +PayerFSP -> PayerFSP: Calculate total fee for Payer +Payer <- PayerFSP: Bulk has finished processing,\npresent fees +deactivate PayerFSP +Payer -> PayerFSP: Execute my bulk +activate PayerFSP +Loop #Oldlace + hnote left of PayerFSP #Oldlace + For each + created bulk + file per + Payee FSP + end hnote + PayerFSP -> PayerFSP: Reserve each individual\ntransfer from Payer\naccount to Payee FSP account +autonumber stop + PayerFSP ->> Switch: **Perform Bulk Transfer**\n(List of individual transfers\nincluding ILP packet and condition) + activate Switch +autonumber resume + Switch -> Switch: Reserve each individual\ntransfer from Payer FSP\nto Payee FSP + autonumber stop + Switch ->> PayeeFSP: **Perform Bulk Transfer**\n(List of individual transfers\nincluding ILP packet and condition) + activate PayeeFSP +autonumber resume + PayeeFSP -> PayeeFSP: Perform each transaction from\nPayer FSP account to Payee\naccount, generate fulfilments + PayeeFSP -> Payee: Transaction notification\nfor each Payee + Switch <<- PayeeFSP: **Return Bulk Transfer Information**\n(List of fulfilments) + autonumber stop + deactivate PayeeFSP + Switch -> Switch: Commit each successful\ntransfer from Payer\nFSP to Payee FSP + autonumber resume + PayerFSP <<- Switch: **Return Bulk Transfer Information**\n(List of fulfilments) + deactivate Switch + PayerFSP -> PayerFSP: Commit each successful\ntransfer from Payer account\nto Payee FSP account +end Loop +Payer <- PayerFSP: Your bulk has been executed +deactivate PayerFSP +@enduml diff --git a/documents/Generic Transaction Patterns.md b/documents/Generic Transaction Patterns.md new file mode 100644 index 00000000..babddc75 --- /dev/null +++ b/documents/Generic Transaction Patterns.md @@ -0,0 +1,1806 @@ +# Generic Transaction Patterns + +## Open API for FSP Interoperability Specification + +**Table of Contents** + +[1. Preface](#1-preface) + +[1.1 Conventions Used in This Document](#11-conventions-used-in-this-document) + +[1.2 Document Version Information](#12-document-version-information) + +[2. Introduction](#2-introduction) + +[2.1 Open API for FSP Interoperability Specification](#21-open-api-for-fsp-interoperability-specification) + +[3. Logical API Services](#3-logical-api-services) + +[3.1 Common Functionality](#31-common-functionality) + +[3.2 API Resource Participants](#32-api-resource-participants) + +[3.3 API Resource Parties](#33-api-resource-parties) + +[3.4 API Resource Transaction Requests](#34-api-resource-transaction-requests) + +[3.5 API Resource Quotes](#35-api-resource-quotes) + +[3.6 API Resource Authorizations](#36-api-resource-authorizations) + +[3.7 API Resource Transfers](#37-api-resource-transfers) + +[3.8 API Resource Transactions](#38-api-resource-transactions) + +[3.9 API Resource Bulk Quotes](#39-api-resource-bulk-quotes) + +[3.10 API Resource Bulk Transfers](#310-api-resource-bulk-transfers) + +[4. Generic Transaction Patterns](#4-generic-transaction-patterns) + +[4.1 Payer-Initiated Transaction](#41-payer-initiated-transaction) + +[4.2 Payee-Initiated Transaction](#42-payee-initiated-transaction) + +[4.3 Payee-Initiated Transaction using OTP](#43-payee-initiated-transaction-using-otp) + +[4.4 Bulk Transactions](#44-bulk-transactions) + +[5. References](#5-references) + +**Table of Figures** + +[Figure 1 -- Payer-Initiated Transaction](#443-business-process-sequence-diagram) + +[Figure 2 -- Payee-Initiated Transaction](#423-business-process-sequence-diagram) + +[Figure 3 -- Payee-Initiated Transaction using OTP](#433-business-process-sequence-diagram) + +[Figure 4 -- Bulk Transaction](#443-business-process-sequence-diagram) + +## 1. Preface + +This section contains information about how to use this document. + +### 1.1 Conventions Used in This Document + +The following conventions are used in this document to identify the specified types of information + +|Type of Information|Convention|Example| +|---|---|---| +|**Elements of the API, such as resources**|Boldface|**/authorization**| +|**Variables**|Italics within curly brackets|_{ID}_| +|**Glossary terms**|Italics on first occurrence; defined in _Glossary_|The purpose of the API is to enable interoperable financial transactions between a _Payer_ (a payer of electronic funds in a payment transaction) located in one _FSP_ (an entity that provides a digital financial service to an end user) and a _Payee_ (a recipient of electronic funds in a payment transaction) located in another FSP.| +|**Library documents**|Italics|User information should, in general, not be used by API deployments; the security measures detailed in _API Signature_ and _API Encryption_ should be used instead.| + +### 1.2 Document Version Information + +|Version|Date|Change Description| +|---|---|---| +|**1.0**|2019-03-12|Initial version| + +## 2. Introduction + +This document introduces the four generic transaction patterns that are supported in a logical version of the Interoperability API. Additionally, all logical services that are part of the API are presented on a high-level. + +### 2.1 Open API for FSP Interoperability Specification + +The Open API for FSP Interoperability Specification includes the following documents. + +#### 2.1.1 General Documents + +- _Glossary_ + +#### 2.1.2 Logical Documents + +- _Logical Data Model_ + +- _Generic Transaction Patterns_ + +- _Use Cases_ + +#### 2.1.3 Asynchronous REST Binding Documents + +- _API Definition_ + +- _JSON Binding Rules_ + +- _Scheme Rules_ + +#### 2.1.4 Data Integrity, Confidentiality, and Non-Repudiation + +- _PKI Best Practices_ + +- _Signature_ + +- _Encryption_ + +## 3. Logical API Services + +The Interoperability API consists of a number of logical API resources. Each resource defines one or more services that clients can use to connect to a server that has implemented the API. This section introduces these services. + +**Note:** API services identified in this section may not be relevant to (and therefore may not appear in) the generic transaction patterns identified in [Section 4](#4-generic-transaction-patterns). For example, some services are used for provisioning of information, are part of error cases, or are for retrieving information that is not necessary in a generic transaction pattern. + +### 3.1 Common Functionality + +This section introduces functionality that is used by more than one logical API resource or service. + +#### 3.1.1 Party Addressing + +A Party is an entity such as an individual, a business, an organization that has a financial account in one of the FSPs. A party is addressed by a combination of an _ID type_ and an _ID_, and possibly also a _subtype_ or _sub ID_. Some examples of _ID type_ and _ID_ combinations are: + +- _ID type_: **MSISDN**, _ID_: **+123456789** + +- _ID type_: **Email**, _ID_: **john@doe.com** + +#### 3.1.2 Interledger + +The API includes basic support for the Interledger Protocol (ILP) by defining a concrete implementation of the Interledger Payment Request protocol[1](https://interledger.org/rfcs/0011-interledger-payment-request)(ILP) in the logical API resources **Quotes** and **Transfers**. More details of the ILP protocol can be found on the Interledger project website[2](https://interledger.org), in the Interledger Whitepaper[3](https://interledger.org/interledger.pdf), and in the Interledger architecture specification[4](https://interledger.org/rfcs/0001-interledger-architecture). + +### 3.2 API Resource Participants + +In the API, a _Participant_ is the same as an FSP that is participating in an Interoperability Scheme. The primary purpose of the logical API resource **Participants** is for FSPs to find out in which other FSP a counterparty in an interoperable financial transaction is located. There are also services defined for the FSPs to provision information to a common system. + +#### 3.2.1 Requests + +This section identifies the logical API service requests that can be sent from a client to a server. + +##### 3.2.1.1 Lookup Participant Information + +The logical API service request **Lookup Participant Information** is used from an FSP to request from another system, which could be another FSP or a common system, information regarding in which FSP a counterparty in an interoperable financial transaction is located. + +- Successful response: **Return Participant Information** + +- Error response: **Return Participant Information Error** + +##### 3.2.1.2 Create Participant Information + +The logical API service request **Create Participant Information** is used to provision information regarding in which FSP a party is located. + +- Successful response: **Return Participant Information** + +- Error response: **Return Participant Information Error** + +##### 3.2.1.3 Create Bulk Participant Information + +The logical API service request **Bulk Create Participant Information** is used to provision information regarding in which FSP one or more parties are located. + +- Successful response: **Return Bulk Participant Information** + +- Error response: **Return Bulk Participant Information Error** + +##### 3.2.1.4 Delete Participant Information + +The logical API service request **Delete Participant Information** is used to remove information regarding in which FSP a party is located. + +- Successful response: **Return Participant Information** + +- Error response: **Return Participant Information Error** + +#### 3.2.2 Responses + +This section identifies the logical API service responses that can be sent back to a client from a server. + +##### 3.2.2.1 Return Participant Information + +The logical API service response **Return Participant Information** is used to return information from the requests **Lookup Participant Information**, **Create Participant Information**, and **Delete Participant Information**. + +##### 3.2.2.2 Return Bulk Participant Information + +The logical API service response **Return Bulk Participant Information** is used to return information from the request **Create Bulk Participant Information**. + +#### 3.2.3 Error Responses + +This section identifies the logical API service error responses that can be sent back to a client from a server. + +##### 3.2.3.1 Return Participant Information Error + +The logical API service error response **Return Participant Information Error** is used to return error information regarding the requests **Lookup Participant Information**, **Create Participant Information**, and **Delete Participant Information**. + +##### 3.2.3.2 Return Bulk Participant Information Error + +The logical API service error response **Return Bulk Participant Information Error** is used to return error information regarding the request **Create Bulk Participant Information**. + +### 3.3 API Resource Parties + +In the API, a _Party_ is an individual, a business, an organization, or a similar entity, that has a financial account in one of the FSPs. The primary purpose of the logical API resource **Parties** is for FSPs to ascertain information regarding a counterparty in an interoperable financial transaction, such as name and birth date of the Party. + +#### 3.3.1 Requests + +This section identifies the logical API service requests that can be sent from a client to a server. + +##### 3.3.1.1 Lookup Party Information + +The logical API service request **Lookup Party Information** is used by an FSP to request from another FSP information regarding a counterparty in an interoperable financial transaction. + +- Successful response: **Return Party Information** + +- Error response: **Return Party Information Error** + +#### 3.3.2 Responses + +This section identifies the logical API service responses that can be sent back to a client from a server. + +##### 3.3.2.1 Return Party Information + +The logical API service response **Return Party Information** is used to return information from the request **Lookup Party Information**. + +#### 3.3.3 Error Responses + +This section identifies the logical API service error responses that can be sent back to a client from a server. + +##### 3.3.3.1 Return Party Information Error + +The logical API service error response **Return Party Information Error** is used to return error information regarding the request **Lookup Party Information**. + +### 3.4 API Resource Transaction Requests + +In the API, a _Transaction Request_ is a request from a Payee to a Payer to transfer electronic funds to the Payee, which the Payer can accept or reject. The primary purpose of the logical API resource **Transaction Requests** is for a Payee FSP to send the request to transfer to the Payer FSP. + +#### 3.4.1 Requests + +This section identifies the logical API service requests that can be sent from a client to a server. + +##### 3.4.1.1 Perform Transaction Request + +The logical API service request **Perform Transaction Request** is used to send a Transaction Request from a Payee FSP to the Payer FSP; that is, to ask if a Payer will accept or reject a transaction from the Payer to the Payee. + +- Successful response: **Return Transaction Request Information** + +- Error response: **Return Transaction Request Information Error** + +##### 3.4.1.2 Retrieve Transaction Request Information + +The logical API service request **Retrieve Transaction Request Information** is used from a Payee FSP to a Payer FSP to request information regarding a previously-sent Transaction Request. + +- Successful response: **Return Transaction Request Information** + +- Error response: **Return Transaction Request Information Error** + +#### 3.4.2 Responses + +This section identifies the logical API service responses that can be sent back to a client from a server. + +##### 3.4.2.1 Return Transaction Request Information + +The logical API service response **Return Transaction Request Information** is used to return information from the requests **Perform Transaction Request** or **Retrieve Transaction Request Information**. + +#### 3.4.3 Error Responses + +This section identifies the logical API service error responses that can be sent back to a client from a server. + +##### 3.4.3.1 Return Transaction Request Information Error + +The logical API service error response **Return Transaction Request Information Error** is used to return error information regarding the requests **Perform Transaction Request** or **Retrieve Transaction Request Information**. + +### 3.5 API Resource Quotes + +In the API, a _Quote_ is the price for performing an interoperable financial transaction from the Payer FSP to the Payee FSP. The primary purpose of the logical API resource **Quotes** is for a Payer FSP to request a Payee FSP to calculate the Payee FSP's part of the quote. + +#### 3.5.1 Requests + +This section identifies the logical API service requests that can be sent from a client to a server. + +##### 3.5.1.1 Calculate Quote + +The logical API service request **Calculate Quote** is used from a Payer FSP to ask a Payee FSP to calculate the Payee FSP's part of the quote to perform an interoperable financial transaction. The Payee FSP should also create the ILP Packet and the condition (see [Section 3.1.2](#312-interledger) for links to more information) when receiving the request. + +- Successful response: **Return Quote Information** + +- Error response: **Return Quote Information Error** + +##### 3.5.1.2 Retrieve Quote Information + +The logical API service request **Retrieve Quote Information** is used by a Payer FSP to request that a Payee FSP ask for information regarding a previously-sent **Calculate Quote** request. + +- Successful response: **Return Quote Information** + +- Error response: **Return Quote Information Error** + +#### 3.5.2 Responses + +This section identifies the logical API service responses that can be sent back to a client from a server. + +##### 3.5.2.1 Return Quote Information + +The logical API service response **Return Quote Information** is used to return information from the requests **Calculate Quote** or **Retrieve Quote Information**. + +#### 3.5.3 Error Responses + +This section identifies the logical API service error responses that can be sent back to a client from a server. + +##### 3.5.3.1 Return Quote Information Error + +The logical API service error response **Return Quote Information Error** is used to return error information regarding the requests **Calculate Quote** or **Retrieve Quote Information**. + +### 3.6 API Resource Authorizations + +In the API, an _Authorization_ is an approval from a Payer to perform an interoperable financial transaction by entering the applicable credentials in a Payee FSP system. An example where this kind of approval is used, is when a Payer is using an ATM that is managed by another FSP. The primary purpose of the logical API resource **Authorizations** is for a Payer FSP to request a Payee FSP to ask the Payer to enter the credentials. + +#### 3.6.1 Requests + +This section identifies the logical API service requests that can be sent from a client to a server. + +##### 3.6.1.1 Perform Authorization + +The logical API service request **Perform Authorization** is used from a Payer FSP to ask a Payee FSP to enter the applicable credentials to approve an interoperable financial transaction. + +- Successful response: **Return Authorization Result** + +- Error response: **Return Authorization Error** + +#### 3.6.2 Responses + +This section identifies the logical API service responses that can be sent back to a client from a server. + +##### 3.6.2.1 Return Authorization Result + +The logical API service response **Return Authorization Result** is used to return information from the request **Perform Authorization**. + +#### 3.6.3 Error Responses + +This section identifies the logical API service error responses that can be sent back to a client from a server. + +##### 3.6.3.1 Return Authorization Error + +The logical API service error response **Return Authorization Error** is used to return error information regarding the request **Perform Authorization**. + +### 3.7 API Resource Transfers + +In the API, a _Transfer_ is hop-to-hop ILP (see [Section 3.1.2](#312-interledger) for links to more information) transfer of funds. The transfer also contains information regarding the end-to-end interoperable financial transaction. The primary purpose of the logical API resource **Transfers** is for an FSP or Switch to request that the next entity in the chain of the ILP Payment perform the transfer involved in the interoperable financial transaction. + +#### 3.7.1 Requests + +This section identifies the logical API service requests that can be sent from a client to a server. + +##### 3.7.1.1 Perform Transfer + +The logical API service request **Perform Transfer** is used by an FSP or Switch to request the next entity in the chain of the ILP Payment to reserve the transfer involved in an interoperable financial transaction. + +- Successful response: **Return Transfer Information** + +- Error response: **Return Transfer Information Error** + +##### 3.7.1.2 Retrieve Transfer Information + +The logical API service request **Retrieve Transfer Information** is used by an FSP or Switch to request the next entity in the chain of the ILP Payment for information regarding the transfer involved in an interoperable financial transaction. + +- Successful response: **Return Transfer Information** + +- Error response: **Return Transfer Information Error** + +#### 3.7.2 Responses + +This section identifies the logical API service responses that can be sent back to a client from a server. + +##### 3.7.2.1 Return Transfer Information + +The logical API service re**sponse Return Transfer Information** is used to return information from the requests **Perform Transfer** or **Retrieve Transfer Information**. On receiving the response **Return Transfer Information**, the FSP or Switch should validate the fulfilment (see [Section 3.1.2](#312-interledger) for links to more information) and commit the reserved transfer if the validation is successful. + +#### 3.7.3 Error Responses + +This section identifies the logical API service error responses that can be sent back to a client from a server. + +##### 3.7.3.1 Return Transfer Information Error + +The logical API service error response **Return Transfer Information Error** is used to return error information regarding the requests **Perform Transfer** or **Retrieve Transfer Information**. + +### 3.8 API Resource Transactions + +In the API, a _Transaction_ is an end-to-end interoperable financial transaction between the Payer FSP and Payee FSP. The primary purpose of the logical API resource **Transactions** is for a Payer FSP to request end-to-end information from the Payee FSP regarding an interoperable financial transaction; for example, in order to get a token or code that the Payer can use to redeem a service or product. + +### 3.8.1 Requests + +This section identifies the logical API service requests that can be sent from a client to a server. + +##### 3.8.1.1 Retrieve Transaction Information + +The logical API service request **Retrieve Transaction Information** is used by a Payer FSP to request that a Payee FSP get information regarding a previously-performed interoperable financial transaction (by using the logical API resource **Transfers**, see [Section 3.7](#37-api-resource-transfers)). + +- Successful response: **Return Transaction Information** + +- Error response: **Return Transaction Information Error** + +#### 3.8.2 Responses + +This section identifies the logical API service responses that can be sent back to a client from a server. + +##### 3.8.2.1 Return Transaction Information + +The logical API service response **Return Transaction Information** is used to return information from the request **Retrieve Transaction Information**. + +#### 3.8.3 Error Responses + +This section identifies the logical API service error responses that can be sent back to a client from a server. + +##### 3.8.3.1 Return Transaction Information Error + +The logical API service error response **Return Transaction Information Error** is used to return error information regarding the request **Retrieve Transaction Information**. + +### 3.9 API Resource Bulk Quotes + +In the API, a _Bulk Quote_ is a collection of individual quotes (see [Section 3.5](#35-api-resource-quotes) for information regarding a single quote) for performing more than one interoperable financial transaction from the Payer FSP to the Payee FSP. The primary purpose of the logical API resource **Bulk Quotes** is for a Payer FSP to request a Payee FSP to calculate the Payee FSP's part of the bulk quote. + +#### 3.9.1 Requests + +This section identifies the logical API service requests that can be sent from a client to a server. + +##### 3.9.1.1 Calculate Bulk Quote + +The logical API service request **Calculate Bulk Quote** is used by a Payer FSP to request that a Payee FSP calculate the Payee FSP's part of the quotes to perform more than one interoperable financial transaction. The Payee FSP should also create the ILP Packet and the condition (see [Section 3.1.2](#312-interledger) for links to more information) per quote when receiving the request. + +- Successful response: **Return Bulk Quote Information** + +- Error response: **Return Bulk Quote Information Error** + +##### 3.9.1.2 Retrieve Bulk Quote Information + +The logical API service request **Retrieve Bulk Quote Information** is used by a Payer FSP to request that a Payee FSP ask for information regarding a previously-sent **Calculate Bulk Quote request**. + +- Successful response: **Return Bulk Quote Information** + +- Error response: **Return Bulk Quote Information Error** + +#### 3.9.2 Responses + +This section identifies the logical API service responses that can be sent back to a client from a server. + +##### 3.9.2.1 Return Bulk Quote Information + +The logical API service response **Return Bulk Quote Information** is used to return information from the requests **Calculate Bulk Quote** or **Retrieve Bulk Quote Information**. + +#### 3.9.3 Error Responses + +This section identifies the logical API service error responses that can be sent back to a client from a server. + +##### 3.9.3.1 Return Bulk Quote Information Error + +The logical API service error response **Return Bulk Quote Information Error** is used to return error information regarding the requests **Calculate Bulk Quote** or **Retrieve Bulk Quote Information**. + +### 3.10 API Resource Bulk Transfers + +In the API, a _Bulk Transfer_ is a collection of hop-to-hop ILP (see [section 3.1.2](#312-interledger) for links to more information) transfers of funds. The transfers also contain information regarding the end-to-end interoperable financial transactions. The primary purpose of the logical API resource **Bulk Transfers** is to enable an FSP or Switch to request that the next entity in the chain of the ILP Payment perform the transfers involved in the interoperable financial transactions. + +#### 3.10.1 Requests + +This section identifies the logical API service requests that can be sent from a client to a server. + +##### 3.10.1.1 Perform Bulk Transfer + +The logical API service request **Perform Bulk Transfer** is used by an FSP or Switch to request that the next entity in the chain of the ILP Payment reserve the transfer involved in an interoperable financial transaction. + +- Successful response: **Return Bulk Transfer Information** + +- Error response: **Return Bulk Transfer Information Error** + +##### 3.10.1.2 Retrieve Bulk Transfer Information + +The logical API service request **Retrieve Bulk Transfer Information** is used from an FSP or Switch to request that the next entity in the chain of the ILP Payment for information regarding the transfer involved in an interoperable financial transaction. + +- Successful response: **Return Bulk Transfer Information** + +- Error response: **Return Bulk Transfer Information Error** + +#### 3.10.2 Responses + +This section identifies the logical API service responses that can be sent back to a client from a server. + +##### 3.10.2.1 Return Bulk Transfer Information + +The logical API service response **Return Bulk Transfer Information** is used to return information from the requests **Perform Bulk Transfer** or **Retrieve Bulk Transfer Information**. On receiving the response **Return Bulk Transfer Information**, the FSP or Switch should validate the fulfilments (see [Section 3.1.2](#312-interledger) for links to more information) and commit the reserved transfers if the validations are successful. + +#### 3.10.3 Error Responses + +This section identifies the logical API service error responses that can be sent back to a client from a server. + +##### 3.10.3.1 Return Bulk Transfer Information Error + +The logical API service error response **Return Bulk Transfer Information Error** is used to return error information regarding the requests **Perform Bulk Transfer** or **Retrieve Bulk Transfer Information**. + +## 4. Generic Transaction Patterns + +This section provides information about the three primary transaction patterns defined in the Interoperability API: + +- _Payer-Initiated Transaction_ + +- _Payee-Initiated Transaction_ + +- _Bulk Transaction_ + +Each transaction pattern defines how funds can be transferred from a Payer located in one Financial Service Provider (FSP) to a Payee located in another FSP. + +Both the _Payer-Initiated Transaction_ and the _Payee-Initiated Transaction_ patterns are intended for a single transfer of funds from one Payer to one Payee. The significant difference between the two patterns is in which of the participants in the transaction is responsible for the initiation of the transaction. + +The _Bulk Transaction_ pattern should be used when a single Payer would like to transfer funds to multiple Payees, possibly in different FSPs, in a single transaction. + +This section also provides information about _Payee-Initiated Transaction using OTP_. which is an alternative to _Payee-Initiated Transaction_. + +Additionally, the section provides high-level information about all logical services that are part of the API. + +### 4.1 Payer-Initiated Transaction + +In a _Payer-Initiated Transaction_, the Payer initiates the transaction. + +#### 4.1.1 Business Process Pattern Description + +The _Payer-Initiated Transaction_ pattern should be used whenever a Payer would like to transfer funds to another party whose account is not located in the same FSP. + +In most implementations, Payee involvement is limited to receiving a notification in the event of a successful transaction. Exceptions in which the Payee is more involved are: + +- In countries that require the Payee to confirm receipt of funds. + +- Cases in which the Payee should accept the terms of the transaction (for example, Agent-Initiated Cash-In). + +#### 4.1.2 Participants and Roles + +The actors in a _Payer-Initiated Transaction_ are: + +- **Payer** -- The payer of funds in a financial transaction. + +- **Payee** -- The recipient of funds in a financial transaction. + +The intermediary objects used in a _Payer-Initiated Transaction_ to perform the transaction are: + +- **Payer FSP** -- The FSP in which the Payer's account is located. + +- **Switch (optional)** -- An optional entity used for routing of requests between different FSPs. This object can be removed if requests should be routed directly between a Payer and Payee FSP. + +- **Account Lookup System** -- An entity used for retrieving information regarding accounts or participants. Could be hosted in a separate server, in the Switch, or in the different FSPs. + +- **Payee FSP** -- The FSP in which the Payee's account is located. + +#### 4.1.3 Business Process Sequence Diagram + +Figure 1 shows the UML sequence diagram for a _Payer-Initiated Transaction_. + +{% uml src="assets/diagrams/sequence/figure63a.plantuml" %} +{% enduml %} + +**Figure 1 -- Payer-Initiated Transaction** + +#### 4.1.4 Internal Processing Steps + +This section provides descriptions of and assumptions made for all steps in the sequence shown in Figure 1. + +**Lookup Counterparty** + +1. **Description** + + The Payer initiates the transaction by requesting to send funds to a Payee, using the Payer FSP's front-end API (outside the scope of this API). + + **Assumptions** + + None. + +2. **Description** + + The Payer FSP tries to find the Payee within the FSP system. Because the Payee cannot be found in the Payer FSP system, the request **Lookup Party Information** is sent by the Payer FSP to the optional Switch to get information regarding the Payee, including in which FSP the Payee is located. + + **Assumptions** + + The Payee is assumed to be in a different FSP than the Payer. Also, a Switch is assumed to be placed between the Payer FSP and the Payee FSP to route the messages between FSPs. The Switch is optional in the process, as the request **Lookup Party Information** could also be sent directly to the Payee FSP if there is no Switch in-between. As the Payer FSP should not know in which FSP the Payee is located if there is no Switch present, the request might need to be sent to more than one FSP. + +3. **Description** + + The Switch receives the request **Lookup Party Information**. The Switch then tries to find in which FSP the Payee is located by sending the request **Lookup Participant Information** to the Account Lookup System. + + **Assumptions** + + An Account Lookup System is assumed to exist in a different server than the Switch. It is possible that the Account Lookup System is in the same system as the Switch. + +4. **Description** + + The Account Lookup System receives the request **Lookup Participant Information***.* It then performs an internal lookup to find in which FSP the Payee is located. When the lookup is completed, the response **Return Participant Information** is sent to inform the Switch about which FSP the Payee is located in. + + **Assumptions** + + The Payee can be found by the Account Lookup System. + +5. **Description** + + The Switch receives the response **Return Participant Information**. As the Switch now knows in which FSP the Payee is located, the Switch sends the request **Lookup Party Information** to the Payee FSP to get more information about the Payee. + + **Assumptions** + + None. + +6. **Description** + + The Payee FSP receives the request **Lookup Party Information**. The Payee FSP then does an internal lookup to find more information regarding the Payee and sends the response **Return Party Information** to the Switch. + + **Assumptions** + + None. + +7. **Description** + + The Switch receives the response **Return Party Information**. The Switch then routes the **Return Party Information** response to the Payer FSP to send the information about the Payee. + + **Assumptions** + + None. + +8. **Description** + + The Payer FSP receives the response **Return Party Information** containing information about the Payee. + + **Assumptions** + + None. + + **Calculate Quote** + +9. **Description** + + Depending on the fee model used, the Payer FSP rates the transaction internally and includes the quote information in the request **Calculate Quote** to a Switch to retrieve the full quote for performing the interoperable financial transaction from the Payer FSP to the Payee FSP. The transaction details are sent in the parameters of the request to allow for the Payee FSP to correctly calculate the quote. + + **Assumptions** + + In this sequence, a Switch is placed between the Payer FSP and the Payee FSP to route the messages. The Switch is optional in the process, as the request **Calculate Quote** could also be sent directly to the Payee FSP if there is no Switch in-between. + +10. **Description** + + The Switch receives the **Calculate Quote** request. The Switch then routes the request to the Payee FSP, using the same parameters. + + **Assumptions** + + None. + +11. **Description** + + The Payee FSP receives the **Calculate Quote** request. The Payee FSP then internally calculates the fees or FSP commission for performing the transaction. It then constructs the ILP Packet containing the ILP Address of the Payee, the amount that the Payee will receive, and the transaction details. The fulfilment and the condition are then generated out of the ILP Packet combined with a local secret. + + **Assumptions** + + None. + + **Optional procedure: Quote Confirmation by Payee** + + a. **Description** + + Depending on the use case and the fee model used, the Payee might be informed of the quote in order to confirm the proposed financial transaction. The quote is in that case sent to the Payee using a front-end API (outside the scope of this API). The Payee receives the quote including information regarding the transaction including fees and optionally Payer name. The Payee then confirms the quote using a front-end API (outside the scope of this API), and the Payee FSP receives the confirmation from the Payee. + + **Assumptions** + + The Payee is assumed to accept and confirm the quote. If the Payee would reject the quote, an error response would be sent from the Payee FSP to the Payer FSP via the Switch to inform about the rejected quote. + + **End of Optional procedure** + +12. **Description** + + The Payee FSP uses the response **Return Quote Information** to the Switch to return information to the Payer FSP about the quote, the ILP Packet, and the condition. The quote has an expiration time, to inform the Payer FSP until which point in time the quote is valid. + + **Assumptions** + + None. + +13. **Description** + + The Switch receives the response **Return Quote Information**. The Switch will then route the response to the Payer FSP. + + **Assumptions** + + None. + +14. **Description** + + The Payer FSP receives the response **Return Quote Information** from the Switch. The Payer FSP then informs the Payer using a front-end API (outside the scope of this API) about the total fees to perform the transaction, along with the Payee name. + + **Assumptions** + + The total quote can be calculated by the Payer FSP. Also, the Payee name was allowed to be sent during the counterparty lookup (depending on regulation on privacy laws). + +15. **Description** + + The Payer receives the transaction information including fees, taxes and optionally Payee name. If the Payer rejects the transaction, the sequence ends here. + + **Assumptions** + + The Payer is assumed to approve the transaction in this sequence. If the Payer would reject the transaction at this stage, no response regarding the rejection is sent to the Payee FSP. The created quote at the Payee FSP should have an expiry time, at which time it is automatically deleted. + + **Perform Transfer** + +16. **Description** + + The Payer FSP receives an approval of the interoperable financial transaction using a front-end API (out of scope of this API). The Payer FSP then performs all applicable internal transaction validations (for example, limit checks, blacklist check, and so on). If the validations are successful, a transfer of funds is reserved from the Payer's account to either a combined Switch account or a Payee FSP account, depending on setup. After the transfer has been successfully reserved, the request **Perform Transfer** is sent to the Switch to request the Switch to transfer the funds from the Payer FSP account in the Switch to the Payee FSP account. The request **Perform Transfer** includes a reference to the earlier quote, an expiry of the transfer, the ILP Packet, and the condition that was received from the Payee FSP. The interoperable financial transaction is now irrevocable from the Payer FSP. + + **Assumptions** + + Internal validations and reservation are assumed to be successful. In this sequence, a Switch is placed between the Payer FSP and the Payee FSP to route the messages. The Switch is optional in the process, as the request **Perform Transfer** could also be sent directly to the Payee FSP if there is no Switch in-between. + +17. **Description** + + The Switch receives the request **Perform Transfer**. The Switch then performs all its applicable internal transfer validations (for example, limit checks blacklist check and so on). If the validations are successful, a transfer is reserved from a Payer FSP account to a Payee FSP account. After the transfer has been successfully reserved, the request **Perform Transfer** is sent to the Payee FSP, including the same ILP Packet and condition as was received from the Payer FSP. The expiry time should be decreased by the Switch so that the Payee FSP should answer before the Switch answers to the Payer FSP. The transfer is now irrevocable from the Switch. + + **Assumptions** + + Internal validations and reservation are successful. + +18. **Description** + + The Payee FSP receives the request **Perform Transfer**. The Payee FSP then performs all applicable internal transaction validations (for example, limit checks, blacklist check, and so on). It also verifies that the amount and ILP Address in the ILP Packet are correct and match the amount and Payee in the transaction details stored in the ILP Packet. If all the validations are successful, a transfer of funds is performed from either a combined Switch account or a Payer FSP account to the Payee's account and the fulfilment of the condition is regenerated, using the same secret as in Step 11. After the interoperable financial transaction has been successfully performed, a transaction notification is sent to the Payee using a front-end API (out of scope of this API) and the response **Return Transfer Information** is sent to the Switch, including the regenerated fulfilment. The transfer is now irrevocable from the Payee FSP. + + **Assumptions** + + Internal validations and transfer of funds are successful. + +19. **Description** + + The Payee receives a transaction notification containing information about the successfully performed transaction. + + **Assumptions** + + None. + +20. **Description** + + The Switch receives the response **Return Transfer Information**. The Switch then validates the fulfilment and commits the earlier reserved transfer. The Switch then uses the response **Return Transfer Information** to the Payer FSP, using the same parameters. + + **Assumptions** + + The fulfilment is assumed to be correctly validated. + +21. **Description** + + The Payer FSP receives the response **Return Transfer Information**. The Payer FSP then validates the fulfilment and commits the earlier reserved transaction. + + **Assumptions** + + The fulfilment is assumed to be correctly validated. + + **Optional fragment: Get Transaction Details** + +22. **Description** + + In case the interoperable financial transaction contains additional information that is useful for the Payer or the Payer FSP, such as a code or a voucher token, the Payer FSP can use the request **Retrieve Transaction Information** to get the additional transaction information. The request **Retrieve Transaction Information** is sent to the Switch. + + **Assumptions** + + None. + +23. **Description** + + The Switch receives the request **Retrieve Transaction Information**. The Switch then routes the **Retrieve Transaction Information** request to the Payee FSP. + + **Assumptions** + + None. + +24. **Description** + + The Payee FSP receives the request **Retrieve Transaction Information**. The Payee FSP then collects the requested information and sends the response **Return Transaction Information** to the Switch. + + **Assumptions** + + The transaction with the provided ID can be found in the Payee FSP. + +25. **Description** + + The Switch receives the response **Return Transaction Information**. The Switch then routes the **Return Transaction Information** response to the Payer FSP. + + **Assumptions** + + None. + +26. **Description** + + The Payer FSP receives the response **Return Transaction Information**. + + **Assumptions** + + None. + + **End of Optional fragment** + +28. **Description** + + The Payer FSP sends a transaction notification to the Payee using a front-end API (out of scope of this API), optionally including transaction details retrieved from the Payee FSP. + + **Assumptions** + + None. + +29. **Description** + + The Payer receives a transaction notification containing information about the successfully performed transaction. + + **Assumptions** + + None. + +### 4.2 Payee-Initiated Transaction + +In a _Payee-Initiated Transaction_, the Payee (that is, the recipient of electronic funds) initiates the transaction. + +#### 4.2.1 Business Process Pattern Description + +The pattern should be used whenever a Payee would like to receive funds from another party whose account is not located in the same FSP. + +In all alternatives to this pattern, the Payer must in some way confirm the request of funds. Some possible alternatives for confirming the request are: + +- **Manual approval** -- A transaction request is routed from the Payee to the Payer, the Payer can then either approve or reject the transaction. + +- **Pre-approval of Payee** -- A Payer can pre-approve a specific Payee to request funds, used for automatic approval of, for example, school fees or electric bills. + +Another alternative for approval is to use the business pattern _Payee-Initiated Transaction using OTP_, described in [Section 4.3](#43-payee-initiated-transaction-using-otp). + +#### 4.2.2 Participants and Roles + +The actors in a _Payee-Initiated Transaction_ are: + +- **Payer** -- The payer of funds in a financial transaction. + +- **Payee** -- The recipient of funds in a financial transaction. + +The intermediary objects used in a _Payee-Initiated Transaction_ to perform the transaction are: + +- **Payer FSP** -- The FSP in which the Payer's account is located. + +- **Switch (optional)** -- An optional entity used for routing of requests between different FSPs. This object can be removed if requests should be routed directly between a Payer and Payee FSP. + +- **Account Lookup System** -- An entity used for retrieving information regarding accounts or participants. Could be hosted in a separate server, in the Switch, or in the different FSPs. + +- **Payee FSP** -- The FSP in which the Payee's account is located. + +#### 4.2.3 Business Process Sequence Diagram + +Figure 2 shows the UML sequence diagram for a _Payee-Initiated Transaction_. + +{% uml src="assets/diagrams/sequence/figure64a.plantuml" %} +{% enduml %} + +**Figure 2 -- Payee-Initiated Transaction** + +#### 4.2.4 Internal Processing Steps + +This section provides descriptions of and assumptions made for all steps in the sequence shown in Figure 2. + +**Lookup Counterparty** + +1. **Description** + + The Payee initiates the transaction by requesting to receive funds from a Payer, using the Payee FSP's front-end API (outside the scope of this API). + + **Assumptions** + + None. + +2. **Description** + + The Payee FSP tries to find the Payer within the FSP system. Because the Payer cannot be found in the Payee FSP system, the Payee FSP sends the request to the optional Account Lookup System to get information regarding in which FSP the Payer is located. + + **Assumptions** + + The Payer is assumed to be located in a different FSP than the Payee. Also, an Account Lookup System is assumed to exist. The Account Lookup System is optional in the process, as the request **Lookup Participant Information** could also be sent directly to the Payer FSP if there is no Account Lookup System. As the Payee FSP should not know in which FSP the Payer is located if there is no Account Lookup System present, the request might need to be sent to more than one FSP. It is also possible that the Payee FSP would like more information about the Payer before a transaction request is sent; in that case the request **Lookup Party Information**, either to the Switch or directly to the Payer FSP, should be sent instead of **Lookup Participant Information** to the Account Lookup System. + +3. **Description** + + The Account Lookup System receives the **Lookup Participant Information**. It then performs an internal lookup to find in which FSP the Payer is located. When the lookup is completed, the response **Return Participant Information** is sent to inform the Payee FSP about which FSP the Payer is located. + + **Assumptions** + + The Payer can be found by the Account Lookup System. + +4. **Description** + + The Payee FSP receives the response **Return Participant Information**. + + **Assumptions** + + None. + + **Transaction Request** + +5. **Description** + + The Payee FSP sends the request **Perform Transaction Request** to the Switch. The request contains the transaction details including the amount that the Payee would like to receive. + + **Assumptions** + + In this sequence, a Switch is placed between the Payee FSP and the Payer FSP to route the messages. The Switch is optional in the process, as the request **Perform Transaction Request** could also be sent directly to the Payer FSP if there is no Switch in-between. + +6. **Description** + + The Switch receives the **Request Transaction**. The Switch then routes the request to the Payer FSP, using the same parameters. + + **Assumptions** + + None. + +7. **Description** + + The Payer FSP receives the request **Perform Transaction Request**. The Payer FSP then optionally validates the transaction request (for example, whether the Payer exists) and uses the response **Return Transaction Request Information** to inform the Payee FSP via the Switch that the transaction request has been received. + + **Assumptions** + + The optional validation succeeds. + +8. **Description** + + The Switch receives the response **Return Transaction Request Information**. The Switch then sends the same response (**Return Transaction Request Information**) to inform the Payee FSP about the successfully delivered transaction request to the Payer FSP. + + **Assumptions** + + None. + +9. **Description** + + The Payee FSP receives the response **Return Transaction Request Information** from the Switch. + + **Assumptions** + + None. + + **Calculate Quote** + +10. **Description** + + The Payer FSP rates the transaction internally based on the fee model used and includes the quote information in the request **Calculate Quote** to a Switch to retrieve the full quote for performing the interoperable financial transaction from the Payer FSP to the Payee FSP. The transaction details, including a reference to the earlier sent transaction request, are sent in the parameters of the request to allow for the Payee FSP to correctly calculate the quote. + + **Assumptions** + + In this sequence, a Switch is placed between the Payer FSP and the Payee FSP to route the messages. The Switch is optional in the process, as the request **Calculate Quote** could also be sent directly to the Payee FSP if there is no Switch in-between. + +11. **Description** + + The Switch receives the **Calculate Quote** request. The Switch then routes the request to the Payee FSP. + + **Assumptions** + + None. + +12. **Description** + + The Payee FSP receives the **Calculate Quote** request. The Payee FSP then internally calculates the fees or FSP commission for performing the transaction. It then constructs the ILP Packet containing the ILP Address of the Payee, the amount that the Payee will receive, and the transaction details. The fulfilment and the condition are then generated out of the ILP Packet combined with a local secret. + + **Assumptions** + + None + +13. **Description** + + Depending on use case and the fee model used, the Payee might be informed of the quote so that the Payee can confirm the proposed financial transaction. The quote is in that case sent to the Payee using a front-end API (outside the scope of this API). The Payee receives the quote including information regarding the transaction including fees and optionally Payer name. The Payee then confirms the quote using a front-end API (outside the scope of this API). The Payee FSP receives the confirmation from the Payee. + + **Assumptions** + + The quote is assumed to be sent to the Payer for confirmation, and the Payee is assumed to accept and confirm the quote. If the Payee would reject the quote, an error response would be sent from the Payee FSP to the Payer FSP via the Switch to inform about the rejected quote. + + **End of Optional fragment** + +14. **Description** + + The Payee FSP uses the response **Return Quote Information** to the Switch to return information to the Payer FSP about the quote, the ILP Packet, and the condition. The quote has an expiration time, to inform the Payer FSP until which point in time the quote is valid. + + **Assumptions** + + None. + +15. **Description** + + The Switch receives the response **Return Quote Information**. The Switch then routes the response to the Payer FSP. + + **Assumptions** + + None. + +16. **Description** + + The Payer FSP receives the response **Return Quote Information** from the Switch. The Payer FSP then informs the Payer using a front-end API (outside the scope of this API) about the transaction request from the Payee, including the amount and the total fees required to perform the transaction, along with the Payee name. + + **Assumptions** + + The total quote can be calculated by the Payer FSP. Also, the Payee name was allowed to be sent during the counterparty lookup (depending on regulation on privacy laws). + +17. **Description** + + The Payer receives the transaction request information including fees, taxes and optionally Payee name. + + **Assumptions** + + If the Payer rejects the transaction request, the sequence proceeds to Step 18. If the Payer approves the transaction request, the sequence proceeds to Step 22. + + **Alternative: Transaction Rejection** + +18. **Description** + + The Payer FSP receives the rejection of the transaction request using a front-end API (out of scope of this API). The Payer FSP then uses the response **Return Transaction Request Information** with a rejected status to inform the Switch that the transaction was rejected. + + **Assumptions** + + The Payer is assumed to reject the transaction request in Step 17. + +19. **Description** + + The Switch receives the response **Return Transaction Request Information** from the Payer FSP. The Switch then routes the response **Return Transaction Request Information** to the Payee FSP. + + **Assumptions** + + None. + +20. **Description** + + The Payee FSP receives the response **Return Transaction Request Information** with a rejected status from the Switch. The Payee FSP then informs the Payee using a front-end API (outside the scope of this API) about the rejected transaction request. + + **Assumptions** + + None. + +21. **Description** + + The Payee receives the notification that the transaction was rejected. The process ends here as the transaction request was rejected and the Payee has been informed of the decision. + + **Assumptions** + + None. + + **Alternative: Perform Transfer** + +22. **Description** + + The Payer FSP receives an approval of the interoperable financial transaction using a front-end API (out of scope of this API). The Payer FSP then performs all applicable internal transaction validations (for example, limit checks, blacklist check, and so on). If the validations are successful, a transfer of funds is reserved from the Payer's account to either a combined Switch account or a Payee FSP account, depending on setup. After the transfer has been successfully reserved, the request **Perform Transfer** is sent to the Switch to request the Switch to transfer the funds from the Payer FSP account in the Switch to the Payee FSP account. The request **Perform Transfer** includes a reference to the earlier quote, an expiry of the transfer, the ILP Packet, and the condition that was received from the Payee FSP. The interoperable financial transaction is now irrevocable from the Payer FSP. + + **Assumptions** + + The Payer is assumed to approve the transaction request in Step 17. Internal validations and reservation are assumed to be successful. In this sequence, a Switch is placed between the Payer FSP and the Payee FSP to route the messages. The Switch is optional in the process, as the request **Perform Transfer** could also be sent directly to the Payee FSP if there is no Switch in-between. + +23. **Description** + + The Switch receives the request **Perform Transfer**. The Switch then performs all its applicable internal transfer validations (for example, limit checks, blacklist check, and so on). If the validations are successful, a transfer is reserved from a Payer FSP account to a Payee FSP account. After the transfer has been successfully reserved, the request **Perform Transfer** is sent to the Payee FSP, including the same ILP Packet and condition as was received from the Payer FSP. The expiry time should be decreased by the Switch, so that the Payee FSP should answer before the Switch should answer to the Payer FSP. The transfer is now irrevocable from the Switch. + + **Assumptions** + + Internal validations and reservation are successful. + +24. **Description** + + The Payee FSP receives the request **Perform Transfer**. The Payee FSP then performs all applicable internal transaction validations (for example, limit checks, blacklist check, and so on). It also verifies that the amount and ILP Address in the ILP Packet are correct and match the amount and Payee in the transaction details stored in the ILP Packet. If all the validations are successful, a transfer of funds is performed from either a combined Switch account or a Payer FSP account to the Payee's account and the fulfilment of the condition is regenerated, using the same secret as in Step 11. After the interoperable financial transaction has been successfully performed, a transaction notification is sent to the Payee using a front-end API (out of scope of this API) and the response **Return Transfer Information** is sent to the Switch, including the regenerated fulfilment. The transfer is now irrevocable from the Payee FSP. + + **Assumptions** + + Internal validations and transfer of funds are successful. + +25. **Description** + + The Payee receives a transaction notification containing information about the successfully performed transaction. + + **Assumptions** + + None. + +26. **Description** + + The Switch receives the response **Return Transfer Information**. The Switch then validates the fulfilment and commits the earlier reserved transfer. The Switch then uses the response **Return Transfer Information** to the Payer FSP, using the same parameters. + + **Assumptions** + + The fulfilment is assumed to be correctly validated. + +27. **Description** + + The Payer FSP receives the response **Return Transfer Information**. The Payer FSP then validates the fulfilment and commits the earlier reserved transaction. + + **Assumptions** + + The fulfilment is assumed to be correctly validated. + + **Optional fragment: Get Transaction Details** + +28. **Description** + + In case the interoperable financial transaction contains additional information that is useful for the Payer or the Payer FSP; for example, a code or a voucher token, the Payer FSP can use the request **Retrieve Transaction Information** to get the additional information. The request **Retrieve Transaction Information** is sent to the Switch. + + **Assumptions** + + None. + +29. **Description** + + The Switch receives the request **Retrieve Transaction Information**. The Switch then routes the request **Retrieve Transaction Information** to the Payee FSP. + + **Assumptions** + + None. + +30. **Description** + + The Payee FSP receives the request **Retrieve Transaction Information**. The Payee FSP then collects the requested information and uses the response **Return Transaction Information** to the Switch. + + **Assumptions** + + The transaction with the provided ID can be found in the Payee FSP. + +31. **Description** + + The Switch receives the response **Return Transaction Information**. The Switch then routes the **Return Transaction Information** response to the Payer FSP. + + **Assumptions** + + None. + +32. **Description** + + The Payer FSP receives the response **Return Transaction Information** from the Switch. + + **Assumptions** + + None. + + **End of Optional fragment** + +33. **Description** + + The Payer FSP sends a transaction notification to the Payee using a front-end API (out of scope of this API), optionally including transaction details retrieved from the Payee FSP. + + **Assumptions** + + None. + +34. **Description** + + The Payer receives a transaction notification containing information about the successfully performed transaction. + + **Assumptions** + + None. + +### 4.3 Payee-Initiated Transaction using OTP + +A _Payee-Initiated Transaction using OTP_ is very similar to a _Payee-Initiated Transaction_, but the transaction information (including fees and taxes) and approval for the Payer is shown/entered on a Payee device instead. + +#### 4.3.1 Business Process Pattern Description + +The pattern should be used when a Payee would like to receive funds from another party whose account is not located in the same FSP, and both the transaction information (including fees and taxes) and approval is shown/entered on a Payee device instead. + +- **Approval using OTP** -- A Payer can approve a transaction by first creating an OTP in his/her FSP. An alternative to user- initiated creation of OTP is that the OTP is automatically generated and sent by the Payer FSP. The same OTP is then entered by the Payer in a Payee device, usually a POS device or an ATM. The OTP in the transaction request is automatically matched by the Payer FSP to either approve or reject the transaction. The OTP does not need to be encrypted as it should only be valid once during a short time period. + +#### 4.3.2 Participants and Roles + +The actors in a _Payee-Initiated Transaction using OTP_ are: + +- **Payer** -- The payer of funds in a financial transaction. + +- **Payee** -- The recipient of funds in a financial transaction. + +The intermediary objects used in a _Payee-Initiated Transaction using OTP_ to perform the transaction are: + +- **Payer FSP** -- The FSP in which the Payer's account is located. + +- **Switch (optional)** -- An optional entity used for routing of requests between different FSPs. This object can be removed if requests should be routed directly between a Payer and Payee FSP. + +- **Account Lookup System** -- An entity used for retrieving information regarding accounts or participants. Could be hosted in a separate server, in the Switch, or in the different FSPs. + +- **Payee FSP** -- The FSP in which the Payee's account is located. + +#### 4.3.3 Business Process Sequence Diagram + +Figure 3 shows the UML sequence diagram for a _Payee-Initiated Transaction using OTP_. + +{% uml src="assets/diagrams/sequence/figure65a.plantuml" %} +{% enduml %} + +**Figure 3 -- Payee-Initiated Transaction using OTP** + +#### 4.3.4 Internal Processing Steps + +This section provides descriptions of and assumptions made for all steps in the sequence shown in Figure 3. + +**Optional fragment: Manual OTP request** + +1. **Description** + + The Payer requests that an OTP be generated, using the Payer FSP's front-end API (outside the scope of this API). + + **Assumptions** + + There are two alternatives for generating an OTP; either it is generated upon request by the Payer (this option), or it is automatically generated in Step 19. + +2. **Description** + + The Payer FSP receives the request to generate an OTP and returns a generated OTP to the Payer, using the Payer FSP's front-end API (outside the scope of this API). + + **Assumptions** + + None. + +3. **Description** + + Payer receives the generated OTP. The OTP can then be used by the Payer in Step 25 for automatic approval. + + **Assumptions** + + None. + + **End of Optional fragment** + + **Lookup Counterparty** + +4. **Description** + + The Payee initiates the transaction by requesting to receive funds from a Payer, using the Payee FSP's front-end API (outside the scope of this API). + + **Assumptions** + + None. + +5. **Description** + + The Payee FSP tries to find the Payer within the FSP system. Because the Payer cannot be found in the Payee FSP system, the request **Lookup Participant Information** is sent by the Payee FSP to the optional Account Lookup System to get information regarding in which FSP the Payer is located. + + **Assumptions** + + The Payer is assumed to be in a different FSP than the Payee. Also, an Account Lookup System is assumed to exist. The Account Lookup System is optional in the process, as the request **Lookup Participant Information** could also be sent directly to the Payer FSP if there is no Account Lookup System. As the Payee FSP should not know in which FSP the Payer is located if there is no Account Lookup System present, the request might need to be sent to more than one FSP. It is also possible that the Payee FSP would like more information about the Payer before a transaction request is sent; in that case the request **Lookup Party Information**, either to the Switch or directly to the Payer FSP, should be sent instead of **Lookup Participant Information** to the Account Lookup System. + +6. **Description** + + The Account Lookup System receives the **Lookup Participant Information**. It then performs an internal lookup to find in which FSP the Payer is located. When the lookup is completed, the response **Return Participant Information** is sent to inform the Payee FSP about which FSP the Payer is located in. + + **Assumptions** + + The Payer can be found by the Account Lookup System. + +7. **Description** + + The Payee FSP receives the response **Return Participant Information**. + + **Assumptions** + + None. + + **Transaction Request** + +8. **Description** + + The Payee FSP sends the request **Perform Transaction Request** to the Switch. The request contains the transaction details including the amount that the Payee would like to receive, and that the request should be validated using an OTP (possibly a QR code containing a OTP). + + **Assumptions** + + In this sequence, a Switch is placed between the Payee FSP and the Payer FSP to route the messages. The Switch is optional in the process, as the request **Perform Transaction Request** could also be sent directly to the Payer FSP if there is no Switch in-between. + +9. **Description** + + The Switch receives the request **Perform Transaction Request**. The Switch then routes the request to the Payer FSP, using the same parameters. + + **Assumptions** + + None. + +10. **Description** + + The Payer FSP receives the request **Perform Transaction Request**. The Payer FSP then optionally validates the transaction request (for example, whether the Payer exists or not) and sends the response **Return Transaction Request Information** to inform the Payee FSP via the Switch that the transaction request has been received. + + **Assumptions** + + The optional validation succeeds. + +11. **Description** + + The Switch receives the response **Return Transaction Request Information**. The Switch then uses the same response **Return Transaction Request Information** to inform the Payee FSP about the successfully delivered transaction request to the Payer FSP. + + **Assumptions:** + + None. + +12. **Description** + + The Payee FSP receives the response **Return Transaction Request Information** from the Switch. + + **Assumptions** + + None. + + **Calculate Quote** + +13. **Description** + + The Payer FSP rates the transaction internally based on the fee model used and includes the quote information in the request **Calculate Quote** to a Switch to retrieve the full quote for performing the interoperable financial transaction from the Payer FSP to the Payee FSP. The transaction details, including a reference to the transaction request, are sent in the parameters of the request to allow for the Payee FSP to correctly calculate the quote. + + **Assumptions** + + In this sequence, a Switch is placed between the Payer FSP and the Payee FSP to route the messages. The Switch is optional in the process, as the request **Calculate Quote** could also be sent directly to the Payee FSP if there is no Switch in-between. + +14. **Description** + + The Switch receives the **Calculate Quote** request. The Switch then routes the request to the Payee FSP, using the same parameters. + + **Assumptions** + + None. + +15. **Description** + + The Payee FSP receives the **Calculate Quote** request. The Payee FSP then internally calculates the fees or FSP commission for performing the transaction. It then constructs the ILP Packet containing the ILP Address of the Payee, the amount that the Payee will receive, and the transaction details. The fulfilment and the condition is then generated out of the ILP Packet combined with a local secret. + + **Assumptions** + + None. + + **Optional fragment: Quote Confirmation by Payee** + +16. **Description** + + Depending on the fee model used and which use case it is, the Payee might be informed of the quote to be able to confirm the proposed financial transaction. The quote is in that case sent to the Payee using a front- end API (outside the scope of this API. The Payee receives the quote including information regarding the transaction including fees and optionally Payer name. The Payee then confirms the quote using a front-end API (outside the scope of this API). The Payee FSP receives the confirmation from the Payee. + + **Assumptions** + + The quote is assumed to be sent to the Payer for confirmation, and the Payee is assumed to accept and confirm the quote. If the Payee would reject the quote, an error response would be sent from the Payee FSP to the Payer FSP via the Switch to inform about the rejected quote. + + **End of Optional fragment** + +17. **Description** + + The Payee FSP uses the response **Return Quote Information** to the Switch to return information to the Payer FSP about the quote, the ILP Packet, and the condition. The quote has an expiration time, to inform the Payer FSP until which point in time the quote is valid. + + **Assumptions** + + None. + +18. **Description** + + The Switch receives the response **Return Quote Information**. The Switch will then route the request to the Payer FSP. + + **Assumptions** + + None. + +19. **Description** + + The Payer FSP receives the response **Return Quote Information** from the Switch. + + **Assumptions** + + The total quote can be calculated by the Payer FSP. + + **Optional fragment: Automatic OTP generation** + +20. **Description** + + The Payer FSP automatically generates an OTP and sends it to the Payer, using the Payer FSP's front-end API (outside the scope of this API). + + **Assumptions** + + There are two alternatives for generating the OTP. Either it is generated upon request by the Payer (Step 1), or it is automatically generated (this option). + +21. **Description** + + The Payer receives the automatically-generated OTP. + + **Assumptions** + + None. + + **End of Optional fragment** + +22. **Description** + + The Payer FSP sends the request **Perform Authorization** to the Switch, to get an authorization to perform the transaction from the Payer via a POS, ATM, or similar payment device, in the Payee FSP. The request includes the amount to be withdrawn from the Payer's account, and how many retries are left for the Payer to retry the OTP. + + **Assumptions** + + None. + +23. **Description** + + The Switch receives the request **Perform Authorization** from the Payer FSP. The Switch then routes the **Perform Authorization** to the Payee FSP. + + **Assumptions** + + None. + +24. **Description** + + The Payee FSP receives the request **Perform Authorization** from the Switch. The Payee FSP sends the authorization request to the Payee device (POS, ATM, or similar payment device) using the Payee FSP's front-end API (outside the scope of this API). + + **Assumptions** + + None. + +25. **Description** + + The Payee device receives the authorization request, and the Payer can see the amount that will be withdrawn from his or her account. The Payer then uses the OTP received in Step 3 or Step 21, depending on whether the OTP was manually requested or automatically generated. The entered or scanned OTP is then sent to the Payee FSP using the Payee FSP's front-end API (outside the scope of this API). + + **Assumptions** + + The Payer has received the OTP in Step 3 or Step 21. + +26. **Description** + + The Payee FSP receives the OTP from the Payee device. The Payee FSP then sends the response **Return Authorization Result** to the Switch containing the OTP from the Payer. + + **Assumptions** + + None. + +27. **Description** + + The Switch receives the request **Return Authorization Result** from the Payee FSP. The Switch then routes the **Return Authorization Result** to the Payer FSP. + + **Assumptions** + + None. + +28. **Description** + + The Payer FSP receives the request **Return Authorization Result** to the Switch. The Payer FSP then validates the OTP received from the OTP generated in Step 2 or Step 20. If the Payer FSP is unable to validate the OTP (for example, because the OTP is incorrect) and this was the last remaining retry for the Payer, the sequence continues with Step 29. If the Payer FSP correctly validates the OTP, the sequence continues with Step 33. + + **Assumptions** + + None. + + **Alternative: OTP validation failed** + +29. **Description** + + The validation in Step 28 fails and this was the final retry for the Payer. The Payer FSP then uses the response **Return Transaction Request Information** with a rejected state to inform the Switch that the transaction was rejected. + + **Assumptions** + + The OTP validation in Step 28 is assumed to fail and no more retries remains for the Payer. + +30. **Description** + + The Switch receives the response **Return Transaction Request Information** from the Payer FSP. The Switch then routes the **Return Transaction Request Information** response to the Payee FSP. + + **Assumptions** + + None. + +31. **Description** + + The Payee FSP receives the response **Return Transaction Request Information** with a rejected status from the Switch. The Payee FSP then informs the Payee using a front-end API (outside the scope of this API) about the rejected transaction request. + + **Assumptions** + + None. + +32. **Description** + + The Payee receives the notification that the transaction was rejected. The process ends here as the transaction request was rejected and the Payee has been informed of the decision. The Payer is also assumed to receive the notification via the Payee device. + + **Assumptions** + + None. + + **Alternative: OTP validation succeed** + +33. **Description** + + The validation in Step 28 is successful. The Payer FSP then performs all applicable internal transaction validations (for example, limit checks, blacklist check, and so on). If the validations are successful, a transfer of funds is reserved from the Payer's account to either a combined Switch account or a Payee FSP account, depending on setup. After the transfer has been successfully reserved, the request **Perform Transfer** is sent to the Switch to request the Switch to transfer the funds from the Payer FSP account in the Switch to the Payee FSP account. The request **Perform Transfer** includes a reference to the earlier quote, an expiry of the transfer, the ILP Packet, and the condition that was received from the Payee FSP. The interoperable financial transaction is now irrevocable from the Payer FSP. + + **Assumptions** + + The OTP validation in Step 28 is assumed to be successful. Internal validations and reservation are assumed to be successful. In this sequence, a Switch is placed between the Payer FSP and the Payee FSP to route the messages. The Switch is optional in the process, as the request **Perform Transfer** could also be sent directly to the Payee FSP if there is no Switch in-between. + + 34. **Description** + + The Switch receives the request **Perform Transfer**. The Switch then performs all its applicable internal transfer validations (for example, limit checks, blacklist check, and so on). If the validations are successful, a transfer is reserved from a Payer FSP account to a Payee FSP account. After the transfer has been successfully reserved, the request **Perform Transfer** is sent to the Payee FSP, including the same ILP Packet and condition as was received from the Payer FSP. The expiry time should be decreased by the Switch so that the Payee FSP should answer before the Switch should answer to the Payer FSP. The transfer is now irrevocable from the Switch. + + **Assumptions** + + Internal validations and reservation are successful. + +35. **Description** + + The Payee FSP receives the **Perform Transfer**. The Payee FSP then performs all applicable internal transaction validations (for example, limit checks, blacklist check, and so on). It also verifies that the amount and ILP Address in the ILP Packet are correct, and match the amount and Payee in the transaction details stored in the ILP Packet. If all the validations are successful, a transfer of funds is performed from either a combined Switch account or a Payer FSP account to the Payee's account and the fulfilment of the condition is regenerated, using the same secret as in Step 11. After the interoperable financial transaction has been successfully performed, a transaction notification is sent to the Payee using a front-end API (out of scope of this API) and the response **Return Transfer Information** is sent to the Switch, including the regenerated fulfilment. The transfer is now irrevocable from the Payee FSP. + + **Assumptions** + + Internal validations and transfer of funds are successful. + +36. **Description** + + The Payee receives a transaction notification containing information about the successfully performed transaction. + + **Assumptions** + + None. + +37. **Description** + + The Switch receives the response **Return Transfer Information**. The Switch then validates the fulfilment and commits the earlier reserved transfer. The Switch will then use the response **Return Transfer Information** to the Payer FSP, using the same parameters. + + **Assumptions** + + The fulfilment is assumed to be correctly validated. + +38. **Description** + + The Payer FSP receives the response **Return Transfer Information**. The Payer FSP then validates the fulfilment and commits the earlier reserved transaction. + + **Assumptions** + + The fulfilment is assumed to be correctly validated. + + **Optional fragment: Get Transaction Details** + +39. **Description** + + In case the interoperable financial transaction contains additional information that is useful for the Payer or the Payer FSP, such as a code or a voucher token, the Payer FSP can use the request **Retrieve Transaction Information** to get the additional information. The request **Retrieve Transaction Information** is sent to the Switch. + + **Assumptions** + + None. + +40. **Description** + + The Switch receives the request **Retrieve Transaction Information**. The Switch then routes the request **Retrieve Transaction Information** to the Payee FSP. + + **Assumptions** + + None. + +41. **Description** + + The Payee FSP receives the request **Retrieve Transaction Information**. The Payee FSP then collects the requested information and uses the response **Return Transaction Information** to the Switch. + + **Assumptions** + + The transaction with the provided ID can be found in the Payee FSP. + +42. **Description** + + The Switch receives the response **Return Transaction Information**. The Switch then routes the **Return Transaction Information** response to the Payer FSP. + + **Assumptions** + + None. + +43. **Description** + + The Payer FSP receives the response **Return Transaction Information** from the Switch. + + **Assumptions** + + None. + + **End of Optional fragment** + +44. **Description** + + The Payer FSP sends a transaction notification to the Payee using a front-end API (out of scope of this API), optionally including transaction details retrieved from the Payee FSP. + + **Assumptions** + + None. + +45. **Description** + + The Payer receives a transaction notification containing information about the successfully performed transaction. + + **Assumptions** + + None. + +### 4.4 Bulk Transactions + +In a _Bulk Transaction_, the Payer (that is, the sender of funds) initiates multiple transactions to multiple Payees, potentially located in different FSPs. + +#### 4.4.1 Business Process Pattern Description + +The pattern should be used whenever a Payer would like to transfer funds to multiple Payees in the same transaction. The Payees can potentially be located in different FSPs. + +#### 4.4.2 Participants and Roles + +The actors in a _Bulk Transaction_ are: + +- **Payer** -- The sender of funds. + +- **Payees** -- The recipients of funds. There should be multiple Payees in a _Bulk Transaction_. + +The intermediary objects used in a _Bulk Transaction_ to perform the transaction are: + +- **Payer FSP** -- The FSP in which the Payer's account is located. + +- **Switch (optional)** -- An optional entity used for routing of transactions between different FSPs. This object can be removed if transactions should be routed directly between a Payer and Payee FSP. + +- **Account Lookup System** -- An entity used for retrieving information regarding accounts or participants. Could be hosted in a separate server, in the Switch, or in the different FSPs. + +- **Payee FSP** -- The FSP in which a Payee's account is located. There may be multiple Payee FSPs in a _Bulk Transaction_. + +#### 4.4.3 Business Process Sequence Diagram + +Figure 4 shows the UML sequence diagram for a _Bulk Transaction_. + +{% uml src="assets/diagrams/sequence/figure66a.plantuml" %} +{% enduml %} + +**Figure 4 -- Bulk Transaction** + +#### 4.4.4 Internal Processing Steps + +This section provides descriptions of and assumptions made for all steps in the sequence shown in Figure 4. + +**Lookup Counterparties** + +1. **Description** + + The Payer initiates the bulk transaction process by uploading a bulk file to the Payer FSP, using the Payer FSP's front-end API (outside the scope of this API). + + **Assumptions** + + None. + + **Loop for each Transaction in bulk file** + +2. **Description** + + Payer FSP tries to find the Payee within the Payer FSP system. + + **Assumptions** + + The Payee is assumed to be located in a different FSP than the Payer. If the Payee is within the Payer FSP, the transaction can be handled internally in the Payer FSP (outside the scope of this API). + +3. **Description** + + The Payer FSP sends the request **Lookup Participant Information** to the optional Account Lookup System to get information regarding in which FSP the Payer is present in. + + **Assumptions** + + The Payee is assumed to in a different FSP than the Payer. Also, an Account Lookup System is assumed to exist. The Account Lookup System is optional in the process, as the request **Lookup Participant Information** could also be sent directly to the Payee FSPs if there is no Account Lookup System. As the Payer FSP should not know in which FSP the Payee is located in if there is no Account Lookup System present, the request might need to be sent to more than one FSP. It is also possible that the Payer FSP would like more information about the Payee before a bulk transaction is executed; for example, for additional verification purposes of the Payee name. In that case, the request **Lookup Party Information**, either to the Switch or directly to the Payee FSP, should be sent instead of the request **Lookup Participant Information** to the Account Lookup System. + +4. **Description** + + The Account Lookup System receives the request **Lookup Participant Information.** It then performs an internal lookup to find in which FSP the Payee is located. When the lookup is completed, the response **Return Participant Information** is sent to inform the Payer FSP about which FSP the Payee is located in. + + **Assumptions** + + The Payee can be found by the Account Lookup System. + +5. **Description** + + The Payer FSP receives the response **Return Participant Information**. The Payee and the related transaction is then placed in a new bulk file separated per Payee FSP. + + **Assumptions** + + None. + + **End of loop for each Transaction** + + **Calculate Bulk Quote** + + **Loop for each Payee FSP to Calculate Bulk Quote** + +6. **Description** + + The Payer FSP uses the request **Calculate Bulk Quote** on a Switch to retrieve a quote for performing the bulk transaction from the Payer FSP to the Payee FSP. The request contains details for each individual transaction in the bulk transaction. + + **Assumptions** + + In this sequence, a Switch is placed between the Payer FSP and the Payee FSP to route the messages. The Switch is optional in the process, as the request **Calculate Bulk Quote** could also be sent directly to the Payee FSP if there is no Switch in-between. + +7. **Description** + + The Switch receives the **Calculate Bulk Quote** request. The Switch then routes the request to the Payee FSP, using the same parameters. + + **Assumptions** + + None. + +8. **Description** + + The Payee FSP receives the **Calculate Bulk Quote** request. The Payee FSP then internally calculates the fees or FSP commission for performing each individual transaction in the bulk transaction. For each individual transaction, the Payee FSP then constructs an ILP Packet containing the ILP Address of the Payee, the amount that the Payee will receive, and the transaction details. The fulfilment and the condition is then generated out of the ILP Packet combined with a local secret. It then uses the response **Return Bulk Quote Information** to the Switch to inform the Payer FSP about the fees involved in performing the bulk transaction and the ILP Packet and condition. The bulk quote has an expiration date and time, to inform the Payer FSP until which time the bulk quote is valid. + + **Assumptions** + + The bulk quote can be calculated by the Payee FSP. + +9. **Description** + + The Switch receives the response **Return Bulk Quote Information**. The Switch then routes the response to the Payer FSP. + + **Assumptions** + + None. + +10. **Description** + + The Payer FSP receives the response **Return Bulk Quote Information** from the Switch. + + **Assumptions** + + None. + + **End of loop for each Payee FSP** + +11. **Description** + + The Payer FSP calculates any internal bulk fees and taxes, and informs the Payer using a front-end API (outside the scope of this API) about the total fees and taxes to perform the bulk transaction. + + **Assumptions** + + None. + +12. **Description** + + The Payer receives the notification about the completed processing of the bulk transaction and the fees and taxes to perform the bulk transaction. The Payer then decides to execute the bulk transaction. + + **Assumptions** + + The Payer is assumed to execute the bulk transaction. If the Payer would reject the bulk transaction at this stage, no response is sent to the Payee FSP. The created bulk quote at the Payee FSPs should have an expiry date; that is, at which time it's automatically deleted. + + **Perform Bulk Transfer** + +13. **Description** + + The Payer FSP receives the request to execute the bulk transaction from the Payer. + + **Assumptions** + + None. + + **Loop for each Payee FSP to perform Bulk Transfer** + +14. **Description** + + The Payer FSP performs all applicable internal transaction validations (for example, limit checks, blacklist check, and so on) for the bulk transaction to the Payee FSP. If the validations are successful, a transfer of funds is reserved from the Payer's account to either a combined Switch account or a Payee FSP account, depending on setup. After the transfer has been successfully reserved, the request **Perform Bulk Transfer** is sent to the Switch. The request **Perform Bulk Transfer includes** a reference to the earlier bulk quote, an expiry of the bulk transfer, and the ILP Packets and condition per transfer that was received from the Payee FSP. The interoperable financial transaction is now irrevocable from the Payer FSP. The interoperable bulk transaction is now irrevocable from the Payer FSP. + + **Assumptions** + + In this sequence, a Switch is placed between the Payer FSP and the Payee FSP to route the messages. The Switch is optional in the process, as the request **Perform Bulk Transfer** could also be sent directly to the Payee FSP if there is no Switch in-between. + +15. **Description** + + The Switch receives the request **Perform Bulk Transfer**. The Switch then performs all applicable internal transfer validations (such as limit checks, blacklist check, and so on). If the validations are successful, a transfer is reserved from a Payer FSP account to a Payee FSP account. After the transfer has been successfully reserved, the request **Perform Bulk Transfer** is sent to the Payee FSP, including the same ILP Packets and conditions for each transfer that were received from the Payer FSP. The expiry time should be decreased by the Switch so that the Payee FSP should answer before the Switch should answer to the Payer FSP. The bulk transfer is now irrevocable from the Switch. + + **Assumptions** + + Internal validations and reservation are successful. + +16. **Description** + + The Payee FSP receives the request **Perform Bulk Transfer**. The Payee FSP then performs all applicable internal transaction validations (such as limit checks, and blacklist checks) for each individual transaction in the bulk transaction. If the validations are successful, a transfer of funds is performed from either a combined Switch account or a Payer FSP account, depending on setup, to each of the Payees' accounts and the fulfilment of each condition is regenerated, using the same secret as in Step 8. After each transfer to a Payee has been successfully performed, a transaction notification is sent to the Payee using a front-end API (out of scope of this API). After each of the individual transactions in the bulk transaction has been completed, the response **Return Bulk Transfer Information** is sent to the Switch to inform the Switch and the Payer FSP of the result including each fulfilment. The transactions in the bulk transaction are now irrevocable from the Payee FSP. + + **Assumptions** + + Internal validations and transfers of funds are successful. + +17. **Description** + + Each Payee receives a transaction notification containing information about the successfully performed transaction. + + **Assumptions** + + None. + +18. **Description** + + The Switch receives the response **Return Bulk Transfer Information**. The Switch then validates the fulfilments and commits the earlier reserved transfers. The Switch then uses the response **Return Bulk Transfer Information** to the Payer FSP, using the same parameters. + + **Assumptions** + + Each individual transaction in the bulk transaction is assumed to be successful in the Payee FSP, and the validation of the fulfilments is also assumed to be correct. If one or more of the transactions in the bulk transaction were unsuccessful, the earlier reserved, now unsuccessful, transfer or transfers in the Switch would need to be cancelled. + +19. **Description** + + The Payer FSP receives the response **Return Bulk Transfer Information**. The Payer FSP then commits the earlier reserved transfers. After the bulk transaction has been successfully committed, a transaction notification is sent to the Payer using a front-end API (out of scope of this API). + + **Assumptions** + + Each individual transaction in the bulk transaction is assumed to be successful in the Payee FSP, and the validation of the fulfilments is also assumed to be correct. If one or more of the transactions in the bulk transaction were unsuccessful, the earlier reserved transfer in the Payer FSP would need to be updated with the total amount of all successful transactions before being committed. + + **End of loop for each Payee FSP** + +20. **Description** + + After each of the Payee FSPs has executed their part of the bulk transaction, a response is sent to the Payer using a front- end API (out of scope for this API). + + **Assumptions** + + None. + +21. **Description** + + The Payer receives a bulk transaction notification containing information about the successfully performed bulk transaction. + + **Assumptions** + + None. + +## 5. References + +1 [https://interledger.org/rfcs/0011-interledger-payment-request/ - Interledger Payment Request (IPR)](https://interledger.org/rfcs/0011-interledger-payment-request) + +2 [https://interledger.org/ - Interledger](https://interledger.org) + +3 [https://interledger.org/interledger.pdf - A Protocol for Interledger Payments](https://interledger.org/interledger.pdf) + +4 [https://interledger.org/rfcs/0001-interledger-architecture/ - Interledger Architecture](https://interledger.org/rfcs/0001-interledger-architecture) diff --git a/documents/JSON Binding Rules.md b/documents/JSON Binding Rules.md new file mode 100644 index 00000000..3751d9ca --- /dev/null +++ b/documents/JSON Binding Rules.md @@ -0,0 +1,1345 @@ +--- +showToc: true +--- + +# JSON Binding Rules + +## Open API for FSP Interoperability Specification + +**Table of Contents** + +[1. Preface](#1-preface) + +[1.1 Conventions Used in This Document](#11-conventions-used-in-this-document) + +[1.2 Document Version Information](#12-document-version-information) + +[2. Introduction](#2-introduction) + +[2.1 Open API for FSP Interoperability Specification](#21-open-api-for-fsp-interoperability-specification) + +[3. Keywords and Usage](#3-keywords-and-usage) + +[3.1 Validation Keywords](#31-validation-keywords) + +[3.2 Metadata Keywords](#32-metadata-keywords) + +[3.3 Instance and \$ref](#33-instance-and-$ref) + +[3.4 JSON Definitions and Examples](#34-json-definitions-and-examples) + +[4. Element and Basic Data Types](#4-element-and-basic-data-types) + +[4.1 Data Type Amount](#41-data-type-amount) + +[4.2 Data Type BinaryString](#42-data-type-binaryString) + +[4.3 Data Type BinaryString32](#43-data-type-binaryString32) + +[4.4 Data Type BopCode](#44-data-type-bopcode) + +[4.5 Data Type Enum](#45-data-type-enum) + +[4.6 Data Type Date](#46-data-type-date) + +[4.7 Data Type DateTime](#47-data-type-datetime) + +[4.8 Data Type ErrorCode](#48-data-type-errorcode) + +[4.9 Data Type Integer](#49-data-type-integer) + +[4.10 Data Type Latitude](#410-data-type-latitude) + +[4.11 Data Type Longitude](#411-data-type-longitude) + +[4.12 Data Type MerchantClassificationCode](#412-data-type-merchantclassificationcode) + +[4.13 Data Type Name](#413-data-type-name) + +[4.14 Data Type OtpValue](#414-data-type-otpvalue) + +[4.15 Data Type String](#415-data-type-string) + +[4.16 Data Type TokenCode](#416-data-type-tokencode) + +[4.17 Data Type UndefinedEnum](#417-data-type-undefinedenum) + +[4.18 Data Type UUID](#418-data-type-uuid) + +[5. Complex Type](#5-complex-type) + +[5.1 Complex Type Definition, Transformation](#51-complex-type-definition,-transformation) + +[5.2 Types of objects in Requests or Responses](#52-types-of-objects-in-requests-or-responses) + +[6. References](#6-references) + +**Table of Listings** + +[Listing 1 -- JSON Schema for Data type Amount](#listing-1) + +[Listing 2 -- JSON Schema for Data type BinaryString](#listing-2) + +[Listing 3 -- JSON Schema for BinaryString type IlpPacket](#listing-3) + +[Listing 4 -- JSON Schema for Data type BinaryString32](#listing-4) + +[Listing 5 -- JSON Schema for BinaryString32 type IlpCondition](#listing-5) + +[Listing 6 -- JSON Schema for Data type BopCode](#listing-6) + +[Listing 7 -- List of Enum types specified and used in the API](#listing-7) + +[Listing 8 -- JSON Schema for Enumeration Type AmountType](#listing-8) + +[Listing 9 -- JSON Schema for Data type Date](#listing-9) + +[Listing 10 -- JSON Schema for Date type DateOfBirth](#listing-10) + +[Listing 11 -- JSON Schema for Data type DateTime](#listing-11) + +[Listing 12 -- JSON Schema for Data type ErrorCode](#listing-12) + +[Listing 13 -- JSON Schema for Data type Integer](#listing-13) + +[Listing 14 -- JSON Schema for Data type Latitude](#listing-14) + +[Listing 15 -- JSON Schema for Data type Longitude](#listing-15) + +[Listing 16 -- JSON Schema for Data type MerchantClassificationCode](#listing-16) + +[Listing 17 -- JSON Schema for Data type Name](#listing-17) + +[Listing 18 -- JSON Schema for Name type FirstName](#listing-18) + +[Listing 19 -- JSON Schema for Data type OtpValue](#listing-19) + +[Listing 20 -- String types specified and used in the API](#listing-20) + +[Listing 21 -- JSON Schema for Data type ErrorDescription](#listing-21) + +[Listing 22 -- JSON Schema for Data type TokenCode](#listing-22) + +[Listing 23 -- JSON Schema for TokenCode type Code](#listing-23) + +[Listing 24 -- JSON Schema for Data type UndefinedEnum](#listing-24) + +[Listing 25 -- JSON Schema for Data type UUID](#listing-25) + +[Listing 26 -- JSON Schema for complex type AuthenticationInfo](#listing-26) + +[Listing 27 -- Example instance of AuthenticationInfo complex type](#listing-27) + +[Listing 28 -- Complex type Examples](#listing-28) + +[Listing 29 -- JSON Schema for complex type AuthorizationsIDPutResponse](#listing-29) + +[Listing 30 -- Example instance of AuthorizationsIDPutResponse complex type](#listing-30) + +[Listing 31 -- Complex type Examples for Objects in Requests and Responses in the API](#listing-31) + +## 1. Preface + +This section contains information about how to use this document. + +### 1.1 Conventions Used in This Document + +The following conventions are used in this document to identify the specified types of information + +|Type of Information|Convention|Example| +|---|---|---| +|**Elements of the API, such as resources**|Boldface|**/authorization**| +|**Variables**|Italics within curly brackets|_{ID}_| +|**Glossary terms**|Italics on first occurrence; defined in _Glossary_|The purpose of the API is to enable interoperable financial transactions between a _Payer_ (a payer of electronic funds in a payment transaction) located in one _FSP_ (an entity that provides a digital financial service to an end user) and a _Payee_ (a recipient of electronic funds in a payment transaction) located in another FSP.| +|**Library documents**|Italics|User information should, in general, not be used by API deployments; the security measures detailed in _API Signature_ and _API Encryption_ should be used instead.| + +### 1.2 Document Version Information + +|Version|Date|Change Description| +|---|---|---| +|**1.0**|2019-03-12|Initial version| + +## 2. Introduction + +The purpose of this document is to express the data model used by the Open API for FSP Interoperability (hereafter cited as "the API") in the form of JSON Schema binding rules, along with the validation rules for their corresponding instances. + +This document adds to and builds on the information provided in _Open API for FSP Interoperability Specification._ The contents of the Specification are listed in [Section 2.1](#21-open-api-for-fsp-interoperability-specification). + +The types used in the PDP API fall primarily into three categories: + +- Basic data types and Formats used + +- Element types + +- Complex types + +The various types used in _API Definition_, _Data Model_ and the _Open API Specification_, as well as the JSON transformation rules to which their instances must adhere, are identified in the following sections. + +### 2.1 Open API for FSP Interoperability Specification + +The Open API for FSP Interoperability Specification includes the following documents. + +#### 2.1.1 General Documents + +- _Glossary_ + +#### 2.1.2 Logical Documents + +- _Logical Data Model_ + +- _Generic Transaction Patterns_ + +- _Use Cases_ + +#### 2.1.3 Asynchronous REST Binding Documents + +- _API Definition_ + +- _JSON Binding Rules_ + +- _Scheme Rules_ + +#### 2.1.4 Data Integrity, Confidentiality, and Non-Repudiation + +- _PKI Best Practices_ + +- _Signature_ + +- _Encryption_ + +## 3. Keywords and Usage + +The _keywords_ used in the JSON Schemas and rules are derived from _JSON Schema Specification_[1](http://json-schema.org/documentation.html). The types of keywords used are identified in [Sections 3.1](#31-validation-keywords), [3.2](#32-metadata-keywords) and [3.3](#33-instance-and-$ref). As discussed in detail later, some of these keywords specify validation parameters whereas others are more descriptive, such as Metadata. The description that follows specifies details such as whether a field MUST[2](https://www.ietf.org/rfc/rfc2119.txt) be present in the definition and whether a certain field is associated with a particular data type. + +### 3.1 Validation Keywords + +This section[3](http://json-schema.org/latest/json-schema-validation.html) provides descriptions of the keywords used for validation in _API Definition_. Validation keywords in a schema impose requirements for successful validation of an instance. + +#### 3.1.1 maxLength + +The value of this keyword MUST be a non-negative integer. A string instance is valid against this keyword if its length is less than, or equal to, the value of this keyword. The length of a string instance is defined as the number of its characters as defined by RFC 7159[RFC7159]. + +#### 3.1.2 minLength + +The value of this keyword MUST be a non-negative integer. A string instance is valid against this keyword if its length is greater than, or equal to, the value of this keyword. The length of a string instance is defined as the number of its characters as defined by RFC 7159[RFC7159]. Omitting this keyword has the same behaviour as assigning it a value of **0**. + +#### 3.1.3 pattern + +The value of this keyword MUST be a string. This string SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect. A string instance is considered valid if the regular expression matches the instance successfully. Recall: regular expressions are not implicitly anchored. + +#### 3.1.4 items + +The value of _items_ MUST be either a valid JSON Schema or an array of valid JSON Schemas. This keyword determines how child instances validate for arrays; it does not directly validate the immediate instance itself. If _items_ is a schema, validation succeeds if all elements in the array successfully validate against that schema. If _items_ is an array of schemas, validation succeeds if each element of the instance validates against the schema at the same position, if such a schema exists. Omitting this keyword has the same behaviour as specifying an empty schema. + +#### 3.1.5 maxItems + +The value of this keyword MUST be a non-negative integer. An array instance is valid against _maxItems_ if its size is less than, or equal to, the value of this keyword. + +#### 3.1.6 minItems + +The value of this keyword MUST be a non-negative integer. An array instance is valid against _minItems_ if its size is greater than, or equal to, the value of this keyword. Omitting this keyword has the same behaviour as a value of **0**. + +#### 3.1.7 required + +The value of this keyword MUST be an array. Elements of this array (if there are any) MUST be strings and MUST be unique. An object instance is valid against this keyword if every item in the array is the name of a property in the instance. Omitting this keyword results in the same behaviour as does having the array be empty. + +#### 3.1.8 properties + +The value of _properties_ MUST be an object. Each value of this object MUST be a valid JSON Schema. This keyword determines how child instances validate for objects; it does not directly validate the immediate instance itself. Validation succeeds if, for each name that appears in both the instance and as a name within this keyword's value, the child instance for that name successfully validates against the corresponding schema. Omitting this keyword results in the same behaviour as does having an empty object. + +#### 3.1.9 enum + +The value of this keyword MUST be an array. This array SHOULD have at least one element. Elements in the array SHOULD be unique. An instance validates successfully against this keyword if its value is equal to one of the elements in this keyword's array value. Elements in the array might be of any value, including null. + +#### 3.1.10 type + +The value of this keyword MUST be either a string or an array. If it is an array, elements of the array MUST be strings and MUST be unique. String values MUST be one of the six primitive types (null, boolean, object, array, number, or string), or integer which matches any number with a zero-fractional part. An instance validates if and only if the instance is in any of the sets listed for this keyword. + +This specification uses string type for all basic types and element types, but enforces restrictions using regular expressions as _patterns_. Complex types are of object type and contain properties that are either element or object types in turn. Array types are used to specify lists, which are currently only used as part of complex types. + +### 3.2 Metadata Keywords + +This section provides descriptions of the fields used in the JSON definitions of the types used. The description specifies whether a field MUST be present in the definition and specifies whether a certain field is associated with a primary data type. Validation keywords in a schema impose requirements for successful validation of an instance. + +#### 3.2.1 definitions + +This keyword's value MUST be an object. Each member value of this object MUST be a valid JSON Schema. This keyword plays no role in validation. Its role is to provide a standardized location for schema authors to incorporate JSON Schemas into a more general schema. + +#### 3.2.2 "title" and "description" + +The value of both keywords MUST be a string. Both keywords can be used to provide a user interface with information about the data produced by this user interface. A title will preferably be short, whereas a description will provide explanation about the purpose of the instance described in this schema. + +### 3.3 Instance and $ref + +Two keywords, **Instance** and **$ref** are used in either the JSON Schema definitions or the transformation rules in this document, which are described in [Sections 3.3.1](#331-instance) and [3.3.2](#332-schema-references-with-$ref-keyword). **Instance** is not used in the Open API Specification; this term is used in this document to describe validation and transformation rules. **$ref** contains a URI value as a reference to other types; it is used in the Specification. + +#### 3.3.1 Instance + +JSON Schema interprets documents according to a data model. A JSON value interpreted according to this data model is called an _instance_[4](http://json-schema.org/latest/json-schema-core.html\#rfc.section.4.2). An instance has one of six primitive types, and a range of possible values depending on the type: + +null: A JSON **null** production + +boolean: A **true** or **false** value, from the JSON **true** or **false** productions + +object: An unordered set of properties mapping a string to an instance, from the JSON **object** production + +array: An ordered list of instances, from the JSON **array** production + +number: An arbitrary-precision, base-10 decimal number value, from the JSON **number** production + +string: A string of Unicode code points, from the JSON **string** production + +Whitespace and formatting concerns are outside the scope of the JSON Schema. Since an object cannot have two properties with the same key, behaviour for a JSON document that tries to define two properties (the **member** production) with the same key (the **string** production) in a single object is undefined. + +#### 3.3.2 Schema references with $ref keyword + +The **$ref**[5](http://json-schema.org/latest/json-schema-core.html\#rfc.section.8) keyword is used to reference a schema and provides the ability to validate recursive structures through self- reference. An object schema with a **$ref** property MUST be interpreted as a **"$ref"** reference. The value of the **$ref** property MUST be a URI Reference. Resolved against the current URI base, it identifies the URI of a schema to use. All other properties in a **"$ref"** object MUST be ignored. + +The URI is not a network locator, only an identifier. A schema need not be downloadable from the address if it is a network- addressable URL, and implementations SHOULD NOT assume they should perform a network operation when they encounter a network-addressable URI. A schema MUST NOT be run into an infinite loop against a schema. For example, if two schemas "#alice" and "#bob" both have an "allOf" property that refers to the other, a naive validator might get stuck in an infinite recursive loop trying to validate the instance. Schemas SHOULD NOT make use of infinite recursive nesting like this; the behavior is undefined. + +It is used with the syntax **"$ref"** and is mapped to an existing definition. From the syntax, the value part of _$ref_, **#/definitions/**, indicates that the type being referenced is from the Definitions section of the Open API Specification (Typically, an Open API Specification has sections named Paths, Definitions, Responses and Parameters.). An example for this can be found in [Listing 26](#listing-26), where the types for properties **authentication** and **authenticationValue** are provided by using references to Authenticationtype and AuthenticationValue types, respectively. + +### 3.4 JSON Definitions and Examples + +JSON definitions and examples are provided after most sections defining the transformation rules, where relevant. These are provided in JSON form, taken from the JSON version of the Open API Specification. The Regular Expressions in the examples may have minor differences (sometimes having an additional '**\\**' symbol) when compared to the ones in rules and descriptions because the regular expressions in the examples are taken from the JSON version whereas the rules and descriptions are from the standard Open API (Swagger) Specification. They are provided in the relevant section as a numbered Listing. For example, [Listing 1](#listing-1) provides the JSON representation of the definition of data type Amount. + +For each of the data types, a description of the JSON Schema from the Open API Specification and (where relevant) an example of that type are provided. Following the Schema description are transformation rules that apply to an instance of that particular type. + +## 4. Element and Basic Data Types + +This section contains the definitions of and transformation rules for the basic formats and _element_ types used by the API as specified in _API Definition_ and _API Data Model_. These definitions are basic in the context of the API specification, but *not* the Open API Technical Specification. Often, these basic data types are derived from the basic types supported by Open API Specification standards, such as string type. + +### 4.1 Data Type Amount + +This section provides the JSON Schema definition for the data type Amount. [Listing 1](#listing-1) provides a JSON Schema for the Amount type. + +- JSON value pair with Name "**title**" and Value "**Amount**" + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**pattern**" and Value "**^(\[0\]\|(\[1-9\]\[0-9\]{0,17}))(\[.\]\[0-9\]{0,3}\[1-9\])?\$**" + +- JSON value pair with Name "**description**" and Value "**The API data type Amount is a JSON String in a canonical format that is restricted by a regular expression for interoperability reasons. This pattern does not allow any trailing zeroes at all, but allows an amount without a minor currency unit. It also only allows four digits in the minor currency unit; a negative value is not allowed. Using more than 18 digits in the major currency unit is not allowed.**" + +###### Listing 1 + + +```JSON +"Amount": { + "title": "Amount", + "type": "string", + "pattern": + "^([0]|([1-9][0-9]{0,17}))([.][0-9]{0,3}[1-9])?$", + "maxLength": 32, + "description": "The API data type Amount is a JSON String in a canonical format that is restricted by a regular expression for interoperability reasons." +} +``` +**Listing 1 -- JSON Schema for Data type Amount** + +The transformation rules for an instance of Amount data type are as follows: + +- A given Instance of Amount type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^(\[0\]\|(\[1-9\]\[0-9\]{0,17}))(\[.\]\[0-9\]{0,3}\[1-9\])?\$** + +- The length of this instance is restricted by the regular expression above as 23, with 18 digits in the major currency unit and four digits in the minor currency unit. Valid example values for Amount type: **124.45**, **5, 5.5, 4.4444, 0.5, 0, 181818181818181818** + +### 4.2 Data Type BinaryString + +This section provides the JSON Schema definition for the data type BinaryString. [Listing 2](#listing-2) provides a JSON Schema for the BinaryString type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**BinaryString**" + +- JSON value pair with Name "**pattern**" and Value "**^\[A-Za-z0-9-\_\]+\[=\]{0,2}\$**" + +- JSON value pair with Name "**description**" and Value the content of Property **description** + +###### Listing 2 + +```JSON +"BinaryString":{ + "title":"BinaryString", + "type":"string", + "pattern":"^[A-Za-z0-9-_]+[=]{0,2}$", + "description":"The API data type BinaryString is a JSON String. The string is the base64url encoding of a string of raw bytes, where padding (character '=') is added at the end of the data if needed to ensure that the string is a multiple of 4 characters. The length restriction indicates the allowed number of characters. +} +``` +**Listing 2 -- JSON Schema for Data type BinaryString** + +[Section 4.2.1](#421-binarystring-type-ilppacket) gives an example for BinaryString type. + +The transformation rules for an instance of BinaryString data type are as follows: + +- A given Instance of BinaryString type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^\[A-Za-z0-9-\_\]+\[=\]{0,2}\$** + +An example value for BinaryString type is + +```text +AYIBgQAAAAAAAASwNGxldmVsb25lLmRmc3AxLm1lci45T2RTOF81MDdqUUZERmZlakgyOVc4bXFmNEpLMHlGTFGCAUBQU0svMS4wCk5vbmNlOiB1SXlweUYzY3pYSXBFdzVVc05TYWh3CkVuY3J5cHRpb246IG5vbmUKUGF5bWVudC1JZDogMTMyMzZhM2ItOGZhOC00MTYzLTg0NDctNGMzZWQzZGE5OGE3CgpDb250ZW50LUxlbmd0aDogMTM1CkNvbnRlbnQtVHlwZTogYXBwbGljYXRpb24vanNvbgpTZW5kZXItSWRlbnRpZmllcjogOTI4MDYzOTEKCiJ7XCJmZWVcIjowLFwidHJhbnNmZXJDb2RlXCI6XCJpbnZvaWNlXCIsXCJkZWJpdE5hbWVcIjpcImFsaWNlIGNvb3BlclwiLFwiY3JlZGl0TmFtZVwiOlwibWVyIGNoYW50XCIsXCJkZWJpdElkZW50aWZpZXJcIjpcIjkyODA2MzkxXCJ9Ig +``` + +#### 4.2.1 BinaryString Type IlpPacket + +This section provides the JSON Schema definition for the BinaryString type IlpPacket. [Listing 3](listing-3) provides a JSON Schema for the IlpPacket type. The transformation rules for an instance of IlpPacket are the same as those of Data Type BinaryString. + + - JSON value pair with Name "**title**" and Value "**IlpPacket**" + - JSON value pair with Name "**type**" and Value "**string**" + - JSON value pair with Name "**pattern**" and Value "**^\[A-Za-z0-9-\_\]+\[=\]{0,2}\$**" + - JSON value pair with Name "**minLength**" and Value **1** + - JSON value pair with Name "**pattern**" and Value **32768** + - JSON value pair with Name "**description**" and Value "**Information for recipient (transport layer information).**" + +###### Listing 3 + +```json +"IlpPacket":{ + "title":"IlpPacket", + "type":"string", + "pattern":"^[A-Za-z0-9-_]+[=]{0,2}$", + "minLength":1 + "maxLength":32768 + "description":"Information for recipient (transport layer information)." +} +``` + +**Listing 3 -- JSON Schema for BinaryString type IlpPacket** + +### 4.3 Data Type BinaryString32 + +This section provides the JSON Schema definition for the data type BinaryString32. [Listing 4](#listing-4) provides a JSON Schema for the BinaryString32 type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**BinaryString32**" + +- JSON value pair with Name "**pattern**" and Value "**^\[A-Za-z0-9-\_\]{43}\$**" + +- JSON value pair with Name "**description**" and Value the content of Property **description** + +###### Listing 4 + +```json +"BinaryString32":{ + "title":"BinaryString32", + "type":"string", + "pattern":"^[A-Za-z0-9-_]{43}$", + "description":"The API data type BinaryString32 is a fixed size version of the API data type BinaryString, where the raw underlying data is always of 32 bytes. The data type BinaryString32 should not use a padding character as the size of the underlying data is fixed." +} +``` + +**Listing 4 -- JSON Schema for Data type BinaryString32** + +[Section 4.3.1](#431-binarystring32-type-ilpcondition) gives an example for BinaryString32 type. Another example in the API of BinaryString32 type is IlpFulfilment. The transformation rules for an instance of Amount data type are as follows: + +- A given Instance of BinaryString type MUST be of String Type. + +- The instance MUST be a match for the regular expression "**^\[A-Za-z0-9-\_\]{43}\$**". + +An example value for BinaryString32 type is: + +```text +AYIBgQAAAAAAAASwNGxldmVsb25lLmRmc3AxLm1lci45T2RTOF81MDdqUUZERmZlakgyOVc4bXFmNEpLMHlGTFGCAUBQU0svMS4wCk5vbmNlOiB1SXlweUYzY3pYSXBFdzVVc05TYWh3CkVuY3J5cHRpb246IG5vbmUKUGF5bWVudC1JZDogMTMyMzZhM2ItOGZhOC00MTYzLTg0NDctNGMzZWQzZGE5OGE3CgpDb250ZW50LUxlbmd0aDogMTM1CkNvbnRlbnQtVHlwZTogYXBwbGljYXRpb24vanNvbgpTZW5kZXItSWRlbnRpZmllcjogOTI4MDYzOTEKCiJ7XCJmZWVcIjowLFwidHJhbnNmZXJDb2RlXCI6XCJpbnZvaWNlXCIsXCJkZWJpdE5hbWVcIjpcImFsaWNlIGNvb3BlclwiLFwiY3JlZGl0TmFtZVwiOlwibWVyIGNoYW50XCIsXCJkZWJpdElkZW50aWZpZXJcIjpcIjkyODA2MzkxXCJ9IgA +``` + +#### 4.3.1 BinaryString32 Type IlpCondition + +This section provides the JSON Schema definition for the BinaryString32 type IlpCondition. [Listing 5](#listing-5) provides a JSON Schema for the IlpCondition type. The transformation rules for an instance of IlpCondition are the same as those of Data Type BinaryString32. + +- JSON value pair with Name "**title**" and Value "**IlpCondition**" + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**pattern**" and Value "**^\[A-Za-z0-9-\_\]{43}\$**" + +- JSON value pair with Name "**maxLength**" and Value **48** + +- JSON value pair with Name "**description**" and Value "**Condition that must be attached to the transfer by the Payer.**" + +###### Listing 5 + +```json +"IlpCondition":{ + "title":"IlpCondition", + "type":"string", + "pattern":"^[A-Za-z0-9-_]{43}$", + "maxLength":48, + "description":"Condition that must be attached to the transfer by the Payer." +} +``` + +**Listing 5 -- JSON Schema for BinaryString32 type IlpCondition** + +### 4.4 Data Type BopCode + +This section provides the JSON Schema definition for the data type BopCode. [Listing 6](#listing-6) provides a JSON Schema for the BopCode type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**BalanceOfPayments**" + +- JSON value pair with Name "**pattern**" and Value "**^\[1-9\]\\d{2}\$**" + +- JSON value pair with Name "**description**" and Value "**The API data type BopCode is a JSON String of 3 characters, consisting of digits only. Negative numbers are not allowed. A leading zero is not allowed. [https://www.imf.org/external/np/sta/bopcode/](https://www.imf.org/external/np/sta/bopcode/).**" + +###### Listing 6 + +```json +"BalanceOfPayments":{ + "title":"BalanceOfPayments", + "type":"string", + "pattern":"^[1-9]\d{2}$", + "description":"(BopCode) The API data type BopCode is a JSON String of 3 characters, consisting of digits only. Negative numbers are not allowed. A leading zero is not allowed. https://www.imf.org/external/np/sta/bopcode/" +} +``` + +**Listing 6 -- JSON Schema for Data type BopCode** + +The transformation rules for an instance of BopCode data type are as follows: + +- A given Instance of BopCode type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^\[1-9\]\\d{2}\$**. + +An example value for BopCode type is **124**. + +### 4.5 Data Type Enum + +This section provides the JSON Schema definition for the data type Enum. These are generic characteristics of an Enum type, alternately known as CodeSet. [Listing 8](#listing-8) provides an example JSON Schema for the data type Enumeration (CodeSet). + +- CodeSet.Name is the name of the JSON object. + +- JSON value pair with Name "**title**" and Value "**CodeSet.Name**" + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**enum**" and Value the array containing all the CodeSetLiteral values of the CodeSet + +- If Property description is not empty, JSON value pair with Name "**description**" and Value the content of Property description An example for Enum/CodeSet type -- "AmountType" can found in [Section 4.5.1](#451-enumeration-amounttype). [Listing 7](#listing-7) lists the other Enum types defined and used in the API. + +###### Listing 7 + +```text +AuthenticationType, AuthorizationResponse, BulkTransferState, Currency, PartyIdentifier, PartyIdType, PartySubIdOrType , PersonalIdentifierType, TransactionInitiator, TransactionInitiatorType, TransactionRequestState, TransactionScenario, TransactionState, TransferState. +``` + +**Listing 7 -- List of Enum types specified and used in the API** + +The transformation rules for an instance of Enum data type are as +follows: + +- A given Instance of Enum type MUST be of String Type. + +- The instance MUST be one of the values specified in the CodeSetLiteral values. + +#### 4.5.1 Enumeration AmountType + +This section provides the JSON Schema definition for the Enum type AmountType. [Listing 8](#listing-8) provides a JSON Schema for the AmountType type. + +- CodeSet.Name "**AmountType**" + +- JSON value pair with Name "**title**" and Value "**AmountType**" + +- JSON value pair with Name "**type**"and Value "**string**" + +- JSON value pair with Name **description** and Value "**_Below are the allowed values for the enumeration AmountType_** + - **_SEND The amount the Payer would like to send, i.e. the amount that should be withdrawn from the Payer account including any fees._** + - **_RECEIVE The amount the Payer would like the Payee to receive, i.e. the amount that should be sent to the receiver exclusive fees._**" + +- JSON value pair with Name **enum** and Value the array containing the values: + + → **SEND** + + → **RECEIVE** + +###### Listing 8 + +```json +"AmountType":{ + "title":"AmountType", + "type":"string", + "enum":[ + "SEND", + "RECEIVE" + ], + "description":"Below are the allowed values for the enumeration AmountType - SEND The amount the Payer would like to send, i.e. the amount that should be withdrawn from the Payer account including any fees. - RECEIVE The amount the Payer would like the Payee to receive, i.e. the amount that should be sent to the receiver exclusive fees." +} +``` + +**Listing 8 -- JSON Schema for Enumeration Type AmountType** + +The transformation rules for an instance of AmountType data type are as follows (same as those of Data Type Enum, but listing the rules here to demonstrate a valid set of literal values): + +- A given Instance of AmountType type MUST be of "string" type. + +- The instance MUST be one of the values defined in the set: {"**SEND**", "**RECEIVE**"}. + +An example value for AmountType type is "**SEND**". + +### 4.6 Data Type Date + +This section provides the JSON Schema definition for the data type Date. [Listing 9](#listing-9) provides a JSON Schema for the Date type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**Date**" + +- JSON value pair with Name "**pattern**" and Value "**^(?:\[1-9\]\\d{3}-(?:(?:0\[1-9\]\|1\[0-2\])-(?:0\[1-9\]\|1\\d\|2\[0- 8\])\|(?:0\[13-9\]\|1\[0-2\])-(?:29\|30)\|(?:0\[13578\]\|1\[02\])-31)\|(?:\[1- 9\]\\d(?:0\[48\]\|\[2468\]\[048\]\|\[13579\]\[26\])\|(?:\[2468\]\[048\]\|\[13579\]\[26\])00)-02-29)\$**" + +- JSON value pair with Name "**description**" and Value "**The API data type Date is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons. This format is according to ISO 8601 containing a date only. A more readable version of the format is "yyyy-MM-dd", e.g. "1982-05-23" or "1987-08- 05"**." + +###### Listing 9 + +```json +"Date": { + "title": "Date", + "type": "string", + "pattern": "^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$", + "description": "The API data type Date is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons. This format is according to ISO 8601 containing a date only. A more readable version of the format is “yyyy-MM-dd”, e.g. "1982-05-23" or "1987-08-05”." +} +``` + +**Listing 9 -- JSON Schema for Data type Date** + +The transformation rules for an instance of Date data type are as follows: + +- A given Instance of AmountType type MUST be of string type. + +- The instance MUST be a match for the regular expression **^(?:\[1-9\]\\d{3}-(?:(?:0\[1-9\]\|1\[0-2\])-(?:0\[1-9\]\|1\\d\|2\[0- 8\])\|(?:0\[13-9\]\|1\[0-2\])-(?:29\|30)\|(?:0\[13578\]\|1\[02\])-31)\|(?:\[1- 9\]\\d(?:0\[48\]\|\[2468\]\[048\]\|\[13579\]\[26\])\|(?:\[2468\]\[048\]\|\[13579\]\[26\])00)-02-29)\$**. + +An example value for AmountType type is **1971-12-25**. + +#### 4.6.1 Date Type DateOfBirth + +This section provides the JSON Schema definition for the Date type DateOfBirth. [Listing 10](#listing-10) provides a JSON Schema for the DateOfBirth type. The transformation rules for an instance of DateOfBirth are the same as those of Data Type Date. + +- JSON value pair with Name "**title**" and Value "**DateOfBirth (type Date)**" + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**description**" and Value "**Date of Birth for the Party**" + +- JSON value pair with Name "**pattern**" and Value "**^(?:\[1-9\]\\d{3}-(?:(?:0\[1-9\]\|1\[0-2\])-(?:0\[1-9\]\|1\\d\|2\[0- 8\])\|(?:0\[13-9\]\|1\[0-2\])-(?:29\|30)\|(?:0\[13578\]\|1\[02\])-31)\|(?:\[1- 9\]\\d(?:0\[48\]\|\[2468\]\[048\]\|\[13579\]\[26\])\|(?:\[2468\]\[048\]\|\[13579\]\[26\])00)-02-29)\$**" + +###### Listing 10 + +```json +"DateOfBirth": { + "title": "DateOfBirth (type Date)", + "type": "string", + "pattern": "^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)$", + "description": "Date of Birth for the Party." +} +``` + +**Listing 10 -- JSON Schema for Date type DateOfBirth** + +### 4.7 Data Type DateTime + +The JSON Schema definition for this section provides the JSON Schema definition for the data type DateTime. [Listing 11](#listing-11) provides a JSON Schema for the DateTime type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**DateTime**" + +- JSON value pair with Name "**pattern**" and Value "**^(?:\[1-9\]\\d{3}-(?:(?:0\[1-9\]\|1\[0-2\])-(?:0\[1-9\]\|1\\d\|2\[0- 8\])\|(?:0\[13-9\]\|1\[0-2\])-(?:29\|30)\|(?:0\[13578\]\|1\[02\])-31)\|(?:\[1- 9\]\\d(?:0\[48\]\|\[2468\]\[048\]\|\[13579\]\[26\])\|(?:\[2468\]\[048\]\|\[13579\]\[26\])00)-02-29)T(?:\[01\]\\d\|2\[0-3\]):\[0-5\]\\d:\[0-5\]\\d(?:(\\.\\d{3}))(?:Z\|\[+-\]\[01\]\\d:\[0-5\]\\d)\$**" + +- JSON value pair with Name "**description**" and Value "**The API data type DateTime is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons. This format is according to ISO 8601, expressed in a combined date, time and time zone format. A more readable version of the format is "yyyy-MM-ddTHH:mm:ss.SSS\[-HH:MM\]", e.g. \"2016-05-24T08:38:08.699-04:00\" or \"2016-05-24T08:38:08.699Z\" (where Z indicates Zulu time zone, same as UTC)**." + +###### Listing 11 + +```json +"DateTime": { + "title":"DateTime", + "type": "string", + "pattern": "^(?:[1-9]\d{3}-(?:(?:0[1-9]|1[0-2])-(?:0[1-9]|1\d|2[0-8])|(?:0[13-9]|1[0-2])-(?:29|30)|(?:0[13578]|1[02])-31)|(?:[1-9]\d(?:0[48]|[2468][048]|[13579][26])|(?:[2468][048]|[13579][26])00)-02-29)T(?:[01\d|2[0-3]):[0-5]\d:[0-5]\d(?:(\.\d{3}))(?:Z|[+-][01]\d:[0-5]\\d)$", + "description": "The API data type DateTime is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons. This format is according to ISO 8601, expressed in a combined date, time and time zone format. A more readable version of the format is “yyyy-MM-ddTHH:mm:ss.SSS[-HH:MM]”, e.g. "2016-05-24T08:38:08.699-04:00" or "2016-05-24T08:38:08.699Z" (where Z indicates Zulu time zone, same as UTC)." +} +``` + +**Listing 11 -- JSON Schema for Data type DateTime** + +The transformation rules for an instance of DateTime data type are as follows: + +- A given Instance of type AmountType MUST be of String Type. + +- The instance MUST be a match for the regular expression **^(?:\[1-9\]\\d{3}-(?:(?:0\[1-9\]\|1\[0-2\])-(?:0\[1-9\]\|1\\d\|2\[0-8\])\|(?:0\[13-9\]\|1\[0-2\])-(?:29\|30)\|(?:0\[13578\]\|1\[02\])-31)\|(?:\[1-9\]\\d(?:0\[48\]\|\[2468\]\[048\]\|\[13579\]\[26\])\|(?:\[2468\]\[048\]\|\[13579\]\[26\])00)-02-29)T(?:\[01\]\\d\|2\[0-3\]):\[0-5\]\\d:\[0-5\]\\d(?:(\\.\\d{3}))(?:Z\|\[+-\]\[01\]\\d:\[0-5\]\\d)\$**. + +An example value for DateTime type is **2016-05-24T08:38:08.699-04:00**. + +### 4.8 Data Type ErrorCode + +This section provides the JSON Schema definition for the data type ErrorCode. [Listing 12](#listing-12) provides a JSON Schema for the ErrorCode type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**ErrorCode**" + +- JSON value pair with Name "**pattern**" and Value "**^\[1-9\]\\d{3}\$**" + +- JSON value pair with Name "**description**" and Value "**The API data type ErrorCode is a JSON String of 4 characters, consisting of digits only. Negative numbers are not allowed. A leading zero is not allowed. Specific error number in the form _{C}{E}{SS}_ where _{C}_ is a one-digit category _{E}_ is a one-digit error within the category _{SS}_ is a scheme defined two-digit sub-error within the error. Please refer to x.x for the list of the possible category/error codes**". + +###### Listing 12 + +```json +"ErrorCode": { + "title": "ErrorCode", + "type": "string", + "pattern": "^[1-9]\d{3}$", + "description": "The API data type ErrorCode is a JSON String of 4 characters, consisting of digits only. Negative numbers are not allowed. A leading zero is not allowed. Specific error number in the form {C}{E}{SS} where {C} is a one-digit category {E} is a one-digit error within the category {SS} is a scheme defined two-digit sub-error within the error. Please refer to x.x for the list of the possible category/error codes" +} +``` + +**Listing 12 -- JSON Schema for Data type ErrorCode** + +The transformation rules for an instance of ErrorCode data type are as follows: + +- A given Instance of ErrorCode type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^\[1-9\]\d{3}\$**. + +An example value for ErrorCode type is **5100**. + +### 4.9 Data Type Integer + +This section provides the JSON Schema definition for the data type Integer. [Listing 13](#listing-13) provides a JSON Schema for the Integer type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**Integer**" + +- JSON value pair with Name "**pattern**" and Value "**^\[1-9\]\d\*\$**" + +- JSON value pair with Name "**description**" and Value "**The API data type Integer is a JSON String consisting of digits only. Negative numbers and leading zeroes are not allowed. The data type is always limited by a number of digits.**" + +###### Listing 13 + +```json +"Integer": { + "title": "Integer", + "type": "string", + "pattern": "^[1-9]\d*$", + "description": "The API data type Integer is a JSON String consisting of digits only. Negative numbers and leading zeroes are not allowed. The data type is always limited by a number of digits." +} +``` + +**Listing 13 -- JSON Schema for Data type Integer** + +The transformation rules for an instance of Integer data type are as follows: + +- A given Instance of Integer type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^\[1-9\]\d\*\$**. + +An example value for Integer type is **12345**. + +### 4.10 Data Type Latitude + +This section provides the JSON Schema definition for the data type Latitude. [Listing 14](#listing-14) provides a JSON Schema for the Latitude type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**Latitude**" + +- JSON value pair with Name "**pattern**" and Value "**^(\\+\|-)?(?:90(?:(?:\\.0{1,6})?)\|(?:\[0-9\]\|\[1-8\]\[0-9\])(?:(?:\\.\[0-9\]{1,6})?))\$**" + +- JSON value pair with Name "**description**" and Value "**The API data type Latitude is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons**". + +###### Listing 14 + +```json +"Latitude": { + "title": "Latitude", + "type": "string", + "pattern": "^(\+|-)?(?:90(?:(?:\.0{1,6})?)|(?:[0-9]|[1-8][0-9])(?:(?:\.[0-9]{1,6})?))$", + "description": "The API data type Latitude is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons." +} +``` + +**Listing 14 -- JSON Schema for Data type Latitude** + +The transformation rules for an instance of Latitude data type are as follows: + +- A given Instance of Latitude type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^(\\+\|-)?(?:90(?:(?:\\.0{1,6})?)\|(?:\[0-9\]\|\[1-8\]\[0-9\])(?:(?:\\.\[0-9\]{1,6})?))\$**. + +An example value for Latitude type is **+45.4215**. + +## 4.11 Data Type Longitude + +This section provides the JSON Schema definition for the data type Longitude. [Listing 15](#listing-15) provides a JSON Schema for the Longitude type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**Longitude**" + +- If Property pattern is not empty, JSON value pair with Name "**pattern**" and Value "**^(\\+\|-)?(?:180(?:(?:\\.0{1,6})?)\|(?:\[0-9\]\|\[1-9\]\[0-9\]\|1\[0-7\]\[0-9\])(?:(?:\\.\[0-9\]{1,6})?))\$**". + +- JSON value pair with Name "**description**" and Value "**The API data type Longitude is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons.**" + +###### Listing 15 + +```json +"Longitude": { + "title": "Longitude", + "type": "string", + "pattern": "^(\+|-)?(?:180(?:(?:\.0{1,6})?)|(?:[0-9]|[1-9][0-9]|1[0-7][0-9])(?:(?:\.[0-9]{1,6})?))$", + "description": "The API data type Longitude is a JSON String in a lexical format that is restricted by a regular expression for interoperability reasons." +} +``` + +**Listing 15 -- JSON Schema for Data type Longitude** + +The transformation rules for an instance of Longitude data type are as follows: + +- A given Instance of Longitude type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^(\\+\|-)?(?:180(?:(?:\\.0{1,6})?)\|(?:\[0-9\]\|\[1-9\]\[0-9\]\|1\[0-7\]\[0-9\])(?:(?:\\.\[0-9\]{1,6})?))\$**. + +An example value for Longitude type is **+75.6972**. + +### 4.12 Data Type MerchantClassificationCode + +This section provides the JSON Schema definition for the data type MerchantClassificationCode. [Listing 16](#listing-16) provides a JSON Schema for the MerchantClassificationCode type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**MerchantClassificationCode**" + +- JSON value pair with Name "**pattern**" and Value "**^\[\\d\]{1,4}\$**". + +- JSON value pair with Name "**description**" and Value "**A limited set of pre-defined numbers. This list would be a limited set of numbers identifying a set of popular merchant types like School Fees, Pubs and Restaurants, Groceries, etc.**" + +###### Listing 16 + +```json +"MerchantClassificationCode": { + "title": "MerchantClassificationCode", + "type": "string", + "pattern": "^[\d]{1,4}$", + "description": "A limited set of pre-defined numbers. This list would be a limited set of numbers identifying a set of popular merchant types like School Fees, Pubs and Restaurants, Groceries, etc." +} +``` + +**Listing 16 -- JSON Schema for Data type MerchantClassificationCode** + +The transformation rules for an instance of MerchantClassificationCode data type are as follows: + +- A given Instance of MerchantClassificationCode type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^\[\\d\]{1,4}\$**. + +An example value for MerchantClassificationCode type is **99**. + +### 4.13 Data Type Name + +This section provides the JSON Schema definition for the data type Name. [Listing 17](#listing-17) provides the JSON Schema for a Name type. [Section 4.13.1](#4131-name-type-firstname) contains an example of Name type -- "First Name". Other Name types used in the API are "Middle Name" and "Last Name". + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**Name**" + +- JSON value pair with Name "**minLength**" and Value the content of Property **minLength** + +- JSON value pair with Name "**maxLength**" and Value the content of Property **maxLength** + +- JSON value pair with Name "**pattern**" and Value "**^(?!\\\\s\*\$)\[\\\\w .,'-\]+\$**". + +- JSON value pair with Name "**description**" and Value "**The API data type Name is a JSON String, restricted by a regular expression to avoid characters which are generally not used in a name. The restriction will not allow a string consisting of whitespace only, all Unicode characters should be allowed, as well as the characters ".", "'" (apostrophe), "-", "," and " " (space). Note - In some programming languages, Unicode support needs to be specifically enabled. As an example, if Java is used the flag UNICODE\_CHARACTER\_CLASS needs to be enabled to allow Unicode characters.**" + +###### Listing 17 + +```json +"Name": { + "title": "Name", + "type": "string", + "pattern": "^(?!\\s*$)[\\w .,'-]+$", + "description": "The API data type Name is a JSON String, restricted by a regular expression to avoid characters which are generally not used in a name. The restriction will not allow a string consisting of whitespace only, all Unicode characters should be allowed, as well as the characters ".", "'" (apostrophe), "- ", "," and " " (space). Note - In some programming languages, Unicode support needs to be specifically enabled. As an example, if Java is used the flag UNICODE_CHARACTER_CLASS needs to be enabled to allow Unicode characters." +} +``` + +**Listing 17 -- JSON Schema for Data type Name** + +The transformation rules for an instance of Name data type are as follows: + +- A given Instance of Name type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^(?!\\\\s\*\$)\[\\\\w .,'-\]+\$**. + +An example value for Name type is **Bob**. + +#### 4.13.1 Name Type FirstName + +This section provides the JSON Schema definition for the Name type FirstName. [Listing 18](#listing-18) provides a JSON Schema for the FirstName type. The transformation rules for an instance of FirstName are the same as those of Data Type . + +- JSON value pair with Name "**title**" and Value "**FirstName**" + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**pattern**" and Value "**^(?!\\s\*\$)\[\\w .,\'-\]+\$**" + +- JSON value pair with Name "**maxLength**" and Value **128** + +- JSON value pair with Name "**minLength**" and Value **1** + +- JSON value pair with Name "**description**" and Value "**First name of the Party (Name type).**" + +###### Listing 18 + +```json +"FirstName": { + "title": "FirstName", + "type": "string", + "minLength": 1, + "maxLength": 128, + "pattern": "^(?!\s*$)[\w .,'-]+$", + "description": "First name of the Party (Name Type)." +} +``` + +**Listing 18 -- JSON Schema for Name type FirstName** + +### 4.14 Data Type OtpValue + +This section provides the JSON Schema definition for the data type OtpValue. [Listing 19](#listing-19) provides a JSON Schema for the OtpValue type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**OtpValue**" + +- JSON value pair with Name "**pattern**" and Value "**^\\d{3,10}\$**" + +- JSON value pair with Name "**description**" and Value "**The API data type OtpValue is a JSON String of 3 to 10 characters, consisting of digits only. Negative numbers are not allowed. One or more leading zeros are allowed.**" + +###### Listing 19 + +```json +"OtpValue": { + "title": "OtpValue", + "type": "string", + "pattern": "^\d{3,10}$", + "description": "The API data type OtpValue is a JSON String of 3 to 10 characters, consisting of digits only. Negative numbers are not allowed. One or more leading zeros are allowed." +} +``` + +**Listing 19 -- JSON Schema for Data type OtpValue** + +The transformation rules for an instance of OtpValue data type are as follows: + +- A given Instance of OtpValue type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^\\d{3,10}\$**. + +An example value for OtpValue type is **987345**. + +### 4.15 Data Type String + +This section provides the JSON Schema definition for the data type String. [Listing 21](#listing-21) provides an example JSON Schema for a String type. + +- **String.Name** is the name of the JSON object. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**String.Name**" + +- JSON value pair with Name "**minLength**" and Value the content of Property "**minLength**" + +- JSON value pair with Name "**maxLength**" and Value the content of Property "**maxLength**" + +- If Property pattern is not empty, JSON value pair with Name **pattern** and Value the content of Property **pattern**. + +- JSON value pair with Name "**description**" and Value the content of Property **description**. Below, in [section 4.15.1](#4151-string-type-errordescription), is an example for String type, ErrorDescription. [Listing 20](#listing-20) has other String types specified and used in the API. + +###### Listing 20 + +```text +AuthenticationValue, ExtensionKey, ExtensionValue, FspId, Note, PartyName, QRCODE, RefundReason, TransactionSubScenario. +``` + +**Listing 20 -- String types specified and used in the API** + +The transformation rules for an instance of String data type are as follows: + +- A given Instance of String type MUST be of String Type. + +- The length of this instance MUST not be greater than the **maxLength** specified. + +- The length of this instance MUST not be less than the **minLength** specified. + +- The instance MUST be a match for the regular expression specified by a **pattern** property if one is specified. + +An example value for String type is **Financial Services for the Poor**. + +### 4.15.1 String Type ErrorDescription + +This section provides the JSON Schema definition for the String type ErrorDescription. [Listing 21](#listing-21) provides a JSON Schema for the ErrorDescription type. + +- JSON value pair with Name "**title**" and Value "**ErrorDescription**" + +- JSON value pair with Name "**type**" and Value "**ErrorDescription**" + +- JSON value pair with Name "**description**" and Value "**Error description string**" + +- JSON value pair with Name "**minLength**" and Value **1** + +- JSON value pair with Name "**maxLength**" and Value **128** + +###### Listing 21 + +```json +"ErrorDescription": { + "title": "ErrorDescription", + "type": "string", + "minLength": 1, + "maxLength": 128, + "description": "Error description string." +} +``` + +**Listing 21 -- JSON Schema for Data type ErrorDescription** + +The transformation rules for an instance of ErrorDescription data type are as follows (same as those of Data Type String, but listing the rules here to demonstrate a valid set of values for length properties): + +- A given Instance of AmountType type MUST be of String Type. + +- The length of this instance MUST not be greater than 128. + +- The length of this instance MUST not be less than 1. + +An example value for ErrorDescription type is **This is an error description**. + +### 4.16 Data Type TokenCode + +This section provides the JSON Schema definition for the data type TokenCode. [Listing 22](#listing-22) provides a JSON Schema for the TokenCode type. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and Value "**TokenCode**" + +- JSON value pair with Name "**pattern**" and Value "**^\[0-9a-zA-Z\]{4,32}\$**" + +- JSON value pair with Name "**description**" and Value "**The API data type TokenCode is a JSON String between 4 and 32 characters, consisting of digits or characters from a to z (case insensitive).**" + +###### Listing 22 + +```json +"TokenCode": { + "title": "TokenCode", + "type": "string", + "pattern": "^[0-9a-zA-Z]{4,32}$", + "description": "The API data type TokenCode is a JSON String between 4 and 32 characters, consisting of digits or characters from a to z (case insensitive)." +} +``` + +**Listing 22 -- JSON Schema for Data type TokenCode** + +The transformation rules for an instance of TokenCode data type are as follows: + +- A given Instance of TokenCode type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^\[0-9a-zA-Z\]{4,32}\$**. + +An example value for TokenCode type is **Test-Code**. + +#### 4.16.1 TokenCode Type Code + +This section provides the JSON Schema definition for the TokenCode type Code. [Listing 23](#listing-23) provides a JSON Schema for the Code type. The transformation rules for an instance of Code are the same as those of Data Type TokenCode. + +- JSON value pair with Name "**title**" and Value "**Code**" + +- JSON value pair with Name "**type**" and Value "**String**" + +- JSON value pair with Name "**pattern**" and Value "**^\[0-9a-zA-Z\]{4,32}\$**" + +- JSON value pair with Name "**description**" and Value "**Any code/token returned by the Payee FSP (TokenCode type).**" + +###### Listing 23 + +```json +"Code": { + "title": "Code", + "type": "string", + "pattern": "^[0-9a-zA-Z]{4,32}$", + "description": "Any code/token returned by the Payee FSP (TokenCode Type)." +} +``` + +**Listing 23 -- JSON Schema for TokenCode type Code** + +### 4.17 Data Type UndefinedEnum + +This section provides the JSON Schema definition for the data type UndefinedEnum. [Listing 24](#listing-24) provides the JSON Schema for the data type UndefinedEnum (Enumeration). + +- JSON value pair with Name "**title**" and Value "**UndefinedEnum**" + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**pattern**" and Value "**^\[A-Z\_\]{1,32}\$**" + +- If Property description is not empty, JSON value pair with Name "**description**" and Value "**The API data type UndefinedEnum is a JSON String consisting of 1 to 32 uppercase characters including "\_" (underscore).**" + +###### Listing 24 + +```json +"UndefinedEnum": { + "title": "UndefinedEnum", + "type": "string", + "pattern": "^[A-Z_]{1,32}$", + "description": "The API data type UndefinedEnum is a JSON String consisting of 1 to 32 uppercase characters including "_" (underscore)." +} +``` + +**Listing 24 -- JSON Schema for Data type UndefinedEnum** + +The transformation rules for an instance of UndefinedEnum data type are as follows: + +- A given Instance of UndefinedEnum type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^\[A-Z\_\]{1,32}\$**. + +An example value for UndefinedEnum type depends on the list of values specified. + +### 4.18 Data Type UUID + +This section provides the JSON Schema definition for the data type UUID. [Listing 25](#listing-25) provides a JSON Schema for CorrelationId which is of UUID type. Since CorrelationID is an element type in the *API Definition*, it is being used interchangeably with UUID in the Open API Specification version. + +- JSON value pair with Name "**type**" and Value "**string**" + +- JSON value pair with Name "**title**" and "**Value CorrelationId**" + +- JSON value pair with Name "**pattern**" and Value "**^\[0-9a-f\]{8}-\[0-9a-f\]{4}-\[1-5\]\[0-9a-f\]{3}-\[89ab\]\[0-9a-f\]{3}-\[0-9a- f\]{12}\$**" + +- JSON value pair with Name "**description**" and Value "**Identifier that correlates all messages of the same sequence. The API data type UUID (Universally Unique Identifier) is a JSON String in canonical format, conforming to RFC 4122, that is restricted by a regular expression for interoperability reasons. An example of a UUID is "b51ec534-ee48-4575-b6a9-ead2955b8069". An UUID is always 36 characters long, 32 hexadecimal symbols and 4 dashes ("-").**" + +###### Listing 25 + +```json +"CorrelationId": { + "title": "CorrelationId", + "type": "string", + "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a- f]{12}$", + "description": "Identifier that correlates all messages of the same sequence. The API data type UUID (Universally Unique Identifier) is a JSON String in canonical format, conforming to RFC 4122, that is restricted by a regular expression for interoperability reasons. An example of a UUID is "b51ec534-ee48-4575-b6a9- ead2955b8069". An UUID is always 36 characters long, 32 hexadecimal symbols and 4 dashes ("-")." +} +``` + +**Listing 25 -- JSON Schema for Data type UUID** + +The transformation rules for an instance of UUID data type are as follows: + +- A given Instance of UUID type MUST be of String Type. + +- The instance MUST be a match for the regular expression **^\[0-9a-f\]{8}-\[0-9a-f\]{4}-\[1-5\]\[0-9a-f\]{3}-\[89ab\]\[0-9a- f\]{3}-\[0-9a-f\]{12}\$**. + +An example value for UUID type is **b51ec534-ee48-4575-b6a9-ead2955b8069**. + +## 5 Complex Types + +This section contains definitions of and transformation characteristics for complex types that are used by the API. Along with the complex types defined in the _API Definition_ and _Data Model_ documents, there are other complex types defined in the PDP Open API Specification based on the objects present in several requests and responses in the **body** section. These are discussed in [Section 5.2](#52-types-of-objects-in-requests-or-responses). + +### 5.1 Complex Type Definition, Transformation + +This section provides the JSON Schema definition for a complex type. [Listing 26](#listing-26) provides an example JSON Schema for a complex type, AuthenticationInfo. Transformation rules specific to a complex type are listed in [Section 5.1.1](#511-complex-type-authenticationinfo). + +- JSON value pair with Name "**type**" and Value "**object**" + +- JSON value pair with Name "**title**" and Value "**complextype.Name**" + +- If Property **description** is not empty, JSON value pair with Name "**description**" and Value the content of Property **description**. + +- An array with Name "**required**" and Value the list of properties that MUST be present in an instance of complex type. + +- A JSON object **properties** with the following content: + + - A list of key, value pairs with Name **key.Name** and Value of element, complex or Array type + + - JSON value pair with Name **$ref** and as Value the concatenation of **#/definitions/** with **key.Type** type. An example for a complex type is provided under [Section 5.1.1](#511-complex-type-authenticationinfo). + +#### 5.1.1 Complex Type AuthenticationInfo + +This section provides the JSON Schema definition for the complex type AuthenticationInfo can be expressed as follows. [Listing 26](#listing-26) provides the JSON Schema for AuthenticationInfo. + +- JSON value pair with Name "**type**" and Value "**object**" + +- JSON value pair with Name "**title**" and Value "**AuthenticationInfo**" + +- JSON value pair with Name "**description**" and Value "**complex type AuthenticationInfo**" + +- An array with Name "**required**" and as Value a list with elements "**authentication**" and "**authenticationValue**" + +- A JSON object **properties** with the following content: + + - A JSON object **authentication** with the following content: + + - JSON value pair with Name "**$ref**" and as Value the concatenation of **#/definitions/** with Authenticationtype type. + + - A JSON object **authenticationValue** with the following content: + + - JSON value pair with Name "**$ref**" and as Value the concatenation of **#/definitions/** with AuthenticationValue type. + +###### Listing 26 + +```json +"AuthenticationInfo": { + "title": "AuthenticationInfo", + "type": "object", + "description": "complex type AuthenticationInfo", + "properties": { + "authentication": { + "$ref": "#/definitions/AuthenticationType", + "description": "The type of authentication." + }, + "authenticationValue":\ { + "$ref": "#/definitions/AuthenticationValue", + "description": " The authentication value." + } + }, + "required": [ + "authentication", + "authenticationValue" + ] +} +``` + +**Listing 26 -- JSON Schema for complex type AuthenticationInfo** + +The transformation rules for an instance of AuthenticationInfo complex type are as follows: + +- A given Instance of AuthenticationInfo type MUST be of Object type. + +- The instance MUST contain a property with name **authentication**. + +- The JSON object titled **authentication** MUST be an instance of AuthenticationType type, provided in the definitions. + +- The instance MUST contain a property with name **authenticationValue**. + +- The JSON object titled **authenticationValue** MUST be an instance of AuthenticationValue type, provided in the definitions. An example instance for AuthenticationInfo complex type is given in [Listing 27](#listing-27). + +###### Listing 27 + +```json +"authenticationInfo": { + "authentication": "OTP", + "authenticationValue": "1234" +} +``` + +**Listing 27 -- Example instance of AuthenticationInfo complex type** + +#### 5.1.2 Complex Types in the API + +The examples for complex type from the API appear in [Listing 28](#listing-28). The list includes complex types defined in _API Definition_ and _Data Model_ and does not contain the complex types defined only in the Open API version of the specification which capture the objects in Requests and Reponses. + +###### Listing 28 + +```text +ErrorInformation, Extension, ExtensionList, GeoCode, IndividualQuote, IndividualQuoteResult, IndividualTransfer, IndividualTransferResult, Money, Party, PartyComplexName, PartyIdInfo, PartyPersonalInfo, PartyResult, Refund, Transaction, TransactionType. +``` + +**Listing 28 -- Complex type Examples** + +### 5.2 Types of objects in Requests or Responses + +This section contains the definitions and transformation characteristics of the complex types that are used in the API Specification of the PDP API to capture objects in Requests and Responses. These have the same characteristics as the complex data types discussed in the Complex Type section. + +#### 5.2.1 Complex Type AuthorizationsIDPutResponse + +This section provides the JSON Schema definition for the complex type AuthorizationsIDPutResponse. [Listing 29](#listing-29) provides a JSON Schema for complex type AuthorizationsIDPutResponse. + +- JSON value pair with Name "**type**" and Value "**object**" + +- JSON value pair with Name "**title**" and Value "**AuthorizationsIDPutResponse**". + +- JSON value pair with Name "**description**" and Value "**PUT /authorizations/{ID} object**". + +- A JSON object "**properties**" with the following content: + + - If Property "**authenticationInfo**" is present, a JSON object "**authenticationInfo**" with the following content: + + - JSON value pair with Name "**$ref**" and as Value the definition of AuthenticationInfo type, located under **definitions** as indicated by **#/definitions/** + + - A JSON object **responseType** with the following content: + + - JSON value pair with Name "**$ref**" and as Value the definition of AuthorizationResponse type, located under **definitions** as indicated by "**#/definitions/**". + +- An array **required** and as Value a list with single element "**responseType**" + +###### Listing 29 + +```json +"AuthorizationsIDPutResponse": { + "title": "AuthorizationsIDPutResponse", + "type": "object", + "description": "PUT /authorizations/{ID} object", + "properties": { + "authenticationInfo": { + "$ref": "#/definitions/AuthenticationInfo", + "description": "OTP or QR Code if entered, otherwise empty." + } + "responseType": { + "$ref": "#/definitions/AuthorizationResponse", + "description": "Enum containing response information; if the customer entered the authentication value, rejected the transaction, or requested a resend of the authentication value." + } + }, + "required ": [ + "responseType" + ] +} +``` + +**Listing 29 -- JSON Schema for complex type AuthorizationsIDPutResponse** + +The transformation rules for an instance of AuthorizationsIDPutResponse complex type are as follows: + +- A given Instance of AuthorizationsIDPutResponse type MUST be of object type. + +- The instance MUST contain a property with name "**authenticationInfo**". + +- The JSON object titled "**authenticationInfo**" MUST be an instance of AuthenticationInfo type, provided in the definitions. + +- The instance MUST contain a property with name "**responseType**". + +- The JSON object titled "**responseType**" MUST be an instance of AuthorizationReponse type, provided in the definitions. + +An example instance for AuthorizationsIDPutResponse complex type is given in [Listing 30](#listing-30). + +###### Listing 30 + +```json +{ + "authenticationInfo": { + "authentication": "OTP", + "authenticationValue": "1234" + }, + "responseType": "ENTERED" +} +``` + +**Listing 30 -- Example instance of AuthorizationsIDPutResponse complex type** + +**5.2.2 Other Complex types in Requests and Responses** + +Other complex type examples from the API used in Requests or Responses can be found in [Listing 31](#listing-31). + +###### Listing 31 + +```text +BulkQuotesPostRequest, BulkQuotesIDPutResponse, BulkTransfersPostRequest, BulkTransfersIDPutResponse, ErrorInformationObject, ErrorInformationResponse, ParticipantsTypeIDSubIDPostRequest, ParticipantsTypeIDPutResponse, ParticipantsIDPutResponse, ParticipantsPostRequest, QuotesPostRequest, QuotesIDPutResponse, TransactionRequestsIDPutResponse, TransactionsIDPutResponse, TransfersPostRequest, TransactionRequestsPostRequest, TransfersIDPutResponse. +``` + +**Listing 31 -- Complex type Examples for Objects in Requests and Responses in the API** + +## 6. References + +1 The link for this is: [http://json-schema.org/documentation.html](http://json-schema.org/documentation.html) + +2 MUST, MAY, OPTIONAL in this document are to be interpreted as described\ in [RFC2119](https://www.ietf.org/rfc/rfc2119.txt) + +3 Most of the items in this section and the next one, "Metadata Keywords" are taken from: [http://json-schema.org/latest/json-schema-validation.html](http://json-schema.org/latest/json-schema-validation.html). Some changes are made based on Open API limitations or constraints. Also, only relevant keywords are referenced. + +4 The description for "Instance" keyword is taken from: [http://json-schema.org/latest/json-schema-core.html\#rfc.section.4.2](http://json-schema.org/latest/json-schema-core.html\#rfc.section.4.2) + +5 Meaning and usage of \$ref as specified here: [http://json-schema.org/latest/json-schema-core.html\#rfc.section.8](http://json-schema.org/latest/json-schema-core.html\#rfc.section.8) diff --git a/package-lock.json b/package-lock.json index 05ade42d..5045f43b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,6 +1,6 @@ { "name": "mojaloop-specification", - "version": "8.8.0", + "version": "8.8.1", "lockfileVersion": 1, "requires": true, "dependencies": { diff --git a/package.json b/package.json index 6a0ffcba..095cba94 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "mojaloop-specification", - "version": "8.8.0", + "version": "8.8.1", "description": "Mojaloop-specification", "dependencies": { "express": "4.17.1",