openapi: 3.0.1 info: title: Yapily Beneficiaries Application Beneficiaries Constraints API description: Application and User Beneficiaries endpoints for managing reusable payment counterparties. version: 12.4.0 contact: name: Yapily Support url: https://docs.yapily.com/resources/support email: support@yapily.com servers: - url: https://api.yapily.com security: - basicAuth: [] tags: - description: The constraints endpoints can be used to retrieve institution specific data requirements and rules that will apply when performing other operations. name: Constraints paths: /institutions/constraints/payments: get: description: Retrieve institution specific constraints for payment authorisation and submission requests operationId: getPaymentConstraintsRulesByInstitution x-beta: true parameters: - description: Unique Id(s) of the `Institution`(s) to retrieve the Payment Constraints for. Multiple institutionIds need to be separated by `,` name: institutionIds required: true in: query schema: type: array items: type: string - description: 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. in: query name: institutionCountryCode required: true schema: type: string - description: Type of payment to retrieve payment constraints for in: query name: paymentType required: true schema: type: string enum: - DOMESTIC_PAYMENT - DOMESTIC_INSTANT_PAYMENT - DOMESTIC_VARIABLE_RECURRING_PAYMENT - DOMESTIC_SCHEDULED_PAYMENT - DOMESTIC_PERIODIC_PAYMENT - INTERNATIONAL_PAYMENT - INTERNATIONAL_SCHEDULED_PAYMENT - INTERNATIONAL_PERIODIC_PAYMENT - description: The path on the API that is associated with the operation for which constraints are to be retrieved in: query name: endpointPath required: false schema: type: string - description: The HTTP method that is associated with the operation for which constraints are to be retrieved in: query name: endpointMethod required: false schema: type: string enum: - POST - PATCH - PUT - GET - DELETE responses: '200': content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ApiListResponseOfPaymentConstraints' description: Ok '400': content: application/json;charset=UTF-8: examples: 500 Error Response: $ref: '#/components/examples/400-error-response' schema: $ref: '#/components/schemas/ApiResponseError' description: Bad Request. '401': content: application/json;charset=UTF-8: examples: 500 Error Response: $ref: '#/components/examples/401-error-response' schema: $ref: '#/components/schemas/ApiResponseError' description: Either authentication credentials were not supplied, or they were invalid. '404': content: application/json;charset=UTF-8: examples: 500 Error Response: $ref: '#/components/examples/404-error-response' schema: $ref: '#/components/schemas/ApiResponseError' description: Not Found. '500': content: application/json;charset=UTF-8: examples: 500 Error Response: $ref: '#/components/examples/500-error-response' schema: $ref: '#/components/schemas/ApiResponseError' description: Unexpected Error summary: Get Payment Constraints Rules tags: - Constraints x-mint: content: 'Learn more: [Payment Constraints](/payments/payment-resources/payment-constraints) for institution-specific requirements' /institutions/constraints/data: get: description: Get Data Constraints Rules against an Institution for Account Authorisation requests operationId: getAccountConstraintsRulesByInstitution x-beta: true parameters: - description: Unique Id(s) of the `Institution`(s) to retrieve the Data Constraints for. Multiple institutionIds need to be separated by `,` name: institutionIds required: true in: query schema: type: array items: type: string - description: 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. in: query name: institutionCountryCode required: true schema: type: string - description: The path on the API that is associated with the operation for which constraints are to be retrieved in: query name: endpointPath required: false schema: type: string - description: The HTTP method that is associated with the operation for which constraints are to be retrieved in: query name: endpointMethod required: false schema: type: string enum: - POST - PATCH - PUT - GET - DELETE responses: '200': content: application/json;charset=UTF-8: schema: $ref: '#/components/schemas/ApiListResponseOfDataConstraints' description: Ok '400': content: application/json;charset=UTF-8: examples: 500 Error Response: $ref: '#/components/examples/400-error-response' schema: $ref: '#/components/schemas/ApiResponseError' description: Bad Request. '401': content: application/json;charset=UTF-8: examples: 500 Error Response: $ref: '#/components/examples/401-error-response' schema: $ref: '#/components/schemas/ApiResponseError' description: Either authentication credentials were not supplied, or they were invalid. '404': content: application/json;charset=UTF-8: examples: 500 Error Response: $ref: '#/components/examples/404-error-response' schema: $ref: '#/components/schemas/ApiResponseError' description: Not Found. '500': content: application/json;charset=UTF-8: examples: 500 Error Response: $ref: '#/components/examples/500-error-response' schema: $ref: '#/components/schemas/ApiResponseError' description: Unexpected Error summary: Get Data Constraints Rules tags: - Constraints components: schemas: PaymentConstraintsResponse: required: - institutionId - institutionCountry - paymentType - request type: object properties: institutionId: type: string description: The id to represent the `Institution`. example: modelo-sandbox institutionCountryCode: type: string description: 2 letter ISO Country code of the `Institution`. example: GB endpointPath: type: string description: Define the applicable API end point. endpointMethod: type: string description: Https Method for the endpoint. paymentType: $ref: '#/components/schemas/PaymentTypeOfConstraints' request: $ref: '#/components/schemas/RequestConstraints' ResponseMeta: type: object properties: tracingId: type: string ApiError: type: object description: Provides details of the error that has occurred. properties: code: type: integer description: __Mandatory__. Numeric `HTTP` status code associated with the error. format: int32 institutionError: $ref: '#/components/schemas/InstitutionError' message: type: string description: __Mandatory__. Description of the exact error that has been experienced. source: type: string status: type: string description: __Mandatory__. Textual description of the `HTTP` error status type. tracingId: type: string description: __Optional__. A unique identifier assigned by Yapily for the request that can be used for support purposes. RawResponse: deprecated: true type: object description: '[DEPRECATED] Interaction (raw request and response) that occurred with the `Institution` in order to fulfil a request.' properties: request: $ref: '#/components/schemas/RawRequest' duration: type: string format: iso8601 headers: type: object additionalProperties: type: string resultCode: type: integer format: int32 result: type: object ApiListResponseOfDataConstraints: type: object properties: meta: $ref: '#/components/schemas/ResponseMeta' data: type: array items: $ref: '#/components/schemas/DataConstraintsResponse' example: 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. \n\nSee [Using a callback with an OTT (Optional)](/open-banking-flow/handling-redirects/callback-url) 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`. \n\nSee [Using a callback (Optional)](/open-banking-flow/handling-redirects/callback-url) 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](/data/financial-data-resources/data-restrictions#cbi-globe-gateway). 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. **Note**: If this supported by the bank, specifying this is property is opting out of having a long-lived consent that can be perpetually re-authorised by the user. This will add an `expiresAt` field on the `Consent` object which will render it unusable after this date. **Note**: This is not supported by every `Institution`. In such case, the request will not fail but the property will be ignored and the created `Consent` will not have an expiry date.' 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.\n\n See [Account Identification Combinations](/payments/payment-resources/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.\n\n See [Account Identification Combinations](/payments/payment-resources/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).\n\n 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.\n\n See [Account Identification Combinations](/payments/payment-resources/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.\n\n See [Account Identification Combinations](/payments/payment-resources/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). \n\nThis 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.\n\n See [Account Identification Combinations](/payments/payment-resources/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.\n\n See [Account Identification Combinations](/payments/payment-resources/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). \n\nThis 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 SchemaType: type: string enum: - array - boolean - integer - number - object - string InstitutionError: type: object description: Raw error details provided by the `Institution`, when it was the error source. properties: errorMessage: type: string description: Textual description of the `Institution` error. httpStatusCode: type: integer description: Numeric HTTP status code associated with the `Institution` error. format: int32 ApiResponseError: type: object properties: error: $ref: '#/components/schemas/ApiError' raw: deprecated: true type: array items: $ref: '#/components/schemas/RawResponse' description: 'Used to return errors from the bank from each request - `400` - Returned by any `POST` endpoint when the body does not conform to the contract - `401` - Returned by any endpoint when an invalid `authToken` is used for authentication - `403` - Returned by any [Financial Data](/api-reference#financial-data) and any [Payments](/api-reference#payments) endpoint when the `Consent` is no longer authorised to access financial data or to make a payment - `404` - Returned by any endpoint where there are path parameters and the path parameters supplied are unable to find the desired resource - `409` - Returned by any `POST` endpoint when creating a resource that conflicts with any other existing resource e.g. [Create User](/api-reference/addUser) - `424` - Returned by any [Financial Data](/api-reference#financial-data) and any [Payments](/api-reference#payments) endpoint when the feature to be accessed is not supported by the `Institution`. - `500` - Returned by any endpoint when Yapily is down. If you encounter any false positives, please [notify us](mailto:support@yapily.com)' example: error: tracingId: 74b13ce8ed51419f92c5d609e04532de code: 424 institutionError: errorMessage: '{"Code":"500 Internal Server Error","Id":"5ff8d331-4282-41e0-b5ef-1ac9ac39f009","Message":"Technical Error. Please try again later","Errors":[{"ErrorCode":"UK.OBIE.UnexpectedError","Message":"There was a problem processing your request. Please try again later"}]}' httpStatusCode: 500 source: INSTITUTION status: FAILED_DEPENDENCY Schema: type: object properties: title: type: string maximum: type: number exclusiveMaximum: type: number minimum: type: number exclusiveMinimum: type: number pattern: type: string format: regex maxItems: type: integer minimum: 0 minItems: type: integer minimum: 0 uniqueItems: type: boolean required: type: array items: type: string minItems: 1 uniqueItems: true enum: type: array items: {} minItems: 1 uniqueItems: false type: $ref: '#/components/schemas/SchemaType' contains: $ref: '#/components/schemas/Schema' not: $ref: '#/components/schemas/Schema' if: $ref: '#/components/schemas/Schema' then: $ref: '#/components/schemas/Schema' else: $ref: '#/components/schemas/Schema' allOf: type: array items: $ref: '#/components/schemas/Schema' oneOf: type: array items: $ref: '#/components/schemas/Schema' anyOf: type: array items: $ref: '#/components/schemas/Schema' items: $ref: '#/components/schemas/Schema' properties: type: object additionalProperties: $ref: '#/components/schemas/Schema' description: type: string format: type: string default: {} example: {} dependentRequired: description: dependentRequired keyword is used to satisfy dependency between fields type: object additionalProperties: type: array items: type: string uniqueItems: true default: [] $defs: type: object additionalProperties: $ref: '#/components/schemas/Schema' $ref: type: string x-yapily-annotations: type: object properties: lastUpdatedAt: type: string format: date-time x-yapily-validations: type: object properties: maxDurationFromNow: type: string format: duration additionalProperties: false PaymentTypeOfConstraints: title: Payment Type type: string description: Payment type associated with constraints. enum: - DOMESTIC_PAYMENT - DOMESTIC_INSTANT_PAYMENT - DOMESTIC_VARIABLE_RECURRING_PAYMENT - DOMESTIC_SCHEDULED_PAYMENT - DOMESTIC_PERIODIC_PAYMENT - INTERNATIONAL_PAYMENT - INTERNATIONAL_SCHEDULED_PAYMENT - INTERNATIONAL_PERIODIC_PAYMENT DataConstraintsResponse: required: - institutionId - institutionCountry - request type: object properties: institutionId: type: string description: The id to represent the `Institution`. example: modelo-sandbox institutionCountryCode: type: string description: 2 letter ISO Country code of the `Institution`. example: GB endpointPath: type: string description: Define the applicable API end point. endpointMethod: type: string description: Https Method for the endpoint. request: $ref: '#/components/schemas/RequestConstraints' Pagination: type: object properties: totalCount: type: integer format: int64 self: $ref: '#/components/schemas/FilterAndSort' next: $ref: '#/components/schemas/Next' ApiListResponseOfPaymentConstraints: type: object properties: meta: $ref: '#/components/schemas/ResponseListMeta' data: type: array items: $ref: '#/components/schemas/PaymentConstraintsResponse' example: 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.\n\n See [Account Identification Combinations](/payments/payment-resources/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.\n\n See [Account Identification Combinations](/payments/payment-resources/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. \n\nAn `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. \n\nAn `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 Next: type: object properties: from: type: string format: date-time before: type: string format: date-time limit: type: integer format: int32 cursor: type: string FilterAndSort: type: object properties: from: type: string description: __Optional__. The earliest date and time of resources / records that should be returned. format: date-time before: type: string description: __Optional__. The latest date and time of resources / records that should be returned. format: date-time limit: type: integer description: __Optional__. The maximum number of resources / records that should be returned. format: int32 sort: $ref: '#/components/schemas/SortEnum' offset: type: integer format: int32 cursor: type: string RequestConstraints: required: - body type: object description: Object defining the constraints rules applicable for a given requests. properties: headers: $ref: '#/components/schemas/Schema' body: $ref: '#/components/schemas/Schema' ResponseListMeta: type: object properties: tracingId: type: string count: type: integer format: int32 pagination: $ref: '#/components/schemas/Pagination' RawRequest: type: object properties: method: type: string url: type: string requestInstant: type: string format: date-time headers: type: object additionalProperties: type: string body: type: object bodyParameters: type: object additionalProperties: type: string startTime: type: string format: date-time startedAt: type: string format: date-time deprecated: true SortEnum: type: string description: The attribute on which resources / records returned should be sorted. Valid options for the sort parameter. enum: - date - -date securitySchemes: basicAuth: description: Use HTTP Basic Authentication with your Application ID as username and Application Secret as password. Manage credentials in the [Yapily Console](https://console.yapily.com/). See [Authentication](/api-reference/authentication) for details. scheme: basic type: http