· 5 years ago · Feb 07, 2021, 03:08 PM
1swagger: '2.0'
2info:
3 version: 0.1.8
4 title: uCom Customer Services
5 description: Services related to uCom Customer Profile Management
6tags:
7 - name: customers
8 description: Operations and details about customers which are defined as the end-user of the application.
9host: int.api.firstdata.com
10basePath: /ucom
11schemes:
12 - https
13consumes:
14 - application/json
15produces:
16 - application/json
17paths:
18 /v1/customers:
19 post:
20 operationId: createCustomer
21 tags:
22 - customers
23 summary: 'Create a Customer Profile, a.k.a. ''register a customer'''
24 description: Registering a customer in the uCom system results in a unique identifier 'fdCustomerId' that is used in subsequent operations like vaulting a payment account and making mobile payments.
25 parameters:
26 - $ref: '#/parameters/ApiKeyParam'
27 - $ref: '#/parameters/TimestampParam'
28 - $ref: '#/parameters/AuthorizationParam'
29 - $ref: '#/parameters/ClientTokenParam'
30 - $ref: '#/parameters/ClientRequestIdParam'
31 - $ref: '#/parameters/AcceptLanguageParam'
32 - name: payload
33 description: Customer profile information
34 in: body
35 required: true
36 schema:
37 $ref: '#/definitions/CustomerRequest'
38 responses:
39 '201':
40 $ref: '#/responses/Created'
41 '400':
42 $ref: '#/responses/BadRequest'
43 '401':
44 $ref: '#/responses/Unauthorized'
45 '409':
46 $ref: '#/responses/Conflict'
47 '500':
48 $ref: '#/responses/ServerError'
49 '/v1/customers/{fdCustomerId}':
50 get:
51 operationId: getCustomer
52 tags:
53 - customers
54 summary: Read a Customer Profile
55 description: Fetch the details of a customer providing the fdCustomerId.
56 parameters:
57 - $ref: '#/parameters/ApiKeyParam'
58 - $ref: '#/parameters/TimestampParam'
59 - $ref: '#/parameters/AuthorizationParam'
60 - $ref: '#/parameters/ClientTokenParam'
61 - $ref: '#/parameters/FdCustomerIdParam'
62 - $ref: '#/parameters/AcceptLanguageParam'
63 responses:
64 '200':
65 $ref: '#/responses/OK'
66 '400':
67 $ref: '#/responses/BadRequest'
68 '401':
69 $ref: '#/responses/Unauthorized'
70 '404':
71 $ref: '#/responses/NotFound'
72 '500':
73 $ref: '#/responses/ServerError'
74 patch:
75 operationId: updateCustomer
76 tags:
77 - customers
78 summary: Update a Customer Profile
79 description: Update the details in a Customer Profile providing the fdCustomerId.
80 parameters:
81 - $ref: '#/parameters/ApiKeyParam'
82 - $ref: '#/parameters/TimestampParam'
83 - $ref: '#/parameters/AuthorizationParam'
84 - $ref: '#/parameters/ClientTokenParam'
85 - $ref: '#/parameters/FdCustomerIdParam'
86 - $ref: '#/parameters/AcceptLanguageParam'
87 - name: payload
88 in: body
89 description: Customer Profile information
90 required: true
91 schema:
92 $ref: '#/definitions/CustomerRequest'
93 responses:
94 '204':
95 $ref: '#/responses/NoContent'
96 '400':
97 $ref: '#/responses/BadRequest'
98 '401':
99 $ref: '#/responses/Unauthorized'
100 '404':
101 $ref: '#/responses/NotFound'
102 '409':
103 $ref: '#/responses/Conflict'
104 '500':
105 $ref: '#/responses/ServerError'
106 delete:
107 operationId: deleteCustomer
108 tags:
109 - customers
110 summary: Delete a Customer Profile
111 description: Delete a customer profile from uCom system by providing the fdCustomerId.
112 parameters:
113 - $ref: '#/parameters/ApiKeyParam'
114 - $ref: '#/parameters/TimestampParam'
115 - $ref: '#/parameters/AuthorizationParam'
116 - $ref: '#/parameters/ClientTokenParam'
117 - $ref: '#/parameters/FdCustomerIdParam'
118 - $ref: '#/parameters/AcceptLanguageParam'
119 responses:
120 '204':
121 $ref: '#/responses/NoContent'
122 '400':
123 $ref: '#/responses/BadRequest'
124 '401':
125 $ref: '#/responses/Unauthorized'
126 '404':
127 $ref: '#/responses/NotFound'
128 '500':
129 $ref: '#/responses/ServerError'
130definitions:
131 CustomerRequest:
132 title: Customer Request
133 type: object
134 properties:
135 customer:
136 $ref: '#/definitions/User'
137 deviceInfo:
138 $ref: '#/definitions/DeviceInfo'
139 Address:
140 description: A physical mailing address for this user.
141 type: object
142 properties:
143 type:
144 description: 'Canonical type values of "work", "home", and "other".'
145 type: string
146 streetAddress:
147 description: 'The full street address component, which may include house number, street name, P.O. box, and multi-line extended street address information.'
148 type: string
149 locality:
150 description: The city or locality component.
151 type: string
152 region:
153 description: The state or region component.
154 type: string
155 postalCode:
156 description: The zip code or postal code component.
157 type: string
158 country:
159 description: 'The country name component. When specified, the value MUST be in ISO 3166-1 "alpha-2" code format; e.g., the United States and Sweden are "US" and "SE", respectively.'
160 type: string
161 formatted:
162 description: 'The full mailing address, formatted for display or use with a mailing label.'
163 type: string
164 primary:
165 description: Indicates if this is the default address for the associated resource. It only has meaning when used in a set or array of addresses.
166 type: boolean
167 example:
168 type: work
169 streetAddress: 100 Universal City Plaza
170 locality: Hollywood
171 region: CA
172 postalCode: '91608'
173 country: US
174 formatted: |-
175 100 Universal City Plaza
176 Hollywood, CA 91608 US
177 primary: true
178 Email:
179 description: Email address for the user.
180 type: object
181 properties:
182 type:
183 description: 'The "type" sub-attribute is used to provide a classification meaningful to the (human) user. The user interface should encourage the use of basic values of "work", "home", and "other" and MAY allow additional type values to be used at the discretion of the service client.'
184 type: string
185 value:
186 description: The value SHOULD be specified according to RFC5321.
187 type: string
188 primary:
189 description: Defines if this entry is to be used as the primary or default for the user.
190 type: boolean
191 default: false
192 example:
193 value: bjensen@example.com
194 type: work
195 primary: true
196 Group:
197 description: Group
198 type: object
199 properties:
200 value:
201 description: The id of the group.
202 type: string
203 href:
204 description: The URI of the corresponding "Group" resources to which the user belongs.
205 type: string
206 display:
207 description: The common name of the group.
208 type: string
209 example:
210 value: e9e30dba-f08f-4109-8486-d5c6a331660a
211 href: 'https://example.com/v2/Groups/e9e30dba-f08f-4109-8486'
212 display: Tour Guides
213 Link:
214 description: Model to communicate linked resources.
215 type: object
216 required:
217 - href
218 - rel
219 properties:
220 href:
221 description: URL to linked resource.
222 type: string
223 format: uri
224 rel:
225 description: Defines the type of link relationship to current resource.
226 type: string
227 enum:
228 - current.page
229 - previous.page
230 - next.page
231 - self
232 example: self
233 method:
234 description: Defines the HTTP method for the given href.
235 type: string
236 default: GET
237 example: GET
238 id:
239 description: Identifier to the resource.
240 type: string
241 example: 415e5cf6bfdb11e8a355529269fb1459
242 IMS:
243 description: Instant messaging address for the user.
244 type: object
245 properties:
246 value:
247 description: 'A shortened version one of the following values - aim, gtalk, icq, xmpp, msn, skype, qq, yahoo, or other. This will change with popularity of various applicatiions at any time.'
248 type: string
249 type:
250 type: string
251 primary:
252 description: Flag to indicate primary account
253 type: boolean
254 default: false
255 example:
256 value: someaimhandle
257 type: aim
258 PersonName:
259 description: The components of the user's name.
260 type: object
261 properties:
262 formatted:
263 description: 'The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g.,"Ms. Barbara Jane Jensen, III").'
264 type: string
265 familyName:
266 description: 'The family name of the User, or last name in most Western languages (e.g., "Jensen" given the full name "Ms. Barbara Jane Jensen, III").'
267 type: string
268 givenName:
269 description: 'The given name of the User, or first name in most Western languages (e.g., "Barbara" given the full name "Ms. Barbara Jane Jensen, III").'
270 type: string
271 middleName:
272 description: 'The middle name(s) of the User (e.g., "Jane" given the full name "Ms. Barbara Jane Jensen, III").'
273 type: string
274 honorificPrefix:
275 description: 'The honorific prefix(es) of the User, or title in most Western languages (e.g., "Ms." given the full name "Ms. Barbara Jane Jensen, III").'
276 type: string
277 honorificSuffix:
278 description: 'The honorific suffix(es) of the User, or suffix in most Western languages (e.g., "III" given the full name "Ms. Barbara Jane Jensen, III").'
279 type: string
280 example:
281 formatted: Ms. Barbara J Jensen III
282 familyName: Jensen
283 givenName: Barbara
284 middleName: Jane
285 honorificPrefix: Ms.
286 honorificSuffix: III
287 Phone:
288 description: Phone number for the user.
289 type: object
290 properties:
291 value:
292 description: 'The value SHOULD be specified according to the format defined in RFC3966, e.g., ''tel:+1-201-555-0123''.'
293 type: string
294 type:
295 description: 'Often has typical values of "work", "home", "mobile", "fax", "pager", and "other" and MAY allow more types to be defined by the service client.'
296 type: string
297 primary:
298 description: Defines if this entry is to be used as the primary or default for the user.
299 type: boolean
300 default: false
301 example:
302 value: 555-555-5555
303 type: work
304 Photo:
305 description: 'A URI that is a uniform resource locator (as defined in Section 1.1.3 of RFC3986) that points to a resource location representing the user''s image. The resource MUST be a file (e.g., a GIF, JPEG, or PNG image file) rather than a web page containing an image.'
306 type: object
307 properties:
308 value:
309 description: URI pointing to user's image file.
310 type: string
311 type:
312 description: Defines the following canonical values to represent popular photo sizes - "photo" and "thumbnail".
313 type: string
314 example:
315 value: 'https://photos.example.com/profilephoto/72930000000Ccne/F'
316 type: thumbnail
317 ThreeDSecure:
318 description: Details of ThreeDSecure transaction used to process the challege flow
319 type: object
320 properties:
321 transactionId:
322 description: Transaction id generated on the server
323 type: string
324 example: 292bb6b886fc4446894f878b7e32bd5e
325 transactionStatus:
326 type: string
327 description: Transactions status of 3DS server
328 example: C
329 transactionStatusReason:
330 type: string
331 description: Reason for the transaction status
332 challengeResponse:
333 type: string
334 example: ewogIC
335 challengeIndicator:
336 type: string
337 example: '01 = No preference 02 = No challenge requested 03 = Challenge requested: 3DS Requestor Preference 04 = Challenge requested: Mandate'
338 dsTransactionId:
339 type: string
340 example: 292bb6b886fc4446894f878b7e32bd5e
341 acsTransactionId:
342 type: string
343 example: 292bb6b886fc4446894f878b7e32bd5e
344 serverTransactionId:
345 type: string
346 example: 292bb6b886fc4446894f878b7e32bd5e
347 acsReferenceNumber:
348 type: string
349 example: 292bb6b886fc4446894f878b7e32bd5e
350 acsSignedContent:
351 type: string
352 example: 292bb6b88....6fc4446894f878b7e32bd5e
353 cardType:
354 $ref: '#/definitions/CreditCardType'
355 challengeRequest:
356 type: string
357 example: ewogICAiYW.......MjJjMGVjIgp9
358 acsUrl:
359 type: string
360 example: 'https://test.modirum.com/dstests/ACSEmu2'
361 iframeContent:
362 type: string
363 example: <iframe></iframe>
364 termUrl:
365 type: string
366 example: 'https://mydomain/3dstest?transactionId=292bb6b886fc4446894f878b7e32bd5e'
367 isThreeDSMethodCompleted:
368 type: boolean
369 example: true
370 expiryDateTime:
371 description: 3DS challenge transaction expiry date time.
372 type: string
373 readOnly: true
374 format: date-time
375 example: '2020-01-01T16:06:05Z'
376 User:
377 description: 'User resource as defined by the System for Cross-domain Identity Management (SCIM). For more info see http://www.simplecloud.info'
378 type: object
379 required:
380 - externalId
381 properties:
382 id:
383 description: Unique identifier for a customer profile registered with uCom.
384 type: string
385 readOnly: true
386 example: fdCustomerId
387 externalId:
388 description: 'A String that is an identifier for the resource as defined by the provisioning client. While the server does not enforce uniqueness, it is assumed that the value''s uniqueness is controlled by the client setting the value.'
389 type: string
390 example: 123abc456def890ghi098jkl765mno
391 userName:
392 description: 'A service provider''s unique identifier for the user, typically used by the user to directly authenticate to the service provider.'
393 type: string
394 example: bjensen@example.com
395 name:
396 $ref: '#/definitions/PersonName'
397 displayName:
398 description: 'The name of the user, suitable for display to end-users.'
399 type: string
400 example: Babs Jensen
401 nickName:
402 description: 'The casual way to address the user in real life, e.g., "Bob" or "Bobby" instead of "Robert".'
403 type: string
404 example: Babs
405 profileUrl:
406 description: 'A URI that is a uniform resource locator (as defined in Section 1.1.3 of [RFC3986]) and that points to a location representing the user''s online profile (e.g., a web page)'
407 type: string
408 example: 'https://login.example.com/bjensen'
409 emails:
410 type: array
411 items:
412 $ref: '#/definitions/Email'
413 addresses:
414 type: array
415 items:
416 $ref: '#/definitions/Address'
417 phoneNumbers:
418 type: array
419 items:
420 $ref: '#/definitions/Phone'
421 ims:
422 type: array
423 items:
424 $ref: '#/definitions/IMS'
425 photos:
426 type: array
427 items:
428 $ref: '#/definitions/Photo'
429 userType:
430 description: Used to identify the relationship between the organization and the user.
431 type: string
432 example: Employee
433 title:
434 description: 'The user''s title, such as "Vice President".'
435 type: string
436 example: Tour Guide
437 preferredLanguage:
438 description: Indicates the user's preferred written or spoken languages and is generally used for selecting a localized user interface.
439 type: string
440 example: en-US
441 locale:
442 description: 'Used to indicate the User''s default location for purposes of localizing such items as currency, date time format, or numerical representations.'
443 type: string
444 example: en-US
445 timezone:
446 description: The User's time zone
447 type: string
448 example: America/Los_Angeles
449 active:
450 description: A Boolean value indicating the user's administrative status. The definitive meaning of this attribute is determined by the service provider.
451 type: boolean
452 example: true
453 password:
454 description: 'This attribute is intended to be used as a means to set, replace, or compare (i.e., filter for equality) a password.'
455 type: string
456 example: some-hashed-value
457 groups:
458 description: 'A list of groups to which the user belongs, either through direct membership, through nested groups, or dynamically calculated.'
459 type: array
460 items:
461 $ref: '#/definitions/Group'
462 dateCreated:
463 description: 'Date created time in Internet Date/Time format - yyyy-MM-dd''T''HH:mm:ss''Z'''
464 type: string
465 format: date-time
466 example: '2016-04-16T16:06:05Z'
467 dateModified:
468 description: 'Date modified time in Internet Date/Time format - yyyy-MM-dd''T''HH:mm:ss''Z'''
469 type: string
470 format: date-time
471 example: '2016-04-16T16:06:05Z'
472 DeviceInfo:
473 description: Request origin device details
474 type: object
475 required:
476 - id
477 - kind
478 properties:
479 id:
480 description: 'Unique Id for the device. Value should not contain line feeds, carriage returns, tabs, leading or trailing spaces, or multiple spaces.'
481 type: string
482 example: 537edec8-d33e-4ee8-93a7-b9f61876950c
483 kind:
484 description: 'Possible values are mobile, wearable, automobile, embedded,desktop, other.'
485 type: string
486 example: mobile
487 details:
488 title: deviceData
489 description: Device data information from multiple providers.
490 type: array
491 minItems: 0
492 uniqueItems: true
493 items:
494 description: Collection of device data
495 type: object
496 properties:
497 provider:
498 description: Identifies the provider of the data and is often used when decrypting data on the server.
499 type: string
500 example: InAuth
501 dataCapture:
502 description: Device data captured as a bundle and transmitted as an encrypted and/or specifically formated string.
503 type: object
504 properties:
505 rawData:
506 description: Device capture - raw data blob
507 type: string
508 example: aaaaaXREUVZGRlFY...aMV
509 dataEventId:
510 description: Event identifier used map state on the server.
511 type: string
512 example: BB8E4E92...Fz1E063113
513 captureTime:
514 description: 'Device data capture time in Internet Date/Time format - yyyy-MM-dd''T''HH:mm:ss''Z'''
515 type: string
516 format: date-time
517 example: '2016-04-16T16:06:05Z'
518 dataStatic:
519 description: Device static details
520 type: object
521 properties:
522 os:
523 description: Device OS name
524 type: string
525 example: Android 5.1.1 Lollipop
526 osVersion:
527 description: Device OS version
528 type: string
529 example: 5.1.1 Lollipop
530 model:
531 description: Device model
532 type: string
533 example: XT1540
534 type:
535 description: Device type
536 type: string
537 example: Moto G
538 dataDynamic:
539 description: Device location details
540 type: object
541 properties:
542 latitude:
543 description: Device position - latitude at the time of the data event
544 type: string
545 example: 13.0827 N
546 longitude:
547 description: Device position - longitude at the time of the data event
548 type: string
549 example: 80.2707 E
550 ipAddress:
551 description: IP address
552 type: string
553 example: 172.27.37.221
554 captureTime:
555 description: 'Device data capture time in Internet Date/Time format - yyyy-MM-dd''T''HH:mm:ss''Z'''
556 type: string
557 format: date-time
558 example: '2016-04-16T16:06:05Z'
559 dataApplication:
560 description: Mobile application specific data
561 type: object
562 properties:
563 version:
564 description: Mobile application version.
565 type: string
566 format: sting
567 example: 1.0.0
568 name:
569 description: Mobile application name.
570 type: string
571 format: sting
572 example: aplication-name
573 country:
574 description: Mobile application store country.
575 type: string
576 format: sting
577 example: US
578 additionalInfo:
579 type: array
580 minItems: 0
581 items:
582 $ref: '#/definitions/NVP'
583 uniqueItems: true
584 example:
585 id: 537edec8-d33e-4ee8-93a7-b9f61876950c
586 kind: mobile
587 details:
588 - provider: InAuth
589 dataCapture:
590 rawData: aaaaaXREUVZGRlFY...aMV
591 dataEventId: BB8E4E92...Fz1E063113
592 captureTime: '2016-04-16T16:06:05Z'
593 dataStatic:
594 os: Android 5.1.1 Lollipop
595 osVersion: 5.1.1 Lollipop
596 model: XYX-1
597 Type: Moto G
598 dataDynamic:
599 latitude: 13.0827 N
600 longitude: 80.2707 E
601 ipAddress: 172.27.37.221
602 captureTime: '2016-04-16T16:06:05Z'
603 additionalInfo:
604 - name: some-key
605 value: some-value
606 NVP:
607 title: Name and Value pair.
608 type: object
609 properties:
610 name:
611 type: string
612 value:
613 type: string
614 valueAsList:
615 type: array
616 minItems: 0
617 items:
618 type: string
619 Error:
620 description: Model for error messaging
621 type: object
622 properties:
623 code:
624 type: string
625 description: Uniquely identifies an error condition. Client applications need to read and handle errors based on this.
626 message:
627 type: string
628 description: A generic description of the error condition.
629 category:
630 type: string
631 description: The resource associated with the error condition.
632 developerInfo:
633 type: object
634 description: Information that needs to be understood by the client developers and should not be interpreted for application processing.
635 properties:
636 developerMessage:
637 type: string
638 description: An elaborative description of the error description.
639 moreInfo:
640 type: string
641 description: Link to the error in Developer page.
642 fieldError:
643 description: Detailed information about message format errors.
644 type: array
645 items:
646 properties:
647 field:
648 description: The property or attribute associated with the error
649 type: string
650 message:
651 description: Information specific to a property or attribute.
652 type: string
653 hostExtraInfo:
654 type: array
655 minItems: 0
656 items:
657 $ref: '#/definitions/NVP'
658 uniqueItems: true
659 threeDSecureInfo:
660 $ref: '#/definitions/ThreeDSecure'
661 _links:
662 type: array
663 items:
664 $ref: '#/definitions/Link'
665 example:
666 code: '40000'
667 message: Example Error
668 category: example
669 developerInfo:
670 developerMessage: Invalid Message format in request payload
671 moreInfo: 'https://www.example.com/errors/40000'
672 fieldError:
673 - field: example id
674 message: exampleId is mandatory
675 CreditCardType:
676 title: Credit Card Type
677 description: Indicates the type of credit account association
678 type: string
679 enum:
680 - AMEX
681 - DISCOVER
682 - MASTERCARD
683 - PLCC
684 - VISA
685responses:
686 Created:
687 description: Resource created
688 headers:
689 Location:
690 type: string
691 description: Location of newly created resource.
692 schema:
693 $ref: '#/definitions/User'
694 OK:
695 description: OK
696 schema:
697 $ref: '#/definitions/User'
698 NoContent:
699 description: The request succeeded but there’s really nothing to show.
700 BadRequest:
701 description: Bad request
702 schema:
703 $ref: '#/definitions/Error'
704 Unauthorized:
705 description: Unauthorized
706 NotFound:
707 description: Not Found - The requested resource doesn't exist.
708 schema:
709 $ref: '#/definitions/Error'
710 Conflict:
711 description: Conflict - The requested operation conflicts with the current state of the identified resource.
712 schema:
713 $ref: '#/definitions/Error'
714 ServerError:
715 description: An unexpected server error occured.
716 schema:
717 $ref: '#/definitions/Error'
718parameters:
719 AcceptLanguageParam:
720 name: Accept-Language
721 description: 'The Accept-Language header contains information about the language preference of a user. This HTTP header is useful to multilingual sites for deciding the best language to serve to the client. i.e en-US,fr-CA'
722 in: header
723 type: string
724 ApiKeyParam:
725 name: Api-Key
726 description: An API key is a string value passed by a client app to the API proxies. The key uniquely identifies the client app.
727 in: header
728 required: true
729 type: string
730 AuthorizationParam:
731 name: Authorization
732 description: 'Authorization information for the request. Format- `HMAC {hmacToken}`'
733 in: header
734 required: true
735 type: string
736 ClientTokenParam:
737 name: Client-Token
738 description: 'Used to pass the original client OAuth token information given in a client-credentials flow. This field is only used when the server is making the request and needs to link the transaction to a specific client. Format- `Bearer {access_token}`'
739 in: header
740 type: string
741 ClientRequestIdParam:
742 name: Client-Request-Id
743 description: 'Contains a unique ID generated by the client that can be used for enforcing idempotency on POST actions. POSTs are inherently non-idempotent and submitting the exact same request multiple times would create duplicate resources. Note:- Omitting this header increases the risk of duplicate transactions, which for payments could cost the client issues like double-billing.'
744 in: header
745 required: true
746 type: string
747 FdCustomerIdParam:
748 name: fdCustomerId
749 description: Unique identifier for a customer profile registered with uCom.
750 in: path
751 required: true
752 type: string
753 TimestampParam:
754 name: Timestamp
755 description: Epoch timestamp in the request initiating syste
756 in: header
757 required: true
758 type: string
759