API

The PayWithEther API

Hello! Hopefully you’re here because you would like to integrate PayWithEther’s API with your eCommerce site. If you are, perfect. Our API implementation is located at: https://api.paywithether.com (https standard port 443), and any requests should be directed there.

Public Endpoints

POST /user/auth

Check that you’re successfully talking to the API.

Parameters:

{
  apiKey: <YOUR_API_KEY> 
}

Response (If success): 200 OK

 

POST /transaction/create
Create a new transaction for PayWithEther to watch out for on the blockchain.
This should generally be called after a user has created an order, and you’re awaiting payment.

Parameters:

{
  apiKey: <YOUR_API_KEY>,
  to: "0x6B6fAAbB987381e5452460449c2c82b85730261E",
  ethVal: 0.1,
  dustAmount: 0.00000123,
  timeoutInSecs: 1200,
  callbackUrl: "http://your-store.com/payment-complete-url",
  reference: "0xabcdef123456"
}

Explanations:
to – This is the Ethereum address that you are going to ask the user to send funds to
value – The value of the transaction (in Ether) that PayWithEther should watch for (we do a >= check on this, so it won’t matter if the customer sends more)
dustAmount – An order-unique number which will be numerically added to the value, and PayWithEther will watch for a transaction for this exact amount, instead of (or as well as) watching for the reference.
timeoutInSecs – How long PayWithEther should watch for this transaction before considering it a failure. A higher number increases the chances of a value fluctuation, a lower number means your customer doesn’t have as long to submit the payment. Beware that in times of high transaction volume, PayWithEther might not pick up the transaction if it takes a long time to go through. (Default 1200, which is 20 minutes)
callbackUrl – A URL for PayWithEther’s service to POST back to, details of the POST back are below
reference – A hexadecimal string that you will ask the user to send as the data portion of their transaction

Response:

{   success: true,   data: {     txId: "-Kfg7EzGRwIQU8UpvGU7"   } }

Where txId is the transaction ID which has been assigned by PayWithEther for this transaction.

 

POST /transaction/success
Let PayWithEther know that you received a POST back from the API regarding an order.

NOTE: Make sure you don’t mark a transaction as complete before you get the 200 response from this, otherwise anybody could send a fake success request to your site!

Parameters:

{
  apiKey: <YOUR_API_KEY>,
  txId: "-Kfg7EzGRwIQU8UpvGU7"
}

Response: 200 OK

Post Back from the API

PayWithEther needs to post back to your server on a couple of occasions.
The first is if the transaction was seen on the blockchain, and we can let you know that you’ve received the funds. The second is if the transaction has not been seen for 20 minutes, and we let you know that we’re timing out the order to protect you from any volatilities. In future we’re going to add the ability for users to specify how long they would like this timeout to be.

This POST request goes to the URL specified in /transaction/create

{
  pweCallback: {
    callbackUrl: "http://your-store.com/payment-complete-url"
    created: 1490020271
    ethVal: "0.00046"
    reference: "0x3233333c2870"
    status: "success" (or 'timeout' if the order timed out)
    to: "0xeC1cfEb1597866904C17e91A0d2311E1DE701f82"
    txHash: "0x41e36f18f770624219c08e713db4dbc20bf743e86e190219567403fa4ed7f345"
    txId: "-Kfg7EzGRwIQU8UpvGU7"
    updated: 1490020359
  }
}