Yapily API v1.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

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

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

For a list of changes, see our changelog.

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

Authentication

Requests to the Yapily API are authenticated using an Application's API_KEY and API_SECRET. You can view and manage your credentials in the Yapily Dashboard.

An API_KEY and API_SECRET relate to a single Application and its associated Institutions, configuration and registration information, so it is important to keep these credentials secure. Do not share your API_SECRET in publicly accessible areas such as GitHub, client-side code, etc.

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

All requests should be made via HTTPS.

Application

The Application is the base entity that is used to interact with the API and represents your application software. You may have multiple Applications associated with your account.

Get Application

Request

curl -X GET https://api.yapily.com/me \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /me

Returns the details of the Application that owns the request credentials

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.

Example responses

200 Response

{
  "active": true,
  "authCallbacks": [
    "https://test.example.com/callback"
  ],
  "created": "2020-09-09T10:31:53.968+0000",
  "institutions": [
    {
      "countries": [
        {
          "countryCode2": "GB",
          "displayName": "United Kingdom"
        }
      ],
      "credentialsType": "OAUTH1",
      "environmentType": "SANDBOX",
      "features": [
        "INITIATE_PRE_AUTHORISATION"
      ],
      "fullName": "Yapily Mock Bank",
      "id": "yapily-mock",
      "media": [
        {
          "source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
          "type": "icon"
        }
      ],
      "name": "Yapily Mock"
    }
  ],
  "media": [
    {
      "source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
      "type": "icon"
    }
  ],
  "name": "My App 6238",
  "updated": "2020-09-09T10:31:53.968+0000",
  "uuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a"
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning an `Application`.	Application
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
404	Not Found	The Application Service was unable to retrieve the Application.	ApiResponseError

Response Headers

Status	Header	Type	Format	Description
200	x-yapily-platform	string		The backend that processed the request

Users

A User represents a customer of your application software and is associated with the Application. A User is also refered to as the 'PSU'

Get Users

Request

curl -X GET https://api.yapily.com/users \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /users

Used to retrieve all User objects from an Application.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
filter[applicationUserId]	query	string	Optional. Filter users by a comma separated array of application user Ids.

Example responses

200 Response

[
  {
    "applicationUserId": "bojack@8tees.com",
    "applicationUuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a",
    "institutionConsents": [
      {
        "institutionId": "yapily-mock"
      }
    ],
    "referenceId": "myuserreference",
    "uuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
  }
]

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a list of Users.	Inline
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError

Response Schema

Status Code 200

An array of 'User'

Name	Type	Description
anonymous	[User]	An array of 'User'
» applicationUserId	string	The additional unique identifier that you can specify when creating a new `User` to more easily reference it
» applicationUuid	string	The unique identifier for your application
» institutionConsents	[InstitutionConsent]	The consents associated with this `User` object
»» institutionId	string	The id of the `Institution` for the `Consent`.
» referenceId	string	Deprecated. A non-unique reference for `User`
» uuid	string	The unique identifier that Yapily generates to reference this `User` object

Create User

Request

curl -X POST https://api.yapily.com/users \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /users

Used to create a User associated with the Application. This step is not necessary to make an authorisation request.

Body parameter

{
  "applicationUserId": "bojack@9tees.com",
  "referenceId": "myuserreference"
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
body Mandatory	body	NewApplicationUser	The requestBody containing a `NewApplicationUser` json payload.

Example responses

201 Response

{
  "applicationUserId": "bojack@8tees.com",
  "applicationUuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a",
  "institutionConsents": [
    {
      "institutionId": "yapily-mock"
    }
  ],
  "referenceId": "myuserreference",
  "uuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a User.	User
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
409	Conflict	Returned if the applicationUserId already exists for the `Application` or if the applicationUserId equals the reserved value 'Simulator User'	ApiResponseError

Get User

Request

curl -X GET https://api.yapily.com/users/{userUuid} \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /users/{userUuid}

Used to retrieve a User object from an Application by the unique id of the user.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
userUuid Mandatory	path	string	The ID of the User

Example responses

200 Response

{
  "applicationUserId": "bojack@8tees.com",
  "applicationUuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a",
  "institutionConsents": [
    {
      "institutionId": "yapily-mock"
    }
  ],
  "referenceId": "myuserreference",
  "uuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a User.	User
400	Bad Request	Bad Request. Returned if the userUuid is not a valid UUID.	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
404	Not Found	Not Found. Returned if the userUuid is not found for the `Application`.	ApiResponseError

Delete User

Request

curl -X DELETE https://api.yapily.com/users/{userUuid} \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

DELETE /users/{userUuid}

Delete an application user and sub-resources (including consent resources on institution APIs if they exist)

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
userUuid Mandatory	path	string	The ID of the User
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "creationDate": "2019-05-10T17:36:49.269+0000",
    "deleteStatus": "SUCCESS",
    "id": "c50844cb-1498-44aa-90d1-62eae8cdb3f6",
    "userConsents": [
      {
        "creationDate": "2019-05-10T16:45:43.566+0000",
        "deleteStatus": "SUCCESS",
        "id": "a71fd46f-4144-478e-9a72-dd0d7a1158ab",
        "institutionConsentId": "aac-1cce1cfc-1ab2-4ed6-8062-a0fd6c5c2122",
        "institutionId": "yapily-mock"
      }
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a UserDeleteResponse.	Inline
400	Bad Request	Bad Request. Returned if the userUuid is not a valid UUID or if the optional raw parameter is sent with an invalid value.	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
404	Not Found	Not Found. Returned if the userUuid is not found for the `Application`.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	UserDeleteResponse	An object returned from a successful user delete request
»» creationDate	string	The date the user was created.
»» deleteStatus	DeleteStatusEnum	The result of the delete operation.
»» id	string	The userUuid of the `User`.
»» userConsents	[ConsentDeleteResponse]	[An object returned from a UserDeleteResponse]
»»» creationDate	string	The date the `Consent` was created.
»»» deleteStatus	DeleteStatusEnum	The result of the delete operation.
»»» id	string	The id of the `Consent`.
»»» institutionConsentId	string	The bank's identification for the consent.
»»» institutionId	string	The `Institution` the consent was granted for.

Enumerated Values

Property	Value
deleteStatus	SUCCESS
deleteStatus	FAILED
deleteStatus	SUCCESS
deleteStatus	FAILED

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’ account transaction data available to third party providers via their API end points).

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 Institutions

Request

curl -X GET https://api.yapily.com/institutions \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /institutions

Used to retrieve all Institutions from the Application.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.

Example responses

200 Response

{
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "countries": [
        {
          "countryCode2": "GB",
          "displayName": "United Kingdom"
        }
      ],
      "credentialsType": "OAUTH1",
      "environmentType": "SANDBOX",
      "features": [
        "INITIATE_PRE_AUTHORISATION"
      ],
      "fullName": "Yapily Mock Bank",
      "id": "yapily-mock",
      "media": [
        {
          "source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
          "type": "icon"
        }
      ],
      "name": "Yapily Mock"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a list of Institutions.	Inline
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseListMeta	An object containing a tracingId of the request
»» count	integer	The number of records returned.
»» pagination	Pagination	An object containing pagination information in ResponseListMeta
»»» next	Next	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»» self	FilterAndSort	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset.
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»»» offset	integer	Optional. The offset specified for the request.
»»»» sort	SortEnum	Valid options for the sort parameter
»»» totalCount	integer	Optional. The total count of the paged entities.
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[Institution]	[An object that represents an institution.]
»» countries	[Country]	An array of Country for the Institution.
»»» countryCode2	string	The 2-letter country code for the `Institution`.
»»» displayName	string	The display name of the `Country`.
»» credentialsType	CredentialsType	The type of credentials used.
»» environmentType	EnvironmentType	The environment type.
»» features	[FeatureEnum]	A list of features supported by the `Institution`.
»» fullName	string	The full name of the `Institution`.
»» id	string	The id of the `Institution`.
»» media	[Media]	[An object containing media information such as an icon.]
»»» source	string	The source of the `Media`.
»»» type	string	The type of the `Media`, e.g. icon.
»» name	string	A friendly name of the `Institution`.

Enumerated Values

Property	Value
sort	DATE_ASCENDING("date")
sort	DATE_DESCENDING("-date")
credentialsType	OAUTH1
credentialsType	OAUTH2
credentialsType	OAUTH2_NOSECRET
credentialsType	OAUTH2_SIGNATURE
credentialsType	OPEN_BANKING_UK_MANUAL
credentialsType	OPEN_BANKING_UK_AUTO
credentialsType	OPEN_BANKING_IBM
credentialsType	OPEN_BANKING_AUTO
credentialsType	OPEN_BANKING_AUTO_EMAIL
credentialsType	OPEN_BANKING_MANUAL
credentialsType	API_KEY
credentialsType	OPEN_BANKING_NO_KEY
credentialsType	OPEN_BANKING_NO_TRANSPORT
credentialsType	TOKEN_IO
environmentType	SANDBOX
environmentType	MOCK
environmentType	LIVE

Get Institution

Request

curl -X GET https://api.yapily.com/institutions/{institutionId} \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /institutions/{institutionId}

Used to retrieves details of a specific institution from the Application.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
institutionId Mandatory	path	string	The ID of the Institution

Example responses

200 Response

{
  "countries": [
    {
      "countryCode2": "GB",
      "displayName": "United Kingdom"
    }
  ],
  "credentialsType": "OAUTH1",
  "environmentType": "SANDBOX",
  "features": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "fullName": "Yapily Mock Bank",
  "id": "yapily-mock",
  "media": [
    {
      "source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
      "type": "icon"
    }
  ],
  "name": "Yapily Mock"
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning an Institution.	Institution
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
404	Not Found	Not Found. Returned if the institutionId is not valid or if it is not configured for the `Application`	ApiResponseError

Get Features

Request

curl -X GET https://api.yapily.com/features \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

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.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.

Example responses

200 Response

{
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "documentationUrl": "https://docs.yapily.com/#757fde49-a294-bbff-d5f9-2c21c5f57be0",
      "endpoint": "https://api.yapily.com/account/{account-id}",
      "feature": "INITIATE_PRE_AUTHORISATION"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning an Institution.	Inline
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseListMeta	An object containing a tracingId of the request
»» count	integer	The number of records returned.
»» pagination	Pagination	An object containing pagination information in ResponseListMeta
»»» next	Next	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»» self	FilterAndSort	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset.
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»»» offset	integer	Optional. The offset specified for the request.
»»»» sort	SortEnum	Valid options for the sort parameter
»»» totalCount	integer	Optional. The total count of the paged entities.
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[FeatureDetails]	A list of all `Features`.
»» documentationUrl	string	Optional. A reference for the feature.
»» endpoint	string	Optional. The endpoint that uses the feature.
»» feature	FeatureEnum	Used to describes what functions the account holder has given access to when using that Consent. When creating a Create Account Authorisation Request, you can optionally set which features the user should consent for.

Enumerated Values

Property	Value
sort	DATE_ASCENDING("date")
sort	DATE_DESCENDING("-date")
feature	INITIATE_PRE_AUTHORISATION
feature	INITIATE_ACCOUNT_REQUEST
feature	ACCOUNT_REQUEST_DETAILS
feature	ACCOUNTS
feature	ACCOUNT
feature	ACCOUNT_TRANSACTIONS
feature	ACCOUNT_STATEMENTS
feature	ACCOUNT_STATEMENT
feature	ACCOUNT_STATEMENT_FILE
feature	ACCOUNT_SCHEDULED_PAYMENTS
feature	ACCOUNT_DIRECT_DEBITS
feature	ACCOUNT_PERIODIC_PAYMENTS
feature	ACCOUNT_TRANSACTIONS_WITH_MERCHANT
feature	IDENTITY
feature	ACCOUNTS_WITHOUT_BALANCE
feature	ACCOUNT_WITHOUT_BALANCE
feature	ACCOUNT_BALANCES
feature	INITIATE_SINGLE_PAYMENT_SORTCODE
feature	EXISTING_PAYMENT_INITIATION_DETAILS
feature	CREATE_SINGLE_PAYMENT_SORTCODE
feature	EXISTING_PAYMENTS_DETAILS
feature	INITIATE_DOMESTIC_SINGLE_PAYMENT
feature	CREATE_DOMESTIC_SINGLE_PAYMENT
feature	INITIATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
feature	CREATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
feature	INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT
feature	CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT
feature	INITIATE_DOMESTIC_SCHEDULED_PAYMENT
feature	CREATE_DOMESTIC_SCHEDULED_PAYMENT
feature	INITIATE_DOMESTIC_PERIODIC_PAYMENT
feature	CREATE_DOMESTIC_PERIODIC_PAYMENT
feature	PERIODIC_PAYMENT_FREQUENCY_EXTENDED
feature	INITIATE_INTERNATIONAL_VARIABLE_RECURRING_PAYMENT
feature	CREATE_INTERNATIONAL_VARIABLE_RECURRING_PAYMENT
feature	INITIATE_INTERNATIONAL_SCHEDULED_PAYMENT
feature	CREATE_INTERNATIONAL_SCHEDULED_PAYMENT
feature	INITIATE_INTERNATIONAL_PERIODIC_PAYMENT
feature	CREATE_INTERNATIONAL_PERIODIC_PAYMENT
feature	INITIATE_INTERNATIONAL_SINGLE_PAYMENT
feature	CREATE_INTERNATIONAL_SINGLE_PAYMENT
feature	INITIATE_BULK_PAYMENT
feature	CREATE_BULK_PAYMENT
feature	TRANSFER
feature	OPEN_DATA_PERSONAL_CURRENT_ACCOUNTS
feature	OPEN_DATA_ATMS
feature	READ_DOMESTIC_SINGLE_REFUND
feature	READ_DOMESTIC_SCHEDULED_REFUND
feature	READ_DOMESTIC_PERIODIC_PAYMENT_REFUND
feature	READ_INTERNATIONAL_SINGLE_REFUND
feature	READ_INTERNATIONAL_SCHEDULED_REFUND

Consents

The Consent object contains data that identifies a user's consent for a specific financial 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.

Get Consents

Request

curl -X GET https://api.yapily.com/consents \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /consents

Used to retrieve all Consent objects in descending order by date (with the most recently created consent at the top).

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
filter[applicationUserId]	query	array[string]	Filter consents by your application user Id (applicationUserId)
filter[userUuid]	query	array[string]	Filter consents by Yapily user Id (userUuid)
filter[institution]	query	array[string]	Use this parameter to filter consent by institution, using the Yapily institution Id
filter[status]	query	array[string]	Use this parameter to filter consent by status
from	query	string	Use this parameter to filter consents created after the date specified. Date must be a valid date-time of format yyyy-MM-dd'T'HH:mm:ss.SSSZ e.g. `2007-12-03T10:15:30+01:00`.
before	query	string	Use this parameter to filter consents created before the date specified. Date must be a valid date-time of format yyyy-MM-dd'T'HH:mm:ss.SSSZ e.g. `2007-12-03T10:15:30+01:00`.
limit	query	integer	Use this parameter to limit consent results, max limit is 20
offset	query	integer	Use this parameter to specify the offset of the results
raw	query	boolean	Raw parameter available for debugging purposes

Enumerated Values

Parameter	Value
filter[status]	AWAITING_AUTHORIZATION
filter[status]	AWAITING_FURTHER_AUTHORIZATION
filter[status]	AWAITING_RE_AUTHORIZATION
filter[status]	AWAITING_DECOUPLED_AUTHORIZATION
filter[status]	AUTHORIZED
filter[status]	CONSUMED
filter[status]	REJECTED
filter[status]	REVOKED
filter[status]	FAILED
filter[status]	EXPIRED
filter[status]	UNKNOWN
filter[status]	INVALID
filter[status]	AWAITING_PRE_AUTHORIZATION
filter[status]	PRE_AUTHORIZED

Example responses

200 Response

{
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "applicationUserId": "bojack@8tees.com",
      "authorizedAt": "2020-09-13T15:57:46.450Z",
      "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
      "createdAt": "2020-09-13T15:57:46.450Z",
      "expiresAt": "2020-09-13T15:57:46.450Z",
      "featureScope": [
        "INITIATE_PRE_AUTHORISATION"
      ],
      "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
      "institutionId": "yapily-mock",
      "referenceId": "myuserreference",
      "state": "754f6022f47548b99284f3f1993e050e",
      "status": "AWAITING_AUTHORIZATION",
      "timeToExpire": "PT-375H-40M-21.397S",
      "transactionFrom": "2020-09-13T15:57:46.450Z",
      "transactionTo": "2020-09-13T15:57:46.450Z",
      "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a list of Consents.	Inline
400	Bad Request	Bad Request. Returned if optional parameter filter[status] is sent with an invalid enum value or if the optional raw parameter is not a valid boolean or if the optional filter[userUuid] parameter is not a valid UUID or if the optional offset parameter is not a valid integer or if the optional limit parameter is not a valid integer or if the optional from parameter is not a valid date with format yyyy-MM-dd'T'HH:mm:ss.SSSZ. VERIFY or if the optional before parameter is not a valid date with format yyyy-MM-dd'T'HH:mm:ss.SSSZ. VERIFY	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseListMeta	An object containing a tracingId of the request
»» count	integer	The number of records returned.
»» pagination	Pagination	An object containing pagination information in ResponseListMeta
»»» next	Next	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»» self	FilterAndSort	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset.
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»»» offset	integer	Optional. The offset specified for the request.
»»»» sort	SortEnum	Valid options for the sort parameter
»»» totalCount	integer	Optional. The total count of the paged entities.
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[Consent]	[The `Consent` object.]
»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»» authorizedAt	string	The date the consent was authorized.
»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»» createdAt	string	The date and time the `Consent` object was created.
»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»» id	string	Used to uniquely identify the Consent object within an application.
»» institutionId	string	Used to identify the Institution that holds your user's account
»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»» state	string	The state.
»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

Enumerated Values

Property	Value
sort	DATE_ASCENDING("date")
sort	DATE_DESCENDING("-date")
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Request

curl -X GET https://api.yapily.com/consents/{consentId} \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /consents/{consentId}

Used to retrieve a specific consent by ID.

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consentId Mandatory	path	string	The ID of the consent
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
  }
}

Status	Meaning	Description	Schema
200	OK	A successful response, returning a list of Consents.	Inline
400	Bad Request	Bad Request. Returned if the consentId is not a valid UUID. or if the optional raw parameter is not a valid boolean	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
404	Not Found	Not Found. Returned if the consentId is not found for the `Application`.	ApiResponseError

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	Consent	The `Consent` object.
»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»» authorizedAt	string	The date the consent was authorized.
»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»» createdAt	string	The date and time the `Consent` object was created.
»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»» id	string	Used to uniquely identify the Consent object within an application.
»» institutionId	string	Used to identify the Institution that holds your user's account
»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»» state	string	The state.
»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Request

curl -X DELETE https://api.yapily.com/consents/{consentId} \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

DELETE /consents/{consentId}

Deleting a user consent will also delete the tokens created through user authorisation. For example, in the case of an institution that makes use of OAuth2, the encrypted access token and refresh token will be deleted. To execute further requests requiring consent, you will need to request authorisation again from the user to Create Account Authorisation or Create Payment Authorisation.

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consentId Mandatory	path	string	The ID of the consent
forceDelete	query	boolean	Whether to forceDelete consents. Defaults to true
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "creationDate": "2019-05-10T16:45:43.566+0000",
    "deleteStatus": "SUCCESS",
    "id": "a71fd46f-4144-478e-9a72-dd0d7a1158ab",
    "institutionConsentId": "aac-1cce1cfc-1ab2-4ed6-8062-a0fd6c5c2122",
    "institutionId": "yapily-mock"
  }
}

Status	Meaning	Description	Schema
200	OK	A successful response, returning a ConsentDeleteResponse.	Inline
400	Bad Request	Bad Request. Returned if the consentId is not a valid UUID. or if the optional raw parameter is not a valid boolean or if the optional forceDelete parameter is not a valid boolean	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
404	Not Found	Not Found. Returned if the consentId is not found for the `Application`.	ApiResponseError

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	ConsentDeleteResponse	An object returned from a UserDeleteResponse
»» creationDate	string	The date the `Consent` was created.
»» deleteStatus	DeleteStatusEnum	The result of the delete operation.
»» id	string	The id of the `Consent`.
»» institutionConsentId	string	The bank's identification for the consent.
»» institutionId	string	The `Institution` the consent was granted for.

Enumerated Values

Property	Value
deleteStatus	SUCCESS
deleteStatus	FAILED

Exchange One Time Token

Request

curl -X POST https://api.yapily.com/consent-one-time-token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /consent-one-time-token

Used to retrieve a consentToken in exchange for a oneTimeToken. One time tokens cannot be used again after successfully being exchanged for a consentToken. A one time token is only valid for 3 minutes and in case of it expiring, Get Consents should be used to obtain the consentToken.

Note: to receive a one time token, set oneTimeToken to true in your Create Account Authorisation Request or Create Payment Authorisation Request.

Body parameter

{
  "oneTimeToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6ImJidmEtc2FuZGJveCIsIlVVSUQiOiJmMzNmNGU4ZC1jMDQ0LTQ2YTktOTlkMC0wYmRlMzIyYTJjOTIifQ.4Qv3NJI6av2nKi1U3aNmm71cIwJ3TvRsIlYDafQUVv_Khy_e-8oEpV_BoP4V1CII12oT-Yq4cPveHILz8BOwjg"
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
body Mandatory	body	OneTimeTokenRequest	The requestBody

Example responses

201 Response

{
  "applicationUserId": "bojack@8tees.com",
  "authorizedAt": "2020-09-13T15:57:46.450Z",
  "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
  "createdAt": "2020-09-13T15:57:46.450Z",
  "expiresAt": "2020-09-13T15:57:46.450Z",
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
  "institutionId": "yapily-mock",
  "referenceId": "myuserreference",
  "state": "754f6022f47548b99284f3f1993e050e",
  "status": "AWAITING_AUTHORIZATION",
  "timeToExpire": "PT-375H-40M-21.397S",
  "transactionFrom": "2020-09-13T15:57:46.450Z",
  "transactionTo": "2020-09-13T15:57:46.450Z",
  "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a Consent.	Consent
400	Bad Request	Bad Request. Returned if the oneTimeToken is not present in the requestBody.	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Forbidden. Returned if the `oneTimeToken` has status CLAIMED or EXPIRED.	ApiResponseError
404	Not Found	Not Found. Returned if the `oneTimeToken` is invalid or not found.	ApiResponseError

(Forwarding) Send Access Token

Request

curl -X POST https://api.yapily.com/users/{userUuid}/consents \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /users/{userUuid}/consents

For standard user authorised requests, ignore this endpoint and execute a Create Account Authorisation Request to obtain a Yapily consent token.

This endpoint is particularly for creating a Yapily consent token by sending OAuth2 access token or API key data.

The most common use cases for creating consent tokens with this data:

The financial institution provides API keys to access user data. This applies to any institution with the credentialsType of API_KEY You already have the access token for a user and want to allow Yapily to manage your integration and token refreshing Note the distinction between access tokens, API keys and the Yapily consent token. An OAuth2 access token is a short-lived, refreshable object created by a third party to authorise access to the end user's resources. Similarly, an API key is created by a third party and is valid until either the institution or end user revokes access. The consent token returned by Yapily is a generic, longer-lived token specifically for use with this API that abstracts multiple methods of representing consent and handles the mechanisms for using and refreshing tokens.

Body parameter

{
  "accessToken": "access-token",
  "institutionId": "yapily-mock",
  "refreshToken": "",
  "scope": ""
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
userUuid Mandatory	path	string	The ID of the User
body Mandatory	body	CreateConsentAccessToken	The requestBody

Example responses

201 Response

{
  "applicationUserId": "bojack@8tees.com",
  "authorizedAt": "2020-09-13T15:57:46.450Z",
  "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
  "createdAt": "2020-09-13T15:57:46.450Z",
  "expiresAt": "2020-09-13T15:57:46.450Z",
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
  "institutionId": "yapily-mock",
  "referenceId": "myuserreference",
  "state": "754f6022f47548b99284f3f1993e050e",
  "status": "AWAITING_AUTHORIZATION",
  "timeToExpire": "PT-375H-40M-21.397S",
  "transactionFrom": "2020-09-13T15:57:46.450Z",
  "transactionTo": "2020-09-13T15:57:46.450Z",
  "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a Consent.	Consent
400	Bad Request	Bad Request. Returned if the userUuid is not a valid UUID or if the institutionId is not configured for the `Application` or if accessToken is missing from the requestBody or if institutionId is missing from the requestBody	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
404	Not Found	Not Found. Returned if the userUuid is not found for the `Application` or if the institutionId is not valid.	ApiResponseError

(Forwarding) Send OAuth2 Code

Request

curl -X POST https://api.yapily.com/consent-auth-code \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /consent-auth-code

Submit the OAuth2 authorisation code authCode and state authState received from the institution after the user has authenticated to receive a consent-token.

Body parameter

{
  "authCode": "fg67Hj",
  "authState": "f3daec98152e420297cebdd301db6dde"
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
body Mandatory	body	ConsentAuthCodeRequest	The requestBody

Example responses

201 Response

{
  "applicationUserId": "bojack@8tees.com",
  "authorizedAt": "2020-09-13T15:57:46.450Z",
  "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
  "createdAt": "2020-09-13T15:57:46.450Z",
  "expiresAt": "2020-09-13T15:57:46.450Z",
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
  "institutionId": "yapily-mock",
  "referenceId": "myuserreference",
  "state": "754f6022f47548b99284f3f1993e050e",
  "status": "AWAITING_AUTHORIZATION",
  "timeToExpire": "PT-375H-40M-21.397S",
  "transactionFrom": "2020-09-13T15:57:46.450Z",
  "transactionTo": "2020-09-13T15:57:46.450Z",
  "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a Consent.	Consent
400	Bad Request	Bad Request. Returned if the authCode is not set or is invalid or authState is not set or is invalid.	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
424	Failed Dependency	Failed Dependency.	ApiResponseError

Before calling Financial Data or Payment 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.

Create Account Authorisation

Request

curl -X POST https://api.yapily.com/account-auth-requests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /account-auth-requests

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.

Feature: INITIATE_ACCOUNT_REQUEST

A User can be generated as part of this request, if no userUuid is provided and if the applicationUserId does not already exist.

Body parameter

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "accountRequest": {
    "accountIdentifiers": {
      "accountId": "500000000000000000000001",
      "accountIdentification": {
        "identification": null,
        "type": null
      }
    },
    "accountIdentifiersForBalance": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {}
      }
    ],
    "accountIdentifiersForTransaction": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {}
      }
    ],
    "expiresAt": "2018-10-17T15:11:38Z",
    "featureScope": [
      "ACCOUNT_STATEMENT"
    ],
    "psuCorporateId": "",
    "psuId": "",
    "transactionsFrom": "",
    "transactionsTo": ""
  }
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	AccountAuthorisationRequest	The requestBody

Example responses

201 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
    "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a AuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the requestBody does not contain either the userUuid or applicationUserId. or if the requestBody does not contain the institutionId or the institution does not belong to the `Application`. or if the AccountRequest.expiresAt is in the past. or if the AccountRequest.transactionsFrom is after AccountRequest.transactionsTo or if the callback is set but is an invalid URI or is not configured on the `Application` or if the callback longer than 4096. or if oneTimeToken is set to true without a callback or if the featureScope array includes an invalid `Feature`	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError

Response Schema

Status Code 201

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	any	A response object containing the result of the authorisation.

allOf

Name	Type	Description
»» anonymous	Consent	The `Consent` object.
»»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»»» authorizedAt	string	The date the consent was authorized.
»»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»»» createdAt	string	The date and time the `Consent` object was created.
»»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»»» id	string	Used to uniquely identify the Consent object within an application.
»»» institutionId	string	Used to identify the Institution that holds your user's account
»»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»»» state	string	The state.
»»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

and

Name	Type	Description
»» anonymous	object	none
»»» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
»»» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Re-authorise Account Authorisation

Request

curl -X PATCH https://api.yapily.com/account-auth-requests \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

PATCH /account-auth-requests

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. Only the original features that were specified when the Consent can be re-authorised.

A financial data Consent can be re-authorised at any time as long as it is not in any on of the following terminal states:
- EXPIRED
- REJECTED
- REVOKED

If your financial data Consent is in a terminal state, it can no longer be used and a new Consent needs to be created from a Create Account Authorisation for continued access to the user's data.

When to re-authorise?

For the CMA9, each institution must prompt for Strong Customer Authentication (SCA) every 90 days to remain compliant. This means that the maximum period that any endpoint can be accessed without any interaction with the user is 90 days.

Restrictions enforced by institutions

It is common for institutions to enforce their own restrictions on specific endpoints, drastically reducing the period where no authorisation from the user is required to as little as 5 minutes e.g. identity or historical data older than 90 days. Yapily does not publicly release information on how each Institution behaves as this information is subject to change.

You can usually identify when an endpoint requires re-authorisation by the emergence of FORBIDDEN 403 errors for requests to financial data endpoints that previously returned OK 200. In light of this, Yapily recommends that you design flows which prompt for SCA when requests for financial data returns FORBIDDEN 403 errors.

NOTE: A payment Consent can not be re-authorised because it is single use only. Once the payment request is made, the Consent reaches the terminal state CONSUMED and is no longer usable.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consent Mandatory	header	string	The `consentToken` obtained from the original authorisation.
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
    "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a AuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
404	Not Found	Not Found. The Consent-Token was not valid.	ApiResponseError
406	Not Acceptable	Not Acceptable. The Consent-Token does not support re-authorisation.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	any	A response object containing the result of the authorisation.

allOf

Name	Type	Description
»» anonymous	Consent	The `Consent` object.
»»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»»» authorizedAt	string	The date the consent was authorized.
»»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»»» createdAt	string	The date and time the `Consent` object was created.
»»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»»» id	string	Used to uniquely identify the Consent object within an application.
»»» institutionId	string	Used to identify the Institution that holds your user's account
»»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»»» state	string	The state.
»»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

and

Name	Type	Description
»» anonymous	object	none
»»» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
»»» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Update Account Authorisation

Request

curl -X PUT https://api.yapily.com/account-auth-requests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

PUT /account-auth-requests

Update pre authorize consent for user to authorise account

Body parameter

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "accountRequest": {
    "accountIdentifiers": {
      "accountId": "500000000000000000000001",
      "accountIdentification": {
        "identification": null,
        "type": null
      }
    },
    "accountIdentifiersForBalance": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {}
      }
    ],
    "accountIdentifiersForTransaction": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {}
      }
    ],
    "expiresAt": "2018-10-17T15:11:38Z",
    "featureScope": [
      "ACCOUNT_STATEMENT"
    ],
    "psuCorporateId": "",
    "psuId": "",
    "transactionsFrom": "",
    "transactionsTo": ""
  }
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consent	header	string	The Consent-Token obtained from the original authorisation.
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	AccountAuthorisationRequest	The requestBody

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
    "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a AuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the AccountRequest.expiresAt is in the past. or if the AccountRequest.transactionsFrom is after AccountRequest.transactionsTo	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Forbidden. The status of the original is not PRE_AUTHORIZED. or the scope is not AIS	ApiResponseError
404	Not Found	Not Found. The Consent-Token was not valid.	ApiResponseError
406	Not Acceptable	Not Acceptable. The Consent-Token does not support re-authorisation.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	any	A response object containing the result of the authorisation.

allOf

Name	Type	Description
»» anonymous	Consent	The `Consent` object.
»»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»»» authorizedAt	string	The date the consent was authorized.
»»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»»» createdAt	string	The date and time the `Consent` object was created.
»»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»»» id	string	Used to uniquely identify the Consent object within an application.
»»» institutionId	string	Used to identify the Institution that holds your user's account
»»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»»» state	string	The state.
»»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

and

Name	Type	Description
»» anonymous	object	none
»»» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
»»» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Create Payment Authorisation

Request

curl -X POST https://api.yapily.com/payment-auth-requests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /payment-auth-requests

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 types mentioned above. Based on the type of payment you wish to make, you may be required to provide specific properties in the payload of the request. First make sure that the payment feature you wish to executed is supported by the bank by checking the features array in GET Institution.

NOTE: The PaymentRequest object is particularly important to understand when creating a payment due to the various types of possible payments, such as:
- Domestic and International Single Payments
- Domestic and International Periodic Payment
- Domestic and International Scheduled Payments

Body parameter

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "paymentRequest": {
    "type": "DOMESTIC_PAYMENT",
    "amount": {
      "amount": 10,
      "currency": "GBP"
    },
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "payee": {
      "accountIdentifications": [
        {}
      ],
      "name": "Bojack Horseman",
      "address": {
        "addressLines": null,
        "addressType": null,
        "buildingNumber": null,
        "country": null,
        "county": null,
        "department": null,
        "postCode": null,
        "streetName": null,
        "subDepartment": null,
        "townName": null
      },
      "merchantCategoryCode": "5462",
      "merchantId": "12345678"
    },
    "payer": {
      "accountIdentifications": [
        {}
      ],
      "address": {
        "addressLines": null,
        "addressType": null,
        "buildingNumber": null,
        "country": null,
        "county": null,
        "department": null,
        "postCode": null,
        "streetName": null,
        "subDepartment": null,
        "townName": null
      },
      "name": "Bojack Horseman"
    },
    "reference": "myreference",
    "paymentDateTime": "2019-12-26T14:42:53Z",
    "contextType": "BILL",
    "internationalPayment": {
      "chargeBearer": "DEBT",
      "currencyOfTransfer": "GBP",
      "exchangeRateInformation": "string",
      "priority": "NORMAL",
      "purpose": "277ca9eb968948d4b5f8bfa4b6b6b16f"
    },
    "periodicPayment": {
      "frequency": {
        "type": null,
        "executionDay": null,
        "intervalMonth": null,
        "intervalWeek": null
      },
      "nextPaymentAmount": {
        "amount": null,
        "currency": null
      },
      "nextPaymentDateTime": "2018-01-10T00:00:00Z",
      "finalPaymentAmount": {
        "amount": null,
        "currency": null
      },
      "finalPaymentDateTime": "2021-01-10T00:00:00Z",
      "numberOfPayments": 5
    },
    "readRefundAccount": true,
    "psuCorporateId": "",
    "psuId": ""
  },
  "allowOverdraft": true,
  "startsAt": "2020-08-18T16:24:22.316Z",
  "expiresAt": "2020-08-18T16:24:22.316Z",
  "maxAmountPerRequest": 10,
  "totalMaxAmount": 10,
  "totalMaxAmountFrequency": "DAILY"
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	PaymentAuthorisationRequest	The requestBody

Example responses

201 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
    "charges": [
      {
        "chargeAmount": {},
        "chargeTo": "",
        "chargeType": "BULK_PAYMENT"
      }
    ],
    "exchangeRateInformation": {
      "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
    },
    "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a PaymentAuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the `paymentRequest` is not part of the requestBody or if the `AccountRequest.transactionsFrom` is after `AccountRequest.transactionsTo` or if the `requestBody` does not contain either the `userUuid` or `applicationUserId`. or if the requestBody does not contain the `institutionId` or the institution does not belong to the `Application`. or if the `callback` is set but is an invalid URI or is not configured on the `Application` or if the `callback` longer than 4096. or if `oneTimeToken` is set to true without a callback or if the `featureScope` array includes an invalid `Feature` or if the `PaymentRequest.type` is sent with an invalid `PaymentType` enum value.	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError

Response Schema

Status Code 201

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	any	The response object containing the result of the payment authorisation.

allOf

Name	Type	Description
»» anonymous	Consent	The `Consent` object.
»»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»»» authorizedAt	string	The date the consent was authorized.
»»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»»» createdAt	string	The date and time the `Consent` object was created.
»»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»»» id	string	Used to uniquely identify the Consent object within an application.
»»» institutionId	string	Used to identify the Institution that holds your user's account
»»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»»» state	string	The state.
»»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

and

Name	Type	Description
»» anonymous	object	none
»»» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
»»» charges	[ChargeDetails]	An array of ChargeDetails objects for each charge made in the payment request.
»»»» chargeAmount	Amount	none
»»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»»» chargeTo	string	Not used.
»»»» chargeType	string	The type of charge for the payment.
»»» exchangeRateInformation	ExchangeRateInformationResponse	An object containing exchange rate information.
»»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»»» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Update Payment Authorisation

Request

curl -X PUT https://api.yapily.com/payment-auth-requests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

PUT /payment-auth-requests

Update pre authorize consent for user to authorise payment

Body parameter

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "paymentRequest": {
    "type": "DOMESTIC_PAYMENT",
    "amount": {
      "amount": 10,
      "currency": "GBP"
    },
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "payee": {
      "accountIdentifications": [
        {}
      ],
      "name": "Bojack Horseman",
      "address": {
        "addressLines": null,
        "addressType": null,
        "buildingNumber": null,
        "country": null,
        "county": null,
        "department": null,
        "postCode": null,
        "streetName": null,
        "subDepartment": null,
        "townName": null
      },
      "merchantCategoryCode": "5462",
      "merchantId": "12345678"
    },
    "payer": {
      "accountIdentifications": [
        {}
      ],
      "address": {
        "addressLines": null,
        "addressType": null,
        "buildingNumber": null,
        "country": null,
        "county": null,
        "department": null,
        "postCode": null,
        "streetName": null,
        "subDepartment": null,
        "townName": null
      },
      "name": "Bojack Horseman"
    },
    "reference": "myreference",
    "paymentDateTime": "2019-12-26T14:42:53Z",
    "contextType": "BILL",
    "internationalPayment": {
      "chargeBearer": "DEBT",
      "currencyOfTransfer": "GBP",
      "exchangeRateInformation": "string",
      "priority": "NORMAL",
      "purpose": "277ca9eb968948d4b5f8bfa4b6b6b16f"
    },
    "periodicPayment": {
      "frequency": {
        "type": null,
        "executionDay": null,
        "intervalMonth": null,
        "intervalWeek": null
      },
      "nextPaymentAmount": {
        "amount": null,
        "currency": null
      },
      "nextPaymentDateTime": "2018-01-10T00:00:00Z",
      "finalPaymentAmount": {
        "amount": null,
        "currency": null
      },
      "finalPaymentDateTime": "2021-01-10T00:00:00Z",
      "numberOfPayments": 5
    },
    "readRefundAccount": true,
    "psuCorporateId": "",
    "psuId": ""
  },
  "allowOverdraft": true,
  "startsAt": "2020-08-18T16:24:22.316Z",
  "expiresAt": "2020-08-18T16:24:22.316Z",
  "maxAmountPerRequest": 10,
  "totalMaxAmount": 10,
  "totalMaxAmountFrequency": "DAILY"
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	PaymentAuthorisationRequest	The requestBody

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
    "charges": [
      {
        "chargeAmount": {},
        "chargeTo": "",
        "chargeType": "BULK_PAYMENT"
      }
    ],
    "exchangeRateInformation": {
      "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
    },
    "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a PaymentAuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the requestBody does not contain the institutionId or the institution does not belong to the `Application`. or if the callback is set but is an invalid URI or is not configured on the `Application` or if the callback longer than 4096. or if oneTimeToken is set to true without a callback or if the PaymentRequest.type is sent with an invalid PaymentType enum value.	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Forbidden. The status of the original is not PRE_AUTHORIZED. or the scope is not PIS	ApiResponseError
404	Not Found	Not Found. The Consent-Token was not valid.	ApiResponseError
406	Not Acceptable	Not Acceptable. The Consent-Token does not support re-authorisation.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	any	The response object containing the result of the payment authorisation.

allOf

Name	Type	Description
»» anonymous	Consent	The `Consent` object.
»»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»»» authorizedAt	string	The date the consent was authorized.
»»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»»» createdAt	string	The date and time the `Consent` object was created.
»»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»»» id	string	Used to uniquely identify the Consent object within an application.
»»» institutionId	string	Used to identify the Institution that holds your user's account
»»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»»» state	string	The state.
»»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

and

Name	Type	Description
»» anonymous	object	none
»»» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
»»» charges	[ChargeDetails]	An array of ChargeDetails objects for each charge made in the payment request.
»»»» chargeAmount	Amount	none
»»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»»» chargeTo	string	Not used.
»»»» chargeType	string	The type of charge for the payment.
»»» exchangeRateInformation	ExchangeRateInformationResponse	An object containing exchange rate information.
»»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»»» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Create Embedded Payment Authorisation

Request

curl -X POST https://api.yapily.com/embedded-payment-auth-requests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /embedded-payment-auth-requests

Used to initiate the embedded authorisation process in order to request a user to give their consent for a payment. This endpoint is used to initiate a Domestic Single Payment with an Institution that requires embedded credentials, i.e. when the Institution has the INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT feature.

Check the features array in GET Institution to know when an Institution requires the embedded authorisation.

Body parameter

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "paymentRequest": {
    "type": "DOMESTIC_PAYMENT",
    "amount": {
      "amount": null,
      "currency": null
    },
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "payee": {
      "accountIdentifications": null,
      "name": null,
      "address": null,
      "merchantCategoryCode": null,
      "merchantId": null
    },
    "payer": {
      "accountIdentifications": null,
      "address": null,
      "name": null
    },
    "reference": "myreference",
    "paymentDateTime": "2019-12-26T14:42:53Z",
    "contextType": "BILL",
    "internationalPayment": {
      "chargeBearer": null,
      "currencyOfTransfer": null,
      "exchangeRateInformation": null,
      "priority": null,
      "purpose": null
    },
    "periodicPayment": {
      "frequency": null,
      "nextPaymentAmount": null,
      "nextPaymentDateTime": null,
      "finalPaymentAmount": null,
      "finalPaymentDateTime": null,
      "numberOfPayments": null
    },
    "readRefundAccount": true,
    "psuCorporateId": "",
    "psuId": ""
  },
  "allowOverdraft": true,
  "startsAt": "2020-08-18T16:24:22.316Z",
  "expiresAt": "2020-08-18T16:24:22.316Z",
  "maxAmountPerRequest": 10,
  "totalMaxAmount": 10,
  "totalMaxAmountFrequency": "DAILY",
  "userCredentials": {
    "id": "user123",
    "corporateId": "corp456",
    "password": "Password123"
  },
  "selectedScaMethod": {
    "id": "id123",
    "type": "SMS_OTP"
  },
  "scaCode": "123ABC"
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
psu-id	header	string	Conditional. Represents the user's login ID for the Institution to a personal account.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account.
psu-ip-address	header	string	Conditional. The IP address of the PSU.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	PaymentEmbeddedAuthorisationRequest	The requestBody

Example responses

201 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "["
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
    "charges": [
      {}
    ],
    "exchangeRateInformation": {
      "exchangeRateExpiryDate": null
    },
    "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0",
    "scaMethods": [
      {
        "id": "id123",
        "type": "SMS_OTP"
      }
    ],
    "selectedScaMethod": {
      "id": "id123",
      "type": "SMS_OTP"
    }
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a PaymentEmbeddedAuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the paymentRequest is not part of the requestBody or if the requestBody does not contain either the userUuid or applicationUserId. or if the requestBody does not contain the institutionId or the institution does not belong to the `Application`. or if the requestBody does not contain the userCredentials or if the callback is set but is an invalid URI or is not configured on the `Application` or if the callback longer than 4096. or if oneTimeToken is set to true without a callback or if the featureScope array includes an invalid `Feature` or if the PaymentRequest.type is sent with an invalid PaymentType enum value.	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError

Response Schema

Status Code 201

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	any	The authorisation response for an embedded payment request.

allOf

Name	Type	Description
»» anonymous	any	The response object containing the result of the payment authorisation.

allOf

Name	Type	Description
»»» anonymous	Consent	The `Consent` object.
»»»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»»»» authorizedAt	string	The date the consent was authorized.
»»»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»»»» createdAt	string	The date and time the `Consent` object was created.
»»»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»»»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»»»» id	string	Used to uniquely identify the Consent object within an application.
»»»» institutionId	string	Used to identify the Institution that holds your user's account
»»»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»»»» state	string	The state.
»»»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»»»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»»»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»»»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»»»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

and

Name	Type	Description
»»» anonymous	object	none
»»»» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
»»»» charges	[ChargeDetails]	An array of ChargeDetails objects for each charge made in the payment request.
»»»»» chargeAmount	Amount	none
»»»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»»»» chargeTo	string	Not used.
»»»»» chargeType	string	The type of charge for the payment.
»»»» exchangeRateInformation	ExchangeRateInformationResponse	An object containing exchange rate information.
»»»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»»»» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

and

Name	Type	Description
»» anonymous	object	none
»»» scaMethods	[ScaMethod]	A list of supported ScaMethods
»»»» id	string	The id of the SCA Method.
»»»» type	string	The type of the SCA Method.
»»» selectedScaMethod	ScaMethod	Describes the method for second-factor authentication, for embedded payments

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Update Embedded Payment Authorisation

Request

curl -X PUT https://api.yapily.com/embedded-payment-auth-requests/{consentId} \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

PUT /embedded-payment-auth-requests/{consentId}

Used to update a Consent that has been created through executing Create Embedded Payment Authorisation. Where the Institution provides a single method for the user to complete SCA, this must be executed once before the consentToken is issued. Otherwise, if the Institution provides multiple methods for the user to complete SCA, this must be executed twice.

Once the consentToken is issued, the payment can be executed using Create Payment.

Body parameter

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "paymentRequest": {
    "type": "DOMESTIC_PAYMENT",
    "amount": {
      "amount": null,
      "currency": null
    },
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "payee": {
      "accountIdentifications": null,
      "name": null,
      "address": null,
      "merchantCategoryCode": null,
      "merchantId": null
    },
    "payer": {
      "accountIdentifications": null,
      "address": null,
      "name": null
    },
    "reference": "myreference",
    "paymentDateTime": "2019-12-26T14:42:53Z",
    "contextType": "BILL",
    "internationalPayment": {
      "chargeBearer": null,
      "currencyOfTransfer": null,
      "exchangeRateInformation": null,
      "priority": null,
      "purpose": null
    },
    "periodicPayment": {
      "frequency": null,
      "nextPaymentAmount": null,
      "nextPaymentDateTime": null,
      "finalPaymentAmount": null,
      "finalPaymentDateTime": null,
      "numberOfPayments": null
    },
    "readRefundAccount": true,
    "psuCorporateId": "",
    "psuId": ""
  },
  "allowOverdraft": true,
  "startsAt": "2020-08-18T16:24:22.316Z",
  "expiresAt": "2020-08-18T16:24:22.316Z",
  "maxAmountPerRequest": 10,
  "totalMaxAmount": 10,
  "totalMaxAmountFrequency": "DAILY",
  "userCredentials": {
    "id": "user123",
    "corporateId": "corp456",
    "password": "Password123"
  },
  "selectedScaMethod": {
    "id": "id123",
    "type": "SMS_OTP"
  },
  "scaCode": "123ABC"
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consentId Mandatory	path	string	The ID of the Consent
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	PaymentEmbeddedAuthorisationRequest	The requestBody

Example responses

202 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "["
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
    "charges": [
      {}
    ],
    "exchangeRateInformation": {
      "exchangeRateExpiryDate": null
    },
    "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0",
    "scaMethods": [
      {
        "id": "id123",
        "type": "SMS_OTP"
      }
    ],
    "selectedScaMethod": {
      "id": "id123",
      "type": "SMS_OTP"
    }
  }
}

Responses

Status	Meaning	Description	Schema
202	Accepted	A successful response, returning a PaymentEmbeddedAuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the paymentRequest is not part of the requestBody or if the requestBody does not contain either the userUuid or applicationUserId. or if the requestBody does not contain the institutionId or the institution does not belong to the `Application`. or it the status of the original is neither AWAITING_SCA_METHOD nor AWAITING_SCA_CODE or if the requestBody does not contain the selectedScaMethod if the status is AWAITING_SCA_METHOD or if the requestBody does not contain the scaCode if the status is AWAITING_SCA_CODE or if the callback is set but is an invalid URI or is not configured on the `Application` or if the callback longer than 4096. or if oneTimeToken is set to true without a callback or if the featureScope array includes an invalid `Feature` or if the PaymentRequest.type is sent with an invalid PaymentType enum value.	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Forbidden. The status of the original is already AUTHORIZED.	ApiResponseError

Response Schema

Status Code 202

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	any	The authorisation response for an embedded payment request.

allOf

Name	Type	Description
»» anonymous	any	The response object containing the result of the payment authorisation.

allOf

Name	Type	Description
»»» anonymous	Consent	The `Consent` object.
»»»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»»»» authorizedAt	string	The date the consent was authorized.
»»»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»»»» createdAt	string	The date and time the `Consent` object was created.
»»»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»»»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»»»» id	string	Used to uniquely identify the Consent object within an application.
»»»» institutionId	string	Used to identify the Institution that holds your user's account
»»»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»»»» state	string	The state.
»»»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»»»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»»»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»»»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»»»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

and

Name	Type	Description
»»» anonymous	object	none
»»»» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
»»»» charges	[ChargeDetails]	An array of ChargeDetails objects for each charge made in the payment request.
»»»»» chargeAmount	Amount	none
»»»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»»»» chargeTo	string	Not used.
»»»»» chargeType	string	The type of charge for the payment.
»»»» exchangeRateInformation	ExchangeRateInformationResponse	An object containing exchange rate information.
»»»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»»»» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

and

Name	Type	Description
»» anonymous	object	none
»»» scaMethods	[ScaMethod]	A list of supported ScaMethods
»»»» id	string	The id of the SCA Method.
»»»» type	string	The type of the SCA Method.
»»» selectedScaMethod	ScaMethod	Describes the method for second-factor authentication, for embedded payments

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Create Pre-authorisation

Request

curl -X POST https://api.yapily.com/pre-auth-requests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /pre-auth-requests

Initiate request for user to pre authorise for AIS or PIS

Body parameter

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "scope": "AIS"
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	PreAuthorisationRequest	The requestBody

Example responses

201 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
    "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a AuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the callback is set but is an invalid URI or is not configured on the `Application` or if the callback longer than 4096. or if oneTimeToken is set to true without a callback or if the requestBody does not contain the institutionId or the institution does not belong to the `Application`. or if the scope is not either AIS or PIS or if the scope is AIS and the institution does not support AIS or if the scope is PIS and the institution does not support PIS or if the institution does not support pre-authorisation `Feature`	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError

Response Schema

Status Code 201

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	any	A response object containing the result of the authorisation.

allOf

Name	Type	Description
»» anonymous	Consent	The `Consent` object.
»»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»»» authorizedAt	string	The date the consent was authorized.
»»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»»» createdAt	string	The date and time the `Consent` object was created.
»»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»»» id	string	Used to uniquely identify the Consent object within an application.
»»» institutionId	string	Used to identify the Institution that holds your user's account
»»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»»» state	string	The state.
»»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

and

Name	Type	Description
»» anonymous	object	none
»»» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
»»» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Create Bulk Payment Authorisation

Request

curl -X POST https://api.yapily.com/bulk-payment-auth-requests \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /bulk-payment-auth-requests

Used to initiate the bulk payment authorisation process in order to request a user to give their consent for a bulk payment. This endpoint is used to initiate a bulk payment: A group of payments (e.g. in a file) to be paid to multiple creditor accounts from the same debtor account, on the same date, with the same currency and through the same payment scheme. This can be used with any Institution that contains the INITIATE_BULK_PAYMENT feature. You can use GET Institution and check the features array to see if this feature is supported.

Body parameter

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "paymentRequest": {
    "executionDateTime": "2020-10-17T00:00:00Z",
    "originatorIdentificationNumber": "",
    "payments": [
      {
        "type": "[",
        "amount": {},
        "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
        "payee": {},
        "payer": {},
        "reference": "myreference",
        "paymentDateTime": "2019-12-26T14:42:53Z",
        "contextType": "[",
        "internationalPayment": {},
        "periodicPayment": {},
        "readRefundAccount": true,
        "psuCorporateId": "",
        "psuId": ""
      }
    ]
  }
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	BulkPaymentAuthorisationRequest	The requestBody

Example responses

201 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "applicationUserId": "bojack@8tees.com",
    "authorizedAt": "2020-09-13T15:57:46.450Z",
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "expiresAt": "2020-09-13T15:57:46.450Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "institutionId": "yapily-mock",
    "referenceId": "myuserreference",
    "state": "754f6022f47548b99284f3f1993e050e",
    "status": "AWAITING_AUTHORIZATION",
    "timeToExpire": "PT-375H-40M-21.397S",
    "transactionFrom": "2020-09-13T15:57:46.450Z",
    "transactionTo": "2020-09-13T15:57:46.450Z",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
    "charges": [
      {
        "chargeAmount": {},
        "chargeTo": "",
        "chargeType": "BULK_PAYMENT"
      }
    ],
    "exchangeRateInformation": {
      "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
    },
    "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a PaymentAuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the paymentRequest is not part of the requestBody or if the AccountRequest.transactionsFrom is after AccountRequest.transactionsTo or if the requestBody does not contain either the userUuid or applicationUserId. or if the requestBody does not contain the institutionId or the institution does not belong to the `Application`. or if the callback is set but is an invalid URI or is not configured on the `Application` or if the callback longer than 4096. or if oneTimeToken is set to true without a callback or if any of the PaymentRequests.type are sent with an invalid PaymentType enum value.	None
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError

Response Schema

Status Code 201

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	any	The response object containing the result of the payment authorisation.

allOf

Name	Type	Description
»» anonymous	Consent	The `Consent` object.
»»» applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
»»» authorizedAt	string	The date the consent was authorized.
»»» consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
»»» createdAt	string	The date and time the `Consent` object was created.
»»» expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
»»» featureScope	[FeatureEnum]	An array of Features in scope for the consent.
»»» id	string	Used to uniquely identify the Consent object within an application.
»»» institutionId	string	Used to identify the Institution that holds your user's account
»»» referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
»»» state	string	The state.
»»» status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
»»» timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
»»» transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
»»» transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
»»» userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

and

Name	Type	Description
»» anonymous	object	none
»»» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
»»» charges	[ChargeDetails]	An array of ChargeDetails objects for each charge made in the payment request.
»»»» chargeAmount	Amount	none
»»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»»» chargeTo	string	Not used.
»»»» chargeType	string	The type of charge for the payment.
»»» exchangeRateInformation	ExchangeRateInformationResponse	An object containing exchange rate information.
»»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»»» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

Enumerated Values

Property	Value
status	AWAITING_AUTHORIZATION
status	AWAITING_FURTHER_AUTHORIZATION
status	AWAITING_RE_AUTHORIZATION
status	AWAITING_DECOUPLED_AUTHORIZATION
status	AUTHORIZED
status	CONSUMED
status	REJECTED
status	REVOKED
status	FAILED
status	EXPIRED
status	UNKNOWN
status	INVALID
status	AWAITING_PRE_AUTHORIZATION
status	PRE_AUTHORIZED

Financial Data

In order to access your user's financial data, you are required to obtain their consent to share this information. Once a Consent token is obtained, you can call the Financial Data endpoints to retrieve various financial data for your user.

Get Accounts

Request

curl -X GET https://api.yapily.com/accounts \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts

Returns all accounts and balances for the end user associated with the presented consent token.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "accountBalances": [
        {
          "balanceAmount": {
            "amount": null,
            "currency": null
          },
          "creditLineIncluded": true,
          "creditLines": [
            {}
          ],
          "dateTime": "2020-09-21T16:35:55Z",
          "type": "CLOSING_AVAILABLE"
        }
      ],
      "accountIdentifications": [
        {
          "identification": "123456",
          "type": "SORT_CODE"
        }
      ],
      "accountNames": [
        {
          "name": "name"
        }
      ],
      "accountType": "CASH_TRADING",
      "balance": 5313.4,
      "currency": "GBP",
      "description": "HSBC ADVANCE",
      "details": "",
      "id": "aadn1pyst5ka1o1x8gkklori09n60rtgcr5t",
      "nickname": "Personal",
      "type": "Personal - Current",
      "usageType": "PERSONAL"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a AuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseListMeta	An object containing a tracingId of the request
»» count	integer	The number of records returned.
»» pagination	Pagination	An object containing pagination information in ResponseListMeta
»»» next	Next	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»» self	FilterAndSort	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset.
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»»» offset	integer	Optional. The offset specified for the request.
»»»» sort	SortEnum	Valid options for the sort parameter
»»» totalCount	integer	Optional. The total count of the paged entities.
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[Account]	An array of Accounts for the User.
»» accountBalances	[AccountBalance]	An array of AccountBalance objects.
»»» balanceAmount	Amount	none
»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»» creditLineIncluded	boolean	Indicates whether or not the credit line is included in the balance.
»»» creditLines	[CreditLine]	An array of CreditLine objects.
»»»» creditLineAmount	Amount	none
»»»» type	CreditLineType	The type of credit line.
»»» dateTime	string	The timestamp of the last change of the balance amount.
»»» type	AccountBalanceType	The OBBalanceType1Code balance type. CLOSING_AVAILABLE - Closing balance of amount of money that is at the disposal of the account owner on the date specified CLOSING_BOOKED - Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. CLOSING_CLEARED - Closing balance of amount of money that is cleared on the date specified. EXPECTED - Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. FORWARD_AVAILABLE - Forward available balance of money that is at the disposal of the account owner on the date specified. INFORMATION - Balance for informational purposes. INTERIM_AVAILABLE - Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_BOOKED - Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_CLEARED - Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. OPENING_AVAILABLE - Opening balance of amount of money that is at the disposal of the account owner on the date specified. OPENING_BOOKED - Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. OPENING_CLEARED - Opening balance of amount of money that is cleared on the date specified. PREVIOUSLY_CLOSED_BOOKED - Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date. AUTHORISED - Balance of the account minus any authorised transactions not yet cleared. OTHER - Used when an unrecognised enum is parsed UNKNOWN - Used as a Yapily default
»» accountIdentifications	[AccountIdentification]	An array of AccountIdentification objects.
»»» identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
»»» type Mandatory	AccountIdentificationType	See Account Identifications Types for more information on each type
»» accountNames	[AccountName]	The array of AccountName objects.
»»» name	string	One of the names for the account.
»» accountType	AccountType	The type of account.
»» balance	integer(decimal)	The balance of the account.
»» currency	string	The ISO 4217 Currency code.
»» description	string	The product name as defined by the financial institution for this account.
»» details	string	The specifications that might be provided by the institution e.g. characteristics of the account or characteristics of the relevant card
»» id	string	The account Id returned by the Institution if present. This is simply a direct mapping to the unique ID provided by the bank for all of the accounts a user has provided access to via a consent, and is then required as a parameter the bank will recognise for all subsequent requests required to pull data related to that specific account (e.g balances, transactions, statements, etc.)
»» nickname	string	The name of the account as defined by the financial institution or the end user.
»» type	string	The type of the Account.
»» usageType	UsageType	The usage type for the account.

Enumerated Values

Property	Value
sort	DATE_ASCENDING("date")
sort	DATE_DESCENDING("-date")
type	AVAILABLE
type	CREDIT
type	EMERGENCY
type	PRE_AGREED
type	TEMPORARY
type	OTHER
type	UNKNOWN
type	CLOSING_AVAILABLE
type	CLOSING_BOOKED
type	CLOSING_CLEARED
type	EXPECTED
type	FORWARD_AVAILABLE
type	INFORMATION
type	INTERIM_AVAILABLE
type	INTERIM_BOOKED
type	INTERIM_CLEARED
type	OPENING_AVAILABLE
type	OPENING_BOOKED
type	OPENING_CLEARED
type	PREVIOUSLY_CLOSED_BOOKED
type	AUTHORISED
type	OTHER
type	UNKNOWN
type	SORT_CODE
type	ACCOUNT_NUMBER
type	IBAN
type	BBAN
type	BIC
type	PAN
type	MASKED_PAN
type	MSISDN
type	BSB
type	NCC
type	ABA
type	ABA_WIRE
type	ABA_ACH
type	EMAIL
accountType	CASH_TRADING
accountType	CASH_INCOME
accountType	CASH_PAYMENT
accountType	CHARGE_CARD
accountType	CHARGES
accountType	COMMISSION
accountType	CREDIT_CARD
accountType	CURRENT
accountType	E_MONEY
accountType	LIMITED_LIQUIDITY_SAVINGS_ACCOUNT
accountType	LOAN
accountType	MARGINAL_LENDING
accountType	MONEY_MARKET
accountType	MORTGAGE
accountType	NON_RESIDENT_EXTERNAL
accountType	OTHER
accountType	OVERDRAFT
accountType	OVERNIGHT_DEPOSIT
accountType	PREPAID_CARD
accountType	SALARY
accountType	SAVINGS
accountType	SETTLEMENT
accountType	TAX
accountType	UNKNOWN
usageType	PERSONAL
usageType	BUSINESS
usageType	OTHER
usageType	UNKNOWN

Get Account

Request

curl -X GET https://api.yapily.com/accounts/{account-id} \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts/{account-id}

Returns the account and balance details of a specific account belonging to the end user associated with the presented consent token.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
account-id Mandatory	path	string	The ID of the Account
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "accountBalances": [
      {
        "balanceAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "creditLineIncluded": true,
        "creditLines": [
          {
            "creditLineAmount": null,
            "type": null
          }
        ],
        "dateTime": "2020-09-21T16:35:55Z",
        "type": "CLOSING_AVAILABLE"
      }
    ],
    "accountIdentifications": [
      {
        "identification": "123456",
        "type": "SORT_CODE"
      }
    ],
    "accountNames": [
      {
        "name": "name"
      }
    ],
    "accountType": "CASH_TRADING",
    "balance": 5313.4,
    "currency": "GBP",
    "description": "HSBC ADVANCE",
    "details": "",
    "id": "aadn1pyst5ka1o1x8gkklori09n60rtgcr5t",
    "nickname": "Personal",
    "type": "Personal - Current",
    "usageType": "PERSONAL"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a AuthorisationRequestResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	Account	none
»» accountBalances	[AccountBalance]	An array of AccountBalance objects.
»»» balanceAmount	Amount	none
»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»» creditLineIncluded	boolean	Indicates whether or not the credit line is included in the balance.
»»» creditLines	[CreditLine]	An array of CreditLine objects.
»»»» creditLineAmount	Amount	none
»»»» type	CreditLineType	The type of credit line.
»»» dateTime	string	The timestamp of the last change of the balance amount.
»»» type	AccountBalanceType	The OBBalanceType1Code balance type. CLOSING_AVAILABLE - Closing balance of amount of money that is at the disposal of the account owner on the date specified CLOSING_BOOKED - Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. CLOSING_CLEARED - Closing balance of amount of money that is cleared on the date specified. EXPECTED - Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. FORWARD_AVAILABLE - Forward available balance of money that is at the disposal of the account owner on the date specified. INFORMATION - Balance for informational purposes. INTERIM_AVAILABLE - Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_BOOKED - Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_CLEARED - Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. OPENING_AVAILABLE - Opening balance of amount of money that is at the disposal of the account owner on the date specified. OPENING_BOOKED - Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. OPENING_CLEARED - Opening balance of amount of money that is cleared on the date specified. PREVIOUSLY_CLOSED_BOOKED - Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date. AUTHORISED - Balance of the account minus any authorised transactions not yet cleared. OTHER - Used when an unrecognised enum is parsed UNKNOWN - Used as a Yapily default
»» accountIdentifications	[AccountIdentification]	An array of AccountIdentification objects.
»»» identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
»»» type Mandatory	AccountIdentificationType	See Account Identifications Types for more information on each type
»» accountNames	[AccountName]	The array of AccountName objects.
»»» name	string	One of the names for the account.
»» accountType	AccountType	The type of account.
»» balance	integer(decimal)	The balance of the account.
»» currency	string	The ISO 4217 Currency code.
»» description	string	The product name as defined by the financial institution for this account.
»» details	string	The specifications that might be provided by the institution e.g. characteristics of the account or characteristics of the relevant card
»» id	string	The account Id returned by the Institution if present. This is simply a direct mapping to the unique ID provided by the bank for all of the accounts a user has provided access to via a consent, and is then required as a parameter the bank will recognise for all subsequent requests required to pull data related to that specific account (e.g balances, transactions, statements, etc.)
»» nickname	string	The name of the account as defined by the financial institution or the end user.
»» type	string	The type of the Account.
»» usageType	UsageType	The usage type for the account.

Enumerated Values

Property	Value
type	AVAILABLE
type	CREDIT
type	EMERGENCY
type	PRE_AGREED
type	TEMPORARY
type	OTHER
type	UNKNOWN
type	CLOSING_AVAILABLE
type	CLOSING_BOOKED
type	CLOSING_CLEARED
type	EXPECTED
type	FORWARD_AVAILABLE
type	INFORMATION
type	INTERIM_AVAILABLE
type	INTERIM_BOOKED
type	INTERIM_CLEARED
type	OPENING_AVAILABLE
type	OPENING_BOOKED
type	OPENING_CLEARED
type	PREVIOUSLY_CLOSED_BOOKED
type	AUTHORISED
type	OTHER
type	UNKNOWN
type	SORT_CODE
type	ACCOUNT_NUMBER
type	IBAN
type	BBAN
type	BIC
type	PAN
type	MASKED_PAN
type	MSISDN
type	BSB
type	NCC
type	ABA
type	ABA_WIRE
type	ABA_ACH
type	EMAIL
accountType	CASH_TRADING
accountType	CASH_INCOME
accountType	CASH_PAYMENT
accountType	CHARGE_CARD
accountType	CHARGES
accountType	COMMISSION
accountType	CREDIT_CARD
accountType	CURRENT
accountType	E_MONEY
accountType	LIMITED_LIQUIDITY_SAVINGS_ACCOUNT
accountType	LOAN
accountType	MARGINAL_LENDING
accountType	MONEY_MARKET
accountType	MORTGAGE
accountType	NON_RESIDENT_EXTERNAL
accountType	OTHER
accountType	OVERDRAFT
accountType	OVERNIGHT_DEPOSIT
accountType	PREPAID_CARD
accountType	SALARY
accountType	SAVINGS
accountType	SETTLEMENT
accountType	TAX
accountType	UNKNOWN
usageType	PERSONAL
usageType	BUSINESS
usageType	OTHER
usageType	UNKNOWN

Get Account Direct Debits

Request

curl -X GET https://api.yapily.com/accounts/{account-id}/direct-debits \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'limit: 0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts/{account-id}/direct-debits

Get the list of direct debits for an account.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
account-id Mandatory	path	string	The ID of the Account
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
limit	header	integer	Use this parameter to limit account's direct debit results
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "amount": "10.00",
      "amountDetails": {
        "amount": 10,
        "currency": "GBP"
      },
      "bulkAmountSum": 100,
      "chargeDetails": [
        {
          "chargeAmount": {
            "amount": null,
            "currency": null
          },
          "chargeTo": "",
          "chargeType": "BULK_PAYMENT"
        }
      ],
      "createdAt": "2019-09-26T15:38:33.401Z",
      "currency": "GBP",
      "currencyOfTransfer": "",
      "exchangeRate": {
        "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
      },
      "finalPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "finalPaymentDateTime": "2019-09-26T15:38:33.401Z",
      "firstPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "firstPaymentDateTime": "2019-09-26T15:38:33.401Z",
      "frequency": {
        "type": "DAILY",
        "executionDay": 1,
        "intervalMonth": 1,
        "intervalWeek": 1
      },
      "id": "pv3-c8eece27-eb1a-4c27-a13c-2f805703dab2",
      "institutionConsentId": "sdp-1-aa9d0941-43ff-4abb-8129-4d56b620b8ee",
      "nextPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "nextPaymentDateTime": "2019-09-26T15:38:33.401Z",
      "numberOfPayments": 10,
      "payeeDetails": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "name": "Bojack Horseman",
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "merchantCategoryCode": "5462",
        "merchantId": "12345678"
      },
      "payer": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "name": "Bojack Horseman"
      },
      "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
      "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d1",
      "previousPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "previousPaymentDateTime": "",
      "priority": "",
      "purpose": "",
      "reference": "myreference",
      "scheduledPaymentDateTime": "",
      "scheduledPaymentType": "",
      "status": "PENDING",
      "statusDetails": {
        "status": "PENDING",
        "statusReason": "PENDING",
        "statusReasonDescription": "",
        "statusUpdateDate": "2019-09-26T15:38:33.401Z",
        "multiAuthorisationStatus": {
          "status": "AWAITING_FURTHER_AUTHORIZATION",
          "numberOfAuthorisationRequired": 2,
          "numberOfAuthorisationReceived": 1,
          "lastUpdatedDateTime": "2019-09-26T15:38:33.408Z",
          "expirationDateTime": "2019-09-26T14:20:14.393Z"
        }
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a PaymentResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseListMeta	An object containing a tracingId of the request
»» count	integer	The number of records returned.
»» pagination	Pagination	An object containing pagination information in ResponseListMeta
»»» next	Next	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»» self	FilterAndSort	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset.
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»»» offset	integer	Optional. The offset specified for the request.
»»»» sort	SortEnum	Valid options for the sort parameter
»»» totalCount	integer	Optional. The total count of the paged entities.
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[PaymentResponse]	An array of PaymentResponses
»» amount	integer(decimal)	Deprecated. The amount of the Payment.
»» amountDetails	Amount	none
»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»» bulkAmountSum	integer(decimal)	The sum of all bulk payments
»» chargeDetails	[ChargeDetails]	The array of ChargeDetails, used to provide any additional fee if there is any of the payment. Mostly populated for International Payments.
»»» chargeAmount	Amount	none
»»» chargeTo	string	Not used.
»»» chargeType	string	The type of charge for the payment.
»» createdAt	string	The date and time the Payment was created.
»» currency	string	Deprecated. The currency of the Payment.
»» currencyOfTransfer	string	Used for International Payments. The currency used to transfer the money from source bank.
»» exchangeRate	ExchangeRateInformationResponse	An object containing exchange rate information.
»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»» finalPaymentAmount	Amount	none
»» finalPaymentDateTime	string	The date of the final payment in a sequence.
»» firstPaymentAmount	Amount	none
»» firstPaymentDateTime	string	The date of the first payment in a sequence.
»» frequency	FrequencyRequest	none
»»» type Mandatory	FrequencyEnumExtended	See payment frequency for more information.
»»» executionDay	integer	Conditional. See payment frequency for more information.
»»» intervalMonth	integer	Conditional. See payment frequency for more information.
»»» intervalWeek	integer	Conditional. See payment frequency for more information.
»» id	string	The id of the Payment.
»» institutionConsentId	string	The banks identification for the consent.
»» nextPaymentAmount	Amount	none
»» nextPaymentDateTime	string	The date of the next payment in a sequence.
»» numberOfPayments	integer	The number of payments in a sequence.
»» payeeDetails	Payee	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payee` bank account
»»»» identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
»»»» type Mandatory	AccountIdentificationType	See Account Identifications Types for more information on each type
»»» name Mandatory	string	The account holder name of the beneficiary
»»» address	Address	none
»»»» addressLines	[string]	The address lines for the address Mandatory for `INTERNATIONAL` payment types
»»»» addressType	AddressTypeEnum	The type of the Address.
»»»» buildingNumber	string	The building number for the address
»»»» country	string	The 2-letter country code for the address Mandatory for `INTERNATIONAL` payment types Some banks in the UK require this to be specified for `DOMESTIC` payment types. In this case, `country` should be set to "GB"
»»»» county	[string]	The county name for the address
»»»» department	string	The department name for the address
»»»» postCode	string	The post code for the address
»»»» streetName	string	The street name for the address Mandatory for `INTERNATIONAL` payment types
»»»» subDepartment	string	The sub department name for the address
»»»» townName	string	The town name for the address Mandatory for `INTERNATIONAL` payment types
»»» merchantCategoryCode	string	The category code of the merchant in case the `Payee` is a business
»»» merchantId	string	A merchant ID is a unique code provided by the payment processor to the merchant
»» payer	Payer	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payer` bank account
»»» address	Address	none
»»» name	string	The account holder name of the Payer
»» paymentIdempotencyId	string	The Payment IdempotencyId
»» paymentLifecycleId	string	The Payment LifecycleId
»» previousPaymentAmount	Amount	none
»» previousPaymentDateTime	string	The date of the previous payment in a sequence.
»» priority	string	The priority for the Payment.
»» purpose	string	The purpose for the Payment.
»» reference	string	A reference for the Payment.
»» scheduledPaymentDateTime	string	The scheduled payment date and time.
»» scheduledPaymentType	string	The type of scheduled payment.
»» status	PaymentStatus	The status of the Payment.
»» statusDetails	PaymentStatusDetails	none
»»» status	PaymentStatus	The status of the Payment.
»»» statusReason	string	The status reason.
»»» statusReasonDescription	string	The description of the status reason.
»»» statusUpdateDate	string	The date and time the status was updated.
»»» multiAuthorisationStatus	MultiAuthorisation	none
»»»» status	string	The status of the multi authorisation. Possible values are AUTHORIZED, AWAITING_FURTHER_AUTHORIZATION, REJECTED and UNKNOWN.
»»»» numberOfAuthorisationRequired	integer	The number of authorisations required to authorise the consent.
»»»» numberOfAuthorisationReceived	integer	The number of authorisations that have been completed.
»»»» lastUpdatedDateTime	string	The time at which the multi authorisation was last updated.
»»»» expirationDateTime	string	The time at which the multi authorisation expires if there is one.

Enumerated Values

Property	Value
sort	DATE_ASCENDING("date")
sort	DATE_DESCENDING("-date")
type	DAILY
type	EVERY_WORKING_DAY
type	CALENDAR_DAY
type	WEEKLY
type	EVERY_TWO_WEEKS
type	MONTHLY
type	EVERY_TWO_MONTHS
type	QUARTERLY
type	SEMIANNUAL
type	ANNUAL
type	SORT_CODE
type	ACCOUNT_NUMBER
type	IBAN
type	BBAN
type	BIC
type	PAN
type	MASKED_PAN
type	MSISDN
type	BSB
type	NCC
type	ABA
type	ABA_WIRE
type	ABA_ACH
type	EMAIL
addressType	BUSINESS
addressType	CORRESPONDENCE
addressType	DELIVERY_TO
addressType	MAIL_TO
addressType	PO_BOX
addressType	POSTAL
addressType	RESIDENTIAL
addressType	STATEMENT
addressType	UNKNOWN
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE

Get Account Periodic Payments

Request

curl -X GET https://api.yapily.com/accounts/{account-id}/periodic-payments \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'limit: 0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts/{account-id}/periodic-payments

Returns a list of periodic payments (standing orders in the UK) for a specific account.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
account-id Mandatory	path	string	The ID of the Account
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
limit	header	integer	Use this parameter to limit account's periodic payment order results
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "amount": "10.00",
      "amountDetails": {
        "amount": 10,
        "currency": "GBP"
      },
      "bulkAmountSum": 100,
      "chargeDetails": [
        {
          "chargeAmount": {
            "amount": null,
            "currency": null
          },
          "chargeTo": "",
          "chargeType": "BULK_PAYMENT"
        }
      ],
      "createdAt": "2019-09-26T15:38:33.401Z",
      "currency": "GBP",
      "currencyOfTransfer": "",
      "exchangeRate": {
        "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
      },
      "finalPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "finalPaymentDateTime": "2019-09-26T15:38:33.401Z",
      "firstPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "firstPaymentDateTime": "2019-09-26T15:38:33.401Z",
      "frequency": {
        "type": "DAILY",
        "executionDay": 1,
        "intervalMonth": 1,
        "intervalWeek": 1
      },
      "id": "pv3-c8eece27-eb1a-4c27-a13c-2f805703dab2",
      "institutionConsentId": "sdp-1-aa9d0941-43ff-4abb-8129-4d56b620b8ee",
      "nextPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "nextPaymentDateTime": "2019-09-26T15:38:33.401Z",
      "numberOfPayments": 10,
      "payeeDetails": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "name": "Bojack Horseman",
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "merchantCategoryCode": "5462",
        "merchantId": "12345678"
      },
      "payer": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "name": "Bojack Horseman"
      },
      "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
      "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d1",
      "previousPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "previousPaymentDateTime": "",
      "priority": "",
      "purpose": "",
      "reference": "myreference",
      "scheduledPaymentDateTime": "",
      "scheduledPaymentType": "",
      "status": "PENDING",
      "statusDetails": {
        "status": "PENDING",
        "statusReason": "PENDING",
        "statusReasonDescription": "",
        "statusUpdateDate": "2019-09-26T15:38:33.401Z",
        "multiAuthorisationStatus": {
          "status": "AWAITING_FURTHER_AUTHORIZATION",
          "numberOfAuthorisationRequired": 2,
          "numberOfAuthorisationReceived": 1,
          "lastUpdatedDateTime": "2019-09-26T15:38:33.408Z",
          "expirationDateTime": "2019-09-26T14:20:14.393Z"
        }
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a PaymentResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseListMeta	An object containing a tracingId of the request
»» count	integer	The number of records returned.
»» pagination	Pagination	An object containing pagination information in ResponseListMeta
»»» next	Next	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»» self	FilterAndSort	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset.
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»»» offset	integer	Optional. The offset specified for the request.
»»»» sort	SortEnum	Valid options for the sort parameter
»»» totalCount	integer	Optional. The total count of the paged entities.
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[PaymentResponse]	An array of PaymentResponses.
»» amount	integer(decimal)	Deprecated. The amount of the Payment.
»» amountDetails	Amount	none
»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»» bulkAmountSum	integer(decimal)	The sum of all bulk payments
»» chargeDetails	[ChargeDetails]	The array of ChargeDetails, used to provide any additional fee if there is any of the payment. Mostly populated for International Payments.
»»» chargeAmount	Amount	none
»»» chargeTo	string	Not used.
»»» chargeType	string	The type of charge for the payment.
»» createdAt	string	The date and time the Payment was created.
»» currency	string	Deprecated. The currency of the Payment.
»» currencyOfTransfer	string	Used for International Payments. The currency used to transfer the money from source bank.
»» exchangeRate	ExchangeRateInformationResponse	An object containing exchange rate information.
»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»» finalPaymentAmount	Amount	none
»» finalPaymentDateTime	string	The date of the final payment in a sequence.
»» firstPaymentAmount	Amount	none
»» firstPaymentDateTime	string	The date of the first payment in a sequence.
»» frequency	FrequencyRequest	none
»»» type Mandatory	FrequencyEnumExtended	See payment frequency for more information.
»»» executionDay	integer	Conditional. See payment frequency for more information.
»»» intervalMonth	integer	Conditional. See payment frequency for more information.
»»» intervalWeek	integer	Conditional. See payment frequency for more information.
»» id	string	The id of the Payment.
»» institutionConsentId	string	The banks identification for the consent.
»» nextPaymentAmount	Amount	none
»» nextPaymentDateTime	string	The date of the next payment in a sequence.
»» numberOfPayments	integer	The number of payments in a sequence.
»» payeeDetails	Payee	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payee` bank account
»»»» identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
»»»» type Mandatory	AccountIdentificationType	See Account Identifications Types for more information on each type
»»» name Mandatory	string	The account holder name of the beneficiary
»»» address	Address	none
»»»» addressLines	[string]	The address lines for the address Mandatory for `INTERNATIONAL` payment types
»»»» addressType	AddressTypeEnum	The type of the Address.
»»»» buildingNumber	string	The building number for the address
»»»» country	string	The 2-letter country code for the address Mandatory for `INTERNATIONAL` payment types Some banks in the UK require this to be specified for `DOMESTIC` payment types. In this case, `country` should be set to "GB"
»»»» county	[string]	The county name for the address
»»»» department	string	The department name for the address
»»»» postCode	string	The post code for the address
»»»» streetName	string	The street name for the address Mandatory for `INTERNATIONAL` payment types
»»»» subDepartment	string	The sub department name for the address
»»»» townName	string	The town name for the address Mandatory for `INTERNATIONAL` payment types
»»» merchantCategoryCode	string	The category code of the merchant in case the `Payee` is a business
»»» merchantId	string	A merchant ID is a unique code provided by the payment processor to the merchant
»» payer	Payer	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payer` bank account
»»» address	Address	none
»»» name	string	The account holder name of the Payer
»» paymentIdempotencyId	string	The Payment IdempotencyId
»» paymentLifecycleId	string	The Payment LifecycleId
»» previousPaymentAmount	Amount	none
»» previousPaymentDateTime	string	The date of the previous payment in a sequence.
»» priority	string	The priority for the Payment.
»» purpose	string	The purpose for the Payment.
»» reference	string	A reference for the Payment.
»» scheduledPaymentDateTime	string	The scheduled payment date and time.
»» scheduledPaymentType	string	The type of scheduled payment.
»» status	PaymentStatus	The status of the Payment.
»» statusDetails	PaymentStatusDetails	none
»»» status	PaymentStatus	The status of the Payment.
»»» statusReason	string	The status reason.
»»» statusReasonDescription	string	The description of the status reason.
»»» statusUpdateDate	string	The date and time the status was updated.
»»» multiAuthorisationStatus	MultiAuthorisation	none
»»»» status	string	The status of the multi authorisation. Possible values are AUTHORIZED, AWAITING_FURTHER_AUTHORIZATION, REJECTED and UNKNOWN.
»»»» numberOfAuthorisationRequired	integer	The number of authorisations required to authorise the consent.
»»»» numberOfAuthorisationReceived	integer	The number of authorisations that have been completed.
»»»» lastUpdatedDateTime	string	The time at which the multi authorisation was last updated.
»»»» expirationDateTime	string	The time at which the multi authorisation expires if there is one.

Enumerated Values

Property	Value
sort	DATE_ASCENDING("date")
sort	DATE_DESCENDING("-date")
type	DAILY
type	EVERY_WORKING_DAY
type	CALENDAR_DAY
type	WEEKLY
type	EVERY_TWO_WEEKS
type	MONTHLY
type	EVERY_TWO_MONTHS
type	QUARTERLY
type	SEMIANNUAL
type	ANNUAL
type	SORT_CODE
type	ACCOUNT_NUMBER
type	IBAN
type	BBAN
type	BIC
type	PAN
type	MASKED_PAN
type	MSISDN
type	BSB
type	NCC
type	ABA
type	ABA_WIRE
type	ABA_ACH
type	EMAIL
addressType	BUSINESS
addressType	CORRESPONDENCE
addressType	DELIVERY_TO
addressType	MAIL_TO
addressType	PO_BOX
addressType	POSTAL
addressType	RESIDENTIAL
addressType	STATEMENT
addressType	UNKNOWN
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE

Get Account Scheduled Payments

Request

curl -X GET https://api.yapily.com/accounts/{account-id}/scheduled-payments \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'limit: 0' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts/{account-id}/scheduled-payments

Get the list of scheduled payments for an account.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
account-id Mandatory	path	string	The ID of the Account
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
limit	header	integer	Use this parameter to limit account's scheduled payment results
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "amount": "10.00",
      "amountDetails": {
        "amount": 10,
        "currency": "GBP"
      },
      "bulkAmountSum": 100,
      "chargeDetails": [
        {
          "chargeAmount": {
            "amount": null,
            "currency": null
          },
          "chargeTo": "",
          "chargeType": "BULK_PAYMENT"
        }
      ],
      "createdAt": "2019-09-26T15:38:33.401Z",
      "currency": "GBP",
      "currencyOfTransfer": "",
      "exchangeRate": {
        "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
      },
      "finalPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "finalPaymentDateTime": "2019-09-26T15:38:33.401Z",
      "firstPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "firstPaymentDateTime": "2019-09-26T15:38:33.401Z",
      "frequency": {
        "type": "DAILY",
        "executionDay": 1,
        "intervalMonth": 1,
        "intervalWeek": 1
      },
      "id": "pv3-c8eece27-eb1a-4c27-a13c-2f805703dab2",
      "institutionConsentId": "sdp-1-aa9d0941-43ff-4abb-8129-4d56b620b8ee",
      "nextPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "nextPaymentDateTime": "2019-09-26T15:38:33.401Z",
      "numberOfPayments": 10,
      "payeeDetails": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "name": "Bojack Horseman",
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "merchantCategoryCode": "5462",
        "merchantId": "12345678"
      },
      "payer": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "name": "Bojack Horseman"
      },
      "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
      "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d1",
      "previousPaymentAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "previousPaymentDateTime": "",
      "priority": "",
      "purpose": "",
      "reference": "myreference",
      "scheduledPaymentDateTime": "",
      "scheduledPaymentType": "",
      "status": "PENDING",
      "statusDetails": {
        "status": "PENDING",
        "statusReason": "PENDING",
        "statusReasonDescription": "",
        "statusUpdateDate": "2019-09-26T15:38:33.401Z",
        "multiAuthorisationStatus": {
          "status": "AWAITING_FURTHER_AUTHORIZATION",
          "numberOfAuthorisationRequired": 2,
          "numberOfAuthorisationReceived": 1,
          "lastUpdatedDateTime": "2019-09-26T15:38:33.408Z",
          "expirationDateTime": "2019-09-26T14:20:14.393Z"
        }
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a PaymentResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseListMeta	An object containing a tracingId of the request
»» count	integer	The number of records returned.
»» pagination	Pagination	An object containing pagination information in ResponseListMeta
»»» next	Next	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»» self	FilterAndSort	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset.
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»»» offset	integer	Optional. The offset specified for the request.
»»»» sort	SortEnum	Valid options for the sort parameter
»»» totalCount	integer	Optional. The total count of the paged entities.
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[PaymentResponse]	none
»» amount	integer(decimal)	Deprecated. The amount of the Payment.
»» amountDetails	Amount	none
»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»» bulkAmountSum	integer(decimal)	The sum of all bulk payments
»» chargeDetails	[ChargeDetails]	The array of ChargeDetails, used to provide any additional fee if there is any of the payment. Mostly populated for International Payments.
»»» chargeAmount	Amount	none
»»» chargeTo	string	Not used.
»»» chargeType	string	The type of charge for the payment.
»» createdAt	string	The date and time the Payment was created.
»» currency	string	Deprecated. The currency of the Payment.
»» currencyOfTransfer	string	Used for International Payments. The currency used to transfer the money from source bank.
»» exchangeRate	ExchangeRateInformationResponse	An object containing exchange rate information.
»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»» finalPaymentAmount	Amount	none
»» finalPaymentDateTime	string	The date of the final payment in a sequence.
»» firstPaymentAmount	Amount	none
»» firstPaymentDateTime	string	The date of the first payment in a sequence.
»» frequency	FrequencyRequest	none
»»» type Mandatory	FrequencyEnumExtended	See payment frequency for more information.
»»» executionDay	integer	Conditional. See payment frequency for more information.
»»» intervalMonth	integer	Conditional. See payment frequency for more information.
»»» intervalWeek	integer	Conditional. See payment frequency for more information.
»» id	string	The id of the Payment.
»» institutionConsentId	string	The banks identification for the consent.
»» nextPaymentAmount	Amount	none
»» nextPaymentDateTime	string	The date of the next payment in a sequence.
»» numberOfPayments	integer	The number of payments in a sequence.
»» payeeDetails	Payee	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payee` bank account
»»»» identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
»»»» type Mandatory	AccountIdentificationType	See Account Identifications Types for more information on each type
»»» name Mandatory	string	The account holder name of the beneficiary
»»» address	Address	none
»»»» addressLines	[string]	The address lines for the address Mandatory for `INTERNATIONAL` payment types
»»»» addressType	AddressTypeEnum	The type of the Address.
»»»» buildingNumber	string	The building number for the address
»»»» country	string	The 2-letter country code for the address Mandatory for `INTERNATIONAL` payment types Some banks in the UK require this to be specified for `DOMESTIC` payment types. In this case, `country` should be set to "GB"
»»»» county	[string]	The county name for the address
»»»» department	string	The department name for the address
»»»» postCode	string	The post code for the address
»»»» streetName	string	The street name for the address Mandatory for `INTERNATIONAL` payment types
»»»» subDepartment	string	The sub department name for the address
»»»» townName	string	The town name for the address Mandatory for `INTERNATIONAL` payment types
»»» merchantCategoryCode	string	The category code of the merchant in case the `Payee` is a business
»»» merchantId	string	A merchant ID is a unique code provided by the payment processor to the merchant
»» payer	Payer	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payer` bank account
»»» address	Address	none
»»» name	string	The account holder name of the Payer
»» paymentIdempotencyId	string	The Payment IdempotencyId
»» paymentLifecycleId	string	The Payment LifecycleId
»» previousPaymentAmount	Amount	none
»» previousPaymentDateTime	string	The date of the previous payment in a sequence.
»» priority	string	The priority for the Payment.
»» purpose	string	The purpose for the Payment.
»» reference	string	A reference for the Payment.
»» scheduledPaymentDateTime	string	The scheduled payment date and time.
»» scheduledPaymentType	string	The type of scheduled payment.
»» status	PaymentStatus	The status of the Payment.
»» statusDetails	PaymentStatusDetails	none
»»» status	PaymentStatus	The status of the Payment.
»»» statusReason	string	The status reason.
»»» statusReasonDescription	string	The description of the status reason.
»»» statusUpdateDate	string	The date and time the status was updated.
»»» multiAuthorisationStatus	MultiAuthorisation	none
»»»» status	string	The status of the multi authorisation. Possible values are AUTHORIZED, AWAITING_FURTHER_AUTHORIZATION, REJECTED and UNKNOWN.
»»»» numberOfAuthorisationRequired	integer	The number of authorisations required to authorise the consent.
»»»» numberOfAuthorisationReceived	integer	The number of authorisations that have been completed.
»»»» lastUpdatedDateTime	string	The time at which the multi authorisation was last updated.
»»»» expirationDateTime	string	The time at which the multi authorisation expires if there is one.

Enumerated Values

Property	Value
sort	DATE_ASCENDING("date")
sort	DATE_DESCENDING("-date")
type	DAILY
type	EVERY_WORKING_DAY
type	CALENDAR_DAY
type	WEEKLY
type	EVERY_TWO_WEEKS
type	MONTHLY
type	EVERY_TWO_MONTHS
type	QUARTERLY
type	SEMIANNUAL
type	ANNUAL
type	SORT_CODE
type	ACCOUNT_NUMBER
type	IBAN
type	BBAN
type	BIC
type	PAN
type	MASKED_PAN
type	MSISDN
type	BSB
type	NCC
type	ABA
type	ABA_WIRE
type	ABA_ACH
type	EMAIL
addressType	BUSINESS
addressType	CORRESPONDENCE
addressType	DELIVERY_TO
addressType	MAIL_TO
addressType	PO_BOX
addressType	POSTAL
addressType	RESIDENTIAL
addressType	STATEMENT
addressType	UNKNOWN
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE

Get Account Balances

Request

curl -X GET https://api.yapily.com/accounts/{account-id}/balances \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts/{account-id}/balances

Returns the balance for the end user associated with the presented consent token.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
account-id Mandatory	path	string	The ID of the Account
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "balances": [
        {
          "balanceAmount": {
            "amount": null,
            "currency": null
          },
          "creditLineIncluded": true,
          "creditLines": [
            {}
          ],
          "dateTime": "2020-09-21T16:35:55Z",
          "type": "CLOSING_AVAILABLE"
        }
      ],
      "mainBalanceAmount": {
        "amount": 10,
        "currency": "GBP"
      }
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a PaymentResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[Balances]	none
»» balances	[AccountBalance]	An array of AccountBalances.
»»» balanceAmount	Amount	none
»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»» creditLineIncluded	boolean	Indicates whether or not the credit line is included in the balance.
»»» creditLines	[CreditLine]	An array of CreditLine objects.
»»»» creditLineAmount	Amount	none
»»»» type	CreditLineType	The type of credit line.
»»» dateTime	string	The timestamp of the last change of the balance amount.
»»» type	AccountBalanceType	The OBBalanceType1Code balance type. CLOSING_AVAILABLE - Closing balance of amount of money that is at the disposal of the account owner on the date specified CLOSING_BOOKED - Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. CLOSING_CLEARED - Closing balance of amount of money that is cleared on the date specified. EXPECTED - Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. FORWARD_AVAILABLE - Forward available balance of money that is at the disposal of the account owner on the date specified. INFORMATION - Balance for informational purposes. INTERIM_AVAILABLE - Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_BOOKED - Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_CLEARED - Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. OPENING_AVAILABLE - Opening balance of amount of money that is at the disposal of the account owner on the date specified. OPENING_BOOKED - Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. OPENING_CLEARED - Opening balance of amount of money that is cleared on the date specified. PREVIOUSLY_CLOSED_BOOKED - Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date. AUTHORISED - Balance of the account minus any authorised transactions not yet cleared. OTHER - Used when an unrecognised enum is parsed UNKNOWN - Used as a Yapily default
»» mainBalanceAmount	Amount	none

Enumerated Values

Property	Value
type	AVAILABLE
type	CREDIT
type	EMERGENCY
type	PRE_AGREED
type	TEMPORARY
type	OTHER
type	UNKNOWN
type	CLOSING_AVAILABLE
type	CLOSING_BOOKED
type	CLOSING_CLEARED
type	EXPECTED
type	FORWARD_AVAILABLE
type	INFORMATION
type	INTERIM_AVAILABLE
type	INTERIM_BOOKED
type	INTERIM_CLEARED
type	OPENING_AVAILABLE
type	OPENING_BOOKED
type	OPENING_CLEARED
type	PREVIOUSLY_CLOSED_BOOKED
type	AUTHORISED
type	OTHER
type	UNKNOWN

Get Account Transactions

Request

curl -X GET https://api.yapily.com/accounts/{account-id}/transactions \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts/{account-id}/transactions

Used to get the transactions from a specific account.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
account-id Mandatory	path	string	The ID of the Account
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
with	query	string	Can be `categories` or `merchant`. When set, will include enrichment data in the transactions returned. Enrichment data is optional, e.g. when 'merchant' enrichment data is requested, the enrichment response will include merchant data only if it can be evaluated from the transaction.
from	query	string	Optional. Returned transactions will be on or after this date. (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
to	query	string	Optional. Returned transactions will be on or before this date. (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
limit	query	string	Optional. The maximum number of transaction records to be returned. Must be between 0 and 1000
sort	query	string	Optional. Sort transaction records by date ascending with date or descending with -date. The default sort order is descending.
offset	query	string	Optional. The number of transaction records to be skipped. Used primarily with paginated results
cursor	query	string	Optional. This property is not currently in use.
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "addressDetails": {
        "addressLine": "123 Test Street, Test, AB1 2DC"
      },
      "amount": 10,
      "balance": {
        "balanceAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "type": "CLOSING_AVAILABLE"
      },
      "bookingDateTime": "2019-04-20T23:54:10.937Z",
      "chargeDetails": {
        "chargeAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "chargeTo": "",
        "chargeType": "BULK_PAYMENT"
      },
      "currency": "GBP",
      "currencyExchange": {
        "exchangeRate": 1.34,
        "sourceCurrency": "GBP",
        "targetCurrency": "EUR",
        "unitCurrency": "GBP"
      },
      "date": "2019-04-20T23:54:10.937Z",
      "description": "Exchanged to EUR",
      "enrichment": {
        "categorisation": {
          "categories": "[Object]",
          "source": "MODEL"
        },
        "transactionHash": {
          "hash": "b0781fd71caa48c75039ec01c0ffb011.1"
        },
        "merchant": {
          "merchantName": "DEBENHAMS",
          "parentGroup": "ARCADIA"
        },
        "paymentProcessor": "PAYPAL",
        "location": "LONDON",
        "correctedDate": "2020-05-04T14:31:04.872Z"
      },
      "id": "d6f8ee30-7804-4c62-9457-fe64fcd23fc2",
      "isoBankTransactionCode": {
        "domainCode": {
          "code": "",
          "name": ""
        },
        "familyCode": {
          "code": "",
          "name": ""
        },
        "subFamilyCode": {
          "code": "",
          "name": ""
        }
      },
      "merchant": {
        "merchantCategoryCode": "5462",
        "merchantName": "London Luxury Baker"
      },
      "payeeDetails": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "name": "Bojack Horseman",
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "merchantCategoryCode": "5462",
        "merchantId": "12345678"
      },
      "payerDetails": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "name": "Bojack Horseman"
      },
      "proprietaryBankTransactionCode": {
        "code": "EXCHANGE",
        "issuer": "Revolut"
      },
      "reference": "mytrxref",
      "statementReferences": [
        {
          "value": "They sent you money for carrots"
        }
      ],
      "status": "BOOKED",
      "supplementaryData": {
        "name": "",
        "value": ""
      },
      "transactionAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "grossAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "transactionInformation": [
        ""
      ],
      "valueDateTime": "2019-04-20T23:54:10.937Z"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a PaymentResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseListMeta	An object containing a tracingId of the request
»» count	integer	The number of records returned.
»» pagination	Pagination	An object containing pagination information in ResponseListMeta
»»» next	Next	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»» self	FilterAndSort	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset.
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»»» offset	integer	Optional. The offset specified for the request.
»»»» sort	SortEnum	Valid options for the sort parameter
»»» totalCount	integer	Optional. The total count of the paged entities.
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[Transaction]	none
»» addressDetails	AddressDetails	none
»»» addressLine	string	The address line for the address
»» amount	integer(decimal)	Deprecated. Use the amount value in transactionAmount instead.
»» balance	Balance	An object containing the amount and balance type.
»»» balanceAmount	Amount	none
»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»» type	AccountBalanceType	The OBBalanceType1Code balance type. CLOSING_AVAILABLE - Closing balance of amount of money that is at the disposal of the account owner on the date specified CLOSING_BOOKED - Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. CLOSING_CLEARED - Closing balance of amount of money that is cleared on the date specified. EXPECTED - Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. FORWARD_AVAILABLE - Forward available balance of money that is at the disposal of the account owner on the date specified. INFORMATION - Balance for informational purposes. INTERIM_AVAILABLE - Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_BOOKED - Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_CLEARED - Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. OPENING_AVAILABLE - Opening balance of amount of money that is at the disposal of the account owner on the date specified. OPENING_BOOKED - Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. OPENING_CLEARED - Opening balance of amount of money that is cleared on the date specified. PREVIOUSLY_CLOSED_BOOKED - Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date. AUTHORISED - Balance of the account minus any authorised transactions not yet cleared. OTHER - Used when an unrecognised enum is parsed UNKNOWN - Used as a Yapily default
»» bookingDateTime	string	The date and (if available) time that transaction is posted. It is quite common for an Institution to return a time of 12:00:00.
»» chargeDetails	ChargeDetails	The amount details for the payment.
»»» chargeAmount	Amount	none
»»» chargeTo	string	Not used.
»»» chargeType	string	The type of charge for the payment.
»» currency	string	Deprecated. Use the currency value in transactionAmount instead.
»» currencyExchange	CurrencyExchange	Used to describe currency exchanges.
»»» exchangeRate	integer	The currency exchange rate.
»»» sourceCurrency	string	The ISO 4217 currency code denoting the currency of the creditor.
»»» targetCurrency	string	The ISO 4217 currency code denoting the currency of the debtor.
»»» unitCurrency	string	The ISO 4217 currency code denoting the currency used to set the exchange rate (GBP is the unit currency in the conversion of 1 GBP = x CUR).
»» date	string	The transaction date as defined by the institution.
»» description	string	Unstructured text containing details of the transaction. Usage varies according to the Institution.
»» enrichment	Enrichment	An object containing Transaction enrichment information.
»»» categorisation	Categorisation	Enrichment object provided for merchant and categories enrichment.
»»»» categories	[string]	An array of Strings describing the transaction category.
»»»» source	string	The source of the categorisation information.
»»» transactionHash	TransactionHash	A hash of the Transaction, provided in the enrichment object.
»»»» hash	string	none
»»» merchant	MerchantEnrichment	Enrichment object provided for Transaction merchant enrichment.
»»»» merchantName	string	none
»»»» parentGroup	string	none
»»» paymentProcessor	string	Optional. Can be provided with merchant enrichment.
»»» location	string	Optional. Can be provided with merchant enrichment.
»»» correctedDate	string	Optional. Can be provided with merchant enrichment.
»» id	string	The transaction Id returned by the institution if present.
»» isoBankTransactionCode	IsoBankTransactionCode	none
»»» domainCode	IsoCodeDetails	none
»»»» code	string	The ISO Code.
»»»» name	string	A friendly name for the ISO Code.
»»» familyCode	IsoCodeDetails	none
»»» subFamilyCode	IsoCodeDetails	none
»» merchant	Merchant	none
»»» merchantCategoryCode	string	Optional. The merchant category code.
»»» merchantName	string	Optional. The name of the merchant.
»» payeeDetails	Payee	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payee` bank account
»»»» identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
»»»» type Mandatory	AccountIdentificationType	See Account Identifications Types for more information on each type
»»» name Mandatory	string	The account holder name of the beneficiary
»»» address	Address	none
»»»» addressLines	[string]	The address lines for the address Mandatory for `INTERNATIONAL` payment types
»»»» addressType	AddressTypeEnum	The type of the Address.
»»»» buildingNumber	string	The building number for the address
»»»» country	string	The 2-letter country code for the address Mandatory for `INTERNATIONAL` payment types Some banks in the UK require this to be specified for `DOMESTIC` payment types. In this case, `country` should be set to "GB"
»»»» county	[string]	The county name for the address
»»»» department	string	The department name for the address
»»»» postCode	string	The post code for the address
»»»» streetName	string	The street name for the address Mandatory for `INTERNATIONAL` payment types
»»»» subDepartment	string	The sub department name for the address
»»»» townName	string	The town name for the address Mandatory for `INTERNATIONAL` payment types
»»» merchantCategoryCode	string	The category code of the merchant in case the `Payee` is a business
»»» merchantId	string	A merchant ID is a unique code provided by the payment processor to the merchant
»» payerDetails	Payer	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payer` bank account
»»» address	Address	none
»»» name	string	The account holder name of the Payer
»» proprietaryBankTransactionCode	ProprietaryBankTransactionCode	none
»»» code	string	The code
»»» issuer	string	The issuer.
»» reference	string	The transaction reference.
»» statementReferences	[StatementReference]	An array of StatementReference objects.
»»» value	string	The statement reference value.
»» status	TransactionStatusEnum	The status of the Transaction.
»» supplementaryData	Map	none
»»» name	string	The name.
»»» value	string	The value.
»» transactionAmount	Amount	none
»» grossAmount	Amount	none
»» transactionInformation	[string]	Further information related to the transaction. Usage varies according to the Institution.
»» valueDateTime	string	The actual or expected date and time transaction is cleared. It is quite common for an Institution to return a time of 12:00:00.

Enumerated Values

Property	Value
sort	DATE_ASCENDING("date")
sort	DATE_DESCENDING("-date")
type	CLOSING_AVAILABLE
type	CLOSING_BOOKED
type	CLOSING_CLEARED
type	EXPECTED
type	FORWARD_AVAILABLE
type	INFORMATION
type	INTERIM_AVAILABLE
type	INTERIM_BOOKED
type	INTERIM_CLEARED
type	OPENING_AVAILABLE
type	OPENING_BOOKED
type	OPENING_CLEARED
type	PREVIOUSLY_CLOSED_BOOKED
type	AUTHORISED
type	OTHER
type	UNKNOWN
type	SORT_CODE
type	ACCOUNT_NUMBER
type	IBAN
type	BBAN
type	BIC
type	PAN
type	MASKED_PAN
type	MSISDN
type	BSB
type	NCC
type	ABA
type	ABA_WIRE
type	ABA_ACH
type	EMAIL
addressType	BUSINESS
addressType	CORRESPONDENCE
addressType	DELIVERY_TO
addressType	MAIL_TO
addressType	PO_BOX
addressType	POSTAL
addressType	RESIDENTIAL
addressType	STATEMENT
addressType	UNKNOWN
status	BOOKED
status	PENDING

Get Account Statements

Request

curl -X GET https://api.yapily.com/accounts/{account-id}/statements \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts/{account-id}/statements

Used to get the statements from a specific account.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
account-id Mandatory	path	string	The ID of the Account
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
from	query	string	Optional. Returned statements will be after this date. (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
before	query	string	Optional. Returned statements will be before this date. (yyyy-MM-dd'T'HH:mm:ss.SSSZ)
limit	query	string	Optional. The maximum number of statements records to be returned. Must be between 0 and 1000
sort	query	string	Optional. Sort statements records by date ascending with date or descending with -date. The default sort order is descending.
offset	query	string	Optional. The number of statements records to be skipped. Used primarily with paginated results
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": [
    {
      "creationDateTime": "2017-02-01T00:00:00Z",
      "endDateTime": "2017-02-01T00:00:00Z",
      "id": "",
      "startDateTime": "2017-02-01T00:00:00Z"
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a AccountStatement.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseListMeta	An object containing a tracingId of the request
»» count	integer	The number of records returned.
»» pagination	Pagination	An object containing pagination information in ResponseListMeta
»»» next	Next	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»» self	FilterAndSort	An object for filter and sort information
»»»» before	string	Optional. The upper bound of the date range.
»»»» cursor	string	Optional. Used in some cases instead of limit/offset.
»»»» from	string	Optional. The lower bound of the date range.
»»»» limit	integer	Optional. The limit specified for the request.
»»»» offset	integer	Optional. The offset specified for the request.
»»»» sort	SortEnum	Valid options for the sort parameter
»»» totalCount	integer	Optional. The total count of the paged entities.
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	[AccountStatement]	none
»» creationDateTime	string	The date and time the statement was created.
»» endDateTime	string	The date and time for the end of the period of the statement.
»» id	string	The identifer of the statement.
»» startDateTime	string	The date and time for the start of the period of the statement.

Enumerated Values

Property	Value
sort	DATE_ASCENDING("date")
sort	DATE_DESCENDING("-date")

Get Account Statement

Request

curl -X GET https://api.yapily.com/accounts/{account-id}/statements/{statement-id} \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts/{account-id}/statements/{statement-id}

Used to get a statement from a specific account.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
account-id Mandatory	path	string	The ID of the Account
statement-id Mandatory	path	string	The ID of the Statement
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "creationDateTime": "2017-02-01T00:00:00Z",
    "endDateTime": "2017-02-01T00:00:00Z",
    "id": "",
    "startDateTime": "2017-02-01T00:00:00Z"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a AccountStatement.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	AccountStatement	none
»» creationDateTime	string	The date and time the statement was created.
»» endDateTime	string	The date and time for the end of the period of the statement.
»» id	string	The identifer of the statement.
»» startDateTime	string	The date and time for the start of the period of the statement.

Get Account Statement PDF

Request

curl -X GET https://api.yapily.com/accounts/{account-id}/statements/{statement-id}/file \
  -H 'Accept: application/pdf' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /accounts/{account-id}/statements/{statement-id}/file

Download the specific statement file for an account.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
account-id Mandatory	path	string	The ID of the Account
statement-id Mandatory	path	string	The ID of the Statement
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

400 Response

{
  "error": {
    "code": 401,
    "institutionError": {
      "errorMessage": "{\"Code\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Errors\":[{\"ErrorCode\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Field\":\"x-jws-signature\"}]}",
      "httpStatusCode": 100
    },
    "message": "Full authentication is required to access this resource",
    "source": "YAPILY",
    "status": "BAD_REQUEST",
    "tracingId": "e7b01315-cbc5-4d0b-91e8-4f77cb1a3253"
  },
  "monitoring": [
    {
      "lastTested": "",
      "resourceEndpoint": "",
      "span": "",
      "status": "UP"
    }
  ],
  "raw": [
    {
      "duration": "",
      "headers": [
        {
          "name": "",
          "value": ""
        }
      ],
      "request": {
        "method": "",
        "requestInstant": "",
        "templateUri": "",
        "url": ""
      },
      "result": "",
      "resultCode": 100
    }
  ]
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a PDF of the statement.	string
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Headers

Status	Header	Type	Format	Description
200	attachment	string	binary	Contains the PDF of the statement

Get Identity

Request

curl -X GET https://api.yapily.com/identity \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /identity

Used to get identity information from the bank for the account holder.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "addresses": [
      {
        "addressLine": "",
        "buildingNumber": "123",
        "city": "London",
        "country": "GB",
        "county": "London",
        "postalCode": "A12 3BC",
        "streetName": "123 Test Street",
        "type": "BUSINESS"
      }
    ],
    "birthdate": "1970-01-01",
    "email": "bojack@horsingaround.com",
    "firstName": "Bojack",
    "lastName": "Horseman",
    "fullName": "Bojack Horseman",
    "gender": "MALE",
    "id": "abc123",
    "phone": "02071234567"
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a PaymentResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	Identity	none
»» addresses	[IdentityAddress]	An array of addresses for the Identity.
»»» addressLine	[string]	none
»»» buildingNumber	string	none
»»» city	string	none
»»» country	string	none
»»» county	string	none
»»» postalCode	string	none
»»» streetName	string	none
»»» type	AddressTypeEnum	The type of the Address.
»» birthdate	string	A birth date for the Identity.
»» email	string	An email for the Identity.
»» firstName	string	A first name for the Identity.
»» lastName	string	A last name for the Identity.
»» fullName	string	A full name for the Identity.
»» gender	string	A gender for the Identity.
»» id	string	An identifier for the Identity.
»» phone	string	A phone number for the Identity.

Enumerated Values

Property	Value
type	BUSINESS
type	CORRESPONDENCE
type	DELIVERY_TO
type	MAIL_TO
type	PO_BOX
type	POSTAL
type	RESIDENTIAL
type	STATEMENT
type	UNKNOWN

Payments

In order to create a payment for your user, you are required to obtain their consent to proceed. Once a Consent token is obtained, you can call the Payment endpoints to create single, scheduled, periodic or recurring payments.

Create Payment

Request

curl -X POST https://api.yapily.com/payments \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /payments

Used to send a request to the Institution to execute a payment that has been authorised by the user. This endpoint is used once a user has authorised a payment using Create Payment Authorisation with their bank. Make sure to use the Create Bulk Payment endpoint for executing bulk payments.

Body parameter

{
  "type": "DOMESTIC_PAYMENT",
  "amount": {
    "amount": 10,
    "currency": "GBP"
  },
  "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
  "payee": {
    "accountIdentifications": [
      {
        "identification": "123456",
        "type": "SORT_CODE"
      }
    ],
    "name": "Bojack Horseman",
    "address": {
      "addressLines": [
        "1 Downing St"
      ],
      "addressType": "BUSINESS",
      "buildingNumber": "123",
      "country": "GB",
      "county": "London",
      "department": "",
      "postCode": "A12 3BC",
      "streetName": "123 Test Street",
      "subDepartment": "",
      "townName": "London"
    },
    "merchantCategoryCode": "5462",
    "merchantId": "12345678"
  },
  "payer": {
    "accountIdentifications": [
      {
        "identification": "123456",
        "type": "SORT_CODE"
      }
    ],
    "address": {
      "addressLines": [
        "1 Downing St"
      ],
      "addressType": "BUSINESS",
      "buildingNumber": "123",
      "country": "GB",
      "county": "London",
      "department": "",
      "postCode": "A12 3BC",
      "streetName": "123 Test Street",
      "subDepartment": "",
      "townName": "London"
    },
    "name": "Bojack Horseman"
  },
  "reference": "myreference",
  "paymentDateTime": "2019-12-26T14:42:53Z",
  "contextType": "BILL",
  "internationalPayment": {
    "chargeBearer": "DEBT",
    "currencyOfTransfer": "GBP",
    "exchangeRateInformation": "string",
    "priority": "NORMAL",
    "purpose": "277ca9eb968948d4b5f8bfa4b6b6b16f"
  },
  "periodicPayment": {
    "frequency": {
      "type": "DAILY",
      "executionDay": 1,
      "intervalMonth": 1,
      "intervalWeek": 1
    },
    "nextPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "nextPaymentDateTime": "2018-01-10T00:00:00Z",
    "finalPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "finalPaymentDateTime": "2021-01-10T00:00:00Z",
    "numberOfPayments": 5
  },
  "readRefundAccount": true,
  "psuCorporateId": "",
  "psuId": ""
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consent Mandatory	header	string	The `consentToken` obtained from the original authorisation.
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	PaymentRequest	The exact value of the `paymentRequest` json object used in the Create Payment Authorisation request. This must be an exact match otherwise the payment request will fail.

Example responses

201 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "amount": "10.00",
    "amountDetails": {
      "amount": 10,
      "currency": "GBP"
    },
    "bulkAmountSum": 100,
    "chargeDetails": [
      {
        "chargeAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "chargeTo": "",
        "chargeType": "BULK_PAYMENT"
      }
    ],
    "createdAt": "2019-09-26T15:38:33.401Z",
    "currency": "GBP",
    "currencyOfTransfer": "",
    "exchangeRate": {
      "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
    },
    "finalPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "finalPaymentDateTime": "2019-09-26T15:38:33.401Z",
    "firstPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "firstPaymentDateTime": "2019-09-26T15:38:33.401Z",
    "frequency": {
      "type": "DAILY",
      "executionDay": 1,
      "intervalMonth": 1,
      "intervalWeek": 1
    },
    "id": "pv3-c8eece27-eb1a-4c27-a13c-2f805703dab2",
    "institutionConsentId": "sdp-1-aa9d0941-43ff-4abb-8129-4d56b620b8ee",
    "nextPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "nextPaymentDateTime": "2019-09-26T15:38:33.401Z",
    "numberOfPayments": 10,
    "payeeDetails": {
      "accountIdentifications": [
        {
          "identification": "123456",
          "type": "["
        }
      ],
      "name": "Bojack Horseman",
      "address": {
        "addressLines": [
          "1 Downing St"
        ],
        "addressType": "BUSINESS",
        "buildingNumber": "123",
        "country": "GB",
        "county": "London",
        "department": "",
        "postCode": "A12 3BC",
        "streetName": "123 Test Street",
        "subDepartment": "",
        "townName": "London"
      },
      "merchantCategoryCode": "5462",
      "merchantId": "12345678"
    },
    "payer": {
      "accountIdentifications": [
        {
          "identification": "123456",
          "type": "["
        }
      ],
      "address": {
        "addressLines": [
          "1 Downing St"
        ],
        "addressType": "BUSINESS",
        "buildingNumber": "123",
        "country": "GB",
        "county": "London",
        "department": "",
        "postCode": "A12 3BC",
        "streetName": "123 Test Street",
        "subDepartment": "",
        "townName": "London"
      },
      "name": "Bojack Horseman"
    },
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d1",
    "previousPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "previousPaymentDateTime": "",
    "priority": "",
    "purpose": "",
    "reference": "myreference",
    "scheduledPaymentDateTime": "",
    "scheduledPaymentType": "",
    "status": "PENDING",
    "statusDetails": {
      "status": "PENDING",
      "statusReason": "PENDING",
      "statusReasonDescription": "",
      "statusUpdateDate": "2019-09-26T15:38:33.401Z",
      "multiAuthorisationStatus": {
        "status": "AWAITING_FURTHER_AUTHORIZATION",
        "numberOfAuthorisationRequired": 2,
        "numberOfAuthorisationReceived": 1,
        "lastUpdatedDateTime": "2019-09-26T15:38:33.408Z",
        "expirationDateTime": "2019-09-26T14:20:14.393Z"
      }
    }
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a PaymentResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 201

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	PaymentResponse	none
»» amount	integer(decimal)	Deprecated. The amount of the Payment.
»» amountDetails	Amount	none
»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»» bulkAmountSum	integer(decimal)	The sum of all bulk payments
»» chargeDetails	[ChargeDetails]	The array of ChargeDetails, used to provide any additional fee if there is any of the payment. Mostly populated for International Payments.
»»» chargeAmount	Amount	none
»»» chargeTo	string	Not used.
»»» chargeType	string	The type of charge for the payment.
»» createdAt	string	The date and time the Payment was created.
»» currency	string	Deprecated. The currency of the Payment.
»» currencyOfTransfer	string	Used for International Payments. The currency used to transfer the money from source bank.
»» exchangeRate	ExchangeRateInformationResponse	An object containing exchange rate information.
»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»» finalPaymentAmount	Amount	none
»» finalPaymentDateTime	string	The date of the final payment in a sequence.
»» firstPaymentAmount	Amount	none
»» firstPaymentDateTime	string	The date of the first payment in a sequence.
»» frequency	FrequencyRequest	none
»»» type Mandatory	FrequencyEnumExtended	See payment frequency for more information.
»»» executionDay	integer	Conditional. See payment frequency for more information.
»»» intervalMonth	integer	Conditional. See payment frequency for more information.
»»» intervalWeek	integer	Conditional. See payment frequency for more information.
»» id	string	The id of the Payment.
»» institutionConsentId	string	The banks identification for the consent.
»» nextPaymentAmount	Amount	none
»» nextPaymentDateTime	string	The date of the next payment in a sequence.
»» numberOfPayments	integer	The number of payments in a sequence.
»» payeeDetails	Payee	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payee` bank account
»»»» identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
»»»» type Mandatory	AccountIdentificationType	See Account Identifications Types for more information on each type
»»» name Mandatory	string	The account holder name of the beneficiary
»»» address	Address	none
»»»» addressLines	[string]	The address lines for the address Mandatory for `INTERNATIONAL` payment types
»»»» addressType	AddressTypeEnum	The type of the Address.
»»»» buildingNumber	string	The building number for the address
»»»» country	string	The 2-letter country code for the address Mandatory for `INTERNATIONAL` payment types Some banks in the UK require this to be specified for `DOMESTIC` payment types. In this case, `country` should be set to "GB"
»»»» county	[string]	The county name for the address
»»»» department	string	The department name for the address
»»»» postCode	string	The post code for the address
»»»» streetName	string	The street name for the address Mandatory for `INTERNATIONAL` payment types
»»»» subDepartment	string	The sub department name for the address
»»»» townName	string	The town name for the address Mandatory for `INTERNATIONAL` payment types
»»» merchantCategoryCode	string	The category code of the merchant in case the `Payee` is a business
»»» merchantId	string	A merchant ID is a unique code provided by the payment processor to the merchant
»» payer	Payer	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payer` bank account
»»» address	Address	none
»»» name	string	The account holder name of the Payer
»» paymentIdempotencyId	string	The Payment IdempotencyId
»» paymentLifecycleId	string	The Payment LifecycleId
»» previousPaymentAmount	Amount	none
»» previousPaymentDateTime	string	The date of the previous payment in a sequence.
»» priority	string	The priority for the Payment.
»» purpose	string	The purpose for the Payment.
»» reference	string	A reference for the Payment.
»» scheduledPaymentDateTime	string	The scheduled payment date and time.
»» scheduledPaymentType	string	The type of scheduled payment.
»» status	PaymentStatus	The status of the Payment.
»» statusDetails	PaymentStatusDetails	none
»»» status	PaymentStatus	The status of the Payment.
»»» statusReason	string	The status reason.
»»» statusReasonDescription	string	The description of the status reason.
»»» statusUpdateDate	string	The date and time the status was updated.
»»» multiAuthorisationStatus	MultiAuthorisation	none
»»»» status	string	The status of the multi authorisation. Possible values are AUTHORIZED, AWAITING_FURTHER_AUTHORIZATION, REJECTED and UNKNOWN.
»»»» numberOfAuthorisationRequired	integer	The number of authorisations required to authorise the consent.
»»»» numberOfAuthorisationReceived	integer	The number of authorisations that have been completed.
»»»» lastUpdatedDateTime	string	The time at which the multi authorisation was last updated.
»»»» expirationDateTime	string	The time at which the multi authorisation expires if there is one.

Enumerated Values

Property	Value
type	DAILY
type	EVERY_WORKING_DAY
type	CALENDAR_DAY
type	WEEKLY
type	EVERY_TWO_WEEKS
type	MONTHLY
type	EVERY_TWO_MONTHS
type	QUARTERLY
type	SEMIANNUAL
type	ANNUAL
type	SORT_CODE
type	ACCOUNT_NUMBER
type	IBAN
type	BBAN
type	BIC
type	PAN
type	MASKED_PAN
type	MSISDN
type	BSB
type	NCC
type	ABA
type	ABA_WIRE
type	ABA_ACH
type	EMAIL
addressType	BUSINESS
addressType	CORRESPONDENCE
addressType	DELIVERY_TO
addressType	MAIL_TO
addressType	PO_BOX
addressType	POSTAL
addressType	RESIDENTIAL
addressType	STATEMENT
addressType	UNKNOWN
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE

Create Bulk Payment

Request

curl -X POST https://api.yapily.com/bulk-payments \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

POST /bulk-payments

Used to create a bulk payment request from a business account. See Create Bulk Payment Authorisation to learn how to obtain a Consent Token for a Bulk Payment.

Body parameter

{
  "executionDateTime": "2020-10-17T00:00:00Z",
  "originatorIdentificationNumber": "",
  "payments": [
    {
      "type": "DOMESTIC_PAYMENT",
      "amount": {
        "amount": 10,
        "currency": "GBP"
      },
      "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
      "payee": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "name": "Bojack Horseman",
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "merchantCategoryCode": "5462",
        "merchantId": "12345678"
      },
      "payer": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "name": "Bojack Horseman"
      },
      "reference": "myreference",
      "paymentDateTime": "2019-12-26T14:42:53Z",
      "contextType": "BILL",
      "internationalPayment": {
        "chargeBearer": "DEBT",
        "currencyOfTransfer": "GBP",
        "exchangeRateInformation": "string",
        "priority": "NORMAL",
        "purpose": "277ca9eb968948d4b5f8bfa4b6b6b16f"
      },
      "periodicPayment": {
        "frequency": {
          "type": "[",
          "executionDay": 1,
          "intervalMonth": 1,
          "intervalWeek": 1
        },
        "nextPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "nextPaymentDateTime": "2018-01-10T00:00:00Z",
        "finalPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "finalPaymentDateTime": "2021-01-10T00:00:00Z",
        "numberOfPayments": 5
      },
      "readRefundAccount": true,
      "psuCorporateId": "",
      "psuId": ""
    }
  ]
}

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes
body Mandatory	body	BulkPaymentRequest	The requestBody

Example responses

201 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "amount": "10.00",
    "amountDetails": {
      "amount": 10,
      "currency": "GBP"
    },
    "bulkAmountSum": 100,
    "chargeDetails": [
      {
        "chargeAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "chargeTo": "",
        "chargeType": "BULK_PAYMENT"
      }
    ],
    "createdAt": "2019-09-26T15:38:33.401Z",
    "currency": "GBP",
    "currencyOfTransfer": "",
    "exchangeRate": {
      "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
    },
    "finalPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "finalPaymentDateTime": "2019-09-26T15:38:33.401Z",
    "firstPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "firstPaymentDateTime": "2019-09-26T15:38:33.401Z",
    "frequency": {
      "type": "DAILY",
      "executionDay": 1,
      "intervalMonth": 1,
      "intervalWeek": 1
    },
    "id": "pv3-c8eece27-eb1a-4c27-a13c-2f805703dab2",
    "institutionConsentId": "sdp-1-aa9d0941-43ff-4abb-8129-4d56b620b8ee",
    "nextPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "nextPaymentDateTime": "2019-09-26T15:38:33.401Z",
    "numberOfPayments": 10,
    "payeeDetails": {
      "accountIdentifications": [
        {
          "identification": "123456",
          "type": "["
        }
      ],
      "name": "Bojack Horseman",
      "address": {
        "addressLines": [
          "1 Downing St"
        ],
        "addressType": "BUSINESS",
        "buildingNumber": "123",
        "country": "GB",
        "county": "London",
        "department": "",
        "postCode": "A12 3BC",
        "streetName": "123 Test Street",
        "subDepartment": "",
        "townName": "London"
      },
      "merchantCategoryCode": "5462",
      "merchantId": "12345678"
    },
    "payer": {
      "accountIdentifications": [
        {
          "identification": "123456",
          "type": "["
        }
      ],
      "address": {
        "addressLines": [
          "1 Downing St"
        ],
        "addressType": "BUSINESS",
        "buildingNumber": "123",
        "country": "GB",
        "county": "London",
        "department": "",
        "postCode": "A12 3BC",
        "streetName": "123 Test Street",
        "subDepartment": "",
        "townName": "London"
      },
      "name": "Bojack Horseman"
    },
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d1",
    "previousPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "previousPaymentDateTime": "",
    "priority": "",
    "purpose": "",
    "reference": "myreference",
    "scheduledPaymentDateTime": "",
    "scheduledPaymentType": "",
    "status": "PENDING",
    "statusDetails": {
      "status": "PENDING",
      "statusReason": "PENDING",
      "statusReasonDescription": "",
      "statusUpdateDate": "2019-09-26T15:38:33.401Z",
      "multiAuthorisationStatus": {
        "status": "AWAITING_FURTHER_AUTHORIZATION",
        "numberOfAuthorisationRequired": 2,
        "numberOfAuthorisationReceived": 1,
        "lastUpdatedDateTime": "2019-09-26T15:38:33.408Z",
        "expirationDateTime": "2019-09-26T14:20:14.393Z"
      }
    }
  }
}

Responses

Status	Meaning	Description	Schema
201	Created	A successful response, returning a PaymentResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 201

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	PaymentResponse	none
»» amount	integer(decimal)	Deprecated. The amount of the Payment.
»» amountDetails	Amount	none
»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»» bulkAmountSum	integer(decimal)	The sum of all bulk payments
»» chargeDetails	[ChargeDetails]	The array of ChargeDetails, used to provide any additional fee if there is any of the payment. Mostly populated for International Payments.
»»» chargeAmount	Amount	none
»»» chargeTo	string	Not used.
»»» chargeType	string	The type of charge for the payment.
»» createdAt	string	The date and time the Payment was created.
»» currency	string	Deprecated. The currency of the Payment.
»» currencyOfTransfer	string	Used for International Payments. The currency used to transfer the money from source bank.
»» exchangeRate	ExchangeRateInformationResponse	An object containing exchange rate information.
»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»» finalPaymentAmount	Amount	none
»» finalPaymentDateTime	string	The date of the final payment in a sequence.
»» firstPaymentAmount	Amount	none
»» firstPaymentDateTime	string	The date of the first payment in a sequence.
»» frequency	FrequencyRequest	none
»»» type Mandatory	FrequencyEnumExtended	See payment frequency for more information.
»»» executionDay	integer	Conditional. See payment frequency for more information.
»»» intervalMonth	integer	Conditional. See payment frequency for more information.
»»» intervalWeek	integer	Conditional. See payment frequency for more information.
»» id	string	The id of the Payment.
»» institutionConsentId	string	The banks identification for the consent.
»» nextPaymentAmount	Amount	none
»» nextPaymentDateTime	string	The date of the next payment in a sequence.
»» numberOfPayments	integer	The number of payments in a sequence.
»» payeeDetails	Payee	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payee` bank account
»»»» identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
»»»» type Mandatory	AccountIdentificationType	See Account Identifications Types for more information on each type
»»» name Mandatory	string	The account holder name of the beneficiary
»»» address	Address	none
»»»» addressLines	[string]	The address lines for the address Mandatory for `INTERNATIONAL` payment types
»»»» addressType	AddressTypeEnum	The type of the Address.
»»»» buildingNumber	string	The building number for the address
»»»» country	string	The 2-letter country code for the address Mandatory for `INTERNATIONAL` payment types Some banks in the UK require this to be specified for `DOMESTIC` payment types. In this case, `country` should be set to "GB"
»»»» county	[string]	The county name for the address
»»»» department	string	The department name for the address
»»»» postCode	string	The post code for the address
»»»» streetName	string	The street name for the address Mandatory for `INTERNATIONAL` payment types
»»»» subDepartment	string	The sub department name for the address
»»»» townName	string	The town name for the address Mandatory for `INTERNATIONAL` payment types
»»» merchantCategoryCode	string	The category code of the merchant in case the `Payee` is a business
»»» merchantId	string	A merchant ID is a unique code provided by the payment processor to the merchant
»» payer	Payer	none
»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payer` bank account
»»» address	Address	none
»»» name	string	The account holder name of the Payer
»» paymentIdempotencyId	string	The Payment IdempotencyId
»» paymentLifecycleId	string	The Payment LifecycleId
»» previousPaymentAmount	Amount	none
»» previousPaymentDateTime	string	The date of the previous payment in a sequence.
»» priority	string	The priority for the Payment.
»» purpose	string	The purpose for the Payment.
»» reference	string	A reference for the Payment.
»» scheduledPaymentDateTime	string	The scheduled payment date and time.
»» scheduledPaymentType	string	The type of scheduled payment.
»» status	PaymentStatus	The status of the Payment.
»» statusDetails	PaymentStatusDetails	none
»»» status	PaymentStatus	The status of the Payment.
»»» statusReason	string	The status reason.
»»» statusReasonDescription	string	The description of the status reason.
»»» statusUpdateDate	string	The date and time the status was updated.
»»» multiAuthorisationStatus	MultiAuthorisation	none
»»»» status	string	The status of the multi authorisation. Possible values are AUTHORIZED, AWAITING_FURTHER_AUTHORIZATION, REJECTED and UNKNOWN.
»»»» numberOfAuthorisationRequired	integer	The number of authorisations required to authorise the consent.
»»»» numberOfAuthorisationReceived	integer	The number of authorisations that have been completed.
»»»» lastUpdatedDateTime	string	The time at which the multi authorisation was last updated.
»»»» expirationDateTime	string	The time at which the multi authorisation expires if there is one.

Enumerated Values

Property	Value
type	DAILY
type	EVERY_WORKING_DAY
type	CALENDAR_DAY
type	WEEKLY
type	EVERY_TWO_WEEKS
type	MONTHLY
type	EVERY_TWO_MONTHS
type	QUARTERLY
type	SEMIANNUAL
type	ANNUAL
type	SORT_CODE
type	ACCOUNT_NUMBER
type	IBAN
type	BBAN
type	BIC
type	PAN
type	MASKED_PAN
type	MSISDN
type	BSB
type	NCC
type	ABA
type	ABA_WIRE
type	ABA_ACH
type	EMAIL
addressType	BUSINESS
addressType	CORRESPONDENCE
addressType	DELIVERY_TO
addressType	MAIL_TO
addressType	PO_BOX
addressType	POSTAL
addressType	RESIDENTIAL
addressType	STATEMENT
addressType	UNKNOWN
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE

Get Payment Details

Request

curl -X GET https://api.yapily.com/payments/{payment-id}/details \
  -H 'Accept: application/json' \
  -H 'x-yapily-api-version: 1.0' \
  -H 'consent: string' \
  -H 'psu-id: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-ip-address: string' \
  -H 'Authorization: Basic B64(API_KEY:API_SECRET)'

GET /payments/{payment-id}/details

Used to the get the payment details of a payment. The response of this endpoint is a list of Payment Responses.

Parameters

Name	In	Type	Description
x-yapily-api-version Mandatory	header	string	Determines the API version to use. Valid values are 1.0 or 2.0-ALPHA.
payment-id Mandatory	path	string	The ID of the Payment
consent Mandatory	header	string	The Consent-Token obtained from the original authorisation.
psu-id	header	string	Conditional. Represents the user's login ID for the `Institution` to a personal account. See PSU identifiers to see if this is required.
psu-corporate-id	header	string	Conditional. Represents the user's login ID for the Institution to a business account. See PSU identifiers to see if this is required.
psu-ip-address	header	string	Conditional. The IP address of the PSU. See PSU identifiers to see if this is required.
raw	query	boolean	Raw parameter available for debugging purposes

Example responses

200 Response

{
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "data": {
    "payments": [
      {
        "amount": "10.00",
        "amountDetails": {
          "amount": 10,
          "currency": "GBP"
        },
        "bulkAmountSum": 100,
        "chargeDetails": [
          {
            "chargeAmount": null,
            "chargeTo": null,
            "chargeType": null
          }
        ],
        "createdAt": "2019-09-26T15:38:33.401Z",
        "currency": "GBP",
        "currencyOfTransfer": "",
        "exchangeRate": {
          "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
        },
        "finalPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "finalPaymentDateTime": "2019-09-26T15:38:33.401Z",
        "firstPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "firstPaymentDateTime": "2019-09-26T15:38:33.401Z",
        "frequency": {
          "type": "[",
          "executionDay": 1,
          "intervalMonth": 1,
          "intervalWeek": 1
        },
        "id": "pv3-c8eece27-eb1a-4c27-a13c-2f805703dab2",
        "institutionConsentId": "sdp-1-aa9d0941-43ff-4abb-8129-4d56b620b8ee",
        "nextPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "nextPaymentDateTime": "2019-09-26T15:38:33.401Z",
        "numberOfPayments": 10,
        "payeeDetails": {
          "accountIdentifications": [
            null
          ],
          "name": "Bojack Horseman",
          "address": {},
          "merchantCategoryCode": "5462",
          "merchantId": "12345678"
        },
        "payer": {
          "accountIdentifications": [
            null
          ],
          "address": {},
          "name": "Bojack Horseman"
        },
        "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
        "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d1",
        "previousPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "previousPaymentDateTime": "",
        "priority": "",
        "purpose": "",
        "reference": "myreference",
        "scheduledPaymentDateTime": "",
        "scheduledPaymentType": "",
        "status": "PENDING",
        "statusDetails": {
          "status": "[",
          "statusReason": "PENDING",
          "statusReasonDescription": "",
          "statusUpdateDate": "2019-09-26T15:38:33.401Z",
          "multiAuthorisationStatus": {}
        }
      }
    ]
  }
}

Responses

Status	Meaning	Description	Schema
200	OK	A successful response, returning a PaymentResponse.	Inline
400	Bad Request	Bad Request. Returned if the optional raw parameter is not a valid boolean or if the consent token is not sent	ApiResponseError
401	Unauthorized	Either authentication credentials were not supplied, or they were invalid.	ApiResponseError
403	Forbidden	Not Found. The Consent-Token was not valid or has expired	ApiResponseError
424	Failed Dependency	Failed Dependency. Unable to complete request to the institution.	ApiResponseError

Response Schema

Status Code 200

Name	Type	Description
» meta	ResponseMeta	An object containing a tracingId of the request
»» tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries
» data	PaymentResponses	none
»» payments	[PaymentResponse]	An array of PaymentResponses.
»»» amount	integer(decimal)	Deprecated. The amount of the Payment.
»»» amountDetails	Amount	none
»»»» amount Mandatory	integer(float)	Mandatory. The monetary value
»»»» currency Mandatory	string	Mandatory. The ISO 4217 currency code
»»» bulkAmountSum	integer(decimal)	The sum of all bulk payments
»»» chargeDetails	[ChargeDetails]	The array of ChargeDetails, used to provide any additional fee if there is any of the payment. Mostly populated for International Payments.
»»»» chargeAmount	Amount	none
»»»» chargeTo	string	Not used.
»»»» chargeType	string	The type of charge for the payment.
»»» createdAt	string	The date and time the Payment was created.
»»» currency	string	Deprecated. The currency of the Payment.
»»» currencyOfTransfer	string	Used for International Payments. The currency used to transfer the money from source bank.
»»» exchangeRate	ExchangeRateInformationResponse	An object containing exchange rate information.
»»»» exchangeRateExpiryDate	string	The expiry rate of the exchange rate.
»»» finalPaymentAmount	Amount	none
»»» finalPaymentDateTime	string	The date of the final payment in a sequence.
»»» firstPaymentAmount	Amount	none
»»» firstPaymentDateTime	string	The date of the first payment in a sequence.
»»» frequency	FrequencyRequest	none
»»»» type Mandatory	FrequencyEnumExtended	See payment frequency for more information.
»»»» executionDay	integer	Conditional. See payment frequency for more information.
»»»» intervalMonth	integer	Conditional. See payment frequency for more information.
»»»» intervalWeek	integer	Conditional. See payment frequency for more information.
»»» id	string	The id of the Payment.
»»» institutionConsentId	string	The banks identification for the consent.
»»» nextPaymentAmount	Amount	none
»»» nextPaymentDateTime	string	The date of the next payment in a sequence.
»»» numberOfPayments	integer	The number of payments in a sequence.
»»» payeeDetails	Payee	none
»»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payee` bank account
»»»»» identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
»»»»» type Mandatory	AccountIdentificationType	See Account Identifications Types for more information on each type
»»»» name Mandatory	string	The account holder name of the beneficiary
»»»» address	Address	none
»»»»» addressLines	[string]	The address lines for the address Mandatory for `INTERNATIONAL` payment types
»»»»» addressType	AddressTypeEnum	The type of the Address.
»»»»» buildingNumber	string	The building number for the address
»»»»» country	string	The 2-letter country code for the address Mandatory for `INTERNATIONAL` payment types Some banks in the UK require this to be specified for `DOMESTIC` payment types. In this case, `country` should be set to "GB"
»»»»» county	[string]	The county name for the address
»»»»» department	string	The department name for the address
»»»»» postCode	string	The post code for the address
»»»»» streetName	string	The street name for the address Mandatory for `INTERNATIONAL` payment types
»»»»» subDepartment	string	The sub department name for the address
»»»»» townName	string	The town name for the address Mandatory for `INTERNATIONAL` payment types
»»»» merchantCategoryCode	string	The category code of the merchant in case the `Payee` is a business
»»»» merchantId	string	A merchant ID is a unique code provided by the payment processor to the merchant
»»» payer	Payer	none
»»»» accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payer` bank account
»»»» address	Address	none
»»»» name	string	The account holder name of the Payer
»»» paymentIdempotencyId	string	The Payment IdempotencyId
»»» paymentLifecycleId	string	The Payment LifecycleId
»»» previousPaymentAmount	Amount	none
»»» previousPaymentDateTime	string	The date of the previous payment in a sequence.
»»» priority	string	The priority for the Payment.
»»» purpose	string	The purpose for the Payment.
»»» reference	string	A reference for the Payment.
»»» scheduledPaymentDateTime	string	The scheduled payment date and time.
»»» scheduledPaymentType	string	The type of scheduled payment.
»»» status	PaymentStatus	The status of the Payment.
»»» statusDetails	PaymentStatusDetails	none
»»»» status	PaymentStatus	The status of the Payment.
»»»» statusReason	string	The status reason.
»»»» statusReasonDescription	string	The description of the status reason.
»»»» statusUpdateDate	string	The date and time the status was updated.
»»»» multiAuthorisationStatus	MultiAuthorisation	none
»»»»» status	string	The status of the multi authorisation. Possible values are AUTHORIZED, AWAITING_FURTHER_AUTHORIZATION, REJECTED and UNKNOWN.
»»»»» numberOfAuthorisationRequired	integer	The number of authorisations required to authorise the consent.
»»»»» numberOfAuthorisationReceived	integer	The number of authorisations that have been completed.
»»»»» lastUpdatedDateTime	string	The time at which the multi authorisation was last updated.
»»»»» expirationDateTime	string	The time at which the multi authorisation expires if there is one.

Enumerated Values

Property	Value
type	DAILY
type	EVERY_WORKING_DAY
type	CALENDAR_DAY
type	WEEKLY
type	EVERY_TWO_WEEKS
type	MONTHLY
type	EVERY_TWO_MONTHS
type	QUARTERLY
type	SEMIANNUAL
type	ANNUAL
type	SORT_CODE
type	ACCOUNT_NUMBER
type	IBAN
type	BBAN
type	BIC
type	PAN
type	MASKED_PAN
type	MSISDN
type	BSB
type	NCC
type	ABA
type	ABA_WIRE
type	ABA_ACH
type	EMAIL
addressType	BUSINESS
addressType	CORRESPONDENCE
addressType	DELIVERY_TO
addressType	MAIL_TO
addressType	PO_BOX
addressType	POSTAL
addressType	RESIDENTIAL
addressType	STATEMENT
addressType	UNKNOWN
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE
status	PENDING
status	FAILED
status	DECLINED
status	COMPLETED
status	COMPLETED_SETTLEMENT_IN_PROCESS
status	EXPIRED
status	UNKNOWN
status	ACTIVE
status	INACTIVE

Schemas

AccessToken

{
  "accessToken": "",
  "authorisedAt": "",
  "expiresIn": 400,
  "refreshToken": "",
  "scope": "",
  "tokenType": ""
}

Properties

Name	Type	Description
accessToken	string	The access token that gives access to the resource server.
authorisedAt	string	The date and time the access token was granted.
expiresIn	integer	How long until the accessToken expires
refreshToken	string	The refreshToken can be used to get a new accessToken once it expires.
scope	string	The Oauth2 scope of the accessToken.
tokenType	string	The type of the token, e.g. 'Bearer'

Account

{
  "accountBalances": [
    {
      "balanceAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "creditLineIncluded": true,
      "creditLines": [
        {
          "creditLineAmount": {
            "amount": null,
            "currency": null
          },
          "type": "AVAILABLE"
        }
      ],
      "dateTime": "2020-09-21T16:35:55Z",
      "type": "CLOSING_AVAILABLE"
    }
  ],
  "accountIdentifications": [
    {
      "identification": "123456",
      "type": "SORT_CODE"
    }
  ],
  "accountNames": [
    {
      "name": "name"
    }
  ],
  "accountType": "CASH_TRADING",
  "balance": 5313.4,
  "currency": "GBP",
  "description": "HSBC ADVANCE",
  "details": "",
  "id": "aadn1pyst5ka1o1x8gkklori09n60rtgcr5t",
  "nickname": "Personal",
  "type": "Personal - Current",
  "usageType": "PERSONAL"
}

Properties

Name	Type	Description
accountBalances	[AccountBalance]	An array of AccountBalance objects.
accountIdentifications	[AccountIdentification]	An array of AccountIdentification objects.
accountNames	[AccountName]	The array of AccountName objects.
accountType	AccountType	The type of account.
balance	integer(decimal)	The balance of the account.
currency	string	The ISO 4217 Currency code.
description	string	The product name as defined by the financial institution for this account.
details	string	The specifications that might be provided by the institution e.g. characteristics of the account or characteristics of the relevant card
id	string	The account Id returned by the Institution if present. This is simply a direct mapping to the unique ID provided by the bank for all of the accounts a user has provided access to via a consent, and is then required as a parameter the bank will recognise for all subsequent requests required to pull data related to that specific account (e.g balances, transactions, statements, etc.)
nickname	string	The name of the account as defined by the financial institution or the end user.
type	string	The type of the Account.
usageType	UsageType	The usage type for the account.

AccountAuthorisationRequest

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "accountRequest": {
    "accountIdentifiers": {
      "accountId": "500000000000000000000001",
      "accountIdentification": {
        "identification": null,
        "type": null
      }
    },
    "accountIdentifiersForBalance": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {}
      }
    ],
    "accountIdentifiersForTransaction": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {}
      }
    ],
    "expiresAt": "2018-10-17T15:11:38Z",
    "featureScope": [
      "ACCOUNT_STATEMENT"
    ],
    "psuCorporateId": "",
    "psuId": "",
    "transactionsFrom": "",
    "transactionsTo": ""
  }
}

An object containing the authorisation request information and specific AccountRequest object.

Properties

allOf

Name	Type	Description
anonymous	AuthorisationRequest	Generic properties to define the authorisation to be created

and

Name	Type	Description
anonymous	object	none
» accountRequest	AccountRequest	The specific `AccountRequest` information for the Authorisation.

AccountBalance

{
  "balanceAmount": {
    "amount": 10,
    "currency": "GBP"
  },
  "creditLineIncluded": true,
  "creditLines": [
    {
      "creditLineAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "type": "AVAILABLE"
    }
  ],
  "dateTime": "2020-09-21T16:35:55Z",
  "type": "CLOSING_AVAILABLE"
}

An object containing the OBBalanceType1Code and Amount.

Properties

Name	Type	Description
balanceAmount	Amount	none
creditLineIncluded	boolean	Indicates whether or not the credit line is included in the balance.
creditLines	[CreditLine]	An array of CreditLine objects.
dateTime	string	The timestamp of the last change of the balance amount.
type	AccountBalanceType	The OBBalanceType1Code balance type. CLOSING_AVAILABLE - Closing balance of amount of money that is at the disposal of the account owner on the date specified CLOSING_BOOKED - Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. CLOSING_CLEARED - Closing balance of amount of money that is cleared on the date specified. EXPECTED - Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. FORWARD_AVAILABLE - Forward available balance of money that is at the disposal of the account owner on the date specified. INFORMATION - Balance for informational purposes. INTERIM_AVAILABLE - Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_BOOKED - Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_CLEARED - Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. OPENING_AVAILABLE - Opening balance of amount of money that is at the disposal of the account owner on the date specified. OPENING_BOOKED - Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. OPENING_CLEARED - Opening balance of amount of money that is cleared on the date specified. PREVIOUSLY_CLOSED_BOOKED - Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date. AUTHORISED - Balance of the account minus any authorised transactions not yet cleared. OTHER - Used when an unrecognised enum is parsed UNKNOWN - Used as a Yapily default

AccountBalanceType

"CLOSING_AVAILABLE"

The OBBalanceType1Code balance type.

CLOSING_AVAILABLE - Closing balance of amount of money that is at the disposal of the account owner on the date specified
CLOSING_BOOKED - Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period.
CLOSING_CLEARED - Closing balance of amount of money that is cleared on the date specified.
EXPECTED - Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted.
FORWARD_AVAILABLE - Forward available balance of money that is at the disposal of the account owner on the date specified.
INFORMATION - Balance for informational purposes.
INTERIM_AVAILABLE - Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified.
INTERIM_BOOKED - Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified.
INTERIM_CLEARED - Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day.
OPENING_AVAILABLE - Opening balance of amount of money that is at the disposal of the account owner on the date specified.
OPENING_BOOKED - Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report.
OPENING_CLEARED - Opening balance of amount of money that is cleared on the date specified.
PREVIOUSLY_CLOSED_BOOKED - Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date.
AUTHORISED - Balance of the account minus any authorised transactions not yet cleared.
OTHER - Used when an unrecognised enum is parsed
UNKNOWN - Used as a Yapily default

Enumerated Values

Value
CLOSING_AVAILABLE
CLOSING_BOOKED
CLOSING_CLEARED
EXPECTED
FORWARD_AVAILABLE
INFORMATION
INTERIM_AVAILABLE
INTERIM_BOOKED
INTERIM_CLEARED
OPENING_AVAILABLE
OPENING_BOOKED
OPENING_CLEARED
PREVIOUSLY_CLOSED_BOOKED
AUTHORISED
OTHER
UNKNOWN

AccountIdentification

{
  "identification": "123456",
  "type": "SORT_CODE"
}

Properties

Name	Type	Description
identification Mandatory	string	The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values.
type Mandatory	AccountIdentificationType	Used to describe the format of the account. See Account Identification Combinations for more information on when to specify each type.

AccountIdentificationType

"SORT_CODE"

See Account Identifications Types for more information on each type

Enumerated Values

Value
SORT_CODE
ACCOUNT_NUMBER
IBAN
BBAN
BIC
PAN
MASKED_PAN
MSISDN
BSB
NCC
ABA
ABA_WIRE
ABA_ACH
EMAIL

AccountInfo

{
  "accountId": "500000000000000000000001",
  "accountIdentification": {
    "identification": "123456",
    "type": "SORT_CODE"
  }
}

Properties

Name	Type	Description
accountId	string	Mandatory. The bank's account identifier for the account
accountIdentification	AccountIdentification	Mandatory. The AccountIdentification object for the user's account identifications for the account.

AccountName

{
  "name": "name"
}

Properties

Name	Type	Description
name	string	One of the names for the account.

AccountRequest

{
  "accountIdentifiers": {
    "accountId": "500000000000000000000001",
    "accountIdentification": {
      "identification": "123456",
      "type": "SORT_CODE"
    }
  },
  "accountIdentifiersForBalance": [
    {
      "accountId": "500000000000000000000001",
      "accountIdentification": {
        "identification": "123456",
        "type": "SORT_CODE"
      }
    }
  ],
  "accountIdentifiersForTransaction": [
    {
      "accountId": "500000000000000000000001",
      "accountIdentification": {
        "identification": "123456",
        "type": "SORT_CODE"
      }
    }
  ],
  "expiresAt": "2018-10-17T15:11:38Z",
  "featureScope": [
    "ACCOUNT_STATEMENT"
  ],
  "psuCorporateId": "",
  "psuId": "",
  "transactionsFrom": "",
  "transactionsTo": ""
}

Properties

Name	Type	Description
accountIdentifiers	AccountInfo	Conditional. Used to create a request for the account information (IBAN) for the account specified. Once the user authorises the request, only the `accountId`, `accountIdentification`, the `currency` of the account and the `usageType` can be obtained by executing GET Accounts. In order to access the balance or transactions of the account, you must create another authorisation providing `accountIdentifiersForBalance` and `accountIdentifiersForTransaction`. Used exclusively by an `Institution` connected through the CBI Globe Gateway.
accountIdentifiersForBalance	[AccountInfo]	Conditional. Used to create a request for the balance of the account specified. Once the user authorises the request, only the balance can be obtained by executing GET Account Balances. This can be specified in conjunction with `accountIdentifiersForTransaction` to generate a `Consent` that can both access the accounts balance and transactions. Used exclusively by an `Institution` connected through the CBI Globe Gateway.
accountIdentifiersForTransaction	[AccountInfo]	Conditional. Used to create a request for the transactions of the account specified. Once the user authorises the request, only the transactions can be obtained by executing GET Account Transactions. This can be specified in conjunction with `accountIdentifiersForBalance` to generate a `Consent` that can both access the accounts balance and transactions. Used exclusively by an `Institution` connected through the CBI Globe Gateway.
expiresAt	string	Optional. Used to set a hard date for when the user's associated `Consent` will expire. Note: If this supported by the bank, specifying this is property is opting out of having a long-lived consent that can be perpetually re-authorised by the user. This will add an `expiresAt` field on the `Consent` object which will render it unusable after this date. Note: This is not supported by every `Institution`. In such case, the request will not fail but the property will be ignored and the created `Consent` will not have an expiry date.
featureScope	[string]	Optional. Used to granularly specify the set of features that the user will give their consent for when requesting access to their account information. Depending on the `Institution`, this may also populate a consent screen which list these scopes before the user authorises. This endpoint accepts allow all Financial Data Features that the `Institution` supports. To find out which scopes an `Institution` supports, check GET Institution.
psuCorporateId	string	Deprecated.
psuId	string	Deprecated.
transactionsFrom	string(date-time)	Optional. Used to specify the lower bound on when to pull transaction. This should be declared when accessing transaction older than 90 days
transactionsTo	string(date-time)	Optional. Used to specify the upper bound on when to pull transaction.

AccountStatement

{
  "creationDateTime": "2017-02-01T00:00:00Z",
  "endDateTime": "2017-02-01T00:00:00Z",
  "id": "",
  "startDateTime": "2017-02-01T00:00:00Z"
}

Properties

Name	Type	Description
creationDateTime	string	The date and time the statement was created.
endDateTime	string	The date and time for the end of the period of the statement.
id	string	The identifer of the statement.
startDateTime	string	The date and time for the start of the period of the statement.

AccountType

"CASH_TRADING"

The type of account.

Enumerated Values

Value
CASH_TRADING
CASH_INCOME
CASH_PAYMENT
CHARGE_CARD
CHARGES
COMMISSION
CREDIT_CARD
CURRENT
E_MONEY
LIMITED_LIQUIDITY_SAVINGS_ACCOUNT
LOAN
MARGINAL_LENDING
MONEY_MARKET
MORTGAGE
NON_RESIDENT_EXTERNAL
OTHER
OVERDRAFT
OVERNIGHT_DEPOSIT
PREPAID_CARD
SALARY
SAVINGS
SETTLEMENT
TAX
UNKNOWN

Address

{
  "addressLines": [
    "1 Downing St"
  ],
  "addressType": "BUSINESS",
  "buildingNumber": "123",
  "country": "GB",
  "county": "London",
  "department": "",
  "postCode": "A12 3BC",
  "streetName": "123 Test Street",
  "subDepartment": "",
  "townName": "London"
}

Properties

Name	Type	Description
addressLines	[string]	The address lines for the address Mandatory for `INTERNATIONAL` payment types
addressType	AddressTypeEnum	The type of the address
buildingNumber	string	The building number for the address
country	string	The 2-letter country code for the address Mandatory for `INTERNATIONAL` payment types Some banks in the UK require this to be specified for `DOMESTIC` payment types. In this case, `country` should be set to "GB"
county	[string]	The county name for the address
department	string	The department name for the address
postCode	string	The post code for the address
streetName	string	The street name for the address Mandatory for `INTERNATIONAL` payment types
subDepartment	string	The sub department name for the address
townName	string	The town name for the address Mandatory for `INTERNATIONAL` payment types

AddressDetails

{
  "addressLine": "123 Test Street, Test, AB1 2DC"
}

Properties

Name	Type	Description
addressLine	string	The address line for the address

AddressTypeEnum

"BUSINESS"

The type of the Address.

Enumerated Values

Value
BUSINESS
CORRESPONDENCE
DELIVERY_TO
MAIL_TO
PO_BOX
POSTAL
RESIDENTIAL
STATEMENT
UNKNOWN

Amount

{
  "amount": 10,
  "currency": "GBP"
}

Properties

Name	Type	Description
amount Mandatory	integer(float)	Mandatory. The monetary value
currency Mandatory	string	Mandatory. The ISO 4217 currency code

AmountFrequency

"DAILY"

Used exclusively with Variable Recurring Payments to define the frequency of the amount.

Enumerated Values

Value
DAILY
WEEKLY
MONTHLY
YEARLY

ApiError

{
  "code": 401,
  "institutionError": {
    "errorMessage": "{\"Code\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Errors\":[{\"ErrorCode\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Field\":\"x-jws-signature\"}]}",
    "httpStatusCode": 100
  },
  "message": "Full authentication is required to access this resource",
  "source": "YAPILY",
  "status": "BAD_REQUEST",
  "tracingId": "e7b01315-cbc5-4d0b-91e8-4f77cb1a3253"
}

An object containing further information about the error that occurred.

Properties

Name	Type	Description
code	integer	The HTTP Status code
institutionError	InstitutionError	The error message provided by the `Institution`
message	string	The error message provided by Yapily
source	string	The source of the error
status	HttpStatus	The HTTP Status enumeration
tracingId	string	The unique identifier for the request. Used to trace the request in logging enquiries

ApiListResponse

{
  "data": [],
  "links": [
    {
      "name": "",
      "value": ""
    }
  ],
  "meta": {
    "count": 100,
    "pagination": {
      "next": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100
      },
      "self": {
        "before": "",
        "cursor": "",
        "from": "",
        "limit": 100,
        "offset": 100,
        "sort": "DATE_ASCENDING(\"date\")"
      },
      "totalCount": 100
    },
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "raw": [
    {
      "duration": "",
      "headers": [
        {
          "name": "",
          "value": ""
        }
      ],
      "request": {
        "method": "",
        "requestInstant": "",
        "templateUri": "",
        "url": ""
      },
      "result": "",
      "resultCode": 100
    }
  ]
}

Properties

Name	Type	Description
data	string	An array of objects, depending on the endpoint
links	[Map]	none
meta	ResponseListMeta	An object containing a tracingId of the request
raw	[RawResponse]	[An object returned when the raw parameter is sent]

ApiResponse

{
  "data": "{}",
  "links": [
    {
      "name": "",
      "value": ""
    }
  ],
  "meta": {
    "tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
  },
  "raw": [
    {
      "duration": "",
      "headers": [
        {
          "name": "",
          "value": ""
        }
      ],
      "request": {
        "method": "",
        "requestInstant": "",
        "templateUri": "",
        "url": ""
      },
      "result": "",
      "resultCode": 100
    }
  ]
}

Properties

Name	Type	Description
data	string	An object, depending on the endpoint
links	[Map]	none
meta	ResponseMeta	An object containing a tracingId of the request
raw	[RawResponse]	[An object returned when the raw parameter is sent]

ApiResponseError

{
  "error": {
    "code": 401,
    "institutionError": {
      "errorMessage": "{\"Code\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Errors\":[{\"ErrorCode\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Field\":\"x-jws-signature\"}]}",
      "httpStatusCode": 100
    },
    "message": "Full authentication is required to access this resource",
    "source": "YAPILY",
    "status": "BAD_REQUEST",
    "tracingId": "e7b01315-cbc5-4d0b-91e8-4f77cb1a3253"
  },
  "monitoring": [
    {
      "lastTested": "",
      "resourceEndpoint": "",
      "span": "",
      "status": "UP"
    }
  ],
  "raw": [
    {
      "duration": "",
      "headers": [
        {
          "name": "",
          "value": ""
        }
      ],
      "request": {
        "method": "",
        "requestInstant": "",
        "templateUri": "",
        "url": ""
      },
      "result": "",
      "resultCode": 100
    }
  ]
}

Properties

Name	Type	Description
error	ApiError	The error object contains additional information about the error.
monitoring	[MonitoringEndpointStatus]	An endpoint for mointoring.
raw	[RawResponse]	The raw response returned from the `Institution`.

Application

{
  "active": true,
  "authCallbacks": [
    "https://test.example.com/callback"
  ],
  "created": "2020-09-09T10:31:53.968+0000",
  "institutions": [
    {
      "countries": [
        {
          "countryCode2": "GB",
          "displayName": "United Kingdom"
        }
      ],
      "credentialsType": "OAUTH1",
      "environmentType": "SANDBOX",
      "features": [
        "INITIATE_PRE_AUTHORISATION"
      ],
      "fullName": "Yapily Mock Bank",
      "id": "yapily-mock",
      "media": [
        {
          "source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
          "type": "icon"
        }
      ],
      "name": "Yapily Mock"
    }
  ],
  "media": [
    {
      "source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
      "type": "icon"
    }
  ],
  "name": "My App 6238",
  "updated": "2020-09-09T10:31:53.968+0000",
  "uuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a"
}

Properties

Name	Type	Description
active	boolean	Whether the `Application` is active or not
authCallbacks	[string]	A list of callbacks configured for the `Application`.
created	string	The date the `Application` was created.
institutions	[Institution]	[An object that represents an institution.]
media	[Media]	[An object containing media information such as an icon.]
name	string	The friendly name of the `Application`.
updated	string	The date the `Application` was last updated.
uuid	string	The identifier of the `Application`.

ApplicationCallback

{
  "authCallbackURL": "http://tpp.domain/callback"
}

Properties

Name	Type	Description
authCallbackURL	string	The callback URL associated with the Application.

AuthorisationRequest

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": []
}

Generic properties to define the authorisation to be created

Properties

Name	Type	Description
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 `applicationUserId` or `userUuid` must be specified.
userUuid	string	Conditional. The reference to the `User` using the Yapily generated UUID. The `userUuid` must find an existing `User` object otherwise the request will fail. Either the `applicationUserId` or `userUuid` must be specified.
institutionId Mandatory	string	The reference to the `Institution` which identifies which institution the authorisation request is sent to.
callback	string	The server to redirect the user to after the user complete the authorisation at the `Institution`. See Using a callback (Optional) for more information.
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.
forwardParameters	[string]	Not currently used.

AuthorisationRequestResponse

{
  "applicationUserId": "bojack@8tees.com",
  "authorizedAt": "2020-09-13T15:57:46.450Z",
  "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
  "createdAt": "2020-09-13T15:57:46.450Z",
  "expiresAt": "2020-09-13T15:57:46.450Z",
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
  "institutionId": "yapily-mock",
  "referenceId": "myuserreference",
  "state": "754f6022f47548b99284f3f1993e050e",
  "status": "AWAITING_AUTHORIZATION",
  "timeToExpire": "PT-375H-40M-21.397S",
  "transactionFrom": "2020-09-13T15:57:46.450Z",
  "transactionTo": "2020-09-13T15:57:46.450Z",
  "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
  "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
  "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
}

A response object containing the result of the authorisation.

Properties

allOf

Name	Type	Description
anonymous	Consent	The `Consent` object.

and

Name	Type	Description
anonymous	object	none
» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

AuthorisationStatus

"AWAITING_AUTHORIZATION"

Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed.

AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object.
AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl.
AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED.
AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED.
AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user.
AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent.
CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state *.
EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state *.
FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data.
PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request.
REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state *.
REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state *.
UNKNOWN - Used as a default

Enumerated Values

Value
AWAITING_AUTHORIZATION
AWAITING_FURTHER_AUTHORIZATION
AWAITING_RE_AUTHORIZATION
AWAITING_DECOUPLED_AUTHORIZATION
AUTHORIZED
CONSUMED
REJECTED
REVOKED
FAILED
EXPIRED
UNKNOWN
INVALID
AWAITING_PRE_AUTHORIZATION
PRE_AUTHORIZED

Balance

{
  "balanceAmount": {
    "amount": 10,
    "currency": "GBP"
  },
  "type": "CLOSING_AVAILABLE"
}

An object containing the amount and balance type.

Properties

Name	Type	Description
balanceAmount	Amount	none
type	AccountBalanceType	The OBBalanceType1Code balance type. CLOSING_AVAILABLE - Closing balance of amount of money that is at the disposal of the account owner on the date specified CLOSING_BOOKED - Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period. CLOSING_CLEARED - Closing balance of amount of money that is cleared on the date specified. EXPECTED - Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted. FORWARD_AVAILABLE - Forward available balance of money that is at the disposal of the account owner on the date specified. INFORMATION - Balance for informational purposes. INTERIM_AVAILABLE - Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_BOOKED - Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified. INTERIM_CLEARED - Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. OPENING_AVAILABLE - Opening balance of amount of money that is at the disposal of the account owner on the date specified. OPENING_BOOKED - Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report. OPENING_CLEARED - Opening balance of amount of money that is cleared on the date specified. PREVIOUSLY_CLOSED_BOOKED - Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date. AUTHORISED - Balance of the account minus any authorised transactions not yet cleared. OTHER - Used when an unrecognised enum is parsed UNKNOWN - Used as a Yapily default

Balances

{
  "balances": [
    {
      "balanceAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "creditLineIncluded": true,
      "creditLines": [
        {
          "creditLineAmount": {
            "amount": null,
            "currency": null
          },
          "type": "AVAILABLE"
        }
      ],
      "dateTime": "2020-09-21T16:35:55Z",
      "type": "CLOSING_AVAILABLE"
    }
  ],
  "mainBalanceAmount": {
    "amount": 10,
    "currency": "GBP"
  }
}

Properties

Name	Type	Description
balances	[AccountBalance]	An array of AccountBalances.
mainBalanceAmount	Amount	none

BulkPaymentAuthorisationRequest

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "paymentRequest": {
    "executionDateTime": "2020-10-17T00:00:00Z",
    "originatorIdentificationNumber": "",
    "payments": [
      {
        "type": "[",
        "amount": {},
        "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
        "payee": {},
        "payer": {},
        "reference": "myreference",
        "paymentDateTime": "2019-12-26T14:42:53Z",
        "contextType": "[",
        "internationalPayment": {},
        "periodicPayment": {},
        "readRefundAccount": true,
        "psuCorporateId": "",
        "psuId": ""
      }
    ]
  }
}

The bulk payment authorisation request.

Properties

allOf

Name	Type	Description
anonymous	AuthorisationRequest	Generic properties to define the authorisation to be created

and

Name	Type	Description
anonymous	object	none
» paymentRequest Mandatory	BulkPaymentRequest	Details of the bulk payment request, including the array of payments.

BulkPaymentRequest

{
  "executionDateTime": "2020-10-17T00:00:00Z",
  "originatorIdentificationNumber": "",
  "payments": [
    {
      "type": "DOMESTIC_PAYMENT",
      "amount": {
        "amount": 10,
        "currency": "GBP"
      },
      "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
      "payee": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "name": "Bojack Horseman",
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "merchantCategoryCode": "5462",
        "merchantId": "12345678"
      },
      "payer": {
        "accountIdentifications": [
          {
            "identification": null,
            "type": null
          }
        ],
        "address": {
          "addressLines": "[Object]",
          "addressType": "[",
          "buildingNumber": "123",
          "country": "GB",
          "county": "London",
          "department": "",
          "postCode": "A12 3BC",
          "streetName": "123 Test Street",
          "subDepartment": "",
          "townName": "London"
        },
        "name": "Bojack Horseman"
      },
      "reference": "myreference",
      "paymentDateTime": "2019-12-26T14:42:53Z",
      "contextType": "BILL",
      "internationalPayment": {
        "chargeBearer": "DEBT",
        "currencyOfTransfer": "GBP",
        "exchangeRateInformation": "string",
        "priority": "NORMAL",
        "purpose": "277ca9eb968948d4b5f8bfa4b6b6b16f"
      },
      "periodicPayment": {
        "frequency": {
          "type": "[",
          "executionDay": 1,
          "intervalMonth": 1,
          "intervalWeek": 1
        },
        "nextPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "nextPaymentDateTime": "2018-01-10T00:00:00Z",
        "finalPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "finalPaymentDateTime": "2021-01-10T00:00:00Z",
        "numberOfPayments": 5
      },
      "readRefundAccount": true,
      "psuCorporateId": "",
      "psuId": ""
    }
  ]
}

Details of the bulk payment request, including the array of payments.

Properties

Name	Type	Description
executionDateTime	string	The date and time the bulk payment request was executed.
originatorIdentificationNumber	string	The identification number of the originator.
payments	[PaymentRequest]	The array of PaymentRequests for the BulkPayment.

BulkUserDelete

{
  "id": "",
  "links": [
    {
      "name": "",
      "value": ""
    }
  ],
  "startedAt": "",
  "status": "IN_PROGRESS"
}

Deprecated.

Properties

Name	Type	Description
id	string	none
links	[Map]	none
startedAt	string	none
status	DeleteTaskStatus	none

BulkUserDeleteDetails

{
  "invalidApplicationUserIds": "",
  "invalidUserUuids": "",
  "users": [
    {
      "creationDate": "2019-05-10T17:36:49.269+0000",
      "deleteStatus": "SUCCESS",
      "id": "c50844cb-1498-44aa-90d1-62eae8cdb3f6",
      "userConsents": [
        {
          "creationDate": "2019-05-10T16:45:43.566+0000",
          "deleteStatus": "SUCCESS",
          "id": "a71fd46f-4144-478e-9a72-dd0d7a1158ab",
          "institutionConsentId": "aac-1cce1cfc-1ab2-4ed6-8062-a0fd6c5c2122",
          "institutionId": "yapily-mock"
        }
      ]
    }
  ]
}

Deprecated.

Properties

Name	Type	Description
invalidApplicationUserIds	[string]	none
invalidUserUuids	[string]	none
users	[UserDeleteResponse]	[An object returned from a successful user delete request]

Categorisation

{
  "categories": [
    "SHOPPING",
    "GROCERIES"
  ],
  "source": "MODEL"
}

Enrichment object provided for merchant and categories enrichment.

Properties

Name	Type	Description
categories	[string]	An array of Strings describing the transaction category.
source	string	The source of the categorisation information.

ChargeDetails

{
  "chargeAmount": {
    "amount": 10,
    "currency": "GBP"
  },
  "chargeTo": "",
  "chargeType": "BULK_PAYMENT"
}

The amount details for the payment.

Properties

Name	Type	Description
chargeAmount	Amount	The Amount of the Charge.
chargeTo	string	Not used.
chargeType	string	The type of charge for the payment.

Consent

{
  "applicationUserId": "bojack@8tees.com",
  "authorizedAt": "2020-09-13T15:57:46.450Z",
  "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
  "createdAt": "2020-09-13T15:57:46.450Z",
  "expiresAt": "2020-09-13T15:57:46.450Z",
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
  "institutionId": "yapily-mock",
  "referenceId": "myuserreference",
  "state": "754f6022f47548b99284f3f1993e050e",
  "status": "AWAITING_AUTHORIZATION",
  "timeToExpire": "PT-375H-40M-21.397S",
  "transactionFrom": "2020-09-13T15:57:46.450Z",
  "transactionTo": "2020-09-13T15:57:46.450Z",
  "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
}

The Consent object.

Properties

Name	Type	Description
applicationUserId	string	Used by you to uniquely identify the user associated with the `Consent` object.
authorizedAt	string	The date the consent was authorized.
consentToken	string	Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header.
createdAt	string	The date and time the `Consent` object was created.
expiresAt	string	Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date).
featureScope	[FeatureEnum]	An array of Features in scope for the consent.
id	string	Used to uniquely identify the Consent object within an application.
institutionId	string	Used to identify the Institution that holds your user's account
referenceId	string	Deprecated. A non unique reference for the `User` tied to the `Consent`.
state	string	The state.
status	AuthorisationStatus	Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed. AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object. AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl. AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED. AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED. AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user. AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent. CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state . EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state . FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data. PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request. REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state . REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state . UNKNOWN - Used as a default
timeToExpire	string	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
transactionFrom	string	Used to specify the date the Consent will start pulling transactions from.
transactionTo	string	Used to specify the date the Consent will stop pulling transactions from.
userUuid	string	Used by Yapily to uniquely identify the user associated with the Consent object.

ConsentAuthCodeRequest

{
  "authCode": "fg67Hj",
  "authState": "f3daec98152e420297cebdd301db6dde"
}

Properties

Name	Type	Description
authCode Mandatory	string	Mandatory. The auth-code.
authState Mandatory	string	Mandatory. The auth-state.

ConsentDeleteResponse

{
  "creationDate": "2019-05-10T16:45:43.566+0000",
  "deleteStatus": "SUCCESS",
  "id": "a71fd46f-4144-478e-9a72-dd0d7a1158ab",
  "institutionConsentId": "aac-1cce1cfc-1ab2-4ed6-8062-a0fd6c5c2122",
  "institutionId": "yapily-mock"
}

An object returned from a UserDeleteResponse

Properties

Name	Type	Description
creationDate	string	The date the `Consent` was created.
deleteStatus	DeleteStatusEnum	The result of the delete operation.
id	string	The id of the `Consent`.
institutionConsentId	string	The bank's identification for the consent.
institutionId	string	The `Institution` the consent was granted for.

ConsentRedirectRequest

{
  "code": "",
  "error": "",
  "state": "",
  "twofoldRedirect": true
}

Properties

Name	Type	Description
code	string	Conditional. The OAuth2 `code` to be exchanged for an AccessToken
error	string	Conditional. If an error occured, this field is populated.
state	string	Mandatory. The state provided in the original request.
twofoldRedirect	boolean	Optional. Causes a double redirect flow for clients setup to use custom redirect flows.

Country

{
  "countryCode2": "GB",
  "displayName": "United Kingdom"
}

The country.

Properties

Name	Type	Description
countryCode2	string	The 2-letter country code for the `Institution`.
displayName	string	The display name of the `Country`.

CreateConsentAccessToken

{
  "accessToken": "access-token",
  "institutionId": "yapily-mock",
  "refreshToken": "",
  "scope": ""
}

Properties

Name	Type	Description
accessToken Mandatory	string	Mandatory. The OAuth2 access token
institutionId Mandatory	string	Mandatory. The institution-id for the institution that provided the token
refreshToken	string	Optional. The OAuth2 refresh token string refresh-token .
scope	string	Optional. The OAuth2 scope

CredentialsType

"OAUTH1"

The type of credentials used.

Enumerated Values

Value
OAUTH1
OAUTH2
OAUTH2_NOSECRET
OAUTH2_SIGNATURE
OPEN_BANKING_UK_MANUAL
OPEN_BANKING_UK_AUTO
OPEN_BANKING_IBM
OPEN_BANKING_AUTO
OPEN_BANKING_AUTO_EMAIL
OPEN_BANKING_MANUAL
API_KEY
OPEN_BANKING_NO_KEY
OPEN_BANKING_NO_TRANSPORT
TOKEN_IO

CreditLine

{
  "creditLineAmount": {
    "amount": 10,
    "currency": "GBP"
  },
  "type": "AVAILABLE"
}

An object containing the credit line type and amount.

Properties

Name	Type	Description
creditLineAmount	Amount	none
type	CreditLineType	The type of credit line.

CreditLineType

"AVAILABLE"

The type of credit line.

Enumerated Values

Value
AVAILABLE
CREDIT
EMERGENCY
PRE_AGREED
TEMPORARY
OTHER
UNKNOWN

CurrencyExchange

{
  "exchangeRate": 1.34,
  "sourceCurrency": "GBP",
  "targetCurrency": "EUR",
  "unitCurrency": "GBP"
}

Used to describe currency exchanges.

Properties

Name	Type	Description
exchangeRate	integer	The currency exchange rate.
sourceCurrency	string	The ISO 4217 currency code denoting the currency of the creditor.
targetCurrency	string	The ISO 4217 currency code denoting the currency of the debtor.
unitCurrency	string	The ISO 4217 currency code denoting the currency used to set the exchange rate (GBP is the unit currency in the conversion of 1 GBP = x CUR).

DeleteStatusEnum

"SUCCESS"

The result of the delete operation.

Enumerated Values

Value
SUCCESS
FAILED

DeleteTaskStatus

"IN_PROGRESS"

Enumerated Values

Value
IN_PROGRESS
COMPLETED
FAILED

DeregistrationResult

{
  "applicationId": "",
  "institutionId": ""
}

Properties

Name	Type	Description
applicationId	string	none
institutionId	string	none

Enrichment

{
  "categorisation": {
    "categories": [
      "SHOPPING",
      "GROCERIES"
    ],
    "source": "MODEL"
  },
  "transactionHash": {
    "hash": "b0781fd71caa48c75039ec01c0ffb011.1"
  },
  "merchant": {
    "merchantName": "DEBENHAMS",
    "parentGroup": "ARCADIA"
  },
  "paymentProcessor": "PAYPAL",
  "location": "LONDON",
  "correctedDate": "2020-05-04T14:31:04.872Z"
}

An object containing Transaction enrichment information.

Properties

Name	Type	Description
categorisation	Categorisation	Enrichment object provided for merchant and categories enrichment.
transactionHash	TransactionHash	A hash of the Transaction, provided in the enrichment object.
merchant	MerchantEnrichment	Enrichment object provided for Transaction merchant enrichment.
paymentProcessor	string	Optional. Can be provided with merchant enrichment.
location	string	Optional. Can be provided with merchant enrichment.
correctedDate	string	Optional. Can be provided with merchant enrichment.

EnvironmentType

"SANDBOX"

The environment type.

Enumerated Values

Value
SANDBOX
MOCK
LIVE

ExchangeRateInformationResponse

{
  "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
}

An object containing exchange rate information.

Properties

Name	Type	Description
exchangeRateExpiryDate	string	The expiry rate of the exchange rate.

FeatureDetails

{
  "documentationUrl": "https://docs.yapily.com/#757fde49-a294-bbff-d5f9-2c21c5f57be0",
  "endpoint": "https://api.yapily.com/account/{account-id}",
  "feature": "INITIATE_PRE_AUTHORISATION"
}

Properties

Name	Type	Description
documentationUrl	string	Optional. A reference for the feature.
endpoint	string	Optional. The endpoint that uses the feature.
feature	FeatureEnum	A list of all `Features`.

FeatureEnum

"INITIATE_PRE_AUTHORISATION"

Used to describes what functions the account holder has given access to when using that Consent. When creating a Create Account Authorisation Request, you can optionally set which features the user should consent for.

Enumerated Values

Value
INITIATE_PRE_AUTHORISATION
INITIATE_ACCOUNT_REQUEST
ACCOUNT_REQUEST_DETAILS
ACCOUNTS
ACCOUNT
ACCOUNT_TRANSACTIONS
ACCOUNT_STATEMENTS
ACCOUNT_STATEMENT
ACCOUNT_STATEMENT_FILE
ACCOUNT_SCHEDULED_PAYMENTS
ACCOUNT_DIRECT_DEBITS
ACCOUNT_PERIODIC_PAYMENTS
ACCOUNT_TRANSACTIONS_WITH_MERCHANT
IDENTITY
ACCOUNTS_WITHOUT_BALANCE
ACCOUNT_WITHOUT_BALANCE
ACCOUNT_BALANCES
INITIATE_SINGLE_PAYMENT_SORTCODE
EXISTING_PAYMENT_INITIATION_DETAILS
CREATE_SINGLE_PAYMENT_SORTCODE
EXISTING_PAYMENTS_DETAILS
INITIATE_DOMESTIC_SINGLE_PAYMENT
CREATE_DOMESTIC_SINGLE_PAYMENT
INITIATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
CREATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT
CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT
INITIATE_DOMESTIC_SCHEDULED_PAYMENT
CREATE_DOMESTIC_SCHEDULED_PAYMENT
INITIATE_DOMESTIC_PERIODIC_PAYMENT
CREATE_DOMESTIC_PERIODIC_PAYMENT
PERIODIC_PAYMENT_FREQUENCY_EXTENDED
INITIATE_INTERNATIONAL_VARIABLE_RECURRING_PAYMENT
CREATE_INTERNATIONAL_VARIABLE_RECURRING_PAYMENT
INITIATE_INTERNATIONAL_SCHEDULED_PAYMENT
CREATE_INTERNATIONAL_SCHEDULED_PAYMENT
INITIATE_INTERNATIONAL_PERIODIC_PAYMENT
CREATE_INTERNATIONAL_PERIODIC_PAYMENT
INITIATE_INTERNATIONAL_SINGLE_PAYMENT
CREATE_INTERNATIONAL_SINGLE_PAYMENT
INITIATE_BULK_PAYMENT
CREATE_BULK_PAYMENT
TRANSFER
OPEN_DATA_PERSONAL_CURRENT_ACCOUNTS
OPEN_DATA_ATMS
READ_DOMESTIC_SINGLE_REFUND
READ_DOMESTIC_SCHEDULED_REFUND
READ_DOMESTIC_PERIODIC_PAYMENT_REFUND
READ_INTERNATIONAL_SINGLE_REFUND
READ_INTERNATIONAL_SCHEDULED_REFUND

FeatureStatusEnum

"UP"

Enumerated Values

Value
UP
DOWN
WARNING
UNKNOWN
EXPIRED

FilterAndSort

{
  "before": "",
  "cursor": "",
  "from": "",
  "limit": 100,
  "offset": 100,
  "sort": "DATE_ASCENDING(\"date\")"
}

An object for filter and sort information

Properties

Name	Type	Description
before	string	Optional. The upper bound of the date range.
cursor	string	Optional. Used in some cases instead of limit/offset.
from	string	Optional. The lower bound of the date range.
limit	integer	Optional. The limit specified for the request.
offset	integer	Optional. The offset specified for the request.
sort	SortEnum	Valid options for the sort parameter

FrequencyEnumExtended

"DAILY"

See payment frequency for more information.

Enumerated Values

Value
DAILY
EVERY_WORKING_DAY
CALENDAR_DAY
WEEKLY
EVERY_TWO_WEEKS
MONTHLY
EVERY_TWO_MONTHS
QUARTERLY
SEMIANNUAL
ANNUAL

FrequencyRequest

{
  "type": "DAILY",
  "executionDay": 1,
  "intervalMonth": 1,
  "intervalWeek": 1
}

Properties

Name	Type	Description
type Mandatory	FrequencyEnumExtended	See payment frequency for more information.
executionDay	integer	Conditional. See payment frequency for more information.
intervalMonth	integer	Conditional. See payment frequency for more information.
intervalWeek	integer	Conditional. See payment frequency for more information.

HttpStatus

"BAD_REQUEST"

Possible HTTP status codes.

Enumerated Values

Value
BAD_REQUEST
UNAUTHORIZED
PAYMENT_REQUIRED
FORBIDDEN
NOT_FOUND
METHOD_NOT_ALLOWED
NOT_ACCEPTABLE
PROXY_AUTHENTICATION_REQUIRED
REQUEST_TIMEOUT
CONFLICT
GONE
LENGTH_REQUIRED
PRECONDITION_FAILED
PAYLOAD_TOO_LARGE
URI_TOO_LONG
UNSUPPORTED_MEDIA_TYPE
REQUESTED_RANGE_NOT_SATISFIABLE
EXPECTATION_FAILED
I_AM_A_TEAPOT
INSUFFICIENT_SPACE_ON_RESOURCE
METHOD_FAILURE
DESTINATION_LOCKED
UNPROCESSABLE_ENTITY
LOCKED
FAILED_DEPENDENCY
UPGRADE_REQUIRED
PRECONDITION_REQUIRED
TOO_MANY_REQUESTS
REQUEST_HEADER_FIELDS_TOO_LARGE
UNAVAILABLE_FOR_LEGAL_REASONS
INTERNAL_SERVER_ERROR
NOT_IMPLEMENTED
BAD_GATEWAY
SERVICE_UNAVAILABLE
GATEWAY_TIMEOUT
HTTP_VERSION_NOT_SUPPORTED
VARIANT_ALSO_NEGOTIATES
INSUFFICIENT_STORAGE
LOOP_DETECTED
BANDWIDTH_LIMIT_EXCEEDED
NOT_EXTENDED
NETWORK_AUTHENTICATION_REQUIRED

Identity

{
  "addresses": [
    {
      "addressLine": "",
      "buildingNumber": "123",
      "city": "London",
      "country": "GB",
      "county": "London",
      "postalCode": "A12 3BC",
      "streetName": "123 Test Street",
      "type": "BUSINESS"
    }
  ],
  "birthdate": "1970-01-01",
  "email": "bojack@horsingaround.com",
  "firstName": "Bojack",
  "lastName": "Horseman",
  "fullName": "Bojack Horseman",
  "gender": "MALE",
  "id": "abc123",
  "phone": "02071234567"
}

Properties

Name	Type	Description
addresses	[IdentityAddress]	An array of addresses for the Identity.
birthdate	string	A birth date for the Identity.
email	string	An email for the Identity.
firstName	string	A first name for the Identity.
lastName	string	A last name for the Identity.
fullName	string	A full name for the Identity.
gender	string	A gender for the Identity.
id	string	An identifier for the Identity.
phone	string	A phone number for the Identity.

IdentityAddress

{
  "addressLine": "",
  "buildingNumber": "123",
  "city": "London",
  "country": "GB",
  "county": "London",
  "postalCode": "A12 3BC",
  "streetName": "123 Test Street",
  "type": "BUSINESS"
}

Properties

Name	Type	Description
addressLine	[string]	none
buildingNumber	string	none
city	string	none
country	string	none
county	string	none
postalCode	string	none
streetName	string	none
type	AddressTypeEnum	The type of the Address.

Institution

{
  "countries": [
    {
      "countryCode2": "GB",
      "displayName": "United Kingdom"
    }
  ],
  "credentialsType": "OAUTH1",
  "environmentType": "SANDBOX",
  "features": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "fullName": "Yapily Mock Bank",
  "id": "yapily-mock",
  "media": [
    {
      "source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
      "type": "icon"
    }
  ],
  "name": "Yapily Mock"
}

An object that represents an institution.

Properties

Name	Type	Description
countries	[Country]	An array of Country for the Institution.
credentialsType	CredentialsType	The type of credentials used.
environmentType	EnvironmentType	The environment type.
features	[FeatureEnum]	A list of features supported by the `Institution`.
fullName	string	The full name of the `Institution`.
id	string	The id of the `Institution`.
media	[Media]	[An object containing media information such as an icon.]
name	string	A friendly name of the `Institution`.

InstitutionConsent

{
  "institutionId": "yapily-mock"
}

A Consent tied to a specific institution.

Properties

Name	Type	Description
institutionId	string	The id of the `Institution` for the `Consent`.

InstitutionError

{
  "errorMessage": "{\"Code\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Errors\":[{\"ErrorCode\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Field\":\"x-jws-signature\"}]}",
  "httpStatusCode": 100
}

Properties

Name	Type	Description
errorMessage	string	The error reponse message from the Institution.
httpStatusCode	integer	The http status code from the Institution.

InstitutionTypeEnum

"SANDBOX"

The type of Institution.

Enumerated Values

Value
SANDBOX
MOCK
LIVE

InternationalPaymentRequest

{
  "chargeBearer": "DEBT",
  "currencyOfTransfer": "GBP",
  "exchangeRateInformation": "string",
  "priority": "NORMAL",
  "purpose": "277ca9eb968948d4b5f8bfa4b6b6b16f"
}

Properties

Name	Type	Description
chargeBearer	string	Optional. Specifies which party/parties will bear the charges associated with the processing of the payment transaction. Valid values are: DEBT - All transaction charges are to be borne by the debtor. CRED - All transaction charges are to be borne by the creditor. SHAR - In a credit transfer context, means that transaction charges on the sender side are to be borne by the debtor, transaction charges on the receiver side are to be borne by the creditor SLEV - Charges are to be applied following the rules agreed in the service level and/or scheme.
currencyOfTransfer	string	Mandatory. The 3-letter currency code for the currency of the payment to be transferred which can differ from the currency of the payer's account.
exchangeRateInformation	string	Optional. Used to express more details about the exchange rate
priority	string	Optional. The indicator of order of importance that the PSU would like the ASPSP to apply to the processing of the payments. Possible values are NORMAL and URGENT
purpose	string	Optional. Used to indicate the external purpose as a ISO20022 purpose code value.

IsoBankTransactionCode

{
  "domainCode": {
    "code": "",
    "name": ""
  },
  "familyCode": {
    "code": "",
    "name": ""
  },
  "subFamilyCode": {
    "code": "",
    "name": ""
  }
}

Properties

Name	Type	Description
domainCode	IsoCodeDetails	The IsoCodeDetails Object for the domain code.
familyCode	IsoCodeDetails	The IsoCodeDetails Object for the family code.
subFamilyCode	IsoCodeDetails	The IsoCodeDetails Object for the sub family code.

IsoCodeDetails

{
  "code": "",
  "name": ""
}

Properties

Name	Type	Description
code	string	The ISO Code.
name	string	A friendly name for the ISO Code.

Map

{
  "name": "",
  "value": ""
}

Properties

Name	Type	Description
name	string	The name.
value	string	The value.

Media

{
  "source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
  "type": "icon"
}

An object containing media information such as an icon.

Properties

Name	Type	Description
source	string	The source of the `Media`.
type	string	The type of the `Media`, e.g. icon.

Merchant

{
  "merchantCategoryCode": "5462",
  "merchantName": "London Luxury Baker"
}

Properties

Name	Type	Description
merchantCategoryCode	string	Optional. The merchant category code.
merchantName	string	Optional. The name of the merchant.

MerchantEnrichment

{
  "merchantName": "DEBENHAMS",
  "parentGroup": "ARCADIA"
}

Enrichment object provided for Transaction merchant enrichment.

Properties

Name	Type	Description
merchantName	string	none
parentGroup	string	none

MonitoringEndpointStatus

{
  "lastTested": "",
  "resourceEndpoint": "",
  "span": "",
  "status": "UP"
}

Properties

Name	Type	Description
lastTested	string	none
resourceEndpoint	string	none
span	string	none
status	FeatureStatusEnum	none

MultiAuthorisation

{
  "status": "AWAITING_FURTHER_AUTHORIZATION",
  "numberOfAuthorisationRequired": 2,
  "numberOfAuthorisationReceived": 1,
  "lastUpdatedDateTime": "2019-09-26T15:38:33.408Z",
  "expirationDateTime": "2019-09-26T14:20:14.393Z"
}

Properties

Name	Type	Description
status	string	The status of the multi authorisation. Possible values are AUTHORIZED, AWAITING_FURTHER_AUTHORIZATION, REJECTED and UNKNOWN.
numberOfAuthorisationRequired	integer	The number of authorisations required to authorise the consent.
numberOfAuthorisationReceived	integer	The number of authorisations that have been completed.
lastUpdatedDateTime	string	The time at which the multi authorisation was last updated.
expirationDateTime	string	The time at which the multi authorisation expires if there is one.

NewApplicationUser

{
  "applicationUserId": "bojack@9tees.com",
  "referenceId": "myuserreference"
}

Properties

Name	Type	Description
applicationUserId	string	Optional. An additional unique identifier that you can specify when creating a new `User` to more easily reference it
referenceId	string	Deprecated. A non-unique reference Id for the `User`.

{
  "before": "",
  "cursor": "",
  "from": "",
  "limit": 100
}

An object for filter and sort information

Properties

Name	Type	Description
before	string	Optional. The upper bound of the date range.
cursor	string	Optional. Used in some cases instead of limit/offset
from	string	Optional. The lower bound of the date range.
limit	integer	Optional. The limit specified for the request.

OneTimeTokenRequest

{
  "oneTimeToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6ImJidmEtc2FuZGJveCIsIlVVSUQiOiJmMzNmNGU4ZC1jMDQ0LTQ2YTktOTlkMC0wYmRlMzIyYTJjOTIifQ.4Qv3NJI6av2nKi1U3aNmm71cIwJ3TvRsIlYDafQUVv_Khy_e-8oEpV_BoP4V1CII12oT-Yq4cPveHILz8BOwjg"
}

Properties

Name	Type	Description
oneTimeToken	string	Mandatory. The one-time-token to exchange for a consentToken.

Pagination

{
  "next": {
    "before": "",
    "cursor": "",
    "from": "",
    "limit": 100
  },
  "self": {
    "before": "",
    "cursor": "",
    "from": "",
    "limit": 100,
    "offset": 100,
    "sort": "DATE_ASCENDING(\"date\")"
  },
  "totalCount": 100
}

An object containing pagination information in ResponseListMeta

Properties

Name	Type	Description
next	Next	An object for filter and sort information
self	FilterAndSort	An object for filter and sort information
totalCount	integer	Optional. The total count of the paged entities.

Payee

{
  "accountIdentifications": [
    {
      "identification": "123456",
      "type": "SORT_CODE"
    }
  ],
  "name": "Bojack Horseman",
  "address": {
    "addressLines": [
      "1 Downing St"
    ],
    "addressType": "BUSINESS",
    "buildingNumber": "123",
    "country": "GB",
    "county": "London",
    "department": "",
    "postCode": "A12 3BC",
    "streetName": "123 Test Street",
    "subDepartment": "",
    "townName": "London"
  },
  "merchantCategoryCode": "5462",
  "merchantId": "12345678"
}

Properties

Name	Type	Description
accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payee` bank account
name Mandatory	string	The account holder name of the beneficiary
address	Address	The address of the beneficiary. Mandatory when the paymentType is an `INTERNATIONAL` payment Some banks in the UK will fail unless `address.country` is provided in the case of any `DOMESTIC` payment
merchantCategoryCode	string	The category code of the merchant in case the `Payee` is a business
merchantId	string	A merchant ID is a unique code provided by the payment processor to the merchant

Payer

{
  "accountIdentifications": [
    {
      "identification": "123456",
      "type": "SORT_CODE"
    }
  ],
  "address": {
    "addressLines": [
      "1 Downing St"
    ],
    "addressType": "BUSINESS",
    "buildingNumber": "123",
    "country": "GB",
    "county": "London",
    "department": "",
    "postCode": "A12 3BC",
    "streetName": "123 Test Street",
    "subDepartment": "",
    "townName": "London"
  },
  "name": "Bojack Horseman"
}

Properties

Name	Type	Description
accountIdentifications Mandatory	[AccountIdentification]	The account identifications that identify the `Payer` bank account
address	Address	The address of the Payer.
name	string	The account holder name of the Payer

PaymentAuthorisationRequest

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "paymentRequest": {
    "type": "DOMESTIC_PAYMENT",
    "amount": {
      "amount": 10,
      "currency": "GBP"
    },
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "payee": {
      "accountIdentifications": [
        {}
      ],
      "name": "Bojack Horseman",
      "address": {
        "addressLines": null,
        "addressType": null,
        "buildingNumber": null,
        "country": null,
        "county": null,
        "department": null,
        "postCode": null,
        "streetName": null,
        "subDepartment": null,
        "townName": null
      },
      "merchantCategoryCode": "5462",
      "merchantId": "12345678"
    },
    "payer": {
      "accountIdentifications": [
        {}
      ],
      "address": {
        "addressLines": null,
        "addressType": null,
        "buildingNumber": null,
        "country": null,
        "county": null,
        "department": null,
        "postCode": null,
        "streetName": null,
        "subDepartment": null,
        "townName": null
      },
      "name": "Bojack Horseman"
    },
    "reference": "myreference",
    "paymentDateTime": "2019-12-26T14:42:53Z",
    "contextType": "BILL",
    "internationalPayment": {
      "chargeBearer": "DEBT",
      "currencyOfTransfer": "GBP",
      "exchangeRateInformation": "string",
      "priority": "NORMAL",
      "purpose": "277ca9eb968948d4b5f8bfa4b6b6b16f"
    },
    "periodicPayment": {
      "frequency": {
        "type": null,
        "executionDay": null,
        "intervalMonth": null,
        "intervalWeek": null
      },
      "nextPaymentAmount": {
        "amount": null,
        "currency": null
      },
      "nextPaymentDateTime": "2018-01-10T00:00:00Z",
      "finalPaymentAmount": {
        "amount": null,
        "currency": null
      },
      "finalPaymentDateTime": "2021-01-10T00:00:00Z",
      "numberOfPayments": 5
    },
    "readRefundAccount": true,
    "psuCorporateId": "",
    "psuId": ""
  },
  "allowOverdraft": true,
  "startsAt": "2020-08-18T16:24:22.316Z",
  "expiresAt": "2020-08-18T16:24:22.316Z",
  "maxAmountPerRequest": 10,
  "totalMaxAmount": 10,
  "totalMaxAmountFrequency": "DAILY"
}

Properties

allOf

Name	Type	Description
anonymous	AuthorisationRequest	Generic properties to define the authorisation to be created

and

Name	Type	Description
anonymous	object	none
» paymentRequest Mandatory	PaymentRequest	Mandatory. Used to define the details of the payment to be executed
» allowOverdraft	boolean	Optional. Not currently used
» startsAt	string	Optional. Used exclusively with Variable Recurring Payments. The date at which the first VRP payment can be made
» expiresAt	string	Optional. Used exclusively with Variable Recurring Payments. The date at which the last VRP payment can be made
» maxAmountPerRequest	integer(decimal)	Optional. Not currently used
» totalMaxAmount	integer(decimal)	Optional. Not currently used
» totalMaxAmountFrequency	AmountFrequency	Used exclusively with Variable Recurring Payments to define the frequency of the amount.

PaymentAuthorisationRequestResponse

{
  "applicationUserId": "bojack@8tees.com",
  "authorizedAt": "2020-09-13T15:57:46.450Z",
  "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
  "createdAt": "2020-09-13T15:57:46.450Z",
  "expiresAt": "2020-09-13T15:57:46.450Z",
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
  "institutionId": "yapily-mock",
  "referenceId": "myuserreference",
  "state": "754f6022f47548b99284f3f1993e050e",
  "status": "AWAITING_AUTHORIZATION",
  "timeToExpire": "PT-375H-40M-21.397S",
  "transactionFrom": "2020-09-13T15:57:46.450Z",
  "transactionTo": "2020-09-13T15:57:46.450Z",
  "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
  "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
  "charges": [
    {
      "chargeAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "chargeTo": "",
      "chargeType": "BULK_PAYMENT"
    }
  ],
  "exchangeRateInformation": {
    "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
  },
  "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
}

The response object containing the result of the payment authorisation.

Properties

allOf

Name	Type	Description
anonymous	Consent	The `Consent` object.

and

Name	Type	Description
anonymous	object	none
» authorisationUrl	string	The url to redirect the user to, in order to obtain their consent.
» charges	[ChargeDetails]	An array of ChargeDetails objects for each charge made in the payment request.
» exchangeRateInformation	ExchangeRateInformationResponse	An object containing exchange rate information.
» qrCodeUrl	string	A QR code that encapsulates the authorisationUrl.

PaymentContextType

"BILL"

Enumerated Values

Value
BILL
GOODS
SERVICES
OTHER
PERSON_TO_PERSON

PaymentEmbeddedAuthorisationRequest

{
  "applicationUserId": "bojack@9tees.com",
  "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
  "institutionId": "yapily-mock",
  "callback": "https://tpp.application/callback",
  "oneTimeToken": false,
  "forwardParameters": [],
  "paymentRequest": {
    "type": "DOMESTIC_PAYMENT",
    "amount": {
      "amount": null,
      "currency": null
    },
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "payee": {
      "accountIdentifications": null,
      "name": null,
      "address": null,
      "merchantCategoryCode": null,
      "merchantId": null
    },
    "payer": {
      "accountIdentifications": null,
      "address": null,
      "name": null
    },
    "reference": "myreference",
    "paymentDateTime": "2019-12-26T14:42:53Z",
    "contextType": "BILL",
    "internationalPayment": {
      "chargeBearer": null,
      "currencyOfTransfer": null,
      "exchangeRateInformation": null,
      "priority": null,
      "purpose": null
    },
    "periodicPayment": {
      "frequency": null,
      "nextPaymentAmount": null,
      "nextPaymentDateTime": null,
      "finalPaymentAmount": null,
      "finalPaymentDateTime": null,
      "numberOfPayments": null
    },
    "readRefundAccount": true,
    "psuCorporateId": "",
    "psuId": ""
  },
  "allowOverdraft": true,
  "startsAt": "2020-08-18T16:24:22.316Z",
  "expiresAt": "2020-08-18T16:24:22.316Z",
  "maxAmountPerRequest": 10,
  "totalMaxAmount": 10,
  "totalMaxAmountFrequency": "DAILY",
  "userCredentials": {
    "id": "user123",
    "corporateId": "corp456",
    "password": "Password123"
  },
  "selectedScaMethod": {
    "id": "id123",
    "type": "SMS_OTP"
  },
  "scaCode": "123ABC"
}

Properties

allOf

Name	Type	Description
anonymous	PaymentAuthorisationRequest	none

and

Name	Type	Description
anonymous	object	none
» userCredentials	UserCredentials	The SCA User credentials for embedded flow.
» selectedScaMethod	ScaMethod	Describes the method for second-factor authentication, for embedded payments
» scaCode	string	The SCA Code choosen by the User.

PaymentEmbeddedAuthorisationRequestResponse

{
  "applicationUserId": "bojack@8tees.com",
  "authorizedAt": "2020-09-13T15:57:46.450Z",
  "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
  "createdAt": "2020-09-13T15:57:46.450Z",
  "expiresAt": "2020-09-13T15:57:46.450Z",
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
  "institutionId": "yapily-mock",
  "referenceId": "myuserreference",
  "state": "754f6022f47548b99284f3f1993e050e",
  "status": "AWAITING_AUTHORIZATION",
  "timeToExpire": "PT-375H-40M-21.397S",
  "transactionFrom": "2020-09-13T15:57:46.450Z",
  "transactionTo": "2020-09-13T15:57:46.450Z",
  "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
  "authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
  "charges": [
    {
      "chargeAmount": {},
      "chargeTo": "",
      "chargeType": "BULK_PAYMENT"
    }
  ],
  "exchangeRateInformation": {
    "exchangeRateExpiryDate": "2020-05-04T14:31:04.872Z"
  },
  "qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0",
  "scaMethods": [
    {
      "id": "id123",
      "type": "SMS_OTP"
    }
  ],
  "selectedScaMethod": {
    "id": "id123",
    "type": "SMS_OTP"
  }
}

The authorisation response for an embedded payment request.

Properties

allOf

Name	Type	Description
anonymous	PaymentAuthorisationRequestResponse	The response object containing the result of the payment authorisation.

and

Name	Type	Description
anonymous	object	none
» scaMethods	[ScaMethod]	A list of supported ScaMethods
» selectedScaMethod	ScaMethod	The selected ScaMethod

PaymentRequest

{
  "type": "DOMESTIC_PAYMENT",
  "amount": {
    "amount": 10,
    "currency": "GBP"
  },
  "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
  "payee": {
    "accountIdentifications": [
      {
        "identification": "123456",
        "type": "SORT_CODE"
      }
    ],
    "name": "Bojack Horseman",
    "address": {
      "addressLines": [
        "1 Downing St"
      ],
      "addressType": "BUSINESS",
      "buildingNumber": "123",
      "country": "GB",
      "county": "London",
      "department": "",
      "postCode": "A12 3BC",
      "streetName": "123 Test Street",
      "subDepartment": "",
      "townName": "London"
    },
    "merchantCategoryCode": "5462",
    "merchantId": "12345678"
  },
  "payer": {
    "accountIdentifications": [
      {
        "identification": "123456",
        "type": "SORT_CODE"
      }
    ],
    "address": {
      "addressLines": [
        "1 Downing St"
      ],
      "addressType": "BUSINESS",
      "buildingNumber": "123",
      "country": "GB",
      "county": "London",
      "department": "",
      "postCode": "A12 3BC",
      "streetName": "123 Test Street",
      "subDepartment": "",
      "townName": "London"
    },
    "name": "Bojack Horseman"
  },
  "reference": "myreference",
  "paymentDateTime": "2019-12-26T14:42:53Z",
  "contextType": "BILL",
  "internationalPayment": {
    "chargeBearer": "DEBT",
    "currencyOfTransfer": "GBP",
    "exchangeRateInformation": "string",
    "priority": "NORMAL",
    "purpose": "277ca9eb968948d4b5f8bfa4b6b6b16f"
  },
  "periodicPayment": {
    "frequency": {
      "type": "DAILY",
      "executionDay": 1,
      "intervalMonth": 1,
      "intervalWeek": 1
    },
    "nextPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "nextPaymentDateTime": "2018-01-10T00:00:00Z",
    "finalPaymentAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "finalPaymentDateTime": "2021-01-10T00:00:00Z",
    "numberOfPayments": 5
  },
  "readRefundAccount": true,
  "psuCorporateId": "",
  "psuId": ""
}

Properties

Name	Type	Description
type Mandatory	PaymentType	Mandatory. One of Yapily's available payment types to execute. See European Payments to verify whether the `type` should be `DOMESTIC` or `INTERNATIONAL`.
amount Mandatory	Amount	Mandatory. The `Amount` object that contains the amount and currency of the payment.
paymentIdempotencyId Mandatory	string	Mandatory. A unique identifier that you must provide to identify the payment. This can be anything but the only requirement is that it is limited to a maximum of 35 characters long as per the Open Banking spec.
payee Mandatory	Payee	Mandatory. The `Payee` object contains details of the beneficiary [person or business]. You must define this in your payment request along with all of the nested mandatory properties.
payer	Payer	Conditional. The `Payer` object contains details of the benefactor [person or business]. If you define this in your payment request, you must define this along with all of the nested mandatory properties. Conditions: 1. The `Payer` object is mandatory along with its mandatory properties when the account of the benefactor is from an `Institution` in Europe. See Berlin Group for more information. 2. The `Payer` should be specified if the `Payer` account is intended to be locked.
reference	string	Optional. The payment reference or description. Limited to a maximum of 18 characters long.
paymentDateTime	string	Conditional. Used to specify the date of the payment when the payment type is one of the following: - `DOMESTIC_SCHEDULED_PAYMENT` - `DOMESTIC_PERIODIC_PAYMENT` - `INTERNATIONAL_SCHEDULED_PAYMENT` - `INTERNATIONAL_PERIODIC_PAYMENT`
contextType	PaymentContextType	Optional. Used to categorise the payment being made.
internationalPayment	InternationalPaymentRequest	Conditional. Used to specify properties to define an international payment. Must be specified when the payment `type` is one of the following: - `INTERNATIONAL_SINGLE_PAYMENT` - `INTERNATIONAL_SCHEDULED_PAYMENT` - `INTERNATIONAL_PERIODIC_PAYMENT`
periodicPayment	PeriodicPaymentRequest	Conditional. Used to specify properties to define a periodic payment. Must be specified when the payment `type` is one of the following: - `DOMESTIC_PERIODIC_PAYMENT` - `INTERNATIONAL_PERIODIC_PAYMENT`
read

Yapily API v1.0

Authentication

Application

Get Application

Parameters

Responses

Response Headers

Users

Get Users

Parameters

Responses

Response Schema

Create User

Parameters

Responses

Get User

Parameters

Responses

Delete User

Parameters

Responses

Response Schema

Enumerated Values

Institutions

Get Institutions

Parameters

Responses

Response Schema

Enumerated Values

Get Institution

Parameters

Responses

Get Features

Parameters

Responses

Response Schema

Enumerated Values

Consents

Get Consents

Parameters

Enumerated Values

Responses

Response Schema

Enumerated Values

Get Consent

Parameters

Responses

Response Schema

Enumerated Values

Delete Consent

Parameters

Responses

Response Schema

Enumerated Values

Exchange One Time Token

Parameters

Responses

(Forwarding) Send Access Token

Parameters

Responses

(Forwarding) Send OAuth2 Code

Parameters

Responses

Obtaining a Consent

Create Account Authorisation

Parameters

Responses

Response Schema

Enumerated Values

Re-authorise Account Authorisation

Parameters

Responses

Response Schema

Enumerated Values

Update Account Authorisation

Parameters

Responses

Response Schema

Enumerated Values

Create Payment Authorisation