Payment Execution Service
Overview
Before payments are posted, they may be in requested
state. This indicates that the payment should be processed with a transaction with an external financial institution and then distributed according to the payment request’s targets. Payments in requested
state are typically called Payment Requests.
Payments can be created in requested
state either using the Autopay feature, or directly using the Create Payment API. They will be processed by the payment execution service in the same way.
Setup
The system is setup for one or more third-party payment providers by calling the Add Payment Provider Configuration endpoint, with the details of your account with that provider, such as merchantId
, secretKey
and so on. Then, each financial instrument (which represent insureds’ payment credentials, such as a credit card) is updated with an offlinePaymentToken
which is used to indicate that the credential is authorized to pay the account.
Note
The details of the payment providers and tokens are managed in a separate service in order to facilitate PCI-Compliance. Please review Socotra’s PCI Compliance Statement for more information.
Initial Process
When the payment request is first processed, it will immediately try to post the transaction by calling the payment provider. During this time, the payment will be in executing
state.
If successful, the payment will advance to posted
state, and an external cash transaction record will be created for that payment.
If the payment fails, it will revert back to requested
state and await a retry.
The general state flow for payments looks like this:

To move to requested
state from validated
without waiting for the autopayTime
, you can use the Execute Payment endpoint.
Retry Plans
Retry plans contain the following properties:
attempts
: The maximum number of tries to execute a payment requesthoursBetweenAttempts
: How long to wait between tries
Each retry plan is created in configuration and has a name.
The retry plan can be set in any of these places, and the system will start with the first until it finds a plan specified:
The payment itself
The financial instrument being used
The payment’s account
The tenant’s default retry plan as configured
Retry Process
The overall retry process looks like this:

While the payment is awaiting a retry, you can manually override the process in these ways:
Use the Post Payment endpoint to cause the payment to be posted as-is
Use the Cancel Payment endpoint to indicate the that payment is no longer needed
Use the Fail Payment endpoint to indicate that the payment cannot be processed
Use the Update Payment endpoint to manually change the
nextRequestTime
to retry sooner or later than scheduled
These endpoints will advance the payment state to posted
, cancelled
, failed
, or requested
respectively.
Post-Execution Plugin
Process
After the payment execution is attempted, the Payment Post-Execution Plugin is called. Its payload includes:
The
paymentLocator
The
financialInstrumentLocator
The payment
amount
The payment
state
An
externalTransactionId
, if one existsThe payment
currency
Extension
data
for the payment
The plugin can then return a response including:
The
nextRequestTime
, if you wish to override the defaulthoursBetweenAttempts
in the retry planAn updated payment
amount
An updated
state
for the payment (posted
,cancelled
, orfailed
)A
note
Important
If the post-execution plugin fails, even if the payment provider transaction has succeeded, the payment will be also be marked as failed
. The information from the provider’s response will be available on the payment history with failure information in the note
. The post-execution plugin will not be called. In this case you should post the payment manually and resolve the cause of the failure to prevent future problems.
Execution Log
The history of execution attempts is kept in the executionLog
property for each payment. Each log entry looks like this:
requiredpaymentRequestLocator stringpaymentRequestState Enum completed | error | failed | pendingdata map<string,object>optionalnote string?requestTime datetime?transactionId string?