PgClient events

PgClient communicates with the application using events.

Typical transaction flow looks like this:

  • Charge/Authorize/Refund method is called
  • TransactionStarted event is raised
  • ProgressInfo event is raised multiple times
  • [optional] SignatureRequested event is raised for some transactions
  • [optional] BeepRequested event is raised for some transactions
  • [optional] more ProgressInfo events
  • depending on outcome, one of the following events is raised:
    • TransactionFinished: transaction was successfully processed to the end and it was either approved or declined. data provided with the event to notify customer or store in your local system.
    • Error: an error occurred and the transaction was not processed.
    • TransactionCanceled: your application has canceled the transaction.

Event reference

Most of the events carry with them useful additional information.

TransactionStarted event

Raised when the transaction starts.

It carries the information about payment request.

Arguments:

  • object sender: object which raised the event
  • TransactionStartedEventArgs args: transaction details.
    • TransactionRequest property with payment request information:
      • Amount: the amount to be charged from the credit card holder
      • Currency: ISO 4217 code of currency of the amount (e.g. “EUR”)
      • InstallmentCount: number of installments
      • ExternalId: external identifier, used by 3rd party apps to identify the transactions in their own system
      • CallbackUrl: callback URL to be called by the gateway after payment transaction ends
      • Id: the id of the transaction

TransactionFinished event

Raised after the transaction is processed.

It carries the information about outcome (approved/declined) and other transaction details.

Arguments:

  • object sender: object which raised the event
  • TransactionFinishedEventArgs args: transaction details.
    • TransactionInfo property
      • TransactionId: internal transaction identifier
      • ExternalId: external identifier specified by end user, which can be used to map the transaction to end user’s systems
      • AuthorizationCode: transaction authorisation code
      • CreatedAt: transaction creation time
      • Amount: transaction amount
      • Currency: transaction currency code
      • Mid: merchant identifier
      • Tid: terminal identifier
      • ReceiptUrl: returns the URL which can be used to access online receipt
      • Rrn: returns the transaction reference number (RRN)
      • EntryMode: card entry mode. Can be one of: Unknown, Manual, Chip, Magstripe, Contactless, ContactlessMagstripe
      • Status: transaction status. Can be one of: Processing, Approved, Declined, Refunded, Voided, Unknown
      • CardInfo: card details with following data:
        • MaskedPan: PAN with masked data
        • PanSequenceNumber: PAN sequence number
        • ExpiryDate: Card expiry date
        • Brand: Card brand, e.g. Visa, MasterCard…

Error event

Raised if an error has happened, which prevented the transaction to be carried out.

Arguments:

  • object sender: object which raised the event
  • TransactionErrorEventArgs args: error details.
    • Scope: returns the error category. One of ErrorScope enum values:
      • CommunicationError: there was a problem communicating with card reader or payment gateway.
      • TransactionError: Transaction was processed but it failed due to some other reason.
    • Code: returns the error code. One of ErrorCode enum values:
      • CardReaderFailedToConnect: could not connect to card reader
      • CardReaderDisconnected: connection to reader was lost
      • PaymentGatewayError: error in communication with payment gateway
      • TransactionVoid: transaction was voided
      • TransactionCancelled: transaction was cancelled
      • SignatureError: transaction declined because signature was not given
      • TransactionDeclined: transaction declined due to invalid card
      • TransactionDeclinedKeepCard: transaction declined and card should be captured.
      • InvalidCard: transaction declined due to invalid card
      • GenericError: Unspecified error happened
    • Description: additional information about the error

ProgressInfo event

Raised to provide notifications of transaction progress (insert card, enter PIN, etc)

Arguments:

  • object sender: object which raised the event
  • ProgressInfoEventArgs args: progress event details.
    • Message: contains the description of the event
    • Event: returns the event identifier, which is a ProgressInfoEvent enum value:
      • TransactionStarted: transaction was started
      • Unspecified: unspecified progress event
      • ReaderConfigCheck: reader config was verified
      • ReaderUpdating: reader update started
      • ReaderConnecting: reader is connecting
      • ReaderRestarting: reader initiated restart
      • PresentCard: waiting for card to be presented
      • RemoveCard: waiting for card removal
      • CardDataRead: card info read by gateway
      • WaitingForPinEntry: waiting for PIN entry
      • PinEntryCompleted: PIN was entered
      • Processing: transaction is being processed
      • SeeDevice: important information is displayed on device
      • TransactionFinished: transaction was finished

TransactionCanceled event

Raised when you cancel the transaction by calling PgClient.Cancel method, to mark the end of the transaction. If the transaction is canceled, TransactionFinished event WILL NOT be raised.

Arguments:

  • object sender: object which raised the event
  • EventArgs args: an empty EventArgs instance.

SignatureRequested event

Raised when customer must authorize the transaction with the signature.

Arguments:

  • object sender: object which raised the event
  • SignatureRequestedEventArgs args: doesn’t contain any properties, but allows caller code to set signature or cancel signature collection with following methods.
    • SetSignature(byte[] data): Sets the signature which will be sent to gateway.
    • CancelSignature(): Cancels the signature request. Transaction will be canceled.

BeepRequested event

Raised when sound confirmation is required for contactless transactions.

  • object sender: object which raised the event
  • BeepRequestedEventArgs args:
    • Success: specifies whether the beep should notify success or failure.