Contents

Cash to Code

 

The requests outlined in this document will need to be processed manually using our Webservices API.

 

PAYMENT Cash to Code
Cash to Code allows customers to complete online payments using cash at one of the thousands of retail locations across Europe. Customers select a deposit amount within the app and a barcode is generated that can be presented at their chosen point-of-sale, allowing them to pay in cash and instantly have their gaming account credited. This page outlines how to process payments using Cash to Code.

 

Features

Supported customer countries No restrictions on customer countries.
Supported currencies
EUR
Protect Plus
Supported.
Refunds Refunds not supported.
Chargebacks
Payments are not subject to chargebacks.

 


 

Configuration

To enable Cash to Code on your account, please get in touch with your account manager.
A test sandbox account will be provided, which you will need when testing your implementation.

 


 

Process overview

What will the customer see?

  • During the checkout process, your app / website states that Cash to Code is a supported payment method.
  • The customer enters their details and opts to pay using Cash to Code.
  • The customer is redirected to pages hosted by Cash to Code. Here, they choose their preferred retail location, after which, they are displayed a unique code.
  • The customer provides their unique code to the retailer they selected earlier and completes the payment by paying with cash.
  • If the customer still has their browser window open, they can click to be redirected back to your app / website, which can then display a success message of your choosing.

 

 

How does it work behind the scenes?

The Cash to Code payment flow can be split into three main parts, as shown below:

1

Performing the authorisation

2

Redirect to Cash to Code

3

Settlement

 

If the previous steps have been successful and the customer has completed the payment with cash:

 

Warning
Handling errors

In the unlikely event of an unexpected error occurring while on Cash to Code’s pages, the customer’s browser may be redirected to the page specified in the errorurlredirect field. This page will need to inform the customer that there has been a problem with processing the payment, and that they should seek assistance from your organisation / business to determine its status. In such a scenario, we recommend contacting our Support team for assistance.


 

1. Performing the authorisation

AUTH request

The following is an example AUTH request to be submitted when processing a Cash to Code payment:

Info
You cannot cancel a Cash to Code transaction once it has been authorised.

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "EUR",
  "baseamount": "2500",
  "successfulurlredirect": "https://example.com",
  "errorurlredirect": "https://example.com",
  "billingid": "1234567",
  "billingdob": "1994-01-01",
  "billingalias": "myuser",
  "billingcountryiso2a": "AT",
  "billingreturning": "0",
  "billingfirstname": "Joe",
  "billinglastname": "Bloggs",
  "paymenttypedescription": "CASHTOCODE"
}

strequest = securetrading.Request()
strequest.update(auth)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php

if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);

$configData = array(
  'username' => '[email protected]',
  'password' => 'Password1^',
);

$requestData = array(
  'sitereference' => 'test_site12345',
  'requesttypedescriptions' => array('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'EUR',
  'baseamount' => '2500',
  'successfulurlredirect' => 'https://example.com',
  'errorurlredirect' => 'https://example.com',
  'billingid' => '1234567',
  'billingdob' => '1994-01-01',
  'billingalias' => 'myuser',
  'billingcountryiso2a' => 'AT',
  'billingreturning' => '0',
  'billingfirstname' => 'Joe',
  'billinglastname' => 'Bloggs',
  'paymenttypedescription' => 'CASHTOCODE'
);

$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());

?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"version": "1.00",
"request": [{
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "EUR",
  "baseamount": "2500",
  "successfulurlredirect": "https://example.com",
  "errorurlredirect": "https://example.com",
  "billingid": "1234567",
  "billingdob": "1994-01-01",
  "billingalias": "myuser",
  "billingcountryiso2a": "AT",
  "billingreturning": "0",
  "billingfirstname": "Joe",
  "billinglastname": "Bloggs",
  "paymenttypedescription": "CASHTOCODE"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"sitereference":"test_site12345","requesttypedescriptions":["AUTH"],"accounttypedescription":"ECOM","currencyiso3a":"EUR","baseamount":"2500","successfulurlredirect":"https:\/\/example.com","errorurlredirect":"https:\/\/example.com","billingid":"1234567","billingdob":"1994-01-01","billingalias":"myuser","billingcountryiso2a":"AT","billingreturning":"0","billingfirstname":"Joe","billinglastname":"Bloggs","paymenttypedescription":"CASHTOCODE"}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
   <operation>
    <sitereference>test_site12345</sitereference>
    <accounttypedescription>ECOM</accounttypedescription>
   </operation>
   <merchant>
    <successfulurlredirect>https://www.example.com/success</successfulurlredirect>
    <errorurlredirect>https://www.example.com/error</errorurlredirect>
   </merchant>
   <billing id="1234567">
    <amount currencycode="EUR">2500</amount>
    <dob>1994-01-01</dob>
    <alias>myuser</alias>
    <country>AT</country>
    <returning>0</returning>
    <name>
     <first>Joe</first>
     <last>Bloggs</last>     
    </name>
    <payment type="CASHTOCODE"/>
   </billing>
  </request>
</requestblock>

Replace <DOMAIN> with a supported domain. Click here for a full list.

 

Field specification

Field Format Description
accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) Only “ECOM” (e-commerce) is supported.
baseamount
XPath: /billing/amount
Numeric (5) The amount of the transaction in base units, with no commas or decimal points, so €10 is submitted as 1000. This value must be greater than zero.
billingalias
XPath: /billing/alias
Alphanumeric (100) An alias provided by you, to identify the customer.
billingcountryiso2a
XPath: /billing/country
Alpha (2) The country for the customer’s billing address. This will need to be in ISO2A format. Click here for a full list of country codes.
billingdob
XPath: /billing/dob
Date YYYY-MM-DD The customer’s date of birth.
billingfirstname
XPath: /billing/name/first
Alphanumeric including
symbols (127)
The customer’s billing first name.
billingid
XPath: /billing/@id
Alphanumeric (100) An id provided by you, used to uniquely identify each customer. Returning customers must be assigned the same unique id as during their previous payment.
billinglastname
XPath: /billing/name/last
Alphanumeric including
symbols (127)
The customer’s billing last name.
billingreturning
XPath: /billing/returning
Numeric (1) Indicates if customer has previously completed a payment with Cash to Code:

“1” = True  –OR–  “0” = False

currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) For Cash to Code, “EUR” is submitted.
errorurlredirect
XPath: /merchant/errorurlredirect
URL (2048) The URL that the customer’s browser will be returned to if an error occurs during the transaction.
orderreference
XPath: /merchant/orderreference
Alphanumeric including
symbols (255)
Your unique order reference that can be stored on the Trust Payments system.
paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value must be submitted as “CASHTOCODE”.
requesttypedescription
XPath: /@type
Alpha (20) The value in the request must be “AUTH”.
sitereference
XPath: /operation/sitereference
Alphanumeric
& underscore (50)
The site reference relates to your individual account which you received on setup. If you do not know your site reference, please contact our Support team.
successfulurlredirect
XPath: /merchant/successfulurlredirect
URL (2048) If the customer completes their payment, they can click through to this success page hosted on your server.

 

AUTH response

Following a successful authorisation, your system will be returned an AUTH response with the following structure:


{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 11:32:44',
        u 'livestatus': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'transactionreference': u '23-9-80001',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'CASHTOCODE',
        u 'baseamount': u '2500',
        u 'accounttypedescription': u 'ECOM',
        u 'requesttypedescription': u 'AUTH',
        u 'currencyiso3a': u 'EUR',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'settlestatus': u '10',
        u 'redirecturl': u 'https://example.com'
    }]
}
array(3) {
  ["requestreference"] => string(9) "A3579dkvx"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(15) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-07 11:32:44",
      ["livestatus"] => string(1) "0",
      ["settleduedate"] => string(10) "2016-12-07",
      ["errorcode"] => string(1) "0",
      ["transactionreference"] => string(10) "23-9-80001",
      ["merchantname"] => string(13) "Test Merchant",
      ["paymenttypedescription"] => string(10) "CASHTOCODE",
      ["baseamount"] => string(4) "2500",
      ["accounttypedescription"] => string(4) "ECOM",
      ["requesttypedescription"] => string(4) "AUTH",
      ["currencyiso3a"] => string(3) "EUR",
      ["errormessage"] => string(2) "Ok",
      ["operatorname"] => string(23) "[email protected]",
      ["settlestatus"] => string(2) "10",
      ["redirecturl"] => string(23) "https://example.com"
    }
  }
}
{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 11:32:44","livestatus":"0","settleduedate":"2016-12-07","errorcode":"0","transactionreference":"23-9-80001","merchantname":"Test Merchant","paymenttypedescription":"CASHTOCODE","baseamount":"2500","accounttypedescription":"ECOM","requesttypedescription":"AUTH","currencyiso3a":"EUR","errormessage":"Ok","operatorname":"[email protected]","settlestatus":"10","redirecturl":"https:\/\/example.com"}],"secrand":"zO9"}
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
  <requestreference>Xmn8q5t0k</requestreference>
  <response type="AUTH">
    <merchant>
      <merchantname>Test Merchant</merchantname>
      <operatorname>[email protected]</operatorname>
    </merchant>
    <transactionreference>72-87-114</transactionreference>
    <timestamp>2017-05-31 13:15:40</timestamp>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <settlement>
      <settleduedate>2017-05-31</settleduedate>
      <settlestatus>10</settlestatus>
    </settlement>
    <billing>
      <amount currencycode="EUR">2500</amount>
      <payment type="CASHTOCODE"/>
    </billing>
    <live>0</live>
    <other>
     <redirecturl>https://redirecturl.com</redirecturl>
    </other>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
  </response>
  <secrand>50uacO</secrand>
</responseblock>

 

Field specification

Field Format Description
accounttypedescription
XPath: /operation/accounttypedescription
Alpha (20) The value returned is “ECOM”.
baseamount
XPath: /billing/amount
Numeric (5) The amount of the transaction in base units, with no commas or decimal points, so €10 is returned as 1000.
currencyiso3a
XPath: /billing/amount/@currencycode
Alpha (3) For Cash to Code, “EUR” is returned.
errorcode
XPath: /error/code
Numeric (1-5) The error code should be used to determine if the request was successful or not.

  • If the error code is “0” then the transaction was successful.
  • If the error code is not “0” then the transaction was not successful.

Click here for a full list of errorcode and message values.

errordata
XPath: /error/data
Alphanumeric (255) Additional information to help troubleshoot the error.
errormessage
XPath: /error/message
Alphanumeric (255) This is the corresponding message to the above code.

Click here for a full list of errorcode and message values.

livestatus
XPath: /live
Numeric (1)
  • 0 – Transaction processed using a test account.
  • 1 – Transaction processed using a live account.
merchantname
XPath: /merchant/merchantname
Alphanumeric (255) These are details associated with the account used to process the transaction.

To amend these fields, please contact our Support Team.

operatorname
XPath: /merchant/operatorname
Alphanumeric (255) The value of this field contains the name of the user that processed the request.
paymenttypedescription
XPath: /billing/payment/@type
Alpha (20) This value returned is “CASHTOCODE”.
redirecturl
XPath: /other/redirecturl
URL (255) Redirect the customer’s browser to this URL, to allow them to complete the payment on the Cash to Code-hosted pages.
requesttypedescription
XPath: /@type
Alpha (20) The value returned is “AUTH”.
settleduedate
XPath: /settlement/settleduedate
Date YYYY-MM-DD The date on which the transaction will be settled.
settlestatus
XPath: /settlement/settlestatus
Numeric (3) This allows you to determine the status of the payment. Refer to the Handling the response section below for information on how to best interpret this field.
transactionreference
XPath: /transactionreference
Alphanumeric including
hyphens (25)
A unique reference for the transaction assigned by Trust Payments.
transactionstartedtimestamp
XPath: /timestamp
Date time YYYY-MM-DD hh:mm:ss The time the transaction was processed.

 

Handling the response

Following a successful AUTH:

URL
The settlestatus value will remain “10” until the customer completes the payment.

In order to proceed with the payment, you must redirect the customer’s browser to the redirecturl returned in the AUTH response, as explained below.

 

If the errorcode is NOT “0” or the settlestatus is NOT “10”:

When interpreting the response, we recommend following our best practices.


 

2. Redirect to Cash to Code

If the AUTH response returned indicates the request was successful (errorcode is “0”), redirect the customer to the redirecturl returned in the response by following the instructions below.

 

Process overview

 

Testing

 


 

3. Settlement

Info
The settlestatus will remain with value “10” (indicating settlement has yet to be completed) until the customer goes to a retail outlet and completes the payment with cash. If the customer never completes the payment, the settlestatus will remain as “10” indefinitely.

 

For this reason, we strongly advise against providing goods or services to the customer until the settlestatus has been updated to “100”, indicating the customer has completed the payment.

 

Redirect back to your website

If the customer still has their browser open on Cash to Code’s pages after they have paid in cash and the payment has been completed, they will be provided with the option to click through to the page specified in the successfulurlredirect field. On this page, we recommend displaying a success message.

Info
As soon as the customer receives their unique code from Cash to Code, they are free to close their browser, and as such, may not view the page specified in the successfulurlredirect field after they have paid at the retail location.
Info
Please check for any URL redirect rules that may be enabled in the MyST Rule manager on your site reference(s), as these may conflict and take precedence over the successfulurlredirect and errorurlredirect fields submitted in the AUTH request.

 

URL notifications

Updates on the status of Cash to Code payments are performed on an hourly basis. To keep you informed of developments, we recommend contacting our Support team and request that URL notifications for Cash to Code are enabled on your account. URL notifications are sent in the following scenarios:

You will be asked to provide a destination endpoint URL
(e.g. “https://yoursite.com/cashtocode.php”), along with a list of fields you would like to be included in the notification.

 

Configuring the authorisation notification

We recommend including at least the following fields in URL notifications sent on authorisation:

 

Configuring the settlement notification

After the customer completes the payment by going to a retail outlet and paying in cash, Trust Payments will submit a URL notification to your system. We recommend including the following fields in URL notifications sent on settlement:

 

Check the notification

You will need to check the contents of each notification received and respond accordingly by following the processes outlined in the URL notifications section on the Action types page. In particular, you will need to look at the updated settlestatus value:

 


 

Additional notes