Use Case 3: Providing Payment Services

Overview

The following is a walkthrough for integrating into the FinP2P API for the purpose of performing payment processing. The steps involve:

  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 sell-side integration involved in providing payment services:

# API ReferenceDescription

Provide Deposit Instructions
1Process Deposit Request InstructionsReceive 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.
2Provide Request StatusImplement the get operation ability in order to allow to query for the status of the execution request sent to you.

Process Execution
3Receive Notification and Approve New Execution PlanYou 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.
4Review Execution PlanPoll the plan to review and asset your participation in the execution plan.

Refer to the execution plan explanation.
Execution Plan
5Process 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.
6Hold FundsUpon 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.
7Release FundsOnce the trade completes, release the funds which will be transferred from the buyer to the seller account.
8Rollback FundsIn the case the transaction fails, you will receive an instruction to rollback the funds that were held and release it back to the buyer
9Transfer FundsIn 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
10Process Payout RequestProcess 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.
11Provide Request StatusImplement the get operation ability in order to allow to query for the status of the execution request sent to you.

Other Operations
12Import TransactionUse this in order to adjust fund holdings balance for the given user.
13Provide Receipts Allow to request receipt details from your ledger.
14Provide 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 buy-side/sell-side 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**

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