Skip to content

Latest commit

 

History

History
88 lines (71 loc) · 3.54 KB

sep-0004.md

File metadata and controls

88 lines (71 loc) · 3.54 KB
Raw

Preamble

SEP: 0004
Title: Tx Status Endpoint
Author: stellar.org
Status: Final
Created: 2017-10-30

Simple Summary

Simple way to get the status of a payment that has been sent through the compliance protocol from the receiver.

Abstract

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.

Specification

Endpoint at the URL specified by AUTH_SERVER in the stellar.toml file of an institution that receives payments. This endpoint is used to relay the status of payments to the sender or other interested parties. Can be used for simple informational purposes or to convey a code needed by the individual to claim the money on the receiving end.

AUTH_SERVER/tx_status?id=tx_id
return
{
    status: <status code see below>,
    recv_code: <arbitrary string>,
    refund_tx: <tx_hash>,
    msg: <arbitrary string>
}

id The Stellar transaction ID of of the payment we are interested in.

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.

status is one of the following codes:

  • unknown - what money?
  • approved - payment was approved by the receiving FI but the Stellar transaction hasn't been received yet.
  • not_approved - Stellar transaction was found but it was never approved by the receiving FI.
  • pending - payment was received. we are attempting to deposit it. This also covers scenarios where something could not be deposited via the default method, but may be deposited by another method (i.e. electronic deposit failed, but it may be deposited manually and it will take longer)
  • failed - we could not deposit it. msg should contain more info.
  • refunded - payment was 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 - Mostly used for cash pickup. Cash is ready to be picked up at specified locations
  • delivered - Receiver should now have the funds, cash has been picked up, or money has been deposited into the bank account.

Rationale

Prior discussion was done here stellar-deprecated/bridge-server#59

Current steps in a payment that goes through the compliance protocol:

  1. Alice initiates a payment to bob*bankb.com
  2. Client Endpoint A handles request
  3. Client Endpoint debits Alice's account
  4. Client Endpoint A call Bridge A
  5. Bridge A calls Compliance A
  6. Compliance A loads the stellar.toml B
  7. Compliance A resolves bob*bankb.com from federation server B
  8. Compliance A crafts the stellar tx
  9. Compliance A calls Compliance B
  10. Compliance B checks sanctions and other things
  11. Compliance B replies to Compliance A
  12. Compliance A replies to Bridge A with the stellar tx.
  13. Bridge A submits the stellar tx to horizon A
  14. horizon A submits the tx to stellar-core A
  15. Stellar network does its thing
  16. horizon B sees the tx applied to the ledger
  17. bridge B receives the applied tx to the ledger
  18. bridge B checks with Compliance B to verify that the tx was approved
  19. bridge B calls receive hook B to finish the payment
  20. Receive hook B credits bob's account
  21. Receive Hook notifies Bob
  22. Bob has been paid.