Business and Technical Decisions
Integrating a new Platform within the Cashier requires the Platform to have an API exposing the necessary web services to be consumed by the Cashier. During the Platform’s web service development phase , we normally recommend it to be handled over the Internet as it allows for faster iterations between your Platform team and our Cashier team. Once this testing phase is completed, we can proceed to installing the Cashier into your computing environment and run more tests as API integration is essentially completed. This would typically be an internal LAN communication between the Cashier and your Platform, offering the benefits of a faster, more secure, direct connection between both applications.
To implement your API web service, you can choose your coding language of preference as long as you support HTTPS POST and are web friendly. You also have your choice of the request/response of your web service between: raw HTTP Post, JSON, XML or SOAP XML, etc. We do not recommend using RESTful HTTP status codes but instead return an HTTP 200 OK status when your web service was able to accept and process the request, and if any application errors occurred, then return those details in the web service response body in your chosen format (e.g. serialized response either querystring, XML or JSON). If possible your API should always return an accurate reason for any service method failure, which facilitates troubleshooting issues in production to the business operators.
The Cashier offers flexibility in handling 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:
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 the payout requests and allows making 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 are unable to cancel the 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.
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 as long as the customer’s account has not been officially debited yet. 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 sure that your Platform can handle that the amount and/or fee passed from CreatePayout can be different from 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)|
Below are some typical examples of payout status changes and flow:
E.g. Payout authorized and processed
E.g. Payout rejected by operator or cancelled by customer prior to Authorization
E.g. Payout automatically rejected prior to processing due to insufficient funds in customer account
E.g. Payout reversed after attempted processing (batch or API) due to mistake or later rejection
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 visiting 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 ‘MyPhoneCards.com’ 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 the choice is locked-in. When visiting the Cashier, the customer should be linked to the correct Front End in the cashier with the corresponding combination of the web-site and currency.
|Customer ID||Currency||Website||Cashier Front End|
Our Cashier works with over 300 different payment providers. Merchants usually have multiple processing accounts, some with multiple accounts from the same provider. Our Cashier uses a string up to 25 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:
Be sure to review this within your implementation discussion.
You are currently viewing version 3.1 Latest API version here