Contents
Table of Contents maxLevel 4 outline true
Version Control
Version | Date | Author | Comments |
---|---|---|---|
1.0.0 | 01 March 2019 | Payments 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.
...
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.
Expand | ||
---|---|---|
| ||
@startuml
Pending -down-> AcceptedTechnicalValidation : [API call is valid] AcceptedCustomerProfile-right->AcceptedSettlementInProcess : [Payment has been successfully submitted to API Provider] @enduml |
Enumerations
Common Enumerations
This section gives the definitions for enumerations shared by the payments and payment-submissions resources
Code Class | Name | Definition |
---|---|---|
ExternalPaymentContext1Code | BillPayment | The context of the payment initiation is a bill payment. |
ExternalPaymentContext1Code | EcommerceGoods | The context of the payment initiation is for goods via an ecommerce channel. |
ExternalPaymentContext1Code | EcommerceServices | The context of the payment initiation is for services via an ecommerce channel. |
ExternalPaymentContext1Code | PartyToParty | The context of the payment initiation is a party to party payment. |
ExternalPaymentContext1Code | Other | The context of the payment initiation is of an other type. |
OBExternalAccountIdentification2Code | BECSElectronicCredit | 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:
|
OBExternalFinancialInstitutionIdentification2Code | BICFI | Valid 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. |
OBTransactionIndividualStatus1Code | AcceptedCustomerProfile | Preceding check of technical validation was successful. Customer profile check was also successful. |
OBTransactionIndividualStatus1Code | AcceptedSettlementCompleted | Settlement on the debtor's account has been completed. Third Parties must not use this status as confirmation that settlement is complete on the creditor's account. |
OBTransactionIndividualStatus1Code | AcceptedSettlementInProcess | All preceding checks such as technical validation and customer profile were successful and therefore the payment initiation has been accepted for execution. |
OBTransactionIndividualStatus1Code | AcceptedTechnicalValidation | Authentication and syntactical and semantic validation are successful. |
OBTransactionIndividualStatus1Code | Pending | Payment initiation or individual transaction included in the payment initiation is pending. Further checks and status update will be performed. |
OBTransactionIndividualStatus1Code | Rejected | Payment 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 Type | Fields | ISO Enumerations Values URL |
---|---|---|
Min3Max4Text | MerchantCategoryCode | https://www.iso.org/standard/33365.html |
ActiveOrHistoricCurrencyCode | Currency | https://www.iso20022.org/external_code_list.page |
CountryCode | Currency | https://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.
...
Payments
Resource | End-point | Mandatory ? | Scope | Grant Type | Idempotent | Request Object | Response Object |
---|---|---|---|---|---|---|---|
payments | POST /payments | Mandatory | third_party_client_credential | Client Credentials | Yes | OBPaymentSetup1 | OBPaymentSetupResponse1 |
payments | GET /payments/{PaymentId} | Mandatory | third_party_client_credential | Client Credentials | NA | NA | OBPaymentSetupResponse1 |
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.
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.
Expand | ||
---|---|---|
| ||
@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
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBPaymentSetup1 | OBPaymentSetup1 | OBPaymentSetup1 | ||||
Data | 1..1 | OBPaymentSetup1/Data | OBPaymentDataSetup1 | |||
Initiation | 1..1 | OBPaymentSetup1/Data/Initiation | The 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 | ||
Risk | 1..1 | OBPaymentSetup1/Risk | The 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
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBPaymentSetupResponse1 | OBPaymentSetupResponse1 | OBPaymentSetupResponse1 | ||||
Data | 1..1 | OBPaymentSetupResponse1/Data | OBPaymentDataSetupResponse1 | |||
PaymentId | 1..1 | OBPaymentSetupResponse1/Data/PaymentId | Unique identification as assigned by the API Provider to uniquely identify the payment setup resource. | Max128Text | ||
Status | 1..1 | OBPaymentSetupResponse1/Data/Status | Specifies the status of the payment resource. | OBTransactionIndividualStatus1Code | AcceptedCustomerProfile AcceptedTechnicalValidation Pending Rejected | |
CreationDateTime | 1..1 | OBPaymentSetupResponse1/Data/CreationDateTime | Date and time at which the resource was created. | ISODateTime | ||
Initiation | 1..1 | OBPaymentSetupResponse1/Data/Initiation | The 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 | ||
Risk | 1..1 | OBPaymentSetupResponse1/Risk | The 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:
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 State. |
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. insufficient funds. |
3 | AcceptedSettlementInProcess | 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:
|
Once settlement on the debtor's account has been completed, the payments-submissions resource may have one of the following statuses:
Status | Payment Status Description | NZ Status Clarification | |
---|---|---|---|
4 | AcceptedSettlementCompleted | Settlement 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:
|
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.
Expand | ||
---|---|---|
| ||
@startuml
Pending -down-> AcceptedSettlementInProcess : [API call is valid] @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
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBPaymentSubmission1 | OBPaymentSubmission1 | OBPaymentSubmission1 | ||||
Data | 1..1 | OBPaymentSubmission1/Data | OBPaymentDataSubmission1 | |||
PaymentId | 1..1 | OBPaymentSubmission1/Data/PaymentId | Unique identification as assigned by the API Provider to uniquely identify the payment setup resource. | Max128Text | ||
Initiation | 1..1 | OBPaymentSubmission1/Data/Initiation | The 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 | ||
Risk | 1..1 | OBPaymentSubmission1/Risk | The 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
Name | Occurrence | XPath | EnhancedDefinition | Class | Codes | Pattern |
---|---|---|---|---|---|---|
OBPaymentSubmissionResponse1 | OBPaymentSubmissionResponse1 | OBPaymentSubmissionResponse1 | ||||
Data | 1..1 | OBPaymentSubmissionResponse1/Data | OBPaymentDataSubmissionResponse1 | |||
PaymentSubmissionId | 1..1 | OBPaymentSubmissionResponse1/Data/PaymentSubmissionId | Unique identification as assigned by the API Provider to uniquely identify the payment submission resource. | Max40Text | ||
PaymentId | 1..1 | OBPaymentSubmissionResponse1/Data/PaymentId | Unique identification as assigned by the API Provider to uniquely identify the payment setup resource. | Max128Text | ||
Status | 1..1 | OBPaymentSubmissionResponse1/Data/Status | Specifies the status of the payment submission resource. | OBTransactionIndividualStatus1Code | AcceptedSettlementCompleted AcceptedSettlementInProcess Pending Rejected | |
CreationDateTime | 1..1 | OBPaymentSubmissionResponse1/Data/CreationDateTime | Date and time at which the resource was created. | ISODateTime | ||
Initiation | 1..1 | OBPaymentSubmissionResponse1/Data/Initiation | The 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 | ||
Risk | 1..1 | OBPaymentSubmissionResponse1/Risk | The 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
Expand | ||
---|---|---|
| ||
participant "Customer" as Cx |
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
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
...
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
Code Block | ||||||
---|---|---|---|---|---|---|
| ||||||
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
Expand | ||
---|---|---|
| ||
participant "Customer" as Cx |
Illustrative Interactions
POST /payments request
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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
Code Block | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
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
Expand | ||
---|---|---|
| ||
participant "Customer" as Cx The status of the resource may be |
Idempotent Payment Submission
Payment Submission Conflict - Sequence Diagram
Expand | ||
---|---|---|
| ||
participant "Customer" as Cx The operation can be retried multiple times |
Swagger Specification
Use the below link to download and access the raw YAML swagger specifications in .txt format.
payment-initiation-nz-swagger.txtspecifications from the Payments NZ API Centre GitHub repo:
https://github.com/PaymentsNZ/API-Payments-Initiation/tree/master/dist/v1.0.0