Introduction

A payment is one of the most common transactions in a blockchain. It changes the ownership of a token amount from one address to another. This endpoint supports the payment of native tokens of the blockchain network and fungible tokens available in the Supported Fungible Tokens endpoint. For other tokens, please view the Smart Contract Write guide.

In this guide, we will show you how to:

• Send payments in the native token of the network
• Send payments with ERC20 fungible tokens supported by Overledger on networks based on the Ethereum Virtual Machine.

Prerequisites

• Create an account and generate your application's API keys
  Create an account on Quant Connect. Then, register your application to generate API keys to authorise your requests on Overledger APIs.

• Obtain an authorization token
  You must obtain an authorisation token to interact with Overledger's API and call any endpoint. This token will authenticate your requests and grant you access to the necessary endpoints. Please follow the authentication process provided by Overledger to get your authorisation token.

Prepare

During the Prepare step, you will provide the essential details of your payment:

• Location: The location parameter specifies which network the payment will occur in. A location is an object containing the "technology" field, which specifies the underlying technology powering the blockchain "network" on which the transfer occurs.
• Origin: The address which initially owns the token. The payer.
• Destination: The address receiving the token. The payee.
• Payment: The payment object contains information about how much is being paid and which token is used.

Let's take a look at an example request for a transaction preparation where the address 0x2ac51211bf3c22a0f859b82fabb8964a646a382b is paying 0.1 ETH to the address 0x708d1C75e5880a9942f49e17483Cb8d58118D395 on the Ethereum Sepolia Testnet:

• This is a POST request to https://api.overledger.staging.quantnetwork.net/v2/preparation/transaction
• It contains the authentication header with your application's access token.

curl --request POST \
     --url https://api.sandbox.overledger.io/v2/preparation/transaction \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "location": {
    "technology": "ethereum",
    "network": "ethereum sepolia testnet"
  },
  "type": "Payment",
  "urgency": "Normal",
  "requestDetails": {
    "overledgerSigningType": "overledger-javascript-library",
    "message": "OVL Transaction Message",
    "origin": [
      {
        "originId": "0x2ac51211bf3c22a0f859b82fabb8964a646a382b"
      }
    ],
    "destination": [
      {
        "payment": {
          "amount": "0.1",
          "unit": "ETH"
        },
        "destinationId": "0x708d1C75e5880a9942f49e17483Cb8d58118D395"
      }
    ]
  }
}
'

The successful response to this request is:

{
    "requestId": "4d50903f-0ea1-4c65-b22f-4841b980c5b0",
    "gatewayFee": {
        "amount": "0",
        "unit": "QNT"
    },
    "dltFee": {
        "amount": "0.00002179000017432",
        "unit": "ETH"
    },
    "nativeData": {
        "nonce": 11,
        "chainId": 5,
        "chain": "sepolia",
        "hardfork": "london",
        "to": "0x708d1C75e5880a9942f49e17483Cb8d58118D395",
        "gas": "21790",
        "maxFeePerGas": "1000000008",
        "maxPriorityFeePerGas": "1000000000",
        "value": "100000000000000000",
        "data": "5061796d656e7420666f722070616e6520696e7374616c6c6174696f6e2073657276696365732e"
    }
}

The request has been created on Overledger and must now be signed. The "nativeData" field contains data specific to the blockchain technology where this transaction will happen. This part must be digitally signed for the request to be executed successfully.

The "requestId" is an identification created by Overledger.

The DLT fee is the estimated fee the blockchain will charge for executing the transaction.

The Gateway Fee is always 0.

Sign

The request can only be executed once the owner of the source of the payment signs it. Please refer to Transaction Signing for detailed instructions on obtaining the digital signature. The "nativeData" field received in the previous step should be signed with the private key of the token owner's address.

Once the payment has been signed, see below an example of a signed payload:

"0x02f9011583013881048502540be4008502540be43283017aa5949673f628bb338dd94f840998a47af24eef526a5780b8a494d008ef000000000000000000000000ad595039d006197f0f5e1a079399a929c81c555516d7c7ad6d719d11503873c3f78ef5d6ace91a5a45c7cd0"

Execute

The execution step provides Overledger with the signature of the payment request, allowing it to be executed. Once this step is complete and everything is in order, the transaction will be broadcast to the network. It is then up to the network to process the payment transaction into a new block. Depending on the network, this is not immediate and can take many minutes depending on the blockchain network ( It can range from a few seconds to 10 minutes).

The execute request is as follows:

{
    "requestId": "4d50903f-0ea1-4c65-b22f-4841b980c5b0",
    "signed": "0x02f9011583013881048502540be4008502540be43283017aa5949673f628bb338dd94f840998a47af24eef526a5780b8a494d008ef000000000000000000000000ad595039d006197f0f5e1a079399a929c81c555516d7c7ad6d719d11503873c3f78ef5d6ace91a5a45c7cd0"
}

• "RequestId" is the ID of the request you have prepared.
• "Signed" is the digital signature done by the payer's private key.

If Overledger does not support the token, please refer to smart contract write guide