Skip to main content

· 12 min read

SEPA OWTs now require description text from end user

In order to comply with European regulation, a payment reference must be provided by the payer when instructing a SEPA Outgoing Wire Transfer (OWT) regardless of the purpose of that OWT. As such, the description field will become mandatory for SEPA OWTs (the field exists but before this change was not mandatory). This requirement applies to both single OWTs and those created in bulk transactions.

(NB currently adding a description/reference is not mandatory on UK Faster Payments - i.e. for OWTs in GBP.)

The End Customer is required to provide the text during the UX flow of creating an OWT. Therefore, as the Embedder, if you have not previously made this field available in your application, you must now add it and make it mandatory to complete, in order to proceed with the OWT flow.

Here is example text for labelling the field in your application:

“Reference - Add text which to pass to the payee as the reason for payment or any payment reference”

End Customers may use this field as appropriate to the scenarios in which they are creating OWTs in your application, e.g. to add an invoice number or customer number on the payment to a business payee.

This text must be provided and confirmed by the End Customer. Therefore if your application suggests text for the End Customer to use, there must still be the option for them to edit it and accept the final text when proceeding with their OWT.

The field currently accepts a maximum of 35 alphanumeric characters, observing the SEPA extended character set (SEPA Requirements for an Extended Character Set (UNICODE Subset) - Best Practices)

The endpoints impacted are:

POST /outgoing_wire_transfers

POST /outgoing_wire_transfers/bulk/create

If the field is left empty or invalid, and your application attempts to submit the OWT to the Weavr system, our API will return a 400 error noting the description field is “REQUIRED”.

For successfully completed OWTs, the description is currently returned in the GET Outgoing Wire transfer Transaction APIs, and the GET Managed Account Statement API.

OTP retries are now limited

We will limit the number of times an OTP can be submitted incorrectly, to reduce the risk of fraud or abuse. This applies to all scenarios where an OTP is submitted by any kind of user.

For the example below, the number of attempts is 5. However, Embedders should handle the error appropriately rather than assume a fixed number of attempts.

Example:

After the 4th incorrect attempt a 409 Failed will be returned with error - "ONE_CHALLENGE_LIMIT_REMAINING"

After the 5th incorrect attempt a 409 Failed will be returned with error - "CHALLENGE_LIMIT_EXCEEDED"

If the challenge is being performed to verify a transaction (such as an OWT or a Send), after the 5th incorrect attempt, the state of the corresponding transaction will be updated to "REJECTED" and no further challenges can be triggered against this transaction.

Submitting another verify call will return Failed 409 - "STATE_INVALID"

Endpoints affected: /multi/challenges/otp/{channel}

/multi/authentication_factors/otp/{channel}/verify

/multi/stepup/challenges/otp/{channel}/verify

/multi/outgoing_wire_transfers/{id}/challenges/otp/{channel}/verify

/multi/sends/{id}/challenges/otp/{channel}/verify

The time limits for submitting an OTP to complete an action remain the same regardless of the timings of one or more errors or retries.

Phone numbers must now have standard country code for SMS delivery

In order to improve SMS deliverability we are making it mandatory to include the country code with the '+' symbol in the phone number.

Please ensure your users are entering the mobile number in the following format: [+Country Code] [ Mobile Number]

For existing Identities, Embedders do not need to amend data manually or ask End Customers to take any action, as Weavr will standardise existing data.

Creation of Authorised Users now requires Step-Up

Creation of an Authorised User linked to an Identity is a key moment in the integrity of the security for that Identity.

Therefore we are now requiring a session Step-Up when creating a new Authorised User. A new Authorised User can be created by the Root User or by another Authorised User. The active user can Step Up their token by completing a second authentication factor.

Weavr Multi supports the following methods:

  • One-time password via SMS
  • Biometrics
  • Twilio Authy Push Notification More details on how to step-up a token are available on our documentation.

KYC and KYB now require email verification at start of process

Previously it has been possible to start the KYC and KYB processes with an unverified email address, and validate it later. Now we require the email address of the Root User in Consumer and Corporate scenarios to be verified by an end user action before the KYC or KYB process can begin.

Email verification begins as described in our documentation for creating a Consumer or Corporate Identity.

  • An email verification link is valid for 60 minutes - we recommend Embedders provide clear instructions to end users to explain the time limit

  • The Embedder’s application can offer UI to the end user to “resend email verification link”.

  • Call the “Send an email verification code to the root user” API endpoint again

  • If the Embedder’s application requests to re-send the verification link, the new link will again be available for 60 minutes from the time it is created (and the previous link cannot be used)

  • If the user does not verify the email address within the time limit, and the link expires, the user will not be able to login (Weavr returns “403 Forbidden”) and therefore the Embedder’s application will need to prompt the end user to start the onboarding process again

  • If the user tries to start KYC/KYB without having the email verified, we will respond with 409 - Email_Unverified

API handling Step-Ups now uses consistent error code

In the situation when an API is called, and a Stepped-Up token is required but has not been provided, we currently respond with STEP_UP_REQUIRED, but sometimes as a message, and sometimes as an error. We have now aligned all our APIs to provide the response as an error code rather than a message. The endpoints impacted are:

GET /managed_cards

POST /managed_account

POST /managed_cards

GET /managed_accounts

GET /managed_accounts/{id}

GET /managed_cards

GET /managed_cards/{id}

PATCH /managed_accounts

PATCH /managed_cards

POST /managed_cards/assign

POST /managed_cards/{id}/physical

POST /managed_cards/{id}/physical

GET /managed_cards/{id}/physical/pin

POST /managed_cards/{id}/physical/replace_damaged

POST /managed_cards/{id}/physical/replace_lost_stolen

POST authentication_factors/push/{channel}

POST /users

In all cases if the session is not Stepped Up validly, we will respond with the error above.

New feature: payment card renewals

Payment cards issued across Weavr embedded finance programmes carry expiry dates. Up till now, if a cardholder needed to replace an expiring card, and the embedded finance use case called for it, the new card issued would have a new card number. This can cause inconvenience for cardholders because a new card number begins a new transaction history in terms of statements, reporting, and (where applicable) balances.

We are now introducing payment card renewals which allow the cardholder to be issued a new card with the same card number as before, with a new expiry date and CVV.

Here are some key points:

  • Renewal of a card, keeping the original card number, is an optional setting at the card level;

  • Cards not set to renew will still, as before, expire and not be automatically replaced;

  • When a card is set to renew, Weavr will automatically issue the new card;

  • This is available for both virtual and physical cards;

  • Automatic advance warning of upcoming card expiry is now available for all payment cards.

The option to enable automatic renewal of cards can be set at the point of creation for new cards, or can be updated at any point before the renewal date for existing cards.

Embedders can choose to expose this choice to the End Customers. If the Embedder chooses to enable automatic renewal for a specific card or more generally, we advise seeking agreement from the End Customer, although technically no end user interaction or confirmation is required in the current setup.

In the case of physical cards, lead time is required to allow for delivery to the cardholder. Where renewal is enabled on a physical card, the new card will be sent out with the process starting (currently by default) 30 days ahead of the expiry date, based on an internal “renewal date” for the card.

With this lead time in mind, Embedders should take the opportunity to check with the End Customer, further in advance of this renewal process, that their address for delivery of the card(s) is still up-to-date.

By default cards that are currently issued, and new cards issued from now on, will not automatically be set to renew. Therefore the Embedder needs to take a decision in general on their programme, and specifically within subsets of cardholders, whether to take advantage of this feature.

Key points about a new card on a renewal basis:

  • The long card number of the new card is the same as the original card

  • The expiry date is updated

  • The card has a new CVV

  • The PIN on the card remains the same as set by the cardholder, and they can update the PIN any time

  • The spend control rules applied to the original card are applied to the new card

  • New physical cards must be activated (via the API as per activating any new card), while new virtual cards are renewed with updated details immediately

  • Cards provisioned in mobile wallets (Google and Apple) are expected to continue working without the cardholder having to update or replace the original card they added

  • Soon-to-expire cards remain active and usable until the new card is activated

Please note: renewal of expiring cards is a different scenario from replacement of a lost or stolen card. In those scenarios the original card would be blocked immediately and a new card would be issued with a different long card number, as a security measure.

Notifications are sent via webhook relating to upcoming card renewals and expiry events:

CARD_ABOUT_TO_EXPIRE (60 days, 30 days, and 1 day before expiry date)

CARD_RENEWED

CARD_EXPIRED

The Embedder’s system will need to listen on a new webhook:

/managed_cards/expiries/watch

New simulator tools have been added Sandbox area of the Embedder Portal to enable developers to test events related to card renewals and expiry.

Further developer documentation is available here.

Mobile wallet type (Google Pay / Apple Pay) included in card purchase webhooks

Embedded finance programmes with cards can apply to enable mobile wallet provisioning, allowing cardholders to add their card(s) to Google Pay or Apple Pay. Thanks to the dual benefit to users of enhanced security and convenience, programmes taking advantage of mobile wallet provisioning typically see a strong uplift in product engagement, card spend frequency, average transaction values, and overall card spend volume.

In order to help Embedders track these KPIs we are introducing a digitalWalletDetails object in the Card Authorisation and Card Settlement webhooks that notes the digitalWalletType (GOOGLE_PAY or APPLE_PAY). This makes it possible to tell, for any card purchase, if it was used through one of these mobile wallets.

Embedders whose programmes already allow End Customers to provision cards to mobile wallets can immediately start using this information for business intelligence, as well as making the data available for End Customers e.g. for use in accounting and business spend monitoring.

Webhooks impacted:

  • Card authorisations

  • Card settlements

In some business purchasing situations with commercial cards of Corporates, a merchant may seek a single cardholder authorisation for a total amount for a purchase and then break down a purchase into individual items (such as travel tickets). These will then appear to the cardholder as multiple smaller settlements. Previously only the first relatedAuthorisationId or relatedSettlementId was returned by Weavr in the ‘Card authorisation’ or ‘Card settlement' webhooks. This meant that references for any additional related transactions were omitted.

We have now introduced new fields in that can accommodate an array of related transaction IDs, so that the Embedder’s system, and through this the End Customer can correctly view a group of settlement transactions which relate to an original authorisation.

The fields added are:

  • Card authorisation webhook - relatedAuthorisationIds

  • Card settlement webhook - relatedAuthorisationIds and relatedSettlementIds

Alphanumeric SMS Sender ID for Finland and UAE

A few months ago, we implemented an enhancement to the Sender ID used in the SMS messages containing One Time Passwords (OTPs) and Strong Customer Authentication (SCA) for users with UK phone numbers. This was aimed at telecoms rules and deliverability of SMS.

The enhancement involved transitioning from the alphanumeric Sender ID "AUTHMSG" to the default "WEAVR" - or a customised one, for some Embedder programmes on request. This change only affected SMS messages sent to UK numbers, while other countries continued to receive messages with numeric Sender IDs.

We are now introducing a similar change for Finland and the United Arab Emirates (UAE). Regulators in these countries require that Sender IDs in SMS messages be alphanumeric to prevent blocking. As a result, users with phone numbers in these countries will now receive SMS messages with the default "WEAVR" Sender ID or the custom one specified by the Embedder.

This enhancement is automated and users with the country codes +358 (Finland) and +971 (UAE) will automatically receive the new Sender ID when requesting an OTP or SCA.

Managed Account Root Email and Processor Token added to Data Insights

As Embedder operations teams managing B2B programmes in production, you’ll often want to drill down into certain details for support cases for Corporate End Customers, or create reports to help with proactive customer success monitoring.

To help with this, we have added two new fields as columns in the details view of the Managed Accounts dashboard in the Embedder Portal:

  • Root Email, i.e. the email address of the Root User Identity owning each Managed Account

  • Processor Token, i.e. an identifier for a Managed Account in our underlying payment system that can be useful for Embedders and Weavr in support cases where we need to track a transaction state or exception


· 4 min read

New Data Insights

We provide Embedders with data reports and dashboards in the Embedder Portal, collectively referred to as Data Insights. With this release we’re launching a significant wave of improvements and additions across Data Insights.

Key changes include:

  • dashboards have a fresh new look, with charts split across focused tabs; tabs have different purposes, including an overview, analytical tabs and more detailed tabs with transactional information

  • all charts within Data Insights (except for KPIs and tables) now offer an interactive drill-down functionality, allowing Embedder staff a way to see a detailed view of a particular bar/segment

  • an informational tooltip has been introduced within each chart, providing definitions and granularity details pertaining to that chart

  • filters have been enhanced to offer a drop-down menu, making it easier to find what you are searching for

  • improvements to performance

Detailed documentation around Data Insights is now available within the knowledge base section of the Weavr support portal here. This is also linked via the Help button within the Embedder Portal.

We’d like to hear your feedback about Data Insights. Please speak with your Weavr contacts to share your ideas.

Data Insights enhancement - reporting on Authorisations in mobile wallets

We have introduced a new Authorisation Details tab within the XPay Enabled Cards dashboard (formerly known as the Apple Pay/Google Pay Overview dashboard).

This new tab will help Embedder programme operations and support staff identify whether a card payment Authorisation has been done with a card that is provisioned in Apple Pay or Google Pay mobile wallets. The detailed view includes various details such as merchant details, device details, and instrument amounts.

New error message if new Step-Up is retried too fast after initial attempt

We are always looking to improve the error messages returned by the Weavr APIs. Within the Step-Up flow, if the Embedder’s application attempts to start a new Step-Up for a user before the first one has been completed or timed out, we have replaced the error “400 Invalid_request” with the more specific “409 Retry_in_15sec”.

The flow works like this:

  • Embedder’s application calls Weavr API to start Step-Up flow
  • Weavr awaits a response showing the user has not completed the challenge
  • Before any response it received, the Embedder’s application begins a new Step-Up attempt within 15 seconds of the first
  • This results in the error “409 Retry_in_15sec”

If a new Step-Up is started after 15 seconds from the first attempt, then the first attempt will be invalidated and the user will need to respond to the new challenge.

In general, Embedders must provide reasonable times for users to complete multifactor authentication challenges and not make repeat requests on the API for Step-Up in a short space of time.

New error message for a step-up called twice

We have improved the response for the scenario when the Step-up verify endpoint was called twice. If by mistake, you were calling twice the Verify endpoint for the same token that has been already stepped-up, we returned error State_invalid. In order to become more clear on the situation, for the above scenario we are changing the error from State_invalid to Already_verified. More details on step-up authentication is available here.

Ensuring emails are unique in your programme

In some programmes, Embedders have encountered problems when legacy signup flows allowed the same email to be used for a Consumer Identity at the same time as a Corporate Identity. In these types of programme we are now enforcing that the email address of a user has to be unique at the programme level.

Custom tags for Authorised Users

Authorised Users can multiply in programmes with lots of cardholders. As an Embedder you’ll want to manage interactions and data around Authorised Users, so we’ve introduced an optional tag field which allows you to store custom information against those records.

The Authorised User Tag can be included in API calls as follows:

  • POST/users
  • GET/users
  • PATCH/users{user_id}

The tag is available when filtering Authorised Users in the Embedder Portal:

WEB


· 2 min read

Merchant country code data in card authorisations and settlements

Following your valuable feedback, we are continuously enhancing our webhooks to provide Embedder programme managers and administrators with additional webhook data.

As part of our continuous efforts to refine our webhook events, we have included the merchant country code in two specific webhook operations relating to card purchases. The two operations are:

  • /managed_cards/authorisations/watch
  • /managed_cards/settlements/watch

We are currently providing you with the merchant details that include the category code (merchantCategoryCode), merchant name (merchantName) and ID (merchantId). With this release you will start receiving the merchant country code (merchantCountryCode) for the two specific webhook events. WEB

With this additional information you can gain more insights into understanding in which countries transactions are being performed, whether domestic or international.

Webhook logs default to recent first

We understand the importance of accessibility and efficiency when it comes to monitoring your webhook events and for this reason, we have restructured the Webhook Logs page within our Embedder Portal to provide you as the Embedder programme manager or administrator with a better user experience.

We restructured the list of webhook events to be presented in descending order, with the latest created event displayed first. Webhook events will be automatically displayed in descending order, presenting the latest created event first.

WEB

Webhook when an IWT is rejected

If an incoming wire transfer is rejected, an Managed Accounts / Account Deposit webhook will be sent with state : REJECTED.

IWTs can be rejected for various reasons: account closed, account blocked, risk-based limits, SOF declaration not provided or inadequate.


· 2 min read

Automatic webhook retries for extra error scenarios

Webhooks are sent via POST to the Embedder's application’s webhook endpoint URL specified in the Embedder Portal (under the Application Details section).

If the Embedder's server responds to a webhook POST with a 5xx error, signifying that there was an issue with receiving the event, the webhooks are retried automatically.

This feature is being expanded to include automatic webhook retries for 408, 409, and 425 status codes.

The webhook is retried 5 times starting with an initial delay of 10 seconds, and incrementing with a delay factor of 6, signifying:

  • Failure on the first attempt will be retried after 10 seconds
  • Failure on the second attempt will be retried after 60 seconds
  • Failure on third attempt will be retried after 360 seconds
  • Retrying up to 5 times

This improvement increases the likelihood for Embedders to successfully receive all webhook events, even when errors occur, thereby enhancing reconciliation and ensuring data integrity.

Optional Activation Code during the physical card activation process

Previously, when upgrading a virtual card to a physical card, it was mandatory to provide an activation code to activate the card. This process is now being simplified by removing the activation code requirement and making it optional instead.

The old activation code flow is still supported but Embedders can now take advantage of a simpler method: a cardholder who receives the physical card simply needs to be logged in and then a card activation can be initiated through the Embedder’s application, for example through an activation button.

The endpoints impacted are:

  • POST /managed_cards/{id}/physical
  • POST /managed_cards/{id}/physical/activate

If an activation code is provided when activating a card, it will still be validated against the activation code set when upgrading the card. Any mismatch will trigger the existing 409 error, specifically ACTIVATION_CODE_INVALID. However, if no code is provided, the card will be activated, and a 200 success generated.


· 2 min read

Enhanced API Key management

Embedders now have the flexibility of managing and rotating API keys, ensuring secure usage and storage. These options are conveniently accessible on the API Credentials page, within the Embedder portal.

This enhancement introduces three new options for managing API Keys:

  • Creating additional API Keys: Create multiple API keys to support various use cases and enhance security measures. To create a new key, Embedders should navigate to the API Keys tab and click "Add New API Key".
  • Rotating between keys: Easily switch between different API keys, ensuring secure usage. Embedders can click to reveal and copy the key provided within the API Keys tab.
  • Deactivating an API key: In the event of security concerns or changes in access requirements, Embedders can deactivate API keys as needed. Once deactivated, an API key cannot be reactivated.

WEB

Alternative Step-up via fallback SMS channel

Embedders may use different channels for stepping-up a token: SMS, Twilio Authy or Biometrics. In situations where users encounter difficulties accessing Twilio Authy for authentication, Embedders can now initiate the SMS channel as a fallback. This ensures that users still receive the verification code and can successfully confirm the challenge.

Enhanced User Verification Indicators

To prevent confusion in interpreting user verification statuses, the verification indicators now feature new, distinct, and recognisable colours corresponding to their respective statuses:

  • Upon creating a new user, the email and mobile verification indicators will now appear grey instead of red.
  • When a new user starts verifying the email or mobile, the verification indicators will be displayed yellow, not red.
  • Upon successful verification of the email or mobile, the verification status will continue to be indicated in green.

Enhanced Data Insights Dashboard

To ensure Embedders can closely monitor the progress and operations of their customers, the Data Insights Dashboard has been enriched with the following information:

  1. The details table within the KYC Overview dashboard includes a new Rejection Comment column, showing the reason why a consumer failed a KYC submission.
  2. The Card Settlements and Fees Details dashboards now include new filtering options:
  • a. Managed Card ID, Merchant Name and Merchant Category Code filters, within the Card Settlements dashboard
  • b. Instrument Friendly Name, Card Last 4 Digits, Merchant Category and Merchant Category Code (where applicable), within the Fees Details dashboard.