OliPay SDK

olipay-sdk-documentation.md

Getting started

1. Copy olipaysdk-release.aar and emvlibrary-release.aar to app/libs folder

2. Add the following dependencies to app/build.gradle

dependencies {
    //... other project dependencies
    implementation files('libs/olipaysdk-release.aar')
    implementation files('libs/emvlibrary-release.aar')
    implementation 'com.google.code.ksoap2-android:ksoap2-android:3.6.4'
}

3. Add the following repositories to build.gradle

allprojects {
    repositories {
        //... other project repositories
        maven { url 'https://oss.sonatype.org/content/repositories/ksoap2-android-releases/' }
    }
}

4. Create an instance of the QpayController and pass the an event handler that implements QpayController.QpayControlEventos

import mx.qpay.client.QpAmbiente;
import mx.qpay.controller.QpayController;

public class MainActivity extends AppCompatActivity {
    
    public static QpayController qpayController;
    
    @Override
    protected void onCreate(Bundle savedInstanceState) {
        //... init activity
        QpAmbiente ambiente = QpAmbiente.TEST; // Pass the environment, TEST or PRODUCTION, when instantiating the  QpayController
        qpayController = QpayController.getInstance(this, new QpayController.QpayControlEventos() {
            @Override
            public void qpMostrarEstadoTexto(String pResultado, int pCodigo) {
                Log.d("QpayControllerEvent", "qpMostrarEstadoTexto pResultado=" + pResultado);
                Log.d("QpayControllerEvent", "qpMostrarEstadoTexto pCodigo=" + pCodigo);
            }

            @Override
            public void qpRegresaTransaccion(HashMap<String, String> pResultado) {
                Log.d("QpayControllerEvent", "qpRegresaTransaccion CodigoTransaccion=" + pResultado.get("CodigoTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion DescripcionCodigo=" + pResultado.get("DescripcionCodigo"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion NumeroTransaccion=" + pResultado.get("NumeroTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion CodigoAprobacion=" + pResultado.get("CodigoAprobacion"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion DigitosTarjeta=" + pResultado.get("DigitosTarjeta"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion FechaTransaccion=" + pResultado.get("FechaTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion HoraTransaccion=" + pResultado.get("HoraTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion Monto=" + pResultado.get("Monto"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion TipoTarjeta=" + pResultado.get("TipoTarjeta"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion MarcaTarjeta=" + pResultado.get("MarcaTarjeta"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion BancoEmisor=" + pResultado.get("BancoEmisor"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion ARQC=" + pResultado.get("ARQC"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion AID=" + pResultado.get("AID"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion TSI=" + pResultado.get("TSI"));
                Log.d("QpayControllerEvent", "qpRegresaTransaccion Titular=" + pResultado.get("Titular"));
            }

            @Override
            public void qpRegresaFirma(HashMap<String, String> pResultado) {
                Log.d("QpayControllerEvent", "qpRegresaFirma=" + pResultado.toString());
            }

            @Override
            public void qpRegresaCancelacion(HashMap<String, String> pResultado) {
                Log.d("QpayControllerEvent", "qpRegresaCancelacion CodigoTransaccion=" + pResultado.get("CodigoTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaCancelacion DescripcionCodigo=" + pResultado.get("DescripcionCodigo"));
                Log.d("QpayControllerEvent", "qpRegresaCancelacion NumeroTransaccion=" + pResultado.get("NumeroTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaCancelacion CodigoAprobacion=" + pResultado.get("CodigoAprobacion"));
                Log.d("QpayControllerEvent", "qpRegresaCancelacion FechaTransaccion=" + pResultado.get("FechaTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaCancelacion HoraTransaccion=" + pResultado.get("HoraTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaCancelacion Monto=" + pResultado.get("Monto"));
            }

            @Override
            public void qpRegresaDevolucion(HashMap<String, String> pResultado) {
                Log.d("QpayControllerEvent", "qpRegresaDevolucion CodigoTransaccion=" + pResultado.get("CodigoTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaDevolucion DescripcionCodigo=" + pResultado.get("DescripcionCodigo"));
                Log.d("QpayControllerEvent", "qpRegresaDevolucion NumeroTransaccion=" + pResultado.get("NumeroTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaDevolucion CodigoAprobacion=" + pResultado.get("CodigoAprobacion"));
                Log.d("QpayControllerEvent", "qpRegresaDevolucion FechaTransaccion=" + pResultado.get("FechaTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaDevolucion HoraTransaccion=" + pResultado.get("HoraTransaccion"));
                Log.d("QpayControllerEvent", "qpRegresaDevolucion Monto=" + pResultado.get("Monto"));
            }

            @Override
            public void qpRegresaVentaECommerce(HashMap<String, String> pResultado) {
                Log.d("QpayControllerEvent", "qpRegresaVentaECommerce=" + pResultado.toString());
            }

            @Override
            public void qpRegresaDevolucionECommerce(HashMap<String, String> pResultado) {
                Log.d("QpayControllerEvent", "qpRegresaDevolucionECommerce=" + pResultado.toString());
            }

            @Override
            public void qpRegresaCancelacionECommerce(HashMap<String, String> pResultado) {
                Log.d("QpayControllerEvent", "qpRegresaCancelacionECommerce=" + pResultado.toString());
            }

            @Override
            public void qpRegresaHistorial(List<HashMap<String, String>> pResultado) {
                Log.d("QpayControllerEvent", "qpRegresaHistorial=" + pResultado.toString());
            }

            @Override
            public void qpRegresaVoucher(HashMap<String, String> pResultado) {
                Log.d("QpayControllerEvent", "qpRegresaVoucher=" + pResultado.toString());
            }

            @Override
            public void qpError(String pResultado, int pCodigo) {
                Log.d("QpayControllerEvent", "qpError pResultado=" + pResultado);
                Log.d("QpayControllerEvent", "qpError pCodigo=" + pResultado);
            }

            @Override
            public void emvEvent(String eventName, Map<String, Object> data) {
                Log.d("QpayControllerEvent", "emvEvent eventName=" + eventName);
                Log.d("QpayControllerEvent", "emvEvent data=" + data);
            }
        }, ambiente);
    }
    

5. Create a transaction with method qpRealizaTransaccion, the result will be returned in the qpRegresaTransaccion event. If something went wrong with the transaction qpError event is fired.

    String identificador = "377";
    String contrasena = "tvOLiGmx19";
    int monto = 1;
    String referencia = "a test transaction";
    qpayController.qpRealizaTransaccion(MainActivity.this, identificador, contrasena, monto, referencia, -1, -1, -1);

6. Cancel a transaction with qpRealizaCancelacion if the transaction is from today or qpRealizaDevolucion if it is older, the result will be returned in the qpRegresaCancelacion/qpRegresaDevolucion event. If something went wrong with the transaction qpError event is fired.

    String identificador = "377";
    String contrasena = "tvOLiGmx19";
    int monto = 1;
    String referencia = "a test transaction";
    String numeroTransaccion = "6dd29fd3e2ad41afa44e";
    String codigoAprobacion = "29362592";
    
    if(transactionIsCreatedToday) {
        qpayController.qpRealizaCancelacion(identificador, contrasena, numeroTransaccion, monto, codigoAprobacion, referencia);
    } else {
        qpayController.qpRealizaDevolucion(identificador, contrasena, numeroTransaccion, monto, codigoAprobacion, referencia);
    }

Events

qpError

@Override
public void qpError(String pResultado, int pCodigo) {
    Log.d("QpayControllerEvent", "qpError pResultado=" + pResultado);
    Log.d("QpayControllerEvent", "qpError pCodigo=" + pResultado);
}

Error Codes

pCodig	pResultado
90001	Unknown error
90002	Bad swipe
90003	Not ICC
90004	Need fallback
90008	Transaction failed
90009	Reading card timed out
2	Referral (General).
3	Referral - Call bank for manual approval.
50	Declined (General).
51	Connection timed-out.
52	Error connecting to processor or sending data.
500	Declined - Transaction considered fraudulent by Fraud component.
501	The transaction was Approved by the processor. However, it failed a post-processing fraud rule and has been voided.
502	The transaction was Approved by the processor. However, it failed a fraud rule and has been marked for review.
1002	Amount not valid.
1003	Interchange or Payment Service data submitted is not valid.
1005	Currency is not valid.
1006	BIN is not valid.
1007	Card number is not valid.
1010	Magnetic stripe data is not valid.
1011	Card expiration date is not valid.
1012	Transaction date or time is not valid.
1013	Date is not valid.
1014	Transaction is not valid.
1015	PIN is not correct.
1016	Merchant ID is not valid.
1017	Account is not valid.
1018	Encryption Error.
1019	Check Digit Error.
1020	Verification Error.
1021	Destination not found.
1022	Service code is not valid or is restricted.
1023	Violation, cannot complete.
1024	Error response text from check service.
1025	No account.
1026	No such issuer.
1027	PIN tries exceeded.
1028	Transaction not permitted.
1029	Security Violation.
1030	Unable to back out transaction.
1031	Unable to locate. No match was found.
1035	Terminal ID is not valid.
1036	Message format error.
1037	Track 2 data is not valid.
1050	Declined - Insufficient funds.
1051	Customer card is expired.
1052	Lost or stolen card.
1053	Pick up card. Issuer wants card returned.
1054	Response is not valid.
1055	CVV failure or CVV Value supplied is not valid.
1056	Transaction type or code is not valid.
1057	Declined - Do not honor.
1058	Declined - Exceeds issuer withdrawal limit.
1059	Declined - Exceeds withdrawal limit.
1060	Declined - Activity limit exceeded.
1063	Resend Batch.
1064	Download failed.
1065	Switch or issuer system error.
1066	Unable to route transaction.
1067	System error.
1069	Honor with identification.
1071	Periodic transaction - new account information available.
1076	Unable to complete transaction.
1500	Checking account is not valid.
2003	Process code, authorization type, or card type is not valid.
2005	Source ID is not valid.
2009	File access error occurred in the processor host database.
2011	Merchant ID and terminal ID combination is not valid.
2019	Account number found by authorization process is not valid.
2026	Lost or stolen card. Card issuer wants the card returned.
2028	Terminal is not programmed for this service.
2052	Credit card number does not match the method of payment.
2055	Issuer requires more information.
2056	Restricted card.
2058	Check merchant entitlement
2059	Capture not allowed.
2060	Communication error - resend.
2062	Retain card.
2063	No action taken.
2064	Suspicion of manipulation.
2065	Requested function not supported.
2066	Secondary transaction was not carried out with the card which was used for the original transaction.
2067	The transaction amount of the secondary transaction is higher than original transaction amount.
2068	Card issuer temporarily not reachable.
2069	The card type is not processed by the authorization center.
2070	Processing temporarily not possible.
2073	Declined - data entry error.
2074	Declined - negative data.
2075	Declined - scoring decline.
2076	Declined - no response from host.
2077	Institution is no longer valid.
2078	Card not active. Effective date not valid.