Yapily API (2.31.2)

Download OpenAPI specification:Download

Yapily Support: support@yapily.com URL: https://docs.yapily.com/pages/resources/support/

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

basicAuth

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

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.

HTTP Basic Authentication credentials are generated by concatenating APPLICATION_KEY and APPLICATION_SECRET separated with a colon and encoded with base64 to form the authToken, as follows:

authToken = Base64 encoded(APPLICATION_KEY + ':' + APPLICATION_SECRET).

Security Scheme Type	HTTP
HTTP Authorization Scheme	basic

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

Get the information about the institutions configured in your application

Request

Security:

basicAuth

Responses

200

default

Error Response

get/me

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  https://api.yapily.com/me

Response samples

200
default

application/json;charset=UTF-8

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

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

Get all the users configured in your application

Request

Security:

basicAuth

query Parameters

filter[applicationUserId]

Array of strings unique

Optional. Filter records based on the list of applicationUserId users provided.

Responses

200

default

Error Response

get/users

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/users?filter%5BapplicationUserId%5D=string'

Response samples

200
default

application/json;charset=UTF-8

Example Response

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

Create User

Create a new user in your application

Request

Security:

basicAuth

Request Body schema: application/json;charset=UTF-8

applicationUserId	string Optional. The unique identifier of the `Application User` assigned by the Application Owner.
referenceId	string Deprecated. A non-unique reference Id for the `Application User`.

Responses

201

Created

default

Error Response

post/users

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create User Example Request

{"applicationUserId": "string"
}

Response samples

201
default

application/json;charset=UTF-8

Example Response

{"uuid": "1ec8e814-085e-46ad-a303-3fe11808f67e",
"applicationUuid": "50935110-c7df-4003-a06a-1cc5fd4643c9",
"applicationUserId": "string",
"createdAt": "2022-10-17T08:51:02.463Z",
"institutionConsents": [ ]
}

Delete User

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

Request

Security:

basicAuth

path Parameters

userUuid

required

string <uuid>

Mandatory. The Yapily generated UUID for the user.

Responses

200

default

Error Response

delete/users/{userUuid}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api.yapily.com/users/{userUuid}'

Response samples

200
default

application/json;charset=UTF-8

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"
}
]
}
}

Get User

Get a specific user using the user UUID

Request

Security:

basicAuth

path Parameters

userUuid

required

string <uuid>

Mandatory. The Yapily generated UUID for the user.

Responses

200

default

Error Response

get/users/{userUuid}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/users/{userUuid}'

Response samples

200
default

application/json;charset=UTF-8

Example Response

{"uuid": "3b908179-6faa-42e1-8129-8fd0ff1fc68f",
"applicationUuid": "3020bf54-e254-40ba-ba7b-fc959774486a",
"applicationUserId": "string",
"createdAt": "2022-10-17T08:51:02.463Z",
"institutionConsents": [{"institutionId": "modelo-sandbox"
}
]
}

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:

Traditional banks e.g. Santander
Neo-banks e.g. Monzo
Building societies e.g. Cumberland Building Society

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.

Request

Security:

basicAuth

Responses

200

default

Error Response

get/features

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  https://api.yapily.com/features

Response samples

200
default

application/json;charset=UTF-8

Example Response

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

Get Institutions

Used to retrieve all Institutions within an application

Request

Security:

basicAuth

Responses

200

default

Error Response

get/institutions

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  https://api.yapily.com/institutions

Response samples

200
default

application/json;charset=UTF-8

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"
]
}
]
}

Get Institution

Used to retrieves details of a specific Institution within an application

Request

Security:

basicAuth

path Parameters

institutionId

required

string

Mandatory. The Yapily institution Id for the Institution.

Responses

200

default

Error Response

get/institutions/{institutionId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/institutions/{institutionId}'

Response samples

200
default

application/json;charset=UTF-8

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"
]
}

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

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.

Request

Security:

basicAuth

Request Body schema: application/json

authCode required	string Mandatory. The authorisation code
authState required	string Mandatory. The authorisation state

Responses

201

Created

default

Error Response

post/consent-auth-code

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

{"authCode": "6b965fbb-ff09-4afa-b897-90c34797cb8f",
"authState": "1270cb2ffc4842b78953afa2228e0a87"
}

Response samples

201
default

application/json;charset=UTF-8

Example Response

{"id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
"userUuid": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
"applicationUserId": "string",
"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"
}

Exchange One Time Token

Exchange a One-time-token for the consent token

Request

Security:

basicAuth

Request Body schema: application/json

oneTimeToken

required

string

Mandatory. The one time token to exchange for a consent token.

Responses

201

Created

default

Error Response

post/consent-one-time-token

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

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

Response samples

201
default

application/json;charset=UTF-8

Example Response

{"id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
"userUuid": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
"applicationUserId": "string",
"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"
}

Get Consents

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

Request

Security:

basicAuth

query Parameters

filter[applicationUserId]	Array of strings unique Optional. Filter records based on the list of `applicationUserId` users provided.
filter[userUuid]	Array of strings <uuid> unique Optional. Filter records based on the list of `userUuid` users provided.
filter[institution]	Array of strings unique Optional. Filter records based on the list of `Institution` provided.
filter[status]	Array of strings unique 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 1 and 1000.
offset	integer <int32> Default: 0 Optional. The number of transaction records to be skipped. Used primarily with paginated results.

Responses

200

default

Error Response

get/consents

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/consents?filter%5BapplicationUserId%5D=string&filter%5BuserUuid%5D=497f6eca-6276-4993-bfeb-53cbbbba6f08&filter%5Binstitution%5D=string&filter%5Bstatus%5D=string&from=string&before=string&limit=0&offset=0'

Response samples

200
default

application/json;charset=UTF-8

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": "string",
"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"
}
]
}

Delete Consent

Delete a consent using the consent Id

Request

Security:

basicAuth

path Parameters

consentId

required

string <uuid>

Mandatory. The consent Id of the Consent to update.

query Parameters

forceDelete

boolean

Default: true

Optional. Whether to force the deletion.

Responses

200

default

Error Response

delete/consents/{consentId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api.yapily.com/consents/{consentId}?forceDelete=true'

Response samples

200
default

application/json;charset=UTF-8

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

Get Consent

Get consent using the consent Id

Request

Security:

basicAuth

path Parameters

consentId

required

string <uuid>

Mandatory. The consent Id of the Consent to update.

Responses

200

default

Error Response

get/consents/{consentId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/consents/{consentId}'

Response samples

200
default

application/json;charset=UTF-8

Example Response

{"meta": {"tracingId": "679e7bb6cd45416a9a9a8d004c5315da"
},
"data": {"id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
"userUuid": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
"applicationUserId": "string",
"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",
"lastConfirmedAt": "2021-07-08T10:59:53.288Z",
"reconfirmBy": "2021-10-06T10:59:53.288Z",
"institutionConsentId": "aac-605d48f2-2a0e-4594-81a9-996524fa3b2a"
}
}

Extend Consentbeta

Used to indicate to Yapily that reconfirmation has occurred for a given Consent, and to update lastUpdatedAt and reconfirmBy for that Consent. Returns the Consent.

Request

Security:

basicAuth

path Parameters

consentId

required

string <uuid>

Mandatory. The consent Id of the Consent to update.

Request Body schema: application/json;charset=UTF-8

lastConfirmedAt

required

string <date-time>

Mandatory. The time that the user confirmed access to their account information

Responses

200

Created

400

Error Response. The supplied lastConfirmedAt date, Consent type, or Consent status is invalid.

default

Error Response

post/consents/{consentId}/extend

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Extend Consent Example Request

{"lastConfirmedAt": "2021-07-08T10:59:53.288Z"
}

Response samples

200
400
default

application/json;charset=UTF-8

Example Response

{"meta": {"tracingId": "679e7bb6cd45416a9a9a8d004c5315da"
},
"data": {"id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
"userUuid": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
"applicationUserId": "string",
"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",
"lastConfirmedAt": "2021-07-08T10:59:53.288Z",
"reconfirmBy": "2021-10-06T10:59:53.288Z",
"institutionConsentId": "aac-605d48f2-2a0e-4594-81a9-996524fa3b2a"
}
}

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.

Re-authorise Account Consent

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.

Request

Security:

basicAuth

query Parameters

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

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
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.

Responses

201

Created

default

Error Response

patch/account-auth-requests

Request samples

curl
JavaScript
Node.js
Python

curl -i -X PATCH \
  -u <username>:<password> \
  'https://api.yapily.com/account-auth-requests?raw=true' \
  -H 'consent: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-id: string' \
  -H 'psu-ip-address: string'

Response samples

201
default

application/json;charset=UTF-8

OBIE Example Response

{"meta": {"tracingId": "8719f9c97272463d9c2d1ee6108c8e24"
},
"data": {"id": "2812b61c-9d0b-4730-8c94-22c18918e66a",
"userUuid": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"applicationUserId": "string",
"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"
}
}

Create Account Authorisation

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

See Redirect Account Flows for more information about this flow.

Feature: INITIATE_ACCOUNT_REQUEST

Request

Security:

basicAuth

query Parameters

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

header Parameters

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.

Request Body schema: application/json;charset=UTF-8

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	Array of strings Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId required	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.
	object (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.
	object (AccountRequest) Conditional. Used to further specify details of the `Consent` to request Conditions: Mandatory to specify the individual scopes to request from the user at the `Institution` for an account authorisation Mandatory to specify an expiry time on the created `Consent` at which time will render it unusable 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`)

Responses

201

Created

default

Error Response

post/account-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

OBIE Example Request

{"applicationUserId": "string",
"institutionId": "modelo-sandbox",
"callback": "https://display-parameters.com/"
}

Response samples

201
default

application/json;charset=UTF-8

OBIE Example Response

{"meta": {"tracingId": "3b262569303f47f188d16b43acd552c0"
},
"data": {"id": "2d5c3632-1729-4a5e-bc69-c7fa1cbba815",
"userUuid": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"applicationUserId": "string",
"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"
}
}

Update Account Pre-authorisation

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:

INITIATE_ACCOUNT_REQUEST
INITIATE_PRE_AUTHORISATION

Request

Security:

basicAuth

query Parameters

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

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
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.

Request Body schema: application/json;charset=UTF-8

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	Array of strings Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId required	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.
	object (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.
	object (AccountRequest) Conditional. Used to further specify details of the `Consent` to request Conditions: Mandatory to specify the individual scopes to request from the user at the `Institution` for an account authorisation Mandatory to specify an expiry time on the created `Consent` at which time will render it unusable 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`)

Responses

200

default

Error Response

put/account-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Berlin Group Example Request

{"applicationUserId": "string",
"institutionId": "n26"
}

Response samples

200
default

application/json;charset=UTF-8

OBIE Example Response

{"meta": {"tracingId": "ee8e5bcfedf348b18ae45a34135790cc"
},
"data": {"id": "68e14e00-38b0-467d-a999-f70340e467b3",
"userUuid": "e2578545-27a4-4edf-983f-5d33c2d7b559",
"applicationUserId": "string",
"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"
]
}
}

Create Bulk Payment Authorisation

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

See Redirect Payment Flows for more information about this flow.

Feature: INITIATE_BULK_PAYMENT

Request

Security:

basicAuth

query Parameters

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

header Parameters

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.

Request Body schema: application/json;charset=UTF-8

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	Array of strings Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId required	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.
	object (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.
	object (BulkPaymentRequest) The payment request object defining the details of the bulk payment

Responses

201

Created

default

Error Response

post/bulk-payment-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

UK Bulk Payment Example Request

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

Response samples

201
default

application/json;charset=UTF-8

UK Bulk Payment Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "a2a9ec77-a479-4996-9896-4568e1968e7a",
"userUuid": "5350782b-60f3-489e-aae5-a24d8d679a07",
"applicationUserId": "string",
"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"
}
}

Create Embedded Account Authorisation

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

Request

Security:

basicAuth

query Parameters

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

header Parameters

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.

Request Body schema: application/json;charset=UTF-8

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	Array of strings Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId required	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.
	object (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.
	object (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`.
	object (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 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`.
	object (AccountRequest) Conditional. Used to further specify details of the `Consent` to request Conditions: Mandatory to specify the individual scopes to request from the user at the `Institution` for an account authorisation Mandatory to specify an expiry time on the created `Consent` at which time will render it unusable 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`)

Responses

201

Created

default

Error Response

post/embedded-account-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Berlin Group Example Request

{"applicationUserId": "string",
"institutionId": "fiducia-sandbox",
"userCredentials": {"id": "6154057725",
"password": "PISPWD12"
}
}

Response samples

201
default

application/json;charset=UTF-8

Berlin Group (Multiple SCA Methods) Example Response

{"meta": {"tracingId": "a9d8d8c5e6a84b00b8510d90c28cbbc6"
},
"data": {"id": "149da283-2958-4128-9d72-e3a02e8bb83d",
"userUuid": "6b082877-b137-4743-bba3-07b6a8148b42",
"applicationUserId": "string",
"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"
}
]
}
}

Update Embedded Account Authorisation

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

Request

Security:

basicAuth

path Parameters

consentId

required

string

Mandatory. The consent Id of the Consent to update.

query Parameters

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

header Parameters

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.

Request Body schema: application/json;charset=UTF-8

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	Array of strings Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId required	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.
	object (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.
	object (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`.
	object (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 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`.
	object (AccountRequest) Conditional. Used to further specify details of the `Consent` to request Conditions: Mandatory to specify the individual scopes to request from the user at the `Institution` for an account authorisation Mandatory to specify an expiry time on the created `Consent` at which time will render it unusable 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`)

Responses

201

Created

default

Error Response

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

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Berlin Group (SCA Code) Example Request

{"applicationUserId": "string",
"institutionId": "fiducia-sandbox",
"scaCode": "6154057725"
}

Response samples

201
default

application/json;charset=UTF-8

Berlin Group (SCA Code) Example Response

{"meta": {"tracingId": "0ad7c46c4e4445bab3a0d4ccae25556b"
},
"data": {"id": "66c8c0f2-1678-4404-a68f-2236a1afcdad",
"userUuid": "6b082877-b137-4743-bba3-07b6a8148b42",
"applicationUserId": "string",
"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"
}
}

Create Embedded Bulk Payment Authorisation

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

Request

Security:

basicAuth

query Parameters

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

header Parameters

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.

Request Body schema: application/json;charset=UTF-8

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 required	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.
	object (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.
	object (BulkPaymentRequest) The payment request object defining the details of the bulk payment
	object (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`.
	object (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`.

Responses

201

Created

default

Error Response

post/embedded-bulk-payment-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Berlin Group EUR Embedded Bulk Payment Example Request

{"applicationUserId": "string",
"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"
}
]
}
}
]
}
}

Response samples

201
default

application/json;charset=UTF-8

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": "string",
"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"
}
}
}

Update Embedded Bulk Payment Authorisation

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

Request

Security:

basicAuth

path Parameters

consentId

required

string

Mandatory. The consent Id of the Consent to update.

query Parameters

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

header Parameters

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.

Request Body schema: application/json;charset=UTF-8

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 required	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.
	object (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.
	object (BulkPaymentRequest) The payment request object defining the details of the bulk payment
	object (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`.
	object (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`.

Responses

200

default

Error Response

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

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

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

{"applicationUserId": "string",
"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"
}
]
}
}
]
}
}

Response samples

200
default

application/json;charset=UTF-8

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": "string",
"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"
}
}

Create Embedded Payment Authorisation

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

Request

Security:

basicAuth

query Parameters

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

header Parameters

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.

Request Body schema: application/json;charset=UTF-8

userUuid	string <uuid>
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 required	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.
	object (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.
required	object (PaymentRequest) Mandatory. The payment request object defining the details of the payment.
	object (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`.
	object (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`.

Responses

201

Created

default

Error Response

post/embedded-payment-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Berlin Group EUR Single Domestic Payment Example Request

{"applicationUserId": "string",
"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"
}
]
}
}
}

Response samples

201
default

application/json;charset=UTF-8

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": "string",
"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"
}
]
}
}

Update Embedded Payment Authorisation

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

Request

Security:

basicAuth

path Parameters

consentId

required

string

Mandatory. The consent Id of the Consent to update.

query Parameters

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

header Parameters

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.

Request Body schema: application/json;charset=UTF-8

userUuid	string <uuid>
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 required	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.
	object (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.
required	object (PaymentRequest) Mandatory. The payment request object defining the details of the payment.
	object (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`.
	object (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`.

Responses

200

default

Error Response

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

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

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

{"applicationUserId": "string",
"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"
}
]
}
}
}

Response samples

200
default

application/json;charset=UTF-8

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": "string",
"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"
}
}

Create Payment Authorisation

Used to initiate the authorisation process and direct users to the login screen of their financial Institution in order to give their consent for a payment. This endpoint is used to initiate all the different payment 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:

INITIATE_DOMESTIC_PERIODIC_PAYMENT
INITIATE_DOMESTIC_SCHEDULED_PAYMENT
INITIATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
INITIATE_DOMESTIC_SINGLE_PAYMENT
INITIATE_INTERNATIONAL_PERIODIC_PAYMENT
INITIATE_INTERNATIONAL_SCHEDULED_PAYMENT
INITIATE_INTERNATIONAL_SINGLE_PAYMENT

Request

Security:

basicAuth

query Parameters

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

header Parameters

psu-id	string (User Id) 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 (Corporate User Id) 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 (User IP Address) Conditional. The IP address of the PSU. See PSU identifiers to see if this header is required.

Request Body schema: application/json;charset=UTF-8

userUuid	string <uuid>
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	Array of strings Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId required	string Mandatory. The reference to the `Institution` which identifies which institution the authorisation request is sent to.
callback	string Optional. The URL to redirect the user to after the user complete the authorisation at the `Institution`.
	object (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.
required	object (PaymentRequest) Mandatory. The payment request object defining the details of the payment.

Responses

201

Created

default

Error Response

post/payment-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

EUR Single Domestic Example Request

{"applicationUserId": "string",
"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"
}
]
}
}
}

Response samples

201
default

application/json;charset=UTF-8

EUR Single Domestic Example Response

{"meta": {"tracingId": "a3d09f97bea244e2bb8be0bffbe53f81"
},
"data": {"id": "cae22f3d-1033-4ba6-95ae-0d8ca193b090",
"userUuid": "5350782b-60f3-489e-aae5-a24d8d679a07",
"applicationUserId": "string",
"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"
}
}

Update Payment Pre-authorisation

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

Request

Security:

basicAuth

query Parameters

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

header Parameters

psu-id	string (User Id) 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 (Corporate User Id) 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 (User IP Address) Conditional. The IP address of the PSU. See PSU identifiers to see if this header is required.
consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}

Request Body schema: application/json;charset=UTF-8

userUuid	string <uuid>
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	Array of strings Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
institutionId required	string Mandatory. The reference to the `Institution` which identifies which institution the authorisation request is sent to.
callback	string Optional. The URL to redirect the user to after the user complete the authorisation at the `Institution`.
	object (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.
required	object (PaymentRequest) Mandatory. The payment request object defining the details of the payment.

Responses

200

default

Error Response

put/payment-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Berlin Group EUR Single Domestic Payment Example Request

{"applicationUserId": "string",
"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"
}
]
}
}
}

Response samples

200
default

application/json;charset=UTF-8

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": "string",
"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"
}
}

Create Pre-authorisation

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

Request

Security:

basicAuth

query Parameters

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

header Parameters

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.

Request Body schema: application/json;charset=UTF-8

userUuid	string <uuid>
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	Array of strings Extra parameters to be forwarded in the redirect back to the client after the user authorisation flow has been completed.
institutionId required	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.
	object (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.
scope required	string Mandatory. Defines the scope of the pre-authorisation request.

Responses

201

Created

default

Error Response

post/pre-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Berlin Group (AIS) Example Request

{"applicationUserId": "string",
"institutionId": "n26",
"callback": "https://display-parameters.com/",
"scope": "AIS"
}

Response samples

201
default

application/json;charset=UTF-8

Berlin Group Example (AIS) Response

{"meta": {"tracingId": "8acb66e6a9e142e79acc3ccf6cc03e04"
},
"data": {"id": "73064bb9-c84d-4242-897c-4150aacfa658",
"userUuid": "e2578545-27a4-4edf-983f-5d33c2d7b559",
"applicationUserId": "string",
"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"
}
}

Create Payment Pre-authorisation

Used to initiate the pre-authorisation process for payments for CBI Globe institutions that contain the INITIATE_ONETIME_PRE_AUTHORISATION_PAYMENTS feature to authenticate the user.

Feature: INITIATE_ONETIME_PRE_AUTHORISATION_PAYMENTS

Request

Security:

basicAuth

query Parameters

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

header Parameters

psu-ip-address

string

Conditional. The IP address of the PSU.

See PSU identifiers to see if this header is required.

Request Body schema: application/json;charset=UTF-8

userUuid	string <uuid>
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	Array of strings Extra parameters to be forwarded in the redirect back to the client after the user authorisation flow has been completed.
institutionId required	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.
	object (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.
scope required	string Mandatory. Defines the scope of the pre-authorisation request.
required	object (PayeeDetails) Mandatory. Details of the beneficiary [person or business].
required	object (PayerDetails) Conditional. Details of the benefactor [person or business].
required	object (Amount Details) Mandatory. Monetary Amount.
reference required	string Mandatory. The payment reference or description. Limited to a maximum of 18 characters long.

Responses

201

Created

default

Error Response

post/payment-pre-auth-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

CBI Globe (PIS) example request

{"applicationUserId": "string",
"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"
}
]
}
}

Response samples

201
default

application/json;charset=UTF-8

Berlin Group Example (PIS) Response

{"meta": {"tracingId": "ba79c56773de42129dbf8164b202276c"
},
"data": {"id": "53ff00d0-91dd-417d-880b-cdd7c50090ed",
"userUuid": "e2578545-27a4-4edf-983f-5d33c2d7b559",
"applicationUserId": "string",
"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"
}
}

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

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

Feature: ACCOUNTS

Request

Security:

basicAuth

query Parameters

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

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
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.

Responses

200

default

Error Response

get/accounts

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts?raw=true' \
  -H 'consent: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-id: string' \
  -H 'psu-ip-address: string'

Response samples

200
default

application/json;charset=UTF-8

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": [ ]
}
]
}
]
}

Get Account

Returns the account and balance information for a user's specified account.

Feature: ACCOUNT

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The account Id of the user's bank account.

query Parameters

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

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
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.

Responses

200

default

Error Response

get/accounts/{accountId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}?raw=true' \
  -H 'consent: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-id: string' \
  -H 'psu-ip-address: string'

Response samples

200
default

application/json;charset=UTF-8

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": [ ]
}
]
}
}

Get Account Balances

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

Feature: ACCOUNT_BALANCES

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The account Id of the user's bank account.

query Parameters

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

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
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.

Responses

200

default

Error Response

get/accounts/{accountId}/balances

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/balances?raw=true' \
  -H 'consent: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-id: string' \
  -H 'psu-ip-address: string'

Response samples

200
default

application/json;charset=UTF-8

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"
}
}
]
}
}

Get Account Beneficiaries

Returns all the beneficiaries of a user's account.

Feature: ACCOUNT_BENEFICIARIES

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The account Id of the user's bank account.

query Parameters

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

header Parameters

consent

required

string

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

Example: {consentToken}

Responses

200

default

Error Response

get/accounts/{accountId}/beneficiaries

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/beneficiaries?raw=true' \
  -H 'consent: string'

Response samples

200
default

application/json;charset=UTF-8

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"
}
]
}
}
]
}

Get Account Direct Debits

Returns the list of direct debits for an account.

Feature: ACCOUNT_DIRECT_DEBITS

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The account Id of the user's bank account.

query Parameters

limit	integer <int32> Optional. The maximum number of transaction records to be returned. Must be between 1 and 1000.
raw	boolean Optional. Used to obtain the raw request and response to and from the `Institution`.

header Parameters

consent

required

string

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

Example: {consentToken}

Responses

200

default

Error Response

get/accounts/{accountId}/direct-debits

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/direct-debits?limit=0&raw=true' \
  -H 'consent: string'

Response samples

200
default

application/json;charset=UTF-8

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

Get Account Periodic Payments

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

Feature: ACCOUNT_PERIODIC_PAYMENTS

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The account Id of the user's bank account.

query Parameters

limit	integer <int32> Optional. The maximum number of transaction records to be returned. Must be between 1 and 1000.
raw	boolean Optional. Used to obtain the raw request and response to and from the `Institution`.

header Parameters

consent

required

string

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

Example: {consentToken}

Responses

200

default

Error Response

get/accounts/{accountId}/periodic-payments

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/periodic-payments?limit=0&raw=true' \
  -H 'consent: string'

Response samples

200
default

application/json;charset=UTF-8

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

Get Account Scheduled Payments

Returns the list of scheduled payments for an account.

Feature: ACCOUNT_SCHEDULED_PAYMENTS

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The account Id of the user's bank account.

query Parameters

limit	integer <int32> Optional. The maximum number of transaction records to be returned. Must be between 1 and 1000.
raw	boolean Optional. Used to obtain the raw request and response to and from the `Institution`.

header Parameters

consent

required

string

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

Example: {consentToken}

Responses

200

default

Error Response

get/accounts/{accountId}/scheduled-payments

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/scheduled-payments?limit=0&raw=true' \
  -H 'consent: string'

Response samples

200
default

application/json;charset=UTF-8

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

Get Account Statements

Returns the list of statements for an account.

Feature: ACCOUNT_STATEMENTS

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The account Id of the user's bank account.

query Parameters

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 1 and 1000.
sort	string (SortEnum) Optional. Sort transaction records by date ascending with 'date' or descending with '-date'. The default sort order is descending Enum: "date" "-date"
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`.

header Parameters

consent

required

string

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

Example: {consentToken}

Responses

200

default

Error Response

get/accounts/{accountId}/statements

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/statements?from=string&before=string&limit=0&sort=date&offset=0&raw=true' \
  -H 'consent: string'

Response samples

200
default

application/json;charset=UTF-8

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

Get Account Statement

Returns a statement for an account.

Feature: ACCOUNT_STATEMENT

Request

Security:

basicAuth

path Parameters

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

query Parameters

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

header Parameters

consent

required

string

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

Responses

200

default

Error Response

get/accounts/{accountId}/statements/{statementId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/statements/{statementId}?raw=true' \
  -H 'consent: string'

Response samples

200
default

application/json;charset=UTF-8

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

Get Account Statement File

Returns a PDF file of a statement for an account.

Feature: ACCOUNT_STATEMENT_FILE

Request

Security:

basicAuth

path Parameters

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

query Parameters

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

header Parameters

consent

required

string

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

Example: {consentToken}

Responses

200

default

Error Response

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

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/statements/{statementId}/file?raw=true' \
  -H 'consent: string'

Response samples

default

application/json;charset=UTF-8

Error Response

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

Get Account Transactions

Returns the account transactions for an account.

Feature: ACCOUNT_TRANSACTIONS

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The account Id of the user's bank account.

query Parameters

with	Array of strings Optional. Acceptable value: `categorisation`. When set, will include enrichment data in the transactions returned. Enrichment data is optional, e.g. when 'categorisation' enrichment data is requested, the enrichment response will include categorisation data and merchant name, only if it can be evaluated from the transaction. This service is limited for UK institution transactions currently. This is a legacy feature and will be deprecated. Date TBC
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 1 and 1000.
sort	string (SortEnum) Optional. Sort transaction records by date ascending with 'date' or descending with '-date'. The default sort order is descending Enum: "date" "-date"
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`.

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
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.

Responses

200

default

Error Response

get/accounts/{accountId}/transactions

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/transactions?with=string&from=string&before=string&limit=0&sort=date&offset=0&cursor=string&raw=true' \
  -H 'consent: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-id: string' \
  -H 'psu-ip-address: string'

Response samples

200
default

application/json;charset=UTF-8

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

Get Categories

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

See Data Enrichment for more information.

Request

Security:

basicAuth

path Parameters

country

required

string

Mandatory. The 2 letter country code e.g. 'GB'.

Responses

200

default

Error Response

get/categories/{country}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/categories/{country}'

Response samples

200
default

application/json;charset=UTF-8

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": [ ]
}
]
}

Get Identity

Returns the identity information for an account.

Feature: IDENTITY

Request

Security:

basicAuth

query Parameters

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

header Parameters

consent

required

string

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

Example: {consentToken}

Responses

200

default

Error Response

get/identity

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/identity?raw=true' \
  -H 'consent: string'

Response samples

200
default

application/json;charset=UTF-8

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"
}
]
}
}

Get Real Time Account Transactionsbeta

Used to get the account transactions for an account in real time with cursor pagination

Feature: ACCOUNT_TRANSACTIONS

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The account Id of the user's bank account.

query Parameters

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).
cursor	string Optional. The cursor token supplied by a previous call. The cursor represents a location in the data set.
raw	boolean Optional. Used to obtain the raw request and response to and from the `Institution`.

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
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.

Responses

200

401

Error Response

default

Error Response

get/accounts/{accountId}/real-time/transactions

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/real-time/transactions?from=string&before=string&cursor=string&raw=true' \
  -H 'consent: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-id: string' \
  -H 'psu-ip-address: string'

Response samples

200
401
default

application/json;charset=UTF-8

Example Response

{"meta": {"tracingId": "488ce8243ee74a378be722ffffec8f7f",
"count": 1
},
"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",
"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"
}
}
}
],
"links": {"first": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=aaa",
"prev": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=bbb",
"self": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=ccc",
"next": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=ddd",
"last": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=zzz"
}
}

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

Creates a bulk payment after obtaining the user's authorisation.

Feature: CREATE_BULK_PAYMENT

Request

Security:

basicAuth

query Parameters

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

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
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.

Request Body schema: application/json;charset=UTF-8

required	Array of objects (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`.

Responses

201

Created

default

Error Response

post/bulk-payments

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

UK Bulk Payment Example Request

{"payments": [{"type": "DOMESTIC_PAYMENT",
"paymentIdempotencyId": "d78fy48uh8f9odhde68dfi38di9",
"reference": "payment1",
"contextType": "BILL_IN_ARREARS",
"purposeCode": "COMT",
"amount": {"amount": 2,
"currency": "GBP"
},
"payee": {"name": "Jane Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
],
"accountType": "BUSINESS_SAVING"
}
},
{"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"
}
]
}
}
]
}

Response samples

201
default

application/json;charset=UTF-8

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

Create Payment

Creates a payment after obtaining the user's authorisation.

Features:

CREATE_DOMESTIC_PERIODIC_PAYMENT
CREATE_DOMESTIC_SCHEDULED_PAYMENT
CREATE_DOMESTIC_SINGLE_INSTANT_PAYMENT
CREATE_DOMESTIC_SINGLE_PAYMENT
CREATE_INTERNATIONAL_PERIODIC_PAYMENT
CREATE_INTERNATIONAL_SCHEDULED_PAYMENT
CREATE_INTERNATIONAL_SINGLE_PAYMENT

Request

Security:

basicAuth

query Parameters

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

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
psu-id	string (User Id) 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 (Corporate User Id) 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 (User IP Address) Conditional. The IP address of the PSU. See PSU identifiers to see if this header is required.

Request Body schema: application/json;charset=UTF-8

paymentIdempotencyId required	string (Idempotency Id) Mandatory. A unique identifier that you must provide to identify the payment. This can be any alpha-numeric string but is limited to a maximum of 35 characters.
	object (Payer Details) Conditional. Details of the benefactor [person or business].
reference	string (Payment Reference) Optional. The payment reference or description. Limited to a maximum of 18 characters long.
contextType	string (Payment Code) Default: "OTHER" Optional. The payment context code. This defaults to `OTHER` if not specified. Enum: "BILL" "GOODS" "SERVICES" "OTHER" "PERSON_TO_PERSON" … 7 more
purposeCode	string (Payment Purpose Code) Optional. The payment purpose code. Allowed values: INTP,DEPT,BEXP,LICF,SERV,SUPP,TRAD,SUBS,GDSV,ROYA,COMT,CHAR,ECPR,CLPR,INTE,LOAN,LOAR,INPC,INPR,INSC,INSU,LIFI,PPTI,HLRP,HLST,PDEP,IVPT,REBT,REFU,CDBL,CPKC,EDUC,FEES,GAMB,LOTT,GIFT,INSM,REOD,GOVT,TCSC,BLDM,RENT,DIVD,INVS,SAVG,HLTI,DNTS,LTCF,MDCS,VIEW,BECH,BENE,SSBE,PEFC,PENS,ADCS,BONU,COMM,SALA,ESTX,HSTX,INTX,PTXP,RDTX,TAXS,VATX,WHLD,TAXR,CBTV,ELEC,GASB,PHON,UBIL,WTER . See Payment Purpose code to see the definition of each code
type required	string (Payment Type) Mandatory. Used to specify which of the payment types to execute. See European Payments to verify whether the `type` should be `DOMESTIC` or `INTERNATIONAL`. Enum: "DOMESTIC_PAYMENT" "DOMESTIC_INSTANT_PAYMENT" "DOMESTIC_VARIABLE_RECURRING_PAYMENT" "DOMESTIC_SCHEDULED_PAYMENT" "DOMESTIC_PERIODIC_PAYMENT" … 4 more
required	object (Payee Details) Mandatory. Details of the beneficiary [person or business].
	object (PeriodicPaymentRequest) Conditional. Used to specify properties to define a periodic payment. Must be specified when the payment `type` is one of the following: `DOMESTIC_PERIODIC_PAYMENT` `INTERNATIONAL_PERIODIC_PAYMENT`
	object (InternationalPaymentRequest) Conditional. Used to specify properties to define an international payment. Must be specified when the payment `type` is one of the following: `INTERNATIONAL_SINGLE_PAYMENT` `INTERNATIONAL_SCHEDULED_PAYMENT` `INTERNATIONAL_PERIODIC_PAYMENT`
required	object (Amount Details) Mandatory. Monetary Amount.
paymentDateTime	string <date-time> (Payment Date) Conditional. Used to specify the date of the payment when the payment type is one of the following: `DOMESTIC_SCHEDULED_PAYMENT` `DOMESTIC_PERIODIC_PAYMENT` `INTERNATIONAL_SCHEDULED_PAYMENT` `INTERNATIONAL_PERIODIC_PAYMENT`
readRefundAccount	boolean (Read Refund Account) Optional. Used to request the payer details in the payment response when the `Institution` provides the feature `READ_DOMESTIC_SINGLE_REFUND`. See Reverse Payments for more information.

Responses

201

Created

default

Error Response

post/payments

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

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"
}
]
}
}

Response samples

201
default

application/json;charset=UTF-8

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

Get Payment Details

Returns the details of a payment.

Most commonly used to check for payment status updates.

Feature: EXISTING_PAYMENTS_DETAILS

Request

Security:

basicAuth

path Parameters

paymentId

required

string

Mandatory. The payment Id of the payment.

query Parameters

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

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
psu-id	string (User Id) 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 (Corporate User Id) 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 (User IP Address) Conditional. The IP address of the PSU. See PSU identifiers to see if this header is required.

Responses

200

default

Error Response

get/payments/{paymentId}/details

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/payments/{paymentId}/details?raw=true' \
  -H 'consent: string' \
  -H 'psu-corporate-id: string' \
  -H 'psu-id: string' \
  -H 'psu-ip-address: string'

Response samples

200
default

application/json;charset=UTF-8

EUR Single Domestic Payment Example Response

{"meta": {"tracingId": "590c99aecd2844c7a5c3ea00c55ce0ef"
},
"data": {"payments": [{"id": "pv3-a6ac6528-e8c8-44eb-b6f9-8521963518dd",
"institutionConsentId": "sdp-1-27a192bb-482f-4731-989b-e7271661248d",
"paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
"paymentLifecycleId": "3gaq9wj387aojd83dh7549824",
"status": "COMPLETED",
"statusDetails": {"status": "COMPLETED",
"statusUpdateDate": "2021-06-10T11:26:54.887Z",
"isoStatus": {"code": "ACSC",
"name": "AcceptedSettlementCompleted"
}
},
"payeeDetails": {"name": "Jane Doe",
"address": {"country": "BE"
},
"accountIdentifications": [{"type": "IBAN",
"identification": "BE12345678901234"
}
]
},
"reference": "Bill Payment",
"amount": 1,
"currency": "EUR",
"amountDetails": {"amount": 1,
"currency": "EUR"
},
"scheduledPaymentType": "DOMESTIC_PAYMENT",
"createdAt": "2021-06-10T11:26:54.887Z"
}
]
}
}

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.

Create Profile Consent

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.

Request

Security:

basicAuth

path Parameters

userUuid

required

string <uuid>

Mandatory. The Yapily generated UUID for the user.

header Parameters

consent

required

string

Mandatory. The consent-token obtained from the original authorisation.

Responses

201

A successful response, returning a ApiResponseOfFinancialProfileAuthorisationResponse.

400

Bad Request. Returned if the userUuid is not a valid UUID.

401

Either authentication credentials were not supplied, or they were invalid.

404

Not Found. Returned if the userUuid is not found for the Application.

post/users/{userUuid}/profile/consents

Request samples

curl
JavaScript
Node.js
Python

curl -i -X POST \
  -u <username>:<password> \
  'https://api.yapily.com/users/{userUuid}/profile/consents' \
  -H 'consent: string'

Response samples

application/json

{"meta": {"tracingId": "string"
},
"data": [{"id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
"status": "PENDING",
"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"referenceConsentId": "1e2e5167-8519-4c19-b016-8f2f0c6e38b6",
"institutionId": "mock-sandbox",
"createdAt": "28-07-2022 21:00:00",
"expiresAt": "28-07-2022 21:05:00",
"dataInsertedAt": "28-07-2022 21:00:30"
}
],
"links": {"property1": "string",
"property2": "string"
}
}

Get Profile Consent

Used to retrieve a specific ProfileConsent for a User.

Request

Security:

basicAuth

path Parameters

userUuid required	string <uuid> Mandatory. The Yapily generated UUID for the user.
profileConsentId required	string Mandatory. The ID of the ProfileConsent

Responses

200

A successful response, returning a ApiResponseOfFinancialProfileConsent.

400

Bad Request. Returned if the userUuid is not a valid UUID.

401

Either authentication credentials were not supplied, or they were invalid.

404

Not Found. Returned if the userUuid or ProfileConsent is not found for the Application.

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

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/users/{userUuid}/profile/consents/{profileConsentId}'

Response samples

application/json

{"meta": {"tracingId": "string"
},
"data": {"id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
"status": "PENDING",
"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"referenceConsentId": "1e2e5167-8519-4c19-b016-8f2f0c6e38b6",
"institutionId": "mock-sandbox",
"createdAt": "28-07-2022 21:00:00",
"expiresAt": "28-07-2022 21:05:00",
"dataInsertedAt": "28-07-2022 21:00:30"
},
"links": {"property1": "string",
"property2": "string"
}
}

Delete Profile Consent

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

Request

Security:

basicAuth

path Parameters

userUuid required	string <uuid> Mandatory. The Yapily generated UUID for the user.
profileConsentId required	string Mandatory. The ID of the ProfileConsent

Responses

200

The ProfileConsent was deleted.

400

Bad Request. Returned if the userUuid is not a valid UUID.

401

Either authentication credentials were not supplied, or they were invalid.

404

Not Found. Returned if the userUuid or ProfileConsent is not found for the Application.

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

Request samples

curl
JavaScript
Node.js
Python

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api.yapily.com/users/{userUuid}/profile/consents/{profileConsentId}'

Response samples

application/json

{"meta": {"tracingId": "string"
},
"links": {"property1": "string",
"property2": "string"
}
}

Get Transaction Groups

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

Request

Security:

basicAuth

path Parameters

userUuid

required

string <uuid>

Mandatory. The Yapily generated UUID for the user.

Responses

200

A successful response, returning a ApiResponseOfFinancialProfile.

400

Bad Request. Returned if the userUuid is not a valid UUID.

401

Either authentication credentials were not supplied, or they were invalid.

404

Not Found. Returned if the userUuid is not found for the Application.

get/users/{userUuid}/profile/transaction-groups

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/users/{userUuid}/profile/transaction-groups'

Response samples

application/json

{"meta": {"tracingId": "string"
},
"data": {"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",
"createdAt": "28-07-2022 21:00:00",
"expiresAt": "28-07-2022 21:05:00",
"dataInsertedAt": "28-07-2022 21:00:30"
}
],
"enrichment": {"incomeStreams": [{"name": "Amazon Marketplace",
"transactions": [{"transactionId": "c51e3bee-36fb-4c0a-8441-d6ba2056fe87",
"transactionInformation": "Amazon Marketplace",
"amount": 21.99,
"institution": "starling",
"bookingDateTime": "2020-04-24T00:30:19.951Z"
}
],
"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": "c51e3bee-36fb-4c0a-8441-d6ba2056fe87",
"transactionInformation": "Amazon Marketplace",
"amount": 21.99,
"institution": "starling",
"bookingDateTime": "2020-04-24T00:30:19.951Z"
}
],
"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": "c51e3bee-36fb-4c0a-8441-d6ba2056fe87",
"transactionInformation": "Amazon Marketplace",
"amount": 21.99,
"institution": "starling",
"bookingDateTime": "2020-04-24T00:30:19.951Z"
}
],
"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": "c51e3bee-36fb-4c0a-8441-d6ba2056fe87",
"transactionInformation": "Amazon Marketplace",
"amount": 21.99,
"institution": "starling",
"bookingDateTime": "2020-04-24T00:30:19.951Z"
}
],
"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
}
]
}
},
"links": {"property1": "string",
"property2": "string"
}
}

Get Predicted Balances

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

Request

Security:

basicAuth

path Parameters

userUuid

required

string <uuid>

Mandatory. The Yapily generated UUID for the user.

Responses

200

A successful response, returning a Balance Prediction Profile.

400

Bad Request. Returned if the userUuid is not a valid UUID.

401

Either authentication credentials were not supplied, or they were invalid.

404

Not Found. Returned if the userUuid is not found for the Application, or data not found for the userUuid.

get/users/{userUuid}/profile/predicted-balances

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/users/{userUuid}/profile/predicted-balances'

Response samples

application/json

Balance Prediction Example Response

{"status": "COMPLETED",
"profileConsents": [{"id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
"status": "COMPLETED",
"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"referenceConsentId": "1e2e5167-8519-4c19-b016-8f2f0c6e38b6",
"institutionId": "mock-sandbox"
}
],
"enrichedBalances": [{"accountIds": ["abc123",
"xyz456"
],
"institutions": ["llyods",
"monzo_ab"
],
"historic": [{"date": "2021-03-01",
"balance": 20
},
{"date": "2021-03-02",
"balance": 60
},
{"date": "2021-03-03",
"balance": 0
},
{"date": "2021-03-04",
"balance": 0
},
{"date": "2021-03-05",
"balance": 100
}
],
"predicted": [{"date": "2021-03-24",
"medianBalance": 28.48,
"90percentileBalance": 49.26,
"10percentileBalance": 5.96
},
{"date": "2021-03-25",
"medianBalance": 28.88,
"90percentileBalance": 46.38,
"10percentileBalance": -2.39
},
{"date": "2021-03-26",
"medianBalance": 22.07,
"90percentileBalance": 41.48,
"10percentileBalance": 0.82
},
{"date": "2021-03-27",
"medianBalance": 20.91,
"90percentileBalance": 38.25,
"10percentileBalance": -1.24
},
{"date": "2021-03-28",
"medianBalance": 14.99,
"90percentileBalance": 35.98,
"10percentileBalance": -14.64
}
]
}
]
}

Notifications

The Notifications endpoints provide an interactive way for user to receive notifications according to different event-types. This feature is currently in private beta. Please reach out if you require access.

Create Event Subscriptionbeta

Used to subscribe to notifications relating to a specified event type.

Request

Security:

basicAuth

Request Body schema: application/json

eventTypeId required	string Unique identifier of the event type (for which notifications will be sent). Allowed values: payment.status, payment.status.completed, payment.isoStatus, virtualAccount.payIn.status, virtualAccount.payOut.status, virtualAccount.createBeneficiary.status, virtualAccount.account.status, virtualAccount.client.status, virtualAccount.refund.status, virtualAccount.payOut.return
required	object (Notification) Subscription details for how and where to receive notifications.

Responses

201

Event subscription created successfully

400

Bad request for missing required properties

401

Unauthorized

409

Event subscription already exist for the application

post/notifications/event-subscriptions

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

{"eventTypeId": "payment.status.completed",
"notification": {"type": "WEBHOOK",
"url": "https://httpbin.com/new_endpoint"
}
}

Response samples

application/json

{"meta": {"tracingId": "string"
},
"data": {"eventTypeId": "payment.status.completed",
"applicationId": "2698db90-6635-4f76-b673-5ce8e2aeda0e",
"created": "28-07-2021 15:47:03",
"notification": {"type": "WEBHOOK",
"url": "https://httpbin.com/new_endpoint"
}
},
"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": { }
}
]
}

Get Event Subscriptionsbeta

Get all event subscriptions that your application is subscribed to

Request

Security:

basicAuth

Responses

200

Event subscriptions for the application

401

Unauthorized

get/notifications/event-subscriptions

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  https://api.yapily.com/notifications/event-subscriptions

Response samples

application/json

{"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": [{"eventTypeId": "payment.status.completed",
"applicationId": "2698db90-6635-4f76-b673-5ce8e2aeda0e",
"created": "28-07-2021 15:47:03",
"notification": {"type": "WEBHOOK",
"url": "https://httpbin.com/new_endpoint"
}
}
],
"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",
"date": "2019-08-24T14:15:22Z",
"bookingDateTime": "2019-08-24T14:15:22Z",
"valueDateTime": "2019-08-24T14:15:22Z",
"status": "BOOKED",
"amount": 0,
"currency": "string",
"transactionAmount": {"amount": 10,
"currency": "GBP"
},
"grossAmount": {"amount": 10,
"currency": "GBP"
},
"currencyExchange": {"sourceCurrency": "string",
"targetCurrency": "string",
"unitCurrency": "string",
"exchangeRate": 0
},
"chargeDetails": {"chargeAmount": {"amount": 10,
"currency": "GBP"
}
},
"reference": "string",
"statementReferences": [{"value": "string"
}
],
"description": "string",
"transactionInformation": ["string"
],
"addressDetails": {"addressLine": "string"
},
"isoBankTransactionCode": {"domainCode": {"code": "UNKNOWN",
"name": "UNKNOWN"
},
"familyCode": {"code": "UNKNOWN",
"name": "UNKNOWN"
},
"subFamilyCode": {"code": "UNKNOWN",
"name": "UNKNOWN"
}
},
"proprietaryBankTransactionCode": {"code": "string",
"issuer": "string"
},
"balance": {"type": "CLOSING_AVAILABLE",
"balanceAmount": {"amount": 10,
"currency": "GBP"
}
},
"payeeDetails": {"name": "string",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "string"
}
]
},
"payerDetails": {"name": "string",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "string"
}
]
},
"merchant": {"merchantName": "string",
"merchantCategoryCode": "string"
},
"enrichment": {"categorisation": {"categories": ["string"
],
"source": "string"
},
"transactionHash": {"hash": "string"
},
"cleansedDescription": "string",
"merchant": {"merchantName": "string",
"parentGroup": "string"
},
"location": "string",
"paymentProcessor": "string",
"correctedDate": "2019-08-24T14:15:22Z"
},
"supplementaryData": { },
"transactionMutability": "Mutable"
}
],
"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
}
}

Get Event Subscriptionbeta

Used to get details of your subscription to a specified event type.

Request

Security:

basicAuth

path Parameters

eventTypeId

required

string

Unique identifier of the event type (for which notifications will be sent).

Responses

200

Event subscription data found

401

Unauthorized

404

Event subscription not found

get/notifications/event-subscriptions/{eventTypeId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/notifications/event-subscriptions/{eventTypeId}'

Response samples

application/json

{"meta": {"tracingId": "string"
},
"data": {"eventTypeId": "payment.status.completed",
"applicationId": "2698db90-6635-4f76-b673-5ce8e2aeda0e",
"created": "28-07-2021 15:47:03",
"notification": {"type": "WEBHOOK",
"url": "https://httpbin.com/new_endpoint"
}
},
"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": { }
}
]
}

Delete Event Subscriptionbeta

Used to unsubscribe to notifications relating to a specified event type.

Request

Security:

basicAuth

path Parameters

eventTypeId

required

string

Unique identifier of the event type (for which notifications will be sent).

Responses

200

Event subscription deleted successfully

401

Unauthorized

404

Event subscription not found

delete/notifications/event-subscriptions/{eventTypeId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api.yapily.com/notifications/event-subscriptions/{eventTypeId}'

Response samples

application/json

{"meta": {"tracingId": "string"
},
"data": {"eventTypeId": "payment.status.completed",
"applicationId": "2698db90-6635-4f76-b673-5ce8e2aeda0e",
"created": "28-07-2021 15:47:03",
"deleteStatus": "SUCCESS"
},
"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": { }
}
]
}

Virtual Accounts

Virtual accounts can be used within PIS associated flow of funds in order to take advantage of payment features such as receipt of funds, reconciliation, funds handling and settlement. Accounts can be created, managed and enquired upon using these endpoints

Get List Of Beneficiaries

Gets the list of beneficiaries (individual or business account) to which a Pay Out can be made.

Request

Security:

basicAuth

query Parameters

cursor

string

Optional. Data required to provide pagination

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/beneficiaries

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/beneficiaries?cursor=string' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get Beneficiaries Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"links": {"self": "2",
"first": "0",
"last": "7",
"next": "3",
"previous": "1"
},
"data": [{"id": "a2d43be3-972a-4458-9b6b-84ac15ae5287",
"nickname": "MyBeneficiary123",
"paymentSchemes": ["FASTER_PAYMENTS",
"CHAPS"
],
"type": "INDIVIDUAL",
"name": "Mr Jack Williams",
"birthDate": "1999-10-04",
"address": {"addressLine": "12 New Street",
"townName": "London",
"postCode": "NE15 PLZ",
"country": "GB"
},
"account": {"currency": "GBP",
"bankName": "Lloyds Bank",
"bankAddress": "London, WE12 ABC",
"bankCountry": "GB",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "401016"
},
{"type": "ACCOUNT_NUMBER",
"identification": "71518920"
}
]
},
"status": "ACTIVE"
}
]
}

Create Beneficiary

Create a new beneficiary (individual or business account) to which a Pay Out can be made. The beneficiary can be used from any virtual account that is held

Request

Security:

basicAuth

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Request Body schema: application/json;charset=UTF-8

nickname required	string Reference that can be provided in order to help with identification of the Beneficiary
type required	string Indicates the type of Beneficiary as either an INDIVIDUAL or BUSINESS
name required	string
birthDate	string <date>
paymentSchemes required	Array of strings Beneficiary payment schemes
required	object (VirtualAccountBeneficiaryAddress)
required	object (VirtualAccountBeneficiaryAccount)

Responses

201

Created

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

409

Conflict with another beneficiary with same account identifications

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

post/virtual-accounts/beneficiaries

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Beneficiary Example Request

{"nickname": "MyBeneficiary123",
"paymentSchemes": ["FASTER_PAYMENTS",
"CHAPS"
],
"type": "INDIVIDUAL",
"name": "Mr Jack Williams",
"birthDate": "1999-10-04",
"address": {"addressLine": "12 New Street",
"townName": "London",
"postCode": "NE15 PLZ",
"country": "GB"
},
"account": {"currency": "GBP",
"bankName": "Lloyds Bank",
"bankAddress": "London, WE12 ABC",
"bankCountry": "GB",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "401016"
},
{"type": "ACCOUNT_NUMBER",
"identification": "71518920"
}
]
}
}

Response samples

application/json

Create Beneficiary Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "a2d43be3-972a-4458-9b6b-84ac15ae5287",
"nickname": "MyBeneficiary123",
"paymentSchemes": ["FASTER_PAYMENTS",
"CHAPS"
],
"type": "INDIVIDUAL",
"name": "Mr Jack Williams",
"birthDate": "1999-10-04",
"address": {"addressLine": "12 New Street",
"townName": "London",
"postCode": "NE15 PLZ",
"country": "GB"
},
"account": {"currency": "GBP",
"bankName": "Lloyds Bank",
"bankAddress": "London, WE12 ABC",
"bankCountry": "GB",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "401016"
},
{"type": "ACCOUNT_NUMBER",
"identification": "71518920"
}
]
},
"status": "ACTIVE"
}
}

Get Beneficiary

Get the details of a specific beneficiary (individual or business account) to which a Pay Out can be made from its id.

Request

Security:

basicAuth

path Parameters

beneficiaryId

required

string

Mandatory. The Id of the requested beneficiary.

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

404

Not Found. Requested beneficiary is not found.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/beneficiaries/{beneficiaryId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/beneficiaries/{beneficiaryId}' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get Beneficiary Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "a2d43be3-972a-4458-9b6b-84ac15ae5287",
"nickname": "MyBeneficiary123",
"paymentSchemes": ["FASTER_PAYMENTS",
"CHAPS"
],
"type": "INDIVIDUAL",
"name": "Mr Jack Williams",
"birthDate": "1999-10-04",
"address": {"addressLine": "12 New Street",
"townName": "London",
"postCode": "NE15 PLZ",
"country": "GB"
},
"account": {"currency": "GBP",
"bankName": "Lloyds Bank",
"bankAddress": "London, WE12 ABC",
"bankCountry": "GB",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "401016"
},
{"type": "ACCOUNT_NUMBER",
"identification": "71518920"
}
]
},
"status": "ACTIVE"
}
}

Delete Beneficiary

Delete a specific beneficiary (individual or business account)

Request

Security:

basicAuth

path Parameters

beneficiaryId

required

string

Mandatory. The Id of the beneficiary that will be deleted

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

404

Not Found. Requested beneficiary is not found

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

delete/virtual-accounts/beneficiaries/{beneficiaryId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/beneficiaries/{beneficiaryId}' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

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

Get Accounts

Retrieve a list of all virtual accounts held

Request

Security:

basicAuth

query Parameters

nickname	string Optional. Filter accounts based on reference provided in order to help with identification of the account
currency	string^[A-Z]{3}$ Optional. Filter accounts based on three-letter ISO 4217 currency code
status	string Optional. Filter accounts based on their current state. One of PENDING, ACTIVE, FAILED, SUSPENDED or CLOSED
cursor	string Optional. Data required to provide pagination

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/accounts

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/accounts?nickname=string&currency=string&status=string&cursor=string' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get Accounts Example Response

{"meta": {"tracingId": "sd2ad0343-a141-4143-8756-a3a3cefrt31c",
"count": 1
},
"links": {"self": "2",
"first": "0",
"last": "7",
"next": "3",
"previous": "1"
},
"data": [{"id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
"createdDateTime": "2020-04-24T00:30:19.951Z",
"status": "ACTIVE",
"nickname": "MyAccount123",
"currency": "GBP",
"balances": [{"type": "INTERIM_AVAILABLE",
"balanceAmount": {"amount": 10.5,
"currency": "GBP"
}
},
{"type": "INTERIM_BOOKED",
"balanceAmount": {"amount": 10.5,
"currency": "GBP"
}
}
],
"bankAccount": {"currency": "GBP",
"bankName": "Lloyds Bank",
"bankAddress": "WE12 ABC",
"bankCountry": "GB",
"accountIdentifications": [{"identification": "401016",
"type": "SORT_CODE"
},
{"identification": "71518920",
"type": "ACCOUNT_NUMBER"
}
],
"payInReference": "Ref1249944"
}
}
],
"forwardedData": [ ]
}

Create Account

Create a new virtual account

Request

Security:

basicAuth

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Request Body schema: application/json;charset=UTF-8

nickname required	string Reference that can be provided in order to help with identification of the account
currency required	string Three-letter ISO 4217 currency code

Responses

201

Created

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

post/virtual-accounts/accounts

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Account Example Request

{"nickname": "MyAccount123",
"currency": "GBP"
}

Response samples

application/json

Create Account Example Response

{"meta": {"tracingId": "sd2ad0343-a141-4143-8756-a3a3cefrt31c",
"count": 1
},
"data": {"id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
"createdDateTime": "2020-04-24T00:30:19.951Z",
"status": "PENDING",
"nickname": "MyAccount123",
"currency": "GBP",
"balances": [{"type": "INTERIM_AVAILABLE",
"balanceAmount": {"amount": 0,
"currency": "GBP"
}
},
{"type": "INTERIM_BOOKED",
"balanceAmount": {"amount": 0,
"currency": "GBP"
}
}
]
},
"forwardedData": [ ]
}

Create Pay Out

Initiate a payment from a specified virtual account to a previously added beneficiary using any of the schemes that it supports
When subscribed to virtualAccount.payOut.status notifications, further updates on payment processing status will be delivered asynchronously

Request

Security:

basicAuth

header Parameters

idempotency-key required	string Uniquely identifies a request, such that requests made with a same value are considered retries We recommend that a v4 UUID is supplied Example: a346fe67-1d81-4ccd-8409-bf9d6c07980f
client-id required	string <uuid> The customer or sub-customer ID. Identifies the customer to perform the request for Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Request Body schema: application/json;charset=UTF-8

accountId required	string Unique id of the source / payer account
required	object Mandatory. Monetary Amount.
reference required	string Reference to be associated with the payment. This will be appear on the beneficiary's bank statement
beneficiaryId required	string Unique id of the beneficiary to whom the payment will be made
paymentScheme required	string Method of settlement to complete the payment. One of: FASTER_PAYMENTS SEPA_CREDIT SEPA_INSTANT SWIFT SWIFT_EXPRESS CHAPS IAT WIRE
paymentDate	string <date> Date on which a payment instruction will be executed, that must be in the future

Responses

201

Created

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

post/virtual-accounts/payments/pay-outs

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Pay Out Example Request

{"accountId": "eb2ad083-a111-4143-8756-a3a3cef4031c",
"amount": {"amount": 10.5,
"currency": "GBP"
},
"reference": "Invoice 1267765",
"beneficiaryId": "sd6ad034-a111-4143-8756-a3a3cef4045v",
"paymentScheme": "FASTER_PAYMENTS",
"paymentDate": "2022-08-28"
}

Response samples

application/json

Create Pay Out Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "za2ad0234-a333-5435-8787-a3a3cef4031c",
"createdDateTime": "2022-08-24T00:30:19.951Z",
"paymentDate": "2022-08-28",
"type": "PAY_OUT",
"paymentScheme": "FASTER_PAYMENTS",
"amount": {"amount": 10.5,
"currency": "GBP"
},
"reference": "Invoice 1267765",
"status": "INITIATED",
"source": {"type": "ACCOUNT",
"accountId": "eb2ad083-a111-4143-8756-a3a3cef4031c"
},
"destination": {"type": "BENEFICIARY",
"beneficiaryId": "sd6ad034-a111-4143-8756-a3a3cef4045v"
}
}
}

Get Account

Get the details of a specific account using its Id

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The Id of the account.

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

404

Not Found. Resource requested is not found.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/accounts/{accountId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/accounts/{accountId}' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get Account By Id Example Response

{"meta": {"tracingId": "sd2ad0343-a141-4143-8756-a3a3cefrt31c",
"count": 1
},
"data": {"id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
"createdDateTime": "2020-04-24T00:30:19.951Z",
"status": "ACTIVE",
"nickname": "MyAccount123",
"currency": "GBP",
"balances": [{"type": "INTERIM_AVAILABLE",
"balanceAmount": {"amount": 10.5,
"currency": "GBP"
}
},
{"type": "INTERIM_BOOKED",
"balanceAmount": {"amount": 10.5,
"currency": "GBP"
}
}
],
"bankAccount": {"currency": "GBP",
"bankName": "Lloyds Bank",
"bankAddress": "WE12 ABC",
"bankCountry": "GB",
"accountIdentifications": [{"identification": "401016",
"type": "SORT_CODE"
},
{"identification": "71518920",
"type": "ACCOUNT_NUMBER"
}
],
"payInReference": "Ref1249944"
}
},
"forwardedData": [ ]
}

Update Account

Update the details of a specific account using its Id

Request

Security:

basicAuth

path Parameters

accountId

required

string

Mandatory. The Id of the account.

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Request Body schema: application/json;charset=UTF-8

nickname	string New reference that can be provided in order to help with identification of the account
status	string New state of the Account: CLOSED - The account has been permanently closed and cannot be used

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

404

Not Found. Resource requested is not found.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

patch/virtual-accounts/accounts/{accountId}

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Update Account Example Request

{"nickname": "MyAccount456",
"status": "CLOSED"
}

Response samples

application/json

Update Account By Id Example Response

{"meta": {"tracingId": "sd2ad0343-a141-4143-8756-a3a3cefrt31c",
"count": 1
},
"data": {"id": "eb2ad083-a111-4143-8756-a3a3cef4031c",
"createdDateTime": "2020-04-24T00:30:19.951Z",
"status": "ACTIVE",
"nickname": "MyAccount123",
"currency": "GBP",
"balances": [{"type": "INTERIM_AVAILABLE",
"balanceAmount": {"amount": 10.5,
"currency": "GBP"
}
},
{"type": "INTERIM_BOOKED",
"balanceAmount": {"amount": 10.5,
"currency": "GBP"
}
}
],
"bankAccount": {"currency": "GBP",
"bankName": "Lloyds Bank",
"bankAddress": "WE12 ABC",
"bankCountry": "GB",
"accountIdentifications": [{"identification": "401016",
"type": "SORT_CODE"
},
{"identification": "71518920",
"type": "ACCOUNT_NUMBER"
}
],
"payInReference": "Ref1249944"
}
},
"forwardedData": [ ]
}

Get Payments

Retrieve a list of virtual account payments

Request

Security:

basicAuth

query Parameters

accountId	string Optional. Filter payments based on accountId Example: accountId=eb2ad083-a111-4143-8756-a3a3cef4031c
createdDateTimeFrom	string <date-time> Optional. Filter payments based on the createdDateTime Example: createdDateTimeFrom=2022-04-24T00:30:19.951Z
createdDateTimeTo	string <date-time> Optional. Filter payments based on the createdDateTime Example: createdDateTimeTo=2022-04-24T00:30:19.951Z
status	Array of strings Optional. Filter payments based on the payment status. One of INITIATED, PENDING, PROCESSING, COMPLETED, FAILED Example: status=INITIATED&status=COMPLETED
type	Array of strings Optional. Filter payments based on the payment type. One of PAY_IN, PAY_OUT, RETURN_IN, RETURN_OUT Example: type=PAY_IN&type=PAY_OUT
cursor	string Optional. Data required to provide pagination

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/payments

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/payments?accountId=string&createdDateTimeFrom=2020-04-24T00%3A30%3A19.951Z&createdDateTimeTo=2020-04-24T00%3A30%3A19.951Z&status=string&type=string&cursor=string' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get List of Payments Example Response

{"meta": {"tracingId": "sd2ad0343-a141-4143-8756-a3a3cefrt31c",
"count": 1
},
"links": {"self": "2",
"first": "0",
"last": "7",
"next": "3",
"previous": "1"
},
"data": [{"id": "za2ad0234-a333-5435-8787-a3a3cef4031c",
"createdDateTime": "2022-08-24T00:30:19.951Z",
"paymentDate": "2022-08-28",
"type": "PAY_OUT",
"paymentScheme": "FASTER_PAYMENTS",
"amount": {"amount": 10.5,
"currency": "GBP"
},
"reference": "Invoice 1267765",
"status": "INITIATED",
"source": {"type": "ACCOUNT",
"accountId": "eb2ad083-a111-4143-8756-a3a3cef4031c"
},
"destination": {"type": "BENEFICIARY",
"beneficiaryId": "sd6ad034-a111-4143-8756-a3a3cef4045v"
}
}
],
"forwardedData": [ ]
}

Get Payment

Get the details of a specific payment using its Id

Request

Security:

basicAuth

path Parameters

required

string

Mandatory. The id of the payment

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

404

Not Found. Requested payment is not found.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/payments/{id}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/payments/{id}' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get Payment Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "za2ad0234-a333-5435-8787-a3a3cef4031c",
"createdDateTime": "2022-08-24T00:30:19.951Z",
"paymentDate": "2022-08-28",
"type": "PAY_OUT",
"paymentScheme": "FASTER_PAYMENTS",
"amount": {"amount": 10.5,
"currency": "GBP"
},
"reference": "Invoice 1267765",
"status": "INITIATED",
"source": {"type": "ACCOUNT",
"accountId": "eb2ad083-a111-4143-8756-a3a3cef4031c"
},
"destination": {"type": "BENEFICIARY",
"beneficiaryId": "sd6ad034-a111-4143-8756-a3a3cef4045v"
}
}
}

Create Virtual Account Transfer

Create a transfer between two virtual accounts

Request

Security:

basicAuth

header Parameters

idempotency-key required	string Uniquely identifies a request, such that requests made with a same value are considered retries We recommend that a v4 UUID is supplied Example: a346fe67-1d81-4ccd-8409-bf9d6c07980f
client-id required	string <uuid> The customer or sub-customer ID. Identifies the customer to perform the request for Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Request Body schema: application/json;charset=UTF-8

required	object Mandatory. Monetary Amount.
reference required	string Reference to be associated with the transfer. This will be appear on the destination's bank statement
required	object (VirtualAccountTransferSource)
required	object (VirtualAccountTransferDestination)

Responses

201

Created

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

post/virtual-accounts/payments/transfers

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Transfer Example Request

{"amount": {"amount": 10.5,
"currency": "GBP"
},
"source": {"accountId": "a346fe67-1d81-4ccd-8409-bf9d6c07980f"
},
"destination": {"accountId": "e3465e67-1d81-4ccd-8409-tf9d6c07980r"
},
"reference": "Ref 86543"
}

Response samples

application/json

Create Transfer Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "za2ad0234-a333-5435-8787-a3a3cef4031c",
"createdDateTime": "2022-08-24T00:30:19.951Z",
"type": "TRANSFER",
"amount": {"amount": 10.5,
"currency": "GBP"
},
"reference": "Invoice 1267765",
"status": "INITIATED",
"source": {"type": "ACCOUNT",
"accountId": "eb2ad083-a111-4143-8756-a3a3cef4031c"
},
"destination": {"type": "ACCOUNT",
"accountId": "sd6ad034-a111-4143-8756-a3a3cef4045v"
}
}
}

Get Pay-In Details

Get the details of a pay-in transaction

Request

Security:

basicAuth

path Parameters

paymentId

required

string

Uniquely identifies a transaction

Example: 8b66abb5-5412-4454-aa7b-4e693ada6321

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

404

Not Found. Requested beneficiary is not found.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/payments/{paymentId}/pay-in-details

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/payments/{paymentId}/pay-in-details' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Create Pay-in Details Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "96169af01d394ad39658f17d53b49a5d",
"paymentScheme": "FASTER_PAYMENTS",
"amount": {"amount": 10,
"currency": "GBP"
},
"reference": "My part of meal",
"source": {"type": "EXTERNAL",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "401016"
},
{"type": "ACCOUNT_NUMBER",
"identification": "71518920"
},
{"type": "BIC",
"identification": "BUKBGB22"
}
]
},
"name": "Sam Sender",
"address": "10 Old Street"
}
}

Create Virtual Account Client

Create a new virtual account client (individual or business client). Available for clients who have direct onboarding permissions only. Please contact your CSM to enquire about access

Request

Security:

basicAuth

header Parameters

client-id

required

string <uuid>

Mandatory. This must be your master client-id (and not one associated with one of your clients)

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Request Body schema: application/json;charset=UTF-8

type required	string (VirtualAccountClientType) Enum: "INDIVIDUAL" "BUSINESS"
	object (VirtualAccountIndividualClient)
	object (VirtualAccountBusinessClient)

Responses

201

Created

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

post/virtual-accounts/clients

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Virtual Account Business Client Example Request

{"type": "BUSINESS",
"business": {"name": "Payments ltd company",
"type": "LIMITED_LIABILITY",
"registrationNumber": "1234567",
"contactName": "James Edward Rhodes",
"email": "james.rhodes@example.com",
"phone": "447006783009",
"registeredAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
},
"tradingAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
}
}
}

Response samples

application/json

Create Virtual Account Business Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "a2d43be3-972a-4458-9b6b-84ac15ae5287",
"type": "BUSINESS",
"business": {"name": "Payments ltd company",
"type": "LIMITED_LIABILITY",
"registrationNumber": "1234567",
"contactName": "James Edward Rhodes",
"email": "james.rhodes@example.com",
"phone": "447006783009",
"registeredAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
},
"tradingAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
}
},
"status": "ACTIVE",
"kycStatus": "VERIFIED",
"createdDateTime": "2022-08-11T00:00:00Z"
}
}

Get List of Virtual Account Clients

Get Virtual Account Clients (individual or business client).

Request

Security:

basicAuth

query Parameters

type	string Optional. Filter clients based on client type. One of BUSINESS or INDIVIDUAL Example: type=BUSINESS
status	string Optional. Filter clients based on client status. One of ACTIVE, PENDING or SUSPENDED Example: status=ACTIVE
cursor	string Optional. Data required to provide pagination

header Parameters

client-id

required

string <uuid>

Mandatory. This must be your master client-id (and not one associated with one of your clients)

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occured during interaction with a third party provider

500

Unexpected Error

get/virtual-accounts/clients

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/clients?type=string&status=string&cursor=string' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get Virtual Account Clients Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"links": {"self": "https://api.yapily.com/virtual-accounts/clients?cursor=cGFnZT0wJnNpemU9MTAwMCZzb3J0PWNyZWF0ZWREYXRlLGRlc2M=",
"first": "https://api.yapily.com/virtual-accounts/clients?cursor=cGFnZT0wJnNpemU9MTAwMCZzb3J0PWNyZWF0ZWREYXRlLGRlc2M=",
"last": "https://api.yapily.com/virtual-accounts/clients?cursor=cGFnZT0wJnNpemU9MTAwMCZzb3J0PWNyZWF0ZWREYXRlLGRlc2M=",
"next": "https://api.yapily.com/virtual-accounts/clients?cursor=cGFnZT0wJnNpemU9MTAwMCZzb3J0PWNyZWF0ZWREYXRlLGRlc2M=",
"previous": "https://api.yapily.com/virtual-accounts/clients?cursor=cGFnZT0wJnNpemU9MTAwMCZzb3J0PWNyZWF0ZWREYXRlLGRlc2M="
},
"data": [{"id": "a2d43be3-972a-4458-9b6b-84ac15ae5287",
"type": "BUSINESS",
"business": {"name": "Payments ltd company",
"type": "LIMITED_LIABILITY",
"registrationNumber": "1234567",
"contactName": "James Edward Rhodes",
"email": "james.rhodes@example.com",
"phone": "447006783009",
"registeredAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
},
"tradingAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
}
},
"status": "ACTIVE",
"kycStatus": "VERIFIED",
"createdDateTime": "2022-08-11T00:00:00Z"
},
{"id": "a2d43be3-972a-4458-9b6b-84ac15ae5283",
"type": "INDIVIDUAL",
"individual": {"firstName": "James",
"middleName": "Edward",
"lastName": "Rhodes",
"email": "james.rhodes@example.com",
"phone": "447006783009",
"birthDate": "1970-07-10",
"address": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
}
},
"status": "ACTIVE",
"kycStatus": "VERIFIED",
"createdDateTime": "2022-08-11T00:00:00Z"
}
]
}

Create Refund

Create a refund for a payment received into a virtual account. Funds are returned to the source account. When subscribed to virtualAccount.refund.status notifications, updates on the refund status are delivered asynchronously.

Request

Security:

basicAuth

header Parameters

idempotency-key required	string Uniquely identifies a request, such that requests made with a same value are considered retries We recommend that a v4 UUID is supplied Example: a346fe67-1d81-4ccd-8409-bf9d6c07980f
client-id required	string <uuid> The customer or sub-customer ID. Identifies the customer to perform the request for Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Request Body schema: application/json;charset=UTF-8

required	object (VirtualAccountOriginalPayment)
	object Mandatory. Monetary Amount.
reason	string Reason for the refund. Allowed values [REQUESTED_BY_CUSTOMER, DUPLICATE_PAYMENT, OTHER]
paymentDate	string <date> The date that the refund instruction will be executed. Must be in the present or future
reference	string Reference to be associated with the refund. This will appear on the beneficiary's bank statement
refundTo required	string Indicates which account will be used for refund. Allowed value: SOURCE
refundToOriginalPayer	boolean Conditional. This field is required when refundTo is BENEFICIARY. Indicates if the refund is back to the original payer. Allowed value: true
beneficiaryType	string Conditional. This field is required when refundTo is SOURCE. Indicates the type of Beneficiary as either an INDIVIDUAL or BUSINESS.
	object Not yet supported

Responses

201

Created

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

post/virtual-accounts/refunds

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Refund Example Request

{"originalPayment": {"paymentInitiationId": "19d2fbfb-f30c-44eb-b3b5-978560d2b712"
},
"amount": {"amount": 100,
"currency": "GBP"
},
"reason": "REQUESTED_BY_CUSTOMER",
"paymentDate": "2022-11-11",
"reference": "Refund 123",
"refundTo": "SOURCE",
"beneficiaryType": "INDIVIDUAL"
}

Response samples

application/json

Create Virtual Account Refund Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "46d3349e-6733-459d-a6da-71850a7e8076",
"originalPayment": {"paymentInitiationId": "19d2fbfb-f30c-44eb-b3b5-978560d2b712"
},
"status": "INITIATED",
"amount": {"amount": 100,
"currency": "GBP"
},
"reason": "REQUESTED_BY_CUSTOMER",
"paymentDate": "2022-11-11",
"reference": "Refund 123",
"refundTo": "SOURCE",
"beneficiaryType": "INDIVIDUAL",
"createdDateTime": "2022-11-11T15:00:57.345Z",
"updatedDateTime": "2022-11-11T14:00:57.751Z"
}
}

Get list of refunds

Retrieve a list of refunds

Request

Security:

basicAuth

query Parameters

paymentInitiationId	string Optional. Filter refunds based on unique ID of the original payment Example: paymentInitiationId=PDC_29bd8528-9b6f-4b6e-a963-9382944dc830
status	string Optional. Filter refunds based on refund status. One of INITIATED, SCHEDULED, PROCESSING, COMPLETED, FAILED Example: status=PROCESSING
createdDateTimeAfter	string <date-time> Optional. Filter to get refunds created on or after this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ) Example: createdDateTimeAfter=2023-01-13T16:41:51.136085Z
createdDateTimeBefore	string <date-time> Optional. Filter to get refunds created on or before this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ) Example: createdDateTimeBefore=2023-02-13T16:41:51.136085Z
cursor	string Optional. Encoded pagination cursor to fetch next page Example: cursor=cGF5bWVudEluaXRpYXRpb25JZD1QRENfMjliZDg1MjgtOWI2Zi00YjZlLWE5NjMtOTM4Mjk0NGRjODMwJnN0YXR1cz1GQUlMRUQmY3JlYXRlZERhdGVUaW1lRnJvbT0yMDIzLTAxLTEzVDE2OjQxOjUxLjEzNjA4NVomY3JlYXRlZERhdGVUaW1lVG89MjAyMy0wMi0xMFQxODo0Mjo1MS4xMzYwODVaJnBvaW50ZXI9MjAyMy0wMS0xM1QxNjo0MTo1MS4xMzYwODU=

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/refunds

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/refunds?paymentInitiationId=string&status=string&createdDateTimeAfter=2019-08-24T14%3A15%3A22Z&createdDateTimeBefore=2019-08-24T14%3A15%3A22Z&cursor=string' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get Virtual Account Refunds Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"links": {"next": "https://api.yapily.com/virtual-accounts/refunds?cursor=cGF5bWVudEluaXRpYXRpb25JZD1QRENfMjliZDg1MjgtOWI2Zi00YjZlLWE5NjMtOTM4Mjk0NGRjODMwJnN0YXR1cz1GQUlMRUQmY3JlYXRlZERhdGVUaW1lRnJvbT0yMDIzLTAxLTEzVDE2OjQxOjUxLjEzNjA4NVomY3JlYXRlZERhdGVUaW1lVG89MjAyMy0wMi0xMFQxODo0Mjo1MS4xMzYwODVaJnBvaW50ZXI9MjAyMy0wMS0xM1QxNjo0MTo1MS4xMzYwODU="
},
"data": [{"id": "46d3349e-6733-459d-a6da-71850a7e8076",
"originalPayment": {"paymentInitiationId": "19d2fbfb-f30c-44eb-b3b5-978560d2b712"
},
"status": "INITIATED",
"amount": {"amount": 100,
"currency": "GBP"
},
"reason": "REQUESTED_BY_CUSTOMER",
"paymentDate": "2022-11-11",
"reference": "Refund 123",
"refundTo": "SOURCE",
"refundToOriginalPayer": true,
"beneficiaryType": "INDIVIDUAL",
"createdDateTime": "2022-11-11T15:00:57.345Z",
"updatedDateTime": "2022-11-11T14:00:57.751Z"
}
]
}

Get Refund By Id

Get the details of a refund by its ID

Request

Security:

basicAuth

path Parameters

required

string

Mandatory. The id of the refund

header Parameters

client-id

required

string <uuid>

The customer or sub-customer ID. Identifies the customer to perform the request for

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/refunds/{id}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/refunds/{id}' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get Virtual Account Refund By ID Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "46d3349e-6733-459d-a6da-71850a7e8076",
"originalPayment": {"paymentInitiationId": "19d2fbfb-f30c-44eb-b3b5-978560d2b712"
},
"status": "INITIATED",
"amount": {"amount": 100,
"currency": "GBP"
},
"reason": "REQUESTED_BY_CUSTOMER",
"paymentDate": "2022-11-11",
"reference": "Refund 123",
"refundTo": "SOURCE",
"beneficiaryType": "INDIVIDUAL",
"beneficiaryId": "sd6ad034-a111-4143-8756-a3a3cef4045v",
"createdDateTime": "2022-11-11T15:00:57.345Z",
"updatedDateTime": "2022-11-11T14:00:57.751Z"
}
}

Get a Virtual Account Client by ID

Get a Virtual Account Client using its ID. Restricted to applications with direct onboarding permissions only

Request

Security:

basicAuth

path Parameters

clientId

required

string

Mandatory. The ID of the client.

header Parameters

client-id

required

string <uuid>

Mandatory. This must be your master client-id (and not one associated with one of your clients)

Example: 5a7294ab-6b7d-4681-835a-f9b9775c75db

Responses

200

Success

400

Bad Request.

401

Unauthorised. Credentials are missing or invalid

403

Forbidden. Permission to access this endpoint is not granted.

404

Not Found. Resource requested is not found.

424

A failure occurred during an interaction with a third party provider.

500

Unexpected Error.

get/virtual-accounts/clients/{clientId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/virtual-accounts/clients/{clientId}' \
  -H 'client-id: 497f6eca-6276-4993-bfeb-53cbbbba6f08'

Response samples

application/json

Get Virtual Account Client By Id Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "a2d43be3-972a-4458-9b6b-84ac15ae5287",
"type": "BUSINESS",
"business": {"name": "Payments ltd company",
"type": "LIMITED_LIABILITY",
"registrationNumber": "1234567",
"contactName": "James Edward Rhodes",
"email": "james.rhodes@example.com",
"phone": "447006783009",
"registeredAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
},
"tradingAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
}
},
"status": "ACTIVE",
"kycStatus": "VERIFIED",
"createdDateTime": "2022-08-11T00:00:00Z"
}
}

Variable Recurring Payments

Variable Recurring Payments enables transfer of money between accounts held by the same person or transfer of money for business payments.

In order to make Sweeping Variable Recurring Payments on behalf of a user, you are required to request an Consent from the user by calling the Sweeping Consent endpoint to authorise the user's account to make the payment. Once a consent-token is obtained, you can call the Payments endpoint to execute the Sweeping Variable Recurring Payments transaction. Before executing the payment, you have the option to confirm availability of funds in the user's account by calling the Funds Confirmation endpoint.

See VRP Payments for more information.

Create Sweeping Variable Recurring Payment Authorisationbeta

Used to initiate the authorisation process and direct users to the login screen of their financial Institution in order to give their consent for Sweeping Variable Recurring Payments. The request would return an Authorization URL and an Identifier for the consent created at the Institution. 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:

INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_SWEEPING

Request

Security:

basicAuth

Request Body schema: application/json;charset=UTF-8

userId	string <uuid> This is the Yapily user identifier for the user returned by the create user step POST ../users
applicationUserId	string A client's own user reference. If the client wants to work with their own unique references for individual PSUs then they can use the applicationUserId property to provide that value. Where Yapily does not already have a Yapily userId that matches the supplied applicationUserId, then a new Yapily userId is created automatically and linked to the applicationUserId value. Clients can then use either their own applicationUserId or the Yapily userId to reference the same user in future calls.
forwardParameters	Array of strings Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
contextType	string (Payment Code) Default: "OTHER" Optional. The payment context code. This defaults to `OTHER` if not specified. Enum: "BILL" "GOODS" "SERVICES" "OTHER" "PERSON_TO_PERSON" … 7 more
institutionId required	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.
	object (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.
required	object (SweepingControlParameters) Define the restrictions and limits for payment orders as part of Sweeping VRP consent
required	object (InitiationDetails) Mandatory. The payment initiation object defining the details of the payment under the Variable Recurring Payment consent.
	object (ComplianceData) Conditional. Information needed to complete compliance checks. Mandatory for Yapily Connect customers.

Responses

201

Created

401

Error Response

default

Error Response

post/variable-recurring-payments/sweeping/consents

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

UK Domestic Sweeping VRP Authorisation Example Request

{"applicationUserId": "string",
"institutionId": "modelo-sandbox",
"callback": "https://display-parameters.com/",
"controlParameters": {"psuAuthenticationMethods": ["SCA_NOT_REQUIRED"
],
"periodicLimits": [{"totalMaxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "DAILY",
"alignment": "CONSENT"
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
}
},
"initiationDetails": {"reference": "Own Account Sweeping",
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"payee": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
}
},
"complianceData": {"payer": {"type": "INDIVIDUAL",
"individual": {"name": "John Doe",
"birthDate": "2000-08-12"
}
}
}
}

Response samples

201
401
default

application/json;charset=UTF-8

UK Domestic Sweeping VRP Authorisation Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "a2a9ec77-a479-4996-9896-4568e1968e7a",
"userId": "5350782b-60f3-489e-aae5-a24d8d679a07",
"applicationUserId": "string",
"institutionId": "modelo-sandbox",
"status": "AWAITING_AUTHORIZATION",
"createdAt": "2021-06-09T13:48:25.138Z",
"featureScope": ["EXISTING_PAYMENTS_DETAILS",
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_SWEEPING",
"VARIABLE_RECURRING_PAYMENT_FUNDS_CONFIRMATION",
"INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_SWEEPING"
],
"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",
"controlParameters": {"psuAuthenticationMethods": ["SCA_NOT_REQUIRED"
],
"periodicLimits": [{"totalMaxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "DAILY",
"alignment": "CONSENT"
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
}
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"initiationDetails": {"reference": "Own Account Sweeping",
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"payee": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
}
}
}
}

Create Non-Sweeping Variable Recurring Payment Authorisationbeta

Used to initiate the authorisation process and direct users to the login screen of their financial Institution in order to give their consent for Non-Sweeping Variable Recurring Payments. The request would return an Authorization URL and an Identifier for the consent created at the Institution. 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:

INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_NONSWEEPING

Request

Security:

basicAuth

Request Body schema: application/json;charset=UTF-8

userId	string <uuid> This is the Yapily user identifier for the user returned by the create user step POST ../users
applicationUserId	string A client's own user reference. If the client wants to work with their own unique references for individual PSUs then they can use the applicationUserId property to provide that value. Where Yapily does not already have a Yapily userId that matches the supplied applicationUserId, then a new Yapily userId is created automatically and linked to the applicationUserId value. Clients can then use either their own applicationUserId or the Yapily userId to reference the same user in future calls.
forwardParameters	Array of strings Extra parameters the TPP may want to get forwarded in the callback request after the PSU redirect.
contextType	string (Payment Code) Optional. The payment context code. Allowed values are [BILL_IN_ADVANCE, BILL_IN_ARREARS, ECOMMERCE_MERCHANT, FACE_TO_FACE_POS, TRANSFER_TO_SELF,TRANSFER_TO_THIRD_PARTY, PISP_PAYEE ].
institutionId required	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.
	object (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.
required	object (NonSweepingControlParameters) Define the restrictions and limits for payment orders as part of Non-Sweeping VRP consent
required	object (InitiationDetails) Mandatory. The payment initiation object defining the details of the payment under the Variable Recurring Payment consent.
	object (ComplianceData) Conditional. Information needed to complete compliance checks. Mandatory for Yapily Connect customers.

Responses

201

Created

401

Error Response

default

Error Response

post/variable-recurring-payments/non-sweeping/consents

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

UK Domestic Non-Sweeping VRP Authorisation Example Request

{"applicationUserId": "string",
"institutionId": "modelo-sandbox",
"callback": "https://display-parameters.com/",
"controlParameters": {"psuAuthenticationMethods": ["SCA_NOT_REQUIRED"
],
"periodicLimits": [{"totalMaxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "DAILY",
"alignment": "CONSENT",
"maxNumberOfPayments": 1
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
},
"maxCumulativeAmount": {"amount": 100,
"currency": "GBP"
},
"maxCumulativeNumberOfPayments": 10,
"recurringPaymentCategory": "ONGOING"
},
"initiationDetails": {"reference": "Bill Payment",
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"payee": {"name": "Thames Water",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
}
},
"complianceData": {"payer": {"type": "BUSINESS",
"business": {"name": "Company LTD",
"registrationNumber": "COM123NO",
"registeredAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
},
"tradingAddress": {"addressLine1": "123 Queens Street",
"addressLine2": "Unit 13",
"townName": "York",
"postCode": "12345",
"country": "GB"
}
}
}
}
}

Response samples

201
401
default

application/json;charset=UTF-8

UK Domestic Non-Sweeping VRP Authorisation Example Response

{"meta": {"tracingId": "96169af01d394ad39658f17d53b49a5d"
},
"data": {"id": "a2a9ec77-a479-4996-9896-4568e1968e7a",
"userId": "5350782b-60f3-489e-aae5-a24d8d679a07",
"applicationUserId": "string",
"institutionId": "modelo-sandbox",
"status": "AWAITING_AUTHORIZATION",
"createdAt": "2021-06-09T13:48:25.138Z",
"featureScope": ["EXISTING_PAYMENTS_DETAILS",
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_NONSWEEPING",
"VARIABLE_RECURRING_PAYMENT_FUNDS_CONFIRMATION",
"INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_NONSWEEPING"
],
"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",
"controlParameters": {"psuAuthenticationMethods": ["SCA_NOT_REQUIRED"
],
"periodicLimits": [{"totalMaxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "DAILY",
"alignment": "CONSENT",
"maxNumberOfPayments": 1
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
},
"maxCumulativeAmount": {"amount": 100,
"currency": "GBP"
},
"maxCumulativeNumberOfPayments": 10,
"recurringPaymentCategory": "ONGOING"
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"initiationDetails": {"reference": "Bill Payment",
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"payee": {"name": "Thames Water",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
}
}
}
}

Create Variable Recurring Paymentbeta

Creates a Variable Recurring Payment transaction after obtaining the user's authorisation.

Features:

CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_SWEEPING
CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_NONSWEEPING

Request

Security:

basicAuth

header Parameters

consent

required

string

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

Example: {consentToken}

Request Body schema: application/json;charset=UTF-8

paymentIdempotencyId required	string Mandatory. A unique identifier that you must provide to identify the payment. This can be any alpha-numeric string but is limited to a maximum of 35 characters.
psuAuthenticationMethod required	string Mandatory. Chosen authentication method for submission step. Allowed values are [SCA_REQUIRED, SCA_NOT_REQUIRED].
contextType	string (Payment Code) Default: "OTHER" Optional. The payment context code. This defaults to `OTHER` if not specified. Enum: "BILL" "GOODS" "SERVICES" "OTHER" "PERSON_TO_PERSON" … 7 more
required	object (Amount Details) Mandatory. Monetary Amount.

Responses

201

Created

401

Error Response

default

Error Response

post/variable-recurring-payments/payments

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

UK Domestic VRP Payment Example Request

{"paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
"psuAuthenticationMethod": "SCA_NOT_REQUIRED",
"paymentAmount": {"amount": 10,
"currency": "GBP"
}
}

Response samples

201
401
default

application/json;charset=UTF-8

UK Domestic VRP Payment Example Response

{"meta": {"tracingId": "0f14e900011b445fa6b6c2c4272d7321"
},
"data": {"id": "a9582f8e-08be-4cca-9f01-1ad3be96532d",
"paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
"institutionConsentId": "PF23232222DD",
"status": "COMPLETED",
"statusDetails": {"status": "COMPLETED",
"isoStatus": {"code": "ACCP",
"name": "AcceptedCustomerProfile"
}
},
"initiationDetails": {"reference": "Own Account Sweeping",
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"payee": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
}
},
"submissionDetails": {"reference": "Own Account Sweeping",
"payee": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
},
"paymentAmount": {"amount": 10,
"currency": "GBP"
}
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"refundAccount": {"accountIdentifications": [{"identification": "400400",
"type": "SORT_CODE"
},
{"identification": "99999999",
"type": "ACCOUNT_NUMBER"
}
],
"name": "Refund Account"
},
"expectedSettlementTime": "2022-03-02T12:00:00.000Z",
"expectedExecutionTime": "2022-03-02T12:00:00.000Z"
}
}

Get Sweeping Variable Recurring Payment Consent Detailsbeta

Get Sweeping Variable Recurring Payments consent details using the consent Id

Request

Security:

basicAuth

path Parameters

consentId

required

string <uuid>

Mandatory. The consent Id of the Variable Recurring Payments Consent to retrieve.

Responses

200

401

Error Response

default

Error Response

get/variable-recurring-payments/sweeping/consents/{consentId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/variable-recurring-payments/sweeping/consents/{consentId}'

Response samples

200
401
default

application/json;charset=UTF-8

Get Sweeping Variable Recurring Payments Consent Example Response

{"meta": {"tracingId": "679e7bb6cd45416a9a9a8d004c5315da"
},
"data": {"id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
"userId": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
"applicationUserId": "string",
"institutionId": "modelo-sandbox",
"status": "AUTHORIZED",
"createdAt": "2021-06-08T10:59:35.138Z",
"featureScope": ["EXISTING_PAYMENTS_DETAILS",
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_SWEEPING",
"VARIABLE_RECURRING_PAYMENT_FUNDS_CONFIRMATION",
"INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_SWEEPING"
],
"consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjU2YTQyMjQ0LTQxNGEtNGI1Mi04YzRmLTRhZDJhNTBlODJmZSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJtb2ZlLTIiLCJVU0VSIjoiY2E0MTJmZGYtNWEzMC00M2EyLTg4YjctNTk2NGEyNGE4ZTU1In0.gorwpnUjSr5dzQJLR32M2geWOj7yK9xMsZmq27ssY9xP_xGmWfUL_aqVHYyQ4r5KWw6Xb6RjvO839st8chJLtg",
"state": "a09f8ff9c1284444aa635267e05f76e1",
"authorizedAt": "2021-06-08T10:59:53.288Z",
"institutionConsentId": "aac-605d48f2-2a0e-4594-81a9-996524fa3b2a",
"controlParameters": {"psuAuthenticationMethods": ["SCA_NOT_REQUIRED"
],
"periodicLimits": [{"totalMaxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "DAILY",
"alignment": "CONSENT"
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
}
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"initiationDetails": {"reference": "Own Account Sweeping",
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"payee": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
}
}
}
}

Get Non-Sweeping Variable Recurring Payment Consent Detailsbeta

Get Non-Sweeping Variable Recurring Payments consent details using the consent Id

Request

Security:

basicAuth

path Parameters

consentId

required

string <uuid>

Mandatory. The consent Id of the Variable Recurring Payments Consent to retrieve.

Responses

200

401

Error Response

default

Error Response

get/variable-recurring-payments/non-sweeping/consents/{consentId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/variable-recurring-payments/non-sweeping/consents/{consentId}'

Response samples

200
401
default

application/json;charset=UTF-8

Get Non-Sweeping Variable Recurring Payments Consent Example Response

{"meta": {"tracingId": "679e7bb6cd45416a9a9a8d004c5315da"
},
"data": {"id": "56a42244-414a-4b52-8c4f-4ad2a50e82fe",
"userId": "ca412fdf-5a30-43a2-88b7-5964a24a8e55",
"applicationUserId": "string",
"institutionId": "modelo-sandbox",
"status": "AUTHORIZED",
"createdAt": "2021-06-08T10:59:35.138Z",
"featureScope": ["EXISTING_PAYMENTS_DETAILS",
"EXISTING_PAYMENT_INITIATION_DETAILS",
"CREATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_NONSWEEPING",
"VARIABLE_RECURRING_PAYMENT_FUNDS_CONFIRMATION",
"INITIATE_DOMESTIC_VARIABLE_RECURRING_PAYMENT_NONSWEEPING"
],
"consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjU2YTQyMjQ0LTQxNGEtNGI1Mi04YzRmLTRhZDJhNTBlODJmZSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJtb2ZlLTIiLCJVU0VSIjoiY2E0MTJmZGYtNWEzMC00M2EyLTg4YjctNTk2NGEyNGE4ZTU1In0.gorwpnUjSr5dzQJLR32M2geWOj7yK9xMsZmq27ssY9xP_xGmWfUL_aqVHYyQ4r5KWw6Xb6RjvO839st8chJLtg",
"state": "a09f8ff9c1284444aa635267e05f76e1",
"authorizedAt": "2021-06-08T10:59:53.288Z",
"institutionConsentId": "aac-605d48f2-2a0e-4594-81a9-996524fa3b2a",
"controlParameters": {"psuAuthenticationMethods": ["SCA_NOT_REQUIRED"
],
"periodicLimits": [{"totalMaxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "DAILY",
"alignment": "CONSENT",
"maxNumberOfPayments": 10
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
},
"maxCumulativeAmount": {"amount": 100,
"currency": "GBP"
},
"maxCumulativeNumberOfPayments": 10
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"initiationDetails": {"reference": "Bill Payment",
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"payee": {"name": "Thames Water",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
}
}
}
}

Confirm Funds for Variable Recurring Paymentbeta

Confirms whether there are available funds on the Payer account to execute a Variable Recurring Payment after obtaining the user's authorisation.

Features:

VARIABLE_RECURRING_PAYMENT_FUNDS_CONFIRMATION

Request

Security:

basicAuth

header Parameters

consent

required

string

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

Example: {consentToken}

Request Body schema: application/json;charset=UTF-8

reference	string Optional. The payment reference or description. Limited to a maximum of 18 characters long.
required	object (Amount Details) Mandatory. Monetary Amount.

Responses

201

Created

401

Error Response

default

Error Response

post/variable-recurring-payments/funds-confirmation

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

UK Domestic VRP Funds Confirmation Example Request

{"reference": "Own Account Sweeping",
"paymentAmount": {"amount": 10,
"currency": "GBP"
}
}

Response samples

201
401
default

application/json;charset=UTF-8

UK Domestic VRP Funds Confirmation Example Response

{"meta": {"tracingId": "0f14e900011b445fa6b6c2c4272d7321"
},
"data": {"id": "a9582f8e-08be-4cca-9f01-1ad3be96532d",
"fundsAvailable": {"fundsAvailable": true,
"fundsAvailableAt": "2021-06-08T10:59:35.138Z"
},
"reference": "Own Account Sweeping",
"paymentAmount": {"amount": 10,
"currency": "GBP"
}
}
}

Get Variable Recurring Payment Detailsbeta

Get Variable Recurring Payment details using the Payment Id

Request

Security:

basicAuth

path Parameters

paymentId

required

string

Mandatory. The Payment Id of the Variable Recurring Payments to retrieve.

header Parameters

consent

required

string

Mandatory. The consent token containing the user's authorisation to make the Variable Recurring Payments request.

Responses

200

401

Error Response

default

Error Response

get/variable-recurring-payments/payments/{paymentId}/details

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/variable-recurring-payments/payments/{paymentId}/details' \
  -H 'consent: string'

Response samples

200
401
default

application/json;charset=UTF-8

Get Variable Recurring Payment Details Example Response

{"meta": {"tracingId": "679e7bb6cd45416a9a9a8d004c5315da"
},
"data": {"id": "a9582f8e-08be-4cca-9f01-1ad3be96532d",
"paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
"institutionConsentId": "PF23232222DD",
"status": "COMPLETED",
"statusDetails": {"status": "COMPLETED",
"isoStatus": {"code": "ACCP",
"name": "AcceptedCustomerProfile"
}
},
"initiationDetails": {"reference": "Own Account Sweeping",
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"payee": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
}
},
"submissionDetails": {"reference": "Own Account Sweeping",
"payee": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
},
{"type": "SORT_CODE",
"identification": "123456"
}
]
},
"paymentAmount": {"amount": 10,
"currency": "GBP"
}
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
},
{"type": "SORT_CODE",
"identification": "654321"
}
]
},
"refundAccount": {"accountIdentifications": [{"identification": "400400",
"type": "SORT_CODE"
},
{"identification": "99999999",
"type": "ACCOUNT_NUMBER"
}
],
"name": "Refund Account"
},
"expectedSettlementTime": "2022-03-02T12:00:00.000Z",
"expectedExecutionTime": "2022-03-02T12:00:00.000Z"
}
}

Hosted Pages

Hosted Pages endpoints for payments and data products

Create Hosted payment requestbeta

Used to initiate a payment request using Yapily Hosted Pages.

Request

Security:

basicAuth

Request Body schema: application/json;charset=UTF-8

userId	string <uuid> Conditional. Yapily Identifier for the `User` returned by the create user step POST /users. You must provide either a `userId` or `applicationUserId`.
applicationUserId	string Conditional. Your own `User` reference. This field allows you to use your own unique references for individual users. Where the `User` reference doesn't have an associated Yapily `userId`, a new `userId` is created and linked to it. You must provide either a `userId` or `applicationUserId`.
required	object (InstitutionIdentifiers) Specifies the institution requirements for making the payment. Skips the bank selection screen in payment flow if the `institutionId` and `institutionCountryCode` are provided.
	object (UserSettings) Specifies the language and location preferences of the user.
redirectUrl required	string URL of your server to redirect the user after completion of the payment flow.
required	object (HostedPaymentRequestDetails) Details of the payment.

Responses

201

Created

400

Bad Request

401

Unauthorized. Credentials are missing or invalid

500

Unexpected Error

default

Error Response

post/hosted/payment-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Hosted payment request

{"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"applicationUserId": "string",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"userSettings": {"language": "en",
"location": "GB"
},
"redirectUrl": "https://tpp-application.com/",
"paymentRequestDetails": {"paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
"amountDetails": {"amountToPay": 10,
"currency": "GBP"
},
"reference": "Test Payment",
"contextType": "OTHER",
"type": "DOMESTIC_PAYMENT",
"payee": {"name": "Jane Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "123456"
},
{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
}
]
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "121212"
},
{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
}
]
}
}
}

Response samples

201
400
401
500
default

application/json;charset=UTF-8

Create Hosted Payment Response

{"meta": {"tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
},
"data": {"paymentRequestId": "eb39f8ae-aeff-4ffa-a23d-d4a5b3eff406",
"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"applicationUserId": "string",
"applicationId": "64949de6-6510-4d70-9500-d4aa094c506c",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"userSettings": {"language": "en",
"location": "GB"
},
"redirectUrl": "https://tpp-application.com/",
"paymentRequestDetails": {"paymentIdempotencyId": "4289457hd38djoa783jw9qag3",
"amountDetails": {"amountToPay": 1,
"currency": "GBP"
},
"reference": "Test Payment",
"contextType": "OTHER",
"type": "DOMESTIC_PAYMENT",
"payee": {"name": "Jane Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "123456"
},
{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
}
]
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "121212"
},
{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
}
]
}
},
"hostedUrl": "https://prototypes.yapily.com/auth-link1.html",
"authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"createdAt": "2021-06-10T11:26:54.887Z",
"authorisationExpiresAt": "2021-06-10T11:36:54.887Z",
"status": "ACTIVE"
}
}

Create Pay By Linkbeta

Used to created a long lived payment request for Pay By Link

Request

Security:

basicAuth

Request Body schema: application/json;charset=UTF-8

userId	string <uuid> Conditional. Yapily Identifier for the `User` returned by the create user step POST /users. You must either provide `userId` or `applicationUserId`.
applicationUserId	string Conditional. Your own `User` reference. If you want to work with their own unique references for individual PSUs then you can use the `applicationUserId` property to provide that value. Where Yapily does not already have a Yapily userId that matches the supplied `applicationUserId`, then a new Yapily userId is created automatically and linked to the `applicationUserId` value. You must either provide userId or `applicationUserId`.
required	object (InstitutionIdentifiers) Specifies the institution requirements for making the payment. Skips the bank selection screen in payment flow if the `institutionId` and `institutionCountryCode` are provided.
	object (UserSettings) Specifies the language and location preferences of the user.
redirectUrl required	string URL of your server to redirect the user after completion of the payment flow.
authorisationExpiresAt	string <date-time> The date and time that the authorisation expires. Must be between 10 minutes and 30 days in the future. If not specified, the authorisation URL will expire 10 minutes after creation.
required	object (HostedPaymentRequestDetailsLink)

Responses

201

Created

400

Bad Request

401

Unauthorized. Credentials are missing or invalid

500

Unexpected Error

default

Error Response

post/hosted/payment-requests/links

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Hosted payment request

{"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"applicationUserId": "string",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"userSettings": {"language": "en",
"location": "GB"
},
"redirectUrl": "https://tpp-application.com/",
"paymentRequestDetails": {"amountDetails": {"amountToPay": 1,
"currency": "GBP"
},
"reference": "Test Payment",
"contextType": "OTHER",
"type": "DOMESTIC_PAYMENT",
"payee": {"name": "Jane Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "123456"
},
{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
}
]
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "121212"
},
{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
}
]
}
}
}

Response samples

201
400
401
500
default

application/json;charset=UTF-8

Create Hosted Payment Response

{"meta": {"tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
},
"data": {"paymentRequestId": "eb39f8ae-aeff-4ffa-a23d-d4a5b3eff406",
"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"applicationUserId": "string",
"applicationId": "64949de6-6510-4d70-9500-d4aa094c506c",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"userSettings": {"language": "en",
"location": "GB"
},
"redirectUrl": "https://tpp-application.com/",
"paymentRequestDetails": {"amountDetails": {"amountToPay": 10,
"currency": "GBP"
},
"reference": "Test Payment",
"contextType": "OTHER",
"type": "DOMESTIC_PAYMENT",
"payee": {"name": "Jane Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "123456"
},
{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
}
]
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "121212"
},
{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
}
]
}
},
"hostedUrl": "https://prototypes.yapily.com/auth-link1.html",
"authToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
"createdAt": "2021-06-10T11:26:54.887Z",
"authorisationExpiresAt": "2021-06-10T11:36:54.887Z",
"status": "ACTIVE"
}
}

Get Hosted payment requestbeta

Used to get details of a payment request

Request

Security:

basicAuth

path Parameters

paymentRequestId

required

string

Unique Identifier of the payment request

Responses

200

401

Unauthorized

404

Not Found

500

Unexpected Error

default

Error Response

get/hosted/payment-requests/{paymentRequestId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/hosted/payment-requests/{paymentRequestId}'

Response samples

200
401
404
500
default

application/json;charset=UTF-8

Get Hosted payment request Response

{"meta": {"tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
},
"data": {"paymentRequestId": "eb39f8ae-aeff-4ffa-a23d-d4a5b3eff406",
"userId": "3ddf5dd0-aa48-4d0f-baa7-fa057e9e911d",
"applicationUserId": "string",
"applicationId": "64949de6-6510-4d70-9500-d4aa094c506c",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"userSettings": {"language": "en",
"location": "GB"
},
"redirectUrl": "https://tpp-application.com/",
"paymentRequestDetails": {"amountDetails": {"amountToPay": 1,
"currency": "GBP"
},
"reference": "Test Payment",
"contextType": "OTHER",
"type": "DOMESTIC_PAYMENT",
"payee": {"name": "Jane Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "123456"
},
{"type": "ACCOUNT_NUMBER",
"identification": "12345678"
}
]
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "121212"
},
{"type": "ACCOUNT_NUMBER",
"identification": "87654321"
}
]
}
},
"createdAt": "2021-06-10T11:26:54.887Z",
"authorisationExpiresAt": "2021-06-10T11:36:54.887Z",
"status": "ACTIVE",
"payments": [{"paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"institutionIdentifiers": {"institutionId": "string",
"institutionCountryCode": "GB"
},
"userIdentifiers": {"psuId": "string",
"psuCorporateId": "string",
"psuIpAddress": "string"
},
"phases": [{"phaseName": "INITIATED",
"phaseCreatedAt": "2021-06-10T11:26:54.887Z"
},
{"phaseName": "INSTITUTION_SUBMITTED",
"phaseCreatedAt": "2021-06-10T11:26:55.123Z"
},
{"phaseName": "INPUT_CAPTURED",
"phaseCreatedAt": "2021-06-10T11:27:05.123Z"
},
{"phaseName": "VALIDATION_COMPLETED",
"phaseCreatedAt": "2021-06-10T11:27:05.223Z"
},
{"phaseName": "AUTHORISATION_CREATED",
"phaseCreatedAt": "2021-06-10T11:27:06.637Z"
},
{"phaseName": "AUTHORISED",
"phaseCreatedAt": "2021-06-10T11:27:10.637Z"
},
{"phaseName": "SUBMITTED",
"phaseCreatedAt": "2021-06-10T11:27:10.654Z"
},
{"phaseName": "ACCEPTED",
"phaseCreatedAt": "2021-06-10T11:27:11.867Z"
},
{"phaseName": "SETTLEMENT_COMPLETED",
"phaseCreatedAt": "2021-06-10T11:27:13.887Z"
}
],
"statusDetails": [{"status": "PENDING",
"statusUpdateDate": "2021-06-10T11:27:11.867Z",
"isoStatus": {"code": "PDNG",
"name": "Pending"
}
},
{"status": "COMPLETED",
"statusUpdateDate": "2021-06-10T11:27:13.887Z",
"isoStatus": {"code": "ACSC",
"name": "AcceptedSettlementCompleted"
}
}
],
"institutionPaymentId": "string",
"paymentLifecycleId": "string",
"paymentIdempotencyId": "04ab4536gaerfc0e1f93c4f4",
"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"
},
"payer": {"name": "John Doe",
"accountIdentifications": [{"type": "SORT_CODE",
"identification": "401016"
}
],
"address": {"country": "GB"
}
},
"amount": {"amount": 10,
"currency": "GBP"
}
}
]
}
}

Create VRP Consentbeta

Used to initiate a VRP consent / mandate request through Yapily Hosted Pages

Request

Security:

basicAuth

header Parameters

sub-application

required

string

Mandatory. The unique identifier of the sub application the request is being submitted on behalf of (e.g. an underlying merchant)

Request Body schema: application/json;charset=UTF-8

userId	string <uuid> Conditional. Yapily Identifier for the `User` returned by the create user step POST /users. Clients must either provide userId or applicationUserId.
applicationUserId	string Conditional. Client's own `User` reference. If the client wants to work with their own unique references for individual PSUs then they can use the applicationUserId property to provide that value. Where Yapily does not already have a Yapily userId that matches the supplied applicationUserId, then a new Yapily userId is created automatically and linked to the applicationUserId value. Clients must either provide userId or applicationUserId.
required	object (InstitutionIdentifiers) Specifies the institution requirements for making the payment. Skips the bank selection screen in payment flow if the `institutionId` and `institutionCountryCode` are provided.
	object (UserSettings) Specifies the language and location preferences of the user.
redirectUrl required	string URL of client's server to redirect the PSU after completion of the consent authorisation.
oneTimeToken	boolean Used to receive a oneTimeToken rather than a consentToken at the redirectUrl for additional security. This can only be used when the redirectUrl is set.
required	object (VRPSetupRequest)

Responses

201

Created

400

Bad Request

401

Unauthorized. Credentials are missing or invalid

500

Unexpected Error

post/hosted/vrp/consent-requests

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Hosted VRP Consent Request

{"applicationUserId": "45cf7ffe-6350-11ee-8c99-0242ac120002",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"userSettings": {"language": "en",
"location": "GB"
},
"redirectUrl": "https://tpp-application.com",
"vrpSetup": {"payee": {"name": "Merchant Doe",
"accountIdentifications": [{"identification": "401016",
"type": "SORT_CODE"
},
{"identification": "71518920",
"type": "ACCOUNT_NUMBER"
}
]
},
"reference": "Test Payment",
"limits": {"periodicLimits": [{"maxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CALENDAR"
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
}
},
"validFrom": "2023-10-04T16:41:17.870Z",
"validTo": "2024-10-04T16:41:17.870Z",
"recurringPaymentCategory": "ONGOING",
"risk": {"contextType": "ECOMMERCE_MERCHANT"
}
}
}

Response samples

application/json;charset=UTF-8

Create Hosted VRP Consent Response

{"meta": {"tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
},
"data": {"id": "ad4bfe58-6352-11ee-8c99-0242ac120002",
"applicationUserId": "45cf7ffe-6350-11ee-8c99-0242ac120002",
"applicationId": "ea4cdf01ee-278f-4e3e-8b30-695515aa4cdf01d64",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"userSettings": {"language": "en",
"location": "GB"
},
"redirectUrl": "https://tpp-application.com",
"vrpSetup": {"payee": {"name": "Merchant Doe",
"accountIdentifications": [{"identification": "401016",
"type": "SORT_CODE"
},
{"identification": "71518920",
"type": "ACCOUNT_NUMBER"
}
]
},
"reference": "Test Payment",
"limits": {"periodicLimits": [{"maxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CALENDAR"
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
}
},
"validFrom": "2023-10-04T16:41:17.870Z",
"validTo": "2024-10-04T16:41:17.870Z",
"risk": {"contextType": "ECOMMERCE_MERCHANT"
}
},
"hostedUrl": "https://payments.yapily.com/vrp?authToken=eyJra&applicationId=e5515aee-278f-4e3e-8b30-69a4cdf01d64",
"authToken": "eyJraWQiOiIwNmViZTQ1Yy1OiJFUzI1NiJ9.eyJhdWQiOiJwcm9kdWN0aW9uIiwic3ViIjoiZTU1MTVhZWUtMjc4Zi00ZTNlLThiMzAtNjlhNGNkZjAxZDY0Iiwib3JnIjoiYTUwZmEwNWUtNWIwYy00MGIxLTk0NWUtOTcxM2JkOGQzODk4IiwiY29uc2VudFJlcXVlc3RJZCI6IjdkMmMzZjU5LTU3NDgtNDhlNS1hODdjLWVkZmRkODJiMzQxZCIsImlzcyI6Imhvc3RlZC12cjgwMDE2NCwiaWF0IjoxNzA2Nzk5NTY0LCJqdGkiOiJjMTFkNTBkNy0wMjkxLTRhNTktYmFhNy1jZDhhYWIzMmYzOWIifQ.xa38HzD6phhFiR069E9nMrzvQ9GCmNZMQ",
"createdAt": "2024-02-01T14:59:25.007193Z"
}
}

Get Hosted VRP Consent Requestsbeta

Used to get all VRP consent requests initiated through Yapily Hosted Pages

Request

Security:

basicAuth

header Parameters

sub-application

required

string

Mandatory. The unique identifier of the sub application the request is being submitted on behalf of (e.g. an underlying merchant)

Responses

200

400

Bad Request

401

Unauthorized. Credentials are missing or invalid

500

Unexpected Error

get/hosted/vrp/consent-requests

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  https://api.yapily.com/hosted/vrp/consent-requests \
  -H 'sub-application: string'

Response samples

application/json;charset=UTF-8

Get Hosted VRP Consents Response

{"meta": {"tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
},
"data": [{"id": "ad4bfe58-6352-11ee-8c99-0242ac120002",
"applicationId": "45cf7ffe-6350-11ee-8c99-0242ac120002",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"vrpSetup": {"limits": {"periodicLimits": [{"maxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CALENDAR"
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
}
},
"recurringPaymentCategory": "ONGOING",
"risk": {"contextType": "ECOMMERCE_MERCHANT"
}
},
"updatedAt": "2023-10-05T07:56:44.552Z",
"consentStatus": "AUTHORIZED"
}
]
}

Get Hosted VRP Consent Requestbeta

Used to get details of a VRP Consent Request

Request

Security:

basicAuth

path Parameters

consentRequestId

required

string <uuid>

Unique Identifier of the Consent Request

header Parameters

sub-application

string

The unique identifier of the sub application the request is being submitted on behalf of (e.g. an underlying merchant)

Responses

200

401

Unauthorized

404

Not Found

500

Unexpected Error

get/hosted/vrp/consent-requests/{consentRequestId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/hosted/vrp/consent-requests/{consentRequestId}' \
  -H 'sub-application: string'

Response samples

application/json;charset=UTF-8

Get Hosted VRP Consent Response

{"meta": {"tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
},
"data": {"id": "ad4bfe58-6352-11ee-8c99-0242ac120002",
"applicationUserId": "45cf7ffe-6350-11ee-8c99-0242ac120002",
"applicationId": "ea4cdf01ee-278f-4e3e-8b30-695515aa4cdf01d64",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"userSettings": {"language": "en",
"location": "GB"
},
"redirectUrl": "https://tpp-application.com",
"vrpSetup": {"payer": {"accountIdentifications": [{"type": "MASKED_ACCOUNT_NUMBER",
"identification": "*****493"
}
]
},
"payee": {"name": "Merchant Doe",
"accountIdentifications": [{"identification": "401016",
"type": "SORT_CODE"
},
{"identification": "71518920",
"type": "ACCOUNT_NUMBER"
}
]
},
"reference": "Test Payment",
"limits": {"periodicLimits": [{"maxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CALENDAR"
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
}
},
"validFrom": "2023-10-04T16:41:17.870Z",
"validTo": "2024-10-04T16:41:17.870Z",
"recurringPaymentCategory": "ONGOING",
"risk": {"contextType": "ECOMMERCE_MERCHANT"
}
},
"createdAt": "2023-10-05T07:56:44.552Z",
"authorisationExpiresAt": "2023-10-05T07:56:44.552Z",
"consentStatus": "AUTHORIZED",
"consentToken": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJJTlNUSVRVVElPTiI6Im1vZGVsby1zYW5kYm94IiwiQ09OU0VOVCI6IjU2YTQyMjQ0LTQxNGEtNGI1Mi04YzRmLTRhZDJhNTBlODJmZSIsIkFQUExJQ0FUSU9OX1VTRVJfSUQiOiJtb2ZlLTIiLCJVU0VSIjoiY2E0MTJmZGYtNWEzMC00M2EyLTg4YjctNTk2NGEyNGE4ZTU1In0.gorwpnUjSr5dzQJLR32M2geWOj7yK9xMsZmq27ssY9xP_xGmWfUL_aqVHYyQ4r5KWw6Xb6RjvO839st8chJLtg",
"phases": [{"phaseName": "INITIATED",
"phaseCreatedAt": "2023-05-10T07:56:54.887Z"
},
{"phaseName": "INPUT_CAPTURED",
"phaseCreatedAt": "2023-05-10T07:57:05.123Z"
},
{"phaseName": "VALIDATION_COMPLETED",
"phaseCreatedAt": "2023-05-10T07:57:05.223Z"
},
{"phaseName": "AUTHORISATION_CREATED",
"phaseCreatedAt": "2023-05-10T07:57:06.637Z"
},
{"phaseName": "AUTHORISED",
"phaseCreatedAt": "2023-05-10T07:57:10.637Z"
},
{"phaseName": "SUBMITTED",
"phaseCreatedAt": "2023-05-10T07:57:10.654Z"
},
{"phaseName": "ACCEPTED",
"phaseCreatedAt": "2023-05-10T07:57:11.867Z"
}
]
}
}

Revoke Hosted VRP Consent Requestbeta

Revoke Hosted VRP Consent Request

Request

Security:

basicAuth

path Parameters

consentRequestId

required

string <uuid>

Unique Identifier of the Consent Request

header Parameters

sub-application

string

The unique identifier of the sub application the request is being submitted on behalf of (e.g. an underlying merchant)

Responses

200

401

Unauthorized

404

Not Found

500

Unexpected Error

post/hosted/vrp/consent-requests/{consentRequestId}/revoke

Request samples

curl
JavaScript
Node.js
Python

curl -i -X POST \
  -u <username>:<password> \
  'https://api.yapily.com/hosted/vrp/consent-requests/{consentRequestId}/revoke' \
  -H 'sub-application: string'

Response samples

application/json;charset=UTF-8

Revoke Hosted VRP Consent Response

{"meta": {"tracingId": "2dbfd85b4f2940c6a206e96dd90e52d0"
},
"data": {"id": "ad4bfe58-6352-11ee-8c99-0242ac120002",
"applicationUserId": "45cf7ffe-6350-11ee-8c99-0242ac120002",
"applicationId": "ea4cdf01ee-278f-4e3e-8b30-695515aa4cdf01d64",
"institutionIdentifiers": {"institutionId": "modelo-sandbox",
"institutionCountryCode": "GB"
},
"userSettings": {"language": "en",
"location": "GB"
},
"redirectUrl": "https://tpp-application.com",
"vrpSetup": {"payee": {"name": "Merchant Doe",
"accountIdentifications": [{"identification": "401016",
"type": "SORT_CODE"
},
{"identification": "71518920",
"type": "ACCOUNT_NUMBER"
}
]
},
"reference": "Test Payment",
"limits": {"periodicLimits": [{"maxAmount": {"amount": 100,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CALENDAR"
}
],
"maxAmountPerPayment": {"amount": 10,
"currency": "GBP"
}
},
"validFrom": "2023-10-04T16:41:17.870Z",
"validTo": "2024-10-04T16:41:17.870Z",
"risk": {"contextType": "ECOMMERCE_MERCHANT"
}
},
"createdAt": "2023-10-05T07:56:44.552Z",
"authorisationExpiresAt": "2023-10-05T07:56:44.552Z",
"consentStatus": "REVOKED",
"phases": [{"phaseName": "INITIATED",
"phaseCreatedAt": "2023-05-10T07:56:54.887Z"
},
{"phaseName": "INPUT_CAPTURED",
"phaseCreatedAt": "2023-05-10T07:57:05.123Z"
},
{"phaseName": "VALIDATION_COMPLETED",
"phaseCreatedAt": "2023-05-10T07:57:05.223Z"
},
{"phaseName": "AUTHORISATION_CREATED",
"phaseCreatedAt": "2023-05-10T07:57:06.637Z"
},
{"phaseName": "AUTHORISED",
"phaseCreatedAt": "2023-05-10T07:57:10.637Z"
},
{"phaseName": "SUBMITTED",
"phaseCreatedAt": "2023-05-10T07:57:10.654Z"
},
{"phaseName": "ACCEPTED",
"phaseCreatedAt": "2023-05-10T07:57:11.867Z"
},
{"phaseName": "REVOKED",
"phaseCreatedAt": "2023-05-11T09:57:11.867Z"
}
]
}
}

Create VRP Paymentbeta

Creates a Variable Recurring Payment

Request

Security:

basicAuth

path Parameters

consentRequestId

required

string <uuid>

Unique Identifier of the Consent Request

header Parameters

consent-token required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
sub-application	string The unique identifier of the sub application the request is being submitted on behalf of (e.g. an underlying merchant)

Request Body schema: application/json;charset=UTF-8

paymentIdempotencyId required	string Mandatory. A unique identifier that you must provide to identify the payment. This can be any alpha-numeric string but is limited to a maximum of 35 characters.
required	object (Amount Details) Mandatory. Monetary Amount.

Responses

201

Created

401

Error Response

default

Error Response

post/hosted/vrp/consent-requests/{consentRequestId}/payments

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Hosted VRP Payment Request

{"paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
"amount": {"amount": 10,
"currency": "GBP"
}
}

Response samples

201
401
default

application/json;charset=UTF-8

Created Hosted VRP Payment Response

{"meta": {"tracingId": "d80a638a-635e-11ee-8c99-0242ac120002"
},
"data": {"id": "string",
"paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
"amount": {"amount": 10,
"currency": "GBP"
},
"reference": "Test Payment",
"payee": {"name": "Merchant Doe",
"accountIdentifications": [{"identification": "401016",
"type": "SORT_CODE"
},
{"identification": "71518920",
"type": "ACCOUNT_NUMBER"
}
]
},
"refundAccount": {"name": "string",
"accountIdentifications": [{"type": "MASKED_ACCOUNT_NUMBER",
"identification": "*****493"
}
]
},
"paymentLifecycleId": "234g87t58tgeuo848wudjew489",
"institutionPaymentId": "35a4bd02-635e-11ee-8c99-0242ac120002",
"statusDetails": {"status": "PENDING",
"statusUpdateDate": "2023-10-05T09:00:36.360Z",
"isoStatus": {"code": "PDNG",
"name": "Pending"
}
}
}
}

Get VRP paymentbeta

Used to get details of a VRP Payment

Request

Security:

basicAuth

path Parameters

consentRequestId required	string <uuid> Unique Identifier of the Consent Request
paymentId required	string Unique Identifier of the Consent Request

header Parameters

sub-application

string

The unique identifier of the sub application the request is being submitted on behalf of (e.g. an underlying merchant)

Responses

200

401

Unauthorized

404

Not Found

500

Unexpected Error

get/hosted/vrp/consent-requests/{consentRequestId}/payments/{paymentId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/hosted/vrp/consent-requests/{consentRequestId}/payments/{paymentId}' \
  -H 'sub-application: string'

Response samples

application/json;charset=UTF-8

Get Hosted VRP Payment Response

{"meta": {"tracingId": "d80a638a-635e-11ee-8c99-0242ac120002"
},
"data": {"id": "string",
"paymentIdempotencyId": "234g87t58tgeuo848wudjew489",
"amount": {"amount": 10,
"currency": "GBP"
},
"reference": "Test Payment",
"payee": {"name": "Merchant Doe",
"accountIdentifications": [{"identification": "401016",
"type": "SORT_CODE"
},
{"identification": "71518920",
"type": "ACCOUNT_NUMBER"
}
]
},
"refundAccount": {"name": "string",
"accountIdentifications": [{"type": "MASKED_ACCOUNT_NUMBER",
"identification": "*****493"
}
]
},
"paymentLifecycleId": "234g87t58tgeuo848wudjew489",
"institutionPaymentId": "35a4bd02-635e-11ee-8c99-0242ac120002",
"statusDetails": {"status": "COMPLETED",
"statusUpdateDate": "2023-10-05T09:00:36.360Z",
"isoStatus": {"code": "ACSC",
"name": "AcceptedSettlementCompleted"
}
}
}
}

Check Funds Availabilitybeta

Confirms whether there are available funds on the Payer account to execute a Variable Recurring Payment after obtaining the user's authorisation.

Features:

VARIABLE_RECURRING_PAYMENT_FUNDS_CONFIRMATION

Request

Security:

basicAuth

path Parameters

consentRequestId

required

string <uuid>

Unique Identifier of the Consent Request

header Parameters

consent-token required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
sub-application	string The unique identifier of the sub application the request is being submitted on behalf of (e.g. an underlying merchant)

Request Body schema: application/json;charset=UTF-8

reference	string Optional. The payment reference or description. Limited to a maximum of 18 characters long.
required	object (Amount Details) Mandatory. Monetary Amount.

Responses

201

Created

401

Error Response

default

Error Response

post/hosted/vrp/consent-requests/{consentRequestId}/funds-confirmation

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json;charset=UTF-8

Create Hosted VRP Fund Confirmation Request

{"reference": "Own Account Sweeping",
"paymentAmount": {"amount": 10,
"currency": "GBP"
}
}

Response samples

201
401
default

application/json;charset=UTF-8

Created Hosted VRP Fund Confirmation Response

{"meta": {"tracingId": "0f14e900011b445fa6b6c2c4272d7321"
},
"data": {"id": "a9582f8e-08be-4cca-9f01-1ad3be96532d",
"fundsAvailable": {"fundsAvailable": true,
"fundsAvailableAt": "2021-06-08T10:59:35.138Z"
},
"reference": "Own Account Sweeping",
"paymentAmount": {"amount": 10,
"currency": "GBP"
}
}
}

Constraints

The constraints endpoints can be used to retrieve institution specific data requirements and rules that will apply when performing other operations.

Get Payment Constraints Rulesbeta

Retrieve institution specific constraints for payment authorisation and submission requests

Request

Security:

basicAuth

query Parameters

institutionIds required	Array of strings Unique Id(s) of the `Institution`(s) to retrieve the Payment Constraints for. Multiple institutionIds need to be separated by `,`
institutionCountryCode required	string Country code of the `Institution`(s). Ensure that the country code matches the respective institutionIds; any mismatch will result in an HTTP 404 error response.
paymentType required	string Type of payment to retrieve payment constraints for Enum: "DOMESTIC_PAYMENT" "DOMESTIC_INSTANT_PAYMENT" "DOMESTIC_VARIABLE_RECURRING_PAYMENT" "DOMESTIC_SCHEDULED_PAYMENT" "DOMESTIC_PERIODIC_PAYMENT" … 4 more
endpointPath	string The path on the API that is associated with the operation for which constraints are to be retrieved
endpointMethod	string The HTTP method that is associated with the operation for which constraints are to be retrieved Enum: "POST" "PATCH" "PUT" "GET" "DELETE"

Responses

200

400

Bad Request.

401

Either authentication credentials were not supplied, or they were invalid.

404

Not Found.

500

Unexpected Error

get/institutions/constraints/payments

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/institutions/constraints/payments?institutionIds=string&institutionCountryCode=string&paymentType=DOMESTIC_PAYMENT&endpointPath=string&endpointMethod=POST'

Response samples

application/json;charset=UTF-8

{"meta": {"tracingId": "661471ddb4344113a2d185b861cb3dcf"
},
"data": [{"institutionId": "mock-sandbox",
"institutionCountryCode": "GB",
"endpointPath": "/payments",
"endpointMethod": "POST",
"paymentType": "DOMESTIC_PAYMENT",
"request": {"headers": {"title": "Header",
"type": "object",
"properties": {"psuID": {"title": "PSU Id",
"type": "string",
"description": ""
}
}
},
"body": {"title": "Payment Request",
"required": ["payee",
"amount",
"paymentIdempotencyId",
"type"
],
"type": "object",
"properties": {"paymentIdempotencyId": {"title": "Payment Idempotency Id",
"pattern": "^.{1,35}$",
"type": "string",
"description": "Id for the payment"
},
"type": {"enum": ["DOMESTIC_PAYMENT"
],
"title": "Payment Type",
"type": "string",
"description": "type of the payment"
},
"contextType": {"default": "OTHER",
"enum": ["BILL",
"GOODS",
"SERVICES",
"OTHER",
"PERSON_TO_PERSON"
],
"title": "Context Type",
"type": "string",
"description": "__Optional__. The payment context code. This defaults to `OTHER` if not specified."
},
"reference": {"title": "Reference",
"pattern": "^.{1,18}$",
"type": "string",
"description": "__Mandatory__. The payment reference or description. Limited to a maximum of 18 characters long.",
"example": "Bill payment"
},
"payee": {"title": "Payee",
"required": ["accountIdentifications",
"name"
],
"type": "object",
"properties": {"name": {"title": "Name",
"pattern": "^.{1,18}$",
"type": "string",
"description": "__Mandatory__. The account holder name of the beneficiary.",
"example": "Jane Doe"
},
"accountIdentifications": {"title": "Account Identifications",
"type": "array",
"items": {"required": ["identification",
"type"
],
"type": "object",
"properties": {"type": {"title": "Account Identification Type",
"type": "string",
"description": "__Mandatory__. Used to describe the format of the account.<br><br> See [Account Identification Combinations](https://docs.yapily.com/pages/key-concepts/payments/payment-execution/intro-to-payment-execution/#account-identifications-combinations) for more information on when to specify each type."
},
"identification": {"title": "Account Identification",
"type": "string",
"description": "__Mandatory__. The value associated with the account identification type.<br><br> See [Account Identification Combinations](https://docs.yapily.com/pages/key-concepts/payments/payment-execution/intro-to-payment-execution/#account-identifications-combinations) for more information on the format of the values."
}
}
},
"description": "__Mandatory__. The account identifications that identify the `Payee` bank account."
},
"address": {"title": "Address",
"type": "object",
"properties": {"addressLines": {"title": "Address Lines",
"type": "array",
"items": {"title": "Address Line",
"type": "string"
},
"description": "__Optional__. The address line of the address"
},
"streetName": {"title": "Street Name",
"type": "string",
"description": "__Optional__. The street name of the address"
},
"buildingNumber": {"title": "Building Number",
"type": "string",
"description": "__Optional__. The building number of the address"
},
"postCode": {"title": "Postcode",
"type": "string",
"description": "__Optional__. The post code of the address"
},
"townName": {"title": "Town",
"type": "string",
"description": "__Optional__. The town name of the address"
},
"county": {"title": "County",
"type": "array",
"items": {"type": "string"
},
"description": "__Optional__. The list of counties for the address"
},
"country": {"title": "Country",
"type": "string",
"description": "__Conditional__. The 2-letter country code for the address. <br><br>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": {"title": "Department",
"type": "string",
"description": "__Optional__. The department for the address"
},
"subDepartment": {"title": "Sub-department",
"type": "string",
"description": "__Optional__. The sub-department for the address"
},
"addressType": {"enum": ["BUSINESS",
"CORRESPONDENCE",
"DELIVERY_TO",
"MAIL_TO",
"PO_BOX",
"POSTAL",
"RESIDENTIAL",
"STATEMENT",
"UNKNOWN"
],
"title": "Address Type",
"type": "string",
"description": "__Optional__. The type of address"
}
},
"description": "__Conditional__. The address of the `Payee` or `Payer`."
}
},
"description": "__Mandatory__. Details of the beneficiary [person or business]."
},
"payer": {"title": "Payer",
"required": ["accountIdentifications"
],
"type": "object",
"properties": {"accountIdentifications": {"title": "Account Identifications",
"type": "array",
"items": {"required": ["identification",
"type"
],
"type": "object",
"properties": {"type": {"enum": ["IBAN"
],
"title": "Account Identification Type",
"type": "string",
"description": "__Mandatory__. Should be IBAN only."
},
"identification": {"title": "Account Identification",
"pattern": "DE\\d{20}",
"type": "string",
"description": "__Mandatory__. The IBAN value associated with the account identity"
}
}
},
"description": "__Mandatory__. The account identifications that identify the `Payer` bank account."
},
"address": {"title": "Address",
"type": "object",
"properties": {"addressLines": {"title": "Address Lines",
"type": "array",
"items": {"title": "Address Line",
"type": "string"
},
"description": "__Optional__. The address line of the address"
},
"streetName": {"title": "Street Name",
"type": "string",
"description": "__Optional__. The street name of the address"
},
"buildingNumber": {"title": "Building Number",
"type": "string",
"description": "__Optional__. The building number of the address"
},
"postCode": {"title": "Postcode",
"type": "string",
"description": "__Optional__. The post code of the address"
},
"townName": {"title": "Town",
"type": "string",
"description": "__Optional__. The town name of the address"
},
"county": {"title": "County",
"type": "array",
"items": {"type": "string"
},
"description": "__Optional__. The list of counties for the address"
},
"country": {"title": "Country",
"type": "string",
"description": "__Conditional__. The 2-letter country code for the address. <br><br>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": {"title": "Department",
"type": "string",
"description": "__Optional__. The department for the address"
},
"subDepartment": {"title": "Sub-department",
"type": "string",
"description": "__Optional__. The sub-department for the address"
},
"addressType": {"enum": ["BUSINESS",
"CORRESPONDENCE",
"DELIVERY_TO",
"MAIL_TO",
"PO_BOX",
"POSTAL",
"RESIDENTIAL",
"STATEMENT",
"UNKNOWN"
],
"title": "Address Type",
"type": "string",
"description": "__Optional__. The type of address"
}
},
"description": "__Conditional__. The address of the `Payee` or `Payer`."
}
}
},
"amount": {"title": "Amount",
"required": ["amount",
"currency"
],
"type": "object",
"properties": {"amount": {"title": "Amount",
"minimum": 0,
"type": "number",
"description": "__Mandatory__. The monetary value"
},
"currency": {"title": "Currency",
"pattern": "^[A-Z]{3,3}$",
"type": "string",
"description": "__Mandatory__. The [ISO 4217](https://www.xe.com/iso4217.php) currency code"
}
},
"description": "__Mandatory__. Monetary Amount."
},
"paymentDateTime": {"type": "string",
"description": "__Optional__, If present date should be greater than or equal to current date",
"format": "date-time"
}
},
"description": "Domestic payment request schema"
}
}
}
]
}

Get Data Constraints Rulesbeta

Get Data Constraints Rules against an Institution for Account Authorisation requests

Request

Security:

basicAuth

query Parameters

institutionIds required	Array of strings Unique Id(s) of the `Institution`(s) to retrieve the Data Constraints for. Multiple institutionIds need to be separated by `,`
institutionCountryCode required	string Country code of the `Institution`(s). Ensure that the country code matches the respective institutionIds; any mismatch will result in an HTTP 404 error response.
endpointPath	string The path on the API that is associated with the operation for which constraints are to be retrieved
endpointMethod	string The HTTP method that is associated with the operation for which constraints are to be retrieved Enum: "POST" "PATCH" "PUT" "GET" "DELETE"

Responses

200

400

Bad Request.

401

Either authentication credentials were not supplied, or they were invalid.

404

Not Found.

500

Unexpected Error

get/institutions/constraints/data

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/institutions/constraints/data?institutionIds=string&institutionCountryCode=string&endpointPath=string&endpointMethod=POST'

Response samples

application/json;charset=UTF-8

{"meta": {"tracingId": "a43049c1dbc04d6f8c8e2dfdc523217a"
},
"data": [{"institutionId": "mock-sandbox",
"institutionCountryCode": "GB",
"endpointPath": "/account-auth-requests",
"endpointMethod": "POST",
"request": {"headers": {"title": "Header",
"type": "object",
"properties": {"psuID": {"title": "PSU Id",
"type": "string",
"description": "__Mandatory__. The psu id"
}
}
},
"body": {"required": ["institutionId"
],
"type": "object",
"properties": {"userUuid": {"title": "User UUID",
"type": "string",
"format": "uuid"
},
"institutionId": {"title": "Institution Identifier",
"type": "string",
"description": "__Mandatory__. The reference to the `Institution` which identifies which institution the authorisation request is sent to.",
"example": "yapily-mock"
},
"oneTimeToken": {"title": "One Time Token",
"type": "boolean",
"description": "__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. <br><br>See [Using a callback with an OTT (Optional)](https://docs.yapily.com/pages/knowledge/yapily-concepts/callback_url/#using-a-callback-with-an-ott-optional) for more information.",
"example": false
},
"callback": {"title": "Callback",
"type": "string",
"description": "__Optional__. The server to redirect the user to after the user complete the authorisation at the `Institution`. <br><br>See [Using a callback (Optional)](https://docs.yapily.com/pages/knowledge/yapily-concepts/callback_url/#using-a-callback-optional) for more information.",
"example": "https://display-parameters.com"
},
"accountRequest": {"title": "Account Request",
"type": "object",
"properties": {"transactionFrom": {"title": "Transaction From Date",
"type": "string",
"description": "__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](https://docs.yapily.com/pages/knowledge/open-banking/cbi_globe/).",
"format": "date-time"
},
"transactionTo": {"title": "Transaction To Date",
"type": "string",
"description": "__Optional__. When performing a request using the consent, this is the latest date of transaction records that can be retrieved.",
"format": "date-time"
},
"expiresAt": {"title": "Expires At",
"type": "string",
"description": "__Optional__. Used to set a hard date for when the user's associated `Consent` will expire.<br><br>**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.<br><br>**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.",
"format": "date-time"
},
"accountIdentifiers": {"title": "Account Info",
"required": ["accountIdentification"
],
"type": "object",
"properties": {"accountId": {"type": "string",
"description": "__Conditional__. Unique identifier of the account.",
"example": "500000000000000000000001"
},
"accountIdentification": {"title": "Account Identifications",
"required": ["identification",
"type"
],
"type": "object",
"properties": {"type": {"enum": ["SORT_CODE",
"ACCOUNT_NUMBER",
"IBAN",
"BBAN",
"BIC",
"PAN",
"MASKED_PAN",
"MSISDN",
"BSB",
"NCC",
"ABA",
"ABA_WIRE",
"ABA_ACH",
"EMAIL",
"ROLL_NUMBER",
"BLZ",
"IFS",
"CLABE",
"CTN",
"BRANCH_CODE",
"VIRTUAL_ACCOUNT_ID"
],
"title": "Account Identification Type",
"type": "string",
"description": "__Mandatory__. Used to describe the format of the account.<br><br> See [Account Identification Combinations](https://docs.yapily.com/pages/key-concepts/payments/payment-execution/intro-to-payment-execution/#account-identifications-combinations) for more information on when to specify each type.",
"example": "SORT_CODE"
},
"identification": {"title": "Account Identification",
"type": "string",
"description": "__Mandatory__. The value associated with the account identification type.<br><br> See [Account Identification Combinations](https://docs.yapily.com/pages/key-concepts/payments/payment-execution/intro-to-payment-execution/#account-identifications-combinations) for more information on the format of the values.",
"example": "401016"
}
}
}
},
"description": "__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](./#get-account-balances).<br><br> This can be specified in conjunction with `accountIdentifiersForTransaction` to generate a `Consent` that can both access the accounts balance and transactions."
},
"accountIdentifiersForTransaction": {"type": "array",
"items": {"required": ["accountIdentification"
],
"type": "object",
"properties": {"accountId": {"type": "string",
"description": "__Conditional__. Unique identifier of the account.",
"example": "500000000000000000000001"
},
"accountIdentification": {"title": "Account Identifications",
"required": ["identification",
"type"
],
"type": "object",
"properties": {"type": {"enum": ["SORT_CODE",
"ACCOUNT_NUMBER",
"IBAN",
"BBAN",
"BIC",
"PAN",
"MASKED_PAN",
"MSISDN",
"BSB",
"NCC",
"ABA",
"ABA_WIRE",
"ABA_ACH",
"EMAIL",
"ROLL_NUMBER",
"BLZ",
"IFS",
"CLABE",
"CTN",
"BRANCH_CODE",
"VIRTUAL_ACCOUNT_ID"
],
"title": "Account Identification Type",
"type": "string",
"description": "__Mandatory__. Used to describe the format of the account.<br><br> See [Account Identification Combinations](https://docs.yapily.com/pages/key-concepts/payments/payment-execution/intro-to-payment-execution/#account-identifications-combinations) for more information on when to specify each type.",
"example": "SORT_CODE"
},
"identification": {"title": "Account Identification",
"type": "string",
"description": "__Mandatory__. The value associated with the account identification type.<br><br> See [Account Identification Combinations](https://docs.yapily.com/pages/key-concepts/payments/payment-execution/intro-to-payment-execution/#account-identifications-combinations) for more information on the format of the values.",
"example": "401016"
}
}
}
}
},
"description": "__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](./#get-account-transactions). <br><br>This can be specified in conjunction with `accountIdentifiersForBalance` to generate a `Consent` that can both access the accounts balance and transactions."
},
"accountIdentifiersForBalance": {"type": "array",
"items": {"required": ["accountIdentification"
],
"type": "object",
"properties": {"accountId": {"type": "string",
"description": "__Conditional__. Unique identifier of the account.",
"example": "500000000000000000000001"
},
"accountIdentification": {"title": "Account Identifications",
"required": ["identification",
"type"
],
"type": "object",
"properties": {"type": {"enum": ["SORT_CODE",
"ACCOUNT_NUMBER",
"IBAN",
"BBAN",
"BIC",
"PAN",
"MASKED_PAN",
"MSISDN",
"BSB",
"NCC",
"ABA",
"ABA_WIRE",
"ABA_ACH",
"EMAIL",
"ROLL_NUMBER",
"BLZ",
"IFS",
"CLABE",
"CTN",
"BRANCH_CODE",
"VIRTUAL_ACCOUNT_ID"
],
"title": "Account Identification Type",
"type": "string",
"description": "__Mandatory__. Used to describe the format of the account.<br><br> See [Account Identification Combinations](https://docs.yapily.com/pages/key-concepts/payments/payment-execution/intro-to-payment-execution/#account-identifications-combinations) for more information on when to specify each type.",
"example": "SORT_CODE"
},
"identification": {"title": "Account Identification",
"type": "string",
"description": "__Mandatory__. The value associated with the account identification type.<br><br> See [Account Identification Combinations](https://docs.yapily.com/pages/key-concepts/payments/payment-execution/intro-to-payment-execution/#account-identifications-combinations) for more information on the format of the values.",
"example": "401016"
}
}
}
}
},
"description": "__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](./#get-account-transactions). <br><br>This can be specified in conjunction with `accountIdentifiersForBalance` to generate a `Consent` that can both access the accounts balance and transactions."
},
"featureScope": {"title": "Feature Scope",
"type": "array",
"items": {"type": "string"
},
"description": "Used to describe what functions are supported by the associated `Institution`"
}
},
"description": "Account authorisation request schema"
}
},
"description": "The request body containing an `AccountAuthorisationRequest` json payload"
}
}
}
]
}

Application Management

Application Management endpoints help with creating and managing client sub-applications.

Creates a sub-application for the root application id provided in the authentication tokenbeta

Creates a sub-application under the given root application id provided in the authentication token. The sub-application can use the root's credentials to call the API

Request

Security:

basicAuth

Request Body schema: application/json

The sub-application to create

name required	string <^[a-zA-Z0-9 \-_\[\]]+$> The name of the application
merchantCategoryCode required	string <^\d{4}$> The ISO-18245 merchant category code of the merchant the application is being created for. Allowed values: `0742` (Veterinary Services) `0763` (Agricultural Cooperatives) `0780` (Landscaping and Horticultural Services) `1520` (General Contractor/Residential Building) `1711` (Heating, Plumbing, Air Conditioning Contractors) `1731` (Electrical Contractors) `1740` (Masonry, Stonework, Tile Setting, Plastering, Insulation Contractors) `1750` (Carpentry) `1761` (Roof, Siding, and Sheet Metal Work Contractors) `1771` (Contractors, Concrete) `1799` (Special Trade Contractor - Not Elsewhere Classified) `2741` (Miscellaneous Publishing and Printing Services) `2791` (Typesetting, Plate Making and Related Services (Business to Business MCC)) `2842` (Specialty Cleaning, Polishing and Sanitation Preparations (Business to Business MCC)) `3000` (United Airlines) `3001` (American Airlines) `3002` (Pan American) `3003` (Eurofly Airlines) `3004` (Dragon Airlines) `3005` (British Airways) `3006` (Japan Air Lines) `3007` (Air France) `3008` (Lufthansa) `3009` (Air Canada) `3010` (KLM) `3011` (AeroFlot) `3012` (Qantas) `3013` (Alitalia) `3014` (Saudi Arabian Airlines) `3015` (SWISS) `3016` (SAS) `3017` (South African Airway) `3018` (Varig (Brazil)) `3020` (Air India) `3021` (Air Algerie) `3022` (PAL AIR) `3023` (Mexicana) `3024` (Pakistan International) `3025` (Air New Zealand Ltd.) `3026` (Emirates Airlines) `3027` (UTA/InterAir) `3028` (Air Malta) `3029` (SN Brussels Airlines - SN BRUSSELS) `3030` (Aerolineas Argentinas) `3031` (Olympic Airways) `3032` (El Al) `3033` (Ansett Airlines) `3034` (ETIHADAIR) `3035` (TAP (Portugal)) `3036` (VASP (Brazil)) `3037` (EgyptAir) `3038` (Kuwait Airways) `3039` (Avianca) `3040` (GulfAir (Bahrain)) `3041` (Balkan-Bulgarian) `3042` (FinnAir) `3043` (Aer Lingus) `3044` (Air Lanka) `3045` (Nigeria Airways) `3046` (Cruzeiro do Sul (Bra)) `3047` (THY (Turkey)) `3048` (Royal Air Maroc) `3049` (Tunis Air) `3050` (Icelandair) `3051` (Austrian Airlines) `3052` (LANAIR) `3053` (AVIACO (Spain)) `3054` (Ladeco (Chile)) `3055` (LAB (Bolivia)) `3056` (JetAir) `3057` (Virgin America – VIR AMER) `3058` (Delta) `3059` (DBA Airlines-DBA AIR) `3060` (NWA Air) `3061` (Continental) `3062` (Hapag-Lloyd Express - HLX) `3063` (US Airways) `3064` (Adria Airways) `3065` (Airinter (AirInternational)) `3066` (Southwest) `3068` (AIR STANA) `3069` (Sun Country Air) `3070` (Pacific Southwest Airlines (PSA)) `3071` (Air British Columbia) `3072` (CEBU PAC) `3073` (Air Cal) `3075` (Singapore Airlines) `3076` (Aeromexico) `3077` (Thai Airways) `3078` (China Airlines) `3079` (Jetstar Airways - Jetstar) `3081` (NordAir) `3082` (Korean Airlines) `3083` (Air Afrique) `3084` (Eva Airlines) `3085` (Midwest Express Airlines, Inc) `3087` (Metro Airlines) `3088` (Croatia Airlines) `3089` (Tans Saero) `3090` (Uni Airways) `3094` (Zambia Airways) `3096` (Air Zimbabwe) `3097` (Spanair (abbreviation: SPANAIR)) `3098` (Asiana Airlines) `3099` (Cathay Pacific) `3100` (Malaysian Airline Sys) `3102` (Iberia) `3103` (Garuda (Indonesia)) `3105` (Piedmont) `3106` (Braathens S.A.F.E. (Norway)) `3110` (Wings Airways) `3111` (British Midland) `3112` (Windward Island) `3117` (Venezolana Int de Aviacion) `3118` (Valley Airlines) `3125` (Tan Airlines) `3126` (Talair PTY Ltd.) `3127` (Taca International) `3129` (Surinam Airways) `3130` (Sunworld International Airways) `3131` (VLM Air) `3132` (Frontier Airlines) `3133` (Sunbelt Airlines) `3135` (Sudan Airlines) `3136` (Qatar Air) `3137` (Singleton) `3138` (Simmons Airlines) `3141` (Seair Alaska) `3143` (Scenic Airlines) `3144` (Virgin Atlantic) `3145` (San Juan) `3146` (Luxair) `3148` (Air Littoral SA) `3151` (Air Laire) `3154` (Princeville) `3156` (Go Fly) `3159` (PBA-Provincetwn-Bstn Air) `3161` (All Nippon Airways) `3164` (Norontair) `3165` (New York Helicopter) `3167` (Aero Continente - AEROCONTINENTE) `3170` (Mount Cook) `3171` (Canadian Airlines) `3172` (Nation Air) `3174` (JetBlue Airways) `3175` (Middle East Air) `3176` (Metroflight Airlines) `3177` (AirTran Airways) `3178` (Mesa Air) `3180` (Westjet Airlines-WESTJET) `3181` (Malev Hungarian Airlines) `3182` (LOT (Poland)) `3183` (Oman Aviation - OMAN AIR) `3184` (LIAT) `3185` (LAV (Venezuela)) `3186` (LAP (Paraguay)) `3187` (LACSA (Costa Rica)) `3188` (Virgin Express - VIR EXP) `3190` (Jugoslav Air) `3191` (Island Airlines) `3192` (Iran Air) `3193` (Indian Airlines) `3195` (Holiday Airlines) `3196` (Hawaiian Air) `3197` (Havasu Airlines) `3198` (Harbor Airlines) `3199` (Servicios Aereos Militares) `3200` (Guyana Airways) `3203` (Golden Pacific Air) `3204` (Freedom Airlines) `3206` (China Eastern Airlines (Abbr: China East Air)) `3207` (Empresa Ecuatoriana) `3211` (Norwegian Air Shuttle - NORWEGIANAIR) `3212` (Dominicana de Aviacion) `3213` (Malmo Aviation - MALMO AV) `3215` (Dan Air Services) `3216` (Cumberland Airlines) `3217` (CSA-Ceskoslovenske Aeroln) `3218` (Crown Air) `3219` (Copa) `3220` (Compania Faucett) `3221` (Transportes Aeros Mil) `3222` (Command Airways) `3223` (Comair) `3226` (Skyways Air- SKYWAYS) `3228` (Cayman Airways) `3229` (SAETA) `3231` (SAHSA) `3233` (Capitol Air) `3234` (CARIBAIR) `3235` (Brockway Air) `3236` (Air Arabia Airlines - Air Arab) `3238` (Bemidji Aviation) `3239` (Bar Harbor Airlines) `3240` (Bahamasair) `3241` (Aviateca (Guatemala)) `3242` (Avensa) `3243` (Austrian Air Service) `3245` (Easy Jet - EASYJET) `3246` (Ryan Air - RYANAIR) `3247` (Gol Airlines - GOL) `3248` (Tam Airlines - TAM) `3251` (Aloha Airlines) `3252` (ALM-Antilean Airlines) `3253` (America West) `3254` (U.S. Air Shuttle) `3256` (Alaska Airlines Inc.) `3259` (American Trans Air) `3260` (Spirit Airlines - SPIRIT) `3261` (Air China) `3262` (Reno Air) `3263` (Aero Servicio Carabobo) `3266` (Air Seychelles) `3267` (Air Panama International) `3268` (Air Pacific) `3275` (Air Nevada) `3276` (Air Midwest) `3277` (Air Madagascar) `3279` (Air LA) `3280` (Air Jamaica) `3282` (Air Djibouti) `3284` (Aero Virgin Islands) `3285` (AeroPeru) `3286` (Aero Nicaraguensis) `3287` (Aero Coach Aviation) `3291` (Ariana Afghan) `3292` (Cyprus Airways) `3293` (Ecuatoriana) `3294` (Ethiopian Airlines) `3295` (Kenya Airways) `3296` (Air Berlin-AIRBERLIN) `3297` (Tarom Romanian Air Transport) `3298` (Air Mauritius) `3299` (Wideroe's Flyveselskap) `3351` (Affiliated Auto Rental) `3352` (American International) `3353` (Brooks Rent a Car) `3354` (Action Auto Rental) `3355` (SIXT Car Rental) `3357` (Hertz) `3359` (Payless Car Rental) `3360` (Snappy Car Rental) `3361` (Airways Rent a Car) `3362` (Altra Auto Rental) `3364` (Agency Rent a Car) `3366` (Budget Rent a Car) `3368` (Holiday R-A-C) `3370` (Rent-a-Wreck) `3374` (Accent Rent-A-Car) `3376` (Ajax R-A-C) `3380` (Triangle Rent a Car) `3381` (Europ Car) `3385` (Tropical R-A-C) `3386` (Showcase Rental Cars) `3387` (Alamo Rent a Car) `3388` (Merchants Rent-A-Car, Inc) `3389` (Avis R-A-C) `3390` (Dollar R-A-C) `3391` (Europe by Car) `3393` (National Car Rental) `3394` (Kemwell Group R-A-C) `3395` (Thrify Car Rental) `3396` (Tilden R-A-C) `3398` (Econo Car R-A-C) `3400` (Auto Host Car Rentals) `3405` (Enterprise R-A-C) `3409` (General Rent-a-Car) `3412` (A-1 R-A-C) `3414` (Godfrey National) `3420` (ANSA International) `3421` (Allstate Rent-a-Car) `3423` (Avcar Rent-a-Car) `3425` (Automate Rent-a-Car) `3427` (Avon Rent-a-Car) `3428` (Carey Rent-a-Car) `3429` (Insurance Rent-a-Car) `3430` (Major Rent-a-Car) `3431` (Replacement Rent-a-Car) `3432` (Reserve Rent-a-Car) `3433` (Ugly Duckling R-A-C) `3434` (USA Rent-a-Car) `3435` (Value Rent-a-Car) `3436` (Autohansa Rent-a-Car) `3437` (Cite) `3438` (Interenet Rent-a-Car) `3439` (Millville Rent-a-Car) `3441` (Advantage Rent A Car) `3501` (Holiday Inns) `3502` (Best Western Hotels) `3503` (Sheraton) `3504` (Hilton) `3505` (Forte Hotels) `3506` (Golden Tulip Hotels) `3507` (Friendship Inns) `3508` (Quality Inns) `3509` (Marriott) `3510` (Days Inn Colonial Resort) `3511` (Arabella Hotels) `3512` (Intercontinental Hotels) `3513` (Westin) `3514` (Amerisuites) `3515` (Rodeway Inn) `3516` (LaQuinta Motor Inns) `3517` (Americana Hotels) `3518` (Sol Hotels) `3519` (Pullman International Hotels) `3520` (Meridien Hotels) `3521` (Royal Lahaina Resort) `3522` (Tokyo Group) `3523` (Peninsula Hotels) `3524` (WelcomGroup Hotels) `3525` (Dunfey Hotels) `3526` (Prince Hotels) `3527` (Downtowner Passport) `3528` (Red Lion Inns) `3529` (CP (Canadian Pacific)) `3530` (Renaissance Hotels) `3531` (Kauai Coconut Beach Resort) `3532` (Royal Kona Resort) `3533` (Hotel Ibis) `3534` (Southern Pacific) `3535` (Hilton International) `3536` (AMFAC Hotels) `3537` (ANA Hotels) `3538` (Concorde Hotels) `3539` (Summerfield Suites Hotel) `3540` (Iberotel Hotels) `3541` (Hotel Okura) `3542` (Royal Hotels) `3543` (Four Seasons) `3544` (Cigna Hotels) `3545` (Shangri-La International) `3546` (Hotel Sierra) `3548` (Hotels Melia) `3549` (Auberge des Governeurs) `3550` (Regal 8 Inns) `3551` (Mirage Hotel and Casino) `3552` (Coast Hotel) `3553` (Park Inn by Radisson) `3554` (Pinehurst Resort) `3555` (Treasure Island Hotel and Casino) `3556` (Barton Creek Resort) `3557` (Manhattan East Suite Hotels) `3558` (Jolly Hotels) `3559` (Candlewood Suites) `3560` (Aladdin Resort and Casino) `3561` (Golden Nugget) `3562` (Comfort Inns) `3563` (Journey's End Motels) `3564` (Sam's Town Hotel and Casino) `3565` (Relax Inns) `3566` (Garden Place Hotel) `3567` (Soho Grand Hotel) `3568` (Ladbroke Hotels) `3569` (Tribeca Grand Hotel) `3570` (Forum Hotels) `3571` (Grand Wailea Resort) `3572` (Miyako Hotel) `3573` (Sandman Hotels) `3574` (Venture Inn) `3575` (Vagabond Hotels) `3576` (La Quinta Resort) `3577` (Mandarin Oriental Hotel) `3578` (Frankenmuth Bavarian) `3579` (Hotel Mercure) `3580` (Hotel Del Coronado) `3581` (Delta Hotels) `3582` (California Hotel and Casino) `3583` (Radisson BLU) `3584` (Princess Hotels International) `3585` (Hungar Hotels) `3586` (Sokos Hotels) `3587` (Doral Hotels) `3588` (Helmsley Hotels) `3589` (Doral Golf Resort) `3590` (Fairmont Hotel) `3591` (Sonesta Hotels) `3592` (Omni Hotels) `3593` (Cunard Hotels) `3594` (Arizona Biltmore) `3595` (Hospitality Inns) `3596` (Wynn Las Vegas) `3597` (Riverside Resort and Casino) `3598` (Regent International Hotels) `3599` (Pannonia Hotels) `3600` (Saddlebrook Resort - Tampa) `3601` (Trade Winds Resorts) `3602` (Hudson Hotel) `3603` (Noah's Hotel) `3604` (Hilton Garden Inn) `3605` (Jurys Doyle Hotel Group) `3606` (Jefferson Hotel) `3607` (Fountainebleau Resort) `3608` (Gaylord Opryland) `3609` (Gaylord Palms) `3610` (Gaylord Texan) `3611` (C MON INN) `3612` (Movenpick Hotels) `3613` (Microtel Inns & Suites) `3614` (Americinn) `3615` (Travelodge Motels) `3617` (America's Best Value Inn) `3618` (Great Wolf) `3619` (Aloft) `3620` (Binion's Horseshoe Club) `3621` (Extended Stay) `3622` (Merlin Hotel) `3623` (Dorint Hotels) `3624` (Lady Luck Hotel and Casino) `3625` (Hotel Universale) `3626` (Studio Plus) `3627` (Extended Stay America) `3628` (Excalibur Hotel and Casino) `3629` (Dan Hotels) `3630` (Extended Stay Deluxe) `3631` (Sleep Inn) `3632` (The Phoenician) `3633` (Rank Hotels) `3634` (Swissotel) `3635` (Reso Hotel) `3636` (Sarova Hotels) `3637` (Ramada Inns) `3638` (Howard Johnson) `3639` (Mount Charlotte Thistle) `3640` (Hyatt Motels) `3641` (Sofitel Hotels) `3642` (Novotel) `3643` (Steigenberger Hotels) `3644` (EconoLodges) `3645` (Queens Moat Houses) `3646` (Swallow Hotels) `3647` (Husa Hotels) `3648` (De Vere Hotels) `3649` (Radisson) `3650` (Red Roof Inns) `3651` (Imperial London Hotel) `3652` (Embassy Hotels) `3653` (Penta Hotels) `3654` (Loews Hotels) `3655` (Scandic Hotels) `3656` (Sara Hotels) `3657` (Oberoi Hotels) `3658` (New Otani Hotels) `3659` (Taj Hotels International) `3660` (Knights Inn) `3661` (Metropole Hotels) `3662` (Circus Circus Hotel and Casino) `3663` (Hoteles El Presidente) `3664` (Flag Inns) `3665` (Hampton Inn Hotels) `3666` (Stakis Hotels) `3667` (Luxor Hotel and Casino) `3668` (Maritim Hotels) `3669` (Eldorado Hotel and Casino) `3670` (Arcade Hotels) `3671` (Arctia Hotels) `3672` (Campanile Hotels) `3673` (IBUSZ Hotels) `3674` (Rantasipi Hotels) `3675` (Interhotel CEDOK) `3676` (Monte Carlo Hotel and Casino) `3677` (Climat de France Hotels) `3678` (Cumulus Hotels) `3679` (Silver Legacy Hotel and Casino) `3680` (Hoteis Othan) `3681` (Adams Mark Hotels) `3682` (Sahara Hotel and Casino) `3683` (Bradbury Suites) `3684` (Budget Hosts Inns) `3685` (Budgetel Hotels) `3686` (Suisse Chalet) `3687` (Clarion Hotels) `3688` (Compri Hotels) `3689` (Consort Hotels) `3690` (Courtyard Inns) `3691` (Dillon Inn) `3692` (Doubletree) `3693` (Drury Inn) `3694` (Economy Inns of America) `3695` (Embassy Suites) `3696` (Excel Inn) `3697` (Fairfield Hotels) `3698` (Harley Hotels) `3699` (Midway Motor Lodge) `3700` (Motel 6) `3701` (La Mansion Del Rio) `3702` (The Registry Hotels) `3703` (Residence Inn) `3704` (Royce Hotels) `3705` (Sandman Inn) `3706` (Shilo Inn) `3707` (Shoney's Inn) `3708` (Virgin River Hotel and Casino) `3709` (Super 8 Motels) `3710` (The Ritz Carlton Hotels) `3711` (Flag Inns (Australia)) `3712` (Buffalo Bill's Hotel and Casino) `3713` (Quality Pacific Hotel) `3714` (Four Seasons Hotels-Austr) `3715` (Fairfield Inn) `3716` (Carlton Hotels) `3717` (City Lodge Hotels) `3718` (Karos Hotels) `3719` (Protea Hotels) `3720` (Southern Sun Hotels) `3721` (Hilton Conrad Hotels) `3722` (Wyndham Hotels) `3723` (Rica Hotels) `3724` (Inter Nor Hotels) `3725` (SeaPines Plantation) `3726` (Rio Suites) `3727` (Broadmoor Hotel) `3728` (Bally's Hotel and Casino) `3729` (John Ascuaga's Nugget) `3730` (MGM Grand Hotel) `3731` (Harrah's Hotels and Casinos) `3732` (Opryland Hotel) `3733` (Boca Raton Resort) `3734` (Harvey/Bristol Hotels) `3735` (Master Economy Inns) `3736` (Colorado Belle/Edgewater Resort) `3737` (Riviera Hotel and Casino) `3738` (Tropicana Resort & Casino) `3739` (Woodside Hotels & Resorts) `3740` (Towneplace Suites) `3741` (Millennium Hotel) `3742` (Club Med) `3743` (Biltmore Hotel and Suites) `3744` (Carefree Resorts) `3745` (St. Regis Hotel) `3746` (The Eliot Hotel) `3747` (ClubCorp/ClubResorts) `3748` (Wellesley Inns) `3749` (The Beverly Hills Hotel) `3750` (Crown Plaza Hotels) `3751` (Homewood Suites) `3752` (Peabody Hotels) `3753` (Greenbriar Resorts) `3754` (Amelia Island Plantation) `3755` (The Homestead) `3757` (Canyon Ranch) `3758` (Kahala Mandarion Oriental Hotel) `3759` (The Orchid at Mauna Lani) `3760` (Halekulani Hotel/Waikiki Parc) `3761` (Primadonna Hotel and Casino) `3762` (Whisky Pete's Hotel and Casino) `3763` (Chateau Elan Winery and Resort) `3764` (Beau Rivage Hotel and Casino) `3765` (Bellagio) `3766` (Fremont Hotel and Casino) `3767` (Main Street Hotel and Casino) `3768` (Silver Star Hotel and Casino) `3769` (Stratosphere Hotel and Casino) `3770` (SpringHill Suites) `3771` (Caesar's Resort) `3772` (Nemacolin Woodlands) `3773` (The Venetian Resort Hotel and Casino) `3774` (New York-New York Hotel and Casino) `3775` (Sands Resort) `3776` (Nevele Grande Resort and Country Club) `3777` (Mandalay Bay Resort) `3778` (Four Points Hotels) `3779` (W Hotels) `3780` (Disney Resorts) `3781` (Patricia Grand Resort Hotels) `3782` (Rosen Hotels & Resort) `3783` (Town and Country Resort and Convention Center) `3784` (First Hospitality Hotel) `3785` (Outrigger Hotels and Resorts) `3786` (Ohana Hotel of Hawaii) `3787` (Caribe Royale Resort Suites & Villas) `3788` (Ala Moana Hotel / Ala Moana Hotels) `3789` (Smugglers' Notch Resort) `3790` (Raffles Hotels) `3791` (Staybridge Suites) `3792` (Claridge Casino Hotel) `3793` (The Flamingo Hotels) `3794` (Grand Casino Hotels) `3795` (Paris Las Vegas Hotel) `3796` (Peppermill Hotel Casino) `3797` (Atlantic City Hilton) `3798` (Embassy Vacation Resort) `3799` (Hale Koa Hotel) `3800` (Homestead) `3801` (Wilderness Hotel and Golf Resort) `3802` (The Palace Hotel) `3807` (Element) `3808` (LXR) `3810` (La Costa Resort) `3811` (Premier Travel Inn) `3812` (Hyatt Place) `3813` (Hotel Indigo) `3814` (The Roosevelt Hotel NY) `3815` (Holiday Inn Nickelodeon) `3816` (Home2 Suites) `3817` (Affinia) `3818` (Mainstay Suites) `3819` (Oxford Suites) `3820` (Jumeirah Essex House) `3821` (Caribe Royale) `3822` (Crossland) `3823` (Grand Sierra Resort) `3824` (Aria) `3825` (Vdara) `3826` (Autograph) `3827` (Galt House) `3828` (Cosmopolitan of Las Vegas) `3829` (Country Inn by Carlson) `3830` (Park Plaza Hotel) `3831` (Waldorf) `4011` (Railroads) `4111` (Local and Suburban Commuter Passenger Transportation, including Ferries) `4112` (Passenger Rail (train)) `4119` (Ambulance Services) `4121` (Taxicabs and Limousines) `4131` (Bus Lines, includes Charters/Tour Buses) `4214` (Motor Freight Carriers and Trucking-Local and Long Distance, Moving & Storage Companies, and Local Delivery) `4215` (Courier Services-Air and Ground, and Freight Forwarders) `4225` (Public Warehousing-Farm products, Refrigerated Goods, Household Goods, and Storage) `4411` (Steamship and Cruise Lines) `4457` (Boat Rentals and Leasing) `4468` (Marinas, Marine Service, and Supplies) `4511` (Airlines and Air Carriers) `4582` (Airports, Flying Fields, and Airport Terminals) `4722` (Travel Agencies) `4723` (Package Tour Operators (Germany Only)) `4761` (Telemarketing of Travel Related Services and Vitamins) `4784` (Bridge and Road Fees, Tolls) `4789` (Transportation Services-not elsewhere classified) `4812` (Telecommunication Equipment and Telephone Sales) `4813` (Special Telecom Merchant) `4814` (Telecommunication Services, Including Local and Long Distance Calls, Credit Card Calls, Call Through Use of Magnetic-Strip-Reading Telephones, and Fax Services) `4815` (Monthly Summary Telephone Charges) `4816` (Computer Network/Information Services and other Online Services such as electronic bulletin board, e-mail, web site hosting services, or Internet access) `4821` (Telegraph Services) `4829` (Quasi Cash - Money Transfer) `4899` (Cable, Satellite, and Other Pay Television and Radio Services) `4900` (Utilities-Electric, Gas, Water, and Sanitary) `5013` (Motor Vehicle Supplies and New Parts (Business to Business MCC)) `5021` (Office Furniture (Business to Business MCC)) `5039` (Construction Materials Not Elsewhere Classified (Business to Business MCC)) `5044` (Photographic, Photocopy, Microfilm Equipment and Supplies (Business to Business MCC)) `5045` (Computers, Computer Peripheral Equipment, and Software) `5046` (Commercial Equipment Not Elsewhere Classified (Business to Business MCC)) `5047` (Dental/Laboratory/Medical/Ophthalmic Hospital Equipment and Supplies) `5051` (Metal Service Centers and Offices (Business to Business MCC)) `5065` (Electrical Parts and Equipment (Business to Business MCC)) `5072` (Hardware, Plumbing, Heat Equipment and Supplies (Business to Business MCC)) `5074` (Plumbing and Heating Equipment and Supplies (Business to Business MCC)) `5085` (Industrial Supplies Not Elsewhere Classified (Business to Business MCC)) `5094` (Precious Stones, Metals, Watches and Jewelry (Business to Business MCC)) `5099` (Durable Goods Not Elsewhere Classified (Business to Business MCC)) `5111` (Stationery, Office Supplies, and Printing and Writing Paper) `5122` (Drugs, Drug Proprietary's, and Druggists' Sundries) `5131` (Piece Goods, Notions and Other Dry Goods (Business to Business MCC)) `5137` (Men's, Women's and Children's Uniforms (Business to Business MCC)) `5139` (Commercial Footwear (Business to Business MCC)) `5169` (Chemicals and Allied Products Not Elsewhere Classified (Business to Business MCC)) `5172` (Petroleum and Products (Business to Business MCC)) `5192` (Books, Periodicals and Newspapers (Business to Business MCC)) `5193` (Florist Suppliers, Nursery Stock & Flowers (Business to Business MCC)) `5198` (Paints, Varnishes and Supplies (Business to Business MCC)) `5199` (Non-durable Goods Not Elsewhere Classified (Business to Business MCC)) `5200` (Home Supply Warehouse) `5211` (Lumber & Building Materials Stores) `5231` (Glass, Paint, and Wallpaper Stores) `5251` (Hardware Stores, Equipment Utilities Regulated) `5261` (Nurseries and Lawn and Garden Supply Stores) `5271` (Mobile Home Dealer) `5300` (Wholesale Club with or without membership fee) `5309` (Duty Free Stores) `5310` (Discount Store) `5311` (Department Stores) `5331` (Variety Stores) `5399` (Miscellaneous General Merchandise) `5411` (Grocery Stores and Supermarkets) `5422` (Freezer & Locker Meat Provisions) `5441` (Candy, Nut, and Confectionary Stores) `5451` (Dairy Product Stores) `5462` (Bakeries) `5499` (Miscellaneous Food Stores-Convenience Stores and Specialty Markets) `5511` (Car and Truck Dealers (New and Used)- Sales, Service, Repairs, Parts, and Leasing) `5521` (Car and Truck Dealers (Used)- Sales, Service, Repairs, Parts, and Leasing) `5532` (Automotive Tire Stores) `5531` (Auto and Home Supply Stores) `5533` (Automotive Parts and Accessories Stores) `5541` (Service Stations (with or without Ancillary Services)) `5542` (Automated Fuel Dispensers) `5551` (Boat Dealers) `5561` (Camper, Recreational and Utility Trailer Dealers) `5571` (Motorcycle Dealers) `5592` (Motor Home Dealers) `5598` (Snowmobile Dealers) `5599` (Miscellaneous Automotive, Aircraft, and Farm Equipment Dealers --Not Elsewhere Classified) `5611` (Men's & Boys' Clothing and Accessory Stores) `5621` (Women's Ready-to-Wear Stores) `5631` (Women's Accessory and Specialty Stores) `5641` (Children's and Infants' Wear Stores) `5651` (Family Clothing Stores) `5655` (Sports and Riding Apparel Stores) `5661` (Shoe Stores) `5681` (Furriers & Fur Shops) `5691` (Men's and Women's Clothing Stores) `5697` (Tailors, Seamstresses, Mending, Alterations) `5698` (Wig & Toupee Shops) `5699` (Miscellaneous Apparel and Accessory Stores) `5712` (Furniture, Home Furnishings, and Equipment Stores, except Appliances) `5713` (Floor coverings, Rugs) `5714` (Drapery, Window Covering, and Upholstery Stores) `5718` (Fireplaces, Fireplace Screens and Accessories Stores) `5719` (Miscellaneous Home Furnishing Specialty Stores) `5722` (Household Appliance Stores) `5732` (Electronics Stores) `5733` (Music Stores-Musical Instruments, Pianos, and Sheet Music) `5734` (Computer Software Stores) `5735` (Record Stores) `5811` (Caterers - Prepare & Delivery) `5812` (Eating Places and Restaurants) `5813` (Drinking Places (Alcoholic Beverages) - Bars, Taverns, Nightclubs, Cocktail Lounges, and Discotheques) `5814` (Quick Payment Service-Fast Food Restaurants) `5815` (Digital Goods – Media, Books, Movies, Music) `5816` (Digital Goods – Games) `5817` (Digital Goods – Applications (Excludes Games)) `5818` (Large Digital Goods Merchant) `5912` (Drug Stores and Pharmacies) `5921` (Package Stores--Beer, Wine, and Liquor) `5931` (Used Merchandise and Secondhand Stores) `5932` (Antique Shop) `5933` (Pawn Shop) `5935` (Wrecking and Salvage Yards) `5937` (Antique Reproduction Stores) `5940` (Bicycle Shop-Sales and Services) `5941` (Sporting Goods Stores) `5942` (Book Stores) `5943` (Stationery, Office and School Supply Stores) `5944` (Jewelry, Watch, Clock, and Silverware Stores) `5945` (Hobby, Toy and Game Stores) `5946` (Camera and Photographic Supply Stores) `5947` (Gift, Card, Novelty, and Souvenir Stores) `5948` (Luggage and Leather Goods Stores) `5949` (Sewing, Needlework, Fabric, and Piece Good Stores) `5950` (Glassware and Crystal Stores) `5960` (Direct Marketing Insurance Services) `5961` (Mail Order) `5962` (Direct Marketing -- Travel Related Arrangement Services) `5963` (Direct Selling Establishments/Door to Door Sales) `5964` (Catalog Merchant) `5965` (Combined Catalog and Retail Merchant) `5966` (Outbound Telemarketing Merchant) `5967` (Direct Marketing -- Inbound Telemarketing Merchants) `5968` (Continuity/Subscription Merchants) `5969` (Direct Marketing/Direct Marketers--Not Elsewhere Classified) `5970` (Artist Supply and Craft Stores) `5971` (Art Dealers and Galleries) `5972` (Stamp and Coin Stores) `5973` (Religious Goods Stores) `5975` (Hearing Aids--Sales, Service, and Supplies) `5976` (Orthopedic Goods and Prosthetic Devices) `5977` (Cosmetic Stores) `5978` (Typewriter Stores--Sales, Service, and Rentals) `5983` (Fuel Dealers--Fuel Oil, Wood, Coal, and Liquefied Petroleum) `5992` (Florists) `5993` (Cigar Stores & Stands) `5994` (News Dealers & Newsstands) `5995` (Pet Shops, Pet Food, and Supplies) `5996` (Swimming Pools--Sales, Supplies, and Services) `5997` (Electric Razor Stores Sales & Services) `5998` (Tent and Awning Stores) `5999` (Miscellaneous & Specialty Retail Stores) `6010` (Financial Institutions--Manual Cash Disbursements) `6011` (Financial Institutions--Automated Cash Disbursements) `6012` (Quasi Cash - Financial Institution - Merchandise and Services) `6050` (Quasi Cash - Member Financial Institution) `6051` (MasterCard - Quasi Cash-Merchant) `6211` (Securities - Brokers and Dealers) `6300` (Insurance Sales and Underwriting) `6381` (Insurance - Premiums) `6399` (Insurance - Not Elsewhere Classified) `6513` (Real Estate Agents and Managers - Rentals; Property Management) `6529` (Remote Stored Value Load - Member Financial Institution) `6530` (Remote Stored Value Load - Merchant) `6531` (Payment Service Provider) `6532` (Payment Transaction - Member) `6533` (Payment Transaction - Merchant) `6534` (Money Transfer - Member Financial Institution) `6535` (Value Purchase - Member Financial Institution) `6536` (MoneySend Intracountry) `6537` (MoneySend Intercountry) `6538` (MoneySend Funding) `6540` (POI Funding Transactions (Excluding MoneySend)) `7011` (Lodging - Hotels, Motels, and Resorts) `7012` (Timeshares) `7032` (Sporting and Recreational Camps) `7033` (Trailer Parks and Campgrounds) `7210` (Laundry, Cleaning, and Garment Services) `7211` (Laundry Services - Family and Commercial) `7216` (Dry Cleaners) `7217` (Carpet and Upholstery Cleaning) `7221` (Photographic Studios) `7230` (Beauty and Barber Shops) `7251` (Shoe Repair Shops, Shoe Shine Parlors, and Hat Cleaning Shops) `7261` (Funeral Services and Crematories) `7273` (Dating Services) `7276` (Tax Preparation Services) `7277` (Counseling Services - Debt, Marriage, and Personal) `7278` (Buying and Shopping Services and Clubs) `7296` (Clothing Rental - Costumes, Uniforms and Formal Wear) `7297` (Massage Parlors) `7298` (Health and Beauty Spas) `7299` (Miscellaneous Personal Services - Not Elsewhere Classified) `7311` (Advertising Services) `7321` (Consumer Credit Reporting Agencies) `7332` (Blueprinting and Photocopying Services) `7333` (Commercial Photography, Art, and Graphics) `7338` (Quick Copy, Reproduction Service) `7339` (Stenographic Service) `7342` (Exterminating and Disinfecting Services) `7349` (Cleaning, Maintenance & Janitorial Services) `7361` (Employment Agencies and Temporary Help Services) `7372` (Computer Programming, Data Processing, and Integrated Systems Design Services) `7375` (Information Retrieval Services (Business to Business MCC)) `7379` (Computer Maintenance, Repair and Services (Business to Business MCC)) `7392` (Management, Consulting, and Public Relations Services) `7393` (Detective Agencies, Protective Agencies, and Security Services, including Armored Cars and Guard Dogs) `7394` (Equipment, Tool, Furniture, and Appliance Rental and Leasing) `7395` (Photofinishing Laboratories and Photo Developing) `7399` (Business Services) `7511` (Truck Stops) `7512` (Automobile Rental Agency) `7513` (Truck and Utility Trailer Rentals) `7519` (Motor Home and Recreational Vehicle Rentals) `7523` (Parking Lots and Garages) `7524` (Express Payment Service Mechants - Parking Lots and Garages) `7531` (Automotive Top & Body Shops) `7534` (Tire Retreading & Repair) `7535` (Automotive Paint Shops) `7538` (Automotive Service Shops (Non-Dealer)) `7542` (Car Washes) `7549` (Towing Services) `7622` (Electronic Repair Shops) `7623` (Air Conditioning and Refrigeration Repair Shops) `7629` (Electrical and Small Appliance Repair Shops) `7631` (Watch, Clock, and Jewelry Repair Shops) `7641` (Furniture - Reupholster, Repair, and Refinishing) `7692` (Welding Services) `7699` (Miscellaneous Repair Shops and Related Services) `7778` (Citishare Cash Advance) `7800` (Government-Owned Lotteries) `7801` (Government-Licensed Casinos (Online Gambling)) `7802` (Government-Licensed Horse/Dog Racing) `7829` (Motion Picture & Video Tape Production and Distribution (Business to Business MCC)) `7832` (Motion Picture Theater) `7841` (DVD/Video Tape Rental Stores) `7911` (Dance Halls, Studios & Schools) `7922` (Theatrical Producers (except Motion Pictures) and Ticket Agencies) `7929` (Bands, Orchestras & Misc Entertainment) `7932` (Billiards & Pool Establishments) `7933` (Bowling Alleys) `7941` (Commercial Sports, Professional Sports Clubs, Athletic Fields, and Sports Promoters) `7991` (Tourist Attractions and Exhibits) `7992` (Public Golf Courses) `7993` (Video Amusement Game Supply) `7994` (Video Game Arcades and Establishments) `7995` (Betting, including Lottery Tickets, Casino Gaming Chips, Off- Track Betting, and Wagers at Race Track) `7996` (Amusement Parks, Circuses, Carnivals, and Fortune Tellers) `7997` (Membership Clubs (Sports, Recreation, Athletic), Country Clubs, and Private Golf Courses) `7998` (Aquarium, Seaquarium, Dolphinariums) `7999` (Recreation Services - Not Elsewhere Classified) `8011` (Doctors and Physicians - Not Elsewhere Classified) `8021` (Dentists and Orthodontists) `8031` (Osteopathic Physicians) `8041` (Chiropractors) `8042` (Optometrists and Ophthalmologists) `8043` (Opticians, Optical Goods and Eyeglasses) `8049` (Podiatrists and Chiropodists) `8050` (Nursing and Personal Care Facilities) `8062` (Hospitals) `8071` (Medical and Dental Laboratories) `8099` (Medical Services Health Practitioners - No Elsewhere Classified) `8111` (Legal Services and Attorneys) `8211` (Elementary and Secondary Schools) `8220` (Colleges, Universities, Professional Schools, and Junior Colleges) `8241` (Correspondence Schools) `8244` (Business and Secretarial Schools) `8249` (Trade and Vocational Schools) `8299` (Schools and Educational Services - Not Elsewhere Classified) `8351` (Child Care Services) `8398` (Charitable and Social Service Organizations) `8641` (Civic, Social, and Fraternal Associations) `8651` (Political Organizations) `8661` (Religious Organizations) `8675` (Automobile Associations) `8699` (Membership Organizations - Not Elsewhere Classified) `8734` (Testing Laboratories (Not Medical) - (Business to Business MCC)) `8911` (Architectural, Engineering, and Surveying Services) `8931` (Accounting, Auditing, and Bookkeeping Services) `8999` (Professional Services - Not Elsewhere Classified) `9211` (Court Costs, including Alimony and Child Support) `9222` (Fines) `9223` (Bail & Bond Payments) `9311` (Tax Payments) `9399` (Government Services - Not Elsewhere Classified) `9401` (i-Purchasing) `9402` (Postal Services) `9405` (U.S. Fed Government Agencies) `9700` (Automated Referral Service) `9701` (Visa Credential Server) `9702` (GCAS Emergency Services) `9751` (U.K. Supermarkets, Electronic Hot File) `9752` (U.K. Petrol Stations, Electronic Hot File) `9753` (Consumer Electronics/Furniture Store) `9754` (Quasi Cash - Gambling-Horse Racing, Dog Racing, State Lotteries) `9950` (Intra-Company Purchases)
ppcUserGroup required	string The payment user group from the purpose code list for the application. Allowed values: WHOLESALE_FI_FI COMMERCIAL CONSUMER_GOODS_SERVICES FINANCE INSURANCE PROPERTY UTILITIES TAX SALARIES_INCOMES INVESTMENTS FOREIGN_EXCHANGE GOVERNMENT BENEFIT_PAYMENTS MEDICAL PENSIONS
callbackUrls	Array of strings The application callback URLs
isContractPresent required	boolean Indicates if a contract is in place with the merchant and a KYB process has been completed

Responses

201

Sub-application was successfully created

400

There are validation errors

401

Either authentication credentials were not supplied, or they were invalid.

403

Forbidden from accessing the requested Application.

404

Application with given root id not found.

500

An unexpected error occurred.

post/applications

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

{"name": "Merchant Uno",
"merchantCategoryCode": 7995,
"ppcUserGroup": "WHOLESALE_FI_FI",
"callbackUrls": ["https://www.callback-service.com"
],
"isContractPresent": true
}

Response samples

application/json;charset=UTF-8

{"meta": {"tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154"
},
"data": {"id": "2698db90-6635-4f76-b673-5ce8e2aeda0e",
"name": "Merchant Uno",
"merchantCategoryCode": 7995,
"ppcUserGroup": "WHOLESALE_FI_FI",
"callbackUrls": ["https://www.callback-service.com"
],
"isContractPresent": true,
"rootApplicationId": "eb25e1ee-f6af-4131-92fe-748e177bf950"
}
}

Retrieve sub-applications for the root application provided in the authentication token.beta

Retrieves sub-applications for the root application provided in the authentication token. If a sub-application is provided in the authentication token, it will return an empty list.

Request

Security:

basicAuth

query Parameters

object

Responses

200

The sub-applications that are returned as part of the search results.

400

There are validation errors

401

Either authentication credentials were not supplied, or they were invalid.

403

Forbidden from accessing the requested Application.

500

An unexpected error occurred.

get/applications

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/applications?applicationIds=497f6eca-6276-4993-bfeb-53cbbbba6f08&limit=1000&offset=0&sort=name'

Response samples

application/json

{"meta": {"tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154",
"count": 1,
"pagination": {"offset": 0,
"limit": 1,
"totalCount": 1
}
},
"data": [{"id": "2698db90-6635-4f76-b673-5ce8e2aeda0e",
"name": "Merchant Uno",
"merchantCategoryCode": 7995,
"ppcUserGroup": "WHOLESALE_FI_FI",
"callbackUrls": ["https://www.callback-service.com"
],
"isContractPresent": true,
"rootApplicationId": "eb25e1ee-f6af-4131-92fe-748e177bf950"
}
]
}

Get application detailsbeta

Retrieves an application by the id provided in the path

Request

Security:

basicAuth

path Parameters

applicationId

required

string <uuid>

The id of the application being fetched

Responses

200

Application was successfully fetched

401

Either authentication credentials were not supplied, or they were invalid.

403

Forbidden from accessing the requested Application.

404

Application with given id not found.

500

An unexpected error occurred.

get/applications/{applicationId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/applications/{applicationId}'

Response samples

application/json;charset=UTF-8

{"meta": {"tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154"
},
"data": {"id": "2698db90-6635-4f76-b673-5ce8e2aeda0e",
"name": "Merchant Uno",
"merchantCategoryCode": 7995,
"ppcUserGroup": "WHOLESALE_FI_FI",
"callbackUrls": ["https://www.callback-service.com"
],
"isContractPresent": true,
"rootApplicationId": "eb25e1ee-f6af-4131-92fe-748e177bf950"
}
}

Update an Applicationbeta

Updates the application properties for the application with the given ID in the path

Request

Security:

basicAuth

path Parameters

applicationId

required

string <uuid>

The id of the application being updated

Request Body schema: application/json

The application to update

name required	string <^[a-zA-Z0-9 \-_\[\]]+$> The name of the application
merchantCategoryCode required	string <^\d{4}$> The ISO-18245 merchant category code of the merchant the application is being created for. Allowed values: `0742` (Veterinary Services) `0763` (Agricultural Cooperatives) `0780` (Landscaping and Horticultural Services) `1520` (General Contractor/Residential Building) `1711` (Heating, Plumbing, Air Conditioning Contractors) `1731` (Electrical Contractors) `1740` (Masonry, Stonework, Tile Setting, Plastering, Insulation Contractors) `1750` (Carpentry) `1761` (Roof, Siding, and Sheet Metal Work Contractors) `1771` (Contractors, Concrete) `1799` (Special Trade Contractor - Not Elsewhere Classified) `2741` (Miscellaneous Publishing and Printing Services) `2791` (Typesetting, Plate Making and Related Services (Business to Business MCC)) `2842` (Specialty Cleaning, Polishing and Sanitation Preparations (Business to Business MCC)) `3000` (United Airlines) `3001` (American Airlines) `3002` (Pan American) `3003` (Eurofly Airlines) `3004` (Dragon Airlines) `3005` (British Airways) `3006` (Japan Air Lines) `3007` (Air France) `3008` (Lufthansa) `3009` (Air Canada) `3010` (KLM) `3011` (AeroFlot) `3012` (Qantas) `3013` (Alitalia) `3014` (Saudi Arabian Airlines) `3015` (SWISS) `3016` (SAS) `3017` (South African Airway) `3018` (Varig (Brazil)) `3020` (Air India) `3021` (Air Algerie) `3022` (PAL AIR) `3023` (Mexicana) `3024` (Pakistan International) `3025` (Air New Zealand Ltd.) `3026` (Emirates Airlines) `3027` (UTA/InterAir) `3028` (Air Malta) `3029` (SN Brussels Airlines - SN BRUSSELS) `3030` (Aerolineas Argentinas) `3031` (Olympic Airways) `3032` (El Al) `3033` (Ansett Airlines) `3034` (ETIHADAIR) `3035` (TAP (Portugal)) `3036` (VASP (Brazil)) `3037` (EgyptAir) `3038` (Kuwait Airways) `3039` (Avianca) `3040` (GulfAir (Bahrain)) `3041` (Balkan-Bulgarian) `3042` (FinnAir) `3043` (Aer Lingus) `3044` (Air Lanka) `3045` (Nigeria Airways) `3046` (Cruzeiro do Sul (Bra)) `3047` (THY (Turkey)) `3048` (Royal Air Maroc) `3049` (Tunis Air) `3050` (Icelandair) `3051` (Austrian Airlines) `3052` (LANAIR) `3053` (AVIACO (Spain)) `3054` (Ladeco (Chile)) `3055` (LAB (Bolivia)) `3056` (JetAir) `3057` (Virgin America – VIR AMER) `3058` (Delta) `3059` (DBA Airlines-DBA AIR) `3060` (NWA Air) `3061` (Continental) `3062` (Hapag-Lloyd Express - HLX) `3063` (US Airways) `3064` (Adria Airways) `3065` (Airinter (AirInternational)) `3066` (Southwest) `3068` (AIR STANA) `3069` (Sun Country Air) `3070` (Pacific Southwest Airlines (PSA)) `3071` (Air British Columbia) `3072` (CEBU PAC) `3073` (Air Cal) `3075` (Singapore Airlines) `3076` (Aeromexico) `3077` (Thai Airways) `3078` (China Airlines) `3079` (Jetstar Airways - Jetstar) `3081` (NordAir) `3082` (Korean Airlines) `3083` (Air Afrique) `3084` (Eva Airlines) `3085` (Midwest Express Airlines, Inc) `3087` (Metro Airlines) `3088` (Croatia Airlines) `3089` (Tans Saero) `3090` (Uni Airways) `3094` (Zambia Airways) `3096` (Air Zimbabwe) `3097` (Spanair (abbreviation: SPANAIR)) `3098` (Asiana Airlines) `3099` (Cathay Pacific) `3100` (Malaysian Airline Sys) `3102` (Iberia) `3103` (Garuda (Indonesia)) `3105` (Piedmont) `3106` (Braathens S.A.F.E. (Norway)) `3110` (Wings Airways) `3111` (British Midland) `3112` (Windward Island) `3117` (Venezolana Int de Aviacion) `3118` (Valley Airlines) `3125` (Tan Airlines) `3126` (Talair PTY Ltd.) `3127` (Taca International) `3129` (Surinam Airways) `3130` (Sunworld International Airways) `3131` (VLM Air) `3132` (Frontier Airlines) `3133` (Sunbelt Airlines) `3135` (Sudan Airlines) `3136` (Qatar Air) `3137` (Singleton) `3138` (Simmons Airlines) `3141` (Seair Alaska) `3143` (Scenic Airlines) `3144` (Virgin Atlantic) `3145` (San Juan) `3146` (Luxair) `3148` (Air Littoral SA) `3151` (Air Laire) `3154` (Princeville) `3156` (Go Fly) `3159` (PBA-Provincetwn-Bstn Air) `3161` (All Nippon Airways) `3164` (Norontair) `3165` (New York Helicopter) `3167` (Aero Continente - AEROCONTINENTE) `3170` (Mount Cook) `3171` (Canadian Airlines) `3172` (Nation Air) `3174` (JetBlue Airways) `3175` (Middle East Air) `3176` (Metroflight Airlines) `3177` (AirTran Airways) `3178` (Mesa Air) `3180` (Westjet Airlines-WESTJET) `3181` (Malev Hungarian Airlines) `3182` (LOT (Poland)) `3183` (Oman Aviation - OMAN AIR) `3184` (LIAT) `3185` (LAV (Venezuela)) `3186` (LAP (Paraguay)) `3187` (LACSA (Costa Rica)) `3188` (Virgin Express - VIR EXP) `3190` (Jugoslav Air) `3191` (Island Airlines) `3192` (Iran Air) `3193` (Indian Airlines) `3195` (Holiday Airlines) `3196` (Hawaiian Air) `3197` (Havasu Airlines) `3198` (Harbor Airlines) `3199` (Servicios Aereos Militares) `3200` (Guyana Airways) `3203` (Golden Pacific Air) `3204` (Freedom Airlines) `3206` (China Eastern Airlines (Abbr: China East Air)) `3207` (Empresa Ecuatoriana) `3211` (Norwegian Air Shuttle - NORWEGIANAIR) `3212` (Dominicana de Aviacion) `3213` (Malmo Aviation - MALMO AV) `3215` (Dan Air Services) `3216` (Cumberland Airlines) `3217` (CSA-Ceskoslovenske Aeroln) `3218` (Crown Air) `3219` (Copa) `3220` (Compania Faucett) `3221` (Transportes Aeros Mil) `3222` (Command Airways) `3223` (Comair) `3226` (Skyways Air- SKYWAYS) `3228` (Cayman Airways) `3229` (SAETA) `3231` (SAHSA) `3233` (Capitol Air) `3234` (CARIBAIR) `3235` (Brockway Air) `3236` (Air Arabia Airlines - Air Arab) `3238` (Bemidji Aviation) `3239` (Bar Harbor Airlines) `3240` (Bahamasair) `3241` (Aviateca (Guatemala)) `3242` (Avensa) `3243` (Austrian Air Service) `3245` (Easy Jet - EASYJET) `3246` (Ryan Air - RYANAIR) `3247` (Gol Airlines - GOL) `3248` (Tam Airlines - TAM) `3251` (Aloha Airlines) `3252` (ALM-Antilean Airlines) `3253` (America West) `3254` (U.S. Air Shuttle) `3256` (Alaska Airlines Inc.) `3259` (American Trans Air) `3260` (Spirit Airlines - SPIRIT) `3261` (Air China) `3262` (Reno Air) `3263` (Aero Servicio Carabobo) `3266` (Air Seychelles) `3267` (Air Panama International) `3268` (Air Pacific) `3275` (Air Nevada) `3276` (Air Midwest) `3277` (Air Madagascar) `3279` (Air LA) `3280` (Air Jamaica) `3282` (Air Djibouti) `3284` (Aero Virgin Islands) `3285` (AeroPeru) `3286` (Aero Nicaraguensis) `3287` (Aero Coach Aviation) `3291` (Ariana Afghan) `3292` (Cyprus Airways) `3293` (Ecuatoriana) `3294` (Ethiopian Airlines) `3295` (Kenya Airways) `3296` (Air Berlin-AIRBERLIN) `3297` (Tarom Romanian Air Transport) `3298` (Air Mauritius) `3299` (Wideroe's Flyveselskap) `3351` (Affiliated Auto Rental) `3352` (American International) `3353` (Brooks Rent a Car) `3354` (Action Auto Rental) `3355` (SIXT Car Rental) `3357` (Hertz) `3359` (Payless Car Rental) `3360` (Snappy Car Rental) `3361` (Airways Rent a Car) `3362` (Altra Auto Rental) `3364` (Agency Rent a Car) `3366` (Budget Rent a Car) `3368` (Holiday R-A-C) `3370` (Rent-a-Wreck) `3374` (Accent Rent-A-Car) `3376` (Ajax R-A-C) `3380` (Triangle Rent a Car) `3381` (Europ Car) `3385` (Tropical R-A-C) `3386` (Showcase Rental Cars) `3387` (Alamo Rent a Car) `3388` (Merchants Rent-A-Car, Inc) `3389` (Avis R-A-C) `3390` (Dollar R-A-C) `3391` (Europe by Car) `3393` (National Car Rental) `3394` (Kemwell Group R-A-C) `3395` (Thrify Car Rental) `3396` (Tilden R-A-C) `3398` (Econo Car R-A-C) `3400` (Auto Host Car Rentals) `3405` (Enterprise R-A-C) `3409` (General Rent-a-Car) `3412` (A-1 R-A-C) `3414` (Godfrey National) `3420` (ANSA International) `3421` (Allstate Rent-a-Car) `3423` (Avcar Rent-a-Car) `3425` (Automate Rent-a-Car) `3427` (Avon Rent-a-Car) `3428` (Carey Rent-a-Car) `3429` (Insurance Rent-a-Car) `3430` (Major Rent-a-Car) `3431` (Replacement Rent-a-Car) `3432` (Reserve Rent-a-Car) `3433` (Ugly Duckling R-A-C) `3434` (USA Rent-a-Car) `3435` (Value Rent-a-Car) `3436` (Autohansa Rent-a-Car) `3437` (Cite) `3438` (Interenet Rent-a-Car) `3439` (Millville Rent-a-Car) `3441` (Advantage Rent A Car) `3501` (Holiday Inns) `3502` (Best Western Hotels) `3503` (Sheraton) `3504` (Hilton) `3505` (Forte Hotels) `3506` (Golden Tulip Hotels) `3507` (Friendship Inns) `3508` (Quality Inns) `3509` (Marriott) `3510` (Days Inn Colonial Resort) `3511` (Arabella Hotels) `3512` (Intercontinental Hotels) `3513` (Westin) `3514` (Amerisuites) `3515` (Rodeway Inn) `3516` (LaQuinta Motor Inns) `3517` (Americana Hotels) `3518` (Sol Hotels) `3519` (Pullman International Hotels) `3520` (Meridien Hotels) `3521` (Royal Lahaina Resort) `3522` (Tokyo Group) `3523` (Peninsula Hotels) `3524` (WelcomGroup Hotels) `3525` (Dunfey Hotels) `3526` (Prince Hotels) `3527` (Downtowner Passport) `3528` (Red Lion Inns) `3529` (CP (Canadian Pacific)) `3530` (Renaissance Hotels) `3531` (Kauai Coconut Beach Resort) `3532` (Royal Kona Resort) `3533` (Hotel Ibis) `3534` (Southern Pacific) `3535` (Hilton International) `3536` (AMFAC Hotels) `3537` (ANA Hotels) `3538` (Concorde Hotels) `3539` (Summerfield Suites Hotel) `3540` (Iberotel Hotels) `3541` (Hotel Okura) `3542` (Royal Hotels) `3543` (Four Seasons) `3544` (Cigna Hotels) `3545` (Shangri-La International) `3546` (Hotel Sierra) `3548` (Hotels Melia) `3549` (Auberge des Governeurs) `3550` (Regal 8 Inns) `3551` (Mirage Hotel and Casino) `3552` (Coast Hotel) `3553` (Park Inn by Radisson) `3554` (Pinehurst Resort) `3555` (Treasure Island Hotel and Casino) `3556` (Barton Creek Resort) `3557` (Manhattan East Suite Hotels) `3558` (Jolly Hotels) `3559` (Candlewood Suites) `3560` (Aladdin Resort and Casino) `3561` (Golden Nugget) `3562` (Comfort Inns) `3563` (Journey's End Motels) `3564` (Sam's Town Hotel and Casino) `3565` (Relax Inns) `3566` (Garden Place Hotel) `3567` (Soho Grand Hotel) `3568` (Ladbroke Hotels) `3569` (Tribeca Grand Hotel) `3570` (Forum Hotels) `3571` (Grand Wailea Resort) `3572` (Miyako Hotel) `3573` (Sandman Hotels) `3574` (Venture Inn) `3575` (Vagabond Hotels) `3576` (La Quinta Resort) `3577` (Mandarin Oriental Hotel) `3578` (Frankenmuth Bavarian) `3579` (Hotel Mercure) `3580` (Hotel Del Coronado) `3581` (Delta Hotels) `3582` (California Hotel and Casino) `3583` (Radisson BLU) `3584` (Princess Hotels International) `3585` (Hungar Hotels) `3586` (Sokos Hotels) `3587` (Doral Hotels) `3588` (Helmsley Hotels) `3589` (Doral Golf Resort) `3590` (Fairmont Hotel) `3591` (Sonesta Hotels) `3592` (Omni Hotels) `3593` (Cunard Hotels) `3594` (Arizona Biltmore) `3595` (Hospitality Inns) `3596` (Wynn Las Vegas) `3597` (Riverside Resort and Casino) `3598` (Regent International Hotels) `3599` (Pannonia Hotels) `3600` (Saddlebrook Resort - Tampa) `3601` (Trade Winds Resorts) `3602` (Hudson Hotel) `3603` (Noah's Hotel) `3604` (Hilton Garden Inn) `3605` (Jurys Doyle Hotel Group) `3606` (Jefferson Hotel) `3607` (Fountainebleau Resort) `3608` (Gaylord Opryland) `3609` (Gaylord Palms) `3610` (Gaylord Texan) `3611` (C MON INN) `3612` (Movenpick Hotels) `3613` (Microtel Inns & Suites) `3614` (Americinn) `3615` (Travelodge Motels) `3617` (America's Best Value Inn) `3618` (Great Wolf) `3619` (Aloft) `3620` (Binion's Horseshoe Club) `3621` (Extended Stay) `3622` (Merlin Hotel) `3623` (Dorint Hotels) `3624` (Lady Luck Hotel and Casino) `3625` (Hotel Universale) `3626` (Studio Plus) `3627` (Extended Stay America) `3628` (Excalibur Hotel and Casino) `3629` (Dan Hotels) `3630` (Extended Stay Deluxe) `3631` (Sleep Inn) `3632` (The Phoenician) `3633` (Rank Hotels) `3634` (Swissotel) `3635` (Reso Hotel) `3636` (Sarova Hotels) `3637` (Ramada Inns) `3638` (Howard Johnson) `3639` (Mount Charlotte Thistle) `3640` (Hyatt Motels) `3641` (Sofitel Hotels) `3642` (Novotel) `3643` (Steigenberger Hotels) `3644` (EconoLodges) `3645` (Queens Moat Houses) `3646` (Swallow Hotels) `3647` (Husa Hotels) `3648` (De Vere Hotels) `3649` (Radisson) `3650` (Red Roof Inns) `3651` (Imperial London Hotel) `3652` (Embassy Hotels) `3653` (Penta Hotels) `3654` (Loews Hotels) `3655` (Scandic Hotels) `3656` (Sara Hotels) `3657` (Oberoi Hotels) `3658` (New Otani Hotels) `3659` (Taj Hotels International) `3660` (Knights Inn) `3661` (Metropole Hotels) `3662` (Circus Circus Hotel and Casino) `3663` (Hoteles El Presidente) `3664` (Flag Inns) `3665` (Hampton Inn Hotels) `3666` (Stakis Hotels) `3667` (Luxor Hotel and Casino) `3668` (Maritim Hotels) `3669` (Eldorado Hotel and Casino) `3670` (Arcade Hotels) `3671` (Arctia Hotels) `3672` (Campanile Hotels) `3673` (IBUSZ Hotels) `3674` (Rantasipi Hotels) `3675` (Interhotel CEDOK) `3676` (Monte Carlo Hotel and Casino) `3677` (Climat de France Hotels) `3678` (Cumulus Hotels) `3679` (Silver Legacy Hotel and Casino) `3680` (Hoteis Othan) `3681` (Adams Mark Hotels) `3682` (Sahara Hotel and Casino) `3683` (Bradbury Suites) `3684` (Budget Hosts Inns) `3685` (Budgetel Hotels) `3686` (Suisse Chalet) `3687` (Clarion Hotels) `3688` (Compri Hotels) `3689` (Consort Hotels) `3690` (Courtyard Inns) `3691` (Dillon Inn) `3692` (Doubletree) `3693` (Drury Inn) `3694` (Economy Inns of America) `3695` (Embassy Suites) `3696` (Excel Inn) `3697` (Fairfield Hotels) `3698` (Harley Hotels) `3699` (Midway Motor Lodge) `3700` (Motel 6) `3701` (La Mansion Del Rio) `3702` (The Registry Hotels) `3703` (Residence Inn) `3704` (Royce Hotels) `3705` (Sandman Inn) `3706` (Shilo Inn) `3707` (Shoney's Inn) `3708` (Virgin River Hotel and Casino) `3709` (Super 8 Motels) `3710` (The Ritz Carlton Hotels) `3711` (Flag Inns (Australia)) `3712` (Buffalo Bill's Hotel and Casino) `3713` (Quality Pacific Hotel) `3714` (Four Seasons Hotels-Austr) `3715` (Fairfield Inn) `3716` (Carlton Hotels) `3717` (City Lodge Hotels) `3718` (Karos Hotels) `3719` (Protea Hotels) `3720` (Southern Sun Hotels) `3721` (Hilton Conrad Hotels) `3722` (Wyndham Hotels) `3723` (Rica Hotels) `3724` (Inter Nor Hotels) `3725` (SeaPines Plantation) `3726` (Rio Suites) `3727` (Broadmoor Hotel) `3728` (Bally's Hotel and Casino) `3729` (John Ascuaga's Nugget) `3730` (MGM Grand Hotel) `3731` (Harrah's Hotels and Casinos) `3732` (Opryland Hotel) `3733` (Boca Raton Resort) `3734` (Harvey/Bristol Hotels) `3735` (Master Economy Inns) `3736` (Colorado Belle/Edgewater Resort) `3737` (Riviera Hotel and Casino) `3738` (Tropicana Resort & Casino) `3739` (Woodside Hotels & Resorts) `3740` (Towneplace Suites) `3741` (Millennium Hotel) `3742` (Club Med) `3743` (Biltmore Hotel and Suites) `3744` (Carefree Resorts) `3745` (St. Regis Hotel) `3746` (The Eliot Hotel) `3747` (ClubCorp/ClubResorts) `3748` (Wellesley Inns) `3749` (The Beverly Hills Hotel) `3750` (Crown Plaza Hotels) `3751` (Homewood Suites) `3752` (Peabody Hotels) `3753` (Greenbriar Resorts) `3754` (Amelia Island Plantation) `3755` (The Homestead) `3757` (Canyon Ranch) `3758` (Kahala Mandarion Oriental Hotel) `3759` (The Orchid at Mauna Lani) `3760` (Halekulani Hotel/Waikiki Parc) `3761` (Primadonna Hotel and Casino) `3762` (Whisky Pete's Hotel and Casino) `3763` (Chateau Elan Winery and Resort) `3764` (Beau Rivage Hotel and Casino) `3765` (Bellagio) `3766` (Fremont Hotel and Casino) `3767` (Main Street Hotel and Casino) `3768` (Silver Star Hotel and Casino) `3769` (Stratosphere Hotel and Casino) `3770` (SpringHill Suites) `3771` (Caesar's Resort) `3772` (Nemacolin Woodlands) `3773` (The Venetian Resort Hotel and Casino) `3774` (New York-New York Hotel and Casino) `3775` (Sands Resort) `3776` (Nevele Grande Resort and Country Club) `3777` (Mandalay Bay Resort) `3778` (Four Points Hotels) `3779` (W Hotels) `3780` (Disney Resorts) `3781` (Patricia Grand Resort Hotels) `3782` (Rosen Hotels & Resort) `3783` (Town and Country Resort and Convention Center) `3784` (First Hospitality Hotel) `3785` (Outrigger Hotels and Resorts) `3786` (Ohana Hotel of Hawaii) `3787` (Caribe Royale Resort Suites & Villas) `3788` (Ala Moana Hotel / Ala Moana Hotels) `3789` (Smugglers' Notch Resort) `3790` (Raffles Hotels) `3791` (Staybridge Suites) `3792` (Claridge Casino Hotel) `3793` (The Flamingo Hotels) `3794` (Grand Casino Hotels) `3795` (Paris Las Vegas Hotel) `3796` (Peppermill Hotel Casino) `3797` (Atlantic City Hilton) `3798` (Embassy Vacation Resort) `3799` (Hale Koa Hotel) `3800` (Homestead) `3801` (Wilderness Hotel and Golf Resort) `3802` (The Palace Hotel) `3807` (Element) `3808` (LXR) `3810` (La Costa Resort) `3811` (Premier Travel Inn) `3812` (Hyatt Place) `3813` (Hotel Indigo) `3814` (The Roosevelt Hotel NY) `3815` (Holiday Inn Nickelodeon) `3816` (Home2 Suites) `3817` (Affinia) `3818` (Mainstay Suites) `3819` (Oxford Suites) `3820` (Jumeirah Essex House) `3821` (Caribe Royale) `3822` (Crossland) `3823` (Grand Sierra Resort) `3824` (Aria) `3825` (Vdara) `3826` (Autograph) `3827` (Galt House) `3828` (Cosmopolitan of Las Vegas) `3829` (Country Inn by Carlson) `3830` (Park Plaza Hotel) `3831` (Waldorf) `4011` (Railroads) `4111` (Local and Suburban Commuter Passenger Transportation, including Ferries) `4112` (Passenger Rail (train)) `4119` (Ambulance Services) `4121` (Taxicabs and Limousines) `4131` (Bus Lines, includes Charters/Tour Buses) `4214` (Motor Freight Carriers and Trucking-Local and Long Distance, Moving & Storage Companies, and Local Delivery) `4215` (Courier Services-Air and Ground, and Freight Forwarders) `4225` (Public Warehousing-Farm products, Refrigerated Goods, Household Goods, and Storage) `4411` (Steamship and Cruise Lines) `4457` (Boat Rentals and Leasing) `4468` (Marinas, Marine Service, and Supplies) `4511` (Airlines and Air Carriers) `4582` (Airports, Flying Fields, and Airport Terminals) `4722` (Travel Agencies) `4723` (Package Tour Operators (Germany Only)) `4761` (Telemarketing of Travel Related Services and Vitamins) `4784` (Bridge and Road Fees, Tolls) `4789` (Transportation Services-not elsewhere classified) `4812` (Telecommunication Equipment and Telephone Sales) `4813` (Special Telecom Merchant) `4814` (Telecommunication Services, Including Local and Long Distance Calls, Credit Card Calls, Call Through Use of Magnetic-Strip-Reading Telephones, and Fax Services) `4815` (Monthly Summary Telephone Charges) `4816` (Computer Network/Information Services and other Online Services such as electronic bulletin board, e-mail, web site hosting services, or Internet access) `4821` (Telegraph Services) `4829` (Quasi Cash - Money Transfer) `4899` (Cable, Satellite, and Other Pay Television and Radio Services) `4900` (Utilities-Electric, Gas, Water, and Sanitary) `5013` (Motor Vehicle Supplies and New Parts (Business to Business MCC)) `5021` (Office Furniture (Business to Business MCC)) `5039` (Construction Materials Not Elsewhere Classified (Business to Business MCC)) `5044` (Photographic, Photocopy, Microfilm Equipment and Supplies (Business to Business MCC)) `5045` (Computers, Computer Peripheral Equipment, and Software) `5046` (Commercial Equipment Not Elsewhere Classified (Business to Business MCC)) `5047` (Dental/Laboratory/Medical/Ophthalmic Hospital Equipment and Supplies) `5051` (Metal Service Centers and Offices (Business to Business MCC)) `5065` (Electrical Parts and Equipment (Business to Business MCC)) `5072` (Hardware, Plumbing, Heat Equipment and Supplies (Business to Business MCC)) `5074` (Plumbing and Heating Equipment and Supplies (Business to Business MCC)) `5085` (Industrial Supplies Not Elsewhere Classified (Business to Business MCC)) `5094` (Precious Stones, Metals, Watches and Jewelry (Business to Business MCC)) `5099` (Durable Goods Not Elsewhere Classified (Business to Business MCC)) `5111` (Stationery, Office Supplies, and Printing and Writing Paper) `5122` (Drugs, Drug Proprietary's, and Druggists' Sundries) `5131` (Piece Goods, Notions and Other Dry Goods (Business to Business MCC)) `5137` (Men's, Women's and Children's Uniforms (Business to Business MCC)) `5139` (Commercial Footwear (Business to Business MCC)) `5169` (Chemicals and Allied Products Not Elsewhere Classified (Business to Business MCC)) `5172` (Petroleum and Products (Business to Business MCC)) `5192` (Books, Periodicals and Newspapers (Business to Business MCC)) `5193` (Florist Suppliers, Nursery Stock & Flowers (Business to Business MCC)) `5198` (Paints, Varnishes and Supplies (Business to Business MCC)) `5199` (Non-durable Goods Not Elsewhere Classified (Business to Business MCC)) `5200` (Home Supply Warehouse) `5211` (Lumber & Building Materials Stores) `5231` (Glass, Paint, and Wallpaper Stores) `5251` (Hardware Stores, Equipment Utilities Regulated) `5261` (Nurseries and Lawn and Garden Supply Stores) `5271` (Mobile Home Dealer) `5300` (Wholesale Club with or without membership fee) `5309` (Duty Free Stores) `5310` (Discount Store) `5311` (Department Stores) `5331` (Variety Stores) `5399` (Miscellaneous General Merchandise) `5411` (Grocery Stores and Supermarkets) `5422` (Freezer & Locker Meat Provisions) `5441` (Candy, Nut, and Confectionary Stores) `5451` (Dairy Product Stores) `5462` (Bakeries) `5499` (Miscellaneous Food Stores-Convenience Stores and Specialty Markets) `5511` (Car and Truck Dealers (New and Used)- Sales, Service, Repairs, Parts, and Leasing) `5521` (Car and Truck Dealers (Used)- Sales, Service, Repairs, Parts, and Leasing) `5532` (Automotive Tire Stores) `5531` (Auto and Home Supply Stores) `5533` (Automotive Parts and Accessories Stores) `5541` (Service Stations (with or without Ancillary Services)) `5542` (Automated Fuel Dispensers) `5551` (Boat Dealers) `5561` (Camper, Recreational and Utility Trailer Dealers) `5571` (Motorcycle Dealers) `5592` (Motor Home Dealers) `5598` (Snowmobile Dealers) `5599` (Miscellaneous Automotive, Aircraft, and Farm Equipment Dealers --Not Elsewhere Classified) `5611` (Men's & Boys' Clothing and Accessory Stores) `5621` (Women's Ready-to-Wear Stores) `5631` (Women's Accessory and Specialty Stores) `5641` (Children's and Infants' Wear Stores) `5651` (Family Clothing Stores) `5655` (Sports and Riding Apparel Stores) `5661` (Shoe Stores) `5681` (Furriers & Fur Shops) `5691` (Men's and Women's Clothing Stores) `5697` (Tailors, Seamstresses, Mending, Alterations) `5698` (Wig & Toupee Shops) `5699` (Miscellaneous Apparel and Accessory Stores) `5712` (Furniture, Home Furnishings, and Equipment Stores, except Appliances) `5713` (Floor coverings, Rugs) `5714` (Drapery, Window Covering, and Upholstery Stores) `5718` (Fireplaces, Fireplace Screens and Accessories Stores) `5719` (Miscellaneous Home Furnishing Specialty Stores) `5722` (Household Appliance Stores) `5732` (Electronics Stores) `5733` (Music Stores-Musical Instruments, Pianos, and Sheet Music) `5734` (Computer Software Stores) `5735` (Record Stores) `5811` (Caterers - Prepare & Delivery) `5812` (Eating Places and Restaurants) `5813` (Drinking Places (Alcoholic Beverages) - Bars, Taverns, Nightclubs, Cocktail Lounges, and Discotheques) `5814` (Quick Payment Service-Fast Food Restaurants) `5815` (Digital Goods – Media, Books, Movies, Music) `5816` (Digital Goods – Games) `5817` (Digital Goods – Applications (Excludes Games)) `5818` (Large Digital Goods Merchant) `5912` (Drug Stores and Pharmacies) `5921` (Package Stores--Beer, Wine, and Liquor) `5931` (Used Merchandise and Secondhand Stores) `5932` (Antique Shop) `5933` (Pawn Shop) `5935` (Wrecking and Salvage Yards) `5937` (Antique Reproduction Stores) `5940` (Bicycle Shop-Sales and Services) `5941` (Sporting Goods Stores) `5942` (Book Stores) `5943` (Stationery, Office and School Supply Stores) `5944` (Jewelry, Watch, Clock, and Silverware Stores) `5945` (Hobby, Toy and Game Stores) `5946` (Camera and Photographic Supply Stores) `5947` (Gift, Card, Novelty, and Souvenir Stores) `5948` (Luggage and Leather Goods Stores) `5949` (Sewing, Needlework, Fabric, and Piece Good Stores) `5950` (Glassware and Crystal Stores) `5960` (Direct Marketing Insurance Services) `5961` (Mail Order) `5962` (Direct Marketing -- Travel Related Arrangement Services) `5963` (Direct Selling Establishments/Door to Door Sales) `5964` (Catalog Merchant) `5965` (Combined Catalog and Retail Merchant) `5966` (Outbound Telemarketing Merchant) `5967` (Direct Marketing -- Inbound Telemarketing Merchants) `5968` (Continuity/Subscription Merchants) `5969` (Direct Marketing/Direct Marketers--Not Elsewhere Classified) `5970` (Artist Supply and Craft Stores) `5971` (Art Dealers and Galleries) `5972` (Stamp and Coin Stores) `5973` (Religious Goods Stores) `5975` (Hearing Aids--Sales, Service, and Supplies) `5976` (Orthopedic Goods and Prosthetic Devices) `5977` (Cosmetic Stores) `5978` (Typewriter Stores--Sales, Service, and Rentals) `5983` (Fuel Dealers--Fuel Oil, Wood, Coal, and Liquefied Petroleum) `5992` (Florists) `5993` (Cigar Stores & Stands) `5994` (News Dealers & Newsstands) `5995` (Pet Shops, Pet Food, and Supplies) `5996` (Swimming Pools--Sales, Supplies, and Services) `5997` (Electric Razor Stores Sales & Services) `5998` (Tent and Awning Stores) `5999` (Miscellaneous & Specialty Retail Stores) `6010` (Financial Institutions--Manual Cash Disbursements) `6011` (Financial Institutions--Automated Cash Disbursements) `6012` (Quasi Cash - Financial Institution - Merchandise and Services) `6050` (Quasi Cash - Member Financial Institution) `6051` (MasterCard - Quasi Cash-Merchant) `6211` (Securities - Brokers and Dealers) `6300` (Insurance Sales and Underwriting) `6381` (Insurance - Premiums) `6399` (Insurance - Not Elsewhere Classified) `6513` (Real Estate Agents and Managers - Rentals; Property Management) `6529` (Remote Stored Value Load - Member Financial Institution) `6530` (Remote Stored Value Load - Merchant) `6531` (Payment Service Provider) `6532` (Payment Transaction - Member) `6533` (Payment Transaction - Merchant) `6534` (Money Transfer - Member Financial Institution) `6535` (Value Purchase - Member Financial Institution) `6536` (MoneySend Intracountry) `6537` (MoneySend Intercountry) `6538` (MoneySend Funding) `6540` (POI Funding Transactions (Excluding MoneySend)) `7011` (Lodging - Hotels, Motels, and Resorts) `7012` (Timeshares) `7032` (Sporting and Recreational Camps) `7033` (Trailer Parks and Campgrounds) `7210` (Laundry, Cleaning, and Garment Services) `7211` (Laundry Services - Family and Commercial) `7216` (Dry Cleaners) `7217` (Carpet and Upholstery Cleaning) `7221` (Photographic Studios) `7230` (Beauty and Barber Shops) `7251` (Shoe Repair Shops, Shoe Shine Parlors, and Hat Cleaning Shops) `7261` (Funeral Services and Crematories) `7273` (Dating Services) `7276` (Tax Preparation Services) `7277` (Counseling Services - Debt, Marriage, and Personal) `7278` (Buying and Shopping Services and Clubs) `7296` (Clothing Rental - Costumes, Uniforms and Formal Wear) `7297` (Massage Parlors) `7298` (Health and Beauty Spas) `7299` (Miscellaneous Personal Services - Not Elsewhere Classified) `7311` (Advertising Services) `7321` (Consumer Credit Reporting Agencies) `7332` (Blueprinting and Photocopying Services) `7333` (Commercial Photography, Art, and Graphics) `7338` (Quick Copy, Reproduction Service) `7339` (Stenographic Service) `7342` (Exterminating and Disinfecting Services) `7349` (Cleaning, Maintenance & Janitorial Services) `7361` (Employment Agencies and Temporary Help Services) `7372` (Computer Programming, Data Processing, and Integrated Systems Design Services) `7375` (Information Retrieval Services (Business to Business MCC)) `7379` (Computer Maintenance, Repair and Services (Business to Business MCC)) `7392` (Management, Consulting, and Public Relations Services) `7393` (Detective Agencies, Protective Agencies, and Security Services, including Armored Cars and Guard Dogs) `7394` (Equipment, Tool, Furniture, and Appliance Rental and Leasing) `7395` (Photofinishing Laboratories and Photo Developing) `7399` (Business Services) `7511` (Truck Stops) `7512` (Automobile Rental Agency) `7513` (Truck and Utility Trailer Rentals) `7519` (Motor Home and Recreational Vehicle Rentals) `7523` (Parking Lots and Garages) `7524` (Express Payment Service Mechants - Parking Lots and Garages) `7531` (Automotive Top & Body Shops) `7534` (Tire Retreading & Repair) `7535` (Automotive Paint Shops) `7538` (Automotive Service Shops (Non-Dealer)) `7542` (Car Washes) `7549` (Towing Services) `7622` (Electronic Repair Shops) `7623` (Air Conditioning and Refrigeration Repair Shops) `7629` (Electrical and Small Appliance Repair Shops) `7631` (Watch, Clock, and Jewelry Repair Shops) `7641` (Furniture - Reupholster, Repair, and Refinishing) `7692` (Welding Services) `7699` (Miscellaneous Repair Shops and Related Services) `7778` (Citishare Cash Advance) `7800` (Government-Owned Lotteries) `7801` (Government-Licensed Casinos (Online Gambling)) `7802` (Government-Licensed Horse/Dog Racing) `7829` (Motion Picture & Video Tape Production and Distribution (Business to Business MCC)) `7832` (Motion Picture Theater) `7841` (DVD/Video Tape Rental Stores) `7911` (Dance Halls, Studios & Schools) `7922` (Theatrical Producers (except Motion Pictures) and Ticket Agencies) `7929` (Bands, Orchestras & Misc Entertainment) `7932` (Billiards & Pool Establishments) `7933` (Bowling Alleys) `7941` (Commercial Sports, Professional Sports Clubs, Athletic Fields, and Sports Promoters) `7991` (Tourist Attractions and Exhibits) `7992` (Public Golf Courses) `7993` (Video Amusement Game Supply) `7994` (Video Game Arcades and Establishments) `7995` (Betting, including Lottery Tickets, Casino Gaming Chips, Off- Track Betting, and Wagers at Race Track) `7996` (Amusement Parks, Circuses, Carnivals, and Fortune Tellers) `7997` (Membership Clubs (Sports, Recreation, Athletic), Country Clubs, and Private Golf Courses) `7998` (Aquarium, Seaquarium, Dolphinariums) `7999` (Recreation Services - Not Elsewhere Classified) `8011` (Doctors and Physicians - Not Elsewhere Classified) `8021` (Dentists and Orthodontists) `8031` (Osteopathic Physicians) `8041` (Chiropractors) `8042` (Optometrists and Ophthalmologists) `8043` (Opticians, Optical Goods and Eyeglasses) `8049` (Podiatrists and Chiropodists) `8050` (Nursing and Personal Care Facilities) `8062` (Hospitals) `8071` (Medical and Dental Laboratories) `8099` (Medical Services Health Practitioners - No Elsewhere Classified) `8111` (Legal Services and Attorneys) `8211` (Elementary and Secondary Schools) `8220` (Colleges, Universities, Professional Schools, and Junior Colleges) `8241` (Correspondence Schools) `8244` (Business and Secretarial Schools) `8249` (Trade and Vocational Schools) `8299` (Schools and Educational Services - Not Elsewhere Classified) `8351` (Child Care Services) `8398` (Charitable and Social Service Organizations) `8641` (Civic, Social, and Fraternal Associations) `8651` (Political Organizations) `8661` (Religious Organizations) `8675` (Automobile Associations) `8699` (Membership Organizations - Not Elsewhere Classified) `8734` (Testing Laboratories (Not Medical) - (Business to Business MCC)) `8911` (Architectural, Engineering, and Surveying Services) `8931` (Accounting, Auditing, and Bookkeeping Services) `8999` (Professional Services - Not Elsewhere Classified) `9211` (Court Costs, including Alimony and Child Support) `9222` (Fines) `9223` (Bail & Bond Payments) `9311` (Tax Payments) `9399` (Government Services - Not Elsewhere Classified) `9401` (i-Purchasing) `9402` (Postal Services) `9405` (U.S. Fed Government Agencies) `9700` (Automated Referral Service) `9701` (Visa Credential Server) `9702` (GCAS Emergency Services) `9751` (U.K. Supermarkets, Electronic Hot File) `9752` (U.K. Petrol Stations, Electronic Hot File) `9753` (Consumer Electronics/Furniture Store) `9754` (Quasi Cash - Gambling-Horse Racing, Dog Racing, State Lotteries) `9950` (Intra-Company Purchases)
ppcUserGroup required	string The payment user group from the purpose code list for the application. Allowed values: WHOLESALE_FI_FI COMMERCIAL CONSUMER_GOODS_SERVICES FINANCE INSURANCE PROPERTY UTILITIES TAX SALARIES_INCOMES INVESTMENTS FOREIGN_EXCHANGE GOVERNMENT BENEFIT_PAYMENTS MEDICAL PENSIONS
callbackUrls	Array of strings The application callback URLs
isContractPresent required	boolean Indicates if a contract is in place with the merchant and a KYB process has been completed

Responses

200

Application was successfully updated

400

There are validation errors

401

Either authentication credentials were not supplied, or they were invalid.

403

Forbidden from accessing the requested Application.

500

An unexpected error occurred.

put/applications/{applicationId}

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

{"name": "Merchant Uno",
"merchantCategoryCode": 7995,
"ppcUserGroup": "WHOLESALE_FI_FI",
"callbackUrls": ["https://www.callback-service.com"
],
"isContractPresent": true
}

Response samples

application/json;charset=UTF-8

{"meta": {"tracingId": "0c2d0973bdd24224a65e5d0f7d1b6154"
},
"data": {"id": "2698db90-6635-4f76-b673-5ce8e2aeda0e",
"name": "Merchant Uno",
"merchantCategoryCode": 7995,
"ppcUserGroup": "WHOLESALE_FI_FI",
"callbackUrls": ["https://www.callback-service.com"
],
"isContractPresent": true,
"rootApplicationId": "eb25e1ee-f6af-4131-92fe-748e177bf950"
}
}

Delete an applicationbeta

Deletes the application with the given ID in the path

Request

Security:

basicAuth

path Parameters

applicationId

required

string <uuid>

The id of the application being deleted

Responses

204

Application was successfully deleted

401

Either authentication credentials were not supplied, or they were invalid.

403

Forbidden from accessing the requested Application.

404

Application with given id not found.

500

An unexpected error occurred.

delete/applications/{applicationId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X DELETE \
  -u <username>:<password> \
  'https://api.yapily.com/applications/{applicationId}'

Response samples

application/json;charset=UTF-8

Error Response

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

Create application VRP configuration by Application Idbeta

Create application vrp configuration

Request

Security:

basicAuth

path Parameters

applicationId

required

string <uuid>

The id of the application that vrp configuration being created for

Request Body schema: application/json

The vrp configuration to create

	object Maximum amount per transaction
	object Maximum cumulative amount
maximumCumulativeNumberOfPayments	integer >= 0 Maximum cumulative number of payments
	Array of objects (VrpPeriodicLimit) non-empty
recurringPaymentCategory	string Payment Category with allowed values: ONGOING, SUBSCRIPTION

Responses

201

Application vrp configuration was successfully created

400

There are validation errors

401

Either authentication credentials were not supplied, or they were invalid.

403

Forbidden from accessing the requested Application.

404

VRP Configuration with given application id not found.

500

An unexpected error occurred.

post/applications/{applicationId}/vrp

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

{"maximumIndividualAmount": {"amount": 10,
"currency": "GBP"
},
"maximumCumulativeAmount": {"amount": 10,
"currency": "GBP"
},
"maximumCumulativeNumberOfPayments": 0,
"periodicLimits": [{"maximumAmount": {"amount": 10,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CONSENT"
}
],
"recurringPaymentCategory": "ONGOING"
}

Response samples

application/json;charset=UTF-8

{"name-is-mandatory": {"value": {"errors": [{"fieldName": "name",
"error": "MANDATORY"
}
]
}
}
}

Update application VRP configuration by Application Idbeta

Update application vrp configuration

Request

Security:

basicAuth

path Parameters

applicationId

required

string <uuid>

The id of the application that vrp configuration being created for

Request Body schema: application/json

The vrp configuration to create

	object Maximum amount per transaction
	object Maximum cumulative amount
maximumCumulativeNumberOfPayments	integer >= 0 Maximum cumulative number of payments
	Array of objects (VrpPeriodicLimit) non-empty
recurringPaymentCategory	string Payment Category with allowed values: ONGOING, SUBSCRIPTION

Responses

201

Application vrp configuration was successfully updated

400

There are validation errors

401

Either authentication credentials were not supplied, or they were invalid.

403

Forbidden from accessing the requested Application.

404

VRP Configuration with given application id not found.

500

An unexpected error occurred.

put/applications/{applicationId}/vrp

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

{"maximumIndividualAmount": {"amount": 10,
"currency": "GBP"
},
"maximumCumulativeAmount": {"amount": 10,
"currency": "GBP"
},
"maximumCumulativeNumberOfPayments": 0,
"periodicLimits": [{"maximumAmount": {"amount": 10,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CONSENT"
}
],
"recurringPaymentCategory": "ONGOING"
}

Response samples

application/json;charset=UTF-8

{"name-is-mandatory": {"value": {"errors": [{"fieldName": "name",
"error": "MANDATORY"
}
]
}
}
}

Get application VRP configuration by Application Idbeta

Get application vrp configuration

Request

Security:

basicAuth

path Parameters

applicationId

required

string <uuid>

The id of the application that vrp configuration being created for

Responses

200

Application vrp configuration was successfully fetched

400

There are validation errors

401

Either authentication credentials were not supplied, or they were invalid.

403

Forbidden from accessing the requested Application.

404

VRP Configuration with given application id not found.

500

An unexpected error occurred.

get/applications/{applicationId}/vrp

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/applications/{applicationId}/vrp'

Response samples

application/json;charset=UTF-8

{"maximumIndividualAmount": {"amount": 10,
"currency": "GBP"
},
"maximumCumulativeAmount": {"amount": 10,
"currency": "GBP"
},
"maximumCumulativeNumberOfPayments": 0,
"periodicLimits": [{"maximumAmount": {"amount": 10,
"currency": "GBP"
},
"frequency": "MONTHLY",
"alignment": "CONSENT"
}
],
"recurringPaymentCategory": "ONGOING"
}

Enrichment

Enrichment endpoints enable our customers to enrich transaction data.

Trigger transaction categorisationbeta

Trigger categorisation for a specified set of transactions

Request

Security:

basicAuth

path Parameters

accountId

required

string

Unique identifier for account

header Parameters

consent required	string Mandatory. The `consent-token` containing the user's authorisation to make the request. Example: {consentToken}
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.

Request Body schema: application/json

countryCode required	string Mandatory, ISO 3166-1 alpha-2 two-letter country codes e.g. GB
from	string <date-time> Optional. Returned transactions will be on or after this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
before	string <date-time> Optional. Returned transactions will be on or before this date (yyyy-MM-dd'T'HH:mm:ss.SSSZ).
sort	any Optional. Sort transaction records by date ascending with 'date' or descending with '-date'. The default sort order is descending Enum: "-date" "date"

Responses

201

Created

400

Bad Request

401

Unauthorized

500

Internal Server Error

post/accounts/{accountId}/transactions/categorisation

Request samples

Payload
curl
JavaScript
Node.js
Python

application/json

{"countryCode": "GB",
"from": "2019-08-24T14:15:22Z",
"before": "2019-08-24T14:15:22Z",
"sort": "-date"
}

Response samples

application/json

{"meta": {"tracingId": "string"
},
"data": {"categorisationId": "b835bb6a-766d-42bf-8c0c-93921937925a"
}
}

Get Categorised Transactionsbeta

Retrieve a set of categorised transactions using a provided categorisation ID (Note: A categorisation ID will only be valid for 30 mins after a transactions.categorisation.successful wedhook has be received)

Request

Security:

basicAuth

path Parameters

accountId required	string Unique identifier for account
categorisationId required	string Unique identifier for transaction categorisation request

query Parameters

limit

integer <int32>

Optional. The maximum number of transaction records to be returned. Must be between 1 and 1000.

header Parameters

consent

required

string

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

Example: {consentToken}

Responses

200

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/accounts/{accountId}/transactions/categorisation/{categorisationId}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/accounts/{accountId}/transactions/categorisation/{categorisationId}?limit=0' \
  -H 'consent: string'

Response samples

application/json

{"meta": {"tracingId": "string",
"count": 1
},
"data": {"transactions": [{"id": "string",
"date": "string",
"bookingDateTime": "2019-08-24T14:15:22Z",
"valueDateTime": "2019-08-24T14:15:22Z",
"status": "string",
"amount": 0,
"currency": "string",
"transactionAmount": {"amount": 0,
"currency": "string"
},
"reference": "string",
"description": "string",
"transactionInformation": ["string"
],
"proprietaryBankTransactionCode": {"code": "string",
"issuer": "string"
},
"isoBankTransactionCode": {"domainCode": {"code": "string",
"name": "string"
},
"familyCode": {"code": "string",
"name": "string"
},
"subFamilyCode": {"code": "string",
"name": "string"
}
},
"balance": {"type": "string",
"balanceAmount": {"amount": 0,
"currency": "string"
}
},
"enrichment": {"categorisation": {"categories": ["string"
]
},
"recurrence": "string",
"transactionHash": {"hash": "string"
},
"merchant": {"merchantName": "string"
},
"paymentProcessor": "string"
},
"hash": "string"
}
]
},
"links": {"first": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=aaa",
"prev": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=bbb",
"self": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=ccc",
"next": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=ddd",
"last": "https://api.yapily.com/accounts/700004000000000000000002/transactions?cursor=zzz"
}
}

Get the list of all categories for a specific account typebeta

Returns the list of categories that can be returned for a specific account type (consumer or business)

Request

Security:

basicAuth

path Parameters

accountType

required

string

type of bank account (consumer or business)

Responses

200

400

Bad Request

401

Unauthorized

500

Internal Server Error

get/transactions/categorisation/categories/{accountType}

Request samples

curl
JavaScript
Node.js
Python

curl -i -X GET \
  -u <username>:<password> \
  'https://api.yapily.com/transactions/categorisation/categories/{accountType}'

Response samples

application/json

{"meta": {"tracingId": "string"
},
"data": {"incoming": ["string"
],
"outgoing": ["string"
]
}
}

Yapily.com|
Demo|
Status|
Support