Payment Interfaces (PI) - Nodes Banks Payment Processors

v.2.0.0

Marionette’s Payment Interface (PI) serves as the middleware connecting third-party financial services, including banks, payment processing services, liquidity providers, market makers, blockchains, and Marionette’s accounting engine. The Payment Interface simplifies interaction with these external sources by integrating with their individual APIs. It interprets inbound financial information to update Marionette’s internal ledger records. Similarly, when connecting to the API source, it retrieves updated information and communicates it back to the connected third-party services.

In this example, we review how PIs communicate with specifically with blockchain nodes. Marionette treats blockchains as an external third-party financial service (bank, payment gateway, payment processor, etc.), but with extended capabilities applicable to each individual node and its unique parameters.

Marionette’s Payment Interfaces request real-time updates from individual blockchain nodes and uses this data to update internal accounting ledger records, including end-user and system wallet addresses.

Marionette’s PIs are responsible for:

Transaction Execution:
- Facilitating currency transfers between addresses

Transaction Handling:
- Receiving transactions from blockchains nodes, banks, payment gateways, liquidity provider, payment processor and other third-party financial services
- Processing the received financial data received from external sources and interpreting the data to the format accepted by Marionette’s Accounting Engine
- Sending transaction information to the backend for further processing

Data Integrity and Accuracy:
- Ensuring correctness and completeness of recipient data

Proxy Wallet Management:
- Generating new addresses for end-user proxy wallets for assigning end-user deposits to their individual platform wallets

Balance Management:
- Accepting deposits
- Processing withdrawals
- Updating user balances for addresses associated with the platform

Backend interaction with paymentInterface goes through following backend services:

paymentGateway - main tasks
blockchainRegistry - in the framework of saving the data of the system's hot wallet and reading blocks

Therefore, when the payment interface is starting, it must register with the relevant services

Examples:

await broker.call('blockchainRegistry.registerBlockchain', {
  id: config.id,
  title: config.title,
  subtitle: config.subtitle,
  description: config.subtitle,
  explorer_address: config.explorer_address,
  explorer_transaction: config.explorer_transaction,
  minConfirmations: config.minConfirmations,
  chainId: config.chainId
});

await broker.call('paymentGateway.registerPaymentInterface', {
  id: config.id,
  title: config.title,
  subtitle: config.subtitle,
  invoiceBased: false,
  multiCurrency: true,
  isCollectabled: true
});

Processing transfer transactions of currencies from various internal and external sources

When the backend calls for transactions:

when a user requests a withdrawal
when transferring currency from a hot wallet to a user's proxy wallet. Happens before collection tokens to hot system wallet when there is not enough coin for transaction commission.
when collecting currency from the user's proxy wallet

Action: transfer

Required parameters:

addressFrom - sender address
address - recipient's address
amount - amount to transfer

Optional parameters (particularly evm-based blockchains):

privateKey - for sender address
contractAddress - when sending a token
gasPrice - if it is necessary that the token transfer transaction be carried out with a fixed gasPrice in advance
subtractFeeFromAmount - specified only for transfers in the base currency of the blockchain. if the value is true, then the amount minus the blockchain fee should be sent to the recipient's address.

If transaction succeed should be returned JSON with fields:

txid - transaction hash

transferAmount - amount which received on recipient’s address

fee - transaction commission

feeCurrency - commission’s currency id

If transaction failed should be returned JSON with field:

error - error text which should be written to description of operation.

Receiving transactions from blockchain (and other third-party CeFi and DeFi financial services) and processing the received data, while updating back-end accounting ledger records.

Operations must be parsed sequentially block by block, it is also possible to move parsed blocks back and forth from the admin panel.

How it must work:

get the block
select from it transactions related to the currencies that are registered in this payment interface
convert the data to JSON with the following fields and call action “paymentGateway.processTransaction”:

txid - transaction hash
amount - transaction amount
paymentInterfaceId
currencyId
address
addressFrom

Informing and monitoring the correctness and completeness of recipient’s data

Actions: recipientSchema, initialDepositData, validateRecipient

recipientSchema

returns the JSON schema for the form to be filled in by the user

initialDepositData

returns JSON with fields:

address - how address would be show to users

encodedAddress - address as it is (frontend shows QR-Code based on this field)

redirectUrl - if frontend must be show redirect url (usually for fiat-based payment interfaces)

validateRecipient

Checks if the frontend received the recipient data correctly.

In the case of a blockchain:

turn the received text into JSON
find the address in it
check the address for validity in our blockchain

Generation of new addresses for proxy wallets of users. If users make deposits to proxy wallets designated to EVM (Ethereum Virtual Machine) type currencies.

Action: getNewAddress

Generate new address for user’s proxy wallet and returns it (with secret for evm-based blockchains).

Receiving currency balance for address

Action: balance

Receive currency balance for address (if contractAddress does not exist - receive coin balance)

Parameters:

address - compulsory
contractAddress - optional