OpenAPI Specification
openapi: 3.0.0
info:
title: TabaPay APIs 3D Secure User API
description: TabaPay Resource and Service Operations
version: 1.0.0
license:
name: All rights reserved
servers:
- url: https://{FQDN}:{PORT}
description: TabaPay APIs
variables:
FQDN:
default: FQDN
description: Contact [TabaPay Support](https://tabapay.zendesk.com/hc/en-us/requests/new) for the Fully Qualified Domain Name you should be using.
PORT:
default: PORT
description: Ensure you have the capability to access the PORT TabaPay specifies in your credentials file.
security:
- bearerAuth: []
tags:
- name: User
description: This resource represents a Client's User.
paths:
/v2/clients/{ClientID}/users:
post:
tags:
- User
summary: Create User
description: "Creates a user for the client/subclient.\n\n Request to enable at [TabaPay Support](https://tabapay.zendesk.com/hc/en-us/requests/new#/) or [help@tabapay.com](mailto:help@tabapay.com)"
operationId: createuser
parameters:
- $ref: '#/components/parameters/ClientID'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/userCreate'
examples:
Individual:
value:
referenceID: 1234UniqueRefID
type: NaturalPerson
name:
individual:
first: Samwise
middle: Sam
last: Gamgee
email: user@example.com
phone:
countryCode: '1'
number: '5555555555'
address:
line1: 123 Street
city: San Francisco
state: CA
zipcode: '94103'
country: '840'
dateOfBirth: '19990131'
identification:
type: SSN
number: '243353678'
Business:
value:
referenceID: 1kdev05126
type: LLC
name:
company:
legal: PaymentsLLC
dba: Easy Pay
address:
line1: 123 Street
city: San Francisco
state: CA
zipcode: '94103'
identification:
type: EIN
number: '243353678'
businessOwners:
businessOwner1:
identification:
type: SSN
number: '243353679'
firstName: Name
lastName: SirName
dateOfBirth: '19990131'
businessOwner2:
identification:
type: SSN
number: '243353660'
firstName: Name2
lastName: SurName
dateOfBirth: '19990130'
email: user@example.com
dateOfFormation: '19990131'
responses:
'200':
description: User created.
content:
application/json:
schema:
$ref: '#/components/schemas/createUserResponse'
example:
SC: 200
EC: '0'
userID: 22CharacterTabaPayID12
'207':
description: One or more failures occurred while processing the Request.
content:
application/json:
schema:
$ref: '#/components/schemas/apiResponseSCEC'
/v2/clients/{ClientID}/users/{UserID}:
delete:
tags:
- User
summary: Delete User
description: Deletes (soft delete) an existing user.
operationId: deleteuser
parameters:
- $ref: '#/components/parameters/ClientID'
- $ref: '#/components/parameters/UserID'
responses:
'200':
description: User deleted.
content:
application/json:
schema:
$ref: '#/components/schemas/apiResponseSCEC'
'404':
description: User not found.
content:
application/json:
schema:
$ref: '#/components/schemas/apiResponseSCECEM'
get:
tags:
- User
summary: Retrieve User
description: Retrieves a user by userID.
operationId: retrieveuser
parameters:
- $ref: '#/components/parameters/ClientID'
- $ref: '#/components/parameters/UserID'
- $ref: '#/components/parameters/ReferenceIDQuery'
responses:
'200':
description: User retrieved.
content:
application/json:
schema:
$ref: '#/components/schemas/retrieveUserResponse'
example:
SC: 200
EC: '0'
userID: 22CharacterTabaPayID12
referenceID: 1kdev41526
type: NaturalPerson
name:
individual:
first: Samwise
last: Gamgee
middle: Sam
address:
country: '840'
line1: 123 Street
city: San Francisco
zipcode: '94103'
state: CA
email: user@example.com
phone:
countryCode: '1'
number: '5555555555'
identification:
type: SSN
number: '243353678'
dateOfBirth: '19990131'
'404':
description: User not found.
content:
application/json:
schema:
$ref: '#/components/schemas/apiResponseSCECEM'
put:
tags:
- User
summary: Update User
description: Updates an existing user.
operationId: updateuser
parameters:
- $ref: '#/components/parameters/ClientID'
- $ref: '#/components/parameters/UserID'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/userUpdate'
required: true
responses:
'200':
description: User updated.
content:
application/json:
schema:
$ref: '#/components/schemas/createUserResponse'
components:
schemas:
businessOwner:
type: object
description: Additional individuals that own at least 25% of the entity.
required:
- firstName
- lastName
- dateOfBirth
properties:
firstName:
type: string
description: First name
middleName:
type: string
description: Middle name
lastName:
type: string
description: Last name
dateOfBirth:
type: string
description: 'Date of birth with the format: YYYYMMDD. Owner must be at least 18 years old.'
tpReferenceID:
type: string
description: Client-defined reference identifier
minLength: 1
maxLength: 15
pattern: ^[A-Za-z0-9._-]+$
address:
type: object
description: Address
required:
- line1
- city
- state
- zipcode
properties:
line1:
$ref: '#/components/schemas/line1'
line2:
$ref: '#/components/schemas/line2'
city:
$ref: '#/components/schemas/city'
state:
$ref: '#/components/schemas/state'
zipcode:
$ref: '#/components/schemas/zipcode'
country:
$ref: '#/components/schemas/country'
apiResponseSCECEM:
type: object
properties:
SC:
$ref: '#/components/schemas/SC'
EC:
$ref: '#/components/schemas/EC'
EM:
$ref: '#/components/schemas/EM'
city:
type: string
description: City
pattern: ^[ a-zA-Z0-9_-]+$
tpDateYYYYMMDD:
type: string
description: Date in YYYYMMDD format
pattern: ^[0-9]{8}$
example: '19990131'
userNameCompany:
type: object
required:
- legal
properties:
legal:
type: string
description: Legal name
dba:
type: string
description: Doing Business As (DBA)
line1:
type: string
description: Address Line 1
pattern: ^[ a-zA-Z0-9._-]+$
apiResponseSCEC:
type: object
properties:
SC:
$ref: '#/components/schemas/SC'
EC:
$ref: '#/components/schemas/EC'
SC:
type: integer
description: '[HTTP Status Code](https://developers.tabapay.com/reference/http-status-codes#/)'
createUserResponse:
type: object
properties:
SC:
$ref: '#/components/schemas/SC'
EC:
$ref: '#/components/schemas/EC'
EM:
$ref: '#/components/schemas/EM'
userID:
$ref: '#/components/schemas/tpUserID'
userCreate:
type: object
required:
- referenceID
- type
- name
- identification
properties:
referenceID:
$ref: '#/components/schemas/tpReferenceID'
type:
type: string
enum:
- LLC
- LLP
- C-Corp
- S-Corp
- SoleProprietor
- Nonprofit
- Charitable
- NaturalPerson
- Other
name:
$ref: '#/components/schemas/userName'
email:
type: string
format: email
description: Valid Email Address
phone:
$ref: '#/components/schemas/phone'
address:
$ref: '#/components/schemas/address'
dateOfBirth:
$ref: '#/components/schemas/tpDateYYYYMMDD'
dateOfFormation:
$ref: '#/components/schemas/tpDateYYYYMMDD'
identification:
$ref: '#/components/schemas/userIdentification'
businessOwners:
type: object
description: 'Individuals that own at least 25% of the entity, or the largest owner if no one owns at least 25%.
**Note: If you plan to add/remove/modify any owner information in the future, you will need re-submit all existing information to the update SubClient API. It is recommend that you store the owner information for this purpose.**'
required:
- businessOwner1
properties:
businessOwner1:
allOf:
- $ref: '#/components/schemas/businessOwner'
- properties:
identification:
$ref: '#/components/schemas/userIdentification'
businessOwner2:
allOf:
- $ref: '#/components/schemas/businessOwner'
- properties:
identification:
$ref: '#/components/schemas/userIdentification'
businessOwner3:
allOf:
- $ref: '#/components/schemas/businessOwner'
- properties:
identification:
$ref: '#/components/schemas/userIdentification'
businessOwner4:
allOf:
- $ref: '#/components/schemas/businessOwner'
- properties:
identification:
$ref: '#/components/schemas/userIdentification'
userName:
type: object
properties:
individual:
$ref: '#/components/schemas/userNameIndividual'
company:
$ref: '#/components/schemas/userNameCompany'
description: For type NaturalPerson use name.individual; otherwise use name.company.
userUpdate:
type: object
properties:
referenceID:
$ref: '#/components/schemas/tpReferenceID'
type:
type: string
enum:
- LLC
- LLP
- C-Corp
- S-Corp
- SoleProprietor
- Nonprofit
- Charitable
- NaturalPerson
- Other
name:
$ref: '#/components/schemas/userName'
email:
type: string
format: email
description: Valid Email Address
phone:
$ref: '#/components/schemas/phone'
address:
$ref: '#/components/schemas/address'
dateOfBirth:
$ref: '#/components/schemas/tpDateYYYYMMDD'
dateOfFormation:
$ref: '#/components/schemas/tpDateYYYYMMDD'
identification:
$ref: '#/components/schemas/userIdentification'
beneficialOwners:
type: object
description: beneficialOwner1..beneficialOwner4 objects
description: Partial update; only supplied fields are updated.
userNameIndividual:
type: object
required:
- first
- last
properties:
first:
type: string
description: First name
middle:
type: string
description: Middle name
last:
type: string
description: Last name
suffix:
type: string
maxLength: 50
zipcode:
type: string
description: 'Zip Code
If `country` is `840`, `zipcode` must be 5 or 9 digits.
If country is `124`, `zipcode` must be in the *A1A 1A1* format.
Zip codes from other countries will not be checked.'
pattern: ^[ a-zA-Z0-9_-]+$
userIdentification:
type: object
required:
- type
- number
properties:
type:
type: string
enum:
- SSN
- GovernmentID
- Passport
- EIN
number:
type: string
description: A unique ID number issued by a government or organization.
EM:
type: string
description: Short description of the error if an error occurred.
state:
type: string
description: 'State Code
[State Code](https://developers.tabapay.com/reference/us-state-codes#/) must be a valid 2-character code if `country` is [840](https://developers.tabapay.com/reference/country-codes#/) or [Canadian 2-char code](https://developers.tabapay.com/reference/canadian-province-codes#/) if [124](https://developers.tabapay.com/reference/country-codes#/).'
pattern: ^[ a-zA-Z0-9_-]+$
country:
type: string
description: '[Country Code](https://developers.tabapay.com/reference/country-codes#/)
*Optional. Default is `840`*'
pattern: ^[0-9]{3}$
example: '840'
phone:
type: object
required:
- number
description: Phone *object*
properties:
countryCode:
type: string
description: '1-3 digit Country Calling Code
*Optional.* Default is `1`.'
pattern: ^[0-9]{3}$
example: '1'
number:
type: string
description: 'Phone Number.
For phone numbers with `countryCode` equal to `1` (or blank), provide a 10-digit phone number. For all `countryCodes`, other than `1`, a 4-14 digit phone number is accepted.'
pattern: ^[0-9]{4,14}$
example: '5555555555'
EC:
type: string
description: Internal Error Code. This is used to help TabaPay team members trace an error.
tpUserID:
type: string
description: TabaPay user identifier
pattern: ^[A-Za-z0-9]{22}$
line2:
type: string
description: 'Address Line 2
*Optional*'
pattern: ^[ a-zA-Z0-9._-]+$
retrieveUserResponse:
type: object
properties:
SC:
$ref: '#/components/schemas/SC'
EC:
$ref: '#/components/schemas/EC'
EM:
$ref: '#/components/schemas/EM'
userID:
$ref: '#/components/schemas/tpUserID'
referenceID:
$ref: '#/components/schemas/tpReferenceID'
type:
type: string
enum:
- LLC
- LLP
- C-Corp
- S-Corp
- SoleProprietor
- Nonprofit
- Charitable
- NaturalPerson
- Other
name:
$ref: '#/components/schemas/userName'
address:
$ref: '#/components/schemas/address'
email:
type: string
format: email
description: Email Address
phone:
$ref: '#/components/schemas/phone'
identification:
$ref: '#/components/schemas/userIdentification'
dateOfBirth:
$ref: '#/components/schemas/tpDateYYYYMMDD'
dateOfFormation:
$ref: '#/components/schemas/tpDateYYYYMMDD'
businessOwners:
type: object
kyc:
type: string
description: "Lists the status of the verification request\n\nValid Values:\n - CREATED\n - PENDING\n - COMPLETED\n - FAILED\n - UNKNOWN"
parameters:
UserID:
name: UserID
in: path
description: 22-character UserID returned from Create User.
required: true
style: simple
explode: false
schema:
type: string
ReferenceIDQuery:
name: referenceID
in: query
description: Reference ID fallback lookup.
required: false
schema:
type: string
ClientID:
name: ClientID
in: path
description: 22-character <<glossary:ClientID>>. Ask [TabaPay Support](https://tabapay.zendesk.com/hc/en-us/requests/new) if you need to specify a <<glossary:SubClientID>>.
required: true
style: simple
explode: false
schema:
type: string
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
custom-header:
type: apiKey
name: Authorization
in: header