Override risk declines

Trustly Risk Decline Override allows you to manage, override, and approve declined Trustly transactions.

When you approve a declined transaction, it becomes a non-guaranteed capture. This means you combine the benefits of guaranteed and non-guaranteed payments, and this gives you full control to manage risk according to your own criteria.

The following are a few of the key features of Trustly Risk Decline Override:

• Trustly Integration: Direct integration with the Trustly payment system.
• Risk Data Access: Retrieve detailed risk data for transactions.
• Custom Risk Management: Make decisions based on your own risk appetite and policies.
• Override Capability: Approve transactions that Trustly has flagged for potential override, making them non-guaranteed.

Workflow

The following is the Trustly Risk Decline Override workflow:

• Receive the Trustly declined or failed transaction notification. This notification includes extended reason codes and a flag that indicates if you can override the transaction.
• When an override is possible, call the Get Risk Data API to retrieve important risk signals about the transaction. Use this data to decide whether to approve the transaction.
• Based upon your risk assessment, if you’d like to override and approve the transaction, call the Approve Transaction API. This action overrides the Trustly risk decline and converts the transaction into a non-guaranteed transaction.
• Process returned transactions for the non-guaranteed transactions. Trustly offers Representment as a Service that you can enable for these returns to help reduce your losses.

API Reference

Rather than duplicating the full API specification here, this section highlights the specific endpoints and parameters relevant to the risk override flow. For complete endpoint definitions, see the API Reference.

Declined transaction notification parameters

When a transaction fails or is denied, the Fail and Deny webhook notifications include parameters that indicate if you can override the transaction. The most relevant items to check in the payload are:

• isOverridePossible: Indicates if a transaction override is possible.
• shouldOverrideBeAvoided: Indicates if a transaction override should be avoided (due to the extended reasons provided).

Sample notification request

The following is an example of the notification you’ll receive from Trustly when a transaction is declined.

POST /{notification path}
Authorization: Basic TThSYUhnRWpCRTU0enVGWU1SUXE6RVlOM0dYYXNyVlUxdlExdXlZejIyTk5RZHk0PQ==
merchantId=00123&merchantReference=my+reference&paymentType=2&transactionType=3&eventId=1030845856&eventType=Deny&objectId=1025228290&objectType=Transaction&message=Not+enough+balance&createdAt=1714503865362&errorCode=331&isOverridePossible=true&shouldOverrideBeAvoided=true&paymentProviderTransaction.reasonCode=12&paymentProviderTransaction.reasonCodeMessage=Not+enough+balance&paymentProviderTransaction.status=SW021&paymentProviderTransaction.statusMessage=Not+enough+balance&paymentProviderTransaction.extendedReason.code=10000&paymentProviderTransaction.extendedReason.code=11000&status=8&statusMessage=Denied

See Payment Decline Codes and Reason Codes for more information about the decline reason codes shared by Trustly.

Get risk data

To request risk data from Trustly, define the following parameters in your API request:

• Endpoint: /api/v1/transactions/{transactionId}/risk
• Method: GET
• Description: Retrieves risk data for the specified declined capture transaction.
• transactionId (string): A unique identifier for the transaction.

Approve transaction

To approve a declined Trustly transaction, define the following parameters in your API request:

• Endpoint: /api/v1/transactions/{transactionId}/approve
• Method: POST
• Description: Approves the specified transaction, overriding the Trustly risk engine and converting it to a non-guaranteed transaction. If a return happens for this non-guaranteed transaction, its status changes to Reversed, and the payment provider transaction status shows the return code (for example, R03).
• transactionId (string): A unique identifier for the transaction.

Remove debt block

To remove a debt block, define the following parameters in your API request:

• Endpoint: /api/v1/transactions/{transactionId}/removeDebtBlock
• Method: POST
• Description: Removes any holds placed by Trustly on the consumer due to an ACH return on an overridden transaction. If there are no other transactions with debt blocks, the consumer can successfully authorize new transactions.
• transactionId (string): A unique identifier for the transaction that received an ACH return.

Remove debt block

To remove a debt block, define the following parameters in your API request:

• Endpoint: /api/v1/transactions/{transactionId}/removeDebtBlock
• Method: POST
• Description: Removes any holds placed by Trustly on the consumer due to an ACH return on an overridden transaction. If there are no other transactions with debt blocks, the consumer can successfully authorize new transactions.
• transactionId (string): A unique identifier for the transaction that received an ACH return.

Receive ACH return notifications from Trustly

When an ACH return occurs on a transaction whose risk decline you overrode, the resulting non-guaranteed transaction’s status changes to Reversed. The payment provider transaction status shows the specific ACH return code. For example, R01.

Additionally, Trustly places a hold on the consumer, automatically declining all their subsequent transactions. To enable the consumer to authorize new transactions, you must call the Remove Debt Block API.

Trustly sends webhook notifications to make you aware of ACH returns. The following table lists the parameters that are included in an ACH return notification.

Sample notification request

The following is an example of the ACH notification request you’ll send to Trustly.

POST /{notification path}
Authorization: Basic TThSYUhnRWpCRTU0enVGWU1SUXE6RVlOM0dYYXNyVlUxdlExdXlZejIyTk5RZHk0PQ==
merchantId=00123&merchantReference=my+reference&paymentType=2&transactionType=3&eventId=1030845856&eventType=Reverse&objectId=1025228290&objectType=Transaction&message=US_ACH_CROSSRIVER+returned+transaction+with+message%3A+R01&createdAt=1714503865362&paymentProviderTransaction.status=R01&paymentProviderTransaction.statusMessage=Insufficient+Funds&reversedAmount=37.99&status=10&statusMessage=Reversed