Use Case 3: Payment Hub Services

Overview

This Payment Hub walkthrough shows how to connect your payments platform to the Ownera router via the FinP2P API, enabling settlement and payment processing across the FinP2P network. The steps are as follows:

  1. Providing deposit instructions which are requests by an investor, which in turn will be used to deposit the funds into the settlement account.
  2. Facilitating the payments leg in a DvP (Delivery vs. Payment) process.
  3. Allow for cash withdrawal (payout) of funds from escrow account.

API Integration Flow

The following table will walk you through the step-by-step payment integration involved in providing payment services:

API Reference

Description

Provide Deposit Instructions

1

Process Deposit Request Instructions

Receive an owner request for deposit instruction and in turn provide deposit instruction details for the owner.

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 (get status) your side for completion.

2

Provide Request Status

Implement the get operation ability in order to allow to query for the status of the execution request sent to you.

Process Execution

3

Receive Notification and Approve New Execution Plan

You will receive an execution plan notification which will be an indication that a new request for a trade was submitted in which your organization is participating as the payments leg.

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.

4

Review Execution Plan

Poll the plan to review and asset your participation in the execution plan.

Refer to the execution plan explanation. Execution Plan

5

Process 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.

6

Hold Funds

Upon an execution request, you will receive a request to put the funds of the buyer on hold while the trade DvP process is being processed.

7

Release Funds

Once the trade completes, release the funds which will be transferred from the buyer to the seller account.

8

Rollback Funds

In the case the transaction fails, you will receive an instruction to rollback the funds that were held and release it back to the buyer

9

Transfer Funds

In the case the execution plan calls for the holding of the asset (and not the funds), the fund transfer will be used to send the money from the buy to the seller.

Process Payout Request

10

Process Payout Request

Process request to withdrawal the given funds from the escrow account of the given owner.

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 (get status) your side for completion.

11

Provide Request Status

Implement the get operation ability in order to allow to query for the status of the execution request sent to you.

Other Operations

12

Import Transaction

Use this in order to adjust fund holdings balance for the given user.

13

Provide Receipts

Allow to request receipt details from your ledger.

14

Provide Ledger Asset Balance

Allow to request the funds balance for the given owner.

Testing Your Integration

You can test your payments service integration by requesting from Ownera a investor/tokenization sandbox which will provide you with a test Investor App and a tokenization simulation in order to initiate trades.

Example: Deposit, Payment Processing, and Payout

The following is an example walkthrough for processing deposit instruction request, processing payment, and facilitating payout request.

Deposit Instruction

The escrow payments adapter will receive this message as a result of an investor requesting deposit instructions.

curl --location --request POST 'http://<adatper_url>/payments/depositInstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
  "asset": {
    "code": "USD",
    "type": "fiat"
  },
  "destination": {
    "account": {
      "type": "finId",
      "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
      "orgId": "payment-service"
    },
    "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
  },
  "owner": {
    "account": {
      "type": "finId",
      "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
    },
    "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
  },
  "amount": "10000",
  "details": "deposit insructions",
  "nonce": "9428f58efed898947660dc01e72a3c8101588a3fd49e8a6600000000649d56bf",
  "signature": {
    "signature": "3ac8de15c35de470a403e9e59629e5068c8c55046cd76611c28c5e0cc76aa45911f468973e041ff455e67dedca7e33de1bb3cc0872498773bbfb5de355cae1ab",
    "template": {
      "hashGroups": [
        {
          "hash": "string",
          "fields": [
            {
              "name": "string",
              "type": "string",
              "value": "string"
            }
          ]
        }
      ],
      "hash": "string"
    }
  }
}'
{
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": false,    
    "response": {              
    }
}

Process polling request to check on status of deposit instruction processing

curl --location --request POST 'http://<adapter_url>/operations/6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9' \
--header 'Content-Type: application/json' \
--data-raw '
{
}'
{
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": true,
    "response": {
        "account": {
            "account": {
                "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
                "type": "finId"
            },
            "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
        },
        "description": "Bank Adress|<Bank Address>|Beneficiary Name|<Beneficiary>|Bank Name|<Bank Name>|Account number|<Account Number>|Account type|<Custodial>|Routing number|<Routing Number>|Bic Swift Code|<BIC Swift Code>|Reference number|<Reference Number>"
    }
}

Receive a notification message which indicates of a new execution plan submission for a trade request in which your organization participates in the payment leg of the transaction. 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"
  }
  }
}

Hold the funds

Hold the funds for the given investor (buyer) to process the DvP. Once the hold is processed successfully, a request to transfer the asset will be sent. The response of false indicates that the adapter will be polled in an asynchronous process to get hold operation status. The payload will contain the execution plan id and sequence # for the steps being performed as outlined in the execution plan details.

curl --location --request POST 'http://<adapter url>/assets/hold' \
--header 'Content-Type: application/json' \
--data-raw '{
  "asset": {
    "code": "USD",
    "type": "fiat"
  },
  "source": {
    "account": {
      "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
      "type": "finId"
    },
    "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
  },
  "expiry": 500,
  "nonce": "657f704e2a862d8f0784e5612569313284698429fde7d0150000000063c535e6",
  "operationId": "f5cd25ae-1cdc-9ff3-199d-7637d29e1149",
  "quantity": "10000",
  "signature": {
    "signature": "f675cf2869f805490db3625dd53329f8c7257fb082d43f040498afdb5067adc0413eaa0c6ebcc8f8b48d1d93b77762a8697c6e47e716d0bc9f61e2ffacbb764d",
    "template": {
      "hash": "621edc6c9da7e061115902e7b8a137e8e78d1baeb019eb58fc28f73bc0acaaea",
      "hashGroups": [
        {
          "fields": [
            {
              "name": "nonce",
              "type": "bytes",
              "value": "657f704e2a862d8f0784e5612569313284698429fde7d0150000000063c535e6"
            },
            {
              "name": "operation",
              "type": "string",
              "value": "issue"
            },
            {
              "name": "assetType",
              "type": "string",
              "value": "finp2p"
            },
            {
              "name": "assetId",
              "type": "string",
              "value": "bank-us:102:0cfdcca8-0208-4923-be52-8d98f9e578c6"
            },
            {
              "name": "dstAccountType",
              "type": "string",
              "value": "finId"
            },
            {
              "name": "dstAccount",
              "type": "string",
              "value": "0351bd56def63039c4c6e196718841c1a619c104c50a8e3912aaf542a7aa60f1d9"
            },
            {
              "name": "amount",
              "type": "string",
              "value": "2"
            }
          ],
          "hash": "f74757568ef27b22c1560129a18041332a5a9838646797aed0c1b8a55c1f68da"
        },
        {
          "fields": [
            {
              "name": "assetType",
              "type": "string",
              "value": "fiat"
            },
            {
              "name": "assetId",
              "type": "string",
              "value": "USD"
            },
            {
              "name": "srcAccountType",
              "type": "string",
              "value": "finId"
            },
            {
              "name": "srcAccount",
              "type": "string",
              "value": "0351bd56def63039c4c6e196718841c1a619c104c50a8e3912aaf542a7aa60f1d9"
            },
            {
              "name": "dstAccountType",
              "type": "string",
              "value": "finId"
            },
            {
              "name": "dstAccount",
              "type": "string",
              "value": "0312ac0f073f996f4d78103db03f238273c6411d277150457f3c647244b2ab0250"
            },
            {
              "name": "amount",
              "type": "string",
              "value": "200"
            },
            {
              "name": "expiry",
              "type": "string",
              "value": "201"
            }
          ],
          "hash": "f38336d03cf895a6a9d2ad4bb0f48518704efed81e3674fed4f9d85058f2da48"
        }
      ]
    }
  },
  "executionContext": {
    "executionPlanId": "bank-uk:106:9909e355-df0e-4708-8121-cec192089418",
    "instructionSequenceNumber": 1
  }
}'
{
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": false,
    "response": {
    }
}

Process polling request to check on status of hold operation

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,
    "response": {
  }
}
{
  "type": "receipt",
  "operation": {
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": true,
    "error": {
      "Code": 11,
      "Message": "Hold operation failed"
    }
  }
}

Release Funds

Once the DvP process is completed and asset has ben transferred to buyer, release the fund to the seller.

The payload will contain the execution plan id and sequence # for the steps being performed as outlined in the execution plan details.

curl --location --request POST 'http://<adapter_url>/assets/hold' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "asset": {
    "code": "USD",
    "type": "fiat"
  },
  "destination": {
    "account": {
      "finId": "039385bc4760bb0df502475d66e622b6b4938cb14e43721a4c76221254c140f960",
      "type": "finId"
    },
    "finId": "039385bc4760bb0df502475d66e622b6b4938cb14e43721a4c76221254c140f960"
  },
  "operationId": "1dd84799-220c-885e-ccc6-2cadcf2e4bda",
  "quantity": "10000",
  "source": {
    "account": {
      "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
      "type": "finId"
    },
    "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
  },
  "executionContext": {
    "executionPlanId": "bank-uk:106:9909e355-df0e-4708-8121-cec192089418",
    "instructionSequenceNumber": 3
  }
}'
{
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": false,
    "response": {
    }
}

Process polling request to check on status of release operation

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,
    "response": {
      "asset": {
        "code": "USD",
        "type": "fiat"
      },
      "destination": {
        "account": {
          "finId": "039385bc4760bb0df502475d66e622b6b4938cb14e43721a4c76221254c140f960",
          "type": "finId"
        },
        "finId": "039385bc4760bb0df502475d66e622b6b4938cb14e43721a4c76221254c140f960"
      },
      "id": "a1a1d94f-ceb0-40d8-a788-288b519d3d63",
      "quantity": "2",
      "settlementRef": "",
      "source": {
        "account": {
          "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
          "type": "finId"
        },
        "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
      },
      "timestamp": 1677499658
    }
  }
}
{
  "type": "receipt",
  "operation": {
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": true,
    "error": {
      "Code": 12,
      "Message": "Release operation failed"
    }
  }
}

Rollback Held Funds

In the case when a transaction has failed, this will be used to undo the hold of the asset (funds) for the investor (buyer).

The payload will contain the execution plan id and sequence # for the steps being performed as outlined in the execution plan details.

curl --location --request POST 'http://<adapter url>/assets/rollback' \
--header 'Content-Type: application/json' \
--data-raw '
{
  "asset": {
    "code": "USD",
    "type": "fiat"
  },
  "operationId": "f5cd25ae-1cdc-9ff3-199d-7637d29e1149",
  "quantity": "10000",
  "source": {
    "account": {
      "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
      "type": "finId"
    },
    "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
  },
  "executionContext": {
    "executionPlanId": "bank-uk:106:9909e355-df0e-4708-8121-cec192089418",
    "instructionSequenceNumber": 1
  }
}'
{
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": false,
    "response": {
    }
}

Process polling request to check on status of release operation

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,
    "response": {
      "asset": {
        "code": "USD",
        "type": "fiat"
      },
      "id": "b6bb6e8b-3b37-4152-8984-c1b6fc0f1b1e",
      "quantity": "10000",
      "settlementRef": "f5cd25ae-1cdc-9ff3-199d-7637d29e1149",
      "timestamp": 1673886030
    }
  }
}
{
  "type": "receipt",
  "operation": {
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": true,
    "error": {
      "Code": 13,
      "Message": "Rollback operation failed"
    }
  }
}

Transfer funds

This call will be made to transfer the funds for the given transaction from the buyer to the seller, which occurs following the holding of the asset for an execution plan that calls to hold the asset and transfer the funds. The response of false indicates that the adapter will be polled in an asynchronous process to get transfer operation status. The payload will contain the execution plan id and sequence # for the steps being performed as outlined in the execution plan details.

curl --location --request POST 'http://<adapter_url>/assets/transfer' \
--header 'Content-Type: application/json' \
--data-raw '
	{
  "nonce": "08d53ff8f3aa9ec71476002facf319b567ddfbd80ab7c1d50000000063d7e00d",
  "asset": {
    "code": "USD",
    "type": "fiat"
  },
  "source": {
    "account": {
      "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c",
      "type": "finId"
    },
    "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c"
  },
  "destination": {
    "finId": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3",
    "account": {
      "finId": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3",
      "type": "finId"
    }
  },
  "quantity": "1000000",
  "transactionDetails": {
	  	"transactionId": "73358f79-3b3a-4080-90c3-cbb7edd26668",
    	"operationId": "cbb7edd26668-3b3a-4080-90c3-cbb7edd234668"
  },
  "signature": {
    "signature": "4161063d6353d991b5ff58c666fc5c5fa3b8a56863639eef7f19fc5e6e4d61747d3dcd5aed9d9a1978f5bc0486086e8798ffa8d3613c1367e112e8649a831856",
    "template": {
      "hash": "2433e6287831821d342c1b744495982ef579d41dc5af629c8f3fcaa1e4cb071f",
      "hashGroups": [       
      ]
    }
  },
  "executionContext": {
    "executionPlanId": "execution/bank-uk:106:aa0ab7c6-3193-44c5-9760-c9e1e048e2a0",
    "instructionSequenceNumber": 2
  }
}'
{
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": false,
    "response": {
    }
}

Process polling request to check on status of transfer operation

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,
    "response": {
      "asset": {
        "resourceId": "bank-uk:102:f96240dc-8365-475b-84e2-9611bb5e5bc0",
        "type": "finp2p"
      },
      "source": {
        "account": {
          "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c",
          "type": "finId"
        },
        "finId": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c"
      },
      "destination": {
        "account": {
          "finId": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3",
          "type": "finId"
        },
        "finId": "03c7c9d6b96a678f549c4dd5407eabffc779cf665846846f1a8bb5d5e63cedc8e3"
      },
      "id": "f86ea694-2638-4b8d-a407-bfe03217e07a",
      "quantity": "1000000",
      "timestamp": 1702203549
    }
  }
}
{
  "type": "receipt",
  "operation": {
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": true,
    "error": {
      "Code": 11,
      "Message": "Not enough funds"
    }
  }
}

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": "02ae39c9adaff2485deb65ac3749261089d268874c55ca73c5bd83815154b6ea9c"
    }
  },
  "asset": {
    "type": "fiat",
    "code": "USD"
  }
}'

{
  "asset": {
    "type": "fiat",
    "code": "USD"
  },
  "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": {
      "code": "USD",
      "type": "fiat"
    },
    "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",
  	"transactionDetails": {
	  	"transactionId": "73358f79-3b3a-4080-90c3-cbb7edd26668",
    	"operationId": "cbb7edd26668-3b3a-4080-90c3-cbb7edd234668"
  }
  }
}

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": ""
    }
  }
}

Process payout withdrawal request

You will receive in payoutInstructions the text/object of the details required for your payment organization to process the withdrawal request sent.

curl --location --request POST 'http://<adapter url>/finapi/payments/payout' \
--header 'Content-Type: application/json' \
--data-raw '{
  "asset": {
    "code": "USD",
    "type": "fiat"
  },
  "source": {
    "account": {
      "type": "finId",
      "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
      "orgId": "payment-service"
    },
    "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
  },
  "amount": "10000",
  "payoutInstruction": {
    "description": "withdrawl instructions"
  },
  "nonce": "9428f58efed898947660dc01e72a3c8101588a3fd49e8a6600000000649d56bf",
  "signature": {
    "signature": "3ac8de15c35de470a403e9e59629e5068c8c55046cd76611c28c5e0cc76aa45911f468973e041ff455e67dedca7e33de1bb3cc0872498773bbfb5de355cae1ab",
    "template": {
      "hashGroups": [
        {
          "hash": "string",
          "fields": [
            {
              "name": "string",
              "type": "string",
              "value": "string"
            }
          ]
        }
      ],
      "hash": "string"
    }
  }
}'
{
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": false,
    "response": {
    }
}

Process polling request to check on status of withdrawal operation

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": {
    }
}
TBD
{
  "type": "receipt",
  "operation": {
    "cid": "6661b36bbc7ee21b182bd909f1e0cb14c40a8d9dd80badee0000000063db7cf9",
    "isCompleted": true,
    "error": {
      "Code": 22,
      "Message": "Withdrawal operation failed"
    }
  }
}

Example: Adjusting Balances Manually

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

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>/ledger/transaction/import' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transactions": [
        {
            "id": "fa5e7391-fce9-4cf6-98e4-b53cdf38d79d",
            "asset": {
                "type": "fiat",
                "code": "USD"
            },
            "quantity": "10000",
            "timestamp": 1673863664,
            "destination": {
                "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
                "account": {
                    "type": "finId",
                    "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
                    "orgId": "payment-service"
                }
            },
            "settlementRef": "d9ea365e-56c8-43df-9674-c7132ee1c197",
            "transactionDetails": {
                "transactionId": "73358f79-3b3a-4080-90c3-cbb7edd26668"
            }
        }
    ]
}'
curl --location --request POST 'http://<router url>/ledger/transaction/import' \
--header 'Content-Type: application/json' \
--data-raw '{
    "transactions": [
        {
            "id": "2e9e41ab-43ac-43c6-9952-e06da35417c2",
            "asset": {
                "type": "fiat",
                "code": "USD"
            },
            "quantity": "10000",
            "timestamp": 1673863664,
            "source": {
                "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
                "account": {
                    "type": "finId",
                    "finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
                    "orgId": "payment-service"
                }
            },
            "settlementRef": "d9cff0f0-1d8d-4d6f-a0ba-b9a5ccdccef8",
            "transactionDetails": {
                "transactionId": "931dd475-9442-46b8-b1b8-8a0e5e937985"
            }
        }
    ]
}'

Execution Plan Details

Execution Plan

Field

Sub-Field

Description

id

Execution plan unique ID

intentID

The intent ID in which was created by the trading platform processing the intent request.

instructions

This 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.

type

The operation being performed at the given instruction sequence number, as follows:

1

The step in the execution plan which requests the hold of the funds for the transaction.

2

The step in the execution plan which requests the issuance or transfer of the asset tokens.

3

The step in the execution plan which requests the release of the funds to the issuer or seller.

Organizations

Specifies the organization(s) ID that are involved in performing the step in the execution plan.

Participants

This 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).

creationTimeStamp

The time the execution plan was submitted, in epoch format.

currentInstructionSequence

Provides you with the current sequence number being waited on or executed.

executionPlanStatus

Provides 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