NAV
shell

Yapily API

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

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

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

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

Authentication

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

An APPLICATION_KEY and APPLICATION_SECRET pair provides connectivity to each Institution configured in a Yapily Application, so it is important to keep these credentials secure. Do not share your APPLICATION_SECRET in publicly accessible areas such as GitHub, client-side code, etc.

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

All requests should be made via HTTPS.

Application

The Application is the base entity that is used to interact with the API and contains a collection of Institution objects. You can have multiple Applications associated with your account e.g. a production application with live access to each Institution and a development application with access to sandboxes.

Get Application Self

Example Request

curl -X GET https://api.yapily.com/me \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

GET /me

Get the information about the institutions configured in your application

Example Responses

Example Response

{
  "uuid": "64949de6-6510-4d70-9500-d4aa094c506c",
  "name": "APPLICATION NAME",
  "active": true,
  "authCallbacks": [
    "https://display-parameters.com/"
  ],
  "institutions": [
    {
      "id": "modelo-sandbox",
      "name": "Modelo Sandbox",
      "fullName": "Modelo Sandbox",
      "countries": [
        {
          "displayName": "United Kingdom",
          "countryCode2": "GB"
        }
      ],
      "environmentType": "SANDBOX",
      "credentialsType": "OPEN_BANKING_UK_AUTO",
      "media": [
        {
          "source": "https://images.yapily.com/image/ce2bfdbf-1ae2-4919-ab7b-e8b3d5e93b36?size=0",
          "type": "icon"
        },
        {
          "source": "https://images.yapily.com/image/ca502f24-d6df-4785-b4b8-1034b100af77?size=0",
          "type": "logo"
        }
      ],
      "features": [
        "INITIATE_SINGLE_PAYMENT_SORTCODE",
        "CREATE_DOMESTIC_PERIODIC_PAYMENT",
        "ACCOUNT_REQUEST_DETAILS",
        "ACCOUNT_STATEMENT_FILE",
        "CREATE_SINGLE_PAYMENT_SORTCODE",
        "ACCOUNTS",
        "CREATE_DOMESTIC_SCHEDULED_PAYMENT",
        "ACCOUNT_PERIODIC_PAYMENTS",
        "CREATE_DOMESTIC_SINGLE_PAYMENT",
        "INITIATE_DOMESTIC_PERIODIC_PAYMENT",
        "EXISTING_PAYMENTS_DETAILS",
        "INITIATE_BULK_PAYMENT",
        "EXISTING_PAYMENT_INITIATION_DETAILS",
        "ACCOUNT_DIRECT_DEBITS",
        "ACCOUNT_TRANSACTIONS",
        "INITIATE_DOMESTIC_SINGLE_PAYMENT",
        "PERIODIC_PAYMENT_FREQUENCY_EXTENDED",
        "CREATE_INTERNATIONAL_SINGLE_PAYMENT",
        "ACCOUNT_SCHEDULED_PAYMENTS",
        "ACCOUNT",
        "ACCOUNT_STATEMENTS",
        "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
        "CREATE_BULK_PAYMENT",
        "ACCOUNT_BALANCES",
        "INITIATE_INTERNATIONAL_SINGLE_PAYMENT",
        "INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
        "ACCOUNT_BENEFICIARIES",
        "IDENTITY",
        "ACCOUNT_STATEMENT",
        "INITIATE_ACCOUNT_REQUEST"
      ]
    }
  ],
  "media": [],
  "created": "2020-11-09T10:05:29.897+0000",
  "updated": "2021-04-14T12:51:07.419+0000"
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Users

The Users endpoints are used to manage each user (otherwise known as the PSU) in Yapily. Each user belongs to an Application and as a consequence, so do each Consent created for a particular User.

Get Users

Example Request

curl -X GET https://api.yapily.com/users \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

GET /users

Get all the users configured in your application

Query Parameters

Name
Description
filter[applicationUserId]
array[string]
Optional. Filter records based on the list of applicationUserId users provided.

Example Responses

Example Response

[
  {
    "uuid": "3b908179-6faa-42e1-8129-8fd0ff1fc68f",
    "applicationUuid": "3020bf54-e254-40ba-ba7b-fc959774486a",
    "applicationUserId": "bojack@9tees.com",
    "institutionConsents": [
      {
        "institutionId": "modelo-sandbox"
      }
    ]
  },
  {
    "uuid": "be7dd6fa-1236-41b6-a7a1-5d7863ab9553",
    "applicationUuid": "3020bf54-e254-40ba-ba7b-fc959774486a",
    "referenceId": "hollyhock@9tees.com",
    "institutionConsents": [
      {
        "institutionId": "mock-sandbox"
      }
    ]
  },
  {
    "uuid": "deb9aac1-b0bc-4f40-9c0b-6a675cf6646f",
    "applicationUuid": "3020bf54-e254-40ba-ba7b-fc959774486a",
    "referenceId": "beatrice@9tees.com",
    "institutionConsents": [
      {
        "institutionId": "yapily-mock"
      }
    ]
  }
]

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
200
OK
Inline
default
Default

Response Schema

Status Code 200

Status
Schema
anonymous
[ApplicationUser]
No description
» uuid
string(uuid)
No description
» applicationUuid
string(uuid)
No description
» applicationUserId
string
No description
» referenceId
string
No description
» institutionConsents
[InstitutionConsent]
No description
»» institutionId
string
No description

Create User

Example Request

curl -X POST https://api.yapily.com/users \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /users

Create a new user in your application

Example Request Bodies

Create User Example Request

{
  "applicationUserId": "john.doe@company.com"
}

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Example Response

{
  "uuid": "1ec8e814-085e-46ad-a303-3fe11808f67e",
  "applicationUuid": "50935110-c7df-4003-a06a-1cc5fd4643c9",
  "applicationUserId": "john.doe@company.com",
  "institutionConsents": []
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Delete User

Example Request

curl -X DELETE https://api.yapily.com/users/{userUuid} \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

DELETE /users/{userUuid}

Delete a user from your application along with any sub-resources (including consent resources on institution APIs if they exist)

Path Parameters

Name
Description
userUuid
string(uuid)
Mandatory. The Yapily generated UUID for the user.

Example Responses

Example Response

{
  "meta": {
    "tracingId": "e6625041a9fb46e2a450b3f9f1528cb8"
  },
  "data": {
    "id": "b8ebe390-f6fb-45b5-bf20-1b4436644390",
    "deleteStatus": "SUCCESS",
    "creationDate": "2021-06-07T16:44:52.221Z",
    "userConsents": [
      {
        "institutionId": "modelo-sandbox"
      }
    ]
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get User

Example Request

curl -X GET https://api.yapily.com/users/{userUuid} \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

GET /users/{userUuid}

Get a specific user using the user UUID

Path Parameters

Name
Description
userUuid
string(uuid)
Mandatory. The Yapily generated UUID for the user.

Example Responses

Example Response

{
  "uuid": "3b908179-6faa-42e1-8129-8fd0ff1fc68f",
  "applicationUuid": "3020bf54-e254-40ba-ba7b-fc959774486a",
  "applicationUserId": "bojack@9tees.com",
  "institutionConsents": [
    {
      "institutionId": "modelo-sandbox"
    }
  ]
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

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� financial data available to third party providers via their API endpoints).

Any one of the following would be represented as Institution:

Get Features

Example Request

curl -X GET https://api.yapily.com/features \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

GET /features

Used to retrieve all features available from Yapily. Each Institution supports a one, many or all of these features and can be seen in the features field of the Institution object.

Note: Every Institution does not necessarily support every feature. To see which features are available for a particular Institution, use either the Get Institutions or Get Institution endpoint and check the features array within the Institution payload.

Example Responses

Example Response

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

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Institutions

Example Request

curl -X GET https://api.yapily.com/institutions \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

GET /institutions

Used to retrieve all Institutions within an application

Example Responses

Example Response

{
  "meta": {
    "tracingId": "1304b771e4e34f67b39977bde6b1a8e2",
    "count": 1
  },
  "data": [
    {
      "id": "modelo-sandbox",
      "name": "Modelo Sandbox",
      "fullName": "Modelo Sandbox",
      "countries": [
        {
          "displayName": "United Kingdom",
          "countryCode2": "GB"
        }
      ],
      "environmentType": "SANDBOX",
      "credentialsType": "OPEN_BANKING_UK_AUTO",
      "media": [
        {
          "source": "https://images.yapily.com/image/ce2bfdbf-1ae2-4919-ab7b-e8b3d5e93b36?size=0",
          "type": "icon"
        },
        {
          "source": "https://images.yapily.com/image/ca502f24-d6df-4785-b4b8-1034b100af77?size=0",
          "type": "logo"
        }
      ],
      "features": [
        "ACCOUNT_BALANCES",
        "INITIATE_BULK_PAYMENT",
        "ACCOUNT_BENEFICIARIES",
        "ACCOUNT_SCHEDULED_PAYMENTS",
        "EXISTING_PAYMENTS_DETAILS",
        "ACCOUNT_TRANSACTIONS",
        "ACCOUNT_STATEMENTS",
        "INITIATE_DOMESTIC_PERIODIC_PAYMENT",
        "INITIATE_ACCOUNT_REQUEST",
        "IDENTITY",
        "ACCOUNT_PERIODIC_PAYMENTS",
        "ACCOUNT_REQUEST_DETAILS",
        "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
        "INITIATE_SINGLE_PAYMENT_SORTCODE",
        "INITIATE_DOMESTIC_SINGLE_PAYMENT",
        "INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
        "ACCOUNT_STATEMENT",
        "CREATE_DOMESTIC_SINGLE_PAYMENT",
        "ACCOUNT_STATEMENT_FILE",
        "CREATE_DOMESTIC_PERIODIC_PAYMENT",
        "CREATE_DOMESTIC_SCHEDULED_PAYMENT",
        "EXISTING_PAYMENT_INITIATION_DETAILS",
        "INITIATE_INTERNATIONAL_SINGLE_PAYMENT",
        "CREATE_SINGLE_PAYMENT_SORTCODE",
        "CREATE_BULK_PAYMENT",
        "CREATE_INTERNATIONAL_SINGLE_PAYMENT",
        "ACCOUNT",
        "PERIODIC_PAYMENT_FREQUENCY_EXTENDED",
        "ACCOUNT_DIRECT_DEBITS",
        "ACCOUNTS"
      ]
    }
  ]
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Institution

Example Request

curl -X GET https://api.yapily.com/institutions/{institutionId} \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

GET /institutions/{institutionId}

Used to retrieves details of a specific Institution within an application

Path Parameters

Name
Description
institutionId
string
Mandatory. The Yapily institution Id for the Institution.

Example Responses

Example Response

{
  "id": "modelo-sandbox",
  "name": "Modelo Sandbox",
  "fullName": "Modelo Sandbox",
  "countries": [
    {
      "displayName": "United Kingdom",
      "countryCode2": "GB"
    }
  ],
  "environmentType": "SANDBOX",
  "credentialsType": "OPEN_BANKING_UK_AUTO",
  "media": [
    {
      "source": "https://images.yapily.com/image/ce2bfdbf-1ae2-4919-ab7b-e8b3d5e93b36?size=0",
      "type": "icon"
    },
    {
      "source": "https://images.yapily.com/image/ca502f24-d6df-4785-b4b8-1034b100af77?size=0",
      "type": "logo"
    }
  ],
  "features": [
    "ACCOUNT_BALANCES",
    "INITIATE_BULK_PAYMENT",
    "ACCOUNT_BENEFICIARIES",
    "ACCOUNT_SCHEDULED_PAYMENTS",
    "EXISTING_PAYMENTS_DETAILS",
    "ACCOUNT_TRANSACTIONS",
    "ACCOUNT_STATEMENTS",
    "INITIATE_DOMESTIC_PERIODIC_PAYMENT",
    "INITIATE_ACCOUNT_REQUEST",
    "IDENTITY",
    "ACCOUNT_PERIODIC_PAYMENTS",
    "ACCOUNT_REQUEST_DETAILS",
    "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
    "INITIATE_SINGLE_PAYMENT_SORTCODE",
    "INITIATE_DOMESTIC_SINGLE_PAYMENT",
    "INITIATE_DOMESTIC_SCHEDULED_PAYMENT",
    "ACCOUNT_STATEMENT",
    "CREATE_DOMESTIC_SINGLE_PAYMENT",
    "ACCOUNT_STATEMENT_FILE",
    "CREATE_DOMESTIC_PERIODIC_PAYMENT",
    "CREATE_DOMESTIC_SCHEDULED_PAYMENT",
    "EXISTING_PAYMENT_INITIATION_DETAILS",
    "INITIATE_INTERNATIONAL_SINGLE_PAYMENT",
    "CREATE_SINGLE_PAYMENT_SORTCODE",
    "CREATE_BULK_PAYMENT",
    "CREATE_INTERNATIONAL_SINGLE_PAYMENT",
    "ACCOUNT",
    "PERIODIC_PAYMENT_FREQUENCY_EXTENDED",
    "ACCOUNT_DIRECT_DEBITS",
    "ACCOUNTS"
  ]
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Consents

The Consents endpoints are used to manage each Consent created by Yapily in response to an authorisation created for a user.

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

Exchange OAuth2 Code

Example Request

curl -X POST https://api.yapily.com/consent-auth-code \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /consent-auth-code

Used to obtain a Yapily Consent object containing the consentToken once the user has authenticated and you have an OAuth2 authorisation code auth-code and state auth-state.

Example Request Bodies

{
  "authCode": "6b965fbb-ff09-4afa-b897-90c34797cb8f&id_token=eyJhbGciOiJQUzI1NiIsImtpZCI6InprYm9LRmpRUndCZDlVRW5QQzV3bHY1N2lnNCJ9.eyJzdWIiOiJzZHAtNi0xZjA1MjBiNC1mZmNkLTQ4OTgtYWVkMC0wYjU0Y2I2ZDkwM2QiLCJvcGVuYmFua2luZ19pbnRlbnRfaWQiOiJzZHAtNi0xZjA1MjBiNC1mZmNkLTQ4OTgtYWVkMC0wYjU0Y2I2ZDkwM2QiLCJwc3VfaWRlbnRpZmllcnMiOnsidXNlcklkIjoiNzAwMDAxMDAwMDAwMDAwMDAwMDAwMDAyIiwiY29tcGFueUlkIjoiMTIzNDUifSwiaXNzIjoiaHR0cHM6Ly9vYjE5LWF1dGgxLXVpLm8zYmFuay5jby51ayIsImF1ZCI6IjA0ZmJjMGQ5LTlmMDgtNGIyOC1iNjY2LWFkNmEwYmMzM2NjZSIsImlhdCI6MTYxMTIyMjgzNywiZXhwIjoxNjExMjI2NDM3LCJub25jZSI6IjEyNzBjYjJmZmM0ODQyYjc4OTUzYWZhMjIyOGUwYTg5IiwiYXV0aF90aW1lIjoxNjExMjIyODM3LCJhenAiOiIwNGZiYzBkOS05ZjA4LTRiMjgtYjY2Ni1hZDZhMGJjMzNjY2UiLCJyZWZyZXNoX3Rva2VuX2V4cGlyZXNfYXQiOjE2MTE2MTE2MzcsImNfaGFzaCI6Inc5NG9pTkg1RWlBdVNKdWJfUHAxSlEiLCJzX2hhc2giOiJhRmxHY3dJY1EtdTVHYnBmcXRCR293IiwiYWNyIjoidXJuOm9wZW5iYW5raW5nOnBzZDI6c2NhIn0.nfaJ-llxVVa4HS7oii2oGgAV6k3MPwtQLFaOAZ2RY8VcxoWBkXKnrPkwf2jRHvE4aJnnfD3BcDAfJNeDBFEt5YQcujl0NxQm3XpOVkhjUVvINjmi9zbDMz2WFDpz8hSZZxvzxQ29h5nFSFcvXxE-0d2i10nX87OVlophc5GabHt3mnP3UbFIy-k0i9a9JGodheF9Qu3J-q2bgNJpLww8jj-gNH1LekG3qu8fxaB1c5-MuERfSWvrgwrJKKUe_yIxXVpL4zMMXw3B6JGIeUgPHKtAZxiAA9YA6dTlA1yPQwOfh4B-qvAZDmuGBnoB3iUXKLIUqBUA8j3rzLkQj51ORg",
  "authState": "1270cb2ffc4842b78953afa2228e0a87"
}

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Example Response

{
  "id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
  "userUuid": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
  "applicationUserId": "john.doe@company.com",
  "institutionId": "modelo-sandbox",
  "status": "AUTHORIZED",
  "createdAt": "2021-06-08T10:59:35.138Z",
  "featureScope": [
    "ACCOUNT_BENEFICIARIES",
    "ACCOUNT_STATEMENT_FILE",
    "ACCOUNTS",
    "ACCOUNT_PERIODIC_PAYMENTS",
    "ACCOUNT_TRANSACTIONS",
    "ACCOUNT",
    "ACCOUNT_STATEMENTS",
    "ACCOUNT_SCHEDULED_PAYMENTS",
    "IDENTITY",
    "ACCOUNT_DIRECT_DEBITS",
    "ACCOUNT_STATEMENT",
    "ACCOUNT_BALANCES",
    "ACCOUNT_TRANSACTIONS_WITH_MERCHANT"
  ],
  "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjU2YTQyMjQ0LTQxNGEtNGI1Mi04YzRmLTRhZDJhNTBlODJmZSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJtb2ZlLTIiLCJVU0VSIjoiY2E0MTJmZGYtNWEzMC00M2EyLTg4YjctNTk2NGEyNGE4ZTU1In0.gorwpnUjSr5dzQJLR32M2geWOj7yK9xMsZmq27ssY9xP_xGmWfUL_aqVHYyQ4r5KWw6Xb6RjvO839st8chJLtg",
  "state": "a09f8ff9c1284444aa635267e05f76e1",
  "authorizedAt": "2021-06-08T10:59:53.288Z",
  "institutionConsentId": "aac-605d48f2-2a0e-4594-81a9-996524fa3b2a"
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Exchange One Time Token

Example Request

curl -X POST https://api.yapily.com/consent-one-time-token \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /consent-one-time-token

Exchange a One-time-token for the consent token

Example Request Bodies

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

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Example Response

{
  "id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
  "userUuid": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
  "applicationUserId": "john.doe@company.com",
  "institutionId": "modelo-sandbox",
  "status": "AUTHORIZED",
  "createdAt": "2021-06-08T10:59:35.138Z",
  "featureScope": [
    "ACCOUNT_BENEFICIARIES",
    "ACCOUNT_STATEMENT_FILE",
    "ACCOUNTS",
    "ACCOUNT_PERIODIC_PAYMENTS",
    "ACCOUNT_TRANSACTIONS",
    "ACCOUNT",
    "ACCOUNT_STATEMENTS",
    "ACCOUNT_SCHEDULED_PAYMENTS",
    "IDENTITY",
    "ACCOUNT_DIRECT_DEBITS",
    "ACCOUNT_STATEMENT",
    "ACCOUNT_BALANCES",
    "ACCOUNT_TRANSACTIONS_WITH_MERCHANT"
  ],
  "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjU2YTQyMjQ0LTQxNGEtNGI1Mi04YzRmLTRhZDJhNTBlODJmZSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJtb2ZlLTIiLCJVU0VSIjoiY2E0MTJmZGYtNWEzMC00M2EyLTg4YjctNTk2NGEyNGE4ZTU1In0.gorwpnUjSr5dzQJLR32M2geWOj7yK9xMsZmq27ssY9xP_xGmWfUL_aqVHYyQ4r5KWw6Xb6RjvO839st8chJLtg",
  "state": "a09f8ff9c1284444aa635267e05f76e1",
  "authorizedAt": "2021-06-08T10:59:53.288Z",
  "institutionConsentId": "aac-605d48f2-2a0e-4594-81a9-996524fa3b2a"
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Consents

Example Request

curl -X GET https://api.yapily.com/consents \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

GET /consents

Used to retrieve all the consents created for each user within an application

Query Parameters

Name
Description
filter[applicationUserId]
array[string]
Optional. Filter records based on the list of applicationUserId users provided.
filter[userUuid]
array[string]
Optional. Filter records based on the list of userUuid users provided.
filter[institution]
array[string]
Optional. Filter records based on the list of Institution provided.
filter[status]
array[string]
Optional. Filter records based on the list of Consent statuses.
from
string
Optional. Returned transactions will be on or after this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
before
string
Optional. Returned transactions will be on or before this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
limit
integer(int32)
Optional. The maximum number of transaction records to be returned. Must be between 0 and 1000.
offset
integer(int32)
Optional. The number of transaction records to be skipped. Used primarily with paginated results.

Example Responses

Example Response

{
  "meta": {
    "tracingId": "d7b537b108934105a522dc7b4522380b",
    "count": 1,
    "pagination": {
      "totalCount": 1,
      "self": {
        "sort": "-date",
        "offset": 0
      }
    }
  },
  "data": [
    {
      "id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
      "userUuid": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
      "applicationUserId": "john.doe@company.com",
      "institutionId": "modelo-sandbox",
      "status": "AUTHORIZED",
      "createdAt": "2021-06-08T10:59:35.138Z",
      "featureScope": [
        "ACCOUNT_BENEFICIARIES",
        "ACCOUNT_STATEMENT_FILE",
        "ACCOUNTS",
        "ACCOUNT_PERIODIC_PAYMENTS",
        "ACCOUNT_TRANSACTIONS",
        "ACCOUNT",
        "ACCOUNT_STATEMENTS",
        "ACCOUNT_SCHEDULED_PAYMENTS",
        "IDENTITY",
        "ACCOUNT_DIRECT_DEBITS",
        "ACCOUNT_STATEMENT",
        "ACCOUNT_BALANCES",
        "ACCOUNT_TRANSACTIONS_WITH_MERCHANT"
      ],
      "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjU2YTQyMjQ0LTQxNGEtNGI1Mi04YzRmLTRhZDJhNTBlODJmZSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJtb2ZlLTIiLCJVU0VSIjoiY2E0MTJmZGYtNWEzMC00M2EyLTg4YjctNTk2NGEyNGE4ZTU1In0.gorwpnUjSr5dzQJLR32M2geWOj7yK9xMsZmq27ssY9xP_xGmWfUL_aqVHYyQ4r5KWw6Xb6RjvO839st8chJLtg",
      "state": "a09f8ff9c1284444aa635267e05f76e1",
      "authorizedAt": "2021-06-08T10:59:53.288Z",
      "institutionConsentId": "aac-605d48f2-2a0e-4594-81a9-996524fa3b2a"
    }
  ]
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Example Request

curl -X DELETE https://api.yapily.com/consents/{consentId} \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

DELETE /consents/{consentId}

Delete a consent using the consent Id

Name
Description
consentId
string(uuid)
Mandatory. The consent Id of the Consent to update.
Name
Description
forceDelete
boolean
Optional. Whether to force the deletion.

Example Responses

Example Response

{
  "meta": {
    "tracingId": "9aacaccc6dbf4a86960c9541969087a0"
  },
  "data": {
    "id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
    "deleteStatus": "SUCCESS",
    "institutionId": "modelo-sandbox",
    "institutionConsentId": "aac-605d48f2-2a0e-4594-81a9-996524fa3b2a",
    "creationDate": "2021-06-08T10:59:35.138Z"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}
Status
Schema
default
Default

Example Request

curl -X GET https://api.yapily.com/consents/{consentId} \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

GET /consents/{consentId}

Get consent using the consent Id

Name
Description
consentId
string(uuid)
Mandatory. The consent Id of the Consent to update.

Example Responses

Example Response

{
  "meta": {
    "tracingId": "679e7bb6cd45416a9a9a8d004c5315da"
  },
  "data": {
    "id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
    "userUuid": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "modelo-sandbox",
    "status": "AUTHORIZED",
    "createdAt": "2021-06-08T10:59:35.138Z",
    "featureScope": [
      "ACCOUNT_BENEFICIARIES",
      "ACCOUNT_STATEMENT_FILE",
      "ACCOUNTS",
      "ACCOUNT_PERIODIC_PAYMENTS",
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNT",
      "ACCOUNT_STATEMENTS",
      "ACCOUNT_SCHEDULED_PAYMENTS",
      "IDENTITY",
      "ACCOUNT_DIRECT_DEBITS",
      "ACCOUNT_STATEMENT",
      "ACCOUNT_BALANCES",
      "ACCOUNT_TRANSACTIONS_WITH_MERCHANT"
    ],
    "consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjU2YTQyMjQ0LTQxNGEtNGI1Mi04YzRmLTRhZDJhNTBlODJmZSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJtb2ZlLTIiLCJVU0VSIjoiY2E0MTJmZGYtNWEzMC00M2EyLTg4YjctNTk2NGEyNGE4ZTU1In0.gorwpnUjSr5dzQJLR32M2geWOj7yK9xMsZmq27ssY9xP_xGmWfUL_aqVHYyQ4r5KWw6Xb6RjvO839st8chJLtg",
    "state": "a09f8ff9c1284444aa635267e05f76e1",
    "authorizedAt": "2021-06-08T10:59:53.288Z",
    "institutionConsentId": "aac-605d48f2-2a0e-4594-81a9-996524fa3b2a"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}
Status
Schema
default
Default

Authorisations

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

Example Request

curl -X PATCH https://api.yapily.com/account-auth-requests \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

PATCH /account-auth-requests

Used to prompt the account holder for continued access to their financial data. This endpoint should be used when a Consent that was previously AUTHORIZED can no longer be used to retrieve data.

See Re-Authorisation for more information.

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.
Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

OBIE Example Response

{
  "meta": {
    "tracingId": "8719f9c97272463d9c2d1ee6108c8e24"
  },
  "data": {
    "id": "2812b61c-9d0b-4730-8c94-22c18918e66a",
    "userUuid": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "modelo-sandbox",
    "status": "AWAITING_RE_AUTHORIZATION",
    "createdAt": "2021-06-09T08:22:50.135Z",
    "featureScope": [
      "ACCOUNT_STATEMENT_FILE",
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNT_STATEMENTS",
      "ACCOUNTS",
      "ACCOUNT"
    ],
    "state": "0623e536c5044b4aa3f6c66e7537bee0",
    "authorizedAt": "2021-06-09T08:23:03.944Z",
    "institutionConsentId": "aac-f7847e99-7c66-4bb8-8641-61a24057f2e8",
    "authorisationUrl": "https://ob19-auth1-ui.o3bank.co.uk/auth?client_id=e7f6b95b-5f35-419b-b301-8b08bcd946de&response_type=code+id_token&state=0623e536c5044b4aa3f6c66e7537bee0&nonce=0623e536c5044b4aa3f6c66e7537bee0&scope=openid+accounts&redirect_uri=https%3A%2F%2Fauth.yapily.com%2F&request=eyJraWQiOiJnRTRvU3VaZDl4TVpUNXZDdTNWYy1mdktNak0iLCJhbGciOiJQUzI1NiJ9.eyJhdWQiOiJodHRwczovL29iMTktYXV0aDEtdWkubzNiYW5rLmNvLnVrIiwic2NvcGUiOiJvcGVuaWQgYWNjb3VudHMiLCJpc3MiOiJlN2Y2Yjk1Yi01ZjM1LTQxOWItYjMwMS04YjA4YmNkOTQ2ZGUiLCJjbGllbnRfaWQiOiJlN2Y2Yjk1Yi01ZjM1LTQxOWItYjMwMS04YjA4YmNkOTQ2ZGUiLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vYXV0aC55YXBpbHkuY29tLyIsInN0YXRlIjoiMDYyM2U1MzZjNTA0NGI0YWEzZjZjNjZlNzUzN2JlZTAiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsiYWNyIjp7InZhbHVlIjoidXJuOm9wZW5iYW5raW5nOnBzZDI6c2NhIiwiZXNzZW50aWFsIjp0cnVlfSwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiYWFjLWY3ODQ3ZTk5LTdjNjYtNGJiOC04NjQxLTYxYTI0MDU3ZjJlOCIsImVzc2VudGlhbCI6dHJ1ZX19LCJ1c2VyaW5mbyI6eyJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJhYWMtZjc4NDdlOTktN2M2Ni00YmI4LTg2NDEtNjFhMjQwNTdmMmU4IiwiZXNzZW50aWFsIjp0cnVlfX19LCJub25jZSI6IjA2MjNlNTM2YzUwNDRiNGFhM2Y2YzY2ZTc1MzdiZWUwIiwianRpIjoiMjEyM2E1OGMtMTExYi00OGY2LTg2ODAtZTViYTNiMzI3MjM5IiwiaWF0IjoxNjIzMjI3MDAxLCJleHAiOjE2MjMyMjg4MDF9.JG5lc5TWjCucWZPfcyd34trk0QcGNzhYXfhHTlVrcfu1zjrAtSUI8i0o4yKqS19cOGKHq1HtuQac2hhO8gCr_vd5n7eIuIrWfjEM1MuIwsJ85jOpMBkEiSOurLRIgW77VmqHpVUVj5-0-1Tk-N-vaC_4nIdtSi576sOb4rjLQvs2EX_sFODGjyMxHXiZlnr2p71gA3nRy8M2Vv_At4-NPW8OLULS8zXclWoK797HFAGtsNLCy8tz0YCsnEaFhcLhZSliy3a7DRfxvBmIzhY23M4uQ6bpM1zCyqTPsOhqR-qdgnZorBrax_2CQ37yIeV4becUJWvZSdnjYX7gDtNltA",
    "qrCodeUrl": "https://images.yapily.com/image/4ef6e16c-dbe2-4d90-9e1b-868d946082ef/1623227001?size=0"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}
Status
Schema
default
Default

Create Account Authorisation

Example Request

curl -X POST https://api.yapily.com/account-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /account-auth-requests

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

See Redirect Account Flows for more information about this flow.

Feature: INITIATE_ACCOUNT_REQUEST

Example Request Bodies

CBI Globe Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "bpm-sandbox",
  "callback": "https://display-parameters.com/",
  "accountRequest": {
    "accountIdentifiersForBalance": [
      {
        "accountId": "account1234567",
        "accountIdentification": {
          "type": "IBAN",
          "identification": "IT77O0848283352871412938123"
        }
      }
    ],
    "accountIdentifiersForTransaction": [
      {
        "accountId": "account1234567",
        "accountIdentification": {
          "type": "IBAN",
          "identification": "IT77O0848283352871412938123"
        }
      }
    ]
  }
}

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

CBI Globe Example Response

{
  "meta": {
    "tracingId": "a55a89c4a27b41129e484d74fc338121"
  },
  "data": {
    "id": "4f988304-67ea-4ea9-a61e-cb90cac37f78",
    "userUuid": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "bpm-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-06-09T11:06:54.132Z",
    "expiresAt": "2021-09-07T00:00:00Z",
    "timeToExpire": "P89DT12H53M5.589S",
    "featureScope": [
      "ACCOUNT_BALANCES",
      "ACCOUNT_TRANSACTIONS"
    ],
    "state": "a55ae8debaad4fb991b73a3a912a2004",
    "institutionConsentId": "bdbd7ad0-b2d1-4a5c-9173-3586f30bc575",
    "authorisationUrl": "https://scasandbox.bancobpm.it/sca/login.html?idRichiestaSCA=20210609110654029&tipoRisorsa=C&codiceASPSP=05034",
    "qrCodeUrl": "https://images.yapily.com/image/72095dc7-4a23-4971-9a7f-e3f9c6af7921/1623236814?size=0"
  }
}

OBIE Example Response

{
  "meta": {
    "tracingId": "3b262569303f47f188d16b43acd552c0"
  },
  "data": {
    "id": "2d5c3632-1729-4a5e-bc69-c7fa1cbba815",
    "userUuid": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "modelo-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-06-09T08:03:20.510Z",
    "featureScope": [
      "ACCOUNT_STATEMENT_FILE",
      "ACCOUNTS",
      "ACCOUNT_STATEMENTS",
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNT",
      "ACCOUNT_BALANCES",
      "ACCOUNT_STATEMENT",
      "ACCOUNT_SCHEDULED_PAYMENTS",
      "ACCOUNT_TRANSACTIONS_WITH_MERCHANT",
      "ACCOUNT_PERIODIC_PAYMENTS",
      "ACCOUNT_BENEFICIARIES",
      "IDENTITY",
      "ACCOUNT_DIRECT_DEBITS"
    ],
    "state": "7948ba4d6a064001b06ef28f8c06ca4a",
    "institutionConsentId": "aac-0a743a0f-0b7d-4e7b-87eb-0bc65e1d2f97",
    "authorisationUrl": "https://ob19-auth1-ui.o3bank.co.uk/auth?client_id=e7f6b95b-5f35-419b-b301-8b08bcd946de&response_type=code+id_token&state=7948ba4d6a064001b06ef28f8c06ca4a&nonce=7948ba4d6a064001b06ef28f8c06ca4a&scope=openid+accounts&redirect_uri=https%3A%2F%2Fauth.yapily.com%2F&request=eyJraWQiOiJnRTRvU3VaZDl4TVpUNXZDdTNWYy1mdktNak0iLCJhbGciOiJQUzI1NiJ9.eyJhdWQiOiJodHRwczovL29iMTktYXV0aDEtdWkubzNiYW5rLmNvLnVrIiwic2NvcGUiOiJvcGVuaWQgYWNjb3VudHMiLCJpc3MiOiJlN2Y2Yjk1Yi01ZjM1LTQxOWItYjMwMS04YjA4YmNkOTQ2ZGUiLCJjbGllbnRfaWQiOiJlN2Y2Yjk1Yi01ZjM1LTQxOWItYjMwMS04YjA4YmNkOTQ2ZGUiLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vYXV0aC55YXBpbHkuY29tLyIsInN0YXRlIjoiNzk0OGJhNGQ2YTA2NDAwMWIwNmVmMjhmOGMwNmNhNGEiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsiYWNyIjp7InZhbHVlIjoidXJuOm9wZW5iYW5raW5nOnBzZDI6c2NhIiwiZXNzZW50aWFsIjp0cnVlfSwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoiYWFjLTBhNzQzYTBmLTBiN2QtNGU3Yi04N2ViLTBiYzY1ZTFkMmY5NyIsImVzc2VudGlhbCI6dHJ1ZX19LCJ1c2VyaW5mbyI6eyJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJhYWMtMGE3NDNhMGYtMGI3ZC00ZTdiLTg3ZWItMGJjNjVlMWQyZjk3IiwiZXNzZW50aWFsIjp0cnVlfX19LCJub25jZSI6Ijc5NDhiYTRkNmEwNjQwMDFiMDZlZjI4ZjhjMDZjYTRhIiwianRpIjoiNTIxNGFjNTQtNTEzYi00N2Y1LTgyYjUtZWExY2NhYzg0YzNiIiwiaWF0IjoxNjIzMjI1ODAxLCJleHAiOjE2MjMyMjc2MDF9.wmNfzJD1ekN_f028qWOyVvICkFm2uJ5Umok4hmxk4HZnDY2AOWDg4VX_MJjPHDydhfW8ZciBfCbEgmnButmASBbil-tHzwDIholS4RmnOZ4DXD-AttYx_VA2_X36J53kmlCHstPZpoawSIzdcnyW0JIhmVEvs5ZsaJvsDKhWk0hgYNS2GI0PORcn85W98EaE8APVrsz-tR-EfC9NmSZu7tH1zLyyD43AuD2BqdlMiYVTlzZsJ3FGPZ-ddT0rRloJvxPV6GLibjNAEowpSLjmDLv2v7gWszmYgcrzp5UM2jllfVL2KPA6Be5Eg6LVkL60Q3FKQyOMc8SCAWhALq_7Ew",
    "qrCodeUrl": "https://images.yapily.com/image/3b634d3c-a2ce-49b8-9014-330661800604/1623225801?size=0"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Update Account Pre-authorisation

Example Request

curl -X PUT https://api.yapily.com/account-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

PUT /account-auth-requests

Used to continue the authorisation process and for any Institution that contains the INITIATE_PRE_AUTHORISATION feature and direct user to the login screen of their financial institution in order to give consent to access account data.

See Redirect Account Flows for more information about this flow.

Features:

Example Request Bodies

Berlin Group Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "n26"
}

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

OBIE Example Response

{
  "meta": {
    "tracingId": "ee8e5bcfedf348b18ae45a34135790cc"
  },
  "data": {
    "id": "68e14e00-38b0-467d-a999-f70340e467b3",
    "userUuid": "e2578545-27a4-4edf-983f-5d33c2d7b559",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "n26",
    "institutionConsentId": "87ec9ded-d5ea-4fb6-80c5-ad4c88246c9f",
    "state": "4f4f9766f7264afc96a5269d6e65e066",
    "status": "AWAITING_DECOUPLED_AUTHORIZATION",
    "authorizedAt": "2021-05-13T09:00:06.867Z",
    "createdAt": "2021-05-13T08:59:23.864Z",
    "featureScope": [
      "ACCOUNT_TRANSACTIONS",
      "INITIATE_PRE_AUTHORISATION",
      "ACCOUNTS",
      "ACCOUNT_TRANSACTIONS_WITH_MERCHANT"
    ]
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Create Bulk Payment Authorisation

Example Request

curl -X POST https://api.yapily.com/bulk-payment-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /bulk-payment-auth-requests

Used to initiate the authorisation process and direct users to the login screen of their financial Institution in order to give their consent for a bulk payment. See Bulk Payments for more information.

See Redirect Payment Flows for more information about this flow.

Feature: INITIATE_BULK_PAYMENT

Example Request Bodies

UK Bulk Payment Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "modelo-sandbox",
  "callback": "https://display-parameters.com/",
  "paymentRequest": {
    "payments": [
      {
        "type": "DOMESTIC_PAYMENT",
        "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9",
        "reference": "payment1",
        "amount": {
          "amount": 2,
          "currency": "GBP"
        },
        "payee": {
          "name": "Jane Doe",
          "accountIdentifications": [
            {
              "type": "ACCOUNT_NUMBER",
              "identification": "12345678"
            },
            {
              "type": "SORT_CODE",
              "identification": "123456"
            }
          ]
        }
      },
      {
        "type": "DOMESTIC_PAYMENT",
        "paymentIdempotencyId": "4279gdy8t63dg73gd8gx87738dg",
        "reference": "payment2",
        "amount": {
          "amount": 5,
          "currency": "GBP"
        },
        "payee": {
          "name": "John Doe",
          "accountIdentifications": [
            {
              "type": "ACCOUNT_NUMBER",
              "identification": "87654321"
            },
            {
              "type": "SORT_CODE",
              "identification": "654321"
            }
          ]
        }
      }
    ]
  }
}

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

UK Bulk Payment Example Response

{
  "meta": {
    "tracingId": "96169af01d394ad39658f17d53b49a5d"
  },
  "data": {
    "id": "a2a9ec77-a479-4996-9896-4568e1968e7a",
    "userUuid": "5350782b-60f3-489e-aae5-a24d8d679a07",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "modelo-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-06-09T13:48:25.138Z",
    "featureScope": [
      "EXISTING_PAYMENTS_DETAILS",
      "EXISTING_PAYMENT_INITIATION_DETAILS",
      "CREATE_BULK_PAYMENT"
    ],
    "state": "80052c03007f41d589f64377eef4d620",
    "institutionConsentId": "sdp-6-25ff5bd8-d01c-422d-aa9e-8e68808bc899",
    "authorisationUrl": "https://ob19-auth1-ui.o3bank.co.uk/auth?client_id=e7f6b95b-5f35-419b-b301-8b08bcd946de&response_type=code+id_token&state=80052c03007f41d589f64377eef4d620&nonce=80052c03007f41d589f64377eef4d620&scope=openid+payments&redirect_uri=https%3A%2F%2Fauth.yapily.com%2F&request=eyJraWQiOiJnRTRvU3VaZDl4TVpUNXZDdTNWYy1mdktNak0iLCJhbGciOiJQUzI1NiJ9.eyJhdWQiOiJodHRwczovL29iMTktYXV0aDEtdWkubzNiYW5rLmNvLnVrIiwic2NvcGUiOiJvcGVuaWQgcGF5bWVudHMiLCJpc3MiOiJlN2Y2Yjk1Yi01ZjM1LTQxOWItYjMwMS04YjA4YmNkOTQ2ZGUiLCJjbGllbnRfaWQiOiJlN2Y2Yjk1Yi01ZjM1LTQxOWItYjMwMS04YjA4YmNkOTQ2ZGUiLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vYXV0aC55YXBpbHkuY29tLyIsInN0YXRlIjoiODAwNTJjMDMwMDdmNDFkNTg5ZjY0Mzc3ZWVmNGQ2MjAiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsiYWNyIjp7InZhbHVlIjoidXJuOm9wZW5iYW5raW5nOnBzZDI6c2NhIiwiZXNzZW50aWFsIjp0cnVlfSwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoic2RwLTYtMjVmZjViZDgtZDAxYy00MjJkLWFhOWUtOGU2ODgwOGJjODk5IiwiZXNzZW50aWFsIjp0cnVlfX0sInVzZXJpbmZvIjp7Im9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6InNkcC02LTI1ZmY1YmQ4LWQwMWMtNDIyZC1hYTllLThlNjg4MDhiYzg5OSIsImVzc2VudGlhbCI6dHJ1ZX19fSwibm9uY2UiOiI4MDA1MmMwMzAwN2Y0MWQ1ODlmNjQzNzdlZWY0ZDYyMCIsImp0aSI6ImUxYjZmMWM4LTQ1ZTktNGM0NS05NGE0LWExMTY1Nzk2NjZiNiIsImlhdCI6MTYyMzI0NjUwNSwiZXhwIjoxNjIzMjQ4MzA1fQ.C5YkClHiDOWl1CKnmEY0gM_JizUuELp2-k7sDjsWV5T-mgTWviO-jM7iVfCf4MsU6batLSBmeUFLco1b3S8PTQkAzwM3laHIgbfDAb_6bYkSBTbPriyzKcC8xAwhX3VdvWtb9qqdrn9zXSmIIITBhJdMzk1cgIjyETD7WNPln839eGP1-w8iB8yDOJOkYGRHJ850mQY-lk61GegmKs5kaxtYPIhrG2gygIi3JsN-uQJ6YOl2-5pylTEcJbuwhFiyeePdqHZdabqW2BSA6lDKQbMV_Zow_zhSWoFFv6RZdXCQpt4TBRj1W7tzZQKin-MC-TpzaF1q07RpSy0NtlN85w",
    "qrCodeUrl": "https://images.yapily.com/image/2bbb79b8-2c4a-4c8e-9132-0636879437da/1623246505?size=0"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Create Embedded Account Authorisation

Example Request

curl -X POST https://api.yapily.com/embedded-account-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /embedded-account-auth-requests

Used to initiate the embedded authorisation process for an Institution that contains the INITIATE_EMBEDDED_ACCOUNT_REQUEST feature in order to obtain the the user's authorisation to access their account information.

See Embedded Account Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_ACCOUNT_REQUEST

Example Request Bodies

Berlin Group Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "fiducia-sandbox",
  "userCredentials": {
    "id": "6154057725",
    "password": "PISPWD12"
  }
}

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Berlin Group (Multiple SCA Methods) Example Response

{
  "meta": {
    "tracingId": "a9d8d8c5e6a84b00b8510d90c28cbbc6"
  },
  "data": {
    "id": "149da283-2958-4128-9d72-e3a02e8bb83d",
    "userUuid": "6b082877-b137-4743-bba3-07b6a8148b42",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "fiducia-sandbox",
    "status": "AWAITING_SCA_METHOD",
    "createdAt": "2021-06-09T11:47:24.513Z",
    "expiresAt": "2021-09-07T00:00:00Z",
    "timeToExpire": "P89DT12H12M35.472S",
    "featureScope": [
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNTS",
      "ACCOUNT",
      "ACCOUNT_BALANCES"
    ],
    "state": "c99f35c118194737b83487a0e6a48ed9",
    "institutionConsentId": "4514274319060120226PSDLT-BL-LB002045CO9545RW",
    "scaMethods": [
      {
        "id": "962",
        "type": "CHIP_OTP",
        "description": "SmartTAN plus HHD 1.4"
      },
      {
        "id": "952",
        "type": "CHIP_OTP",
        "description": "SmartTAN optic"
      },
      {
        "id": "972",
        "type": "CHIP_OTP",
        "description": "SmartTAN optic/USB HHD 1.4"
      },
      {
        "id": "982",
        "type": "PHOTO_OTP",
        "description": "Smart-TAN photo"
      },
      {
        "id": "932",
        "type": "CHIP_OTP",
        "description": "SmartTAN plus"
      },
      {
        "id": "944",
        "type": "PUSH_OTP",
        "description": "SecureSIGN"
      },
      {
        "id": "942",
        "type": "SMS_OTP",
        "description": "mobile TAN"
      }
    ]
  }
}

Berlin Group (Single SCA Method) Example Response

{
  "meta": {
    "tracingId": "1565f7e13a0b4bf6b312cf8cc5747c7c"
  },
  "data": {
    "id": "66c8c0f2-1678-4404-a68f-2236a1afcdad",
    "userUuid": "6b082877-b137-4743-bba3-07b6a8148b42",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "fiducia-sandbox",
    "status": "AWAITING_SCA_CODE",
    "createdAt": "2021-06-09T11:49:18.815Z",
    "expiresAt": "2021-09-07T00:00:00Z",
    "timeToExpire": "P89DT12H10M41.167S",
    "featureScope": [
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNTS",
      "ACCOUNT",
      "ACCOUNT_BALANCES"
    ],
    "state": "3fb4024282d0432cb710094c4c723ae5",
    "institutionConsentId": "1448194319060120228PSDLT-BL-LB002045CO9545RW",
    "scaMethods": [
      {
        "id": "944",
        "type": "PUSH_OTP",
        "description": "SecureSIGN"
      }
    ],
    "selectedScaMethod": {
      "id": "944",
      "type": "PUSH_OTP",
      "description": "SecureSIGN"
    }
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Update Embedded Account Authorisation

Example Request

curl -X PUT https://api.yapily.com/embedded-account-auth-requests/{consentId} \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

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

Used to pass the SCA Code received from the Institution (and the SCA method selected by the user where multiple SCA methods are supported by the Institution) in order to complete the embedded authorisation to access the user's financial data.

See Embedded Account Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_ACCOUNT_REQUEST

Example Request Bodies

Berlin Group (SCA Code) Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "fiducia-sandbox",
  "scaCode": "6154057725"
}

Path Parameters

Name
Description
consentId
string
Mandatory. The consent Id of the Consent to update.

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Berlin Group (SCA Code) Example Response

{
  "meta": {
    "tracingId": "0ad7c46c4e4445bab3a0d4ccae25556b"
  },
  "data": {
    "id": "66c8c0f2-1678-4404-a68f-2236a1afcdad",
    "userUuid": "6b082877-b137-4743-bba3-07b6a8148b42",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "fiducia-sandbox",
    "status": "AUTHORIZED",
    "createdAt": "2021-06-09T11:49:18.815Z",
    "featureScope": [
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNTS",
      "ACCOUNT",
      "ACCOUNT_BALANCES"
    ],
    "state": "3fb4024282d0432cb710094c4c723ae5",
    "authorizedAt": "2021-06-09T11:51:14.140Z",
    "institutionConsentId": "1448194319060120228PSDLT-BL-LB002045CO9545RW"
  }
}

Berlin Group (Selected SCA Method) Example Response

{
  "meta": {
    "tracingId": "eaa703f3869b46b18732fa0de60f6073"
  },
  "data": {
    "id": "149da283-2958-4128-9d72-e3a02e8bb83d",
    "userUuid": "6b082877-b137-4743-bba3-07b6a8148b42",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "fiducia-sandbox",
    "status": "AWAITING_SCA_CODE",
    "createdAt": "2021-06-09T11:47:24.513Z",
    "expiresAt": "2021-09-07T00:00:00Z",
    "timeToExpire": "P89DT12H6M39.998S",
    "featureScope": [
      "ACCOUNT_TRANSACTIONS",
      "ACCOUNTS",
      "ACCOUNT",
      "ACCOUNT_BALANCES"
    ],
    "state": "c99f35c118194737b83487a0e6a48ed9",
    "institutionConsentId": "4514274319060120226PSDLT-BL-LB002045CO9545RW",
    "selectedScaMethod": {
      "id": "942",
      "type": "SMS_OTP",
      "description": "mobile TAN"
    }
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Create Embedded Bulk Payment Authorisation

Example Request

curl -X POST https://api.yapily.com/embedded-bulk-payment-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /embedded-bulk-payment-auth-requests

Used to initiate the embedded authorisation process for an Institution that contains the INITIATE_EMBEDDED_BULK_PAYMENT feature in order to obtain the the user's authorisation for a bulk payment. See Bulk Payments for more information.

See Embedded Payment Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_BULK_PAYMENT

Example Request Bodies

Berlin Group EUR Embedded Bulk Payment Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "fiducia-sandbox",
  "userCredentials": {
    "id": "VRK1234567890PLUS",
    "password": "password"
  },
  "paymentRequest": {
    "executionDateTime": "2021-10-29T00:00:00Z",
    "payments": [
      {
        "type": "DOMESTIC_PAYMENT",
        "paymentIdempotencyId": "e4f913909a3d11eabb370242ac130002",
        "reference": "REFERENCE",
        "amount": {
          "amount": 1,
          "currency": "EUR"
        },
        "payer": {
          "name": "John Doe",
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "DE39499999600000005111"
            }
          ]
        },
        "payee": {
          "name": "Jane Doe",
          "address": {
            "country": "DE"
          },
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "DE12345678901234567890"
            }
          ]
        }
      },
      {
        "type": "DOMESTIC_PAYMENT",
        "paymentIdempotencyId": "e4f913909a3d11eabb370242ac130002",
        "reference": "REFERENCE",
        "amount": {
          "amount": 1,
          "currency": "EUR"
        },
        "payer": {
          "name": "Jane Doe",
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "DE39499999600000005111"
            }
          ]
        },
        "payee": {
          "name": "John Doe",
          "address": {
            "country": "DE"
          },
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "DE12345678900000000000"
            }
          ]
        }
      }
    ]
  }
}

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Berlin Group EUR Embedded Bulk Payment Example Response

{
  "meta": {
    "tracingId": "4ab90c8cc13a4b74ba855a48100d6084"
  },
  "data": {
    "id": "6117b6dd-5a43-4f26-8e36-b91b9bf3c434",
    "userUuid": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "fiducia-sandbox",
    "status": "AWAITING_SCA_CODE",
    "createdAt": "2021-08-02T14:58:45.446Z",
    "featureScope": [
      "EXISTING_PAYMENT_INITIATION_DETAILS",
      "CREATE_BULK_PAYMENT",
      "EXISTING_PAYMENTS_DETAILS"
    ],
    "state": "85853421299c44e0829debefffd8622e",
    "institutionConsentId": "0515485612080120206PSDLT-BL-LB002045PA9545RW",
    "scaMethods": [
      {
        "id": "932",
        "type": "CHIP_OTP",
        "description": "SmartTAN plus"
      }
    ],
    "selectedScaMethod": {
      "id": "932",
      "type": "CHIP_OTP",
      "description": "SmartTAN plus"
    }
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Update Embedded Bulk Payment Authorisation

Example Request

curl -X PUT https://api.yapily.com/embedded-bulk-payment-auth-requests/{consentId} \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

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

Used to pass the SCA Code received from the Institution (and the SCA method selected by the user where multiple SCA methods are supported by the Institution) in order to complete the embedded authorisation to initiate a bulk payment. See Bulk Payments for more information.

See Embedded Payment Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_BULK_PAYMENT

Example Request Bodies

Berlin Group EUR Embedded Bulk Payment (SCA Code) Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "fiducia-sandbox",
  "scaCode": "123456",
  "paymentRequest": {
    "executionDateTime": "2021-10-29T00:00:00Z",
    "payments": [
      {
        "type": "DOMESTIC_PAYMENT",
        "paymentIdempotencyId": "e4f913909a3d11eabb370242ac130002",
        "reference": "REFERENCE",
        "amount": {
          "amount": 1,
          "currency": "EUR"
        },
        "payer": {
          "name": "John Doe",
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "DE39499999600000005111"
            }
          ]
        },
        "payee": {
          "name": "Jane Doe",
          "address": {
            "country": "DE"
          },
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "DE12345678901234567890"
            }
          ]
        }
      },
      {
        "type": "DOMESTIC_PAYMENT",
        "paymentIdempotencyId": "e4f913909a3d11eabb370242ac130002",
        "reference": "REFERENCE",
        "amount": {
          "amount": 1,
          "currency": "EUR"
        },
        "payer": {
          "name": "Jane Doe",
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "DE39499999600000005111"
            }
          ]
        },
        "payee": {
          "name": "John Doe",
          "address": {
            "country": "DE"
          },
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "DE12345678900000000000"
            }
          ]
        }
      }
    ]
  }
}

Path Parameters

Name
Description
consentId
string
Mandatory. The consent Id of the Consent to update.

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Berlin Group EUR Embedded Bulk Payment (SCA Code) Example Response

{
  "meta": {
    "tracingId": "cfa351c5de6f4398bb9deea04041acc5"
  },
  "data": {
    "id": "6117b6dd-5a43-4f26-8e36-b91b9bf3c434",
    "userUuid": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "fiducia-sandbox",
    "status": "AUTHORIZED",
    "createdAt": "2021-08-02T14:58:45.446Z",
    "featureScope": [
      "EXISTING_PAYMENT_INITIATION_DETAILS",
      "CREATE_BULK_PAYMENT",
      "EXISTING_PAYMENTS_DETAILS"
    ],
    "state": "85853421299c44e0829debefffd8622e",
    "authorizedAt": "2021-08-02T14:59:29.174Z",
    "institutionConsentId": "0515485612080120206PSDLT-BL-LB002045PA9545RW"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Create Embedded Payment Authorisation

Example Request

curl -X POST https://api.yapily.com/embedded-payment-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /embedded-payment-auth-requests

Used to initiate the embedded authorisation process for an Institution that contains the INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT feature in order to obtain the the user's authorisation for a payment.

See Embedded Payment Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT

Example Request Bodies

Berlin Group EUR Single Domestic Payment Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "postbank-sandbox",
  "userCredentials": {
    "id": "6154057725",
    "password": "PISPWD12"
  },
  "paymentRequest": {
    "type": "DOMESTIC_PAYMENT",
    "paymentIdempotencyId": "e4f913909a3d11eabb370242ac130002",
    "reference": "REFERENCE",
    "amount": {
      "amount": 1,
      "currency": "EUR"
    },
    "payer": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "DE12345678901234567890"
        }
      ]
    },
    "payee": {
      "name": "Jane Doe",
      "address": {
        "country": "DE"
      },
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "DE09876543210987654321"
        }
      ]
    }
  }
}

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Berlin Group EUR Single Domestic Payment Example Response

{
  "meta": {
    "tracingId": "bcebc29b55434cc8b2aae80cb782edff"
  },
  "data": {
    "id": "7c3f0355-f59b-4cc6-b13f-e1b5349b5caf",
    "userUuid": "95f71ebc-c8ae-4e25-aded-86e9bbd62966",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "postbank-sandbox",
    "state": "551440fc13794010855ad81c8463c926",
    "status": "AWAITING_SCA_METHOD",
    "createdAt": "2021-01-26T23:31:45.443Z",
    "featureScope": [
      "CREATE_DOMESTIC_SINGLE_PAYMENT",
      "EXISTING_PAYMENTS_DETAILS",
      "EXISTING_PAYMENT_INITIATION_DETAILS"
    ],
    "scaMethods": [
      {
        "id": "258211#OPTICAL",
        "type": "CHIP_OTP",
        "description": "Testkarte Hr. Haubach_1, optisch"
      },
      {
        "id": "258211#MANUEL",
        "type": "CHIP_OTP",
        "description": "Testkarte Hr. Haubach_1, manuell"
      },
      {
        "id": "591655",
        "type": "SMS_OTP",
        "description": "RolandmTAN"
      },
      {
        "id": "591656",
        "type": "PUSH_OTP",
        "description": "RSRolandIP2"
      }
    ]
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Update Embedded Payment Authorisation

Example Request

curl -X PUT https://api.yapily.com/embedded-payment-auth-requests/{consentId} \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

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

Used to pass the SCA Code received from the Institution (and the SCA method selected by the user where multiple SCA methods are supported by the Institution) in order to complete the embedded authorisation to initiate a payment.

See Embedded Payment Flows for more information about this flow.

Feature: INITIATE_EMBEDDED_DOMESTIC_SINGLE_PAYMENT

Example Request Bodies

Berlin Group EUR Single Domestic Payment (SCA Code) Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "postbank-sandbox",
  "scaCode": "325614",
  "paymentRequest": {
    "type": "DOMESTIC_PAYMENT",
    "paymentIdempotencyId": "e4f913909a3d11eabb370242ac130002",
    "reference": "REFERENCE",
    "amount": {
      "amount": 1,
      "currency": "EUR"
    },
    "payer": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "DE12345678901234567890"
        }
      ]
    },
    "payee": {
      "name": "Jane Doe",
      "address": {
        "country": "DE"
      },
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "DE09876543210987654321"
        }
      ]
    }
  }
}

Path Parameters

Name
Description
consentId
string
Mandatory. The consent Id of the Consent to update.

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Berlin Group EUR Single Domestic Payment (SCA Code) Example Response

{
  "meta": {
    "tracingId": "94563449b4634d13b89b8f1c78c21882"
  },
  "data": {
    "id": "1767d386-c20a-4136-a311-0a455dd41a78",
    "userUuid": "95f71ebc-c8ae-4e25-aded-86e9bbd62966",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "postbank-sandbox",
    "state": "048a1187a9324652bedb6a653211a8a3",
    "status": "AUTHORIZED",
    "createdAt": "2021-01-25T18:32:23.933Z",
    "featureScope": [
      "CREATE_DOMESTIC_SINGLE_PAYMENT",
      "EXISTING_PAYMENT_INITIATION_DETAILS",
      "EXISTING_PAYMENTS_DETAILS"
    ],
    "authorizedAt": "2021-01-25T18:33:18.248Z"
  }
}

Berlin Group EUR Single Domestic Payment (Selected SCA Method) Example Response

{
  "meta": {
    "tracingId": "f69f66322b4b482c93099a206d9f003e"
  },
  "data": {
    "id": "1767d386-c20a-4136-a311-0a455dd41a78",
    "userUuid": "95f71ebc-c8ae-4e25-aded-86e9bbd62966",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "postbank-sandbox",
    "state": "048a1187a9324652bedb6a653211a8a3",
    "status": "AWAITING_SCA_CODE",
    "createdAt": "2021-01-25T18:32:23.933Z",
    "featureScope": [
      "CREATE_DOMESTIC_SINGLE_PAYMENT",
      "EXISTING_PAYMENT_INITIATION_DETAILS",
      "EXISTING_PAYMENTS_DETAILS"
    ],
    "selectedScaMethod": {
      "id": "591655"
    }
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Create Payment Authorisation

Example Request

curl -X POST https://api.yapily.com/payment-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /payment-auth-requests

Used to initiate the authorisation process and direct users to the login screen of their financial Institution in order to give their consent for a payment. This endpoint is used to initiate all the different payment listed below. Based on the type of payment you wish to make, you may be required to provide specific properties in PaymentRequest. First make sure that the payment feature you wish to execute is supported by the bank by checking the features array in GET Institution.

See Redirect Payment Flows for more information about this flow.

Features:

Example Request Bodies

EUR Single Domestic Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "bpm-sandbox",
  "callback": "https://display-parameters.com/",
  "paymentRequest": {
    "paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
    "payer": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "DE12345678901234567890"
        }
      ]
    },
    "amount": {
      "amount": 1,
      "currency": "EUR"
    },
    "reference": "Bill Payment",
    "type": "DOMESTIC_PAYMENT",
    "payee": {
      "name": "Jane Doe",
      "address": {
        "country": "BE"
      },
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "BE12345678901234"
        }
      ]
    }
  }
}

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

EUR Single Domestic Example Response

{
  "meta": {
    "tracingId": "a3d09f97bea244e2bb8be0bffbe53f81"
  },
  "data": {
    "id": "cae22f3d-1033-4ba6-95ae-0d8ca193b090",
    "userUuid": "5350782b-60f3-489e-aae5-a24d8d679a07",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "bpm-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-06-10T11:47:12.887Z",
    "featureScope": [
      "EXISTING_PAYMENTS_DETAILS",
      "CREATE_DOMESTIC_SINGLE_PAYMENT",
      "EXISTING_PAYMENT_INITIATION_DETAILS"
    ],
    "state": "6a5f69be6a084b5c8c1becac88d45c95",
    "institutionConsentId": "79cee256-077f-4e11-a307-43892646a4a6",
    "authorisationUrl": "https://scasandbox.bancobpm.it/sca/login.html?paymentId=79cee256-077f-4e11-a307-43892646a4a6&tppAuthenticationRedirectUri=https%3A%2F%2Fauth.yapily.com%2F%3Ftwofold_redirect%3Dtrue%26state%3D6a5f69be6a084b5c8c1becac88d45c95&tppName=YAPILY+LTD&aspspCode=05034&aspspProductCode=IBP01&tppRegistrationNumber=PSDGB-FCA-927459&hash=GY5CmKG3MVeoxrboUQkjCoIb1X0nGR9ZTfoIG3T%2FLx1At1UJ92w0sjDeRXbNP9NhO203Y03UeI6Xn9ThebOjtQ%3D%3D",
    "qrCodeUrl": "https://images.yapily.com/image/5955c0db-a5b7-4b12-a682-0f83317ba46d/1623325632?size=0"
  }
}

GBP Single Domestic Example Response

{
  "meta": {
    "tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
  },
  "data": {
    "id": "eb39f8ae-aeff-4ffa-a23d-d4a5b3eff406",
    "userUuid": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "modelo-sandbox",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2021-06-08T09:45:42.145Z",
    "featureScope": [
      "EXISTING_PAYMENTS_DETAILS",
      "EXISTING_PAYMENT_INITIATION_DETAILS",
      "CREATE_DOMESTIC_SINGLE_PAYMENT"
    ],
    "state": "430b2756e9724c8eaad3862524817260",
    "institutionConsentId": "sdp-1-6d8d035e-868e-4355-be41-bddc25b7aac8",
    "authorisationUrl": "https://ob19-auth1-ui.o3bank.co.uk/auth?client_id=e7f6b95b-5f35-419b-b301-8b08bcd946de&response_type=code+id_token&state=430b2756e9724c8eaad3862524817260&nonce=430b2756e9724c8eaad3862524817260&scope=openid+payments&redirect_uri=https%3A%2F%2Fauth.yapily.com%2F&request=eyJraWQiOiJnRTRvU3VaZDl4TVpUNXZDdTNWYy1mdktNak0iLCJhbGciOiJQUzI1NiJ9.eyJhdWQiOiJodHRwczovL29iMTktYXV0aDEtdWkubzNiYW5rLmNvLnVrIiwic2NvcGUiOiJvcGVuaWQgcGF5bWVudHMiLCJpc3MiOiJlN2Y2Yjk1Yi01ZjM1LTQxOWItYjMwMS04YjA4YmNkOTQ2ZGUiLCJjbGllbnRfaWQiOiJlN2Y2Yjk1Yi01ZjM1LTQxOWItYjMwMS04YjA4YmNkOTQ2ZGUiLCJyZXNwb25zZV90eXBlIjoiY29kZSBpZF90b2tlbiIsInJlZGlyZWN0X3VyaSI6Imh0dHBzOi8vYXV0aC55YXBpbHkuY29tLyIsInN0YXRlIjoiNDMwYjI3NTZlOTcyNGM4ZWFhZDM4NjI1MjQ4MTcyNjAiLCJjbGFpbXMiOnsiaWRfdG9rZW4iOnsiYWNyIjp7InZhbHVlIjoidXJuOm9wZW5iYW5raW5nOnBzZDI6c2NhIiwiZXNzZW50aWFsIjp0cnVlfSwib3BlbmJhbmtpbmdfaW50ZW50X2lkIjp7InZhbHVlIjoic2RwLTEtNmQ4ZDAzNWUtODY4ZS00MzU1LWJlNDEtYmRkYzI1YjdhYWM4IiwiZXNzZW50aWFsIjp0cnVlfX0sInVzZXJpbmZvIjp7Im9wZW5iYW5raW5nX2ludGVudF9pZCI6eyJ2YWx1ZSI6InNkcC0xLTZkOGQwMzVlLTg2OGUtNDM1NS1iZTQxLWJkZGMyNWI3YWFjOCIsImVzc2VudGlhbCI6dHJ1ZX19fSwibm9uY2UiOiI0MzBiMjc1NmU5NzI0YzhlYWFkMzg2MjUyNDgxNzI2MCIsImp0aSI6IjJjYzczMzRhLTJmMDYtNDNjNi04MDkzLTNiYWZjNjQzMWE0YyIsImlhdCI6MTYyMzE0NTU0MiwiZXhwIjoxNjIzMTQ3MzQyfQ.bh0sCVmwkwbx_rxxIwE6p7SjswaH007bdMJfWYo_njIHwoPOkcGjygi2yU7bpNd7bqeqxY1adtkMg_acg6A7awq1jX7nxv6mZC44Q2zGKNMc_nOQPSNO6LkktRcozBxyJ2sEfLheVmmVsyyCQw4FV0w_7Cgc4tFO11FjZ0LNxbp5kpMCK7SABa4RgvZ4IpG-Zl6jFKHfNK1zUP79yBaQcBvNseIirAmG3iJjdpwVc3tD8bl-0SPcPwStk1A3T8OvOgW8DKM4OSEPgKL73I9CExQiJzYykKYLr8tp9bQmI0OgajVM9BT2nbKszRnRe92gPq31goRHHWhfzgQHKFBCNg",
    "qrCodeUrl": "https://images.yapily.com/image/5121fd6a-5010-4f36-9c25-df691cf465c1/1623145542?size=0"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Update Payment Pre-authorisation

Example Request

curl -X PUT https://api.yapily.com/payment-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

PUT /payment-auth-requests

Used to continue the authorisation process and for any Institution that contains the INITIATE_PRE_AUTHORISATION feature and direct user to the login screen of their financial institution in order to give consent to initiate a payment.

See Redirect Payment Flows for more information about this flow.

Feature: INITIATE_PRE_AUTHORISATION

Example Request Bodies

Berlin Group EUR Single Domestic Payment Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "n26",
  "paymentRequest": {
    "paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
    "payer": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "DE12345678901234567890"
        }
      ]
    },
    "amount": {
      "amount": 1,
      "currency": "EUR"
    },
    "reference": "Bill Payment",
    "type": "DOMESTIC_PAYMENT",
    "payee": {
      "name": "Jane Doe",
      "address": {
        "country": "BE"
      },
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "BE12345678901234"
        }
      ]
    }
  }
}

Header Parameters

Name
Description
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Berlin Group EUR Single Domestic Payment Example Response

{
  "meta": {
    "tracingId": "54ec0645a5b444c4a70c61357e9ad887"
  },
  "data": {
    "id": "53ff00d0-91dd-417d-880b-cdd7c50090ed",
    "userUuid": "e2578545-27a4-4edf-983f-5d33c2d7b559",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "n26",
    "state": "4399535ee4de46238fce108a95669848",
    "status": "AWAITING_DECOUPLED_AUTHORIZATION",
    "createdAt": "2021-06-10T09:54:46.669Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION",
      "CREATE_DOMESTIC_SINGLE_PAYMENT",
      "EXISTING_PAYMENTS_DETAILS"
    ],
    "authorizedAt": "2021-06-10T09:55:22.359Z",
    "institutionConsentId": "a9582f8e-08be-4cca-9f01-1ad3be96532d"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Create Pre-authorisation

Example Request

curl -X POST https://api.yapily.com/pre-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /pre-auth-requests

Used to initiate the pre-authorisation process for any Institution that contains the INITIATE_PRE_AUTHORISATION feature to authenticate the user.

Feature: INITIATE_PRE_AUTHORISATION

Example Request Bodies

Berlin Group (AIS) Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "n26",
  "callback": "https://display-parameters.com/",
  "scope": "AIS"
}

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Berlin Group Example (AIS) Response

{
  "meta": {
    "tracingId": "8acb66e6a9e142e79acc3ccf6cc03e04"
  },
  "data": {
    "id": "73064bb9-c84d-4242-897c-4150aacfa658",
    "userUuid": "e2578545-27a4-4edf-983f-5d33c2d7b559",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "n26",
    "state": "1575102ed5664761bce34927f0caa50f",
    "status": "AWAITING_PRE_AUTHORIZATION",
    "createdAt": "2021-05-11T13:03:43.619Z",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "authorisationUrl": "https://app.n26.com/open-banking?requestId=9ae856ce-6b10-4956-8da8-c66ee0c9d86f&state=1575102ed5664761bce34927f0caa50f&authType=XS2A&scope=DEDICATED_AISP",
    "qrCodeUrl": "https://images.yapily.com/image/f86d382b-c00a-4650-8d0d-9ee6ba1093cd/1620738225?size=0"
  }
}

Berlin Group Example (PIS) Response

{
  "meta": {
    "tracingId": "ba79c56773de42129dbf8164b202276c"
  },
  "data": {
    "id": "53ff00d0-91dd-417d-880b-cdd7c50090ed",
    "userUuid": "e2578545-27a4-4edf-983f-5d33c2d7b559",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "n26",
    "state": "4399535ee4de46238fce108a95669848",
    "status": "AWAITING_PRE_AUTHORIZATION",
    "createdAt": "2021-06-10T09:54:46.669Z",
    "featureScope": [
      "INITIATE_ONETIME_PRE_AUTHORISATION_PAYMENTS"
    ],
    "authorisationUrl": "https://app.n26.com/open-banking?requestId=2e2b2efd-82bb-4a2b-8f67-ced1a93511b8&state=4399535ee4de46238fce108a95669848&authType=XS2A&scope=DEDICATED_PISP",
    "qrCodeUrl": "https://images.yapily.com/image/7384ad3b-5eb1-4304-9cfa-7aa6fcc5e0c7/1623318888?size=0"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Create Payment Pre-authorisation

Example Request

curl -X POST https://api.yapily.com/payment-pre-auth-requests \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

POST /payment-pre-auth-requests

Used to initiate the pre-authorisation process for payments for CbiGlobe Institution that contains the INITIATE_ONETIME_PRE_AUTHORISATION_PAYMENTS feature to authenticate the user.

Feature: INITIATE_ONETIME_PRE_AUTHORISATION_PAYMENTS

Example Request Bodies

Cbi Globe (PIS) Example Request

{
  "applicationUserId": "john.doe@company.com",
  "institutionId": "n26",
  "callback": "https://display-parameters.com/",
  "scope": "PIS",
  "reference": "Bill Payment",
  "amount": {
    "amount": 1,
    "currency": "EUR"
  },
  "payee": {
    "name": "Jane Doe",
    "country": "BE",
    "accountIdentifications": [
      {
        "type": "IBAN",
        "identification": "BE12345678901234"
      }
    ]
  },
  "payer": {
    "accountIdentifications": [
      {
        "type": "IBAN",
        "identification": "DE12345678901234567890"
      }
    ]
  }
}

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

Berlin Group Example (PIS) Response

{
  "meta": {
    "tracingId": "ba79c56773de42129dbf8164b202276c"
  },
  "data": {
    "id": "53ff00d0-91dd-417d-880b-cdd7c50090ed",
    "userUuid": "e2578545-27a4-4edf-983f-5d33c2d7b559",
    "applicationUserId": "john.doe@company.com",
    "institutionId": "n26",
    "state": "4399535ee4de46238fce108a95669848",
    "status": "AWAITING_PRE_AUTHORIZATION",
    "createdAt": "2021-06-10T09:54:46.669Z",
    "featureScope": [
      "INITIATE_ONETIME_PRE_AUTHORISATION_PAYMENTS"
    ],
    "authorisationUrl": "https://app.n26.com/open-banking?requestId=2e2b2efd-82bb-4a2b-8f67-ced1a93511b8&state=4399535ee4de46238fce108a95669848&authType=XS2A&scope=DEDICATED_PISP",
    "qrCodeUrl": "https://images.yapily.com/image/7384ad3b-5eb1-4304-9cfa-7aa6fcc5e0c7/1623318888?size=0"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Financial Data

In order to access a user's Financial Data, you are required to request an Authorisation from the user to share the account information the bank has. Once a consent-token is obtained, you can call the necessary Financial Data endpoint(s) to retrieve the user's data.

Get Accounts

Example Request

curl -X GET https://api.yapily.com/accounts \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts

Used to return all accounts and balances for the end user associated with the presented consent token.

Feature: ACCOUNTS

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

OBIE Example Response

{
  "meta": {
    "tracingId": "1139346006be4345a94fd8b3728844e3",
    "count": 1
  },
  "data": [
    {
      "id": "700004000000000000000002",
      "type": "Personal - Current",
      "balance": -12.57,
      "currency": "GBP",
      "usageType": "PERSONAL",
      "accountType": "CURRENT",
      "nickname": "xxxx0006",
      "accountNames": [
        {
          "name": "Mr. Roberto Rastapopoulos & Ivan Sakharine"
        }
      ],
      "accountIdentifications": [
        {
          "type": "SORT_CODE",
          "identification": "700001"
        },
        {
          "type": "ACCOUNT_NUMBER",
          "identification": "70000002"
        }
      ],
      "accountBalances": [
        {
          "type": "EXPECTED",
          "dateTime": "2021-06-09T08:51:02.463Z",
          "balanceAmount": {
            "amount": -12.57,
            "currency": "GBP"
          },
          "creditLineIncluded": false,
          "creditLines": []
        }
      ]
    }
  ]
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Account

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId} \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}

Used to return the account and balance information for the end user associated with the presented consent token.

Feature: ACCOUNTS

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

OBIE Example Response

{
  "meta": {
    "tracingId": "01191f59dcd54be2854a7e686702dbd6"
  },
  "data": {
    "id": "700004000000000000000002",
    "type": "Personal - Current",
    "balance": -12.57,
    "currency": "GBP",
    "usageType": "PERSONAL",
    "accountType": "CURRENT",
    "nickname": "xxxx0006",
    "accountNames": [
      {
        "name": "Mr. Roberto Rastapopoulos & Ivan Sakharine"
      }
    ],
    "accountIdentifications": [
      {
        "type": "SORT_CODE",
        "identification": "700001"
      },
      {
        "type": "ACCOUNT_NUMBER",
        "identification": "70000002"
      }
    ],
    "accountBalances": [
      {
        "type": "EXPECTED",
        "dateTime": "2021-06-09T08:51:02.463Z",
        "balanceAmount": {
          "amount": -12.57,
          "currency": "GBP"
        },
        "creditLineIncluded": false,
        "creditLines": []
      }
    ]
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Account Balances

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId}/balances \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}/balances

Used to return the balance for the end user associated with the presented consent token.

Note: This endpoint is only for obtaining the balance information of an account belonging to an Institution that exposes their APIs through the CBI Globe Gateway. If the Institution you wish to obtain balance data is not in the CBI Globe, use Get Account or Get Accounts to get balance data.

Feature: ACCOUNT_BALANCES

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

CBI Globe Example Response

{
  "meta": {
    "tracingId": "82e86ae9547a4f04b3773c1207e4b84d"
  },
  "data": {
    "mainBalanceAmount": {
      "amount": -3079208604.11,
      "currency": "EUR"
    },
    "balances": [
      {
        "type": "INTERIM_AVAILABLE",
        "balanceAmount": {
          "amount": -3079208604.11,
          "currency": "EUR"
        }
      },
      {
        "type": "AUTHORISED",
        "balanceAmount": {
          "amount": -3079208604.11,
          "currency": "EUR"
        }
      }
    ]
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Account Beneficiaries

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId}/beneficiaries \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}/beneficiaries

Used to get all the beneficiaries of a user's account

Feature: ACCOUNT_BENEFICIARIES

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

OBIE Example Response

{
  "data": [
    {
      "id": "112",
      "trusted": true,
      "reference": "Rent",
      "payee": {
        "name": "John Doe",
        "accountIdentifications": [
          {
            "type": "SORT_CODE",
            "identification": "123456"
          },
          {
            "type": "ACCOUNT_NUMBER",
            "identification": "12345678"
          }
        ]
      }
    }
  ]
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Account Direct Debits

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId}/direct-debits \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}/direct-debits

Used to get the list of direct debits for an account.

Feature: ACCOUNT_DIRECT_DEBIT

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.

Query Parameters

Name
Description
limit
integer(int32)
Optional. The maximum number of transaction records to be returned. Must be between 0 and 1000.
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

OBIE Example Response

{
  "meta": {
    "tracingId": "c2dec674a3fb402e8543129565491244",
    "count": 2,
    "pagination": {
      "totalCount": 2,
      "self": {
        "limit": 1000
      }
    }
  },
  "data": [
    {
      "id": "700009000000000000000076",
      "statusDetails": {
        "status": "INACTIVE"
      },
      "payeeDetails": {
        "name": "EDF ENERGY"
      },
      "reference": "671018097704",
      "previousPaymentAmount": {
        "amount": 145,
        "currency": "GBP"
      },
      "previousPaymentDateTime": "2016-10-05T00:00:00Z"
    },
    {
      "id": "700009000000000000000038",
      "statusDetails": {
        "status": "ACTIVE"
      },
      "payeeDetails": {
        "name": "SANTANDER MORTGAGE"
      },
      "reference": "40118272",
      "previousPaymentAmount": {
        "amount": 1000,
        "currency": "GBP"
      },
      "previousPaymentDateTime": "2017-12-01T00:00:00Z"
    }
  ],
  "links": {
    "self": "https://api.yapily.com/accounts/700004000000000000000002/direct-debits?limit=1000"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Account Periodic Payments

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId}/periodic-payments \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}/periodic-payments

Used to get the list of periodic payments (standing orders in the UK) for an account.

Feature: ACCOUNT_PERIODIC_PAYMENTS

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.

Query Parameters

Name
Description
limit
integer(int32)
Optional. The maximum number of transaction records to be returned. Must be between 0 and 1000.
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

OBIE Example Response

{
  "meta": {
    "tracingId": "51d039be096f492ca5184d4ea72b4caf",
    "count": 1,
    "pagination": {
      "totalCount": 1,
      "self": {
        "limit": 1000
      }
    }
  },
  "data": [
    {
      "id": "95d29cb3-5ef4-4c92-885f-8ba971adc5d1",
      "statusDetails": {
        "status": "UNKNOWN"
      },
      "payeeDetails": {
        "name": "xxxxx129",
        "accountIdentifications": [
          {
            "type": "IBAN",
            "identification": "DE16700222000072880129"
          }
        ]
      },
      "reference": "544878_60c0809a",
      "firstPaymentAmount": {
        "amount": 1259,
        "currency": "GBP"
      },
      "firstPaymentDateTime": "2021-07-10T23:00:00Z",
      "nextPaymentAmount": {
        "amount": 1259,
        "currency": "GBP"
      },
      "nextPaymentDateTime": "2021-07-10T23:00:00Z",
      "finalPaymentAmount": {
        "amount": 1259,
        "currency": "GBP"
      },
      "finalPaymentDateTime": "2022-04-11T23:00:00Z",
      "frequency": {
        "frequencyType": "MONTHLY",
        "intervalMonth": 1,
        "executionDay": 11
      }
    }
  ],
  "links": {
    "self": "https://api.yapily.com/accounts/700004000000000000000002/periodic-payments?limit=1000"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Account Scheduled Payments

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId}/scheduled-payments \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}/scheduled-payments

Used to get the list of scheduled payments for an account.

Feature: ACCOUNT_SCHEDULED_PAYMENT

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.

Query Parameters

Name
Description
limit
integer(int32)
Optional. The maximum number of transaction records to be returned. Must be between 0 and 1000.
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

OBIE Example Response

{
  "meta": {
    "tracingId": "0de4ed83caf542f6bcaa30c62275191c",
    "count": 1,
    "pagination": {
      "totalCount": 1,
      "self": {
        "limit": 1000
      }
    }
  },
  "data": [
    {
      "id": "6f62b428-c3a0-42eb-a838-ae41e52916e9",
      "payeeDetails": {
        "name": "Mr. Roberto Rastapopoulos & Ivan Sakharine & mits",
        "accountIdentifications": [
          {
            "type": "ACCOUNT_NUMBER",
            "identification": "70000002"
          },
          {
            "type": "SORT_CODE",
            "identification": "700001"
          }
        ]
      },
      "reference": "f62ee3bad94d432d9786ba038131b5d7",
      "amountDetails": {
        "amount": 1,
        "currency": "GBP"
      },
      "scheduledPaymentType": "EXECUTION",
      "scheduledPaymentDateTime": "2021-12-01T00:00:00+01:00"
    }
  ],
  "links": {
    "self": "https://api.yapily.com/accounts/700004000000000000000002/scheduled-payments?limit=1000"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Account Statements

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId}/statements \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}/statements

Used to get the list of statements for an account.

Feature: ACCOUNT_STATEMENTS

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.

Query Parameters

Name
Description
from
string
Optional. Returned transactions will be on or after this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
before
string
Optional. Returned transactions will be on or before this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
limit
integer(int32)
Optional. The maximum number of transaction records to be returned. Must be between 0 and 1000.
sort
SortEnum
Optional. Sort transaction records by date ascending with 'date' or descending with '-date'. The default sort order is descending
offset
integer(int32)
Optional. The number of transaction records to be skipped. Used primarily with paginated results.
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Enumerated Values

Parameter Value
sort date
sort -date

Example Responses

Example Response

{
  "meta": {
    "tracingId": "fd5c215acd034401a8eaa8aeec1eafc7",
    "count": 1,
    "pagination": {
      "totalCount": 1,
      "self": {
        "limit": 1000,
        "sort": "-date",
        "offset": 0
      }
    }
  },
  "data": [
    {
      "id": "700014000000000000000002",
      "startDateTime": "2017-08-01T00:00:00Z",
      "endDateTime": "2017-08-31T23:59:59Z",
      "creationDateTime": "2017-09-01T00:00:00Z"
    }
  ],
  "links": {
    "self": "https://api.yapily.com/accounts/700004000000000000000002/statements?from&before&limit=1000&sort=-date&offset=0"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Account Statement

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId}/statements/{statementId} \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: string' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}/statements/{statementId}

Used to get a statement for an account.

Feature: ACCOUNT_STATEMENT

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.
statementId
string
Mandatory. The statement Id of the statement file.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

Example Response

{
  "meta": {
    "tracingId": "8bacaae3025647efa1891157993e32fb"
  },
  "data": {
    "id": "700014000000000000000002",
    "startDateTime": "2017-08-01T00:00:00Z",
    "endDateTime": "2017-08-31T23:59:59Z",
    "creationDateTime": "2017-09-01T00:00:00Z"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Account Statement File

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId}/statements/{statementId}/file \
  -H 'Accept: application/pdf' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}/statements/{statementId}/file

Used to get the statement file for an account.

Feature: ACCOUNT_STATEMENT_FILE

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.
statementId
string
Mandatory. The statement Id of the statement file.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

200 Response

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
200
OK
string
default
Default

Get Account Transactions

Example Request

curl -X GET https://api.yapily.com/accounts/{accountId}/transactions \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /accounts/{accountId}/transactions

Used to get the account transactions for an account

Feature: ACCOUNT_TRANSACTIONS

Path Parameters

Name
Description
accountId
string
Mandatory. The account Id of the user's bank account.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
with
array[string]
Optional. Can be categories or merchant. When set, will include enrichment data in the transactions returned.

Enrichment data is optional, e.g. when 'merchant' enrichment data is requested, the enrichment response will include merchant data only if it can be evaluated from the transaction.
from
string
Optional. Returned transactions will be on or after this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
before
string
Optional. Returned transactions will be on or before this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
limit
integer(int32)
Optional. The maximum number of transaction records to be returned. Must be between 0 and 1000.
sort
SortEnum
Optional. Sort transaction records by date ascending with 'date' or descending with '-date'. The default sort order is descending
offset
integer(int32)
Optional. The number of transaction records to be skipped. Used primarily with paginated results.
cursor
string
Optional. This property is not currently in use.
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Enumerated Values

Parameter Value
sort date
sort -date

Example Responses

Example Response

{
  "meta": {
    "tracingId": "488ce8243ee74a378be722ffffec8f7f",
    "count": 1,
    "pagination": {
      "totalCount": 1,
      "self": {
        "limit": 1000,
        "sort": "-date",
        "offset": 0
      }
    }
  },
  "data": [
    {
      "id": "49d6e5c6-0130-46e3-884b-1b185432d9e0",
      "date": "2021-05-06T17:44:34.589Z",
      "bookingDateTime": "2021-05-06T17:44:34.589Z",
      "valueDateTime": "2021-05-06T17:44:34.589Z",
      "status": "BOOKED",
      "amount": -100.23,
      "currency": "GBP",
      "transactionAmount": {
        "amount": -100.23,
        "currency": "GBP"
      },
      "reference": "0",
      "description": "Debit for Payment Id: sdp-1-57379a43-c4b8-49f5-bd7c-699189ee7a60",
      "transactionInformation": [
        "Debit for Payment Id: sdp-1-57379a43-c4b8-49f5-bd7c-699189ee7a60"
      ],
      "isoBankTransactionCode": {
        "domainCode": {
          "code": "PMNT",
          "name": "Payments"
        },
        "familyCode": {
          "code": "ICDT",
          "name": "Issued Credit Transfers"
        },
        "subFamilyCode": {
          "code": "DMCT",
          "name": "Domestic Credit Transfer"
        }
      },
      "proprietaryBankTransactionCode": {
        "code": "PMT",
        "issuer": "modelo-sandbox"
      },
      "balance": {
        "type": "CLOSING_AVAILABLE",
        "balanceAmount": {
          "amount": 426.53,
          "currency": "GBP"
        }
      },
      "enrichment": {
        "transactionHash": {
          "hash": "adad72d7b3069ab9e4a6cb2844e2e3e9.1"
        }
      }
    }
  ],
  "links": {
    "self": "https://api.yapily.com/accounts/700004000000000000000002/transactions?from&before&limit=1000&sort=-date&offset=0&cursor"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Categories

Example Request

curl -X GET https://api.yapily.com/categories/{country} \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'Authorization: Basic {authToken}'

GET /categories/{country}

Used to retrieve the list of categories returned by the Yapily Categorisation engine for a given locale.

See Data Enrichment for more information.

Path Parameters

Name
Description
country
string
Mandatory. The 2 letter country code e.g. 'GB'.

Example Responses

Example Response

{
  "meta": {
    "tracingId": "a5b0fc4b8b8a4b7085f4412b2b64e969",
    "count": 21
  },
  "data": [
    {
      "id": "06d10bcd-dbcc-4a61-b5a1-c119adc16adf",
      "label": "INCOME",
      "country": "GB",
      "subcategories": []
    },
    {
      "id": "1051a1ff-5552-4b53-ba43-eeeac96d710f",
      "label": "INCOME_OTHER",
      "country": "GB",
      "subcategories": []
    },
    {
      "id": "2f527678-a698-4c00-9880-3063b39f71df",
      "label": "INCOME_REFUNDS",
      "country": "GB",
      "subcategories": []
    },
    {
      "id": "3954ed5c-1663-4356-869e-241f305c8b4b",
      "label": "BILLS",
      "country": "GB",
      "subcategories": [
        {
          "id": "03e037d4-c950-4540-a298-36cce7eb9ce9",
          "label": "INTERNET / TV"
        },
        {
          "id": "05ed46b2-dfa4-4cde-8900-692a899e1290",
          "label": "MOBILE PHONE"
        },
        {
          "id": "06df5c74-3783-48d4-9825-f508a237d60f",
          "label": "SUBSCRIPTION"
        },
        {
          "id": "11e189ab-3794-478b-8a30-1c1c7aae7af1",
          "label": "TV LICENCE"
        },
        {
          "id": "1238e562-2a7b-4ef1-8e41-037491cefd53",
          "label": "UTILITY BILL"
        },
        {
          "id": "129c7a08-2125-4b0f-87bb-253fca906eb7",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "5de14494-fec8-44c2-af9c-91656d2e8d1b",
      "label": "CHARITY AND GIFTS",
      "country": "GB",
      "subcategories": [
        {
          "id": "1655bc45-de79-4fd2-9b45-8bd9271a2520",
          "label": "DONATIONS"
        },
        {
          "id": "1b9e1a46-5229-4488-a68c-19d7cb450c79",
          "label": "GIFTS"
        },
        {
          "id": "1d09a62b-1f9c-418d-9f37-9ee5003d5abc",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "6edef913-2c1e-4935-9f23-4a71fe92124c",
      "label": "EATING OUT",
      "country": "GB",
      "subcategories": [
        {
          "id": "1e13a0f5-6892-4436-ba71-f11cd1a0b8fe",
          "label": "COFFEE"
        },
        {
          "id": "1eb03b3e-e9ab-4d54-ae9a-e63778390794",
          "label": "DRINKS"
        },
        {
          "id": "253e0e15-f260-44ee-a1cf-ac42afbc8a48",
          "label": "FAST FOOD"
        },
        {
          "id": "25a39d3e-d2c5-47e5-9874-57d9d4edfaaa",
          "label": "RESTAURANT"
        },
        {
          "id": "26594166-4e32-4a9b-8cbf-ea7ab86c19e6",
          "label": "TAKEAWAY / DELIVERY"
        },
        {
          "id": "36949186-bb90-427a-840b-8d9c9ff5ca35",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "705dddcc-03f8-4a27-ac8b-a2256f950239",
      "label": "ENTERTAINMENT",
      "country": "GB",
      "subcategories": [
        {
          "id": "380694b8-efc4-4443-9c49-df81229f3d69",
          "label": "ART / MUSEUM"
        },
        {
          "id": "380c0b10-1afd-4f4f-8fd5-7cac3392fb9a",
          "label": "CINEMA"
        },
        {
          "id": "397b698d-4f46-4356-a283-2af934bf51a3",
          "label": "LIVE MUSIC"
        },
        {
          "id": "39aed540-1702-4e50-9109-5808e5636146",
          "label": "LIVE SPORT"
        },
        {
          "id": "44a99d0c-2718-4c95-8c2c-13c9802e2d20",
          "label": "THEATRE"
        },
        {
          "id": "4a419ef8-f953-4866-881e-0ad61adf110c",
          "label": "NIGHTCLUB"
        },
        {
          "id": "4c483465-980d-4274-81d5-32e2d61e8aed",
          "label": "ONLINE GAMBLING"
        },
        {
          "id": "50bbec77-b23d-4ce2-bedb-a0e1ca2e34f4",
          "label": "LOTTERY"
        },
        {
          "id": "5a3d65f9-a8ae-4eb8-bae0-973c7c4de372",
          "label": "BETTING SHOP"
        },
        {
          "id": "5b8493cb-09f6-457a-a642-9a309ee1d424",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "75cdc4b8-dc29-409f-8f9b-a99341ea2e39",
      "label": "INVESTMENT AND SAVINGS",
      "country": "GB",
      "subcategories": [
        {
          "id": "5c8c11a1-ad38-4101-898e-9ceb1ee90d48",
          "label": "CREDIT CARD PAYMENT"
        },
        {
          "id": "5f93b21e-7e63-4652-91a9-610026252b29",
          "label": "INVESTMENTS"
        },
        {
          "id": "5fb0ba5d-71eb-42db-bd51-63637ef356df",
          "label": "SAVINGS"
        },
        {
          "id": "5fe79b4e-8ab3-4cb4-b51e-bc5eb3263a0c",
          "label": "PENSION"
        },
        {
          "id": "61eaee8c-eea4-4d9f-93f1-74f22f38b6ea",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "7bc5d291-8af1-4ad0-bf29-302f4e1c6995",
      "label": "GENERAL",
      "country": "GB",
      "subcategories": [
        {
          "id": "656abd3b-8a71-455f-ab28-6f4e3262da2c",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "84c9be40-4114-43ce-9e06-5f93c2719693",
      "label": "GROCERIES",
      "country": "GB",
      "subcategories": [
        {
          "id": "69f5d7b7-f1e6-498a-9318-23ba5916c7ef",
          "label": "SUPERMARKET"
        },
        {
          "id": "6d4395bb-466c-419a-80b5-7428cec4f88f",
          "label": "ONLINE GROCERIES"
        },
        {
          "id": "74a0185b-632d-4edd-832f-d32582b15e8d",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "8abdddb5-92c4-42e1-b380-12537f84b40e",
      "label": "PERSONAL CARE",
      "country": "GB",
      "subcategories": [
        {
          "id": "7702e7ec-32b9-4ce6-879e-20ac84e52293",
          "label": "BEAUTY PRODUCTS"
        },
        {
          "id": "7affed3f-f9d0-4946-b2c0-70c79b0334ac",
          "label": "DOCTOR"
        },
        {
          "id": "7f84092a-c67d-4cb3-99af-c7a4be5109db",
          "label": "GYM / EXERCISE"
        },
        {
          "id": "7fcaceb6-9c4e-4395-b216-5ae41b3991d2",
          "label": "HAIRDRESSER"
        },
        {
          "id": "83f7fb77-8b56-4f47-b531-6d06e245597d",
          "label": "PHARMACY"
        },
        {
          "id": "8546fdde-8b73-4a58-9aa0-4781e4ca6340",
          "label": "SPA / BEAUTY TREATMENT"
        },
        {
          "id": "85936cb0-aa0c-4c93-b0bc-cbf1672bd675",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "8b37bbd3-76e9-4937-a7fc-e9cf7d8232a3",
      "label": "HOME",
      "country": "GB",
      "subcategories": [
        {
          "id": "899cbae5-c556-4e2d-8cdd-9fef7fd4d820",
          "label": "RENT"
        },
        {
          "id": "8af1b65f-62f2-4b56-a348-97e7390d2f62",
          "label": "MORTGAGE"
        },
        {
          "id": "8cf40b23-e7a4-4ae3-88f0-4ab3b35a679b",
          "label": "SERVICE CHARGE"
        },
        {
          "id": "8dfb3077-3e29-4a3b-b41c-964bf368071b",
          "label": "GARDEN"
        },
        {
          "id": "922cd0ca-bd5f-44ab-aa40-6536f9d2abe5",
          "label": "COUNCIL TAX"
        },
        {
          "id": "9d3ca620-4ae3-4296-8864-c0962b2f4539",
          "label": "HOME IMPROVEMENT"
        },
        {
          "id": "a1bfe200-c1d7-4c0c-9d60-d0b83cd71f74",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "92aef8f2-18f8-464f-8915-e44dc5b97731",
      "label": "INSURANCE",
      "country": "GB",
      "subcategories": [
        {
          "id": "a72f6cbf-d894-4bfa-ac87-39f85012a7f8",
          "label": "HOME INSURANCE"
        },
        {
          "id": "a7bc0f36-ee80-496c-a1c1-ac49c51c6d07",
          "label": "MOTOR INSURANCE"
        },
        {
          "id": "a8a505af-7e73-4d6f-a146-51d2eb5d4db8",
          "label": "TRAVEL INSURANCE"
        },
        {
          "id": "a9e1b431-6d75-41ac-9a23-44fb25e64b1a",
          "label": "HEALTH INSURANCE"
        },
        {
          "id": "aa420049-2d7a-4f11-94d5-c76e45329a47",
          "label": "LIFE INSURANCE"
        },
        {
          "id": "ab441944-859a-44db-93fc-0800266dd4f6",
          "label": "PET INSURANCE"
        },
        {
          "id": "ab95ea13-8d0c-497d-8d8b-e06cde0eaf97",
          "label": "PHONE / GADGET INSURANCE"
        },
        {
          "id": "aba53905-b630-4cf3-b1f8-698d124197a6",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "b0b56616-8cf6-4653-8512-d5eefe8400fe",
      "label": "OTHER",
      "country": "GB",
      "subcategories": [
        {
          "id": "ad5e46b2-f9ad-4ef2-96d7-a2817073beec",
          "label": "EDUCATION"
        },
        {
          "id": "b18ec1a3-171c-405a-bd4f-c9fddcd6c594",
          "label": "ATM WITHDRAWAL"
        },
        {
          "id": "b1d4abd8-1c2f-412a-9916-4167cc7d58d8",
          "label": "CREDIT CARD PAYMENT"
        },
        {
          "id": "b4cd0587-1d2f-4378-a31c-8ddc0ce0dc03",
          "label": "TRANSFER"
        },
        {
          "id": "b667ea18-8679-4608-91b6-cbd4488d3802",
          "label": "CARD TOPUP"
        },
        {
          "id": "b6c611d7-d8cc-4d16-8e42-16cfa6dfd56e",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "b1f468dd-8f0c-4bbb-a720-f6c117187b15",
      "label": "SHOPPING",
      "country": "GB",
      "subcategories": [
        {
          "id": "b7181636-097c-4362-9f71-9da1559685f2",
          "label": "BOOKS"
        },
        {
          "id": "becc8b91-f594-490b-aecf-50e12fb6ca84",
          "label": "CLOTHING"
        },
        {
          "id": "bf41624e-5790-43d9-966d-25878cd79881",
          "label": "ELECTRONICS"
        },
        {
          "id": "c8bab464-ade8-4ec2-9d83-d42a2aa7d088",
          "label": "GAMES"
        },
        {
          "id": "c99e826c-302c-4abf-85b5-557d65184f63",
          "label": "HOBBIES"
        },
        {
          "id": "cb09c4e8-00d2-41d7-a581-f73d0e3b0cb2",
          "label": "MUSIC"
        },
        {
          "id": "cbe0734a-c10b-4901-bf7c-be4df9b1ed42",
          "label": "PETS"
        },
        {
          "id": "d13b7872-0418-426c-9054-315a41ddcd21",
          "label": "SOFTWARE"
        },
        {
          "id": "d17705fc-1a34-42a2-bc77-0511635f0d21",
          "label": "SPORTING ITEMS"
        },
        {
          "id": "d2668855-296d-450f-b309-3f28c4f3fa5f",
          "label": "HOUSE ITEMS"
        },
        {
          "id": "d4cf6c32-d94f-4488-9e74-46734cb34cc2",
          "label": "FILM / DVD"
        },
        {
          "id": "d837fb3f-f614-410b-b9d9-3e89e92e683a",
          "label": "STATIONARY"
        },
        {
          "id": "d8d74d91-7810-4995-8337-72c39dff05a2",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "b831661f-c8af-4eec-91d8-b09b53616394",
      "label": "TRANSPORT",
      "country": "GB",
      "subcategories": [
        {
          "id": "d9da6e16-7a9f-41ee-b727-a7d39f0e4c2c",
          "label": "PUBLIC TRANSPORT"
        },
        {
          "id": "d9e7f133-d0d7-471a-be28-da3f61d453c2",
          "label": "PETROL / FUEL"
        },
        {
          "id": "dbb9104d-e0e4-4e25-838a-083dc751c665",
          "label": "PARKING"
        },
        {
          "id": "dcab2001-efc7-42be-a381-c7169ff806e6",
          "label": "TAXI"
        },
        {
          "id": "dee109d5-0347-404e-81f2-cc736949e62d",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "baf7ee41-0a29-49f7-b5fd-af602935c2fe",
      "label": "TRAVEL AND HOLIDAY",
      "country": "GB",
      "subcategories": [
        {
          "id": "e1cc65b3-30ba-47fc-90aa-c7a1fb93ebdf",
          "label": "AIR TRAVEL"
        },
        {
          "id": "e44e3d55-a843-4660-940b-b2756198992e",
          "label": "CAR RENTAL"
        },
        {
          "id": "e76ee6e8-1cef-4986-b229-ef96af9f473d",
          "label": "HOTELS"
        },
        {
          "id": "ed57cd0b-2abc-4af9-b478-75bbee149a5a",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "bc4de368-67f2-4bd6-ae09-ebfa1164e259",
      "label": "FEES AND CHARGES",
      "country": "GB",
      "subcategories": [
        {
          "id": "ed8d73e4-79ea-42a0-aab3-0c2d40594ba8",
          "label": "LATE FEE"
        },
        {
          "id": "ee16362b-f67c-4f1a-8e6a-f2ed6f325df3",
          "label": "ATM FEE"
        },
        {
          "id": "ef9652f1-67cf-40eb-8ef5-ecb96419c60c",
          "label": "SERVICE FEE"
        },
        {
          "id": "f0d996d4-be7e-48f3-bb3b-48d10c287b75",
          "label": "OVERDRAFT CHARGE"
        },
        {
          "id": "f16c80bb-4e77-43de-bb8e-3391d8c8d2f0",
          "label": "FOREIGN CURRENCY CHARGE"
        },
        {
          "id": "f2a19ee6-d181-4454-98e4-1f8c5d83be82",
          "label": "OTHER"
        }
      ]
    },
    {
      "id": "c17a6985-a47c-463c-bbd0-934a156224e3",
      "label": "FINANCES",
      "country": "GB",
      "subcategories": []
    },
    {
      "id": "cdc636d5-2dc7-444a-a53c-edd81f449cdc",
      "label": "TRANSFERS",
      "country": "GB",
      "subcategories": []
    },
    {
      "id": "2a497caa-eea6-4e99-b460-57a26fffd0d7",
      "label": "UNKNOWN",
      "country": "GB",
      "subcategories": []
    }
  ]
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Identity

Example Request

curl -X GET https://api.yapily.com/identity \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /identity

Used to get the identity information for an account.

Feature: IDENTITY

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

Example Response

{
  "meta": {
    "tracingId": "e4de605bd760459aa7f82aa81856ec1e"
  },
  "data": {
    "id": "700001000000000000000002",
    "fullName": "Mitsuhirato",
    "email": "mits@suntori.com",
    "phone": "+22-8937484901",
    "addresses": [
      {
        "addressLines": [],
        "city": "Hichikanzo",
        "postalCode": "JP102",
        "country": "TA"
      },
      {
        "addressLines": [],
        "city": "St Albans",
        "postalCode": "AL1 3SF",
        "country": "GB"
      }
    ]
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Payments

In order to make a Payment on behalf of a user, you are required to request an Authorisation from the user to authorise the user's account to make the payment from. Once a consent-token is obtained, you can call the necessary Payments endpoint(s) to execute a payment.

Create Bulk Payment

Example Request

curl -X POST https://api.yapily.com/bulk-payments \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

POST /bulk-payments

Used to initiate a bulk payment after obtaining the user's authorisation.

Feature: CREATE_BULK_PAYMENT

Example Request Bodies

UK Bulk Payment Example Request

{
  "payments": [
    {
      "type": "DOMESTIC_PAYMENT",
      "paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9",
      "reference": "payment1",
      "amount": {
        "amount": 2,
        "currency": "GBP"
      },
      "payee": {
        "name": "Jane Doe",
        "accountIdentifications": [
          {
            "type": "ACCOUNT_NUMBER",
            "identification": "12345678"
          },
          {
            "type": "SORT_CODE",
            "identification": "123456"
          }
        ]
      }
    },
    {
      "type": "DOMESTIC_PAYMENT",
      "paymentIdempotencyId": "4279gdy8t63dg73gd8gx87738dg",
      "reference": "payment2",
      "amount": {
        "amount": 5,
        "currency": "GBP"
      },
      "payee": {
        "name": "John Doe",
        "accountIdentifications": [
          {
            "type": "ACCOUNT_NUMBER",
            "identification": "87654321"
          },
          {
            "type": "SORT_CODE",
            "identification": "654321"
          }
        ]
      }
    }
  ]
}

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

UK Bulk Payment Example Response

{
  "meta": {
    "tracingId": "0cda48c70f3941148bbee775a65fa3d0"
  },
  "data": {
    "id": "pv3-a1e2ecb0-270c-42e2-8ba5-005261b629d2",
    "institutionConsentId": "sdp-6-b06f9a82-c641-4aba-b76d-43e6bc052f75",
    "status": "COMPLETED",
    "statusDetails": {
      "status": "COMPLETED",
      "statusUpdateDate": "2021-06-09T13:53:28.67Z"
    },
    "createdAt": "2021-06-09T13:53:28.67Z",
    "bulkAmountSum": 7
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Create Payment

Example Request

curl -X POST https://api.yapily.com/payments \
  -H 'Content-Type: application/json;charset=UTF-8' \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

POST /payments

Used to initiate a payment after obtaining the user's authorisation.

Features:

Example Request Bodies

EUR Domestic Single Payment Example Request

{
  "paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
  "payer": {
    "name": "John Doe",
    "accountIdentifications": [
      {
        "type": "IBAN",
        "identification": "DE12345678901234567890"
      }
    ]
  },
  "amount": {
    "amount": 1,
    "currency": "EUR"
  },
  "reference": "Bill Payment",
  "type": "DOMESTIC_PAYMENT",
  "payee": {
    "name": "Jane Doe",
    "address": {
      "country": "BE"
    },
    "accountIdentifications": [
      {
        "type": "IBAN",
        "identification": "BE12345678901234"
      }
    ]
  }
}

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Request Body Schema

Name
Description
Mandatory. The request body

Example Responses

EUR Domestic Single Payment Example Response

{
  "meta": {
    "tracingId": "0f14e900011b445fa6b6c2c4272d7321"
  },
  "data": {
    "id": "a9582f8e-08be-4cca-9f01-1ad3be96532d",
    "status": "COMPLETED",
    "statusDetails": {
      "status": "COMPLETED",
      "isoStatus": {
        "code": "ACCP",
        "name": "AcceptedCustomerProfile"
      }
    },
    "payer": {
      "name": "John Doe",
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "DE12345678901234567890"
        }
      ]
    },
    "payeeDetails": {
      "name": "Jane Doe",
      "accountIdentifications": [
        {
          "type": "IBAN",
          "identification": "BE12345678901234"
        }
      ]
    },
    "reference": "Bill Payment",
    "amount": 1,
    "currency": "EUR",
    "amountDetails": {
      "amount": 1,
      "currency": "EUR"
    }
  }
}

GBP Domestic Single Payment Example Response

{
  "meta": {
    "tracingId": "2b93dc6029634a5095b3415cc5cc0e84"
  },
  "data": {
    "id": "pv3-a6ac6528-e8c8-44eb-b6f9-8521963518dc",
    "institutionConsentId": "sdp-1-27a192bb-482f-4731-989b-e7271661248c",
    "paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
    "paymentLifecycleId": "3gaq9wj387aojd83dh7549824",
    "status": "COMPLETED",
    "statusDetails": {
      "status": "COMPLETED",
      "statusUpdateDate": "2021-06-10T11:26:54.887Z",
      "isoStatus": {
        "code": "ACSC",
        "name": "AcceptedSettlementCompleted"
      }
    },
    "payeeDetails": {
      "name": "Jane Doe",
      "accountIdentifications": [
        {
          "type": "ACCOUNT_NUMBER",
          "identification": "12345678"
        },
        {
          "type": "SORT_CODE",
          "identification": "123456"
        }
      ]
    },
    "reference": "Bill Payment",
    "amount": 1,
    "currency": "GBP",
    "amountDetails": {
      "amount": 1,
      "currency": "GBP"
    },
    "createdAt": "2021-06-10T11:26:54.887Z"
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Get Payment Details

Example Request

curl -X GET https://api.yapily.com/payments/{paymentId}/details \
  -H 'Accept: application/json;charset=UTF-8' \
  -H 'consent: {consentToken}' \
  -H 'Authorization: Basic {authToken}'

GET /payments/{paymentId}/details

Used to get the payment details of a payment. This is most commonly used to check for any updates to the payment status.

Feature: EXISTING_PAYMENTS_DETAILS

Path Parameters

Name
Description
paymentId
string
Mandatory. The payment Id of the payment.

Header Parameters

Name
Description
consent
string
Mandatory. The consent-token containing the user's authorisation to make the request.
psu-id
string
Conditional. Represents the user's login ID for the Institution to a personal account.

See PSU identifiers to see if this header is required.
psu-corporate-id
string
Conditional. Represents the user's login ID for the Institution to a business account.

See PSU identifiers to see if this header is required.
psu-ip-address
string
Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Query Parameters

Name
Description
raw
boolean
Optional. Used to obtain the raw request and response to and from the Institution.

Example Responses

EUR Single Domestic Payment Example Response

{
  "meta": {
    "tracingId": "590c99aecd2844c7a5c3ea00c55ce0ef"
  },
  "data": {
    "payments": [
      {
        "paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
        "payer": {
          "name": "John Doe",
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "DE12345678901234567890"
            }
          ]
        },
        "amount": 1,
        "amountDetails": {
          "amount": 1,
          "currency": "EUR"
        },
        "reference": "Bill Payment",
        "type": "DOMESTIC_PAYMENT",
        "payee": {
          "name": "Jane Doe",
          "address": {
            "country": "BE"
          },
          "accountIdentifications": [
            {
              "type": "IBAN",
              "identification": "BE12345678901234"
            }
          ]
        }
      }
    ]
  }
}

GBP Single Domestic Payment Example Response

{
  "meta": {
    "tracingId": "547ffd74b2ea46968cef64e0ddac59e1"
  },
  "data": {
    "payments": [
      {
        "id": "pv3-a6ac6528-e8c8-44eb-b6f9-8521963518dc",
        "institutionConsentId": "sdp-1-27a192bb-482f-4731-989b-e7271661248c",
        "paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
        "paymentLifecycleId": "3gaq9wj387aojd83dh7549824",
        "status": "COMPLETED",
        "statusDetails": {
          "status": "COMPLETED",
          "statusUpdateDate": "2021-06-10T11:26:54.887Z",
          "isoStatus": {
            "code": "ACSC",
            "name": "AcceptedSettlementCompleted"
          }
        },
        "payeeDetails": {
          "name": "Jane Doe",
          "accountIdentifications": [
            {
              "type": "ACCOUNT_NUMBER",
              "identification": "12345678"
            },
            {
              "type": "SORT_CODE",
              "identification": "123456"
            }
          ]
        },
        "reference": "Bill Payment",
        "amount": 1,
        "currency": "GBP",
        "amountDetails": {
          "amount": 1,
          "currency": "GBP"
        },
        "createdAt": "2021-06-10T11:26:54.887Z"
      }
    ]
  }
}

UK Bulk Payment Example Response

{
  "meta": {
    "tracingId": "a63d57d771d64875a8230a1fcabd87f2"
  },
  "data": {
    "payments": [
      {
        "id": "pv3-a1e2ecb0-270c-42e2-8ba5-005261b629d2",
        "institutionConsentId": "sdp-6-b06f9a82-c641-4aba-b76d-43e6bc052f75",
        "status": "COMPLETED",
        "statusDetails": {
          "status": "COMPLETED",
          "statusUpdateDate": "2021-06-09T13:53:28.67Z"
        },
        "createdAt": "2021-06-09T13:53:28.67Z",
        "bulkAmountSum": 7
      }
    ]
  }
}

Error Response

{
  "error": {
    "code": 401,
    "status": "UNAUTHORIZED",
    "message": "Full authentication is required to access this resource"
  }
}

Responses

Status
Schema
default
Default

Financial Profile

The Financial Profile endpoints assist in collating authorised consents for a user which can subsequently be used to classify user income streams across multiple accounts. For each income stream, the financial profile determines the frequency and score that describes how well the income stream fits to that schedule.

Example Request

curl -X POST https://api.yapily.com/users/{userUuid}/profile/consents \
  -H 'Accept: application/json' \
  -H 'consent: string' \
  -H 'Authorization: Basic {authToken}'

POST /users/{userUuid}/profile/consents

Used to add a consent to a Financial Profile for a User. The response is asynchronous, returned with pending status, while retrieval of financial data is commenced. There is a limit of 10,000 transactions for enrichment.

Name
Description
userUuid
string(uuid)
Mandatory. The Yapily generated UUID for the user.
Name
Description
consent
string
Mandatory. The consent-token obtained from the original authorisation.

Example Responses

200 Response

{
  "id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
  "status": "PENDING",
  "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
  "referenceConsentId": "1e2e5167-8519-4c19-b016-8f2f0c6e38b6",
  "institutionId": "mock-sandbox"
}

Example Request

curl -X GET https://api.yapily.com/users/{userUuid}/profile/consents/{profileConsentId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {authToken}'

GET /users/{userUuid}/profile/consents/{profileConsentId}

Used to retreive a specific ProfileConsent for a User.

Name
Description
userUuid
string(uuid)
Mandatory. The Yapily generated UUID for the user.
profileConsentId
string
Mandatory. The ID of the ProfileConsent

Example Responses

200 Response

{
  "id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
  "status": "PENDING",
  "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
  "referenceConsentId": "1e2e5167-8519-4c19-b016-8f2f0c6e38b6",
  "institutionId": "mock-sandbox"
}

Example Request

curl -X DELETE https://api.yapily.com/users/{userUuid}/profile/consents/{profileConsentId} \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {authToken}'

DELETE /users/{userUuid}/profile/consents/{profileConsentId}

Used to delete a ProfileConsent for a User. This will remove the consent and all associated financial data from the 'Financial Profile'.

Name
Description
userUuid
string(uuid)
Mandatory. The Yapily generated UUID for the user.
profileConsentId
string
Mandatory. The ID of the ProfileConsent

Example Responses

400 Response

{
  "error": {
    "tracingId": "74b13ce8ed51419f92c5d609e04532de",
    "code": 424,
    "institutionError": {
      "errorMessage": "{\"Code\":\"500 Internal Server Error\",\"Id\":\"5ff8d331-4282-41e0-b5ef-1ac9ac39f009\",\"Message\":\"Technical Error. Please try again later\",\"Errors\":[{\"ErrorCode\":\"UK.OBIE.UnexpectedError\",\"Message\":\"There was a problem processing your request. Please try again later\"}]}",
      "httpStatusCode": 500
    },
    "source": "INSTITUTION",
    "status": "FAILED_DEPENDENCY"
  },
  "monitoring": []
}

Get User Profile

Example Request

curl -X GET https://api.yapily.com/users/{userUuid}/profile \
  -H 'Accept: application/json' \
  -H 'Authorization: Basic {authToken}'

GET /users/{userUuid}/profile

Used to retrieve a FinancialProfile for a User. Status will be PENDING until all ProfileConsents are COMPLETED.

Path Parameters

Name
Description
userUuid
string(uuid)
Mandatory. The Yapily generated UUID for the user.

Example Responses

200 Response

{
  "status": "COMPLETED",
  "profileConsents": [
    {
      "id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
      "status": "PENDING",
      "userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
      "referenceConsentId": "1e2e5167-8519-4c19-b016-8f2f0c6e38b6",
      "institutionId": "mock-sandbox"
    }
  ],
  "enrichment": {
    "incomeStreams": [
      {
        "name": "Amazon Marketplace",
        "transactions": [
          {
            "transactionId": null,
            "transactionInformation": null,
            "amount": null,
            "institution": null,
            "bookingDateTime": null
          }
        ],
        "transactionSchedule": {
          "frequency": "Daily",
          "detailedFrequency": "Daily",
          "detailedFrequencyParameter": 1
        },
        "scheduleConsistencyScore": 0.44,
        "nextExpectedTransactionDate": "2019-10-04",
        "earliestTransactionDate": "2020-04-24",
        "mostRecentTransactionDate": "2019-10-03",
        "amountConsistencyScore": 0.74,
        "averageAmount": 19.708
      }
    ],
    "expenditureStreams": [
      {
        "name": "Amazon Marketplace",
        "transactions": [
          {
            "transactionId": null,
            "transactionInformation": null,
            "amount": null,
            "institution": null,
            "bookingDateTime": null
          }
        ],
        "transactionSchedule": {
          "frequency": "Daily",
          "detailedFrequency": "Daily",
          "detailedFrequencyParameter": 1
        },
        "scheduleConsistencyScore": 0.44,
        "nextExpectedTransactionDate": "2019-10-04",
        "earliestTransactionDate": "2020-04-24",
        "mostRecentTransactionDate": "2019-10-03",
        "amountConsistencyScore": 0.74,
        "averageAmount": 19.708
      }
    ],
    "recentlyTerminatedIncomeStreams": [
      {
        "name": "Amazon Marketplace",
        "transactions": [
          {
            "transactionId": null,
            "transactionInformation": null,
            "amount": null,
            "institution": null,
            "bookingDateTime": null
          }
        ],
        "transactionSchedule": {
          "frequency": "Daily",
          "detailedFrequency": "Daily",
          "detailedFrequencyParameter": 1
        },
        "scheduleConsistencyScore": 0.44,
        "nextExpectedTransactionDate": "2019-10-04",
        "earliestTransactionDate": "2020-04-24",
        "mostRecentTransactionDate": "2019-10-03",
        "amountConsistencyScore": 0.74,
        "averageAmount": 19.708,
        "missedTransactions": 3
      }
    ],
    "recentlyTerminatedExpenditureStreams": [
      {
        "name": "Amazon Marketplace",
        "transactions": [
          {
            "transactionId": null,
            "transactionInformation": null,
            "amount": null,
            "institution": null,
            "bookingDateTime": null
          }
        ],
        "transactionSchedule": {
          "frequency": "Daily",
          "detailedFrequency": "Daily",
          "detailedFrequencyParameter": 1
        },
        "scheduleConsistencyScore": 0.44,
        "nextExpectedTransactionDate": "2019-10-04",
        "earliestTransactionDate": "2020-04-24",
        "mostRecentTransactionDate": "2019-10-03",
        "amountConsistencyScore": 0.74,
        "averageAmount": 19.708,
        "missedTransactions": 3
      }
    ]
  }
}

Schemas

Account

{
  "id": "string",
  "type": "string",
  "description": "string",
  "balance": 0,
  "currency": "string",
  "usageType": "PERSONAL",
  "accountType": "CASH_TRADING",
  "nickname": "string",
  "details": "string",
  "accountNames": [
    {
      "name": "string"
    }
  ],
  "accountIdentifications": [
    {
      "type": "SORT_CODE",
      "identification": "401016"
    }
  ],
  "accountBalances": [
    {
      "type": "CLOSING_AVAILABLE",
      "dateTime": "2019-08-24T14:15:22Z",
      "balanceAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "creditLineIncluded": true,
      "creditLines": [
        {
          "type": "AVAILABLE",
          "creditLineAmount": {
            "amount": null,
            "currency": null
          }
        }
      ]
    }
  ],
  "consolidatedAccountInformation": {
    "id": "string",
    "accountBalances": [
      {
        "type": "CLOSING_AVAILABLE",
        "dateTime": "2019-08-24T14:15:22Z",
        "balanceAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "creditLineIncluded": true,
        "creditLines": [
          {
            "type": null,
            "creditLineAmount": null
          }
        ]
      }
    ]
  }
}

Properties

Property
Description
id
string
Unique identifier of the account.
type
string
Specifies the type of account e.g. (BUSINESS_CURRENT).
description
string
Product name as defined by the financial institution for this account
balance
number
Main / headline balance for the account.

Use of this field is recommended as fallback only. Instead, use of the typed balances (accountBalances) is recommended.
currency
string
Currency the bank account balance is denoted in.

Specified as a 3-letter ISO 4217 currency code
usageType
UsageType
No description
accountType
AccountType
No description
nickname
string
Nickname of the account that was provided by the account owner.

May be used to aid identification of the account.
details
string
Supplementary specifications that might be provided by the Bank. These provide further characteristics about the account.
accountNames
[AccountName]
No description
accountIdentifications
[AccountIdentification]
Mandatory. The AccountIdentification object for the user's account identifications for the account
accountBalances
[AccountBalance]
No description
consolidatedAccountInformation
ConsolidatedAccountInformation
Summary information regarding account balances of the overall account provided by the bank

AccountApiListResponse

{
  "meta": {
    "tracingId": "string",
    "count": 0,
    "pagination": {
      "totalCount": 0,
      "self": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "sort": "date",
        "offset": 0,
        "cursor": "string"
      },
      "next": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "cursor": "string"
      }
    }
  },
  "data": [
    {
      "id": "string",
      "type": "string",
      "description": "string",
      "balance": 0,
      "currency": "string",
      "usageType": "PERSONAL",
      "accountType": "CASH_TRADING",
      "nickname": "string",
      "details": "string",
      "accountNames": [
        {
          "name": "string"
        }
      ],
      "accountIdentifications": [
        {
          "type": "SORT_CODE",
          "identification": "401016"
        }
      ],
      "accountBalances": [
        {
          "type": "CLOSING_AVAILABLE",
          "dateTime": "2019-08-24T14:15:22Z",
          "balanceAmount": {
            "amount": null,
            "currency": null
          },
          "creditLineIncluded": true,
          "creditLines": [
            {}
          ]
        }
      ],
      "consolidatedAccountInformation": {
        "id": "string",
        "accountBalances": [
          {
            "type": null,
            "dateTime": null,
            "balanceAmount": null,
            "creditLineIncluded": null,
            "creditLines": null
          }
        ]
      }
    }
  ],
  "links": {
    "property1": "string",
    "property2": "string"
  },
  "forwardedData": [
    {
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "url": "string"
    }
  ],
  "raw": [
    {
      "request": {
        "method": "string",
        "url": "string",
        "requestInstant": "2019-08-24T14:15:22Z",
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "body": {},
        "bodyParameters": {
          "property1": "string",
          "property2": "string"
        },
        "startTime": "2019-08-24T14:15:22Z",
        "startedAt": "2019-08-24T14:15:22Z"
      },
      "duration": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "resultCode": 0,
      "result": {}
    }
  ],
  "paging": {
    "apiCall": {},
    "data": [
      {
        "id": "string",
        "type": "string",
        "description": "string",
        "balance": 0,
        "currency": "string",
        "usageType": "PERSONAL",
        "accountType": "CASH_TRADING",
        "nickname": "string",
        "details": "string",
        "accountNames": [
          {
            "name": null
          }
        ],
        "accountIdentifications": [
          {
            "type": null,
            "identification": null
          }
        ],
        "accountBalances": [
          {
            "type": null,
            "dateTime": null,
            "balanceAmount": null,
            "creditLineIncluded": null,
            "creditLines": null
          }
        ],
        "consolidatedAccountInformation": {
          "id": "string",
          "accountBalances": [
            null
          ]
        }
      }
    ],
    "nextCursorHash": "string",
    "nextLink": "string",
    "pagingMap": {
      "property1": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "sort": "date",
        "offset": 0,
        "cursor": "string"
      },
      "property2": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "sort": "date",
        "offset": 0,
        "cursor": "string"
      }
    },
    "totalCount": 0
  },
  "tracingId": "string"
}

Properties

Property
Description
No description
data
[Account]
No description
links
object
No description
» additionalProperties
string
No description
forwardedData
[ResponseForwardedData]
No description
No description
No description
tracingId
string
No description

ApiResponseOfAccount

{
  "meta": {
    "tracingId": "string"
  },
  "data": {
    "id": "string",
    "type": "string",
    "description": "string",
    "balance": 0,
    "currency": "string",
    "usageType": "PERSONAL",
    "accountType": "CASH_TRADING",
    "nickname": "string",
    "details": "string",
    "accountNames": [
      {
        "name": "string"
      }
    ],
    "accountIdentifications": [
      {
        "type": "SORT_CODE",
        "identification": "401016"
      }
    ],
    "accountBalances": [
      {
        "type": "CLOSING_AVAILABLE",
        "dateTime": "2019-08-24T14:15:22Z",
        "balanceAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "creditLineIncluded": true,
        "creditLines": [
          {
            "type": null,
            "creditLineAmount": null
          }
        ]
      }
    ],
    "consolidatedAccountInformation": {
      "id": "string",
      "accountBalances": [
        {
          "type": "[",
          "dateTime": "2019-08-24T14:15:22Z",
          "balanceAmount": {},
          "creditLineIncluded": true,
          "creditLines": [
            null
          ]
        }
      ]
    }
  },
  "links": {
    "property1": "string",
    "property2": "string"
  },
  "forwardedData": [
    {
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "url": "string"
    }
  ],
  "raw": [
    {
      "request": {
        "method": "string",
        "url": "string",
        "requestInstant": "2019-08-24T14:15:22Z",
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "body": {},
        "bodyParameters": {
          "property1": "string",
          "property2": "string"
        },
        "startTime": "2019-08-24T14:15:22Z",
        "startedAt": "2019-08-24T14:15:22Z"
      },
      "duration": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "resultCode": 0,
      "result": {}
    }
  ],
  "tracingId": "string"
}

Properties

Property
Description
No description
data
Account
No description
links
object
No description
» additionalProperties
string
No description
forwardedData
[ResponseForwardedData]
No description
No description
tracingId
string
No description

AccountAuthorisationRequest

{
  "userUuid": "dcbf2986-7a6c-4291-9074-6441a23e4826",
  "applicationUserId": "user-234562290",
  "forwardParameters": [
    "string"
  ],
  "institutionId": "yapily-mock",
  "callback": "https://display-parameters.com",
  "redirect": {
    "url": "string"
  },
  "oneTimeToken": false,
  "accountRequest": {
    "transactionFrom": "2020-01-01T00:00:00Z",
    "transactionTo": "2021-01-01T00:00:00Z",
    "expiresAt": "2025-01-01T00:00:00Z",
    "accountIdentifiers": {
      "accountId": "500000000000000000000001",
      "accountIdentification": {
        "type": "SORT_CODE",
        "identification": "401016"
      }
    },
    "accountIdentifiersForTransaction": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {
          "type": "SORT_CODE",
          "identification": "401016"
        }
      }
    ],
    "accountIdentifiersForBalance": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {
          "type": "SORT_CODE",
          "identification": "401016"
        }
      }
    ],
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ]
  }
}

Properties

Property
Description
userUuid
string(uuid)
User for which the authorisation request was created.
applicationUserId
string
Conditional. User-friendly identifier of the User that provides authorisation. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.
forwardParameters
[string]
Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId
string
Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.
callback
string
Optional. The server to redirect the user to after the user completes the authorisation at the Institution.

See Using a callback (Optional) for more information.
redirect
RedirectRequest
Optional. The server to redirect the user to after the user complete the authorisation at the Institution.
oneTimeToken
boolean
Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.
accountRequest
AccountRequest
Conditional. Used to further specify details of the Consent to request

Conditions:
  1. Mandatory to access balance/transaction data for an Institution within the CBI Globe
  2. Mandatory to specify the individual scopes to request from the user at the Institution for an account authorisation
  3. Mandatory to specify an expiry time on the created Consent at which time will render it unusable
  4. Mandatory to specify the date range that the created Consent will be able to access transactions for (given the range is support for the Institution)

AccountBalance

{
  "type": "CLOSING_AVAILABLE",
  "dateTime": "2019-08-24T14:15:22Z",
  "balanceAmount": {
    "amount": 10,
    "currency": "GBP"
  },
  "creditLineIncluded": true,
  "creditLines": [
    {
      "type": "AVAILABLE",
      "creditLineAmount": {
        "amount": 10,
        "currency": "GBP"
      }
    }
  ]
}

Properties

Property
Description
No description
dateTime
string(date-time)
Date and time of the reported balance.
balanceAmount
Amount
Mandatory. The Amount object that contains the amount and currency of the payment.
creditLineIncluded
boolean
_Optional_. Indicates whether any credit lines are included in the balance.
creditLines
[CreditLine]
_Optional_. Specifies the type of balance.

EmbeddedAccountAuthorisationRequest

{
  "userUuid": "dcbf2986-7a6c-4291-9074-6441a23e4826",
  "applicationUserId": "user-234562290",
  "forwardParameters": [
    "string"
  ],
  "institutionId": "yapily-mock",
  "callback": "https://display-parameters.com",
  "redirect": {
    "url": "string"
  },
  "oneTimeToken": false,
  "userCredentials": {
    "id": "6154057725",
    "corporateId": "6345898763",
    "password": "PISPWD12"
  },
  "selectedScaMethod": {
    "id": "944",
    "type": "PUSH_OTP",
    "description": "SecureSIGN"
  },
  "scaCode": "325614",
  "accountRequest": {
    "transactionFrom": "2020-01-01T00:00:00Z",
    "transactionTo": "2021-01-01T00:00:00Z",
    "expiresAt": "2025-01-01T00:00:00Z",
    "accountIdentifiers": {
      "accountId": "500000000000000000000001",
      "accountIdentification": {
        "type": "SORT_CODE",
        "identification": "401016"
      }
    },
    "accountIdentifiersForTransaction": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {
          "type": "SORT_CODE",
          "identification": "401016"
        }
      }
    ],
    "accountIdentifiersForBalance": [
      {
        "accountId": "500000000000000000000001",
        "accountIdentification": {
          "type": "SORT_CODE",
          "identification": "401016"
        }
      }
    ],
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ]
  }
}

Properties

Property
Description
userUuid
string(uuid)
User for which the authorisation request was created.
applicationUserId
string
Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.
forwardParameters
[string]
Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId
string
Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.
callback
string
Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.
redirect
RedirectRequest
Optional. The server to redirect the user to after the user complete the authorisation at the Institution.
oneTimeToken
boolean
Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.
userCredentials
UserCredentials
Conditional. Used to capture the user's credentials to allow them to login to an Institution that uses the embedded account authorisation flow.

This is the first step required in the embedded account authorisation flow to authorise the Consent.
selectedScaMethod
ScaMethod
The `SCA method` selected for use.
scaCode
string
Conditional. Used to update the authorisation with the sca code received by the user from the Institution using the embedded account authorisation flow.

This is the penultimate step required in the embedded account authorisation flow to authorise the Consent. After sending the sca code, to obtain an authorised consent, the last step is to poll Get Consent until the Institution authorises the request and the Consent status transitions to AUTHORIZED.
accountRequest
AccountRequest
Conditional. Used to further specify details of the Consent to request

Conditions:
  1. Mandatory to access balance/transaction data for an Institution within the CBI Globe
  2. Mandatory to specify the individual scopes to request from the user at the Institution for an account authorisation
  3. Mandatory to specify an expiry time on the created Consent at which time will render it unusable
  4. Mandatory to specify the date range that the created Consent will be able to access transactions for (given the range is support for the Institution)

AccountIdentification

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

Mandatory. The AccountIdentification object for the user's account identifications for the account

Properties

Property
Description
Mandatory. Used to describe the format of the account.

See Account Identification Combinations for more information on when to specify each type.
identification
string
Mandatory. The value associated with the account identification type.

See Account Identification Combinations for more information on the format of the values.

AccountInfo

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

Conditional. Used to create a request for the balance of the account specified. Once the user authorises the request, only the balance can be obtained by executing GET Account Balances.

This can be specified in conjunction with accountIdentifiersForTransaction to generate a Consent that can both access the accounts balance and transactions.

Properties

Property
Description
accountId
string
Mandatory. The Institution account identifier for the account
accountIdentification
AccountIdentification
Mandatory. The AccountIdentification object for the user's account identifications for the account

AccountName

{
  "name": "string"
}

Properties

Property
Description
name
string
No description

AccountRequest

{
  "transactionFrom": "2020-01-01T00:00:00Z",
  "transactionTo": "2021-01-01T00:00:00Z",
  "expiresAt": "2025-01-01T00:00:00Z",
  "accountIdentifiers": {
    "accountId": "500000000000000000000001",
    "accountIdentification": {
      "type": "SORT_CODE",
      "identification": "401016"
    }
  },
  "accountIdentifiersForTransaction": [
    {
      "accountId": "500000000000000000000001",
      "accountIdentification": {
        "type": "SORT_CODE",
        "identification": "401016"
      }
    }
  ],
  "accountIdentifiersForBalance": [
    {
      "accountId": "500000000000000000000001",
      "accountIdentification": {
        "type": "SORT_CODE",
        "identification": "401016"
      }
    }
  ],
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ]
}

Conditional. Used to further specify details of the Consent to request

Conditions:

  1. Mandatory to access balance/transaction data for an Institution within the CBI Globe
  2. Mandatory to specify the individual scopes to request from the user at the Institution for an account authorisation
  3. Mandatory to specify an expiry time on the created Consent at which time will render it unusable
  4. Mandatory to specify the date range that the created Consent will be able to access transactions for (given the range is support for the Institution)

Properties

Property
Description
transactionFrom
string(date-time)
Optional. Used to specify the lower bound on when to pull transaction. This should be declared when accessing transaction older than 90 days for banks in the CBI Globe.
transactionTo
string(date-time)
Optional. Used to specify the upper bound on when to pull transaction
expiresAt
string(date-time)
Optional. Used to set a hard date for when the user's associated Consent will expire.

Note: If this supported by the bank, specifying this is property is opting out of having a long-lived consent that can be perpetually re-authorised by the user. This will add an expiresAt field on the Consent object which will render it unusable after this date.

Note: This is not supported by every Institution. In such case, the request will not fail but the property will be ignored and the created Consent will not have an expiry date.
accountIdentifiers
AccountInfo
Conditional. Used to create a request for the balance of the account specified. Once the user authorises the request, only the balance can be obtained by executing GET Account Balances.

This can be specified in conjunction with accountIdentifiersForTransaction to generate a Consent that can both access the accounts balance and transactions.
accountIdentifiersForTransaction
[AccountInfo]
Conditional. Used to create a request for the transactions of the account specified. Once the user authorises the request, only the transactions can be obtained by executing GET Account Transactions.

This can be specified in conjunction with accountIdentifiersForBalance to generate a Consent that can both access the accounts balance and transactions.
accountIdentifiersForBalance
[AccountInfo]
Conditional. Used to create a request for the balance of the account specified. Once the user authorises the request, only the balance can be obtained by executing GET Account Balances.

This can be specified in conjunction with accountIdentifiersForTransaction to generate a Consent that can both access the accounts balance and transactions.
featureScope
[FeatureEnum]
Optional. Used to granularly specify the set of features that the user will give their consent for when requesting access to their account information. Depending on the Institution, this may also populate a consent screen which list these scopes before the user authorises.

This endpoint accepts allow all Financial Data Features that the Institution supports.To find out which scopes an Institution supports, check GET Institution.

AccountStatement

{
  "id": "string",
  "startDateTime": "2019-08-24T14:15:22Z",
  "endDateTime": "2019-08-24T14:15:22Z",
  "creationDateTime": "2019-08-24T14:15:22Z"
}

Properties

Property
Description
id
string
No description
startDateTime
string(date-time)
No description
endDateTime
string(date-time)
No description
creationDateTime
string(date-time)
No description

AccountBalanceType

"CLOSING_AVAILABLE"

Enumerated Values

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

AccountIdentificationType

"SORT_CODE"

Mandatory. Used to describe the format of the account.

See Account Identification Combinations for more information on when to specify each type.

Enumerated Values

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

ApiResponseOfAccountStatement

{
  "meta": {
    "tracingId": "string"
  },
  "data": {
    "id": "string",
    "startDateTime": "2019-08-24T14:15:22Z",
    "endDateTime": "2019-08-24T14:15:22Z",
    "creationDateTime": "2019-08-24T14:15:22Z"
  },
  "links": {
    "property1": "string",
    "property2": "string"
  },
  "forwardedData": [
    {
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "url": "string"
    }
  ],
  "raw": [
    {
      "request": {
        "method": "string",
        "url": "string",
        "requestInstant": "2019-08-24T14:15:22Z",
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "body": {},
        "bodyParameters": {
          "property1": "string",
          "property2": "string"
        },
        "startTime": "2019-08-24T14:15:22Z",
        "startedAt": "2019-08-24T14:15:22Z"
      },
      "duration": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "resultCode": 0,
      "result": {}
    }
  ],
  "tracingId": "string"
}

Properties

Property
Description
No description
No description
links
object
No description
» additionalProperties
string
No description
forwardedData
[ResponseForwardedData]
No description
No description
tracingId
string
No description

ApiListResponseOfAccountStatement

{
  "meta": {
    "tracingId": "string",
    "count": 0,
    "pagination": {
      "totalCount": 0,
      "self": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "sort": "date",
        "offset": 0,
        "cursor": "string"
      },
      "next": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "cursor": "string"
      }
    }
  },
  "data": [
    {
      "id": "string",
      "startDateTime": "2019-08-24T14:15:22Z",
      "endDateTime": "2019-08-24T14:15:22Z",
      "creationDateTime": "2019-08-24T14:15:22Z"
    }
  ],
  "links": {
    "property1": "string",
    "property2": "string"
  },
  "forwardedData": [
    {
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "url": "string"
    }
  ],
  "raw": [
    {
      "request": {
        "method": "string",
        "url": "string",
        "requestInstant": "2019-08-24T14:15:22Z",
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "body": {},
        "bodyParameters": {
          "property1": "string",
          "property2": "string"
        },
        "startTime": "2019-08-24T14:15:22Z",
        "startedAt": "2019-08-24T14:15:22Z"
      },
      "duration": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "resultCode": 0,
      "result": {}
    }
  ],
  "paging": {
    "apiCall": {},
    "data": [
      {
        "id": "string",
        "startDateTime": "2019-08-24T14:15:22Z",
        "endDateTime": "2019-08-24T14:15:22Z",
        "creationDateTime": "2019-08-24T14:15:22Z"
      }
    ],
    "nextCursorHash": "string",
    "nextLink": "string",
    "pagingMap": {
      "property1": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "sort": "date",
        "offset": 0,
        "cursor": "string"
      },
      "property2": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "sort": "date",
        "offset": 0,
        "cursor": "string"
      }
    },
    "totalCount": 0
  },
  "tracingId": "string"
}

Properties

Property
Description
No description
No description
links
object
No description
» additionalProperties
string
No description
forwardedData
[ResponseForwardedData]
No description
No description
tracingId
string
No description

AccountType

"CASH_TRADING"

Enumerated Values

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

Address

{
  "country": "GB"
}

Conditional. The address of the Payee or Payer.

Properties

Property
Description
addressLines
[string]
Optional. The address line of the address
streetName
string
Optional. The street name of the address
buildingNumber
string
Optional. The building number of the address
postCode
string
Optional. The post code of the address
townName
string
Optional. The town name of the address
county
[string]
Optional. The list of counties for the address
country
string
Conditional. The 2-letter country code for the address.

An Institution may require you to specify the country when used in the context of the Payee to be able to make a payment
department
string
Optional. The department for the address
subDepartment
string
Optional. The sub-department for the address
addressType
AddressTypeEnum
Optional. The type of address

AddressDetails

{
  "addressLine": "string"
}

Properties

Property
Description
addressLine
string
No description

AddressTypeEnum

"BUSINESS"

Optional. The type of address

Enumerated Values

Value
BUSINESS
CORRESPONDENCE
DELIVERY_TO
MAIL_TO
PO_BOX
POSTAL
RESIDENTIAL
STATEMENT
UNKNOWN

Amount

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

Mandatory. The Amount object that contains the amount and currency of the payment.

Properties

Property
Description
amount
number
Mandatory. The monetary value
currency
string
Mandatory. The ISO 4217 currency code

ApiCall

{}

None

ApiError

{
  "code": 0,
  "institutionError": {
    "errorMessage": "string",
    "httpStatusCode": 0
  },
  "message": "string",
  "source": "string",
  "status": "string",
  "tracingId": "string"
}

Properties

Property
Description
code
integer(int32)
No description
institutionError
InstitutionError
No description
message
string
No description
source
string
No description
status
string
No description
tracingId
string
No description

ApiResponseError

{
  "error": {
    "tracingId": "74b13ce8ed51419f92c5d609e04532de",
    "code": 424,
    "institutionError": {
      "errorMessage": "{\"Code\":\"500 Internal Server Error\",\"Id\":\"5ff8d331-4282-41e0-b5ef-1ac9ac39f009\",\"Message\":\"Technical Error. Please try again later\",\"Errors\":[{\"ErrorCode\":\"UK.OBIE.UnexpectedError\",\"Message\":\"There was a problem processing your request. Please try again later\"}]}",
      "httpStatusCode": 500
    },
    "source": "INSTITUTION",
    "status": "FAILED_DEPENDENCY"
  },
  "monitoring": []
}

Used to return errors from the bank from each request

Properties

Property
Description
error
ApiError
No description
No description
No description

Application

{
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "name": "string",
  "active": true,
  "authCallbacks": [
    "string"
  ],
  "institutions": [
    {
      "id": "string",
      "name": "string",
      "fullName": "string",
      "countries": [
        {
          "displayName": "string",
          "countryCode2": "string"
        }
      ],
      "environmentType": "SANDBOX",
      "credentialsType": "OAUTH1",
      "media": [
        {
          "source": "string",
          "type": "string"
        }
      ],
      "features": [
        "INITIATE_PRE_AUTHORISATION"
      ],
      "monitoring": {
        "property1": {
          "lastTested": "2019-08-24T14:15:22Z",
          "span": "string",
          "status": "Up"
        },
        "property2": {
          "lastTested": "2019-08-24T14:15:22Z",
          "span": "string",
          "status": "Up"
        }
      }
    }
  ],
  "media": [
    {
      "source": "string",
      "type": "string"
    }
  ],
  "created": "2019-08-24T14:15:22Z",
  "updated": "2019-08-24T14:15:22Z"
}

Properties

Property
Description
uuid
string(uuid)
No description
name
string
No description
active
boolean
No description
authCallbacks
[string]
No description
institutions
[Institution]
No description
media
[Media]
Contains links to the logo and the icons for the Institution
created
string(date-time)
No description
updated
string(date-time)
No description

ApplicationUser

{
  "uuid": "095be615-a8ad-4c33-8e9c-c7612fbf6c9f",
  "applicationUuid": "97c158a3-a8ce-4cdc-9d87-535a99a52ac6",
  "applicationUserId": "string",
  "referenceId": "string",
  "institutionConsents": [
    {
      "institutionId": "string"
    }
  ]
}

Properties

Property
Description
uuid
string(uuid)
No description
applicationUuid
string(uuid)
No description
applicationUserId
string
No description
referenceId
string
No description
institutionConsents
[InstitutionConsent]
No description

EmbeddedAccountAuthorisationResponse

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "userUuid": "dcbf2986-7a6c-4291-9074-6441a23e4826",
  "applicationUserId": "string",
  "referenceId": "string",
  "institutionId": "string",
  "status": "AWAITING_AUTHORIZATION",
  "createdAt": "2019-08-24T14:15:22Z",
  "transactionFrom": "2019-08-24T14:15:22Z",
  "transactionTo": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z",
  "timeToExpireInMillis": 0,
  "timeToExpire": "string",
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "consentToken": "string",
  "state": "string",
  "authorizedAt": "2019-08-24T14:15:22Z",
  "institutionConsentId": "string",
  "authorisationUrl": "string",
  "qrCodeUrl": "string",
  "scaMethods": [
    {
      "id": "944",
      "type": "PUSH_OTP",
      "description": "SecureSIGN"
    }
  ],
  "selectedScaMethod": {
    "id": "944",
    "type": "PUSH_OTP",
    "description": "SecureSIGN"
  }
}

Properties

Property
Description
id
string(uuid)
No description
userUuid
string(uuid)
No description
applicationUserId
string
No description
referenceId
string
No description
institutionId
string
No description
No description
createdAt
string(date-time)
No description
transactionFrom
string(date-time)
No description
transactionTo
string(date-time)
No description
expiresAt
string(date-time)
No description
timeToExpireInMillis
integer(int64)
No description
timeToExpire
string(iso8601)
No description
featureScope
[FeatureEnum]
Used to describe what functions are supported by the associated Institution.

For more information on each feature, see the following links:
consentToken
string
No description
state
string
No description
authorizedAt
string(date-time)
No description
institutionConsentId
string
No description
authorisationUrl
string
No description
qrCodeUrl
string
No description
scaMethods
[ScaMethod]
Conditional. Used to update the authorisation with the sca method of the user's choice for the Institution that uses the embedded authorisation flow. If the user has multiple sca methods configured, the Institution will allow the user to select from each of these options.

When the user has multiple sca methods for the Institution, this is the second step required in the embedded authorisation flow to authorise the Consent.
selectedScaMethod
ScaMethod
Conditional. Used to update the authorisation with the sca method of the user's choice for the Institution that uses the embedded authorisation flow. If the user has multiple sca methods configured, the Institution will allow the user to select from each of these options.

When the user has multiple sca methods for the Institution, this is the second step required in the embedded authorisation flow to authorise the Consent.

ApiResponseOfEmbeddedAccountAuthorisationResponse

{
  "meta": {
    "tracingId": "string"
  },
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "userUuid": "dcbf2986-7a6c-4291-9074-6441a23e4826",
    "applicationUserId": "string",
    "referenceId": "string",
    "institutionId": "string",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2019-08-24T14:15:22Z",
    "transactionFrom": "2019-08-24T14:15:22Z",
    "transactionTo": "2019-08-24T14:15:22Z",
    "expiresAt": "2019-08-24T14:15:22Z",
    "timeToExpireInMillis": 0,
    "timeToExpire": "string",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "consentToken": "string",
    "state": "string",
    "authorizedAt": "2019-08-24T14:15:22Z",
    "institutionConsentId": "string",
    "authorisationUrl": "string",
    "qrCodeUrl": "string",
    "scaMethods": [
      {
        "id": "944",
        "type": "PUSH_OTP",
        "description": "SecureSIGN"
      }
    ],
    "selectedScaMethod": {
      "id": "944",
      "type": "PUSH_OTP",
      "description": "SecureSIGN"
    }
  },
  "links": {
    "property1": "string",
    "property2": "string"
  },
  "forwardedData": [
    {
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "url": "string"
    }
  ],
  "raw": [
    {
      "request": {
        "method": "string",
        "url": "string",
        "requestInstant": "2019-08-24T14:15:22Z",
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "body": {},
        "bodyParameters": {
          "property1": "string",
          "property2": "string"
        },
        "startTime": "2019-08-24T14:15:22Z",
        "startedAt": "2019-08-24T14:15:22Z"
      },
      "duration": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "resultCode": 0,
      "result": {}
    }
  ],
  "tracingId": "string"
}

Properties

Property
Description
No description
links
object
No description
» additionalProperties
string
No description
forwardedData
[ResponseForwardedData]
No description
No description
tracingId
string
No description

AccountAuthorisationResponse

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "userUuid": "dcbf2986-7a6c-4291-9074-6441a23e4826",
  "applicationUserId": "string",
  "referenceId": "string",
  "institutionId": "string",
  "status": "AWAITING_AUTHORIZATION",
  "createdAt": "2019-08-24T14:15:22Z",
  "transactionFrom": "2019-08-24T14:15:22Z",
  "transactionTo": "2019-08-24T14:15:22Z",
  "expiresAt": "2019-08-24T14:15:22Z",
  "timeToExpireInMillis": 0,
  "timeToExpire": "string",
  "featureScope": [
    "INITIATE_PRE_AUTHORISATION"
  ],
  "consentToken": "string",
  "state": "string",
  "authorizedAt": "2019-08-24T14:15:22Z",
  "institutionConsentId": "string",
  "authorisationUrl": "string",
  "qrCodeUrl": "string"
}

Properties

Property
Description
id
string(uuid)
No description
userUuid
string(uuid)
No description
applicationUserId
string
No description
referenceId
string
No description
institutionId
string
No description
No description
createdAt
string(date-time)
No description
transactionFrom
string(date-time)
No description
transactionTo
string(date-time)
No description
expiresAt
string(date-time)
No description
timeToExpireInMillis
integer(int64)
No description
timeToExpire
string(iso8601)
No description
featureScope
[FeatureEnum]
Used to describe what functions are supported by the associated Institution.

For more information on each feature, see the following links:
consentToken
string
No description
state
string
No description
authorizedAt
string(date-time)
No description
institutionConsentId
string
No description
authorisationUrl
string
No description
qrCodeUrl
string
No description

AuthorisationStatus

"AWAITING_AUTHORIZATION"

Enumerated Values

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

ApiResponseOfAccountAuthorisationResponse

{
  "meta": {
    "tracingId": "string"
  },
  "data": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "userUuid": "dcbf2986-7a6c-4291-9074-6441a23e4826",
    "applicationUserId": "string",
    "referenceId": "string",
    "institutionId": "string",
    "status": "AWAITING_AUTHORIZATION",
    "createdAt": "2019-08-24T14:15:22Z",
    "transactionFrom": "2019-08-24T14:15:22Z",
    "transactionTo": "2019-08-24T14:15:22Z",
    "expiresAt": "2019-08-24T14:15:22Z",
    "timeToExpireInMillis": 0,
    "timeToExpire": "string",
    "featureScope": [
      "INITIATE_PRE_AUTHORISATION"
    ],
    "consentToken": "string",
    "state": "string",
    "authorizedAt": "2019-08-24T14:15:22Z",
    "institutionConsentId": "string",
    "authorisationUrl": "string",
    "qrCodeUrl": "string"
  },
  "links": {
    "property1": "string",
    "property2": "string"
  },
  "forwardedData": [
    {
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "url": "string"
    }
  ],
  "raw": [
    {
      "request": {
        "method": "string",
        "url": "string",
        "requestInstant": "2019-08-24T14:15:22Z",
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "body": {},
        "bodyParameters": {
          "property1": "string",
          "property2": "string"
        },
        "startTime": "2019-08-24T14:15:22Z",
        "startedAt": "2019-08-24T14:15:22Z"
      },
      "duration": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "resultCode": 0,
      "result": {}
    }
  ],
  "tracingId": "string"
}

Properties

Property
Description
No description
No description
links
object
No description
» additionalProperties
string
No description
forwardedData
[ResponseForwardedData]
No description
No description
tracingId
string
No description

TransactionBalance

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

Properties

Property
Description
No description
balanceAmount
Amount
Mandatory. The Amount object that contains the amount and currency of the payment.

Balances

{
  "mainBalanceAmount": {
    "amount": 10,
    "currency": "GBP"
  },
  "balances": [
    {
      "type": "CLOSING_AVAILABLE",
      "dateTime": "2019-08-24T14:15:22Z",
      "balanceAmount": {
        "amount": 10,
        "currency": "GBP"
      },
      "creditLineIncluded": true,
      "creditLines": [
        {
          "type": "AVAILABLE",
          "creditLineAmount": {
            "amount": null,
            "currency": null
          }
        }
      ]
    }
  ]
}

Properties

Property
Description
mainBalanceAmount
Amount
Mandatory. The Amount object that contains the amount and currency of the payment.
balances
[AccountBalance]
No description

ApiResponseOfBalances

{
  "meta": {
    "tracingId": "string"
  },
  "data": {
    "mainBalanceAmount": {
      "amount": 10,
      "currency": "GBP"
    },
    "balances": [
      {
        "type": "CLOSING_AVAILABLE",
        "dateTime": "2019-08-24T14:15:22Z",
        "balanceAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "creditLineIncluded": true,
        "creditLines": [
          {
            "type": null,
            "creditLineAmount": null
          }
        ]
      }
    ]
  },
  "links": {
    "property1": "string",
    "property2": "string"
  },
  "forwardedData": [
    {
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "url": "string"
    }
  ],
  "raw": [
    {
      "request": {
        "method": "string",
        "url": "string",
        "requestInstant": "2019-08-24T14:15:22Z",
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "body": {},
        "bodyParameters": {
          "property1": "string",
          "property2": "string"
        },
        "startTime": "2019-08-24T14:15:22Z",
        "startedAt": "2019-08-24T14:15:22Z"
      },
      "duration": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "resultCode": 0,
      "result": {}
    }
  ],
  "tracingId": "string"
}

Properties

Property
Description
No description
data
Balances
No description
links
object
No description
» additionalProperties
string
No description
forwardedData
[ResponseForwardedData]
No description
No description
tracingId
string
No description

Beneficiary

{
  "id": "string",
  "reference": "string",
  "payee": {
    "name": "Jane Doe",
    "accountIdentifications": [
      {
        "identification": "401016",
        "type": "SORT_CODE"
      },
      {
        "identification": "71518920",
        "type": "ACCOUNT_NUMBER"
      }
    ],
    "address": {
      "country": "GB"
    }
  },
  "trusted": true
}

Properties

Property
Description
id
string
No description
reference
string
No description
Mandatory. The BeneficiaryPayee 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.
trusted
boolean
No description

BeneficiaryPayee

{
  "name": "Jane Doe",
  "accountIdentifications": [
    {
      "identification": "401016",
      "type": "SORT_CODE"
    },
    {
      "identification": "71518920",
      "type": "ACCOUNT_NUMBER"
    }
  ],
  "address": {
    "country": "GB"
  }
}

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

Properties

Property
Description
name
string
The account holder name of the beneficiary.
accountIdentifications
[AccountIdentification]
Mandatory. The account identifications that identify the BeneficiaryPayee bank account.
address
Address
Conditional. The address of the Payee or Payer.
  • payee.address is mandatory when the paymentType is an INTERNATIONAL payment
  • An Institution may require you to specify the country when used in the context ofthe Payee to be able to make a payment.

ApiListResponseOfBeneficiary

{
  "meta": {
    "tracingId": "string",
    "count": 0,
    "pagination": {
      "totalCount": 0,
      "self": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "sort": "date",
        "offset": 0,
        "cursor": "string"
      },
      "next": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "cursor": "string"
      }
    }
  },
  "data": [
    {
      "id": "string",
      "reference": "string",
      "payee": {
        "name": "Jane Doe",
        "accountIdentifications": [
          {
            "identification": "401016",
            "type": "SORT_CODE"
          },
          {
            "identification": "71518920",
            "type": "ACCOUNT_NUMBER"
          }
        ],
        "address": {
          "country": "GB"
        }
      },
      "trusted": true
    }
  ],
  "links": {
    "property1": "string",
    "property2": "string"
  },
  "forwardedData": [
    {
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "url": "string"
    }
  ],
  "raw": [
    {
      "request": {
        "method": "string",
        "url": "string",
        "requestInstant": "2019-08-24T14:15:22Z",
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "body": {},
        "bodyParameters": {
          "property1": "string",
          "property2": "string"
        },
        "startTime": "2019-08-24T14:15:22Z",
        "startedAt": "2019-08-24T14:15:22Z"
      },
      "duration": "string",
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "resultCode": 0,
      "result": {}
    }
  ],
  "tracingId": "string"
}

Properties

Property
Description
No description
data
[Beneficiary]
No description
links
object
No description
» additionalProperties
string
No description
forwardedData
[ResponseForwardedData]
No description
No description
tracingId
string
No description

BulkPaymentAuthorisationRequest

{
  "userUuid": "e006a012-c306-4355-a6a1-99bf69ae5171",
  "applicationUserId": "user-234562290",
  "forwardParameters": [
    "string"
  ],
  "institutionId": "yapily-mock",
  "callback": "https://display-parameters.com",
  "redirect": {
    "url": "string"
  },
  "oneTimeToken": false,
  "paymentRequest": {
    "payments": [
      {
        "paymentIdempotencyId": "04ab4536gaerfc0e1f93c4f4",
        "payer": {
          "name": "John Doe",
          "accountIdentifications": [
            null
          ],
          "address": "[Object]"
        },
        "reference": "Bill payment",
        "contextType": "OTHER",
        "type": "DOMESTIC_PAYMENT",
        "payee": {
          "name": "Jane Doe",
          "accountIdentifications": "[Object]",
          "address": "[Object]",
          "merchantId": "24589303",
          "merchantCategoryCode": "5551"
        },
        "periodicPayment": {
          "frequency": {},
          "numberOfPayments": 5,
          "nextPaymentDateTime": "2018-01-10T00:00:00Z",
          "nextPaymentAmount": {},
          "finalPaymentDateTime": "2030-01-10T00:00:00Z",
          "finalPaymentAmount": {}
        },
        "internationalPayment": {
          "currencyOfTransfer": "string",
          "exchangeRateInformation": {},
          "purpose": "string",
          "priority": "[",
          "chargeBearer": "["
        },
        "amount": {
          "amount": 10,
          "currency": "GBP"
        },
        "paymentDateTime": "2021-07-21T17:32:28Z",
        "readRefundAccount": false
      }
    ],
    "originatorIdentificationNumber": "string",
    "executionDateTime": "2019-08-24T14:15:22Z"
  }
}

Properties

Property
Description
userUuid
string(uuid)
Conditional. The reference to the User that will authorise the authorisation request using the Yapily generated UUID. Either the userUuid or applicationUserId must be provided.
applicationUserId
string
Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.
forwardParameters
[string]
Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId
string
Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.
callback
string
Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.
redirect
RedirectRequest
Optional. The server to redirect the user to after the user complete the authorisation at the Institution.
oneTimeToken
boolean
Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.
paymentRequest
BulkPaymentRequest
The payment request object defining the details of the bulk payment

BulkPaymentEmbeddedAuthorisationRequest

{
  "userUuid": "e006a012-c306-4355-a6a1-99bf69ae5171",
  "applicationUserId": "user-234562290",
  "institutionId": "yapily-mock",
  "callback": "https://display-parameters.com",
  "redirect": {
    "url": "string"
  },
  "oneTimeToken": false,
  "paymentRequest": {
    "payments": [
      {
        "paymentIdempotencyId": "04ab4536gaerfc0e1f93c4f4",
        "payer": {
          "name": "John Doe",
          "accountIdentifications": [
            null
          ],
          "address": "[Object]"
        },
        "reference": "Bill payment",
        "contextType": "OTHER",
        "type": "DOMESTIC_PAYMENT",
        "payee": {
          "name": "Jane Doe",
          "accountIdentifications": "[Object]",
          "address": "[Object]",
          "merchantId": "24589303",
          "merchantCategoryCode": "5551"
        },
        "periodicPayment": {
          "frequency": {},
          "numberOfPayments": 5,
          "nextPaymentDateTime": "2018-01-10T00:00:00Z",
          "nextPaymentAmount": {},
          "finalPaymentDateTime": "2030-01-10T00:00:00Z",
          "finalPaymentAmount": {}
        },
        "internationalPayment": {
          "currencyOfTransfer": "string",
          "exchangeRateInformation": {},
          "purpose": "string",
          "priority": "[",
          "chargeBearer": "["
        },
        "amount": {
          "amount": 10,
          "currency": "GBP"
        },
        "paymentDateTime": "2021-07-21T17:32:28Z",
        "readRefundAccount": false
      }
    ],
    "originatorIdentificationNumber": "string",
    "executionDateTime": "2019-08-24T14:15:22Z"
  },
  "userCredentials": {
    "id": "6154057725",
    "corporateId": "6345898763",
    "password": "PISPWD12"
  },
  "selectedScaMethod": {
    "id": "944",
    "type": "PUSH_OTP",
    "description": "SecureSIGN"
  },
  "scaCode": "325614"
}

The request body containing a BulkPaymentEmbeddedAuthorisationRequest json payload

Properties

Property
Description
userUuid
string(uuid)
Conditional. The reference to the User that will authorise the authorisation request using the Yapily generated UUID. Either the userUuid or applicationUserId must be provided.
applicationUserId
string
Conditional. The user-friendly reference to the User that will authorise the authorisation request. If a User with the specified applicationUserId exists, it will be used otherwise, a new User with the specified applicationUserId will be created and used. Either the userUuid or applicationUserId must be provided.
institutionId
string
Mandatory. The reference to the Institution which identifies which institution the authorisation request is sent to.
callback
string
Optional. The server to redirect the user to after the user complete the authorisation at the Institution.

See Using a callback (Optional) for more information.
redirect
RedirectRequest
Optional. The server to redirect the user to after the user complete the authorisation at the Institution.
oneTimeToken
boolean
Conditional. Used to receive a oneTimeToken rather than a consentToken at the callback for additional security. This can only be used when the callback is set.

See Using a callback with an OTT (Optional) for more information.
paymentRequest
BulkPaymentRequest
The payment request object defining the details of the bulk payment
userCredentials
UserCredentials
Conditional. Used to capture the user's credentials to allow them to login to an Institution that uses the embedded account authorisation flow.

This is the first step required in the embedded account authorisation flow to authorise the Consent.
selectedScaMethod
ScaMethod
Conditional. Used to update the authorisation with the sca method of the user's choice for the Institution that uses the embedded authorisation flow. If the user has multiple sca methods configured, the Institution will allow the user to select from each of these options.

When the user has multiple sca methods for the Institution, this is the second step required in the embedded authorisation flow to authorise the Consent.
scaCode
string
Conditional. Used to update the authorisation with the sca code received by the user from the Institution using the embedded payment authorisation flow.

This is the penultimate step required in the embedded payment authorisation flow to authorise the Consent. After sending the sca code, to obtain an authorised consent, the last step is to poll Get Consent until the Institution authorises the request and the Consent status transitions to AUTHORIZED.

BulkPaymentRequest

{
  "payments": [
    {
      "paymentIdempotencyId": "04ab4536gaerfc0e1f93c4f4",
      "payer": {
        "name": "John Doe",
        "accountIdentifications": [
          {
            "type": null,
            "identification": null
          }
        ],
        "address": {
          "country": "GB"
        }
      },
      "reference": "Bill payment",
      "contextType": "OTHER",
      "type": "DOMESTIC_PAYMENT",
      "payee": {
        "name": "Jane Doe",
        "accountIdentifications": [
          {
            "identification": "401016",
            "type": "SORT_CODE"
          },
          {
            "identification": "71518920",
            "type": "ACCOUNT_NUMBER"
          }
        ],
        "address": {
          "country": "GB"
        },
        "merchantId": "24589303",
        "merchantCategoryCode": "5551"
      },
      "periodicPayment": {
        "frequency": {
          "type": "[",
          "intervalWeek": 1,
          "intervalMonth": 1,
          "executionDay": 1
        },
        "numberOfPayments": 5,
        "nextPaymentDateTime": "2018-01-10T00:00:00Z",
        "nextPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        },
        "finalPaymentDateTime": "2030-01-10T00:00:00Z",
        "finalPaymentAmount": {
          "amount": 10,
          "currency": "GBP"
        }
      },
      "internationalPayment": {
        "currencyOfTransfer": "string",
        "exchangeRateInformation": {
          "unitCurrency": "string",
          "rate": 0,
          "rateType": "[",
          "foreignExchangeContractReference": "string"
        },
        "purpose": "string",
        "priority": "NORMAL",
        "chargeBearer": "DEBT"
      },
      "amount": {
        "amount": 10,
        "currency": "GBP"
      },
      "paymentDateTime": "2021-07-21T17:32:28Z",
      "readRefundAccount": false
    }
  ],
  "originatorIdentificationNumber": "string",
  "executionDateTime": "2019-08-24T14:15:22Z"
}

The payment request object defining the details of the bulk payment

Properties

Property
Description
payments
[PaymentRequest]
Mandatory. The array of PaymentRequest objects to initiate in the bulk payment.
originatorIdentificationNumber
string
Conditional. The identification number of the originator.
  • Mandatory for AIB bulk payments
executionDateTime
string(date-time)
Optional. Used to schedule the bulk payment to be executed at a future date if supported by the Institution.

Categorisation

{
  "categories": [
    "string"
  ],
  "source": "string"
}

Properties

Property
Description
categories
[string]
No description
source
string
No description

Category

{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "label": "string",
  "country": "string",
  "subcategories": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "label": "string"
    }
  ]
}

Properties

Property
Description
id
string(uuid)
No description
label
string
No description
country
string
No description
subcategories
[Subcategory]
No description

ApiListResponseOfCategory

{
  "meta": {
    "tracingId": "string",
    "count": 0,
    "pagination": {
      "totalCount": 0,
      "self": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "sort": "date",
        "offset": 0,
        "cursor": "string"
      },
      "next": {
        "from": "2019-08-24T14:15:22Z",
        "before": "2019-08-24T14:15:22Z",
        "limit": 0,
        "cursor": "string"
      }
    }
  },
  "data": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "label": "string",
      "country": "string",
      "subcategories": [
        {
          "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
          "label": "string"
        }
      ]
    }
  ],
  "links": {
    "property1": "string",
    "property2": "string"
  },
  "forwardedData": [
    {
      "headers": {
        "property1": "string",
        "property2": "string"
      },
      "url": "string"
    }
  ],
  "raw": [
    {
      "request": {
        "method": "string",
        "url": "string",
        "requestInstant": "2019-08-24T14:15:22Z",
        "headers": {
          "property1": "string",
          "property2": "string"
        },
        "body": {},
        "bodyParameters": {
          "property1": "string",