Getting started with APM (QR code based)

QR code scan - let your customers choose to pay the way they want to pay!

Check the QR code Payment API reference here.

PPaaS brings an excellent in-store experience for consumers with speedy QR code transactions that are considered an alternate payment mode over any traditional card-based transaction. When it comes to QR codes, consumers can be offered two ways of completing a transaction with PPaaS: either by scanning a code displayed on the payment device or by showing the code on their mobile phone, which is then scanned by the payment device. The same ease and speed apply to other payment methods; PPaaS provides a comprehensive range of APMs for in-store payments, with easy access for developers to connect to the platform through APIs and plugins.

Please note that these APIs, SPIs, and callbacks are also used in the Buy Now Pay Later (BNPL) service. From a PPaaS payment perspective, once the payment request is authorized, we have no further information regarding the payment mode either direct wallet payment or installment payment.

Overall APM data flow

Integration to PPaaS APM service would involve at least two integrations. APIs are used for communication between payment device/POS and PPaaS, while SPIs facilitate the connection between PPaaS and APM service providers. In addition, if there is a notification from an APM service provider back to PPaaS, you should use the API CallBack integration. However, note that the callback part is optional and depends on each APM solution flow as we can also fetch the payment result from the SPI with the GET transaction endpoint.

Configure QR payment with PPaaS

PPaaS supports various QR code wallet providers. With different APM wallets, it comes with different configurations required. The ability to use these configurable functionalities depends on both APM provider capability to support and merchant aggregator preference. For example, a merchant aggregator can easily turn off the cancellation function if you prefer to only offer a refund to the consumer by deactivating the cancel parameter.

For any new APM wallet partner to integrate with PPaaS Ecosystem, stay tuned!

Configure QR payment mode

This QR payment is for the use of sales transactions only. Cancellation and refund transactions can still be done through a standard procedure via a payment device or via a portal.

QR mode as merchant scan

Merchant scans the QR code provided by the customer.

QR mode as consumer scan

Consumer scans the QR code provided by the merchant.

For the QR payment mode with the consumer scan mode, there are two solutions to acquire the QR code:

1. The APM provider generates the QR code

2. The APM provider sends PPaaS the URL to generate the QR code

The mentioned solution fully depends on the APM provider and the proxy implementation to use a QR code generator.

APM directly provides the QR code

In the codeValue field, the text value should be in a URL format that hosts the QR code image so that the payment device can display the QR code directly.

For example, "codeValue": https://qr.alipayplus.com/showQrImage?code=2816660400931LBC9hrwh7Qniq30nPfv4Z4L&picSize=S

APM provides the payment URL and PPaaS helps generate the QR code

In the codeValue field, the text value should be in a URL link that PPaaS can use to generate a QR code. After getting the URL, the proxy will call the QR code generator to get the QR code image from the given URL.

For example, "codeValue": "https://www.paypal.com/qrcodes/integrated?payer_id=6T4MWHR5E2ADN&merchant_ref_id=EZP-ac79b5ef-c4dc-42f0-af6e-b8f680301dcb&time_stamp=1677592719"

Configure transaction type

• Sales: With the alternative payment method with a QR code, the merchant benefits from the sales payment transaction through both the merchant and consumer scanning the QR code.

• Cancellation: After a sales transaction has been authorized, there will be a certain period of time allowance for the merchant to cancel the sales transaction. The allowance is directly driven by the APM providers, and some providers do not allow the cancellation as the transaction will get settled right away after authorization from their scheme.

• Refund: As mentioned above regarding the cancellation, after the time allowance dues, the merchant only allows making a refund.

QR payment use cases

Once you have configured our QR payment services, the merchant can perform the following use cases:

• Sale transaction with consumer scan

• Sale transaction with merchant scan

• Cancel transaction

• Refund transaction

• Get transaction

Sale transaction with merchant scan

The merchant scan is also called consumer presented mode. For a sale transaction, the payment interaction can happen through merchant scan. Here, the consumer displays the QR code, and the merchant can scan the QR code.

Sale transaction with consumer scan

The consumer scan is also called merchant presented mode. For a sale transaction, the payment interaction can happen through consumer scan. Here, the merchant displays the QR code, and the consumer can scan the QR code.

A successful response creates the payment object, and the authorization transaction is initiated. The value returned in the response body is the newly created transaction. The operation is asynchronous, the returned transaction may not be completed yet. Use the get transaction API to check for the status of this transaction.

Cancel transaction

PPaaS Payment API allows you to reverse a payment transaction through the cancellation transaction if it is supported by the corresponding APM service provider. The duration of the cancellation allowance depends on the APM service provider. After this duration ends, the transaction cannot be cancelled, and a merchant should resort to making a refund instead.

Preconditions for a cancellation and refund If the Merchant Approval Code (MACO) is enabled for refund transactions, the merchant supervisor can provide the approval code to process to refund or cancel. This code is set up at the merchant level during the onboarding process. If the approval code is not available or incorrect during the transaction processing, the validation fails and results in an error, Unauthorized. Authentication of the caller failed.

Overall flow of cancellation and refund via a payment device

Overall flow of cancellation and refund via a PPaaS portal

Please note that the cancellation allowance directly depends on APM wallet provider. For example, Alipay+ allows you to cancel a transaction before 00:15 UTC+8 of the following day.

Refund transaction

A refund can either be partial or full. Depending on the APM wallet provider, some constraints might be related to refund acceptance.

Get transaction

To inquire a specific transaction for the details or its current status, you can use this endpoint GET /payment/v1/transactions/{transactionId}. Note that if you want to see multiple transactions with a certain time period or status, the PPaaS portal can provide this list of transactions. PPaaS also uses this endpoint to fetch the transaction status of a payment and refund in case of not getting the result notification from the APM.

Transaction life cycle and state machine

Each transaction type has different states throughout its life cycle. Some of the states are intermittent states which will, later, transcend to other states based on the scenario. However, only the stable states of each transaction type should be used for any further operational action.

Sales

A sales transaction is an asynchronous transaction, once validated the request, the transaction will be in the “authorizing” state until it gets approved, rejected, or even aborted. Either receiving a callback API from APM or fetching the result is required to update the next sales state.

Cancellation

To make a cancellation from a previous sales payment, the merchant can do so only when the current original payment directs Authorized. As mentioned above regarding the direct settlement, some of the APM providers also have a limited timeframe for cancellation allowance, after the status has transitioned to captured, the transaction is no longer eligible to get cancelled.

Since a cancellation transaction is a synchronous transaction, after the API/SPI is called, the response would allow the merchant to inform the customer right away if the cancellation has been completed and the original payment is reversed.

Refund

The refund functionality allows a merchant to partially or fully return the money back to the consumer after the cancellation eligibility is no longer an option. The refund API is an asynchronous call, either receiving a callback API from APM or fetching the result is required to update the next refund state.

Summary of all transaction types and stable states

Scenarios of transaction types and statuses based on the reason.

Example user journey on a payment device

This section shows the user journey examples with the Alipay+ service.

• Sale transaction with merchant scan

• Sale transaction with consumer scan

• Cancel a transaction

Sale transaction with merchant scan

Enter transaction details

Select the payment method

Select the wallet provider

Select the QR scanning method

Payment device scans the QR code

Transaction processing

Success notification screen (After the payment has been authorized)

Customer receipt options

Authorized sale transaction receipt

Sale transaction with consumer scan

Enter transaction details

Select the payment method

Select the wallet provider

Select the QR scanning method

Payment device scans the QR code

Transaction processing

Success notification screen (After the payment has been authorized)

Customer receipt options

Authorized sale transaction receipt

Cancel a transaction

Select transaction list

Retrieving the transaction data

Select the transaction

View the transaction details

MACO display - This screen displays only if MACO is enabled

Transaction processing

Customer receipt options

Authorized cancel transaction receipt