Payments API
The payments API allows Entrecard users to accept payments using Entrecard credits via an automated process similar to Paypal IPN.
Policy
The payments API is intended for the purposes of shopping cart and service integration for trading goods and services using Entrecard credits. It is not intended as a general mechanism for performing credit transfers.
The following policy applies:
- While we do not require third parties intending to use the API to vet their code with us, we highly recommend it. Developers intending to use the API should contact Entrecard support via the Feedback box on the dashboard once their code is mostly functional for review. Entrecard will provide some credits for testing transactions with, as well as checking the code for correct behaviour and security.
- Entrecard offers a bounty of 20,000ec for correct, well implemented example code in popular web frameworks such as PHP/Symfony, Python Django/Turbogears, Ruby on Rails etc.
- Abuse of the API can result in a range of measures from API suspension for the user through to account deletion.
- API payments are subject to transaction fees of 12.5% of the total, this is taken from the receiver (in effect, the seller receives 12.5% less than their asking price).
Basic flow
- Seller presents Buyer with link to “Buy now”
- Buyer arrives at Entrecard, where details contained in the link are displayed
- Buyer confirms payment
- Entrecard performs transaction, displays result
- Buyer follows link back to seller website
Constructing the Buy Now link
First, you need to know the Seller Secret. This is a secret string known only to the seller and Entrecard, it is different for every seller. The Buy now URL is constructed as follows:
http://entrecard.com/uapi/1/buy?seller=(seller id)&id=(item id)&description=(description)&quantity=(quantity)&cost=(per unit cost)¬ify=(notify url)&success=(success url) &cancel=(cancel_url)&signature=(signature)
Fields
| Field | Description |
|---|---|
| seller id | The Entrecard ID of the seller (number displayed in /user/<whatever/) |
| item id | arbitrary string of characters matching regex [A-Za-z_\-\d]+ up to 32 chars length |
| description | arbitrary string of characters matching regex [A-Za-z_\-\d \.,]+ up to 64 chars in length |
| quantity | integer number of units >= 1 |
| cost | integer number of credits > 1 |
| notify | URL that result notifications will be sent repeatedly until 200 OK is received |
| success | URL user will be redirected to after successful transaction with results |
| cancel | URL user will be redirected to after cancelled/failed transaction, possibly with results |
| signature | hex digest of the sha1 of the urlencoded string of the above parameters, plus the secret. |
Receiving the result
The result can be received one of three ways:
- Via the notify URL
- Via the success URL
- Via the cancel URL
Of these, only the cancel URL may arrive without a formal result attached. This occurs when the user bails out before a transaction is created.
for notify or success, either URL has the following appended:
?seller_id=&id=&total=&transaction_id=&status=&signature=
- total is the sum total of the credits transfered (will always = cost * quantity)
- transaction id is a unique integer id assigned by Entrecard to the transaction. You should always check you have not already received a response for this transaction. If you have, simply return the previous result.
the signature is calculated in the same fashion, and you MUST use this to verify the result is correct.
status can be one of 'cancelled','failed' or 'complete'. Cancelled means it was cancelled by the user, failed means the user had insufficient funds, complete means the funds have been transferred.
Future status may include 'escrow', which means the funds have been transferred into an escrow account awaiting confirmation by the user that the service was performed. escrow should be treated as equivalent to complete.
