Wallets API

Overview
version: 1.0

The Wallets API is a collection of methods used to perform financial deposits into a user account. Currently this service only processes credit and debit card payments but will be expanded in future to support many other methods, e.g. PayPal.
Summary
MethodNameDescriptionResource
makeTransactionDeposits funds into a customer's account.https://sandbox.whapi.com/v1/wallets/me
getPaymentMethodsRetrieves a customer's registered methods of payment, for example credit and debits cards.https://sandbox.whapi.com/v1/wallets/me/methods
ResourcesExpand AllCollapse All
makeTransaction()
Deposits funds into a customer's account.
Request Example
POST /v1/wallets/me HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-ticket: TGT-2131-AvmSCnqFLOF4yYfNNcj1ralzdFxfJzj1TdiLEWxTrrPTsmb3qi-brsuxxxx
Content-Type: application/x-www-form-urlencoded
Payload:
transactionType=deposit&amount=50.00&id=12XXX&cv2=123
Request Parameters
header parameters
NameTypeDescription
who-apiKeystring
(required)
A unique identifier of your application that is generated by the API portal and presented in the header.
who-secretstring
(required)
Another unique identifier for your application. The secret must never be sent over HTTP.
who-ticketstring
(required)
The authentication ticket associated with the user session.
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
query parameters
NameTypeDescription
transactionTypestring
(required)
default:
deposit
Define whether the transaction is a deposit or a withdrawal from the wallet. In the initial release only deposits are supported.
amountfloat
(required)
Payment amount.
idinteger
(required)
An identifier for the payment that was retrieved from an earlier call to the service.
cv2integer
(required)
An authentication scheme established by credit card companies to further efforts towards reducing fraud for internet transactions.
Response Description
whoWallets
Object Name Type Constraints Optional Description
element paymentId String - No The identifier for the individual payment transaction.
element paymentDateTime String - No Thedate and time of the payment in the following format: YYYY-MM-DD HH:MM:SS.
ResponsesExpand AllCollapse All
Status: 200 (Ok) - Success - Date and time the payment (deposit) was made
Representations
application/xml
                        
<whoWallets>
     <paymentId>3248</paymentId>
     <paymentDateTime>2011-02-14 15:29:45</paymentDateTime>
</whoWallets>
application/json
                        
{
   "whoWallets":  {
         "paymentDateTime": "2011-02-1415: 29: 45",
         "paymentId": "3248"
   }
}
Status: 200 (Ok) - Fault 10070 - No transactionType parameter
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>transactionType</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"transactionType"
      }
   ]
}
Status: 200 (Ok) - Fault 10070 - No amount parameter
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>amount</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"amount"
      }
   ]
}
Status: 200 (Ok) - Fault 10070 - No id parameter
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>id</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"id"
      }
   ]
}
Status: 200 (Ok) - Fault 10070 - No cv2 parameter
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10070</faultCode>
      <faultString>Missing request parameter.</faultString>
      <faultName>cv2</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10070",
         "faultString":"Missing request parameter.",
         "faultName":"cv2"
      }
   ]
}
Status: 200 (Ok) - Fault 10071 - id parameter is invalid
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>10071</faultCode>
      <faultString>Invalid request parameter.</faultString>
      <faultName>id</faultName>
   </fault>
</whoFaults>
application/json
{
   "whoFaults":[
      {
         "faultCode":"10071",
         "faultString":"Invalid request parameter.",
         "faultName":"id"
      }
   ]
}
Status: 200 (Ok) - Fault 24001 - Invalid payment method Id
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24001</faultCode>
      <faultString>Invalid payment method Id.</faultString>
      <faultName>transactionType</faultName>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24001",
         "faultString":"Invalid payment method Id.",
         "faultName":"transactionType"
      }
   ]
}
Status: 200 (Ok) - Fault 24002 - The deposit is less than the allowed minimum
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24002</faultCode>
      <faultString>The deposit is less than the allowed minimum.</faultString>
      <faultName>amount</faultName>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24002",
         "faultString":"The deposit is less than the allowed minimum.",
         "faultName":"amount"
      }
   ]
}
Status: 200 (Ok) - Fault 24003 - The deposit is greater than the allowed maximum
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24003</faultCode>
      <faultString>The deposit is greater than the allowed maximum.</faultString>
      <faultName>amount</faultName>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24003",
         "faultString":"The deposit is greater than the allowed maximum.",
         "faultName":"amount"
      }
   ]
}
Status: 200 (Ok) - Fault 24004 - Invalid permission level
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24004</faultCode>
      <faultString>Invalid permission level.</faultString>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24004",
         "faultString":"Invalid permission level."
      }
   ]
}
Status: 200 (Ok) - Fault 24005 - Payment authorisation failed
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24005</faultCode>
      <faultString>Payment authorisation failed.</faultString>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24005",
         "faultString":"Payment authorisation failed."
      }
   ]
}
Status: 200 (Ok) - Fault 24006 - Invalid card number
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24006</faultCode>
      <faultString>Invalid card number.</faultString>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24006",
         "faultString":"Invalid card number."
      }
   ]
}
Status: 200 (Ok) - Fault 24007 - Insufficient funds
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24007</faultCode>
      <faultString>Insufficient funds.</faultString>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24007",
         "faultString":"Insufficient funds."
      }
   ]
}
Status: 200 (Ok) - Fault 24008 - Daily deposit limit has been exceeded
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24008</faultCode>
      <faultString>Daily deposit limit has been exceeded.</faultString>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24008",
         "faultString":"Daily deposit limit has been exceeded."
      }
   ]
}
Status: 200 (Ok) - Fault 24009 - Invalid CV2 number
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24009</faultCode>
      <faultString>Invalid CV2 number.</faultString>
      <faultName>cv2</faultName>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24009",
         "faultString":"Invalid CV2 number.",
         "faultName":"cv2"
      }
   ]
}
Status: 200 (Ok) - Fault 24010 - Invalid expiry date
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24010</faultCode>
      <faultString>Invalid expiry date.</faultString>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24010",
         "faultString":"Invalid expiry date."
      }
   ]
}
Status: 200 (Ok) - Fault 24011 - Still processing last transaction
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24011</faultCode>
      <faultString>Still processing last transaction.</faultString>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24011",
         "faultString":"Still processing last transaction."
      }
   ]
}
Status: 200 (Ok) - Fault 24015 - Protection of customer funds statement has not been accepted
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24015</faultCode>
      <faultString>Protection of customer funds statement has not been accepted.</faultString>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24015",
         "faultString":"Protection of customer funds statement has not been accepted."
      }
   ]
}
getPaymentMethods()
Retrieves a customer's registered methods of payment, for example credit and debits cards.
Request Example
POST /v1/wallets/me/methods HTTP/1.1
Host: sandbox.whapi.com
Accept: application/xml
who-apiKey: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-secret: l7xxa54460c573b5497c9b24b505xxxxxxxx
who-ticket: TGT-2131-AvmSCnqFLOF4yYfNNcj1ralzdFxfJzj1TdiLEWxTrrPTsmb3qi-brsuxxxx
Request Parameters
header parameters
NameTypeDescription
who-apiKeystring
(required)
A unique identifier of your application that is generated by the API portal and presented in the header.
who-secretstring
(required)
Another unique identifier for your application. The secret must never be sent over HTTP.
who-ticketstring
(required)
The authentication ticket associated with the user session.
acceptstring
(required)
options:
application/xml, application/json
The representation of the response.
Response Description
whoWallets
Object Name Type Constraints Optional Description
node paymentMethods Node - No The payment methods node.
paymentMethods
Object Name Type Constraints Optional Description
node method Node - No The method node.
method
Object Name Type Constraints Optional Description
element id String - No The system ID that corresponds to a payment method.
element type String - No The payment method. Note that the codes for card types vary across different systems.
node limits Node - No The limits node.
node card Node - No The card node.
limits
Object Name Type Constraints Optional Description
elements minDeposit String - No Minimum deposit limit for the payment method type
elements maxDeposit String - No Maximum deposit limit for the payment method type
card
Object Name Type Constraints Optional Description
elements number String - No The card number, only the first 6 and last 4 digits are returned.
elements issueDate String - No The issue date of the card in the following format: MM/YY
elements expiryDate String - No The expiry date of the card in the following format: MM/YY
elements country String - No The name of the country the card is registered in
elements scheme String - No The scheme the card belongs to
ResponsesExpand AllCollapse All
Status: 200 (Ok) - Success - Methods retrieved
Representations
application/xml
<whoWallets>
   <paymentMethods>
      <method>
         <id>2367</id>
         <type>CC</type>
         <limits>
            <minDeposit>1.00</minDeposit>
            <maxDeposit>7500.00</maxDeposit>    
         </limits>
         <card>
            <number>454312XXXXXX1115</number>
            <issueDate>12/09</issueDate>
            <expiryDate>12/12</expiryDate>
            <country>UNITED KINGDOM</country>
            <scheme>VC</scheme>
         </card>
      </method>
   </paymentMethods>
</whoWallets>
application/json
{
   "whoWallets": {
      "paymentMethods": [
         {
            "id": "2367",
            "type": "CC",
            "limits": {
               "minDeposit": "1.00",
               "maxDeposit": "7500.00"
            },
            "card": {
               "number": "454312XXXXXX1115",
               "issueDate": "12/09",
               "expiryDate": "12/12",
               "country": "UNITED KINGDOM",
               "scheme": "VC"
            }
         }
      ]
   }
}
Status: 200 (Ok) - Fault 24000 - No payment methods available
Representations
application/xml
<whoFaults>
   <fault>
      <faultCode>24000</faultCode>
      <faultString>No payment methods available.</faultString>
   </fault>                            
</whoFault>
application/json
{
   "whoFaults":[
      {
         "faultCode":"24000",
         "faultString":"No payment methods available."
      }
   ]
}
Error Handling
General Error Structure
As an application developer, you will need to see a standard error response when the system generates an error. As well as supplying a standard HTTP status code, we also supply a unique William Hill fault code, fault string and fault name (in some cases) to help you identify and resolve any issues that you may be having with our API or your requests and code.

Where the elements can be defined as the following:
  • Fault code - A unique William Hill identifier for the error
  • Fault string - A unique William Hill text string to enable you to identify the error (in English only)
  • HTTP code - the standard HTTP status code for the error
  • HTTP response - the standard HTTP response for the error

Note: A Fault name may also be generated in order to pinpoint the exact parameter where a request has failed.

Available Response Formats

The error codes are supplied in the following representations:

  • XML
  • JSON
Error Response Body

The response body will contain the unique William Hill fault code and fault string appropriate to the corresponding error.

The response will be sent according to the representation type governed by the accept parameter within the original request. The default representation is for application/xml and this representation will be returned if either the accept header is absent or if the accept header is set to application/xml.

Generic William Hill Error Codes

Click here to view the complete list of William Hill error codes for the APIs.

API Specific Error Codes

Error codeFault stringHTTP codeHTTP response
24000 No payment methods available 200 OK
24001 Invalid payment method Id 200 OK
24002 The deposit is less than the allowed minimum 200 OK
24003 The deposit is greater than the maximum allowed 200 OK
24005 Payment authorisation failed 200 OK
24006 Invalid card number 200 OK
24007 Insufficient funds 200 OK
24008 Daily deposit limit has been exceeded 200 OK
24009 Invalid CV2 number 200 OK
24010 Invalid expiry date 200 OK
24011 Still processing last transaction 200 OK
24015 Protection of customer funds statement has not been accepted 200 OK
HTTP Status Codes

For more information about how William Hill uses HTTP status codes with their APIs, click here.