Payment Authorisation

Further reading on the second step in performing a payment with Yapily.


2 Authorisation

API References

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'.

Authorisation Flows

The Payment Initiation Flow starts when your user (PSU) indicates their intent to make a payment.

Depending on the Institution your user wishes to use for the payment request, you may need to initate one of the following authorisation flows:

Note: Each of the flows listed below will assume your redirectUrl is managed by Yapily (if it is https://auth.yapily.com/) in order to keep the number of diagrams and explanations minimal. If you have your own redirectUrl, see the "Managed by you" dropdown in Redirect Url to see how each of the flows differ for you.

Default One-legged Payment Authorisation Flow

  • Every Institution that exclusively has the INITIATE_ACCOUNT_REQUEST feature (and no other INITIATE features mentioned in the flows below) will always use the "one-legged" flow
  • The flow is "one-legged" because there is only one authorisation request sent to the Institution in the authorisation flow
  • The flow is "default" because this is the flow that occurs when no callback is specified in the single authorisation request
  • Use GET Institutions to check for each Institution that uses the INITIATE_ACCOUNT_REQUEST feature
  • If your redirectUrl is managed by Yapily (if it is https://auth.yapily.com/), Yapily recommends using the callback option replacing steps 2-3 in the following flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.

Show Details
  1. You will need to execute POST Create Payment Authorisation or POST Create Bulk Payment Authorisation request and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_AUTHORIZATION until the user authorises the request
  2. After the user authorises the request at the Institution, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to initiate the payment on behalf of the user
  3. Using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  4. You will then be able to use the consent-token to initiate the payment using POST Create Payment or POST Create Bulk Payment
  5. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-1L_Default_Payments

Default Two-legged Payment Authorisation Flow

  • Every Institution that has the INITIATE_PRE_AUTHORISATION feature will always use the "default two-legged" flow
  • The flow is "two-legged" because there are two authorisation request sent to the Institution in the authorisation flow
  • The flow is "default" because this is the flow that occurs when no callback is specified in both authorisation requests
  • Use GET Institutions to check for each Institution that uses the INITIATE_PRE_AUTHORISATION feature
  • IIf your redirectUrl is managed by Yapily (if it is https://auth.yapily.com/), Yapily recommends using the callback option replacing steps 2-3 and 5-6 in the following flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.

Show Details
  1. You will need to execute POST Create Pre-authorisation request with the body parameter scope: PIS and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_PRE_AUTHORIZATION until the user authorises the request
  2. After the user authorises the request at the Institution, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to authorise the pre authorisation request
  3. Using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  4. You will then need to execute PUT Update Payment Authorisation request with the consentToken and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_AUTHORIZATION until the user authorises the request
  5. After the user authorises the request at the Institution for the second time, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to initiate the payment on behalf of the user
  6. Once again, using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  7. You will then be able to use the consent-token to initiate the payment using POST Create Payment
  8. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-2L_Default_Payments

Decoupled Two-legged Payment Authorisation Flow

  • Every Institution that has the INITIATE_PRE_AUTHORISATION feature and returns the AWAITING_DECOUPLED_AUTHORIZATION status in the second authorisation will always use the "decoupled two-legged" flow.
  • The flow is "two-legged" because there are two authorisation request sent to the Institution in the authorisation flow
  • The flow is "decoupled" because it contains a mandatory decoupled authorisation step
  • Use GET Institutions to check for each Institution that uses the INITIATE_PRE_AUTHORISATION feature
  • If your redirectUrl is managed by Yapily (if it is https://auth.yapily.com/), Yapily recommends using the callback option replacing steps 2-3 in the following flows. Alternatively, the callback with OTT option can also be used instead of the listed steps.

Show Details
  1. You will need to execute POST Create Pre-authorisation request with the body parameter scope: PIS and redirect the user to the Institution using the qrCodeUrl or authorisationUrl returned by the Yapily API. The status of the Consent will be AWAITING_PRE_AUTHORIZATION until the user authorises the request
  2. After the user authorises the request at the Institution, the user will be redirected to the redirectUrl where the Consent object will be updated with the consent-token to authorise the pre authorisation request
  3. Using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  4. You will then need to execute PUT Update Payment Authorisation request with the consentToken. The status of the Consent will be AWAITING_DECOUPLED_AUTHORIZATION until the user authorises the request on their device
  5. The user will receive an authorisation directly from the Institution where they will authorise outside of Yapily. You can add a prompt in your application for the user to signal that they have approved the request in order to know when the consent-token is available, otherwise, poll the status of the Consent
  6. Once again, using the default flow, you will need to poll the result of GET Consent until the Consent object is updated with the consent-token
  7. You will then be able to use the consent-token to initiate the payment using POST Create Payment
  8. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-2L_Decoupled_Payments

Coupled Embedded Payment Authorisation Flow

  • Every Institution that has the INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT feature will always use the "embedded authorisation" flow
  • These flows are "embedded" because the user is never redirected to the Institution
  • These flows are "coupled" because the SCA code received by the user is sent to the Institution via Yapily
  • Use GET Institutions to check for each Institution that uses the INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT feature
  • The redirectUrl is not used at all in any of these flows so the diagrams are the same for all customers

Coupled Embedded Payment Flow (Single SCA method)

Show Details
  1. You will need to execute POST Create Embedded Payment Authorisation supplying the username and password of the user to the Institution as body parameters. The status of the Consent will be AWAITING_SCA_CODE
  2. When you send the POST request in step 1, the Institution will send the SCA code to the user directly. You will need to provide an input field to capture this in your application
  3. After the user inputs the SCA code, you will need to execute PUT Update Embedded Payment Authorisation using the consent-id returned in the response in step 1 along with the sca_code. If successful, the status of the Consent will transition to AUTHORIZED
  4. You will then need to execute GET Consent to obtain the consent-token
  5. You will then be able to use the consent-token to initiate the payment using POST Create Payment. Unlike other flows, the payment is actually executed by the Institution in step 3, however, this step is still required to obtain the payment-id
  6. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-Embedded_Payments_singSCA

Coupled Embedded Payment Flow (Multiple SCA Methods)

Show Details
  1. You will need to execute POST Create Embedded Payment Authorisation supplying the username and password of the user to the Institution as body parameters. Yapily will respond with the various SCA methods that the Institution supports and the status of the Consent will be AWAITING_SCA_METHOD
  2. You can use the various sca methods returned by Yapily to populate a dropdown and display the options the Institution supports to the user in your application
  3. After the user selects an SCA method, you will need to execute PUT Update Embedded Payment Authorisation using the consent-id returned in the response in step 1 and the sca_methodId. If successful, the status of the Consent will transition to AWAITING_SCA_CODE
  4. When you send the PUT request in step 3, the Institution will send the SCA code to the user directly. You will need to provide an input field to capture this in your application
  5. After the user inputs the SCA code, you will need to execute PUT Update Embedded Payment Authorisation a second time using the consent-id returned in the response in step 1 along with the sca_code. If successful, the status of the Consent will transition to AUTHORIZED
  6. You will then need to execute GET Consent to obtain the consent-token
  7. You will then be able to use the consent-token to initiate the payment using POST Create Payment. Unlike other flows, the payment is actually executed by the Institution in step 5, however, this step is still required to obtain the payment-id
  8. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-Embedded_Payments_MultiSCA

Decoupled Embedded Payment Authorisation Flow

  • Every Institution that has the INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT feature will always use the "embedded authorisation" flow
  • These flows are "embedded" because the user is never redirected to the Institution
  • These flows are "decoupled" because they contain a mandatory decoupled authorisation step
  • Use GET Institutions to check for each Institution that uses the INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT feature
  • The redirectUrl is not used at all in any of these flows so the diagrams are the same for all customers

Decoupled Embedded Payment Flow (Single SCA method)

Show Details
  1. You will need to execute POST Create Embedded Payment Authorisation supplying the username and password of the user to the Institution as body parameters. The status of the Consent will be AWAITING_SCA_CODE
  2. When you send the POST request in step 1, the Institution will send the SCA code to the user directly. You will need to provide an input field to capture this in your application
  3. After the user inputs the SCA code, you will need to execute PUT Update Embedded Payment Authorisation using the consent-id returned in the response in step 1 along with the sca_code. If successful, the status of the Consent will transition to AWAITING_DECOUPLED_AUTHORIZATION until the user authorises the request on their device
  4. The user will receive an authorisation directly from the Institution where they will authorise outside of Yapily. You can add a prompt in your application for the user to signal that they have approved the request in order to know when the consent-token is available, otherwise, poll the status of the Consent
  5. You will then need to execute GET Consent to obtain the consent-token
  6. You will then be able to use the consent-token to initiate the payment using POST Create Payment. Unlike other flows, the payment is actually executed by the Institution once the user has completed the decoupled authorisation, however, this step is still required to obtain the payment-id
  7. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-Embedded_Payments_singSCA

Decoupled Embedded Payment Flow (Multiple SCA Methods)

Show Details
  1. You will need to execute POST Create Embedded Payment Authorisation supplying the username and password of the user to the Institution as body parameters. Yapily will respond with the various SCA methods that the Institution supports and the status of the Consent will be AWAITING_SCA_METHOD
  2. You can use the various sca methods returned by Yapily to populate a dropdown and display the options the Institution supports to the user in your application
  3. After the user selects an SCA method, you will need to execute PUT Update Embedded Payment Authorisation using the consent-id returned in the response in step 1 and the sca_methodId. If successful, the status of the Consent will transition to AWAITING_SCA_CODE
  4. When you send the PUT request in step 3, the Institution will send the SCA code to the user directly. You will need to provide an input field to capture this in your application
  5. After the user inputs the SCA code, you will need to execute PUT Update Embedded Payment Authorisation a second time using the consent-id returned in the response in step 1 along with the sca_code. If successful, the status of the Consent will transition to AWAITING_DECOUPLED_AUTHORIZATION until the user authorises the request on their device
  6. The user will receive an authorisation directly from the Institution where they will authorise outside of Yapily. You can add a prompt in your application for the user to signal that they have approved the request in order to know when the consent-token is available, otherwise, poll the status of the Consent
  7. You will then need to execute GET Consent to obtain the consent-token
  8. You will then be able to use the consent-token to initiate the payment using POST Create Payment. Unlike other flows, the payment is actually executed by the Institution once the user has completed the decoupled authorisation, however, this step is still required to obtain the payment-id
  9. You will also be able to use the consent-token along with the payment-id from the response of the previous request to check the status of the payment using GET Payment Details
Authorisation_Flows-Embedded_Payments_MultiSCA

Payment Types

The following table shows the different payment types that are currently available in Yapily. The associated features column shows the features that will be created in the payment consent after you execute Create Payment Authorisation and specify one of the payment types.

To create bulk payments, there is no bulk payment type. Instead you use Create Bulk Payment Authorisation which will take an array of paymentRequest where the payment type will be defined per payment.

Payment Type Description Associated Features
DOMESTIC_INSTANT_PAYMENT Initiate and create domestic single instant payments.

The DOMESTIC_INSTANT_PAYMENT payment type is used to indicate that when sending funds to another account from a participating SEPA country and when the payment is in Euros, SEPA Instant in addition to SEPA is also a viable configuration for the payment.

See European Payments for more information.
INITIATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
CREATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
EXISTING_PAYMENT_DETAILS
DOMESTIC_PAYMENT Initiate and create domestic single payments.

Particular payments between accounts from SEPA member countries can be considered a DOMESTIC_PAYMENT payment when the payment is in Euros. In these scenarios, funds will be transferred via. SEPA.

See European Payments for more information.
INITIATE_DOMESTIC_SINGLE_PAYMENT
CREATE_DOMESTIC_SINGLE_PAYMENT
EXISTING_PAYMENT_DETAILS
DOMESTIC_PERIODIC_PAYMENT Initiate and create domestic periodic payments. They are known as standing orders in UK. INITIATE_DOMESTIC_PERIODIC_PAYMENT
CREATE_DOMESTIC_PERIODIC_PAYMENT
EXISTING_PAYMENT_DETAILS
DOMESTIC_SCHEDULED_PAYMENT Initiate and create domestic scheduled payments. INITIATE_DOMESTIC_SCHEDULED_PAYMENT
CREATE_DOMESTIC_SCHEDULED_PAYMENT
EXISTING_PAYMENT_DETAILS
INTERNATIONAL_PAYMENT Initiate and create international single payments. INITIATE_INTERNATIONAL_SINGLE_PAYMENT
CREATE_INTERNATIONAL_SINGLE_PAYMENT
EXISTING_PAYMENT_DETAILS
INTERNATIONAL_PERIODIC_PAYMENT Initiate and create international periodic payments. INITIATE_INTERNATIONAL_PERIODIC_PAYMENT
CREATE_INTERNATIONAL_PERIODIC_PAYMENT
EXISTING_PAYMENT_DETAILS
INTERNATIONAL_SCHEDULED_PAYMENT Initiate and create international scheduled payments. INITIATE_INTERNATIONAL_SCHEDULED_PAYMENT
CREATE_INTERNATIONAL_SCHEDULED_PAYMENT
EXISTING_PAYMENT_DETAILS

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.

Payment Features

The following payment features are used to create or use a PIS consent-token:

Feature Description Endpoint
CREATE_BULK_PAYMENT Create a bulk payment request from a business account POST Create Bulk Payment
CREATE_DOMESTIC_PERIODIC_PAYMENT Create a domestic periodic payment (known as a standing order in UK) POST Create Payment
CREATE_DOMESTIC_SCHEDULED_PAYMENT Create a domestic scheduled payment
CREATE_DOMESTIC_SINGLE_INSTANT_PAYMENT Create a domestic single instant payment
CREATE_DOMESTIC_SINGLE_PAYMENT Create a domestic single payment
CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT Create a domestic variable recurring payment. Not currently available
CREATE_INTERNATIONAL_PERIODIC_PAYMENT Create an international periodic payment
CREATE_INTERNATIONAL_SCHEDULED_PAYMENT Create an international scheduled payment
CREATE_INTERNATIONAL_SINGLE_PAYMENT Create an international single payment
CREATE_INTERNATIONAL_VARIABLE_RECURRING_PAYMENT Create an international variable recurring payment
CREATE_SINGLE_PAYMENT_SORTCODE Deprecated. Initiate a payment request using the account sort code POST Create Sort Code Payment
EXISTING_PAYMENTS_DETAILS Get the payment details of a payment GET Payment Details
INITIATE_BULK_PAYMENT Initiate a bulk payment request from a business account POST Create Bulk Payment Authorisation
INITIATE_DOMESTIC_PERIODIC_PAYMENT Initiate a domestic periodic payment (known as a standing order in UK) POST Create Payment Authorisation
INITIATE_DOMESTIC_SCHEDULED_PAYMENT Initiate a domestic scheduled payment
INITIATE_DOMESTIC_SINGLE_INSTANT_PAYMENT Initiate a domestic single instant payment
INITIATE_DOMESTIC_SINGLE_PAYMENT Initiate a domestic single payment
INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT Initiate a domestic variable recurring payment
INITIATE_INTERNATIONAL_PERIODIC_PAYMENT Initiate an international periodic payment
INITIATE_INTERNATIONAL_SCHEDULED_PAYMENT Initiate an international scheduled payment
INITIATE_INTERNATIONAL_SINGLE_PAYMENT Initiate an international single payment
INITIATE_INTERNATIONAL_VARIABLE_RECURRING_PAYMENT Initiate an international variable recurring payment
INITIATE_PRE_AUTHORISATION Initiate a generic pre-authorisation request POST Create Pre-authorisation
INITIATE_SINGLE_PAYMENT_SORTCODE Deprecated. Initiate a payment authorisation request using the accounts sort code request POST Create Sort Code Payment Authorisation
PERIODIC_PAYMENT_FREQUENCY_EXTENDED - -
READ_DOMESTIC_PERIODIC_PAYMENT_REFUND Initiate a domestic periodic payment (known as a standing order in UK) GET Payment Details
POST Create Payment
READ_DOMESTIC_SCHEDULED_REFUND Get the refund details for a domestic scheduled payment
READ_DOMESTIC_SINGLE_REFUND Get the refund details for a domestic single payment
READ_INTERNATIONAL_SCHEDULED_REFUND Get the refund details for an international scheduled payment
READ_INTERNATIONAL_SINGLE_REFUND Get the refund details for an international single payment

Account Identification

When making a Payment, it is necessary to provide details of the Account which you would like the payment to be sent. This is the purpose of the AccountIdentification object in the PaymentRequest.

Type Description Format
SORT_CODE Used only in the UK in conjunction with ACCOUNT_NUMBER to uniquely identify account 6 numerical characters
ACCOUNT_NUMBER Used only in the UK in conjunction with SORT_CODE to uniquely identify account 8 numerical characters
IBAN National standard for uniquely identifying bank accounts See IBAN Formats by countries
BBAN The Basic Bank Account Number. This forms the first part of the IBAN after the first 4 characters See IBAN Formats by countries
BIC Business Identifier Codes otherwise known as SWIFT Code No specific format
PAN - -
MASKED_PAN - -
MSISDN - -
BSB - -
NCC - -
ABA - -
ABA_WIRE - -
ABA_ACH - -
EMAIL Email address -

Combinations

For more assistance on what account identifications to use in specific scenarios, see the following table below of which account identifications are generally required:

Payer Country Payee Country Payee Account Identification
UK UK ACCOUNT_NUMBER + SORT_CODE
UK All EU and EEA countries: Albania, Austria, Belgium, Bosnia and Herzegovina, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Greece, Guernsey, Hungary, Iceland, Republic of Ireland, Italy, Jersey, Latvia, Liechtenstein, Lithuania, Luxembourg, Malta, The Netherlands, Norway, Poland, Portugal, Romania, Slovakia, Slovenia, Spain and Sweden and also the following non EU and EEA countries: Andorra, Bahrain, Faroe Islands, Georgia, Gibraltar, Greenland, Isle of Man, Israel, Jordan, Kuwait, Lebanon, Macedonia, Montenegro, Moldova, Monaco, Pakistan, Palestine, Qatar, San Marino, Saudi Arabia, Switzerland, Tunisia, Turkey, and United Arab Emirates. IBAN + BIC
UK Australia: Bank-State-Branch (BSB) Code Canada: Canadian Transit Number Hong Kong: Bank Code of Hong Kong India: IFSC - Indian Financial Sys Code New Zealand: New Zealand National Clearing Code South Africa: South Africa National Clearing United States: Fedwire code NCC (National Clearing Code) AND/OR BIC
UK Other countries BBAN / IBAN + BIC
SEPA Country (EUR) SEPA Country (EUR) IBAN*

* This type of payment will also require the Payer account identifications

Authorisation Status & Payment Status

Payment initiation is a two-step process, with each step having its own process flow and status:

  1. Obtaining the user's authorisation (through the Create Payment Authorisation endpoint)

    The current status of the user's authorisation can be obtained by calling the Get Consent endpoint

  2. Requesting payment execution (through the Create Payment endpoint)

    This will only be successful if the authorisation status is AUTHORIZED. As soon as a Payment Submission is successful, the authorisation status becomes CONSUMED (although, currently, this occurs for OBIE ASPSP’s only)

The current status of the payment can be obtained by calling the Get Payment Details endpoint

The full flow of these two different states is defined in the diagram below:

Mulitple 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 MultiAuthorisation object for the payment. This object contains details of how many authorisations are required and how many more need to be completed

e.g.:

{
    "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

Payment Frequency

The Payment Frequency should be set for recurring payments.

Description executionDay intervalWeek intervalMonth type
Every day - - - DAILY
Every working day - - - EVERY_WORKING_DAY
Every 15th day of the month 15 - - CALENDAR_DAY
Every week, on the 3rd day of the week 3 1 - WEEKLY
Every 2 weeks, on the 3rd day of the week 3 2 - EVERY_TWO_WEEKS
Every 3 weeks, on the 3rd day of the week 3 3 - WEEKLY
Every month, on the 2nd week of the month and on the 3rd day of the week 3 2 1 MONTHLY
Every month, on the first day of the month 1 - 1 MONTHLY
Every 2 months, on the 15th day of the month 15 - 2 EVERY_TWO_MONTHS
Every 3 months, on the 15th day of the month 15 - 3 MONTHLY
Every 6 months, on the 15th day of the month 15 - - SEMIANNUAL
Every 12 months, on the 3rd day of the month 3 - - ANNUAL
Every quarter - - - QUARTERLY