JustiFi API Documentation (v1)

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.

To process a payment with JustiFi, follow these steps

• Get Your Accounts
• Get Your API Keys
• Authenticate With JustiFi
• For Platforms, Create and Onboard Your Sub Accounts
• Create a Payment

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

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.

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.

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

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

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