Skip to main content

Best Practices

Here you can find the best practices for integration, interpreting webhook notifications, communicating with your customers, and handling return payments.

Providing Customer info via the Session​

The Session API allows merchants to register customers and initiate the bank linking flow. This critical step is the merchant’s opportunity to create a robust user profile for an optimal customer experience. Link Money uses the data provided through the session API alongside data collected from our Data Access Networks (DANs) and fraud providers to accurately decision payments and mitigate fraud. In addition, the Session API can be leveraged to enhance the user experience by providing payment information on the Link Money UI. Some examples of field usage are listed below.

  • orderDetails: All fields in this section will be used to enhance the UX if the merchant wants payment details to be surfaced on the Link Money UI. It is also used to mitigate fraud and maximize the authorization rate.
  • customerProfile: All fields in this section will be used to enhance risk decisioning, maximizing Authorization rate and minimizing returns.
  • Other: phoneNumber and billingAddress are both extremely valuable to fraud detection models, although not mandatory, all best practice integrations should include these fields.

Creating Payments via the Session​

The most simple way to create payments while a customer is in session is to provide the payment details in the session request body. Payments will be initiated when the customer successfully finishes the Pay by Bank flow and the payment decision will be communicated in the redirect url as well as in the PAYMENT webhook.

paymentDetails: Providing the payment details will enable merchants to initiate transactions after successful account linking attempts. Customers will be prompted with a pay now screen including the transaction amount.

Payment Webhook: Subscribing to this webhook is a requirement to enable pending state, a payment decision that maximizes authentication rate and minimizes transaction risk.

Surfacing HTML Button object at checkout​

To maintain brand uniformity across merchants Link Money provides this UI asset via the Pay by Bank SDKs. Use the sessionUrl returned by the session API in the SDK config to enable the createButton method. The button offered by the client SDK chosen for integrating with Link Money should be displayed on your checkout UI to the customer when the following action is expected to be a redirect to the linking and payment experience. Use CSS to make necessary changes for UI synergy.

Prerequisite​

Please subscribe to Link Money's webhooks as part of the SDK integration.

Surfacing Customer Payment Info​

Following the customer-linking phase, LinkCore will provide the Merchant with customer information regarding the chosen financial institution (FI) that will be invoked during payments. It is recommended that the Merchant surfaces this information in a best-practice fashion to the customer. The following actions are encouraged to provide a transparent experience:

Displaying linked banking account information in billing​

  • Event
    • Following the initiation of linking to a customer’s financial institution via the SDK, the Merchant can then make a call to the getAccounts method in the SDK, passing in the customerId and returning with:
      • FIS Name (e.g. Chase, Wells Fargo, etc.)
      • Account Type (e.g. Checking)
      • Last 4 digits of Account Number
  • Actions for Merchant
    • It is recommended for the Merchant to display these three fields within the billing/account page for the customer in a similar fashion.

Account Linking Button​

Best Practices Button

Utilizing Webhooks & Communicating with Customers​

Following the integration of the Link Money SDK, Merchants will get the ability to subscribe to and listen for key webhook events, which will allow the Merchant to provide an intuitive and transparent experience to their end-customer. Link Money encourages our Merchant partners to take the following actions to communicate with customers following respective webhook events:

  • Events
    • customer.account.deactivated
  • Actions for Merchant
    • Surfacing in Billing UI utilizing Link Money SDK:
      • Add a text with the following statement: “Error, please re-link the bank account.”
      • Provide a button for the customer to click to re-initiate the linking flow, which will automatically deactivate the existing payment method on Link Money's backend.
    • Outreach channels (email, push):
      • Utilize existing internal communication channels to notify your customer that an existing linked payment method needs to be relinked and provide them with the ability to re-initiate the Linking flow.

Communicating to a customer a “pending” payment status​

We anticipate a small percentage of transactions going into pending status. For the majority of transactions, merchants will receive an authorized or failed event right away. Within a purchasing flow, merchants should not wait for the authorized webhook to display the confirmation page to the customer. If a pending event is received, you may prefer to display a confirmation page with a pending status. Complete the purchase once the authorized event has been received.

  • Events
    • payment.pending
    • payment.authorized
    • payment.failed
  • Actions for Merchant
    • Surfacing in payment status page UI after finalizing Link Money SDK Flow and receiving payment.pending:
      • Add a text with the following statement: “Thank you for submitting your order. We will send you a confirmation once the payment has been accepted along with your order details.”
    • Outreach channels (email, push):
      • payment.pending will usually be followed by payment.authorized, but can result in payment.failed; utilize existing internal communication channels to notify your customer the updated status of their payment.

Utilizing Webhooks & Merchant Taking Internal Actions​

Following the integration and utilization of the Link Money webhooks, there are certain scenarios where the Merchant is recommended to take the following internal actions within their system:

Status on payment (based on TransferID)​

  • Events
    • payment.created
    • payment.pending
    • payment.authorized
    • payment.scheduled
    • payment.initiated
    • payment.succeeded
    • payment.disbursed
  • Actions for Merchant
    • It is recommended that the customer either gets a push notification, email or update in the order form on the status of their transaction.
    • It is recommended that the Merchant considers payment.authorized as the event that signals that a payment has been accepted by Link Money.

Payment failed for X reason​

  • Events
    • payment.failed
  • Actions for Merchant
    • It is recommended that the customer either gets a push notification, email or update in the order form on the state of the failed transaction.

Return Payments / Valid Disputes​

For cases where a payment needs to be returned, either due to an error surrounding a wrong initial amount or a general dispute that has been raised by the customer, the decision for a return is purely in the control of the Merchant, who can initiate the return payment in the following way:

Initiating the return payment​

  • API Call
  • Action for Merchant
    • Reserve Funds
      • The Merchant is responsible for maintaining a backend reserve on their respective bank account.
    • Accounting & Billing
      • The Merchant is responsible for all backend reconciliation and account management of these different transactions as part of the same customer order.
      • The Merchant will be billed for the return as a separate transaction.