logo

JustiFi API Documentation (v1)

Download OpenAPI specification:Download

E-mail: api-development@justifi.ai Terms of Service

Introduction

The JustiFi API is a REST-based payment processing API. Our API has predictable, resource-oriented URLs, accepts JSON, and returns JSON. We use HTTP status codes and supply detailed error codes whenever possible. We'll provide you with both a test and live account with which to use our API. Each account will have its own API key, and the key you use to authenticate each request will determine whether to use your test or live account. When you use your test account, it won't affect your live data or move any real money.

Getting Started

To process a payment with JustiFi, follow these steps


Get Your Accounts

Our customer onboarding team will work with you to create your test and live accounts. For platforms, our team will also guide you through setting up your sub accounts onboarding. Once you're up and running, you'll have access to the JustiFi API as well as the admin features at https://app.justifi.ai where you can see your account overview, payments, payouts, issue refunds, etc.


Get Your API Keys

Once your test and live accounts have been created, you'll have access to generate your API keys in the Developer Tools section of the app. You'll need a test key and a live key. Each key will provide you with a client id and a client secret, which you'll use to authenticate your API requests. Requests authenticated with your test key will use your test account; requests authenticated with your live key will use your live account. Make sure to store your client secrets somewhere secure (like a password manager) because this is the only time they'll display in the UI.

Additionally, we can provide access to a sandbox environment upon request.


Authenticate With JustiFi

Example OAuth Client Credentials Grant Request
curl -X POST https://api.justifi.ai/oauth/token \
    -H 'Content-Type: application/json' \
    --data '{"client_id":"[your client id]","client_secret":"[your client secret]"}'
Example Authenticated Response
{
  "access_token": "... this will be a very long string and is valid for 24 hours"
}
Example Authenticated Request
curl -X POST https://api.justifi.ai/v1/payments \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Content-Type: application/json'
    -H 'Idempotency-Key: a-unique-string-for-the-transaction'

JustiFi uses the OAuth Client Credentials authentication flow. To access, use your JustiFi client id and client secret to POST to https://api.justifi.ai/oauth/token. These are valid for 24 hours. The test key is prepended with test_ and the live key is prepended with live_.

Next, take the access token in that response and pass it in all subsequent requests as the Authorization header.

This token is valid for 24 hours, so be sure to handle a 401 - Unauthorized response by getting a new access token via the client credentials grant API.

Idempotent Requests

Example Request with Idempotency-Key Header
curl -X POST https://api.justifi.ai/v1/payments \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'
    -H 'Idempotency-Key: a-unique-string-for-the-transaction'

In order to guarantee that payments and other important transactions are only ever processed a single time, we leverage the Idempotency-Key header in our payments APIs. This means that you MUST provide an Idempotency-Key header along with your request, otherwise you'll receive an error. If a second request with same idempotent key is processed concurrently, it will result in a 409 error instead of double processing.

If these requests fail with a network timeout or a 5XX error, they should be retried with the same exact parameters. Once they're fully successful, you'll receive a 2XX response. If you POST the same request and Idempotency-Key again, you'll get the response you originally received back. If you receive a 4XX error, do not retry the request, unless the response code is a 409.

If you try the same Idempotency-Key with different parameters, your request will error and won't be possible to process. The Idempotency-Key header is only meant for a single transaction; it's there to protect against processing the same exact thing more than once. Once the parameters change, a request is considered distinct from the original request.

You may use any string to identify your Idempotency-Key; we generally recommend using a generated uuid, but you may use any unique string.

Pagination

Example Paginated Request
curl -X GET https://api.justifi.ai/v1/payments?limit=25&after_cursor=token-from-page-info \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'
Example Paginated Response
{
    "id": null,
    "type": "array",
    "data":[
        { "id":"py_438xBom2Drh55kE1WfyGLg",
          "amount": 1000,
          ... additional response attributes based on resource schema
        }
    ],
    "page_info": {
      "has_previous": false,
      "has_next": true,
      "start_cursor": "WyIyMDIyLTAxLTExIDE1OjI3OjM2LjAyNzc3MDAwMCIsImNhNjQwMTk1LTEzYzMtNGJlZi1hZWQyLTU3ZjA1MzhjNjNiYSJd",
      "end_cursor": "WyIyMDIyLTAxLTExIDEyOjU5OjQwLjAwNTkxODAwMCIsImQ0Njg5MGE2LTJhZDItNGZjNy1iNzdkLWFiNmE3MDJhNTg3YSJd"
    }
}

All top-level API resources have support for bulk fetches via array API methods. JustiFi uses cursor-based pagination, which supports limit, before_cursor and after_cursor. Each response will have a page_info object that contains the has_next and has_previous fields, which tells you if there are more items before or after the current page. The page_info object also includes start_cursor and end_cursor values which can be used in conjunction with before_cursor and after_cursor to retrieve items from the API one page at a time.

Standard array API Request Parameters

Parameter Description
limit The number of resources to retrieve.
type: integer
default: 25
minimum: 1
maximum: 100
after_cursor Token to fetch the next page of a list.
type: string
before_cursor Token to fetch the previous page of a list.
type: string

The after_cursor/before_cursor parameter determines which page of results will be returned. If after_cursor is the encoded id of the last record in the collection has_next will be false and you'll get an empty array response. If before_cursor is the encoded id of the first record in the collection has_previous will be false and you'll get an empty array response.

The limit parameter determines the maximum number of results included in each response. If there are fewer records available than the limit value, the response will include all available records. The maximum value allowed is 100 with a default value of 25. If the limit value is an invalid type, the default value of 25 is used.

Standard API Response Structure

All of our responses are contained in the same envelope, for arrays the id field will be null and the object will be an array.

Attribute Description
id The id of the object returned. Will be null for arrays.
type: string
default: "a uuid"
type The type of object returned.
type: string
default: "array"
data The resource OR an array of the requested resources.
type: array | object
Notes: May be an empty array [] if no resources are available.
page_info The object containing pagination information.
type: object
Notes: Contains has_previous, has_next, start_cursor and end_cursor

Testing

Use these card numbers to test successful transactions as well as various error scenarios. Make sure to authenticate your requests using your test API key (these cards won't work for live payments).

Successful Test Cards

Number Brand CVC Date
4242424242424242 Visa Any 3 digits Any future date
4000056655665556 Visa (debit) Any 3 digits Any future date
5555555555554444 Mastercard Any 3 digits Any future date
2223003122003222 Mastercard (2-series) Any 3 digits Any future date
5200828282828210 Mastercard (debit) Any 3 digits Any future date
5105105105105100 Mastercard (prepaid) Any 3 digits Any future date
378282246310005 American Express Any 4 digits Any future date
371449635398431 American Express Any 4 digits Any future date
6011000990139424 Discover Any 3 digits Any future date
3056930009020004 Diners Club Any 3 digits Any future date
36227206271667 Diners Club (14 digit card) Any 3 digits Any future date
3566002020360505 JCB Any 3 digits Any future date
6200000000000005 UnionPay Any 3 digits Any future date

Declined Test Cards

Number Description
4000000000000101 If a CVC number is provided, the cvc_check fails.
4000000000000341 Tokenizing this card succeeds, but attempts to make a payment fail.
4000000000000002 Payment is declined with a card_declined code.
4000000000009995 Payment is declined with a card_declined code. The decline_code attribute is insufficient_funds.
4000000000009987 Payment is declined with a card_declined code. The decline_code attribute is lost_card.
4000000000009979 Payment is declined with a card_declined code. The decline_code attribute is stolen_card.
4000000000000069 Payment is declined with an expired_card code.
4000000000000127 Payment is declined with an invalid_cvc code.
4000000000000119 Payment is declined with a gateway_error code.
4242424242424241 Payment is declined with an card_number_invalid code as the card number fails the Luhn check.

Successful Bank Account (ACH)

Routing Number Account Number
110000000 000123456789

Declined Bank Accounts (ACH)

Routing Number Account Number Payment Error
110000000 000222222227 Insufficient Funds
110000000 000333333335 The account doesn't support debits
110000000 000111111113 The account is closed
110000000 000111111116 The account doesn't exist

HTTP Errors

The JustiFi API may return a number of standard HTTP errors due to invalid requests. Some common errors are described below to help you build with JustiFi.

Bad Request

The server cannot process the request. This error is most likely due to malformed request syntax.

  • code: 400
  • status: Bad Request

Unauthorized

Similar to a 403 Forbidden, but specifically when authentication is provided and has failed, or has not been provided. This error is most likely due to not including your API key in the request header.

  • code: 401
  • status: Unauthorized

Payment Required

There was an error processing the payment. This response is returned when errors occur while tokenizing the payment method, such as an invalid cvc or an expiration date in the past. This can also occur when making a payment and the card is declined. In that case, the error message will provide more specific information about why the request was declined.

  • code: 402
  • status: Payment Required

Forbidden

The request was valid, but you are unable to execute the request. This error is most likely due to the API key that was used not having the necessary permissions, or attempting a prohibited action such as creating a duplicate record where one already exists.

  • code: 403
  • status: Forbidden

Not Found

The requested resource could not be found, but may be available in the future. This error is most likely due to requesting a resource by id that doesn't exist. You'll want to double check that you're referencing the correct id and that it exists on your account.

  • code: 404
  • status: Not Found

Concurrent Request Error

The request has an identical Idempotency-Key header for another request which either failed OR is processing at the same time. You can retry these requests without risk of double processing.

  • code: 409
  • status: Conflict

Unprocessable Entity

The request was well-formed, but was unable to be processed due to semantic errors. This error is most likely due to including invalid data in POST, PATCH, and PUT requests. Double check the request documentation to make sure you're supplying the required attributes, and that the attribute types are correct.

  • code: 422
  • status: Unprocessable Entity

Internal Server Error

An internal server error occurred due to an unexpected condition. This error is most likely due to an issue with our servers.

  • code: 500
  • status: Internal Server Error

Error Codes

Many of our 4XX errors will provide an error code in addition to their HTTP status. Here is a list of our error codes and a brief description of the error to provide more context when applicable.

Error Code Description
acct_last_four_required Missing required parameter: acct_last_four
amount_below_minimum Amount must be greater than 50
amount_must_be_an_integer Amount must be an integer
amount_required Missing required parameter: amount
amount_too_large The specified amount is greater than the maximum amount allowed. Use a lower amount and try again.
amount_too_small The specified amount is less than the minimum amount allowed. Use a higher amount and try again.
application_fee_rate_id_required Missing required parameter: application_fee_rate_id
application_fee_required Missing required parameter: application_fee
brand_required Missing required parameter: brand
capture_strategy_invalid Format is invalid for parameter: capture_strategy
card_decline_rate_limit_exceeded This card has been declined too many times. You can try to charge this card again after 24 hours. We suggest reaching out to your customer to make sure they have entered all of their information correctly and that there are no issues with their card.
card_declined The card has been declined. When a card is declined, the error returned also includes the decline_code attribute with the reason why the card was declined.
card_name_required Missing required parameter: card_name
card_number_invalid Format is invalid for parameter: card_number
card_number_required Missing required parameter: card_number
charge_expired_for_capture The charge cannot be captured as the authorization has expired. Auth and capture charges must be captured within 7 days.
country_invalid Format is invalid for parameter: country
currency_invalid Format is invalid for parameter: currency
currency_required Missing required parameter: currency
customer_id_required Missing required parameter: customer_id
customer_max_payment_methods The maximum number of PaymentMethods for this Customer has been reached. Either detach some PaymentMethods from this Customer or proceed with a different Customer.
email_invalid The email address is invalid (e.g., not properly formatted). Check that the email address is properly formatted and only includes allowed characters.
email_required Missing required parameter: email
expired_card The card has expired. Check the expiration date or use a different card.
gateway_account_id_required Missing required parameter: gateway_account_id
gateway_authentication_error The payment network returned an authentication error
gateway_error There was an issue processing your payment with the gateway. Please try again later.
gateway_idempotency_error The gateway detected concurrent requests using this idempotency key
gateway_rate_limit_error Too many requests hit the API too quickly. We recommend an exponential back-off of your requests.
gateway_ref_id_required Missing required parameter: gateway_ref_id
gateway_timeout_error There was a timeout with the gateway, we recommend retrying using the Should-Retry header
idempotency_concurrent_request We detected concurrent requests using this idempotency key
idempotency_key_required Idempotency-Key is a required header
idempotency_params_mismatch The request parameters do not match those of a previous request using this idempotency key
idempotency_request_in_progress Another request using this idempotency key is currently in progress
internal_server_error An unexpected error has occurred. JustiFi engineers will investigate the error and contact you if any remediation steps are necessary.
invalid_address The card’s address is incorrect. Check the card’s address or use a different card.
invalid_card_number The card number is incorrect. Check the card number or use a different card.
invalid_characters This value provided to the field contains characters that are unsupported by the field
invalid_charge_amount The specified amount is invalid. The charge amount must be a positive integer in the smallest currency unit, and not exceed the minimum or maximum amount.
invalid_cvc The card’s security code is incorrect. Check the card’s security code or use a different card.
invalid_expiry_month The card’s expiration month is incorrect. Check the expiration date or use a different card.
invalid_expiry_year The card’s expiration year is incorrect. Check the expiration date or use a different card.
invalid_zip_code The card’s postal code is incorrect. Check the card’s postal code or use a different card.
month_invalid Format is invalid for parameter: month
not_authenticated Not authenticated
not_authorized Not authorized
parameter_missing Missing required parameter
payment_fully_refunded The refund cannot be processed because the associated payment is fully refunded
payment_intent_cannot_be_captured Payment Intent status is '%{status}' so it cannot be captured
payment_intent_not_found Payment intent not found
payment_intent_unexpected_state You cannot provide a new payment method to a PaymentIntent when it has a status of requires_capture, canceled, or succeeded
payment_method_not_found Payment method not found
payment_method_required Missing required parameter: payment_method
payment_method_token_required Missing required parameter: payment_method_token
payment_outside_refund_window The refund cannot be processed because the associated payment is outside the refund window
postal_code_invalid Format is invalid for parameter: postal_code
refund_exceeds_amount_available The refund cannot be processed because the refund amount exceeds the available funds
refund_exceeds_payment_amount The refund cannot be processed because the refund amount exceeds the associated payment amount
refund_reason_invalid Refund reason must be one of the following: %{Refund::REASONS}
resource_not_found Resource not found
state_invalid Format is invalid for parameter: state
token_already_used The token provided has already been used. You must create a new token before you can retry this request.
token_in_use The token provided is currently being used in another request. This occurs if your integration is making duplicate requests simultaneously.
transfer_required Missing required parameter: transfer
unexpected_parameter Unexpected parameter for this request
verification_invalid Format is invalid for parameter: verification
year_invalid Format is invalid for parameter: year

API Credentials

Generate Access Token

To get an access token, post your client_id and client_secret. The request responds with an access token, which is valid for 24 hours. Pass the token as the Authorization header with Bearer appended before the token, e.g. Bearer {access_token}.

Request
Request Body schema: application/json
client_id
string

the client id for your (live or test) account

client_secret
string

the client secret for your (live or test) account

Responses
200

An access token has been granted

post/oauth/token
Request samples
application/json
{
  • "client_id": "test_clientId",
  • "client_secret": "test_clientSecret"
}
Response samples
application/json
{
  • "access_token": "string"
}

Sub Accounts

Sub Accounts are the representation of your platform's customers in JustiFi. Payments are processed through sub accounts, each of which is associated with your platform account. To gain approval for payment processing, each sub account must submit the required onboarding information. You may send this to us through either our hosted onboarding or the API, and you'll be able to monitor each sub account's onboarding status along the way.

Status Description
created this sub account has been created (via Sub Accounts API), but we haven't received their onboarding entry yet
submitted we've received this sub account's onboarding entry (via hosted onboarding or API) and we're reviewing their information
information_needed we reviewed this sub account's onboarding entry and found an issue; we need more information before we can enable this account
enabled this sub account is approved to process payments note: test accounts are automatically enabled
rejected this sub account didn't pass approval, so they won't be able to process payments
disabled this sub account was previously approved, but has since become ineligible to process payments (e.g. due to fraud)
archived this sub account has been archived; they won't be able to process payments (but their record will remain for historical reasons)

Create a Sub Account

Create a JustiFi account for your customer, so they can process payments (once approved by JustiFi). The sub account will be created as part of your platform. If you use your test credentials, the sub account you create will have one account with the account_type of test. If you use your live credentials, the sub account you create will have two accounts -- one with the account_type of test and another with the account_type of live. This allows you to perform test operations on your real accounts by using their test account. When viewing the data payload for any sub account, you can reference the related_accounts attribute to get the test_account_id and live_account_id (if present) for that sub account.

Request
header Parameters
Authorization
required
string

the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)

Example: Bearer {access_token}
Request Body schema: application/json
name
required
string

name for the sub account
note: the name must be unique in your platform

Responses
201

Sub account was created successfully

post/sub_accounts
Request samples
application/json
{
  • "name": "Sub account name"
}
Response samples
application/json
{
  • "id": 1,
  • "type": "sub_account",
  • "data": {
    },
  • "page_info": null
}

List Sub Accounts

List the sub accounts for your platform. This endpoint supports pagination. Note: By default, all sub accounts which are not archived will be returned. To list archived sub accounts, use the optional status parameter set to archived

Request
query Parameters
status
string

Return accounts with specific status

Enum: "created" "submitted" "information_needed" "rejected" "enabled" "disabled" "archived"
Example: status=archived
header Parameters
Authorization
required
string

the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)

Example: Bearer {access_token}
Responses
200

Successfully list sub accounts

get/sub_accounts
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Sub Account
Get information about a sub account.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a sub account


get/sub_accounts/{id}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "sub_account",
  • "data": {
    },
  • "page_info": null
}
Seller Accounts
Note: the term seller account has been deprecated and will be removed in future versions. Please use sub account instead


Create a Seller Account
Create a JustiFi account for your customer, so they can process payments (once approved by JustiFi). The seller will be created as part of your platform. If you use your test credentials, the seller you create will have one account with the account_type of test. If you use your live credentials, the seller you create will have two accounts -- one with the account_type of test and another with the account_type of live. This allows you to perform test operations on your real sellers by using their test account. When viewing the data payload for any seller account, you can reference the related_accounts attribute to get the test_account_id and live_account_id (if present) for that seller.
Note: seller account is deprecated, please use sub account


Request 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
name
required
string
name for the seller account
note: the name must be unique in your platform


 
Responses 
201
Seller account was created successfully


post/seller_accounts
Request samples 
application/json
{
  • "name": "Seller account name"
}
Response samples 
application/json
{
  • "id": 1,
  • "type": "seller_account",
  • "data": {
    },
  • "page_info": null
}
List Seller Accounts
List the sellers for your account. This endpoint supports pagination.
Note: By default, all sellers which are not archived will be returned. To list archived sellers, use the optional status parameter set to archived
Note: seller account is deprecated, please use sub account


Request 
query Parameters
status
string
Return accounts with specific status


 Enum: "created" "submitted" "information_needed" "rejected" "enabled" "disabled" "archived"  
 Example:  status=archived
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully list seller accounts


get/seller_accounts
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Seller Account
Get information about a seller account.
Note: seller account is deprecated, please use sub account


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a seller account


get/seller_accounts/{id}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "seller_account",
  • "data": {
    },
  • "page_info": null
}
Hosted Onboarding
In order to process payments, each of your customers (whom we refer to as sub accounts) will go through an approval process. JustiFi's hosted onboarding provides you with an easy-to-implement, user-friendly way to collect the required business and financial information from each sub accounts within your platform. Once approved, your sub account can process payments through JustiFi.


To onboard a new sub account via hosted onboarding


    

  1. Create a sub account
    2. 

  2. Include JustiFi hosted onboarding in your application
    3. 

  3. (optional) Listen to success/fail message
    4. 

  4. Check the sub account's status
    5. 



Create a sub account


Create a sub account


curl -X POST \
  https://api.justifi.ai/v1/sub_accounts \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sub account name"
  }'



Use the sub accounts API to create a sub account on JustiFi that is associated with your platform. You will need the account_id from the account you create for the next step.


Include JustiFi hosted onboarding in your application


To present the JustiFi hosted onboarding form to your user, create an iframe with a source of https://accounts.justifi.ai/onboarding/SUB_ACCOUNT_ID, where SUB_ACCOUNT_ID is the account_id that was created in the previous step. This iframe will present your user with a multi-step form where they can enter the business and financial information needed for approval. Upon submission, a success message will display.


(optional) Listen to success/fail message


Listen to success/fail message


const handleOnboardingCompletion = (e) => {
  const { eventType } = e.data;
  if (eventType === 'submitSuccess') {
    // Handle successful onboarding
  }
  if (eventType === 'submitFailure') {
    // Handle failed onboarding
  }
};

window.addEventListener('message', handleOnboardingCompletion);



When the onboarding is completed, success or failure, the JustiFi iframe will send a postMessage. This allows your platform to take a next step, for example closing a modal, or redirecting to another page.


Check the sub account status


Retrieve a sub account


curl -X GET https://api.justifi.ai/v1/sub_accounts/ACCOUNT_ID \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'



Once your sub account submits the onboarding form, we'll review their information. This approval process can take up to a few business days. In order to check the account's onboarding status, call the Get a Sub Account endpoint or use an event publisher to subscribe to the sub_account.updated events.Note: seller_account.updated event has been deprecated


Onboarding via API
In order to process payments, each of your customers (whom we refer to as sub accounts) will go through an approval process. JustiFi's onboarding API allows you to utilize your own onboarding frontend to collect the required business and financial information from each of your sub accounts. Once approved, your sub account can process payments through JustiFi.


To onboard a new sub account via the API


    

  1. Create a sub account
    2. 

  2. Create an onboarding entry
    3. 

  3. Check the sub account's status
    4. 



Create a sub account


Create a sub account


curl -X POST \
  https://api.justifi.ai/v1/sub_accounts \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Sub account name"
  }'



Use the sub accounts API to create a sub account on JustiFi that is associated with your platform. You will need the account_id from the sub account you create for the next step.


Create an onboarding entry


Use the onboarding API to create an onboarding entry containing the required information for the sub account you made.


Check the sub account status


Retrieve a sub account


curl -X GET https://api.justifi.ai/v1/sub_accounts/ACCOUNT_ID \
    -H 'Authorization: Bearer [access_token]' \
    -H 'Accept: application/json'



Once you create the account's onboarding entry, we'll review their information. This approval process can take up to a few business days. In order to check the account's onboarding status, call the Get a Sub Account endpoint or use an event publisher to subscribe to the sub_account.updated events.Note: seller_account.updated event has been deprecated


Create an Onboarding Entry
First, you'll need to create a sub account so you can use that sub account id in the path for this API.


Create an onboarding entry for a sub account, which will send their required onboarding information to the JustiFi team for review. This will change the sub account's status to submitted. Upon review, if we require additional verification in the form of an ID document (which is rare), we'll work with your sub account to obtain the documentation we need.


Depending on each sub account's business type and structure, the onboarding information you'll need to collect will vary. Use the table below to check the requirements for each. You can also get a head start by copying the payloads from the request samples on the right; just choose the type of business you need from the dropdown first. Note: The payload, response, and restrictions are all subject to change based on gateway requirements.



  
    

      
      
      For-Profit
      Non-Profit
      Government Entity
    

    

      
      Individual
      Sole Proprietorship
      Single Member LLC
      Multi Member LLC
      Private Partnership
      Private Corporation
      Unincorporated Association
      Public Partnership
      Public Corporation
      Incorporated
      Unincorporated
      Governmental Unit
      Government Instrumentality
    

  
  
    

      business_details.url
      Required for all
    

    

      business_details.type
      Required for all
    

    

      business_details.structure
      Required for all
    

    

      business_details.industry
      Required for all
    

    

      business_details.tax_id
      -
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
    

    

      business_details.phone
      -
      -
      -
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
    

    

      business_details.email
      -
      -
      -
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
    

    

      business_details.legal.name
      -
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
    

    

      business_details.legal.address* fields
      -
      -
      -
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
    

    

      business_details.doing_business_as.name
      Required for none
    

    

      representative.name
      Required for all
    

    

      representative.title
      -
      -
      -
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
    

    

      representative.email
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      -
      -
      ✅
      ✅
      -
      -
    

    

      representative.phone
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      -
      -
      ✅
      ✅
      -
      -
    

    

      representative.ssn_last4
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      -
      -
      ✅
      ✅
      ✅
      ✅
    

    

      representative.is_owner
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      -
      -
      ✅
      ✅
      -
      -
    

    

      representative.dob* fields
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      -
      -
      ✅
      ✅
      ✅
      ✅
    

    

      representative.address* fields
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      ✅
      -
      -
      ✅
      ✅
      -
      -
    

    

      owners list
      -
      -
      -
      ✅
      ✅
      ✅
      ✅
      -
      -
      -
      -
      -
      -
    

    

      bank_account
      Required for all
    

    

      terms_and_conditions.accepted
      Required for all
    

    

      terms_and_conditions.ip
      Required for all
    

    

      terms_and_conditions.user_agent
      Required for none
    

  



Request 
path Parameters
id
required
string <uuid> 
sub account id for which this entry is being submitted


 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
onboarding_version
string
defaults to v1.0 if not passed, may change in the future as onboarding requirements change


 
object
information about the sub account's business, as defined on their SS-4 tax document


 
object
personal information about the financial representative -- this must be someone who has significant control over managing this sub account's finances


 
Array of objects
up to four business owners total; do not re-record the financial representative if they are marked as an owner


 
object
bank account which will be used for payouts to the sub account (must be a US-based checking account)


 
object
details about accepting JustiFi's terms and conditions on behalf of a sub account


 
Responses 
200
Onboarding entry was created successfully


post/onboarding/{id}
Request samples 
application/json
{
  • "business_details": {},
  • "representative": {
    },
  • "bank_account": {
    },
  • "terms_and_conditions": {
    }
}
Response samples 
application/json
{
  • "id": 1,
  • "type": "onboarding_entry",
  • "data": {
    },
  • "page_info": null
}
Proceeds
Proceeds represent your platform's take-home portion of the fees from your sellers' financial transactions.
Proceeds are batched together according to the payout schedule configured on your account, then transferred
to your active bank account.


List Proceeds
List the proceeds payouts for your account. This endpoint supports pagination.


Request 
query Parameters
created_before
string <datetime> 
Filter records which were created before the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00


 
 Example:  created_before=2022-01-01T00:00:00Z
created_after
string <datetime> 
Filter records which were created after the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00


 
 Example:  created_after=2022-01-01T00:00:00Z
deposits_before
string <datetime> 
Filter records which deposit before the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00


 
 Example:  deposits_before=2022-01-01T00:00:00Z
deposits_after
string <datetime> 
Filter records which deposit after the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00


 
 Example:  deposits_after=2022-01-01T00:00:00Z
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully list proceeds


get/platform/proceeds
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Proceeds Payout
Get information about a proceeds payout.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a proceeds payout


get/platform/proceeds/{id}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "payout",
  • "data": [
    ],
  • "page_info": {
    }
}
Hosted Checkout
JustiFi provides a hosted checkout solution which allows you to collect a payment via a checkout form which we host. This solution provides less customization compared to using our PaymentsJS / Payment Web Components, however it requires less frontend integration work on your platform.


To collect a payment via hosted checkout, you must first ensure you ask the JustiFi team to enable the hosted checkout feature for your platform. We will also configure the branding for the checkout at this time.


Once you have configured hosted checkout, you must complete the following steps to complete a payment:


    

  1. Create a Payment Intent
    2. 

  2. Create a Checkout Session
    3. 

  3. Redirect to our hosted checkout
    4. 

  4. Handle successful payment redirect
    5. 

  5. OR handle redirect back from checkout (optional)
    6. 

  6. Handle payment_intent.succeeded event (optional)
    7. 



Create a payment intent


Create a Payment Intent with the amount you'd like to capture, and a description of the payment.


Create a checkout session


Create a checkout session which will be used to redirect your customer to the JustiFi checkout page. This in includes the payment intent, a url to redirect for a back/cancel action, and a url for redirect after completing the payment. At this point You have 24 hours to complete the checkout.


Redirect to our hosted checkout


Using the checkout session id returned from the previous step, redirect to https://checkout.justifi.ai/r/{checkout_session_id}, this will redirect your customer our checkout form with your branding.


Handle AFTER payment redirect


If the checkout is completed, we will redirect to the after payment url provided when the checkout session was created. Please note, it is possible the payment may not be in a pending, or failed status, so please interrogate the payment via API.


OR handle redirect back from checkout


If a customer decides not to pay, we have a back button on the checkout form. If you provide a back_url, we will redirect the customer back to that url.


(Optional) handle payment_intent.succeeded event


In addition to the after payment redirect, we recommend creating an Event Publisher which publishes payment_intent.succeeded events. This will provide a secondary means to ensure the payment was successful if there are network issues with the redirect.


Payments
To charge a payment method the desired amount, you'll use a payment.
You can choose whether to charge a payment method that's already been
tokenized or tokenize a new one when you create the payment.
If a payment fails, the status will reflect it and an error code will be returned.
You can retrieve information about your payments and refund them if needed.


Create a Payment
Authorize, capture, and charge a payment method.
Note: For platforms, if the sub account status is not enabled, 400 will be returned.


Request 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Sub-Account
string
for platforms, the id of the sub account that this request applies to


 
 Example:  acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
 Deprecated 
for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account


 
Request Body schema: application/json
amount
required
number
amount to charge in cents


 
currency
required
string
 Value: "usd"  
capture_strategy
required
string
automatic will authorize and capture the payment in the same request, manual will only authorize the payment (which will need to be captured in a subsequent request).  Not supported by bank account (ACH) payment methods.


 Enum: "automatic" "manual"  
email
string <email> 
email address to associate with payment method


 
required
object
 
application_fee_amount
integer
sets a custom application fee amount that applies to this payment, instead of relying on application fee rates configured at the platform account level (only Platforms may set application_fee_amount)


 
description
string
your meaningful description of the payment (e.g. an order number or other value from your system)


 
metadata
object <json> 
any useful information you'd like to store alongside this payment


 
Responses 
201
Payment was created successfully


post/payments
Request samples 
application/json
{
  • "amount": 1000,
  • "currency": "usd",
  • "capture_strategy": "automatic",
  • "email": "example@test.com",
  • "description": "Charging $10 to the test card",
  • "payment_method": {
    }
}
Response samples 
application/json
{
  • "id": "py_123xyz",
  • "type": "payment",
  • "data": {
    },
  • "page_info": null
}
List Payments
List the payments for your account. This endpoint supports pagination.


Request 
query Parameters
financial_transaction_id
string
Filter records which are associated with a financial transaction.


 
 Example:  financial_transaction_id=ft_123xyz
created_after
string <datetime> 
Filter records which were created after the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00


 
 Example:  created_after=2022-01-01T00:00:00Z
payment_status
string
Filter to payments which have request payment_status


 Enum: "succeeded" "failed" "pending" "authorized" "refunded" "disputed"  
 Example:  payment_status=refunded
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Sub-Account
string
for platforms, the id of the sub account that this request applies to


 
 Example:  acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
 Deprecated 
for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account


 
Responses 
200
Successfully list payments


get/payments
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Payment
Get information about a payment.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a payment


get/payments/{id}
Request samples 
Response samples 
application/json
{
  • "id": "py_123xyz",
  • "type": "payment",
  • "data": {
    },
  • "page_info": null
}
Update a Payment
Change a payment's description or metadata.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
description
string
your meaningful description of the payment (e.g. an order number or other value from your system)


 
metadata
object <json> 
any useful information you'd like to store alongside this payment; when you update metadata, any previous metadata will be overwritten


 
Responses 
200
Payment update was successful


patch/payments/{id}
Request samples 
application/json
{
  • "description": "order_xyz new description",
  • "metadata": { }
}
Response samples 
application/json
{
  • "id": "py_123xyz",
  • "type": "payment",
  • "data": {
    },
  • "page_info": null
}
Capture a Payment
To charge a payment method and capture a previously authorized payment.  Returns a payment_already_captured error if the payment is in a captured state.
Note: For platforms, if the sub account status is not enabled, 400 will be returned.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Payment with identical idempotency key was captured


201
Payment was captured successfully


post/payments/{id}/capture
Request samples 
Response samples 
application/json
{
  • "id": "py_123xyz",
  • "type": "payment",
  • "data": {
    },
  • "page_info": null
}
Refund a Payment
Issue a refund for a payment. You may refund the full payment amount or just a portion. When refunding a portion, multiple refunds are supported up until the full payment amount has been refunded.
Note: For platforms, if the seller account status is not enabled, 400 will be returned.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
amount
number
amount to refund; must be less than or equal to the amount_refundable on the payment


 
description
string
an optional note about this refund


 
reason
string
the reason this refund is being issued


 Enum: "duplicate" "fraudulent" "customer_request"  
metadata
object <json> 
any useful information you'd like to store alongside this refund


 
Responses 
201
Refund was created successfully


post/payments/{id}/refunds
Request samples 
application/json
{
  • "amount": 10000,
  • "description": "string",
  • "reason": "duplicate",
  • "metadata": { }
}
Response samples 
application/json
{
  • "id": 1,
  • "type": "refund",
  • "data": {
    },
  • "page_info": null
}
Get Balance Transactions
Get information about the payment-balance-transactions associated with a payment.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully retrieve the payment-balance-transactions for a payment


get/payments/{id}/payment_balance_transactions
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Payment Intents
If you'd like to track the payment method and all associated payment attempts
for a particular payment, you can use payment intents.
Once you've tokenized a payment method and attached it to a payment intent,
capturing the payment intent will let JustiFi know to charge the payment method and create a payment.
If the capture fails, you can attempt again on the same payment intent.


Create a Payment Intent
Create a payment intent if you'd like a place to track the payment method along with all payment attempts for a payment.
Note: For platforms, if the seller account status is not enabled, 400 will be returned.


Request 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Sub-Account
string
for platforms, the id of the sub account that this request applies to


 
 Example:  acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
 Deprecated 
for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account


 
Request Body schema: application/json
amount
required
number
amount to charge in cents


 
currency
required
string
 Value: "usd"  
description
string
your meaningful description of the payment intent (e.g. an order number or other value from your system)


 
metadata
object <json> 
any useful information you'd like to store alongside this payment intent


 
Responses 
201
Payment intent was created successfully


post/payment_intents
Request samples 
application/json
{
  • "amount": 1000,
  • "currency": "usd",
  • "description": "ORDER 1235ABC: Charging $10 to the test card",
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "id": "pi_xyz",
  • "account_id": "acc_xyz",
  • "amount": 10000,
  • "currency": "usd",
  • "description": "my_order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "status": "requires_payment_method",
  • "created_at": "2021-01-01T12:00:00Z",
  • "updated_at": "2021-01-01T12:00:00Z"
}
List Payment Intents
List the payment intents for your account. This endpoint supports pagination.


Request 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Sub-Account
string
for platforms, the id of the sub account that this request applies to


 
 Example:  acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
 Deprecated 
for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account


 
Responses 
200
Successfully list payment intents


get/payment_intents
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Payment Intent
Get information about a payment intent.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a payment intent


get/payment_intents/{id}
Request samples 
Response samples 
application/json
{
  • "id": "pi_xyz",
  • "account_id": "acc_xyz",
  • "amount": 10000,
  • "currency": "usd",
  • "description": "my_order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "status": "requires_payment_method",
  • "created_at": "2021-01-01T12:00:00Z",
  • "updated_at": "2021-01-01T12:00:00Z"
}
Update a Payment Intent
Change a payment intent's description or metadata; attach a payment method.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
description
string
your meaningful description of the payment intent (e.g. an order number or other value from your system)


 
metadata
object <json> 
any useful information you'd like to store alongside this payment intent; when you update metadata, any previous metadata will be overwritten


 
object
can be updated if the payment intent status is requires_payment_method or pending


 
amount
integer
payment intent amount, in cents; can be updated if the payment intent status is requires_payment_method or pending


 
Responses 
200
Payment intent update was successful


patch/payment_intents/{id}
Request samples 
application/json
{
  • "description": "order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "amount": 10000
}
Response samples 
application/json
{
  • "id": "pi_xyz",
  • "account_id": "acc_xyz",
  • "amount": 10000,
  • "currency": "usd",
  • "description": "my_order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "status": "requires_payment_method",
  • "created_at": "2021-01-01T12:00:00Z",
  • "updated_at": "2021-01-01T12:00:00Z"
}
Capture a Payment Intent
Capturing a payment intent lets JustiFi know you intend to process a payment. JustiFi will charge the attached payment method and create a payment.
Note: For platforms, if the sub account status is not enabled, 400 will be returned.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
object
 
Responses 
201
Payment intent was captured successfully


post/payment_intents/{id}/capture
Request samples 
application/json
{
  • "payment_method": {
    }
}
Response samples 
application/json
{
  • "id": "pi_xyz",
  • "account_id": "acc_xyz",
  • "amount": 10000,
  • "currency": "usd",
  • "description": "my_order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "status": "requires_payment_method",
  • "created_at": "2021-01-01T12:00:00Z",
  • "updated_at": "2021-01-01T12:00:00Z"
}
Get Payments for a Payment Intent
Get information about the payments associated with a payment intent.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully retrieve the payments for a payment intent


get/payment_intents/{id}/payments
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Payment Methods
Payment methods refer to the specific form of payment each customer uses
(e.g. their credit card). Payment methods are tokenized, then charged at time of payment.


Create a Payment Method
You can create payment methods ahead of time, then pass their existing tokens to payments.
Alternatively, you can create and tokenize payment methods inline when processing payments.
Note: For platforms, if the seller account status is not enabled, 400 will be returned.


Request 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Sub-Account
string
for platforms, the id of the sub account that this request applies to


 
 Example:  acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
 Deprecated 
for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account


 
Request Body schema: application/json
required
object
 
email
string <email> 
email address to associate with the payment method


 
Responses 
201
Payment method was created successfully


post/payment_methods
Request samples 
application/json
{
  • "payment_method": {
    }
}
Response samples 
application/json
{
  • "id": "pm_123xyz",
  • "type": "payment_method",
  • "data": {
    },
  • "page_info": null
}
List Payment Methods
List the payment methods for your account. This endpoint supports pagination.


Request 
query Parameters
customer_id
string
Filter records which are associated with a customer.


 
 Example:  customer_id=cust_123xyz
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Sub-Account
string
for platforms, the id of the sub account that this request applies to


 
 Example:  acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
 Deprecated 
for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account


 
Responses 
200
Successfully list payment methods


get/payment_methods
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Payment Method
Get information about a payment method.


Request 
path Parameters
token
required
string
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a payment method


get/payment_methods/{token}
Request samples 
Response samples 
application/json
{
  • "id": "pm_123xyz",
  • "type": "payment_method",
  • "data": {
    },
  • "page_info": null
}
Update a Payment Method
Change a payment method's expiration date, address, or metadata.


Request 
path Parameters
token
required
string
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
object (UpdateCard) 
 
object (UpdateBankAccount) 
Bank Account


 
Responses 
200
Payment method update was successful


patch/payment_methods/{token}
Request samples 
application/json
{
  • "card": {
    },
  • "bank_account": {
    }
}
Response samples 
application/json
{
  • "id": "pm_123xyz",
  • "type": "payment_method",
  • "data": {
    },
  • "page_info": null
}
Clone a Payment Method
Copy a payment method from one sub account to another sub account. This allows one
to share payment methods between accounts without having to collect the card information again. 
The original payment method's id / token should be provided in the path.


Request 
path Parameters
token
required
string
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
destination_account_id
string
The sub account id to which the payment method should be cloned


 
Responses 
200
Payment method clone was successful


post/payment_methods/{token}/clone
Request samples 
application/json
{
  • "destination_account_id": "acc_xyz123"
}
Response samples 
application/json
{
  • "id": "pm_123xyz",
  • "type": "payment_method",
  • "data": {
    },
  • "page_info": null
}
Refunds
When you refund a payment, a refund object is created. You can retrieve
information about the refunds you've issued.


List Refunds
List the refunds for your account. This endpoint supports pagination.


Request 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Sub-Account
string
for platforms, the id of the sub account that this request applies to


 
 Example:  acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
 Deprecated 
for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account


 
Responses 
200
Successfully list refunds


get/refunds
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Refund
Get information about a refund.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a refund


get/refunds/{id}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "refund",
  • "data": {
    },
  • "page_info": null
}
Update a Refund
Update the refund metadata.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
metadata
object <json> 
any useful information you'd like to store alongside this refund; when you update metadata, any previous metadata will be overwritten


 
Responses 
200
Refund update was successful


patch/refunds/{id}
Request samples 
application/json
{
  • "metadata": { }
}
Response samples 
application/json
{
  • "id": 1,
  • "type": "refund",
  • "data": {
    },
  • "page_info": null
}
Disputes
A customer may dispute their payment with the card issuer/bank if they believe
the charge is erroneous. When this happens, a dispute record is created and
associated with their original payment.


List Disputes
List the disputes for your account. This endpoint supports pagination.
The disputes for a specific payment are also included in the payments API
response.


Request 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Sub-Account
string
for platforms, the id of the sub account that this request applies to


 
 Example:  acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
 Deprecated 
for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account


 
Responses 
200
Successfully list disputes


get/disputes
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Dispute
Get information about a dispute.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a dispute


get/disputes/{id}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "dispute",
  • "data": {
    },
  • "page_info": null
}
Update a Dispute
Change a dispute's metadata.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
metadata
object <json> 
any useful information you'd like to store alongside this dispute; when you update metadata, any previous metadata will be overwritten


 
Responses 
200
Dispute update was successful


patch/disputes/{id}
Request samples 
application/json
{
  • "metadata": { }
}
Response samples 
application/json
{
  • "id": 1,
  • "type": "dispute",
  • "data": {
    },
  • "page_info": null
}
Payouts
Each day, a payout containing that day's funds is automatically created for the
purpose of distributing those funds to the active bank account. Payout amounts are calculated by
summing the associated balance transactions for that specific day.


List Payouts
Request 
query Parameters
created_before
string <datetime> 
Filter records which were created before the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00


 
 Example:  created_before=2022-01-01T00:00:00Z
created_after
string <datetime> 
Filter records which were created after the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00


 
 Example:  created_after=2022-01-01T00:00:00Z
deposits_before
string <datetime> 
Filter records which deposit before the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00


 
 Example:  deposits_before=2022-01-01T00:00:00Z
deposits_after
string <datetime> 
Filter records which deposit after the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00


 
 Example:  deposits_after=2022-01-01T00:00:00Z
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully list payouts


get/payouts
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
Get a Payout
Get information about a payout.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a payout


get/payouts/{id}
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "payout",
  • "data": {
    },
  • "page_info": null
}
Update a Payout
Change a payout's metadata.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Idempotency-Key
required
string <uuid> 
a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests


 
 Example:  my-request-123abc
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Request Body schema: application/json
metadata
object <json> 
any useful information you'd like to store alongside this payout; when you update metadata, any previous metadata will be overwritten


 
Responses 
200
Payout update was successful


patch/payouts/{id}
Request samples 
application/json
{
  • "metadata": {
    }
}
Response samples 
application/json
{
  • "id": 1,
  • "type": "payout",
  • "data": {
    },
  • "page_info": null
}
Get a Payout CSV Report
Get a link to a CSV report with information a payout and balance transactions related to that payout. CSV report headers include id, currency, amount, fee, net, source_id, source_account_id, source_type, source_amount, available_on and created_at.


Request 
path Parameters
id
required
string <uuid> 
 
header Parameters
Authorization
required
string
the access_token value returned from the JustiFi oauth/token endpoint (be sure to append Bearer before the token)


 
 Example:  Bearer {access_token}
Responses 
200
Successfully get a link to a csv report for a payout