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:
- Providing deposit instructions which are requests by an investor, which in turn will be used to deposit the funds into the settlement account.
- Facilitating the payments leg in a DvP (Delivery vs. Payment) process.
- 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 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 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:
- Token Exchange Confirmation
- 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 |
Updated 12 months ago