AsyncThirdPartyPaymentGatewayEvent

Represents an asynchronous payment gateway notification platform event. When a payment, payment authorization, or refund reaches a terminal status through an asynchronous gateway notification, Salesforce Payments publishes one of these events. Subscribe to these events so you can listen and respond to them when they’re published. For example, create a Salesforce Flow that is triggered when a sale or refund settles asynchronously. This object is available in API version 64.0 and later.

Supported Calls

describeSObjects()

Special Access Rules

To access Salesforce Payments objects, you must have a Salesforce Payments license and Payments must be enabled for your org. Salesforce Payments objects are available only in Lightning Experience.

This event is published by Salesforce internal processes only. The create, edit, and delete operations aren't available to users.

Usage

Each event describes exactly one payment transaction. Exactly one of the Payment, PaymentAuthorization, or Refund relationship fields is populated, matching the value of TransactionType.

Use GatewayReferenceNumber to detect and ignore duplicate notifications, because the same gateway notification can be delivered more than once.

Fields

Field Details
ClientContext
Type
textarea
Properties
Nillable
Description
Caller-supplied context that was carried on the originating transaction. This value is copied from the terminal Payment or Refund record. It isn't populated for authorization transactions.
The maximum length is 2000 characters.
EventUuid
Type
string
Properties
Nillable
Description
A universally unique identifier (UUID) that identifies a platform event message.
GatewayMessage
Type
string
Properties
Create, Filter, Group, Sort, Nillable
Description
The message returned by the payment gateway. For a failed notification, this code represents the gateway's error code.
The maximum length is 255 characters.
GatewayReferenceDetails
Type
string
Properties
Create, Filter, Group, Sort, Nillable
Description
Additional reference details returned by the payment gateway for the transaction.
The maximum length is 255 characters.
GatewayReferenceNumber
Type
string
Properties
Create, Filter, Group, Sort
Description
The reference number that the payment gateway assigned to the transaction. Use this value to detect and ignore duplicate notifications for the same transaction.
The maximum length is 255 characters.
GatewayResultCode
Type
string
Properties
Create, Filter, Group, Sort, Nillable
Description
The result code returned by the payment gateway. For a failed notification, this code represents the gateway's error code.
The maximum length is 255 characters.
NotificationStatus
Type
string
Properties
Create, Filter, Group, Sort
Description
The outcome of the asynchronous gateway notification for the transaction.
Possible values are:
  • Failed – the transaction failed at the gateway.
  • Success – the transaction completed at the gateway.
PaymentAuthorizationId
Type
reference
Properties
Nillable
Description
Identifies the PaymentAuthorization record for which the event occurs. Populated for authorization transactions.
This field is a relationship field.
Relationship Name
PaymentAuthorization
Refers To
PaymentAuthorization
PaymentId
Type
reference
Properties
Nillable
Description
Identifies the Payment record for which the event occurs. Populated for sale and capture transactions.
This field is a relationship field.
Relationship Name
Payment
Refers To
Payment
RefundId
Type
reference
Properties
Nillable
Description
Identifies the Refund record for which the event occurs. Populated for referenced and unreferenced refund transactions.
This field is a relationship field.
Relationship Name
Refund
Refers To
Refund
ReplayId
Type
string
Properties
Nillable
Description
Represents an ID value that is populated by the system and refers to the position of the event in the event stream. Replay ID values aren’t guaranteed to be contiguous for consecutive events. A subscriber can store a replay ID value and use it on resubscription to retrieve missed events that are within the retention window.
RetryCategory
Type
picklist
Properties
Nillable, Restricted picklist
Description
The Salesforce-categorized retry category for a failed transaction, indicating the class of failure.
Possible values are:
  • CardLimit—Card Limit Decline
  • GatewayConnection—Gateway Connection Error
  • PaymentInformation—Invalid Payment Details
  • PaymentProcessing—Payment Processing Error
  • Security—Security Failure
  • Unknown—Unknown error
  • ValidationFailure—Internal Validation Error
RetryDecision
Type
picklist
Properties
Nillable, Restricted picklist
Description
Indicates whether the failed transaction can be retried.
Possible values are:
  • NonRetriable—Non Retriable
  • Retriable
SalesforceResultCode
Type
picklist
Properties
Nillable, Restricted picklist
Description
The Salesforce-categorized result code derived from the gateway response, providing a normalized outcome that's consistent across payment gateways.
Possible values are:
  • Decline
  • Indeterminate
  • PermanentFail—Permanent Fail
  • RequiresReview—Requires Review
  • Success
  • SystemError—System Error
  • ValidationError—Validation Error
TransactionType
Type
string
Properties
Create, Filter, Group, Sort
Description
The type of payment transaction that the asynchronous notification applies to.
Possible values are:
  • Authorization – an authorization transaction.
  • Capture – a capture transaction.
  • ReferencedRefund – a refund against a referenced payment.
  • Sale – a sale transaction.
  • UnreferencedRefund – an unreferenced refund transaction.