Payment Constraints
The Payment Constraints feature is available as a Private Beta version. Please contact your Customer Success Manager if you would like to access it.
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:
-
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
- 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 Parameter | Description | Mandatory? | Example |
|---|---|---|---|
institutionIds |
The unique id(s) of the Institution(s) that you wish to retrieve the Payment Constraints for. Multiple institutionIds need to be separated by , |
Yes | commerzbank |
institutionCountryCode |
The country code in which the institution(s) operates and that you wish to gain the constraints for | Yes | DE |
paymentType |
The payment type that you wish to gain the constraints for | Yes | DOMESTIC_PAYMENT |
endpointPath |
The endpoint path on the Yapily API to which the constraints apply | No | /payment-auth-requests |
endpointMethod |
The endpoint method on the Yapily API to which the constraints apply | No | POST |
Example Request:
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'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.
institutionIdandpaymentType -
A
requestblock that includes a detailed json schema for the requestheadersand another schema for the requestbody. This JSON schema describes what a request to theendpointPathneeds to conform to in order to be successful
Example Response:
Please note that this has been shortened and is to indicate the structure of the response only.
{
"meta": {
"tracingId": "c1342598c42e4ecdab28b802bf9b88bb"
},
"data": [
{
"institutionId": "commerzbank",
"institutionCountryCode": "DE",
"endpointPath": "/payment-auth-requests",
"endpointMethod": "POST",
"paymentType": "DOMESTIC_PAYMENT",
"request": {
"headers": {
"required": [
"psu-ip-address"
],
"type": "object",
"properties": {
"psu-ip-address": {
"title": "User IP Address",
"type": "string",
"x-yapily-annotations": {
"lastUpdatedAt": "2023-04-14T13:48:27.844Z"
}
}
},
"x-yapily-annotations": {
"lastUpdatedAt": "2023-04-14T13:48:27.768Z"
}
},
"body": {
"required": [
"institutionId",
"paymentRequest"
],
"type": "object",
"properties": {
"redirect": {
"required": [
"url"
],
"type": "object",
"properties": {
"url": {
"type": "string",
"x-yapily-annotations": {
"lastUpdatedAt": "2023-04-14T13:48:27.688Z"
}
}
},
"x-yapily-annotations": {
"lastUpdatedAt": "2023-04-14T13:48:27.602Z"
}
},
"institutionId": {
"type": "string",
"x-yapily-annotations": {
"lastUpdatedAt": "2023-04-14T13:48:27.442Z"
}
},
.....
},
"paymentRequest": {
"required": [
"payee",
"reference",
"amount",
"paymentIdempotencyId",
"type",
"payer"
],
"type": "object",
"properties": {
"payee": {
"title": "Payee Details",
"required": [
"accountIdentifications",
"name"
],
"type": "object",
"properties": {
"accountIdentifications": {
"type": "array",
"allOf": [
{
"$ref": "#/$defs/IBAN_REQUIRED"
}
],
"items": {
"required": [
"identification",
"type"
],
"type": "object",
"allOf": [
{
"$ref": "#/$defs/IBAN_FORMAT"
}
],
"properties": {
"identification": {
"title": "Account Identification",
"type": "string",
"x-yapily-annotations": {
"lastUpdatedAt": "2023-07-14T10:32:13.495Z"
}
},
"type": {
"enum": [
"IBAN",
"BBAN",
"PAN",
"MASKED_PAN",
"MSISDN"
],
"title": "Account Identification Type",
"type": "string",
"x-yapily-annotations": {
"lastUpdatedAt": "2023-07-14T10:32:13.336Z"
}
}
}
},
"x-yapily-annotations": {
"lastUpdatedAt": "2023-04-14T13:51:21.164Z"
}
},
"address": {
......
},
......
},
"readRefundAccount": {
......
},
......
},
"$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 needs to be in the format provided"
},
......
}
}
}
]
}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:
-
An
IBAN_REQUIREDcondition that applies to theaccountIdentificationsarray -
An
IBAN_FORMATcondition that applies to each item within theaccountIdentificationsarray
"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
| Name | Description | Example |
|---|---|---|
| ACCOUNT_NUMBER_FORMAT | 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_NUMBER This requirement will be associated with the payer or payee details |
|
| ACCOUNT_NUMBER_REQUIRED | 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_NUMBER This requirement will be associated with the payer or payee details |
|
| BBAN_FORMAT | 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 = BBAN This requirement will be associated with the payer or payee details |
|
| IBAN_FORMAT | 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 = IBAN This requirement will be associated with the payer or payee details |
|
| IBAN_OR_BBAN_REQUIRED | 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 = BBAN This requirement will be associated with the payer or payee details |
|
| IBAN_REQUIRED | Indicates that an IBAN must be provided in the request. That is, an item must be provided in the accountIdentifications array where type = IBAN This requirement will be associated with the payer or payee details |
|
| SORT_CODE_FORMAT | 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_CODE This requirement will be associated with the payer or payee details |
|
| SORT_CODE_REQUIRED | 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_CODE This requirement will be associated with the payer or payee details |
|