Skip to content

Latest commit

 

History

History
152 lines (95 loc) · 7.81 KB

tg008.md

File metadata and controls

152 lines (95 loc) · 7.81 KB
Raw
TG: 008
Title: Implementation guide for online merchants
Author: Mike Gaertner <[email protected]>
Status: Active
Created: 2021-06-23
Updated: 2021-06-23
Version 1.0.0

Implementation guide for online merchants

This document describes the account setup and API implementation required for merchants to integrate with SSN. The integration assumes that the merchant has:

  • a database which stores information about payments due
  • is able to host a public API which can interact with the merchants database
  • has access to technical resources to implement the integration

The integration on SSN consist of 3 components

  • interface for the merchant to access his account
  • payment address resolver
  • blockchain stream listener

For each of the components SSN provides examples and documentation to help with the implementation process. SSN provides a testing network for integration development.

Documentation

SSN provides public document for all APIs and workflows, for this integration most relevant are the following APIs"

Please also read the document on how to manage account security and KYC on SSN.

SSN Accounts

Any party can open SSN accounts, provided they have network tokens to pay the transaction fees for the account creation. SSN does not approve or verify any accounts and SSN has no ability to reset passwords, or modify/close/delete accounts. Network tokens are issued by SSN to payment service providers, and system integrators who can freely trade the token between any account.

For testing, you can join our Telegram Group and use the /bot to open an account and request free tokens to make transactions.

For production integration, please request the account opening from your PSP, System Integrator, or contact Sabay Digital direct to arrange a token issuance to open an account.

Please read the following document to better understand what accounts are on SSN:

Payment flow

In this guide we assume the implementation is done for a online merchant who would like to integrate a online payment solution. Typically users order via phone or chat and once confirmed the merchant will issue a invoice ID / or payment ID to the user and ask the user to pay using any payment provider connected with SSN.

Flow

User

  1. user confirms order with merchant
  2. merchant issues payment address (or payment id) to user
  3. user opens his mobile app and select payment to merchant
  4. user enters the payment address (or payment id) in the mobile applications interface

Note: this process can also be implement as the user scanning a QR code from his banks mobile app, or mobile wallet)

Payment processor (PSP)

  1. receives payment address or payment ID from user
  2. PSP queries merchants payment address resolver to find details about the payment
  3. merchant response to PSP with payment details (amount, currency, payment memo, network address)
  4. PSP confirms amount and currency with the user and ask user for authorization
  5. PSP deducts money from the user account, and transfers it to an escrow account for final settlement with the merchant
  6. PSP makes transaction on SSN to send payment

Note: The payment details can also be transmitted via a QR code, skipping step 1-3)

Merchant

  1. listen on blockchain streaming service and calls internal function when a payment arrives
  2. internal processor checks payment memo and finds payment details
  3. books amount to close invoice / or payment request
  4. triggers service delivery to users

Integration

In order to implement this flow the merchant needs to implement 2 services:

  1. the payment address resolver
  2. the blockchain payment stream listener

Payment address resolver

A payment address on SSN represents an identifer for a payment request which can be queried against a merchant database. The resolver will return information about the payment request.

Payment addresses on SSN are used to exchange information about payment details in a secure and federated environment. A payment address consists of 2 parts, a user defined string which contains details that are relevant to the issuer of the payment request, and a federated address in the form of a domain name, separated by a *.

payment_detail*company.example

Please study the guide on implementing payment address and the resolver integration

An example checkout flow and payment address resolver can be found here:

Blockchain stream service

Merchants have direct access to the blockchain API and can stream transactions by subscribing to the SSN stream service. Alternatively merchant can also query the API periodically for transactions and process any new transactions.

We recommend a combination of both approaches, a stream service to process all transactions in real time, and a cron job to check periodically if all transactions have been processed.

To steam transactions SSN provides API using server-sent events (SSE)

Settlement

During the payment authorization process, the PSP will issue a tokenized I own you to the merchant, for money held by the PSP for the merchant. Each token represent money held in escrow at the PSP, and the PSP will redeem the money to the merchant when the merchant returns the IOU token issued by the PSP.

Merchants can use the SSN Dashboard to make a pay out request to payment provider where the merchant maintains an account with. The SSN Dashboard will prepare the transaction and ask the merchant to specify the account to which the tokens should be credited. The account must be a valid account number (or wallet address) with the payment provider.

The merchant can also implement the settlement using a automated process or semi automated workflow within the organization. Transactions can be created and signed as text using simple web forms. Or transactions can be created and signed programmatically and submitted automatically to the network.

To issue transactions 3 steps need to be coded:

It is good practice to require multiple signatures for SSN transactions for high volume accounts. A sample workflow could be implemented by the merchant which.

  1. presents balances in the account
  2. allows the finance controller to initiate the settlement request
  3. a web form to collect the needed information (PSP account number)
  4. a web form to allow signing of the request
  5. submission to the network
  6. display verification