Poynt Payment Fragments
Poynt Payment Fragments provide a secure and consistent payment experience for merchants and consumers across all applications running on Poynt Smart Terminals. Payment Fragments securely process payment transactions at the PoyntOS level, so your apps do not need to worry about handling the variety of payment methods, the payment process and compliance (e.g. PCI).
Currently the Payment Fragments support the following features:
- Payments using different payment card interfaces (MSR, EMV, NFC, etc.)
- Payments with Cash
- Collect Tip, Receipt options, and Signature
- Collect secure pin for Chip and Pin cards (EMV)
- Multi-Tenders (aka split payments)
- Non-referenced credits and auth only transactions
Integrating with Payment Fragments
When an application need to collect a payment, it can launch the Payment Fragments using the Poynt Payment Activity. To launch the payment activity, you will have to create a Payment object and specify the total amount that needs to be collected, the currency and an optional reference ID. The Payment activity has to be launched with the Payment object using the standard android ‘startActivityForResult()’ method. The Payment Activity will walk both the merchant and consumer through the payment flows (payment method entry and consumer authorization). Once a payment is successfully processed, the fragment returns an updated Payment object with the payment status and processed transaction including the redacted payment card info that you can use to display in your application.
Payment payment = new Payment();
String referenceId = UUID.randomUUID().toString();
payment.setReferenceId(referenceId);
payment.setAmount(amount);
payment.setCurrency(currencyCode);
// start Payment activity for result
try {
Intent collectPaymentIntent = new Intent(Intents.ACTION_COLLECT_PAYMENT);
collectPaymentIntent.putExtra(Intents.INTENT_EXTRAS_PAYMENT, payment);
startActivityForResult(collectPaymentIntent, COLLECT_PAYMENT_REQUEST);
} catch (ActivityNotFoundException ex) {
Log.e(TAG, "Poynt Payment Activity not found - did you install PoyntServices?", ex);
}
To handle the response from the Payment Fragments, you would need to override the ‘onActivityResult()’ method and process the response.
@Override
public void onActivityResult(int requestCode, int resultCode, Intent data) {
super.onActivityResult(requestCode, resultCode, data);
// Check which request we're responding to
if (requestCode == COLLECT_PAYMENT_REQUEST) {
// Make sure the request was successful
if (resultCode == Activity.RESULT_OK) {
if (data != null) {
Payment payment = data.getParcelableExtra(Intents.INTENT_EXTRAS_PAYMENT);
Log.d(TAG, "Received onPaymentAction from PaymentFragment w/ Status("
+ payment.getStatus() + ")");
if (payment.getStatus().equals(PaymentStatus.COMPLETED)) {
Toast.makeText(this, "Payment Completed", Toast.LENGTH_LONG).show();
} else if (payment.getStatus().equals(PaymentStatus.AUTHORIZED)) {
Toast.makeText(this, "Payment Authorized", Toast.LENGTH_LONG).show();
} else if (payment.getStatus().equals(PaymentStatus.CANCELED)) {
Toast.makeText(this, "Payment Canceled", Toast.LENGTH_LONG).show();
} else if (payment.getStatus().equals(PaymentStatus.FAILED)) {
Toast.makeText(this, "Payment Failed", Toast.LENGTH_LONG).show();
} else if (payment.getStatus().equals(PaymentStatus.REFUNDED)) {
Toast.makeText(this, "Payment Refunded", Toast.LENGTH_LONG).show();
} else if (payment.getStatus().equals(PaymentStatus.VOIDED)) {
Toast.makeText(this, "Payment Voided", Toast.LENGTH_LONG).show();
} else {
Toast.makeText(this, "Payment Completed", Toast.LENGTH_LONG).show();
}
}
} else if (resultCode == Activity.RESULT_CANCELED) {
Toast.makeText(this, "Payment Canceled", Toast.LENGTH_LONG).show();
}
}
}
Parameters
Payment object contains a number of parameters that allows developers to configure the payment experience:
cashbackAmount (long) - Presets the cash back amount when customer pays by debit
tipAmount (long) - Presets the tip amount. The tip selection screen will be skipped
tipAmounts (Map) - set by the Payment Fragment and contains the mapping between transactionId and tip amount. In case of a multi-tender transaction, tip can be left on more than one transaction. You should always look at the tipAmount in Transaction.amounts.tipAmount and use tipAmounts map as a fall back.
references (List<TransactionReferences>) - Allows the application to pass custom reference information, such as custom order id and other metadata. This list is returned inside Transaction object once the payment is completed
multiTender (boolean) - starts the payment fragment in the multiTender mode which allows the buyer to pay using 2 or more tenders
authzOnly (boolean) - indicates that this is a pre-auth transaction that will not be part of the open settlement batch until it is captured;
orderId (String) - the id of the Order object which has already been created or will be created after the payment. Having an Order object allow Payment Fragment to display item details and sends the itemized email receipt if the customer chooses to get an email receipt.
order (Order) - including Order object allows Payment Fragment to print itemized receipt if the customer chooses paper receipt option
nonReferencedCredit (boolean) - setting this flag will allow merchant to issue a credit to a card without having a prior sale. This is a high risk permission and typically merchant has to be enabled by the acquirer to issue non-refeenced credits.
disableDebit (boolean) - disables debit card option
disableCheck (boolean) - disables check option
disableOther (boolean) - disables “other” option
disableManual (boolean) - disables manual entry
disableEMVCT (boolean) - disables EMV (chip card) payment
disableEMVCL (boolean) - disables contactless payments
disableMSR (boolean) - disables payments with magstripe cards
disableCash (boolean) - disables cash option
disableTip (boolean) - disables tip if the merchant account is configured to present tip screen.
disableChangeAmount (boolean) - if the payment fragment is invoked to perform refund or capture, setting this flag to “true” will not allow the merchant to edit the amount, i.e. no partial capture or partial refund.
notes (String) - custom note which will be added to the transaction
cashOnly (boolean) - launches Payment Fragment directly into the cash flow
debitOnly (boolean) - only allow debit card payment
creditOnly (boolean) - only allow payment by credit
skipReceiptScreen (boolean) - do not show the receipt screen
skipSignatureScreen (boolean) - do not show signature screen
skipPaymentConfirmationScreen (boolean) - Displays processing screen as opposed to Thank you screen after a payment is complete.
manualEntry (boolean) - launch Payment Fragment into manual card entry flow
readCardDataOnly (boolean) - do not process transaction just return some information about the card (e.g. last 4, first 6, name)
offlineAuth (boolean) - process offline transaction. Can be used if there is no network connectivity. Merchant will be prompted to provide an approval code they obtained from the issuing bank.
offlineApprovalCode (String) - optionally the approval code can be passed in the request to launch Payment Fragment.
disablePaymentOptions (boolean) - hide the “Summary”, “Notes” and “Receipt” options from the Payment Fragment.
Post-Payment Actions
Once a payment has been processed often times it’s required to provide the merchants ability to execute different actions on the processed payments. These include payment actions like void, capture, refund, and get details, which are provided by Payment Fragments through “DISPLAY_PAYMENT” intent.
// start Payment activity to display transaction details
try {
Intent displayPaymentIntent = new Intent(Intents.ACTION_DISPLAY_PAYMENT);
displayPaymentIntent.putExtra(Intents.INTENT_EXTRAS_TRANSACTION_ID, transactionId);
startActivityForResult(displayPaymentIntent, DISPLAY_PAYMENT_REQUEST);
} catch (ActivityNotFoundException ex) {
Log.e(TAG, "Poynt Payment Activity not found - did you install PoyntServices?", ex);
}
This will launch Poynt Payment Activity to display the details of the payment along with allowed actions (void, capture, refund) based on it’s current status.
