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:

  1. Providing deposit instructions which are requests by an owner, which in turn will be used to deposit the funds into the escrow account.
  2. 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.
  3. Allow for cash withdrawal (payout) of funds from escrow account.
#ActionDescriptionAPI Reference

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.
https://finp2p-docs.ownera.io/reference/depositinstruction
2Allow for ability to request the status for the transactionImplement 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
3Allow 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
4Hold AssetUpon 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
5Release AssetOnce 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)
6Rollback Held AssetIn 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
7Process 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.
https://finp2p-docs.ownera.io/reference/payout
8Allow for ability to request the status for the transactionImplement 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
9Import a transactionUse 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.

ParameterDescriptionValue
Issuer Fin IDThe 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 IDThe finP2P resource ID for the given user created.bank-us:101:f09fa8ac-2b83-49de-8779-6ff954c5b181
Issuer Escrow Org IDThe escrow organization that will be used to transact the investmentownera-escrow
Asset IDThe asset ID assigned to the created asset.bank-us:102:631dd696-302b-4f6e-b91f-79cc7bf84f54
Primary Sale Intent IDThe 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"
            }
        }
    ]
}'