add /tx_status to the compliance protocol

[jedmccaleb]

In many cases the sender needs to get additional info from the receiver after the payment is sent. To either tell their customer or for their own records.

After a tx is approved by the compliance protocol and submitted to Stellar, the sender can call /tx_status to learn what happened to the tx.

/tx_status?sender=bob*domain.com&id=tx_id&sig=<sig>
return
{
	status: {unknown,pending,ok,failed,refunded},
	recv_code: <arbitrary string>,
	refund_tx: <tx_hash>,
        msg: <arbitrary string>
}

sig is the tx_id signed by the sending domain using the same signature mechanism used in the compliance protocol.

refund_tx only appears if the status is "refunded". It will be the txID of the tx sending the money back. The address to send the refund to needs to be sent as part of the original payment attachment otherwise the receiver won't know how to refund.

[jedmccaleb]

ramon Should we add a delivered status?

[ramontayag]

@jedmccaleb yes, I think so. delivered would signify that the payment has been picked up in the remittance center (for cash pick-up), or it has been deposited to the bank account.

We probably also need to add a special status for a payment that is ready for pick-up and has not been picked up. It is at this stage the tracking number is known and the recipient can be notified. Something like claimable.

EDIT: With these two new statuses, I don't think we need ok - since it's ambiguous.

[ramontayag]

Let me map out what I think you mean by these statuses. Please let me know if sounds right:

• unknown
• pending - we are attempting to deposit it. This would also cover scenarios where something could not be deposited via the default method, but may be deposited another method (i.e. electronic deposit failed, but it may be deposited manually and it will take longer)
• failed - we could not deposit it
• refunded - payment sent back to sending FI. Possible reasons: deposit could not be made, or sending FI decided to cancel the cash pick-up payment (sometimes recipient never picks it up).
• claimable - cash pick-ups only. Cash is ready to be picked up at specified locations
• delivered - cash has been picked up, or money has been deposited into the bank account

[ramontayag]

When you said

sig is the tx_id signed by the sending domain

Do you mean that it will be signed with the seed of the Stellar account that sent the payment? Then the recipient will verify it with the public address that sent the payment.

[jedmccaleb]

@ramontayag do you remember why we preferred having the sender poll the receiver rather than have the receiver just tell the sender when the status becomes known? I think it may have been because we were worried that the sender might miss the msg from the receiver and then be in an unknown state.

Maybe we need both options? @nullstyle any thoughts on this?

[bartekn]

For statuses we need to add:

• stellar_tx_pending - waiting for Stellar transaction.
• stellar_tx_invalid - Stellar transaction arrived but something was wrong (ex. invalid asset).

The address to send the refund to needs to be sent as part of the original payment attachment otherwise the receiver won't know how to refund.

Probably but why not just send it back to sender account? Sending another refund account in an attachment is prone to errors: ex. account without a trust line, account that doesn't exist etc.

When it comes to polling, I think that sender should check status every X minutes because of the reasons in your comment @jedmccaleb.

[nullstyle]

For one note: I think we need to be really careful about adding statuses that don't apply to all compliance protocol users... it just complicates things. Having statuses that imply status regarding cash payouts seems like something we should avoid.

I'll come back to this ticket later today and work on some more feedback about the actual issue at hand. I've been away from the compliance protocol long enough that I need to refresh myself on the flow and the current design.

[ramontayag]

@jedmccaleb yup that's the reason you had in mind.

@nullstyle in that case, do you think Stellar should set a standard on how forwarders connect their APIs? It's not just for cash pickup -- most of those statuses are useful for forwarders that ultimately do not know whether or not the deposit will happen.

[nullstyle]

@ramontayag good point, it definitely makes sense for us to include support for payment forwarding of some kind. I'd like to learn some more about the jargon and standards that are presently used... but I admit I'm not very knowledgeable about the landscape. Could you point me to some other organizations that act as payment forwarders?

[ramontayag]

Hmm.. I'm not aware of other organizations that use stellar and are payment forwarders. However, most remittances all over the world fall under this this - like Western Union or remittance companies that deposit to a bank for you.

…

On Thu, 27 Jul 2017 22:24 Scott Fleckenstein, ***@***.***> wrote: @ramontayag <https://github.com/ramontayag> good point, it definitely makes sense for us to include support for payment forwarding of some kind. I'd like to learn some more about the jargon and standards that are presently used... but I admit I'm not very knowledgeable about the landscape. Could you point me to some other organizations that act as payment forwarders? — You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub <#59 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AABi9HZqrSWO3bRj0Qp0HVTLHseLltAvks5sSOPSgaJpZM4NkDGY> .

[nullstyle]

I'm not specifically looking for payment forwarders who are using stellar... I'm looking to understand the commonalities shared between existing systems like Western Union and remittance companies.

An example question that I'd like to be able to answer: What term does Western Union use to describe a payment that has been completed by the sender but has not been picked up at a western union branch? Or another: Should we differentiate between a bank deposit that isn't settled and a cash payout that hasn't been picked up?

My overall point: If we are building a protocol, we need to look at and learn from existing systems.
I'm nervous we're just encoding one organization's needs into a protocol meant to be more generally useful.

---

As food for thought, why must "pending" and "claimable" be two different states? Couldn't they both just be represented as "unsettled"?

[jedmccaleb]

Well something in pending isn't ready for the receiver to go to the cash pick up place and get the cash. So it needs to be a different status than claimable

[ramontayag]

Yeah, this is something that doesn't feel super clean to me, but I haven't thought of a better design. There are statuses that are just for cash pickup locations.

[bartekn]

After reading the discussion I'm starting to think if we really need a predefined set of statuses. Given the number of companies in the industry I think it will be really hard (or impossible) to create a list that will work for each of these. If I understand it correctly this endpoint will be used:

• To display the status of a transaction to the user.
  In this case I don't think users need more than: pending, delivered, failed (displayed in UI after tx is correctly refunded). I think that statuses like claimable will be more confusing than informational for a normal user.
• To give sending company more details about a transaction.
  In this case I think we don't need status at all because this will be probably always checked by a human, so a simple message in msg field like: "sending FI decided to cancel the cash pick-up payment" is always better than a single word status. Companies may build systems that ask a staff member to check tx status if it is in pending state for a longer period of time.

[ramontayag]

@bartekn, thanks for reviewing this. Just to make sure I understand, would it work this way in the cash pick-up context:

• pending: not yet available for pick up
• delivered: available for pickup, or picked up
• failed: was not able to process this tx

Then, if the sending FI wants to know if it has been picked up, they need to look further in the msg field? If they want to automate this part and put a status on their dashboard that distinguishes a remittance that is ready for pickup and one that has been picked up, like we have, they would need to parse the msg field and look for key words. The key words would probably be agreed upon between the two parties when coding the API calls.

[bartekn]

Then, if the sending FI wants to know if it has been picked up, they need to look further in the msg field?
Yes this is the key question. If there is a need to automate this, then set of statuses is probably needed because parsing msg is a bad idea.

[jedmccaleb]

bartek why do you think the user doesn't need to know when the payment is ready to pick up? That seems like the most important thing to me since that is when they have to take some action.

Also not every status needs to be used by every FI just like not every http status code is used by every website.

[bartekn]

bartek why do you think the user doesn't need to know when the payment is ready to pick up? That seems like the most important thing to me since that is when they have to take some action.

This endpoint is meant to be consumed by a sender. So as a sender I'm less interested if it's available for pick-up, delivered, completed, etc. I'm just interested if my friend received it or not. On the other side, receiver will certainly get more information from the company where the money was sent.

Also not every status needs to be used by every FI just like not every http status code is used by every website.

Yes, the problem is when the company is using a status that is not in a "standard set" we defined.

[jedmccaleb]

That isn't really true. Traditionally the info flow is driven by the sending side. In the tempo->coins case for example the people complaining and that want to know where the tx is are the senders. Also why not be more clear about what is happening with the tx?

[bartekn]

OK, I wasn't aware that Tempo receives complaints from senders. For example, in a normal bank panel you always see just pending, sent or refunded states so I thought it's quite normal that tx needs some time to reach the recipient and you as a sender should just wait.

When it comes to statuses, if we only manage to create a list that is used by majority of companies (and for statuses that are not there, companies can easily switch to similar one from our list) then fine. I think I agree with @nullstyle that we should use more generic statuses rather than super detailed ones that are valid only for a few companies and make this overcomplicated.

[nullstyle]

Alright, so thinking about things some more:

• I'm cool with the general shape of of the response.
• having the input sender be a stellar address rather than an account id seems dangerous. It introduces several variables into the protocol. federation responses can change and resolvers will likely have caches: I'm concerned this will lead to all sorts of complicated error scenarios that will not be obvious to programmers who have to integrate with this protocol.
• We say sig is signed by the sending domain: what that means specifically is unclear. This needs to be better specified.
• Is the response data private? It seems like it should be, and if so we need to incorporate some replay protection into the current auth scheme. Probably we add a nonce into the signature base string.
• When it comes to statuses, I'm mostly concerned about having two statuses where the distinction is subtle (as reflected by my previous question about the pending status). I'm not quite sure how best to change the previous proposals to resolve this issue. Perhaps we should diagram the state transitions then figure out the names... it might lead to some better insight.
• I find myself going back to the term that Anthony used during my lesson this week: "downstream". I'm thinking, for example, having statuses like downstream_rejected and downstream_error, etc.

[jedmccaleb]

Moving this to SEP: stellar/stellar-protocol#42

[jedmccaleb]

I feel like downstream_rejected and downstream_error are just different types of failed maybe we just need the one thing, failed and extra info in the msg field?