Yapily API (6.0.0)

Download OpenAPI specification:Download

The Yapily API enables connections between your application and users' banks. For more information check out our documentation.

In particular, make sure to view our Getting Started steps if this is your first time here.

While testing the API, our list of sandbox credentials maybe useful.

Authentication

basicAuth

Requests to the Yapily API are authenticated using an Application's APPLICATION_KEY and APPLICATION_SECRET. You can view and manage your credentials in the Yapily Console.

An APPLICATION_KEY and APPLICATION_SECRET pair provides connectivity to each Institution configured in a Yapily Application, so it is important to keep these credentials secure. Do not share your APPLICATION_SECRET in publicly accessible areas such as GitHub, client-side code, etc.

Authentication is performed using HTTP Basic Authentication. Your APPLICATION_KEY should be sent as the basic auth username and your APPLICATION_SECRET should be sent as the basic auth password.

All requests should be made via HTTPS.

Security Scheme Type HTTP
HTTP Authorization Scheme basic

Application

The Application is the base entity that is used to interact with the API and contains a collection of Institution objects. You can have multiple Applications associated with your account e.g. a production application with live access to each Institution and a development application with access to sandboxes.

Get Application Self

Get the information about the institutions configured in your application

Request
Security:
Responses
200

Ok

default

Error Response

get/me
Request samples
curl -i -X GET \
  -u <username>:<password> \
  https://api.yapily.com/me
Response samples
application/json;charset=UTF-8

Example Response

{
}

Users

The Users endpoints are used to manage each user (otherwise known as the PSU) in Yapily. Each user belongs to an Application and as a consequence, so do each Consent created for a particular User.

Get Users

Get all the users configured in your application

Request
Security:
query Parameters
filter[applicationUserId]
Array of strings unique

Optional. Filter records based on the list of applicationUserId users provided.

Responses
200

Ok

default

Error Response

get/users
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/users?filter%5BapplicationUserId%5D=string'
Response samples
application/json;charset=UTF-8

Example Response

[
]

Create User

Create a new user in your application

Request
Security:
Request Body schema: application/json;charset=UTF-8
applicationUserId
string

Optional. The unique identifier of the Application User assigned by the Application Owner.

referenceId
string

Deprecated. A non-unique reference Id for the Application User.

Responses
201

Created

default

Error Response

post/users
Request samples
application/json;charset=UTF-8

Create User Example Request

{
}
Response samples
application/json;charset=UTF-8

Example Response

{
}

Delete User

Delete a user from your application along with any sub-resources (including consent resources on institution APIs if they exist)

Request
Security:
path Parameters
userUuid
required
string <uuid>

Mandatory. The Yapily generated UUID for the user.

Responses
200

Ok

default

Error Response

delete/users/{userUuid}
Request samples
curl -i -X DELETE \
  -u <username>:<password> \
  'https://api.yapily.com/users/{userUuid}'
Response samples
application/json;charset=UTF-8

Example Response

{
}

Get User

Get a specific user using the user UUID

Request
Security:
path Parameters
userUuid
required
string <uuid>

Mandatory. The Yapily generated UUID for the user.

Responses
200

Ok

default

Error Response

get/users/{userUuid}
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/users/{userUuid}'
Response samples
application/json;charset=UTF-8

Example Response

{
}

Institutions

An Institution object represents any Account Serving Payment Servicing Provider (ASPSP) that has been integrated and is accessible through the Yapily APIs (ASPSPs are entities that publish Read/Write APIs to permit, with customer consent, payments initiated by third party providers and/or make their customers� financial data available to third party providers via their API endpoints).

Any one of the following would be represented as Institution:

  • Traditional banks e.g. Santander
  • Neo-banks e.g. Monzo
  • Building societies e.g. Cumberland Building Society

Get Features

Used to retrieve all features available from Yapily. Each Institution supports a one, many or all of these features and can be seen in the features field of the Institution object.

Note: Every Institution does not necessarily support every feature. To see which features are available for a particular Institution, use either the Get Institutions or Get Institution endpoint and check the features array within the Institution payload.

Request
Security:
Responses
200

Ok

default

Error Response

get/features
Request samples
curl -i -X GET \
  -u <username>:<password> \
  https://api.yapily.com/features
Response samples
application/json;charset=UTF-8

Example Response

{}

Get Institutions

Used to retrieve all Institutions within an application

Request
Security:
Responses
200

Ok

default

Error Response

get/institutions
Request samples
curl -i -X GET \
  -u <username>:<password> \
  https://api.yapily.com/institutions
Response samples
application/json;charset=UTF-8

Example Response

{
}

Get Institution

Used to retrieves details of a specific Institution within an application

Request
Security:
path Parameters
institutionId
required
string

Mandatory. The Yapily institution Id for the Institution.

Responses
200

Ok

default

Error Response

get/institutions/{institutionId}
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/institutions/{institutionId}'
Response samples
application/json;charset=UTF-8

Example Response

{
}

Consents

The Consents endpoints are used to manage each Consent created by Yapily in response to an authorisation created for a user.

The Consent object contains data that identifies a user's consent for a specific Institution within a Yapily application. Other than the id of the consent, the institution-id for the corresponding Institution and the user identifiers (user-uuid and application-user-id), it contains various details that indicates how the Consent can be used.

Exchange OAuth2 Code

Used to obtain a Yapily Consent object containing the consentToken once the user has authenticated and you have an OAuth2 authorisation code auth-code and state auth-state.

Request
Security:
Request Body schema: application/json
authCode
required
string

Mandatory. The authorisation code

authState
required
string

Mandatory. The authorisation state

Responses
200

Ok

default

Error Response

post/consent-auth-code
Request samples
application/json
{
}
Response samples
application/json;charset=UTF-8

Example Response

{
}

Exchange One Time Token

Exchange a One-time-token for the consent token

Request
Security:
Request Body schema: application/json
oneTimeToken
required
string

Mandatory. The one time token to exchange for a consent token.

Responses
201

Created

default

Error Response

post/consent-one-time-token
Request samples
application/json
{
}
Response samples
application/json;charset=UTF-8

Example Response

{
}

Get Consents

Used to retrieve all the consents created for each user within an application

Request
Security:
query Parameters
filter[applicationUserId]
Array of strings unique

Optional. Filter records based on the list of applicationUserId users provided.

filter[userUuid]
Array of strings <uuid> unique

Optional. Filter records based on the list of userUuid users provided.

filter[institution]
Array of strings unique

Optional. Filter records based on the list of Institution provided.

filter[status]
Array of strings unique

Optional. Filter records based on the list of Consent statuses.

from
string

Optional. Returned transactions will be on or after this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).

before
string

Optional. Returned transactions will be on or before this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).

limit
integer <int32>

Optional. The maximum number of transaction records to be returned. Must be between 1 and 1000.

offset
integer <int32>
Default: 0

Optional. The number of transaction records to be skipped. Used primarily with paginated results.

Responses
200

Ok

default

Error Response

get/consents
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/consents?filter%5BapplicationUserId%5D=string&filter%5BuserUuid%5D=497f6eca-6276-4993-bfeb-53cbbbba6f08&filter%5Binstitution%5D=string&filter%5Bstatus%5D=string&from=string&before=string&limit=0&offset=0'
Response samples
application/json;charset=UTF-8

Example Response

{
}

Delete Consent

Delete a consent using the consent Id

Request
Security:
path Parameters
consentId
required
string <uuid>

Mandatory. The consent Id of the Consent to update.

query Parameters
forceDelete
boolean
Default: true

Optional. Whether to force the deletion.

Responses
200

Ok

default

Error Response

delete/consents/{consentId}
Request samples
curl -i -X DELETE \
  -u <username>:<password> \
  'https://api.yapily.com/consents/{consentId}?forceDelete=true'
Response samples
application/json;charset=UTF-8

Example Response

{
}

Get Consent

Get consent using the consent Id

Request
Security:
path Parameters
consentId
required
string <uuid>

Mandatory. The consent Id of the Consent to update.

Responses
200

Ok

default

Error Response

get/consents/{consentId}
Request samples
curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/consents/{consentId}'
Response samples
application/json;charset=UTF-8

Example Response

{
}

Extend Consentbeta

Used to indicate to Yapily that reconfirmation has occurred for a given Consent, and to update lastUpdatedAt and reconfirmBy for that Consent. Returns the Consent.

Request
Security:
path Parameters
consentId
required
string <uuid>

Mandatory. The consent Id of the Consent to update.

Request Body schema: application/json;charset=UTF-8
lastConfirmedAt
required
string <date-time>

Mandatory. The time that the user confirmed access to their account information

Responses
200

Created

400

Error Response. The supplied lastConfirmedAt date, Consent type, or Consent status is invalid.

default

Error Response

post/consents/{consentId}/extend
Request samples
application/json;charset=UTF-8

Extend Consent Example Request

{
}
Response samples
application/json;charset=UTF-8

Example Response

{
}

Authorisations

Before calling Financial Data or Payments endpoints, a consent from an end-user must be obtained.

Consents are valid for up to 90 days for Financial Data endpoints and have a single-use for Payment endpoints i.e. a new consent must be obtained for each payment.

Re-authorise Account Consent

Used to prompt the account holder for continued access to their financial data. This endpoint should be used when a Consent that was previously AUTHORIZED can no longer be used to retrieve data.

See Re-Authorisation for more information.

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
consent
required
string

Mandatory. The consent-token containing the user's authorisation to make the request.

Example: {consentToken}
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application
string <uuid>

The sub-application ID to which event type is being subscribed to

Responses
201

Created

default

Error Response

patch/account-auth-requests
Request samples
curl -i -X PATCH \
  -u <username>:<password> \
  'https://api.yapily.com/account-auth-requests?raw=true' \
  -H 'consent: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-id: string' \
  -H 'psu-ip-address: string' \
  -H 'sub-application: 497f6eca-6276-4993-bfeb-53cbbbba6f08'
Response samples
application/json;charset=UTF-8

OBIE Example Response

{}

Create Account Authorisation

Used to initiate the authorisation process and direct users to the login screen of their financial institution in order to give consent to access account data.

See Redirect Account Flows for more information about this flow.

Feature: INITIATE_ACCOUNT_REQUEST

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application
string <uuid>

The sub-application ID to which event type is being subscribed to

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>

User for which the authorisation request was created.

applicationUserId
string

Conditional. User-friendly identifier of the User that provides authorisation. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

forwardParameters
Array of strings

Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The server to redirect the user to after the user completes the authorisation at the Institution.

See Using a callback (Optional) for more information.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

object (AccountRequest)

Conditional. Used to further specify details of the Consent to request

Conditions:

  1. Mandatory to specify the individual scopes to request from the user at the Institution for an account authorisation
  2. Mandatory to specify an expiry time on the created Consent at which time will render it unusable
  3. Mandatory to specify the date range that the created Consent will be able to access transactions for (given the range is support for the Institution)

Responses
201

Created

default

Error Response

post/account-auth-requests
Request samples
application/json;charset=UTF-8

OBIE Example Request

{}
Response samples
application/json;charset=UTF-8

OBIE Example Response

{}

Update Account Pre-authorisation

Used to continue the authorisation process and for any Institution that contains the INITIATE_PRE_AUTHORISATION feature and direct user to the login screen of their financial institution in order to give consent to access account data.

See Redirect Account Flows for more information about this flow.

Features:

  • INITIATE_ACCOUNT_REQUEST
  • INITIATE_PRE_AUTHORISATION

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
consent
required
string

Mandatory. The consent-token containing the user's authorisation to make the request.

Example: {consentToken}
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application
string <uuid>

The sub-application ID to which event type is being subscribed to

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>

User for which the authorisation request was created.

applicationUserId
string

Conditional. User-friendly identifier of the User that provides authorisation. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

forwardParameters
Array of strings

Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The server to redirect the user to after the user completes the authorisation at the Institution.

See Using a callback (Optional) for more information.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

object (AccountRequest)

Conditional. Used to further specify details of the Consent to request

Conditions:

  1. Mandatory to specify the individual scopes to request from the user at the Institution for an account authorisation
  2. Mandatory to specify an expiry time on the created Consent at which time will render it unusable
  3. Mandatory to specify the date range that the created Consent will be able to access transactions for (given the range is support for the Institution)

Responses
200

Ok

default

Error Response

put/account-auth-requests
Request samples
application/json;charset=UTF-8

Berlin Group Example Request

{
}
Response samples
application/json;charset=UTF-8

OBIE Example Response

{
}

Create Bulk Payment Authorisation

Used to initiate the authorisation process and direct users to the login screen of their financial Institution in order to give their consent for a bulk payment. See Bulk Payments for more information.

See Redirect Payment Flows for more information about this flow.

Feature: INITIATE_BULK_PAYMENT

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>

Conditional. The reference to the User that will authorise the authorisation request using the Yapily generated UUID. Either the userUuid or applicationUserId must be provided.

applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

forwardParameters
Array of strings

Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

object (BulkPaymentRequest)

The payment request object defining the details of the bulk payment

Responses
201

Created

default

Error Response

post/bulk-payment-auth-requests
Request samples
application/json;charset=UTF-8

UK Bulk Payment Example Request

{
}
Response samples
application/json;charset=UTF-8

UK Bulk Payment Example Response

{}

Create Embedded Account Authorisation

Used to initiate the embedded authorisation process for an Institution that contains the INITIATE_EMBEDDED_ACCOUNT_REQUEST feature in order to obtain the the user's authorisation to access their account information.

See Embedded Account Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_ACCOUNT_REQUEST

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application
string <uuid>

The sub-application ID to which event type is being subscribed to

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>

User for which the authorisation request was created.

applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

forwardParameters
Array of strings

Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

object (UserCredentials)

Conditional. Used to capture the user's credentials to allow them to login to an Institution that uses the embedded account authorisation flow.

This is the first step required in the embedded account authorisation flow to authorise the Consent.

object (ScaMethod)

Conditional. Used to update the authorisation with the sca method of the user's choice for the Institution that uses the embedded authorisation flow. If the user has multiple sca methods configured, the Institution will allow the user to select from each of these options.

When the user has multiple sca methods for the Institution, this is the second step required in the embedded authorisation flow to authorise the Consent.

scaCode
string

Conditional. Used to update the authorisation with the sca code received by the user from the Institution using the embedded account authorisation flow.

This is the penultimate step required in the embedded account authorisation flow to authorise the Consent. After sending the sca code, to obtain an authorised consent, the last step is to poll Get Consent until the Institution authorises the request and the Consent status transitions to AUTHORIZED.

object (AccountRequest)

Conditional. Used to further specify details of the Consent to request

Conditions:

  1. Mandatory to specify the individual scopes to request from the user at the Institution for an account authorisation
  2. Mandatory to specify an expiry time on the created Consent at which time will render it unusable
  3. Mandatory to specify the date range that the created Consent will be able to access transactions for (given the range is support for the Institution)

Responses
201

Created

default

Error Response

post/embedded-account-auth-requests
Request samples
application/json;charset=UTF-8

Berlin Group Example Request

{
}
Response samples
application/json;charset=UTF-8

Berlin Group (Multiple SCA Methods) Example Response

{
}

Update Embedded Account Authorisation

Used to pass the SCA Code received from the Institution (and the SCA method selected by the user where multiple SCA methods are supported by the Institution) in order to complete the embedded authorisation to access the user's financial data.

See Embedded Account Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_ACCOUNT_REQUEST

Request
Security:
path Parameters
consentId
required
string

Mandatory. The consent Id of the Consent to update.

query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application
string <uuid>

The sub-application ID to which event type is being subscribed to

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>

User for which the authorisation request was created.

applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

forwardParameters
Array of strings

Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

object (UserCredentials)

Conditional. Used to capture the user's credentials to allow them to login to an Institution that uses the embedded account authorisation flow.

This is the first step required in the embedded account authorisation flow to authorise the Consent.

object (ScaMethod)

Conditional. Used to update the authorisation with the sca method of the user's choice for the Institution that uses the embedded authorisation flow. If the user has multiple sca methods configured, the Institution will allow the user to select from each of these options.

When the user has multiple sca methods for the Institution, this is the second step required in the embedded authorisation flow to authorise the Consent.

scaCode
string

Conditional. Used to update the authorisation with the sca code received by the user from the Institution using the embedded account authorisation flow.

This is the penultimate step required in the embedded account authorisation flow to authorise the Consent. After sending the sca code, to obtain an authorised consent, the last step is to poll Get Consent until the Institution authorises the request and the Consent status transitions to AUTHORIZED.

object (AccountRequest)

Conditional. Used to further specify details of the Consent to request

Conditions:

  1. Mandatory to specify the individual scopes to request from the user at the Institution for an account authorisation
  2. Mandatory to specify an expiry time on the created Consent at which time will render it unusable
  3. Mandatory to specify the date range that the created Consent will be able to access transactions for (given the range is support for the Institution)

Responses
201

Created

default

Error Response

put/embedded-account-auth-requests/{consentId}
Request samples
application/json;charset=UTF-8

Berlin Group (SCA Code) Example Request

{
}
Response samples
application/json;charset=UTF-8

Berlin Group (SCA Code) Example Response

{
}

Create Embedded Bulk Payment Authorisation

Used to initiate the embedded authorisation process for an Institution that contains the INITIATE_EMBEDDED_BULK_PAYMENT feature in order to obtain the the user's authorisation for a bulk payment. See Bulk Payments for more information.

See Embedded Payment Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_BULK_PAYMENT

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>

Conditional. The reference to the User that will authorise the authorisation request using the Yapily generated UUID. Either the userUuid or applicationUserId must be provided.

applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

object (BulkPaymentRequest)

The payment request object defining the details of the bulk payment

object (UserCredentials)

Conditional. Used to capture the user's credentials to allow them to login to an Institution that uses the embedded account authorisation flow.

This is the first step required in the embedded account authorisation flow to authorise the Consent.

object (ScaMethod)

Conditional. Used to update the authorisation with the sca method of the user's choice for the Institution that uses the embedded authorisation flow. If the user has multiple sca methods configured, the Institution will allow the user to select from each of these options.

When the user has multiple sca methods for the Institution, this is the second step required in the embedded authorisation flow to authorise the Consent.

scaCode
string

Conditional. Used to update the authorisation with the sca code received by the user from the Institution using the embedded payment authorisation flow.

This is the penultimate step required in the embedded payment authorisation flow to authorise the Consent. After sending the sca code, to obtain an authorised consent, the last step is to poll Get Consent until the Institution authorises the request and the Consent status transitions to AUTHORIZED.

Responses
201

Created

default

Error Response

post/embedded-bulk-payment-auth-requests
Request samples
application/json;charset=UTF-8

Berlin Group EUR Embedded Bulk Payment Example Request

{
}
Response samples
application/json;charset=UTF-8

Berlin Group EUR Embedded Bulk Payment Example Response

{
}

Update Embedded Bulk Payment Authorisation

Used to pass the SCA Code received from the Institution (and the SCA method selected by the user where multiple SCA methods are supported by the Institution) in order to complete the embedded authorisation to initiate a bulk payment. See Bulk Payments for more information.

See Embedded Payment Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_BULK_PAYMENT

Request
Security:
path Parameters
consentId
required
string

Mandatory. The consent Id of the Consent to update.

query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>

Conditional. The reference to the User that will authorise the authorisation request using the Yapily generated UUID. Either the userUuid or applicationUserId must be provided.

applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

object (BulkPaymentRequest)

The payment request object defining the details of the bulk payment

object (UserCredentials)

Conditional. Used to capture the user's credentials to allow them to login to an Institution that uses the embedded account authorisation flow.

This is the first step required in the embedded account authorisation flow to authorise the Consent.

object (ScaMethod)

Conditional. Used to update the authorisation with the sca method of the user's choice for the Institution that uses the embedded authorisation flow. If the user has multiple sca methods configured, the Institution will allow the user to select from each of these options.

When the user has multiple sca methods for the Institution, this is the second step required in the embedded authorisation flow to authorise the Consent.

scaCode
string

Conditional. Used to update the authorisation with the sca code received by the user from the Institution using the embedded payment authorisation flow.

This is the penultimate step required in the embedded payment authorisation flow to authorise the Consent. After sending the sca code, to obtain an authorised consent, the last step is to poll Get Consent until the Institution authorises the request and the Consent status transitions to AUTHORIZED.

Responses
200

Ok

default

Error Response

put/embedded-bulk-payment-auth-requests/{consentId}
Request samples
application/json;charset=UTF-8

Berlin Group EUR Embedded Bulk Payment (SCA Code) Example Request

{
}
Response samples
application/json;charset=UTF-8

Berlin Group EUR Embedded Bulk Payment (SCA Code) Example Response

{
}

Create Embedded Payment Authorisation

Used to initiate the embedded authorisation process for an Institution that contains the INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT feature in order to obtain the the user's authorisation for a payment.

See Embedded Payment Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application
string <uuid>

The sub-application ID to which event type is being subscribed to

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>
applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

required
object (PaymentRequest)

Mandatory. The payment request object defining the details of the payment.

object (UserCredentials)

Conditional. Used to capture the user's credentials to allow them to login to an Institution that uses the embedded account authorisation flow.

This is the first step required in the embedded account authorisation flow to authorise the Consent.

object (ScaMethod)

Conditional. Used to update the authorisation with the sca method of the user's choice for the Institution that uses the embedded authorisation flow. If the user has multiple sca methods configured, the Institution will allow the user to select from each of these options.

When the user has multiple sca methods for the Institution, this is the second step required in the embedded authorisation flow to authorise the Consent.

scaCode
string

Conditional. Used to update the authorisation with the sca code received by the user from the Institution using the embedded payment authorisation flow.

This is the penultimate step required in the embedded payment authorisation flow to authorise the Consent. After sending the sca code, to obtain an authorised consent, the last step is to poll Get Consent until the Institution authorises the request and the Consent status transitions to AUTHORIZED.

Responses
201

Created

default

Error Response

post/embedded-payment-auth-requests
Request samples
application/json;charset=UTF-8

Berlin Group EUR Single Domestic Payment Example Request

{
}
Response samples
application/json;charset=UTF-8

Berlin Group EUR Single Domestic Payment Example Response

{
}

Update Embedded Payment Authorisation

Used to pass the SCA Code received from the Institution (and the SCA method selected by the user where multiple SCA methods are supported by the Institution) in order to complete the embedded authorisation to initiate a payment.

See Embedded Payment Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT

Request
Security:
path Parameters
consentId
required
string

Mandatory. The consent Id of the Consent to update.

query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application
string <uuid>

The sub-application ID to which event type is being subscribed to

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>
applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

required
object (PaymentRequest)

Mandatory. The payment request object defining the details of the payment.

object (UserCredentials)

Conditional. Used to capture the user's credentials to allow them to login to an Institution that uses the embedded account authorisation flow.

This is the first step required in the embedded account authorisation flow to authorise the Consent.

object (ScaMethod)

Conditional. Used to update the authorisation with the sca method of the user's choice for the Institution that uses the embedded authorisation flow. If the user has multiple sca methods configured, the Institution will allow the user to select from each of these options.

When the user has multiple sca methods for the Institution, this is the second step required in the embedded authorisation flow to authorise the Consent.

scaCode
string

Conditional. Used to update the authorisation with the sca code received by the user from the Institution using the embedded payment authorisation flow.

This is the penultimate step required in the embedded payment authorisation flow to authorise the Consent. After sending the sca code, to obtain an authorised consent, the last step is to poll Get Consent until the Institution authorises the request and the Consent status transitions to AUTHORIZED.

Responses
200

Ok

default

Error Response

put/embedded-payment-auth-requests/{consentId}
Request samples
application/json;charset=UTF-8

Berlin Group EUR Single Domestic Payment (SCA Code) Example Request

{
}
Response samples
application/json;charset=UTF-8

Berlin Group EUR Single Domestic Payment (SCA Code) Example Response

{
}

Create Payment Authorisation

Used to initiate the authorisation process and direct users to the login screen of their financial Institution in order to give their consent for a payment. This endpoint is used to initiate all the different payment listed below. Based on the type of payment you wish to make, you may be required to provide specific properties in PaymentRequest. First make sure that the payment feature you wish to execute is supported by the bank by checking the features array in GET Institution.

See Redirect Payment Flows for more information about this flow.

Features:

  • INITIATE_DOMESTIC_PERIODIC_PAYMENT
  • INITIATE_DOMESTIC_SCHEDULED_PAYMENT
  • INITIATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
  • INITIATE_DOMESTIC_SINGLE_PAYMENT
  • INITIATE_INTERNATIONAL_PERIODIC_PAYMENT
  • INITIATE_INTERNATIONAL_SCHEDULED_PAYMENT
  • INITIATE_INTERNATIONAL_SINGLE_PAYMENT

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string (User Id)

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string (Corporate User Id)

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string (User IP Address)

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application
string <uuid>

The sub-application ID to which event type is being subscribed to

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>
applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

forwardParameters
Array of strings

Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The URL to redirect the user to after the user complete the authorisation at the Institution.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

required
object (PaymentRequest)

Mandatory. The payment request object defining the details of the payment.

Responses
201

Created

default

Error Response

post/payment-auth-requests
Request samples
application/json;charset=UTF-8

EUR Single Domestic Example Request

{
}
Response samples
application/json;charset=UTF-8

EUR Single Domestic Example Response

{}

Update Payment Pre-authorisation

Used to continue the authorisation process and for any Institution that contains the INITIATE_PRE_AUTHORISATION feature and direct user to the login screen of their financial institution in order to give consent to initiate a payment.

See Redirect Payment Flows for more information about this flow.

Feature: INITIATE_PRE_AUTHORISATION

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string (User Id)

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string (Corporate User Id)

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string (User IP Address)

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

consent
required
string

Mandatory. The consent-token containing the user's authorisation to make the request.

Example: {consentToken}
Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>
applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.

forwardParameters
Array of strings

Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.

institutionId
required
string

Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.

callback
string

Optional. The URL to redirect the user to after the user complete the authorisation at the Institution.

object (RedirectRequest)

Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

oneTimeToken
boolean

Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.

required
object (PaymentRequest)

Mandatory. The payment request object defining the details of the payment.

Responses
200

Ok

default

Error Response

put/payment-auth-requests
Request samples
application/json;charset=UTF-8

Berlin Group EUR Single Domestic Payment Example Request

{
}
Response samples
application/json;charset=UTF-8

Berlin Group EUR Single Domestic Payment Example Response

{
}

Create Pre-authorisation

Used to initiate the pre-authorisation process for any Institution that contains the INITIATE_PRE_AUTHORISATION feature to authenticate the user.

Feature: INITIATE_PRE_AUTHORISATION

Request
Security:
query Parameters
raw
boolean

Optional. Used to obtain the raw request and response to and from the Institution.

header Parameters
psu-id
string

Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.

psu-corporate-id
string

Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.

psu-ip-address
string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

sub-application
string <uuid>

The sub-application ID to which event type is being subscribed to

Request Body schema: application/json;charset=UTF-8
userUuid
string <uuid>
applicationUserId
string

Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.