Webhooks can be configured to receive updates on every status change that occurs through the life cycle of a payin.

Payin events

Events

It's recommended that your platform listen to the following Rainforest webhooks to notify your platform, the merchant, and the end user on key events. We'll break down each webhook event and if the following notifications should be sent:

Internal Notification - notify your platform support team so they can assist your merchants
Merchant Notification - notify your merchants via an email or alert within your platform
End User (Payor) Notification - notify the end user (payor) of the result of the payin

Webhook	Internal Notification	Merchant Notification	End User (Payor) Notification
payin.created	❌	❌	❌
payin.presenting	❌	❌	❌
payin.authorized	❌	❌	✅
payin.processing	❌	❌	✅
payin.succeeded	❌	❌	❌
payin.failed	❌	❌	✅
payin.returned	❌	❌	✅
payin.canceled	❌	❌	✅
payin.in_review	❌	✅	❌

Payload

The webhook payload consists of:

data - represents all payin detail fields returned by the get payin endpoint
event_type - payin events denoted by the format of payin.{payin_status}

{
    "data": {
        "payin_id": "pyi_2sP8QdsOFUAPy7eldhHpDeN3znJ",
        // ...
        "status": "PROCESSING",
        // ...
    },
    "event_type": "payin.processing"
}

Created

Event: payin.created

Triggered when a payin is created and waiting approval.

Field	Description
`payin_id`	The unique payin identifier.
`payin_config_id`	The unique payin config identifier.
`merchant_id`	The unique merchant identifier.
`payment_method_id`	The unique payment method identifier.
`payment_method_config_id`	The unique payment method config identifier.
`threeds_attempt_id`	The unique threeds attempt identifier, applicable if the payin config requested 3DS be attempted.
`idempotency_key`	A unique identifier provided by the platform.
`billing_type`	The merchant billing type applied to the payin to apply fees. Valid values are `NET` or `GROSS`.
`amount`	The amount of the payin to attempt to process, in minor units.
`currency_code`	Three-letter ISO currency code, in uppercase. Currently, only USD is supported.
`status`	The status of the payin, will be `CREATED`.
`amount_splits`	The amount splits of the payin, applicable if the payin config defined the amount splits.
`method_type`	The type of payment method associated to the payin. 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`.
`billing_contact`	Billing contact details.
`method_metadata`	Valid JSON key-value object specified by the platform to store additional information on the payment method.
`metadata`	Valid JSON key-value object specified by the platform to store additional information on the payin.
`payin_config`	Payin config details.
`threeds_attempt`	3DS attempt details.
`created_at`	Date and time payin was created at in UTC RFC 3339 format.

Presenting

Event: payin.presenting

Triggered when a payin is presented on an EMV device and waiting for the user to process the payin on the device.

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

Authorized

Event: payin.authorized

Triggered when a payin is authorized for processing.

Field	Description
`payin_id`	The unique payin identifier.
`amount`	The amount of the payin authorized, in minor units. Could be less than the amount requested if partially authorized.
`is_partially_authorized`	Boolean indicating if payin was authorized for a partial amount.
`auth_code`	The authorization code.
`avs_result_code`	The address verification service result code.
`cvc_result_code`	The card verification code result code.
`device_data`	Device data, applicable if the payin was processed on a device.
`status`	The status of the payin, will be `AUTHORIZED`.
`updated_at`	Date and time payin was updated at in UTC RFC 3339 format.

Processing

Event: payin.processing

Triggered when a payin is approved and is currently processing.

Field	Description
`payin_id`	The unique payin identifier.
`merchant_fees`	The amount of the payin billed to the merchant.
`status`	The status of the payin, will be `PROCESSING`.
`updated_at`	Date and time payin was updated at in UTC RFC 3339 format.

Succeeded

Event: payin.succeeded

Triggered when a payin has completed processing and the funds are available for deposit.

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

Failed

Event: payin.failed

Triggered when a payin unsuccessfully attempted to process.

Field	Description
`payin_id`	The unique payin identifier.
`status`	The status of the payin, will be `FAILED`.
`refusal_code`	The code explaining the reason for the refusal if the payin or refund failed to process.
`refusal_desc`	The description explaining the reason for the refusal if the payin or refund failed to process. This will be a human-readable value that may be presented to the end user.
`updated_at`	Date and time payin was updated at in UTC RFC 3339 format.

Returned

📘
Available on API version 2024-10-16
If you are integrated against a previous API version and your minimum API version is not 2024-10-16, then you'll need to upgrade your API version to 2024-10-16 to access the payin.returned webhook in Production. See the API version upgrades guide for more information.

Event: returned

Triggered when an ACH payin is returned before moving to Succeeded and the payin is available for a deposit.

Field	Description
`payin_id`	The unique payin identifier.
`refundable_amount`	The amount of the payin that can still be refunded, in minor units. Will be set to 0.
`non_refundable_reason_code`	Why the payin is nonrefundable. Provided when refundable_amount is 0. Will be set to `HAS_ACH_RETURN`.
`status`	The status of the payin, will be `RETURNED`.
`updated_at`	Date and time payin was updated at in UTC RFC 3339 format.

Canceled

Event: canceled

Triggered when a payin is canceled before the payin completes processing. This can be from voiding the payment before settlement or canceling a payin presented on a device.

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

In review

Event: payin.in_review

Triggered when a payin is flagged for risk review and is not available for a deposit.

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

Internal notification example

The following example is an internal notification to be sent your platform support team:

[System Alert] The below payin has moved to the status of In Review. This means the Rainforest risk team has flagged the payment for review and will be reaching out to the platform directly with the additional information required to complete the review.

Merchant ID: {insert merchant ID}

Merchant Name: {insert merchant name}

Payin ID: {insert payin ID}

External notification example

The following example is an external notification to be sent your merchant:

[System Alert] PlatformPay has flagged the below payment for further review. Do not worry this is common practice when processing payments. The PlatformPay team is simply attempting to understand the risk of processing this payment for your business. These reviews typically only take a couple of days to complete. Once we complete our review we will release the payment for deposit. The PlatformPay team will reach out directly with information on how to get your funds released.

Don’t worry your funds are safe and this is a standard part of payment processing that ensures the security and safety of your funds and protects your business against potential bad actors.

Payin ID: {insert payin ID}

Payin webhooks

Payin events

Events

Payload

Created

Presenting

Authorized

Processing

Succeeded

Failed

Returned

📘
Available on API version 2024-10-16

Canceled

In review

Internal notification example

External notification example

Payin events

Events

Payload

Created

Presenting

Authorized

Processing

Succeeded

Failed

Returned

📘Available on API version 2024-10-16

Canceled

In review

Internal notification example

External notification example

📘
Available on API version 2024-10-16