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.

Important

The payment execution service currently supports Braintree. Support for Stripe is expected in September 2025. Contact your Socotra account representative to request support for additional payment providers.

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:

../../_images/payment-state-flow.png

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 request

  • hoursBetweenAttempts: 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:

../../_images/autopay-payment-request-flow.png

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 exists

  • The payment currency

  • Extension data for the payment

The plugin can then return a response including:

  • The nextRequestTime, if you wish to override the default hoursBetweenAttempts in the retry plan

  • An updated payment amount

  • An updated state for the payment (posted, cancelled, or failed)

  • 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:

PaymentRequestExecutionLogItem
required
paymentRequestLocator string
paymentRequestState Enum completed | error | failed | pending
data map<string,object>

optional
note string?
requestTime datetime?
transactionId string?

See Also