Skip to main content

Management of asynchronous API responses

Updated

As a main pillar of bank account and account holder match verification, Sis ID uses banking network to check the provided data against banking databases. This comes with a complex network of API exchanges and response delay which by essence can lead to an asynchrone API experience for a significant share of Sis ID checks.

To handle this, Sis ID provides the following implementation recommandation. It can be tailored based on your project specifics.

 

General considerations

  1. Sis ID API returns a check which can be either pending or not pending, based on data providers & sub-services response being obtained within the API response time
  2. SepaMail Diamond being historically linked to the API product, it has a dedicated set of property when others similar banking databases are nested under the MatchVerificationService properties, associated with the MV-X reasons codes
  3. For a pending control, an API consumer should use the API with two modes
  • Retrieval : ask the API for a control to check if it is still pending using GET type methods
  • Retry : submit the API for a new control after the retrieval approach have been used

These modes apply to both unitary checks (POST/checks) and batch (PUT/audition/import)

 

Generate a PENDING check

Following datas can be used to generate a PENDING CHECK in STAGING environment
Please note this environment is mocked and will use a limited set of IBANs to trigger calls to a STAGING SepaMail service allowing discovery of the PENDING case.

In case of failing to generate a PENDING check, please refer to the sections below to get a preview of expected response body in such situation.

 

Natural person

Use a valid IBAN starting with FR76300040000
AND
Change any of the firstName, lastName or birthdate properties to generate more PENDING cases

Example of a request below. Data cannot be reused!

{
"entity": {
"physicalPersonIdentifier": {
"firstName": "John",
"lastName": "Dodo",
"birthdate": "1839-01-19"
},
"paymentIdentity": {
"iban": "FR7630004000031234567890143"
}
}
}

 

Legal person

Use a valid IBAN starting with FR76300040000
AND
change any of the registratoinId to any valid French SIREN to generate more PENDING cases

Example of a request below. Data cannot be reused!

{
"entity": {
"company": {
"countryCode": "FR",
"registrationId": "824 003 958 "
},
"paymentIdentity": {
"iban": "FR7630004003860002004957783"
}
}
}

 

Determine the PENDING state of a check

The status property of a check is not relevant to determine if a check is functionnaly pending. The status property only indicates if the control has been succesfully proceeded by Sis ID, independantly of its pending or not situation

Note:

  • A pending check always has "classification": "MEDIUM"

  • There is currently no dedicated property to identify the PENDING state of a check

 

PENDING state of a unitary check (POST/checks)

PENDING SepaMail

You can use of the following properties in the POST/checks response to identify a PENDING SepaMail :

  • "sepamailVerificationStatus": "PENDING"
  • "reasons" contains "SD-P"
{  "@domain": "PaymentIdentity",  "createdBy": "824003958",  "createdDate": "2024-06-11T12:39:33.688Z",  "lastModifiedBy": "824003958",  "lastModifiedDate": "2024-06-11T12:39:34.442Z",  "id": "66684585f36b032f2c53dbd0",  "score": 70,  "classification": "MEDIUM",  "status": "SUCCEEDED",  "withDeferredResult": true,  "byAPI": true,  "byFTP": false,  "workflow": "PING",  "reasons": [  "S-NR",  "I-NR",  "CLH-SINR",  "COH-SINR",  "SD-P"  ],  "sepamailVerificationStatus": "PENDING",  "sepamailLastReportDate": "2024-06-11T12:39:34.438Z",  "reasonLabels": {  "sepamail.status.PENDING": "Vérification en cours par le service SEPAmail DIAMOND.",  "reason.code.SD-P": "Vérification en cours par le service SEPAmail DIAMOND.",  "reason.code.COH-SINR": "Analyse de l'historique de paiement de la communauté : société et coordonnées bancaires inconnues.",  "reason.code.I-NR": "Coordonnées bancaires non ajoutées sur la plateforme.",  "reason.code.CLH-SINR": "Analyse de votre historique de paiement : société et coordonnées bancaires inconnues.",  "reason.code.S-NR": "Société non enrôlée sur la plateforme."  } }

 

PENDING Another Match Verification Service

You can use of the following properties in the POST/checks response to identify a PENDING state of a control related to another service than SepaMail Diamond :

  • "reasons" contains "MV-P"
 

PENDING state of checks within a batch (PUT/audition/import)

Batch level

From the batch level, you can use the following properties to look after PENDING state checks within the batch when not null

  • nbPendingSepamail.
    It is actually not enough to determine all pending states from other match verification services within the batch and remains valid only on FRENCH bank account checks. There is nonbPending property in PUT/audition/import response.
{  "id": "",  "name": "Import #2 of August 31, 2020",  "nbItems": 387,  "nbAuditedItems": 352,  "nbErrorItems": 35,  "completed": false,  "failed": false,  "classificationResult": {  "high": 297,  "medium": 19,  "low": 11,  "no": 25  },  "nbPendingSepamail": 15,  "errors": "" }
 

Controls level

It is possible to use the GET/audition/import/id/controls route to retrieve all checks within a batch and apply the same sorting as described for Unitary checks above to exclude PENDING state controls from others

 

Retrieval of asynchronous checks

For checks being identified as in PENDING state from the previous section, API consumer need to pull the unitary or bulk API to read a control result (GET/audition/id) or a batch result (GET/audition/import/id/controls) as long as the concerned checks remain in PENDING state

We recommend to implement this pulling strategy following a Fibonacci suite, each pull corresponding to an F in the following suite :

  • F0: 30 seconds after posting the control
  • F1: 1 minute after F0
  • F2: 2 minutes after F0
  • F3: 5 minutes after F0. At this step, we observe results to be available for 80% of requests on average.
  • F4: 10 minutes after F0
  • F5: 15 minutes after F0
  • Fn: 20 minutes after F0. 100% of results should be available.

Important: Retrieval of asynchronous checks strategies should be stopped from this point.

Controls results of a SEPA Mail Diamond that have not been responded within 20 minutes should be considered “in error” / “timeout”.

 

Retry of a check

As the retrieval approach has been expired, API consumer may consider try to relaunch a new identical control using the POST/PUT routes.

Related to

Related articles