-
Notifications
You must be signed in to change notification settings - Fork 0
/
oas3.yaml
363 lines (337 loc) · 14.7 KB
/
oas3.yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
openapi: 3.0.3
info:
title: Validate BPAY Payment API
version: 1.0.0
contact:
name: BPAY
email: [email protected]
description: >
When a payment is submitted to a Financial Institution, the Financial
Institution is required to validate the payment details when accepting it.
This API validates the payment details for the Settlement Date specified in
a request. This API provides functionality to perform BPAY payment
validation before payment is submitted.
* This validation result is correct as at the time of calling the API Service.
* The Validate BPAY Payment API does not result in a payment being submitted to BPAY for processing. The Payment Instruction must be submitted to your financial institution (or BPAY if you are a Scheme Member) before cut-off on the same Business Banking Day as the Settlement date specified in a request.
* A maximum of 200 payment records may be included in a request.
servers:
- url: https://sandbox.api.bpaygroup.com.au/payments/v1
tags:
- name: Bpay
description: Validate payments
paths:
/validatepayments:
post:
tags:
- Bpay
summary: ""
operationId: postValidatePayments
description: >-
The Validate BPAY Payment API validates a set of one or more BPAY
payment data records to ensure that all attributes are valid, and that
the payment will be accepted for processing.
*Authentication Required - The endpoint must always be invoked by a user with a valid access token.*
**For scenarios to test in the 'Try this API' feature, refer to the Testing Guide [here.](/guides)**
**Try our API products using Postman, refer to the Postman collections [here.](/postman)**
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationPayment'
description: The payment details that are being submitted for validation.
required: true
responses:
"200":
description: Response to indicate the request was successfully processed. Note
that the order of the results should not be relied on to co-relate
the response with the original request, rather use the "tid"
included in the response for the co-relation. Note that the response
is considered a 'success' (error code 200) regardless of whether the
included payments are validated successfully or not.
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationResult'
"400":
description: >-
The request was invalid and the data supplied did not match the
expected formats. Possible errors include:
* DUPLICATE_TIDS - Duplicate identifiers found.
* TID_MISSING - An identifier is required.
* PAYMENTS_MISSING - Payment details are required.
content:
application/json:
schema:
$ref: '#/components/schemas/ClientError'
"401":
description: User is not authenticated.
content:
"application/json":
schema:
$ref: '#/components/schemas/Error'
example:
error: UNAUTHENTICATED
errorDescription: User is not authenticated.
"403":
description: User is authenticated but does not have sufficient permissions to
use this service.
content:
"application/json":
schema:
$ref: '#/components/schemas/Error'
example:
error: ACCESS_DENIED
errorDescription: User is authenticated but does not have sufficient
permissions to use this service.
"413":
description: The number of payment records exceeds the limit.
content:
"application/json":
schema:
$ref: '#/components/schemas/ClientError'
examples:
response:
value:
endPoint: /payments/v1/validatepayments
httpMethod: POST
errorSummary:
- errCode: MAX_PAYMENTS_EXCEEDED
errMessage: The number of payment records exceeds the limit for
your file type.
errField: 'null'
"500":
description: Unexpected error was encountered processing the request.
security:
- bpay_auth:
- read:validate-payment
components:
securitySchemes:
bpay_auth:
type: oauth2
flows:
clientCredentials:
tokenUrl: https://sandbox.api.bpaygroup.com.au/oauth/token
scopes:
read:validate-payment: BPAY payment validation API
schemas:
ValidationPayment:
type: object
properties:
payments:
type: array
items:
$ref: '#/components/schemas/PaymentItem'
ValidationResult:
type: object
description: A response to a request to validate single or multiple BPAY
payments
properties:
validationResults:
description: The results of the validation of the payment/s.
type: array
items:
$ref: '#/components/schemas/ValidatonResultItem'
Error:
type: object
properties:
error:
description: "The error code identifying the error type."
type: "string"
errorDescription:
description: "Indicates the description error."
type: "string"
ClientErrorItem:
type: object
properties:
errCode:
description: The error code identifying the format error.
type: string
example: "DUPLICATE_TIDS"
errField:
description: Identifies the field that caused the error. For
example "CRN".
type: string
example: "tid"
errMessage:
description: Indicates the description error. For example invalid
field format.
type: string
example: "Duplicate identifiers found."
ClientError:
type: object
properties:
endpoint:
description: The end point application that made the API call
type: string
example: "/payments/v1/validatepayments"
httpmethod:
description: HTTP method used for request (GET, POST, etc)
type: string
example: "POST"
errorSummary:
description: Summary of the error returned. The end point must make use
of the error code, error message and field to form a
meaningful response to the end user.
items:
$ref: '#/components/schemas/ClientErrorItem'
type: array
ValidatonResultItem:
type: object
description: Represents the outcome of validating the details of an
individual BPAY payment
properties:
tid:
description: Unique identifier for the BPAY payment being
validated. This corresponds to the "tid" supplied in
the corresponding PaymentValidationRequest.
type: string
example: "1"
validationSummary:
description: The collection of batch payments to be included in
the batch file. Note that a maximum of 200 payments
can be processed in a single request.
type: array
items:
$ref: '#/components/schemas/ValidationSummary'
ValidationSummary:
type: object
description: Error code and description for an invalid payment
detail request.
properties:
validationResponseCode:
description: >
Returns a response code that indicates the
result of validation. A value of '0' indicates
that the transaction passed validation. Any
non-zero value indicates that the payment
failed validation.
* 107
* 109
* 113
* 115
* 116
* 122
* 128
* 130
* 131
* 132
* 133
* 140
type: string
validationErrorDescription:
description: >-
If the transaction did not pass validation,
then a human readable description of the
validation error will be provided.
* 107 - The BPAY Biller code is not valid. Please check your entry and try again.
* 109 - The Payment Method is not accepted by the Biller. Please enter a different Payment Method.
* 113 - The BPAY Customer Reference Number you have entered is not valid. Please check your entry and try again.
* 115 - The amount entered is not numeric. Please remove any special characters such as ',' or '$' and try again.
* 116 - The amount entered is less than the minimum amount accepted by the Biller. Please enter a higher amount and try again.
* 122 - The Payment Date is invalid. Please enter a different date.
* 128 - The Settlement Date is invalid. Please enter a different date.
* 130 - The length of the supplied BPAY Customer Reference Number is not valid for this Biller. Please check your entry and try again.
* 131 - The amount you have entered is not correct or not accepted by the Biller. Please check your entry and try again.
* 132 - Only numeric values are allowed for BPAY Customer Reference Number. Please remove any special characters such as '-' or '_' or spaces and try again.
* 133 - The Payment Date you have entered is not correct or has past the date accepted by the Biller. Please check your entry and try again.
* 140 - The amount entered is more than the maximum amount accepted by the Biller. Please enter a lower amount and try again.
type: string
example:
validationResponseCode: "107"
validationErrorDescription: The BPAY Biller code is not valid. Please check
your entry and try again.
PaymentItem:
type: object
required:
- tid
- payment
properties:
tid:
type: string
description: A unique identifier for the BPAY payment item being
validated. This will be returned back in the response
and can be used for correlating the response and
request object elements. It must therefore be unique
for each payment detail within the request.
example: "1"
payment:
$ref: '#/components/schemas/Payment'
Payment:
type: object
properties:
billerCode:
description: The Biller Code for the biller that will
receive the payment. The Biller Code must
be a numeric value with 3 to 10 digits.
type: string
example: "565572"
crn:
description: The Customer Reference Number (CRN) for the
payment. The CRN must contain numeric values
but should be treated as a string as it may
have leading zeros (which must be preserved).
The CRN must contain between 2 and 20 digits.
type: string
example: "651234567890123"
amount:
description: The amount of the payment.
type: number
format: float
example: 234.83
settlementDate:
description: >-
The date that the proposed payment will be
submitted by the Financial Institution to BPAY
for inclusion in settlement. Financial
Institutions determine their own cut-off times
each day for accepting payments to be
submitted on the same day (typically between
3pm-6pm). Please consult with your Financial
Institution regarding their BPAY Payment
settlement cut-off time. The format of the
date should be as defined by full-date in
[RFC3339](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14).
For example, consider the case where your Financial Institution’s cut-off time is 4pm.
* If you are submitting the transaction to your Financial Institution at 3pm, you are submitting before their cut-off and so it will be submitted to BPAY on the same day for inclusion in settlement. You should use the current day’s date as the ‘Settlement Date’ when calling the API.
* If you are submitting the transaction to your Financial Institution at 6pm, you are submitting after their cut-off and so it will be submitted to BPAY on the following day for inclusion in settlement. You should use the next day’s date as the ‘Settlement Date’ when calling the API
type: string
format: date
paymentMethod:
type: string
description: The type of payments methods accepted by the
biller. For PaymentValidationRequest, values
can be "001" (Debit), "101" (Visa), "201"
(MasterCard), "301" (Other Credit Card). For
GenerateBatchFileRequest, paymentMethod must
be "001". Note that Billers are able to define
the account types from which they will accept
payment. The account type will be used to
validate that the biller accepts payments from
that type of account.
enum:
- "001"
- "101"
- "201"
- "301"
paymentDate:
type: string
format: date
description: "The date that the proposed payment will be\
\ submitted by the customer to their Financial Institution\
\ for processing. Note that in the case of Batch Payers,\
\ this will need to correspond to the date that the Batch\
\ Payer submits the transaction to their FI for processing,\
\ not when the Batch Payer initially accepted it from\
\ their customer. This is used in those cases where the\
\ CRN includes an embedded due date. In such cases, the\
\ payment fails validation if the supplied Payment Date\
\ is after the Expiry Date extracted from the CRN. This\
\ field is optional and if its not provided will default\
\ to the current date. The format of the date should be\
\ as defined by full-date in [RFC3339](https://xml2rfc.tools.ietf.org/public/rfc/html/rfc3339.html#anchor14)."
required:
- billerCode
- crn
- amount
- settlementDate
- paymentMethod