Skip to main content
Payment Constraints is currently available in Private Beta. See Glossary for more information.

​
Introduction

The constraints API can help improve your success rates for payment initiation by allowing you to fulfil institution specific requirements and rules. Examples of institution specific requirements, or constraints, include:
  • User credentials (such as their user id and password for the bank’s digital channels) must be provided
  • The users payment account must be indicated through its IBAN
  • The maximum length of a payment reference must be 18 characters
Where requirements, such as those above, are not met then the payment could be rejected by the institution. Ways you can use the constraint information include:
  • As a knowledge base to reference during the build of your application
  • To dynamically control behaviour in your application - such as front end validation and data transformation
  • To validate that your intended initiation request to the Yapily Payments API meets all of the institution’s requirements

​
How it works

The constraints API works as follows:
  1. You make a request to the payment constraints endpoint specifying the type of payment that you wish to initiate and the institution you wish to initiate it with
  2. The response will include a JSON schema that defines all of the data requirements for this institution
This schema is based on the schema for the related payment initiation endpoint (e.g. Create Payment Authorisation), as defined in the Open API Specification and API Reference, but is tailored to take into account the specific requirements / validation for the institution Expressing the data requirements through JSON schema in this way means that:
  • The data requirements are expressed in an identical manner as the Yapily Payments API and can be used to directly construct and validate the request messages to it
  • It’s a standardised solution with many readily-available tools / libraries to help you process the information provided and perform validation against it

​
Current Scope

The payment constraints API currently supports Single Domestic Payments (including Instant) for German institutions. This will later be expanded to include other countries and payment types. The same mechanism will also be used in future versions to share Yapily Data related constraints.

​
Tutorial

​
1. Request Constraint Information

Call Get Constraints to request constraint information for the institution of your user and the operation that you wish to perform. This is done through the below query parameters:
Query ParameterDescriptionMandatory?Example
institutionIdsThe unique id(s) of the Institution(s) that you wish to retrieve the Payment Constraints for. Multiple institutionIds need to be separated by ,Yescommerzbank
institutionCountryCodeThe country code in which the institution(s) operates and that you wish to gain the constraints forYesDE
paymentTypeThe payment type that you wish to gain the constraints forYesDOMESTIC_PAYMENT
endpointPathThe endpoint path on the Yapily API to which the constraints applyNo/payment-auth-requests
endpointMethodThe endpoint method on the Yapily API to which the constraints applyNoPOST

​
2. Receive Constraint Information

The response provides an array of results with one item for every institutionId you have requested. Each array item includes:
  • The key identifiers of the payment scenario (playing back the parameters you have passed in) - e.g. institutionId and paymentType
  • A request block that includes a detailed json schema for the request headers and another schema for the request body. This JSON schema describes what a request to the endpointPath needs to conform to in order to be successful
The response example below has been shortened and is to indicate the structure of the response only.
curl  -L  -X  GET  'https://api.yapily.com//institutions/constraints/payments?institutionIds=commerzbank&country=DE&paymentType=DOMESTIC_PAYMENT&endpointPath=/payment-auth-requests&endpointMethod=POST'  \
-u  'APPLICATION_KEY:APPLICATION_SECRET'

​
Constraint Types

​
Possible Constraints

JSON schema allows for a large number of keywords to describe the desired structure and validation of data. To provide more predictability & reduce the range of constraints your application will need to handle, the information provided by the constraints API will always:
  • Conform to the Yapily API schema (described in the Open API Specification and API reference) for the same endpoint. E.g. The properties included and their types will always align
  • Have tighter validation than the Yapily API schema (and never more relaxed). E.g. An optional property may become mandatory, but a mandatory property will not become optional
  • Contain only the below validation keywords:
    • required
    • type
    • format
    • minimum
    • exclusiveMinimum
    • maximum
    • exclusiveMaximum
    • pattern
    • enum
In addition, the allOf keyword may be used to reference the complex conditions that apply.

​
Complex Conditions

Some data requirements are more complex and conditional in nature meaning that they cannot be communicated using the more simple keywords described above. Where this is the case a condition is used to describe the validation rule. Each of these conditions has a unique name, which is also used as the name of the sub-schema that defines it. This sub-schema definition ($defs) is referenced ($ref) from the property to which it applies This unique name:
  • Aids human identification of these complex conditions
  • Offers a predictable, limited and documented set of conditions that may be provided (and that you may wish for your application to handle)

​
Example

The below extract includes two named conditions:
  1. An IBAN_REQUIRED condition that applies to the accountIdentifications array
  2. An IBAN_FORMAT condition that applies to each item within the accountIdentifications array
"accountIdentifications": {
    "type": "array",
    "allOf": [
        {
            "$ref": "#/$defs/IBAN_REQUIRED"
        }
    ],
    "items": {
        "required": [
            "identification",
            "type"
        ],
        "type": "object",
        "allOf": [
            {
                "$ref": "#/$defs/IBAN_FORMAT"
            }
        ],
Within the response these conditions are defined as sub-schema: 
"$defs": {
    "IBAN_FORMAT": {
        "if": {
            "required": [
                "type"
            ],
            "properties": {
                "type": {
                    "pattern": "^IBAN$",
                    "type": "string"
                }
            }
        },
        "title": "IBAN Format Condition",
        "then": {
            "properties": {
                "identification": {
                    "pattern": "^DE[a-zA-Z0-9]{2}([0-9]{4}){4}([0-9]{2})$"
                }
            }
        },
        "description": "__Condition__, IBAN should be in the format provided"
    },
    "IBAN_REQUIRED": {
        "title": "IBAN Required Condition",
        "contains": {
            "required": [
                "identification",
                "type"
            ],
            "type": "object",
            "properties": {
                "type": {
                    "pattern": "^IBAN$",
                    "type": "string"
                }
            }
        },
        "description": "__Condition__, IBAN is required"
    }
},

​
Complex Conditions Catalogue

Describes the required format of a provided Account Number.That is, the required pattern of the identification value for an item in the accountIdentifications array where type = ACCOUNT_NUMBERThis requirement will be associated with the payer or payee details
"ACCOUNT_NUMBER_FORMAT": {
    "description":"__Condition__, account number should follow the format given",
    "title": "Account Number Format Condition",
    "if": {
        "required":[
            "type"
        ],
        "properties": {
            "type": {
                "type": "string",
                "pattern": "^ACCOUNT_NUMBER$"
            }
        }
    },
    "then": {
        "properties": {
            "identification": {
                "pattern": "^[0-9]{8}$"
            }
        }
    }
}
Indicates that an Account Number must be provided in the request.That is, an item must be provided in the accountIdentifications array where type = ACCOUNT_NUMBERThis requirement will be associated with the payer or payee details
"ACCOUNT_NUMBER_REQUIRED": {
    "description":"__Condition__, Account number is required",
    "title": "Account Number Required Condition",
    "contains": {
        "type": "object",
        "required": [
            "type",
            "identification"
        ],
        "properties": {
            "type": {
                "type": "string",
                "pattern": "^ACCOUNT_NUMBER$"
            }
        }
    }
}
Describes the required format of a provided BBAN.That is, the required pattern of the identification value for an item in the accountIdentificiations array where type = BBANThis requirement will be associated with the payer or payee details
 "BBAN_FORMAT": {
    "description":"__Condition__, BBAN format should follow the format given",
    "title": "BBAN Format Condition",
    "if": {
        "required":[
            "type"
        ],
        "properties": {
            "type": {
                "type": "string",
                "pattern": "^BBAN$"
            }
        }
    },
    "then": {
        "properties": {
            "identification": {
                "pattern":"^d{18}$"
            }
        }
    }
}
Describes the required format of a provided IBAN.That is, the required pattern of the identification value for an item in the accountIdentificiations array where type = IBANThis requirement will be associated with the payer or payee details
 "IBAN_FORMAT": {
    "description":"__Condition__, IBAN format should follow the format given",
    "title": "IBAN Format Condition",
    "if": {
        "required":[
            "type"
        ],
        "properties": {
            "type": {
                "type": "string",
                "pattern": "^IBAN$"
            }
        }
    },
    "then": {
        "properties": {
            "identification": {
                "pattern": "^DE[a-zA-Z0-9]{2}([0-9]{4}){4}([0-9]{2})$"
            }
        }
    }
}
Indicates that at least one of an IBAN or a BBAN must be provided in the request.That is, an item must be provided in the accountIdentifications array where type = IBAN or type = BBANThis requirement will be associated with the payer or payee details
"IBAN_OR_BBAN_REQUIRED": {
    "description":"__Condition__, IBAN or BBAN is required",
    "title": "IBAN or BBAN Required Condition",
    "contains": {
        "type": "object",
        "required":[
            "type",
            "identification"
        ],
        "properties": {
            "type": {
                "type": "string",
                "pattern":"^(IBAN|BBAN)$"
            }
        }
    }
}
Indicates that an IBAN must be provided in the request.That is, an item must be provided in the accountIdentifications array where type = IBANThis requirement will be associated with the payer or payee details
"IBAN_REQUIRED": {
    "description":"__Condition__, IBAN is required",
    "title": "IBAN Required Condition",
    "contains": {
        "type": "object",
        "required": [
            "type",
            "identification"
        ],
        "properties": {
            "type": {
                "type": "string",
                "pattern": "^IBAN$"
            }
        }
    }
}
Describes the required format of a provided Sort Code.That is, the required pattern of the identification value for an item in the accountIdentificiations array where type = SORT_CODEThis requirement will be associated with the payer or payee details
"SORT_CODE_FORMAT": {
    "description": "__Condition__, sort code format should follow the format given",
    "title": "Sort Code Condition",
    "if": {
        "required":[
            "type"
        ],
        "properties": {
            "type": {
                "type": "string",
                "pattern": "^SORT_CODE$"
            }
        }
    },
    "then": {
        "properties": {
            "identification": {
                "pattern": "^[0-9]{6}$"
            }
        }
    }
}
Indicates that an Sort Code must be provided in the request.That is, an item must be provided in the accountIdentifications array where type = SORT_CODEThis requirement will be associated with the payer or payee details
"SORT_CODE_REQUIRED": {
    "title": "Sort Code Required Condition",
    "contains": {
        "required": [
            "identification",
            "type"
        ],
        "type": "object",
        "properties": {
            "type": {
                "pattern": "^SORT_CODE$",
                "type": "string"
            }
        }
    },
    "description": "__Condition__, IBAN is required"
}