LogoLogo
Connect
Connect
  • 🏡Welcome to LHV Connect API
  • 📺News and Updates
    • 📈Performance and Stats
    • 🔔Notice of Change
  • 🧭Quick Start Guide
  • 🎥Connect Fundamentals
    • Authentication and Certificates
    • Environments
    • Messaging Pattern
    • Service Provider model
    • Technical limitations
    • Encoding and Languages
    • Response Compression
    • Dates and Time Zones
    • Response Codes and Error handling
    • Onboarding
    • Live Proving
    • LHV UK and Estonia integrations
    • FAQ and Tips
  • 📖Service Catalogue
    • 💚Heartbeat
      • Heartbeat - GET
      • Heartbeat Advanced - GET
    • 📩Messages Services
      • Get next message
      • Get list of messages
      • Get list of messages V2
      • Get message by response ID
      • Get list of requests
      • Get request by request ID
      • Count number of messages
      • Mark message as processed
      • Mark batch of messages as processed
      • Mark batch of messages as processed V2
      • Messages Metadata
      • Get compressed message for testing
    • 💰Account Information Services
      • Account Balance
      • Account Statement
      • Transaction Notification
        • Incoming Bacs Credit Notification
    • 💸Payment Initiation Services
      • Pain.001.001.09
      • Pain.002.001.10
      • Samples
      • Authentication methods
      • Payment Scheme Selection
      • Payment Return Initiation
      • Payments Service Idempotency
      • Payments Originating Overseas
      • Legacy documents
        • pain.001.001.03 format
    • ✅Confirmation of Payee Services
      • Confirmation of Payee - Requester
      • Confirmation of Payee - Responder
    • 😶‍🌫️VIBAN Services
      • VIBAN Open
      • VIBAN Bulk Open
      • VIBAN Modify
      • VIBAN Info
      • VIBAN Close
      • VIBAN Notification
    • 🔗Indirect Scheme Access
      • Agency Account Synchronization
      • RTF - Routing Table Files message
      • 🧾Payment Collection Services
        • 💷Bacs Direct Debit
          • Bacs Direct Debit Mandate Initiation Request
          • Bacs Direct Debit Mandate Initiation Response
          • Bacs Direct Debit Mandate Initiation Response Confirmation
          • Bacs Direct Debit Mandate Cancellation Request
          • Bacs Direct Debit Mandate Cancellation Response
          • Direct Debit Incoming Collection Notification Request
          • Direct Debit Collection Notification Response
          • Direct Debit Collection Notification Response Confirmation
          • Direct Debit Reversal Notification Request
          • Examples
    • 📨Webhooks
      • Webhook Format and Processing
      • Managing Webhook Configurations
      • Webhook Security
      • Webhook Metadata
      • Full Bodied Webhooks
  • 🗓️Reference
    • Glossary
    • Code Reference Tables
      • Balance Type Codes
      • Credit and Debit Transaction Codes
      • Payment Scheme Codes
      • Direct Debit Scheme Codes
      • Payment Reject Codes
      • Payment Return Codes
      • Bacs Direct Debit Mandate Reject Codes
      • Bacs Direct Debit Reject Codes
      • Bacs Direct Debit Reversal Reason
      • Bank Transaction Codes
      • Transaction Purpose Codes
      • Category Purpose Codes
      • Private Person Identification Codes
      • Organisation Identification Type Codes
      • Payment Priority Codes
      • Charges Bearer Codes
  • ☎️Support
    • Contact
Powered by GitBook
On this page
  • Idempotency Keys
  • Detailed Logic

Was this helpful?

  1. Connect Fundamentals

Messaging Pattern

PreviousEnvironmentsNextService Provider model

Last updated 1 year ago

Was this helpful?

The fundamental core of the Connect API is built on asynchronous messaging, which now offers options for parallel processing and various strategies to enhance your integration. You can think of the client message container as an inbox. The client initiates by sending a request to the server and then periodically checks the inbox for a response. If there are any messages in the inbox, the default behaviour is to return the oldest unread message.

The lifecycle of a single message encompasses three stages:

  1. Sending the request

  2. Retrieving the response

  3. Deleting the response.

This is illustrated below:

A typical flow of API requests for payment and account-statement messages respectively:

POST [base-url]/payment                 # submit payment request
GET [base-url]/messages/next            # get response message with first payment status
# process message on customer side
DELETE [base-url]/messages/[Message-Response-Id]    # confirm message received

POST [base-url]/account-statement       # submit account statement request
GET [base-url]/messages/next            # get response message with account statement data status
# process message on customer side
DELETE [base-url]/messages/[Message-Response-Id]    # confirm message received

Idempotency Keys

Idempotency keys are an optional feature that allow you to ensure that your message request is processed at most once. This means you will not risk Connect acting on your message request twice if you retry an HTTP request due to a network interruption. Any such duplicate will be harmlessly rejected.

Idempotency keys are an X-Idempotency-Key header that you add to your HTTP request. If present, the header value must be a UUID, generated uniquely for each unique message request. For example

X-Idempotency-Key=bfce988a-1bc1-47fc-93d6-a5b8115cea64

The above example was generated by UUID.randomUUID() in Java (from java.util.UUID). Similar functions can be found in virtually any programming language, often as part of the standard library. No particular version of UUID is required - any standard form is accepted (case insensitively)

Connect will accept the first HTTP request with this idempotency key, but if another request with the same key is received, it will instead reject the message with an HTTP 409 (CONFLICT) status. This is an error code, and does mean something has gone wrong somewhere, but it also means that a previous request did succeed, so Connect has received your message fine.

Connect is guaranteed to detect and reject duplicate idempotency keys with up to 24 hours between them. In practice, it may detect those even further apart, but this should not be relied upon.

Idempotency keys should never be reused, even days apart, even for requests to different endpoints. The only reason that two HTTP requests should use the same key is if one is a retry of a failed request. For fresh requests, concerning a new message, you must generate a new UUID each time. As long as you use a standard UUID-generating function, you do not have to worry about duplicates being generated

Detailed Logic

In most cases you do not need to implement any logic by hand, as most HTTP client libraries will let you declaratively ask for retries, similar to the following pseudocode.

# This is not real code
def make_message_request(endpoint, body):
    idempotencyKey = generate_uuid()
    httpClient.post(
        endpoint,
        body,
        headers={ "X-Idempotency-Key": idempotencyKey },
        retryLimit=3,
    )

But for the purposes of illustration, this is the full logic that should result.

def make_message_request(endpoint, body):
    idempotencyKey = generate_uuid()
    for attempt in range(0, 3):
        try:
            httpClient.post(endpoint, body, headers={ "X-Idempotency-Key": idempotencyKey })
            return # Success
        except NetworkException as e:
            # Request failed
            log(e)

Observe that the same idempotency key may be sent multiple times. This is because all of those HTTP requests belong to one logical message request. In contrast, a new message request will get a new idempotency key.

🎥
Connect Inbox-Style Messaging Flow