PayFacHub Rest API
The base url for the production api is: https://virtserver.swaggerhub.com/PayfacHub6/PayfacHub/1.0.0
All API endpoints return an ApiResponse object as their content. The payload section of the ApiResponse will contain the different data type objects or arrays returned from the call.
Our API is rate limited at 75 calls per minute or 7000 per day to protect against attacks. To get further information on our rate limits or to discuss increasing these limits for your project please contact support@paidyet.com.
Authentication Endpoint
Login – [BASE_URL]/login
PayFacHub uses bearer tokens to authenticate each API call. To obtain your bearer token for use in the API call simply pass in the subdomian and key to the login endpoint.
method | request content | payload content | description |
POST | Authentication | Bearer token object | Authenticate with your PaidYET key and subdomain to retrieve a bearer token. The bearer token will expire periodically and you will need to obtain a new one. |
{
"email": "user@example.com",
"password": "string",
"submerchant_id": "string"
}
Example Login Response
{
"access_token": "string",
"token_type": "string"
}
Submerchant Applications
This section will show you how to search for applications by ID, display a list of applications, or create a new submerchant application.
Applications by ID – [BASE_URL]/applications/{applicationId}
method | request content | payload content | description |
GET | NA | Submerchant Application Object | Returns a single application given the application ID passed to the endpoint |
Example Submerchant Application Object Response
{
"submerchant": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payfac_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"legal_company_name": "string",
"company_address": "string",
"company_city": "string",
"company_state": "string",
"company_zip": "03202",
"company_ein": "233-65-3620",
"ssn": "618-59-4959",
"company_website": "example.com",
"have_dba": true,
"company_type": "string",
"company_description": "string",
"company_mcc": "string",
"year_established": 2017,
"average_monthly_volume": 30000,
"max_ticket_amount": 300000,
"average_monthly_tickets": 50000
},
"contact": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"first_name": "string",
"last_name": "string",
"email": "user@example.com",
"phone": "215 872-5438"
},
"banking": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"account_name": "string",
"account_type": "string",
"routing": "440571432",
"account": "310011045"
},
"owners": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"legal_fname": "string",
"legal_lname": "string",
"legal_address": "string",
"address_type": "string",
"legal_city": "string",
"legal_state": "string",
"legal_zip": "85515",
"legal_phone": "512 383-6342",
"legal_email": "user@example.com",
"dob": "2022-04-28",
"ssn": "345-34-9490",
"percent_owner": "08.46%",
"control": true
}
]
}
Applications – [BASE_URL]/applications
method | request content | payload content | description |
GET | NA | Submerchant Application Objects | Returns a JSON list of applications for the Payfac associated with the user |
Example Response
[
{
"submerchant": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payfac_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"legal_company_name": "string",
"company_address": "string",
"company_city": "string",
"company_state": "string",
"company_zip": "33267",
"company_ein": "648-34-1649",
"ssn": "971-03-9401",
"company_website": "example.com",
"have_dba": true,
"company_type": "string",
"company_description": "string",
"company_mcc": "string",
"year_established": 2017,
"average_monthly_volume": 30000,
"max_ticket_amount": 300000,
"average_monthly_tickets": 50000
},
"contact": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"first_name": "string",
"last_name": "string",
"email": "user@example.com",
"phone": "581 277-4188"
},
"banking": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"account_name": "string",
"account_type": "string",
"routing": "347775457",
"account": "693339318"
},
"owners": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"legal_fname": "string",
"legal_lname": "string",
"legal_address": "string",
"address_type": "string",
"legal_city": "string",
"legal_state": "string",
"legal_zip": "15246",
"legal_phone": "728 468-5732",
"legal_email": "user@example.com",
"dob": "2022-04-28",
"ssn": "861-73-3732",
"percent_owner": "41.35%",
"control": true
}
]
}
]
Create Submerchant Application – [BASE_URL]/applications
method | request content | payload content | description |
POST | Submerchant Application | Submerchant Application Object | Creates a submerchant application and returns application object |
Example Response
{
"submerchant": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payfac_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"legal_company_name": "string",
"company_address": "string",
"company_city": "string",
"company_state": "string",
"company_zip": "03202",
"company_ein": "233-65-3620",
"ssn": "618-59-4959",
"company_website": "example.com",
"have_dba": true,
"company_type": "string",
"company_description": "string",
"company_mcc": "string",
"year_established": 2017,
"average_monthly_volume": 30000,
"max_ticket_amount": 300000,
"average_monthly_tickets": 50000
},
"contact": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"first_name": "string",
"last_name": "string",
"email": "user@example.com",
"phone": "215 872-5438"
},
"banking": {
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"account_name": "string",
"account_type": "string",
"routing": "440571432",
"account": "310011045"
},
"owners": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"legal_fname": "string",
"legal_lname": "string",
"legal_address": "string",
"address_type": "string",
"legal_city": "string",
"legal_state": "string",
"legal_zip": "85515",
"legal_phone": "512 383-6342",
"legal_email": "user@example.com",
"dob": "2022-04-28",
"ssn": "345-34-9490",
"percent_owner": "08.46%",
"control": true
}
]
}
Submerchants
This section will show you how to search for submerchants by ID and display a list of submerchants.
Submerchants by ID – [BASE_URL]/submerchants/{submerchantId}
method | request content | payload content | description |
GET | NA | JSON Submerchant Object | Returns a JSON object containing a single submerchant given the submerchant ID passed to the endpoint |
Example Response
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payfac_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"partner_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subdomain": "string",
"api_key": "stringstringstringstringstringstringstri",
"mid": 1234,
"status": true,
"cards_accepted": true,
"payments_active": true,
"batch_days": 3
}
Submerchants – [BASE_URL]/submerchants
method | request content | payload content | description |
GET | NA | One Submerchant Object | Returns a JSON list of submerchants for the Payfac associated with the user |
Example Response
[
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"payfac_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"partner_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"subdomain": "string",
"api_key": "stringstringstringstringstringstringstri",
"mid": 1234,
"status": true,
"cards_accepted": true,
"payments_active": true,
"batch_days": 3
}
]
Transactions
This section will show you how to search for transactions by ID, display a list of transactions,and create a new transaction record.
Transactions by ID – [BASE_URL]/transactions/{transactionId}
method | request content | payload content | description |
GET | NA | JSON transaction object | Returns a single transaction given the transaction ID passed to the endpoint |
Example Response
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"submerchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"batch_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"external_batch_id": "52693",
"amount": 10545,
"first_name": "string",
"last_name": "string",
"description": "string",
"ip": "059-4-9-19",
"email": "user@example.com",
"mobile_phone": "557 024-0928",
"address": "string",
"city": "string",
"state": "string",
"zip": "09392",
"deposit_status": "string"
}
Transactions – [BASE_URL]/transactions
method | request content | payload content | description |
GET | NA | JSON transaction object | Returns a JSON list of transactions for the Payfac associated with the user |
Example Response
[
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"submerchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"batch_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"external_batch_id": "85836",
"amount": 10545,
"first_name": "string",
"last_name": "string",
"description": "string",
"ip": "406-2-9-68",
"email": "user@example.com",
"mobile_phone": "534 682-5342",
"address": "string",
"city": "string",
"state": "string",
"zip": "09825",
"deposit_status": "string"
}
]
Create Transaction – [BASE_URL]/transactions
method | request content | payload content | description |
POST | Transaction | JSON transaction object | Creates a transaction record and returns a transaction object |
Example Transaction Request
{
"submerchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"batch_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"external_batch_id": "72208",
"amount": 10545,
"first_name": "string",
"last_name": "string",
"description": "string",
"ip": "818-2-7-89",
"email": "user@example.com",
"mobile_phone": "395 340-9464",
"address": "string",
"city": "string",
"state": "string",
"zip": "73832",
"deposit_status": "string",
"fees": [
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"type": "string",
"amount": 1000
}
]
}
Example Response
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"submerchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"batch_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"external_batch_id": "22190",
"amount": 10545,
"first_name": "string",
"last_name": "string",
"description": "string",
"ip": "073-1-6-69",
"email": "user@example.com",
"mobile_phone": "137 150-5127",
"address": "string",
"city": "string",
"state": "string",
"zip": "63001",
"deposit_status": "string"
}
Batches
This section will who you how to search for batches by ID, display a list of batches, and create a new batch record.
Batches by ID – [BASE_URL]/batches/{batchId}
method | request content | payload content | description |
GET | NA | JSON batch object | Returns a JSON object containing a single batch given the batch ID passed to the endpoint |
Example Response
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"external_batch_id": "42477",
"merchant_batch_ref_num": "string",
"submerchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount_charged": 20000,
"amount_refunded": 2000,
"total_fees": 10000,
"total_credits": 2000,
"date_to_settle": "2022-04-28",
"date_settled": "2022-04-28",
"transaction_count": 100
}
Batches – [BASE_URL]/batches
method | request content | payload content | description |
GET | NA | JSON batch object | Returns a JSON list of batches for the Payfac associated with the user |
Example Response
[
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"external_batch_id": "27997",
"merchant_batch_ref_num": "string",
"submerchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount_charged": 20000,
"amount_refunded": 2000,
"total_fees": 10000,
"total_credits": 2000,
"date_to_settle": "2022-04-28",
"date_settled": "2022-04-28",
"transaction_count": 100
}
]
Example Response
Create Batch – [BASE_URL]/batches
method | request content | payload content | description |
POST | Batch | JSON Batch object | Creates a batch and returns a batch object |
Example Request
{
"external_batch_id": "string",
"merchant_batchRefNum": "string",
"submerchant_id": "string",
"amount_charged": 0,
"amount_refunded": 0,
"num_transactions": 0,
"fees": [
{
"transactionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"description": "string",
"fee_rate": 0,
"amount": 0
}
]
}
Example Response
{
"id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"status": "string",
"external_batch_id": "61447",
"merchant_batch_ref_num": "string",
"submerchant_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"amount_charged": 20000,
"amount_refunded": 2000,
"total_fees": 10000,
"total_credits": 2000,
"date_to_settle": "2022-04-28",
"date_settled": "2022-04-28",
"transaction_count": 100
}
Data Objects
The following are the object types passed to and from the API. In some cases – particularly when sending to the API, only certain properties are necessary. These properties are denoted in the tables below.
Application
property | type | description |
application | array | an array containing the submerchant, contact, banking, and owners objects. |
Submerchant
property | type | description |
id | string | Submerchant Application ID |
payfac_id | string | Payfac ID |
legal_company_name | string | |
company_address | string | |
company_city | integer | |
company_state | string | |
company_zip | string | pattern: ^\d{5}$ |
company_ein | string | pattern: ^\d{3}-\d{2}-\d{4}$ |
ssn | string | pattern: ^\d{3}-\d{2}-\d{4}$ |
company_website | string | format: hostname |
have_dba | boolean | |
company_type | string | |
company_description | string | |
company_mcc | string | |
year_established | integer | minimum: 2000 maximum: 2017 |
average_monthly_volume | integer | default: 30000 |
max_ticket_amount | integer | default: 300000 |
average_monthly_tickets | integer | default: 50000 |
Contact
property | type | description |
id | string | read-only unique identifier |
first_name | string | |
last_name | string | |
string | format: email | |
phone | string | pattern: ^\d{3} \d{3}-\d{4}$ |
Banking
property | type | description |
id | string | read-only unique identifier |
account_name | string | |
account_type | string | |
routing | string | pattern: ^\d{9}$ |
account | string | pattern: ^\d{9}$ |
Owners
property | type | description |
id | string | read-only unique identifier |
legal_fname | string | |
legal_lname | string | |
legal_address | string | |
address_type | string | |
legal_city | string | format: state |
legal_state | string | |
legal_zip | string | pattern: ^\d{5}$ |
legal_phone | string | pattern: ^\d{3} \d{3}-\d{4}$ |
legal_email | string | format: email |
dob | string | format: date |
ssn | string | |
percent_owner | string | pattern: ^\d{2}\.\d{2}%$ |
control | boolean |
Transaction
property | type | description |
id | string | read-only unique identifier |
submerchant_id | string | submerchant identifier |
batch_id | string | batch identifier |
external_batch_id | string | pattern: ^\d{5}$ |
amount | integer | |
first_name | string | |
last_name | string | |
description | string | |
ip | bool | pattern: ^\d{3}-\d{1}-\d{1}-\d{2} |
string | format: email | |
mobile_phone | string | pattern: ^\d{3} \d{3}-\d{4}$ |
address | string | |
city | string | |
state | string | |
zip | string | pattern: ^\d{5}$ |
deposit_status | string |
Batch
property | type | description |
id | string | read-only unique identifier |
status | string | submerchant identifier |
external_batch_id | string | pattern: ^\d{5}$ |
merchant_batch_ref_num | string | |
submerchant_id | string | |
amount_charged | integer | minimum: 20000 |
amount_refunded | integer | minimum: 2000 |
total_fees | integer | minimum: 0 maximum: 10000 |
total_credits | integer | minumum: 0 maximum: 2000 |
date_to_settle | string | format: date |
date_settled | string | format: date |
transaction_count | integer | minimum: 1 maximum: 100 |