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.
|
»» 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 |
Get Consent
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.
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 |
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"
}
}
Responses
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 |
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 | 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.
|
»» 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 |
Delete Consent
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.
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 |
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"
}
}
Responses
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 |
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 | 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.
|
»»» 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.
|
»»» 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.
|
»»» 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.
|
»»» 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.
|
»»» 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.
|
»»»» 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.
|
»»»» 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.
|
»»» 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.
|
»»» 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.
|
»» 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 | |
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.
|
»» 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 | |
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
|
»»»» 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 | |
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
|
»»»» 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 | |
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
|
»»»» 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 | |
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.
|
»» 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.
|
»» 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
|
»»»» 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 | |
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. |
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
|
»»»» 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 | |
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
|
»»»» 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 | |
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
|
»»»»» 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 | |
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.
|
AccountBalanceType
"CLOSING_AVAILABLE"
The OBBalanceType1Code balance type.
- CLOSING_AVAILABLE - Closing balance of amount of money that is at the disposal of the account owner on the date specified
- CLOSING_BOOKED - Balance of the account at the end of the pre-agreed account reporting period. It is the sum of the opening booked balance at the beginning of the period and all entries booked to the account during the pre-agreed account reporting period.
- CLOSING_CLEARED - Closing balance of amount of money that is cleared on the date specified.
- EXPECTED - Balance, composed of booked entries and pending items known at the time of calculation, which projects the end of day balance if everything is booked on the account and no other entry is posted.
- FORWARD_AVAILABLE - Forward available balance of money that is at the disposal of the account owner on the date specified.
- INFORMATION - Balance for informational purposes.
- INTERIM_AVAILABLE - Available balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified.
- INTERIM_BOOKED - Balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day. The interim balance is calculated on the basis of booked credit and debit items during the calculation time/period specified.
- INTERIM_CLEARED - Cleared balance calculated in the course of the account servicer's business day, at the time specified, and subject to further changes during the business day.
- OPENING_AVAILABLE - Opening balance of amount of money that is at the disposal of the account owner on the date specified.
- OPENING_BOOKED - Book balance of the account at the beginning of the account reporting period. It always equals the closing book balance from the previous report.
- OPENING_CLEARED - Opening balance of amount of money that is cleared on the date specified.
- PREVIOUSLY_CLOSED_BOOKED - Balance of the account at the previously closed account reporting period. The opening booked balance for the new period has to be equal to this balance. Usage: the previously booked closing balance should equal (inclusive date) the booked closing balance of the date it references and equal the actual booked opening balance of the current date.
- AUTHORISED - Balance of the account minus any authorised transactions not yet cleared.
- OTHER - Used when an unrecognised enum is parsed
- UNKNOWN - Used as a Yapily default
Enumerated Values
Value |
---|
CLOSING_AVAILABLE |
CLOSING_BOOKED |
CLOSING_CLEARED |
EXPECTED |
FORWARD_AVAILABLE |
INFORMATION |
INTERIM_AVAILABLE |
INTERIM_BOOKED |
INTERIM_CLEARED |
OPENING_AVAILABLE |
OPENING_BOOKED |
OPENING_CLEARED |
PREVIOUSLY_CLOSED_BOOKED |
AUTHORISED |
OTHER |
UNKNOWN |
AccountIdentification
{
"identification": "123456",
"type": "SORT_CODE"
}
Properties
Name | Type | Description |
---|---|---|
identification Mandatory |
string | The value associated with the account identification type. See Account Identification Combinations for more information on the format of the values. |
type Mandatory |
AccountIdentificationType | Used to describe the format of the account. See Account Identification Combinations for more information on when to specify each type. |
AccountIdentificationType
"SORT_CODE"
See Account Identifications Types for more information on each type
Enumerated Values
Value |
---|
SORT_CODE |
ACCOUNT_NUMBER |
IBAN |
BBAN |
BIC |
PAN |
MASKED_PAN |
MSISDN |
BSB |
NCC |
ABA |
ABA_WIRE |
ABA_ACH |
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
|
county | [string] | The county name for the address |
department | string | The department name for the address |
postCode | string | The post code for the address |
streetName | string | The street name for the address Mandatory for INTERNATIONAL payment types |
subDepartment | string | The sub department name for the address |
townName | string | The town name for the address Mandatory for INTERNATIONAL payment types |
AddressDetails
{
"addressLine": "123 Test Street, Test, AB1 2DC"
}
Properties
Name | Type | Description |
---|---|---|
addressLine | string | The address line for the address |
AddressTypeEnum
"BUSINESS"
The type of the Address.
Enumerated Values
Value |
---|
BUSINESS |
CORRESPONDENCE |
DELIVERY_TO |
MAIL_TO |
PO_BOX |
POSTAL |
RESIDENTIAL |
STATEMENT |
UNKNOWN |
Amount
{
"amount": 10,
"currency": "GBP"
}
Properties
Name | Type | Description |
---|---|---|
amount Mandatory |
integer(float) | Mandatory. The monetary value |
currency Mandatory |
string | Mandatory. The ISO 4217 currency code |
AmountFrequency
"DAILY"
Used exclusively with Variable Recurring Payments to define the frequency of the amount.
Enumerated Values
Value |
---|
DAILY |
WEEKLY |
MONTHLY |
YEARLY |
ApiError
{
"code": 401,
"institutionError": {
"errorMessage": "{\"Code\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Errors\":[{\"ErrorCode\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Field\":\"x-jws-signature\"}]}",
"httpStatusCode": 100
},
"message": "Full authentication is required to access this resource",
"source": "YAPILY",
"status": "BAD_REQUEST",
"tracingId": "e7b01315-cbc5-4d0b-91e8-4f77cb1a3253"
}
An object containing further information about the error that occurred.
Properties
Name | Type | Description |
---|---|---|
code | integer | The HTTP Status code |
institutionError | InstitutionError | The error message provided by the Institution |
message | string | The error message provided by Yapily |
source | string | The source of the error |
status | HttpStatus | The HTTP Status enumeration |
tracingId | string | The unique identifier for the request. Used to trace the request in logging enquiries |
ApiListResponse
{
"data": [],
"links": [
{
"name": "",
"value": ""
}
],
"meta": {
"count": 100,
"pagination": {
"next": {
"before": "",
"cursor": "",
"from": "",
"limit": 100
},
"self": {
"before": "",
"cursor": "",
"from": "",
"limit": 100,
"offset": 100,
"sort": "DATE_ASCENDING(\"date\")"
},
"totalCount": 100
},
"tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
},
"raw": [
{
"duration": "",
"headers": [
{
"name": "",
"value": ""
}
],
"request": {
"method": "",
"requestInstant": "",
"templateUri": "",
"url": ""
},
"result": "",
"resultCode": 100
}
]
}
Properties
Name | Type | Description |
---|---|---|
data | string | An array of objects, depending on the endpoint |
links | [Map] | none |
meta | ResponseListMeta | An object containing a tracingId of the request |
raw | [RawResponse] | [An object returned when the raw parameter is sent] |
ApiResponse
{
"data": "{}",
"links": [
{
"name": "",
"value": ""
}
],
"meta": {
"tracingId": "cfeba8da-d9a8-46c3-b9f6-80a52149a775"
},
"raw": [
{
"duration": "",
"headers": [
{
"name": "",
"value": ""
}
],
"request": {
"method": "",
"requestInstant": "",
"templateUri": "",
"url": ""
},
"result": "",
"resultCode": 100
}
]
}
Properties
Name | Type | Description |
---|---|---|
data | string | An object, depending on the endpoint |
links | [Map] | none |
meta | ResponseMeta | An object containing a tracingId of the request |
raw | [RawResponse] | [An object returned when the raw parameter is sent] |
ApiResponseError
{
"error": {
"code": 401,
"institutionError": {
"errorMessage": "{\"Code\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Errors\":[{\"ErrorCode\":\"UK.OBIE.Signature.Malformed\",\"Message\":\"invalid_iss_claim: Invalid iss claim. Got org_id/statement_id. Expected 001580000103UArAAM/rapTYmFWJcXfdo2EvksDUx\",\"Field\":\"x-jws-signature\"}]}",
"httpStatusCode": 100
},
"message": "Full authentication is required to access this resource",
"source": "YAPILY",
"status": "BAD_REQUEST",
"tracingId": "e7b01315-cbc5-4d0b-91e8-4f77cb1a3253"
},
"monitoring": [
{
"lastTested": "",
"resourceEndpoint": "",
"span": "",
"status": "UP"
}
],
"raw": [
{
"duration": "",
"headers": [
{
"name": "",
"value": ""
}
],
"request": {
"method": "",
"requestInstant": "",
"templateUri": "",
"url": ""
},
"result": "",
"resultCode": 100
}
]
}
Properties
Name | Type | Description |
---|---|---|
error | ApiError | The error object contains additional information about the error. |
monitoring | [MonitoringEndpointStatus] | An endpoint for mointoring. |
raw | [RawResponse] | The raw response returned from the Institution . |
Application
{
"active": true,
"authCallbacks": [
"https://test.example.com/callback"
],
"created": "2020-09-09T10:31:53.968+0000",
"institutions": [
{
"countries": [
{
"countryCode2": "GB",
"displayName": "United Kingdom"
}
],
"credentialsType": "OAUTH1",
"environmentType": "SANDBOX",
"features": [
"INITIATE_PRE_AUTHORISATION"
],
"fullName": "Yapily Mock Bank",
"id": "yapily-mock",
"media": [
{
"source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
"type": "icon"
}
],
"name": "Yapily Mock"
}
],
"media": [
{
"source": "https://images.yapily.com/image/5e81571a-d83e-43ff-be2e-d1fe3b2ef5a0?size=0",
"type": "icon"
}
],
"name": "My App 6238",
"updated": "2020-09-09T10:31:53.968+0000",
"uuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a"
}
Properties
Name | Type | Description |
---|---|---|
active | boolean | Whether the Application is active or not |
authCallbacks | [string] | A list of callbacks configured for the Application . |
created | string | The date the Application was created. |
institutions | [Institution] | [An object that represents an institution.] |
media | [Media] | [An object containing media information such as an icon.] |
name | string | The friendly name of the Application . |
updated | string | The date the Application was last updated. |
uuid | string | The identifier of the Application . |
ApplicationCallback
{
"authCallbackURL": "http://tpp.domain/callback"
}
Properties
Name | Type | Description |
---|---|---|
authCallbackURL | string | The callback URL associated with the Application. |
AuthorisationRequest
{
"applicationUserId": "bojack@9tees.com",
"userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
"institutionId": "yapily-mock",
"callback": "https://tpp.application/callback",
"oneTimeToken": false,
"forwardParameters": []
}
Generic properties to define the authorisation to be created
Properties
Name | Type | Description |
---|---|---|
applicationUserId | string | Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the applicationUserId or userUuid must be specified. |
userUuid | string | Conditional. The reference to the User using the Yapily generated UUID. The userUuid must find an existing User object otherwise the request will fail. Either the applicationUserId or userUuid must be specified. |
institutionId Mandatory |
string | The reference to the Institution which identifies which institution the authorisation request is sent to. |
callback | string | The server to redirect the user to after the user complete the authorisation at the Institution . See Using a callback (Optional) for more information. |
oneTimeToken | boolean | Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set. See Using a callback with an OTT (Optional) for more information. |
forwardParameters | [string] | Not currently used. |
AuthorisationRequestResponse
{
"applicationUserId": "bojack@8tees.com",
"authorizedAt": "2020-09-13T15:57:46.450Z",
"consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
"createdAt": "2020-09-13T15:57:46.450Z",
"expiresAt": "2020-09-13T15:57:46.450Z",
"featureScope": [
"INITIATE_PRE_AUTHORISATION"
],
"id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
"institutionId": "yapily-mock",
"referenceId": "myuserreference",
"state": "754f6022f47548b99284f3f1993e050e",
"status": "AWAITING_AUTHORIZATION",
"timeToExpire": "PT-375H-40M-21.397S",
"transactionFrom": "2020-09-13T15:57:46.450Z",
"transactionTo": "2020-09-13T15:57:46.450Z",
"userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
"authorisationUrl": "https://apis-i.redsys.es:20443/psd2/xs2a/api-oauth-xs2a/services/rest/unicajabanco/authorize?client_id=PSDES-BDE-927459&response_type=code&state=0485a5e6263442f4ac8591ea63ced49d&code_challenge=p9NWLpyT0kvGrDkXeQA6Msb949lqacoI9zrUN6nBang&code_challenge_method=S256&scope=AIS+PIS&redirect_uri=http%3A%2F%2Flocal-auth.yapily.com%3A8082%2F",
"qrCodeUrl": "https://images.yapily.com/image/cf06fd2e-7d50-4097-8392-ec9ed9ae3971/1599231316?size=0"
}
A response object containing the result of the authorisation.
Properties
allOf
Name | Type | Description |
---|---|---|
anonymous | Consent | The Consent object. |
and
Name | Type | Description |
---|---|---|
anonymous | object | none |
» authorisationUrl | string | The url to redirect the user to, in order to obtain their consent. |
» qrCodeUrl | string | A QR code that encapsulates the authorisationUrl. |
AuthorisationStatus
"AWAITING_AUTHORIZATION"
Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed.
- AUTHORIZED - Occurs when a user has successfully given their consent from the Institution to access their account information or to execute a payment. The Consent transitions from AWAITING_AUTHORIZATION (or from AWAITING_PRE_AUTHORIZATION in the case that the Institution requires pre-authorisation) to AUTHORIZED and a consentToken to execute the associated request is created and attached to the object.
- AWAITING_AUTHORIZATION - Occurs when a Create Account Authorisation Request or Create Payment Authorisation Request is executed. The Consent object remains in the AWAITING_AUTHORIZATION state until the user authorises consent with the relevant institution using the authorisationUrl.
- AWAITING_FURTHER_AUTHORIZATION - Occurs when a Consent is authorised by one of the account holders for a joint account or in the case of some business accounts. Some additional offline authorisations (e.g. email or sms) are required before the Consent can transition to AUTHORIZED.
- AWAITING_DECOUPLED_AUTHORIZATION - Occurs during Pre-Auth Decoupled flow after a PUT Create Account Authorisation Request is executed. The Consent object will transition from PRE_AUTHORIZED to AWAITING_DECOUPLED_AUTHORIZATION. Once the user approves the consent on their device the consent will become AUTHORIZED.
- AWAITING_PRE_AUTHORIZATION - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the default state of the Consent once either POST Create Account Pre-Authorisation Request or POST Create Payment Pre-Authorisation Request is executed indicating that pre-authorisation request still requires an authorisation from the user.
- AWAITING_RE_AUTHORIZATION - Occurs when an account information Consent that was previously AUTHORIZED is awaiting another authorisation after executing Re-authorise Consent holder's for continued access to their Financial Data with respect to the features in the Consent.
- CONSUMED - Occurs after successfully executing a payment request. As a payment Consent object is single use only, it transitions from AUTHORIZED (once the user has authorised the payment) to CONSUMED which indicates that it can no longer be used to execute subsequent payment requests. This is a terminal state *.
- EXPIRED - Occurs at the value of AccountRequest.expiresAt if specified by the user when creating an account authorisation request and supported by the bank. The Consent object was previously AUTHORIZED but once EXPIRED, it can no longer be used or re-authorised. This is a terminal state *.
- FAILED - Occurs when the user authorises their consent but there is a failure in the institution's domain during the token exchange process between the institution and Yapily. The Consent object transitions from AWAITING_AUTHORIZATION to FAILED and the expected consentToken will not be available. You can attempt to obtain a valid consentToken by executing Re-authorise Consent if this is a consent for obtaining financial data.
- PRE_AUTHORIZED - Occurs specifically with integrations that support the feature INITIATE_PRE_AUTHORIZATION. This is the state returned to indicate that the user has completed the required pre-authorisation which is the prerequisite for accessing the user's financial data or executing a payment through the additional authorisations using either PUT Create Account Authorisation Request or PUT Create Payment Authorisation Request.
- REJECTED - Occurs after when the user is redirected to the authorisationUrl and chooses not to give consent to their account information or to execute a payment. The Consent object transitions from AWAITING_AUTHORIZATION to REJECTED. This is a terminal state *.
- REVOKED - Occurs when a Consent object that was previously AUTHORIZED is REVOKED by the institution. This occurs when the user has requested to stop giving access to their account information through their bank which can happen at any time. This is a terminal state *.
- UNKNOWN - Used as a default
Enumerated Values
Value |
---|
AWAITING_AUTHORIZATION |
AWAITING_FURTHER_AUTHORIZATION |
AWAITING_RE_AUTHORIZATION |
AWAITING_DECOUPLED_AUTHORIZATION |
AUTHORIZED |
CONSUMED |
REJECTED |
REVOKED |
FAILED |
EXPIRED |
UNKNOWN |
INVALID |
AWAITING_PRE_AUTHORIZATION |
PRE_AUTHORIZED |
Balance
{
"balanceAmount": {
"amount": 10,
"currency": "GBP"
},
"type": "CLOSING_AVAILABLE"
}
An object containing the amount and balance type.
Properties
Name | Type | Description |
---|---|---|
balanceAmount | Amount | none |
type | AccountBalanceType | The OBBalanceType1Code balance type.
|
Balances
{
"balances": [
{
"balanceAmount": {
"amount": 10,
"currency": "GBP"
},
"creditLineIncluded": true,
"creditLines": [
{
"creditLineAmount": {
"amount": null,
"currency": null
},
"type": "AVAILABLE"
}
],
"dateTime": "2020-09-21T16:35:55Z",
"type": "CLOSING_AVAILABLE"
}
],
"mainBalanceAmount": {
"amount": 10,
"currency": "GBP"
}
}
Properties
Name | Type | Description |
---|---|---|
balances | [AccountBalance] | An array of AccountBalances. |
mainBalanceAmount | Amount | none |
BulkPaymentAuthorisationRequest
{
"applicationUserId": "bojack@9tees.com",
"userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
"institutionId": "yapily-mock",
"callback": "https://tpp.application/callback",
"oneTimeToken": false,
"forwardParameters": [],
"paymentRequest": {
"executionDateTime": "2020-10-17T00:00:00Z",
"originatorIdentificationNumber": "",
"payments": [
{
"type": "[",
"amount": {},
"paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
"payee": {},
"payer": {},
"reference": "myreference",
"paymentDateTime": "2019-12-26T14:42:53Z",
"contextType": "[",
"internationalPayment": {},
"periodicPayment": {},
"readRefundAccount": true,
"psuCorporateId": "",
"psuId": ""
}
]
}
}
The bulk payment authorisation request.
Properties
allOf
Name | Type | Description |
---|---|---|
anonymous | AuthorisationRequest | Generic properties to define the authorisation to be created |
and
Name | Type | Description |
---|---|---|
anonymous | object | none |
» paymentRequest Mandatory |
BulkPaymentRequest | Details of the bulk payment request, including the array of payments. |
BulkPaymentRequest
{
"executionDateTime": "2020-10-17T00:00:00Z",
"originatorIdentificationNumber": "",
"payments": [
{
"type": "DOMESTIC_PAYMENT",
"amount": {
"amount": 10,
"currency": "GBP"
},
"paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
"payee": {
"accountIdentifications": [
{
"identification": null,
"type": null
}
],
"name": "Bojack Horseman",
"address": {
"addressLines": "[Object]",
"addressType": "[",
"buildingNumber": "123",
"country": "GB",
"county": "London",
"department": "",
"postCode": "A12 3BC",
"streetName": "123 Test Street",
"subDepartment": "",
"townName": "London"
},
"merchantCategoryCode": "5462",
"merchantId": "12345678"
},
"payer": {
"accountIdentifications": [
{
"identification": null,
"type": null
}
],
"address": {
"addressLines": "[Object]",
"addressType": "[",
"buildingNumber": "123",
"country": "GB",
"county": "London",
"department": "",
"postCode": "A12 3BC",
"streetName": "123 Test Street",
"subDepartment": "",
"townName": "London"
},
"name": "Bojack Horseman"
},
"reference": "myreference",
"paymentDateTime": "2019-12-26T14:42:53Z",
"contextType": "BILL",
"internationalPayment": {
"chargeBearer": "DEBT",
"currencyOfTransfer": "GBP",
"exchangeRateInformation": "string",
"priority": "NORMAL",
"purpose": "277ca9eb968948d4b5f8bfa4b6b6b16f"
},
"periodicPayment": {
"frequency": {
"type": "[",
"executionDay": 1,
"intervalMonth": 1,
"intervalWeek": 1
},
"nextPaymentAmount": {
"amount": 10,
"currency": "GBP"
},
"nextPaymentDateTime": "2018-01-10T00:00:00Z",
"finalPaymentAmount": {
"amount": 10,
"currency": "GBP"
},
"finalPaymentDateTime": "2021-01-10T00:00:00Z",
"numberOfPayments": 5
},
"readRefundAccount": true,
"psuCorporateId": "",
"psuId": ""
}
]
}
Details of the bulk payment request, including the array of payments.
Properties
Name | Type | Description |
---|---|---|
executionDateTime | string | The date and time the bulk payment request was executed. |
originatorIdentificationNumber | string | The identification number of the originator. |
payments | [PaymentRequest] | The array of PaymentRequests for the BulkPayment. |
BulkUserDelete
{
"id": "",
"links": [
{
"name": "",
"value": ""
}
],
"startedAt": "",
"status": "IN_PROGRESS"
}
Deprecated.
Properties
Name | Type | Description |
---|---|---|
id | string | none |
links | [Map] | none |
startedAt | string | none |
status | DeleteTaskStatus | none |
BulkUserDeleteDetails
{
"invalidApplicationUserIds": "",
"invalidUserUuids": "",
"users": [
{
"creationDate": "2019-05-10T17:36:49.269+0000",
"deleteStatus": "SUCCESS",
"id": "c50844cb-1498-44aa-90d1-62eae8cdb3f6",
"userConsents": [
{
"creationDate": "2019-05-10T16:45:43.566+0000",
"deleteStatus": "SUCCESS",
"id": "a71fd46f-4144-478e-9a72-dd0d7a1158ab",
"institutionConsentId": "aac-1cce1cfc-1ab2-4ed6-8062-a0fd6c5c2122",
"institutionId": "yapily-mock"
}
]
}
]
}
Deprecated.
Properties
Name | Type | Description |
---|---|---|
invalidApplicationUserIds | [string] | none |
invalidUserUuids | [string] | none |
users | [UserDeleteResponse] | [An object returned from a successful user delete request] |
Categorisation
{
"categories": [
"SHOPPING",
"GROCERIES"
],
"source": "MODEL"
}
Enrichment object provided for merchant and categories enrichment.
Properties
Name | Type | Description |
---|---|---|
categories | [string] | An array of Strings describing the transaction category. |
source | string | The source of the categorisation information. |
ChargeDetails
{
"chargeAmount": {
"amount": 10,
"currency": "GBP"
},
"chargeTo": "",
"chargeType": "BULK_PAYMENT"
}
The amount details for the payment.
Properties
Name | Type | Description |
---|---|---|
chargeAmount | Amount | The Amount of the Charge. |
chargeTo | string | Not used. |
chargeType | string | The type of charge for the payment. |
Consent
{
"applicationUserId": "bojack@8tees.com",
"authorizedAt": "2020-09-13T15:57:46.450Z",
"consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
"createdAt": "2020-09-13T15:57:46.450Z",
"expiresAt": "2020-09-13T15:57:46.450Z",
"featureScope": [
"INITIATE_PRE_AUTHORISATION"
],
"id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
"institutionId": "yapily-mock",
"referenceId": "myuserreference",
"state": "754f6022f47548b99284f3f1993e050e",
"status": "AWAITING_AUTHORIZATION",
"timeToExpire": "PT-375H-40M-21.397S",
"transactionFrom": "2020-09-13T15:57:46.450Z",
"transactionTo": "2020-09-13T15:57:46.450Z",
"userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48"
}
The Consent
object.
Properties
Name | Type | Description |
---|---|---|
applicationUserId | string | Used by you to uniquely identify the user associated with the Consent object. |
authorizedAt | string | The date the consent was authorized. |
consentToken | string | Used to represent the user's consent encoded as a JSON Web Token (JWT) which is made available once the user has authorised consent with their bank. The value of the token is used when using the Financial Data and Payment endpoints with the Consent request header. |
createdAt | string | The date and time the Consent object was created. |
expiresAt | string | Used to specify the date the Consent will transition to the EXPIRED status and no longer be usable if one was set by the user when the Consent was created and the Institution supports this feature (If any of these conditions are not set, the Consent will not have this property and there will be no expiry date). |
featureScope | [FeatureEnum] | An array of Features in scope for the consent. |
id | string | Used to uniquely identify the Consent object within an application. |
institutionId | string | Used to identify the Institution that holds your user's account |
referenceId | string | Deprecated. A non unique reference for the User tied to the Consent . |
state | string | The state. |
status | AuthorisationStatus | Used to inform on the current state of the Consent object and to inform which subsequent requests can or should be executed.
|
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. |
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:
|
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.
|
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 |