NAV
shell

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

Obtaining a Consent

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.

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.

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.

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.

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.

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

Next

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