HomeGuidesRecipesAPI ReferenceDiscussions
HomeGuidesAPI ReferenceRecipes

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.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.

ParameterDescriptionValue
Buyer Fin IDThe Fin ID of the investor (buyer) that is depositing funds and in turn buying an asset.02acb467116c385e49feeb639c934dde1fcaa50ee12568fcb8856c87c1ac861632
Seller Fin IDThe 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"
            }
        }
    ]
}'