# Payment Request Definition and Validation source: https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/requesting-payments/index.md This section describes how you can define a payment and how the validation of the request works. It also describes how you can get the most out of each individual bank (refered to as "providers"). The APIs that the providers expose vary in functionality and available reference identifiers. The APIs are designed to make it as easy as possible to initiate payments despite these differences. These steps are detailed below: 1. How to define a payment request 2. How our validation works 3. How to use specific provider information to gain full control of the request ## Request properties {#request-properties} The example below is what a payment request looks like in our API. The first part of the payment request (up until `request`) defines how you want to interact with us. The last part, the `request`, defines the payment itself. ```json { // Request properties defining interaction and meta information for the payment. "providerId": "FI_Nordea", "userHash": "hash-identifying-user", "redirectUrl": "string", ... // Defining the specification of the payment. "request": { "sourceAccountId": "d218321fert2342", "destination": { "iban": { "ibanNumber": "DE75512108001245126199" } ... }, "paymentMethod": "Domestic" } } ``` The `request` object defines the payment. The table below describes the properties that can be set to define the payment. | **Name** | **Required** | **Description** | |-------------------|--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `paymentMethod` | No | Defines the payment scheme. Choose either domestic, giro payments or SEPA. | | `destination` | Yes | Defines the destination by filling out either BBAN or IBAN and the name of the recipient. | | `amount` | Yes | The monetary value for the payment. | | `execution` | No | How the payment is executed in regards to time. See [Execution](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/requesting-payments/index.md#execution) for more information. | | `message` | No | This is the message that is shown to the receiver of the payment. | | `transactionText` | No | Transaction text, shown on the transaction on the source account. For OP Financial Group only: This field should contain the name of the final beneficiary, aka the ultimate creditor. The final beneficiary information is required for OP payment providers if funds are not directly transferred to the final beneficiary account, but rather processed through an intermediate account. | | `identifiers` | No | We support several identifiers. The identifiers available vary from country to country. See [Identifers](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/requesting-payments/index.md#Identifiers) for detailed information. | #### Payment method {#payment-method} Below you can see the payment methods we currently support. This is not a required property. The default value is `Domestic`. | **Name** | **Country** | **Description** | |-----------------|----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------| | `Domestic` | All | For domestic payments (e.g. a payment between an account in a specific country to another provider account in the same country using local currency.) | | `InpaymentForm` | Denmark Sweden | Giro or FI payments. Bank giro and Post giro payments. | | `SEPA` | EU | For payments to a [eurozone](https://en.wikipedia.org/wiki/Eurozone) country. | ##### Domestic {#domestic} The `Domestic` payment method allows using the national clearing schemes as provided by the PSD2 APIs made available from different providers. This means that national identifiers are available for each market. * **Denmark** - Special identifier only available with Giro cards and FI Cards. These are available with payment method `InpaymentForm`. * **Sweden** - Special identifier only available with Bank Giro and Post Giro. These are available with payment method `InpaymentForm`. * **Norway** - *KID* , also known as *kundeidentifikasjon*, is available as an identifier. * **Finland** - Finnish Reference is the national reference standard defined by [Finance Finland](https://www.finanssiala.fi/en/) and is available as identifier. ##### Inpayment form {#inpayment-form} The `InpaymentForm` payment method allows you to use the proprietary invoice payment schemes in Denmark and Sweden. Denmark has two different schemes available: * Giro cards have three versions: 01, 04 and 15. See the differences in the Destination section below. * FI cards, the successor scheme of the Giro cards, also have three different versions available: 71, 73 and 75. See the differences in the Destination section below. Sweden also has two different schemes available: * Bank Giro * Post Giro ##### SEPA {#sepa} The `SEPA` payment method allows you to make payments to the entire [eurozone](https://en.wikipedia.org/wiki/Eurozone) region, if supported by a provider. See the [Provider functionality](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/requesting-payments/index.md#provider-functionality) section below to learn how to retrieve the payment methods a specific provider supports. This payment method reflects the standard version of SEPA, as defined by the SEPA rulebook, and does not allow for any country-specific identifiers. This means that: * Only IBAN is accepted in the destination property and only [eurozone](https://en.wikipedia.org/wiki/Eurozone) country codes are accepted in the IBAN. * Only Creditor Reference and EndToEndId are available as identifiers. * Message is available and corresponds to SEPA's remittance information unstructured. * Only euros (EUR) are accepted as currency. * Transaction text is not available. However, most providers use Message for both the sender and the receiver. Note: For OP Financial Group this field should contain the name of the final beneficiary, aka the ultimate creditor. The final beneficiary information is required for OP payment providers if funds are not directly transferred to the final beneficiary account, but rather processed through an intermediate account. ##### Example {#example} See example of usage below. ```json { ... "request": { ... "paymentMethod": "SEPA" ... } } ``` #### Destination {#destination} You can define the payment destination with different parameters. You can only set exactly one of `bban`, `iban`, `ownAccount` or `inpaymentForm`. | **Name** | **Description** | |-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `bban` | Define destination by the [basic bank account number](https://www.iban.com/glossary). | | `iban` | Define destination by the [international bank account number](https://www.iban.com/glossary). | | `ownAccount` | Set when the destination account is one of the user's own accounts. Identified by an internal accounts ID. Refer to the Get accounts endpoint below this table. | | `inpaymentForm` | Destination for Giro payments. Required when the payment method is `InpaymentForm`. | | `name` | The name of the recipient. We recommend you always fill this property. | | `address` | The address of the recipient of the payment. | API Reference: `GET /v2/accounts` ##### Inpayment form {#inpayment-form-1} We offer all common proprietary invoice payments schemes available in Denmark and Sweden, such as Post Giro and Bank Giro, as well as Giro and FI payments in Denmark. You define the type of `InpaymentForm` in the property `request.destination.inpaymentForm.type`. You can choose between the types outlined below. Note that the validation of the specific `InpaymentForm` identifier `ocr` depends on the chosen type: | **Type** | **Schema** | **Country** | **Message** | **Ocr** | |----------|------------|-------------|---------------------------|----------------------------------------------------------| | SE_PGNR | Post Giro | Sweden | Required if `ocr` not set | Required if `message` not set | | SE_BGNR | Bank Giro | Sweden | Required if `ocr` not set | Required if `message` not set | | DK_G01 | Giro 01 | Denmark | Required | Not supported | | DK_G04 | Giro 04 | Denmark | Not supported | Required Mod 10 checksum validation Max length 16 digits | | DK_G15 | Giro 15 | Denmark | Not supported | Required Mod 10 checksum validation Max length 16 digits | | DK_FI71 | FI 71 | Denmark | Not supported | Required Mod 10 checksum validation Max length 15 digits | | DK_FI73 | FI 73 | Denmark | Required | Not supported | | DK_FI75 | FI 75 | Denmark | Required | Required Mod 10 checksum validation Max length 16 digits | ##### Example {#example-1} See example of usage below. ```json { ... "request": { "destination": { "iban": { "ibanNumber": "FI4511231212367871" } } } } ``` #### Amount {#amount} You can define the payment amount by the following properties: | **Name** | **Description** | |------------|-----------------------------------------------------------------------------------------------------------------------------| | `value` | The monetary value that should be paid. | | `currency` | 3 char [ISO 4217](https://docs.1010data.com/1010dataUsersGuideV10/DataTypesAndFormats/currencyUnitCodes.html) currency code | The value of the payment supported can vary from provider to provider. We expose, to the best of our ability, any limits a provider may have in our provider endpoint. API Reference: `GET /v1/providers` ##### Example {#example-2} See example of usage below. ```json { ... "request": { "amount": { "value": 199, "currency": "EUR" }, } } ``` #### Execution {#execution} We expose three different ways of executing a payment. Note that available execution options vary from provider to provider. The default value is `Normal`, which is also supported by all providers. Use our provider endpoint to see which execution types are available from a particular provider. API Reference: `GET /v1/providers` | **Name** | **Description** | |----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `Normal` | Payment will be initiated on the day's date, or the next banking day, and executed according to the provider's standard clearing schedule. | | `SpecificDate` | Payment will be scheduled to be executed on the day specified. If you choose a date not supported by the provider (for example, not a banking day), the request will fail. Note that future dated payment requests are in preview release, and are not fully supported at this time. | | `Instant` | Payment will be executed immediately and be available on the receiver account shortly afterwards (Note: this most often incurs a fee for the user/payer). | Note that it depends on the agreement between the Payer and the provider whether the provider charges a fee. We indicate whether the Payment Service User (PSU) may be charged a fee for the payment. We populate the information on a best-effort basis. ##### Example {#example-3} See example of usage below. ```json { ... "request": { "execution": { "type": "SpecificDate", "date": "2021-04-21" }, } } ``` #### Identifiers {#identifiers} There are different identifiers you can use to identify the payment for either the Payer or/and the payee. These identifiers are in addition to the `message`. However, for some providers, the `message` and `identifier` cannot be set at the same time. If you set both at the same time, the message is removed. The [Provider functionality](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/requesting-payments/index.md#provider-functionality) section below explains how you can see identifier support for each provider. | **Name** | **Country** | **Description** | |---------------------|-----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------| | `creditorReference` | All | Creditor reference in accordance with [ISO 11649](https://www.sis.se/api/document/preview/910915/) is meant for a creditor provided reference. | | `endToEndId` | All | EndToEnd ID in accordance with [ISO 20022](https://knowledge.xmldation.com/xml-iso-20022-standard) is meant for a debtor provided reference. | | `finnishReference` | Finland | National [reference](https://knowledge.xmldation.com/finnish-reference-number) and can only be used for IBANs starting with **FI** . | | `norwegianKID` | Norway | The [KID](https://no.wikipedia.org/wiki/KID-nummer) is a Norwegian customer identification number that is mandatory for invoices. | | `ocr` | Denmark, Sweden | Reference identifier for Giro payments in DK and SE. Can only be used with payment method `InpaymentForm`. Validation depends on chosen `InpaymentForm` type. | ##### Example {#example-4} See example of usage below. ```json { ... "request": { "identifiers": { "creditorReference": "RF18539007547034" }, } } ``` ## Validation {#validation} Our API uses a validation framework to make it easy to initiate payments despite the differences between providers. The goal of the validation is to make any payment request succeed that can succeed and fail any payment request that cannot be altered by us without changing an input of importance. Every request is validated in accordance with our API definition and the ability of a specific provider to ensure that a payment request fails upfront. Some providers may require a property in the payment request that is not required by our API. The validation is applying a set of rules for default values, to ensure that a request does not fail. You can always see the specific rules that each provider applies. This is described in the [Provider functionality](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/requesting-payments/index.md#provider-functionality) section below. The table below shows the rules we apply to a payment request if a provider has special validation requirements. | **Name** | **Provider specific validation failure** | **Default value if required by provider** | |--------------------------|------------------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------| | `execution` | Uses `Normal` | `Normal` | | `message` | Trims message if max length is exceeded | Payment ID | | `transactionText` | Trims message if max length is exceeded | `Domestic` - Payment ID `InpaymentForm` - " `destination.inpaymentForm.type.schema` `identifiers.ocr` `destination.inpaymentForm.creditorNumber`" | | `identifiers.endToEndId` | Fails | Payment ID | The transformed properties can be determined by calling the Get single payment or Refresh payment status endpoints. API Reference: `GET /v1/payments/{paymentId}` API Reference: `POST /v1/payments/{paymentId}/refresh-status` #### Management of identifiers {#management-of-identifiers} Available identifiers vary from provider to provider. There are two ways identifiers can be managed: 1. Set all identifiers and let the API manage which identifier is set. 2. Manage the usage of identifiers yourself by using the provider endpoint. If you set all identifiers, we choose the most appropriate identifier of those available. Hence, you do not need to manage the identifiers. The identifiers are chosen using the following order: 1. Local identifier if supported (for example, Finnish Reference). 2. Creditor reference if supported. The actual identifiers used can be seen by calling the Get single payment or Refresh payment status endpoints. API Reference: `GET /v1/payments/{paymentId}` API Reference: `POST /v1/payments/{paymentId}/refresh-status` #### Management of message and identifiers {#management-of-message-and-identifiers} Some providers do not support setting the `message` and one of the identifiers at the same time. This is exposed by our [Provider functionality](https://developer.mastercard.com/open-finance-europe/documentation/licensed/aiia-enterprise/payments/requesting-payments/index.md#provider-functionality). If you set both `message` and one of these identifiers, and the corresponding provider does not support both, the `identifier` is prioritized for the request. For `InpaymentForm` payments, if both `ocr` and `message` are set, but only one of them is supported, the non-supported properties will be discarded. ## Provider functionality {#provider-functionality} Available payment methods, identifiers, execution types and number of payments that can be authorized at the same time vary from provider to provider. If you want to have full control of the request, you can use our provider endpoint to see payment methods supported by the provider. For instance, you can call the Providers endpoint with FI_DanskeBank parameter as shown below: API Reference: `GET /v1/providers` ```shell curl -X GET \ https://api.nordicapigateway.com/v1/providers/FI_DanskeBank \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' ``` This will return a high-level view of the capabilities of the provider Danske Bank in Finland. ```json { "id": "FI_DanskeBank", "name": "Danske Bank", "countryCode": "FI", ... // Payment methods supported - The payment method is only supported if an execution type is available. "paymentMethods": { "domestic": { "executionTypes": [ "Normal", "SpecificDate" ] }, "international": null, "inpaymentForm": null, "sepa": { "executionTypes": [ "Normal", "SpecificDate" ] } }, "audiences": [ "Private" ], // Information about how payments can be authorized. "paymentAuthorization": { "paymentsAllowedPerAuthorization": 1 } } ``` The provider endpoint exposes for each provider a high level view of the providers ability: * `paymentMethods` - The supported payment methods by the provider. Payment methods are only supported if there is an execution type. For each payment method, we expose information that will make you understand each providers capability by: * `executionType` - Showing the supported execution types. * `properties` - Exposing all supported properties and their provider specific rules. * `rules` - Identifying advanced rules that may apply to multiple properties. You can retrieve the supported payment methods and information about the payment methods by calling `/v1/providers/{providerId}/payment-methods`. You can find all available providers and their IDs by using the providers endpoint. API Reference: `GET /v1/providers` Below you can see an example for Danske Bank in Finland which has the ID FI_DanskeBank. ```shell curl -X GET \ https://api.nordicapigateway.com/v1/providers/FI_DanskeBank/payment-methods \ -H 'Content-Type: application/json' \ -H 'X-Client-Id: ' \ -H 'X-Client-Secret: ' ``` This is what returns. ```json { "domestic": { "executionTypes": [ "Normal", "SpecificDate" ], "properties": { "destination.iban": { "required": true }, "amount.value": {}, "amount.currency": { "possibleValues": [ "EUR" ] }, "destination.name": { "required": true }, "identifiers.endToEndId": { "required": true, "maxLength": 35, "minLength": 1 }, "identifiers.finnishReference": { "rules": [ "r0" ] }, "identifiers.creditorReference": { "rules": [ "r0" ] }, "message": { "maxLength": 140, "rules": [ "r0" ] } }, "rules": { "r0": { "type": "AtMostOne", "properties": [ "identifiers.finnishReference", "identifiers.creditorReference", "message" ] } } } } ``` The example above shows that Danske Bank in Finland supports the payment method `domestic` with the execution types `Normal` and `SpecificDate`. All properties that are listed are supported by Danske Bank and you can see the rules that apply for each property. In this example, you can see that only `destination.iban` can be used as input for the destination and that three identifiers - `creditorReference`, `endToEndId` and `finnishReference` - are supported along with `message`. You can also see that only the currency EURO is allowed and that the name of the receiver - `destination.name` - is required. In addition, you can see that a rule `r0` is applied to the properties `message`, `creditorReference` and `finnishReference`. Rule `r0` describes that, at most, one of these properties can be set at the same time. #### Rules {#rules} There are several types of rules that can describe how a property can be used: | **Rule** | **Description** | |-------------|--------------------------------------------------------| | Required | The property is required by the provider. | | MaxLength | The maximum length. | | MinLength | The minimum length. | | MaxDecimals | The maximum number of decimal digits that are allowed. | | GreaterThan | The value needs to be greater than the given value. | | LessThan | The value needs to be less than the given value. | | InRange | The value needs to be within the given range. | A property can also have one or more complex rules attached to it. A complex rule is when there are two or more properties that are interdependent. | **Rule** | **Description** | |------------|----------------------------------------------------------------------------------------| | AtMostOne | Of the properties this rule applies to, only one property can be set at the same time. | | ExactlyOne | Of the properties this rule applies to, exactly one property should be set. |