openapi: 3.0.0
info:
description: "## Introduction\n\nThe 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.\n\n## Getting Started\n\nTo process a payment with JustiFi, follow these steps\n\n- [Get Your Accounts](#get-your-accounts)\n- [Get Your API Keys](#get-your-api-keys)\n- [Authenticate With JustiFi](#authenticate-with-justifi)\n- For Platforms, [Create and Onboard Your Sub Accounts](https://docs.justifi.tech/api-spec#tag/Sub-Accounts)\n- [Create a Payment](https://docs.justifi.tech/api-spec#tag/Payments/operation/CreatePayment)\n\n<br>\n\n### Get Your Accounts\n\nOur 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.\n\n<br>\n\n### Get Your API Keys\n\nOnce 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.\n\nAdditionally, we can provide access to a sandbox environment upon request.\n\n<br>\n\n### Authenticate With JustiFi\n\n<PullRight>\n\n##### Example OAuth Client Credentials Grant Request\n\n```sh\ncurl -X POST https://api.justifi.ai/oauth/token \\\n -H 'Content-Type: application/json' \\\n --data '{\"client_id\":\"[your client id]\",\"client_secret\":\"[your client secret]\"}'\n```\n\n##### Example Authenticated Response\n\n```json\n{\n \"access_token\": \"... this will be a very long string and is valid for 24 hours\"\n}\n```\n\n##### Example Authenticated Request\n\n```sh\ncurl -X POST https://api.justifi.ai/v1/payments \\\n -H 'Authorization: Bearer [access_token]' \\\n -H 'Content-Type: application/json'\n -H 'Idempotency-Key: a-unique-string-for-the-transaction'\n```\n\n</PullRight>\n\nJustiFi 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_`.\n\nNext, take the access token in that response and pass it in all subsequent requests as the `Authorization` header.\n\nThis 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.\n\n## Idempotent Requests\n\n<PullRight>\n\n##### Example Request with Idempotency-Key Header\n\n```sh\ncurl -X POST https://api.justifi.ai/v1/payments \\\n -H 'Authorization: Bearer [access_token]' \\\n -H 'Accept: application/json'\n -H 'Idempotency-Key: a-unique-string-for-the-transaction'\n```\n\n</PullRight>\n\nIn 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.\n\nIf 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`.\n\nIf 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.\n\nYou may use any string up to 100 characters long to identify your `Idempotency-Key`; we generally recommend using a generated uuid, but you may use any unique string.\n\n## Pagination\n\n<PullRight>\n\n##### Example Paginated Request\n\n```sh\ncurl -X GET https://api.justifi.ai/v1/payments?limit=25&after_cursor=token-from-page-info \\\n -H 'Authorization: Bearer [access_token]' \\\n -H 'Accept: application/json'\n```\n\n##### Example Paginated Response\n\n```sh\n{\n \"id\": null,\n \"type\": \"array\",\n \"data\":[\n { \"id\":\"py_438xBom2Drh55kE1WfyGLg\",\n \"amount\": 1000,\n ... additional response attributes based on resource schema\n }\n ],\n \"page_info\": {\n \"has_previous\": false,\n \"has_next\": true,\n \"start_cursor\": \"WyIyMDIyLTAxLTExIDE1OjI3OjM2LjAyNzc3MDAwMCIsImNhNjQwMTk1LTEzYzMtNGJlZi1hZWQyLTU3ZjA1MzhjNjNiYSJd\",\n \"end_cursor\": \"WyIyMDIyLTAxLTExIDEyOjU5OjQwLjAwNTkxODAwMCIsImQ0Njg5MGE2LTJhZDItNGZjNy1iNzdkLWFiNmE3MDJhNTg3YSJd\"\n }\n}\n```\n\n</PullRight>\nAll 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.\n\n#### Standard `array` API Request Parameters\n\n<table layout=\"fixed\">\n <tr>\n <th style=\"width: 200px\">Parameter</th>\n <th>Description</th>\n </tr>\n <tr>\n <td style=\"vertical-align: top\"><code>limit</code></td>\n <td>\n The number of resources to retrieve.<br />\n <b>type</b>: <code>integer</code><br />\n <b>default</b>: <code>25</code><br />\n <b>minimum</b>: <code>1</code><br />\n <b>maximum</b>: <code>100</code>\n </td>\n </tr>\n <tr>\n <td style=\"vertical-align: top\"><code>after_cursor</code></td>\n <td>\n Token to fetch the next page of a list.<br />\n <b>type</b>: <code>string</code><br />\n </td>\n </tr>\n <tr>\n <td style=\"vertical-align: top\"><code>before_cursor</code></td>\n <td>\n Token to fetch the previous page of a list.<br />\n <b>type</b>: <code>string</code><br />\n </td>\n </tr>\n</table>\n\nThe `after_cursor`/`before_cursor` parameter determines which page of results will be returned.\nIf `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.\n\nThe `limit` parameter determines the maximum number of results included in each response. If there are fewer\nrecords available than the `limit` value, the response will include all available records. The maximum value\nallowed is 100 with a default value of 25. If the `limit` value is an invalid type, the default value of 25 is used.\n\n#### Standard API Response Structure\n\nAll of our responses are contained in the same envelope, for arrays the id field will be null\nand the object will be an array.\n\n<table layout=\"fixed\">\n <tr>\n <th style=\"width: 200px\">Attribute</th>\n <th>Description</th>\n </tr>\n <tr>\n <td style=\"vertical-align: top\"><code>id</code></td>\n <td>\n The id of the object returned. Will be null for arrays.<br />\n <b>type</b>: <code>string</code><br />\n <b>default</b>: <code>\"a uuid\"</code>\n </td>\n </tr>\n <tr>\n <td style=\"vertical-align: top\"><code>type</code></td>\n <td>\n The type of object returned.<br />\n <b>type</b>: <code>string</code><br />\n <b>default</b>: <code>\"array\"</code>\n </td>\n </tr>\n <tr>\n <td style=\"vertical-align: top\"><code>data</code></td>\n <td>\n The resource OR an array of the requested resources.<br />\n <b>type</b>: <code>array | object</code><br />\n <b>Notes</b>: May be an empty array <code>[]</code> if no resources are available.<br />\n </td>\n </tr>\n <tr>\n <td style=\"vertical-align: top\"><code>page_info</code></td>\n <td>\n The object containing pagination information.<br />\n <b>type</b>: <code>object</code><br />\n <b>Notes</b>: Contains <code>has_previous</code>, <code>has_next</code>, <code>start_cursor</code> and <code>end_cursor</code>\n </td>\n </tr>\n</table>\n\n## Testing\n\nUse 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).\n\n#### Successful Test Cards\n\n<table layout=\"fixed\">\n <tr>\n <th style=\"width: 200px\">Number</th>\n <th>Brand</th>\n <th>CVC</th>\n <th>Date</th>\n </tr>\n <tr>\n <td><code>4242424242424242</code></td>\n <td>Visa</td>\n <td>Any 3 digits</td>\n <td>Any future date</td>\n </tr>\n <tr>\n <td><code>4000056655665556</code></td>\n <td>Visa (debit)</td>\n <td>Any 3 digits</td>\n <td>Any future date</td>\n </tr>\n <tr>\n <td><code>5555555555554444</code></td>\n <td>Mastercard</td>\n <td>Any 3 digits</td>\n <td>Any future date</td>\n </tr>\n <tr>\n <td><code>2223003122003222</code></td>\n <td>Mastercard (2-series)</td>\n <td>Any 3 digits</td>\n <td>Any future date</td>\n </tr>\n <tr>\n <td><code>5200828282828210</code></td>\n <td>Mastercard (debit)</td>\n <td>Any 3 digits</td>\n <td>Any future date</td>\n </tr>\n <tr>\n <td><code>5105105105105100</code></td>\n <td>Mastercard (prepaid)</td>\n <td>Any 3 digits</td>\n <td>Any future date</td>\n </tr>\n <tr>\n <td><code>378282246310005</code></td>\n <td>American Express</td>\n <td>Any 4 digits</td>\n <td>Any future date</td>\n </tr>\n <tr>\n <td><code>371449635398431</code></td>\n <td>American Express</td>\n <td>Any 4 digits</td>\n <td>Any future date</td>\n </tr>\n <tr>\n <td><code>6011000990139424</code></td>\n <td>Discover</td>\n <td>Any 3 digits</td>\n <td>Any future date</td>\n </tr>\n</table>\n\n#### Declined Test Cards\n\n<table layout=\"fixed\">\n <tr>\n <th style=\"width: 200px\">Number</th>\n <th>Description</th>\n <th>Tokenization Succeeds</th>\n </tr>\n <tr>\n <td><code>4000000000000101</code></td>\n <td>\n If a CVC number is provided, the cvc_check fails.\n </td>\n <td>true</td>\n </tr>\n <tr>\n <td><code>4000000000000341</code></td>\n <td>\n Tokenizing this card succeeds, but attempts to make a payment fail.\n </td>\n <td>true</td>\n </tr>\n <tr>\n <td><code>4000000000000002</code></td>\n <td>Payment is declined with a card_declined code.</td>\n <td>true</td>\n </tr>\n <tr>\n <td><code>4000000000009995</code></td>\n <td>\n Payment is declined with a card_declined code. The decline_code attribute is insufficient_funds.\n </td>\n <td>true</td>\n </tr>\n <tr>\n <td><code>4000000000009987</code></td>\n <td>\n Payment is declined with a card_declined code. The decline_code attribute is lost_card.\n </td>\n <td>true</td>\n </tr>\n <tr>\n <td><code>4000000000009979</code></td>\n <td>\n Payment is declined with a card_declined code. The decline_code attribute is stolen_card.\n </td>\n <td>true</td>\n </tr>\n <tr>\n <td><code>4000000000000069</code></td>\n <td>Payment is declined with an expired_card code.</td>\n <td>true</td>\n </tr>\n <tr>\n <td><code>4000000000000127</code></td>\n <td>Payment is declined with an invalid_cvc code.</td>\n <td>true</td>\n </tr>\n <tr>\n <td><code>4000000000000119</code></td>\n <td>Payment is declined with a gateway_error code.</td>\n <td>true</td>\n </tr>\n <tr>\n <td><code>4242424242424241</code></td>\n <td>\n Payment is declined with an card_number_invalid code as the card number fails the Luhn check.\n </td>\n <td>false</td>\n </tr>\n</table>\n\n#### Successful Bank Account (ACH)\n\n<table layout=\"fixed\">\n <tr>\n <th>Routing Number</th>\n <th>Account Number</th>\n </tr>\n <tr>\n <td><code>110000000</code></td>\n <td><code>000123456789</code></td>\n </tr>\n</table>\n\n#### Declined Bank Accounts (ACH)\n\n<table layout=\"fixed\">\n <tr>\n <th>Routing Number</th>\n <th>Account Number</th>\n <th>Payment Error</th>\n </tr>\n <tr>\n <td><code>110000000</code></td>\n <td><code>000222222227</code></td>\n <td>\n Insufficient Funds\n </td>\n </tr>\n <tr>\n <td><code>110000000</code></td>\n <td><code>000333333335</code></td>\n <td>\n The account doesn't support debits\n </td>\n </tr>\n <tr>\n <td><code>110000000</code></td>\n <td><code>000111111113</code></td>\n <td>\n The account is closed\n </td>\n </tr>\n <tr>\n <td><code>110000000</code></td>\n <td><code>000111111116</code></td>\n <td>\n The account doesn't exist\n </td>\n </tr>\n</table>\n\n## HTTP Errors\n\nThe JustiFi API may return a number of standard HTTP errors due to invalid requests. Some common errors are described\nbelow to help you build with JustiFi.\n\n#### Bad Request\n\nThe server cannot process the request. This error is most likely due to malformed request syntax.\n\n- code: `400`\n- status: `Bad Request`\n\n#### Unauthorized\n\nSimilar to a `403 Forbidden`, but specifically when authentication is provided and has failed, or has not been provided.\nThis error is most likely due to not including your API key in the request header.\n\n- code: `401`\n- status: `Unauthorized`\n\n#### Payment Required\n\nThere was an error processing the payment. This response is returned when errors occur while tokenizing the payment method, such\nas an invalid cvc or an expiration date in the past. This can also occur when making a payment and the card is declined.\nIn that case, the error message will provide more specific information about why the request was declined.\n\n- code: `402`\n- status: `Payment Required`\n\n#### Forbidden\n\nThe request was valid, but you are unable to execute the request. This error is most likely due to the API key that\nwas used not having the necessary permissions, or attempting a prohibited action such as creating a duplicate\nrecord where one already exists.\n\n- code: `403`\n- status: `Forbidden`\n\n#### Not Found\n\nThe requested resource could not be found, but may be available in the future. This error is most likely due to\nrequesting a resource by `id` that doesn't exist. You'll want to double check that you're referencing the correct\n`id` and that it exists on your account.\n\n- code: `404`\n- status: `Not Found`\n\n#### Concurrent Request Error\n\nThe 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.\n\n- code: `409`\n- status: `Conflict`\n\n#### Unprocessable Entity\n\nThe request was well-formed, but was unable to be processed due to semantic errors. This error is most likely due to\nincluding invalid data in `POST`, `PATCH`, and `PUT` requests. Double check the request documentation to make sure\nyou're supplying the required attributes, and that the attribute types are correct.\n\n- code: `422`\n- status: `Unprocessable Entity`\n\n#### Internal Server Error\n\nAn internal server error occurred due to an unexpected condition. This error is most likely due to an issue with our\nservers.\n\n- code: `500`\n- status: `Internal Server Error`\n\n#### Error Codes\n\nMany 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.\n\n<table layout=\"fixed\">\n <tr>\n <th style=\"width: 300px\">Error Code</th>\n <th>Description</th>\n </tr>\n <tr>\n <td><code>acct_last_four_required</code></td>\n <td>Missing required parameter: acct_last_four</td>\n </tr>\n <tr>\n <td><code>amount_below_minimum</code></td>\n <td>Amount must be greater than 50</td>\n </tr>\n <tr>\n <td><code>amount_must_be_an_integer</code></td>\n <td>Amount must be an integer</td>\n </tr>\n <tr>\n <td><code>amount_required</code></td>\n <td>Missing required parameter: amount</td>\n </tr>\n <tr>\n <td><code>amount_above_maximum</code></td>\n <td>Amount must be lower than 100000000 ($1,000,000.00)</td>\n </tr>\n <tr>\n <td><code>amount_below_minimum</code></td>\n <td>Amount must be greater than 50</td>\n </tr>\n <tr>\n <td><code>application_fee_rate_id_required</code></td>\n <td>Missing required parameter: application_fee_rate_id</td>\n </tr>\n <tr>\n <td><code>application_fee_required</code></td>\n <td>Missing required parameter: application_fee</td>\n </tr>\n <tr>\n <td><code>brand_required</code></td>\n <td>Missing required parameter: brand</td>\n </tr>\n <tr>\n <td><code>capture_strategy_invalid</code></td>\n <td>Format is invalid for parameter: capture_strategy</td>\n </tr>\n <tr>\n <td><code>card_decline_rate_limit_exceeded</code></td>\n <td>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.</td>\n </tr>\n <tr>\n <td><code>card_declined</code></td>\n <td>The card has been declined. When a card is declined, the error includes a decline_code attribute specifying the reason for the decline, and a network_decline_code provided by the card network, if available.</td>\n </tr>\n <tr>\n <td><code>card_name_required</code></td>\n <td>Missing required parameter: card_name</td>\n </tr>\n <tr>\n <td><code>card_number_invalid</code></td>\n <td>Format is invalid for parameter: card_number</td>\n </tr>\n <tr>\n <td><code>card_number_required</code></td>\n <td>Missing required parameter: card_number</td>\n </tr>\n <tr>\n <td><code>charge_expired_for_capture</code></td>\n <td>The charge cannot be captured as the authorization has expired. Auth and capture charges must be captured within 7 days.</td>\n </tr>\n <tr>\n <td><code>country_invalid</code></td>\n <td>Format is invalid for parameter: country</td>\n </tr>\n <tr>\n <td><code>currency_invalid</code></td>\n <td>Format is invalid for parameter: currency</td>\n </tr>\n <tr>\n <td><code>currency_required</code></td>\n <td>Missing required parameter: currency</td>\n </tr>\n <tr>\n <td><code>customer_id_required</code></td>\n <td>Missing required parameter: customer_id</td>\n </tr>\n <tr>\n <td><code>customer_max_payment_methods</code></td>\n <td>The maximum number of PaymentMethods for this Customer has been reached. Either detach some PaymentMethods from this Customer or proceed with a different Customer.</td>\n </tr>\n <tr>\n <td><code>email_invalid</code></td>\n <td>The email address is invalid (e.g., not properly formatted). Check that the email address is properly formatted and only includes allowed characters.</td>\n </tr>\n <tr>\n <td><code>email_required</code></td>\n <td>Missing required parameter: email</td>\n </tr>\n <tr>\n <td><code>expired_card</code></td>\n <td>The card has expired. Please check the expiration date or try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>gateway_account_id_required</code></td>\n <td>Missing required parameter: gateway_account_id</td>\n </tr>\n <tr>\n <td><code>gateway_authentication_error</code></td>\n <td>The payment network returned an authentication error</td>\n </tr>\n <tr>\n <td><code>gateway_error</code></td>\n <td>There was an issue processing your payment with the gateway. Please try again later.</td>\n </tr>\n <tr>\n <td><code>gateway_idempotency_error</code></td>\n <td>The gateway detected concurrent requests using this idempotency key</td>\n </tr>\n <tr>\n <td><code>gateway_rate_limit_error</code></td>\n <td>Too many requests hit the API too quickly. We recommend an exponential back-off of your requests.</td>\n </tr>\n <tr>\n <td><code>gateway_ref_id_required</code></td>\n <td>Missing required parameter: gateway_ref_id</td>\n </tr>\n <tr>\n <td><code>gateway_timeout_error</code></td>\n <td>There was a timeout with the gateway, we recommend retrying using the Should-Retry header</td>\n </tr>\n <tr>\n <td><code>idempotency_concurrent_request</code></td>\n <td>We detected concurrent requests using this idempotency key</td>\n </tr>\n <tr>\n <td><code>idempotency_key_required</code></td>\n <td>Idempotency-Key is a required header</td>\n </tr>\n <tr>\n <td><code>idempotency_params_mismatch</code></td>\n <td>The request parameters do not match those of a previous request using this idempotency key</td>\n </tr>\n <tr>\n <td><code>idempotency_request_in_progress</code></td>\n <td>Another request using this idempotency key is currently in progress</td>\n </tr>\n <tr>\n <td><code>internal_server_error</code></td>\n <td>An unexpected error has occurred. JustiFi engineers will investigate the error and contact you if any remediation steps are necessary.</td>\n </tr>\n <tr>\n <td><code>invalid_address</code></td>\n <td>The card’s address is incorrect. Please check the address or try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>invalid_card_number</code></td>\n <td>The card’s number is incorrect. Please check the number or try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>invalid_card_brand</code></td>\n <td>The card’s brand is not supported. Please use Visa, Mastercard, American Express, or Discover, or try a different payment method.</td>\n </tr>\n <tr>\n <td><code>invalid_characters</code></td>\n <td>This value provided to the field contains characters that are unsupported by the field.</td>\n </tr>\n <tr>\n <td><code>invalid_charge_amount</code></td>\n <td>Your transaction was declined because the payment amount is outside the limits set by your card issuer. Please try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>invalid_cvc</code></td>\n <td>The card’s security code is incorrect. Please check the security code or try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>invalid_expiry_month</code></td>\n <td>The card’s expiration month is incorrect. Please check the expiration date or try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>invalid_expiry_year</code></td>\n <td>The card’s expiration year is incorrect. Please check the expiration date or try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>invalid_expiry_date</code></td>\n <td>The provided expiration date is invalid. Please check the expiration date or try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>invalid_zip_code</code></td>\n <td>The card’s postal code is incorrect. Please check the postal code or try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>month_invalid</code></td>\n <td>Format is invalid for parameter: month</td>\n </tr>\n <tr>\n <td><code>not_authenticated</code></td>\n <td>Not authenticated</td>\n </tr>\n <tr>\n <td><code>not_authorized</code></td>\n <td>Not authorized</td>\n </tr>\n <tr>\n <td><code>parameter_missing</code></td>\n <td>Missing required parameter</td>\n </tr>\n <tr>\n <td><code>payment_fully_refunded</code></td>\n <td>The refund cannot be processed because the associated payment is fully refunded</td>\n </tr>\n <tr>\n <td><code>payment_intent_cannot_be_captured</code></td>\n <td>Payment Intent status is '%{status}' so it cannot be captured</td>\n </tr>\n <tr>\n <td><code>payment_intent_not_found</code></td>\n <td>Payment intent not found</td>\n </tr>\n <tr>\n <td><code>payment_intent_unexpected_state</code></td>\n <td>You cannot provide a new payment method to a PaymentIntent when it has a status of requires_capture, canceled, or succeeded</td>\n </tr>\n <tr>\n <td><code>payment_method_not_found</code></td>\n <td>Payment method not found</td>\n </tr>\n <tr>\n <td><code>payment_method_required</code></td>\n <td>Missing required parameter: payment_method</td>\n </tr>\n <tr>\n <td><code>payment_method_token_required</code></td>\n <td>Missing required parameter: payment_method_token</td>\n </tr>\n <tr>\n <td><code>payment_outside_refund_window</code></td>\n <td>The refund cannot be processed because the associated payment is outside the refund window</td>\n </tr>\n <tr>\n <td><code>postal_code_invalid</code></td>\n <td>Format is invalid for parameter: postal_code</td>\n </tr>\n <tr>\n <td><code>refund_error</code></td>\n <td>An error occurred during refunding your payment, JustiFi engineers have been alerted and are working on a solution</td>\n </tr>\n <tr>\n <td><code>refund_exceeds_amount_available</code></td>\n <td>The refund cannot be processed because the refund amount exceeds the available funds</td>\n </tr>\n <tr>\n <td><code>refund_exceeds_payment_amount</code></td>\n <td>The refund cannot be processed because the refund amount exceeds the associated payment amount</td>\n </tr>\n <tr>\n <td><code>refund_reason_invalid</code></td>\n <td>Refund reason must be one of the following: %{Refund::REASONS}</td>\n </tr>\n <tr>\n <td><code>resource_not_found</code></td>\n <td>Resource not found</td>\n </tr>\n <tr>\n <td><code>state_invalid</code></td>\n <td>Format is invalid for parameter: state</td>\n </tr>\n <tr>\n <td><code>token_already_used</code></td>\n <td>The token provided has already been used. You must create a new token before you can retry this request.</td>\n </tr>\n <tr>\n <td><code>token_in_use</code></td>\n <td>The token provided is currently being used in another request. This occurs if your integration is making duplicate requests simultaneously.</td>\n </tr>\n <tr>\n <td><code>transfer_required</code></td>\n <td>Missing required parameter: transfer</td>\n </tr>\n <tr>\n <td><code>unexpected_parameter</code></td>\n <td>Unexpected parameter for this request</td>\n </tr>\n <tr>\n <td><code>verification_invalid</code></td>\n <td>Format is invalid for parameter: verification</td>\n </tr>\n <tr>\n <td><code>year_invalid</code></td>\n <td>Format is invalid for parameter: year</td>\n </tr>\n <tr>\n <td><code>service_not_allowed</code></td>\n <td>This account is not permitted to process the type of transaction being requested, or the surcharge amount is invalid</td>\n </tr>\n <tr>\n <td><code>do_not_honor</code></td>\n <td>This card has been rejected by the issuing bank. Please try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>do_not_retry</code></td>\n <td>This card has been rejected. Please try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>refund_in_progress</code></td>\n <td>A refund for this payment is already in progress</td>\n </tr>\n <tr>\n <td><code>invalid_sub_account</code></td>\n <td>The sub account cannot process a payment for this card. Please contact customer support.</td>\n </tr>\n <tr>\n <td><code>new_card_issued</code></td>\n <td>The transaction was denied because the issuing bank has issued a new card. Please try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>account_closed</code></td>\n <td>The account associated with this payment method is been closed. Please try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>restricted_card</code></td>\n <td>This card has a restriction preventing approval for this transaction. Please try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>restricted_card</code></td>\n <td>This card has a restriction preventing approval for this transaction. Please try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>insufficient_funds</code></td>\n <td>This card has insufficient funds. Please try a different card or payment method.</td>\n </tr>\n <tr>\n <td><code>exceeds_card_limit</code></td>\n <td>The payment amount would exceed a limit placed on this card.</td>\n </tr>\n <tr>\n <td><code>pin_tries_exceeded</code></td>\n <td>The number of PIN retries has been exceeded.</td>\n </tr>\n <tr>\n <td><code>incorrect_pin</code></td>\n <td>The entered PIN is incorrect.</td>\n </tr>\n <tr>\n <td><code>pin_required</code></td>\n <td>A PIN is required.</td>\n </tr>\n <tr>\n <td><code>payment_outside_void_window</code></td>\n <td>The void cannot be processed because the associated payment is outside the void window. Try a refund instead.</td>\n </tr>\n <tr>\n <td><code>issuer_not_available</code></td>\n <td>The card issuer is not available. Please try again later.</td>\n </tr>\n <tr>\n <td><code>amount_too_small</code></td>\n <td>The specified amount is less than the minimum amount allowed. Use a higher amount and try again.</td>\n </tr>\n <tr>\n <td><code>amount_too_large</code></td>\n <td>The specified amount is less than the minimum amount allowed. Use a higher amount and try again.</td>\n </tr>\n <tr>\n <td><code>gateway_error_please_retry</code></td>\n <td>There was a temporary issue processing this payment. Please try again.</td>\n </tr>\n <tr>\n <td><code>checkout_invalid_currency</code></td>\n <td>The currency parameter does not match the currency this account is configured to process.</td>\n </tr>\n</table>\n\n## Network Errors\n\nWe provide the network error code, and the network error category to help inform you how to handle a decline. These are only returned when a transaction fails while trying to process on the card network. Please take a look at each section. The network error category is especially relevant for recurring payments. It can reduce retries on transactions which will never succeed.\n\n### Network Error Codes\n\nIn addition to the standard error codes provided by JustiFi, some errors may include a `network_error_code` that provides more specific information about the error from the payment network. Here's a list of common `network_error_code` values and their meanings:\n\n| Code | Description | Customer Impact & Suggested Actions |\n| ---- | ----------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------
# --- truncated at 32 KB (89 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/justifi/refs/heads/main/openapi/justifi-payout-holds-api-openapi.yml