Shopping Cart Interface (SCI)

If you find the Shopping Cart Interface too complicated, feel free to use our simple HTML form for receiving gold payments.  Our Shopping Cart Interface allows you (the merchant) to fully integrate iGolder payments to your website with precise control on the transaction flow.  Here is a summary of the integration process:

 

  • Step #1: Your website calls the web service <PreAuthorizedPayment> to submit a payment request to your customer.  The payment amount may be specified in grams of gold, or in a fiat currency such as $100 USD or €75 EUR.
  • Step #2: Your customer is redirected to iGolder.com where he/she logins and approves the gold payment to you.
  • Step #3: Once the transaction is approved, the customer is redirected back to your website where your server simply calls the web service <PreAuthorizedPaymentAccept> to accept the payment.  The web service will transfer gold from your customer's account into your account, or return you an error code if the transfer could not be completed, such as a duplicate transaction or insufficient gold.  After you receive the gold, you simply deliver the product or service to your customer.

 

Step #1: Submit a Payment Request <PreAuthorizedPayment>

The first step to automate a gold transfer is to submit a payment request by calling the web service <PreAuthorizedPayment>.  This web service will record an entry allowing to automatically transfer a quantity of gold from your customer's account into your account.

 

Requested Value Description
SubAccountId Identifier of the sub-account you wish to receive the gold payment from your customer.
SecurityTokenId Security password of your sub-account.  For more information, visit Where can I find my Sub-Account ID and Security Token ID?
AmountGold Amount of gold you wish to receive from your customer.  This amount is a weight in grams of gold.
AmountFiat Payment amount in a fiat currency, such as United States Dollars (USD) or Euros (EUR).
This parameter is mutually exclusive to AmountGold.
The AmountFiat is purely for convenience; iGolder will calculate the weight of gold to transfer from the current market exchange rate.
Description Payment description, such as the product or service the customer is about to purchase from you.
Safetransit How long should the payment remain in Safetransit™.  Safetransit gives peace of mind to your customer; promising that you will deliver the product or service before closing the transaction.  For instance, if you ship a product by mail, we recommend you to specify a Safetransit time of 10 days for domestic shipping and 15 days for international shipping.  It is up to you to specify the Safetransit time you wish, however if you specify a short Safetransit time, your customer may stop your payment if he/she feels the product has not arrived on time.

If you do not specify any value, the gold payment will remain in Safetransit according to the Minimum Safetransit Time.

Examples of <Safetransit>:
<Safetransit>15m</Safetransit>  <!-- 15 minutes in Safetransit -->
<Safetransit>12h</Safetransit>  <!-- 12 hours in Safetransit -->
<Safetransit>30d</Safetransit>  <!-- 30 days in Safetransit -->
UrlReturn URL you wish to redirect your customer after he/she authorized the gold payment.  This URL is typically your confirmation page displaying a message or sending an email to your customer to acknowledge you received the payment.
You are welcome add any parameters you wish to the return URL, such as the email of your customer, name and customer ID.  iGolder will automatically append to the URL's Query String the identifier of the payment request as TransactionId.

Example for UrlReturn:
http://www.MyWebsite.com/buy/?Email=Adam@hotmail.com&Name=Adam+Smith

 

<PreAuthorizedPayment> <PreAuthorizedPayment> <SubAccountId>e3327c2c8843416bb693765c22f51ad1</SubAccountId> <SecurityTokenId>300a9b2804e4469c811327e30004a5aa</SecurityTokenId> <AmountGold>100</AmountGold> <!-- in grams of gold --> <Description>Alice purchasing boat for 100 gr of gold (Invoice #1234)</Description> <Safetransit>14d</Safetransit> <!-- time to deliver the boat --> <UrlReturn>http://demo.igolder.com/DemoConfirmationPage.aspx</UrlReturn> <!-- Bob's confirmation page (it should be on his website such as www.bob.com/buy-igolder.aspx --> </PreAuthorizedPayment>

 

After invoking the web service <PreAuthorizedPayment>, you will receive the following response from iGolder.com:

 

<PreAuthorizedPaymentResponse> <TransactionId>02960caf6cd94898a03108f7c0d9fb2c</TransactionId> <UrlRedirect>http://demo.igolder.com/account/transaction-authorize.aspx?TransactionId=02960caf6cd94898a03108f7c0d9fb2c</UrlRedirect> </PreAuthorizedPaymentResponse>

 

Returned Value Description
TransactionId Unique identifier representing the payment request.  You may use this ID to fetch the payment status or to accept the payment.  The Transaction ID is a GUID, so you may store it in your database as a 128-bit integer or as a string containing 32 hexadecimal characters.
UrlRedirect URL to redirect your customer to iGolder.com.  The customer will enter his/her email and password and approve the payment to you.  Once the payment has been approved, the customer will be redirected to the UrlReturn you specified when invoking <PreAuthorizedPayment>.

Step #2: Redirect your customer to iGolder.com

Simply redirect your customer from your website to iGolder.com.  The URL is provided in the response from <PreAuthorizedPayment>.  Your customer will have the opportunity to login to his/her iGolder account and approve the transaction.  As the merchant, you will never know the customer login nor the password used by him/her.

 

Simulation of Bob's shopping cart

 

In the example above, Alice is redirected to http://demo.igolder.com/account/transaction-authorize.aspx?TransactionId=02960caf6cd94898a03108f7c0d9fb2c

 

Alice loging to send payment to Bob

 

After her login, Alice has the option to authorize the transaction by clicking on the button I authorize this payment.  Alice may also pick which sub-account from which she wishes to pay Bob:

 

Alice is confirming her payment to Bob

 

Once the payment is authorized by Alice, she is automatically re-directed to Bob's website where Bob displays a message to Alice he received her payment and the product will be delivered.  In our simulation, Alice is redirected to http://demo.igolder.com/DemoConfirmationPage.aspx?TransactionId=02960caf6cd94898a03108f7c0d9fb2c as in the screenshot below:

 

Bob accepting payment from Alice

 

Until Bob collects Alice's payment, Alice will view in her account a Pending Payment to Bob:

 

Alice's pending payment to Bob

 

Likewise, if Bob visit his iGolder account, he will see Alice's Pre-Authorized Payment.

 

Bob's Pre-Authorized Payments

 

At this point, you have to return to the test tool to accept the payment, or click on the button Accept Payment.

 

Step #3: Process the transaction to accept the payment <PreAuthorizedPaymentAccept>

Once your customer approved the transaction, he/she will be redirected to the URL you provided in the field UrlReturn.  iGolder will automatically append the TransactionId  to the return URL, so you may use the Query String to fetch the TransactionId and perform additional processing.

 

To collect the gold, your website simply invokes the web service <PreAuthorizedPaymentAccept>.

 

Requested Value Description
SubAccountId Identifier of the sub-account you wish to receive the gold payment from your customer.
SecurityTokenId Security password of your sub-account.  For more information, visit Where can I find my Sub-Account ID and Security Token ID?
TransactionId Identifier of the transaction you wish to accept the payment (collect the gold).
AmountGold [Optional] Amount of gold you wish to transfer from your customer.  You may specify a value equal or less than the quantity you specified in <PreAuthorizedPayment>.  There are many cases where you may wish to pre-authorize a lager amount of gold, and accept a smaller value.  For instance, you may pre-authorize 1 gr of gold for a long-distance call, however bill only a few milligrams once the call is completed.

If you do not specify any value, then iGolder will transfer the full amount authorized by your customer.

 

<PreAuthorizedPaymentAccept> <SubAccountId>2ea41cd8ddb8447b8d74cbb67630bd6f</SubAccountId> <SecurityTokenId>20842b61c2854387b17b1480f4c36cfa</SecurityTokenId> <TransactionId>93d03dae1e004a26ae68b3c980b64f7f</TransactionId> </PreAuthorizedPaymentAccept>

 

If successful, you will receive the following response from iGolder.com:

  

<PreAuthorizedPaymentAcceptResponse> <TransactionId>3ff36a56367045a780dc9f7af8dc7eba</TransactionId> <AmountGold>4.590</AmountGold> <DateSafetransitUntil>2009-09-23 04:21:35</DateSafetransitUntil> </PreAuthorizedPaymentAcceptResponse>

 

Returned Value Description
TransactionId Unique identifier representing the accepted payment.  This value is the same as the TransactionId you supplied when invoking <PreAuthorizedPaymentAccept>.  This parameter is passed for convenience and for debugging purpose.
AmountGold This value is a confirmation of the quantity of gold (in grams) taken from your customer's account and transferred into your account.  Since you are receiving the gold, this value is always positive.  The transaction fee is included in AmountGold, so you have to subtract the fee if you want to know how much gold you actually received.  The transaction fee ranges from 0.1% to 5% depending on your account type.

The value AmountGold is present only if the transaction was successful.  If an error occurred, the web service will return an XML structure starting with the element <Error>.
AmountUSD
AmountEUR
AmountGBP
...more...
Current market exchange rate of the AmountGold in a fiat currency, such as United States Dollars (USD) or Euros (EUR), Great Britain Pound (GBP).  You may add or remove fiat currencies by clicking on the link iGolder Settings at the top right of the page.  If you wish to know the value of the transaction fee, simply do the cross-multiplication.  The value in fiat currency is purely for convenience, and because of the currency market fluctuation, this value changes constantly.
Fee The fee you pay for receiving gold.  The transaction fee varies according to account type and reputation.  This value is always positive.  A negative transaction fee is when you make a payment refund.
DateSafetransitUntil Date when the gold will clear from Safetransit™.  Depending on your customer and transaction amount, the payment may be held in Safetransit according to the Minimum Safetransit Time.

You may use this value for your own bookkeeping to determine when the payment will clear and therefore when the gold become available for spending.  The DateSafetransitUntil is express in UTC/GMT.  If you wish to display this date in your timezone, then you have to perform some arithmetic to adjust the UTC/GMT date to the local time.  Likewise, if you wish to calculate the number of days or hours the gold is held in Safetransit, simply subtract the DateSafetransitUntil from the current date & time.
Error / UrlAction iGolder will return the XML element <Error> if unable to transfer gold to your merchant account.  A frequent error is ErrTransactionNotApproved where the user did not approved the transaction.  Use the element UrlAction to redirect your customer to iGolder for authorizing the payment to you.
Feel free to download our Automation Testing Tool to test our shopping cart APIs.

 

Source Code / Confirmation Page

The following sample code sends a confirmation email to the customer with a registration key.  If an error occurred, the error message is displayed to the user and a link is displayed to redirect the customer to purchase the product.  The code was copied from http://demo.igolder.com/DemoConfirmationPage.aspx

 

using System; using System.Xml; public partial class Confirmation : System.Web.UI.Page { public const string iGolderServer = "http://demo.igolder.com"; // Use "https://www.igolder.com" for live transfers private string strSubAccountId = "5e83571e68d04c90acdf3251245ab453"; // Enter your SubAccountId here private string strSecurityTokenId = "08aefdc7c72c41352319575ab36e26c6"; // Enter your SecurityTokenId here protected void Page_Load(object sender, EventArgs e) { // Get the TransactionId from the URL. The TransactionId is automatically appended by iGolder to the return URL (UrlReturn). string strTransactionId = Request.QueryString["TransactionId"]; // If you have a database, you may use the TransactionId and fetch the customer information. // In our case, we stored the customer information (name and email) in the query string of the URL. string strName = Request.QueryString["Name"]; string strEmail = Request.QueryString["Email"]; Response.Write(string.Format("Dear {0}, <br />", strName)); // Call the web service <PreAuthorizedPaymentAccept> to accept the pre-authorized payment and collect the gold. // This web service will transfer the gold from the customer's account into your account. // You may optionally include the <AmountGold></AmountGold> to specify how much gold you wish to // transfer to your account. The gold amount must be equal or less than the requested amount // when you invoked the web service <PreAuthorizedPayment>. System.Net.WebClient client = new System.Net.WebClient(); string strXmlResponse = client.UploadString(iGolderServer + "/api.ashx", string.Format( @"<PreAuthorizedPaymentAccept> <SubAccountId>{0}</SubAccountId> <SecurityTokenId>{1}</SecurityTokenId> <TransactionId>{2}</TransactionId> </PreAuthorizedPaymentAccept>", strSubAccountId, strSecurityTokenId, strTransactionId)); // If the transfer was successful, there should be a node named <AmountGold> to confirm the gold transfer XmlDocument xmlResponse = new XmlDocument(); try { xmlResponse.LoadXml(strXmlResponse); XmlNode xmlNodeAmountGold = xmlResponse.SelectSingleNode("//AmountGold"); if (xmlNodeAmountGold != null) { string strAmountGold = xmlNodeAmountGold.InnerText; // The amount is in grams of gold // The payment is complete and you collected gold from your customer. // It is now your turn to deliver the product or service to your customer. // In this demo sample, we write a "Thank You" message to the customer and send an email with the product registration key Response.Write("Thank you for purchasing product XYZ. An email message was sent to you with your registration key."); string strRegistrationKey = "123-456-789"; string strEmailSubject = string.Format("{0}, thank you for purchasing product XYZ - Your registration key is {1}", strName, strRegistrationKey); string strEmailBody = string.Format( @"Dear {0}, Thank you for purchasing product XYZ for {1} grams of gold. To install product XYZ, click on the link http://www.MyWebsite.com/InstallProductXYZ.exe and enter your registration key {2}.", strName, strAmountGold, strRegistrationKey); // Send the email to the customer. System.Net.Mail.SmtpClient smtp = new System.Net.Mail.SmtpClient("localhost"); smtp.Send("sales@MyWebsite.com", strEmail, strEmailSubject, strEmailBody); // For debugging purpose, display the whole XML response from ther server Response.Write(string.Format("<br /><br /><br /><hr />XML response from iGolder server:<br /><pre>{0}</pre>", System.Web.HttpUtility.HtmlEncode(strXmlResponse))); // For your records, you may wish to know when the gold payment will clear from Safetransit XmlNode xmlNodeDateSafetransitUntil = xmlResponse.SelectSingleNode("//DateSafetransitUntil"); if (xmlNodeDateSafetransitUntil != null) { string strDateSafetransitUntil = xmlNodeDateSafetransitUntil.InnerText; DateTime dateSafetransitUntil = DateTime.Parse(strDateSafetransitUntil); TimeSpan timeSafetransitRemaining = dateSafetransitUntil.Subtract(DateTime.UtcNow); Response.Write(string.Format("<br />DateSafetransitUntil: {0}, the payment of {1} grams of gold will clear in {2} hours", strDateSafetransitUntil, strAmountGold, timeSafetransitRemaining.TotalHours.ToString("N1"))); } return; } // if string strErrorDescription = null; string strUrlAction = null; // Action URL to fix the error string strHtmlUrlHelp = null; // HTML code containing the hyperlink to the technical documentation of the error // The pre-approved payment was not successful. In this case, we have to fetch the error code. XmlNode xmlNodeError = xmlResponse.SelectSingleNode("//Error"); if (xmlNodeError != null) { // There are four different nodes (see https://www.iGolder.com/developer/API-error-codes/#XML for documentation) XmlNode xmlNodeErrorCode = xmlNodeError.SelectSingleNode("ErrorCode"); // Just in case you need the numeric error code XmlNode xmlNodeErrorName = xmlNodeError.SelectSingleNode("ErrorName"); XmlNode xmlNodeErrorDescription = xmlNodeError.SelectSingleNode("ErrorDescription"); if (xmlNodeErrorName != null && xmlNodeErrorDescription != null) { strErrorDescription = xmlNodeErrorDescription.InnerText; string strErrorName = xmlNodeErrorName.InnerText; switch (strErrorName) { case "ErrTransactionNotApproved": // The customer rejected the transaction. break; case "ErrTransactionAlreadyProcessed": // The merchant already processed your transaction and accepted your payment. break; default: strErrorDescription = null; // Empty the error description and display strXmlResponse break; } // switch } // if XmlNode xmlNodeUrlAction = xmlNodeError.SelectSingleNode("UrlAction"); if (xmlNodeUrlAction != null) strUrlAction = xmlNodeUrlAction.InnerText; XmlNode xmlNodeUrlHelp = xmlNodeError.SelectSingleNode("UrlHelp"); if (xmlNodeUrlHelp != null) strHtmlUrlHelp = string.Format("<br />View Technical Documentation UrlHelp: <a href='{0}' target='_blank'>{0}</a>", xmlNodeUrlHelp.InnerText); } // if // We were unable to fetch the error description, so dump the whole XML response for debugging purpose if (strErrorDescription == null || strErrorDescription == "") strErrorDescription = System.Web.HttpUtility.HtmlEncode(strXmlResponse); // If there is no hyperlink supplied in the error, redirect the customer to the "Buy" page if (strUrlAction == null || strUrlAction == "") strUrlAction = "https://www.MyWebsite.com/buy/"; Response.Write(string.Format("Your iGolder payment could not be completed. Please try again at <a href='{0}'>{0}</a>" + "<br /><br />The server iGolder.com returned the following error:<br /><pre>{1}</pre>", strUrlAction, strErrorDescription)); // For debugging purpose, display the whole XML response from ther server Response.Write(string.Format("<br /><br /><br /><hr />XML response from iGolder server:<br /><pre>{0}</pre>{1}", System.Web.HttpUtility.HtmlEncode(strXmlResponse), strHtmlUrlHelp)); } catch (System.Xml.XmlException ex) { // We were unable to parse string strXmlResponse Response.Write(string.Format("Invalid XML response ({0}) from iGolder: {1}", ex.Message, System.Web.HttpUtility.HtmlEncode(strXmlResponse))); } } }

 

Download Automation Test Tool

You are welcome to download our Automation Test Tool which can invoke the web service <PreAuthorizedPaymentAccept> and display the values returned by the server iGolder.com.

 

 

Error Codes

These are the most common error codes when processing a pre-approved transaction.  Here is an example of an error:

 

<Error> <ErrorCode>450</ErrorCode> <ErrorName>ErrTransactionNotApproved</ErrorName> <ErrorTitle>Transaction Not Approved</ErrorTitle> <ErrorDescription>The customer rejected the transaction. To accept the transaction, click on the button "I authorize this payment" on the iGolder website.</ErrorDescription> <UrlAction>https://www.igolder.com/account/transaction-authorize.aspx?TransactionId=3ff36a56367045a780dc9f7af8dc7eba</UrlAction> <UrlHelp>https://www.igolder.com/developer/API-error-codes/#ErrTransactionNotApproved</UrlHelp> </Error>

 

Error Name Error Description
ErrTransactionNotApproved
(error code 450)
Transaction Not Approved
The customer rejected the transaction.  To accept the transaction, click on the button "I authorize this payment" on the iGolder website.

This error happens when the customer click on the link I do NOT authorize this payment and I wish to cancel this transaction, or when you call the web service <PreAuthorizedPaymentAccept> without redirecting the customer to iGolder.com.

What to do?  Simply redirect your customer to the "buy page" and ask him/her to purchase again.  The element UrlAction contains the hyperlink to redirect your customer to iGolder for authorizing the payment to you.  If your website is friendly, your customer will only have to click on the button I authorize this payment and the transaction will be approved.
ErrTransactionAlreadyProcessed
(error code 451)
Transaction Already Processed
The merchant already processed your transaction and accepted your payment.  This message is a protection so you are not billed twice for the same transaction.

Typically, your customer will see this message when refreshing the web browser, or clicking on the Back button of the web browser and being redirected again to your confirmation page.  As a merchant, just make sure you gracefully handle this case.

For a complete list of all possible errors, visit API Error Codes.

 

Shopping Cart Interface APIs

Web Service Description
<PreAuthorizedPayment> Create a pre-authorized payment request.
<PreAuthorizedPaymentAccept> Process the transaction and accept the payment (collect the gold).
<PreAuthorizedPaymentGetStatus> Optional API to fetch the status of a pre-authorized payment. 

 

 

Optional API: <PreAuthorizedPaymentGetStatus>

The web service <PreAuthorizedPaymentGetStatus> enables you to fetch the payment status of a given transaction.  This is API is useful if you wish to know if you have accepted the payment of a given transaction ID.  If you need additional shopping cart APIs for your website, such as returning all outstanding pending payments or something else, feel free to contact us.

 

Requested Value Description
SubAccountId Identifier of the sub-account you wish to receive the gold payment from your customer.
SecurityTokenId Security password of your sub-account.  For more information, visit Where can I find my Sub-Account ID and Security Token ID?
TransactionId Identifier of the transaction you wish to query the payment status.

 

<PreAuthorizedPaymentGetStatus> <SubAccountId>e3327c2c8843416bb693765c22f51ad1</SubAccountId> <SecurityTokenId>300a9b2804e4469c811327e30004a5aa</SecurityTokenId> <TransactionId>81c63779c603426f9dbe3724420176ce</TransactionId> <!-- ID of the transaction that you want to query --> </PreAuthorizedPaymentGetStatus>

 

If successful, the web service <PreAuthorizedPaymentGetStatus> will return the following:

 

<PreAuthorizedPaymentGetStatusResponse> <TransactionId>81c63779c603426f9dbe3724420176ce</TransactionId> <PaymentAccepted>True</PaymentAccepted> </PreAuthorizedPaymentGetStatusResponse>

 

Returned Value Description
TransactionId Identifier of the transaction you fetched the payment status.  This parameter is passed for convenience and for debugging purpose.
PaymentAccepted This value is True if the merchant (you) accepted the payment and collected the gold.  If this value is False, it means the payment was not yet collected.

 


iGolder Logo

Feel free to use our logo to your website.  You may also use our high-resolution logo at 300 DPI on a black background or on a white background.

 

iGolder Logo
iGolder Logo (210 by 78)
iGolder Logo
iGolder Logo (100 by 37)
iGolder Logo
iGolder Logo (70 by 21)
iGolder Icon
iGolder Icon (32 by 32)
iGolder Icon
iGolder Icon (16 by 16)

 

 

 

Since August 1st, 2013 iGolder is no longer accepting new accounts and balances can only be redeemed. During the past years, we have been recommending Bitcoin more than our own payment system. We believe in physical gold ownership, and developed iGolder as a mechanism for people to acquire physical gold by trading with one another.

Since iGolder has a central point of failure (our server may be raided by thugs wearing some kind of uniform), we feet it is safer for us to cease operations. The iGolder experiment has been personally rewarding as we met many gold enthusiasts and also learned about Bitcoin in the process. For those who have no idea what Bitcoin is, we recommend doing your own research. Bitcoin is far superior to iGolder in every way, both in privacy and security as our server is always vulnerable to confiscation. Bitcoin is a communication protocol with a built-in "escrow service" capable of protecting both the buyer and the seller, rendering our Safetransit completely redundant. To learn more about the Bitcoin protocol and its feature, please watch "http://www.youtube.com/watch?v=mD4L7xDNCmA (Bitcoin 2012 London: Mike Hearn).

For those having gold in their iGolder account, we will ship the physical metal to anyone having more than 1 ounce of gold, assuming the owner is willing to assume the shipping costs. For smaller quantities, we offer to settle in Bitcoin, however we will also settle with any other reasonable payment system. We will give everyone at least two full years (until 2016) to contact us to claim their gold. After that period, any unclaimed gold will go to fund an economic development project in Honduras helping local people to become entrepreneurs.

We sincerely wish you the best in life and hope to keep in contact with you.

Yours in liberty,
The iGolder Team.


Update 2014: Since we announced we no longer accept gold transfers, we have received countless emails asking to keep the free gold charts and the PGP encryption tools. We plan to keep running the domain iGolder.com for both the gold charts and the encryption tools. Better, we are developing state of the art open-source software for a secure decentralized social network with a built-in wallet. We will announce when we have a product ready for use. Stay tuned!