Identity Management Platform (IdM)
Billing Agreement API
This section describes the possible merchant setups and highlights crucial data for in-app transaction processing.
At the core of the structure is the merchant, which owns at least one store. Merchants and stores are represented by abstract entities. Usually the merchant will configure one bank account at the merchant entity to receive the settlement, however it is possible to configure a separate bank account at each store as well. The settlement reports are in turn tied to the bank account(s), since they contain the break down of the received bank statement.
To enable the processing of in-app transactions, each store needs a Payment Provider Contract (PPC) linked to it, which is uniquely defined by the contract UUID. Each PPC contains a reference to the bank account which will be used for settlement of transactions processed with this contract.
To ensure proper reporting, the merchant (or the franchise) needs to maintain a mapping of the stores and PPC UUIDs, since the later one is needed during transaction processing. The same PPC UUID needs to be used for processing refunds, which alternatively can be processed from terminals connected to the store where the transaction was processed.
In case the merchant is part of a franchise structure there will be an additional corporation level in the hierarchy, below which the corporate owned merchant structure and any number of franchisee merchant structures are located.
User management flows
It is assumed that the merchant already has an existing user management including e.g. account creation and login inside the merchant app.
Billing Agreement management
A billing agreement is needed to process in-app transactions. It is best practice to manage the billing agreement at the merchant back end and not store any sensitive data inside the merchant app.
Create Billing Agreement
The creation of the billing agreement is initiated by the user within the merchant app, e.g. during account setup, account configuration or before the first PayPal transaction.
Therefore the merchant back end needs to initiate the billing agreement to receive the approvalUrl and the billingToken, which is a temporary reference until the final agreementId is created.
The user needs to be redirected to the approvalUrl to log into his/her PayPal account and confirm the billing agreement.
Once the user got redirected after the confirmation, the final step is to create the billing agreement and receive the agreementId, which needs to be saved on the merchant back end and linked to the user account.
Cancel Billing Agreement
The merchant app needs to provide an option to cancel the billing agreement linked to the user account.
The merchant back end then collects the required data to perform the cancel request towards the Verifone back end.
Once the successful response is received, the agreementId is deleted from the user account and the same is confirmed to the user inside the app.
Set Billing Agreement as default payment option
It is recommended to provide the option to set the billing agreement as the default payment method, e.g. in the configuration or during transaction processing. However, it is up to the merchant if and how this is implemented.
Best practice is to store the agreementId on the merchant back end only. The app only needs to be aware of the availability of a billing agreement and if it should be used as the default payment method.
Transaction processing with Billing Agreement
PayPal risk management
PayPal requires the integration of their Magnes SDK, which is a portion of PayPal's fraud and risk management. From the Magnes SDK description:
With direct access to the mobile application, Magnes accesses necessary information from the device and provides the data to PayPal Risk Services for early risk identification and mitigation. Magnes is implemented in the form of a library available for the Android and iOS platforms.
The high level steps to integrate the Magnes SDK in PayPal transaction processing are shown below:
Further implementation details can be found in the PayPal Magnes SDK documentation.
Reference merchant app implementation
This section shows sample screens of the app, showcasing above flows for Billing Agreement management and transaction processing. Some code samples are provided as well.
Further details will be available soon.
Reference merchant back-end implementation
Further details will be available soon.