- Ghid de integrare
- SDK Mastercard Gateway Android
SDK Mastercard Gateway Android
Instalare
Acest SDK este structurat ca un depozit maven. Trebuie dezarhivat într-o locație din cadrul proiectului dvs. și adăugat ca depozit în fișierul build.gradle al proiectului.
- De pe portalul Merchant Admin, descărcați cea mai recentă versiune a SDK-ului într-un format de fișier ZIP.
- Dezarhivați acest fișier în directorul rădăcină al proiectului dvs. Android. (De exemplu, ~/my-android- project/gateway- repo)
- Adăugați o referință la acest depozit local în fișierul
build.gradleal proiectului dvs. - În fișierul
build.gradledin modulele aplicației dvs., includeți SDK-ul gateway-ului ca dependență.
Pentru mai multe informații despre descărcarea SDK-ului, consultați Integrarea Mobile SDK.
// build.gradle
allprojects {
repositories {
mavenCentral()
google()
// Gateway Android SDK repo
maven {
url "$rootDir/gateway-repo"
}
}
}
// app/build.gradle implementation 'com.mastercard.gateway:Mobile_SDK_Android:x.x.x'
Directorul Mobile_SDK_Android conține un fișier maven-metadata.xml care conține informații pentru construirea referinței de implementare pentru bibliotecă. Formatul de gradle de implementare este implementation <groupId>:<artifactId>:<version>
Inițializați SDK
Inițializați SDK-ul Android înainte de utilizare. Se recomandă efectuarea acestei operațiuni în clasa dvs. de aplicație personalizată din metoda onCreate() .
// CustomApplication.kt
override fun onCreate()
{
super.onCreate()
// init Gateway SDK
GatewaySDK.initialize
(
this,
"YOUR_MERCHANT_ID",
"Your Merchant Name",
"https://your-merchant-url.com",
"Your gateway region",
callback
)
}
Prezentare generală sesiune
Fluxul SDK pentru gateway se bazează pe conceptul de sesiune. O sesiune este un container temporar pentru orice câmpuri de solicitare și valori ale operațiunilor care fac referire la o sesiune. Pentru mai multe informații, consultați Sesiunea de plată în documentație.
Avantaje cheie
- Reduce costurile de conformitate PCI, nefiind necesar ca dvs. să stocați sau să manipulați niciun fel de detalii de plată.
- Facilitează integrarea, deoarece nu este necesar ca dvs. să manipulați direct valorile pentru câmpurile solicitării stocate în cadrul sesiunii.
- Reduce fraudele interne, personalul dvs. având acces limitat la detaliile plătitorului.
- Vă permite să actualizați câmpurile de solicitare și valorile stocate cu ajutorul unei sesiuni. Această caracteristică este utilă atunci când un card de credit expiră sau alte detalii ale plătitorului se modifică.
- Vă permite să colectați câmpurile de solicitare și valorile conținute într-o sesiune specificând identificatorul de sesiune.
Creați o sesiune
Creați o sesiune cu gateway-ul pentru a iniția procesul de plată pe un dispozitiv mobil.
- Două apeluri API trebuie efectuate pentru pregătirea sesiunii în vederea tranzacțiilor mobile.
- Aceste apeluri sunt securizate cu o parolă API și, prin urmare, trebuie realizate de pe serverul dvs. privat.
| Parametru solicitare | Exemplu |
|---|---|
| authenticationLimit | 25 |
Actualizați sesiunea
| Parametru solicitare | Existență | Exemplu |
|---|---|---|
| order.id | Obligatoriu | ID-ul comenzii dvs. |
| order.amount | Obligatoriu | 1.23 |
| order.currency | Obligatoriu | AUD |
| authentication.acceptVersions | Obligatoriu | 3DS2 |
| authentication.channel | Obligatoriu | PAYER_APP |
| authentication.purpose | Obligatoriu | PAYMENT_TRANSACTION |
Odată ce ați creat o sesiune pe server, trebuie să
- returnați informațiile sesiunii în aplicația mobilă și să
- creați o instanță a obiectului
Session.
// example
val session = Session(
id = "your-session-id",
amount = "1.23",
currency = "USD",
apiVersion = "61", // api version used to create the session
orderId = "your-order-id" // must match order id used on your server
)
Colectarea informațiilor cardului
Metoda SDK pentru updateSession este opțională, dar este recomandată pentru sfera de aplicare a PCI pe serverul comerciantului. Informațiile cardului și simbolului pot fi, însă, încărcate printr-un alt design API și trebuie să fie prezente în sesiune înainte de realizarea unui apel în SDK pentru autentificarea plătitorului.
Introducerea manuală a cardului
Transmiteți informațiile direct către gateway folosind un ID de sesiune existent.
// 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.
val request = 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);
GatewayAPI.updateSession(session, request, callback);
Crearea de simboluri
SDK-ul permite actualizarea unei sesiuni cu informațiile cardului; puteți utiliza sesiunea respectivă pentru a efectua mai multe operații pe gateway. Crearea de simboluri este o metodă de a păstra un card în arhivă și poate fi efectuată pe serverul dvs. cu o sesiune validă.
Urmați acești pași pentru a utiliza Mobile SDK pentru a facilita crearea unui simbol de card.
- Creați și actualizați o sesiune în SDK.
- Actualizați sesiunea cu detaliile cardului clientului folosind metoda Gateway SDK.
GatewayAPIupdateSession. - Returnați ID-ul sesiunii la server și apelați metoda Create or Update Token pe gateway folosindu-vă acreditările private din API.
- Este returnat un ID de simbol, care poate fi păstrat pe serverele dvs. drept card arhivat.
Pentru mai multe informații referitoare la crearea simbolurilor, consultați documentația pentru Create or Update Token.
Google Pay
SDK-ul gateway-ului include un utilitar asistent, numit GooglePayHandler, pentru colectarea informațiilor cardurilor dintr-un portofel electronic Google Pay.
Configurație
Pentru a activa compatibilitatea cu Google Pay în aplicația dvs., consultați documentația Google Pay.
Aceste instrucțiuni ar trebui să vă ghideze cum să:
- configurați API-ul Google Pay
- solicitați informațiile de plată de la portofelul electronic Google
- încorporați butonul în dispunerea dvs. și
- gestionați răspunsul de la API-ul Google Pay.
Deoarece integrarea Google Pay este opțională în SDK-ul gateway-ului, trebuie să furnizați dependența adecvată pentru serviciile de plată.
implementation 'com.google.android.gms:play-services-wallet:X.X.X'
Gateway-ul este integrat cu Google Pay ca tip PAYMENT_GATEWAY.
Pentru a solicita informații criptate despre card de la Google Pay
- utilizați numele valid
mpgsîn solicitarea dvs. și - înlocuiți
YOUR_MERCHANT_IDcu ID-ul de comerciant pe care îl utilizați pe gateway.
val tokenizationSpecification = JSONObject()
.put("type", "PAYMENT_GATEWAY")
.put("parameters", JSONObject()
.put("gateway", "mpgs")
.put("gatewayMerchantId", "YOUR_MERCHANT_ID"))
Solicitarea informațiilor de la portofelul electronic
Utilizați GooglePayHandler pentru a lansa portofelul electronic Google Pay cu clientul de plăți construit și datele de solicitare.
// YourActivity.kt
fun googlePayButtonClicked()
{ try {
val request = PaymentDataRequest.fromJson(paymentDataRequest.toString())
// use the Gateway convenience handler for launching the Google Pay flow
GooglePayHandler.requestData(this, paymentsClient, request)
} catch (e: JSONException) {
Toast.makeText(this, "Could not request payment data", Toast.LENGTH_SHORT).show()
}
}
Gestionarea răspunsului de la portofelul electronic
Pentru comoditate, gateway-ul SDK oferă un handler Google Pay pentru întregul ciclu de viață. Puteți implementa funcția callback Google Pay și utiliza handlerul rezultat în activitatea dvs.
Acest lucru elimină necesitatea de gestionare manuală a rezultatelor activității Google Pay și deleagă pașii importanți ai tranzacției către metodele de callback.
// YourActivity.kt
override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?)
{
// handle the Google Pay response
if (GooglePayHandler.handleActivityResult(requestCode, resultCode, data, callback)) {
return
}
super.onActivityResult(requestCode, resultCode, data)
}
val googlePayCallback = object : GooglePayCallback {
override fun onReceivedPaymentData(paymentData: JSONObject) {
try {
val description = paymentData.getJSONObject("paymentMethodData")
.getString("description")
Log.d(MyGooglePayCallback::class.java.simpleName,"ReceivedPaymentData: $description")
} catch (e: Exception) {
// handle exception
}
handleGooglePayData(paymentData)
}
override fun onGooglePayCancelled() {
// handle cancelled
}
override fun onGooglePayError(status: Status) {
// handle error
}
}
Actualizați o sesiune cu simbolul de plată
Actualizați o sesiune folosind gateway-ul odată ce ați primit datele de plată de la Google Pay.
fun handleGooglePayData(paymentData: JSONObject) {
val token = paymentData.getJSONObject("paymentMethodData")
.getJSONObject("tokenizationData")
.getString("token")
val request = GatewayMap()
.set("sourceOfFunds.provided.card.devicePayment.paymentToken", token)
GatewayAPI.updateSession(session, request, callback)
}
Autentificarea plătitorului
3-D Secure
Autentificarea 3-D Secure sau 3DS este concepută pentru a proteja achizițiile online împotriva fraudei cu carduri de credit, permițându-vă să autentificați plătitorul înainte de a trimite o tranzacție de tip Authorization sau Pay.
3DS EMV, cunoscută sub numele 3DS2 în gateway, este versiunea nouă, care permite fluidizarea validării pentru plătitorii considerați de serverul de control al accesului (ACS) a avea un nivel scăzut de risc.
ACS poate determina riscul folosind informațiile furnizate de comerciant, amprentele digitale din dispozitiv, interacțiunile anterioare cu plătitorul sau ambele. ACS supune plătitorul unui test (de exemplu, introducerea unui cod PIN) numai dacă este necesară o verificare suplimentară pentru autentificarea plătitorului, furnizând astfel rate de schimb mărite.
Schemele de autentificare acceptate sunt Mastercard Identity Check, Visa Secure și American Express SafeKey.
Autentificarea cu Mobile SDK este limitată la 3DS2. Dacă nu este disponibil 3DS2, autentificarea nu va continua. Puteți, însă, continua cu plata dacă gateway-ul recomandă acest lucru.
Pentru mai multe informații referitoare la autentificarea 3-D Secure, consultați documentația Autentificarea 3-D Secure.
Detaliile de autentificare
Mobile SDK încorporat colectează datele dispozitivelor, pe care le trimite către gateway împreună cu informațiile tranzacțiilor atunci când efectuați autentificarea cu Mobile SDK; mai exact, acesta verifică identitatea titularului cardului într-o aplicație mobilă.
Furnizați cât mai multe informații posibil despre plătitor și tranzacție pentru a mări probabilitatea ca autentificarea să aibă succes.
Aceste informații suplimentare pot fi adăugate în session cu o solicitare Update Session.
| Parametru | Existență | Descriere |
|---|---|---|
| order.merchantCategoryCode | Opțional | Același cu codul din profilul dvs. de comerciant |
| Grupul de parametri billing.address | Opțional | Este recomandat cu insistență să îl includeți în solicitarea dvs. în măsura în care acest lucru este posibil |
| Grupul de parametri shipping.address | Opțional | Este recomandat cu insistență să îl includeți în solicitarea dvs. în măsura în care acest lucru este posibil |
| Grupul de parametri customer | Opțional | Este recomandat cu insistență să îl includeți în solicitarea dvs. în măsura în care acest lucru este posibil |
device este relevant numai pentru plățile prin browser. Acesta nu trebuie utilizat pentru autentificarea plătitorilor pe dispozitive mobile.Aceste date ajută sistemul să determine dacă titularul cardului trebuie autentificat și cum trebuie autentificat acesta. În timpul autentificării, utilizatorul se poate aștepta să utilizeze unul dintre cele două procese de autentificare:
- Fluidizat: ACS a colectat suficiente informații despre titularul cardului pentru îl autentifica. Nicio altă acțiune nu este necesară din partea utilizatorului.
- Testare: ACS solicită titularului cardului să efectueze un pas suplimentar de autentificare, respectiv să introducă o parolă de unică folosință, să se autentifice la banca emitentă etc. Mobile SDK încorporat gestionează afișarea unei interfețe native a dispozitivului pentru această testare. UI pentru aceste ecrane poate fi personalizată prin transmiterea parametrilor
UICustomizationîn SDK-ul gateway-ului în timpul inițializării.
Pentru mai multe informații, consultați documentația Authenticate Payer.
authentication.PSD2.exemption nu este acceptat în prezent în SDK. Efectuați autentificarea
Autentificarea plătitorului este considerată tranzacție separată pe gateway și, prin urmare, necesită un ID unic de tranzacție.
Dacă colectați plata pentru o comandă, puteți să
- corelați o plată și o tranzacție de autentificare utilizând același ID de comandă pentru fiecare tranzacție.
- fiecare tranzacție este afișată ca tranzacție separată pe portalul web al gateway-ului, cum ar fi UUID.
AuthenticationHandler.authenticate(activityContext, session, "your-auth- transaction-id", callback)
your-auth-transaction-id este un identificator unic pentru această tranzacție, care distinge tranzacția de toate celelalte tranzacții din cadrul comenzii. Acest lucru este necesar, deoarece gateway-ul va utiliza your-auth-transaction-id pentru a căuta rezultatele de autentificare pe care le-a stocat atunci când ați solicitat SDK-ului să autentifice plătitorul. Gateway-ul va transmite apoi achizitorului informațiile solicitate pentru solicitarea de plată.Interpretarea răspunsului
Metoda authenticate va returna un obiect AuthenticationResponse care conține:
- informații importante despre rezultat și
- acțiunile efectuate în timpul operațiunii.
Cel mai important câmp este response.recommendation. Acesta poate conține valoarea PROCEED sau DO_NOT_PROCEED.
- PROCEED: Indică faptul că este OK să continuați cu o plată sau o autorizare.
- DO_NOT_PROCEED: Indică ceva eșuat în timpul operației de autentificare. Obiectul
AuthenticationErrorpoate fi folosit pentru a determina mai multe.
Din API-ul gateway-ului versiunea 70 și versiunile ulterioare, puteți obține următoarele erori:
AuthenticationError.recommendation_ResubmitWithAlternativePaymentDetails: Indică faptul că ar trebui să solicitați plătitorului detalii alternative de plată. De exemplu, un card nou sau o altă metodă de plată și retrimiterea solicitării cu noile detalii.AuthenticationError.recommendation_AbandonOrder: Indică faptul că furnizorul de servicii de plată, schema sau emitentul vă solicită să abandonați comanda.AuthenticationError.recommendation_DoNotProceed: Indică faptul că gateway-ul respinge solicitarea și nu există nicio modalitate ca această tranzacție să reușească.
Pentru mai multe informații, consultați ghidurile de integrare.
AuthenticationHandler.authenticate(activityContext, session, "your-auth-transaction-id") { response ->
when(response.recommendation) {
AuthenticationRecommendation.PROCEED -> {
// continue to payment/authorization
}
AuthenticationRecommendation.DO_NOT_PROCEED -> {
if (response.error !=null) {
if (response.error is AuthenticationError.RecommendationResubmitWithAlternativePaymentDetails) {
// "Authentication not successful, re-enter card details
}
} else {
// "Authentication not successful"
}
}
}
}
Dacă autentificarea eșuează, puteți să examinați response.error pentru mai multe informații privind cauza.