Was I Paid?

For Developers

URL callback guide

You can configure Was I Paid? to send a request to your website when your account receives a payment (or other events that you may be interested in occur). We will submit all the transaction Ripple transaction to the url you specified.

This allows you to provide instant feedback to your customers and immediately initiate fulfillment. It can be used to integrate Ripple payments with existing shopping cart systems, or for something custom built.

The callback process

  1. The url you specified will receive a POST request, with JSON-formatted data in the request body.
  2. To verify that this is a legitimate notification, you post back the JSON structure verbatim to https://wasipaid.com/receipt. The server will respond with the text VALID if this is a notification it really sent, or INVALID, if it did not. This is equivalent to PayPapl's IPN system.
    Be sure to verify soon; after some time (currently: minutes), the server will forget about it and you'll no longer get an ok.
  3. To confirm receipt, you need to return status code 200 and the two letters OK in the content. This is to protect you from system errors that do not issue a proper error code. Once you acknowledge receipt in this way, the notification will not be sent again. Otherwise, we will periodically retry for up to 30 days.

The data

You will be given a JSON object which contains three keys:

{
   'transaction': {},
   'ledger': {},
   'data': {}
}

transaction and ledger contain the original data structures returned from the Ripple network, see these examples. All the information can be found there.

However, data makes the most important information more easily accessible. It will look like this:

{
   'transaction': {},
   'ledger': {},
   'data': {
       'sender': '',       # Ripple address of sender
       'destination': '',  # Your ripple address
       'amount': '',       # The exact amount received
       'currency': '',     # The currency (XRP, USD)
       'issuer': '',       # Who issued the IOU, missing if XRP
       'tag': ''           # The destination tag used
       'invoice_id': ''    # The invoice id tag used
   }
}

Important Information

  • Despite our best attempt to provide a reliable and secure service, we will not assume liability for any damage caused by errors in this service. Consider checking with a Ripple server you trust before accepting a payment.
  • URL callbacks should normally be received within 30 seconds, often sooner. However, service outages may cause delay. A lot of care was taken to ensure notifications are not lost, though.
  • Don't worry if your site is down and cannot accept notifications. We will retry with increasing delays for up to 30 days.
  • In extremely rare cases, you may receive a notification twice. Rare as in, our service crashes in that exact moment after sending the notification, but before being able to persist the fact that it did. For perfect safety, you should be prepared to handle duplicate notifications.

Examples

You can find a small example project on Github.