Introduction

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 guide 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

ApiClient defaultClient = Configuration.getDefaultApiClient();
// Configure the API authentication
HttpBasicAuth basicAuth = (HttpBasicAuth) defaultClient.getAuthentication("basicAuth");
// Replace these demo constants with your application credentials
basicAuth.setUsername(API_KEY);
basicAuth.setPassword(API_SECRET);

configuration = Configuration()
configuration.username = API_KEY
configuration.password = API_SECRET

apiClient = ApiClient(configuration)

curl 'https://api.yapily.com/me' \ 
-u API_KEY:API_SECRET

module.exports = {
    "APPLICATION_ID" : "{{API_KEY}}",
    "APPLICATION_SECRET" : "{{API_SECRET}}",
    "APPLICATION_USER_ID": "node-sdk@yapily.com",
    "INSTITUTION_ID": "{{INSTITUTION_ID}}",
    "CALLBACK_URL": "{{CALLBACK_URL}}"
}

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

An Application represents your application software. You may have multiple Applications associated with your account.

Application Model

Parameter	Description
uuid	The uuid of the `Application`
name	The name of the `Application`
active	Indicates whether the `Application` is active
authCallbacks	A list of callbacks configured on the `Application`
institutions	A list of `Institutions` associated with the `Application`
media	Media associated with the `Application`
created	The created date of the `Application`
updated	The last updated date of the `Application`

Get Application

ApplicationsApi apiInstance = new ApplicationsApi();
try {
    Application result = apiInstance.getApplicationMeUsingGET();
    System.out.println(result);
} catch (ApiException e) {
    System.err.println("Exception when calling ApplicationsApi#getApplicationMeUsingGET");
    e.printStackTrace();
}

with yapily.ApiClient(configuration) as api_client:
    api_instance = yapily.ApplicationsApi(api_client)
    try:
        api_response = api_instance.get_application_me_using_get()
        pprint(api_response)
    except ApiException as e:
        print("Exception when calling ApplicationsApi->get_application_me_using_get: %s\n" % e)

curl 'https://api.yapily.com/me' \ 
-u API_KEY:API_SECRET

var apiInstance = new YapilyApi.ApplicationsApi();
var callback = function(error, data, response) {
  if (error) {
    console.error(error);
  } else {
    console.log('API called successfully. Returned data: ' + data);
  }
};
apiInstance.getApplicationMeUsingGET(callback);

{
  "uuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a",
  "name": "My App 6238",
  "active": true,
  "authCallbacks": [],
  "institutions": [{
    "id": "yapily-mock",
    "name": "Yapily Mock",
    "fullName": "Yapily Mock Bank",
    "countries": [{
      "displayName": "United Kingdom",
      "countryCode2": "UK"
    }],
    "environmentType": "SANDBOX",
    "credentialsType": "OPEN_BANKING_UK_MANUAL",
    "media": [{
      "source": "https://images.yapily.com/image/b5a23070-4fdb-403e-9537-f8e23fa2469b?size=0",
      "type": "logo"
    }, {
      "source": "https://images.yapily.com/image/4bbb9c1b-29e0-4cc9-8d01-b2ad2fcd57a3?size=0",
      "type": "icon"
    }],
    "features": ["INITIATE_DOMESTIC_PERIODIC_PAYMENT", "CREATE_DOMESTIC_SINGLE_PAYMENT", "ACCOUNT_TRANSACTIONS_WITH_MERCHANT", "EXISTING_PAYMENTS_DETAILS", "INITIATE_ACCOUNT_REQUEST", "INITIATE_DOMESTIC_SINGLE_PAYMENT", "EXISTING_PAYMENT_INITIATION_DETAILS", "CREATE_DOMESTIC_PERIODIC_PAYMENT", "CREATE_DOMESTIC_SCHEDULED_PAYMENT", "ACCOUNTS", "INITIATE_SINGLE_PAYMENT_SORTCODE", "CREATE_SINGLE_PAYMENT_SORTCODE", "INITIATE_DOMESTIC_SCHEDULED_PAYMENT", "ACCOUNT_TRANSACTIONS", "ACCOUNT"]
  }],
  "media": [],
  "created": "2020-09-09T10:31:53.968+0000",
  "updated": "2020-09-09T10:31:53.968+0000"
}

Used to retrieve the details of the Application that owns the request credentials.

HTTP Request

GET https://api.yapily.com/me

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

HTTP Response

The response returns an Application

User

A User represents a customer of your application software and is associated with the Application.

User Model

Parameter	Description
uuid	The uuid of the User
applicationUuid	The uuid of the Application
applicationUserId	Your identifier for the User
institutionConsents	A list of institutionConsent

Get Users

TODO

TODO

curl 'https://api.yapily.com/users' \ 
-u API_KEY:API_SECRET

TODO

[{
  "uuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
  "applicationUuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a",
  "applicationUserId": "bojack@8tees.com",
  "institutionConsents": [{
    "institutionId": "yapily-mock"
  }]
}, {
  "uuid": "36305ed8-65e5-424e-aeb4-20a3610d9691",
  "applicationUuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a",
  "applicationUserId": "bojack@9tees.com",
  "institutionConsents": []
}]

Used to retrieve all User objects from a Yapily application.

HTTP Request

GET https://api.yapily.com/users

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

HTTP Response

The response returns a list of Users.

Get User

TODO

TODO

curl 'https://api.yapily.com/users/{user-uuid}' \ 
-u API_KEY:API_SECRET

TODO

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

Used to retrieve a User object from a Yapily application by the unique id of the user.

HTTP Request

GET https://api.yapily.com/users/<user-uuid>

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

URL Parameters

Parameter	Description
user-uuid	The uuid of the `User` to retrieve

HTTP Response

The response returns a User.

Create User

TODO

TODO

curl -X POST 'https://api.yapily.com/users' \ 
-H 'Content-Type: application/json' \ 
-u API_KEY:API_SECRET \ 
-d '{"applicationUserId":"bojack@9tees.com"}'

TODO

{
  "uuid": "2a811012-de6b-478c-a872-13278f41690f",
  "applicationUuid": "d9581bcc-6359-48d2-bb96-dc0ac74b6f7a",
  "applicationUserId": "bojack@9tees.com",
  "institutionConsents": []
}

Used to create an application user. This step is not necessary to make an authorisation request.

HTTP Request

POST https://api.yapily.com/users

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

Body Parameters

Parameter	Description
applicationUserId	Optional. Your application's user identifier (for example, an email, uuid or username)
referenceId	Optional. A reference string for your users (for example, real name or user group)

HTTP Response

The response returns a User.

Delete User

TODO

TODO

curl -X DELETE 'https://api.yapily.com/users/{user-uuid}' \ 
-u API_KEY:API_SECRET

TODO

{
  "meta": {
    "tracingId": "854db95cdf6ac32fee54e65dace5354b"
  },
  "data": {
    "id": "2a811012-de6b-478c-a872-13278f41690f",
    "deleteStatus": "SUCCESS",
    "creationDate": "2020-09-29T07:24:32.945Z",
    "userConsents": []
  }
}

Used to delete a User from the Application.

HTTP Request

DELETE https://api.yapily.com/user/<user-uuid>

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

URL Parameters

Parameter	Description
user-uuid	The uuid of the User to delete

HTTP Response

Parameter	Description
meta	An object containing a tracingId of the delete request
data	An object containing the results of the DELETE request, including a list of userConsents that were also deleted

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

Institution Model

Parameter	Description
id	The id of the `Institution`
name	The short name of the `Institution`
fullName	The full name of the `Institution`
countries	A list of country objects supported by the `Institution` The country object: displayName - the name of the country countryCode2 - the ISO country code
environmentType	The environment type for the `Institution`
credentialsType	The credentials type for the `Institution`
media	A list of media objects for the `Institution` The media object: source - the image source type - can be icon or logo
features	A list of features supported by the `Institution`

Get Institutions

TODO

TODO

curl 'https://api.yapily.com/institutions' \ 
-u API_KEY:API_SECRET

TODO

{
    "meta": {
        "tracingId": "125e13abc91c6745dceaba86f845ff00",
        "count": 1
    },
    "data": [{
        "id": "yapily-mock",
        "name": "Yapily Mock",
        "fullName": "Yapily Mock Bank",
        "countries": [{
            "displayName": "United Kingdom",
            "countryCode2": "UK"
        }],
        "environmentType": "SANDBOX",
        "credentialsType": "OPEN_BANKING_UK_MANUAL",
        "media": [{
            "source": "https://images.yapily.com/image/b5a23070-4fdb-403e-9537-f8e23fa2469b?size=0",
            "type": "logo"
        }, {
            "source": "https://images.yapily.com/image/4bbb9c1b-29e0-4cc9-8d01-b2ad2fcd57a3?size=0",
            "type": "icon"
        }],
        "features": ["INITIATE_ACCOUNT_REQUEST", "INITIATE_DOMESTIC_SCHEDULED_PAYMENT", "EXISTING_PAYMENTS_DETAILS", "CREATE_DOMESTIC_PERIODIC_PAYMENT", "ACCOUNT", "INITIATE_SINGLE_PAYMENT_SORTCODE", "INITIATE_DOMESTIC_SINGLE_PAYMENT", "CREATE_DOMESTIC_SINGLE_PAYMENT", "CREATE_SINGLE_PAYMENT_SORTCODE", "ACCOUNTS", "ACCOUNT_TRANSACTIONS_WITH_MERCHANT", "ACCOUNT_TRANSACTIONS", "CREATE_DOMESTIC_SCHEDULED_PAYMENT", "EXISTING_PAYMENT_INITIATION_DETAILS", "INITIATE_DOMESTIC_PERIODIC_PAYMENT"]
    }]
}

Used to retrieve all Institutions from the Application.

HTTP Request

GET https://api.yapily.com/institutions

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

HTTP Response

Parameter	Description
meta	An object containing a tracingId of the request
data	An list of Institutions

Get Institution

TODO

TODO

curl 'https://api.yapily.com/institutions/{institution-id}' \ 
-u API_KEY:API_SECRET

TODO

{
    "id": "yapily-mock",
    "name": "Yapily Mock",
    "fullName": "Yapily Mock Bank",
    "countries": [{
        "displayName": "United Kingdom",
        "countryCode2": "UK"
    }],
    "environmentType": "SANDBOX",
    "credentialsType": "OPEN_BANKING_UK_MANUAL",
    "media": [{
        "source": "https://images.yapily.com/image/b5a23070-4fdb-403e-9537-f8e23fa2469b?size=0",
        "type": "logo"
    }, {
        "source": "https://images.yapily.com/image/4bbb9c1b-29e0-4cc9-8d01-b2ad2fcd57a3?size=0",
        "type": "icon"
    }],
    "features": ["INITIATE_SINGLE_PAYMENT_SORTCODE", "ACCOUNTS", "INITIATE_DOMESTIC_SCHEDULED_PAYMENT", "EXISTING_PAYMENT_INITIATION_DETAILS", "ACCOUNT", "ACCOUNT_TRANSACTIONS_WITH_MERCHANT", "CREATE_DOMESTIC_SCHEDULED_PAYMENT", "ACCOUNT_TRANSACTIONS", "CREATE_DOMESTIC_PERIODIC_PAYMENT", "INITIATE_DOMESTIC_PERIODIC_PAYMENT", "INITIATE_ACCOUNT_REQUEST", "EXISTING_PAYMENTS_DETAILS", "INITIATE_DOMESTIC_SINGLE_PAYMENT", "CREATE_SINGLE_PAYMENT_SORTCODE", "CREATE_DOMESTIC_SINGLE_PAYMENT"]
}

Used to retrieve an Institution from the Application.

HTTP Request

GET https://api.yapily.com/institutions/<institution-id>

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

URL Parameters

Parameter	Description
institution-id	The ID of the `Institution`

HTTP Response

The response returns an Institution

Get Features

TODO

TODO

curl 'https://api.yapily.com/features' \ 
-u API_KEY:API_SECRET

TODO

{
    "meta": {
        "tracingId": "e85683f8091ee4df320dd2e789e79c63",
        "count": 48
    },
    "data": [{
        "feature": "ACCOUNT",
        "endpoint": "https://api.yapily.com/account/{account-id}",
        "documentationUrl": "https://docs.yapily.com/#757fde49-a294-bbff-d5f9-2c21c5f57be0"
    }, {
        "feature": "ACCOUNTS",
        "endpoint": "https://api.yapily.com/accounts",
        "documentationUrl": "https://docs.yapily.com/#23faf44e-1093-c676-63ea-369e41ea902d"
    }, {
        "feature": "ACCOUNTS_WITHOUT_BALANCE",
        "endpoint": "https://api.yapily.com/account-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "ACCOUNT_BALANCES",
        "endpoint": "https://api.yapily.com/account/{account-id}/balances",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "ACCOUNT_DIRECT_DEBITS",
        "endpoint": "https://api.yapily.com/account/{accountId}/direct-debits",
        "documentationUrl": "https://docs.yapily.com/#a5affc0a-c9cf-4203-b126-4a1bdcb7700a"
    }, {
        "feature": "ACCOUNT_PERIODIC_PAYMENTS",
        "endpoint": "https://api.yapily.com/account/{accountId}/periodic-payments",
        "documentationUrl": "https://docs.yapily.com/#98e43700-e9c7-4598-b337-42e86b099216"
    }, {
        "feature": "ACCOUNT_REQUEST_DETAILS",
        "endpoint": "https://api.yapily.com/account-request/{authRequestId}",
        "documentationUrl": "https://docs.yapily.com/#c8da0a20-6cb9-4282-aba5-4c66113eb70b"
    }, {
        "feature": "ACCOUNT_SCHEDULED_PAYMENTS",
        "endpoint": "https://api.yapily.com/account/{accountId}/scheduled-payments",
        "documentationUrl": "https://docs.yapily.com/#7eadb71e-d715-4c3f-927d-626c9e3a1303"
    }, {
        "feature": "ACCOUNT_STATEMENT",
        "endpoint": "https://api.yapily.com/account/{accountId}/statements/{statementId}",
        "documentationUrl": "https://docs.yapily.com/?version=latest#29101d1e-2c52-4d36-900a-18435dca75e0"
    }, {
        "feature": "ACCOUNT_STATEMENTS",
        "endpoint": "https://api.yapily.com/account/{accountId}/statements",
        "documentationUrl": "https://docs.yapily.com/#7358d865-3cf3-17da-cf0f-84a1af3b545f"
    }, {
        "feature": "ACCOUNT_STATEMENT_FILE",
        "endpoint": "https://api.yapily.com/account/{accountId}/statements/{statementId}/file",
        "documentationUrl": "https://docs.yapily.com/#3987b1e1-6b9c-4770-96de-fa85e2025d48"
    }, {
        "feature": "ACCOUNT_TRANSACTIONS",
        "endpoint": "https://api.yapily.com/account/{account-id}/transactions",
        "documentationUrl": "https://docs.yapily.com/#7358d865-3cf3-17da-cf0f-84a1af3b545f"
    }, {
        "feature": "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
        "endpoint": "https://api.yapily.com/accounts/{accountId}/transactions",
        "documentationUrl": "https://docs.yapily.com/#7358d865-3cf3-17da-cf0f-84a1af3b545f"
    }, {
        "feature": "ACCOUNT_WITHOUT_BALANCE",
        "endpoint": "https://api.yapily.com/account/{account-id}",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "CREATE_BULK_PAYMENT",
        "endpoint": "https://api.yapily.com/bulk-payments",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "CREATE_DOMESTIC_PERIODIC_PAYMENT",
        "endpoint": "https://api.yapily.com/payments",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "CREATE_DOMESTIC_SCHEDULED_PAYMENT",
        "endpoint": "https://api.yapily.com/payments",
        "documentationUrl": "https://docs.yapily.com/#1fd6bf92-7333-4b46-be2c-1a92a3c72b1c"
    }, {
        "feature": "CREATE_DOMESTIC_SINGLE_INSTANT_PAYMENT",
        "endpoint": "https://api.yapily.com/payments",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "CREATE_DOMESTIC_SINGLE_PAYMENT",
        "endpoint": "https://api.yapily.com/payments",
        "documentationUrl": "https://docs.yapily.com/#4521aa4d-75c2-4c22-9629-acb96c14e4e6"
    }, {
        "feature": "CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT",
        "endpoint": "https://api.yapily.com/payments",
        "documentationUrl": "https://docs.yapily.com/#1fd6bf92-7333-4b46-be2c-1a92a3c72b1c"
    }, {
        "feature": "CREATE_INTERNATIONAL_PERIODIC_PAYMENT",
        "endpoint": "https://api.yapily.com/payments",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "CREATE_INTERNATIONAL_SCHEDULED_PAYMENT",
        "endpoint": "https://api.yapily.com/payments",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "CREATE_INTERNATIONAL_SINGLE_PAYMENT",
        "endpoint": "https://api.yapily.com/payments",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "CREATE_SINGLE_PAYMENT_SORTCODE",
        "endpoint": "https://api.yapily.com/payment-sortcode",
        "documentationUrl": "https://docs.yapily.com/#4521aa4d-75c2-4c22-9629-acb96c14e4e6"
    }, {
        "feature": "EXISTING_PAYMENTS_DETAILS",
        "endpoint": "https://api.yapily.com/payments/{payment-id}",
        "documentationUrl": "https://docs.yapily.com/#2e1a151e-59a7-4fa1-bd5b-5f6a0c4bf4cd"
    }, {
        "feature": "EXISTING_PAYMENT_INITIATION_DETAILS",
        "endpoint": "https://api.yapily.com/payment-initiations/{paymentId}",
        "documentationUrl": "https://docs.yapily.com/#c8da0a20-6cb9-4282-aba5-4c66113eb70b"
    }, {
        "feature": "IDENTITY",
        "endpoint": "https://api.yapily.com/identity",
        "documentationUrl": "https://docs.yapily.com/#8c62ef0f-0cfa-98e6-6b0b-cb2441eb2d51"
    }, {
        "feature": "INITIATE_ACCOUNT_REQUEST",
        "endpoint": "https://api.yapily.com/account-auth-requests",
        "documentationUrl": "https://docs.yapily.com/#c8da0a20-6cb9-4282-aba5-4c66113eb70b"
    }, {
        "feature": "INITIATE_BULK_PAYMENT",
        "endpoint": "https://api.yapily.com/bulk-payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "INITIATE_DOMESTIC_PERIODIC_PAYMENT",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com#8e67c40c-4b0e-4f72-947c-065f1c84f46b"
    }, {
        "feature": "INITIATE_DOMESTIC_SINGLE_INSTANT_PAYMENT",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "INITIATE_DOMESTIC_SINGLE_PAYMENT",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com/#c8da0a20-6cb9-4282-aba5-4c66113eb70b"
    }, {
        "feature": "INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com/#8e67c40c-4b0e-4f72-947c-065f1c84f46b"
    }, {
        "feature": "INITIATE_INTERNATIONAL_PERIODIC_PAYMENT",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "INITIATE_INTERNATIONAL_SCHEDULED_PAYMENT",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "INITIATE_INTERNATIONAL_SINGLE_PAYMENT",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "INITIATE_PRE_AUTHORISATION",
        "endpoint": "https://api.yapily.com/pre-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "INITIATE_SINGLE_PAYMENT_SORTCODE",
        "endpoint": "https://api.yapily.com/payment-sortcode-auth-requests",
        "documentationUrl": "https://docs.yapily.com/#c8da0a20-6cb9-4282-aba5-4c66113eb70b"
    }, {
        "feature": "OPEN_DATA_ATMS",
        "endpoint": "https://api.yapily.com/institutions/{institution-id}/atms",
        "documentationUrl": "https://docs.yapily.com/#f5d271e1-8375-4a4a-a446-6ab9fd823f79"
    }, {
        "feature": "OPEN_DATA_PERSONAL_CURRENT_ACCOUNTS",
        "endpoint": "https://api.yapily.com/institutions/{institution-id}/personal-current-accounts",
        "documentationUrl": "https://docs.yapily.com/#6af35149-9db9-4eb4-862f-93187c64cbcd"
    }, {
        "feature": "PERIODIC_PAYMENT_FREQUENCY_EXTENDED",
        "endpoint": "https://api.yapily.com/payments",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "READ_DOMESTIC_PERIODIC_PAYMENT_REFUND",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "READ_DOMESTIC_SCHEDULED_REFUND",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "READ_DOMESTIC_SINGLE_REFUND",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "READ_INTERNATIONAL_SCHEDULED_REFUND",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "READ_INTERNATIONAL_SINGLE_REFUND",
        "endpoint": "https://api.yapily.com/payment-auth-requests",
        "documentationUrl": "https://docs.yapily.com"
    }, {
        "feature": "TRANSFER",
        "endpoint": "https://api.yapily.com/accounts/{accountId}/transfer",
        "documentationUrl": "https://docs.yapily.com/#c8da0a20-6cb9-4282-aba5-4c66113eb70b"
    }]
}

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.

HTTP Request

GET https://api.yapily.com/features

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	A list of Features

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.

Parameter	Description
id	The id of the `Consent`
userUuid	The userUuid associated with the `Consent`
applicationUserId	The applicationUserId associated with the `Consent`
institutionId	The institutionId associated with the `Consent`
status	The status of the `Consent`
createdAt	The timestamp that the `Consent` was created
transactionFrom	Used to specify the date the Consent will start pulling transactions from.
transactionTo	Used to specify the date the Consent will stop pulling transactions from.
expiresAt	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).
timeToExpire	Used to indicate the time until the Consent object expires as a ISO 8601 duration.
featureScope	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.
consentToken	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 request header Consent: "{{consent-token}}".
state	The correlation Id between the authorisation request to the institution and the OAuth2 redirect, OAuth2 specs.

Get Consents

TODO

TODO

curl 'https://api.yapily.com/consents' \ 
-u API_KEY:API_SECRET

TODO

{
  "meta": {
    "tracingId": "051f97f949c1aed5c08e683d16073f6d",
    "count": 2,
    "pagination": {
      "totalCount": 2,
      "self": {
        "sort": "-date",
        "offset": 0
      }
    }
  },
  "data": [{
    "id": "f1e3b031-f5bb-46a6-84b3-a55909a6372a",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "applicationUserId": "bojack@8tees.com",
    "institutionId": "yapily-mock",
    "status": "EXPIRED",
    "createdAt": "2020-09-13T15:57:46.450Z",
    "transactionFrom": "2017-05-03T00:00:00Z",
    "transactionTo": "2017-12-03T00:00:00Z",
    "expiresAt": "2020-09-13T16:27:46.445Z",
    "timeToExpire": "PT-375H-40M-21.397S",
    "featureScope": ["ACCOUNT", "ACCOUNTS", "ACCOUNT_TRANSACTIONS", "ACCOUNT_TRANSACTIONS_WITH_MERCHANT"],
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6ImYxZTNiMDMxLWY1YmItNDZhNi04NGIzLWE1NTkwOWE2MzcyYSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.TTP6eI5pxOQd-Gj7uUFRgoCwQRKA_i1qHaJCyRnV2lLO1icqtc6PlksXNlPbgZjfp5PjNFl7HVlUNJAOv08mxQ",
    "state": "754f6022f47548b99284f3f1993e050e"
  }, {
    "id": "28a8bf1e-bea4-4abd-99dc-605b14776474",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "applicationUserId": "bojack@8tees.com",
    "institutionId": "yapily-mock",
    "status": "EXPIRED",
    "createdAt": "2020-09-13T15:55:22.775Z",
    "transactionFrom": "2017-05-03T00:00:00Z",
    "transactionTo": "2017-12-03T00:00:00Z",
    "expiresAt": "2020-09-13T16:25:22.765Z",
    "timeToExpire": "PT-375H-42M-45.082S",
    "featureScope": ["ACCOUNT", "ACCOUNTS", "ACCOUNT_TRANSACTIONS", "ACCOUNT_TRANSACTIONS_WITH_MERCHANT"],
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6IjI4YThiZjFlLWJlYTQtNGFiZC05OWRjLTYwNWIxNDc3NjQ3NCIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.cx9wOWEAYug0bbxB-XPAmK265mVfr-ODNIP9aVtDXV8BGxOeY3t1truMINAzLfjrOHcVluhnfmVB4CG11ucRRA",
    "state": "754f6022f47548b99284f3f1993e050e"
  }]
}

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

HTTP Request

GET https://api.yapily.com/consents

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

Querystring Parameters

Parameter	Description
filter[applicationUserId]	Optional. Filter by comma separated list of applicationUserId strings.
filter[institution]	Optional. Filter by comma separated list of institution-id strings.
filter[status]	Optional. Filter by comma separated list of Consent object status strings.
filter[userUuid]	Optional. Filter by comma separated list of user-uuid strings.
before	Optional. Filter for Consent objects created before the given ISO-8601 date time string.
from	Optional. Filter for Consent objects created after the given ISO-8601 date time string.
limit	Optional. An integer to specify the limit of returned Consent objects.
offset	Optional. An integer to specify the offset of the returned Consent objects.

HTTP Response

Parameter	Description
meta	An object containing the tracingId of the request
data	A list of Consents

TODO

TODO

curl 'https://api.yapily.com/consents/{consent-id}' \ 
-u API_KEY:API_SECRET

TODO

{
  "meta": {
    "tracingId": "0683c130e8a2c553d9eb103e885bd865"
  },
  "data": {
    "id": "28a8bf1e-bea4-4abd-99dc-605b14776474",
    "userUuid": "fc65fb6a-b999-4278-943a-e48642a58c48",
    "applicationUserId": "bojack@8tees.com",
    "institutionId": "yapily-mock",
    "status": "EXPIRED",
    "createdAt": "2020-09-13T15:55:22.775Z",
    "transactionFrom": "2017-05-03T00:00:00Z",
    "transactionTo": "2017-12-03T00:00:00Z",
    "expiresAt": "2020-09-13T16:25:22.765Z",
    "timeToExpire": "PT-375H-47M-3.116S",
    "featureScope": ["ACCOUNT", "ACCOUNTS", "ACCOUNT_TRANSACTIONS", "ACCOUNT_TRANSACTIONS_WITH_MERCHANT"],
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6InlhcGlseS1tb2NrIiwiQ09OU0VOVCI6IjI4YThiZjFlLWJlYTQtNGFiZC05OWRjLTYwNWIxNDc3NjQ3NCIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJib2phY2tAOHRlZXMuY29tIiwiVVNFUiI6ImZjNjVmYjZhLWI5OTktNDI3OC05NDNhLWU0ODY0MmE1OGM0OCJ9.cx9wOWEAYug0bbxB-XPAmK265mVfr-ODNIP9aVtDXV8BGxOeY3t1truMINAzLfjrOHcVluhnfmVB4CG11ucRRA",
    "state": "754f6022f47548b99284f3f1993e050e"
  }
}

You can retrieve a specific consent using the id of the desired consent object.

HTTP Request

GET https://api.yapily.com/consents/<consent-id>

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

URL Parameters

Parameter	Description
consent-id	The ID of the `Consent` to retrieve

HTTP Response

Parameter	Description
meta	An object containing the tracingId of the request
data	The Consent object

TODO

TODO

curl -X DELETE 'https://api.yapily.com/consents/{consent-id}' \ 
-u API_KEY:API_SECRET

TODO

{
  "meta": {
    "tracingId": "124e87a37940000781fb0c9129541025"
  },
  "data": {
    "id": "28a8bf1e-bea4-4abd-99dc-605b14776474",
    "deleteStatus": "SUCCESS",
    "institutionId": "yapily-mock",
    "institutionConsentId": "urn-alphabank-intent-88379",
    "creationDate": "2020-09-13T15:55:22.775Z"
  }
}

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 Request or Create Payment Authorisation Request.

HTTP Request

DELETE https://api.yapily.com/consents/<consent-id>

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

URL Parameters

Parameter	Description
consent-id	The ID of the `Consent` to delete

Querystring Parameters

Parameter	Description
forceDelete	Optional. Force deletion of the consent irrespective of whether the response from the institution is successful or not. Default: false.

HTTP Response

Parameter	Description
meta	An object containing the tracingId of the request
data	An object containing the results of the DELETE request

Exchange One Time Token

TODO

TODO

curl --location --request POST 'https://api.yapily.com/consent-one-time-token' \
-H 'Content-Type: application/json' \
-u API_KEY:API_SECRET \
-d '{
 "oneTimeToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6ImJidmEtc2FuZGJveCIsIlVVSUQiOiJmMzNmNGU4ZC1jMDQ0LTQ2YTktOTlkMC0wYmRlMzIyYTJjOTIifQ.4Qv3NJI6av2nKi1U3aNmm71cIwJ3TvRsIlYDafQUVv_Khy_e-8oEpV_BoP4V1CII12oT-Yq4cPveHILz8BOwjg"
}'

TODO

{
    "id": "6ac7d85c-b72a-4b49-bf1a-8c07f61ba914",
    "userUuid": "d62aca7d-283a-4128-9536-881fa763c5df",
    "applicationUserId": "bojack@yapily.com",
    "institutionId": "modelo-sandbox",
    "status": "AUTHORIZED",
    "createdAt": "2020-05-11T14:02:09.109Z",
    "featureScope": [
        "CREATE_DOMESTIC_SINGLE_PAYMENT",
        "EXISTING_PAYMENTS_DETAILS",
        "EXISTING_PAYMENT_INITIATION_DETAILS"
    ],
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjZhYzdkODVjLWI3MmEtNGI0OS1iZjFhLThjMDdmNjFiYTkxNCIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJtb2ZlLnNhbGFtaUB5YXBpbHkuY29tIiwiVVNFUiI6ImQ2MmFjYTdkLTI4M2EtNDEyOC05NTM2LTg4MWZhNzYzYzVkZiJ9._VoLCPgsujK-kJXKJiQ04NmnAsSyzcqlH9GHMePZWZiSYGPL6QEnfXj9XiJS_FQTmuDDVSeujof9CfoV_ZdSKg",
    "state": "754f6022f47548b99284f3f1993e050e"
}

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.

HTTP Request

POST https://api.yapily.com/consent-one-time-token

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

Body Parameters

Parameter	Description
oneTimeToken	Required. The oneTimeToken to exchange for a consentToken.

HTTP Response

The Consent object

[Forwarding] Send Access Token

TODO

TODO

curl 'https://api.yapily.com/users/{user-uuid}/consents' \
-H 'Content-Type: application/json' \
-u API_KEY:API_SECRET \
-d '{
    "accessToken": "ACCESS_TOKEN",
    "refreshToken": "REFRESH_TOKEN",
    "scope": "SCOPE",
    "institutionId": "mock-sandbox"
}'

TODO

{
    "id": "4dd263e2-96fc-4be8-8c28-d931184e629f",
    "userUuid": "3d611a7e-af52-46f8-aa6c-f748dc44ffc7",
    "institutionId": "mock-sandbox",
    "status": "AUTHORIZED",
    "createdAt": "2020-11-25T09:29:17.074Z",
    "featureScope": [
        "ACCOUNT_TRANSACTIONS",
        "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
        "CREATE_DOMESTIC_SINGLE_PAYMENT",
        "INITIATE_DOMESTIC_SINGLE_PAYMENT",
        "INITIATE_DOMESTIC_PERIODIC_PAYMENT",
        "CREATE_DOMESTIC_PERIODIC_PAYMENT",
        "CREATE_DOMESTIC_SCHEDULED_PAYMENT",
        "ACCOUNTS",
        "EXISTING_PAYMENTS_DETAILS",
        "EXISTING_PAYMENT_INITIATION_DETAILS",
        "INITIATE_DOMESTIC_SCHEDULED_PAYMENT"
    ],
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vY2stc2FuZGJveCIsIkNPTlNFTlQiOiI0ZGQyNjNlMi05NmZjLTRiZTgtOGMyOC1kOTMxMTg0ZTYyOWYiLCJBUFBMSUNBVElPTl9VU0VSX0lEIjoiQW5pbCAtIFlhcGlseSBRQTEiLCJVU0VSIjoiM2Q2MTFhN2UtYWY1Mi00NmY4LWFhNmMtZjc0OGRjNDRmZmM3In0.ju2P4YPuApd4vT7h8XyPV7cUkDJWVuiY7mtW7SGVhDtA-R4LWtB4-ZiralnqonzGF6zMOkGUWKepdau2SlEP6Q",
    "state": "2fe4590418bb4ce69f6546137a371fb5",
    "authorizedAt": "2020-11-25T09:29:17.081Z"
}

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.

HTTP Request

POST https://api.yapily.com/users/<user-uuid>/consents

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

URL Parameters

Parameter	Description
user-uuid	The id of the user

Body Parameters

Parameter	Description
accessToken	The Oauth2 access-token
refreshToken	Optional The OAuth2 refresh-token
scope	Optional The OAuth2 scope
institutionId	the institutionId this token will associated with.

HTTP Response

The Consent object

[Forwarding] Send OAuth2 Code

TODO

TODO

curl --location --request POST 'https://api.yapily.com/consent-auth-code' \
-H 'Content-Type: application/json' \
-u API_KEY:API_SECRET \
-d '{
    "authCode": "871494d1-77f8-4474-92bb-eff28c9d2457",
    "authState": "754f6022f47548b99284f3f1993e050e"
}'

TODO

{
    "id": "ce2c9b01-7e7d-4f47-9494-d8325db86062",
    "userUuid": "7d2b947f-ccd7-48dd-b685-e3caef615f08",
    "institutionId": "modelo-sandbox",
    "status": "AUTHORIZED",
    "createdAt": "2020-11-23T15:49:52.259Z",
    "featureScope": [
        "IDENTITY",
        "ACCOUNT_STATEMENT_FILE",
        "ACCOUNT_DIRECT_DEBITS",
        "ACCOUNT_STATEMENT",
        "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
        "ACCOUNTS",
        "ACCOUNT_TRANSACTIONS",
        "ACCOUNT_BALANCES",
        "ACCOUNT_STATEMENTS",
        "ACCOUNT",
        "ACCOUNT_PERIODIC_PAYMENTS",
        "ACCOUNT_SCHEDULED_PAYMENTS"
    ],
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6ImNlMmM5YjAxLTdlN2QtNGY0Ny05NDk0LWQ4MzI1ZGI4NjA2MiIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJLaXJpeCBUZXN0IiwiVVNFUiI6IjdkMmI5NDdmLWNjZDctNDhkZC1iNjg1LWUzY2FlZjYxNWYwOCJ9._TMC4K7h_ZcDSftbwqi0O7AMw5GevSN1V8RjWhoexPa_ntcRt3oWRzmWN6SW9nU6awMsufLdAlNhHJ9Y1T7Rig",
    "state": "bdc26cbf3dfc4e8797f03875dae410d4"
}

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

HTTP Request

POST https://api.yapily.com/consent-auth-code

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)

Body Parameters

Parameter	Description
authCode	Received from the institution after the user has authenticated. See OAuth2 specs.
authState	Received from the institution after the user has authenticated. Used to correlate the authorisation request with the redirect, see OAuth2 specs.

HTTP Response

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

Authorisation Model

Parameter	Description
id	The id of the `Authorisation`
applicationUserId	The applicationUserId associated with the `Authorisation`
applicationUserId	The userUuid associated with the `Authorisation`
institutionId	The institutionId associated with the `Authorisation`
status	The status of the `Authorisation`
createdAt	The timestamp the `Authorisation` was created
expiresAt	The timestamp the `Authorisation` expires
timeToExpireInMillis	How long until the `Authorisation` expires
featureScope	The features supported by the `Authorisation`
charges	Conditional A list of charges for a BULK_PAYMENT request.
authorisationUrl	The authorisation URL to redirect the user to
qrCodeUrl	A QR Code of the authorisation URL

Create Account Authorisation

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

Feature: INITIATE_ACCOUNT_REQUEST

TODO

TODO

curl 'https://api.yapily.com/account-auth-requests' \ 
-u API_KEY:API_SECRET \ 
-H 'Content-Type: application/json' \ 
-d '{
    "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
    "institutionId": "forgerock-sandbox",
    "callback": "https://tpp.application/callback"
}'

TODO

{
    "meta": {
        "tracingId": "e570f627-ee15-4d89-a8db-0988da876329"
    },
    "data": {
        "id": "8dfb23cc-e554-454b-b7be-6e8fc9523102",
        "applicationUserId": "bojack@yapily.com",
        "institutionId": "forgerock-sandbox",
        "status": "AWAITING_AUTHORIZATION",
        "createdAt": "2018-10-17T14:42:53Z",
        "expiresAt": "2018-10-17T14:46:53Z",
        "timeToExpireInMillis": 239164,
        "featureScope": [
            "ACCOUNT",
            "ACCOUNT_TRANSACTIONS",
            "ACCOUNTS"
        ],
        "authorisationUrl": "https://as.aspsp.ob.forgerock.financial/oauth2/realms/root/realms/openbanking/authorize?client_id=9c54251f-3a45-4441-9665-02ef6be588b3&response_type=code+id_token&state=0f3cdf72e2fa4412b4840414807a6b75&nonce=0f3cdf72e2fa4412b4840414807a6b75&scope=openid+accounts&redirect_uri=https%3A%2F%2Fauth.yapily.com%2Fredirect&request=eyJraWQiOiItVEs5WXR4Njd5STRnVDZnR3huQTlSVFI1d28iLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczovL21hdGxzLmFzLmFzcHNwLm9iLmZvcmdlcm9jay5maW5hbmNpYWwvb2F1dGgyL29wZW5iYW5raW5nIiwic2NvcGUiOiJvcGVuaWQgYWNjb3VudHMiLCJpc3MiOiI5YzU0MjUxZi0zYTQ1LTQ0NDEtOTY2NS0wMmVmNmJlNTg4YjMiLCJjbGllbnRfaWQiOiI5YzU0MjUxZi0zYTQ1LTQ0NDEtOTY2NS0wMmVmNmJlNTg4YjMiLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vYXV0aC55YXBpbHkuY29tL3JlZGlyZWN0Iiwic3RhdGUiOiIwZjNjZGY3MmUyZmE0NDEyYjQ4NDA0MTQ4MDdhNmI3NSIsImNsYWltcyI6eyJpZF90b2tlbiI6eyJhY3IiOnsidmFsdWVzIjpbInVybjpvcGVuYmFua2luZzpwc2QyOnNjYSJdLCJlc3NlbnRpYWwiOnRydWV9LCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJBNzUzMDIwNTAtZTAxZi00MzYzLWIzODAtNmU5YmMyYjU4Yjk2IiwiZXNzZW50aWFsIjp0cnVlfX0sInVzZXJpbmZvIjp7Im9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6IkE3NTMwMjA1MC1lMDFmLTQzNjMtYjM4MC02ZTliYzJiNThiOTYiLCJlc3NlbnRpYWwiOnRydWV9fX0sIm5vbmNlIjoiMGYzY2RmNzJlMmZhNDQxMmI0ODQwNDE0ODA3YTZiNzUiLCJqdGkiOiIwOGI3NTcxZC04YTM2LTQ1YTEtYTdlMS0zYmE3MTZhM2UyM2IiLCJpYXQiOjE1Mzk3ODczNzMsImV4cCI6MTUzOTc4OTE3M30.RoyeyFmxI2ynQ3TeDjtXUz0AOoGmZ4O7xp2n4FMJIxp1xGvprH5PlkbddJiSnIbSKXj1dYt_fq1otuqjoNCUkwhjUMJwfTBtk9J6czj2qsOE9yMiW2_cXyaAQecD5S-NmIcyZey2cXwtbw8dEfgsud4UT4am3qatEefC7ImMyqlS0ekmkHmqsa9KZgQGW3Tqufg5VI9sqn4G6hkXjNmDPah5foIs9A-eNknqWc9FgPNlaiMJ2bH_941etRKRIOqEmNYtnK2QyDw5IZM4b4k3N7t1egjj14qp6aRBhFUIESDJJNDFbXD1dtVL0YopQue7JvDFtMGKJCalSvN1xZW_4w"
    }
}

HTTP Request

POST https://api.yapily.com/account-auth-requests

HTTP Headers

Parameter	Description
Content-Type	application/json
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
psu-id	Conditional. Represents the user's login ID for the Institution to a personal account. See PSU Identifiers to see which banks require this header
psu-corporate-id	Conditional. Represents the user's login ID for the Institution to a business account. See PSU Identifiers to see which banks require this header
psu-ip-address	Conditional. The IP address of the PSU. See PSU Identifiers to see which banks require this header

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	The Authorisation object

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

TODO

TODO

curl -X PATCH 'https://api.yapily.com/pre-auth-requests' \ 
-u API_KEY:API_SECRET \ 
-H 'Content-Type: application/json' \ 
-H 'Consent: {consent-token}'

TODO

{
  "meta": {
    "tracingId": "e570f627-ee15-4d89-a8db-0988da876329"
  },
  "data": {
    "id": "8dfb23cc-e554-454b-b7be-6e8fc9523102",
    "userUuid": "37138ee8-ab9a-496c-be98-07ae353fb876",
    "institutionId": "forgerock-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2018-10-17T14:42:53Z",
    "expiresAt": "2018-10-17T14:46:53Z",
    "timeToExpireInMillis": 239164,
    "featureScope": [
      "ACCOUNT",
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNTS"
    ],
    "authorisationUrl": "https://as.aspsp.ob.forgerock.financial/oauth2/realms/root/realms/openbanking/authorize?client_id=9c54251f-3a45-4441-9665-02ef6be588b3&response_type=code+id_token&state=0f3cdf72e2fa4412b4840414807a6b75&nonce=0f3cdf72e2fa4412b4840414807a6b75&scope=openid+accounts&redirect_uri=https%3A%2F%2Fauth.yapily.com%2Fredirect&request=eyJraWQiOiItVEs5WXR4Njd5STRnVDZnR3huQTlSVFI1d28iLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiJodHRwczovL21hdGxzLmFzLmFzcHNwLm9iLmZvcmdlcm9jay5maW5hbmNpYWwvb2F1dGgyL29wZW5iYW5raW5nIiwic2NvcGUiOiJvcGVuaWQgYWNjb3VudHMiLCJpc3MiOiI5YzU0MjUxZi0zYTQ1LTQ0NDEtOTY2NS0wMmVmNmJlNTg4YjMiLCJjbGllbnRfaWQiOiI5YzU0MjUxZi0zYTQ1LTQ0NDEtOTY2NS0wMmVmNmJlNTg4YjMiLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vYXV0aC55YXBpbHkuY29tL3JlZGlyZWN0Iiwic3RhdGUiOiIwZjNjZGY3MmUyZmE0NDEyYjQ4NDA0MTQ4MDdhNmI3NSIsImNsYWltcyI6eyJpZF90b2tlbiI6eyJhY3IiOnsidmFsdWVzIjpbInVybjpvcGVuYmFua2luZzpwc2QyOnNjYSJdLCJlc3NlbnRpYWwiOnRydWV9LCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJBNzUzMDIwNTAtZTAxZi00MzYzLWIzODAtNmU5YmMyYjU4Yjk2IiwiZXNzZW50aWFsIjp0cnVlfX0sInVzZXJpbmZvIjp7Im9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6IkE3NTMwMjA1MC1lMDFmLTQzNjMtYjM4MC02ZTliYzJiNThiOTYiLCJlc3NlbnRpYWwiOnRydWV9fX0sIm5vbmNlIjoiMGYzY2RmNzJlMmZhNDQxMmI0ODQwNDE0ODA3YTZiNzUiLCJqdGkiOiIwOGI3NTcxZC04YTM2LTQ1YTEtYTdlMS0zYmE3MTZhM2UyM2IiLCJpYXQiOjE1Mzk3ODczNzMsImV4cCI6MTUzOTc4OTE3M30.RoyeyFmxI2ynQ3TeDjtXUz0AOoGmZ4O7xp2n4FMJIxp1xGvprH5PlkbddJiSnIbSKXj1dYt_fq1otuqjoNCUkwhjUMJwfTBtk9J6czj2qsOE9yMiW2_cXyaAQecD5S-NmIcyZey2cXwtbw8dEfgsud4UT4am3qatEefC7ImMyqlS0ekmkHmqsa9KZgQGW3Tqufg5VI9sqn4G6hkXjNmDPah5foIs9A-eNknqWc9FgPNlaiMJ2bH_941etRKRIOqEmNYtnK2QyDw5IZM4b4k3N7t1egjj14qp6aRBhFUIESDJJNDFbXD1dtVL0YopQue7JvDFtMGKJCalSvN1xZW_4w"
  }
}

HTTP Request

PATCH https://api.yapily.com/account-auth-requests

HTTP Headers

Parameter	Description
Content-Type	application/json
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent-Token	The Consent-Token obtained from the original authorisation.
psu-id	Conditional. Represents the user's login ID for the Institution to a personal account. See PSU Identifiers to see which banks require this header
psu-corporate-id	Conditional. Represents the user's login ID for the Institution to a business account. See PSU Identifiers to see which banks require this header
psu-ip-address	Conditional. The IP address of the PSU. See PSU Identifiers to see which banks require this header

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	The Authorisation object

Create Payment Authorisation

INITIATE_DOMESTIC_INSTANT_PAYMENT
INITIATE_DOMESTIC_PERIODIC_PAYMENT
INITIATE_DOMESTIC_SCHEDULED_PAYMENT
INITIATE_DOMESTIC_SINGLE_PAYMENT
INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT
INITIATE_INTERNATIONAL_PERIODIC_PAYMENT
INITIATE_INTERNATIONAL_SCHEDULED_PAYMENT
INITIATE_INTERNATIONAL_SINGLE_PAYMENT

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.

TODO

TODO

curl 'https://api.yapily.com/payment-auth-requests' \ 
-u API_KEY:API_SECRET \ 
-H 'Content-Type: application/json' \ 
-d '{
    "applicationUserId": "{{application-user-id}}",
    "institutionId": "{{institution-id}}",
    "callback": "{{callback-url}}",
    "paymentRequest": {
        "type": "DOMESTIC_PAYMENT",
        "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
        "reference": "REFERENCE",
        "contextType": "OTHER",
        "amount": {
        "amount": "4.00",
        "currency": "GBP"
    },
    "payee": {
        "name": "John Doe",
        "address": {
        "country": "GB"
    },
    "accountIdentifications": [
        {
            "type": "SORT_CODE",
            "identification": "123456"
        },
        {
            "type": "ACCOUNT_NUMBER",
            "identification": "12345678"
        }
    ]
}'

TODO

{
    "meta": {
        "tracingId": "274109a96f3c8ddd9d46c7d18e964eaf"
    },
    "data": {
        "id": "e7f1b269-943b-445b-8cea-b0556ceb8048",
        "userUuid": "27aa4942-de6a-4acc-b133-bdeee40c939e",
        "applicationUserId": "user12345",
        "institutionId": "monzo_ob",
        "status": "AWAITING_AUTHORIZATION",
        "createdAt": "2020-08-05T10:11:06.625Z",
        "featureScope": [
            "CREATE_DOMESTIC_SINGLE_PAYMENT",
            "EXISTING_PAYMENTS_DETAILS",
            "EXISTING_PAYMENT_INITIATION_DETAILS"
        ],
        "authorisationUrl": "https://verify.monzo.com/open-banking/authorize?client_id=oauth2client_00009pp1CRt4KarIZM7Pr1&response_type=code+id_token&state=6f3926d09372453595fac3fa6754e01c&nonce=6f3926d09372453595fac3fa6754e01c&scope=openid+payments&redirect_uri=https%3A%2F%2Fauth.yapily.com%2F&request=eyJraWQiOiJPNWp3ZXpxTlNzeVlacHotZHpfVUhEbkJINHciLCJhbGciOiJQUzI1NiJ9.eyJhdWQiOiJodHRwczovL2FwaS5tb256by5jb20vb3Blbi1iYW5raW5nLyIsInNjb3BlIjoib3BlbmlkIHBheW1lbnRzIiwiaXNzIjoib2F1dGgyY2xpZW50XzAwMDA5cHAxQ1J0NEthcklaTTdQcjEiLCJjbGllbnRfaWQiOiJvYXV0aDJjbGllbnRfMDAwMDlwcDFDUnQ0S2FySVpNN1ByMSIsInJlc3BvbnNlX3R5cGUiOiJjb2RlIGlkX3Rva2VuIiwicmVkaXJlY3RfdXJpIjoiaHR0cHM6Ly9hdXRoLnlhcGlseS5jb20vIiwic3RhdGUiOiI2ZjM5MjZkMDkzNzI0NTM1OTVmYWMzZmE2NzU0ZTAxYyIsImNsYWltcyI6eyJpZF90b2tlbiI6eyJhY3IiOnsidmFsdWVzIjpbInVybjpvcGVuYmFua2luZzpwc2QyOnNjYSJdLCJlc3NlbnRpYWwiOnRydWV9LCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJvYnBpc3Bkb21lc3RpY3BheW1lbnRjb25zZW50XzAwMDA5eG9ESXJMQnowYlVma0tOaFIiLCJlc3NlbnRpYWwiOnRydWV9fSwidXNlcmluZm8iOnsib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoib2JwaXNwZG9tZXN0aWNwYXltZW50Y29uc2VudF8wMDAwOXhvRElyTEJ6MGJVZmtLTmhSIiwiZXNzZW50aWFsIjp0cnVlfX19LCJub25jZSI6IjZmMzkyNmQwOTM3MjQ1MzU5NWZhYzNmYTY3NTRlMDFjIiwianRpIjoiMjJhZTRmODgtNjgzZi00NWYwLTgxNDYtZjdhN2U3ZWY2NzA5IiwiaWF0IjoxNTk2NjIyMjY2LCJleHAiOjE1OTY2MjQwNjZ9.fGz7g_tE_oAtbvBqmbcvzBdGFL79NIv2mA99ZjvMVlqqqVW1mohY2_1MaRE27w5WVzrOYYe1h-gCKTA95m5znZFD3eWgDLiqTTaB08KZrv4Vi0tmzsITDcXSLNQKj3N8znck7iTPUYHTqVZyMcoxV7e3hPHrSexVzo5eVtaIX5AHAG0tu3_qWyIRe7h48D55jJGyc7bD7bt5Q73jsEgz4sYos15pOYkxd7W-74arLS10Pube-SjGWoBVFXtPj_pwaxbj9Ub-P7WuhMw5r9Qvaf0rB0Yg0QdTiaCvn05oRD7ssVTezGqHEf5aDu3HXHBfD45f0siFxo5a8QGM2fGaYA",
        "qrCodeUrl": "https://images.yapily.com/image/080b9721-9cc5-4ec5-a882-8aab5c67752a/1596622266?size=0"
    }
}

HTTP Request

POST https://api.yapily.com/payment-auth-requests

HTTP Headers

Parameter	Description
Content-Type	application/json
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
psu-id	Conditional. Represents the user's login ID for the Institution to a personal account. See PSU Identifiers to see which banks require this header
psu-corporate-id	Conditional. Represents the user's login ID for the Institution to a business account. See PSU Identifiers to see which banks require this header
psu-ip-address	Conditional. The IP address of the PSU. See PSU Identifiers to see which banks require this header

Body Parameters

Parameter	Description
callback	The callback url to receive the consent token.
paymentRequest	Mandatory. This PaymentRequest object sent as the payload to Create Payment.
institutionId	Mandatory. Used to identify the Institution that holds your user's account.
applicationUserId	Conditional. Used to identify the user who will authorise access to their data. Either the user-uuid or application-user-id must be provided.
userUuid	Conditional. Used to identify the user who will authorise access to their data. Either the user-uuid or application-user-id must be provided.
allowOverdraft	Optional. Used to allow payments to be initiated from an overdraft when the user does not have enough balance
expiresAt	Optional. Used exclusively with Variable Recurring Payments. The date at which the last VRP payment can be made
maxAmountPerRequest	Conditional. Used exclusively with Variable Recurring Payments. Mandatory for VRP payments to define the maximum amount that can be made in each payment belonging to a single VRP Consent
oneTimeToken	Optional. Should be marked as true to receive a one time token. This field can only be used when the callback url is set.
startsAt	Optional. Used exclusively with Variable Recurring Payments. The date at which the first VRP payment can be made
totalMaxAmount	Conditional. Used exclusively with Variable Recurring Payments. Mandatory for VRP payments to define the maximum total amount that can be made across the sum of all payments belonging to a single VRP Consent

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	The Authorisation object

Create Bulk Payment Authorisation

Feature: INITIATE_BULK_PAYMENT

Used to initiate the payment authorisation process for a business account and direct users to the login screen of their financial institution in order to give their consent for a bulk payment.

TODO

TODO

curl 'https://api.yapily.com/bulk-payment-auth-requests' \ 
-u API_KEY:API_SECRET \ 
-H 'Content-Type: application/json' \ 
-d '{
    "userUuid": "b1aaf0a7-668f-4fa8-a276-cc9fdde7fa05",
    "institutionId": "barclays",
    "callback": "{{callback-url}}",
    "oneTimeToken": false,
    "paymentRequest": {
        "executionDateTime": "2020-10-17T00:00:00Z",
        "payments": [
            {
                "type": "DOMESTIC_PAYMENT",
                "paymentIdempotencyId": "payment1-id-23930482",
                "reference": "payment1",
                "amount": {
                    "amount": "2.00",
                    "currency": "GBP"
                },
                "payee": {
                    "name": "nicholas smith",
                    "accountIdentifications": [
                        {
                            "type": "ACCOUNT_NUMBER",
                            "identification": "12345678"
                        },
                        {
                            "type": "SORT_CODE",
                            "identification": "123456"
                        }
                    ]
                }
            },
            {
                "type": "DOMESTIC_PAYMENT",
                "paymentIdempotencyId": "payment2-id-23034517",
                "reference": "payment2",
                "amount": {
                    "amount": "5.00",
                    "currency": "GBP"
                },
                "payee": {
                    "name": "michael davis",
                    "accountIdentifications": [
                        {
                            "type": "ACCOUNT_NUMBER",
                            "identification": "12345678"
                        },
                        {
                            "type": "SORT_CODE",
                            "identification": "123456"
                        }
                    ]
                }
            }
        ]
    }
}'

TODO

{
  "meta": {
    "tracingId": "node01ignvwrzs1xbe14qhz2feqjwd71"
  },
  "data": {
    "id": "4a5d1b95-cf15-4775-a93d-fd02968a4a61",
    "applicationUserId": "user12345",
    "userUuid": "b1aaf0a7-668f-4fa8-a276-cc9fdde7fa05",
    "institutionId": "barclays",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2020-05-04T14:31:04.872Z",
    "featureScope": [
      "EXISTING_PAYMENTS_DETAILS",
      "CREATE_BULK_PAYMENT",
      "EXISTING_PAYMENT_INITIATION_DETAILS"
    ],
    "charges": [
      {
        "chargeAmount": {
          "amount": 7
        },
        "chargeType": "BULK_PAYMENT"
      }
    ],
    "authorisationUrl": "https://oauth.tiaa.barclays.com/BarclaysPersonal/as/authorization.oauth2?client_id=bdn-...",
    "qrCodeUrl": "https://images.yapily.com/image/153c1b5f-ff8b-4df4-a873-585bcad69f0c/1596703841?size=0"
  }
}

HTTP Request

POST https://api.yapily.com/bulk-payment-auth-requests

HTTP Headers

Parameter	Description
Content-Type	application/json
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
psu-id	Conditional. Represents the user's login ID for the Institution to a personal account. See PSU Identifiers to see which banks require this header
psu-corporate-id	Conditional. Represents the user's login ID for the Institution to a business account. See PSU Identifiers to see which banks require this header
psu-ip-address	Conditional. The IP address of the PSU. See PSU Identifiers to see which banks require this header

Body Parameters

Parameter	Description
callback	The callback url to receive the consent token.
applicationUserId	Conditional. Your identifier for the application user. Either the userUuid or applicationUserId must be provided
institutionId	Mandatory. The identifier for the Institution that the user will use to authorise the payment from
oneTimeToken	Optional. Should be marked as true to receive a one time token. This field can only be used when the callback url is set.
paymentRequest	Mandatory. This BulkPaymentRequest object is the payload you must submit when you execute Create Bulk Payment.
userUuid	Conditional. The uuid for your application user. Either the userUuid or applicationUserId must be provided.

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	The Authorisation object

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.

Account Model

Parameter	Description
id	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.)
type	The type of the account
description	The product name as defined by the financial institution for this account.
balance	The balance of the account.
currency	The ISO 4217 Currency code.
usageType	The usage type for the account. Possible values are: PERSONAL BUSINESS OTHER UNKNOWN
accountType	The type of account. Possible values are: 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
nickname	The name of the account as defined by the financial institution or the end user.
details	The specifications that might be provided by the institution: characteristics of the account or characteristics of the relevant card
accountBalances	An array of AccountBalance objects.
accountIdentifications	An array of AccountIdentification objects. The AccountIdentification object: type - Required. The type of account identifier. Possible values are: SORT_CODE ACCOUNT_NUMBER IBAN BBAN BIC PAN MASKED_PAN MSISDN BSB NCC ABA ABA_WIRE ABA_ACH EMAIL identification - Required. The value of the enumeration type
accountNames	An array of AccountName objects. The AccountName object: name - One of the names for the account

AccountBalance model

Parameter	Description
type	The OBBalanceType1Code balance type. The possible values are listed below in Balance Types
datetime	The timestamp of the last change of the balance amount.
balanceAmount	An Amount object containing `amount` and `currency`
creditLineIncluded	Indicates whether or not the credit line is included in the balance
creditLines	The array of CreditLine objects containing `creditLineAmount` and `type` with possible values: AVAILABLE CREDIT EMERGENCY PRE_AGREED TEMPORARY OTHER UNKNOWN

Balance Types

Parameter	Description
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.
OTHER	Used when an unrecognised enum is parsed
UNKNOWN	Used as a Yapily default

Transaction Model

Parameter	Description
addressDetails	The AddressDetails of the transaction The AddressDetails object: addressLine - The address line of the address.
balance	An AccountBalance object.
bookingDateTime	The date and (if available) time that transaction is posted. Note: It is quite common for an Institution to return a time of 12:00:00.
chargeDetails	An ChargeDetails object. The ChargeDetails object: chargeAmount - An Amount object containing `amount` and `currency`
currencyExchange	An CurrencyExchange object. The CurrencyExchange object: sourceCurrency - The ISO 4217 currency code denoting the currency of the creditor. targetCurrency - The ISO 4217 currency code denoting the currency of the debtor. unitCurrency - 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). exchangeRate - The currency exchange rate.
date	The transaction date as defined by the institution. Note: It is quite common for an Institution to return a time of 12:00:00.
description	Unstructured text containing details of the transaction. Usage varies according to the Institution.
enrichment	An Enrichment object.
id	The transaction Id returned by the institution if present.
isoBankTransactionCode	An IsoBankTransactionCode object. The IsoBankTransactionCode object: domainCode - An object containing `code` and `name` familyCode - An object containing `code` and `name` subFamilyCode - An object containing `code` and `name`
merchant	An Merchant object. The Merchant object: merchantName - The name of the merchant. merchantCategoryCode - The merchant category code.
proprietaryBankTransactionCode	The ProprietaryBankTransactionCode object. The ProprietaryBankTransactionCode object: code type
reference	The transaction reference.
statementReferences	An array of StatementReference objects. The StatementReference object: value
status	The status of the transaction. Possible values are: BOOKED PENDING
supplementaryData	Additional information that can not be captured in the structured fields and/or any other specific block.
transactionAmount	An Amount object containing `amount` and `currency`
transactionInformation	An array of further information related to the transaction. Usage varies according to the Institution.
valueDateTime	The actual or expected date and time transaction is cleared. Note: It is quite common for an Institution to return a time of 12:00:00.

Enrichment Model

Parameter	Description
categorisation	An Categorisation object The Categorisation object: category - A Category object containing `label` and `id`
transactionHash	An TransactionHash object The TransactionHash object: hash - The hash given to uniquely identify the transaction.

DirectDebit Model

Parameter	Description
id	A unique identifier used to identify the direct debit resource String
statusDetails	Details of the direct debit status.
statusDetails.status	Status. Possible values are ACTIVE , INACTIVE or UNKNOWN.
payee	Contains details about the beneficiary.
payee.name	The name of the beneficiary.
reference	A code that is unique to the Direct Debit, provided by the company claiming the payment.
previousPaymentAmount	Contains details of the most recent direct debit collection.
previousPaymentAmount.amount	A number of monetary units specified in an active currency.
previousPaymentAmount.currency	3-letter currency code.
previousPaymentDateTime	The date of the most recent direct debit collection.

Scheduled Payments Model

Parameter	Description
id	A unique identifier used to identify the scheduled payment resource.
reference	Unique reference, as assigned by the beneficiary, to unambiguously refer to the payment transaction.
payee	Contains details about the beneficiary.
payee.accountIdentifications	List of account identification objects containing details about the beneficiary's account details.
payee.accountIdentifications.type	Provides the value to identify the beneficiary account identification type. Possible values SORT_CODE, ACCOUNT_NUMBER, IBAN, BBAN, SWIFT, BIC, PAN, MASKED_PAN, MSISDN, ABA, ABA_WIRE, ABA_ACH.
payee.accountIdentifications.identification	Provides the value to identify the beneficiary account identification.
payee.name	The name of the beneficiary.
amountDetails	Contains details of monetary value and currency to be moved from payer to payee (the beneficiary).
amountDetails.amount	Amount of money to be moved between payer and payee (the beneficiary) in terms of the major unit of currency.
amountDetails.currency	The 3-letter currency code.
scheduledPaymentDateTime	The date on which the scheduled payment will be initiated
scheduledPaymentType	Specifies the scheduled payment type requested. Possible values are Arrival or Execution.

Periodic Payments Model

Parameter	Description
id	A unique identifier used to identify the periodic payment order resource.
statusDetails	Details of the periodic payments status.
statusDetails.status	Status of a Periodic Payment Order. Possible values are ACTIVE, INACTIVE or UNKNOWN.
payee	Contains details about the beneficiary.
payee.accountIdentifications	Contains details about the beneficiary's account details.
payee.accountIdentifications.type	Beneficiary account identification type. Possible values SORT_CODE, ACCOUNT_NUMBER, IBAN, BBAN, SWIFT, BIC, PAN, MASKED_PAN, MSISDN, ABA, ABA_WIRE, ABA_ACH
payee.accountIdentifications.identification	Provides the value to identify the beneficiary account identification.
payee.name	The name of the beneficiary.
reference	Unique reference, as assigned by the beneficiary, to unambiguously refer to the payment transaction.
firstPaymentAmount	The amount of the first Periodic Payment.
firstPaymentAmount.amount	A number of monetary units specified in an active currency.
firstPaymentAmount.currency	The 3-letter currency code.
firstPaymentDateTime	The date on which the first payment for a Periodic Payment schedule will be made.
nextPaymentAmount	Contains the amount and currency of the next periodic payment.
nextPaymentAmount.amount	A number of monetary units specified in an active currency where the unit of currency.
nextPaymentAmount.currency	The 3-letter currency code.
nextPaymentDateTime	The date on which the next payment for a Periodic Order schedule will be made.
finalPaymentAmount	Contains the amount and currency of the final periodic payment.
finalPaymentAmount.amount	A number of monetary units specified in an active currency where the unit of currency.
finalPaymentAmount.currency	The 3-letter currency code.
finalPaymentDateTime	The date on which the final payment for a Periodic Payment schedule will be made.
frequency	The frequency details of the Periodic Payment.
frequency.frequencyType	The frequency value of the periodic payment. Possible values are DAILY, EVERY_WORKING_DAY, CALENDAR_DAY, WEEKLY, EVERY_TWO_WEEKS, MONTHLY, EVERY_TWO_MONTHS, QUARTERLY, SEMIANNUAL, ANNUAL.
frequency.intervalWeek	The intervalWeek is used with frequency value of WEEKLY or MONTHLY. It is used to define the frequency of the week (i.e. every 2nd week) or week in a month ( i.e. 2nd week of a month).
frequency.intervalMonth	The intervalMonth is used with frequency value of MONTHLY. It is used to define the frequency of the month (i.e. every 4th month).
frequency.executionDay	The executionDay is used to define the day on which payment is to be executed. (i.e. Every 2nd week, on the 3rd day of the week. Here executionDay is 3.).

Identity Model

Parameter	Description
id	The id of the Identity
firstName	The first name of the account holder
lastName	The last name of the account holder
gender	The gender of the account holder
birthdate	The birthday of the account holder
email	The email of the account holder
phone	The phone of the account holder
addresses	A list of addresses for the account holder

Get Accounts

Features: ACCOUNTS, ACCOUNTS_WITHOUT_BALANCE

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

TODO

TODO

curl 'https://api.yapily.com/accounts' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
    "meta": {
        "tracingId": "e36daf9e1c079a2ff8117c0077f82840",
        "count": 1
    },
    "data": [
        {
            "id": "aadn1pyst5ka1o1x8gkklori09n60rtgcr5t",
            "type": "Personal - Current",
            "description": "HSBC ADVANCE",
            "balance": 5313.40,
            "currency": "GBP",
            "usageType": "PERSONAL",
            "accountType": "CURRENT",
            "accountNames": [
                {
                    "name": "DOE J"
                }
            ],
            "accountIdentifications": [
                {
                    "type": "SORT_CODE",
                    "identification": "123456"
                },
                {
                    "type": "ACCOUNT_NUMBER",
                    "identification": "12345678"
                }
            ],
            "accountBalances": [
                {
                    "type": "INTERIM_AVAILABLE",
                    "dateTime": "2020-09-21T16:35:55Z",
                    "balanceAmount": {
                        "amount": 5262.73,
                        "currency": "GBP"
                    },
                    "creditLineIncluded": false,
                    "creditLines": [
                        {
                            "type": "TEMPORARY",
                            "creditLineAmount": {
                                "amount": 0.00,
                                "currency": "GBP"
                            }
                        }
                    ]
                },
                {
                    "type": "EXPECTED",
                    "dateTime": "2020-09-21T16:35:55Z",
                    "balanceAmount": {
                        "amount": 5313.40,
                        "currency": "GBP"
                    },
                    "creditLineIncluded": false,
                    "creditLines": []
                }
            ]
        }
    ]
}

HTTP Request

GET https://api.yapily.com/accounts

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	A list of Accounts

Get Account

Feature: ACCOUNT_WITHOUT_BALANCE

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

TODO

TODO

curl 'https://api.yapily.com/accounts/{account-id}' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
    "meta": {
        "tracingId": "6f936f73-32b9-4817-9e26-5d01b31493f7"
    },
    "data": {
        "id": "aadn1pyst5ka1o1x8gkklori09n60rtgcr5t",
        "type": "Personal - Current",
        "description": "HSBC ADVANCE",
        "balance": 5313.4,
        "currency": "GBP",
        "usageType": "PERSONAL",
        "accountType": "CURRENT",
        "accountNames": [
            {
                "name": "DOE J"
            }
        ],
        "accountIdentifications": [
            {
                "type": "SORT_CODE",
                "identification": "123456"
            },
            {
                "type": "ACCOUNT_NUMBER",
                "identification": "12345678"
            }
        ],
        "accountBalances": [
            {
                "type": "INTERIM_AVAILABLE",
                "dateTime": "2020-09-21T16:35:55Z",
                "balanceAmount": {
                    "amount": 5262.73,
                    "currency": "GBP"
                },
                "creditLineIncluded": false,
                "creditLines": [
                    {
                        "type": "TEMPORARY",
                        "creditLineAmount": {
                            "amount": 0,
                            "currency": "GBP"
                        }
                    }
                ]
            },
            {
                "type": "EXPECTED",
                "dateTime": "2020-09-21T16:35:55Z",
                "balanceAmount": {
                    "amount": 5313.4,
                    "currency": "GBP"
                },
                "creditLineIncluded": false,
                "creditLines": []
            }
        ]
    }
}

HTTP Request

GET https://api.yapily.com/accounts/<account-id>

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
account-id	The id of the `Account`

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	The Account object

Get Account Balances

Feature: ACCOUNT_BALANCES

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

TODO

TODO

curl 'https://api.yapily.com/accounts/{account-id}/balances' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{ }

HTTP Request

GET https://api.yapily.com/accounts/<account-id>/balances

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
account-id	The id of the `Account`

HTTP Response

The response returns a BalanceAccount object.

Get Account Transactions

Feature: ACCOUNT_TRANSACTIONS

Used to get the transactions from a specific account.

TODO

TODO

curl 'https://api.yapily.com/accounts/{account-id}/transactions' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
  "meta": {
    "tracingId": "cca49220-5ae4-4496-a202-2e3d622659e2",
    "count": 3
  },
  "data": [
    {
      "id": "d6f8ee30-7804-4c62-9457-fe64fcd23fc2",
      "date": "2019-04-20T23:54:10.937Z",
      "bookingDateTime": "2019-04-20T23:54:10.937Z",
      "valueDateTime": "2019-04-18T23:54:11.937Z",
      "status": "BOOKED",
      "amount": -400,
      "currency": "GBP",
      "transactionAmount": {
        "amount": -400,
        "currency": "GBP"
      },
      "currencyExchange": {
        "sourceCurrency": "GBP",
        "targetCurrency": "EUR",
        "unitCurrency": "GBP",
        "exchangeRate": 1.1528
      },
      "chargeDetails": {
        "chargeAmount": {
          "amount": 0.5,
          "currency": "GBP"
        }
      },
      "description": "Exchanged to EUR",
      "transactionInformation": [
        "Exchanged to EUR"
      ],
      "proprietaryBankTransactionCode": {
        "code": "EXCHANGE",
        "issuer": "Revolut"
      },
      "balance": {
        "type": "INTERIM_BOOKED",
        "balanceAmount": {
          "amount": 0,
          "currency": "GBP"
        }
      }
    },
    {
      "id": "80c03e9e-9f28-4668-9daf-42072f5aad98",
      "date": "2019-04-17T10:16:10.487Z",
      "bookingDateTime": "2019-04-17T10:16:10.487Z",
      "valueDateTime": "2019-04-18T23:54:11.937Z",
      "status": "BOOKED",
      "amount": 400,
      "currency": "GBP",
      "transactionAmount": {
        "amount": 400,
        "currency": "GBP"
      },
      "reference": "Wallpaper money",
      "statementReferences": [
        {
          "value": "They sent you money for carrots"
        }
      ],
      "description": "Payment from Hollyhock",
      "transactionInformation": [
        "Payment from Hollyhock"
      ],
      "proprietaryBankTransactionCode": {
        "code": "TOPUP",
        "issuer": "Revolut"
      },
      "balance": {
        "type": "INTERIM_BOOKED",
        "balanceAmount": {
          "amount": 400,
          "currency": "GBP"
        }
      }
    },
    {
      "id": "8b884d06-9efd-48cc-8ac7-edd21a8ef151",
      "date": "2019-04-16T10:16:10.487Z",
      "bookingDateTime": "2019-04-16T10:16:10.487Z",
      "valueDateTime": "2019-04-17T23:54:11.937Z",
      "status": "BOOKED",
      "amount": -150,
      "currency": "GBP",
      "transactionAmount": {
        "amount": -150,
        "currency": "GBP"
      },
      "description": "Pay bakery store",
      "transactionInformation": [
        "Pay bakery store"
      ],
      "addressDetails": {
        "addressLine": "123 Luxe St, London, WC1 GTF"
      },
      "proprietaryBankTransactionCode": {
        "code": "PURCHASE",
        "issuer": "Revolut"
      },
      "balance": {
        "type": "INTERIM_BOOKED",
        "balanceAmount": {
          "amount": 0,
          "currency": "GBP"
        }
      },
      "merchant": {
        "merchantName": "London Luxury Baker",
        "merchantCategoryCode": "5462"
      }
    }
  ]
}

HTTP Request

GET https://api.yapily.com/accounts/<account-id>/transactions

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
account-id	The id of the `Account`

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	A list of Transactions for the account.

Get Account Statements

Feature: ACCOUNT_STATEMENTS

Used to get the statements from a specific account.

TODO

TODO

curl 'https://api.yapily.com/accounts/{account-id}/statements' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
  "meta": {
    "tracingId": "cca49220-5ae4-4496-a202-2e3d622659e2",
    "count": 3
  },
  "data": [
    {
      "id": "140000000000000000000001",
      "startDateTime": "2017-03-01T00:00:00Z",
      "endDateTime": "2017-03-31T23:59:59Z",
      "creationDateTime": "2017-04-01T00:00:00Z"
    },
    {
      "id": "140000000000000000000002",
      "startDateTime": "2017-02-01T00:00:00Z",
      "endDateTime": "2017-02-31T23:59:59Z",
      "creationDateTime": "2017-03-01T00:00:00Z"
    },
    {
      "id": "140000000000000000000003",
      "startDateTime": "2017-01-01T00:00:00Z",
      "endDateTime": "2017-01-31T23:59:59Z",
      "creationDateTime": "2017-02-01T00:00:00Z"
    }
  ]
}

HTTP Request

GET https://api.yapily.com/accounts/<account-id>/statements

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
account-id	The id of the `Account`

Querystring Parameters

Parameter	Description
from	Optional. The date to start looking for account statements. Note: For some institutions the from and before dates need to be within the range of the consent.
before	Optional. The date to stop looking for account statements. Note: For some institutions the from and before dates need to be within the range of the consent.

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	An array of objects containing id for available statements

Get Account Statement

Feature: ACCOUNT_STATEMENT

Used to get a statement from a specific account.

TODO

TODO

curl 'https://api.yapily.com/accounts/{account-id}/statements/{statement-id}' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
  "meta": {
    "tracingId": "cca49220-5ae4-4496-a202-2e3d622659e2"
  },
  "data": {
    "id": "140000000000000000000001",
    "startDateTime": "2017-03-01T00:00:00Z",
    "endDateTime": "2017-03-31T23:59:59Z",
    "creationDateTime": "2017-04-01T00:00:00Z"
  }
}

HTTP Request

GET https://api.yapily.com/accounts/<account-id>/statements/<statement-id>

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
account-id	The id of the `Account`
statement-id	The id of the Statement

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	A statement object containing the Id, startDateTime, endDateTime and creationDateTime

Get Account Statement File

Feature: ACCOUNT_STATEMENT_FILE

Download the specific statement file for an account.

TODO

TODO

curl 'https://api.yapily.com/accounts/{account-id}/statements/{statement-id}/file' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{ }

HTTP Request

GET https://api.yapily.com/accounts/<account-id>/statements/<statement-id>/file

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
account-id	The id of the `Account`
statement-id	The id of the Statement

HTTP Response

The response returns a statement file for the account and statement-id.

Get Account Direct Debits

Feature: ACCOUNT_DIRECT_DEBIT

Get the list of direct debits for an account.

TODO

TODO

curl 'https://api.yapily.com/accounts/{account-id}/direct-debits' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
  "meta": {
    "tracingId": "7719f383-10d7-4dd7-bae2-a70f6adf7941",
    "count": 28,
    "pagination": {
      "totalCount": 2,
      "self": {
        "limit": 1000
      }
    }
  },
  "data": [
    {
      "id": "900000000000000000000010",
      "statusDetails": {
        "status": "ACTIVE"
      },
      "payeeDetails": {
        "name": "BT GROUP PLC"
      },
      "reference": "GB07414308",
      "previousPaymentAmountDetails": {
        "amount": 23.79,
        "currency": "GBP"
      },
      "previousPaymentDateTime": "2017-12-11T00:00:00Z",
      "accountId": "500000000000000000000001"
    },
    {
      "id": "900000000000000000000011",
      "statusDetails": {
        "status": "ACTIVE"
      },
      "payeeDetails": {
        "name": "TV LICENCE MBP"
      },
      "reference": "3320580761",
      "previousPaymentAmountDetails": {
        "amount": 12.37,
        "currency": "GBP"
      },
      "previousPaymentDateTime": "2017-12-08T00:00:00Z",
      "accountId": "500000000000000000000001"
    }
  ]
}

HTTP Request

GET https://api.yapily.com/accounts/<account-id>/direct-debits

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
account-id	The id of the `Account`

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	A list of Direct Debits

Get Account Scheduled Payments

Feature: ACCOUNT_SCHEDULED_PAYMENT

Get the list of scheduled payments for an account.

TODO

TODO

curl 'https://api.yapily.com/accounts/{account-id}/scheduled-payments' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
  "meta": {
    "tracingId": "98f87cdc-0620-4d1a-99b0-77724668d64f",
    "count": 2,
    "pagination": {
      "totalCount": 2,
      "self": {
        "limit": 1000
      }
    }
  },
  "data": [
    {
      "id": "110000000000000000000001",
      "payeeDetails": {
        "accountIdentifications": [
          {
            "type": "ACCOUNT_NUMBER",
            "identification": "MA10000119820101"
          },
          {
            "type": "SORT_CODE",
            "identification": "GB29MA"
          }
        ]
      },
      "amountDetails": {
        "amount": 10,
        "currency": "GBP"
      },
      "scheduledPaymentType": "ARRIVAL",
      "scheduledPaymentDateTime": "2020-01-26T05:00:00Z",
      "accountId": "500000000000000000000001"
    },
    {
      "id": "110000000000000000000002",
      "payeeDetails": {
        "accountIdentifications": [
          {
            "type": "ACCOUNT_NUMBER",
            "identification": "MA10000119820101"
          },
          {
            "type": "SORT_CODE",
            "identification": "GB29MA"
          }
        ]
      },
      "reference": "Salary",
      "amountDetails": {
        "amount": 10,
        "currency": "GBP"
      },
      "scheduledPaymentType": "EXECUTION",
      "scheduledPaymentDateTime": "2020-03-26T05:00:00Z",
      "accountId": "500000000000000000000001"
    }
  ]
}

HTTP Request

GET https://api.yapily.com/accounts/<account-id>/scheduled-payments

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
account-id	The id of the `Account`

HTTP Response

Parameter	Description
meta	An object containing the tracingId
data	A list of Scheduled Payments

Get Account Periodic Payments

Feature: ACCOUNT_PERIODIC_PAYMENTS

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

TODO

TODO

curl 'https://api.yapily.com/accounts/{account-id}/periodic-payments' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
  "meta": {
    "tracingId": "e7b01315-cbc5-4d0b-91e8-4f77cb1a3253",
    "count": 2,
    "pagination": {
      "totalCount": 2,
      "self": {
        "limit": 1000
      }
    }
  },
  "data": [
    {
      "id": "100000000000000000000010",
      "statusDetails": {
        "status": "UNKNOWN"
      },
      "payeeDetails": {
        "accountIdentifications": [
          {
            "type": "ACCOUNT_NUMBER",
            "identification": "20012001"
          },
          {
            "type": "SORT_CODE",
            "identification": "181818"
          }
        ]
      },
      "reference": "Glock Hire",
      "firstPaymentAmountDetails": {
        "amount": 199.95,
        "currency": "GBP"
      },
      "firstPaymentDateTime": "2012-01-10T00:00:00Z",
      "nextPaymentAmountDetails": {
        "amount": 199.95,
        "currency": "GBP"
      },
      "nextPaymentDateTime": "2018-01-10T00:00:00Z",
      "finalPaymentAmountDetails": {
        "amount": 10,
        "currency": "GBP"
      },
      "finalPaymentDateTime": "2020-01-10T00:00:00Z",
      "frequencyDetails": {
        "frequency": "MONTHLY",
        "intervalWeek": 1,
        "executionDay": 1
      },
      "accountId": "500000000000000000000001"
    },
    {
      "id": "100000000000000000000011",
      "statusDetails": {
        "status": "UNKNOWN"
      },
      "payeeDetails": {
        "accountIdentifications": [
          {
            "type": "ACCOUNT_NUMBER",
            "identification": "19871897"
          },
          {
            "type": "SORT_CODE",
            "identification": "202020"
          }
        ]
      },
      "reference": "Allowance",
      "firstPaymentAmountDetails": {
        "amount": 10,
        "currency": "GBP"
      },
      "firstPaymentDateTime": "2015-09-30T23:00:00Z",
      "nextPaymentAmountDetails": {
        "amount": 10,
        "currency": "GBP"
      },
      "nextPaymentDateTime": "2018-01-01T00:00:00Z",
      "frequencyDetails": {
        "frequency": "DAILY"
      },
      "accountId": "500000000000000000000001"
    }
  ]
}

HTTP Request

GET https://api.yapily.com/accounts/<account-id>/periodic-payments

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
account-id	The id of the `Account`

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	A list of Periodic Payments

Get Identity

Feature: IDENTITY

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

TODO

TODO

curl 'https://api.yapily.com/identity' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
  "meta": {
    "tracingId": "1990ea78-e319-4d60-bc11-568151b36aa4"
  },
  "data": {
    "id": "abc123",
    "firstName": "Bojack",
    "lastName": "Horseman",
    "gender": "MALE",
    "birthdate": "1970-01-01",
    "email": "bojack@horsingaround.com",
    "phone": "02071234567",
    "addresses": [
      {
        "addressLines": [],
        "city": "London",
        "postalCode": "A12 3BC",
        "country": "United Kingdom"
      }
    ]
  }
}

HTTP Request

GET https://api.yapily.com/identity

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	The Identity object

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.

PaymentRequest Model

As the PaymentRequest object is used to create multiple types of payments, the properties required will ultimately depend on what type of payment you wish to initiate on behalf of your users. When initiating a payment, this object must be an exact match in both the authorisation request and in the payment request e.g. for bulk payments, the following applies for each item in the PaymentRequest.payments array when executing Create Bulk Payment Authorisation Request and then also in the payments array when executing Create Bulk Payment Request.

Parameter	Description
amount	Mandatory. The Amount object that contains the amount and currency of the payment.
contextType	Optional. Used to categorise the payment being made. The possible values are BILL, GOODS, SERVICES, OTHER, PERSON_TO_PERSON.
paymentIdempotencyId	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. 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	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.
Payer reference	Optional. The payment reference or description. Limited to a maximum of 18 characters long.
type	Mandatory. The payment type: DOMESTIC_PAYMENT See European Payments to verify that your payment is eligible to be a DOMESTIC_PAYMENT.

Payment Model

Parameter	Description
amount	The amount of the payment.
amountDetails	The Amount object that contains the amount and currency of the payment.
chargeDetails	Specifies an array of ChargeDetails to show any charges associated with the processing of the payment transaction.
currency	Used in international payment to identify 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.
currencyOfTransfer	Used in international payments to express more details about the exchange rate
createdAt	The time at which the payment was created
exchangeRate	Used in international payments to express more details about the exchange rate
finalPaymentAmount	Used in periodic payments to indicate details of the Amount for the first payment.
finalPaymentDateTime	Used in periodic payments to indicate when the final payment occurs.
firstPaymentAmount	Used in periodic payments to indicate details of the Amount for the last payment.
firstPaymentDateTime	Used in periodic payments to indicate when the first payment occurs.
id	Used to uniquely identify the payment
institutionConsentId	The consent associated with the payment
nextPaymentAmount	Used in periodic payments to indicate details of the Amount for the next payment.
nextPaymentDateTime	Used in periodic payments to indicate when the next payment will occur.
numberOfPayments	Used in periodic payments to indicate how many payments will occur.
paymentIdempotencyId	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.
paymentLifecycleId	The payment lifecycle identifier
payeeDetails	The Payee object contains details of the beneficiary [person or business].
payer	The Payer object contains details of the benefactor [person or business].
previousPaymentAmount	Used in periodic payments to indicate details of the Amount for the previous payment.
previousPaymentDateTime	Used in periodic payments to indicate when the previous payment occurred.
priority	Used in international payments as an 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	Used in international payments to indicate the external purpose as a ISO20022 purpose code value.
readRefundAccount	Used to display refund account information in the payment response when set to true. See Reverse Payments for more details
reference	The payment reference or description. Limited to a maximum 18 characters long.
scheduledPaymentAmount	Used in scheduled payments to define details of the Amount to be credited.
scheduledPaymentDateTime	Used in scheduled payments to define when the payment should occur.
status	The status of the payment. Possible values are: PENDING The payment is awaiting some checks before the bank can execute it FAILED The payment failed technical validation on bank side DECLINED The payment was declined by the bank. This can be because the request failed some necessary checks from the bank side. COMPLETED The payment passed all validation checks by the bank and has been executed by the bank. At this point, the account balance on the account is also updated. COMPLETED_SETTLEMENT_IN_PROCESS The payment passed all validation checks by the bank and has been accepted for future execution EXPIRED Not currently being used for payment ACTIVE This is used exclusively for Accounts Direct Debit if the direct debit is active INACTIVE This is used exclusively for Accounts Direct Debit if the direct debit is in-active
statusDetails	Details of the payment

Payee Model

Parameter	Description
name	Required. The account holder name of the beneficiary
address	Conditional. The address of the beneficiary. Conditions: Required when the paymentType is an INTERNATIONAL payment. Some banks in the UK will fail unless address.country is provided in the case of any DOMESTIC payment.
accountIdentifications	Required. An array of AccountIdentification objects that identifies the bank account for the Payee The AccountIdentification object: type - Required. The type of account identifier. Possible values are: SORT_CODE ACCOUNT_NUMBER IBAN BBAN BIC PAN MASKED_PAN MSISDN BSB NCC ABA ABA_WIRE ABA_ACH EMAIL identification - Required. The value of the enumeration type
merchantId	Optional. A merchant ID is a unique code provided by the payment processor to the merchant.
merchantCategoryCode	Optional. The category code of the merchant in case the Payee is a business.

Payer Model

Parameter	Description
name	Optional. The account holder name of the benefactor.
address	Optional. The address of the benefactor.
accountIdentifications	Required. An array of AccountIdentification objects that identifies the bank account of the benefactor. The AccountIdentification object: type - Required. The type of account identifier. Possible values are: SORT_CODE ACCOUNT_NUMBER IBAN BBAN BIC PAN MASKED_PAN MSISDN BSB NCC ABA ABA_WIRE ABA_ACH EMAIL identification - Required. The value of the enumeration type

Get Payment

TODO

TODO

curl 'https://api.yapily.com/payments/{payment-id}/details' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"

TODO

{
    "meta": {
        "tracingId": "dd657a8a33fd6b04e354b9947c8699b1"
    },
    "data": {
        "payments": [
            {
                "id": "pv3-b7020053-238c-45b5-86fb-34a3de5c23ad",
                "institutionConsentId": "sdp-1-a979847c-adc8-4025-a3b6-8a990845f327",
                "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
                "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d",
                "status": "COMPLETED",
                "statusDetails": {
                    "status": "COMPLETED",
                    "statusUpdateDate": "2020-08-07T13:24:50.214Z"
                },
                "payeeDetails": {
                    "name": "John Doe",
                    "accountIdentifications": [
                        {
                            "type": "ACCOUNT_NUMBER",
                            "identification": "00000825"
                        },
                        {
                            "type": "SORT_CODE",
                            "identification": "204514"
                        }
                    ]
                },
                "reference": "REFERENCE",
                "amount": 4.00,
                "currency": "GBP",
                "amountDetails": {
                    "amount": 4.00,
                    "currency": "GBP"
                },
                "createdAt": "2020-08-07T13:24:50.214Z"
            }
        ]
    }
}

Feature: EXISTING PAYMENT DETAILS

Return the list of payments.

HTTP Request

GET https://api.yapily.com/payments/<payment-id>/details

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

URL Parameters

Parameter	Description
payment-id	The id of the Payment to retrieve

HTTP Response

Parameter	Description
meta	An object containing a tracingId for the request
data	A list of Payments

Create Payment

Features:

CREATE_DOMESTIC_SCHEDULED_PAYMENT
CREATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
CREATE_DOMESTIC_SINGLE_PAYMENT
CREATE_DOMESTIC_PERIODIC_PAYMENT
CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT
CREATE_INTERNATIONAL_SINGLE_PAYMENT
CREATE_INTERNATIONAL_SCHEDULED_PAYMENT
CREATE_INTERNATIONAL_PERIODIC_PAYMENT
CREATE_INTERNATIONAL_VARIABLE_RECURRING_PAYMENT

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 Request with their bank. Make sure to use the Create Bulk Payment Request endpoint for executing bulk payments. The response of this endpoint is Payment Response.

TODO

TODO

curl -X POST 'https://api.yapily.com/payments' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"
-d '{
    "type": "DOMESTIC_PAYMENT",
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "reference": "REFERENCE",
    "contextType": "OTHER",
    "amount": {
    "amount": "4.00",
    "currency": "GBP"
}'

TODO

{
  "meta": {
    "tracingId": "a7dc5d27-329f-4701-a019-c12261565d2d"
  },
  "data": {
    "id": "pv3-047446ea-d468-402c-b0bb-4e73976f1aef",
    "paymentIdempotencyId": "1d54cf71bfe44b1b8e67247aed455d96",
    "institutionConsentId": "sdp-2-781c219a-ed53-4570-b70f-df1d2307322b",
    "paymentLifecycleId": "69d554dea74276e8b1b44efb17fc45d1",
    "status": "COMPLETED",
    "statusDetails": {
      "status": "COMPLETED",
      "statusUpdateDate": "2019-09-26T15:46:34.815Z"
    },
    "payeeDetails": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "ACCOUNT_NUMBER",
          "identification": "00000825"
        },
        {
          "type": "SORT_CODE",
          "identification": "204514"
        }
      ]
    },
    "reference": "REFERENCE",
    "amountDetails": {
      "amount": 4,
      "currency": "GBP"
    },
    "createdAt": "2019-09-26T15:46:34.815Z",
    "scheduledPaymentDateTime": "2019-12-26T14:42:53Z"
  }
}

HTTP Request

POST https://api.yapily.com/payments

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

Body Parameters

The JSON body should be the PaymentRequest object sent in the authorisation request.

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	The Payment object

Create Bulk Payment

Feature: CREATE_BULK_PAYMENT

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.

TODO

TODO

curl -X POST 'https://api.yapily.com/bulk-payments' \ 
-u API_KEY:API_SECRET \ 
-H "Consent: {consent-token}"
-d '{
    "executionDateTime": "DATE_OF_EXECUTION",
    "payments": [
        "paymentIdempotencyId": "UNIQUE_PAYMENT_IDENTIFIER",
        "amount": {
            "value": "0.00",
            "currency": "3_LETTER_CURRENCY_CODE"
        },
        "reference": "REFERENCE",
        "type": "PAYMENT_TYPE",
        "payee": {
            "name": "PAYEE_NAME",
            "accountIdentifications": [
                {
                    "type": "TYPE_OF_IDENTIFICATION",
                    "identification": "VALUE_OF_IDENTIFICATION"
                }
            ]
        }
    ]
}'

TODO

{
  "meta": {
    "tracingId": "d778eb267a16985fc4d7b04ccbd00d46"
  },
  "data": {
    "id": "BARCLAYS-P-10000000337598",
    "institutionConsentId": "BARCLAYS-P-10000000337598",
    "status": "COMPLETED",
    "statusDetails": {
      "status": "COMPLETED",
      "statusUpdateDate": "2020-05-01T11:37:16+01:00"
    },
    "amount": 13,
    "amountDetails": {
      "amount": 13
    },
    "createdAt": "2020-05-01T11:32:51+01:00"
  }
}

HTTP Request

POST https://api.yapily.com/bulk-payments

HTTP Headers

Parameter	Description
Authorization	Basic B64(API_KEY + ":" + API_SECRET)
Consent	The Consent-Token obtained from the authorisation.

Body Parameters

Parameter	Description
executionDateTime	Optional. If supplied, the bulk payment will be executed at this time in the future, otherwise, it will execute immediately.
payments	Mandatory. An array of PaymentRequest objects to include in the bulk payment. Each bank will have its own restrictions and Yapily will inform you of them programatically should there be any issues sending your request to the bank.

HTTP Response

Parameter	Description
meta	An object containing the tracingId for the request
data	An object with the result of the bulk payment request.

Error responses

{
    "error": {
        "code": 404,
        "tracingId": "cd5066123f42c9df78b5897fcc52675d",
        "status": "NOT_FOUND",
        "source": "YAPILY",
        "message": "We can help you on https://support.yapily.com/"
    },
    "monitoring": []
}

Code	Description
200	Successful request.
201	Successful request and resource created.
400	Bad request. Where possible Yapily will return details of why the request failed.
401	Unauthorised request to the Yapily API.
403	Forbidden request where a valid consent token is required.
404	Resource not found.
405	HTTP method not allowed.
406	Your application did not accept JSON.
409	Attempted action conflicts with current application state. Actions to resolve will be returned in the body of the response where possible.
424	Failed Dependency. Unable to complete request to the institution.
500	Internal server error, due to an undetermined issue.
501	Not Implemented. The requested feature is unavailable for the specified institution.

Introduction

Authentication

Application

Application Model

Get Application

HTTP Request

HTTP Headers

HTTP Response

User

User Model

Get Users

HTTP Request

HTTP Headers

HTTP Response

Get User

HTTP Request

HTTP Headers

URL Parameters

HTTP Response

Create User

HTTP Request

HTTP Headers

Body Parameters

HTTP Response

Delete User

HTTP Request

HTTP Headers

URL Parameters

HTTP Response

Institutions

Institution Model

Get Institutions

HTTP Request

HTTP Headers

HTTP Response

Get Institution

HTTP Request

HTTP Headers

URL Parameters

HTTP Response

Get Features

HTTP Request

HTTP Headers

HTTP Response

Consents

Consent Model

Get Consents

HTTP Request

HTTP Headers

Querystring Parameters

HTTP Response

Get Consent

HTTP Request

HTTP Headers

URL Parameters

HTTP Response

Delete Consent

HTTP Request

HTTP Headers

URL Parameters

Querystring Parameters

HTTP Response

Exchange One Time Token

HTTP Request

HTTP Headers

Body Parameters

HTTP Response

[Forwarding] Send Access Token

HTTP Request

HTTP Headers

URL Parameters

Body Parameters

HTTP Response

[Forwarding] Send OAuth2 Code

HTTP Request

HTTP Headers

Body Parameters

HTTP Response

Obtaining a Consent

Authorisation Model