Skip to content

Getting Started

How to implement the Payment SDK

The following sections cover how to get started using Payment functionality. You can easily integrate the Payment Service by following these steps.

1. Dependencies

Open the main build.gradle file of your project and add the following dependencies:

1
2
3
4
5
6
7
dependencies {

    implementation 'com.telenav.commerce:paymentservice:${version}'

    implementation 'com.telenav.commerce:common:${version}'

}

2. Initialization of the Payment Service

The entry point to the Commerce Payment Service is the IPaymentApi which exposes the APIs reflecting the payment service functionality.

IPaymentApi is exposed to the client by the implementation of IPaymentManagerProvider → PaymentManagerProvider.

IPaymentApi

The IPaymentApi interface represents the entry point to the payment service module. It exposes APIs for accessing the payment specific features.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
interface IPaymentApi {

    val commercePayment: IPaymentCommerceApi

    val externalPayment: IPaymentExternalApi

    fun init(
        apiEndpoint: ApiEndpoint = ApiEndpoint.PRODUCTION,
        apiKey: String,
        apiKeySecret: String,
        userServiceProvider: IPaymentUserServiceProvider,
        tenantId: String,
        externalApiKey: String
    )

    suspend fun pay(
        priceInfo: PriceInfo,
        clientSecret: String,
        orderId: String
    ): CommerceResponse<String>


    suspend fun addCard(cardData: ExternalCard): CommerceResponse<Boolean>

    suspend fun deleteCard(cardId: String): CommerceResponse<Boolean>

    suspend fun getCards(
        deviceId: String = "",
        storeId: String = ""
    ): CommerceResponse<List<Wallet>>

    fun updateCard()
}


This is the concrete implementation of the IPaymentCommerceApi] used for handling payment commerce calls. 

1
val commercePayment: IPaymentCommerceApi

This the concrete implementation of the IPaymentExternalApi used for handling payment external calls.

1
val externalPayment: IPaymentExternalApi


The init method initializes the payment service (commerce payment service and external payment service). Before interacting with the payment service, the client is responsible to call this method.

The apiEndpoint parameter denotes the Commerce Service/P97 environment that we will use. The default value points to ApiEndpoint.PRODUCTION.

The apiKey parameter represents the unique key used by each integration client in order to use payment module functionality.

The apiKeySecret parameter represents the unique key used by each integration client in order to use payment module functionality together with apiKey.

The userServiceProvider parameter represents the user dependency required by payment service for proper running. View the IPaymentUserServiceProvider specifications.

The tenantId parameter represents the unique id used by each integration client in order to use the external payment module functionality.

The externalApiKey parameter represents the unique key used by each integration client in order to use the external payment module functionality.

1
2
3
4
5
6
7
8
fun init(
        apiEndpoint: ApiEndpoint = ApiEndpoint.PRODUCTION,
        apiKey: String,
        apiKeySecret: String,
        userServiceProvider: IPaymentUserServiceProvider,
        tenantId: String,
        externalApiKey: String
    )


The pay method makes the payment for the given orderId, parking reservation.

The priceInfo parameter provides information about the value that has to be retrieved from the card.

The clientSecret parameter represents a temporary token which facilitates the validation of the user in the P97 database.

The orderId parameter represents the id of the parking order.

It returns a CommerceResponse holding the payment response in a json format as String.

1
2
3
4
5
suspend fun pay(
        priceInfo: PriceInfo,
        clientSecret: String,
        orderId: String
    ): CommerceResponse<String>


The addCard method registers a new card based on the given cardData.

The cardData parameter provides the necessary data in order to register a card.

It returns a CommerceResponse holding a boolean for the register status. If it's successful, then returns "true". Otherwise, it returns "false".

1
suspend fun addCard(cardData: ExternalCard): CommerceResponse<Boolean>


The deleteCard method deletes the card based on its id.

The cardId parameter represents the id of the card that needs to be deleted.

It returns a CommerceResponse holding a boolean value. If the request is successful then it returns "true". Otherwise, it returns "false".

1
suspend fun deleteCard(cardId: String): CommerceResponse<Boolean>


The getCards method gets the cards form the payment provider. The ExternalCards are contained inside a Wallet object.

The deviceId parameter represents the id of the device being used to make te request.

The storeId parameter is optional. It returns a list of Wallets, each wallet containing a list of cards as ExternalCard.

1
2
3
4
suspend fun getCards(
        deviceId: String = "",
        storeId: String = ""
    ): CommerceResponse<List<Wallet>>

The updateCard method updates the card information.

1
fun updateCard()

IPaymentManagerProvider

The IPaymentManagerProvider interface is used for exposing an implementation of the API that should be used by the client for accessing the payment module functionality.

1
2
3
4
5
6
interface IPaymentManagerProvider {

    fun provide(): IPaymentApi

    fun provide(commerceApi: IPaymentCommerceApi, externalApi: IPaymentExternalApi): IPaymentApi
}


The provide method gets a concrete implementation object of the payment module API. View the IPaymentApi specifications.

It returns the instance that should be used by the client for accessing the payment module functionality.

1
fun provide(): IPaymentApi

This method provides a concrete implementation object of the payment module API. View the IPaymentApi specifications.

The commerceApi parameter gets the implementation for IPaymentCommerceApi.

The externalApi parameter gets the implementation for IPaymentExternalApi.

It returns the instance that should be used by the client for accessing the payment module functionality.

1
 fun provide(commerceApi: IPaymentCommerceApi, externalApi: IPaymentExternalApi): IPaymentApi

Here is the code on how to initialize payment service using the PaymentManagerProvider.

1
2
3
4
5
6
7
8
PaymentManagerProvider.provide().init(
      apiEndpoint,
      apiKey,
      apiKeySecret,
      object : IPaymentUserServiceProvider {},
      tenantId,
      externalApiKey
   )

The client is responsible to provide an implementation of IPaymentUserServiceProvider interface.

IPaymentUserServiceProvider

The IPaymentUserServiceProvider interface defines the user data related methods that are requested for a proper running of the payment service. The Client is responsible to provide an implementation of this interface.

1
2
3
4
interface IPaymentUserServiceProvider {

    fun getUserToken(): String
}

The getUserToken method retrieves the user token.

1
fun getUserToken(): String

Implementation example of the IPaymentUserServiceProvider

1
2
3
4
5
object : IPaymentUserServiceProvider {
     override fun getUserToken(): String {
        return UserWrapper.getUserToken(context)
     }
}

2.2 Initialization of the Payment Service with a IPaymentCommerceApi and IPaymentExternalApi provided by the client

If the client needs a specific SDK (network) configuration they can initialize the payment service passing their own instances of IPaymentCommerceApi and IPaymentExternalApi.

The client is responsible to provide an implementation of IPaymentUserServiceProvider interface.

1
2
3
4
5
6
7
8
ParkingManagerProvider.provide(paymentCommerceApi, paymentExternalApi).init(
      apiEndpoint,
      apiKey,
      apiKeySecret,
      object : IPaymentUserServiceProvider {},
      tenantId,
      externalApiKey
   )

IPaymentExternalApi

The IPaymentExternalApi represents the entry point in commerce service regarding the actual payment flow. It exposes the APIs needed in order to pay for a parking reservation.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
interface IPaymentExternalApi {

    val retrofitApi: IHttpApi

    val sdkConfiguration
        get() = retrofitApi.configuration

    fun setConfiguration(configuration: SdkConfiguration)

    suspend fun getPublicKey(): CommerceResponse<PublicKey>

    suspend fun addCard(encryptedCardData: String): CommerceResponse<Boolean>

    suspend fun authorize(authorizationRequestBody: AuthorizationRequestBody): CommerceResponse<String>

    suspend fun deleteCard(cardId: String): CommerceResponse<Boolean>

    suspend fun getCards(
        deviceId: String = "",
        storeId: String = ""
    ): CommerceResponse<List<Wallet>>

    fun updateCard()
}


This is the concrete implementation of the IHttpApi used for handling retrofit actions.

1
val retrofitApi: IHttpApi


This is the current configuration used for requests.

1
2
val sdkConfiguration
    get() = retrofitApi.configuration


The setConfiguration method sets the given configuration for the external payment service requests. The configuration parameter is used.

1
fun setConfiguration(configuration: SdkConfiguration)


The getPublicKey retrieves the response with the public key from the external payment service.

It returns an CommerceResponse holding a PublicKey object.

1
suspend fun getPublicKey(): CommerceResponse<PublicKey>


The addCard retreives the response with the status if the card was registered successfully.

The encryptedCardData parameter represents the encrypted card data.

It returns an CommerceResponse holding a boolean (the status of the request) or a CommerceError object if something went wrong.

1
suspend fun addCard(encryptedCardData: String): CommerceResponse<Boolean>


The authorize method requests to authorize the payment. Money are locked after we receive the response.

The authorizationRequestBody parameter contains the data we need to send in the body of the request.

It returns an CommerceResponse holding a String, the transaction id, needed to complete the payment.

1
suspend fun authorize(authorizationRequestBody: AuthorizationRequestBody): CommerceResponse<String>


The deleteCard method deletes a card from the wallet based on its id. The cardId parameter represents the id of the card to be deleted.

It returns an CommerceResponse when the call is successful.

The CommerceResponse.Success holds the "true" value.

1
suspend fun deleteCard(cardId: String): CommerceResponse<Boolean>


The getCards method gets the Wallets of the user. Each wallet contains a list of Cards.

The deviceId parameter is holding info about the device used to perform the operation.

The storeId parameter is optional.

It returns a list of Wallet where each wallet contains a list of Cards.

When it's successful it returns "true". Otherwise, it returns CommerceResponse.Failure.

1
2
3
4
suspend fun getCards(
        deviceId: String = "",
        storeId: String = ""
    ): CommerceResponse<List<Wallet>>


The updateCard method updates the card information.

1
fun updateCard()

IPaymentCommerceApi

The IPaymentCommerceApi interface represents the entry point to Commerce Service regrading the payment flow. It exposes APIs needed for accessing payment specific information.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
interface IPaymentCommerceApi {

    val retrofitApi: IHttpApi

    fun setConfiguration(configuration: SdkConfiguration)

    suspend fun getAuthorizationToken(): CommerceResponse<Token>

    suspend fun capture(orderId: String, transactionId: String): CommerceResponse<String>
}


Concrete implementation of the IHttpApi used for handling retrofit actions.

1
val retrofitApi: IHttpApi


Sets the given configuration to be used by the retrofit implementation The configuration parameter is used for requests.

1
fun setConfiguration(configuration: SdkConfiguration)

Gets the authorization token which is needed for payment external requests.

1
suspend fun getAuthorizationToken(): CommerceResponse<Token>

Capture/confirm the payment on the backend side. The transactionId parameter represents the id of the transaction given by the external payment provide.

The orderId parameter represents the id of the order to be confirmed.

It returns a String object holding the payment response in a json format.

1
suspend fun capture(orderId: String, transactionId: String): CommerceResponse<String>