Skip to main content

Variable recurring payments

Variable recurring payments (VRPs) allow to initiate multiple instant single payments with only one authorization flow journey required from the remitter. There are 2 VRP types:

Sweeping​

This feature enables customers to set up automatic and recurring transfers to "sweep" between their accounts. For instance, users can arrange for funds to be moved from their checking account to their savings account regularly when their balance exceeds a certain threshold. The creditor and the debtor must be the same legal entity.

Non-Sweeping (Other)​

This function allows to facilitate a new way for businesses to handle customer payments across various services, such as utilities and subscriptions.

note

At the moment the Non-Sweeping VRP type is not allowed by UK banks.

General flow​

General flow of using VRP with Fena is pretty much the same as with any other payment types we support. First, customers need to POST /payment/vrp-consent to register their intent to make VRPs with the selected bank and to get back authorisation URI, to which their end-users should be redirected to approve the consent. Detailed API spec can be found here.

Once the end-user authorises the consent on the bank’s side they are redirected back to Fena and we complete the initiation process with the bank. Once everything is done on our side we redirect end-users back to our customer’s platform. The redirect URI which is used in this case is either set on the per-consent basis by utilizing the options object of the POST /payment/vrp-consent request payload spec or set on a Fena account level, when you contact us and request access to Direct Banking integration API. Important, client_id and client_secret header values which customers need to supply with every call to VRP endpoints are also shared with you upon registration with Fena. Contact email, support@fena.co

Fena will send back a few parameters related to VRP consent as well in the form of query string when end-users are redirected to the customers portal. These are id and status. id is an identification number of the VRP consent on Fena side, status is one of the enum values we have standardised for the initiation process, usually authorized or rejected.

After the VRP consent is authorized you can initiate VRP payments by calling POST /payment/vrp-payment and simply providing ID of the VRP consent and amount of the payment. Detailed API spec can be found here

note

Please remember about the maximumIndividualAmount and periodicLimits set when creating the VRP consent.

To delete the VRP consent, canceling the access to initiate VRP payments, a call should be made to DELETE /payment/vrp-consent/{vrpConsentId}.

Webhooks​

The webhook URI to which Fena sends webhook messages to, can be configured the same way as is the case with Redirect URI - either per-request basis or setting it on Fena account level upon registering with Fena.

Webhooks allow to identify such events like: a VRP consent authorization success or failure or, for example, the webhook will be sent when VRP payment's status changes to executed.

Webhooks:

  1. The end user has authorized the consent and has been redirect back to Fena. The final status of the consent is unknown yet.
{
  type: 'vrp-consent-creation',
  status: 'pre-redirect',
  data: { vrpConsent: <GET_VRP_CONSENT_DATA_SPEC> },
}
  1. VRP Consent Authorization event. Can signalize that the consent was successfully authorized; or that an error occured during its authorization. Also if its Fena redirect link which the end-user is redirect to from the bank is accessed for the second time the webhook with the comment: vrp consent was already created and authorized before; and if the VRP consent has been deleted already then with the comment: vrp consent was deleted previously.
{
  type: 'vrp-consent-authorization',
  status: consent.status,
  comment: 'unexpected consent creation error', 
  data: { error?: <exception>, vrpConsent?: <GET_VRP_CONSENT_DATA_SPEC> },
}
  1. VRP Consent Deletion event. Sent when a DELETE /payment/vrp-consent/{vrpConsentId} request is sent. Possible messages:
  • vrp consent was successfully deleted - VRP consent was deleted via API
  • vrp consent was revoked - VRP consent was deleted by a user via their banking app
  • vrp consent deletion process has failed - The deletion was unsuccessful
  • vrp consent was not created on provider's side so there's nothing to delete - VRP consent was not created and authorized on the bank's side
  • vrp consent was already deleted previously - an API call to delete the consent was sent, but it was deleted previously
{
  type: 'vrp-consent-deletion',
  status: <VRP_CONSENT_STATUS>,
  comment: `vrp consent was revoked`,
  data: { error?: <exception>, vrpConsent: <GET_VRP_CONSENT_DATA_SPEC> },
}
  1. Connection to the VRP consent was lost. Possible causes: a bank has suffered from an outage or unexpected issues; a bank does not provide updates on a user-triggered consent revocation.

Testing: on our staging environment you can send a request to POST /payment/vrp-consent/{consentId}/test-consent-connection-lost which will trigger a webhook with the data specified below and the consent will have its status set to connection_lost.

{
  type: 'vrp-consent-connection-loss',
  status: <'connection_lost' from VRP_CONSENT_STATUS>,
  comment: `connection to the vrp consent was lost`,
  data: { vrpConsent: <GET_VRP_CONSENT_DATA_SPEC> },
}
  1. A VRP payment's status update.
{
  type: 'vrp-payment-initiation',
  status: <NEW_VRP_PAYMENT_STATUS>,
  comment: 'detected payment status update',
  data: { vrpPayment: <GET_VRP_PAYMENT_DATA_SPEC> },
}

Critical: after receiving a webhook event for a VRP payment's or consent's status update, always call our GET endpoint to double-check whether the webhook event originated from Fena. Endpoints are GET /payment/vrp-consent/{vrpConsentId}, GET /payment/vrp-payment/{vrpPaymentId}. Detailed API spec is here. If the webhook originated from us then this endpoint will return the same status as was stated in the webhook event. Otherwise status returned from GET request takes precedence.

Limitations​

  • Monzo:
    • only support creating consents with a periodicAlignment of Consent. Additionally, they currently only allow periodType of Month and Year.