Home

Gateway Android SDK Documentation

Basic Transaction Lifecycle

Components

• Merchant Mobile App: A mobile app integrated with the Gateway Mobile SDK
• Merchant Web Service: A web service, hosted and maintained on the merchant's servers, which will handle sending authenticated requests to the Gateway.
• Gateway: An instance of your Gateway provider.

Steps

1. The mobile app requests a new Session from the merchant service. This is an authenticated call, meaning it requires a private API password, which is why it needs to be carried out on a secure server, rather than the mobile device.
2. The merchant service calls Create a Session on the Gateway.
3. Information about the newly created session is returned to the merchant service, including the Session Id.
4. The Session Id + the version of the API used to create it is returned back to the mobile app. Updating the session with card details must use the same Gateway API version number that created it.
5. Card information is collected from the card holder and sent directly to the Gateway using the SDK method provided.
6. A success / fail message is returned to the app in the appropriate callback method.
7. The app then requests to complete the transaction with the merchant service.
8. The merchant service performs the appropriate transaction operation with the Gateway.
9. The Gateway returns the summary of the transaction attempt to the merchant service.
10. The success / fail status is returned to the mobile app.

Implementation

To help alleviate the worry of passing card information through your servers, the SDK provides a method to update a session with card data directly with the Gateway. Using an existing Session Id, you may pass card information directly to the Gateway object:

GatewayCallback callback = new GatewayCallback() {
    @Override
    public void onSuccess(GatewayMap response) {
        // TODO handle success
    }

    @Override
    public void onError(Throwable throwable) {
        // TODO handle error
    }
};

String sessionId = "...";
String apiVersion = "..."; // must be >= 39

// The GatewayMap object provides support for building a nested map structure using key-based dot(.) notation.
// Each parameter is similarly defined in your online integration guide.
GatewayMap request = new GatewayMap()
    .set("sourceOfFunds.provided.card.nameOnCard", nameOnCard)
    .set("sourceOfFunds.provided.card.number", cardNumber)
    .set("sourceOfFunds.provided.card.securityCode", cardCvv)
    .set("sourceOfFunds.provided.card.expiry.month", cardExpiryMM)
    .set("sourceOfFunds.provided.card.expiry.year", cardExpiryYY);

gateway.updateSession(sessionId, apiVersion, request, callback);