diff --git a/website/versioned_docs/v1.0.1/api/thirdparty/assets/diagrams/linking/5a-credential-registration.puml b/website/versioned_docs/v1.0.1/api/thirdparty/assets/diagrams/linking/5a-credential-registration.puml index b7cd8fe0..7e4b6ac6 100644 --- a/website/versioned_docs/v1.0.1/api/thirdparty/assets/diagrams/linking/5a-credential-registration.puml +++ b/website/versioned_docs/v1.0.1/api/thirdparty/assets/diagrams/linking/5a-credential-registration.puml @@ -44,7 +44,6 @@ PISP -> Switch ++: ""PUT /consents/22222222-0000-0000-0000-000000000000""\n\ "" FSIOP-Source: pispa""\n\ "" FSPIOP-Destination: dfspa""\n\ "" {""\n\ - "" consentRequestId: "11111111-0000-0000-0000-000000000000",""\n\ "" status: "ISSUED",""\n\ "" scopes: [""\n\ "" {""\n\ @@ -86,10 +85,10 @@ rnote over DFSP If the DFSP opts to use the hub-hosted Auth-Service it then: 1. Registers the consent with the Auth Service ""POST /consents"" - 2. If the DFSP recieves a `PUT /consents/{id}` and the callback contains - ""Consent.credential.status"" of ""VERIFIED"", for each scope in the - Consent, the DFSP creates a ""CredentialScope"" else, if it recieves - a `PUT /consents/{id}/error` callback, it knows that the Consent is + 2. If the DFSP recieves a `PUT /consents/{id}` and the callback contains + ""Consent.credential.status"" of ""VERIFIED"", for each scope in the + Consent, the DFSP creates a ""CredentialScope"" else, if it recieves + a `PUT /consents/{id}/error` callback, it knows that the Consent is invalid, and can propagate the error back to the PISP end note @@ -178,7 +177,6 @@ Auth -> Switch: ""PUT /consents/22222222-0000-0000-0000-000000000000"" \n\ "" FSIOP-Source: central-auth""\n\ "" FSPIOP-Destination: dfspa""\n\ "" {""\n\ - "" consentRequestId: "11111111-0000-0000-0000-000000000000"""\n\ "" status: "ISSUED",""\n\ "" scopes: [""\n\ "" {""\n\ diff --git a/website/versioned_docs/v1.0.1/api/thirdparty/assets/diagrams/transfer/1-2-1-agreement.puml b/website/versioned_docs/v1.0.1/api/thirdparty/assets/diagrams/transfer/1-2-1-agreement.puml index 21250e52..3d5aabd8 100644 --- a/website/versioned_docs/v1.0.1/api/thirdparty/assets/diagrams/transfer/1-2-1-agreement.puml +++ b/website/versioned_docs/v1.0.1/api/thirdparty/assets/diagrams/transfer/1-2-1-agreement.puml @@ -74,6 +74,7 @@ rnote left of D2 #Light ""FSPIOP-Source: dfspa"" ""FSPIOP-Destination: pispa"" { + "transactionId": "11111111-0000-0000-0000-000000000000", "transactionRequestState": "RECEIVED" } end note diff --git a/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md b/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md index 0fa1c4b4..d9afaea7 100644 --- a/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md +++ b/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md @@ -4,15 +4,15 @@ Third Party API ### Table Of Contents -1. [Preface](#Preface) - 1.1 [Conventions Used in This Document](#ConventionsUsedinThisDocument) - 1.2 [Document Version Information](#DocumentVersionInformation) - 1.3 [References](#References) -2. [Introduction](#Introduction) - 2.1 [Third Party API Specification](#ThirdPartyAPISpecification) -3. [Third Party API Elements](#ThirdPartyAPIElements) - 3.1 [Resources](#Resources) - 3.2 [Data Models](#DataModels) +1. [Preface](#Preface) + 1.1 [Conventions Used in This Document](#ConventionsUsedinThisDocument) + 1.2 [Document Version Information](#DocumentVersionInformation) + 1.3 [References](#References) +2. [Introduction](#Introduction) + 2.1 [Third Party API Specification](#ThirdPartyAPISpecification) +3. [Third Party API Elements](#ThirdPartyAPIElements) + 3.1 [Resources](#Resources) + 3.2 [Data Models](#DataModels) 3.3 [Error Codes](#ErrorCodes) # 1. Preface This section contains information about how to use this document. @@ -63,7 +63,7 @@ The Mojaloop Third Party API Specification includes the following documents: This section describes the content of the API which will be used by PISPs and DFSPs. -The content of the API falls into two sections: +The content of the API falls into two sections: 1. [Transaction Patterns - Linking](./transaction-patterns-linking.md) describes the process for linking customer accounts and providing a general permission mechanism for PISPs to perform operations on those accounts 2. [Transaction Patterns - Transfer](./transaction-patterns-transfer.md) describes the transfer of funds at the instigation of a PISP. @@ -82,7 +82,7 @@ The API contains the following resources: ### 3.1.1 **/accounts** -The **/accounts** resource is used to request information from a DFSP relating to the accounts +The **/accounts** resource is used to request information from a DFSP relating to the accounts it holds for a given identifier. The identifier is a user-provided value which the user uses to access their account with the DFSP, such as a phone number, email address, or some other identifier previously provided by the DFSP. @@ -111,7 +111,7 @@ Callback and data model information for **GET /accounts/**_{ID}_: - Error Callback - **PUT /accounts/**_{ID}_**/error** - Data Model – Empty body -#### 3.1.1.2 Callbacks +#### 3.1.1.2 Callbacks The responses for the **/accounts** resource are as follows @@ -120,7 +120,7 @@ The responses for the **/accounts** resource are as follows Used by: DFSP The **PUT /accounts/**_{ID}_ response is used to inform the requester of the result of a request -for accounts information. The identifier ID given in the call are the +for accounts information. The identifier ID given in the call are the values given in the original request (see Section 3.1.1.1.1 above.) The data content of the message is given below. @@ -145,20 +145,20 @@ The data content of the message is given below. ### 3.1.2 **/consentRequests** -The **/consentRequests** resource is used by a PISP to initiate the process of linking with a DFSP’s -account on behalf of a user. The PISP contacts the DFSP and sends a list of the permissions that +The **/consentRequests** resource is used by a PISP to initiate the process of linking with a DFSP’s +account on behalf of a user. The PISP contacts the DFSP and sends a list of the permissions that it wants to obtain and the accounts for which it wants permission. #### 3.1.2.1 Requests -This section describes the services that can be requested by a client on the API resource +This section describes the services that can be requested by a client on the API resource **/consentRequests**. ##### 3.1.2.1.1 **GET /consentRequests/**_{ID}_ Used by: PISP -The HTTP request **GET /consentRequests/**_{ID}_ is used to get information about a previously -requested consent. The *{ID}* in the URI should contain the consentRequestId that was assigned to the +The HTTP request **GET /consentRequests/**_{ID}_ is used to get information about a previously +requested consent. The *{ID}* in the URI should contain the consentRequestId that was assigned to the request by the PISP when the PISP originated the request. Callback and data model information for **GET /consentRequests/**_{ID}_: @@ -194,14 +194,14 @@ This section describes the callbacks that are used by the server under the resou Used by: DFSP -A DFSP uses this callback to (1) inform the PISP that the consentRequest has been accepted, +A DFSP uses this callback to (1) inform the PISP that the consentRequest has been accepted, and (2) communicate to the PISP which `authChannel` it should use to authenticate their user with. -When a PISP requests a series of permissions from a DFSP on behalf of a DFSP’s customer, not all -the permissions requested may be granted by the DFSP. Conversely, the out-of-band authorization +When a PISP requests a series of permissions from a DFSP on behalf of a DFSP’s customer, not all +the permissions requested may be granted by the DFSP. Conversely, the out-of-band authorization process may result in additional privileges being granted by the account holder to the PISP. The -**PUT /consentRequests/**_{ID}_ resource returns the current state of the permissions relating to a +**PUT /consentRequests/**_{ID}_ resource returns the current state of the permissions relating to a particular authorization request. The data model for this call is as follows: | Name | Cardinality | Type | Description | @@ -225,16 +225,16 @@ a token which they can use to prove to the DFSP that the user trusts this PISP. #### 3.1.2.3 Error callbacks -This section describes the error callbacks that are used by the server under the resource +This section describes the error callbacks that are used by the server under the resource **/consentRequests**. ##### 3.1.2.3.1 **PUT /consentRequests/**_{ID}_**/error** Used by: DFSP -If the server is unable to complete the consent request, or if an out-of-band processing error or +If the server is unable to complete the consent request, or if an out-of-band processing error or another processing error occurs, the error callback **PUT /consentRequests/**_{ID}_**/error** is used. The -*{ID}* in the URI should contain the *{ID}* that was used in the **GET /consentRequests/**_{ID}_ +*{ID}* in the URI should contain the *{ID}* that was used in the **GET /consentRequests/**_{ID}_ request or the **POST /consentRequests** request. The data model for this resource is as follows: | Name | Cardinality | Type | Description | @@ -244,21 +244,21 @@ request or the **POST /consentRequests** request. The data model for this resour ### 3.1.3 **/consents** -The **/consents** resource is used to negotiate a series of permissions between the PISP and the +The **/consents** resource is used to negotiate a series of permissions between the PISP and the DFSP which owns the account(s) on behalf of which the PISP wants to transact. A **/consents** call is originally sent to the PISP by the DFSP following the original consent -request process described in Section 3.1.2.1.2 above. At the close of this process, the DFSP -which owns the customer’s account(s) will have satisfied itself that its customer really has +request process described in Section 3.1.2.1.2 above. At the close of this process, the DFSP +which owns the customer’s account(s) will have satisfied itself that its customer really has requested that the PISP be allowed access to their accounts, and will have defined the accounts in question and the type of access which is to be granted. -#### 3.1.3.1 Requests +#### 3.1.3.1 Requests The **/consents** resource will support the following requests. ##### 3.1.3.1.1 **GET /consents/**_{ID}_ Used by: DFSP -The **GET /consents/**_{ID}_ resource allows a party to enquire after the status of a consent. The +The **GET /consents/**_{ID}_ resource allows a party to enquire after the status of a consent. The *{ID}* used in the URI of the request should be the consent request ID which was used to identify the consent when it was created. @@ -292,20 +292,20 @@ Callback and data model information for **POST /consents/**: Used by PISP, DFSP The **DELETE /consents/**_{ID}_ request is used to request the revocation of a previously agreed consent. -For tracing and auditing purposes, the switch should be sure not to delete the consent physically; +For tracing and auditing purposes, the switch should be sure not to delete the consent physically; instead, information relating to the consent should be marked as deleted and requests relating to the consent should not be honoured. -> Note: the ALS should verify that the participant who is requesting the deletion is either the -> initiator named in the consent or the account holding institution named in the consent. If any +> Note: the ALS should verify that the participant who is requesting the deletion is either the +> initiator named in the consent or the account holding institution named in the consent. If any > other party attempts to delete a consent, the request should be rejected, and an error raised. Callback and data model information for **DELETE /consents/**_{ID}_: - Callback – **PATCH /consents/**_{ID}_ - Error Callback – **PUT /consents/**_{ID}_**/error** -#### 3.1.3.2 Callbacks -The **/consents** resource supports the following callbacks: +#### 3.1.3.2 Callbacks +The **/consents** resource supports the following callbacks: ##### 3.1.3.2.1 **PATCH/consents/**_{ID}_ Used by: Auth-Service, DFSP @@ -321,10 +321,10 @@ of `VERIFIED`. In the second case, an Auth-Service or DFSP sends a **PATCH/consents/**_{ID}_ request with a `status` of `REVOKED`, and the `revokedAt` field set. -The syntax of this call complies with the JSON Merge Patch specification [RFC-7386](https://datatracker.ietf.org/doc/html/rfc7386) -rather than the JSON Patch specification [RFC-6902](https://datatracker.ietf.org/doc/html/rfc6902). -The **PATCH /consents/**_{ID}_ resource contains a set of proposed changes to the current state of the -permissions relating to a particular authorization grant. The data model +The syntax of this call complies with the JSON Merge Patch specification [RFC-7386](https://datatracker.ietf.org/doc/html/rfc7386) +rather than the JSON Patch specification [RFC-6902](https://datatracker.ietf.org/doc/html/rfc6902). +The **PATCH /consents/**_{ID}_ resource contains a set of proposed changes to the current state of the +permissions relating to a particular authorization grant. The data model for this call is as follows: | Name | Cardinality | Type | Description | @@ -338,8 +338,8 @@ for this call is as follows: Used by: PISP -The **PUT /consents/**_{ID}_ resource is used to return information relating to the consent object -whose `consentId` is given in the URI. And for registering a credential for the consent. The +The **PUT /consents/**_{ID}_ resource is used to return information relating to the consent object +whose `consentId` is given in the URI. And for registering a credential for the consent. The data returned by the call is as follows: | Name | Cardinality | Type | Description | @@ -356,7 +356,7 @@ Used by: PISP, DFSP, Auth-Service If the server is unable to complete the consent, or if an out-of-loop processing error or another processing error occurs, the error callback **PUT /consents/**_{ID}_**/error** is used. The *{ID}* in the -URI should contain the *{ID}* that was used in the **GET /consents/**_{ID}_ request or the +URI should contain the *{ID}* that was used in the **GET /consents/**_{ID}_ request or the **POST /consents** request. The data model for this resource is as follows: | Name | Cardinality | Type | Description | @@ -368,44 +368,44 @@ URI should contain the *{ID}* that was used in the **GET /consents/**_{ID}_ requ The **/parties** resource will be used by the PISP to identify a party to a transfer. This will be used by the PISP to identify the payee DFSP when it requests a transfer. -The PISP will be permitted to issue a **PUT /parties** response. Although it does not own any -transaction accounts, there are circumstances in which another party may want to pay a customer -via their PISP identification: for instance, where the customer is at a merchant’s premises and +The PISP will be permitted to issue a **PUT /parties** response. Although it does not own any +transaction accounts, there are circumstances in which another party may want to pay a customer +via their PISP identification: for instance, where the customer is at a merchant’s premises and tells the merchant that they would like to pay via their PISP app. In these circumstances, the PISP will need to be able to confirm that it does act for the customer. -#### 3.1.4.1 Requests +#### 3.1.4.1 Requests The **/parties** resource will support the following requests. ##### 3.1.4.1.1 **GET /parties** Used by: PISP -The **GET /parties** resource will use the same form as the resource described in +The **GET /parties** resource will use the same form as the resource described in [Section 6.3.3.1](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#6331-get-partiestypeid) of Ref. 1 above. -#### 3.1.4.2 Callbacks +#### 3.1.4.2 Callbacks The parties resource will support the following callbacks. ##### 3.1.4.2.1 **PUT /parties** Used by: DFSP -The **PUT /parties** resource will use the same form as the resource described in +The **PUT /parties** resource will use the same form as the resource described in [Section 6.3.4.1](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#6341-put-partiestypeid) of Ref. 1 above. ### 3.1.5 **/services** -The **/services** resource is a new resource which enables a participant to query for other -participants who offer a particular service. The requester will issue a `GET` request, specifying +The **/services** resource is a new resource which enables a participant to query for other +participants who offer a particular service. The requester will issue a `GET` request, specifying the type of service for which information is required as part of the query string. The switch will respond with a list of the current DFSPs in the scheme which are registered as providing that service. -#### 3.1.5.1 Requests +#### 3.1.5.1 Requests The services resource will support the following requests. #### 3.1.5.2 **GET /services/**_{ServiceType}_ Used by: DFSP, PISP -The HTTP request **GET /services/**_{ServiceType}_ is used to find out the names of the participants in a +The HTTP request **GET /services/**_{ServiceType}_ is used to find out the names of the participants in a scheme which provide the type of service defined in the *{ServiceType}* parameter. The *{ServiceType}* parameter -should specify a value from the ServiceType enumeration. If it does not, the request will be +should specify a value from the ServiceType enumeration. If it does not, the request will be rejected with an error. Callback and data model information for **GET /services/**_{ServiceType}_: @@ -413,13 +413,13 @@ Callback and data model information for **GET /services/**_{ServiceType}_: - Error Callback - **PUT /services/**_{ServiceType}_**/error** - Data Model – Empty body #### 3.1.5.3 Callbacks -This section describes the callbacks that are used by the server for services provided by the +This section describes the callbacks that are used by the server for services provided by the resource **/services**. ##### 3.1.5.3.1 **PUT /services/**_{ServiceType}_ Used by: Switch -The callback **PUT /services/**_{ServiceType}_ is used to inform the client of a successful result of +The callback **PUT /services/**_{ServiceType}_ is used to inform the client of a successful result of the service information lookup. The information is returned in the following form: | Name | Cardinality | Type | Description | @@ -430,8 +430,8 @@ the service information lookup. The information is returned in the following for Used by: Switch -If the server encounters an error in fulfilling a request for a list of participants who -provide a service, the error callback **PUT /services/**_{ServiceType}_**/error** is used to inform the +If the server encounters an error in fulfilling a request for a list of participants who +provide a service, the error callback **PUT /services/**_{ServiceType}_**/error** is used to inform the client that an error has occurred. | Name | Cardinality | Type | Description | @@ -450,14 +450,14 @@ The **/thirdpartyRequests/authorizations** resource is analogous to the **/autho The **/thirdpartyRequests/authorizations** resource supports the endpoints described below. #### 3.1.6.1 Requests -This section describes the services that a client can request on the +This section describes the services that a client can request on the **/thirdpartyRequests/authorizations** resource. ##### 3.1.6.1.1 **GET /thirdpartyRequests/authorizations/**_{ID}_ Used by: DFSP -The HTTP request **GET /thirdpartyRequests/authorizations/**_{ID}_ is used to get information relating -to a previously issued authorization request. The *{ID}* in the request should match the +The HTTP request **GET /thirdpartyRequests/authorizations/**_{ID}_ is used to get information relating +to a previously issued authorization request. The *{ID}* in the request should match the `authorizationRequestId` which was given when the authorization request was created. Callback and data model information for **GET /thirdpartyRequests/authorizations/**_{ID}_: @@ -498,7 +498,7 @@ The following callbacks are supported for the **/thirdpartyRequests/authorizatio Used by: PISP -After receiving the **POST /thirdpartyRequests/authorizations**, the PISP will present the details of the +After receiving the **POST /thirdpartyRequests/authorizations**, the PISP will present the details of the transaction to their user, and request that the client sign the `challenge` field using the credential they previously registered. @@ -510,32 +510,32 @@ The signed challenge will be sent back by the PISP in **PUT /thirdpartyRequests/ | signedPayload | 0..1 | SignedPayload | If the `responseType` is `ACCEPTED`, `signedPayload` is required. | #### 3.1.6.3 Error callbacks -This section describes the error callbacks that are used by the server under the resource +This section describes the error callbacks that are used by the server under the resource **/thirdpartyRequests/authorizations**. ##### 3.1.6.3.1 **PUT /thirdpartyRequests/authorizations/**_{ID}_**/error** Used by: DFSP The **PUT /thirdpartyRequests/authorizations/**_{ID}_**/error** resource will have the same content -as the **PUT /authorizations/**_{ID}_**/error** resource described in [Section 6.6.5.1](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#6651-put-authorizationsiderror) +as the **PUT /authorizations/**_{ID}_**/error** resource described in [Section 6.6.5.1](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#6651-put-authorizationsiderror) of Ref. 1 above. ### 3.1.7 **/thirdpartyRequests/transactions** -The **/thirdpartyRequests/transactions` resource is analogous to the `/transactionRequests** +The **/thirdpartyRequests/transactions` resource is analogous to the `/transactionRequests** resource described in [Section 6.4](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#64-api-resource-transactionrequests) of Ref. 1 above. The PISP uses it to request the -owner of the PISP’s customer’s account to transfer a specified amount from the customer’s +owner of the PISP’s customer’s account to transfer a specified amount from the customer’s account with the DFSP to a named Payee. The **/thirdpartyRequests/transactions** resource supports the endpoints described below. #### 3.1.7.1 Requests -This section describes the services that a client can request on the +This section describes the services that a client can request on the **/thirdpartyRequests/transactions** resource. ##### 3.1.7.1.1 **GET /thirdpartyRequests/transactions/**_{ID}_ Used by: PISP -The HTTP request **GET /thirdpartyRequests/transactions/**_{ID}_ is used to get information -relating to a previously issued transaction request. The *{ID}* in the request should +The HTTP request **GET /thirdpartyRequests/transactions/**_{ID}_ is used to get information +relating to a previously issued transaction request. The *{ID}* in the request should match the `transactionRequestId` which was given when the transaction request was created. Callback and data model information for **GET /thirdpartyRequests/transactions/**_{ID}_: @@ -572,7 +572,7 @@ The following callbacks are supported for the **/thirdpartyRequests/transactions Used by: DFSP After a PISP requests the creation of a Third Party Transaction request (**POST /thirdpartyRequests/transactions**) -or the status of a previously created Third Party Transaction request +or the status of a previously created Third Party Transaction request (**GET /thirdpartyRequests/transactions/**_{ID}_), the DFSP will send this callback. The data model for this endpoint is as follows: @@ -585,10 +585,10 @@ The data model for this endpoint is as follows: Used by: DFSP -The issuing PISP will expect a response to their request for a transfer which describes +The issuing PISP will expect a response to their request for a transfer which describes the finalised state of the requested transfer. This response will be given by a `PATCH` call on the -**/thirdpartyRequests/transactions/**_{ID}_ resource. The *{ID}* given in the query string should be -the `transactionRequestId` which was originally used by the PISP to identify the transaction +**/thirdpartyRequests/transactions/**_{ID}_ resource. The *{ID}* given in the query string should be +the `transactionRequestId` which was originally used by the PISP to identify the transaction request (see [Section 3.1.8.1.2](#31812-post-thirdpartyrequestsverifications) above.) The data model for this endpoint is as follows: @@ -606,17 +606,17 @@ This section describes the error callbacks that are used by the server under the Used by: DFSP -The **PUT /thirdpartyRequests/transactions/**_{ID}_**/error** resource will have the same content as +The **PUT /thirdpartyRequests/transactions/**_{ID}_**/error** resource will have the same content as the **PUT /transactionRequests/**_{ID}_**/error** resource described in [Section 6.4.5.1](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#6451-put-transactionrequestsiderror) of Ref. 1 above. ### 3.1.8 **/thirdpartyRequests/verifications** The **/thirdpartyRequests/verifications** resource is used by a Payer DFSP to verify that an authorization response received from a PISP was signed using the correct private key, in cases where the authentication service -to be used is implemented by the switch and not internally by the DFSP. The DFSP sends the original +to be used is implemented by the switch and not internally by the DFSP. The DFSP sends the original challenge and the signed response to the authentication service, together with the `consentId` to be used for the verification. The authentication service compares the response with the result of signing the -challenge with the private key associated with the `consentId`, and, if the two match, it returns a +challenge with the private key associated with the `consentId`, and, if the two match, it returns a positive result. Otherwise, it returns an error. The **/thirdpartyRequests/verifications** resource supports the endpoints described below. @@ -628,7 +628,7 @@ resource. Used by: DFSP The HTTP request **/thirdpartyRequests/verifications/**_{ID}_ is used to get information regarding a previously -created or requested authorization. The *{ID}* in the URI should contain the verification request ID +created or requested authorization. The *{ID}* in the URI should contain the verification request ID (see [Section 3.1.8.1.2](#31812-post-thirdpartyrequestsverifications) below) that was used for the creation of the transfer.Callback and data model information for **GET /thirdpartyRequests/verifications/**_{ID}_: @@ -656,31 +656,31 @@ Callback and data model information for **POST /thirdpartyRequests/verifications | genericSignedPayload | 0..1 | BinaryString | Required if signedPayloadType is GENERIC. The signed challenge returned by the PISP. A BinaryString representing a signature of the challenge + private key of the credential. | | fidoSignedPayload | 0..1 | FIDOPublicKeyCredentialAssertion | Required if signedPayloadType is FIDO. The signed challenge returned by the PISP in the form of a [`FIDOPublicKeyCredentialAssertion` Object](https://w3c.github.io/webauthn/#iface-pkcredential) | -#### 3.1.8.2 Callbacks +#### 3.1.8.2 Callbacks This section describes the callbacks that are used by the server under the resource **/thirdpartyRequests/verifications** ##### 3.1.8.2.1 **PUT /thirdpartyRequests/verifications/**_{ID}_ Used by: Auth Service -The callback **PUT /thirdpartyRequests/verifications/**_{ID}_ is used to inform the client of the result +The callback **PUT /thirdpartyRequests/verifications/**_{ID}_ is used to inform the client of the result of an authorization check. The *{ID}* in the URI should contain the `authorizationRequestId` -(see [Section 3.1.8.1.2](#31812-post-thirdpartyrequestsverifications) above) which was used to request the check, or the *{ID}* that was +(see [Section 3.1.8.1.2](#31812-post-thirdpartyrequestsverifications) above) which was used to request the check, or the *{ID}* that was used in the **GET /thirdpartyRequests/verifications/**_{ID}_. The data model for this resource is as follows: | Name | Cardinality | Type | Description | | --- | --- | --- | --- | | authenticationResponse | 1 | AuthenticationResponse | The result of the authorization check. | #### 3.1.8.3 Error callbacks -This section describes the error callbacks that are used by the server under the resource +This section describes the error callbacks that are used by the server under the resource **/thirdpartyRequests/verifications**. ##### 3.1.8.3.1 **PUT /thirdpartyRequests/verifications/**_{ID}_**/error** Used by: Auth Service -If the server is unable to complete the authorization request, or another processing error occurs, the -error callback **PUT /thirdpartyRequests/verifications/**_{ID}_**/error** is used.The *{ID}* in the URI should -contain the `verificationRequestId` (see [Section 3.1.8.1.2](#31812-post-thirdpartyrequestsverifications) above) which was used to request the +If the server is unable to complete the authorization request, or another processing error occurs, the +error callback **PUT /thirdpartyRequests/verifications/**_{ID}_**/error** is used.The *{ID}* in the URI should +contain the `verificationRequestId` (see [Section 3.1.8.1.2](#31812-post-thirdpartyrequestsverifications) above) which was used to request the check, or the *{ID}* that was used in the **GET /thirdpartyRequests/verifications/**_{ID}_. The data model for this resource is as follows: @@ -712,7 +712,7 @@ The AccountAddress data type is a variable length string with a maximum size of - Period (.) Addresses MUST NOT end in a period (.) character An entity providing accounts to parties (i.e. a participant) can provide any value for an `AccountAddress` that is meaningful to that entity. -It does not need to provide an address that makes the account identifiable outside the entity’s domain. +It does not need to provide an address that makes the account identifiable outside the entity’s domain. > ***IMPORTANT:* The policy for defining addresses and the life-cycle of these is at the discretion of the address space owner (the payer DFSP in this case).** #### 3.2.1.3 AccountList @@ -726,7 +726,7 @@ The AccountList data model is used to hold information about the accounts that a | Name | Cardinality | Type | Description | | --- | --- | --- | --- | -| AuthenticationResponse | 1 | Enum of String(1..32) | See [Section 3.2.2.1](#3221-AuthenticationResponse) below (AuthenticationResponse) for more information on allowed values.| +| AuthenticationResponse | 1 | Enum of String(1..32) | See [Section 3.2.2.1](#3221-AuthenticationResponse) below (AuthenticationResponse) for more information on allowed values.| #### 3.2.1.6 BinaryString The BinaryString type used in these definitions is as defined in [Section 7.2.17](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#7217-binarystring) of Ref. 1 above. #### 3.2.1.7 ConsentRequestChannelType @@ -740,12 +740,12 @@ The ConsentStatus type stores the status of a consent request, as described in [ | Name | Cardinality | Type | Description | | --- | --- | --- | --- | | ConsentStatus | 1 | Enum of String(1..32) | See [Section 3.2.2.5](#3224-consentstatustype) below (ConsentStatusType) for more information on allowed values.| - + #### 3.2.1.9 CorrelationId The CorrelationId type used in these definitions is as defined in [Section 7.3.8](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#738-correlationid) of Ref. 1 above. ##### 3.2.1.10 Credential The Credential object is used to store information about a publicKey and signature that has been registered with a Consent. -This publicKey can be used to verify that transaction authorizations have been signed by the previously-registered privateKey, +This publicKey can be used to verify that transaction authorizations have been signed by the previously-registered privateKey, which resides on a User's device. | Name | Cardinality | Type | Description | @@ -774,7 +774,7 @@ The ExtensionList data type used in these definitions is as defined in [Section The FspId data type used in these definitions is as defined in [Section 7.3.16](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#7316-fspid) of Ref. 1 above. ##### 3.2.1.16 GenericCredential -The GenericCredential object stores the payload for a credential which is validated according to a comparison of the signature created from the challenge using a private key against the same challenge signed using a public key. Its content is as follows. +The GenericCredential object stores the payload for a credential which is validated according to a comparison of the signature created from the challenge using a private key against the same challenge signed using a public key. Its content is as follows. | Name | Cardinality | Type | Description | | --- | --- | --- | --- | | publicKey | 1 | BinaryString | The public key to be used in checking the signature. | @@ -879,7 +879,6 @@ The AuthenticationResponse enumeration describes the result of authenticating ve | Name | Description | | --- | ----------- | | VERIFIED | The challenge was correctly signed. | -| REJECTED | The challenge was not correctly signed. | #### 3.2.2.2 AuthorizationResponseType The AuthorizationResponseType enumeration is the same as the AuthorizationResponse enumeration described in [Section 7.5.3](https://github.com/mojaloop/mojaloop-specification/blob/master/fspiop-api/documents/v1.1-document-set/API%20Definition%20v1.1.md#753-authorizationresponse) of Ref. 1 above. #### 3.2.2.3 ConsentRequestChannelType diff --git a/website/versioned_docs/v1.0.1/api/thirdparty/thirdparty-dfsp-v1.0.yaml b/website/versioned_docs/v1.0.1/api/thirdparty/thirdparty-dfsp-v1.0.yaml index 327d244d..8bc92530 100644 --- a/website/versioned_docs/v1.0.1/api/thirdparty/thirdparty-dfsp-v1.0.yaml +++ b/website/versioned_docs/v1.0.1/api/thirdparty/thirdparty-dfsp-v1.0.yaml @@ -75,15 +75,24 @@ paths: schema: title: AccountsIDPutResponse type: object - description: 'The object sent in a `PUT /accounts/{ID}` request.' + description: |- + Callback and data model information for GET /accounts/{ID}: + Callback - PUT /accounts/{ID} Error Callback - PUT /accounts/{ID}/error Data Model - Empty body + The PUT /accounts/{ID} response is used to inform the requester of the result of a request for accounts information. The identifier ID given in the call are the values given in the original request. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31121--put-accountsid properties: accountList: - description: Information about the accounts that the DFSP associates with the identifier sent by the PISP + title: AccountList type: array + description: |- + The AccountList data model is used to hold information about the accounts that a party controls. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#3213-accountlist items: title: Account type: object - description: Data model for the complex type Account. + description: |- + Data model for the complex type Account. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#3211-account properties: accountNickname: title: Name @@ -98,180 +107,15 @@ paths: address: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items/properties/address' currency: - title: Currency - description: 'The currency codes defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) as three-letter alphabetic codes are used as the standard naming representation for currencies.' - type: string - minLength: 3 - maxLength: 3 - enum: - - AED - - AFN - - ALL - - AMD - - ANG - - AOA - - ARS - - AUD - - AWG - - AZN - - BAM - - BBD - - BDT - - BGN - - BHD - - BIF - - BMD - - BND - - BOB - - BRL - - BSD - - BTN - - BWP - - BYN - - BZD - - CAD - - CDF - - CHF - - CLP - - CNY - - COP - - CRC - - CUC - - CUP - - CVE - - CZK - - DJF - - DKK - - DOP - - DZD - - EGP - - ERN - - ETB - - EUR - - FJD - - FKP - - GBP - - GEL - - GGP - - GHS - - GIP - - GMD - - GNF - - GTQ - - GYD - - HKD - - HNL - - HRK - - HTG - - HUF - - IDR - - ILS - - IMP - - INR - - IQD - - IRR - - ISK - - JEP - - JMD - - JOD - - JPY - - KES - - KGS - - KHR - - KMF - - KPW - - KRW - - KWD - - KYD - - KZT - - LAK - - LBP - - LKR - - LRD - - LSL - - LYD - - MAD - - MDL - - MGA - - MKD - - MMK - - MNT - - MOP - - MRO - - MUR - - MVR - - MWK - - MXN - - MYR - - MZN - - NAD - - NGN - - NIO - - NOK - - NPR - - NZD - - OMR - - PAB - - PEN - - PGK - - PHP - - PKR - - PLN - - PYG - - QAR - - RON - - RSD - - RUB - - RWF - - SAR - - SBD - - SCR - - SDG - - SEK - - SGD - - SHP - - SLL - - SOS - - SPL - - SRD - - STD - - SVC - - SYP - - SZL - - THB - - TJS - - TMT - - TND - - TOP - - TRY - - TTD - - TVD - - TWD - - TZS - - UAH - - UGX - - USD - - UYU - - UZS - - VEF - - VND - - VUV - - WST - - XAF - - XCD - - XDR - - XOF - - XPF - - XTS - - XXX - - YER - - ZAR - - ZMW - - ZWD + $ref: '#/paths/~1thirdpartyRequests~1transactions/post/requestBody/content/application~1json/schema/properties/amount/allOf/0/properties/currency' required: - accountNickname - - id + - address - currency + minItems: 1 + maxItems: 256 + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - accounts example: @@ -350,7 +194,7 @@ paths: maxLength: 128 description: Error description string. extensionList: - $ref: '#/paths/~1thirdpartyRequests~1authorizations/post/requestBody/content/application~1json/schema/properties/extensionList' + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - errorCode - errorDescription @@ -406,7 +250,12 @@ paths: schema: title: ConsentRequestsPostRequest type: object - description: The object sent in a `POST /consentRequests` request. + description: |- + Used by: PISP + The HTTP request POST /consentRequests is used to request a DFSP to grant access to one or more accounts owned by a customer of the DFSP for the PISP who sends the request. + Callback and data model for POST /consentRequests: + Callback: PUT /consentRequests/{ID} Error callback: PUT /consentRequests/{ID}/error Data model - see below url + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31212-post-consentrequests properties: consentRequestId: title: CorrelationId @@ -426,13 +275,20 @@ paths: items: title: Scope type: object - description: Scope + Account Identifier mapping for a Consent. + description: |- + The Scope element contains an identifier defining, in the terms of a DFSP, an account on which access types can be requested or granted. It also defines the access types which are requested or granted. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#32121-scope properties: address: title: AccountAddress type: string - description: | - An address which can be used to identify the account. + description: |- + The AccountAddress data type is a variable length string with a maximum size of 1023 characters and consists of: + Alphanumeric characters, upper or lower case. (Addresses are case-sensitive so that they can contain data encoded in formats such as base64url.) + - Underscore (_) - Tilde (~) - Hyphen (-) - Period (.) Addresses MUST NOT end in a period (.) character + An entity providing accounts to parties (i.e. a participant) can provide any value for an AccountAddress that is meaningful to that entity. It does not need to provide an address that makes the account identifiable outside the entity's domain. + IMPORTANT: The policy for defining addresses and the life-cycle of these is at the discretion of the address space owner (the payer DFSP in this case). + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#3212-accountaddress pattern: '^([0-9A-Za-z_~\-\.]+[0-9A-Za-z_~\-])$' minLength: 1 maxLength: 1023 @@ -443,16 +299,18 @@ paths: items: title: ScopeAction type: string + description: | + The ScopeAction element contains an access type which a PISP can request + from a DFSP, or which a DFSP can grant to a PISP. + It must be a member of the appropriate enumeration. + + - ACCOUNTS_GET_BALANCE: PISP can request a balance for the linked account + - ACCOUNTS_TRANSFER: PISP can request a transfer of funds from the linked account in the DFSP + - ACCOUNTS_STATEMENT: PISP can request a statement of individual transactions on a user's account enum: - ACCOUNTS_GET_BALANCE - ACCOUNTS_TRANSFER - ACCOUNTS_STATEMENT - description: | - The permissions allowed on a given account by a DFSP as defined in - a consent object - - ACCOUNTS_GET_BALANCE: PISP can request a balance for the linked account - - ACCOUNTS_TRANSFER: PISP can request a transfer of funds from the linked account in the DFSP - - ACCOUNTS_STATEMENT: PISP can request a statement of individual transactions on a user’s account required: - address - actions @@ -467,9 +325,9 @@ paths: - WEB - OTP description: | - The auth channel being used for the consentRequest. - - "WEB" - The Web auth channel. - - "OTP" - The OTP auth channel. + The auth channel being used for the consent request. + - WEB - DFSP can support authorization via a web-based login. + - OTP - DFSP can support authorization via a One Time PIN. callbackUri: title: Uri type: string @@ -478,6 +336,38 @@ paths: maxLength: 512 description: | The API data type Uri is a JSON string in a canonical format that is restricted by a regular expression for interoperability reasons. + extensionList: + title: ExtensionList + type: object + description: 'Data model for the complex type ExtensionList. An optional list of extensions, specific to deployment.' + properties: + extension: + type: array + items: + title: Extension + type: object + description: Data model for the complex type Extension. + properties: + key: + title: ExtensionKey + type: string + minLength: 1 + maxLength: 32 + description: Extension key. + value: + title: ExtensionValue + type: string + minLength: 1 + maxLength: 128 + description: Extension value. + required: + - key + - value + minItems: 1 + maxItems: 16 + description: Number of Extension elements. + required: + - extension required: - consentRequestId - userId @@ -519,8 +409,8 @@ paths: operationId: GetConsentRequestsById summary: GetConsentRequestsById description: | - The HTTP request `GET /consentRequests/{ID}` is used to get information about a previously - requested consent. The *{ID}* in the URI should contain the consentRequestId that was assigned to the + The HTTP request `GET /consentRequests/{ID}` is used to get information about a previously + requested consent. The *{ID}* in the URI should contain the consentRequestId that was assigned to the request by the PISP when the PISP originated the request. tags: - consentRequests @@ -553,14 +443,14 @@ paths: operationId: UpdateConsentRequest summary: UpdateConsentRequest description: | - A DFSP uses this callback to (1) inform the PISP that the consentRequest has been accepted, + A DFSP uses this callback to (1) inform the PISP that the consentRequest has been accepted, and (2) communicate to the PISP which `authChannel` it should use to authenticate their user with. - When a PISP requests a series of permissions from a DFSP on behalf of a DFSP’s customer, not all - the permissions requested may be granted by the DFSP. Conversely, the out-of-band authorization + When a PISP requests a series of permissions from a DFSP on behalf of a DFSP’s customer, not all + the permissions requested may be granted by the DFSP. Conversely, the out-of-band authorization process may result in additional privileges being granted by the account holder to the PISP. The - **PUT /consentRequests/**_{ID}_ resource returns the current state of the permissions relating to a + **PUT /consentRequests/**_{ID}_ resource returns the current state of the permissions relating to a particular authorization request. parameters: - $ref: '#/paths/~1consents/post/parameters/1' @@ -596,11 +486,13 @@ paths: enum: - WEB description: | - The web auth channel being used for PUT consentRequest/{ID} request. + The web auth channel being used for `PUT /consentRequest/{ID}` request. callbackUri: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/callbackUri' authUri: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/callbackUri' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - scopes - authChannels @@ -630,9 +522,11 @@ paths: enum: - OTP description: | - The OTP auth channel being used for PUT consentRequest/{ID} request. + The OTP auth channel being used for `PUT /consentRequests/{ID}` request. callbackUri: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/callbackUri' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - scopes - authChannels @@ -674,12 +568,17 @@ paths: schema: title: ConsentRequestsIDPatchRequest type: object - description: 'The object sent in a `PATCH /consentRequests/{ID}` request.' + description: |- + Used by: PISP + After the user completes an out-of-band authorization with the DFSP, the PISP will receive a token which they can use to prove to the DFSP that the user trusts this PISP. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31222-patch-consentrequestsid properties: authToken: type: string pattern: '^[A-Za-z0-9-_]+[=]{0,2}$' description: 'The API data type BinaryString is a JSON String. The string is a 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.' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - authToken responses: @@ -849,6 +748,8 @@ paths: description: | Common ID between the PISP and FSP for the Consent object determined by the DFSP who creates the Consent. + consentRequestId: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/consentRequestId' scopes: minLength: 1 maxLength: 256 @@ -868,6 +769,8 @@ paths: Allowed values for the enumeration ConsentStatus - ISSUED - The consent has been issued by the DFSP - REVOKED - The consent has been revoked + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - consentId - scopes @@ -883,8 +786,8 @@ paths: allOf: - $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/consentRequestId' description: | - Common ID between the PISP and the Payer DFSP for the consent object. The ID - should be reused for resends of the same consent. A new ID should be generated + Common ID between the PISP and the Payer DFSP for the consent object. The ID + should be reused for re-sends of the same consent. A new ID should be generated for each new consent. consentRequestId: allOf: @@ -899,6 +802,8 @@ paths: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' status: $ref: '#/paths/~1consents/post/requestBody/content/application~1json/schema/oneOf/0/properties/status' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - consentId - consentRequestId @@ -1023,7 +928,7 @@ paths: - $ref: '#/paths/~1consents/parameters/8' get: description: | - The **GET /consents/**_{ID}_ resource allows a party to enquire after the status of a consent. The *{ID}* used in the URI of the request should be the consent request ID which was used to identify the consent when it was created. + The **GET /consents/**_{ID}_ resource allows a party to enquire after the status of a consent. The *{ID}* used in the URI of the request should be the consent request ID which was used to identify the consent when it was created. tags: - consents operationId: GetConsent @@ -1077,7 +982,7 @@ paths: description: | PATCH /consents/{ID} request object. - Sent by the DFSP to the PISP when a consent is verified. + Sent by the DFSP to the PISP when a consent is issued and verified. Used in the "Register Credential" part of the Account linking flow. type: object properties: @@ -1085,7 +990,7 @@ paths: type: object properties: status: - title: CredentialStatus + title: CredentialStatusVerified type: string enum: - VERIFIED @@ -1094,6 +999,8 @@ paths: - "VERIFIED" - The Credential is valid and verified. required: - status + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - credential - title: ConsentsIDPatchResponseRevoked @@ -1105,7 +1012,7 @@ paths: type: object properties: status: - title: ConsentStatus + title: ConsentStatusRevoked type: string enum: - REVOKED @@ -1114,6 +1021,8 @@ paths: - REVOKED - The consent has been revoked revokedAt: $ref: '#/paths/~1thirdpartyRequests~1transactions~1%7BID%7D/patch/requestBody/content/application~1json/schema/properties/completedTimestamp' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - status - revokedAt @@ -1162,18 +1071,18 @@ paths: The HTTP request `PUT /consents/{ID}` is used by the PISP to update a Consent with a signed challenge and register a credential. Called by a `PISP` to after signing a challenge. Sent to a DFSP for verification. properties: - scopes: - type: array - items: - $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' status: - title: ConsentStatus + title: ConsentStatusIssued type: string enum: - ISSUED description: |- Allowed values for the enumeration ConsentStatus - ISSUED - The consent has been issued by the DFSP + scopes: + type: array + items: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' credential: title: SignedCredential type: object @@ -1191,12 +1100,11 @@ paths: enum: - FIDO - GENERIC - description: | - The type of the Credential. - - "FIDO" - A FIDO public/private keypair - - "GENERIC" - A Generic public/private keypair + description: |- + The type of the Credential. - "FIDO" - The credential is based on a FIDO challenge. Its payload is a FIDOPublicKeyCredentialAttestation object. - "GENERIC" - The credential is based on a simple public key validation. Its payload is a GenericCredential object. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#3226-credentialtype status: - title: CredentialStatus + title: CredentialStatusPending type: string enum: - PENDING @@ -1207,7 +1115,7 @@ paths: title: GenericCredential type: object description: | - A publicKey + signature of a challenge for a generic public/private keypair + A publicKey + signature of a challenge for a generic public/private keypair. properties: publicKey: $ref: '#/paths/~1consentRequests~1%7BID%7D/patch/requestBody/content/application~1json/schema/properties/authToken' @@ -1218,50 +1126,10 @@ paths: - signature additionalProperties: false fidoPayload: - $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/1/properties/credential/properties/payload' - required: - - credentialType - - status - additionalProperties: false - required: - - scopes - - credential - additionalProperties: false - - title: ConsentsIDPutResponseVerified - type: object - description: | - The HTTP request `PUT /consents/{ID}` is used by the DFSP or Auth-Service to update a Consent object once it has been Verified. - Called by a `auth-service` to notify a DFSP that a credential has been verified and registered. - properties: - scopes: - type: array - items: - $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' - status: - $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/status' - credential: - title: VerifiedCredential - type: object - description: | - A credential used to allow a user to prove their identity and access - to an account with a DFSP. - - VerifiedCredential is a special formatting of the credential to allow us to be - more explicit about the `status` field - it should only ever be VERIFIED when - updating a credential. - properties: - credentialType: - $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/credentialType' - status: - type: string - enum: - - VERIFIED - description: 'The Credential is valid, and ready to be used by the PISP.' - payload: title: FIDOPublicKeyCredentialAttestation type: object description: | - A data model representing a FIDO Attestation result. Derived from + A data model representing a FIDO Attestation result. Derived from [`PublicKeyCredential` Interface](https://w3c.github.io/webauthn/#iface-pkcredential). The `PublicKeyCredential` interface represents the below fields with @@ -1315,8 +1183,50 @@ paths: required: - credentialType - status - - payload additionalProperties: false + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' + required: + - scopes + - credential + additionalProperties: false + - title: ConsentsIDPutResponseVerified + type: object + description: | + The HTTP request `PUT /consents/{ID}` is used by the DFSP or Auth-Service to update a Consent object once it has been Verified. + Called by a `auth-service` to notify a DFSP that a credential has been verified and registered. + properties: + status: + $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/status' + scopes: + type: array + items: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' + credential: + title: VerifiedCredential + type: object + description: | + A credential used to allow a user to prove their identity and access + to an account with a DFSP. + + VerifiedCredential is a special formatting of Credential to allow us to be + more explicit about the `status` field - it should only ever be VERIFIED when + updating a credential. + properties: + credentialType: + $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/credentialType' + status: + $ref: '#/paths/~1consents~1%7BID%7D/patch/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/status' + genericPayload: + $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/genericPayload' + fidoPayload: + $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/fidoPayload' + required: + - credentialType + - status + additionalProperties: false + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - scopes - credential @@ -1349,7 +1259,7 @@ paths: Used by PISP, DFSP The **DELETE /consents/**_{ID}_ request is used to request the revocation of a previously agreed consent. - For tracing and auditing purposes, the switch should be sure not to delete the consent physically; + For tracing and auditing purposes, the switch should be sure not to delete the consent physically; instead, information relating to the consent should be marked as deleted and requests relating to the consent should not be honoured. operationId: DeleteConsentByID @@ -1451,7 +1361,12 @@ paths: application/json: schema: title: ThirdpartyRequestsAuthorizationsPostRequest - description: POST /thirdpartyRequests/authorizations request object. + description: |- + Used by: DFSP + The HTTP request POST /thirdpartyRequests/authorizations is used to request the validation by a customer for the transfer described in the request. + Callback and data model information for POST /thirdpartyRequests/authorizations: + Callback - PUT /thirdpartyRequests/authorizations/{ID} Error Callback - PUT /thirdpartyRequests/authorizations/{ID}/error Data Model - See below url + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31612-post-thirdpartyrequestsauthorizations type: object properties: authorizationRequestId: @@ -1464,11 +1379,11 @@ paths: transferAmount: allOf: - $ref: '#/paths/~1thirdpartyRequests~1transactions/post/requestBody/content/application~1json/schema/properties/amount/allOf/0' - description: The amount that will be debited from the sending customer’s account as a consequence of the transaction. + description: The amount that will be debited from the sending customer's account as a consequence of the transaction. payeeReceiveAmount: allOf: - $ref: '#/paths/~1thirdpartyRequests~1transactions/post/requestBody/content/application~1json/schema/properties/amount/allOf/0' - description: The amount that will be credited to the receiving customer’s account as a consequence of the transaction. + description: The amount that will be credited to the receiving customer's account as a consequence of the transaction. fees: allOf: - $ref: '#/paths/~1thirdpartyRequests~1transactions/post/requestBody/content/application~1json/schema/properties/amount/allOf/0' @@ -1566,37 +1481,7 @@ paths: - $ref: '#/paths/~1thirdpartyRequests~1transactions~1%7BID%7D/patch/requestBody/content/application~1json/schema/properties/completedTimestamp' description: 'The time by which the transfer must be completed, set by the payee DFSP.' extensionList: - title: ExtensionList - type: object - description: 'Data model for the complex type ExtensionList. An optional list of extensions, specific to deployment.' - properties: - extension: - type: array - items: - title: Extension - type: object - description: Data model for the complex type Extension. - properties: - key: - title: ExtensionKey - type: string - minLength: 1 - maxLength: 32 - description: Extension key. - value: - title: ExtensionValue - type: string - minLength: 1 - maxLength: 128 - description: Extension value. - required: - - key - - value - minItems: 1 - maxItems: 16 - description: Number of Extension elements. - required: - - extension + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - authorizationRequestId - transactionRequestId @@ -1642,8 +1527,8 @@ paths: - $ref: '#/paths/~1consents/parameters/8' get: description: | - The HTTP request **GET /thirdpartyRequests/authorizations/**_{ID}_ is used to get information relating - to a previously issued authorization request. The *{ID}* in the request should match the + The HTTP request **GET /thirdpartyRequests/authorizations/**_{ID}_ is used to get information relating + to a previously issued authorization request. The *{ID}* in the request should match the `authorizationRequestId` which was given when the authorization request was created. operationId: GetThirdpartyRequestsAuthorizationsById summary: GetThirdpartyRequestsAuthorizationsById @@ -1672,7 +1557,7 @@ paths: $ref: '#/paths/~1consents/post/responses/503' put: description: | - After receiving the **POST /thirdpartyRequests/authorizations**, the PISP will present the details of the + After receiving the **POST /thirdpartyRequests/authorizations**, the PISP will present the details of the transaction to their user, and request that the client sign the `challenge` field using the credential they previously registered. @@ -1690,17 +1575,19 @@ paths: application/json: schema: oneOf: - - title: ThirdpartyRequestsAuthorizationsIDPutResponseGeneric + - title: ThirdpartyRequestsAuthorizationsIDPutResponseRejected type: object description: 'The object sent in the PUT /thirdpartyRequests/authorizations/{ID} callback.' properties: responseType: - title: AuthorizationResponseType + title: AuthorizationResponseTypeRejected description: | The customer rejected the terms of the transfer. type: string enum: - REJECTED + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - responseType - title: ThirdpartyRequestsAuthorizationsIDPutResponseFIDO @@ -1715,6 +1602,7 @@ paths: enum: - ACCEPTED signedPayload: + title: SignedPayloadFIDO type: object properties: signedPayloadType: @@ -1725,6 +1613,8 @@ paths: - signedPayloadType - fidoSignedPayload additionalProperties: false + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - responseType - signedPayload @@ -1736,6 +1626,7 @@ paths: responseType: $ref: '#/paths/~1thirdpartyRequests~1authorizations~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/1/properties/responseType' signedPayload: + title: SignedPayloadGeneric type: object properties: signedPayloadType: @@ -1746,6 +1637,8 @@ paths: - signedPayloadType - genericSignedPayload additionalProperties: false + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - responseType - signedPayload @@ -1852,13 +1745,18 @@ paths: schema: title: ThirdpartyRequestsTransactionsPostRequest type: object - description: The object sent in the POST /thirdpartyRequests/transactions request. + description: |- + Used by: PISP + The HTTP request POST /thirdpartyRequests/transactions is used to request the creation of a transaction request on the server for the transfer described in the request. + Callback and data model information for POST /thirdpartyRequests/transactions: + Callback - PUT /thirdpartyRequests/transactions/{ID} Error Callback - PUT /thirdpartyRequests/transactions/{ID}/error Data Model - See link below + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31712-post-thirdpartyrequeststransactions properties: transactionRequestId: allOf: - $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/consentRequestId' description: | - Common ID between the PISP and the Payer DFSP for the transaction request object. The ID should be reused for resends of the same transaction request. A new ID should be generated for each new transaction request. + Common ID between the PISP and the Payer DFSP for the transaction request object. The ID should be reused for resends of the same transaction request. A new ID should be generated for each new transaction request. payee: allOf: - title: Party @@ -1954,7 +1852,7 @@ paths: [RFC 3696](https://tools.ietf.org/html/rfc3696). - PERSONAL_ID - A personal identifier is used as reference to a participant. Examples of personal identification are passport number, birth certificate - number, and national registration number. The identifier number is added in + number, and national registration number. The identifier number is added in the PartyIdentifier element. The personal identifier type is added in the PartySubIdOrType element. - BUSINESS - A specific Business (for example, an organization or a company) @@ -1978,12 +1876,12 @@ paths: PartySubIdOrType element for identifying an account under an Alias defined by the PartyIdentifier. - CONSENT - A Consent represents an agreement between a PISP, a Customer and - a DFSP which allows the PISP permission to perform actions on behalf of the - customer. A Consent has an authoritative source: either the DFSP who issued + a DFSP which allows the PISP permission to perform actions on behalf of the + customer. A Consent has an authoritative source: either the DFSP who issued the Consent, or an Auth Service which administers the Consent. - THIRD_PARTY_LINK - A Third Party Link represents an agreement between a PISP, - a DFSP, and a specific Customer's account at the DFSP. The content of the link - is created by the DFSP at the time when it gives permission to the PISP for + a DFSP, and a specific Customer's account at the DFSP. The content of the link + is created by the DFSP at the time when it gives permission to the PISP for specific access to a given account. example: PERSONAL_ID partyIdentifier: @@ -2006,7 +1904,7 @@ paths: maxLength: 32 description: FSP identifier. extensionList: - $ref: '#/paths/~1thirdpartyRequests~1authorizations/post/requestBody/content/application~1json/schema/properties/extensionList' + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - partyIdType - partyIdentifier @@ -2031,7 +1929,176 @@ paths: description: Data model for the complex type Money. properties: currency: - $ref: '#/paths/~1accounts~1%7BID%7D/put/requestBody/content/application~1json/schema/properties/accountList/items/properties/currency' + title: Currency + description: 'The currency codes defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) as three-letter alphabetic codes are used as the standard naming representation for currencies.' + type: string + minLength: 3 + maxLength: 3 + enum: + - AED + - AFN + - ALL + - AMD + - ANG + - AOA + - ARS + - AUD + - AWG + - AZN + - BAM + - BBD + - BDT + - BGN + - BHD + - BIF + - BMD + - BND + - BOB + - BRL + - BSD + - BTN + - BWP + - BYN + - BZD + - CAD + - CDF + - CHF + - CLP + - CNY + - COP + - CRC + - CUC + - CUP + - CVE + - CZK + - DJF + - DKK + - DOP + - DZD + - EGP + - ERN + - ETB + - EUR + - FJD + - FKP + - GBP + - GEL + - GGP + - GHS + - GIP + - GMD + - GNF + - GTQ + - GYD + - HKD + - HNL + - HRK + - HTG + - HUF + - IDR + - ILS + - IMP + - INR + - IQD + - IRR + - ISK + - JEP + - JMD + - JOD + - JPY + - KES + - KGS + - KHR + - KMF + - KPW + - KRW + - KWD + - KYD + - KZT + - LAK + - LBP + - LKR + - LRD + - LSL + - LYD + - MAD + - MDL + - MGA + - MKD + - MMK + - MNT + - MOP + - MRO + - MUR + - MVR + - MWK + - MXN + - MYR + - MZN + - NAD + - NGN + - NIO + - NOK + - NPR + - NZD + - OMR + - PAB + - PEN + - PGK + - PHP + - PKR + - PLN + - PYG + - QAR + - RON + - RSD + - RUB + - RWF + - SAR + - SBD + - SCR + - SDG + - SEK + - SGD + - SHP + - SLL + - SOS + - SPL + - SRD + - STD + - SVC + - SYP + - SZL + - THB + - TJS + - TMT + - TND + - TOP + - TRY + - TTD + - TVD + - TWD + - TZS + - UAH + - UGX + - USD + - UYU + - UZS + - VEF + - VND + - VUV + - WST + - XAF + - XCD + - XDR + - XOF + - XPF + - XTS + - XXX + - YER + - ZAR + - ZMW + - ZWD amount: title: Amount type: string @@ -2056,6 +2123,8 @@ paths: description: | Date and time until when the transaction request is valid. It can be set to get a quick failure in case the peer FSP takes too long to respond. example: '2016-05-24T08:38:08.699-04:00' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - transactionRequestId - payee @@ -2145,7 +2214,10 @@ paths: schema: title: ThirdpartyRequestsTransactionsIDPutResponse type: object - description: 'The object sent in the PUT /thirdPartyRequests/transactions/{ID} request.' + description: |- + Used by: DFSP + After a PISP requests the creation of a Third Party Transaction request (POST /thirdpartyRequests/transactions) or the status of a previously created Third Party Transaction request (GET /thirdpartyRequests/transactions/{ID}), the DFSP will send this callback. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31721-put-thirdpartyrequeststransactionsid properties: transactionRequestState: title: TransactionRequestState @@ -2162,6 +2234,8 @@ paths: - ACCEPTED - Payer has approved the transaction. - REJECTED - Payer has rejected the transaction. example: RECEIVED + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - transactionRequestState example: @@ -2205,7 +2279,12 @@ paths: schema: title: ThirdpartyRequestsTransactionsIDPatchResponse type: object - description: 'The object sent in the PATCH /thirdpartyRequests/transactions/{ID} callback.' + description: |- + Used by: DFSP + The issuing PISP will expect a response to their request for a transfer which describes the finalized state of the requested transfer. + This response will be given by a PATCH call on the /thirdpartyRequests/transactions/{ID} resource. + The {ID} given in the query string should be the transactionRequestId which was originally used by the PISP to identify the transaction request. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31612-post-thirdpartyrequestsauthorizations properties: completedTimestamp: title: DateTime @@ -2230,6 +2309,8 @@ paths: - COMPLETED - Payee FSP has successfully performed the transaction. - REJECTED - Payee FSP has failed to perform the transaction. example: RECEIVED + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - transactionRequestState - transactionState @@ -2361,9 +2442,14 @@ paths: title: FIDOPublicKeyCredentialAssertion type: object description: | - An object sent in a `PUT /thirdpartyRequests/authorization/{ID}` request. - based mostly on: https://webauthn.guide/#authentication - AuthenticatorAssertionResponse + A data model representing a FIDO Assertion result. + Derived from PublicKeyCredential Interface in WebAuthN. + + The PublicKeyCredential interface represents the below fields with a Type of + Javascript ArrayBuffer. + For this API, we represent ArrayBuffers as base64 encoded utf-8 strings. + + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#32128-fidopublickeycredentialassertion properties: id: type: string @@ -2424,6 +2510,8 @@ paths: - response - type additionalProperties: false + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - verificationRequestId - challenge @@ -2454,6 +2542,8 @@ paths: description: Describes a challenge that has been signed with a private key genericSignedPayload: $ref: '#/paths/~1consentRequests~1%7BID%7D/patch/requestBody/content/application~1json/schema/properties/authToken' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - verificationRequestId - challenge @@ -2500,7 +2590,7 @@ paths: description: | The HTTP request `/thirdpartyRequests/verifications/{ID}` is used to get information regarding a previously created or requested authorization. The *{ID}* - in the URI should contain the verification request ID + in the URI should contain the verification request ID parameters: - $ref: '#/paths/~1consents/post/parameters/0' responses: @@ -2528,12 +2618,10 @@ paths: - sampled operationId: PutThirdpartyRequestsVerificationsById summary: PutThirdpartyRequestsVerificationsById - description: | - The HTTP request `PUT /thirdpartyRequests/verifications/{ID}` is used by the Auth-Service to inform - the DFSP of a successful result in validating the verification of a Thirdparty Transaction Request. - - If the validation fails, The Auth-Service MUST use `PUT /thirdpartyRequests/verifications/{ID}/error` - instead. + description: |- + The HTTP request `PUT /thirdpartyRequests/verifications/{ID}` is used by the Auth-Service to inform the DFSP of a successful result in validating the verification of a Thirdparty Transaction Request. + If the validation fails, the auth-service will send back `PUT /thirdpartyRequests/verifications/{ID}` with `authenticationResponse: 'REJECTED'`. + In unplanned error cases the Auth-Service MUST use `PUT /thirdpartyRequests/verifications/{ID}/error`. parameters: - $ref: '#/paths/~1consents/post/parameters/1' requestBody: @@ -2544,13 +2632,21 @@ paths: schema: title: ThirdpartyRequestsVerificationsIDPutResponse type: object - description: 'The object sent in the PUT /thirdpartyRequests/verifications/{ID} request.' + description: |- + Used by: Auth Service + The callback PUT /thirdpartyRequests/verifications/{ID} is used to inform the client of the result of an authorization check. The {ID} in the URI should contain the authorizationRequestId which was used to request the check, or the {ID} that was used in the GET /thirdpartyRequests/verifications/{ID}. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31821-put-thirdpartyrequestsverificationsid properties: authenticationResponse: + title: AuthenticationResponse type: string enum: - VERIFIED - description: The verification passed + description: |- + The AuthenticationResponse enumeration describes the result of authenticating verification request. + Below are the allowed values for the enumeration AuthenticationResponse. - VERIFIED - The challenge was correctly signed. + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - authenticationResponse example: diff --git a/website/versioned_docs/v1.0.1/api/thirdparty/thirdparty-pisp-v1.0.yaml b/website/versioned_docs/v1.0.1/api/thirdparty/thirdparty-pisp-v1.0.yaml index cb9f52f2..0a42d8dd 100644 --- a/website/versioned_docs/v1.0.1/api/thirdparty/thirdparty-pisp-v1.0.yaml +++ b/website/versioned_docs/v1.0.1/api/thirdparty/thirdparty-pisp-v1.0.yaml @@ -3,8 +3,8 @@ info: title: Mojaloop Third Party API (PISP) version: '1.0' description: | - A Mojaloop API for Payment Initiation Service Providers (PISPs) to perform Third Party functions on DFSPs' User's accounts. - DFSPs who want to enable Payment Initiation Service Providers (PISPs) should implement the accompanying API - Mojaloop Third Party API (DFSP) instead. + A Mojaloop API for Payment Initiation Service Providers (PISPs) to perform Third Party functions on DFSPs' User's accounts. + DFSPs who want to enable Payment Initiation Service Providers (PISPs) should implement the accompanying API - Mojaloop Third Party API (DFSP) instead. license: name: Open API for FSP Interoperability (FSPIOP) (Implementation Friendly Version) url: 'https://github.com/mojaloop/mojaloop-specification/blob/master/LICENSE.md' @@ -69,15 +69,24 @@ paths: schema: title: AccountsIDPutResponse type: object - description: 'The object sent in a `PUT /accounts/{ID}` request.' + description: |- + Callback and data model information for GET /accounts/{ID}: + Callback - PUT /accounts/{ID} Error Callback - PUT /accounts/{ID}/error Data Model - Empty body + The PUT /accounts/{ID} response is used to inform the requester of the result of a request for accounts information. The identifier ID given in the call are the values given in the original request. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31121--put-accountsid properties: accountList: - description: Information about the accounts that the DFSP associates with the identifier sent by the PISP + title: AccountList type: array + description: |- + The AccountList data model is used to hold information about the accounts that a party controls. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#3213-accountlist items: title: Account type: object - description: Data model for the complex type Account. + description: |- + Data model for the complex type Account. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#3211-account properties: accountNickname: title: Name @@ -92,180 +101,15 @@ paths: address: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items/properties/address' currency: - title: Currency - description: 'The currency codes defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) as three-letter alphabetic codes are used as the standard naming representation for currencies.' - type: string - minLength: 3 - maxLength: 3 - enum: - - AED - - AFN - - ALL - - AMD - - ANG - - AOA - - ARS - - AUD - - AWG - - AZN - - BAM - - BBD - - BDT - - BGN - - BHD - - BIF - - BMD - - BND - - BOB - - BRL - - BSD - - BTN - - BWP - - BYN - - BZD - - CAD - - CDF - - CHF - - CLP - - CNY - - COP - - CRC - - CUC - - CUP - - CVE - - CZK - - DJF - - DKK - - DOP - - DZD - - EGP - - ERN - - ETB - - EUR - - FJD - - FKP - - GBP - - GEL - - GGP - - GHS - - GIP - - GMD - - GNF - - GTQ - - GYD - - HKD - - HNL - - HRK - - HTG - - HUF - - IDR - - ILS - - IMP - - INR - - IQD - - IRR - - ISK - - JEP - - JMD - - JOD - - JPY - - KES - - KGS - - KHR - - KMF - - KPW - - KRW - - KWD - - KYD - - KZT - - LAK - - LBP - - LKR - - LRD - - LSL - - LYD - - MAD - - MDL - - MGA - - MKD - - MMK - - MNT - - MOP - - MRO - - MUR - - MVR - - MWK - - MXN - - MYR - - MZN - - NAD - - NGN - - NIO - - NOK - - NPR - - NZD - - OMR - - PAB - - PEN - - PGK - - PHP - - PKR - - PLN - - PYG - - QAR - - RON - - RSD - - RUB - - RWF - - SAR - - SBD - - SCR - - SDG - - SEK - - SGD - - SHP - - SLL - - SOS - - SPL - - SRD - - STD - - SVC - - SYP - - SZL - - THB - - TJS - - TMT - - TND - - TOP - - TRY - - TTD - - TVD - - TWD - - TZS - - UAH - - UGX - - USD - - UYU - - UZS - - VEF - - VND - - VUV - - WST - - XAF - - XCD - - XDR - - XOF - - XPF - - XTS - - XXX - - YER - - ZAR - - ZMW - - ZWD + $ref: '#/paths/~1thirdpartyRequests~1transactions/post/requestBody/content/application~1json/schema/properties/amount/allOf/0/properties/currency' required: - accountNickname - - id + - address - currency + minItems: 1 + maxItems: 256 + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - accounts example: @@ -344,7 +188,7 @@ paths: maxLength: 128 description: Error description string. extensionList: - $ref: '#/paths/~1thirdpartyRequests~1authorizations/post/requestBody/content/application~1json/schema/properties/extensionList' + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - errorCode - errorDescription @@ -400,7 +244,12 @@ paths: schema: title: ConsentRequestsPostRequest type: object - description: The object sent in a `POST /consentRequests` request. + description: |- + Used by: PISP + The HTTP request POST /consentRequests is used to request a DFSP to grant access to one or more accounts owned by a customer of the DFSP for the PISP who sends the request. + Callback and data model for POST /consentRequests: + Callback: PUT /consentRequests/{ID} Error callback: PUT /consentRequests/{ID}/error Data model - see below url + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31212-post-consentrequests properties: consentRequestId: title: CorrelationId @@ -420,13 +269,20 @@ paths: items: title: Scope type: object - description: Scope + Account Identifier mapping for a Consent. + description: |- + The Scope element contains an identifier defining, in the terms of a DFSP, an account on which access types can be requested or granted. It also defines the access types which are requested or granted. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#32121-scope properties: address: title: AccountAddress type: string - description: | - An address which can be used to identify the account. + description: |- + The AccountAddress data type is a variable length string with a maximum size of 1023 characters and consists of: + Alphanumeric characters, upper or lower case. (Addresses are case-sensitive so that they can contain data encoded in formats such as base64url.) + - Underscore (_) - Tilde (~) - Hyphen (-) - Period (.) Addresses MUST NOT end in a period (.) character + An entity providing accounts to parties (i.e. a participant) can provide any value for an AccountAddress that is meaningful to that entity. It does not need to provide an address that makes the account identifiable outside the entity's domain. + IMPORTANT: The policy for defining addresses and the life-cycle of these is at the discretion of the address space owner (the payer DFSP in this case). + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#3212-accountaddress pattern: '^([0-9A-Za-z_~\-\.]+[0-9A-Za-z_~\-])$' minLength: 1 maxLength: 1023 @@ -437,16 +293,18 @@ paths: items: title: ScopeAction type: string + description: | + The ScopeAction element contains an access type which a PISP can request + from a DFSP, or which a DFSP can grant to a PISP. + It must be a member of the appropriate enumeration. + + - ACCOUNTS_GET_BALANCE: PISP can request a balance for the linked account + - ACCOUNTS_TRANSFER: PISP can request a transfer of funds from the linked account in the DFSP + - ACCOUNTS_STATEMENT: PISP can request a statement of individual transactions on a user's account enum: - ACCOUNTS_GET_BALANCE - ACCOUNTS_TRANSFER - ACCOUNTS_STATEMENT - description: | - The permissions allowed on a given account by a DFSP as defined in - a consent object - - ACCOUNTS_GET_BALANCE: PISP can request a balance for the linked account - - ACCOUNTS_TRANSFER: PISP can request a transfer of funds from the linked account in the DFSP - - ACCOUNTS_STATEMENT: PISP can request a statement of individual transactions on a user’s account required: - address - actions @@ -461,9 +319,9 @@ paths: - WEB - OTP description: | - The auth channel being used for the consentRequest. - - "WEB" - The Web auth channel. - - "OTP" - The OTP auth channel. + The auth channel being used for the consent request. + - WEB - DFSP can support authorization via a web-based login. + - OTP - DFSP can support authorization via a One Time PIN. callbackUri: title: Uri type: string @@ -472,6 +330,38 @@ paths: maxLength: 512 description: | The API data type Uri is a JSON string in a canonical format that is restricted by a regular expression for interoperability reasons. + extensionList: + title: ExtensionList + type: object + description: 'Data model for the complex type ExtensionList. An optional list of extensions, specific to deployment.' + properties: + extension: + type: array + items: + title: Extension + type: object + description: Data model for the complex type Extension. + properties: + key: + title: ExtensionKey + type: string + minLength: 1 + maxLength: 32 + description: Extension key. + value: + title: ExtensionValue + type: string + minLength: 1 + maxLength: 128 + description: Extension value. + required: + - key + - value + minItems: 1 + maxItems: 16 + description: Number of Extension elements. + required: + - extension required: - consentRequestId - userId @@ -513,8 +403,8 @@ paths: operationId: GetConsentRequestsById summary: GetConsentRequestsById description: | - The HTTP request `GET /consentRequests/{ID}` is used to get information about a previously - requested consent. The *{ID}* in the URI should contain the consentRequestId that was assigned to the + The HTTP request `GET /consentRequests/{ID}` is used to get information about a previously + requested consent. The *{ID}* in the URI should contain the consentRequestId that was assigned to the request by the PISP when the PISP originated the request. tags: - consentRequests @@ -547,14 +437,14 @@ paths: operationId: UpdateConsentRequest summary: UpdateConsentRequest description: | - A DFSP uses this callback to (1) inform the PISP that the consentRequest has been accepted, + A DFSP uses this callback to (1) inform the PISP that the consentRequest has been accepted, and (2) communicate to the PISP which `authChannel` it should use to authenticate their user with. - When a PISP requests a series of permissions from a DFSP on behalf of a DFSP’s customer, not all - the permissions requested may be granted by the DFSP. Conversely, the out-of-band authorization + When a PISP requests a series of permissions from a DFSP on behalf of a DFSP’s customer, not all + the permissions requested may be granted by the DFSP. Conversely, the out-of-band authorization process may result in additional privileges being granted by the account holder to the PISP. The - **PUT /consentRequests/**_{ID}_ resource returns the current state of the permissions relating to a + **PUT /consentRequests/**_{ID}_ resource returns the current state of the permissions relating to a particular authorization request. parameters: - $ref: '#/paths/~1parties~1%7BType%7D~1%7BID%7D/put/parameters/0' @@ -590,11 +480,13 @@ paths: enum: - WEB description: | - The web auth channel being used for PUT consentRequest/{ID} request. + The web auth channel being used for `PUT /consentRequest/{ID}` request. callbackUri: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/callbackUri' authUri: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/callbackUri' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - scopes - authChannels @@ -624,9 +516,11 @@ paths: enum: - OTP description: | - The OTP auth channel being used for PUT consentRequest/{ID} request. + The OTP auth channel being used for `PUT /consentRequests/{ID}` request. callbackUri: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/callbackUri' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - scopes - authChannels @@ -668,12 +562,17 @@ paths: schema: title: ConsentRequestsIDPatchRequest type: object - description: 'The object sent in a `PATCH /consentRequests/{ID}` request.' + description: |- + Used by: PISP + After the user completes an out-of-band authorization with the DFSP, the PISP will receive a token which they can use to prove to the DFSP that the user trusts this PISP. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31222-patch-consentrequestsid properties: authToken: type: string pattern: '^[A-Za-z0-9-_]+[=]{0,2}$' description: 'The API data type BinaryString is a JSON String. The string is a 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.' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - authToken responses: @@ -782,6 +681,8 @@ paths: description: | Common ID between the PISP and FSP for the Consent object determined by the DFSP who creates the Consent. + consentRequestId: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/consentRequestId' scopes: minLength: 1 maxLength: 256 @@ -801,6 +702,8 @@ paths: Allowed values for the enumeration ConsentStatus - ISSUED - The consent has been issued by the DFSP - REVOKED - The consent has been revoked + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - consentId - scopes @@ -816,8 +719,8 @@ paths: allOf: - $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/consentRequestId' description: | - Common ID between the PISP and the Payer DFSP for the consent object. The ID - should be reused for resends of the same consent. A new ID should be generated + Common ID between the PISP and the Payer DFSP for the consent object. The ID + should be reused for re-sends of the same consent. A new ID should be generated for each new consent. consentRequestId: allOf: @@ -832,6 +735,8 @@ paths: $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' status: $ref: '#/paths/~1consents/post/requestBody/content/application~1json/schema/oneOf/0/properties/status' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - consentId - consentRequestId @@ -870,7 +775,7 @@ paths: - $ref: '#/paths/~1parties~1%7BType%7D~1%7BID%7D/parameters/10' get: description: | - The **GET /consents/**_{ID}_ resource allows a party to enquire after the status of a consent. The *{ID}* used in the URI of the request should be the consent request ID which was used to identify the consent when it was created. + The **GET /consents/**_{ID}_ resource allows a party to enquire after the status of a consent. The *{ID}* used in the URI of the request should be the consent request ID which was used to identify the consent when it was created. tags: - consents operationId: GetConsent @@ -924,7 +829,7 @@ paths: description: | PATCH /consents/{ID} request object. - Sent by the DFSP to the PISP when a consent is verified. + Sent by the DFSP to the PISP when a consent is issued and verified. Used in the "Register Credential" part of the Account linking flow. type: object properties: @@ -932,7 +837,7 @@ paths: type: object properties: status: - title: CredentialStatus + title: CredentialStatusVerified type: string enum: - VERIFIED @@ -941,6 +846,8 @@ paths: - "VERIFIED" - The Credential is valid and verified. required: - status + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - credential - title: ConsentsIDPatchResponseRevoked @@ -952,7 +859,7 @@ paths: type: object properties: status: - title: ConsentStatus + title: ConsentStatusRevoked type: string enum: - REVOKED @@ -961,6 +868,8 @@ paths: - REVOKED - The consent has been revoked revokedAt: $ref: '#/paths/~1thirdpartyRequests~1transactions~1%7BID%7D/patch/requestBody/content/application~1json/schema/properties/completedTimestamp' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - status - revokedAt @@ -1009,18 +918,18 @@ paths: The HTTP request `PUT /consents/{ID}` is used by the PISP to update a Consent with a signed challenge and register a credential. Called by a `PISP` to after signing a challenge. Sent to a DFSP for verification. properties: - scopes: - type: array - items: - $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' status: - title: ConsentStatus + title: ConsentStatusIssued type: string enum: - ISSUED description: |- Allowed values for the enumeration ConsentStatus - ISSUED - The consent has been issued by the DFSP + scopes: + type: array + items: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' credential: title: SignedCredential type: object @@ -1038,12 +947,11 @@ paths: enum: - FIDO - GENERIC - description: | - The type of the Credential. - - "FIDO" - A FIDO public/private keypair - - "GENERIC" - A Generic public/private keypair + description: |- + The type of the Credential. - "FIDO" - The credential is based on a FIDO challenge. Its payload is a FIDOPublicKeyCredentialAttestation object. - "GENERIC" - The credential is based on a simple public key validation. Its payload is a GenericCredential object. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#3226-credentialtype status: - title: CredentialStatus + title: CredentialStatusPending type: string enum: - PENDING @@ -1054,7 +962,7 @@ paths: title: GenericCredential type: object description: | - A publicKey + signature of a challenge for a generic public/private keypair + A publicKey + signature of a challenge for a generic public/private keypair. properties: publicKey: $ref: '#/paths/~1consentRequests~1%7BID%7D/patch/requestBody/content/application~1json/schema/properties/authToken' @@ -1065,50 +973,10 @@ paths: - signature additionalProperties: false fidoPayload: - $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/1/properties/credential/properties/payload' - required: - - credentialType - - status - additionalProperties: false - required: - - scopes - - credential - additionalProperties: false - - title: ConsentsIDPutResponseVerified - type: object - description: | - The HTTP request `PUT /consents/{ID}` is used by the DFSP or Auth-Service to update a Consent object once it has been Verified. - Called by a `auth-service` to notify a DFSP that a credential has been verified and registered. - properties: - scopes: - type: array - items: - $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' - status: - $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/status' - credential: - title: VerifiedCredential - type: object - description: | - A credential used to allow a user to prove their identity and access - to an account with a DFSP. - - VerifiedCredential is a special formatting of the credential to allow us to be - more explicit about the `status` field - it should only ever be VERIFIED when - updating a credential. - properties: - credentialType: - $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/credentialType' - status: - type: string - enum: - - VERIFIED - description: 'The Credential is valid, and ready to be used by the PISP.' - payload: title: FIDOPublicKeyCredentialAttestation type: object description: | - A data model representing a FIDO Attestation result. Derived from + A data model representing a FIDO Attestation result. Derived from [`PublicKeyCredential` Interface](https://w3c.github.io/webauthn/#iface-pkcredential). The `PublicKeyCredential` interface represents the below fields with @@ -1162,8 +1030,50 @@ paths: required: - credentialType - status - - payload additionalProperties: false + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' + required: + - scopes + - credential + additionalProperties: false + - title: ConsentsIDPutResponseVerified + type: object + description: | + The HTTP request `PUT /consents/{ID}` is used by the DFSP or Auth-Service to update a Consent object once it has been Verified. + Called by a `auth-service` to notify a DFSP that a credential has been verified and registered. + properties: + status: + $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/status' + scopes: + type: array + items: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/scopes/items' + credential: + title: VerifiedCredential + type: object + description: | + A credential used to allow a user to prove their identity and access + to an account with a DFSP. + + VerifiedCredential is a special formatting of Credential to allow us to be + more explicit about the `status` field - it should only ever be VERIFIED when + updating a credential. + properties: + credentialType: + $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/credentialType' + status: + $ref: '#/paths/~1consents~1%7BID%7D/patch/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/status' + genericPayload: + $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/genericPayload' + fidoPayload: + $ref: '#/paths/~1consents~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/0/properties/credential/properties/fidoPayload' + required: + - credentialType + - status + additionalProperties: false + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - scopes - credential @@ -1196,7 +1106,7 @@ paths: Used by PISP, DFSP The **DELETE /consents/**_{ID}_ request is used to request the revocation of a previously agreed consent. - For tracing and auditing purposes, the switch should be sure not to delete the consent physically; + For tracing and auditing purposes, the switch should be sure not to delete the consent physically; instead, information relating to the consent should be marked as deleted and requests relating to the consent should not be honoured. operationId: DeleteConsentByID @@ -1298,7 +1208,12 @@ paths: application/json: schema: title: ThirdpartyRequestsAuthorizationsPostRequest - description: POST /thirdpartyRequests/authorizations request object. + description: |- + Used by: DFSP + The HTTP request POST /thirdpartyRequests/authorizations is used to request the validation by a customer for the transfer described in the request. + Callback and data model information for POST /thirdpartyRequests/authorizations: + Callback - PUT /thirdpartyRequests/authorizations/{ID} Error Callback - PUT /thirdpartyRequests/authorizations/{ID}/error Data Model - See below url + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31612-post-thirdpartyrequestsauthorizations type: object properties: authorizationRequestId: @@ -1311,11 +1226,11 @@ paths: transferAmount: allOf: - $ref: '#/paths/~1thirdpartyRequests~1transactions/post/requestBody/content/application~1json/schema/properties/amount/allOf/0' - description: The amount that will be debited from the sending customer’s account as a consequence of the transaction. + description: The amount that will be debited from the sending customer's account as a consequence of the transaction. payeeReceiveAmount: allOf: - $ref: '#/paths/~1thirdpartyRequests~1transactions/post/requestBody/content/application~1json/schema/properties/amount/allOf/0' - description: The amount that will be credited to the receiving customer’s account as a consequence of the transaction. + description: The amount that will be credited to the receiving customer's account as a consequence of the transaction. fees: allOf: - $ref: '#/paths/~1thirdpartyRequests~1transactions/post/requestBody/content/application~1json/schema/properties/amount/allOf/0' @@ -1413,37 +1328,7 @@ paths: - $ref: '#/paths/~1thirdpartyRequests~1transactions~1%7BID%7D/patch/requestBody/content/application~1json/schema/properties/completedTimestamp' description: 'The time by which the transfer must be completed, set by the payee DFSP.' extensionList: - title: ExtensionList - type: object - description: 'Data model for the complex type ExtensionList. An optional list of extensions, specific to deployment.' - properties: - extension: - type: array - items: - title: Extension - type: object - description: Data model for the complex type Extension. - properties: - key: - title: ExtensionKey - type: string - minLength: 1 - maxLength: 32 - description: Extension key. - value: - title: ExtensionValue - type: string - minLength: 1 - maxLength: 128 - description: Extension value. - required: - - key - - value - minItems: 1 - maxItems: 16 - description: Number of Extension elements. - required: - - extension + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - authorizationRequestId - transactionRequestId @@ -1489,8 +1374,8 @@ paths: - $ref: '#/paths/~1parties~1%7BType%7D~1%7BID%7D/parameters/10' get: description: | - The HTTP request **GET /thirdpartyRequests/authorizations/**_{ID}_ is used to get information relating - to a previously issued authorization request. The *{ID}* in the request should match the + The HTTP request **GET /thirdpartyRequests/authorizations/**_{ID}_ is used to get information relating + to a previously issued authorization request. The *{ID}* in the request should match the `authorizationRequestId` which was given when the authorization request was created. operationId: GetThirdpartyRequestsAuthorizationsById summary: GetThirdpartyRequestsAuthorizationsById @@ -1519,7 +1404,7 @@ paths: $ref: '#/paths/~1parties~1%7BType%7D~1%7BID%7D/get/responses/503' put: description: | - After receiving the **POST /thirdpartyRequests/authorizations**, the PISP will present the details of the + After receiving the **POST /thirdpartyRequests/authorizations**, the PISP will present the details of the transaction to their user, and request that the client sign the `challenge` field using the credential they previously registered. @@ -1537,17 +1422,19 @@ paths: application/json: schema: oneOf: - - title: ThirdpartyRequestsAuthorizationsIDPutResponseGeneric + - title: ThirdpartyRequestsAuthorizationsIDPutResponseRejected type: object description: 'The object sent in the PUT /thirdpartyRequests/authorizations/{ID} callback.' properties: responseType: - title: AuthorizationResponseType + title: AuthorizationResponseTypeRejected description: | The customer rejected the terms of the transfer. type: string enum: - REJECTED + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - responseType - title: ThirdpartyRequestsAuthorizationsIDPutResponseFIDO @@ -1562,6 +1449,7 @@ paths: enum: - ACCEPTED signedPayload: + title: SignedPayloadFIDO type: object properties: signedPayloadType: @@ -1574,9 +1462,14 @@ paths: title: FIDOPublicKeyCredentialAssertion type: object description: | - An object sent in a `PUT /thirdpartyRequests/authorization/{ID}` request. - based mostly on: https://webauthn.guide/#authentication - AuthenticatorAssertionResponse + A data model representing a FIDO Assertion result. + Derived from PublicKeyCredential Interface in WebAuthN. + + The PublicKeyCredential interface represents the below fields with a Type of + Javascript ArrayBuffer. + For this API, we represent ArrayBuffers as base64 encoded utf-8 strings. + + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#32128-fidopublickeycredentialassertion properties: id: type: string @@ -1641,6 +1534,8 @@ paths: - signedPayloadType - fidoSignedPayload additionalProperties: false + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - responseType - signedPayload @@ -1652,6 +1547,7 @@ paths: responseType: $ref: '#/paths/~1thirdpartyRequests~1authorizations~1%7BID%7D/put/requestBody/content/application~1json/schema/oneOf/1/properties/responseType' signedPayload: + title: SignedPayloadGeneric type: object properties: signedPayloadType: @@ -1666,6 +1562,8 @@ paths: - signedPayloadType - genericSignedPayload additionalProperties: false + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - responseType - signedPayload @@ -1772,13 +1670,18 @@ paths: schema: title: ThirdpartyRequestsTransactionsPostRequest type: object - description: The object sent in the POST /thirdpartyRequests/transactions request. + description: |- + Used by: PISP + The HTTP request POST /thirdpartyRequests/transactions is used to request the creation of a transaction request on the server for the transfer described in the request. + Callback and data model information for POST /thirdpartyRequests/transactions: + Callback - PUT /thirdpartyRequests/transactions/{ID} Error Callback - PUT /thirdpartyRequests/transactions/{ID}/error Data Model - See link below + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31712-post-thirdpartyrequeststransactions properties: transactionRequestId: allOf: - $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/consentRequestId' description: | - Common ID between the PISP and the Payer DFSP for the transaction request object. The ID should be reused for resends of the same transaction request. A new ID should be generated for each new transaction request. + Common ID between the PISP and the Payer DFSP for the transaction request object. The ID should be reused for resends of the same transaction request. A new ID should be generated for each new transaction request. payee: allOf: - title: Party @@ -1829,7 +1732,7 @@ paths: [RFC 3696](https://tools.ietf.org/html/rfc3696). - PERSONAL_ID - A personal identifier is used as reference to a participant. Examples of personal identification are passport number, birth certificate - number, and national registration number. The identifier number is added in + number, and national registration number. The identifier number is added in the PartyIdentifier element. The personal identifier type is added in the PartySubIdOrType element. - BUSINESS - A specific Business (for example, an organization or a company) @@ -1853,12 +1756,12 @@ paths: PartySubIdOrType element for identifying an account under an Alias defined by the PartyIdentifier. - CONSENT - A Consent represents an agreement between a PISP, a Customer and - a DFSP which allows the PISP permission to perform actions on behalf of the - customer. A Consent has an authoritative source: either the DFSP who issued + a DFSP which allows the PISP permission to perform actions on behalf of the + customer. A Consent has an authoritative source: either the DFSP who issued the Consent, or an Auth Service which administers the Consent. - THIRD_PARTY_LINK - A Third Party Link represents an agreement between a PISP, - a DFSP, and a specific Customer's account at the DFSP. The content of the link - is created by the DFSP at the time when it gives permission to the PISP for + a DFSP, and a specific Customer's account at the DFSP. The content of the link + is created by the DFSP at the time when it gives permission to the PISP for specific access to a given account. example: PERSONAL_ID partyIdentifier: @@ -1877,7 +1780,7 @@ paths: fspId: $ref: '#/paths/~1services~1%7BServiceType%7D/put/requestBody/content/application~1json/schema/properties/providers/items' extensionList: - $ref: '#/paths/~1thirdpartyRequests~1authorizations/post/requestBody/content/application~1json/schema/properties/extensionList' + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - partyIdType - partyIdentifier @@ -1902,7 +1805,176 @@ paths: description: Data model for the complex type Money. properties: currency: - $ref: '#/paths/~1accounts~1%7BID%7D/put/requestBody/content/application~1json/schema/properties/accountList/items/properties/currency' + title: Currency + description: 'The currency codes defined in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) as three-letter alphabetic codes are used as the standard naming representation for currencies.' + type: string + minLength: 3 + maxLength: 3 + enum: + - AED + - AFN + - ALL + - AMD + - ANG + - AOA + - ARS + - AUD + - AWG + - AZN + - BAM + - BBD + - BDT + - BGN + - BHD + - BIF + - BMD + - BND + - BOB + - BRL + - BSD + - BTN + - BWP + - BYN + - BZD + - CAD + - CDF + - CHF + - CLP + - CNY + - COP + - CRC + - CUC + - CUP + - CVE + - CZK + - DJF + - DKK + - DOP + - DZD + - EGP + - ERN + - ETB + - EUR + - FJD + - FKP + - GBP + - GEL + - GGP + - GHS + - GIP + - GMD + - GNF + - GTQ + - GYD + - HKD + - HNL + - HRK + - HTG + - HUF + - IDR + - ILS + - IMP + - INR + - IQD + - IRR + - ISK + - JEP + - JMD + - JOD + - JPY + - KES + - KGS + - KHR + - KMF + - KPW + - KRW + - KWD + - KYD + - KZT + - LAK + - LBP + - LKR + - LRD + - LSL + - LYD + - MAD + - MDL + - MGA + - MKD + - MMK + - MNT + - MOP + - MRO + - MUR + - MVR + - MWK + - MXN + - MYR + - MZN + - NAD + - NGN + - NIO + - NOK + - NPR + - NZD + - OMR + - PAB + - PEN + - PGK + - PHP + - PKR + - PLN + - PYG + - QAR + - RON + - RSD + - RUB + - RWF + - SAR + - SBD + - SCR + - SDG + - SEK + - SGD + - SHP + - SLL + - SOS + - SPL + - SRD + - STD + - SVC + - SYP + - SZL + - THB + - TJS + - TMT + - TND + - TOP + - TRY + - TTD + - TVD + - TWD + - TZS + - UAH + - UGX + - USD + - UYU + - UZS + - VEF + - VND + - VUV + - WST + - XAF + - XCD + - XDR + - XOF + - XPF + - XTS + - XXX + - YER + - ZAR + - ZMW + - ZWD amount: title: Amount type: string @@ -1927,6 +1999,8 @@ paths: description: | Date and time until when the transaction request is valid. It can be set to get a quick failure in case the peer FSP takes too long to respond. example: '2016-05-24T08:38:08.699-04:00' + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - transactionRequestId - payee @@ -2016,7 +2090,10 @@ paths: schema: title: ThirdpartyRequestsTransactionsIDPutResponse type: object - description: 'The object sent in the PUT /thirdPartyRequests/transactions/{ID} request.' + description: |- + Used by: DFSP + After a PISP requests the creation of a Third Party Transaction request (POST /thirdpartyRequests/transactions) or the status of a previously created Third Party Transaction request (GET /thirdpartyRequests/transactions/{ID}), the DFSP will send this callback. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31721-put-thirdpartyrequeststransactionsid properties: transactionRequestState: title: TransactionRequestState @@ -2033,6 +2110,8 @@ paths: - ACCEPTED - Payer has approved the transaction. - REJECTED - Payer has rejected the transaction. example: RECEIVED + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - transactionRequestState example: @@ -2076,7 +2155,12 @@ paths: schema: title: ThirdpartyRequestsTransactionsIDPatchResponse type: object - description: 'The object sent in the PATCH /thirdpartyRequests/transactions/{ID} callback.' + description: |- + Used by: DFSP + The issuing PISP will expect a response to their request for a transfer which describes the finalized state of the requested transfer. + This response will be given by a PATCH call on the /thirdpartyRequests/transactions/{ID} resource. + The {ID} given in the query string should be the transactionRequestId which was originally used by the PISP to identify the transaction request. + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31612-post-thirdpartyrequestsauthorizations properties: completedTimestamp: title: DateTime @@ -2101,6 +2185,8 @@ paths: - COMPLETED - Payee FSP has successfully performed the transaction. - REJECTED - Payee FSP has failed to perform the transaction. example: RECEIVED + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - transactionRequestState - transactionState @@ -2431,7 +2517,7 @@ paths: fspId: $ref: '#/paths/~1services~1%7BServiceType%7D/put/requestBody/content/application~1json/schema/properties/providers/items' extensionList: - $ref: '#/paths/~1thirdpartyRequests~1authorizations/post/requestBody/content/application~1json/schema/properties/extensionList' + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - partyIdType - partyIdentifier @@ -2747,7 +2833,12 @@ paths: schema: title: ServicesServiceTypePutResponse type: object - description: 'The object sent in a `PUT /services/{ServiceType}` request.' + description: |- + Used by: Switch + The callback PUT /services/{ServiceType} is used to inform the client of a successful result of the service information lookup. + Callback and data model information for GET /services/{ServiceType}: + Callback - PUT /services/{ServiceType} Error Callback - PUT /services/{ServiceType}/error Data Model - Empty body + https://github.com/mojaloop/documentation/blob/master/website/versioned_docs/v1.0.1/api/thirdparty/data-models.md#31531-put-servicesservicetype properties: providers: type: array @@ -2759,6 +2850,8 @@ paths: minLength: 1 maxLength: 32 description: FSP identifier. + extensionList: + $ref: '#/paths/~1consentRequests/post/requestBody/content/application~1json/schema/properties/extensionList' required: - providers responses: