Gateway Android SDK Documentation

• Basic Transaction Lifecycle
  • Components
  • Steps
• Implementation
• 3-D Secure Authentication
• Google Pay
• Tokenization

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

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);

3-D Secure Authentication

3-D Secure Authentication provides an extra layer of security by requiring card holders to authenticate a transaction with their card issuer. The SDK supports 3DS 1.0 by providing a web view to help complete the authentication process.

For more information, visit the 3-D Secure Authentication wiki page

Google Pay

For more information on integrating Google Pay with the Gateway SDK, refer to the Google Pay wiki page

Tokenization

The SDK provides support to update a Session with card information, and you can use that Session to perform several operations with the Gateway. Tokenization provides a way to retain a card on file, and can be performed on your server with a valid Session. To use the mobile SDK to facilitate creating a card token, follow these steps:

1. Create and Update a Session using the SDK as illustrated in steps 1 - 6 above.
2. Return the Session Id to your server and call the Create or Update Token method on the Gateway with your private API credentials.
3. A token id is returned and can be retained on your servers as a card-on-file.