Use Case 3: Providing Payment Escrow Services
API Integration Flow
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 owner, which in turn will be used to deposit the funds into the escrow account.
- Facilitating a DvP (Delivery vs. Payment) escrow process for executions performed between buyers and sellers, given you are assigned at the payment escrow service that facilitates the trade.
- Allow for cash withdrawal (payout) of funds from escrow account.
| # | Action | Description | API Reference | |||
|---|---|---|---|---|---|---|
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. | https://finp2p-docs.ownera.io/reference/depositinstruction | |||
| 2 | Allow for ability to request the status for the transaction | Implement the get operation ability in order to allow to query for the status of the execution request sent to you. | https://finp2p-docs.ownera.io/reference/getoperation-1 | |||
| 3 | Allow for ability to request the status for the request. | Implement the get operation ability in order to allow to query for the status of the execution request sent to you. | https://finp2p-docs.ownera.io/reference/getoperation-1 | |||
Process Execution | ||||||
| 4 | Hold Asset | Upon an execution request, you will receive a request to put the asset (e.g., the funding/payment account) of the buyer while the transaction is being performed (e.g., token is transferred from seller to buyer). | https://finp2p-docs.ownera.io/reference/holdoperation | |||
| 5 | Release Asset | Once the transaction (e.g., the exchange) is completed, you will be instructed to release the asset (e.g., the fund) to the seller. | [https://finp2p-docs.ownera.io/reference/releaseoperation (https://finp2p-docs.ownera.io/reference/releaseoperation) | |||
| 6 | Rollback Held Asset | In the case the transaction fails, you will receive an instruction to rollback the asset that was held and release it back to the buyer (e.g., the held funds). | https://finp2p-docs.ownera.io/reference/rollbackoperation | |||
Process Payout Request | ||||||
| 7 | 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. | https://finp2p-docs.ownera.io/reference/payout | |||
| 8 | Allow for ability to request the status for the transaction | Implement the get operation ability in order to allow to query for the status of the execution request sent to you. | https://finp2p-docs.ownera.io/reference/getoperation-1 | |||
Adjust Balance | ||||||
| 9 | Import a transaction | Use this in order to adjust holdings balance for the given user. | https://finp2p-docs.ownera.io/reference/import-transactions | |||
Using the Ownera App for Testing
You can use the Ownera App to simulate buyers and sellers on the Ownera Network in order to:
● Receive deposit instructions
● Receive execution requests (e.g., primary and secondary intent executions) in order to invoke the escrow payment process
● Receive payout requests
Please refer to the section "Using the Ownera App for Testing" in both Use Case 1 and Use Case 2 in order to simulate the end to end process for both the buyer and the seller.
Example: Deposit, Payment Processing, and Payout
The following is an example walkthrough for processing deposit instruction request, processing payment, and facilitating payout request.
| Parameter | Description | Value |
|---|---|---|
| Buyer Fin ID | The Fin ID of the investor (buyer) that is depositing funds and in turn buying an asset. | 02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632 |
| Seller Fin ID | The Fin ID of the asset owner (seller) which will have the funds deposited after a successful completion of the asset transfer (either primary or secondary transaction). | 039385bc4760bb0df502475d66e622b6b4938cb14e43721a4c76221254c140f960 |
Deposit Instruction
The escrow payments adapter will receive this message as a result of an investor requesting deposit instructions.
curl --location --request POST 'http://localhost:55014/payments/depositInstruction' \
--header 'Content-Type: application/json' \
--data-raw '{
"asset": {
"code": "USD",
"type": "fiat"
},
"destination": {
"account": {
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"type": "finId"
},
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
},
"owner": {
"account": {
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"type": "finId"
},
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
}
}'
{
"cid": "12345",
"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>"
}
}
{
"cid": "12345",
"isCompleted": false,
"response": {
}
}
Get status on Deposit Request
curl --location --request GET 'http://localhost:62532/operations/status/12345'
{
"type": "deposit",
"operation": {
"cid": "12345",
"isCompleted": false,
"response": {}
}
}
{
"type": "deposit",
"operation": {
"cid": "12345",
"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>"
}
}
}
Hold Asset
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.
curl --location --request POST 'http://localhost:55014/assets/hold' \
--header 'Content-Type: application/json' \
--data-raw '{
"asset": {
"code": "USD",
"type": "fiat"
},
"expiry": 600,
"nonce": "657f704e2a862d8f0784e5612569313284698429fde7d0150000000063c535e6",
"operationId": "f5cd25ae-1cdc-9ff3-199d-7637d29e1149",
"quantity": "2",
"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"
},2
{
"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"
}
]
}
},
"source": {
"account": {
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"type": "finId"
},
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
}
}'
{
"cid": "56789",
"isCompleted": true,
"response": {
"asset": {
"code": "USD",
"type": "fiat"
},
"id": "b6bb6e8b-3b37-4152-8984-c1b6fc0f1b1e",
"quantity": "2",
"timestamp": 1673886030
}
}
{
"cid": "56789",
"isCompleted": false,
"response": {
}
}
Get Hold Status
curl --location --request GET 'http://localhost:62532/operations/status/56789'
{
"type": "receipt",
"operation": {
"cid": "56789",
"isCompleted": false,
"response": {}
}
}
{
"type": "receipt",
"operation": {
"cid": "56789",
"isCompleted": true,
"response": {
}
}
{
"type": "receipt",
"operation": {
"cid": "56789",
"isCompleted": true,
"error": {
"Code": 11,
"Message": "Hold Failed"
}
}
}
Release Asset
Once the DvP process is completed and asset has ben transferred to buyer, release the fund to the seller.
curl --location --request POST 'http://localhost:55014/assets/release' \
--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": "2",
"source": {
"account": {
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"type": "finId"
},
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
}
}'
{
"cid": "12345",
"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
}
}
{
"cid": "12345",
"isCompleted": false,
"response": {
}
}
Get Release Status
curl --location --request GET 'http://localhost:62532/operations/status/98765'
{
"type": "receipt",
"operation": {
"cid": "12345",
"isCompleted": false,
"response": {}
}
}
{
"type": "receipt",
"operation": {
"cid": "12345",
"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": "12345",
"isCompleted": true,
"error": {
"Code": 10,
"Message": "Release Failed"
}
}
}
Rollback Held Asset
In the case when a transaction has failed, this will be used to undo the hold of the asset (funds) for the investor (buyer).
curl --location --request POST 'http://localhost:55014/assets/rollback' \
--header 'Content-Type: application/json' \
--data-raw '
{
"asset": {
"code": "USD",
"type": "fiat"
},
"operationId": "f5cd25ae-1cdc-9ff3-199d-7637d29e1149",
"quantity": "2",
"source": {
"account": {
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"type": "finId"
},
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632"
}
}'
{
"cid": "54321",
"isCompleted": true,
"response": {
"asset": {
"code": "USD",
"type": "fiat"
},
"id": "b6bb6e8b-3b37-4152-8984-c1b6fc0f1b1e",
"quantity": "2",
"timestamp": 1673886030
}
}
{
"cid": "54321",
"isCompleted": false,
"response": {
}
}
Get Rollback Status
curl --location --request GET 'http://localhost:62532/operations/status/54321'
{
"type": "receipt",
"operation": {
"cid": "54321",
"isCompleted": false,
"response": {}
}
}
{
"type": "receipt",
"operation": {
"cid": "54321",
"isCompleted": false,
"response": {
"asset": {
"code": "USD",
"type": "fiat"
},
"id": "b6bb6e8b-3b37-4152-8984-c1b6fc0f1b1e",
"quantity": "2",
"timestamp": 1673886030
}
}
}
{
"type": "receipt",
"operation": {
"cid": "54321",
"isCompleted": true,
"error": {
"Code": 14,
"Message": "Rollback Failed"
}
}
}
Process Payout
Place example here
Place example here
Example: Adjusting Balances Manually
Import transaction
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.
Message Schema outlined below. 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.
The transactionId should be assigned by your end, and should be indicating the unique ID that can be used to reconcile your records (e.g., could be the transaction ID assigned by the given blockchain). id field is just a unique number that you should assigned to your response to uniquely identify your response message.
curl --location --request POST 'http://localhost:53400/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": "ownera-escrow"
}
},
"transactionDetails": {
"transactionId": "73358f79-3b3a-4080-90c3-cbb7edd26668"
}
}
]
}'
curl --location --request POST 'http://localhost:53400/ledger/transaction/import' \
--header 'Content-Type: application/json' \
--data-raw '{
"transactions": [
{
"id": "2e9e41ab-43ac-43c6-9952-e06da35417c2",
"asset": {
"type": "fiat",
"code": "USD"
},
"quantity": "6",
"timestamp": 1673863664,
"source": {
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"account": {
"type": "finId",
"finId": "02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632",
"orgId": "ownera-escrow"
}
},
"transactionDetails": {
"transactionId": "931dd475-9442-46b8-b1b8-8a0e5e937985"
}
}
]
}'
Updated about 2 months ago