Developers - API

Brief
The XoomWallet API uses HTTP methods and RESTFUL endpoints. You can send payment requests on below mentioned API endpoints by following required paramnaters. Before sending any request your data format must be JSON and XoomWallet API server will return JSON formatted responses.

USER-AGENT Security Note:: All payment requests to XoomWallet API endpoint must be standard HTTPS requests. Due to our network security plan, every request to XoomWallet API endpoint must sent with "User-Agent". If you do not send this string, XoomWallet will not entertain any request on API inerface.

Merchant Start-up:: Before start using XoomWallet API or SCI servcies, Merchant will need to have Business Account with XoomWallet and must submit legal documents to get verified. Merchant will need to create store, by clicking Manage Stores under My Business menu, inside XoomWallet Account. 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 each SCI or API call and must be used to generate security paramater "xw_auth_signature".


Operational Environments
You will need to use below XoomWallet REST API operational environments.
Sandbox: https://sandbox.xoomwallet.com/
 
Live: https://www.xoomwallet.com/

REST API Authentication and Call-to-Action Commands
With each API call, you will need to send two required parameters.
Action:
Action is a command that let XoomWallet API server process specific API call. All available commands are mentioned below:
To Get Active Wallets ISO Codes:- action=do-get-wallets
To Send Payment Request:- action=do-sale
To Resend Payment Confirmation Token After Sale:- action=do-payment-confirm
To Get Specific Transaction Details:- action=do-get-transaction-detail

Header Digest Authentication:
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.

Sandbox Environment AuthenticationFor Sandbox environment you must send below API USERNAME & SECRET
API USERNAME = 0102030405-0102030405-0102030405
API SECRET = 01020304050607080900

Store Passcode:
This is a verified Store Passcode from Merchant Account.
xw_passcode=XXXXXXXXXXXXX (Alphanumeric String from Merchant Verified Store.)


API Technical Details
Below are available API call commands collection

Get Active Wallets ISO Codes
Use do-get-wallets command with /api/wallets/ endpoint to get all active wallets. So that you can show all available wallets to your buyers, to let them select wallet to complete your purchase order.

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

Field Name Is Required Format of Value Description
Action
(action)
Y do-get-wallets Action command
Store Passcode
(xw_passcode)
Y Alphanumeric Verified Store Passcode It must be a verified store passcode reference from Merchant Account.

Response from XoomWallet API server in regards to /api/wallets/ command will be:
Successful Response:
{"status":"success","data":[{"iso":"EUR"},{"iso":"SAR"},{"iso":"SGD"},{"iso":"SLL"},{"iso":"USD"}]}

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


Unsuccessful Response:
{"status":"error","error":"Invalid API Key"}

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




Send Payment Request (Sale)
Use do-sale command with /api/payment/ endpoint to complete your payment request.

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

Field Name Is Required Format of Value Description
Action
(action)
Y do-sale 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.
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 [email protected]
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:You must make sure that this Store Name must be used as it is as listed in Manage Stores, and must be verified.
Order 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
Buyer Account ID
(xw_buyer_id)
Y String It must be a Buyer's account ID. e.g [email protected] Merchant will need to ask it to Buyer before sending payment request.
Buyer Purchase Token
(xw_purchase_token)
Y String It must be an alphanumeric string. Merchant will need to ask it to Buyer before sending payment requests. All direct XoomWallet API payment requests require all buyers to generate one time secure purchase token to use on merchant website to complete order.
Note: For Sandbox Payment API Request You must send "XXXXXXXXXXXXX" token with up to 13 characters in length.
Buyer Currency ISO
(xw_buyer_currency)
Y Standard ISO String Currency parameter must be standard Currency ISO code, and must be available in XoomWallet. Before sending any payment request, Merchant will need to request all active wallets to show you buyer to let them select, from what wallet they want to complete the order.

Response from XoomWallet API server in regards to /api/ command will be:
Successful Response:
{"status":"success","data":{"xw_payment_status":"Completed","xw_item_name":"Jewellery Pack","xw_item_price":45.50,"xw_fee":0.09,"xw_business_id":"[email protected]",
"xw_buyer_id":"[email protected]","xw_buyer_name":"Buyer Name","xw_buyer_currency":"EUR","xw_store_name":"Stone Corner","xw_passcode":"B727MWUL4QN49",
"xw_currency":"USD","xw_order_id":"597F3SJD","xw_auth_signature":"CD01FED9ECF275090AE856A20B3337CDA6FC06C1428B196E688A5379B5866E94",
"xw_payment_confirmation_token":
"OWEzM2ExNDUzNzI2MzllMWFmMDQ4ZjIzNzNkMDBmMzcwZTU4YjgzNy0wNTlhMDg1OWIxMzlhNDY4ZjgwOWQxODZjMjFjOTRmMWNjZGQyMjhkLWFmaWZhdW1lckBnbWFpbC5jb20=",
"xw_transaction_date":"22-11-2016 09:28:45","xw_transaction_id":"7DJRK830DU44HJZ"}}

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


Unsuccessful Response:
{"status":"error","error":"Invalid API Key"}

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


XoomWallet API Server Data Verification Process:
Upon receiving return data from XoomWallet Server, Merchant will need to verify received data. Response 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 Server



Payment Confirmation Token Verification Process
Use do-payment-confirm command with /api/confirm/ endpoint to verify received payment confirmation token.

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

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":"[email protected]"}}

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.



Get Transaction Detail
Use do-get-transaction-detail command with /api/transaction_detail/ endpoint to get completed transaction details.

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

Field Name Is Required Format of Value Description
Action
(action)
Y do-get-transaction-detail 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.
Transaction ID
(xw_transaction_id)
Y String It must be a valid completed transaction ID.

Response from XoomWallet API server in regards to /api/transaction_detail/ command will be:
Successful Response:
{"status":"success","data":{"xw_payment_status":"Completed","xw_item_name":"Jewellery Pack","xw_item_price":45.50,"xw_fee":0.09,"xw_business_id":"[email protected]",
"xw_buyer_id":"[email protected]","xw_buyer_name":"Buyer Name","xw_buyer_currency":"EUR","xw_store_name":"Stone Corner","xw_passcode":"B727MWUL4QN49",
"xw_currency":"USD","xw_order_id":"597F3SJD","xw_auth_signature":"CD01FED9ECF275090AE856A20B3337CDA6FC06C1428B196E688A5379B5866E94",
"xw_payment_confirmation_token":
"OWEzM2ExNDUzNzI2MzllMWFmMDQ4ZjIzNzNkMDBmMzcwZTU4YjgzNy0wNTlhMDg1OWIxMzlhNDY4ZjgwOWQxODZjMjFjOTRmMWNjZGQyMjhkLWFmaWZhdW1lckBnbWFpbC5jb20=",
"xw_transaction_date":"22-11-2016 09:28:45","xw_transaction_id":"7DJRK830DU44HJZ"}}

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


Unsuccessful Response:
{"status":"error","error":"Invalid Transaction ID."}

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