Payment consents

Further reading on how to manage Consents when creating payments with Yapily.

Introduction

In order to process a payment on behalf of the user, the user will need to authenticate with their financial institution and give explicit consent. In most cases, this will involve redirecting users to the bank's authorisation screen either in the web browser or on a mobile device by redirecting to the url provided by the authorisation-url or qr-code-url. In any case, the goal is to obtain a consent-token which is supplied as the Consent header parameter to sign payments requests. Collectively we refer to this process as 'Obtaining a Consent' or 'Authorisation'.

Consent Validity

A PIS consent-token is single use only. Once the consent-token has been used to execute the payment, it can only be used to check the payment details.

Authorisation Status

Depending on which of the payment authorisation flows the Institution your user is initiating a payment from, the Consent status may transition through a number of intermediary states. These states indicate an action that must either be performed by the user before you can be issued a consentToken to successfully initiate the payment:

Status UNKNOWN: This is just the enumeration's default.

Multiple Authorisations

For some business and joint accounts, as part of the SCA process for Open Banking, your users may be required to give multiple authorisations to approve the initiation of a payment.

The normal authorisation flow takes place for the first PSU, including getting receipt of the consent token.

When you request payment execution and multiple authorisations are required:

• The payment status will remain at PENDING
• Information regarding the additional authorisations is included in the MultiAuthorisationStatus object for the payment. This object contains details of how many authorisations are required and how many more need to be completed

For example:

{
    "data": {
        "id": "pv3-c8eece27-eb1a-4c27-a13c-2f805703dab2",
        "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
        "institutionConsentId": "sdp-1-aa9d0941-43ff-4abb-8129-4d56b620b8ee",
        "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d1",
        "status": "PENDING",
        "statusDetails": {
            "status": "PENDING",
            "statusUpdateDate": "2019-09-26T15:38:33.401Z",
            "multiAuthorisationStatus": {
                "status": "AWAITING_FURTHER_AUTHORIZATION",
                "numberOfAuthorisationRequired": 2,
                "numberOfAuthorisationReceived": 1,
                "lastUpdatedDateTime": "2019-09-26T15:38:33.408Z"
            }
        }
    }
}

The extra authorisations take place offline (phone, sms, text, email) and are completed by the owner of the business account or the other account holders of the joint account. As these are offline authorisations, they do not take place within Yapily's domain. Once the authorisations are completed, the payment status is updated. You can monitor the status of the payment using Get Payment Details.