swagger: '2.0' info: title: Payment Initiation API Specification description: >- Swagger for Payment Initiation API Specification. This is heavily derived from the Open Banking UK API - see www.openbanking.org.uk for details. termsOfService: 'https://www.apicentre.paymentsnz.co.nz/contact-us/' contact: name: Payments NZ API Centre email: apicentre@paymentsnz.co.nz license: name: Licence url: 'https://www.apicentre.paymentsnz.co.nz/join/' version: v2.0.0 basePath: /open-banking-nz/v2.0 schemes: - https consumes: - application/json; charset=utf-8 produces: - application/json; charset=utf-8 paths: '/enduring-payment-consents': post: tags: - Enduring Payment Consents operationId: CreateEnduringPaymentConsent summary: Create a new enduring-payment-consent description: >- The enduring-payment-consents resource represents a long lived payment-order consent that has been agreed between the Customer and the Third Party, and contains fields which describe the parameters for payment-order(s) that may be initiated by a Third Party on behalf of a Customer. parameters: - $ref: '#/parameters/AuthorizationParam' - $ref: '#/parameters/x-idempotency-key-Param' - $ref: '#/parameters/x-fapi-auth-date-Param' - $ref: '#/parameters/x-fapi-customer-ip-address-Param' - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/x-merchant-ip-address-Param' - $ref: '#/parameters/x-customer-user-agent-Param' - name: body in: body description: Enduring Payment Consent Body required: true schema: title: Enduring Payment Consent type: object properties: Data: $ref: '#/definitions/EnduringPaymentConsent' Risk: $ref: '#/definitions/Risk' required: - Data - Risk additionalProperties: false responses: '201': description: Created schema: type: object properties: Data: $ref: '#/definitions/EnduringPaymentConsentResponse' Risk: $ref: '#/definitions/Risk' Links: $ref: '#/definitions/Links' Meta: $ref: '#/definitions/Meta' required: - Data - Risk - Links - Meta additionalProperties: false headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. '400': $ref: '#/responses/400ErrorResponse' '401': $ref: '#/responses/401ErrorResponse' '403': $ref: '#/responses/403ErrorResponse' '405': $ref: '#/responses/405ErrorResponse' '406': $ref: '#/responses/406ErrorResponse' '415': $ref: '#/responses/406ErrorResponse' '429': $ref: '#/responses/429ErrorResponse' '500': $ref: '#/responses/500ErrorResponse' '501': $ref: '#/responses/501ErrorResponse' '503': $ref: '#/responses/503ErrorResponse' security: - ThirdPartyOAuth2Security: - payments '/enduring-payment-consents/{ConsentId}': get: tags: - Enduring Payment Consents operationId: GetEnduringPaymentConsent summary: Retrieve an enduring-payment-consent description: >- Retrieve an enduring-payment-consent and check its status. parameters: - $ref: '#/parameters/ConsentIdParam' - $ref: '#/parameters/AuthorizationParam' - $ref: '#/parameters/x-fapi-auth-date-Param' - $ref: '#/parameters/x-fapi-customer-ip-address-Param' - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/x-merchant-ip-address-Param' - $ref: '#/parameters/x-customer-user-agent-Param' responses: '200': description: OK schema: type: object properties: Data: $ref: '#/definitions/EnduringPaymentConsentResponse' Risk: $ref: '#/definitions/Risk' Links: $ref: '#/definitions/Links' Meta: $ref: '#/definitions/Meta' required: - Data - Risk - Links - Meta additionalProperties: false headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. '400': $ref: '#/responses/400ErrorResponse' '401': $ref: '#/responses/401ErrorResponse' '403': $ref: '#/responses/403ErrorResponse' '405': $ref: '#/responses/405ErrorResponse' '406': $ref: '#/responses/406ErrorResponse' '429': $ref: '#/responses/429ErrorResponse' '500': $ref: '#/responses/500ErrorResponse' '501': $ref: '#/responses/501ErrorResponse' '503': $ref: '#/responses/503ErrorResponse' security: - ThirdPartyOAuth2Security: - payments delete: tags: - Enduring Payment Consents operationId: DeleteEnduringPaymentConsent summary: Delete an enduring-payment-consent description: >- If the Customer revokes the enduring-payment-consent with the Third Party - the Third Party must delete the enduring-payment-consent. parameters: - $ref: '#/parameters/ConsentIdParam' - $ref: '#/parameters/AuthorizationParam' - $ref: '#/parameters/x-fapi-auth-date-Param' - $ref: '#/parameters/x-fapi-customer-ip-address-Param' - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/x-merchant-ip-address-Param' - $ref: '#/parameters/x-customer-user-agent-Param' responses: '204': description: No Content headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. '400': $ref: '#/responses/400ErrorResponse' '401': $ref: '#/responses/401ErrorResponse' '403': $ref: '#/responses/403ErrorResponse' '405': $ref: '#/responses/405ErrorResponse' '406': $ref: '#/responses/406ErrorResponse' '429': $ref: '#/responses/429ErrorResponse' '500': $ref: '#/responses/500ErrorResponse' '501': $ref: '#/responses/501ErrorResponse' '503': $ref: '#/responses/503ErrorResponse' security: - ThirdPartyOAuth2Security: - payments '/domestic-payment-consents': post: tags: - Domestic Payment Consents operationId: CreateDomesticPaymentConsent summary: Create a new domestic-payment-consent description: >- The domestic-payment-consents resource represents a short lived payment-order consent that has been agreed between the Customer and the Third Party, and contains fields which describe the parameters for a single domestic-payment that may be initiated by a Third Party on behalf of a Customer. parameters: - $ref: '#/parameters/AuthorizationParam' - $ref: '#/parameters/x-idempotency-key-Param' - $ref: '#/parameters/x-fapi-auth-date-Param' - $ref: '#/parameters/x-fapi-customer-ip-address-Param' - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/x-merchant-ip-address-Param' - $ref: '#/parameters/x-customer-user-agent-Param' - name: body in: body description: Domestic Payment Consent Body required: true schema: title: Domestic Payment Consent type: object properties: Data: $ref: '#/definitions/DomesticPaymentConsent' Risk: $ref: '#/definitions/Risk' required: - Data - Risk additionalProperties: false responses: '201': description: Created schema: type: object properties: Data: $ref: '#/definitions/DomesticPaymentConsentResponse' Risk: $ref: '#/definitions/Risk' Links: $ref: '#/definitions/Links' Meta: $ref: '#/definitions/Meta' required: - Data - Risk - Links - Meta additionalProperties: false headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. '400': $ref: '#/responses/400ErrorResponse' '401': $ref: '#/responses/401ErrorResponse' '403': $ref: '#/responses/403ErrorResponse' '405': $ref: '#/responses/405ErrorResponse' '406': $ref: '#/responses/406ErrorResponse' '415': $ref: '#/responses/415ErrorResponse' '429': $ref: '#/responses/429ErrorResponse' '500': $ref: '#/responses/500ErrorResponse' '501': $ref: '#/responses/501ErrorResponse' '503': $ref: '#/responses/503ErrorResponse' security: - ThirdPartyOAuth2Security: - payments '/domestic-payment-consents/{ConsentId}': get: tags: - Domestic Payment Consents operationId: GetDomesticPaymentConsent summary: Retrieve an domestic-payment-consent description: Retrieve an domestic-payment-consent and check its status. parameters: - $ref: '#/parameters/ConsentIdParam' - $ref: '#/parameters/AuthorizationParam' - $ref: '#/parameters/x-fapi-auth-date-Param' - $ref: '#/parameters/x-fapi-customer-ip-address-Param' - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/x-merchant-ip-address-Param' - $ref: '#/parameters/x-customer-user-agent-Param' responses: '200': description: OK schema: type: object properties: Data: $ref: '#/definitions/DomesticPaymentConsentResponse' Risk: $ref: '#/definitions/Risk' Links: $ref: '#/definitions/Links' Meta: $ref: '#/definitions/Meta' required: - Data - Risk - Links - Meta additionalProperties: false headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. '400': $ref: '#/responses/400ErrorResponse' '401': $ref: '#/responses/401ErrorResponse' '403': $ref: '#/responses/403ErrorResponse' '405': $ref: '#/responses/405ErrorResponse' '406': $ref: '#/responses/406ErrorResponse' '429': $ref: '#/responses/429ErrorResponse' '500': $ref: '#/responses/500ErrorResponse' '501': $ref: '#/responses/501ErrorResponse' '503': $ref: '#/responses/503ErrorResponse' security: - ThirdPartyOAuth2Security: - payments '/domestic-payments': post: tags: - Domestic Payments operationId: CreateDomesticPayment summary: Create a new domestic-payment description: >- The domestic-payments resource represents a single, domestic, electronic credit payment-order made in NZD that has been initiated by a Third Party on behalf of a Customer. A domestic-payment must be initiated using a payment-order consent which has been previously authorised by a Customer with an API Provider. This payment-order consent may either be a short-lived (domestic-payment-consent) or long-lived (enduring-payment-consent) payment order consent. parameters: - $ref: '#/parameters/AuthorizationParam' - $ref: '#/parameters/x-idempotency-key-Param' - $ref: '#/parameters/x-fapi-auth-date-Param' - $ref: '#/parameters/x-fapi-customer-ip-address-Param' - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/x-merchant-ip-address-Param' - $ref: '#/parameters/x-customer-user-agent-Param' - name: body in: body description: Domestic Payment Body required: true schema: title: Domestic Payment type: object properties: Data: $ref: '#/definitions/DomesticPayment' Risk: $ref: '#/definitions/Risk' required: - Data - Risk additionalProperties: false responses: '201': description: Created schema: type: object properties: Data: $ref: '#/definitions/DomesticPaymentResponse' Risk: $ref: '#/definitions/Risk' Links: $ref: '#/definitions/Links' Meta: $ref: '#/definitions/Meta' required: - Data - Risk - Links - Meta additionalProperties: false headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. '400': $ref: '#/responses/400ErrorResponse' '401': $ref: '#/responses/401ErrorResponse' '403': $ref: '#/responses/403ErrorResponse' '405': $ref: '#/responses/405ErrorResponse' '406': $ref: '#/responses/406ErrorResponse' '415': $ref: '#/responses/415ErrorResponse' '429': $ref: '#/responses/429ErrorResponse' '500': $ref: '#/responses/500ErrorResponse' '501': $ref: '#/responses/501ErrorResponse' '503': $ref: '#/responses/503ErrorResponse' security: - CustomerOAuth2Security: - payments '/domestic-payments/{DomesticPaymentId}': get: tags: - Domestic Payments operationId: GetDomesticPayment summary: Retrieve an domestic-payment description: Retrieve an domestic-payment and check its status. parameters: - $ref: '#/parameters/DomesticPaymentIdParam' - $ref: '#/parameters/AuthorizationParam' - $ref: '#/parameters/x-fapi-auth-date-Param' - $ref: '#/parameters/x-fapi-customer-ip-address-Param' - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/x-merchant-ip-address-Param' - $ref: '#/parameters/x-customer-user-agent-Param' responses: '200': description: OK schema: type: object properties: Data: $ref: '#/definitions/DomesticPaymentResponse' Risk: $ref: '#/definitions/Risk' Links: $ref: '#/definitions/Links' Meta: $ref: '#/definitions/Meta' required: - Data - Risk - Links - Meta additionalProperties: false headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. '400': $ref: '#/responses/400ErrorResponse' '401': $ref: '#/responses/401ErrorResponse' '403': $ref: '#/responses/403ErrorResponse' '405': $ref: '#/responses/405ErrorResponse' '406': $ref: '#/responses/406ErrorResponse' '429': $ref: '#/responses/429ErrorResponse' '500': $ref: '#/responses/500ErrorResponse' '501': $ref: '#/responses/501ErrorResponse' '503': $ref: '#/responses/503ErrorResponse' security: - ThirdPartyOAuth2Security: - payments '/domestic-payments/{DomesticPaymentId}/debtor-account': get: tags: - Domestic Payments operationId: GetDomesticPaymentDebtorAccount summary: Get the debtor account associated with the domestic payment description: Get the debtor account associated with the domestic payment parameters: - $ref: '#/parameters/DomesticPaymentIdParam' - $ref: '#/parameters/AuthorizationParam' - $ref: '#/parameters/x-fapi-auth-date-Param' - $ref: '#/parameters/x-fapi-customer-ip-address-Param' - $ref: '#/parameters/x-fapi-interaction-id-Param' - $ref: '#/parameters/x-merchant-ip-address-Param' - $ref: '#/parameters/x-customer-user-agent-Param' responses: '200': description: OK schema: type: object properties: Data: $ref: '#/definitions/DomesticPaymentDebtorAccountResponse' Links: $ref: '#/definitions/Links' Meta: $ref: '#/definitions/Meta' required: - Data - Links - Meta additionalProperties: false headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. '400': $ref: '#/responses/400ErrorResponse' '401': $ref: '#/responses/401ErrorResponse' '403': $ref: '#/responses/403ErrorResponse' '405': $ref: '#/responses/405ErrorResponse' '406': $ref: '#/responses/406ErrorResponse' '429': $ref: '#/responses/429ErrorResponse' '500': $ref: '#/responses/500ErrorResponse' '501': $ref: '#/responses/501ErrorResponse' '503': $ref: '#/responses/503ErrorResponse' security: - ThirdPartyOAuth2Security: - payments parameters: x-idempotency-key-Param: name: x-idempotency-key in: header description: >- Every request will be processed only once per x-idempotency-key. The Idempotency Key will be valid for 24 hours. required: true type: string pattern: ^(?!\s)(.*)(\S)$ maxLength: 40 x-fapi-customer-ip-address-Param: in: header name: x-fapi-customer-ip-address type: string required: false description: >- The Customer's IP address if the Customer is currently logged in with the Third Party. pattern: ^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$ x-fapi-interaction-id-Param: in: header name: x-fapi-interaction-id type: string required: false description: >- An RFC4122 UID used as a correlation id. x-fapi-auth-date-Param: in: header name: x-fapi-auth-date type: string required: false description: >- The time when the Customer last logged in with the Third Party. All dates in the HTTP headers are represented as RFC 7231 Full Dates. An example is below: Sun, 10 Sep 2017 19:43:31 UTC pattern: >- ^(Mon|Tue|Wed|Thu|Fri|Sat|Sun), \d{2} (Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec) \d{4} \d{2}:\d{2}:\d{2} (GMT|UTC)$ x-merchant-ip-address-Param: in: header name: x-merchant-ip-address type: string required: false description: >- The IP address of the merchant when making payment requests through a Third Party. pattern: ^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)\.){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$ x-customer-user-agent-Param: in: header name: x-customer-user-agent type: string required: false description: >- The User-Agent of the application on the customer device that is used to request the payment AuthorizationParam: in: header name: Authorization type: string required: true description: >- An Authorisation Token as per https://tools.ietf.org/html/rfc6750 ConsentIdParam: name: ConsentId in: path description: >- Unique identification as assigned by the API Provider to uniquely identify the consent. required: true type: string DomesticPaymentIdParam: name: DomesticPaymentId in: path description: >- Unique identification as assigned by the API Provider to uniquely identify the the domestic payment. required: true type: string definitions: Error: type: object properties: ErrorCode: description: >- Low level textual error code. type: string enum: - Field.Expected - Field.Invalid - Field.Missing - Field.Unexpected - Header.Invalid - Header.Missing - Reauthenticate - Reauthorise - Resource.Consent.CreditorAccount - Resource.Consent.DebtorAccount - Resource.Consent.Exceed.DataPermissions - Resource.Consent.Exceed.Dates - Resource.Consent.Exceed.Frequency - Resource.Consent.Exceed.MaximumAmount - Resource.Consent.Exceed.TotalAmount - Resource.Consent.Exceed.TotalCount - Resource.Consent.Exceed.TransactionDates - Resource.Consent.InvalidStatus - Resource.Consent.Mismatch - Resource.Invalid - UnexpectedError - Unsupported.AccountIdentifier - Unsupported.AccountSecondaryIdentifier - Unsupported.Currency - Unsupported.Scheme Message: description: >- A free text description of the error that occurred. E.g., 'A mandatory field isn't supplied'. type: string minLength: 1 maxLength: 500 Path: description: >- A recommended but optional reference to the JSON Path of the field with error, e.g., Data.Consent.InstructedAmount.Currency type: string minLength: 1 maxLength: 500 Url: description: >- URL to help remediate the problem, provide more information or to API Reference. type: string required: - ErrorCode - Message additionalProperties: false minProperties: 1 ErrorResponse: description: >- An array of detail error codes, and messages, and URLs to documentation to help remediation. type: object properties: Code: description: >- High level textual error code to help categorise the errors. type: string minLength: 1 maxLength: 128 Id: description: >- A unique reference for the error instance, for audit purposes, in case of unknown/unclassified errors. type: string minLength: 1 maxLength: 128 Message: description: >- Brief Error message. E.g., 'There is something wrong with the request parameters provided' type: string minLength: 1 maxLength: 500 Errors: items: $ref: '#/definitions/Error' type: array minItems: 1 required: - Code - Message - Errors additionalProperties: false CreditorAgent: description: Financial institution servicing an account for the creditor. title: CreditorAgent type: object properties: SchemeName: description: >- Name of the identification scheme, in a coded form as published in an external list. type: string enum: - BICFI Identification: description: >- Unique and unambiguous identification of an organisation. ISO20022 defines this - https://www.iso20022.org/standardsrepository/public/wqt/Description/mx/dico/datatypes/_YWZBNtp-Ed-ak6NoX_4Aeg_-1295138508 type: string minLength: 1 maxLength: 35 required: - SchemeName - Identification additionalProperties: false CreditorAccount: description: >- Unambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction. title: CreditorAccount type: object properties: SchemeName: description: >- Name of the identification scheme, in a coded form as published in an external list. type: string enum: - BECSElectronicCredit default: BECSElectronicCredit Identification: description: >- Identification assigned by an institution to identify an account. This identification is known by the account owner. For the NZ market, this will use the hyphen-delimited format - 2-4-7-2 where this is made up of bank-branch-account-suffix and each of the four components is a number, prepended with leading zeros to match the component length requirement. For example 12-0123-0012345-00 type: string minLength: 1 maxLength: 34 Name: description: >- Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage - The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number. API Providers may carry out name validation for Confirmation of Payee, but it is not mandatory. type: string minLength: 1 maxLength: 70 SecondaryIdentification: description: >- This is secondary identification of the account, as assigned by the account servicing institution. type: string minLength: 1 maxLength: 34 required: - SchemeName - Identification - Name additionalProperties: false DebtorAccount: description: >- Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction. title: DebtorAccount type: object properties: SchemeName: description: >- Name of the identification scheme, in a coded form as published in an external list. title: SchemeName type: string enum: - BECSElectronicCredit default: BECSElectronicCredit Identification: description: >- Identification assigned by an institution to identify an account. This identification is known by the account owner. For the NZ market, this will use the hyphen-delimited format - 2-4-7-2 where this is made up of bank-branch-account-suffix and each of the four components is a number, prepended with leading zeros to match the component length requirement. For example 12-0123-0012345-00 type: string minLength: 1 maxLength: 34 Name: description: >- Name of the account, as assigned by the account servicing institution, in agreement with the account owner in order to provide an additional means of identification of the account. Usage - The account name is different from the account owner name. The account name is used in certain user communities to provide a means of identifying the account, in addition to the account owner's identity and the account number. type: string minLength: 1 maxLength: 70 SecondaryIdentification: description: >- This is secondary identification of the account, as assigned by the account servicing institution. type: string minLength: 1 maxLength: 34 required: - SchemeName - Identification additionalProperties: false Meta: type: object description: Metadata relevant to the payload properties: TotalPages: type: integer format: int32 additionalProperties: false Links: type: object description: Links to assist API navigation properties: Self: type: string format: uri First: type: string format: uri Prev: type: string format: uri Next: type: string format: uri Last: type: string format: uri required: - Self Risk: type: object description: >- The Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring. properties: GeoLocation: description: >- Location of the end-user on the earth specified by two numbers representing vertical and horizontal position type: object properties: Latitude: description: >- Latitude measured in decimal degress type: string maxLength: 14 pattern: ^-?\d{1,3}\.\d{1,8}$ Longitude: description: >- Longitude measured in decimal degress type: string maxLength: 14 pattern: ^-?\d{1,3}\.\d{1,8}$ required: - Latitude - Longitude additionalProperties: false PaymentContextCode: description: >- Specifies the payment context type: string enum: - BillPayment - EcommerceGoods - EcommerceServices - Other - PersonToPerson MerchantCategoryCode: description: >- Category code conforms to ISO 18245, related to the type of services or goods the merchant provides for the transaction type: string minLength: 3 maxLength: 4 MerchantCustomerIdentification: description: >- The unique customer identifier of the Customer with the merchant. type: string minLength: 1 maxLength: 70 DeliveryAddress: description: >- Information that locates and identifies a specific address, as defined by postal services or in free format text. type: object properties: AddressType: description: >- Identifies the nature of the postal address. type: string enum: - DeliveryTo AddressLine: description: >- Information that locates and identifies a specific address, as defined by postal services, that is presented in free format text. type: array items: type: string minLength: 1 maxLength: 70 minItems: 0 maxItems: 5 StreetName: description: >- Name of a street or thoroughfare. type: string minLength: 1 maxLength: 70 BuildingNumber: description: >- Number that identifies the position of a building on a street. type: string minLength: 1 maxLength: 16 PostCode: description: >- Identifier consisting of a group of letters and/or numbers that is added to a postal address to assist the sorting of mail type: string minLength: 1 maxLength: 16 TownName: description: >- Name of a built-up area, with defined boundaries, and a local government. type: string minLength: 1 maxLength: 35 CountrySubDivision: description: >- Identifies a subdivision of a country, for instance state, region, county. type: string minLength: 1 maxLength: 35 Country: description: >- Nation with its own government, occupying a particular territory. type: string pattern: '^[A-Z]{2,2}$' required: - Country additionalProperties: false EndUserAppName: description: >- Name of the end user facing application type: string minLength: 1 maxLength: 70 EndUserAppVersion: description: >- Version of the end user facing application type: string minLength: 1 maxLength: 14 MerchantName: description: >- Name of the merchant type: string minLength: 1 maxLength: 70 MerchantNZBN: description: >- NZ business number for the merchant type: string minLength: 1 maxLength: 70 additionalProperties: false BECSRemittance: type: object description: >- Remittance information for use with BECSElectronicCredit payment scheme. properties: CreditorName: description: >- The Creditor's Name. type: string maxLength: 20 CreditorReference: type: object description: >- Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system. properties: Particulars: type: string description: >- Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction. maxLength: 12 Code: type: string description: >- Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction. maxLength: 12 Reference: type: string description: >- Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction. maxLength: 12 DebtorName: type: string description: >- The Debtor's Name. maxLength: 20 DebtorReference: type: object description: >- Information supplied to enable the reconciling of the payment with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system. properties: Particulars: type: string description: >- Reference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction. maxLength: 12 Code: type: string description: >- Reference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction. maxLength: 12 Reference: type: string description: >- Reference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction. maxLength: 12 required: - CreditorName additionalProperties: false DomesticConsent: type: object properties: InstructionIdentification: description: >- Unique identification as assigned by an instructing party for an instructed party to unambiguously identify the instruction. Usage - The instruction identification is a point to point reference that can be used between the instructing party and the instructed party to refer to the individual instruction. It can be included in several messages related to the instruction. NZ - Updated to allow 36 characters to allow for v4 UUID type: string minLength: 1 maxLength: 36 EndToEndIdentification: description: >- Unique identification assigned by the initiating party to unambiguously identify the transaction. This identification is passed on, unchanged, throughout the entire end-to-end chain. Usage - The end-to-end identification can be used for reconciliation or to link tasks relating to the transaction. It can be included in several messages related to the transaction. NZ - Updated to 36 characters to allow v4 UUID type: string minLength: 1 maxLength: 36 DebtorAccountRelease: type: boolean default: false InstructedAmount: description: >- Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party. Usage - This amount has to be transported unchanged through the transaction chain. type: object properties: Amount: description: >- A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. type: string pattern: '^\d{1,13}\.\d{1,5}$' Currency: description: >- A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 - Codes for the representation of currencies and funds. type: string pattern: '^[A-Z]{3,3}$' required: - Amount - Currency additionalProperties: false DebtorAccount: $ref: '#/definitions/DebtorAccount' CreditorAgent: $ref: '#/definitions/CreditorAgent' CreditorAccount: $ref: '#/definitions/CreditorAccount' RemittanceInformation: description: >- Information supplied to enable the matching of an entry with the items that the transfer is intended to settle, such as commercial invoices in an accounts' receivable system. title: RemittanceInformation type: object properties: Reference: $ref: '#/definitions/BECSRemittance' additionalProperties: false required: - InstructionIdentification - EndToEndIdentification - InstructedAmount - CreditorAccount - RemittanceInformation additionalProperties: false DomesticPaymentConsent: type: object description: Request data properties: Consent: $ref: '#/definitions/DomesticConsent' required: - Consent additionalProperties: false DomesticPaymentConsentResponse: type: object description: Response data properties: ConsentId: description: >- Unique identification as assigned by the API Provider to uniquely identify the consent. type: string minLength: 1 maxLength: 128 Status: description: Specifies the status of consent in code form. title: ConsentStatusCode type: string enum: - AwaitingAuthorisation - Authorised - Consumed - Rejected CreationDateTime: description: >- Date and time at which the consent was created. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00 type: string format: date-time StatusUpdateDateTime: description: >- Date and time at which the consent was updated. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00 type: string format: date-time Consent: $ref: '#/definitions/DomesticConsent' required: - ConsentId - Status - CreationDateTime - StatusUpdateDateTime - Consent additionalProperties: false DomesticPayment: type: object description: Request data properties: ConsentId: description: >- Unique identification as assigned by the API Provider to uniquely identify the consent. type: string minLength: 1 maxLength: 128 Initiation: $ref: '#/definitions/DomesticConsent' required: - ConsentId - Initiation additionalProperties: false DomesticPaymentResponse: type: object description: Response data properties: DomesticPaymentId: description: >- Unique identification as assigned by the API Provider to uniquely identify the domestic payment. type: string minLength: 1 maxLength: 40 ConsentId: description: >- Unique identification as assigned by the API Provider to uniquely identify the consent. type: string minLength: 1 maxLength: 128 Status: description: Specifies the status of the payment information group. title: PaymentStatusCode type: string enum: - Pending - AcceptedSettlementInProcess - AcceptedSettlementCompleted - Rejected CreationDateTime: description: >- Date and time at which the domestic payment was created. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00 type: string format: date-time StatusUpdateDateTime: description: >- Date and time at which the domestic payment was updated. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00 type: string format: date-time Initiation: $ref: '#/definitions/DomesticConsent' required: - DomesticPaymentId - ConsentId - Status - CreationDateTime - StatusUpdateDateTime - Initiation additionalProperties: false DomesticPaymentDebtorAccountResponse: type: object description: Response data properties: DebtorAccount: $ref: '#/definitions/DebtorAccount' required: - DebtorAccount additionalProperties: false EnduringConsent: description: >- The Consent payload is sent by the Third Party to the API Provider. It is used to request a long lived payment consent to move funds from a debtor account to a creditor. type: object properties: FromDateTime: description: >- Date and time at which the consent is expected to be valid from. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00 type: string format: date-time ToDateTime: description: >- Date and time at which the consent is valid to. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00 type: string format: date-time TotalCount: description: >- Maximum number of instructions to be created and processed for the enduring payment consent. type: integer format: int32 DebtorAccountRelease: type: boolean default: false TotalAmount: description: >- Maximum amount of money to be moved between the debtor and creditor as a cumulative total for the duration of the enduring payment consent, before deduction of charges, expressed in the currency as ordered by the initiating party. type: object properties: Amount: description: >- A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. type: string pattern: '^\d{1,13}\.\d{1,5}$' Currency: description: >- A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 - Codes for the representation of currencies and funds. type: string pattern: '^[A-Z]{3,3}$' required: - Amount - Currency additionalProperties: false MaximumAmount: description: >- Maximum amount of money to be moved between the debtor and creditor for an individual payment, before deduction of charges, expressed in the currency as ordered by the initiating party. type: object properties: Amount: description: >- A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. type: string pattern: '^\d{1,13}\.\d{1,5}$' Currency: description: >- A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 - Codes for the representation of currencies and funds. type: string pattern: '^[A-Z]{3,3}$' required: - Amount - Currency additionalProperties: false Frequency: type: object properties: Period: type: string enum: - Annual - Daily - Fortnightly - Monthly - Weekly TotalCount: type: integer format: int32 TotalAmount: description: >- Maximum amount of money to be moved between the debtor and creditor during the period specified, before deduction of charges, expressed in the currency as ordered by the initiating party. type: object properties: Amount: description: >- A number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217. type: string pattern: '^\d{1,13}\.\d{1,5}$' Currency: description: >- A code allocated to a currency by a Maintenance Agency under an international identification scheme, as described in the latest edition of the international standard ISO 4217 - Codes for the representation of currencies and funds. type: string pattern: '^[A-Z]{3,3}$' required: - Amount - Currency additionalProperties: false required: - Period - TotalAmount additionalProperties: false DebtorAccount: $ref: '#/definitions/DebtorAccount' CreditorAccount: type: array items: $ref: '#/definitions/CreditorAccount' minItems: 1 required: - FromDateTime - Frequency - MaximumAmount - CreditorAccount additionalProperties: false EnduringPaymentConsent: type: object description: Request data properties: Consent: $ref: '#/definitions/EnduringConsent' required: - Consent additionalProperties: false EnduringPaymentConsentResponse: type: object description: Response data properties: ConsentId: description: >- Unique identification as assigned by the API Provider to uniquely identify the consent. type: string minLength: 1 maxLength: 128 Status: description: Specifies the status of consent in code form. title: ConsentStatusCode type: string enum: - AwaitingAuthorisation - Authorised - Revoked - Rejected CreationDateTime: description: >- Date and time at which the consent was created. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00 type: string format: date-time StatusUpdateDateTime: description: >- Date and time at which the consent was updated. All dates in the JSON payloads are represented in ISO 8601 date-time format. All date-time fields in responses must include the timezone. An example is below: 2017-04-05T10:43:07+00:00 type: string format: date-time Consent: $ref: '#/definitions/EnduringConsent' required: - ConsentId - Status - CreationDateTime - StatusUpdateDateTime - Consent additionalProperties: false securityDefinitions: CustomerOAuth2Security: type: oauth2 flow: accessCode tokenUrl: 'https://authserver.example/token' authorizationUrl: 'https://authserver.example/authorization' scopes: payments: Generic payment scope description: >- OAuth flow, it is required when the Customer needs to perform SCA with the API Provider when a Third Party wants to access an API Provider resource owned by the Customer ThirdPartyOAuth2Security: type: oauth2 flow: application tokenUrl: 'https://authserver.example/token' scopes: payments: Generic payment scope description: >- Third Party client credential authorisation flow with the API Provider tags: - name: Enduring Payment Consents description: Long lived payment-order consent - name: Domestic Payment Consents description: Short lived payment-order consent - name: Domestic Payments description: Single, domestic, electronic credit payment-order responses: 400ErrorResponse: description: Bad Request headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/ErrorResponse' 401ErrorResponse: description: Unauthorized headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. 403ErrorResponse: description: Forbidden headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/ErrorResponse' 405ErrorResponse: description: Method Not Allowed headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. 406ErrorResponse: description: Not Acceptable headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. 415ErrorResponse: description: Unsupported Media Type headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. 429ErrorResponse: description: Too Many Requests headers: Retry-After: description: Number in seconds to wait type: integer x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. 500ErrorResponse: description: Internal Server Error headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/ErrorResponse' 501ErrorResponse: description: Not Implemented headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. 503ErrorResponse: description: Service Unavailable headers: x-fapi-interaction-id: type: string description: An RFC4122 UID used as a correlation id. schema: $ref: '#/definitions/ErrorResponse'