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.
Example Login Request 
{
  "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

methodrequest contentpayload contentdescription
GETNASubmerchant Application ObjectsReturns 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

methodrequest contentpayload contentdescription
POSTSubmerchant ApplicationSubmerchant Application ObjectCreates 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}

methodrequest contentpayload contentdescription
GETNAJSON Submerchant ObjectReturns 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

methodrequest contentpayload contentdescription
GETNAOne Submerchant ObjectReturns 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}

methodrequest contentpayload contentdescription
GETNAJSON transaction objectReturns 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

methodrequest contentpayload contentdescription
GETNAJSON transaction objectReturns 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

methodrequest contentpayload contentdescription
POSTTransactionJSON transaction objectCreates 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}

methodrequest contentpayload contentdescription
GETNAJSON batch objectReturns 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

methodrequest contentpayload contentdescription
GETNAJSON batch objectReturns 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

methodrequest contentpayload contentdescription
POSTBatchJSON Batch objectCreates 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

propertytypedescription
idstringSubmerchant Application ID
payfac_idstringPayfac ID
legal_company_namestring 
company_addressstring 
company_cityinteger 
company_statestring 
company_zipstring pattern: ^\d{5}$
company_einstring pattern: ^\d{3}-\d{2}-\d{4}$
ssnstringpattern: ^\d{3}-\d{2}-\d{4}$
company_websitestringformat: hostname
have_dbaboolean 
company_typestring 
company_descriptionstring 
company_mccstring 
year_establishedintegerminimum: 2000 maximum: 2017
average_monthly_volumeinteger default: 30000
max_ticket_amountinteger default: 300000
average_monthly_ticketsinteger default: 50000

Contact

property type description
id string read-only unique identifier
first_name string
last_name string
email string format: email
phone string  pattern: ^\d{3} \d{3}-\d{4}$

Banking

propertytypedescription
idstringread-only unique identifier
account_namestring 
account_typestring 
routingstringpattern: ^\d{9}$
accountstring pattern: ^\d{9}$

Owners

propertytypedescription
idstringread-only unique identifier
legal_fnamestring 
legal_lnamestring 
legal_addressstring 
address_typestring 
legal_citystringformat: state
legal_statestring 
legal_zipstringpattern: ^\d{5}$
legal_phonestringpattern: ^\d{3} \d{3}-\d{4}$
legal_emailstringformat: email
dobstringformat: date
ssnstring 
percent_ownerstringpattern: ^\d{2}\.\d{2}%$
controlboolean 

Transaction

propertytypedescription
idstringread-only unique identifier
submerchant_idstringsubmerchant identifier
batch_idstringbatch identifier
external_batch_idstringpattern: ^\d{5}$
amountinteger 
first_namestring 
last_namestring 
descriptionstring 
ipboolpattern: ^\d{3}-\d{1}-\d{1}-\d{2}
emailstringformat: email
mobile_phonestringpattern: ^\d{3} \d{3}-\d{4}$
addressstring 
citystring 
statestring 
zipstringpattern: ^\d{5}$
deposit_statusstring 

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