We want the federation server to enable remittances to two types of institutions: banks and remittance centers (cash pick-up). Stellar provides a standard way of doing this for banks, but not for cash pick-up centers or institutions that forward the money to some other institution.

The following are similar to federation and compliance with some differences that enable further status updates.

Federation

In the Philippines, we cannot rely on a way to determine if a bank account is correct, if it's open, or if it can be deposited to electronically. Therefore, we have to do reasonable checks (some banks have a fixed bank account number limit) on the federation request:

Bank deposits: /federation?type=forward&forward_type=bank_account&swift=BOPBPHMM&acct=2382376 for banks, or
Cash pickups: /federation?type=forward&forward_type=remittance_center&bic=CLHPH for cash pick-up

List of supported institutions can be listed in the stellar.toml file or a file that stellar.toml points to. Here is an example of what the list may look like.

For banks, if the account number does not seem to be correct, reply with 404. If the account number seems to be correct, we reply with a federation server valid response.

An example federation server response is:

{
  "stellar_address": "does not matter because we are not 100% of the identity",
  "account_id":  "stellar-account-id-to-send-to",
  "memo_type": <"text", "id" , or "hash"> *optional*
  "memo": "unique string for this transaction"
}

Compliance

Now that the sending FI knows what memo to attach to the payment to send to the receiving FI, the sending FI makes a call to give sender information and optionally request for recipient information:

{
  "sender":"aldi*bankA.com",
  "need_info":true,
  "tx":"AAABJnsibm9...",
  "attachment":"{\"nonce\":\"1488805458327055805\",\"transaction\":{\"sender_info\":{\"address\":\"678 Mission St\",\"city\":\"San Francisco\",\"country\":\"US\",\"first_name\":\"Aldi\",\"last_name\":\"Dobbs\"},\"route\":\"1\",\"note\":\"\",\"extra\":\"\"},\"operations\":null}"
}

When the receiving FI finally responds with "info_status": "ok", the sending FI sends a payment via Stellar.

In order for the sending FI to get updates about the transaction, they must check the compliance (Auth) server: AUTH_SERVER/tx_status?id=txid (see this).

Note: the txid that is passed here by the sending FI was the one originally given to them when they first pinged the federation server. In order to prevent brute force attacks and leak information of the users of the system, this ID must be large enough to be unguessable, like a UUID.

ramontayag/stellar-for-forwarders.md

Federation

Compliance