Payments Initiation API Specification v1.0.0

Owned by Matthew Bell
Last updated: Feb 21, 2021
28 min read

Contents

Version Control

VersionDateAuthorComments
1.0.001 March 2019Payments NZ API Working Group

Payment Initiation specifcation.

Overview

This Payment Initiation API Specification describes the flows and payloads for initiating a single, domestic, electronic credit payment.

The API endpoints described here allow a Third Party  to: 

  • Register an intent to setup a payment instruction 
  • Subsequently submit the payment instruction for processing
  • Optionally retrieve the status of a payment setup or submission.

This specification should be read in conjunction with NZ Banking Data API Specification which provides a description of the elements that are common across all the NZ Banking Data APIs.

Document Structure

This document consists of the following parts:

Overview: Provides an overview of the scope of the API and the key decisions that contributed to the specification.

Basics: The section identifies the resources, operations that are permitted on those resources, and various special cases.

Endpoints: Provides the list of endpoints for the API specification. The individual end-points are documented in separate sections along with the data model that they employ.

Security & Access Control: Specifies the means for Third Parties (or TPP) and Customers (or PSU) to authenticate themselves and provide consent.

Payments: Describes the specifics of the endpoints for the payments resource.

Payment Submissions: Describes the specifics of the endpoints for the payment-submissions resource.

Usage Examples: Examples for normal flows, and alternate flows.

Swagger Specifications: Provides links to the swagger specifications for the APIs.

Scope

The APIs in this document allow a Third Party to initiate a single, domestic, electronic credit payment made in NZD.

Out of Scope

This specification does not cater for:

  • Payments that involve currency exchange.
  • Payments that involve currencies other than NZD
  • Payments that are not single, domestic, electronic credit payments made in NZD - i.e., payments that are:
    • In bulk - single debit, multiple credit
    • Future dated or deferred
    • Recurring.
  • Multi-authentication flows have been designed - but the full implications of the multi-authentication flows have not been worked through - so these are not included in this version.
  • Non-functional requirements and specification of caching and throttling.


Basics

Overview

The figure below provides a general outline of a payment flow using the Payment APIs.

Diagram



Steps

Step 1: Request Payment Initiation

  • This flow begins with a Customer requesting to initiate a payment being made by a Third Party on their behalf.
  • The debtor account and payment details can optionally be specified at this stage.

Step 2: Setup Single Payment Initiation

  • The Third Party  connects to the Bank  that services the Customer's (or Customer's) payment account and creates a new payments resource. This informs the Bank that one of its Customers intends to make a payment. The Bank responds with an identifier for the resource (the PaymentId - which is the intent identifier).
  • This step is carried out by making a POST request to the payments resource.

Step 3: Authorise Consent

  • The Third Party redirects the Customer to the Bank. The redirect includes the PaymentId generated in the previous step. This allows the Bank to correlate the payment that was setup. The Bank authenticates the Customer. This could use a form of strong authentication, such as multi-factor authentication, if the Bank desires. The Bank  updates the state of the payments resource internally to indicate that the payment has been authorized.
  • The Customer selects the debtor account at this stage - if it has not been previously specified in Step 1.
  • The Customer is redirected back to the Third Party.

Step 4: Create Payment Submission

  • Once the Customer is redirected to the Third Party, the Third Party creates a payment-submissions resource to indicate that the payment created in the steps above should be submitted for processing.
  • This is carried out by making a POST request to the payment-submissions resource.
  • Bank returns the PaymentSubmissionId to the Third Party.

Step 5: Get Payment Submission Status

  • If the Bank provides a status API, the Third Party can check the status of the payment (with the PaymentId) or payment-submission (with the PaymentSubmissionId).
  • This is carried out by making a GET request to the payments or payment-subsmissions resource.

Sequence Diagram

 Click here to expand UML diagram source...

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
note over Cx, APIProviderRS
Step 1: Request payment initiation
end note
Cx -> 3P: Send payment initiation request
note over Cx, APIProviderRS
Step 2: Setup single payment initiation
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payments
APIProviderRS -> 3P: HTTP 201 (Created),  PaymentId
3P -> Cx: HTTP 302 (Found), Redirect (PaymentId)
note over Cx, APIProviderRS
Step 3: Authorize consent
end note
Cx -> APIProviderAS: Follow redirect (PaymentId)
group Refer to Consent Guidelines
Cx <-> APIProviderAS: Authenticate, may involve multi-factors or other strong authentication mechanisms
Cx <-> APIProviderAS: Select debtor account
end group
APIProviderAS -> Cx: HTTP 302 (Found), Redirect (authorization-code)
Cx -> 3P: Follow redirect (authorization-code)
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Exchange authorization-code for access token
APIProviderAS -> 3P: access-token
note over Cx, APIProviderRS
Step 4: Create payment submission
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payment-submissions
APIProviderRS -> 3P: HTTP 201 (Created), PaymentSubmissionId
note over Cx, APIProviderRS
Step 5: Get payment submission status
end note
opt
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: GET /payment-submissions/{PaymentSubmissionId}
APIProviderRS -> 3P: HTTP 200 (OK) payment-submissions resource
end opt


Idempotency

POST operations on both the /payments and /payment-submissions endpoint are designed to be idempotent. The intent of this capability is to allow Third Party to retry API requests that failed with a timeout or an unexpected error.

If the Third Party re-uses an x-Idempotency-key that they previously used within the last 24 hours, but with a different payment Id on the request the API Provider must reject the request with a status code of 400 (Bad Request) 

Payment Limits

The standard does not provide a uniform limit for payments that can be supported through this API.

Each API Provider must determine an appropriate limit that they support based on their individual practices, standards and limitations.

Endpoints

This section looks at the list of available API endpoints to access Account Information and optionality (definitions of mandatory, conditional or optional are defined in the Principles section of the NZ Banking Data API Specification).

The API Provider must implement the API endpoints in the table below that are marked as mandatory.

The API Provider may optionally implement the API endpoints that are marked as non-mandatory.

If an API Provider has not implemented an optional API endpoint, it must respond with a 501 (Not Implemented) for requests to that URL. As all Payment API endpoints are mandatory in this version of the standard, API Providers must not respond with a 501 (Not Implemented) for the Payment APIs.

Endpoint design considerations:

  • Having a separate resource for the payment setup and payment submission means we can extend the flows in the future more easily for bulk and recurring payments. 
  • Separation in setup and submission also allows for cleaner separation in updating the status of resources - for API Providers that chose to implement the functionally
Document SectionResourceEnd-pointMandatory ?
PaymentspaymentsPOST /paymentsMandatory

paymentsGET /payments/{PaymentId}Mandatory
Payment Submissionspayment-submissionsPOST /payment-submissionsMandatory

payment-submissionsGET /payment-submissions/{PaymentSubmissionId}Mandatory


Security & Access Control

Scopes

The access tokens required for accessing the Payment APIs must have one of the following scopes:

Scopes
third_party_client_credential
payments

Grants Types

Third Parties must use a client credentials grant to obtain a token with the scope third_party_client_credential to make POST requests to the payments resource.

Third Parties must use an authorization code grant to obtain a token with the scope payments to make POST requests to the payment-submissions resource.

Third Parties must use a client credentials grant to obtain a token with the scope third_party_client_credential to make GET requests to the payments resource.

Third Parties must use an authorization code grant to obtain a token with the scope payments to make GET requests to the payments-submission resource. The grant type for GET requests to the payment-submission resource is likely to be reviewed for a future version of the standard.

Consent Authorisation

The Third Party must begin a single electronic credit payment request by creating a payments resource through a POST operation. This resource indicates the consent that the Third Party claims it has been given by the Customer. At this stage, the consent is not yet authorised as the API Provider has not yet verified this claim with the Customer.

The API Provider responds with a PaymentId. This is the intent-id that is used when initiating the authorization code grant (as described in the Trust Framework).

As part of the authorization code grant:

  • The API Provider authenticates the Customer.
  • The API Provider plays back the consent (registered by the Third Party) back to the Customer - to get consent authorisation. The Customer may accept or reject the consent in its entirety (but not selectively).
  • If the consent did not indicate a debtor account, the API Provider presents the Customer a list of accounts from which the Customer may select one.

Once these steps are complete, the consent is considered to have been authorised by the Customer

Consent Revocation

A Customer cannot revoke consent for a single electronic credit payment - once it has been authorised.

Changes to Selected Account

For a single electronic credit payment, the selected debtor account cannot be changed once the consent has been authorised.

Handling Expired Tokens

Due to the nature of single electronic credit payments, an access token is unlikely to expire before it is used for creating the payment-submission. Consequently, issuing a refresh token along with the access token is probably not useful in this situation.

However, to simplify their implementation, an API Provider may issue a refresh token along with an access token at the end of an authorisation code grant. 

Identifier Fields

This section describes the identifiers used through the Payment API flows - the direction of flow through the system, and how they are used.

The standard definitions for the elements in the API payloads are described in the Data Model section for each resource. However, this table gives further detail on the business meaning, and how they are used.

GeneratedIdentifierOptional/MandatoryBusiness Description

Merchant/Third Party

Sent in API Payload

EndToEndIdentification
The EndToEndIdentification reference is a reference that can be populated by the debtor (or merchant in the ecommerce space). This reference is important to the debtor (could be an internal reference Id against the transaction), it Is NOT the reference information that will be primarily populated on the statement of the creditor (beneficiary).

Merchant/Third Party

Sent in API Payload

InstructionIdentification

Third Party generates the InstructionIdentification which is a unique transaction Id and passes it to the API Provider (this is mandatory), but this doesn’t have to go any further in the payment flow. The flow of this identifier needs to align with payment scheme rules.

The expectation is that this is unique indefinitely across all time periods. The Third Party can ensure this is indefinitely unique by including a date or date time element to the field, or by inserting a unique Id.

Merchant/Third Party

Sent in API Payload

RemittanceInformation
RemittanceInformation contains Particulars, Code and Reference for both Debtor and Creditor, along with names for both parties.  This information is populated by the Third Party in the payment and payment-submission request. 

API Provider / API System

PaymentId
Unique identification as assigned by the API Provider to uniquely identify the payment setup resource.
API Provider / API SystemPaymentSubmissionId
Unique identification as assigned by the API Provider to uniquely identify the payment-submission resource.

API Provider / Payment Scheme

Scheme Payment ID
This is generated by the API Provider to uniquely identify a payment through a processing scheme. In the case of FPS - this is the FPID.

The tables below identify the actor that initially creates each of the message identifiers and their transmission and visibility to other actors.

These flows are indicative - and will be dependent on what payment schemes or agencies are able to support.

Key:

O indicates the actor that creates the identifier.

=> downstream direction of flow

<= upstream direction of flow

Merchant Flow

Identifier

Customer

Merchant

Third Party

API Provider

Originating Bank

Payment Scheme

Beneficiary

EndToEndIdentification
O=>=>=>=>
RemittanceInformation
O=>=>=>=>
InstructionIdentification

O

=>


PaymentId

<=

O



PaymentSubmissionId

<=O

Scheme Payment ID

(e.g., FPID)




O

=>

=>

Person to Person Flow

Identifier

Customer

Merchant

Third Party

API Provider

Originating Bank

Payment Scheme

Beneficiary

EndToEndIdentification

O=>=>=>
RemittanceInformationO
=>=>=>=>
InstructionIdentification

O

=>


PaymentId

<=

O



PaymentSubmissionId

<=O

Scheme Payment ID

(e.g., FPID)




O

=>

=>

Mapping to Schemes & Standards


ISO 20022

The Initiation section of the Payment API payloads is based on the ISO 20022 pain.001 XML standard - and we have used ISO 20022 message elements or components - where possible. However - has been adapted for APIs based as per our design principles. 

Deviations from the pain.001 XML standard are:

  • The pain.001 header section and trailer sections have been removed - as these are not required for a RESTful API
  • Only fields required for the v1.0 scope of single-debit single-credit NZD payments, immediately executed are included in the payload. This has meant:
    • The separate CreditTransferTransactionInformation section in pain.001 - which is a repeating group for multi-credit payments has been removed and flattened
    • PaymentInformationIdentification not required - we also have a InstructionIdentification
    • PaymentMethod not required - as this is always immediate execution for the API Provider
    • RequestedExecutionDate not required - as this is always as soon as possible - which may differ between FPS and Bacs payments
    • Debtor / DebtorAccount are optional - as the debtor details are not always known to the Third Party submitting the payment setup or submit
  • The Payment Initiation team has requested a flatter structure for the payload:
    • InstructionIdentification and EndToEndIdentification moved to the top level (instead of embedding within PaymentIdentification) 
    • CreditorAgent is simplified to only include the SchemeName and Identification
    • DebtorAccount and CreditorAccount are simplified to only include the SchemeName and Identification


Transaction Status

A principle has been agreed to adhere to the ISO Transaction Status codes.

The ISO Transaction Status has been split into statuses for the payments setup resource, and the payment-submissions resource. Refer to the resource sections for specifics on which states relate to which resource.


 Click here to expand source for state diagram...

@startuml
skinparam monochrome true
hide empty description


[*] --> Pending

Pending -down-> AcceptedTechnicalValidation : [API call is valid]
state Rejected1 as "Rejected"
AcceptedTechnicalValidation -right-> Rejected1 : [Authorisation has failed, payment has been rejected]
AcceptedTechnicalValidation -down-> AcceptedCustomerProfile : [Authorisation is complete]

AcceptedCustomerProfile-right->AcceptedSettlementInProcess : [Payment has been successfully submitted to API Provider]
AcceptedSettlementInProcess-right->Rejected : [Payment has failed and been rejected]
AcceptedSettlementInProcess-down->AcceptedSettlementComplete : [Final checks complete, money has left the debtor's account]

@enduml


Enumerations

Common Enumerations

This section gives the definitions for enumerations shared by the payments and payment-submissions resources

Code ClassName Definition 
ExternalPaymentContext1CodeBillPaymentThe context of the payment initiation is a bill payment.
ExternalPaymentContext1CodeEcommerceGoodsThe context of the payment initiation is for goods via an ecommerce channel.
ExternalPaymentContext1CodeEcommerceServicesThe context of the payment initiation is for services via an ecommerce channel.
ExternalPaymentContext1CodePartyToPartyThe context of the payment initiation is a party to party payment.
ExternalPaymentContext1CodeOtherThe context of the payment initiation is of an other type.
OBExternalAccountIdentification2CodeBECSElectronicCredit

An identifier used to uniquely identify the account of a customer at a financial institution, structured in the form of 12-1234-1234567-12 where:

  • the first two digits are the bank number, which tells us which bank the account resides with;
  • the next four digits indicate the branch number, which tells us which branch of that bank the account is domiciled;  
  • the next seven digits indicate the account number; and
  • the last two digits indicate the account number suffix.
OBExternalFinancialInstitutionIdentification2CodeBICFIValid BICs for financial institutions are registered by the ISO 9362 Registration Authority in the BIC directory, and consist of eight (8) or eleven (11) contiguous characters.
OBTransactionIndividualStatus1CodeAcceptedCustomerProfilePreceding check of technical validation was successful. Customer profile check was also successful.
OBTransactionIndividualStatus1CodeAcceptedSettlementCompleted

Settlement on the debtor's account has been completed.

Usage : this can be used by the first agent to report to the debtor that the transaction has been completed. Warning : this status is provided for transaction status reasons, not for financial information. It can only be used after bilateral agreement.

Third Parties must not use this status as confirmation that settlement is complete on the creditor's account.

OBTransactionIndividualStatus1CodeAcceptedSettlementInProcessAll preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.
OBTransactionIndividualStatus1CodeAcceptedTechnicalValidationAuthentication and syntactical and semantic validation are successful.
OBTransactionIndividualStatus1CodePendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.
OBTransactionIndividualStatus1CodeRejectedPayment initiation or individual transaction included in the payment initiation has been rejected.

ISO Enumerations

These following ISO Enumerations are used in the Payments API

ISO Data TypeFieldsISO Enumerations Values URL
Min3Max4TextMerchantCategoryCodehttps://www.iso.org/standard/33365.html
ActiveOrHistoricCurrencyCodeCurrencyhttps://www.iso20022.org/external_code_list.page
CountryCodeCurrencyhttps://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements

Data Model

Reused Classes

OBInitiation1

This section describes the OBInitiation1 class - which is reused as the Initiation object in the payments and payment-submissions resources.

UML Diagram

Notes

  • The DebtorAccount and DebtorReference are optional - as the Third Party may not know the account identification details for the Customer.
  • If the DebtorAccount is specified by the Third Party - then the account identification details of the Payment resource cannot be changed - as this is part of formal consent from the Customer.
  • If the DebtorAccount is not valid - then the payment will be rejected.
  • If the DebtorAccount is not specified by the Third Party - then the DebtorReference must not be specified, doing so will result in the payment being rejected.
  • If the DebtorReference is specified by the Third Party - then it cannot be changed - as this is part of formal consent from the Customer.
  • SchemeName for PNZ is "BECSElectronicCredit"
  • Where "BECSElectronicCredit" is specified as the SchemeName in the Account identification section, the Servicer section must not be populated and the identification field must be populated with a structured bank account number in the form of 12-1234-1234567-12 where:
    • The first two digits are the bank number, which tells us which bank the account resides with;
    • The next four digits indicate the branch number, which tells us which branch of that bank the account is domiciled;  
    • The next seven digits indicate the account number; and
    • The last two digits indicate the account number suffix.
  • If a Third Party request contains an unsupported account SchemeName, API Provider must return a status code of 400 (Bad Request)
  • If a Third Party request contains an unsupported currency, API Provider must return a status code of 400 (Bad Request)
  • The PNZ API specification includes a specific RemittanceInformation model, called BECSRemittance, which redefines the RemittanceInformation structure for the PaymentSetup object.
  • DebtorReference and CreditorReference - the Particulars, Code and Reference fields are currently constrained to 12 characters. The design choice has been made not to constrain through schema restrictions, to allow for future changes that remove the constraint. Note that not all banks will accept all valid characters. Constraining to a-z, A-Z, - (dash) and 0-9 is advised. One example is abc-XYZ-123.
  • Where the DebtorReference or CreditorReference Particulars, Code and Reference fields contain invalid characters, the API Provider must return a descriptive 400 (Bad Request). 
  • As a merchant may be initiating a payment via a Third Party - two identifiers are included in the payload: 
    • InstructionIdentification is uniquely generated by the Third Party - the expectation is that this is unique indefinitely across all time periods. The Third Party can ensure this is indefinitely unique by including a date or date time element to the field, or by inserting a unique Id. 
    • EndToEndIdentification is uniquely generated by the merchant.
  • Neither the InstructionIdentification nor EndToEndIdentification will be used as the payment resource identifier (PaymentId) - as the PaymentId must be uniquely generated by the API Provider.
  • Design decisions for the Initiation section of the payload - and how this maps to the ISO 20022 messaging standard are articulated in the Mapping to Schemes and Standards section.

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBInitiation1
OBInitiation1The Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

InstructionIdentification1..1OBInitiation1/InstructionIdentificationUnique 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.

OBNZ: Updated to allow 36 characters to allow for v4 UUID		Max36Text

EndToEndIdentification1..1OBInitiation1/EndToEndIdentificationUnique 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.

OBNZ: Updated to allow 36 characters to allow for v4 UUID		Max36Text

InstructedAmount1..1OBInitiation1/InstructedAmountAmount 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.		OBActiveOrHistoricCurrencyAndAmount

Amount1..1OBInitiation1/InstructedAmount/AmountA number of monetary units specified in an active currency where the unit of currency is explicit and compliant with ISO 4217.ActiveCurrencyAndAmount_SimpleType
^\d{1,13}\.\d{1,5}$
Currency1..1OBInitiation1/InstructedAmount/CurrencyA 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".ActiveOrHistoricCurrencyCode
^[A-Z]{3,3}$
DebtorAccount0..1OBInitiation1/DebtorAccountUnambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.OBCashAccountDebtor1

SchemeName1..1OBInitiation1/DebtorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2CodeBECSElectronicCredit
Identification1..1OBInitiation1/DebtorAccount/IdentificationIdentification 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		Max34Text

Name0..1OBInitiation1/DebtorAccount/NameName 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.		Max70Text

SecondaryIdentification0..1OBInitiation1/DebtorAccount/SecondaryIdentificationThis is secondary identification of the account, as assigned by the account servicing institution. Max34Text

CreditorAgent0..1OBInitiation1/CreditorAgentFinancial institution servicing an account for the creditor.OBBranchAndFinancialInstitutionIdentification2

SchemeName1..1OBInitiation1/CreditorAgent/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalFinancialInstitutionIdentification2CodeBICFI
Identification1..1OBInitiation1/CreditorAgent/IdentificationUnique and unambiguous identification of a financial institution or a branch of a financial institution.Max35Text

CreditorAccount1..1OBInitiation1/CreditorAccountUnambiguous identification of the account of the creditor to which a credit entry will be posted as a result of the payment transaction.OBCashAccountCreditor1

SchemeName1..1OBInitiation1/CreditorAccount/SchemeNameName of the identification scheme, in a coded form as published in an external list.OBExternalAccountIdentification2CodeBECSElectronicCredit
Identification1..1OBInitiation1/CreditorAccount/IdentificationIdentification 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		Max34Text

Name1..1OBInitiation1/CreditorAccount/NameName 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.		Max70Text

SecondaryIdentification0..1OBInitiation1/CreditorAccount/SecondaryIdentificationThis is secondary identification of the account, as assigned by the account servicing institution. Max34Text

RemittanceInformation1..1OBInitiation1/RemittanceInformationInformation 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.NZRemittanceInformation1

Reference0..1OBInitiation1/RemittanceInformation/ReferenceRemittance information for use with BECSElectronicCredit payment scheme.NZBECSRemittance1

CreditorName1..1OBInitiation1/RemittanceInformation/Reference/CreditorNameThe Creditor's Name.Max20Text

DebtorName0..1OBInitiation1/RemittanceInformation/Reference/DebtorNameThe Debtor's Name.Max20Text

CreditorReference0..1OBInitiation1/RemittanceInformation/Reference/CreditorReferenceInformation 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.NZBECSReference1

Particulars0..1OBInitiation1/RemittanceInformation/Reference/CreditorReference/ParticularsReference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.Max12Text

Code0..1OBInitiation1/RemittanceInformation/Reference/CreditorReference/CodeReference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.Max12Text

Reference0..1OBInitiation1/RemittanceInformation/Reference/CreditorReference/ReferenceReference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.Max12Text

DebtorReference0..1OBInitiation1/RemittanceInformation/Reference/DebtorReferenceInformation 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.NZBECSReference1

Particulars0..1OBInitiation1/RemittanceInformation/Reference/DebtorReference/ParticularsReference information, as assigned by the debtor, which when combined with Code and Reference, unambiguously refer to the payment transaction.Max12Text

Code0..1OBInitiation1/RemittanceInformation/Reference/DebtorReference/CodeReference information, as assigned by the debtor, which when combined with Particulars and Reference, unambiguously refer to the payment transaction.Max12Text

Reference0..1OBInitiation1/RemittanceInformation/Reference/DebtorReference/ReferenceReference information, as assigned by the debtor, which when combined with Particulars and Code, unambiguously refer to the payment transaction.Max12Text


Payments

ResourceEnd-pointMandatory ?ScopeGrant TypeIdempotentRequest ObjectResponse Object
paymentsPOST /paymentsMandatory

third_party_client_credential

Client CredentialsYesOBPaymentSetup1OBPaymentSetupResponse1
paymentsGET /payments/{PaymentId}Mandatorythird_party_client_credentialClient CredentialsNANAOBPaymentSetupResponse1

Payment Status

The Customer must authenticate with the API Provider and authorise the payment setup for the payment to be successfully setup.When the payments resource is initially created it must have one of the following PaymentStatusCode code-list enumerations:


Status

Payment Status Description

NZ Status Clarification

1

Pending

Payment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.

Initial status.  The request was received but not yet validated. The payment has not yet been authorised.

2

Rejected

Payment initiation or individual transaction included in the payment initiation has been rejected.

Terminal state.  Does not distinguish between failure reasons - e.g. authorisation failed or bank rejected.

3

AcceptedTechnicalValidation

Authentication and syntactical and semantic validation are successful.

Intermediate state. All information supplied in the payment resource is valid, e.g.

  • Adheres to data validation schema

  • Business checks complete such as account is open, account is valid, account has sufficient funds

The payment has not yet been authorised.

When the Customer has authorised consent the status will be updated to "AcceptedCustomerProfile".After authorisation has taken place the payments resource may have these following status:


Status

Payment Status Description

NZ Status Clarification

4

AcceptedCustomerProfile

Preceding check of technical validation was successful. Customer profile check was also successful.

Terminal state.The payment has been authorised by the customer.

This is the state diagram for the status of a payment resource.

 Click here to expand state diagram source...

@startuml

skinparam monochrome true

hide empty description

[*] --> PendingPending -down-> AcceptedTechnicalValidation : [API call is valid]

state Rejected1 as "Rejected"

AcceptedTechnicalValidation -right-> Rejected1 : [Authorisation has failed, payment has been rejected]

AcceptedTechnicalValidation -down-> AcceptedCustomerProfile : [Authorisation is complete]@enduml

POST /payments

The API allows the Third Party to ask an API Provider to create a new payments resource.

  • The POST indicates to the API Provider that a payment should be initiated. At this stage, the Customer may not have been identified by the API Provider, and the request payload may not contain any information of the account that should be debited.
  • This API effectively allows the Third Party to send a copy of the consent (between the Customer and the Third Party)  to the API Provider for the Customer to authorise.
  • The API Provider creates the payments resource and responds with a unique PaymentId to refer to the resource.
  • Note: The payments resource is only valid for 24 hours if not authorised by the Customer.

GET /payments/{PaymentId}

A Third Party may optionally retrieve a payments resource that they have created to check its status.

Data Model

This section gives detail on the payload content for the payments resource. 

Payment Setup - Request

The OBPaymentSetup1 object will be used for the call to:

  • POST /payments

UML Diagram

Notes

The Payment Setup request contains these objects:

  • Initiation

  • Risk

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSetup1
OBPaymentSetup1
OBPaymentSetup1

Data1..1OBPaymentSetup1/Data
OBPaymentDataSetup1

Initiation1..1OBPaymentSetup1/Data/InitiationThe Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

Risk1..1OBPaymentSetup1/RiskThe Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.NZRisk1

Payment Setup - Response

The OBPaymentSetupResponse1 object will be used for a response to a call to:

  • POST /payments

  • GET /payments/{PaymentId}

UML Diagram

Notes

The Payment Setup response contains the full original payload from the Payment Setup POST request - with these additional elements:

  • PaymentId.

  • Status of the payment resource.

  • Date time the payment resource was created.

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSetupResponse1
OBPaymentSetupResponse1
OBPaymentSetupResponse1

Data1..1OBPaymentSetupResponse1/Data
OBPaymentDataSetupResponse1

PaymentId1..1OBPaymentSetupResponse1/Data/PaymentIdUnique identification as assigned by the API Provider to uniquely identify the payment setup resource.Max128Text

Status1..1OBPaymentSetupResponse1/Data/StatusSpecifies the status of the payment resource.OBTransactionIndividualStatus1CodeAcceptedCustomerProfile
AcceptedTechnicalValidation
Pending
Rejected
CreationDateTime1..1OBPaymentSetupResponse1/Data/CreationDateTimeDate and time at which the resource was created.ISODateTime

Initiation1..1OBPaymentSetupResponse1/Data/InitiationThe Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

Risk1..1OBPaymentSetupResponse1/RiskThe Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.NZRisk1

Payment Submissions

Resource

End-Point

Mandatory?

Scope

Grant Type

Idempotent

Request Object

Response Object

payment-submissions

POST /payment-submissions

Mandatory

payments

Authorization Code

Yes

OBPaymentSubmission1

OBPaymentSubmissionResponse1

payment-submissions

GET /payment-submissions/{PaymentSubmissionId}

Mandatory

payments

Authorization Code

NA

NA

OBPaymentSubmissionResponse1

Payment Submission Status

A payment-submission can only be created if its corresponding payments resource has the status of 'AcceptedCustomerProfile'. When payment-submissions resource is initially created it must have  one of the following PaymentStatusCode code-set enumerations:


StatusPayment Status DescriptionNZ Status Clarification
1PendingPayment initiation or individual transaction included in the payment initiation is pending.  Further checks and status update will be performed.Initial State.
2RejectedPayment initiation or individual transaction included in the payment initiation has been rejected.Terminal State.Does not distinguish between failure reasons - e.g. insufficient funds.
3AcceptedSettlementInProcess All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution.Intermediate State.This state indicates:
  • The Payments Resource has been successfully created, including all necessary business checks such as sufficient funds;
  • The customer has authorised consent for the payment to be processed; and
  • The bank has accepted the customer mandate to make the payment.
A payment submission in this status is generally expected to execute successfully; however subsequent fraud checks and/or errors may still prevent the completion of the payment. 

Once settlement on the debtor's account has been completed, the payments-submissions resource may have one of the following statuses:


StatusPayment Status DescriptionNZ Status Clarification
4AcceptedSettlementCompletedSettlement on the debtor's account has been completed. Terminal State.Funds have left the debtors account.  The status of the creditor's account is not known or guaranteed.Settlement on the debtor's account has been completed, but:
  • the inter-bank clearing and settlement process may not have completed and
  • the funds may not have been received in the creditor's account.

Notes

  • In very rare circumstances, a payment submission with a status of AcceptedSettlementCompleted may not be completed end-to-end. These scenarios include:

    • Fraud

    • Bank failure

    • The creditor account is closed/invalid/unable to receive credits

  • These scenarios are best managed in the bilateral agreements between the Third Party and API Provider. 

This is the state diagram for the payments-submission resource.

 Click here to expand state diagram source...

@startuml
skinparam monochrome true
hide empty description


[*] --> Pending

Pending -down-> AcceptedSettlementInProcess : [API call is valid]
AcceptedSettlementInProcess-right->Rejected : [Payment has failed and been rejected]
AcceptedSettlementInProcess-down->AcceptedSettlementComplete : [Final checks complete, money has left the debtor's account]

@enduml



POST /payment-submissions

Once the payment has been authorised by the Customer, the Third Party can proceed to submit the payment for processing:

  • This is done by making a POST request to the payment-submissions resource.

  • This request is an instruction to the API Provider to begin the single electronic credit payment journey. The payment will be submitted immediately, however, there are some scenarios where the payment may not happen immediately (e.g. busy periods at the API Provider or the payment requires settlement with another Bank).

  • The Third Party must ensure that the Initiation and Risk sections of the payment submission match the corresponding Initiation and Risk sections of the original payment resource. If the two do not match, the API Provider must not process the request and must respond with a 400 (Bad Request).

  • Any operations on the payment-submission resource will not result in a Status change for the payment resource.

GET /payment-submissions/{PaymentSubmissionId}

A Third Party can retrieve the payment-submission to check its status.

Notes

  • In very rare circumstances, a payment submission with a status of AcceptedSettlementCompleted may not be completed end-to-end. These scenarios include:

    • Fraud

    • Bank failure

    • The creditor account is closed/invalid/unable to receive credits

  • These scenarios are best managed in the bilateral agreements between the Third Party and API Provider. 

Data Model

This section gives detail on the payload content for the payment-submissions resource. 

Payment Submission - Request

The OBPaymentSubmission1 object will be used for a call to:

  • POST /payment-submissions

UML Diagram

Notes

The payment-submission request object contains the: 

  • PaymentId

  • The full payload from the payment setup request (including the Initiation and Risk sections)

The Initiation and Risk sections of the payment-submission request must match the Initiation and Risk sections of the corresponding payment setup request.

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSubmission1
OBPaymentSubmission1
OBPaymentSubmission1

Data1..1OBPaymentSubmission1/Data
OBPaymentDataSubmission1

PaymentId1..1OBPaymentSubmission1/Data/PaymentIdUnique identification as assigned by the API Provider to uniquely identify the payment setup resource.Max128Text

Initiation1..1OBPaymentSubmission1/Data/InitiationThe Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

Risk1..1OBPaymentSubmission1/RiskThe Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.NZRisk1

Payment Submission - Response

The OBPaymentSubmissionResponse1 object will be used for a response to a call to:

  • POST /payment-submissions

  • GET /payment-submissions/{PaymentSubmissionId}

UML Diagram

Notes

The Payment Submission POST response contains the: 

  • PaymentSubmissionId

  • PaymentId

  • Status of the payment-submission resource

  • Date time the payment-submission resource was created

  • The full payload from the PaymentSubmission request (including the Initiation and Risk sections)

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBPaymentSubmissionResponse1
OBPaymentSubmissionResponse1
OBPaymentSubmissionResponse1

Data1..1OBPaymentSubmissionResponse1/Data
OBPaymentDataSubmissionResponse1

PaymentSubmissionId1..1OBPaymentSubmissionResponse1/Data/PaymentSubmissionIdUnique identification as assigned by the API Provider to uniquely identify the payment submission resource.Max40Text

PaymentId1..1OBPaymentSubmissionResponse1/Data/PaymentIdUnique identification as assigned by the API Provider to uniquely identify the payment setup resource.Max128Text

Status1..1OBPaymentSubmissionResponse1/Data/StatusSpecifies the status of the payment submission resource.OBTransactionIndividualStatus1CodeAcceptedSettlementCompleted
AcceptedSettlementInProcess
Pending
Rejected
CreationDateTime1..1OBPaymentSubmissionResponse1/Data/CreationDateTimeDate and time at which the resource was created.ISODateTime

Initiation1..1OBPaymentSubmissionResponse1/Data/InitiationThe Initiation payload is sent by the initiating party to the API Provider. It is used to request movement of funds from the debtor account to a creditor.OBInitiation1

Risk1..1OBPaymentSubmissionResponse1/RiskThe Risk section is sent by the initiating party to the API Provider. It is used to specify additional details for risk scoring.NZRisk1

Usage Examples

Merchant

This example set of flows and payload examples are for a payment initiated by a merchant via a Third Party.

In this scenario:

  • The merchant has not specified the Debtor Account details for the Customer - the Customer will select their account during the authorisation of consent
  • The merchant's account is a building society account - with a roll number specified in the SecondaryIdentification field

Sequence Diagram

 Click here to expand UML source...

participant "Customer" as Cx
participant "Merchant" as MER
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
note over Cx, APIProviderRS
Step 1: Request payment initiation
end note
Cx -> MER: Check-out and pay
MER -> 3P: Send request to setup single immediate payment initiation
note over Cx, APIProviderRS
Step 2: Setup single payment initiation
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payments
APIProviderRS -> 3P: HTTP 201 (Created), PaymentId
3P -> MER: HTTP 302 (Found), Redirect (PaymentId)
MER -> Cx: HTTP 302 (Found), Redirect (PaymentId)
note over Cx, APIProviderRS
Step 3: Authorize consent
end note
Cx -> APIProviderAS: Follow redirect (PaymentId)
Cx <-> APIProviderAS: authenticate
Cx <-> APIProviderAS: SCA if required
Cx <-> APIProviderAS: Select debtor account
APIProviderAS -> Cx: HTTP 302 (Found), Redirect (authorization-code)
Cx -> 3P: Follow redirect (authorization-code)
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Exchange authorization-code for access token
APIProviderAS -> 3P: access-token
3P -> Cx: HTTP 302 (Found), Redirect back to merchant
Cx -> MER: Follow redirect
MER --> 3P: Check payment status
note over Cx, APIProviderRS
Step 4: Create payment submission
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payment-submissions
APIProviderRS -> 3P: HTTP 201 (Created), PaymentSubmissionId
note over Cx, APIProviderRS
Step 5: Get payment submission status
end note
opt
MER -> 3P: Check payment status
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: GET /payment-submissions/{PaymentSubmissionId}
APIProviderRS -> 3P: HTTP 200 (OK), payment-submissions resource
3P -> MER: HTTP 200 (OK), Return payment-submission Status
end opt


Illustrative Interactions

Notes:

  • As per the Security & Access Control section - examples are given where the call to GET may use either a client credentials grant or an authorization code grant to obtain a token to make GET requests.


POST /payments request

POST /payments HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
 
{
	"Data": {
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "BillPayment",
		"MerchantCategoryCode": "O743",
		"MerchantCustomerIdentification": "CustomerId",
		"DeliveryAddress": {
			"AddressLine": [
				"ACME Wine Sales"
			],
			"StreetName": "Shortland Street",
			"BuildingNumber": "123",
			"PostCode": "1010",
			"TownName": "Auckland",
			"CountrySubDivision": [
				"Auckland Central"
			],
			"Country": "NZ"
		}
	}
}

POST /payments response

HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentId": "58923",
		"Status": "AcceptedTechnicalValidation",
		"CreationDateTime": "2017-06-05T15:15:13+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "BillPayment",
		"MerchantCategoryCode": "O743",
		"MerchantCustomerIdentification": "CustomerId",
		"DeliveryAddress": {
			"AddressLine": [
				"ACME Wine Sales"
			],
			"StreetName": "Shortland Street",
			"BuildingNumber": "123",
			"PostCode": "1010",
			"TownName": "Auckland",
			"CountrySubDivision": [
				"Auckland Central"
			],
			"Country": "NZ"
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payments/58923"
	},
	"Meta": {
		"TotalPages": 0
	}
}

POST /payment-submissions request

POST /payment-submissions HTTP/1.1
Authorization: Bearer Jhingapulaav
x-idempotency-key: FRESNO.1317.GFX.22
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json

{
	"Data": {
		"PaymentId": "58923",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "BillPayment",
		"MerchantCategoryCode": "O743",
		"MerchantCustomerIdentification": "CustomerId",
		"DeliveryAddress": {
			"AddressLine": [
				"ACME Wine Sales"
			],
			"StreetName": "Shortland Street",
			"BuildingNumber": "123",
			"PostCode": "1010",
			"TownName": "Auckland",
			"CountrySubDivision": [
				"Auckland Central"
			],
			"Country": "NZ"
		}
	}
}

POST /payment-submissions response

HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
	"Data": {
		"PaymentSubmissionId": "58923-001",
		"PaymentId": "58923",
		"Status": "AcceptedSettlementInProcess",
		"CreationDateTime": "2017-06-05T15:15:22+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payment-submissions/58923-001"
	},
	"Meta": {
		"TotalPages": 0
	}
}

GET /payments/{PaymentId} request

GET /payments/58923 HTTP/1.1
Authorization: Bearer Jhingapulaav
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

GET /payments/{PaymentId} response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentId": "58923",
		"Status": "AcceptedCustomerProfile",
		"CreationDateTime": "2017-06-05T15:15:13+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "BillPayment",
		"MerchantCategoryCode": "O743",
		"MerchantCustomerIdentification": "CustomerId",
		"DeliveryAddress": {
			"AddressLine": [
				"ACME Wine Sales"
			],
			"StreetName": "Shortland Street",
			"BuildingNumber": "123",
			"PostCode": "1010",
			"TownName": "Auckland",
			"CountrySubDivision": [
				"Auckland Central"
			],
			"Country": "NZ"
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payments/58923"
	},
	"Meta": {
		"TotalPages": 0
	}
}

GET /payment-submissions/{PaymentSubmissionId} request

GET /payment-submissions/58923-001 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

GET /payment-submissions/{PaymentSubmissionId} response

HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
	"Data": {
		"PaymentSubmissionId": "58923-001",
		"PaymentId": "58923",
		"Status": "AcceptedSettlementInProcess",
		"CreationDateTime": "2017-06-05T15:15:22+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					}
				}
			}
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payment-submissions/58923-001"
	},
	"Meta": {
		"TotalPages": 0
	}
}

Person To Person

This example set of flows and payload examples are for a payment initiated by a person to another person via a Third Party.

In this scenario:

  • The Customer has pre-specified the account from which funds will be transferred (i.e., the Debtor Account details)
  • No building society accounts are involved in this interaction - so only the sort code and account number are specified in the DebtorAccount and CreditorAccount sections

Sequence Diagram


 Click here to expand UML source...

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Servcer" as APIProviderRS
note over Cx, APIProviderRS
Step 1: Request payment initiation
end note
Cx <-> 3P: Initiate a funds transfer
Cx -> 3P: Select debtor and creditor accounts
note over Cx, APIProviderRS
Step 2: Setup single payment initiation
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: access-token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payments
APIProviderRS -> 3P: HTTP 201 (Created), PaymentId
3P -> Cx: HTTP 302 (Found), Redirect (PaymentId)
note over Cx, APIProviderRS
Step 3: Authorize consent
end note
Cx -> APIProviderAS: Follow redirect (PaymentId)
Cx <-> APIProviderAS: authenticate
Cx <-> APIProviderAS: SCA if required
APIProviderAS -> Cx: HTTP 302 (Found), Redirect (authorization-code)
Cx -> 3P: Follow redirect (authorization-code)
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Exchange authorization-code for access token
APIProviderAS -> 3P: access-token
note over Cx, APIProviderRS
Step 4: Create payment submission
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payment-submissions
APIProviderRS -> 3P: HTTP 201 (Created), PaymentSubmissionId
note over Cx, APIProviderRS
Step 5: Get payment submission status
end note
opt
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: GET /payment-submissions/{PaymentSubmissionId}
APIProviderRS -> 3P: HTTP 200 (OK), payment-submissions resource
end opt


Illustrative Interactions

POST /payments request

POST payments REQUEST
POST /payments HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESCO.21302.GFX.20
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
 
{
	"Data": {
		"Initiation": {
			"InstructionIdentification": "ANSM023",
			"EndToEndIdentification": "FRESCO.21302.GFX.37",
			"InstructedAmount": {
				"Amount": "20.00",
				"Currency": "NZD"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Andrea Smith"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "21-4321-7654321-12",
				"Name": "Bob Clements"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "PersonToPerson"
	}
}

POST /payment response

POST payments RESPONSE
HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentId": "7290",
		"Status": "AcceptedTechnicalValidation",
		"CreationDateTime": "2017-06-05T15:15:13+00:00",
		"Initiation": {
			"InstructionIdentification": "ANSM023",
			"EndToEndIdentification": "FRESCO.21302.GFX.37",
			"InstructedAmount": {
				"Amount": "20.00",
				"Currency": "NZD"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Andrea Smith"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Bob Clements"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "PersonToPerson"
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payments/7290"
	},
	"Meta": {}
}

POST /payment-submissions request

POST payment-submissions REQUEST
POST /payment-submissions HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-idempotency-key: FRESNO.1317.GFX.22
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
Accept: application/json
 
{
	"Data": {
		"PaymentId": "7290",
		"Initiation": {
			"InstructionIdentification": "ANSM023",
			"EndToEndIdentification": "FRESCO.21302.GFX.37",
			"InstructedAmount": {
				"Amount": "20.00",
				"Currency": "NZD"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Andrea Smith"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "Bob Clements"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Risk": {
		"PaymentContextCode": "PersonToPerson"
	}
}

POST /payment-submissions response

POST payment-submissions RESPONSE
HTTP/1.1 201 Created
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentSubmissionId": "7290-003",
		"PaymentId": "7290",
		"Status": "AcceptedSettlementInProcess",
		"CreationDateTime": "2017-06-05T15:15:22+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "02-0923-0044480-00",
				"Name": "Checking"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payment-submissions/7290-003"
	},
	"Meta": {}
}

GET /payments/{PaymentId} request

GET payments REQUEST
GET /payments/7290 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

GET /payments/{PaymentId} response

GET payments Response
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json

{
  "Data": {
    "PaymentId": "7290",
    "Status": "AcceptedCustomerProfile",
    "CreationDateTime": "2017-06-05T15:15:13+00:00",
    "Initiation": {
      "InstructionIdentification": "ACME412",
      "EndToEndIdentification": "FRESCO.21302.GFX.20",
      "InstructedAmount": {
        "Amount": "165.88",
        "Currency": "NZD"
      },
      "CreditorAccount": {
        "SchemeName": "BECSElectronicCredit",
        "Identification": "12-1234-1234567-12",
        "Name": "ACME Inc",
        "SecondaryIdentification": "0002"
      },
      "DebtorAccount": {
        "SchemeName": "BECSElectronicCredit",
        "Identification": "02-0923-0044480-00",
        "Name": "Checking"
      },
      "RemittanceInformation": {
        "Reference": {
          "CreditorName": "The Creditor",
          "CreditorReference": {
            "Particulars": "CreditorPart",
            "Code": "CreditorCode",
            "Reference": "CreditorRef"
          },
          "DebtorName": "The Debtor",
          "DebtorReference": {
            "Particulars": "DebtorPart",
            "Code": "DebtorCode",
            "Reference": "DebtorRef"
          }
        }
      }
    }
  },
  "Risk": {
    "PaymentContextCode": "PersonToPerson"
  },
  "Links": {
    "Self": "https://api.alphabank.com/open-banking-nz/v1.0/payments/58923"
  },
  "Meta": {}
}

GET /payment-submissions/{PaymentSubmissionId} request

GET payment-submissions REQUEST
GET /payment-submissions/7290-003 HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 UTC
x-fapi-customer-ip-address: 104.25.212.99
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Accept: application/json

GET /payment-submissions/{PaymentSubmissionId} response

GET payment-submissions RESPONSE
HTTP/1.1 200 OK
x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
Content-Type: application/json
 
{
	"Data": {
		"PaymentSubmissionId": "7290-003",
		"PaymentId": "7290",
		"Status": "AcceptedSettlementInProcess",
		"CreationDateTime": "2017-06-05T15:15:22+00:00",
		"Initiation": {
			"InstructionIdentification": "ACME412",
			"EndToEndIdentification": "FRESCO.21302.GFX.20",
			"InstructedAmount": {
				"Amount": "165.88",
				"Currency": "NZD"
			},
			"CreditorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "12-1234-1234567-12",
				"Name": "ACME Inc",
				"SecondaryIdentification": "0002"
			},
			"DebtorAccount": {
				"SchemeName": "BECSElectronicCredit",
				"Identification": "02-0923-0044480-00",
				"Name": "Checking"
			},
			"RemittanceInformation": {
				"Reference": {
					"CreditorName": "The Creditor",
					"CreditorReference": {
						"Particulars": "CreditorPart",
						"Code": "CreditorCode",
						"Reference": "CreditorRef"
					},
					"DebtorName": "The Debtor",
					"DebtorReference": {
						"Particulars": "DebtorPart",
						"Code": "DebtorCode",
						"Reference": "DebtorRef"
					}
				}
			}
		}
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking-nz/v1.0/payment-submissions/7290-003"
	},
	"Meta": {}
}

Alternative and Error Flows

Idempotent Payment Setup

 Click here to expand UML diagram source...

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS
note over Cx, APIProviderRS
Step 2: Setup single payment initiation
end note
3P <-> APIProviderAS: Establish TLS 1.2 MA
3P -> APIProviderAS: Initiate Client Credentials Grant
APIProviderAS -> 3P: token
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payments (x-idempotency-key={Third Party-guid-1})
APIProviderRS -> APIProviderRS: Create new resource (PaymentId=1001)
alt unexpected failure
3P -> APIProviderRS: POST /payments (x-idempotency-key={Third Party-guid-1})
note right of APIProviderRS
The resource server recognizes that
this is the same request as earlier.
A new resource is not created.
The payment id remains the same
(e.g. 1001) as above.

The status of the resource may be
different if it has changed.

This operation can be retried multiple 
times if required.
end note
end
APIProviderRS -> 3P: HTTP 201(Created), PaymentId=1001
3P -> Cx: Redirect (PaymentId}

Idempotent Payment Submission

Payment Submission Conflict - Sequence Diagram

 Click here to expand UML diagram source...

participant "Customer" as Cx
participant "Third Party" as 3P
participant "API Provider\nAuthorisation Server" as APIProviderAS
participant "API Provider\nResource Server" as APIProviderRS  
note over Cx, APIProviderRS
Step 4: Create payment submission
end note
3P <-> APIProviderRS: Establish TLS 1.2 MA
3P -> APIProviderRS: POST /payment-submissions PaymentId = 1001, x-idempotency-key={Third Party-guid-2}
alt Third Party attempts to POST to /payment-submissions with same PaymentId
3P -> APIProviderRS: POST /payment-submissions PaymentId = 1001, x-idempotency-key={Third Party-guid-2}
APIProviderRS -> 3P: HTTP 201 (Created), PaymentSubmissionId
note right of APIProviderRS
The resource server recognizes that this
is the same request as earlier.
A new resource is not created.
The PaymentSubmissionId remains the
same as above. The status of the resource
May be different if it has changed.

The operation can be retried multiple times
if required.
end note
end

Swagger Specification

Use the below link to download the specifications from the Payments NZ API Centre GitHub repo:

https://github.com/PaymentsNZ/API-Payments-Initiation/tree/master/dist/v1.0.0