Skip to main content

Documentación

App to App Guide

Introduction

The Rapyd Core app handles all low-level payment processing, including reading cards, managing PIN entry, and securely communicating with Rapyd systems to authorize transactions.

Partners and merchants can develop custom Android applications for PAX and SUNMI payment terminals on top of the Rapyd Core app. A straightforward app-to-app integration enables partners and merchants to start accepting card payments within just a few days. Additionally, the Core app can be fully branded during setup, incorporating the partner’s logos and color scheme for a seamless merchant experience.

Configuring Your Project for Rapyd Core Integration in Android
Configuring Your Project

The following needs to be added to your AndroidManifest to be able to communicate with the Rapyd Core.

    • Example

      • <queries>
    <package android:name="net.rapyd.core"/>
</queries>

The ACTION_CALLBACK intent filter needs to be added to the activity that the Rapyd Core should return to when

any core interaction has finished. If you do not want to go back to a specific activity this step can be skipped, in this case the core activity will just be finished.

To return to the MainActivity, add the following in your AndroidManifest.xml

    • Example

      • <activity android:name=".MainActivity"
          android:exported="true">
    <intent-filter>
        <action android:name="android.intent.action.MAIN"/>
        <category android:name="android.intent.category.LAUNCHER"/>
    </intent-filter>
    <intent-filter>
        <action android:name="ACTION_CALLBACK"/>
        <category android:name="android.intent.category.DEFAULT"/>
    </intent-filter>
</activity>

The final configuration step is to add a receiver class to get the configuration

and transaction result from the Rapyd Core. This example shows one receiver that listens for all actions,

however it is possible to make separate receivers for each action type.

    • Example

      • <receiver android:name=".receivers.ResultReceiver"
          android:enabled="true"
          android:exported="true">
    <intent-filter>
        <action android:name="TRANSACTION_CANCELLED_ACTION"/>
        <action android:name="TRANSACTION_RESULT_ACTION"/>
        <action android:name="END_OF_DAY_RESULT_ACTION"/>
        <action android:name="CONFIG_RESULT_ACTION"/>
    </intent-filter>
</receiver>

Define the ResultReceiver class and implement handling for each action type.

    • Example

      • public class ResultReceiver extends BroadcastReceiver {

    @Override
    public void onReceive(Context context, Intent intent) {
        if (intent != null) {
            if (TRANSACTION_RESULT_ACTION.equals(intent.getAction())) {
                // TODO: Implement handling of transaction result here
                TransactionResult result = WrapperUtils.getTransactionResultFromJson(intent.getStringExtra(Messages.TRANSACTION_RESULT));
            } else if (TRANSACTION_CANCELLED_ACTION.equals(intent.getAction())) {
                // TODO: Implement handling of cancelled transaction here
            } else if (Messages.END_OF_DAY_RESULT_ACTION.equals(intent.getAction())) {
                // TODO: Implement handling of end of day result here
            } else if (CONFIG_RESULT_ACTION.equals(intent.getAction())) {
                // TODO: Implement handling of config
                String config = intent.getStringExtra(CONFIG_RESULT);
                Config configFromJson = WrapperUtils.getConfigFromJson(config);
            }
        }
    }
}
Supported Actions

The following actions are sent from the Rapyd Core.

Name

Description

TRANSACTION_RESULT_ACTION

Action that contains the transaction result. The transaction result is passed as a JSON string and can be obtained as a string parameter on the intent named TRANSACTION_RESULT. See transaction result table for further information.

TRANSACTION_CANCELLED_ACTION

Action that contains the transaction cancelled result. Omitted when the transaction is cancelled before completion.

END_OF_DAY_RESULT_ACTION

Action that contains the end of day result. Passes the result string as a string parameter on the intent named END_OF_DAY_RESULT. Result string is json formatted.

LAST_END_OF_DAY_RESULT_ACTION

Action that contains the pevious end of day result. Passes the result string as a string parameter on the intent named LAST_END_OF_DAY_RESULT. Result string is json formatted.

X_REPORT_RESULT_ACTION

Action that contains the current x report. Passes the result string as a string parameter on the intent named X_REPORT_RESULT_ACTION. Result string is json formatted.

CONFIG_RESULT_ACTION

Action that contains the Rapyd Core configuration. This is sent at initial startup of the core.

VOID_RESULT_ACTION

Action that contains the result of a void. Intent parameter VOID_RESULT contains the Boolean result of the void. Intent parameter UTI contains the UTI of the voided transaction.

DAILY_SALES_RESULT

Action that contains the current total sale, total refund and total tip value for the day. The data can be obtained as from the following intent parameter DAILY_SALES_RESULT.

Config Data Fields

The following data is passed in the CONFIG_RESULT JSON string.

Name

Type

Description

printReceipt

Boolean

Boolean value indicating whether the Rapyd Core is setup to physically print receipts.

useOnScreenSignature

Boolean

Boolean value indicating whether signatures is written on screen.

cashbackEnabled

Boolean

Boolean value indicating whether cashback is enabled for the terminal.

refund

Boolean

Boolean value indicating whether refund is supported.

refundSecure

Boolean

Boolean value indicating whether refunds require password.

audioSetting

string

String defining the audio settings for the core, possible values are: MUTE, AUDIO, SILENT_KEYBOARD

additionalZeros

Boolean

Boolean value indicating whether 00 and 000 should be visible on the keyboard.

multiMerchant

Boolean

Boolean value indicating whether there are multiple merchants setup for the device.

currentTheme

string

The theme of the core, possible values are: LIGHT, DARK

coreVersionName

string

The version of the Rapyd core.

language

string

The language in Java locale format: is_IS

merchants

array

JSON array containing the merchants config, see merchant config table

Merchant Config Data Fields

Name

Type

Description

id

string

The internal ID of the merchant, this can be used to switch between merchants.

terminalId

Boolean

The terminal ID of the merchant.

merchantId

Boolean

The merchant ID.

merchantNameAndLocation

string

Name of the merchant, shown on receipts.

merchantAddress

string

The merchant address, shown on receipts.

merchantCity

string

The city of the merchant, shown on receipts.

currencyCode

string

ISO 4217 A3 currency code.

currencyNum

string

ISO 4217 N3 currency code.

countryCode

string

Country code in ISO 4217 N3 format.

merchantPassword

string

The merchant PIN code.

mailMerchant

Boolean

Boolean indicating if the merchant wants mailed receipts.

mailMerchantAddress

string

The mail address of the merchant.

printMerchantReceipt

Boolean

Boolean indicating whether the merchant wants to print merchant copies of receipts.

dbaName

string

Partner merchant DBA name.

dbaCity

string

Partner merchant DBA city.

sponsoredMerchantId

string

Partner sponsored merchant ID.

preauth

Boolean

Boolean value indicating whether preauth is supported.

moto

Boolean

Boolean value indicating whether MOTO is supported.

amexSupportEnabled

Boolean

Boolean value indicating whether AMEX cards are supported.

dccSupported

Boolean

Boolean value indicating whether DCC is supported.

tipEnabled

Boolean

Boolean value indicating whether tip is enabled for the merchant.

Transaction Result Fields

Name

Type

Description

uti

string

The UTI of the transaction.

cardAcceptorAddress

string

The merchants address.

cardholderVerificationMethod

Boolean

The CVM of the transaction, possible values are: CVM_NO_CVM, CVM_OFFLINE_PIN, CVM_ONLINE_PIN, CVM_SIG, CVM_ONLINE_PIN_SIG and CVM_CONSUMER_DEVICE

transactionDate

string

The transaction date.

primaryAccountNumber

string

The primary account number with first 6 and last 4 unmasked. The characters in between are masked as *.

cardNumberLength

int

The length of the card number.

totalAmount

string

The total transaction amount, 500.15 will be represented as the following string 50015.

transactionResponse

string

The transaction response code, two letter combination.

transactionSource

string

The transaction source, possible values are: PICC, ICC, MAG and MOTO

transactionType

string

The transaction type, possible values are: SALE, REFUND, PREAUTH and COMPLETION

applicationId

string

The application id, the selected card application of the transaction.

authCode

string

The auth code, only populated for approved transactions.

merchantId

string

The merchant id.

merchantReceipt

string

The merchant receipt.

cardholderReceipt

string

The cardholder receipt.

signature

string

The signature as a byte array, only sent when signature on screen.

terminalId

string

The terminal id.

messageId

integer

The message id of the transaction.

currencyCode

string

The ISO 4217 numeric currency code of the transaction.

currencyCodeAlpha

string

The ISO 4217 alpha currency code of the transaction.

appName

string

The application name in hex format.

transSource

string

The transaction source card type. 240, 250 and 260 indicates debit card. 400, 500 and 530 indicates credit card.

correlationId

string

The correlation id.

referenceId

string

The reference id.

tipAmount

integer

The tip amount, 350.45 will be represented as the following 35045.

dccTransaction

Boolean

Boolean indicating whether this is a DCC transaction.

dccOriginalAmount

integer

The DCC amount, 350.45 will be represented as the following 35045. Set to zero if no DCC.

dccExchangeRate

double

The DCC exchange rate. Set to zero if no DCC.

dccCommissionAmount

integer

DCC commission amount. Set to zero if no DCC.

dccCurrencyCode

String

DCC alphabetical currency code. Set to zero if no DCC.

cashbackAmount

integer

The cashback amount added to the transaction, 2.50 will be represented as the following 250

cashbackAdded

Boolean

Boolean indicating whether cashback has been added to the transaction

dccNumericCurrencyCode

String

DCC numeric currency code. Set to zero if no DCC.

isSignature

Boolean

Boolean indicating whether the receipt needs to be signed with signature.

payerAccountReference

string

Payer Account Reference (PAR)

walletProvider

string

The wallet provider, possible values are: GOOGLE_PAY, APPLE_PAY,SAMSUNG_PAY,MICROSOFT_PAY,VISA_CHECKOUT,FITBIT_PAY,GARMIN_PAY, UNKNOWN

voided

Boolean

Boolean indicating whether the transaction has been voided.

voucherBenefitCardIssuer

string

The card issuer for a voucher card, populated from authorization response. Will not be set for regular transactions.

voucherWalletName

string

The wallet name of the voucher used in the transaction, populated from authorization response. Will not be set for regular transactions.

voucherBalance

string

The voucher balance, populated from authorization response. Will not be set for regular transactions.

voucherExpirationDate

string

The voucher expiration date, populated from authorization response. Will not be set for regular transactions.

tsi

string

The Transaction Status Information, result returned from the card read. Empty for MAG and MOTO transactions.

tvr

string

The Terminal Verification Result. Omitted for MAG and MOTO transactions.

cvmResult

string

The Card Verification Method results.

API

The wrapper library provides an API class that provides a number of functions to integrate with the Rapyd Core.

In the following table all the functions and input parameters are explained.

Function signature

Supported parameters

Description

startCore(Context context)

Function to start the core, it is preferred to call when starting your app, this avoid excessive loading times when performing the first transaction.

startCardCheck(Context context, HashMap<String, String> parameters)

  • CORRELATION_ID

  • REFERENCE_ID

  • DISABLE_PRINTING

  • MERCHANT_ID

  • UTI

  • LOCALE

Function to perform a card check. This can be used to verify that the card is supported and works.

startTransaction(long amount, TransactionType transactionType, Context context)

Function to start a transaction without any parameters. The amount is specified with two minor units. Possible transaction types are: SALE, REFUND, PREAUTH

startTransaction(long amount, TransactionType transactionType, HashMap<String, String> parameters, Context context)

  • CORRELATION_ID

  • REFERENCE_ID

  • DISABLE_PRINTING

  • MERCHANT_ID

  • UTI

  • LOCALE

  • TIME_TO_LEAVE

Function to start a transaction with parameters.

The supported parameters when starting a transaction are the following: CORRELATION_ID, REFERENCE_ID, DISABLE_PRINTING, MERCHANT_ID, UTI, LOCALE

showTransactionList(Context context)

Function to show transaction list.

showTransactionList(Context context, HashMap<String, String> parameters)

  • LOCALE

Function to show transaction list.

Supported parameters are LOCALE.

showVoidList(Context context)

Function to show list of voidable transactions.

showVoidList(Context context, HashMap<String, String> parameters)

  • LOCALE

Function to show list of voidable transactions.

Supported parameters are LOCALE.

cycleKeys(Context context)

Function to cycle keys.

cycleKeys(Context context, HashMap<String, String> parameters)

Function to cycle keys. Supported parameters are LOCALE.

sendEndOfDayReport(Context context)

Function to send end of day report for active merchant.

requestEndOfDay(Context context, HashMap<String, String> parameters)

  • DISABLE_PRINTING

Function to send end of day for active merchant silently. Supported parameter is DISABLE_PRINTING.

requestLastEndOfDay(Context context, HashMap<String, String> parameters)

  • DISABLE_PRINTING

Function to fetch last end of day result for active merchant silently. Supported parameter is DISABLE_PRINTING.

requestXReport(Context context, HashMap<String, String> parameters)

  • DISABLE_PRINTING

Function to fetch current X report result for active merchant silently. Supported parameter is DISABLE_PRINTING.

sendEndOfDayReport(Context context, HashMap<String, String> parameters)

  • DISABLE_PRINTING

  • SHOW_UI

  • LOCALE

Function to send end of day report for active merchant.

Supported parameters are LOCALE.

requestConfig(Context context)

Function to request the core config, the config is sent as CONFIG_RESULT_ACTION intent.

updateParameter(Context context, HashMap<String, String> parameters)

Function to update the parameters. The supported parameters are the following: printReceipt, useOnScreenSignature, audioSetting, themes and merchantReceipt.

completion(Context context, HashMap<String, String> parameters)

  • REFERENCE_ID

  • DISABLE_PRINTING

  • DISABLE_SIGNATURE_VERIFICATION

  • UTI

  • LOCALE

  • CANCEL_PREAUTH

  • TIME_TO_LEAVE

Function to bring up the completion UI.

completion(Context context, final String firstSix, final String lastFour, final String amount, final String authCode, final String messageId, final HashMap<String, String> parameters)

  • REFERENCE_ID

  • DISABLE_PRINTING

  • DISABLE_SIGNATURE_VERIFICATION

  • UTI

  • LOCALE

  • CANCEL_PREAUTH

  • TIME_TO_LEAVE

Function to perform completion automatically.

cancelPreAuth(Context context, final String firstSix, final String lastFour, final String authCode, final String messageId, HashMap<String, String> parameters)

  • REFERENCE_ID

  • DISABLE_PRINTING

  • DISABLE_SIGNATURE_VERIFICATION

  • UTI

  • LOCALE

  • CANCEL_PREAUTH

  • TIME_TO_LEAVE

Function to perform a preauth cancel automatically.

cancelPreAuth(Context context, HashMap<String, String> parameters)

  • REFERENCE_ID

  • DISABLE_PRINTING

  • DISABLE_SIGNATURE_VERIFICATION

  • UTI

  • LOCALE

  • CANCEL_PREAUTH

  • TIME_TO_LEAVE

Function to bring up the cancel preauth UI.

switchMerchant(Context context, final int merchantId)

Function to switch merchant, the merchant id can be retrieved from the Rapyd Core configuration.

The merchantId is returned by the requestConfig endpoint.

printReceipt(Context context, final String uti, Boolean cardHolder)

Function to print the receipt for a given transaction. UTI of transaction is returned in the transaction result.

printOnCommand(Context context, final String message)

Function to print custom formatted receipt.

cancelTransaction(Context context)

Function to cancel transaction, does not do anything if no transaction is ongoing.

voidTransaction(Context context, final String uti, final HashMap<String, String> parameters)

  • REFERENCE_ID

  • DISABLE_PRINTING

Function to void a transaction. Voids the transaction with the specified UTI. Supported parameters are: REFERENCE_ID, DISABLE_PRINTING

sendApprovalResult(Context context, final Boolean approvalResult)

Sends approval result to the core, this is only used for custom cards that are read and then the PAN is passed on to the caller. For example a bonus card for some store.

requestDailySales(Context context)

Function to request that today's daily sale totals is sent. Result is sent with the DAILY_SALES_ACTION. Note that this function is not sending an end of day report.

startScanner(Context context, HashMap<String, String> parameters)

Starts the scanner for receipt QR code reading. Current implementation only supports scanning preauth QR codes.

getTransactionData(Context context, final String uti)

Get the transaction data for the transaction with the given UTI.

Result is returned with the ACTION_GET_TRANSACTION_RESULT broadcast.

updateLanguage(Context context, String language)

Update the system language of the device.

checkIfTransactionInProgress(Context context)

Checks if a transaction is currently in progress.

Result is returned with the ACTION_GET_TRANSACTION_IN_PROGRESS_RESULT broadcast.

getTransactionsForDay(Context context, final Date startDate, final Date endDate)

Get a list of transactions for the given time period.

Result is returned with the TRANSACTION_LIST_RESULT broadcast.

Format of the response is an JSON array with transaction results.

Download Links
En esta sección: