Overview

The MX Merchant Terminal API's enable merchants and integrators to create, manage, and confirm payment transactions directly against registered payment terminals. With these, they can initiate new transactions (such as sales, refunds, or authorizations), monitor their progress in real time through a polling mechanism, and retrieve finalized transaction details once the payment has been processed.

Key Details

Transaction Creation

The transaction creation process begins with defining the necessary input parameters and making a request to the MX Merchant Terminal API. This request initiates a new payment transaction on the specified terminal and returns key identifiers that are required for the subsequent polling process. The following steps outline how to create a transaction and extract the information needed to track its status.

1. Input Parameters created before Transaction

• merchantId - MerchantId
• replayId - Client-provided idempotency key passed in to POST transaction payload
• terminalId - Terminal-specific identifier, existing record of device on MXM system

2. Create transaction against MXM Terminal API

• POST {env-}api2.mxmerchant.com/terminal/v1/transaction/merchantid/{merchantId}/terminalid/{terminalId}
  • sandbox: sandbox-api2.mxmerchant.com/terminal/v1/transaction/merchantid/{merchantId}/terminalid/{terminalId}
  • production: api2.mxmerchant.com/terminal/v1/transaction/merchantid/{merchantId}/terminalid/{terminalId}
• payload:
  • amount
  • type from ['Sale', 'Refund', 'Authorization']
  • replayId
• Response: 200 OK
• Extract from response:
  • terminalPaymentId from response?.data?.prioritypaymentsystems?.mxmerchant?.merchant?.devicePaymentAuditId
  • status from response?.status
    • Expect: 'SENTTOTERMINAL'

3. Input Parameters created before Polling:

• terminalPaymentId - Primary transaction reference, a GUID from the transaction creation

Transaction Polling and Confirmation Process

Core Polling Loop:

• Begin two seconds after confirmed transaction creation
• Polling mechanism: 2-second intervals for a 2-minute duration

Primary Polling Request:

• Endpoint:

  • GET {env-}api2.mxmerchant.com/terminal/v1/transaction/merchantid/{merchantId}/transactionid/{transactionId}
    • sandbox: sandbox-api2.mxmerchant.com/terminal/v1/transaction/merchantid/{merchantId}/transactionid/{transactionId}
    • production: api2.mxmerchant.com/terminal/v1/transaction/merchantid/{merchantId}/transactionid/{transactionId}

• Purpose: Poll for transaction status updates

  • merchantId - Merchant identifier for the business account
  • terminalPaymentId - Unique identifier for the specific transaction
  • Extract from response:
    status = response?.data?.status;
    message = response?.data?.message;
  • Interpret: status

Status Processing of Each Response from Polling Request:

• Success Path: When status is "approved", "declined", or "error"

  • Cease polling and interpret as transaction created with finalized status
  • Retrieve additional transaction details using a replayId

• Failure Path: When status is "canceled", "cancelled", or "failed"

  • Cease polling and interpret as transaction not created , and with no status
  • message will contain information on transaction failure
  • "cancel" method not implemented for Dejavoo devices

• Pending Path:

  • Any status not in ["approved", "declined", "error", "canceled", "cancelled", "failed"] should continue polling for final status

Final Transaction Object Lookup

• Endpoint:

  • GET {env.}api.mxmerchant.com/checkout/v3/payment?merchantId={merchantId}&replayId={replayId}
    • sandbox: sandbox.api.mxmerchant.com/checkout/v3/payment?merchantId={merchantId}&replayId={replayId}
    • production: api.mxmerchant.com/checkout/v3/payment?merchantId={merchantId}&replayId={replayId}

• Purpose: Retrieve detailed transaction information after final status confirmation

  • replayId - Transaction replayId identifier for transaction lookup
  • merchantId - MerchantId (same as above)
  • This is the existing route to retrieve specific transaction record replayId and merchantId