Praxis Wiki logo

Overview Payout Management

When to Debit the Customer’s Account for a Payout

The Cashier offers flexibility in the handling of payout transactions with your Platform. Determining when a payout is debited has an impact on your customer experience and business processes. Using the Front End Option setting “Payout debited upon event” you have the choice of debiting the customer account at the point of:

  • Payout Requested (CreatePayout)
  • Payout Authorized (UpdatePayout – status Authorized)
  • Payout InProgress (UpdatePayout – status InProgress)

The Cashier uses this setting to know when the balance of the customer will be debited and when to mark the payout transaction as debited within its system. This is important due to rules the Cashier manages on whether or not a payout amount or fee can be edited and for determining checks for ensuring the customer’s balance has sufficient funds for the payout request.

Customers’ who request a payout can be prevented from depositing in the Cashier while they have payout requests that have not reached the Authorized status. If that is the case, the Cashier allows them to cancel their payout requests and allows them to make another deposit. The customer’s balance is debited for their payout at one of the status stages described above.

If you debit the customer’s balance upon the initial Payout Request, the customer is unable to spend that payout amount requested from their balance as it is reserved for their payout. This setting usually benefits the customer over the merchant as the customer cannot accidentally spend those funds intended for the payout and run into an insufficient funds issue when the payout is about to be processed. It also forces a restriction in the Cashier’s Backoffice that the payout amount and fee cannot be changed which makes it less flexible for the operator to manage payout requests. We normally do not recommend this option.

If you debit the customer’s balance at Payout Authorized, this prevents customers from cancelling their payout once the G.R.A.M. approvals are set via the Payout Manager. As a merchant, if you are not quick to process payouts at this stage, then the customers are unable to access those funds locked into the payout request and neither can they cancel their payout request. Merchants must either process the payout or reject it.

If you debit the customer’s balance at Payout InProgress, this allows the customer the flexibility to access their full balance up until the time the payout is to be processed. This setting usually benefits the merchant over the customer as it allows the customer to ‘spend’ their funds and may result in their payout being rejected by the merchant for insufficient funds. This is the default option.

Knowing what is best for your business and your customer experience will determine the right setting for you.

Handling Changes in Payout Transaction Detail

All payout requests are queued into the Payout Manager in the Backoffice. From the Payout Manager, the original payout request can be modified, including the payment processor, requested payout amount and applicable fee.

The payment processor (PP) value can change as the payout moves from Requested to Approved. At the time the payout is requested the customer can indicate their payout method such as we see for a credit card payout (e.g. CFT, CCPayout etc.) and it is not until the payout transaction has reached the Approved status do we have the actual payment processor that has fulfilled the payout. This scenario also applies to bank wires, check providers and money transfer solutions.

We can restrict the ability to alter the payout amount and fee prior to the payout reaching the Authorized status so long as the customer’s account has not been officially debited. We do recommend that you permit this functionality as it gives you and your team more flexibility in handling payout requests. If you allow this flexibility, then be certain that your Platform can handle that the amount and/or fee passed from CreatePayout can be different to the amount and/or fee passed on UpdatePayout(“Authorized”). If the payout has already been marked as debited within your Platform or has reached the Authorized status, then neither the amount nor fee can be edited.

The table below illustrates when certain variables are created (introduced) and when they could change based on the status of the payout. Be sure to consider these value changes when updating your payout transactions on your Platform.

Web Method CreatePayout UpdatePayout (updates to one of the statuses listed below)
Variable\Status Requested Authorized InProgress Approved
PP Created Change
Amount Created Change
Fee Created Change
TransactionID Empty Created

Flow examples

Below are some typical examples of payout status changes and flow:

E.g. Payout authorized and processed

  1. CreatePayout
  2. UpdatePayout(“Authorized”)
  3. UpdatePayout(“InProgress”)
  4. UpdatePayout(“Approved”)

E.g. Payout rejected by operator or cancelled by customer prior to Authorization

  1. CreatePayout
  2. UpdatedPayout(“Cancelled’)

E.g. Payout automatically rejected prior to processing due to insufficient funds in customer account

  1. CreatePayout
  2. UpdatePayout(“Authorized”)
  3. UpdatedPayout(“Rejected”)

E.g. Payout reversed after attempted processing (batch or API) due to mistake or later rejection

  1. CreatePayout
  2. UpdatePayout(“Authorized”)
  3. UpdatePayout(“InProgress”)
  4. UpdatePayout(“Approved”)
  5. ReversePayout

Customer Synchronization (Push vs. Pull)

The customer information is an important part of the payment process and having complete and accurate customer information can mean the difference between a successful deposit or a rejected deposit. The Cashier system needs this customer information in order to allow customers to make a deposit or request a payout.

For merchants with an established customer base, it can be easier to create a one-time customer data dump for preloading the Cashier’s database. The data to be loaded must conform to our data scrubbing requirements. Please review the - Standard Data Scrubs.docx for more info. Please contact us if you wish to learn more about this option.

When a customer registers for a new account in your system or there are changes or edits to their information, you should synchronize your customer’s information with the Cashier system. If your Platform makes a distinction between accounts for fun and real money, then we suggest you only send to the Cashier real money accounts. To synchronize customers between your Platform and the Cashier there are two strategies: either PUSH or PULL

Push (deprecated)
  1. Your system will PUSH to the Cashier the newly created or recently edited customers
  2. After a customer signs up to your platform or changes are made to their information, your programmers can implement an automated server to server HTTP POST to a specified Cashier URL posting the customer’s information
  3. The Cashier system will respond OK or a list of error(s) if data submitted does not pass basic validations.
  4. See Push Customer Data for details.
  1. The Cashier will invoke your web service to retrieve customer details for a customer visiting the Cashier.
  2. Your developers need to include a web service method to return details for a specific customer. See GetCustomer

In cases where the customer information is incomplete or does not pass our standard data scrub requirements, the Cashier will automatically provide a customer details form for the customer to review and correct their information upon entering the Cashier system. The Cashier can also push changes of customer information originating within the Cashier to your platform via the UpdateCustomer call. If you implement this feature, be sure that this does not trigger a subsequent ‘push’ of the same customer data back to the Cashier.


Our Cashier establishes a base currency unit for each Cashier Front End. A customer that belongs to a Front End will inherit that base currency. And any deposit or payout transactions will always be recorded in that base currency. So, if you have a website that allows customers to choose from more than one currency, then you will have a Front End in the Cashier for each currency supported by your website.

If a customer from website A has a balance maintained in EUR, then when that customer visits the Cashier,he or she should be directed to Website A’s EUR Front End in the Cashier.

E.g. Merchant has a website called ‘’ and offers customers to register and select from one of three currencies (USD, EUR and GBP). When that customer registers and selects their chosen currency, they have locked-in that choice. When visiting the Cashier, you must ensure to link that customer to the correct Front End in the cashier for your website and currency combination.

Customer ID Currency Website Cashier Front End
Bigdaddy EUR MyPhoneCards EUR
NeverDull USD MyPhoneCards USD
Win4Real GBP MyPhoneCards GBP

Customer Authentication

As the Cashier is a separate web application, it does require the ability to securely authenticate your customers as they arrive to the Cashier. The Cashier can display customer information, balance information, payment information and this can only be displayed following a successful customer authentication step. This is accomplished by posting login credentials of the customer against the Cashier login page. See Linking to the Cashier and AuthCust web service. The parameters to authenticate the customer are:

  • PIN
  • Password

The Cashier will use this information to authenticate the customer via the AuthCust API method. You can use the static password, one-time password or session identifier. Consider that any value that you are sending as Password, you must be able to verify it’s validity and correspondence to the PIN value that you receive within the AuthCust request.

Payment Processors

Our Cashier works with over 150 different payment providers. Merchants will often have multiple processing accounts, some with multiple accounts from the same provider. Our Cashier uses a short text string up to 10 characters long to identify the source of transactions. How these transactions appear in your Platform can be vitally important for your own reporting and risk management processes. Mapping these processors from the Cashier to your Platform can sometimes be a stumbling block as adding a new payment processor to the Cashier, may require a similar addition to your Platform. If naming conventions are different between the two, then some ‘mapping’ or ‘translation’ between the two systems may be required that is typically handled at code level within your “UA_*.asp” file. Here are some examples of common processor names in the Cashier:

  • NETeller
  • WireCard
  • WireCard8 (for most credit card providers we allow multiple accounts from 1-99)
  • Paysafe
  • Skrill
  • BankWire

Be sure to review this within your implementation discussion.

You are currently viewing version 2.24b Latest API version here