Developers - SCI

Brief
SCI - Shopping Cart Interface is a feature offered by XoomWallet system. It allows merchant's to transmit payment from Buyer's account.This features is specially designed for merchants who offer products or services. XoomWallet SCI enables merchants to receive payments easily and securely by using simple HTML forms. XoomWallet supports secure data transfer based on secure socket layers (SSL ).


SCI Technical Details
In order to accept online payments through XoomWallet, Merchant must have business account. Merchant must redirect buyers to SCI interface of XoomWalet to complete payment processing securely. Upon successful payment, Merchant technical payment interfaces, as stated in sent data to XoomWallet with Buyer, are notified with transaction details and if Buyer choose Redirect Back option after completing payment, will be redirected back to Merchant's website.

Operational Environments
You will need to use below mentioned operational environments for XoomWallet Server calls.

Sandbox: https://sandbox.xoomwallet.com

 
Live: https://www.xoomwallet.com

Accpeting payments through XoomWallet SCI requires below steps:

1:- Merchant Account:
Merchant will need to have Business Account with XoomWallet and must submit legal documents to get verified.

2:- Merchant Store:
Merchant will need to create store, by visiting Manage Stores under My Business menu, inside XoomWallet Account and during Store creation process, Merchant will need to input valid Website address. This associated website to Store must be verified by following details inside account while clicking on Verify button. Verifying website means Merchant will have verified Store in XoomWallet Account. Upon creating store, system auto generates a Passcode for each store, which will be required for any SCI or API call and must be used to generate security paramater "xw_auth_signature".

 

Store Field Name Is Required Format of Value Description
Store Name Y String - Length must be between 5 to 15 characters Store name for your own acknowledgment and to be used in SCI and API calls.
Store Website Y String - Length must be between 6 to 50 characters Website, you must verify before using SCI or API by placing generated file at your hosted domain's server.
Website Success URL Y / N String - up to 120 characters in length Success URL, where buyers will be redirected after sucecssful payments.
Website Fail URL Y / N String - up to 120 characters in length Fail URL, where buyers will be redirected if payment will be cancelled by Buyer.
Website Callback URL Y / N String - up to 120 characters in length When Buyer completes order, XoomWallet SCI interface send all completed payment data on set Callback URL. CallBack URL means that all payment related data will be sent as background process, while Buyer will be on XoomWallet SCI page and even not shown the payment/order completion page.
Store Mode Y Test/Live Either mode will be LIVE or TEST, for real or test transactions. This setting will reflect payment call URLs as mentioned below:
Store Mode & their respective URLs

Endpoint: {operational-environment}/sci/

For API calls, please refer to our API documentation.
Store Passcode Y Alphanumeric Auto System Generated Store Passcode By creating store you will get Passcode (Secret API Key) to be used in SCI or API calls
Store Verification Y Associated website verification process In order to use SCI or API calls you must have verified Store. For Store verification, associated website needs to be verified.
Upon new Store creation, Merchant will have a button "Verify" besides the name of Store. Clicking on this button will bring up a dialog box. Merchant will need to first download Store related text file, by clicking "Generate Code" button, to place on associated website hosting root path. After that Merchant will need to click "Verify Website" button.

 

3:- SCI HTML Buttons/Forms
After having one or more verified Stores, Merchant will be able to create HTML buttons on the fly. Upon creation of any button by following required input data details, Merchant can get HTML code by clicking "Get HTML Code" button available in each listed button.

 

Button/Form Field Name Is Required Format of Value Description
Item Name
(xw_item_name)
Y String - Length must be between 3 to 50 characters Name of Item/Service, the purpose of payment is being made for.
Item Price
(xw_item_price)
Y Integer - with up to 2 digits decimal value Item/Service price to be charged.
Note: Item Price plays vital role in generating "xw_auth_signature". Whenever you send item price make sure it must have 2 trailing decimals. Suppose if you want to send 5, item price must be "5.00" and if you want to send 5.5, item price must be "5.50".
Business ID
(xw_business_id)
Y String It must be a merchant's business account ID. e.g merchantid@xoomwallet.com
Store Name
(xw_store_name)
Y String - Length must be between 5 to 15 characters It must match to the verified store name (creatd and verified store in Manage Stores). Name must be used as it is, even if it will have spaces or capital letters etc.
Note: If merchant creates a button inside XoomWallet account, system place this store name from associated store. But if merchant will be manually managing form then must make sure that this Store Name must be used as it is as listed in Manage Stores, and must be verified.
Store Passcode
(xw_passcode)
Y Alphanumeric Auto System Generated Store Passcode While generating button from merchant XoomWallet account, system associates a verified store passcode reference automatically.
Note: If merchant creates a button inside XoomWallet account, system place this store passcode from associated store. But if merchant will be manually managing form then must make sure that this Store Passcode must match with the same Store Name as well.
Currency ISO
(xw_currency)
Y Standard ISO String Currency parameter must be standard Currency ISO code, and must be available in merchant's XoomWallet Account.
Order ID
(xw_order_id)
Y String - up to 15 characters in length Merchant will need to generate and send purchase oder ID by own, as unique identifier.
Authentication Signature
(xw_auth_signature)
Y HASH String Before sending request using SCI/API interface Merchant must generate "xw_auth_signature" Has String by using below parameters. (It prevents vulnerability in sending and receiving data.)
:: xw_business_id
:: xw_store_name
:: xw_item_price
:: xw_passcode
:: xw_currency
:: xw_order_id
Delimeter must be "-" and then xw_auth_signature will be a string by SHA-256 hash following UPPERCASE.
xw_business_id-xw_store_name-xw_item_price-xw_passcode-xw_currency-xw_order_id
URLs Y / N String - up to 120 characters in length (xw_success_url) & (xw_fail_url) & (xw_callback_url)
Note: There are two open options for merchants to use tehse URLs. Either these must be set in associated Store information (Store Name and Store Passcode) or manually sent in form payment request.
Custom Fields Optional Up to 10 Strings After generating button merchant can add up to 10 custom fields in SCI request.
Note: Add custom fields following below rules. System will post back all received custom fields along with its received data back on your success and callback URLs.
%html_tags%

 

%after_button_sample_form%

 

4:- Merchant's Website Checkout Interface
Merchant will need to have a checkout interface for Buyers and utilize generated HTML form code to reflect price, item/service name, order id or any other changes. Upon changes of any technical/required payment processing data will need Merchant to follow security guidelines to generate "xw_auth_signature", before redirecting Buyers to XoomWallet SCI interface to process payments.

 

Digital Authetication Signature Preparation:

Before sending SCI Payment Request, Merchant will need to make sure that "xw_auth_signature" is generated using exactly below used fields

Fields: xw_business_id, xw_store_name, xw_item_price, xw_passcode, xw_currency, xw_order_id

make sure that delimeter must be "-" and then xw_auth_signature will be a string by SHA-256 hash following UPPERCASE.

For Example in PHP:
strtoupper(hash('sha256', "xw_business_id-xw_store_name-xw_item_price-xw_passcode-xw_currency-xw_order_id"));



 

5:- XoomWallet Invoice Page
Redirected Buyer will be landing on payment invoice page, that validates all received data set and describes everything to Buyer to whom they are going to pay and what. Buyer will need to login into their account by providing their Account ID (Email) and Password. Buyer will have option to cancel the payment and XoomWallet SCI interface will redirect back the Buyer on set fail page URL of Merchant's website. Upon successful account authentication, Buyer will have an option to click "Pay Now" button to complete payment order.

6:- Successful Payment Data Processing & verification
After successful authentication of Buyer's account, where Buyer can review complete payment details, if Buyer completes order, XoomWallet SCI interface send all completed payment data on set "xw_callback_url". CallBack URL means that all payment related data will be sent as background process while Buyer will be on XoomWallet SCI page and even not shown the payment/order completion page.

 

Successful Payment Return Data:

Upon receving payment request, XoomWallet SCI server generates Auth Signature using required parameters from received data and makes sure everything is correct to process payment request. Upon successful payment, XoomWallet SCI server regenerate "Auth Signature" & "Payment Confirmation Token" and return below structured data using POST method on callback URL (if set), or on set success page (if Buyer choose to return back to merchant website).

Array
(
    [xw_item_name] => Jewellery Pack
    [xw_item_price] => 45.50
    [xw_fee] => 1.5
    [xw_payment_status] => Completed
    [xw_business_id] => merchantid@xoomwallet.com
    [xw_buyer_id] => buyerid@xoomwallet.com
    [xw_buyer_name] => Buyer Name
    [xw_store_name] => Stone Corner
    [xw_passcode] => B727MWUL4QN49
    [xw_currency] => USD
    [xw_order_id] => 597F3SJD
    [xw_auth_signature] => CD01FED9ECF275090AE856A20B3337CDA6FC06C1428B196E688A5379B5866E94
    [xw_payment_confirmation_token] => OWEzM2ExNDUzNzI2MzllMWFmMDQ4ZjIzNzNkMDBmMzcwZTU4YjgzNy0wNTlhMDg1OWIxMzlhNDY4ZjgwOWQxODZjMjFjOTRmMWNjZGQyMjhkLWFmaWZhdW1lckBnbWFpbC5jb20=
    [xw0] => useremail@somedomain.com
    [xw1] => 350
    [xw2] => 1
    [xw_transaction_date] => 22-11-2016 09:28:45
    [xw_transaction_id] => 7DJRK830DU44HJZ
)

XoomWallet SCI Server Data Verification Process:
Upon receiving return data from XoomWallet SCI Server, Merchant will need to verify received data. Return data will always include HASH String in "xw_auth_signature" parameter and a string in "xw_payment_confirmation_token".

Verification Process:
xw_auth_signature field will contain HASH string based on following fields:
Merchant Business ID (xw_business_id)
Merchant Store Name (xw_store_name)
Item Price (xw_item_price)
Store Passcode (xw_passcode)
Payment Currency ISO Code (xw_currency)
Order ID (xw_order_id)

By concatenating with "-" it will look like:
xw_business_id-xw_store_name-xw_item_price-xw_passcode-xw_currency-xw_order_id
Merchant will need to HASH above data by SHA-256 following UPPERCASE, which becomes like
CD01FED9ECF275090AE856A20B3337CDA6FC06C1428B196E688A5379B5866E94


Merchant will need to compare this generated Auth Signature using received form fields with the received HASH string from XoomWallet SCI Server


Payment Confirmation Token Verification Process:

Payment Confirmation Token will be used only to confirm that security measures are not breached and your own sent business account ID is used to pay, not any other.

In order to make calls to XoomWallet API Operations, you must set API Credentials (API USERNAME & SECRET) in each call of header to identify your API calls are authorized from a valid business account.

Endpoint: {operational-environment}/api/confirm/

Use do-payment-confirm command with /api/confirm/ endpoint to verify received payment confirmation token.

Field Name Is Required Format of Value Description
Action
(action)
Y do-payment-confirm Action command
Store Passcode
(xw_passcode)
Y Alphanumeric Verified Store Passcode It must be a verified store passcode reference from Merchant Account.
Note:You must make sure that this Store Passcode must match/associated with the same used Store Name.
Payment Confirmation Token
(xw_payment_confirmation_token)
Y String Payment Confirmation Token will be used only to confirm that security measures are not breached and your own sent business account ID is used to pay, not any other. Upon receiving successful response data, you will need to resend received payment confirmation token from XoomWallet Server.
Response from XoomWallet API server in regards to /api/confirm/ command will be:

Successful Response:
{"status":"success","data":{"message":"Valid Payment Confirmation Token","xw_business_id":"merchantid@xoomwallet.com"}}

Successful response always have status containing success string & data containing response data.


Unsuccessful Response:
{"status":"error","error":"Invalid Payment Confirmation Token."}

Unsuccessful response always have status containing error string & error containing error description.


 

7:- Order/Payment Results Page
Upon successful completion of payment, Buyer will be redirected on order completion confirmation page to see all details of payment just made. Here, Buyer will have options to click "Go Back to Merchant Website" button to return back to Merchant's Website.

8:- Merchant Success Return Page
This page resides on Merchant's website. XoomWallet redirect back Buyer on this set success page, along with XoomWallet SCI completed payment/order details, as already sent via Callback URL.