Use Case 2: Sell-Side - Distributing Assets

Overview

The following is a sell-side walkthrough for integrating into your Ownera router via the FinP2P API for the purpose of issuing assets to distribute to your partnered financial organizations. The steps involved are as follows:

  1. Onboarding the issuer - create the owner who will be assigned as the issuer of the given asset.
  2. Onboarding the asset - onboard the asset to distribute it to your business partners.
  3. Creating a primary sales intent - define the asset to facilitate primary investment.
  4. Process trade requests - receive and process primary and secondary intent trade requests orchestrated by a comprehensive execution plan.
  5. Facilitate withdrawal requests - implement the ability to send fund withdrawal requests from payment providers on behalf of the issuer, accrued via investment proceeds.

API Integration Flow

The following table will walk you through the step-by-step sell-side integration involved in onboarding you asset for distribution:

#API ReferenceDescription

Onboard the Investor
1Create Issuer Registers the issuer on your router.
2Attach Certificates[Optional] Attach certificates to the investor, such as KYA.

For FinP2P recommended certificate specifications refer to https://github.com/owneraio/finp2p-certificates-spec
3Attach Documentation [Optional] Add additional documentation to provide additional information about the issuer.
4Share Issuer with Payments Service Link the issuer to the applicable payments organization responsible for handling the payments leg for the issuer.

Note: If the your router provides also payment services to the issuer, this step can be omitted

Setup the Account
5n/aNote settlement account will be auto-created (if does not exist already) on-behalf of the issuer during trade execution, therefore no initial setup required.

Onboarding an Asset
6Create the Asset Define the asset you are onboarding, including values such as asset denomination, basic name, etc.
7Attach Certificates Attach certificates, such as “KYA” to the given asset.
8Attach Documentation Add additional documentation to support and facilitate asset trading.

This is done by attaching documents to the given asset certificate, such as PDFs or images of the asset.
9Select Organizations to Distribute To Share an asset with the given organization(s) that you allow to have access to the asset to invest in.
10Handle Asset Creation NotificationWhen an asset is onboarded, you will receive this notification on your ledger adapter.

You will be able to decide which process you want to implement. If tokenization of the asset on the blockchain is done prior to onboarding, just respond back with success, otherwise invoke your process to tokenize the asset.

Create and Processing Primary Sale
11Create a Primary Sale Allow for investors in which you shared the asset with to investment in the primary sale (issuance).

This is an intent of type “Primary Sales”.
12Receive Notification and Approve New Execution PlanYou will receive an execution plan notification which will be an indication that a new request for primary sale investment (issuance) in the given asset by an investor was submitted.

You can chose to immediately approve the execution plan, or response with acknowledgement and approve it in a subsequent asynchronous manner after you review the plan.
13Review Execution Plan(Optional) Poll the plan to review and asset your participation in the execution plan, and in turn will allow you to process your approval.

Refer to the execution plan explanation.
Execution Plan
14Process Status Polling for Execution Plan Approval(Optional) If you chose to process approval in asynchronous manner, the router will polling your side for status on approval.
15Process Issuance RequestDevelop the logic to process the primary sale intent execution request which is sent to your adapter.

This step can include logic for handling regulations and other order execution acceptance parameters

The request can either be processed synchronously or asynchronously (isCompleted set to True or false accordingly)

Respond with a CID which will be used as a method to poll your side for completion.
16Process Request AsynchronouslyImplement the get operation ability in order to allow to query for the status of the execution request sent to you, for the case you chose the process the issuance request asynchronously.
17Query ReceiptsUses GraphQL to either subscribe or query for the receipts that will serve as confirmation that the investment was executed and payment was processed.
18Monitor Execution Plan ProgressionAnd/or use the get execution plan details and continue to pool to see progress of the plan
19Provide ReceiptsAllow to request receipt details from your ledger, which can be used for proof of ownership and/or of a reconciliation processes.
20Provide Ledger Asset BalanceAllow to request the token balance for the given owner off the asset.

Process Secondary Intent Executions
21Receive Notification and Approve New Execution PlanYou will receive an execution plan notification which will be an indication that a new request for a trade in which the given asset is requested to be transferred from one investor to another.

You can chose to immediately approve the execution plan, or response with acknowledgement and approve it in a subsequent asynchronous manner after you review the plan.
22Review Execution Plan(Optional) Poll the plan to review and asset your participation in the execution plan, and in turn will allow you to process your approval.

Refer to the execution plan explanation.
Execution Plan
23Process Status Polling for Execution Plan Approval(Optional) If you chose to process approval in asynchronous manner, the router will polling your side for status on approval.
24Process Secondary Trade RequestDevelop the logic to process the secondary intent execution request which is sent to your adapter.

This step can include logic for handling regulations and other order execution acceptance parameters

The request can either be processed synchronously or asynchronously (isCompleted set to True or false accordingly)

Respond with a CID which will be used as a method to poll your side for completion.
25Process Request AsynchronouslyImplement the get operation ability in order to allow to query for the status of the execution request sent to you.
26Provide ReceiptsAllow to request receipt details from your ledger.
27Provide Ledger Asset BalanceAllow to request the token balance for the given owner on the asset.

Update balance manually
28Perform Balance AdjustmentsThis will allow you to make balance adjustments that were the result of activities performed outside of the Ownera scope of trading.

Request Fund Withdrawal
29Request Funds Withdrawal The issuer has the option to withdraw the funds that are in the given account by putting in a request for withdrawal. This request is routed to the given payment service provider to process.
30Poll for Transaction CompletionIf the request is processed asynchronously, use the get operations to receive the response.

Testing Your Integration

You can test your sell-side integration by requesting from Ownera a buy-side sandbox which will provide you with a test Investor App.

Example: Sell Side Walkthrough

The following is an example walkthrough for the sell side integration.

ParameterDescriptionValue
Issuer Fin IDThe public key used in creating the user profile, which in turn will be used as the finID for the user when transacting.024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a
Issuer User IDThe finP2P resource ID for the given user created.bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181
Issuer Payments Service Org IDThe payments service organization that will be used to transact the investmentpayments-router
Asset IDThe asset ID assigned to the created asset.bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54
Primary Sale Intent IDThe Id assigned to the primary sale intent that is created.bank-us:105:3a360d7a-df60-40b2-9574-eccaa1ed1f08

Create user profile

curl --location --request POST 'http://<router url>/finapi/profiles/owner' \
--header 'Content-Type: application/json' \
--data-raw '{
    "publicKey": "024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a",
    "signature": "a3f1aa3a48ab2cc17957609d294a4d27d1b6146596f017ab672a6a66048a460f7f6efa718014df8b39f7458fde55e9ef008c66e5ae74ee96df437cbf624df620"
}'
{
    "isCompleted": true,
    "response": {
        "id": "bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181"
    },
    "type": "profile"
}

Attach certificate to the given user

curl --location --request POST 'http://<router url>/finapi/profiles/bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181/certificates' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "ownerInfo",
  "issuanceDate": 1668598695,
  "expirationDate": 1700134695,
  "data": "{\"email\":\"[email protected]\",\"name\":\"Issuer1\",\"type\":\"issuer\"}"
}'
{
    "id": "ec634170-8c62-4d55-b324-0391eb30fac1"
}

Upload a document to the given certificate, pointing to a location of the file

curl --location --request POST 'http://<router url>/finapi/profiles/bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181/certificates/ec634170-8c62-4d55-b324-0391eb30fac1' \
--form 'kya doc=@"/kyc.pdf"'

Associate the user with the given payments service

curl --location --request POST 'http://<router url>/finapi/profiles/bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181\share' \
--header 'Content-Type: application/json' \
--data-raw '{
     "organizations": [
          "payements-service"
     ]
}'
n/a

Create the asset

curl --location --request POST 'http://<router url>/finapi/profiles/asset' \
--header 'Content-Type: application/json' \
--data-raw '{     "denomination": {
          "type": "fiat",
          "code": "USD"
     },
     "config": " ",
     "name": "BUILDING123456789",
     "type": "Building",
     "issuerId": "bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181"
}'
{
    "isCompleted": true,
    "response": {
        "id": "bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835"
    },
    "type": "profile"
}

Process the asset creation request

This endpoint that is required on the ledger adapter will process the notification that an asset has been onboarded on Ownera at your organization (e.g., will be invoked as a result of the asset profile creation).

If your process has the asset tokenized prior to onboarding on Ownera, just confirm the message, and/or you can use this call to perform your mapping between the asset id of Ownera provided in this message and your asset id (e.g., blockchain contract address).

If not, invoke your logic for tokenizing the assets and linking it to the Ownera asset id.

curl --location --request POST 'http://<adapter url>/assets/create' \
--header 'Content-Type: application/json' \
--data-raw '{
  "asset": {
    "type": "finp2p",
    "resourceId": "bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835"
  }
}'
{
    "isCompleted": true
}

Attached a Know Your Asset (KYA) certificate to the asset

curl --location --request POST 'http://<router url>/finapi/profiles/bank-us:102:873e82a0-274a-4762-8535-7b9540cf680b/certificates' \
--header 'Content-Type: application/json' \
--data-raw '{

  "type": "KYA",
  "issuanceDate": 1668598695,
  "expirationDate": 1672399561,
  "data": "{\"publicName\":\"Public Asset Building 2\",\"officialName\":\"Official Asset Building 2\",\"description\":\"Description of the Asset Building 2.\",\"info\":[{\"type\":\"text\",\"name\":\"Location\",\"value\":\"NYC\"},{\"type\":\"link\",\"name\":\"Website\",\"value\":\"https://www.assetpage.com\"}]}"
}'

Optional: Attached images to the asset (examples below illustrate the setting of images in case you are using the Ownera App)

Note the naming convention for the images

curl --location --request POST 'http://<router url>/finapi/profiles/bank-us:102:873e82a0-274a-4762-8535-7b9540cf680b/certificates/b57732e7-a477-4769-8753-f761a1412a60/docs' \
--header 'Content-Type: application/json' \
--form 'asset icon=@"/icon-asset profle.png"'
curl --location --request POST 'http://localhost:62532/profiles/bank-us:102:873e82a0-274a-4762-8535-7b9540cf680b/certificates/b57732e7-a477-4769-8753-f761a1412a60/docs' \
--header 'Content-Type: application/json' \
--form 'asset logo=@"/logo-asset profle.png"'

Create a Primary Sale Intent

The intent below is an example of making 50 tokens available each at the price of 1 USD. The intent indicates the finId and the payments service organization that is going to be used for managing the issuance, and the destination for the payment for the investment.

curl --location --request POST 'http://<router url>/finapi/profiles/asset/bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835/intent' \
--header 'Content-Type: application/json' \
--data-raw '{
     "assetTerm": {
          "asset": {
               "type": "finp2p",
               "resourceId": "bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835"
          },
          "amount": "50"
     },
     "assetInstruction": {
          "account": {
               "account": {
                    "type": "finId",
                    "finId": "024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a",
                    "orgId": "payements-service"
               },
               "asset": {
                    "type": "finp2p",
                    "resourceId": "bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835"
               }
          }
     },
     "settlementTerm": {
          "asset": {
               "type": "fiat",
               "code": "USD"
          },
          "unitValue": "1"
     },
     "intent": {
          "type": "primarySale",
          "settlementInstruction": {
               "type": "escrow",
               "destinationAccounts": [
                    {
                         "account": {
                              "type": "finId",
                              "finId": "024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a",
                              "orgId": "payements-service"
                         },
                         "asset": {
                              "type": "fiat",
                              "code": "USD"
                         }
                    }
               ]
          },
          "issuer": "bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181"
     },
     "start": 1671108000,
     "end": 1672399561
}'
{
    "id": "bank-us:105:cd3a32e0-da32-4161-a00b-d138a56712d6"
}

Receive a notification message which indicates of a new execution plan submission for an asset in which is managed by your organization for issuance in which you will need to approve. If no decision making is required, you can approve immediately, otherwise acknowledge and process it asynchronously.

curl --location --request POST 'http://<adapter url>/plan/approve' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "executionPlanId": "bank-uk:106:9909e355-df0e-4708-8121-cec192089418"
}'
{
  "cid": "12321321",
  "isCompleted": false,
}

{
  "cid": "12321321",
  "isCompleted": true,
  "approval": {
    "status": "approved"
  }
}

You can query the router for details on the execution plan outlining the full workflow for the execution of the given transaction.

curl --location 'http://<router url>/finapi/execution/bank-uk:106:9909e355-df0e-4708-8121-cec192089418' \
--header 'Content-Type: application/json' \
--data ''
{
    "approvals": [
        {
            "organizationId": "bank-uk"
        },
        {
            "organizationId": "payements-service"
        }
    ],
    "creationTimestamp": 1702201257,
    "currentInstructionSequence": 3,
    "executionPlanStatus": "completed",
    "instructionsCompletionEvents": [
        {
            "instructionSequenceNumber": 1,
            "output": {
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                },
                "details": {
                    "source": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "asset": {
                            "code": "USD",
                            "type": "fiat"
                        }
                    },
                    "transactionDetails": {
                        "transactionId": ""
                    },
                    "type": "payment"
                },
                "id": "f746274b-533c-4ea4-8c31-1ab3cb45bbd6",
                "quantity": "246",
                "source": "bank-uk:101:a4bba07f-8592-4caa-9803-7a3c5370a6a7",
                "timestamp": 1702201258,
                "type": "receipt"
            }
        },
        {
            "instructionSequenceNumber": 2,
            "output": {
                "asset": {
                    "code": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
                    "type": "finp2p"
                },
                "destination": "bank-uk:101:a4bba07f-8592-4caa-9803-7a3c5370a6a7",
                "details": {
                    "destinationFinId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                    "sourceFinId": "",
                    "transactionDetails": {
                        "transactionId": ""
                    },
                    "type": "asset"
                },
                "id": "2c38639e-a3d7-42dd-b0a6-bebfe4963b4d",
                "quantity": "123",
                "timestamp": 1702201258574140906,
                "type": "receipt"
            }
        },
        {
            "instructionSequenceNumber": 3,
            "output": {
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                },
                "destination": "bank-uk:101:ff60289e-19f0-4f4c-a291-d587fb463999",
                "details": {
                    "destination": {
                        "account": {
                            "finId": "03565ed4e4d889ee24b7a6f830aa0df31d7ba2ad88e9b1839d84c82de951397524",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "asset": {
                            "code": "USD",
                            "type": "fiat"
                        }
                    },
                    "source": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "ownera-escrow",
                            "type": "finId"
                        },
                        "asset": {
                            "code": "USD",
                            "type": "fiat"
                        }
                    },
                    "transactionDetails": {
                        "transactionId": ""
                    },
                    "type": "payment"
                },
                "id": "5f26c679-4a8f-44e1-a9d8-b713f982dbe6",
                "quantity": "246.00",
                "source": "bank-uk:101:a4bba07f-8592-4caa-9803-7a3c5370a6a7",
                "timestamp": 1702201258,
                "type": "receipt"
            }
        }
    ],
    "plan": {
        "id": "bank-uk:106:9909e355-df0e-4708-8121-cec192089418",
        "instructions": [
            {
                "executionPlanOperation": {
                    "amount": "246",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    },
                    "destination": {
                        "account": {
                            "finId": "03565ed4e4d889ee24b7a6f830aa0df31d7ba2ad88e9b1839d84c82de951397524",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "finId": "03565ed4e4d889ee24b7a6f830aa0df31d7ba2ad88e9b1839d84c82de951397524"
                    },
                    "signature": {
                        "signature": "0f23b4f9356c9a1e9885d257ebd1401c4650147c03f0c6139b46f032ee03054368d1d05f117b5f5ba93944d0a1f0eb367e5b0a35b0a43eb3795846928f97fee6",
                        "template": {
                            "hash": "09bfce0aba7baeb04a144a8d43637b6b5ec46bf27e0e7d952fe8e1197198a975",
                            "hashGroups": [
                                {
                                    "fields": [
                                        {
                                            "name": "nonce",
                                            "type": "bytes",
                                            "value": "2b4b91c29a38f3ee67acfc2c8d1a8ee8169603a72097182e0000000065758798"
                                        },
                                        {
                                            "name": "operation",
                                            "type": "string",
                                            "value": "issue"
                                        },
                                        {
                                            "name": "assetType",
                                            "type": "string",
                                            "value": "finp2p"
                                        },
                                        {
                                            "name": "assetId",
                                            "type": "string",
                                            "value": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0"
                                        },
                                        {
                                            "name": "dstAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "dstAccount",
                                            "type": "string",
                                            "value": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                                        },
                                        {
                                            "name": "amount",
                                            "type": "string",
                                            "value": "123"
                                        }
                                    ],
                                    "hash": "ade901c06bfd087769b8eb37ea38209ad01f828014db2e0a61d3646d2cd7fbe1"
                                },
                                {
                                    "fields": [
                                        {
                                            "name": "assetType",
                                            "type": "string",
                                            "value": "fiat"
                                        },
                                        {
                                            "name": "assetId",
                                            "type": "string",
                                            "value": "USD"
                                        },
                                        {
                                            "name": "srcAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "srcAccount",
                                            "type": "string",
                                            "value": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                                        },
                                        {
                                            "name": "dstAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "dstAccount",
                                            "type": "string",
                                            "value": "03565ed4e4d889ee24b7a6f830aa0df31d7ba2ad88e9b1839d84c82de951397524"
                                        },
                                        {
                                            "name": "amount",
                                            "type": "string",
                                            "value": "246"
                                        },
                                        {
                                            "name": "expiry",
                                            "type": "string",
                                            "value": "500"
                                        }
                                    ],
                                    "hash": "917993a24080daac6c47ecc51bbdf0727e7fb272a6775a5b36e7862f9273330b"
                                }
                            ]
                        }
                    },
                    "source": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                    },
                    "type": "hold"
                },
                "organizations": [
                    "ownera-escrow"
                ],
                "sequence": 1
            },
            {
                "executionPlanOperation": {
                    "amount": "123",
                    "asset": {
                        "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
                        "type": "finp2p"
                    },
                    "destination": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "bank-uk",
                            "type": "finId"
                        },
                        "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                    },
                    "signature": {
                        "signature": "0f23b4f9356c9a1e9885d257ebd1401c4650147c03f0c6139b46f032ee03054368d1d05f117b5f5ba93944d0a1f0eb367e5b0a35b0a43eb3795846928f97fee6",
                        "template": {
                            "hash": "09bfce0aba7baeb04a144a8d43637b6b5ec46bf27e0e7d952fe8e1197198a975",
                            "hashGroups": [
                                {
                                    "fields": [
                                        {
                                            "name": "nonce",
                                            "type": "bytes",
                                            "value": "2b4b91c29a38f3ee67acfc2c8d1a8ee8169603a72097182e0000000065758798"
                                        },
                                        {
                                            "name": "operation",
                                            "type": "string",
                                            "value": "issue"
                                        },
                                        {
                                            "name": "assetType",
                                            "type": "string",
                                            "value": "finp2p"
                                        },
                                        {
                                            "name": "assetId",
                                            "type": "string",
                                            "value": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0"
                                        },
                                        {
                                            "name": "dstAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "dstAccount",
                                            "type": "string",
                                            "value": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                                        },
                                        {
                                            "name": "amount",
                                            "type": "string",
                                            "value": "123"
                                        }
                                    ],
                                    "hash": "ade901c06bfd087769b8eb37ea38209ad01f828014db2e0a61d3646d2cd7fbe1"
                                },
                                {
                                    "fields": [
                                        {
                                            "name": "assetType",
                                            "type": "string",
                                            "value": "fiat"
                                        },
                                        {
                                            "name": "assetId",
                                            "type": "string",
                                            "value": "USD"
                                        },
                                        {
                                            "name": "srcAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "srcAccount",
                                            "type": "string",
                                            "value": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                                        },
                                        {
                                            "name": "dstAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "dstAccount",
                                            "type": "string",
                                            "value": "03565ed4e4d889ee24b7a6f830aa0df31d7ba2ad88e9b1839d84c82de951397524"
                                        },
                                        {
                                            "name": "amount",
                                            "type": "string",
                                            "value": "246"
                                        },
                                        {
                                            "name": "expiry",
                                            "type": "string",
                                            "value": "500"
                                        }
                                    ],
                                    "hash": "917993a24080daac6c47ecc51bbdf0727e7fb272a6775a5b36e7862f9273330b"
                                }
                            ]
                        }
                    },
                    "type": "issue"
                },
                "organizations": [
                    "bank-uk"
                ],
                "sequence": 2
            },
            {
                "executionPlanOperation": {
                    "amount": "246",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    },
                    "destination": {
                        "account": {
                            "finId": "03565ed4e4d889ee24b7a6f830aa0df31d7ba2ad88e9b1839d84c82de951397524",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "finId": "03565ed4e4d889ee24b7a6f830aa0df31d7ba2ad88e9b1839d84c82de951397524"
                    },
                    "source": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                    },
                    "type": "release"
                },
                "organizations": [
                    "ownera-escrow"
                ],
                "sequence": 3
            }
        ],
        "intent": {
            "assetInstruction": {
                "account": {
                    "account": {
                        "finId": "03565ed4e4d889ee24b7a6f830aa0df31d7ba2ad88e9b1839d84c82de951397524",
                        "orgId": "bank-uk",
                        "type": "finId"
                    },
                    "asset": {
                        "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
                        "type": "finp2p"
                    }
                }
            },
            "assetTerm": {
                "amount": "100000000",
                "asset": {
                    "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
                    "type": "finp2p"
                }
            },
            "end": 1704029090,
            "intent": {
                "issuer": "bank-uk:101:ff60289e-19f0-4f4c-a291-d587fb463999",
                "settlementInstruction": {
                    "destinationAccounts": [
                        {
                            "account": {
                                "finId": "03565ed4e4d889ee24b7a6f830aa0df31d7ba2ad88e9b1839d84c82de951397524",
                                "orgId": "payements-service",
                                "type": "finId"
                            },
                            "asset": {
                                "code": "USD",
                                "type": "fiat"
                            }
                        }
                    ],
                    "type": "escrow"
                },
                "type": "primarySale"
            },
            "settlementTerm": {
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                },
                "unitValue": "2"
            },
            "start": 1701264290
        },
        "participants": [
            {
                "organizationId": "bank-uk",
                "roles": [
                    "contributor"
                ]
            },
            {
                "organizationId": "payements-service",
                "roles": [
                    "contributor"
                ]
            }
        ]
    }
}

Process request for status of execution plan approval

curl --location 'http://<router url>/operations/status/12321321' \
--header 'Content-Type: application/json' \
--data ''
{
  "cid": "12321321",
  "isCompleted": true,
  "approval": {
    "status": "approved"
  }
}
{
  "cid": "12321321",
  "isCompleted": true,
  "approval": {
     "status": "rejected",
  "failure": {
    "failureType": "validationFailure",
    "code": 1001,
    "message": "Invalid input data provided"
  }
  }
}

Receive and respond back to primary sale investment token issuance request

The message contains a reference to the execution plan you received. Respond to the process as indicated in order to process this request in an asynchronous manner. The cid you will return will be used next in the operational status polling to receive the progress and completion on processing of the issuance request.

curl --location --request POST 'http://<adapter url>/assets/issue' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "nonce": "7282551a6ffc938e58cdb9a32c7e7c2f60e2b0466b47800e0000000063e0c5bd",
  "asset": {
    "resourceId": "bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835",
    "type": "finp2p"
  },
  "destination": {
    "finId": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3",
    "type": "finId"
  },
  "quantity": "1",
  "settlementRef": "2ad5a917-25d9-3e68-743c-30eab4a73fb1",
  "executionContext": {
    "executionPlanId": "bank-uk:106:9909e355-df0e-4708-8121-cec192089418",
    "instructionSequenceNumber": 2
  },
  "signature": {
    "signature": "",
    "template": {
      "hash": "",
      "hashGroups": ""
    }
  }
}'
{
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": false,    
    "response": {              
    }
}

Process request for status of execution plan approval if you chose to handle approval asynchronously

Note: The error code and text should designate an exception that is meaningful for investigation of the processing failure.

curl --location --request POST 'http://<adapter_url>/operations/6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9' \
--header 'Content-Type: application/json' \
--data-raw '
{
}'
{
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": false,    
    "response": {              
    }
}
{
  "type": "receipt",
  "operation": {
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": true,
    "error": "",
    "response": {
      "id": "1031C909828C9BB3ED572A0066B1565357A993409DE4330E8319D2D0B7553D64",
      "asset": {
        "type": "finp2p",
        "resourceId": "bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835"
      },
      "quantity": "1",
      "destination": {
        "finId": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3",
        "account": {
          "type": "finId",
          "finId": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3"
        }
      },
      "settlementRef": "2ad5a917-25d9-3e68-743c-30eab4a73fb1",
      "transactionDetails": {
        "transactionId": "1031C909828C9BB3ED572A0066B1565357A993409DE4330E8319D2D0B7553D64",
        "inputs": [],
        "outputs": []
      }
    }
  }
}
{
  "type": "receipt",
  "operation": {
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": true,
    "error": {
      "Code": 18,
      "Message": "Transfer operation failed"
    }
  }
}

Use GraphQL subscription to get receipts in order to receive indication of investment executions, including confirmation of payment

There will be two generated receipts:

  1. Token Exchange Confirmation
  2. Payments Confirmation

Note both paired receipts are related via the "settlementRef" value.

subscription Receipts {
  receiptAdded {
    id
    asset {
      __typename
      ... on FinP2PAsset {
        resourceId
      }
    }
    source {
      id
      publicKey
      certificates {
        nodes {
          expiry
          type
          data
        }
      }
    }
    sourceAccount {
        __typename
        ... on Iban {
          __typename
        }
        ... on FinIdAccount {
          finId
        }
        ... on CryptoWalletAccount {
          address
        }
        ... on FinIdAccount {
          __typename
        }
      }
      destination {
        id
        publicKey
        certificates {
          nodes {
            expiry
            type
            data
          }
        }
      }
      destinationAccount {
        __typename
      }
      quantity
      tradeDetails {
        intent {
          id
          start
          end
          status
          assetTerm {
            amount
          }
          assetInstruction {
            account {
              asset {
                __typename
              }
            }
          }
          settlementTerm {
            asset {
              __typename
            }
            unitValue
          }
          remainingQuantity
          type
          intent {
            __typename
          }
        }
      }
      settlementRef
      transactionId
    }
  
}
{
  "data": {
    "receipts": {
      "nodes": [
        {
          "id": "c8f1d7c3-1868-4ec0-a4ee-8a342023cd68",
          "asset": {
            "__typename": "FinP2PAsset",
            "resourceId": "bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54"
          },
          "source": {
            "id": "",
            "publicKey": "",
            "certificates": {
              "nodes": []
            }
          },
          "sourceAccount": {
            "__typename": "FinIdAccount",
            "finId": ""
          },
          "destination": {
            "id": "bank-us:101:7572e35f-f9c4-42f6-adee-9669656e6806",
            "publicKey": "039e83762efdb9f4efd8acff6afd4c66a214dee8e288a689a2e9aaf409db75c979",
            "certificates": {
              "nodes": [
                {
                  "expiry": 1700134695,
                  "type": "ownerInfo",
                  "data": "{\"email\":\"[email protected]\",\"name\":\"Investor_us_5_api\",\"type\":\"company\"}"
                }
              ]
            }
          },
          "destinationAccount": {
            "__typename": "FinIdAccount"
          },
          "quantity": "1",
          "tradeDetails": {
            "intent": {
              "id": "bank-us:105:249e3d4e-0530-46c9-bde2-e76c1709ce67",
              "start": 1672236375,
              "end": 1672495560,
              "status": "ACTIVE",
              "assetTerm": {
                "amount": "100"
              },
              "assetInstruction": {
                "account": {
                  "asset": {
                    "__typename": "FinP2PAsset"
                  }
                }
              },
              "settlementTerm": {
                "asset": {
                  "__typename": "FiatAsset"
                },
                "unitValue": "1"
              },
              "remainingQuantity": "99",
              "type": "primarySale",
              "intent": {
                "__typename": "PrimarySale"
              }
            }
          },
          "settlementRef": "44b7c009-beb2-8b7c-5a47-6b843d4e6b2a",
          "transactionId": ""
        }
      ]
    }
  }
}
{
  "data": {
    "receiptAdded": {
      "id": "79af30c5-634f-465a-a740-45a4cb23f064",
      "asset": {
        "__typename": "FiatAsset"
      },
      "source": {
        "id": "bank-us:101:7572e35f-f9c4-42f6-adee-9669656e6806",
        "publicKey": "039e83762efdb9f4efd8acff6afd4c66a214dee8e288a689a2e9aaf409db75c979"
      },
      "sourceAccount": {
        "__typename": "FinIdAccount",
        "finId": "039e83762efdb9f4efd8acff6afd4c66a214dee8e288a689a2e9aaf409db75c979"
      },
      "destination": {
        "id": "bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181",
        "publicKey": "024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a"
      },
      "destinationAccount": {
        "__typename": "FinIdAccount"
      },
      "quantity": "1.00",
      "tradeDetails": {
        "intent": null
      },
      "settlementRef": "44b7c009-beb2-8b7c-5a47-6b843d4e6b2a",
      "transactionId": ""
    }
  }
}

Example: Processing Secondary Intent Execution Request

Receive a notification message which indicates of a new execution plan submission for an asset in which is managed by your organization for transfer of ownership between investors in which you will need to approve. If no decision making is required, you can approve immediately, otherwise acknowledge and process it asynchronously.

curl --location --request POST 'http://<adapter url>/plan/approve' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "executionPlanId": "bank-uk:106:aa0ab7c6-3193-44c5-9760-c9e1e048e2a0"
}'
{
  "cid": "12321321",
  "isCompleted": false,
}

{
  "cid": "12321321",
  "isCompleted": true,
  "approval": {
    "status": "approved"
  }
}

You can request from the router for details on the execution plan outlining the full workflow for the execution of the given transaction

curl --location 'http://http://<router url>/finapi/execution/bank-uk:106:aa0ab7c6-3193-44c5-9760-c9e1e048e2a0' \
--header 'Content-Type: application/json' \
--data ''
{
    "approvals": [
        {
            "organizationId": "payements-service"
        },
        {
            "organizationId": "bank-uk"
        }
    ],
    "creationTimestamp": 1702203545,
    "currentInstructionSequence": 3,
    "executionPlanStatus": "completed",
    "instructionsCompletionEvents": [
        {
            "instructionSequenceNumber": 1,
            "output": {
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                },
                "details": {
                    "source": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "asset": {
                            "code": "USD",
                            "type": "fiat"
                        }
                    },
                    "transactionDetails": {
                        "transactionId": ""
                    },
                    "type": "payment"
                },
                "id": "828d7043-b15f-4de1-8789-e11e296b59cf",
                "quantity": "40000",
                "source": "bank-uk:101:a4bba07f-8592-4caa-9803-7a3c5370a6a7",
                "timestamp": 1702203548,
                "type": "receipt"
            }
        },
        {
            "instructionSequenceNumber": 2,
            "output": {
                "asset": {
                    "code": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
                    "type": "finp2p"
                },
                "destination": "bank-uk:101:a4bba07f-8592-4caa-9803-7a3c5370a6a7",
                "details": {
                    "destinationFinId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                    "sourceFinId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9",
                    "transactionDetails": {
                        "transactionId": ""
                    },
                    "type": "asset"
                },
                "id": "d905a7f2-2884-4a20-b13e-a967c73133cb",
                "quantity": "10000",
                "source": "bank-uk:101:f2ee5840-8b7d-47ae-a4dc-ee9d02b0cee8",
                "timestamp": 1702203549291795598,
                "type": "receipt"
            }
        },
        {
            "instructionSequenceNumber": 3,
            "output": {
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                },
                "destination": "bank-uk:101:f2ee5840-8b7d-47ae-a4dc-ee9d02b0cee8",
                "details": {
                    "destination": {
                        "account": {
                            "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "asset": {
                            "code": "USD",
                            "type": "fiat"
                        }
                    },
                    "source": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "asset": {
                            "code": "USD",
                            "type": "fiat"
                        }
                    },
                    "transactionDetails": {
                        "transactionId": ""
                    },
                    "type": "payment"
                },
                "id": "717a57ad-5b1c-49e2-add4-d755b0007607",
                "quantity": "40000.00",
                "source": "bank-uk:101:a4bba07f-8592-4caa-9803-7a3c5370a6a7",
                "timestamp": 1702203549,
                "type": "receipt"
            }
        }
    ],
    "plan": {
        "id": "bank-uk:106:aa0ab7c6-3193-44c5-9760-c9e1e048e2a0",
        "instructions": [
            {
                "executionPlanOperation": {
                    "amount": "40000",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    },
                    "destination": {
                        "account": {
                            "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9"
                    },
                    "signature": {
                        "signature": "5d8133c5f1606567a17c5eb7348f36367b1c0d2952400cac30471f910a4adb2b02a601dcf4f487ab83596e129dbbd7d255d23f0a307ff7cf4a7ae4435e0f809d",
                        "template": {
                            "hash": "23e6175c15079d49297e83ac158aaefbfce5bc2e93ef3c5851c41b8b3ae3be1e",
                            "hashGroups": [
                                {
                                    "fields": [
                                        {
                                            "name": "nonce",
                                            "type": "bytes",
                                            "value": "87814a2ae40056b7dd79c3e9153afcdcfd36861d22a19efc000000006575907c"
                                        },
                                        {
                                            "name": "operation",
                                            "type": "string",
                                            "value": "transfer"
                                        },
                                        {
                                            "name": "assetType",
                                            "type": "string",
                                            "value": "finp2p"
                                        },
                                        {
                                            "name": "assetId",
                                            "type": "string",
                                            "value": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0"
                                        },
                                        {
                                            "name": "srcAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "srcAccount",
                                            "type": "string",
                                            "value": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9"
                                        },
                                        {
                                            "name": "dstAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "dstAccount",
                                            "type": "string",
                                            "value": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                                        },
                                        {
                                            "name": "amount",
                                            "type": "string",
                                            "value": "10000"
                                        }
                                    ],
                                    "hash": "137e563765af47eadcf484384f197267a7fb8a70891668f7cbf339e78450c52c"
                                },
                                {
                                    "fields": [
                                        {
                                            "name": "assetType",
                                            "type": "string",
                                            "value": "fiat"
                                        },
                                        {
                                            "name": "assetId",
                                            "type": "string",
                                            "value": "USD"
                                        },
                                        {
                                            "name": "srcAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "srcAccount",
                                            "type": "string",
                                            "value": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                                        },
                                        {
                                            "name": "dstAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "dstAccount",
                                            "type": "string",
                                            "value": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9"
                                        },
                                        {
                                            "name": "amount",
                                            "type": "string",
                                            "value": "40000"
                                        },
                                        {
                                            "name": "expiry",
                                            "type": "string",
                                            "value": "500"
                                        }
                                    ],
                                    "hash": "f3d79b4a0f8d439b841251ee92f3b09bf98b9ef7da475b0b0de786599c04a3b6"
                                }
                            ]
                        }
                    },
                    "source": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "ownera-escrow",
                            "type": "finId"
                        },
                        "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                    },
                    "type": "hold"
                },
                "organizations": [
                    "payements-service"
                ],
                "sequence": 1
            },
            {
                "executionPlanOperation": {
                    "amount": "10000",
                    "asset": {
                        "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
                        "type": "finp2p"
                    },
                    "destination": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "bank-uk",
                            "type": "finId"
                        },
                        "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                    },
                    "signature": {
                        "signature": "",
                        "template": {
                            "hash": "23e6175c15079d49297e83ac158aaefbfce5bc2e93ef3c5851c41b8b3ae3be1e",
                            "hashGroups": [
                                {
                                    "fields": [
                                        {
                                            "name": "nonce",
                                            "type": "bytes",
                                            "value": "87814a2ae40056b7dd79c3e9153afcdcfd36861d22a19efc000000006575907c"
                                        },
                                        {
                                            "name": "operation",
                                            "type": "string",
                                            "value": "transfer"
                                        },
                                        {
                                            "name": "assetType",
                                            "type": "string",
                                            "value": "finp2p"
                                        },
                                        {
                                            "name": "assetId",
                                            "type": "string",
                                            "value": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0"
                                        },
                                        {
                                            "name": "srcAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "srcAccount",
                                            "type": "string",
                                            "value": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9"
                                        },
                                        {
                                            "name": "dstAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "dstAccount",
                                            "type": "string",
                                            "value": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                                        },
                                        {
                                            "name": "amount",
                                            "type": "string",
                                            "value": "10000"
                                        }
                                    ],
                                    "hash": "137e563765af47eadcf484384f197267a7fb8a70891668f7cbf339e78450c52c"
                                },
                                {
                                    "fields": [
                                        {
                                            "name": "assetType",
                                            "type": "string",
                                            "value": "fiat"
                                        },
                                        {
                                            "name": "assetId",
                                            "type": "string",
                                            "value": "USD"
                                        },
                                        {
                                            "name": "srcAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "srcAccount",
                                            "type": "string",
                                            "value": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                                        },
                                        {
                                            "name": "dstAccountType",
                                            "type": "string",
                                            "value": "finId"
                                        },
                                        {
                                            "name": "dstAccount",
                                            "type": "string",
                                            "value": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9"
                                        },
                                        {
                                            "name": "amount",
                                            "type": "string",
                                            "value": "40000"
                                        },
                                        {
                                            "name": "expiry",
                                            "type": "string",
                                            "value": "500"
                                        }
                                    ],
                                    "hash": "f3d79b4a0f8d439b841251ee92f3b09bf98b9ef7da475b0b0de786599c04a3b6"
                                }
                            ]
                        }
                    },
                    "source": {
                        "account": {
                            "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9",
                            "orgId": "bank-uk",
                            "type": "finId"
                        },
                        "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9"
                    },
                    "type": "transfer"
                },
                "organizations": [
                    "bank-uk"
                ],
                "sequence": 2
            },
            {
                "executionPlanOperation": {
                    "amount": "40000",
                    "asset": {
                        "code": "USD",
                        "type": "fiat"
                    },
                    "destination": {
                        "account": {
                            "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9"
                    },
                    "source": {
                        "account": {
                            "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
                            "orgId": "payements-service",
                            "type": "finId"
                        },
                        "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
                    },
                    "type": "release"
                },
                "organizations": [
                    "ownera-escrow"
                ],
                "sequence": 3
            }
        ],
        "intent": {
            "assetInstruction": {
                "account": {
                    "account": {
                        "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9",
                        "orgId": "bank-uk",
                        "type": "finId"
                    },
                    "asset": {
                        "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
                        "type": "finp2p"
                    }
                }
            },
            "assetTerm": {
                "amount": "10000",
                "asset": {
                    "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
                    "type": "finp2p"
                }
            },
            "end": 1702229541,
            "intent": {
                "seller": "bank-uk:101:f2ee5840-8b7d-47ae-a4dc-ee9d02b0cee8",
                "settlementInstruction": {
                    "destinationAccounts": [
                        {
                            "account": {
                                "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9",
                                "orgId": "ownera-escrow",
                                "type": "finId"
                            },
                            "asset": {
                                "code": "USD",
                                "type": "fiat"
                            }
                        }
                    ],
                    "type": "escrow"
                },
                "signaturePolicy": {
                    "endpoint": "https://bank-uk-api.app.dev1.ownera.io/custody/signature/callback",
                    "secret": "",
                    "type": "manualPolicy"
                },
                "type": "sellingIntent"
            },
            "settlementTerm": {
                "asset": {
                    "code": "USD",
                    "type": "fiat"
                },
                "unitValue": "4"
            },
            "start": 1701624741
        },
        "participants": [
            {
                "organizationId": "bank-uk",
                "roles": [
                    "contributor"
                ]
            },
            {
                "organizationId": "payements-service",
                "roles": [
                    "contributor"
                ]
            }
        ]
    }
}

Process request for status of execution plan approval if you chose to handle approval asynchronously

curl --location 'http://<router url>/operations/status/12321321' \
--header 'Content-Type: application/json' \
--data ''
{
  "cid": "12321321",
  "isCompleted": true,
  "approval": {
    "status": "approved"
  }
}
{
  "cid": "12321321",
  "isCompleted": true,
  "approval": {
     "status": "rejected",
  "failure": {
    "failureType": "validationFailure",
    "code": 1001,
    "message": "Invalid input data provided"
  }
  }
}

Receive a message and respond back to secondary execution request for a transfer of tokens

The message contains a reference to the execution plan you received. Respond to the process as indicated in order to process this request in an asynchronous manner. The cid you will return will be used next in the operational status polling to receive the progress and completion on processing of the transfer request.

curl --location --request POST 'http://<adapter_url>/assets/transfer' \
--header 'Content-Type: application/json' \
--data-raw '
	{
  "nonce": "08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d",
  "asset": {
    "resourceId": "bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835",
    "type": "finp2p"
  },
  "source": {
    "account": {
      "finId": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3",
      "type": "finId"
    },
    "finId": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3"
  },
  "destination": {
    "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c",
    "account": {
      "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c",
      "type": "finId"
    }
  },
  "quantity": "10000",
  "settlementRef": "82e8a507-5939-8369-6163-f70d071e67f1",
  "signature": {
    "signature": "4161063d6353d991b5ff58c666fc5c5fa3b8a56863639eef7f19fc5e6e4d61747d3dcd5aed9d9a1978f5bc0486086e8798ffa8d3613c1367e112e8649a831856",
    "template": {
      "hash": "2433e6287831821d342c1b744495982ef579d41dc5af629c8f3fcaa1e4cb071f",
      "hashGroups": [
        {
          "fields": [
            {
              "name": "nonce",
              "type": "bytes",
              "value": "08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d"
            },
            {
              "name": "operation",
              "type": "string",
              "value": "transfer"
            },
            {
              "name": "assetType",
              "type": "string",
              "value": "finp2p"
            },
            {
              "name": "assetId",
              "type": "string",
              "value": "bank-il:102:d6b2d0fa-8876-48ec-930f-de364b697f6d"
            },
            {
              "name": "srcAccountType",
              "type": "string",
              "value": "finId"
            },
            {
              "name": "srcAccount",
              "type": "string",
              "value": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3"
            },
            {
              "name": "dstAccountType",
              "type": "string",
              "value": "finId"
            },
            {
              "name": "dstAccount",
              "type": "string",
              "value": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c"
            },
            {
              "name": "amount",
              "type": "string",
              "value": "5"
            }
          ],
          "hash": "55cb7e7c12fe68b010e92bcd68eaaa0983c871fd2bf029d4b84af32b059d366c"
        },
        {
          "fields": [
            {
              "name": "assetType",
              "type": "string",
              "value": "fiat"
            },
            {
              "name": "assetId",
              "type": "string",
              "value": "USD"
            },
            {
              "name": "srcAccountType",
              "type": "string",
              "value": "finId"
            },
            {
              "name": "srcAccount",
              "type": "string",
              "value": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c"
            },
            {
              "name": "dstAccountType",
              "type": "string",
              "value": "finId"
            },
            {
              "name": "dstAccount",
              "type": "string",
              "value": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3"
            },
            {
              "name": "amount",
              "type": "string",
              "value": "10"
            }
          ],
          "hash": "85fe087c5915b6ba1a9fca230c752d78095e633c22195591de0944338765c6eb"
        }
      ]
    }
  },
  "executionContext": {
    "executionPlanId": "execution/bank-uk:106:aa0ab7c6-3193-44c5-9760-c9e1e048e2a0",
    "instructionSequenceNumber": 2
  }
}'
{
    "cid": "08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d",
    "isCompleted": false,    
    "response": {              
    }
}

Process polling request to check on status of execution

curl --location --request POST 'http://<adapter_url>/operations/08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d' \
--header 'Content-Type: application/json' \
--data-raw '
{
}'
{
    "cid": "08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d",
    "isCompleted": false,    
    "response": {              
    }
}
{
  "type": "receipt",
  "operation": {
    "cid": "08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d",
    "isCompleted": true,
    "response": {
      "asset": {
        "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
        "type": "finp2p"
      },
      "destination": {
        "account": {
          "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
          "type": "finId"
        },
        "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
      },
      "id": "f86ea694-2638-4b8d-a407-bfe03217e07a",
      "quantity": "5",
      "settlementRef": "82e8a507-5939-8369-6163-f70d071e67f1",
      "source": {
        "account": {
          "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9",
          "type": "finId"
        },
        "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9"
      },
      "timestamp": 1702203549
    }
  }
}
{
  "type": "receipt",
  "operation": {
    "cid": "08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d",
    "isCompleted": true,
    "error": {
      "Code": 15,
      "Message": "Transfer failed"
    }
  }
}

Process request for the balance of a given asset

curl --location --request GET 'http://<adapter_url>/assets/getBalance' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "owner": {
    "account": {
      "type": "finId",
      "finId": "02d6fea8153a9a64d13e198379dfd4ea3945d03198770e0e5b94f556c4e69f6835"
    }
  },
  "asset": {
    "type": "finp2p",
    "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0"
  }
}'

{
  "asset": {
    "type": "finp2p",
    "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0"
  },
  "balance": "100000"
}

Process request for a receipt of a previously performed transaction

Firstly The get receipt will be sent, in which you can response with with acknowledgement and process the request asynchronously.

curl --location --request GET 'http://<adapter_url>/assets/getReceipt/73358f79-3b3a-4080-90c3-cbb7edd26668' \
--header 'Content-Type: application/json' \
--data-raw ''

{
    "cid": "08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d",
    "isCompleted": false,    
    "response": {              
    }
}

And the response to the get status operation to provide receipt.

curl --location --request POST 'http://<adapter_url>/operations/08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d' \
--header 'Content-Type: application/json' \
--data-raw '
{
}'
{
  "cid": "08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d",
  "isCompleted": true,
  "response": {
    "asset": {
      "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
      "type": "finp2p"
    },
    "quantity": "100000",
    "timestamp": 1702203549,
    "source": {
      "account": {
        "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9",
        "type": "finId"
      },
      "finId": "037fcf0db48dceb2195bd0fc24a4dab68c5731b5b8c141f63d017969a55570c4e9"
    },
    "destination": {
      "account": {
        "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5",
        "type": "finId"
      },
      "finId": "02af7088141665f96ce1eb3db1bb2b45af58a8b3a09ee0dd64ee921e1b197fe2d5"
    },
    "id": "f86ea694-2638-4b8d-a407-bfe03217e07a",
    "settlementRef": "82e8a507-5939-8369-6163-f70d071e67f1",
    "transactionDetails": {
      "transactionId": "73358f79-3b3a-4080-90c3-cbb7edd26668"
    }
  }
}

Example: Importing Transactions Manually

The following allows you to send manual updates to Ownera for the case adjustments need to be performed on the user token holdings for the given asset.

The "source" section should be used to take out of the given account the specified amount. The "destination" section should be used to put into the given account the specified amount. Meaning, it incrementally increase or decreases the balance of the quantity specified.

curl --location --request POST 'http://<router_url>finp2p/ledger/transaction/import' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transactions": [
        {
            "id": "fa5e7391-fce9-4cf6-98e4-b53cdf38d79d",
            "asset": {
                "type": "finp2p",
                "resourceId": "bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835"
            },
            "quantity": "10000",
            "timestamp": 1673863664,
            "destination": {
                "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c",
                "account": {
                    "type": "finId",
                    "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c",
                    "orgId": "bank-uk"
                }
            },
            "settlementRef": "d9ea365e-56c8-43df-9674-c7132ee1c197",
            "transactionDetails": {
                "transactionId": "73358f79-3b3a-4080-90c3-cbb7edd26668"
            }
        }
    ]
}'
curl --location --request POST 'http://<router_url>finp2p/ledger/transaction/import' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transactions": [
        {
            "id": "fa5e7391-fce9-4cf6-98e4-b53cdf38d79d",
            "asset": {
                "type": "finp2p",
                "resourceId": "bank-us:102:4b2fc630-bc23-4337-be44-97f12875f835"
            },
            "quantity": "10000",
            "timestamp": 1673863664,
            "source": {
                "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c",
                "account": {
                    "type": "finId",
                    "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c",
                    "orgId": "bank-uk"
                }
            },
            "settlementRef": "d9ea365e-56c8-43df-9674-c7132ee1c197",
            "transactionDetails": {
                "transactionId": "73358f79-3b3a-4080-90c3-cbb7edd26668"
            }
        }
    ]
}'

Execution Plan Details

**Execution Plan**

FieldSub-FieldDescription
idExecution plan unique ID
intentIDThe intent ID in which was created by the trading platform processing the intent request.
instructionsThis section will have repeating sections with each describing the step and the details to perform the execution.
sequence The step in the execution plan, starting from 1.
typeThe operation being performed at the given instruction sequence number, as follows:
1The step in the execution plan which requests the hold of the funds for the transaction.
2The step in the execution plan which requests the issuance or transfer of the asset tokens.
3The step in the execution plan which requests the release of the funds to the issuer or seller.
OrganizationsSpecifies the organization(s) ID that are involved in performing the step in the execution plan.
ParticipantsThis part of the message will outline all the participants that are involved in the execution plan split into two roles:

Contributor - the participants respond to requests and perform actions.

Observers - the participants “listens” to execution plan progression (and can display progress to the end-user).
creationTimeStampThe time the execution plan was submitted, in epoch format.
currentInstructionSequenceProvides you with the current sequence number being waited on or executed.
executionPlanStatusProvides you with the overall status of the execution plan, which can be one of the following values:

Pending - pending start of execution plan or pending the specific sequence number in which the plan is at.
Approved - Plan is approved
Completed - Plan is fully successfully executed
Failed - Plan has failed in execution
Rejected - Plan was rejected by a given participant