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:
| Data | Where it comes from | What it's for |
|---|---|---|
terminalData | onServiceConnected | merchantDetailId, merchantTerminalId, and the currency |
terminalPaymentId | onCreateTerminalPaymentResponse (response.data.id) | Finalizing the charge |
voucher | onVoucherDataResponse | Deciding 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 atonReturnCurrentTransactionInfoand you confirm by callingtransactionConfirmation()(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 state | What to do |
|---|---|
isTransactionApproved == false | Don't finalize. Show responseCodeDescription |
Approved and type SALE | doFinishTransaction(status = "approved") |
Approved and type VOID | Don't call doFinishTransaction. Close your UI and wait for the reversal callbacks |
| Approved, any other type | Invalid 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:
onSignatureRequiredandonVoucherDataResponseare mutually exclusive. Don't wait for both.- Closing the transaction does not depend on the signature. Call
doFinishTransaction()as soon asonSignatureRequiredfires, whether the customer signs or not. - The upload only happens if the reader accepted the signature. If
onSignatureListenerResponsecarries areason, 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:
| Vehicle | Notes |
|---|---|
| Card | Transfer to a card (SettlementData.card / cardTransferId) |
| Bank account | Deposit to a bank account |
| Balance | Balance 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
createdandtotalAmount0; it moves toapprovedwhen you finalize withdoFinishTransaction. Monetary fields travel as strings. - If connectivity is lost after authorization, the SDK stores the transaction locally and reports
onStoringOfflineAuthorizedTransaction(). - Terminal payment backend errors (
CustomResponseenvelope):
| Code | Name | Meaning |
|---|---|---|
7307 | ERROR_CREATING_TERMINAL_PAYMENT | Terminal payment creation failed |
7308 | ERROR_TERMINAL_PAYMENT_STATUS | Error retrieving the terminal payment status |
7400 | TERMINAL_NOT_FOUND | The referenced terminal does not exist |
7401 | TERMINAL_INACTIVE | The terminal is not active (activation pending) |
7402 | TERMINAL_PAYMENT_NOT_FOUND | The terminal payment does not exist |
7006 | EXTERNAL_ID_ALREADY_EXISTS | Duplicate externalId |
See the Error catalog for the full list of codes and their semantics.
Relatedβ
- Cancel an in-progress charge β abort before authorization.
- Reverse an authorized charge β undo an approved charge.
- SDK Reference β every method, callback, and entity.
- SDK Install β initialization and terminal activation.