API Integration: DirectCashier

Introduction & Document Overview

This is a documentation for the DirectCashier API, a service within the Payment Management Solution set of the GIDX Platform.

This set of documents serves as the integration guide for implementing services of the GIDX Platform API within the operator’s environment. The following pages outline the Customer Insight access points, security, methods, and parameters. As always, please contact us at devteam@tsevo.com any time if further explanation is needed.

GIDX Platform DirectCashier API Method Reference

Below are descriptions of the methods exposed by the GIDX Platform DirectCashier Service. For details about the parameters associated with these methods please see the Class Reference section below.

DirectCashier: Request & Response Parameter Constants

The following parameters are used in every DirectCashier Method Request and Responses. They are labeled within the methods below as Standardized Request Parameters and Standardized Response Parameters.

Making a Request
Each API method has a corresponding Request object used to transport the request parameters as shown below.

Using the Response
Each Response object returned from the method Request will contain properties you can use to determine the status of the methods service. Use the IsSuccess property along with the ResponseCode and ResponseMessage values to detect if the Request completed without a problem.

CustomerIdentity API Methods

Other Identity & Location Methods are located in the CustomerIdentity API located at the endpoint below.

Endpoint URL:

https://api.gidx-service.in/v3.0/api/CustomerIdentity

Response Object Reference

The Object documented below are returned within the Response of Method Request within the GIDX Platform DirectCashier Services. When applicable an Object may be shared by among other Method Responses as indicated in the listings below.

Objects are always returned in JSON format.

Cashier Object: Action

This object provides information on actions that need to be taken within the merchant application to complete the transaction.

Usage:

CompleteSessionDirectCashierResponse (Action)

Cashier Object: PaymentDetails

PaymentDetails object is currently a work in progress. Subject to change.

This object contains the detailed data of a transaction that has taken place within the DirectCashier CreateSession Request.

Returned in Response:

CompleteSession

PaymentDetail

Usage:

The results contained in this object provide your the transaction amount(s), payment method, and other important transaction data parameters and statuses of a DirectCashier Service.

Cashier Object: CashierPaymentAmount

This object contains the payment amount information. For deposits, the user will be charged PaymentAmount + FeeAmount + TaxAmount.

For FeeAmount and TaxAmount, if you don't provide them yourself, we will calculate them based on your settings.

Usage:

CreateSessionDirectCashierRequest (PaymentAmounts)

CompleteSessionDirectCashierResponse (PaymentAmount)

Cashier Object: PaymentMethod

This object is used to both submit and retrieve payment method information.

Usage:

CreateSessionDirectCashierResponse (PaymentMethods)

CompleteSessionDirectCashierRequest (PaymentMethod)

Cashier Object: PaymentMethodSettings

A list of these objects is returned by CreateSession to show you what PaymentMethodTypes you have available.

Only Paypal and GooglePay have additional settings (as shown below), but CreateSession will return an object for every PaymentMethodType you have available. For types other than Paypal and GooglePay, the object will just have a single Type property.

Usage:

CreateSessionDirectCashierResponse (PaymentMethodSettings)

Cashier Object: BillingAddress

Location Object: DeviceGPS

This object should contain the location data derived from the Devices GPS information.

For more information on collecting this data from the Device please click here   to see the table below for both iOS and Android.

Appendix Library: Code / Status Index

The information documented below provides clarification of the codes used within the GIDX Platform DirectCashier Services.

Appendix Library: ResponseCodes & ResponseMessage

Appendix Library: Session StatusCode

Appendix Library: Session ServiceType

Appendix Library: PaymentStatusCode (TransactionStatusCode)

The PaymentStatusCode will be provided when a GIDX service is updating you about a transaction DirectCashier Callback and/or the PaymentDetails method is being called because details/status of the transaction is needed.

In most instances, the PaymentStatus of Pending, Complete, or Failed will be provided, for example...

Pending:

The transaction is in a holding state within the GIDX service for a pre-defined reason such as: the customer needs to complete the ID verification process before the transaction is sent to the bank/processors for processing.

Complete:

The transaction has been completed by the customer and the bank/processor.

Failed:

The processing of the transaction failed at the bank/processor. The details of why the transaction failed are not always provided from the bank/processor in real-time but are updated and viewable in the dashboard as soon as it is provided.

The following PaymentStatus are less common and have specific caveats to their inclusion, for example...

Ineligible:

The transaction was not processed due to reasons associated with the bank/processor. This status is applicable to non-gaming related transactions only.

Reversed:

The transaction was processed but due to reasons associated with the bank/processor it was subsequently reversed - similar to Ineligible but associated with transactions flagged post processing. This status is applicable to non-gaming related transactions only.

Canceled:

The transaction was canceled. Currently applies to the cancellation of recurring transactions.

Processing:

The transaction has been sent for processing at the bank/processor but the response has not been provided. This is a very "edge case" scenario that may occur if the PaymentDetails method is called AFTER the GIDX service begins the processing of a transaction at a bank/processor and BEFORE that bank/processor completes the "processing" of the transaction and provides a response of that process. If this PaymentStatus is returned then the common practice should be to wait 10 to 20 seconds and make the PaymentDetails call again (or wait for the Callback).

Payment Not Found:

The status of "Payment Not Found" would be provided back if the Transaction ID provided in the PaymentDetails method call could not be found.

Appendix Library: PaymentAmountType

Appendix Library: PaymentMethodType

Appendix Library: PaymentAmountCode

Appendix Library: PayActionCode

Appendix Library: RecurringInterval

Appendix Library: AVSResult

Appendix Library: CVVResult

Appendix Library: Data & System Reference

ISO 3166-1 is part of the ISO 3166 standard published by the International Organization for Standardization (ISO), and defines codes for the names of countries, dependent territories, and special areas of geographical interest.
http://en.wikipedia.org/wiki/ISO_3166-1

ISO 3166-2:US is the entry for the United States in ISO 3166-2, part of the ISO 3166 standard published by the International Organization for Standardization (ISO), which defines codes for the names of the principal subdivisions (e.g., provinces or states) of all countries coded in ISO 3166-1.
http://en.wikipedia.org/wiki/ISO_3166-2:US

The ISO 4217 code list is used in banking and business globally. In many countries the ISO codes for the more common currencies are so well known publicly that exchange rates published in newspapers or posted in banks use only these to delineate the different currencies, instead of translated currency names or ambiguous currency symbols.
https://en.wikipedia.org/wiki/ISO_4217

For the latest list of Reason Codes and their description please go to the following URL.
View Reason Codes

Payment Method Workflows

Below are descriptions of how each Payment Method is handled by CompleteSession.

ACH

ACH payments are not immediate and will be left in a Pending state at first. In the live environment, you will get a callback when the status is changed. In sandbox, you can manually set the status to Complete in the dashboard and you will receive a callback.

Expected Actions: None

ACH with Actum Authentecheck

Actum Authentecheck allows the user to login to their bank and select their bank account instead of typing the account and routing numbers themselves.

Sending a blank ACH payment method (no AccountNumber and RoutingNumber) will return an Open Action with a URL that you need to open in a new window or tab on the user's device in order to complete the payment.

The selected bank account will be saved for re-use. They will not need to login to their bank on future transactions.

Expected Actions: Open

RedirectURL

Pass a RedirectURL in your CreateSession request if you want the user to be redirected to your site at the end of the Authentecheck process.

The following values will be appended as query string values to the RedirectURL: MerchantSessionID, MerchantTransactionID

In your RedirectURL, you can make an API call to PaymentDetail to get the status.

Test Bank Login

You can use the test bank login below. This specific test bank requires you to confirm the Routing and Account Numbers, but that's not how most major banks will behave.

Bank

Houndstooth Bank

Username

user_good

Password

pass_good

Account

Plaid Saving (****1111)

Routing #

021000021

Account #

1111222233331111

Credit Card

When using a saved credit card, you must ask the user to re-enter their CVV and pass it in the request as shown in the sample.

Expected Actions: None

Credit Cards with 3DS

To use 3DS for credit card deposits, you should populate the ThreeDS object in the PaymentMethod. ThreeDS is only used in the CompleteSession API. It is ignored when sent to any other API endpoint.

You can get these 3DS values by integrating into a Javascript SDK that provides them:

• PAAY

Expected Actions: None

Paypal

Paypal deposits will require you to use Paypal's SDK (JS, iOS, or Android) after you call CompleteSession, using the OrderID returned in the Action.

When any of the SDKs ask for a Client ID, make sure you are using the one associated with the GIDX app within your Paypal developer account.

Expected Actions (Deposits): Paypal
Expected Actions (Payouts): None

JS

First, add a Paypal button to your page.

The JS for the button should look like this:

                    
paypal.Buttons({
    createOrder: (data, actions) => {
        //Call CompleteSession and return the OrderID that is inside the Paypal Action
        return getCompleteSessionResponse()
            .then(function (response) {
                return response.Action.OrderID;
            });
    },
                        
    onApprove: (data, actions) => {
        //There is no need to manually capture the order here as shown in Paypal's own sample.
        //GIDX will be notified when the order is approved and automatically capture it.
                                
        //Here, you can call PaymentDetail to get the latest transaction status and inform the user.
    }
}).render('#paypal-button-container');
                        
                    

iOS

First, add the Native Checkout SDK to your iOS app.

Add a Paypal button, or programmatically start the SDK.

Follow the instructions in their Server-Side Integration section to set CreateOrder and OnApprove callbacks like this:

                    
Checkout.setCreateOrderCallback { createOrderAction in
    //Call CompleteSession and use the OrderID that is inside the Paypal Action
    createOrderActions.set(orderID)
}

Checkout.setOnApproveCallback { approval in
    //There is no need to manually capture the order here as shown in Paypal's own sample.
    //GIDX will be notified when the order is approved and automatically capture it.

    //Here, you can call PaymentDetail to get the latest transaction status and inform the user.
}
                        
                    

Android

First, add the Native Checkout SDK to your Android app.

Add a Paypal button, or programmatically start the SDK.

Follow the instructions in their Server-Side Integration section to set CreateOrder and OnApprove actions like this:

                    
paymentButton.setup(
    new CreateOrder() {
        @Override
        public void create(@NotNull CreateOrderActions createOrderActions) {
            //Call CompleteSession and use the OrderID that is inside the Paypal Action
            String orderID;
            createOrderActions.set(orderID);
        }
    }
);

paymentButton.setup(
    new OnApprove() {
        @Override
        public void onApprove(@NotNull Approval approval) {
            //There is no need to manually capture the order here as shown in Paypal's own sample.
            //GIDX will be notified when the order is approved and automatically capture it.

            //Here, you can call PaymentDetail to get the latest transaction status and inform the user.
        }
    }
);
                        
                    

Apple Pay

Apple Pay deposits will require you to use Apple's SDK (JS, or iOS) after you call CreateSession. You will then serialize the Payment object returned by Apple to a JSON string, and pass it to CompleteSession.

Sample code available here

Apple Pay JS API Docs

Apple Pay iOS API Docs

Interactive Apple Pay JS Demo

Expected Actions: None

Google Pay

Google Pay deposits will require you to use Google's SDK (JS, or Android) after you call CreateSession. You will then serialize the PaymentData object returned by Google to a JSON string, and pass it to CompleteSession.

Sample code available here

Google Pay API Docs

Expected Actions: None