NAV
shell java python javascript

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);

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Obtaining a Consent

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

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

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

Example Response:

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

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

Example Response:

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

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

{ }

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

 { }

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

Example Response:

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

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

Example Response:

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

Example Response:

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

Example Response:

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