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.

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.