Webhooks can be configured to receive updates on every status change that occurs through the lifecycle of a payment method.

Payment method events

Events

Payload

The webhook payload consists of:

data - represents all payment method detail fields returned by the get payment method endpoint
event_type - payment method events denoted by the format of payment_method.{payment_method_status}

{
    "data": {
        "payment_method_id": "mtd_2sPGuPD2ssbFDeaAHFo9ErooAfa",
        // ...
        "status": "ACTIVE",
        // ...
    },
    "event_type": "payment_method.active"
}

Created

Event: payment_method.created

Triggered when a payment method is created and awaiting presentation or activation.

Field	Description
`payment_method_id`	The unique payment method identifier.
`payment_method_config_id`	The unique payment method config identifier.
`billable_merchant_id`	The unique merchant identifier for the billable merchant.
`status`	The status of the payin, will be `CREATED`.
`billing_contact`	Billing contact details.
`metadata`	Valid JSON key-value object specified by the platform to store additional information on the payment method.
`replaces_payment_method_id`	The unique identifier for the payment method that was replaced by this payment method, applicable if the payment method was created due to the Replace Payment Method process.
`created_at`	Date and time payment method was created at in UTC RFC 3339 format.

Fields available on creation when storing a payment method from the Payment Component:

Field	Description
`fingerprint`	The unique identifier of a payment method across all platform merchants.
`method_type`	The type of payment method. Valid values are `CARD`, `APPLE_PAY`, `ACH`, `PLAID_ACH`.
`card`	Card payment method details, applicable if the `method_type` is `CARD`.
`apple_pay`	Apple Pay payment method details, applicable if the `method_type` is `APPLE_PAY`.
`ach`	ACH payment method details, applicable if the `method_type` is `ACH`.
`plaid_ach`	ACH payment method details from Plaid, applicable if the `method_type` is `PLAID_ACH`.

Fields available on creation when processing a payment on an EMV device:

Field	Description
`method_type`	The type of payment method. Valid values are `CARD`, `APPLE_PAY`, `ACH`, `PLAID_ACH`.
`card`	Card payment method details, applicable if the `method_type` is `CARD`.

Presenting

Event: payment_method.presenting

Triggered when a payment method is presented on an EMV device and waiting for the user to provide their payment method for storage.

Field	Description
`payment_method_id`	The unique payment method identifier.
`device_registration_id`	The unique device registration identifier.
`status`	The status of the payin, will be `PRESENTING`.
`updated_at`	Date and time payment method was updated at in UTC RFC 3339 format.

Active

Event: payment_method.active

Triggered when a payment method has been deemed ready for use.

Field	Description
`payment_method_id`	The unique payment method identifier.
`status`	The status of the payin, will be `ACTIVE`.
`is_available`	Payment method is currently available for use.
`device_data`	Device data, applicable if the payment method was stored via a device.
`updated_at`	Date and time payment method was updated at in UTC RFC 3339 format.

Fields available on activating a payment method when storing a payment method on an EMV device:

Field	Description
`method_type`	The type of payment method. Valid values are `CARD`, `APPLE_PAY`, `ACH`, `PLAID_ACH`.
`card`	Card payment method details, applicable if the `method_type` is `CARD`.

Canceled

Event: payment_method.canceled

Triggered when a payment method is canceled prior to becoming active for payment processing. This can occur if the payment method presented on the EMV device was canceled before it finished collecting the payment method.

Field	Description
`payment_method_id`	The unique payment method identifier.
`status`	The status of the payin, will be `CANCELED`.
`updated_at`	Date and time payment method was updated at in UTC RFC 3339 format.

Failed

Event: payment_method.failed

Triggered when the payment method failed to be stored. This can occur if the payment method presented on the EMV device failed to collect the payment method.

Field	Description
`payment_method_id`	The unique payment method identifier.
`status`	The status of the payin, will be `FAILED`.
`updated_at`	Date and time payment method was updated at in UTC RFC 3339 format.

Replaced

Event: payment_method.replaced

Triggered when a payment method is replaced by a new payment method.

Field	Description
`payment_method_id`	The unique payment method identifier.
`status`	The status of the payin, will be `REPLACED`.
`method_type`	The type of payment method. Valid values are `CARD`, `ACH`, `PLAID_ACH`.
`card`	Card payment method details, applicable if the `method_type` is `CARD`.
`ach`	ACH payment method details, applicable if the `method_type` is `ACH`.
`plaid_ach`	ACH payment method details from Plaid, applicable if the `method_type` is `PLAID_ACH`.
`replaced_by_payment_method_id`	The unique identifier for the payment method that replaced this payment method.
`replaced_reason_code`	The code explaining the reason the payment method was replaced.
`replaced_reason_desc`	The description explaining the reason the payment method was replaced. This will be a human-readable value that may be presented to the end user.
`replaced_at`	Date and time payment method was replaced in UTC RFC 3339 format.
`created_at`	Date and time payment method was created at in UTC RFC 3339 format.