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. | Import Transaction | |||
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 |
|---|---|---|
| Issuer Fin ID | The public key used in creating the user profile, which in turn will be used as the finID for the user when transacting. | 024c9f4cda13349113e312bfe6e8860a5186ab90b3d0987cfd43bcdc285303d93a |
| Issuer User ID | The finP2P resource ID for the given user created. | bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181 |
| Issuer Escrow Org ID | The escrow organization that will be used to transact the investment | ownera-escrow |
| Asset ID | The asset ID assigned to the created asset. | bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54 |
| Primary Sale Intent ID | The Id assigned to the primary sale intent that is created. | bank-us:105:3a360d7a-df60-40b2-9574-eccaa1ed1f08 |
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>"
}
}
Hold Asset
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": "200",
"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-il: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"
}
]
}
},
"source": {
"account": {
"finId": "0351bd56def63039c4c6e196718841c1a619c104c50a8e3912aaf542a7aa60f1d9",
"type": "finId"
},
"finId": "0351bd56def63039c4c6e196718841c1a619c104c50a8e3912aaf542a7aa60f1d9"
}
}'
{
"cid": "",
"isCompleted": true,
"response": {
"asset": {
"code": "USD",
"type": "fiat"
},
"id": "b6bb6e8b-3b37-4152-8984-c1b6fc0f1b1e",
"quantity": "0.00",
"settlementRef": "f5cd25ae-1cdc-9ff3-199d-7637d29e1149",
"timestamp": 1673886030
}
}
Release Asset
Place example here
Place example here
Rollback Held Asset
Place example here
Place example here
Process Payout
Place example here
Place example here
Example: Adjusting Balances Manually
**Import transaction**
POST /ledger/transaction/import
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.
{
"transactions": [
{
"id": "A unique reference id to this message",
"asset": {
"code": ""
},
"quantity": "amount change to apply",
"timestamp": Epochtimestamp,
"source": {b
"finId": "Fin ID of the source account",
"account": {
"type": "finId",
"finId": "Fin ID of the source account",
"orgId": "Organization ID"
}
},
"destination": {
"finId": "Fin ID of the destination account",
"account": {
"type": "finId",
"finId": "FIn ID of the destination account",
"orgId": "Organization ID providng payment escrow services"
}
},
"settlementRef": "A reference number for the settlement",
"transactionDetails": {
"transactionId": "ID generated for the unqiue transaction"
}
}
]
}
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"
}
},
"settlementRef": "d9ea365e-56c8-43df-9674-c7132ee1c197",
"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"
}
},
"settlementRef": "d9cff0f0-1d8d-4d6f-a0ba-b9a5ccdccef8",
"transactionDetails": {
"transactionId": "931dd475-9442-46b8-b1b8-8a0e5e937985"
}
}
]
}'
Updated 11 days ago