The purpose of this documentation is to guide the developer on how to integrate with the Muxi APIs, describing the features and methods to be used, listing information to be sent and received through examples and with a simple and accessible language. This will require only basic programming language skills for the Web, HTTP / HTTPS requests, and JSON file manipulation to interact with our APIs.

In this manual, you will also find reference on all operations available in the Muxi REST API. These operations must be performed using your specific key (authorization token) at the respective endpoints below. To perform an operation, combine the base URL of the environment with the endpoint of the desired operation and send using the HTTP verb as described in the menu item SENDING A TRANSACTION. If these terms are complex for you, read the subitem WHAT IS WEB SERVICE?.

For ease of integration we provide a Sandbox environment so you can test before changing the environment for production. After development, access must be modified to the productive environment.

Card not present Transactions (CNP) allow digital companies to conveniently sell their digital products or services to customers around the world. Our APIs provide a secure environment for doing this type of transaction and thereby leveraging your business.

Through the payment gateways, the customer enters their card information, which is sent to the card companies and financial institutions, and from there the bank confirms that there is a limit available and approves or denies the purchase in seconds.

But is it safe?

Y-E-S !! We at Muxi know how bad it is to be deceived. When we use a service we do not start thinking that it can go wrong, that they can take us for a ride, and that’s certainly not what we offer our customers. We are committed to our users and partners to always seek the highest standard of security with regard to payments. Want to know how we do this?

• PCI -> We follow 100% of the standards defined by PCI. The Payment Card Industry - Data Security Standard is a security standard, aimed at the payment card industry, which defines security models through standards that must be followed strictly. This certification is required for any company that stores, transmits or processes sensitive information from cardholders. Data such as name, card number and security code should be encrypted for the security of cardholders. And since we want you to feel secure, we are a fully PCI-DSS certified company.

• Encryption -> All sensitive data passing through our gateway is protected through the certificates used during the transaction. We use HTTPS, which is an implementation of the HTTP protocol over an additional layer of security that uses the SSL / TLS protocol. This additional layer allows the data to be transmitted over an encrypted connection and that the server and the client are authenticated through digital certificates.

• Token -> We do not save the card data, they are tokenized. Tokenization enables the use of carrier card data securely and compliant with PCI-DSS standards. The basic concept is to send the customer’s card data directly from his browser to Muxi and then retrieve a token representing the card in question. Read the Tokenization subitem and be on the safest way to make a payment nowadays.

To use our services, you need to authenticate yourself by generating a token. To generate our authentication token we are based on the specification JWT.io, so its size is variable according to the generation of it.

How do I get this token?

To receive an authentication token, contact the Muxi operational team. We will be happy to assist you and clarify any pending questions.

Where do I use this token?

After receiving a token, it must be added to the HTTP Authentication header according to the environment we want to access. The following is an example of a curl command to perform a query for transaction cycles.

curl --request GET --url https://hmg-transaction-api.muxi.net.br/v1/financial_cycles --header 'Authorization:<token>'

Webservices allow two (or more) machines to communicate over a network. Here’s an example:

For a deeper explanation, imagine the following scenario: Your company trades dollar-denominated products whose value fluctuates daily. It is extremely important that you have these values ​​updated so that you make decisions that bring you the best results. You can hire a trainee to update these values ​​manually, or you can consume a service that provides you with that information automatically and reliably.

This is the webservice service. You ask a question “How many reals are worth a dollar today?” And he responds. This process, at the communication level, is based on requests based on the HTTP protocol. There is a specific URL, which we call the endpoint, on a server that is always waiting for the question, and if it is done correctly, it responds. We call this endpoint URL because it is rather a URL, but it has several “endings” that specify exactly where you want to go. Imagine as if the URL were the address of a street and the endpoint was the house number, and inside each house there is a service. For example, in a house you deliver the flour, eggs, milk and return a cake; in another house you deliver the fabric, thread, needle and return a garment. After the outfit is ready, you can still go back into the house to make an adjustment, or add an embroidery. Just as there are homes you can throw your clothes off if you will not use more. There are also the houses where you consult the quantities of clothes you have requested. This will all be translated into verbs. For example:

• Make a outfit / transaction -> POST
• Check how many clothes / transactions have already been made -> GET
• Change / adjust an outfit / transaction -> PUT
• Delete / Throw away an outfit / transaction -> DELETE

Remember that the question (or request) must be made correctly, otherwise the webservice will not be able to understand the request. Use this documentation to see if your data is correct and there is nothing missing. There is also an example of a downloadable functional JSON file that you can purchase with what you are using.

Postman

To streamline communication tests with our APIs, any HTTP client can be used. Here at Muxi, we use Postman; because in addition to serving our needs very well, it is more widespread in the community. This client allows you to configure and test before you even start developing integrations like the Muxi APIs. In the case of Postman, there is a well-developed documentation explaining how to use the tool. It also generates for the developer code examples in some languages, such as:

• ASP
• Net
• Java
• PHP
• Ruby
• Python

JSONLint

To validate whether the generated JSON object is valid by default, we can use various tools. Here in Muxi, we use JSONLint, because it is web and has a simple interface to be understood.

SDKs

For those of you using the Java language we are developing SDKs (Software Development Kit) to make it easy to integrate with our APIs.

What is a Transaction?

From the application point of view, the transaction is an operation consisting of a series of instructions or procedures that must be performed together. This kind of circumstance is due to instructions that only make sense when performed together. Our application offers various types of transactions such as initialization, authorization, reversal, tokenization etc. Every time data is sent to API and something is answered, we will have a transaction; but if monetary values ​​are involved in this transaction, we will have a financial transaction.

Financial transaction is a commercial transaction that consists of exchanging a good or service for a certain amount of money. The term also refers to the very technical operation of the database that performs a series of operations. However, the most common meaning refers to the exchange of goods, a specific circumstance of economic activity.

Examples of financial transactions:

• Authorization / Sale
• Pre-authorization
• Pre-authorization Confirmation
• Pre-authorization Cancellation
• Reversal
• Refund
• Recurrence
• Cancellation of Recurrence
• Transfer
• Transfer Cancellation

Examples of non-financial transactions:

• Initialization
• Carrier Registration
• Tokenization

What do I need to complete a financial transaction?

We have several means of sending a financial transaction. To accomplish this, we must first generate a transactional token. When you receive the authentication token, you will also receive a KEY API. In possession of this data, it will send a startup message, thus obtaining the transactional token that is valid for 1 hour, if it generates another, the previous one is invalid.

Calm down! Tell me more about Transactional Token!

Of course! The transactional token is a unique key that identifies to our system who you are! Every time you want to transact, you start by initializing with the authentication token in the Authentication field of the HTTP header. The response from this initialization will generate the transactional token for you. You will copy this transactional token and replace the authentication token that was in the Authentication field of the header with that new token. With this, you will be able to do all other transactions, see an example below. The transactional token is valid for 1 hour, so at the end of this time, you need to initialize again to get a new token and return to normal trading.

HTTP Header

Every request needs a header containing the following detailed information:

• Content-Type -> Indicates the format of the request body.
• Accept -> Indicates the expected return type.
• Authorization -> The field is populated by two possible values:     + Authentication Token -> If it is a startup.     + Transactional Token -> If it is any other transaction except initialization.

Example

Can I change an existing transaction?

Yes, but only the transactions of Recurrence and Carrier Registration. For this you need to send an HTTP / HTTPS request using the PUT method. See the subitems below for each of these transactions.

For a long time, the means of payment were limited to expensive and complex devices that had little computational power. In addition, the financial applications that are necessary to make payments effectively, were developed in a non-scalable and costly way. However, with the advent of technology, smartphones have been important tools to innovate the means of payment and their technologies, making possible to improve the interaction of different stakeholders, like merchants, end users, banks and issuer.

Having that in mind, we offer our customers an Android service called muxiPAY services and an SDK (Software development kit) that enables the development of Android applications to use payment functionality in a transparent, safe and uncomplicated way. In order to developers focus on what really matters, a user experience and its business rules.

Currently, supported devices are:

• PAX D150

For the development of your application, we recommend using Android Studio that is the official IDE for the development of Android app.

After the project has been created, the developer must add in the project module the dependency of the muxiPAY services SDK, provided by Muxi in AAR format. You can download to integrate our SDK with your app here. The instructions to import module you find here.

After SDK imported, its time to install muxiPAY services on your smartphone. You can download our integration version that is not necessary use Pinpad

• smartphone version.

In your own app, you’ll need to put some dependencies on build.gradle inside app folder, to make a bridge between sdk and muxiPAY services.

api "com.josesamuel:remoter-annotations:1.2.0"
annotationProcessor "com.josesamuel:remoter:1.2.0"

You can too download our sample app that contain SDK imported. Click here to download

In this step, the developer should add their logic with payment mechanisms provided by the muxiPAY services.

The developer must create the main object that is an instance of the IMPSManager interface, instantiate it and bind business application in muxiPAY services. It is recommended to do this at onStart method in currentActivity, but you can do bind on any place

Note bindService must be called before any operation

    @Override
    protected void onStart() {
        super.onStart();
        if (mpsManager == null){
            Log.d(TAG, "Instantiating  mpsManager ");
            mpsManager = new MPSManager(this.getApplicationContext());
            bluetoothList.setMpsManager(mpsManager);
        }

        boolean bindService = mpsManager.bindService(getApplicationContext());
    }

The communication between business application and muxiPAY services is established using Callbacks. To facilitate developer interaction, service has a class called CallbackAnswer that implements five methods. All these methods are called when muxiPAY services process ended. It returns a MPSResult object which contains a STATUS information about muxiPAY services process. In ERROR case, it returns a code and a description for occurred error. See Errors table for more information.

• public void onInitAnswer(MPSResult mpsResult); Called when initialization process ended
• public void onTransactionAnswer(MPSResult mpsResult); Called when transaction process ended
• public void onCancelAnswer(MPSResult mpsResult); Called when cancel process ended
• public void onDeconfigureAnswer(MPSResult mpsResult); Called when deconfigure process ended
• public void onServiceConnected(); Called when service is connected
• public void onServiceDisconnected(Component name); Called when service stopped unexpected

The developer must use the method setMpsManagerCallback to define Callback instance to be notified when process ended. For example, adding treatment for onInitAnswer:

    mpsManager.setMpsManagerCallback(new CallbackAnswer() {
            @Override
            public void onInitAnswer(final MPSResult mpsResult) {
                runOnUiThread(new Runnable() {
                    @Override
                    public void run() {
                        String text;
                        updateStatus(getApplicationContext());
                        if(mpsResult.getStatus() == MPSResult.Status.SUCCESS) {
                            text = getResources().getString(R.string.initialize_success);
                        }else{
                            text = mpsResult.getDescriptionError();
                        }
                        createToast(text);

                    }
                });
            }
    }

Note 1: Callback application is called in another thread. To update your application screen, use runOnUiThread method or other that process inside one Thread that be different of Uithread or MainThread

Note 2: CallbackAnswer class are prepared to override just necessary callbacks. It’s a developer choice what methods should be override in current Activity.

IMPSManager object will be used to call initialize method, passing the follow parameters:

1. Boolean to indicate if the messages will be shown on pinpad´s display
2. The merchant id (like CNPJ, in Brazil).

Note: It is recommend to use an AsyncTask to avoid lock UI thread.

    @Override
    protected Void doInBackground(Void... voids){
        mpsManager.initialize(defaultPinpadmsg,cnpj);
        return null;
    }

After initialization process, onInitAnswer method will be called.

Now, with Pinpad paired, must pass MAC address on parameter of the method setCurrentBluetoothDevice, turning possible make your first payment.

    /*
    * TODO: Change this variable to use MAC address do seu pinpad
    */
    String bluetoothDevice = "00:07:80:62:3D:37";
    mpsManager.setCurrentBluetoothDevice(bluetoothDevice);

The developer should access the transaction method, through an instance of the IMPSManager class. This method expects a MPTransaction object as parameter. See the example below.

        MPSTransaction transaction = new MPSTransaction();
        transaction.setAmount("2000");
        transaction.setCurrency(MPSTransaction.CurrencyType.BRL);
        transaction.setInstallments(1);
        transaction.setTransactionMode(MPSTransaction.TransactionMode.CREDIT);
        transaction.setRate(false);

Then, call transaction method, passing created object as a parameter. It’s recommend to call transaction in another thread, using AsyncTask.

    @Override
    protected Void doInBackground(Void... voids){
        mpsManager.transaction(transaction);
        return null;
    }

The example above performs a CREDIT transaction with 1 (one) installment and with the amount of 20.00 BRL.

Note: The transaction type and currency are of type enum.

Each transaction may be approved or denied. Developer should to get the transaction result and treat it, using onTransactionAnswer.

In case of SUCCESS response in onTransactionAnswer, the client’s receipt and the establishment’s receipt are stored in two Strings, for later treatment. These strings are accessed through the getClientReceipt and getEstablishmentReceipt methods, respectively.

Otherwise, the code and description of the error are store in two Strings, for later treatment. These strings are accessed through the getCode and getDescriptionError, respectively.

    @Override
    public void onTransactionAnswer(final MPSResult mpsResult) {
        runOnUiThread(new Runnable() {
            @Override
            public void run() {
                if(mpsResult.getStatus()== MPSResult.Status.SUCCESS) {
                    //do you stuff using mpsResult.getClientReceipt()
                    //and mpsResult.getEstablishmentReceipt()
                } else {
                    //do errror treatment using mpsResult.getCode()
                    //and mpsResult.getDescriptionError();
                }

            }
        }
    }

Notice that handling errors is easy. For instance, if the transaction is denied because an error occurred when reading the card, the business application might implement a “try again” function. There are several possibilities.

The void flow is very similar to making a payment. The onCancelAnswer will be called when cancel process ends.

There are two options to void a payment:

1. Cancel last transaction
2. Cancel a previously transaction

Cancel last transaction

To cancel the last transaction, it is necessary to create a MPSTransaction instance and set its transaction mode.

    MPSTransaction transaction = new MPSTransaction();
    transaction.setCurrency(MPSTransaction.CurrencyType.BRL);
    transaction.setTransactionMode(MPSTransaction.Transaction.CREDIT);

Cancel a previously transaction

To cancel a previously transaction, it is necessary to create a MPSTransaction instance and set its transaction mode, transaction id (like DOC(CV), in Brazil) and authorization code. In example below, muxiPAY services will search a CREDIT transaction, with transaction id equals ‘123456’ and authorization code equals ‘12345678’.

    MPSTransaction transaction = new MPSTransaction();
    transaction.setCurrency(MPSTransaction.CurrencyType.BRL);
    transaction.setTransactionMode(MPSTransaction.TransactionMode.BRL);
    transaction.setCv("123456");
    transaction.setAuth("12345678");

Then, you must call the cancelTransaction method, passing the created object, transaction, as a parameter. It is recommend to call cancelTransaction in another thread, using AsyncTask.

    @Override
    protected Void doInBackground(Void... voids){
        mpsManager.cancelTransaction(transaction);
        return null;
    }

Furthermore, the developer can consult, if necessary, the source code of an example application that we provide on Github.

• muxiPAY services sample
• Javadoc SDK

After make all tests and realize safe, remove muxiPAY services integration version and install our official version here, where this version need an Pinpad. To pair the Pinpad with your device, check the required information with the manufacturer

Can I check the transactions I have already made?

Of course! For this you need to send an HTTP / HTTPS request using the GET method. See the subitems below for each of these transactions.