Actions

Actions are the primary mechanism through which Payment Methods are managed, and implementing actions correctly is the most important part of integrating with this API.

Receiving Action Notifications

There are two ways that Payment Processors can learn about actions that need to be performed:

The action_required webhook
The actionRequired property in the Get All Accounts response

📘
Our recommended implementation is to accept webhooks but to also poll the Get All Accounts endpoint regularly (at least once per day) to ensure that actions aren't missed.

Handling Actions

Upon receiving an action request, processors must take whatever steps are required to handle that action.

Webhooks

    sequenceDiagram

    autonumber

    participant l as Liberis 
    participant p as Payment Processor

    l --) p : Webhook sent 
    p ->> l: Get Account by Id
    p --) p : Handle the action 
    p --) l : Report the result

Get All Accounts

    sequenceDiagram

    autonumber

    participant l as Liberis 
    participant p as Payment Processor

    p ->> l : Get All Accounts 
    loop if actionRequired
			p ->> l: Get Account by Id
      activate p
    	p --) p : Handle the action 
    	p --)l : Report the result
      deactivate p
    end

Possible Actions

Name	Reason	Is Successful When
`VALIDATE`	Check that the payment processor is able to apply the split.	The merchant id matches both the details in the `merchant` object and the records held by the Payment Processor. There are no issues with the merchant's account that might prevent the application of the requested split.
`START`	Informs the payment processor to commence application of the split.	Successfully enabled the given split % for this merchant.
`PAUSE`	This Payment Account is expected to have a 0 balance for an extended period, but Liberis still has an active contract with the merchant.	Acknowledges the receipt of this action. Payment Processors may stop calling the `balance` endpoint for this merchant (treating the balance as 0) until receipt of a `RESUME` action.
`RESUME`	A paused Payment Account should be resumed.	Acknowledges the receipt of this action. If they previously stopped, Payment Processors must now resume calling the `balance` endpoint for this merchant.
`FINISH`	The split is no longer needed.	Successfully removed the split for this merchant. Note: this action must be sent if the Payment Processor removes the split for any reason, even if it was not triggered by Liberis.
`CHANGE`	The split percentage has changed.	Successfully enabled the new split % for this merchant.
`REFRESH`	The split is active (or paused) and the merchant has received a new advance.	Acknowledges the change after updating the split % and remaining balance as required. Note that new documents may also be available for download. If the split was previously paused, Payment Processors must now resume calling the `balance` endpoint for this merchant and re-activate the split.

Recording the Result

Submit the result of an action performed by the Payment Processor using the Post Action Result endpoint.

❗️
Actions should only be performed when the actionRequired property contains a value, except for the FINISH action, which can be sent at any time to inform Liberis that the split is no longer in place.

Error Reasons

Error	Meaning
`MERCHANT_NOT_MATCHED`	The `merchant` details provided by Liberis do not match the Payment Processor's records.
`SETTLEMENT_ACCOUNT_NOT_POSSIBLE`	This merchant's revenue cannot be redirected to a settlement account at this time.
`SPLIT_NOT_POSSIBLE`	A split cannot be applied to this merchant's account at this time.
`INVALID_METHOD`	Liberis has requested that the Payment Processor uses a payment method (`split` or `settlement account`) that is not supported by the Payment Processor.
`WITHOLD_ALL_FUNDS`	The Payment Processor is currently withholding all funds from the merchant and therefore cannot action this request.
`NOT_TRANSACTING`	The merchant is not transacting and therefore the Payment Processor cannot action this request.
`UNSPECIFIED_ERROR`	The action could not be performed for an unspecified reason. Note that this should not be used for transient faults that could be fixed through routine retries by the Payment Processor.

Updated 4 days ago