Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...


Code Block
languagejs
themeMidnight
linenumberstrue
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
languagejs
themeMidnight
linenumberstrue
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
languagejs
themeMidnight
linenumberstrue
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
titleClick 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


Code Block
languagejs
themeMidnight
titlePOST payments REQUEST
linenumberstrue
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
languagejs
themeMidnight
titlePOST payments RESPONSE
linenumberstrue
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
languagejs
themeMidnight
titlePOST payment-submissions REQUEST
linenumberstrue
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
languagejs
themeMidnight
titlePOST payment-submissions RESPONSE
linenumberstrue
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
languagejs
themeMidnight
titleGET payments REQUEST
linenumberstrue
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
languagejs
themeMidnight
titleGET payments Response
linenumberstrue
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
languagejs
themeMidnight
titleGET payment-submissions REQUEST
linenumberstrue
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
languagejs
themeMidnight
titleGET payment-submissions RESPONSE
linenumberstrue
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
titleClick 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


Expand
titleClick 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 and access the raw YAML swagger specifications in .txt format.

payment-initiation-nz-swagger.txt

specifications from the Payments NZ API Centre GitHub repo:

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