Skip to main content
Migo Docs

Process a Terminal Payment

A card-present charge runs inside your app by calling migoSDK.doTransaction(...). The SDK creates the payment on the Migo platform, reads the card over NFC, returns the transaction data for you to confirm, and after authorization hands you the voucher. You finalize it with doFinishTransaction(...) to settle it.

It requires an active terminal β€” see Terminal registration and activation.

At a glance​

doTransaction(amount, currency, merchantDetailId, merchantTerminalId)
β”œβ”€ onCreateTerminalPaymentResponse payment created in backend (status "created")
β”‚ └─ save response.data.id ──► terminalPaymentId
β”œβ”€ onPresentCardRequest ask the customer to tap the card
β”œβ”€ onReadingCardData reading the card
β”œβ”€ onUserCardPinRequest (if needed) cardholder PIN
β”œβ”€ onReturnCurrentTransactionInfo card data ──► transactionConfirmation()
β”œβ”€ onSendingTransactionAuthorization sending for authorization
└─ onVoucherDataResponse isTransactionApproved? ──► doFinishTransaction()

Three pieces of data travel from one step to the next; save them as soon as they arrive:

DataWhere it comes fromWhat it's for
terminalDataonServiceConnectedmerchantDetailId, merchantTerminalId, and the currency
terminalPaymentIdonCreateTerminalPaymentResponse (response.data.id)Finalizing the charge
voucheronVoucherDataResponseDeciding the outcome and finalizing

1. Start the charge​

Take merchantDetailId and merchantTerminalId from terminalData.mPosParameters (received in onServiceConnected), and the currency from the terminal's own configuration:

import com.migo.sdkmigo.presentation.migoSDK
import com.migo.sdkmigo.domain.usecasesparams.DoTransactionParams
import com.migo.sdkmigo.domain.enums.TransactionConfirmationMigoMode

val merchant = terminalData.mPosParameters!!.first()

migoSDK.doTransaction(
DoTransactionParams(
mActivity = this,
transactionAmount = 150.50, // Double, not String
transactionCurrency = merchant.currencyInfoList?.first(), // the terminal's currency
merchantDetailId = merchant.id!!,
merchantTerminalId = merchant.terminalId!!,
confirmationMode = TransactionConfirmationMigoMode.USER_CONFIRMATION,
isApiRest = true
)
)

confirmationMode:

  • USER_CONFIRMATION β€” the flow pauses at onReturnCurrentTransactionInfo and you confirm by calling transactionConfirmation() (recommended, so you can show the amount and card data before authorizing).
  • AUTOMATIC_CONFIRMATION β€” the SDK proceeds to authorization without pausing.

isApiRest = true integrates the charge with Migo's REST backend (payment creation and settlement).

:::caution On MIGO_LINK the reader brings its own screens Everything that follows β€” prompting for the card, reading it, the PIN, and the confirmation β€” applies to MIGO_PAY only. On MIGO_LINK_* the reader drives that experience with its own UI: transactionConfirmation does nothing and the step-by-step callbacks (onPresentCardRequest, onReadingCardData, onReturnCurrentTransactionInfo…) never fire. Your app triggers the charge and waits for the result in onVoucherDataResponse.

Which callback arrives on which provider is detailed in the SDK Reference. :::

Save the payment identifier as soon as the backend creates it:

private var terminalPaymentId: Int? = null

override fun onCreateTerminalPaymentResponse(response: TerminalPaymentResponse?) {
terminalPaymentId = response?.data?.id
}

override fun onCreateTerminalPaymentError(errorMessage: String?, rawResponse: String?) {
// The charge stops here: no further callbacks arrive for this transaction
showError(errorMessage)
}

2. Read the card and confirm​

Implement the MigoSDKCallbacks callbacks. If NFC is off, the SDK calls onNFCStateOff() β€” ask the user to enable it.

override fun onPresentCardRequest(data: PresentCardTransactionMigoData?) {
// Show "Tap the card on the phone"
}

override fun onReturnCurrentTransactionInfo(
info: CurrentTransactionMigoInfo?,
mode: TransactionConfirmationMigoMode?
) {
// info carries amount, brand, cardHolderName, cardObfPan, etc.
// In USER_CONFIRMATION mode, confirm to authorize:
migoSDK.transactionConfirmation(
TransactionConfirmationParams(
mActivity = this,
sendTransactionAuthorization = true, // false to abort
additionalTransactionInfo = null
)
)
}

3. Receive the voucher and finalize​

When the transaction response arrives, the SDK calls onVoucherDataResponse(voucherData). That callback does not mean "approved": it carries the outcome, and you decide what to do with it.

:::info onVoucherDataResponse is a shared callback Both the charge and the void fire it. authorizationMigoType tells you which one arrived, and that decides what to do: you finalize a SALE; you do not finalize a VOID, because the void already settled itself. :::

:::danger Never finalize a void sendTransactionAnnulment already creates the reversal settlement inside the SDK. If you also call doFinishTransaction(status = "reversed"), a second settlement is created: the business is debited twice. On the VOID branch, just close your UI. :::

The decision is as follows:

Voucher stateWhat to do
isTransactionApproved == falseDon't finalize. Show responseCodeDescription
Approved and type SALEdoFinishTransaction(status = "approved")
Approved and type VOIDDon't call doFinishTransaction. Close your UI and wait for the reversal callbacks
Approved, any other typeInvalid type for this flow. Don't finalize

:::note About responseCode "14" It is the synthetic voucher the SDK builds when the attempt expired or was cancelled at the reader: the card was never read. It always arrives with isTransactionApproved = false, so the check above already covers it; authorizationMigoType only tells you whether a charge or a void expired, for the message you show. :::

override fun onVoucherDataResponse(voucher: VoucherMigoData?) {
voucher ?: return

// Declined, expired, or cancelled at the reader
if (voucher.isTransactionApproved != true) {
showError(voucher.responseCodeDescription ?: "Transaction declined")
return
}

// Void: the SDK already settled the reversal. Just close the UI.
if (voucher.authorizationMigoType == AuthorizationMigoType.VOID) {
closeReversalUI(voucher)
return
}

if (voucher.authorizationMigoType != AuthorizationMigoType.SALE) {
showError("Invalid transaction type")
return
}

migoSDK.doFinishTransaction(
DoFinishTransactionParams(
mActivity = this,
terminalPaymentId = terminalPaymentId!!, // Int, from onCreateTerminalPaymentResponse
status = "approved",
authorizationId = voucher.authorizationId!!, // processor authorization code
voucherData = voucher
)
)
}

override fun onCreateSettlementResponse(response: CreateSettlementResponse?) {
// Settlement created β€” response.data carries idRequest, card, balance, cardTransferId
}

override fun onCreateSettlementError(errorMessage: String?, rawResponse: String?) {
// Handle the settlement failure
}

To undo an already authorized charge, see Reverse an authorized charge.

Capture the cardholder signature​

Some transactions require the cardholder's handwritten signature β€” typically those above the brand's CVM limit. This applies to Migo Link integrations.

When it happens, the SDK calls onSignatureRequired(voucher) instead of onVoucherDataResponse:

doTransaction()
β”œβ”€ no signature required ──► onVoucherDataResponse(voucher)
└─ signature required ──► onSignatureRequired(voucher)
β”œβ”€β–Ί doFinishTransaction() ← always, signed or not
└─► (your capture screen)
└─► doSignatureTransaction(historyItem, bitmap)
└─► onSignatureListenerResponse(reason, code)
└─ if reason == null ──► onSignatureUploaded(url)
/ onSignatureUploadError(msg, code)

Three rules that prevent most mistakes:

  1. onSignatureRequired and onVoucherDataResponse are mutually exclusive. Don't wait for both.
  2. Closing the transaction does not depend on the signature. Call doFinishTransaction() as soon as onSignatureRequired fires, whether the customer signs or not.
  3. The upload only happens if the reader accepted the signature. If onSignatureListenerResponse carries a reason, there is no upload.
override fun onSignatureRequired(voucherData: VoucherMigoData?) {
finishTransaction(voucherData) // 1) close the charge just like the normal flow
showSignatureCaptureUI() // 2) show your capture screen
}

fun submitSignature(bitmap: Bitmap) {
migoSDK.doSignatureTransaction(
DoSignatureTransactionParams(
historyItem = signatureHistoryItem, // the transaction that asked for the signature
signature = bitmap
)
)
}

override fun onSignatureListenerResponse(reason: String?, code: Int?) {
if (reason == null) {
// Signature stored in the reader. The upload starts on its own.
} else {
showError("Signature error ($code): $reason")
}
}

override fun onSignatureUploaded(signatureUrl: String?) {
// The signature now travels with the charge and can be redrawn in the detail
}

override fun onSignatureUploadError(errorMessage: String?, code: String?) {
// A warning, not a payment error: the charge is valid and the reader already has the signature
}

You don't need to resize the Bitmap: the SDK converts it to PNG and rescales it if it exceeds the server maximum. If historyItem is null, the SDK responds onSignatureListenerResponse(reason = "Transaction not found", code = null) and does nothing else.

:::note branchId is required for the signature The upload uses the branchId you passed in initService. If it is null or <= 0, the signature is not uploaded and you receive onSignatureUploadError. The transaction is unaffected. :::

The signature comes back in the transaction detail (getSingleTerminalTransaction), in the _signatureUrl and _signatureData fields of HistoryMigoItem.

Settlement​

Every approved charge is finalized with doFinishTransaction(status = "approved"), which creates the settlement on the platform and fires onCreateSettlementResponse. The settlement vehicle β€” where the money lands β€” is defined with your commercial contact when the terminal is activated. The current options are:

VehicleNotes
CardTransfer to a card (SettlementData.card / cardTransferId)
Bank accountDeposit to a bank account
BalanceBalance on the Migo platform (SettlementData.balance)

Batch close against the provider (distinct from per-transaction settlement) is triggered with migoSDK.sendSettlement(SendSettlementParams(mActivity)), which responds in onSettlementResponse(success, message). It applies to MIGO_PAY only: on MIGO_LINK_* the call does nothing.

Notes​

  • The terminal payment record the SDK creates starts with status created and totalAmount 0; it moves to approved when you finalize with doFinishTransaction. Monetary fields travel as strings.
  • If connectivity is lost after authorization, the SDK stores the transaction locally and reports onStoringOfflineAuthorizedTransaction().
  • Terminal payment backend errors (CustomResponse envelope):
CodeNameMeaning
7307ERROR_CREATING_TERMINAL_PAYMENTTerminal payment creation failed
7308ERROR_TERMINAL_PAYMENT_STATUSError retrieving the terminal payment status
7400TERMINAL_NOT_FOUNDThe referenced terminal does not exist
7401TERMINAL_INACTIVEThe terminal is not active (activation pending)
7402TERMINAL_PAYMENT_NOT_FOUNDThe terminal payment does not exist
7006EXTERNAL_ID_ALREADY_EXISTSDuplicate externalId

See the Error catalog for the full list of codes and their semantics.