openapi: 3.0.0 servers: - url: https://api.justifi.ai/v1 description: JustiFi API info: description: >- ## 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](#get-your-accounts) - [Get Your API Keys](#get-your-api-keys) - [Authenticate With JustiFi](#authenticate-with-justifi) - For Platforms, [Create and Onboard Your Sub Accounts](https://docs.justifi.tech/api-spec#tag/Sub-Accounts) - [Create a Payment](https://docs.justifi.tech/api-spec#tag/Payments/operation/CreatePayment)
### 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 ```sh 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 ```json { "access_token": "... this will be a very long string and is valid for 24 hours" } ``` ##### Example Authenticated Request ```sh 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 ```sh 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 up to 100 characters long to identify your `Idempotency-Key`; we generally recommend using a generated uuid, but you may use any unique string. ## Pagination ##### Example Paginated Request ```sh 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 ```sh { "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
#### Declined Test Cards
Number Description Tokenization Succeeds
4000000000000101 If a CVC number is provided, the cvc_check fails. true
4000000000000341 Tokenizing this card succeeds, but attempts to make a payment fail. true
4000000000000002 Payment is declined with a card_declined code. true
4000000000009995 Payment is declined with a card_declined code. The decline_code attribute is insufficient_funds. true
4000000000009987 Payment is declined with a card_declined code. The decline_code attribute is lost_card. true
4000000000009979 Payment is declined with a card_declined code. The decline_code attribute is stolen_card. true
4000000000000069 Payment is declined with an expired_card code. true
4000000000000127 Payment is declined with an invalid_cvc code. true
4000000000000119 Payment is declined with a gateway_error code. true
4242424242424241 Payment is declined with an card_number_invalid code as the card number fails the Luhn check. false
#### 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_above_maximum Amount must be lower than 100000000 ($1,000,000.00)
amount_below_minimum Amount must be greater than 50
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 includes a decline_code attribute specifying the reason for the decline, and a network_decline_code provided by the card network, if available.
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
card_present_payment_method_token_not_supported card_present payment method tokens cannot be used to create a payment. Payment methods with the payment_method_type card_present are recorded from terminal transactions and are single use. To charge the customer again, collect a new payment method.
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. Please check the expiration date or try a different card or payment method.
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. Please check the address or try a different card or payment method.
invalid_card_number The card’s number is incorrect. Please check the number or try a different card or payment method.
invalid_card_brand The card’s brand is not supported. Please use Visa, Mastercard, American Express, or Discover, or try a different payment method.
invalid_characters This value provided to the field contains characters that are unsupported by the field.
invalid_charge_amount 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.
invalid_cvc The card’s security code is incorrect. Please check the security code or try a different card or payment method.
invalid_expiry_month The card’s expiration month is incorrect. Please check the expiration date or try a different card or payment method.
invalid_expiry_year The card’s expiration year is incorrect. Please check the expiration date or try a different card or payment method.
invalid_expiry_date The provided expiration date is invalid. Please check the expiration date or try a different card or payment method.
invalid_zip_code The card’s postal code is incorrect. Please check the postal code or try a different card or payment method.
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_error An error occurred during refunding your payment, JustiFi engineers have been alerted and are working on a solution
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
service_not_allowed This account is not permitted to process the type of transaction being requested, or the surcharge amount is invalid
do_not_honor This card has been rejected by the issuing bank. Please try a different card or payment method.
do_not_retry This card has been rejected. Please try a different card or payment method.
refund_in_progress A refund for this payment is already in progress
invalid_sub_account The sub account cannot process a payment for this card. Please contact customer support.
new_card_issued The transaction was denied because the issuing bank has issued a new card. Please try a different card or payment method.
account_closed The account associated with this payment method is been closed. Please try a different card or payment method.
restricted_card This card has a restriction preventing approval for this transaction. Please try a different card or payment method.
restricted_card This card has a restriction preventing approval for this transaction. Please try a different card or payment method.
insufficient_funds This card has insufficient funds. Please try a different card or payment method.
exceeds_card_limit The payment amount would exceed a limit placed on this card.
pin_tries_exceeded The number of PIN retries has been exceeded.
incorrect_pin The entered PIN is incorrect.
pin_required A PIN is required.
payment_outside_void_window The void cannot be processed because the associated payment is outside the void window. Try a refund instead.
issuer_not_available The card issuer is not available. Please try again later.
amount_too_small The specified amount is less than the minimum amount allowed. Use a higher amount and try again.
amount_too_large The specified amount is less than the minimum amount allowed. Use a higher amount and try again.
gateway_error_please_retry There was a temporary issue processing this payment. Please try again.
checkout_invalid_currency The currency parameter does not match the currency this account is configured to process.
## Network Errors We 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. ### Network Error Codes In 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: | Code | Description | Customer Impact & Suggested Actions | | ---- | ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 005 | Do not honor (Declined by card association) | The payment was declined by the card association. The customer should try a different payment method or contact the card issuer for more information. | | 100 | Do not honor (Declined by card association) | The payment was declined by the card association. The customer should try a different payment method or contact the card issuer for more information. | | 101 | Expired card | The provided card has expired. The customer needs to update with a new, non-expired card or provide a different payment method. | | 102 | Suspected Fraud | The payment was flagged as potentially fraudulent activity. The customer should contact the card issuer to verify the transaction. | | 104 | Restricted card | The provided card is restricted and cannot be used for this transaction type. The customer needs to use a different payment method or contact the card issuer. | | 106 | Allowable PIN tries exceeded | The maximum allowable PIN entry attempts have been exceeded. The customer should verify the PIN and try again, or use a different payment method. | | 110 | Invalid amount | The payment amount entered is invalid. The customer needs to recheck the amount and retry the transaction. | | 116 | Not sufficient funds | There are insufficient funds in the account to cover this payment. The customer should add funds to the account or use a different payment method. | | 117 | Incorrect PIN or PIN length error | The entered PIN is incorrect or has an invalid length. The customer should re-enter the correct PIN and try again. | | 119 | Transaction not permitted to cardholder | This transaction is not permitted for the provided card/account. The customer should contact the card issuer or use a different payment method. | | 121 | Exceeds withdrawal amount limit | The payment amount exceeds the maximum allowed withdrawal limit. The customer should try a smaller amount or use a different payment method. | | 122 | Security violation | A security violation was detected with this payment. The customer should contact the card issuer for assistance. | | 123 | Exceeds withdrawal frequency limit | The maximum number of allowed withdrawals within the set time period has been exceeded. The customer should try again later or use a different payment method. | | 124 | Violation of law | This payment violates applicable laws or regulations and cannot be processed. The customer needs to use a different payment method. | | 129 | Suspected counterfeit card | The card has been flagged as potentially counterfeit. The customer should contact the card issuer immediately. | | 131 | Invalid account number | The provided account number is invalid. The customer needs to verify the account details and try again with the correct information. | | 132 | Unmatched card expiry date | The provided expiration date does not match the card issuer's records. The customer should confirm the correct expiry date and retry. | | 134 | Not sufficient funds | There are insufficient funds in the account to cover this payment. The customer should add funds to the account or use a different payment method. | | 152 | Exceeds limit | The payment amount exceeds the maximum limit allowed. The customer should try a smaller amount or use a different payment method. | | 154 | Over monthly limit | The maximum monthly payment limit has been exceeded. The customer should try again next month or use a different payment method. | | 208 | Lost Card / Lost Check | The card or check was reported as lost. The customer needs to use a different, valid payment method. | | 209 | Stolen card | The card was reported as stolen. The customer should contact the card issuer immediately and use a different payment method. | | 213 | Invalid account number for card type | The provided account number is invalid for the specified card type. The customer needs to verify the account details and retry with the correct information. | | 231 | Stop payment requested for all payments | A stop payment has been requested on this account, so no payments can be processed. The customer should contact the card issuer for assistance. | | 232 | Stop all payments – account closed | This account has been closed, so no payments can be processed. The customer needs to use a different payment method or contact support to update the account details. | | 237 | Deny – new card issued | A new card has been issued for this account. The customer needs to update the payment method with the new card details and retry. | | 302 | Account closed | The account the customer is trying to pay from is closed and cannot be used. The customer needs to update with a different, valid payment method. | | 317 | Max balance exceeded | This payment would cause the account balance to exceed the maximum allowed limit. The customer should try a smaller amount or use a different payment method. | | 351 | Customer PIN authentication required | The customer must authenticate this payment by entering the PIN. The customer should follow the prompts to complete PIN authentication. | | 414 | Void/Full Reversal request unable to process due to network cut-off window elapsed | The void or reversal request could not be processed because the network cut-off time has passed. A refund may be required instead. | | 500 | Generic error | A generic error occurred while processing this payment. The customer should try again later or use a different payment method. | | 503 | New Account Information | New account information is available for this payment method. The customer needs to update the account details and retry the payment. | | 504 | Do not try again | This payment was declined and should not be retried with this payment method. The customer needs to use an alternative method. | | 505 | Please retry | There was a temporary issue processing this payment. The customer should retry the same payment again. | | 512 | Service not allowed or invalid surcharge amount | This service or surcharge amount is not permitted for the account. The customer needs to verify the account details or try a different payment type. | | 516 | Please retry – Reasons include: Format Error, Unable to route transaction, Switch or issuer unavailable, System Busy, Timeout | A temporary issue caused this payment to fail, the customer should retry. If it continues to fail, the card issuer should be contacted. | | 517 | CVV2 Declined | The entered CVV2/CVC security code was declined. The customer should verify the code and retry with the correct information. | | 531 | Retry with 3DS data - 3D Secure authentication is required for this transaction, but not supported at this time | This card requires 3D Secure authentication which is not currently supported. The customer should use an alternative payment method or contact the card issuer. | | 528 | Debit/EBT transaction count exceeds pre-determined limit in specified time/ Withdrawal limit exceeded | The maximum allowed debit/EBT transaction count or withdrawal limit for the given time period has been exceeded. The customer should try again later or use a different payment method. | | 902 | Invalid Transaction | The payment transaction data was invalid and could not be processed. The customer needs to verify the payment details and retry. | | 907 | Card issuer or switch inoperative or processor not available | There was an issue with the card issuer's systems or payment processor during this transaction. The customer should retry later or use another payment method. | ### Network Error Category Both Visa and Mastercard send additional information about how to handle a declined payment for recurring payments. Effective May 30th, 2025 we pass through this information to help handle failures. We have added the `network` and `network_error_category` attributes to declined payments, when we get the additional information from the card networks. We are working on further classification of errors, for now please only respond to those documented here. | network | network_error_category | Definition | | ---------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | VISA | 1 | Issuer will never approve. Do not attempt again. This indicates the card is invalid, never existed or block. Cardholders can contact their bank for more information. | | VISA | 2 | Issuer cannot approve at this time. They may try again at another time. This could be related to credit risk, velocity controls, or system issues. | | VISA | 3 | Issuer cannot approve based on the details provided. This might be an invalid cvv, expiration date, etc. Do not try again without attempting to obtain additional information. | | VISA | R00/R01 | Recurring payment not allowed on card. Do not attempt again. | | MASTERCARD | 01 | Updated information needed. Similar to Visa code 3. | | MASTERCARD | 02 | Try again later. Similar to Visa code 2. | | MASTERCARD | 03 | Do not try again. Do not attempt again. Similar to Visa code 1. | | ALL | R0 | Stop this payment. Stops one specific recurring payment for one merchant and a specific card account. | | ALL | R1 | Stop all future payments. Stops all eligible transactions for one merchant and a specific card account. | | ALL | R3 | Stop all merchants. Stops all payments on a specific card account. | ## ACH Errors ACH (Automated Clearing House) transactions are transfers from the payer's bank account to the seller's bank account. If the funds can't be transferred we receive an error from the banking partners. Most of these errors are returned within 2 business days after the payment was submitted but can occur later. In the case of an error JustiFi will update the payment status to `failed` and populate the `error_description` property on the payment. To get real time notification about a failure [subscibe to the `payment.failed` event](https://docs.justifi.tech/api-spec#tag/Events). The most common ACH errors are described below. | Description | Customer Impact & Suggested Actions | |------------------------------------|-------------------------------------------------------------------------------------------------------- | | ACCOUNT_CLOSED | The cutsomer's bank account is closed and cannot be used. The customer needs to retry the payment with a different, valid payment method. | | ACCOUNT_FROZEN_OR_RETURNED_
OFAC_INSTRUCTION | The customer's bank rejected the transaction because the debit was not approved by the customer. Reach out to the customer. | | ACCOUNT_NOT_FOUND | The receiving bank rejected the transaction because the account number entered does not match an active or existing bank account. The customer needs to verify the account details and try again with the correct information. | | BENEFICIARY_OR_ACCOUNT_
HOLDER_DECEASED | The transaction was rejected because the account holder has passed away. | | CHECK_TRUNCATION_EARLY_RETURN | The electronically deposited check was not deposited successfully. The customer needs to attempt payment again. | | CORPORATE_CUSTOMER_ADVISES_
NOT_AUTHORIZED | The corporate account holder has notified their bank that the attempted ACH debit was not authorized. Reach out to the customer. | | CUSTOMER_ADVISE_INVALID_
TRANSACTION | The customer's bank rejected the debit because the account holder disputed the payment. The customer either claimed the charge was unauthorized, outside the terms of authorization, or improperly processed. | | CUSTOMER_REVOKED_AUTHORIZATION | The account holder explicitly instructed their bank to cancel the permission they previously gave to draft funds from their bank account. Reach out to the customer. | | DUPLICATE_ENTRY | The receiving bank has identified the transaction as a repeat of a previously processed payment and has rejected or reversed it. | | INSUFFICIENT_FUNDS | The bank account has insufficient funds to cover this payment. The customer should add funds to the account or use a different payment method. | INVALID_ACCOUNT_NUMBER | The provided bank account number is invalid. The customer needs to verify the account details and try again with the correct information. | | INVALID_ACH_ROUTING_NUMBER | The provided bank routing number is invalid. The customer needs to verify the account details and try again with the correct information. | | NON_TRANSACTION_ACCOUNT | The customer's bank account is restricted from processing electronic payments; it might be a savings account, money market account, loan account, etc. The customer needs to try again with a different payment method. | | PAYMENT_STOPPED | The bank account holder formally requested to cancel a specific pending or recurring transaction. Reach out to the customer. | | UNAUTHORIZED_DEBIT | The customer's bank flagged the transaction because it lacked the proper preauthorization, the amount pulled was incorrect, or funds were taken at a time the customer did not agree to. Reach out to the customer. | | UNCOLLECTED_FUNDS | The customer's account has enough total funds, but a portion of it is still processing and can't be released for the withdrawal of the payment. The payment should be retried when the account holds sufficient available funds. | | VALIDATION_ERROR | The provided transaction data fails technical or formatting requirements and the payment request was blocked by the gateway, processor, or bank before it entered the ACH network. The customer needs to verify the account details and try again with the correct information. | | ## Enhanced Fee Management JustiFi's enhanced fee management gives platforms granular control over how fees are charged and—importantly—how they are returned when processing refunds. > **New Integrations**: If you're building a new integration, use the `fees` array described below. This is the recommended approach for all new implementations. > > **Existing Integrations**: The `application_fee_amount` field continues to work unchanged. You can migrate to the new structure at your own pace—we'll provide migration support in a future release. ### Overview The enhanced fee structure separates your fees into distinct types, each tracked independently: | Fee Type | Description | |----------|-------------| | `processing_fee` | Fees related to payment processing costs | | `platform_fee` | Fees for your platform's services | This separation enables: - **Selective refunds**: Return the processing fee while keeping your platform fee, or vice versa - **Clear reporting**: Each fee type appears as a separate line item in balance transactions - **Remaining amount tracking**: Track how much of each fee can still be refunded ### Supported Endpoints | Endpoint | Request Field | Description | |----------|---------------|-------------| | [Create Payment](#tag/Payments/operation/CreatePayment) | `fees` | Specify fees when creating a payment | | [Refund a Payment](#tag/Payments/operation/CreateRefund) | `fees` | Choose which fees to return to the merchant | | [Create Checkout](#tag/Checkouts/operation/CreateCheckout) | `payment.fees` | Specify fees for the checkout | | [Refund a Checkout](#tag/Checkouts/operation/RefundCheckout) | `fees` | Choose which fees to return | ### Creating Payments with Fees **Request:** ```json POST /v1/payments { "amount": 10000, "currency": "usd", "capture_strategy": "automatic", "fees": [ { "type": "processing_fee", "amount": 350 }, { "type": "platform_fee", "amount": 500 } ], "payment_method": { "token": "pm_xyz" } } ``` **Response (Create):** > **Important:** The `fees` array will be **empty** in the Create Payment response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee objects once they are available. Alternatively, you can poll with a [Get Payment](#tag/Payments/operation/GetPayment) request. ```json { "id": "py_123xyz", "type": "payment", "data": { "id": "py_123xyz", "amount": 10000, "fee_amount": 850, "fees": [] } } ``` **Response (Webhook Events / Get Payment):** When receiving a payment webhook event or fetching a payment, the `fees` array is populated with the full fee objects: ```json { "fees": [ { "id": "pyfee_abc", "type": "processing_fee", "amount": 350, "remaining_amount": 350, "currency": "usd" }, { "id": "pyfee_xyz", "type": "platform_fee", "amount": 500, "remaining_amount": 500, "currency": "usd" } ] } ``` ### Refunding Payments with Selective Fee Return You control exactly which fees are returned to the merchant. This enables flexible refund policies. **Request:** ```json POST /v1/payments/{id}/refunds { "amount": 5000, "reason": "customer_request", "fees": [ { "type": "processing_fee", "amount": 175 } ] } ``` In this example: - $50.00 is refunded to the customer - $1.75 processing fee is returned to the merchant - The platform fee is retained **Response:** ```json { "id": "re_xyz", "type": "refund", "data": { "id": "re_xyz", "amount": 5000, "status": "succeeded", "returned_fees": [ { "id": "rtfee_xyz", "payment_fee_id": "pyfee_abc", "type": "processing_fee", "returned_amount": 175, "original_amount": 350, "remaining_amount": 175, "currency": "usd" } ] } } ``` After this refund, fetching the payment shows the updated `remaining_amount`: ```json { "fees": [ { "id": "pyfee_abc", "type": "processing_fee", "amount": 350, "remaining_amount": 175, "currency": "usd" }, { "id": "pyfee_xyz", "type": "platform_fee", "amount": 500, "remaining_amount": 500, "currency": "usd" } ] } ``` > **Note**: If no `fees` array is provided in the refund request, no fees are returned to the merchant. ### Creating Checkouts with Fees For checkouts, use the `payment.fees` field: **Request:** ```json POST /v1/checkouts { "amount": 10000, "description": "Order #12345", "payment": { "fees": [ { "type": "processing_fee", "amount": 295 }, { "type": "platform_fee", "amount": 150 } ] } } ``` **Response:** ```json { "id": "cho_xyz", "type": "checkout", "data": { "id": "cho_xyz", "payment_amount": 10000, "status": "created", "payment": { "fees": [ { "type": "processing_fee", "amount": 295 }, { "type": "platform_fee", "amount": 150 } ] } } } ``` When the checkout is completed, the fees are passed to the payment and tracked with `remaining_amount`. ### Refunding Checkouts with Fee Return **Request:** ```json POST /v1/checkouts/{id}/refunds { "amount": 5000, "fees": [ { "type": "processing_fee", "amount": 147 } ] } ``` **Response:** ```json { "id": "chr_xyz", "type": "checkout_refund", "data": { "id": "chr_xyz", "checkout_id": "cho_xyz", "status": "succeeded", "refund_amount": 5000, "returned_fees": [ { "type": "processing_fee", "amount": 147 } ] } } ``` ### Validation Rules | Rule | Error Code | Description | |------|------------|-------------| | Fee type required | `fees_invalid` | Fee type must be `processing_fee` or `platform_fee` | | Amount required | `fee_amount_greater_than_zero` | Fee amount must be an integer greater than 0 | | No duplicate types | `multiple_of_same_fee_type` | Only one fee per type is allowed | | Fees within limit | `fee_amount_greater_than_payment_amount` | Total fees cannot exceed the payment amount | | No mixing fee types | `fee_and_application_fee_declared` | Cannot use both `fees` and `application_fee_amount` | | Fee type exists | `fee_type_must_exist_on_payment_fees` | Refund fee type must exist on the original payment | | Within remaining | `returned_fee_exceeds_remaining_amount` | Refund amount cannot exceed the fee's remaining amount | ### Fee Lifecycle When using the enhanced fee structure (`fees` array), fees are handled as follows throughout the payment lifecycle: | Event | Fee Behavior | |-------|--------------| | **Payment captured** | Fees are charged and appear as separate balance transactions by type | | **Refund** | You control which fees (if any) to return via the `fees` array in the refund request | | **ACH return** | All fees are automatically returned to the merchant | | **Void** | All fees are automatically returned to the merchant | For refunds, if no `fees` array is provided in the refund request, no fees are returned—giving you full control over your refund policy. For ACH returns and voids, fee returns happen automatically since the original payment is reversed. > **Note**: Payments created with `application_fee_amount` (legacy structure) continue to behave as before—this fee lifecycle applies only to payments using the `fees` array. ### Balance Transactions Each fee type creates separate balance transaction entries for clear tracking: **When a payment is captured:** | Transaction Type | Account | Description | |------------------|---------|-------------| | `seller_payment` | Merchant | Payment amount credited | | `processing_fee` | Merchant | Processing fee deducted | | `processing_fee_credit` | Platform | Processing fee credited | | `platform_fee` | Merchant | Platform fee deducted | | `platform_fee_credit` | Platform | Platform fee credited | **When fees are returned (refund/ACH return/void):** | Transaction Type | Account | Description | |------------------|---------|-------------| | `processing_fee_return` | Merchant | Processing fee returned (credit) | | `processing_fee_return` | Platform | Processing fee return (debit) | | `platform_fee_return` | Merchant | Platform fee returned (credit) | | `platform_fee_return` | Platform | Platform fee return (debit) | ### Reporting Each fee type appears as a separate line item in: - Balance transactions for both merchants and platforms - Subaccount payout reports - Platform proceeds reports This gives merchants clear visibility into their true processing costs versus platform charges, and gives platforms detailed revenue breakdowns by fee type. ### CAD (Canadian Dollar) Payments The enhanced fee management features described above — including the `fees` array, `application_fee_amount`, and selective fee returns on refunds — are **not available for CAD payments**. For Canadian dollar payments, fees are determined during merchant onboarding and are not configurable via the API: - The `fees`, `application_fee_amount`, and `application_fees` parameters are not supported on CAD payment or checkout requests - Fee data is available via the `fees` array on the payment record (available via Get Payment API or payment events) as a `processing_fee`. The `application_fee` object will be `null` - **Balance transactions** are created when settlements are imported — not at payment capture time - The `fees` parameter on refund requests is not supported for CAD payments - When a refund incurs a processing fee, it appears in the payment's `fees` array as a `refund_processing_fee` whose `refund_id` links it to the associated refund For more details, see the [Canadian Payments guide](https://docs.justifi.tech/payments/canadianPayments). ### For Existing Integrations The `application_fee_amount` field continues to work unchanged for existing integrations. When you're ready to adopt the enhanced fee structure: 1. Replace `application_fee_amount` with the `fees` array 2. Decide how to split your fee between `processing_fee` and `platform_fee` 3. Update your refund logic to specify which fees to return You cannot use both `application_fee_amount` and `fees` in the same request. title: JustiFi API Documentation termsOfService: https://justifi.ai/terms-and-conditions x-logo: url: >- https://justifi-brand-assets.s3.us-east-2.amazonaws.com/justifi-light-bg.png contact: email: api-development@justifi.ai tags: - name: Payments description: > 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. - name: Payment Methods description: > 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. - name: Tokenize via Component description: >- The Tokenize Payment Method web component allows you to securely collect your customers' credit card and ACH (bank accout) payment methods without any sensitive data entering your system. The following guide takes you through the few simple steps of integrating the [Tokenize Payment Method web component](/web-components/payment-facilitation/tokenize-payment-method) on your platform. We assume you have an activated sub account for payment processing. *Note: If you want to charge a payment at time of payment method tokenization consider using the [Unified Fintech Checkout™ web component](https://docs.justifi.tech/api-spec#tag/Checkout-via-Component) instead.* 1. Get an access token 2. Generate a web component token 3. Render the web component 4. Handle success/failure events 5. Listen to payment method events ### Get an access token On your backend, using your client id and client secret from the Developer > API keys section of the JustiFi dashboard, generate an [access token](https://docs.justifi.tech/api-spec#tag/API-Credentials/operation/CreateAccessToken). ``` function getToken() { return fetch('https://api.justifi.ai/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ "client_id": "YOUR CLIENT ID", "client_secret": "YOUR CLIENT SECRET" }) }) .then(response => response.json()) .then(data => data.access_token); } const token = await getToken(); ``` ### Generate a web component token To render the web component you need to generate a web component token. This is a short lived token which is meant to grant short term, fine grained access. The Tokenize Payment Method web component requires the role of `write:tokenize:{accountId}` with the sub account id you are saving the payment method for. *Note: Consider setting up a [Platform Wallet Account](https://docs.justifi.tech/api-spec#tag/Platform-Wallet-Accounts) if your customers will use payment methods accross different sub accounts on your platform.* ``` async function getWebComponentToken(token, accountId) { const response = await fetch('https://api.justifi.ai/v1/web_component_tokens', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ "resources": [`write:tokenize:${accountId}] }) }); const data = await response.json(); return data.access_token; } const webComponentToken = await getWebComponentToken(token, subAccountId); ``` ### Render the web component Use the web component token generated above and the sub account id passed to the web component token API to render the [Tokenize Payment Method web component](/web-components/payment-facilitation/tokenize-payment-method). This will allow you to collect a customer's credit card or ACH payment method. It will not process a payment. ``` ``` ### Handle success/failure events The web component will emit a `submitted` event when a payment method is submitted. This event will contain the response of the [Create Payment Method API](https://docs.justifi.tech/api-spec#tag/Payment-Methods/operation/CreatePaymentMethod) which includes the payment method `token` attribute. To charge a payment to the newly tokenized payment method pass this token as payment method token to the [Payments API](https://docs.justifi.tech/api-spec#tag/Payments/operation/CreatePayment). An `error` event means there was an issue with the Tokenize Payment Method web component, connecting to the network, etc. ``` ``` At this point, the payment method has been tokenized and can be used for future payments! ### Listen to payment method events In addition to the web component events you can listen to [payment method specific events](https://docs.justifi.tech/api-spec#tag/Events) via event publisher. To set up an event publisher go to the Developer > Event Pubslisher section of the JustiFi dashboard. - name: Payment Method Groups description: > Payment method groups are a way to associate payment methods to a single group for easy access. - name: Forwarding x-displayName: Forwarding (Beta) description: > Forwarding sends a request to a third party in the shape that destination expects, with card details filled in from a payment method JustiFi already holds. You describe the body the destination expects and mark where card details go with `{{card_number}}`, `{{card_expiry_month}}`, `{{card_expiry_year}}` and `{{cardholder_name}}`. JustiFi substitutes the real values at send time, relays the headers you supply, and stores a masked copy of what was sent alongside the destination's response. Forwarding is asynchronous: creating a forwarding request returns immediately with a `pending` status, and the outcome arrives via the [`forwarding_request.completed` or `forwarding_request.failed` event](https://docs.justifi.tech/api-spec#tag/Events/operation/forwardingRequestEvent) or by retrieving the request. Destinations must be allow-listed by JustiFi before they can be used. Contact [JustiFi Customer Success](mailto:customer_success@justifi.tech) to have one added. See the [Forwarding guide](https://docs.justifi.tech/paymentMethods/forwarding) for a full walkthrough. - name: Refunds description: | When you refund a payment, a refund object is created. You can retrieve information about the refunds you've issued. - name: Disputes description: > 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. - name: Payouts description: > 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. Payouts are processed each day at 11:30am US/Central time. A Platform can also configure each sub account to have an expedited payout priority. If this is enabled, the payout will be settled on the day the payout is generated. Otherwise, standard payouts will settle the next business day. - name: Payout Holds description: > A payout hold is a resource that temporarily hold or pause payouts for a sub account. This feature is used for risk management, compliance, or business rule enforcement. Holds can be created automatically by the system (e.g., for first payments) or manually by JustiFi staff.. - name: Balance Transactions description: > Balance transactions are the reflection of any movement of funds that affects the balance of an account. Oftentimes, a single financial transaction (like a payment) will result in the creation of many balance transactions in order to document the flow of funds between multiple accounts. Other financial transactions that result in balance transactions include refunds, disputes, and payouts. - name: Ach Return Fees description: > ACH return fees are fees charged by financial institutions when an ACH (Automated Clearing House) transaction is returned due to insufficient funds or other reasons. If an ACH transaction is returned for any reason, the financial institution may charge a fee to the sender of the transaction. These fees can vary depending on the policies of the financial institution and the reason for the return. - name: Sub Accounts description: > Sub Accounts are the representation of your platform's customers for payment processing in JustiFi and are associated with your platform account. To gain approval for payment processing each of your customers need to be onboarded as a business via [web compoenent](https://docs.justifi.tech/api-spec#tag/Onboarding-via-Component), [hosted onboarding](https://docs.justifi.tech/api-spec#tag/Hosted-Onboarding) or [API](https://docs.justifi.tech/api-spec#tag/Onboarding-via-API). During the onboarding process a sub account is automatically created for each business and updated along the way. Payments can be processed through a sub account once it's status is `enabled`. | 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) | - name: Platform Wallet Accounts description: > A Platform Wallet Account allows you to store payment methods centrally and use them across multiple sub accounts within your platform. This feature enables you to maintain a single source of stored payment methods while processing payments through different sub accounts. ## Enable a Platform Wallet Account *Note: You can choose a sub account as your platform_wallet_account once it is underwritten and enabled for payments.* Contact us at [customer_success@justifi.tech](mailto:customer_success@justifi.tech) to enable the `platform_wallet_account` setting for your designated platform wallet account. ## Key Features Once enabled, you can: - Store payment methods in the designated platform wallet account - Use these payment methods across your platform's sub accounts - Group payment methods for easier management using [PaymentMethodGroups](https://docs.justifi.tech/api-spec#tag/Payment-Method-Groups), to associate multiple payment methods to your customer ## Using Platform Wallet Payment Methods *Note: While the PaymentMethods and Payments API allow you to tokenize a payment method we strongly suggest using the [Unified Fintech Checkout](/web-components/payment-facilitation/unified-fintech-checkout%E2%84%A2) or [Tokenize Payment Method](/web-components/payment-facilitation/tokenize-payment-method) web components instead to avoid PCI scope* ### 1. Manage Payment Methods Create and organize payment methods in your platform wallet account. All payment method operations require the platform wallet account ID in the Sub-Account header. ``` // Example: Create payment method group const group = await fetch('https://api.justifi.ai/v1/payment_method_groups', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Sub-Account': platformWalletAccountId, // Platform wallet account 'Content-Type': 'application/json' } }); // Example: Add payment methods to group const updatedGroup = await fetch(`https://api.justifi.ai/v1/payment_method_groups/${groupId}`, { method: 'PATCH', headers: { 'Authorization': `Bearer ${token}`, 'Sub-Account': platformWalletAccountId, // Platform wallet account 'Content-Type': 'application/json' }, body: JSON.stringify({ "payment_method_ids": ["pm_walletaccxyz", "pm_walletaccabc"] }) }); ``` ### 2. Process Payments You can process payments using wallet payment methods either through the [Unified Fintech Checkout web component](/web-components/payment-facilitation/unified-fintech-checkout%E2%84%A2) or via API #### Via Checkout Component [Checkout via Component Walkthrough](https://docs.justifi.tech/api-spec#tag/Checkout-via-Component) ``` // Create checkout const checkout = await fetch('https://api.justifi.ai/v1/checkouts', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Sub-Account': processingSubAccountId, // Processing sub account 'Content-Type': 'application/json' }, body: JSON.stringify({ "amount": 1799, "description": "Example item", "payment_method_group_id": "pmg_walletGroupId", // Group from wallet account "origin_url": "http://localhost:3000" // Required for component }) }); // Render component ``` #### Via API ``` // Create checkout const checkout = await fetch('https://api.justifi.ai/v1/checkouts', { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Sub-Account': processingSubAccountId, // Processing sub account 'Content-Type': 'application/json' }, body: JSON.stringify({ "amount": 1799, "description": "Example item", "payment_method_group_id": "pmg_walletGroupId" // Group from wallet account }) }); // Complete checkout with wallet payment method const completion = await fetch(`https://api.justifi.ai/v1/checkouts/${checkoutId}/complete`, { method: 'POST', headers: { 'Authorization': `Bearer ${token}`, 'Sub-Account': processingSubAccountId, // Processing sub account 'Content-Type': 'application/json' }, body: JSON.stringify({ "payment_token": "pm_walletPaymentMethodToken" }) }); ``` ## Updating Wallet Payment Methods - You can update a payment method via the [payment methods API](https://docs.justifi.tech/api-spec#tag/Payment-Methods/operation/UpdatePaymentMethod) - Updates should always be made to the payment method in the platform wallet account - Any changes made to the platform wallet payment method automatically propagate to all cloned payment methods across sub accounts - Available update options include: - Card expiration date - Payment method metadata - The system maintains consistency by: - Automatically syncing updates to all cloned versions of the payment method ## Important Notes - Header Requirements: - Use **platform wallet account ID** for: - Creating/managing payment methods - Creating/managing payment method groups - Use **processing sub account ID** for: - Creating checkouts - Completing payments - The system automatically: - Validates wallet payment method access - Creates payment method clones for processing sub accounts - Returns new sub account specific tokens in responses - All sub accounts must be on the same platform as the platform wallet account For complete details on specific endpoints, see: - [Checkout via Component](https://docs.justifi.tech/api-spec#tag/Checkout-via-Component) - [Checkout via API](https://docs.justifi.tech/api-spec#tag/Checkouts/operation/CreateCheckout) - [Payments API](https://docs.justifi.tech/api-spec#tag/Payments/operation/CreatePayment) - name: Onboarding via Component description: >- In order to process payments, each of your customers must be onboarded on the JustiFi platform. Once they are added they go through an approval process. JustiFi's [PaymentProvisioning web component](/web-components/entities/payment-provisioning) allows you to collect the required business and financial information from each of your customers. Once approved, your customer can process payments through JustiFi. To onboard a new business via PaymentProvisioning web component 1. Get an access token 2. Create a business 3. Generate a web component token 4. Render the Payment Provisioning web component 5. Handle success/failure events of the web component 6. Check the sub account's status ### Get an access token On your backend, using your client id and client secret from the Developer > API keys section of the JustiFi dashboard, generate an [access token](https://docs.justifi.tech/api-spec#tag/API-Credentials/operation/CreateAccessToken). ``` function getToken() { return fetch('https://api.justifi.ai/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ "client_id": "YOUR CLIENT ID", "client_secret": "YOUR CLIENT SECRET" }) }) .then(response => response.json()) .then(data => data.access_token); } const token = await getToken(); ``` ### Create a business From your backend create a business using the [Business API](https://docs.justifi.tech/api-spec#tag/Business/operation/CreateBusiness). A business only requires one parameter (e.g. `legal_name`) but you can pass as much information about your customer as you have. When you render the web component all the data you passed to the business will be pre-filled in the form and can be updated by your customer. ``` async function createBusiness(token) { const response = await fetch('https://api.justifi.ai/v1/entities/business', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ "legal_name": "First Business" }) }); const data = await response.json(); return data; } const business = await createBusiness(token); ``` ### Generate a web component token To render the PaymentProvisioning web component, you must generate a web component token. This is a short lived token which is meant to grant short term, fine grained access. The web component requires the role of `write:business:${businessId}` with the id of the business you created in the previous step. ``` async function getWebComponentToken(token, businessId) { const response = await fetch('https://api.justifi.ai/v1/web_component_tokens', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ "resources": [`write:business:${businessId}`] }) }); const data = await response.json(); return data.access_token; } const webComponentToken = await getWebComponentToken(token, business.id); ``` ### Render the PaymentProvisioning web component Using the web component token generated above and the business id, render the [PaymentProvisioning web component](/web-components/entities/payment-provisioning). This will allow your customer to provide all business information required for payment processing ``` ``` ### Handle success/failure events of the web component The web component makes an API request every time the user moves to a `Next` step and when the user submits the form. Whenever the web component receives an API response it emits a `submitted` event that contains the API response. When the form is submitted we provision the business and create a sub account for the business. The `submitted` event data will contain the response from the [Provisioning API request](https://docs.justifi.tech/api-spec#tag/Provisioning/operation/ProductProvisioning). If the provisioning request was successful the response will include the `sub_account_id` attribute of that newly created sub account. Otherwise, an error message can be presented to the user. Our example below covers both. The `error` event means there was an issue with the PaymentProvisioning form connecting to the network, etc. ``` ``` ### Check the sub account's status Once your business submits the onboarding form 1. We will provision your business for payment processing and create a `sub account` for this business as mentioned above. This sub account is the representation of your business for payment processing. 2. We'll review the submitted information. This underwriting process can take up to a few business days. Once approved the status of the sub account will be updated to `enabled` and payments can be processed. In order to check the account's onboarding status, call the [Get a Sub Account endpoint](https://docs.justifi.tech/api-spec#tag/Sub-Accounts/operation/GetSubAccount) or use an event publisher to subscribe to the [`sub_account.updated` events](https://docs.justifi.tech/api-spec#tag/Events/operation/subAccountEvent) #### Retrieve a sub account ``` async function getBusiness(token, accountId) { const response = await fetch(`https://api.justifi.ai/v1/sub_accounts/${accountId}`, { method: 'GET', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` } }); const data = await response.json(); return data; } const business = await getBusiness(toke, account.id); ``` - name: Hosted Onboarding x-traitTag: true description: > In order to process payments, each of your customers (whom we refer to as `businesses`) will have to be onboarded on our platform. Once they are added they 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 business within your platform. Once approved, your business can process payments through JustiFi. To onboard a new business via hosted onboarding: 1. Get an access token 2. Create a business 3. Generate a web component token 4. Include JustiFi Hosted Onboarding in your application 5. (optional) Listen to success/fail message 6. Check the underwriting status of the sub account connected to the business ### 1. Get an access token On your backend, using your client id and client secret from the Developer > API keys section of the JustiFi dashboard, generate an [access token](https://docs.justifi.tech/api-spec#tag/API-Credentials/operation/CreateAccessToken). ``` function getToken() { return fetch('https://api.justifi.ai/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ "client_id": "YOUR CLIENT ID", "client_secret": "YOUR CLIENT SECRET" }) }) .then(response => response.json()) .then(data => data.access_token); } const token = await getToken(); ``` ### 2. Create a business From your backend create a business using the [Business API](https://docs.justifi.tech/api-spec#tag/Business/operation/CreateBusiness). A business only requires one parameter (e.g. `legal_name`) but you can pass as much information about your customer as you have. When you render the web component all the data you passed to the business will be pre-filled in the form and can be updated by your customer. ``` async function createBusiness(token) { const response = await fetch('https://api.justifi.ai/v1/entities/business', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ "legal_name": "First Business" }) }); const data = await response.json(); return data; } const business = await createBusiness(token); ``` ### 3. Generate a web component token To render the Hosted Onboarding form, you must generate a web component token. This is a short-lived token intended to grant temporary, fine-grained access. The web component requires the role `write:business:${businessId}`, with the ID of the business created in the previous step. _Note:The web component token expires after 60 minutes. If the onboarding flow takes longer than that to complete, you’ll need to generate a new web component token and reinitialize the component with the refreshed token._ ``` async function getWebComponentToken(token, businessId) { const response = await fetch('https://api.justifi.ai/v1/web_component_tokens', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ "resources": [`write:business:${businessId}`] }) }); const data = await response.json(); return data.access_token; } const webComponentToken = await getWebComponentToken(token, business.id); ``` ### 4. Include JustiFi Hosted Onboarding in your application To present the JustiFi hosted onboarding form to your user, create an iframe with with the following source:\ `https://components.justifi.ai/onboarding?business_id=BUSINESS_ID&web_component_token=WEB_COMPONENT_TOKEN`,\ where `BUSINESS_ID` is the `business_id` that was created in step 2 and `WEB_COMPONENT_TOKEN` is the `access_token` that was created in step 3.\ 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. ### 5. (optional) Listen to success/fail message #### Listen to success/fail message ```js 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. ### 6. Check the underwriting status of the sub account connected to the business Once your business submits the onboarding form 1. We will provision your business for payment processing and create a `sub account` for this business. This sub account is the representation of your business for payment processing. 2. We'll review the submitted 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](https://docs.justifi.tech/api-spec#tag/Sub-Accounts/operation/GetSubAccount) or use an event publisher to subscribe to the [`sub_account.updated` events](https://docs.justifi.tech/api-spec#tag/Events/operation/subAccountEvent) #### Retrieve a sub account ```sh curl -X GET https://api.justifi.ai/v1/sub_accounts/ACCOUNT_ID \ -H 'Authorization: Bearer [access_token]' \ -H 'Accept: application/json' ``` ### Canada Onboarding When using a Canadian platform, the hosted onboarding form automatically adapts to collect Canada-specific information. The flow follows the same steps described above, but certain fields and requirements change based on the business's country of establishment. | Area | United States | Canada | |------|--------------|--------| | Tax ID / Business Number | Required | Optional | | SSN / SIN | Required (SSN) | Optional (SIN) | | Postal code format | 5-digit ZIP | A1A 1A1 | | State / Province | US states | Canadian provinces | | Bank identification | Routing number (9 digits) | Transit number (5 digits) + Institution number (3 digits) | | Financial documents | Voided check or bank statement | Voided check or bank letter | | Business documents | Not required | Required (articles of incorporation or business registration) | | Identity documents | Not required | Required — two per owner (one Group 1 + one Group 2) | #### Document requirements for Canada Canadian onboarding requires three categories of documents: **Financial document** — one of the following: - Voided check - Bank letter **Business document** — one of the following: - Articles of incorporation - Business registration **Identity documents** — each business owner must provide two identity documents, one from each group: *Group 1 (government-issued photo ID) — one per owner:* - Canadian passport - Canadian driver's license - Canadian government-issued ID card - Permanent resident card - Certificate of Indian Status - US state-issued driver's license *Group 2 (supporting identity document) — one per owner:* - Nexus Card (photo ID) - Canadian citizenship/naturalization card or certificate - Foreign passport - Canadian birth certificate - Social Insurance Number (SIN) card - Social Security Number (SSN) card For example, if a business has two owners, the onboarding form will require two Group 1 documents and two Group 2 documents (one of each per owner). - name: Onboarding via API description: > In order to process payments, each of your customers (whom we refer to as `businesses`) will have to be onboarded on the JustiFi platform. Once they are added they 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 businesses. Once approved, your business can process payments through JustiFi. To onboard a new business via the API 1. Create a business 2. Create a bank account 3. Upload documents 4. Accept terms and conditions 5. Provision the business 6. Check the sub account's status ### Create a business #### Create a business ```sh curl -X POST \ https://api.justifi.ai/v1/entities/business \ -H 'Authorization: Bearer {access_token}' \ -H 'Content-Type: application/json' \ -d '{ "legal_name": "Business name" }' ``` Use the business API to [create a business](https://docs.justifi.tech/api-spec#tag/Business/operation/CreateBusiness) on JustiFi that is associated with your platform. The create business API endpoint does not require any parameters but they will be required when the business is provisioned (see step 5). You will need the ID from the business you create for the next steps. ### Create a bank account Use the bank account API to [create a bank account](https://docs.justifi.tech/api-spec#tag/Bank-Account/operation/CreateBankAccount). This bank account will be used to pay out earnings for payment processing to the business. ### Upload documents Use the document API to [upload a document](https://docs.justifi.tech/api-spec#tag/Document/operation/CreateDocument). The minimum document requirement (for small businesses and sole proprietors) is a voided check. ### Accepte terms and conditions Use the terms and conditions API to [accept terms for payment processing](https://docs.justifi.tech/api-spec#tag/Terms-and-Conditions/operation/TermsAndConditions). ### Provision the business #### Provision the business for payment processing ```sh curl -X POST \ https://api.justifi.ai/v1/entities/provisioning \ -H 'Authorization: Bearer {access_token}' \ -H 'Content-Type: application/json' \ -d '{ "business_id": "biz_123", "product_category": "payment" }' ``` Once you have submitted all business related information use the provisioning API to [provision the business for payment processing](https://docs.justifi.tech/api-spec#tag/Provisioning/operation/ProductProvisioning). At this point all required parameters for payment processing are validated. An error is returned if any fields are missing. If successful, the product provisioning request will create a sub account associated with the business. The response will include the ID of that associated sub account. It is required for any payment processing related API requests. ### Check the sub account status #### Retrieve a sub account ```sh curl -X GET https://api.justifi.ai/v1/sub_accounts/ACCOUNT_ID \ -H 'Authorization: Bearer [access_token]' \ -H 'Accept: application/json' ``` Once you have provisioned the busiess, we'll review their information. This approval process can take up to a few business days. In order to check the associated sub account's onboarding status, call the [Get a Sub Account endpoint](https://docs.justifi.tech/api-spec#tag/Sub-Accounts/operation/GetSubAccount) or use an event publisher to subscribe to the `sub_account.updated` events. - name: Proceeds description: > Proceeds represent your platform's take-home portion of the fees from your sub account's financial transactions. Proceeds are batched together according to the payout schedule configured on your account, then transferred to your active bank account. Each proceeds payout also breaks down the fees behind its amount. `platform_fees_total` is what your platform charged its sub accounts, `justifi_fees_total` is what JustiFi charged your platform, and `interchange_network_fees` is the interchange and card network fees passed through to you. For most payouts, `amount` equals `platform_fees_total` minus `justifi_fees_total` plus `interchange_network_fees`. Less common entries, such as a previously failed payout being forwarded or a fee adjustment, also move the amount. JustiFi calculates these three fields shortly after the payout is created, so they are null in the `proceeds.payout.created` event. Fetch the payout again to read them. - name: Webhook Delivery x-traitTag: true description: > We offer event delivery to your app via webhooks. Webhooks are a reliable method to subscribe to our published events via an API endpoint. Webhooks are secured by signature verification, which you will need to verify by generating a SHA-256 hex using the following information: | Parameter | Header | Value | |------------|-------------------|-----------------------------------------------------------------| | Timestamp | JUSTIFI-TIMESTAMP | ISO string format | | Signature | JUSTIFI-SIGNATURE | String | | Algorithm | ----------------- | SHA-256 | | Secret Key | ----------------- | Found in your event publisher's page | | Message | ----------------- | String in the format `.` | To verify the signature simply compare the generated SHA-256 hex against it; if it is successful the webhook signature is valid. Here is a code example for reference: ```ruby def webhook_signature_valid?(signature, received_event, timestamp, secret_key) timestamp_payload = "#{timestamp}.#{received_event.to_json}" algorithm = OpenSSL::Digest.new("sha256") hex = OpenSSL::HMAC.hexdigest(algorithm, secret_key, timestamp_payload) signature == hex end ``` If you are using any of our SDKs, we provide a convenient method for validating the signature. After validating, you must respond with a `200 OK` with in **5 seconds**. In the event of a non-200 response or a delay of more than 5 seconds, delivery will be attempted again. For live accounts, webhooks are retried 10 times over 24 hours. For test accounts, webhooks are retried 3 times over 1 hour. **When you're ready to get started:** - Create the endpoint on your server that will receive published events - Add an event publisher with webhook delivery method in the **"Developers"** section of the JustiFi dashboard (www.justifi.ai -> Developers -> Event Publishers). You’ll subscribe your endpoint to the event types of your choice. We recommend starting with a test account. - Test the publisher by prompting one of the event types you chose and making sure your subscribed endpoint receives the published event - name: JustiFi Web Components description: > JustiFi Web Components offer an expanding collection of components that can be used in virtually any application, no matter the tech stack. They can be installed using NPM, or included via CDN using a script tag. To learn more, see the documentation in [our public GitHub repositiory](https://github.com/justifi-tech/web-component-library#documentation). - name: JustiFi SDK description: > We offer support for using our API via a Ruby SDK and a Node SDK. The projects are open source and available on Github. You can view full documentation on usage there. As more languages are supported, they will be added to this list: - [JustiFi Ruby SDK](https://github.com/justifi-tech/justifi-ruby) - [JustiFi Node SDK](https://github.com/justifi-tech/justifi-node) - [JustiFi Mobile SDK](https://github.com/justifi-tech/justifi-react-native-sdk) - name: Events description: > Our event publishing system allows you to subscribe to certain events on the JustiFi platform. Once subscribed, your application will be notified anytime those events occur, so you can react accordingly in real time. You can receive events via webhooks. See the [Webhook Delivery section](https://docs.justifi.tech/api-spec#tag/Webhook-Delivery) for more details. We will publish the following events: - payment.created - payment.succeeded - payment.failed - payment.pending - payment.authorized - payment.captured - payment.canceled - payment.refunded - payment.refund.updated - payment.dispute.created - payment.dispute.closed - payment_method.created - payment_method.updated - payment_method.bin_mapped - payment_method.card_present_payment_method_imported - payment_intent.attached - payment_intent.created - payment_intent.requires_capture - payment_intent.succeeded - payout.bank_account.activated - payout.created - payout.paid - payout.failed - proceeds.payout.created - sub_account.updated - application_fee_rate.created - application_fee_rate.updated - entity.business.created - entity.business.updated - entity.identity.created - entity.identity.updated - entity.address.created - entity.address.updated - entity.document.created - entity.document.uploaded - entity.bank_account.created - checkout.created - checkout.completed - checkout.completion.succeeded - checkout.completion.failed - account.payment_setting.updated - account.payout_setting.updated - terminal_order.created - terminal_order.updated - name: Business description: > Creating a business entity is an essential step in integrating your business operations with JustiFi. It is also necessary to comply with local laws and regulations governing your operations. To create a new business entity, you will need to provide basic information such as the business name, website, business type, business structure, and your industry. You may also add details like the legal address, tax ID, and ownership structure. Providing detailed and accurate information about the business entity is essential for ensuring legal compliance, financial accuracy, and it can also help avoid potential legal and financial issues. Business classification encompasses both the type of business and its operational structure. Use the following table to map your current business type and structure to the correct business classification: | Business Type | Business Structure | Business Classification | | ------------- | ------------------ | ----------------------- | | individual | * | sole_proprietor | | for_profit | unincorporated_association | sole_proprietor | | for_profit | sole_proprietorship | sole_proprietor | | for_profit | public_partnership | partnership | | for_profit | private_partnership | partnership | | for_profit | private_corporation | corporation | | for_profit | public_corporation | public_company | | for_profit | multi_llc | limited | | for_profit | single_llc | limited | | non_profit | incorporated | non_profit | | non_profit | unincorporated | non_profit | | government_entity | government_unit | government | | government_entity | government_instrumentality | government | | government_entity | tax_exempt_government_instrumentality | government | Please, choose whether you want to use the business classification (preferred) or the business type and structure (deprecated), but not both. Business classification is a simplification of business type and structure with the same goals. _Note: If you use the classification, it will not have the exact same correspondence with the business type and structure from the previous table because there are fewer classifications than types/structures._ - name: Identity description: > Creating an identity establishes a unique identification for people associated with your business. Accurately providing your information is crucial in ensuring that your identity is properly verified and maintained, and can have important consequences for a variety of financial and legal transactions. Our platform has a secure database for storing identity information, encryption and other security measures to protect your sensitive data. - name: Address description: > Creating an Address entity provides the necessary information to identify and locate a physical address. It may be associated with an Identity entity or Business entity to provide a more complete picture of the parties involved. - name: Document description: > Create/manage documents attached to your businesses and identities. When a document record is created using this API the response object returns a presigned url used to upload this document to an encrypted bucket. The presigned url can then be used to upload directly to an AWS s3 bucket, with a command like `curl -X PUT -T /path/to/file.pdf "insert presigned url"`. You must use the PUT method. This can also be accomplished from a backend or mobile app, from the browser or using our web components. After upload is complete the status changes from `pending` to `uploaded`. - name: Bank Account description: > Create/manage bank accounts for your businesses. These accounts are used for paying out earnings for usage of various products, for example card processing. - name: Terms and Conditions description: > Legally binding rules and agreements that outline the rights, responsibilities, and limitations governing the use of the platform. - name: Provisioning description: > Provisioning API for Products serves as an automated interface to configure resources based on your current entities informations, for example creating an account for card processing. - name: Payment Method Migration description: >+ ## Data Import JustiFi enables you to transfer your existing customer data and payment methods. Please contact our [Customer Success Department](mailto:customer_success@justifi.tech) to begin work with your existing processor to securely transfer your information. ### PGP Encryption Many processors utilize PGP to encrypt sensative data. You can find useful information about PGP by looking over the [GPG](http://gnupg.org/) documentation. Once you understand the basics, you will want to [import a public key](http://www.gnupg.org/gph/en/manual.html#AEN84). Please contact our [Customer Success Department](mailto:customer_success@justifi.tech) if you have any questions. #### JusitiFi's PGP migration key | | | |--|--| |**Key ID** |`A4546473910D638E`| |**User ID**|`JustiFi Import Key (PCI) support-migrations@justifi.tech`| |**Fingerprint**|`0E7C 2E45 F62D 98D7 F7B8 776B A454 6473 910D 638E`| |**Key Type**|`RSA`| |**Key Size**|4096| **PGP Public Key File**: [https://docs.justifi.tech/security/pgp-public-key.asc](/security/pgp-public-key.asc) ##### Public Key ```bash -----BEGIN PGP PUBLIC KEY BLOCK----- mQINBGS+8MwBEACibKFR3bZb4huE7piU0fX3zbLpIq+Jnvs79v5ywVMYvu1kgzbb XcA0Td2IO0PXuG/cgH4JxH1qVG+cSGjSQ0rOpoQWG5hwOrvRVH17SUQMkZxgDwQb pCo1N44L+Ij23wW3JlyVb/FbVTK6uctjPmOoonFtzMG2ObKyeTqc1yWFqaIypjvG AUG2SzgLVqTTLIE5AySyOIpHTnQUwky4J/yCaWhcEJcsQ9GFHx/e+gAlReydMxfa WhTlMf9Cjm/WaOKVVKrTVicOtfVsFSWmxgtVMK5Smo0YGyF57Oz36Axy63g3QyYs 6XhWiuqCYpnH9EYHNDZaD6G1tZMyczon/rQNtCemUJeM96eyoVi8zK9wCDQT0fQ3 06JqqQtJqI3pAdzQ/VNYwm57XzZPXpFQ7ZGW+0JWb0UfGiwHgnOd/NHsy8imMQiK FLQjsFnDKVpRgXjqiRUX2/2Qs22XKprKmr6ptNweFLwU1dW0qBkmeM2GBaq7hAdq Kx6zoPwhYMe7ZxzKO2brvBcxMexhIBYAgdZR3AIdqLWnkGBHY4A3rXYAXqBOiryA SFK9r6VKr8CihdF4sasdf0uALEOiSYzcXarc5k1rlPxD9ldXduv+RdoodoHVW//+ ID+kvQQSwVOMSF8In+9j+Hhu2Ma3BLDRAqz/Vip9vB9frUn/YyqxjoZQxQARAQAB tDpKdXN0aUZpIEltcG9ydCBLZXkgKFBDSSkgPHN1cHBvcnQtbWlncmF0aW9uc0Bq dXN0aWZpLnRlY2g+iQJXBBMBCABBAhsDBQsJCAcCAiICBhUKCQgLAgQWAgMBAh4H AheAFiEEDnwuRfYtmNf3uHdrpFRkc5ENY44FAmiEAzcFCQlorOsACgkQpFRkc5EN Y443phAAgqY1md2ygY4m/Sdrk/GaN82N7IQDx+okFrSKxtckSK2rcEz5m0GcB4fD TWAgSCgEnUz391c/Cu0KA1/r3CdmGGrLMnUeNisCYH83i+dvCVqGBsZcWn3+04Il MG14E1zgtrO3gP48sBowD8hrz1lSdz+YgfHcohrJvp7Dr/Wr78yyULcXeXZvLUsR NhAczwpQlHJi/cpGSefUidpSbAMKmgC2NNS+LvazZBikgYIZ27hLqT0nVv2nY+wd qWp4EkWNkVoNNkvpMYEzVEY7U1eb8rEH5hIibtdTPwfiaRJh0joUrAM2TjaVGzle wKOHdTc9uWxb2IN/Nh2lT2CKdRWak33Jt5rWwOaLGpP+qD2FsU0CgibrO9qDDMYt kjH8WDx78bXj9WHmvjolJT2pe6LELCxzUDPChlXmDu3jjdUYpESJdAvE17cGU28o uLkU9QgFQY5TwKfFaIqrStuSwhc+7FTdLwDObpOqfoC98J47UebE7gtLmddif/0p FLREzLdWE1sAQQnR+Ml8Vsb1+3vCE/vxusS8gx5pyscupE8H35OTe8MA36BmsQfM fbcgtt7xJ+v3EKKeJf+SNEs8xXEw5lXxngMKUXC3f2KA/Lp3pY5HixN+moDi2AdF c4Yr5B9veuHpVnCeuV64/Bzbr6OJRJYIaXON88WrRSI4uokq2V25Ag0EZL7wzAEQ AMF7UzULBsQmK4LwiuwVOcrYnN0ORQ/AXqDt09cOksDON4UzPrZxvq0FTggi9mzj U83onhtOv9mjoLYmgdaHUEhhzw167lmWbpwmD/w8PoLgmssrqUcnZH8nYsdYXpkR ZCTsd68nJdhBQLHjpnH9Ok6nB3ApiPaktIF1Z5Lu8pdPKQVSVHsEUOJ+qZM4cGXk WsqZLhmjycXnoF5ezSrUik8KwJL13fVFT7NCKagZazcCP57dNMF+sN6VZQSsvCOC jGjErIGJ6jZ4Qwdd9XVgygxtT5AEj0UakLZJZJfvO9o1ssxQ0TqOQyIj4n/45fRQ nNSWR03LubksurvduZxpaI1s8p5G3WH2mSVocV+AZV2vmcz/GAFLOS1Ik6EalRDh DVfGy5o/0D+rURs1zpcCwn1C3bib+LES9S6rnahkhzfqn1J456CxXzVtaqKJrfYq l2oYd7C18kbarzBLIlEsygWf3yJi/VnsE/2beV2fa7BtQwvdongq9w8IMPzNyXEU I/7QycB6+YURvt51bhmulSDcFcy6zL1AphLcn/2HQcQs9CMTpwc6QxBuOevgd4Hx zRIweYzwND+a8pEzIoHIsfpPkWNFOzGWTj5apE9IwbrQ4oVk+Yd7KrcbZHDLTmtd /yfAQtgGeiO7ns6APdggzKhGMTuTsLPla9zrY1aLSVOLABEBAAGJAjwEGAEIACYC GwwWIQQOfC5F9i2Y1/e4d2ukVGRzkQ1jjgUCaIQEhgUJCWiuOgAKCRCkVGRzkQ1j jkEyD/95ukg4C3XHuNLnx6D4cvCa+MCMhKL4LXH4nhRf40ChJSt88OsImE9XOhwz zWwsvfqvdzn4szitraUzK8AyYoJ5bQ4mw5KB0flw4qBbo7OZVKpLC9pP4ZDy3Z9D bGQY17uz+KMtzdMdsSgewkYpVcxS9hAqmt4CaQ2X+CWf37c4U/ljs8AOWcUYZ/s+ s9IAP+7wYmIgToqizAfFOHFiFfRbLqA3wbCJD7fiMRJqMLWY4CuMVhRY8k6erDpr HiuXBwb/f7y8Srdtq5kX5fEHw20DsVsSF5zB3rZ/smLeMTJmNWG55iLf7GPhTXA5 m36N+EhbjCYdoMPyEdBGbC2r1In/PgJuyeBX+kteD4aqY7W8QwEHFtCNVRuR3qB1 OA/fuJlKamN5N4OaCTDjNud/iWMeCi9BXdBOpGHf0iH3Un+ZyjicH2D0KaGA8FKX v8oHgP4sTR4dwkHGibvPYKX+1RwQ5/9vkJ6OpqtyuPONAjWbkz7geXPRBtQw+yg9 8aNKlI3D1nLCxDBD5nvFrl7mkK1nh/IbdOw7adRYq+8qGSOBaWCRhBmdAhCf8nz8 yKo41dXUSqDDCGBdzkc4CMMSirF63SJI6qnlvof1apzbwN3JQGSmaL1ROcIviHjs 8M9w1S9P69JkFyMzGYZExD+cHWYA10DHjM4mSWCBxZ+tC3UirA== =SSDk -----END PGP PUBLIC KEY BLOCK----- ``` #### Importing and using our key 1. Copy JustiFi's migration key into a new file named `public.key` 2. Run the GPG command to import the key. ```sh gpg --import public.key ``` 3. Encrypt your file using the newly imported key. This will create an encrypted file named `import_file.json.gpg`. ```sh gpg --encrypt --recipient A4546473910D638E import_file.json ``` - name: Fee Configurations description: > Standard Fee Configurations allow platforms to set per-sub-account fee rates that are automatically applied at payment time. Configurations are managed per fee type — creating a new configuration for the same fee type automatically retires the previous one. For a detailed guide on configurable fees, including the fee hierarchy, calculation formula, and examples, see the [Configurable Fees documentation](https://docs.justifi.tech/configurableFees/overview). - name: Terminals description: >- JustiFi provides a card present solution which allows you to collect a payment via a terminal provider via one of our technology partners. To collect a payment via terminal, you must first ensure you ask the JustiFi team to enable the card present feature for your platform. Next, we will work to provision and configure terminals for your sub accounts. Once you have configured a terminal, you must complete the following steps to complete a payment: 1. Create a Checkout 2. Send a checkout to a terminal 3. Terminal processes payment async 4. Handle checkout.completed event (recommended) 5. OR poll checkouts API for status change (optional) ### Create a checkout [Create a Checkout](https://docs.justifi.tech/api-spec#tag/Checkouts/operation/CreateCheckout) with the amount you'd like to capture, and a description of the payment. ### Send a checkout to a terminal [POST to the terminal pay endpoint](https://docs.justifi.tech/api-spec#tag/Terminals/operation/payTerminal) which will be used to send your checkout to a terminal for processing. This process can take some time as it requires customer interaction. For this reason, the API will return immediately but the process is asynchronusly happening on a terminal. ### Terminal processes payment async At this point, the process is handed over to the terminal to complete. Once the payment transaction is completed, we will publish an event for you to continue the process and take further action, as noted in the next step. ### Handle checkout.completed event Create an [Event Publisher](https://docs.justifi.tech/api-spec#tag/Events) which publishes [`checkout.completed` events](https://docs.justifi.tech/api-spec#tag/Events/operation/checkoutEvent). This will provide a means to ensure the payment was successful. You can also listen to checkout completion events, for example a checkout.completion.failed event will be published each time a card is attempted to be processed but the transaction fails for some reason. ### Poll checkouts API for status change If you do not have the ability to handle event publishing, you could poll our checkout API with the id of the checkout you are processing. Contine to poll until the checkout status attribute changes. We recommend you use the checkout events instead of this approach. - name: Terminals Orders description: | Terminals Orders API for order management - name: Checkouts description: > Checkouts can be used to collect payments directly via API, or using our Checkout component. You can use a checkout to complete a payment via JustiFi, via BNPL, via terminal, and to purchase insurance in a single transaction. All attempts to complete a payment will be recorded, along with the outcome of a payment. - name: Checkout via Component x-traitTag: true description: > A checkout is used to initiate the collection of a credit card payment, ACH payment, insurance quote payment, BNPL payment, or card reader payment in a single flow. This walk through will take you through collecting a payment via checkout using the [Unified Fintech Checkout™ web component](/web-components/payment-facilitation/unified-fintech-checkout%E2%84%A2). We assume you have an activated sub account for payment processing. For a more customized checkout experience refer to the [Modular Checkout](/web-components/modular-checkout) web component docs. 1. Get an access token 2. Create a Checkout 3. Generate a Web Component Token 4. Render the checkout component 5. Handle success/failure events ### Get an access token On your backend, using your client id and client secret from the Developer > API keys section of the JustiFi dashboard. Using those, generate an [access token](https://docs.justifi.tech/api-spec#tag/API-Credentials/operation/CreateAccessToken). ``` function getToken() { return fetch('https://api.justifi.ai/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ "client_id": "YOUR CLIENT ID", "client_secret": "YOUR CLIENT SECRET" }) }) .then(response => response.json()) .then(data => data.access_token); } const token = await getToken(); ``` ### Create a checkout From your backend create a checkout using the [Checkout API](https://docs.justifi.tech/api-spec#tag/Checkouts/operation/CreateCheckout). A checkout requires a payment `amount` and `descripton`. You can also pass a [Payment Method Group](https://docs.justifi.tech/api-spec#tag/Payment-Method-Groups) if you want a customer's pre-entered card information to be shown on the checkout. To render the checkout component, you must set the `origin_url` parameter to be the domain on which you will render the component. For example, to develop locally you could specify "http://localhost:3000" if you're developing on port 3000. ``` async function makeCheckout(token, subAccountId) { const response = await fetch('https://api.justifi.ai/v1/checkouts', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}`, 'Sub-Account': `${subAccount}`, }, body: JSON.stringify({ "amount": 1799, "description": "One Chocolate Donut", "payment_method_group_id": "(optional)", "origin_url": http://localhost:3000 }) }); const data = await response.json(); return data; } const subAccountId = "acc_5Et9iXrSSAZR2KSouQGAWi const checkout = await makeCheckout(token, subAccountId); ``` ### Generate a Web Component Token To render the checkout component, you must generate a web component token. This is a short lived token which is meant to grant short term, fine grained access. The checkout component requires the role of `write:checkout:{checkout id}` for the checkout you want to process and `write:tokenize:{account id}` with the sub account id you are processing the payment for. ``` async function getWebComponentToken(token, checkoutId, accountId) { const response = await fetch('https://api.justifi.ai/v1/web_component_tokens', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}` }, body: JSON.stringify({ "resources": [`write:checkout:${checkoutId}`, `write:tokenize:${accountId}] }) }); const data = await response.json(); return data.access_token; } const webComponentToken = await getWebComponentToken(token, checkout.id, subAccountId); ``` ### Render the checkout component Using the web component token generated above and the checkout id, render the [checkout web component](/web-components/payment-facilitation/unified-fintech-checkout%E2%84%A2). This will allow a customer to complete a checkout via credit card payment, ACH payment, or BNPL payment depending upon the sub account configuration. It will also process payments for attached insurance quotes, if the Insurance components were used. ``` ``` ### Handle success/failure events The web component will emit a `submitted` event when a payment is submitted for a checkout. This event will have a `payment_status` attribute. If the payment succeeded, your app can proceed to a successful checkout state. Otherwise, an error message can be presented to the user. Our example below covers both. If there are insurance quotes being processed, the `additional_transactions` section will contain the results of the insurance payments. An `error` event means there was an issue with the payment form, connecting to the network, etc. ``` ``` At this point, your checkout is completed and you have successfully collected a payment! - name: Checkout via API x-traitTag: true description: > A checkout is used to initiate the collection of a credit card payment, ACH payment, insurance quote payment, BNPL payment, or card reader payment in a single flow. This walk through will take you through collecting a payment via checkout. We assume you have an activated sub account for payment processing. If you want to offer BNPL or insurance as part of the checkout process you will need to implement the [Unified Fintech Checkout™](https://docs.justifi.tech/api-spec#tag/Checkout-via-Component). 1. Get an access token 2. Create a checkout 3. Tokenize or select a payment method 4. Complete a checkout ### Get an access token On your backend, using your client id and client secret from the Developer > API keys section of the JustiFi dashboard, generate an [access token](https://docs.justifi.tech/api-spec#tag/API-Credentials/operation/CreateAccessToken). ``` function getToken() { return fetch('https://api.justifi.ai/oauth/token', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ "client_id": "YOUR CLIENT ID", "client_secret": "YOUR CLIENT SECRET" }) }) .then(response => response.json()) .then(data => data.access_token); } const token = await getToken(); ``` ### Create a checkout From your backend create a checkout using the [Checkout API](https://docs.justifi.tech/api-spec#tag/Checkouts/operation/CreateCheckout). A checkout requires a payment `amount` and `descripton`. You can also pass a [Payment Method Group](https://docs.justifi.tech/api-spec#tag/Payment-Method-Groups), if you want a customer's pre-entered card information to be shown on the checkout. ``` async function makeCheckout(token, subAccountId) { const response = await fetch('https://api.justifi.ai/v1/checkouts', { method: 'POST', headers: { 'Content-Type': 'application/json', 'Authorization': `Bearer ${token}`, 'Sub-Account': `${subAccount}`, }, body: JSON.stringify({ "amount": 1799, "description": "One Chocolate Donut", "payment_method_group_id": "(optional)" }) }); const data = await response.json(); return data; } const subAccountId = "acc_5Et9iXrSSAZR2KSouQGAWi const checkout = await makeCheckout(token, subAccountId); ``` ### Tokenize or select a payment method In order to complete a checkout, you must provide a payment method token. To avoid entering PCI scope, we recommend using our [Payment Form](/web-components/payment-facilitation/tokenize-payment-method) web component. You can also collect the payment method information directly and use our Payment Method APIs, but you will likely be entering PCI scope. Once you have tokenized a payment method you can complete a checkout using the ID of the payment method as payment method token. ### Complete a checkout To complete a checkout, using the [Complete Checkout API](https://docs.justifi.tech/api-spec#tag/Checkouts/operation/CompleteCheckout) pass the payment method token collected above as well as an `Idempotency-Key`. A checkout completion will be recorded upon success or failure. If the `payment_status` attribute in the response is `succeeded` the payment has been collected. If insurance quotes have been attached, the outcome of those payments will be in the `additional_transactions` attribute. - name: Reports description: > Reports can be used to pull data for various different resources. They are CSV format, and can be filtered by date and sub account. Once a the create endpoint is called via POST, a report will be in `created` status. The report will move to `processing` status once it is being generated. Finally, when the report is generated, and the CSV file is available, the report will be in `completed` status. To download a report, you can use the `download_url` provided in the response when retrieving a report. We use presigned URLs to allow you to download the report directly from our S3 bucket. ## Report Types ### Payout Report Contains balance transaction data for payouts. | Column | Description | | ------ | ----------- | | id | Balance transaction ID | | type | Transaction type | | currency | Currency | | amount | Amount in cents | | fee | Fee amount in cents | | net | Net amount in cents | | source_id | Source object ID | | source_account_id | Source account ID | | source_type | Source object type | | source_amount | Source amount in cents | | available_on | When funds become available | | payment_id | Associated payment ID | | created_at | Creation timestamp | | payment_method_name | Payment method name | | source_payment_id | Payment ID associated with the source | | payout_id | Associated payout ID | | payout_created_at | Payout creation timestamp | | payout_deposits_at | Expected payout deposit date | ### Proceeds Report Contains platform proceeds data. | Column | Description | | ------ | ----------- | | id | Balance transaction ID | | type | Transaction type | | currency | Currency code | | amount | Amount in cents | | fee | Fee amount in cents | | net | Net amount in cents | | source_id | Source object ID | | source_account_id | Source account ID | | source_type | Source object type | | source_amount | Source amount in cents | | application_fee_amount | Application fee in cents | | platform_fee_amount | Platform fee in cents | | proceeds | Calculated proceeds in cents | | available_on | When funds become available | | created_at | Creation timestamp | | fee_major_category | Fee major category | | fee_minor_category | Fee minor category | | fee_description | Fee description | | fee_product_code | Fee product code | | fee_batch_date | Fee batch date | | payment_method_type | Payment method type | | payment_method_brand | Payment method brand | | source_payment_id | Payment ID associated with the source | | payout_id | Associated payout ID | | payout_created_at | Payout creation timestamp | | payout_deposits_at | Expected payout deposit date | - name: Payer Account Scope description: >- A request is scoped to a payer account by its path (`/v1/payables/payer_accounts/{payer_id}/…`); your token's permissions determine which payer accounts you can reach. Obtaining a token is unchanged — see [API Credentials](#tag/API-Credentials). x-traitTag: true - name: Payer Account Provisioning x-traitTag: true description: >- A **payer account** is created automatically when a platform begins provisioning Payables for one of its businesses — you don't create it through this API. It starts `pending` and becomes `active` once JustiFi's risk platform reports the business has met Payables's onboarding requirements. That bar is lighter than card/ACH payments, so a business can be Payables-ready before it is enabled for payments. **Bank account validation is asymmetric.** A payer (funding) account must be `verified` before it can fund a payment (payer accounts are validated in-app). A payee (receiving) account is not verified — it is created `not_required` and paid without upfront validation. Subscribe to `payables.payer_account.*` and `payables.bank_account.*` webhooks to follow provisioning and validation. - name: Payee Payment lifecycle x-traitTag: true description: >- A payment progresses `initiated → inbound_submitted → holding → outbound_submitted → succeeded`. There is **no automatic retry**, and where a return leaves the payment depends on whose money had already moved: a returned debit-pull means nothing settled, so the payment is `failed` and nobody is owed anything; a returned credit to the payee means the payer was already debited, so the payment goes to `refunding_payer` and then `refunded`. Subscribe to `payables.payee_payment.*` webhooks to track progress. All Payables events are namespaced under `payables.` so they never collide with JustiFi's core `payment.*` events. ### A return that arrives after a payment succeeded ACH lets a return arrive days after an entry has settled, so one can land after we have already told you a payment succeeded. **The payment moves to `failed_late_return`**, which is terminal, and a `payables.payee_payment.failed_late_return` event is delivered — so a payment you were told had succeeded can still change. Handle that in your reconciliation. **It does not mean your payee holds nothing**, and the difference matters before you act. A returned **outbound** credit means the payee never kept the money. A returned **inbound** debit-pull means the payer's funding was clawed back *after* the payee was paid — the payee still has it, and JustiFi is the one out of pocket. **Re-sending a payment on this status can pay a payee twice.** Read `transfers` to see which leg returned. What changes is the leg. Its `status` becomes `returned` and it carries the network's `network_error_code`. JustiFi works the break by hand and records the corrective movement as a **further leg on the same payment** — `purpose: recovery`, with `transfer_type: manual` where the money moved off the ACH network. The payment's `transfers` array is where you will see it, and the payment's `amount` is unchanged throughout, because the amount is what was instructed rather than a running balance. One limit to plan around: a corrective leg does not name the leg it cleared. _Payments are read and create only: a payment cannot be cancelled once initiated._ - name: Testing payment outcomes x-traitTag: true description: >- A `test` payer account runs against a simulated ACH network: no money moves, and a whole lifecycle takes about a minute instead of several banking days. By default a test payment settles and succeeds. To exercise anything else, name a scenario when you create the payment: ```json { "amount": 91000, "currency": "usd", "payee_id": "pe_...", "fees": [{ "type": "processing_fee", "amount": 1000 }], "metadata": { "simulator": { "scenario": "inbound_returned" } } } ``` `metadata` is otherwise yours to use as you like — `simulator` is the one reserved key, and it is read only for test payer accounts. A live payer account ignores it entirely. | Scenario | What the network does | Payment ends | Also | | --- | --- | --- | --- | | `settles` | both legs settle on schedule | `succeeded` | the default; omit `metadata` for the same result | | `inbound_returned` | the payer's debit-pull is returned, `R01` | `failed` | nothing settled and the payee is never paid | | `outbound_returned` | the payee's credit is returned, `R03` | `refunded` | the payer is refunded automatically. **`R03` says the account does not exist, so the payee is disabled** | | `inbound_returned_late` | the payer's funding is clawed back after the payee was paid, `R10` | `failed_late_return` | the payee keeps the money; see *A return that arrives after a payment succeeded* | | `correction_received` | the payee's bank corrects the account number, `C01` | `succeeded` | the payee is repointed at the corrected account and a `payables.bank_account.corrected` event is delivered | | `correction_received_without_data` | the payee's bank says the account is wrong and does not say what to | `succeeded` | **the payee is disabled** — we cannot correct an account the bank did not describe | | `canceled_by_provider` | the bank ends the payee's credit without a return code | `refunded` | the leg is `failed` and carries no `network_error_code` | | `submission_rejected` | the bank refuses the payer's debit outright, `R13` | `failed` | refused at submission, so no entry was ever sent | | `outbound_submission_rejected` | the bank refuses the payee's credit after the payer was debited, `R13` | `refunded` | the refund returns `amount` less `fees` | **Three of these disable the payee**, which is the same behaviour a live account would produce: a bank that refuses an account, or corrects it without saying what to, means the next payment would go to an account already refused. A disabled payee returns `400` on payment create. **Register a new receiving bank account for it to make it payable again** — that is the way back in test and in production alike, and any payment still held for the payee pays out once it is active. So a scenario that disables the payee ends your run against that payee unless you register a corrected account first. Creating one payee per scenario is the simplest way to walk several in a row. - name: API Credentials description: > Exchange your client credentials for an access token to authenticate API requests. - name: Payer Accounts description: > A payer account is the payer in Payables — a first-class entity, with its own `payer_…` id, that funding bank accounts, payees, and payments attach to. It belongs to a JustiFi business (`business_id`) under a platform (`platform_account_id`); a business holds exactly one payer account. Operate routes are scoped to a payer account in the path (`/v1/payables/payer_accounts/{payer_id}/…`); this collection and `/v1/payables/payer_accounts/{id}` are the platform-level reads. A payer account is created when a platform begins provisioning Payables and becomes `active` once JustiFi's risk platform reports the business Payables-ready (a lighter bar than payments). This API exposes payer accounts read-only. Every payer account is `test` or `live`, inherited from the JustiFi account it is provisioned under and fixed for its life. A `test` payer account runs against a simulated ACH network: payments complete in seconds rather than banking days, returns and corrections can be produced on demand, and no money moves. - name: Payees description: > Payees are the parties you send Payables payments to. A payee is standalone — it can be created and paid without being tied to a business — and carries the identity it is paid and filed against: a legal name, an IRS `entity_type`, a taxpayer identification number (an EIN, or an SSN for a sole proprietor) and an address. All four are required. The tax id is write-only; responses return `tax_id_last4`. Name, address and email are updatable; `entity_type` and `tax_id` are the taxpayer and are fixed at create. - name: Payee Bank Accounts description: > Bank accounts fund payments (the payer account's funding account) or receive them (a payee's account). Account numbers are write-only and never returned. Records are immutable — correcting an account creates a new record and supersedes the old one rather than editing it. Both kinds are readable here, but only payee receiving accounts can be **created** here. The payer account's funding account decides where money is pulled from, so it is set during provisioning and replaced by JustiFi rather than through this API. - name: Payee Payments description: > A payee payment debit-pulls the principal from the payer account's funding bank account, holds it, then credits the payee. There is no automatic retry: a returned debit-pull fails the payment, and a returned credit refunds the payer. Payments cannot be cancelled once initiated. - name: Platform Ledger description: > The platform's single-entry ledger — one entry per fee the platform earned, per JustiFi fee (payment, return handling, NOC handling), or per `settlement` paying the platform its balance, each referencing its source. Read-only and append-only; the platform's balance is the **sum** of its entries, and a `settlement` nets it toward zero. - name: Platform Settlements description: > The disbursements between JustiFi and your platform — when each happens, how much, and which way the money goes. Read-only. A settlement is declared before it is paid, so one appears here while still `scheduled`, which is what the ledger by construction cannot show you. - name: Payables Events description: > Payables delivers events to your configured endpoint as payments and bank accounts change. Return a `200` within 5 seconds; non-2xx responses are retried with backoff. x-tagGroups: - name: Authorization tags: - API Credentials - Web Component Tokens - name: For Platforms tags: - Sub Accounts - Platform Wallet Accounts - Onboarding via Component - Hosted Onboarding - Onboarding via API - Fee Configurations - Proceeds - Reports - name: Payment Resources tags: - Payments - Payment Methods - Tokenize via Component - Payment Method Groups - Refunds - Disputes - Payouts - Payout Holds - Balance Transactions - Ach Return Fees - Payment Method Migration - Forwarding - name: Checkout Resources tags: - Checkouts - Checkout via Component - Checkout via API - name: Insurance Resources tags: - Bind Insurance - name: Entity Resources tags: - Business - Identity - Address - Document - Bank Account - Terms and Conditions - Provisioning - name: Card Present Resources tags: - Terminals - Terminals Orders - name: Payables (Beta) tags: - Payer Account Scope - Payer Account Provisioning - Payee Payment lifecycle - Testing payment outcomes - Payer Accounts - Payees - Payee Bank Accounts - Payee Payments - Platform Ledger - Platform Settlements - name: Libraries tags: - JustiFi Web Components - JustiFi SDK - name: Event Publishing tags: - Events - Webhook Delivery - Payables Events paths: /sub_accounts: post: summary: Create a Sub Account (deprecated) description: > **We no longer allow new platforms to use this API. To onboard a customer so they can process payments use [Hosted Onboarding](https://docs.justifi.tech/api-spec#tag/Hosted-Onboarding) or [Onboarding via API](https://docs.justifi.tech/api-spec#tag/Onboarding-via-API) instead. During the onboarding process a sub account will automatically created for your customer.** 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. operationId: CreateSubAccount tags: - Sub Accounts parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: name: type: string example: Sub account name description: | name for the sub account *note: the name must be unique in your platform* required: - name responses: '201': description: Sub account was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: sub_account data: $ref: '#/components/schemas/SubAccount' get: summary: List Sub Accounts description: > List the sub accounts for your platform. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/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`* operationId: ListSubAccounts tags: - Sub Accounts parameters: - $ref: '#/components/parameters/authorization-header' - in: query name: status schema: type: string enum: - created - submitted - information_needed - rejected - enabled - disabled - archived required: false example: archived description: | Return accounts with specific status - in: query name: business_id schema: type: string required: false example: biz_123abc description: | Filter accounts associated with a business record responses: '200': description: Successfully list sub accounts content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/SubAccount' /sub_accounts/{id}: get: summary: Get a Sub Account description: Get information about a sub account. operationId: GetSubAccount tags: - Sub Accounts parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a sub account content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: sub_account data: $ref: '#/components/schemas/SubAccount' /sub_accounts/{id}/payout_account: get: summary: Get a Payout Account description: >- Get information about the currently active payout bank account of a sub account. operationId: GetPayoutAccount tags: - Sub Accounts parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get the active payout bank account a sub account content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: payout_bank_account data: $ref: '#/components/schemas/PayoutBankAccount' /sub_accounts/{id}/settings: get: summary: Get Sub Account Settings description: Get information about sub account settings. operationId: GetSubAccountSettings tags: - Sub Accounts parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get sub account settings content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: sub_account_settings data: $ref: '#/components/schemas/SubAccountSettings' /sub_accounts/{id}/fee_configurations: get: summary: List Fee Configurations description: > List all active Standard Fee Configurations for a sub account. Returns configurations where the current time is between `effective_start` and `effective_end` (or `effective_end` is null). This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListFeeConfigurations tags: - Fee Configurations parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/pagination-limit' - $ref: '#/components/parameters/pagination-after' - $ref: '#/components/parameters/pagination-before' responses: '200': description: Successfully list fee configurations content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/StandardFeeConfiguration' /sub_accounts/{id}/fee_configurations/scheduled: get: summary: List Scheduled Fee Configurations description: > List Standard Fee Configurations with a future `effective_start` that haven't taken effect yet. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListScheduledFeeConfigurations tags: - Fee Configurations parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/pagination-limit' - $ref: '#/components/parameters/pagination-after' - $ref: '#/components/parameters/pagination-before' responses: '200': description: Successfully list scheduled fee configurations content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/StandardFeeConfiguration' /sub_accounts/{id}/fee_configurations/{fee_type}: post: summary: Create a Fee Configuration description: > Create a Standard Fee Configuration for a specific fee type on a sub account. If an active configuration already exists for the same fee type, it is automatically retired — its `effective_end` is set to the new configuration's `effective_start`. There is no update or delete operation. To change a fee rate, create a new configuration for the same fee type. operationId: CreateFeeConfiguration tags: - Fee Configurations parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/idempotency-key-header' - name: fee_type in: path required: true description: the fee type to configure schema: type: string enum: - processing_ecomm - processing_card_present - processing_ach - processing_ach_expedited - visa_brand_ecomm - visa_brand_card_present - mastercard_brand_ecomm - mastercard_brand_card_present - amex_brand_ecomm - amex_brand_card_present - discover_brand_ecomm - discover_brand_card_present - platform example: processing_ecomm requestBody: required: true content: application/json: schema: properties: variable_rate: description: >- percentage rate applied to the payment amount. `2.75` = 2.75% type: number example: 2.75 transaction_fee_cents: description: >- flat fee in cents added to each transaction (defaults to `0`) type: integer example: 25 fee_cap_cents: description: >- maximum fee amount in cents; if the calculated fee exceeds this, the cap is used instead type: integer nullable: true example: 1000 effective_start: description: >- when the configuration takes effect (UTC); defaults to immediately type: string format: date-time example: '2026-04-01T00:00:00Z' effective_end: description: >- when the configuration expires (UTC); must be later than `effective_start`, so the current time or earlier is rejected; `null` means it stays active indefinitely. Only accepted on optional fee types (brand-specific and `platform`). type: string format: date-time nullable: true example: null required: - variable_rate responses: '201': description: Fee configuration was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: standard_fee_configuration data: $ref: '#/components/schemas/StandardFeeConfiguration' get: summary: Get a Fee Configuration description: > Get the active Standard Fee Configuration for a specific fee type on a sub account. Returns 404 if no active configuration exists for that fee type. operationId: GetFeeConfiguration tags: - Fee Configurations parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' - name: fee_type in: path required: true description: the fee type to retrieve schema: type: string enum: - processing_ecomm - processing_card_present - processing_ach - processing_ach_expedited - visa_brand_ecomm - visa_brand_card_present - mastercard_brand_ecomm - mastercard_brand_card_present - amex_brand_ecomm - amex_brand_card_present - discover_brand_ecomm - discover_brand_card_present - platform example: processing_ecomm responses: '200': description: Successfully retrieve a fee configuration content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: standard_fee_configuration data: $ref: '#/components/schemas/StandardFeeConfiguration' /sub_accounts/{id}/fee_configurations/{fee_type}/history: get: summary: Get Fee Configuration History description: > List all Standard Fee Configurations for a specific fee type on a sub account, including active, retired, and scheduled configurations. Results are ordered by `effective_start` descending. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: GetFeeConfigurationHistory tags: - Fee Configurations parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' - name: fee_type in: path required: true description: the fee type to retrieve history for schema: type: string enum: - processing_ecomm - processing_card_present - processing_ach - processing_ach_expedited - visa_brand_ecomm - visa_brand_card_present - mastercard_brand_ecomm - mastercard_brand_card_present - amex_brand_ecomm - amex_brand_card_present - discover_brand_ecomm - discover_brand_card_present - platform example: processing_ecomm - $ref: '#/components/parameters/pagination-limit' - $ref: '#/components/parameters/pagination-after' - $ref: '#/components/parameters/pagination-before' responses: '200': description: Successfully list fee configuration history content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/StandardFeeConfiguration' /proceeds: get: summary: List Proceeds description: >- List the proceeds payouts for your account. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListProceeds tags: - Proceeds parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/created-before' - $ref: '#/components/parameters/created-after' - $ref: '#/components/parameters/deposits-before' - $ref: '#/components/parameters/deposits-after' responses: '200': description: Successfully list proceeds content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/Proceed' /proceeds/{id}: get: summary: Get a Proceeds Payout description: Get information about a proceeds payout. operationId: GetProceeds tags: - Proceeds parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a proceeds payout content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: payout data: items: $ref: '#/components/schemas/Proceed' /reports/proceeds/{id}: get: deprecated: true summary: Get a Proceeds Report description: >- [DEPRECATION WARNING] This endpoint will be deprecated, please use [Reports API](#tag/Reports). operationId: GetProceedsReport tags: - Proceeds parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: >- Successfully get a link to a csv and json report for a proceeds payout content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: procceds data: $ref: '#/components/schemas/ProceedsReport' /payments: post: summary: Create a Payment description: > Authorize, capture, and charge a payment method. We limit concurrency to 10 concurrent requests per platform. This is due to the nature of the payments API, to reduce rejections, and false positive fraud detection during bulk payment processing. **Payment methods must be tokenized before creating a payment.** Tokenize payment methods use the embedded **[JustiFi Tokenize Payment Method Web Component](https://docs.justifi.tech/web-components/payment-facilitation/tokenize-payment-method)** to securely collect and tokenize card or bank account details. Once you have a payment method token (e.g. `pm_justifi123`), pass it in the `payment_method.token` field to create a payment. > **Note:** Passing raw card or bank account details directly to this endpoint requires prior approval. Contact [JustiFi Customer Success](mailto:customer_success@justifi.tech) if you have a use case that requires direct PAN submission. At minimum, a completed SAQ (Self-Assessment Questionnaire) is required to allow raw PAN submissions. *Note: If the sub account status is not `enabled`, `400` will be returned.* operationId: CreatePayment tags: - Payments parameters: - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account-required' requestBody: required: true content: application/json: schema: properties: amount: type: number example: 10000 description: amount to charge in cents currency: type: string enum: - usd - cad example: usd capture_strategy: type: string example: automatic enum: - automatic - manual description: >- automatic will authorize and capture the payment in the same request; manual will only authorize the payment. An authorized payment will need to be captured in a subsequent capture payment request. If not captured within 7 days the payment will be canceled. Not supported by bank account (ACH) payment methods. email: description: email address to associate with payment method type: string format: email payment_method: type: object properties: token: type: string description: >- A payment method token obtained from the JustiFi Tokenize Payment Method Web Component. example: pm_xyz required: - token application_fee_amount: type: integer description: > 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*). Must be greater than zero. **New integrations** should use the `fees` array instead for granular control over fee types and selective refunds. See [Enhanced Fee Management](#section/Enhanced-Fee-Management). Cannot be used together with `fees`. > **CAD Payments:** This parameter is not available for CAD payments. Fees for Canadian dollar payments are determined during merchant onboarding and are not configurable via the API. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments) for details. example: 400 fees: type: array description: > Array of fee objects to charge on this payment. See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation. Each fee object specifies: - `type`: `processing_fee` or `platform_fee` (required) - `amount`: Fee amount in cents (required) **Benefits over `application_fee_amount`:** - Separate fee types for clear reporting - Selective refunds: Choose which fees to return - Each fee type appears as a separate balance transaction Cannot be used together with `application_fee_amount`. > **Note:** The `fees` array will be empty in the create response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee details, or poll with a subsequent [Get Payment](#tag/Payments/operation/GetPayment) request. > **CAD Payments:** This parameter is not available for CAD payments. Fees for Canadian dollar payments are determined during merchant onboarding and are not configurable via the API. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments) for details. items: $ref: '#/components/schemas/Fee' example: - type: processing_fee amount: 350 - type: platform_fee amount: 500 description: type: string description: >- your meaningful description of the payment (e.g. an order number or other value from your system) example: order_xyz statement_descriptor: type: string description: >- description of the payment that will be available on the account's bank statement, must have between 5-22 alphanumeric characters and can include dash or underscore metadata: type: object format: json description: > Any useful information you'd like to store alongside this payment. **Testing Disputes**: Include `dispute_test_spec` to create test disputes: - `expected_result`: `"won"` or `"lost"` - Final dispute outcome - `reason`: Dispute reason (`"fraudulent"`, `"unrecognized"`, `"duplicate"`, `"subscription_canceled"`, `"product_unacceptable"`, `"product_not_received"`, `"processing_error"`, `"credit_not_processed"`, `"general"`) - `due_date`: Response deadline in YYYY-MM-DD format - `event_publish_delay_in_seconds`: Delay before dispute creation (default: 0) example: {} expedited: type: boolean nullable: true description: >- settlement priority of the payment, only applies to ACH payments example: null required: - amount - currency - capture_strategy - payment_method examples: Charge_10_USD_to_a_Tokenized_Payment_Method: value: amount: 1000 currency: usd capture_strategy: automatic email: example@test.com description: Charging $10 to a tokenized payment method payment_method: token: pm_justifi123 Charge_10_USD_with_Custom_Application_Fee: value: amount: 1000 application_fee_amount: 150 currency: usd capture_strategy: automatic email: example@test.com description: Charging $10 with a $1.50 application fee payment_method: token: pm_justifi123 Charge_100_USD_with_Enhanced_Fees: value: amount: 10000 currency: usd capture_strategy: automatic email: example@test.com description: Payment with enhanced fee management fees: - type: processing_fee amount: 350 - type: platform_fee amount: 500 payment_method: token: pm_justifi123 Create_Test_Dispute_Won: value: amount: 5000 currency: usd capture_strategy: automatic email: example@test.com description: Test payment that will generate a won dispute metadata: dispute_test_spec: expected_result: won reason: fraudulent due_date: '2024-02-15' event_publish_delay_in_seconds: 60 payment_method: token: pm_justifi123 Create_Test_Dispute_Lost: value: amount: 10000 currency: usd capture_strategy: automatic email: example@test.com description: Test payment that will generate a lost dispute metadata: dispute_test_spec: expected_result: lost reason: product_not_received due_date: '2024-02-20' payment_method: token: pm_justifi123 responses: '201': description: Payment was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: payment data: oneOf: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/BankAccountPayment' example: null examples: Card_payment_created: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: my order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: false returned: false status: succeeded payment_mode: ecom terminal_id: trm_123_xyz updated_at: '2021-01-01T12:00:00Z' payment_method: card: id: pm_123xyz acct_last_four: '4242' brand: visa digital_wallet: null name: Sylvia Fowles token: pm_123xyz metadata: {} bin_details: type: Debit card_brand: Visa card_class: Consumer country: United States of America issuer: WELLS FARGO BANK funding_source: Debit created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: 'null' signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] page_info: null Bank_account_payment_created: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: my order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: false returned: false status: succeeded payment_mode: ecom terminal_id: null updated_at: '2021-01-01T12:00:00Z' payment_method: bank_account: id: pm_123xyz acct_last_four: '4242' name: Sylvia Fowles brand: Wells Fargo token: pm_123xyz created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: cust_123xyz signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] page_info: null '400': description: Full card number submitted without PCI approval content: application/json: schema: allOf: - $ref: '#/components/schemas/PaymentError' examples: Full_PAN_not_allowed: value: error: code: full_pan_not_allowed message: >- Full card numbers are not accepted on this endpoint. Please use the tokenization iframe to create a payment method token first. '402': description: Error when processing the payment content: application/json: schema: allOf: - $ref: '#/components/schemas/PaymentError' example: null examples: Card_payment_error: value: error: code: card_declined decline_code: do_not_retry message: >- This card has been rejected. Please try a different card or payment method network: MASTERCARD network_error_category: '03' network_error_code: '504' get: summary: List Payments description: >- List the payments for your account. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListPayments tags: - Payments parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - $ref: '#/components/parameters/payment-method-id' - $ref: '#/components/parameters/void-id' - $ref: '#/components/parameters/created-before' - $ref: '#/components/parameters/created-after' - in: query name: payment_status schema: type: string enum: - succeeded - failed - pending - authorized - refunded - disputed required: false example: refunded description: | filter to payments which have request payment_status responses: '200': description: Successfully list payments content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/BankAccountPayment' /payments/{id}: get: summary: Get a Payment description: Get information about a payment. operationId: GetPayment tags: - Payments parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a payment content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: oneOf: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/BankAccountPayment' example: null examples: Get_a_card_payment: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: my order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: false returned: false status: succeeded payment_mode: ecom terminal_id: trm_123_xyz updated_at: '2021-01-01T12:00:00Z' payment_method: card: id: pm_123xyz acct_last_four: '4242' brand: visa name: Sylvia Fowles token: pm_123xyz metadata: {} created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: null signature: 123abc fees: - id: pyfee_abc type: processing_fee amount: 150 currency: usd remaining_amount: 150 source_configuration_id: null source_fee_type: null refund_id: null application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] page_info: null Get_a_bank_account_payment: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: my order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: false returned: false status: succeeded payment_mode: ecom terminal_id: null updated_at: '2021-01-01T12:00:00Z' payment_method: bank_account: id: pm_123xyz acct_last_four: '4242' name: Sylvia Fowles brand: Wells Fargo token: pm_123xyz created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: cust_123xyz signature: 123abc fees: - id: pyfee_abc type: processing_fee amount: 150 currency: usd remaining_amount: 150 source_configuration_id: null source_fee_type: null refund_id: null application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] page_info: null Get_a_CAD_card_payment_with_refund_fee: value: id: py_cad123 type: payment data: id: py_cad123 account_id: acc_123xyz amount_disputed: 0 amount_refunded: 5000 amount_returned: 0 amount: 10000 amount_refundable: 5000 application_fee_rate_id: null balance: 4650 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: cad description: my order xyz disputed: false error_code: null error_description: null fee_amount: 350 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: true returned: false status: partially_refunded payment_mode: ecom terminal_id: null updated_at: '2021-01-01T12:00:00Z' payment_method: card: id: pm_123xyz acct_last_four: '4242' brand: visa name: Sylvia Fowles token: pm_123xyz metadata: {} created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: null signature: 123abc fees: - id: pyfee_cad1 type: processing_fee amount: 300 currency: cad remaining_amount: 300 source_configuration_id: null source_fee_type: null refund_id: null - id: pyfee_cad2 type: refund_processing_fee amount: 50 currency: cad remaining_amount: 50 source_configuration_id: null source_fee_type: null refund_id: re_cad123 application_fee: null transaction_hold: null refunds: - id: re_cad123 payment_id: py_cad123 amount: 5000 description: customer canceled part of their order reason: customer_request status: succeeded metadata: {} returned_fees: [] created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' disputes: [] page_info: null patch: summary: Update a Payment description: | Change a payment's description or metadata. operationId: UpdatePayment parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' tags: - Payments requestBody: required: true content: application/json: schema: properties: description: type: string description: >- your meaningful description of the payment (e.g. an order number or other value from your system) example: order_xyz new description metadata: type: object format: json description: >- any useful information you'd like to store alongside this payment; when you update metadata, any previous metadata will be overwritten responses: '200': description: Payment update was successful content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: oneOf: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/BankAccountPayment' example: null examples: Update_Card_Payment: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_refunded: 0 amount_disputed: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: order xyz new description disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: false returned: false status: succeeded payment_mode: ecom updated_at: '2021-01-01T12:00:00Z' payment_method: card: id: pm_123xyz acct_last_four: '4242' brand: visa name: Sylvia Fowles token: pm_123xyz metadata: {} created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: null signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' refunds: [] disputes: [] page_info: null Update_Bank_Account_Payment: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: order xyz new description disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz checkout_id: cho_123 is_test: true metadata: {} payment_intent_id: pi_xyz refunded: false returned: false status: succeeded payment_mode: ecom updated_at: '2021-01-01T12:00:00Z' payment_method: bank_account: id: pm_123xyz acct_last_four: '4242' name: Sylvia Fowles brand: Wells Fargo token: pm_123xyz created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: cust_123xyz signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' refunds: [] disputes: [] page_info: null /payments/{id}/capture: post: summary: Capture a Payment description: > 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. If not captured an authorized payment will be canceled after 7 days. *Note: If the sub account status is not `enabled`, `400` will be returned.* operationId: CapturePayment parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' tags: - Payments responses: '200': description: Payment with identical idempotency key was captured content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: oneOf: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/BankAccountPayment' example: null examples: Card_payment_with_identical_idempotency_key_captured: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: false returned: false status: succeeded payment_mode: ecom terminal_id: trm_123_xyz updated_at: '2021-01-01T12:00:00Z' payment_method: card: id: pm_123xyz acct_last_four: '4242' brand: visa name: Sylvia Fowles token: pm_123xyz metadata: {} bin_details: type: Debit card_brand: Visa card_class: Consumer country: United States of America issuer: WELLS FARGO BANK funding_source: Debit created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: null signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] page_info: null Bank_account_payment_with_identical_idempotency_key_captured: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: false returned: false status: succeeded payment_mode: ecom terminal_id: null updated_at: '2021-01-01T12:00:00Z' payment_method: bank_account: id: pm_123xyz acct_last_four: '4242' name: Sylvia Fowles brand: Wells Fargo token: pm_123xyz created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: cust_123xyz signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] page_info: null '201': description: Payment was captured successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: oneOf: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/BankAccountPayment' example: null examples: Card_payment_captured: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: false returned: false status: succeeded payment_mode: ecom terminal_id: trm_123_xyz updated_at: '2021-01-01T12:00:00Z' payment_method: card: id: pm_123xyz acct_last_four: 4242 brand: visa name: Sylvia Fowles token: pm_123xyz metadata: {} bin_details: type: Debit card_brand: Visa card_class: Consumer country: United States of America issuer: WELLS FARGO BANK funding_source: Debit created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: null signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] page_info: null Bank_account_payment_captured: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz checkout_id: cho_123 refunded: false returned: false status: succeeded payment_mode: ecom terminal_id: null updated_at: '2021-01-01T12:00:00Z' payment_method: bank_account: id: pm_123xyz acct_last_four: '4242' name: Sylvia Fowles brand: Wells Fargo token: pm_123xyz created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: cust_123xyz signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] page_info: null /payments/{id}/refunds: post: tags: - Payments - Refunds summary: Refund a Payment description: > 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: If the sub account status is not `enabled`, `400` will be returned.* operationId: CreateRefund parameters: - in: path name: id schema: type: string format: uuid required: true - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: amount: type: number example: 10000 description: >- amount to refund; must be less than or equal to the `amount_refundable` on the payment description: description: an optional note about this refund type: string reason: description: the reason this refund is being issued type: string example: duplicate enum: - duplicate - fraudulent - customer_request fees: type: array description: > Array of fee objects to return to the merchant as part of this refund. If omitted, no fees are returned (current behavior preserved). Each fee object specifies: - `type`: The fee type to refund (`processing_fee` or `platform_fee`) - `amount`: Amount to return in cents **Validation:** - The requested amount cannot exceed the `remaining_amount` for that fee type on the original payment - The fee type must exist on the original payment > **CAD Payments:** This parameter is not available for CAD payments. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments) for details. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation. items: type: object properties: type: type: string enum: - processing_fee - platform_fee description: The type of fee to refund example: processing_fee amount: type: integer description: Amount to refund in cents example: 175 required: - type - amount example: - type: processing_fee amount: 175 metadata: type: object format: json description: >- any useful information you'd like to store alongside this refund example: {} examples: Full_refund: value: amount: 10000 reason: customer_request description: Customer requested full refund Partial_refund_with_processing_fee_return: value: amount: 5000 reason: customer_request description: Partial refund with processing fee returned fees: - type: processing_fee amount: 175 Partial_refund_with_all_fees_returned: value: amount: 5000 reason: customer_request description: Partial refund with both fees returned fees: - type: processing_fee amount: 175 - type: platform_fee amount: 250 responses: '201': description: Refund was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: refund data: $ref: '#/components/schemas/Refund' /payments/{id}/void: post: tags: - Payments - Voids summary: Void a Payment description: > Void an ecom card or ACH payment transaction to cancel the payment before it reaches settlement. Payment transactions are voidable within 25 minutes of the original transaction. This includes `authorized` payments (that were created with `capture_strategy` manual and have not been captured yet). operationId: VoidPayment parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Payment was voided successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: data: oneOf: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/BankAccountPayment' example: null examples: Card_payment_voided: value: id: py_123xyz type: payment data: id: py_123xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz refunded: false returned: false status: canceled payment_mode: ecom updated_at: '2021-01-01T12:00:00Z' payment_method: card: id: pm_123xyz acct_last_four: 4242 brand: visa name: Sylvia Fowles token: pm_123xyz metadata: {} created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: null signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' refunds: [] disputes: [] page_info: null /payments/{id}/payment_balance_transactions: get: summary: Get Payment Balance Transactions description: >- Get information about the payment-balance-transactions associated with a payment. operationId: GetPaymentBalanceTransactions tags: - Payments parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully retrieve the payment-balance-transactions for a payment content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/PaymentBalanceTransaction' /payment_methods: post: summary: Create a Payment Method description: > **This endpoint requires prior approval.** New integrations should use the **[JustiFi Tokenize Payment Method Web Component](https://docs.justifi.tech/web-components/payment-facilitation/tokenize-payment-method)** to securely collect and tokenize payment method details. The web component handles PCI-scoped data collection and returns a payment method token that you can pass to the [Create Payment](https://docs.justifi.tech/api-spec#tag/Payments/operation/CreatePayment) endpoint. If you have a use case that requires creating payment methods directly via the API, contact [JustiFi Customer Success](mailto:customer_success@justifi.tech) for approval. At minimum, a completed SAQ (Self-Assessment Questionnaire) is required to allow raw PAN submissions. *Note: If the sub account status is not `enabled`, `400` will be returned.* operationId: CreatePaymentMethod tags: - Payment Methods parameters: - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account-required' requestBody: required: true content: application/json: schema: properties: payment_method: anyOf: - type: object properties: payment_method_group_id: description: >- When present this payment method will be associated with the given payment method group type: string card: $ref: '#/components/schemas/CreateCard' bank_account: $ref: '#/components/schemas/CreateBankAccount' email: description: email address to associate with the payment method type: string format: email force_tokenize: description: >- Optional. If set to true in the request payload, allows for tokenization even if validations and authorization fail during the creation of the payment method type: boolean required: - payment_method example: null examples: Create_a_payment_method_for_card_payments: summary: Card payment method (requires SAQ approval) description: >- Requires prior approval and a completed SAQ (Self-Assessment Questionnaire). If possible use the Tokenize Payment Method Web Component instead. value: payment_method: payment_method_group_id: pmg_123xyz card: name: Lindsay Whalen number: 4242424242421111 verification: 123 month: 5 year: 2042 address_postal_code: 55555 metadata: new: info Create_a_payment_method_for_ACH_payments: summary: ACH payment method (requires SAQ approval) description: >- Requires prior approval and a completed SAQ (Self-Assessment Questionnaire). If possible use the Tokenize Payment Method Web Component instead. value: payment_method: payment_method_group_id: pmg_123xyz bank_account: account_owner_name: Lindsay Whalen routing_number: '110000000' account_number: '000123456789' account_type: checking account_owner_type: individual country: US currency: usd metadata: new: info Create_a_reusable_payment_method_for_card_payments: summary: Reusable card payment method (requires SAQ approval) description: >- Requires prior approval and a completed SAQ (Self-Assessment Questionnaire). If possible use the Payment Method Web Component instead. value: email: example@test.com payment_method: card: name: Lindsay Whalen number: 4242424242421111 verification: '123' month: 5 year: 2042 address_postal_code: '55555' metadata: new: info Create_an_expired_payment_method_for_card_payments: summary: Force tokenize expired card (requires SAQ approval) description: >- Requires prior approval and a completed SAQ (Self-Assessment Questionnaire). If possible use the Payment Method Web Component instead. value: force_tokenize: true payment_method: card: name: Lindsay Whalen number: 4242424242421111 verification: 123 month: 5 year: 2020 address_postal_code: 55555 metadata: new: info Create_payment_method_associated_with_a_payment_method_group: summary: Payment method group association (requires SAQ approval) description: >- Requires prior approval and a completed SAQ (Self-Assessment Questionnaire). If possible use the Payment Method Web Component instead. value: force_tokenize: true payment_method: payment_method_group: pmg_123xyz card: name: Lindsay Whalen number: 4242424242421111 verification: 123 month: 5 year: 2020 address_postal_code: 55555 metadata: new: info responses: '201': description: Payment method was created successfully content: application/json: schema: oneOf: - $ref: '#/components/schemas/CardResponse' - $ref: '#/components/schemas/BankAccountResponse' - $ref: '#/components/schemas/CardPresentResponse' '400': description: Full card number submitted without PCI approval content: application/json: schema: allOf: - $ref: '#/components/schemas/PaymentError' examples: Full_PAN_not_allowed: value: error: code: full_pan_not_allowed message: >- Full card numbers are not accepted on this endpoint. Please use the tokenization iframe to create a payment method token first. get: summary: List Payment Methods description: >- List the payment methods for your account. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListPaymentMethods tags: - Payment Methods parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - $ref: '#/components/parameters/customer-id' - $ref: '#/components/parameters/payment-method-group-id' - $ref: '#/components/parameters/created-before' - $ref: '#/components/parameters/created-after' responses: '200': description: Successfully list payment methods content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: anyOf: - $ref: >- #/components/schemas/CardPaymentMethodWithBinDetails - $ref: >- #/components/schemas/BankAccountPaymentMethodWithStatus - $ref: '#/components/schemas/CardPresentPaymentMethod' /payment_methods/{token}: get: summary: Get a Payment Method description: > Get information about a payment method. *Note: This is the primary endpoint recommended for retrieving bin_details related to a card payment method. bin_details are not guaranteed to be present on every card — availability depends on the card network and issuer. When unavailable, the bin_details field will be null.* operationId: GetPaymentMethod tags: - Payment Methods parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/token-path' responses: '200': description: Successfully get a payment method content: application/json: schema: oneOf: - $ref: '#/components/schemas/CardResponse' - $ref: '#/components/schemas/BankAccountResponse' - $ref: '#/components/schemas/CardPresentResponse' patch: summary: Update a Payment Method description: | Change a payment method's expiration date, address, or metadata. operationId: UpdatePaymentMethod parameters: - $ref: '#/components/parameters/token-path' - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' tags: - Payment Methods requestBody: required: true content: application/json: schema: properties: card: $ref: '#/components/schemas/UpdateCard' responses: '200': description: Payment method update was successful content: application/json: schema: oneOf: - $ref: '#/components/schemas/CardResponse' - $ref: '#/components/schemas/BankAccountResponse' - $ref: '#/components/schemas/CardPresentResponse' /payment_methods/{token}/clone: post: summary: Clone a Payment Method description: > 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. operationId: ClonePaymentMethod parameters: - $ref: '#/components/parameters/token-path' - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' tags: - Payment Methods requestBody: required: true content: application/json: schema: properties: destination_account_id: type: string description: >- The sub account id to which the payment method should be cloned example: acc_xyz123 responses: '200': description: Payment method clone was successful content: application/json: schema: oneOf: - $ref: '#/components/schemas/CardResponse' - $ref: '#/components/schemas/BankAccountResponse' - $ref: '#/components/schemas/CardPresentResponse' /forwarding/requests: post: summary: Create a Forwarding Request description: > Send a request to an allow-listed destination with card details filled in from a payment method JustiFi already holds. You describe the request the destination expects, and write `{{card_number}}`, `{{card_expiry_month}}`, `{{card_expiry_year}}` or `{{cardholder_name}}` wherever card details belong. JustiFi substitutes them at send time. A tag must be the **entire** value of its field. A tag inside a longer string (`"num:{{card_number}}"`), an unknown tag (`{{card_expiry}}`) and `{{card_cvc}}`, which JustiFi does not store, are all rejected with `invalid_parameter`. **This endpoint responds before anything leaves JustiFi.** The forwarding request is created with `status` `pending` and a `null` `response`. Poll [Get a Forwarding Request](https://docs.justifi.tech/api-spec#tag/Forwarding/operation/GetForwardingRequest) or listen for the [`forwarding_request.completed` and `forwarding_request.failed` events](https://docs.justifi.tech/api-spec#tag/Events/operation/forwardingRequestEvent) for the outcome. Destinations are allow-listed by JustiFi and matched exactly — no trailing slash, casing or query normalization is applied. Contact [JustiFi Customer Success](mailto:customer_success@justifi.tech) to have a destination added. Only card payment methods can be forwarded. Bank accounts and card-present payment methods are rejected with `payment_method_type_not_supported`, and digital wallet cards with `digital_wallet_not_supported`. *Note: no `Sub-Account` header is needed. The account is inferred from the payment method.* operationId: CreateForwardingRequest tags: - Forwarding parameters: - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: type: object properties: payment_method: description: > the id of the card payment method whose details are substituted into the request body type: string example: pm_123xyz url: description: > the destination to send the request to. Must match an allow-listed destination exactly type: string example: https://api.stripe.com/v1/payment_methods forwarding_request: description: the request to send to the destination type: object properties: body: description: > the request body the destination expects, as a JSON object. Use `{{card_number}}`, `{{card_expiry_month}}`, `{{card_expiry_year}}` and `{{cardholder_name}}` where card details belong; each tag must be the entire value of its field. JustiFi encodes the body in the format the destination expects type: object headers: description: > headers to relay to the destination, including the credentials it requires. Values must be strings. JustiFi stores none of its own credentials for the destination and adds only `Content-Type`, and only when you leave it out type: object additionalProperties: type: string required: - body required: - payment_method - url - forwarding_request example: null examples: Forward_a_card_to_a_destination: summary: Forward a card to an allow-listed destination value: payment_method: pm_123xyz url: https://api.stripe.com/v1/payment_methods forwarding_request: body: type: card card: number: '{{card_number}}' exp_month: '{{card_expiry_month}}' exp_year: '{{card_expiry_year}}' billing_details: name: '{{cardholder_name}}' metadata: reference: ord_9f21 headers: Authorization: Bearer sk_live_destination_key responses: '201': description: > The forwarding request was accepted and queued. Nothing has been sent to the destination yet, so `status` is `pending` and `response` is `null`. content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: forwarding_request data: $ref: '#/components/schemas/ForwardingRequest' '400': description: The request was rejected. Nothing was created and nothing was sent. content: application/json: schema: allOf: - $ref: '#/components/schemas/PaymentError' examples: Destination_not_allow_listed: value: error: code: forwarding_destination_not_allowed message: That destination is not on the forwarding allow list Payment_method_type_not_supported: value: error: code: payment_method_type_not_supported message: Only card payment methods can be forwarded Digital_wallet_not_supported: value: error: code: digital_wallet_not_supported message: Digital wallet payment methods cannot be forwarded Invalid_card_tag: value: error: code: invalid_parameter message: >- A card tag must be the entire value of its field and one of {{card_number}}, {{card_expiry_month}}, {{card_expiry_year}}, {{cardholder_name}} Body_is_not_a_json_object: value: error: code: forwarding_request_body_invalid message: forwarding_request.body must be a JSON object Headers_are_not_a_string_map: value: error: code: forwarding_request_headers_invalid message: >- forwarding_request.headers must be an object of string values '404': description: No payment method with that id exists. content: application/json: schema: allOf: - $ref: '#/components/schemas/PaymentError' examples: Payment_method_not_found: value: error: code: payment_method_not_found message: Payment method not found get: summary: List Forwarding Requests description: > List the forwarding requests for a sub account, newest first. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListForwardingRequests tags: - Forwarding parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - $ref: '#/components/parameters/payment-method-id' - $ref: '#/components/parameters/created-before' - $ref: '#/components/parameters/created-after' responses: '200': description: Successfully list forwarding requests content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/ForwardingRequest' /forwarding/requests/{id}: get: summary: Get a Forwarding Request description: > Retrieve a forwarding request, and the destination's response once there is one. While `status` is `pending` or `processing`, `response` is `null`. Once `status` is `completed`, `response` holds the status code, body and headers the destination answered with — a `completed` forwarding request means the destination answered, not that it accepted the request, so check `response.status_code`. Once `status` is `failed`, `response` stays `null` and `failure_reason` explains why the destination could not be reached. Card details are never returned in readable form. The card number renders as its last four digits in `request.body`, every value in `request.headers` renders as `[FILTERED]`, and anything in the destination's response that looks like a card number is reduced to its last four digits. operationId: GetForwardingRequest tags: - Forwarding parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - $ref: '#/components/parameters/id-path' responses: '200': description: Successfully get forwarding request content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: forwarding_request data: $ref: '#/components/schemas/ForwardingRequest' '404': description: No forwarding request with that id exists on this sub account. content: application/json: schema: allOf: - $ref: '#/components/schemas/PaymentError' examples: Forwarding_request_not_found: value: error: code: forwarding_request_not_found param: forwarding_request_id /payment_method_groups: post: summary: Create a Payment Method Group description: > You can create payment methods groups ahead of time, then associate payment methods and easily filter them. operationId: CreatePaymentMethodGroup tags: - Payment Method Groups parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account-required' responses: '201': description: Payment method group was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: payment_method_group data: $ref: '#/components/schemas/PaymentMethodGroupResponse' get: summary: List Payment Method Groups description: | List payment method groups associated to an account operationId: ListPaymentMethodGroup tags: - Payment Method Groups parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' responses: '200': description: Successfully list payment method groups content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: - $ref: '#/components/schemas/PaymentMethodGroupResponse' /payment_method_groups/{id}: get: summary: Get a Payment Method Group description: | Get payment method group associated to an account operationId: GetPaymentMethodGroup tags: - Payment Method Groups parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - $ref: '#/components/parameters/id-path' responses: '200': description: Successfully get payment method group content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: payment_method_group data: $ref: '#/components/schemas/PaymentMethodGroupResponse' patch: summary: Update a Payment Method Group description: | Updates a payment method group to associate payment methods operationId: PatchPaymentMethodGroup tags: - Payment Method Groups parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - $ref: '#/components/parameters/id-path' requestBody: required: true content: application/json: schema: properties: payment_method_ids: type: array description: >- Payment method ids to be associated with the payment method group example: - pm_123xyz - pm_456abc items: type: uuid responses: '200': description: Payment method group update successful /payment_method_groups/{id}/payment_methods/{payment_method_id}: delete: summary: Remove a Payment Method from a Payment Method Group description: | Removes a payment method from a payment method group operationId: RemovePaymentMethodFromGroup tags: - Payment Method Groups parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - $ref: '#/components/parameters/id-path' - name: payment_method_id in: path required: true description: ID of the payment method to remove schema: type: string format: uuid example: pm_123xyz responses: '200': description: Payment method successfully removed from group /payouts: get: summary: List Payouts operationId: ListPayouts tags: - Payouts parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/created-before' - $ref: '#/components/parameters/created-after' - $ref: '#/components/parameters/deposits-before' - $ref: '#/components/parameters/deposits-after' responses: '200': description: Successfully list payouts content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/Payout' /payouts/{id}: get: summary: Get a Payout description: Get information about a payout. operationId: GetPayout tags: - Payouts parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a payout content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: payout data: $ref: '#/components/schemas/Payout' patch: summary: Update a Payout description: Change a payout's metadata. operationId: UpdatePayout parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' tags: - Payouts requestBody: required: true content: application/json: schema: properties: metadata: type: object format: json description: >- any useful information you'd like to store alongside this payout; when you update metadata, any previous metadata will be overwritten example: customer_payout_id: cp_12345 responses: '200': description: Payout update was successful content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: payout data: $ref: '#/components/schemas/Payout' /reports/payouts/{id}: get: deprecated: true summary: Get a Payout CSV Report description: >- [DEPRECATION WARNING] This endpoint will be deprecated, please use [Reports API](#tag/Reports). operationId: GetPayoutCsvReport tags: - Payouts parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a link to a csv report for a payout content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: payout data: $ref: '#/components/schemas/PayoutCsvReport' /payout_holds: get: summary: List Payout Holds description: >- List the payout holds that belong to this account. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListPayoutHolds tags: - Payout Holds parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/created-before' - $ref: '#/components/parameters/created-after' - $ref: '#/components/parameters/start-date-before' - $ref: '#/components/parameters/start-date-after' - $ref: '#/components/parameters/end-date-before' - $ref: '#/components/parameters/end-date-after' responses: '200': description: Successfully list payout holds content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/PayoutHold' /payout_holds/{payout_hold_id}: get: summary: Get a Payout Hold description: Retrieve a specific payout hold by ID. operationId: GetPayoutHold tags: - Payout Holds parameters: - $ref: '#/components/parameters/payout-hold-id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a payout hold content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: payout_hold data: $ref: '#/components/schemas/PayoutHold' /balance_transactions: get: summary: List Balance Transactions description: >- List the balance transactions for your account. This API is limited to a single sub account or payout. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListBalanceTransactions tags: - Balance Transactions parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - in: query name: payout_id schema: type: string required: false example: po_123xyz description: | Filter records which are part of the payout with the specified id - in: query name: source_payment_id schema: type: string required: false example: py_123xyz description: > Filter records which are associated with the payment with the specified id responses: '200': description: Successfully list balance transactions content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/BalanceTransaction' /balance_transactions/{id}: get: summary: Get a Balance Transaction description: Get information about a balance transaction. operationId: GetBalanceTransaction tags: - Balance Transactions parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a balance transaction content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: balance_transaction data: $ref: '#/components/schemas/BalanceTransaction' /refunds: get: summary: List Refunds description: >- List the refunds for your account. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListRefunds tags: - Refunds parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' responses: '200': description: Successfully list refunds content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/Refund' /refunds/{id}: get: summary: Get a Refund description: Get information about a refund. operationId: GetRefund tags: - Refunds parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a refund content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: refund data: $ref: '#/components/schemas/Refund' patch: summary: Update a Refund description: Update the refund metadata. operationId: UpdateRefund parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' tags: - Refunds requestBody: required: true content: application/json: schema: properties: metadata: type: object format: json description: >- any useful information you'd like to store alongside this refund; when you update metadata, any previous metadata will be overwritten responses: '200': description: Refund update was successful content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: refund data: $ref: '#/components/schemas/Refund' /oauth/token: post: summary: Generate Access Token description: > 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}`. **Note: These access tokens are meant only for backend-to-backend calls. If you are looking to authorize a web component, please see the Web Component Token API** operationId: CreateAccessToken tags: - API Credentials requestBody: required: true content: application/json: schema: properties: client_id: type: string example: test_clientId description: the client id for your (live or test) account client_secret: type: string example: test_clientSecret description: the client secret for your (live or test) account example: client_id: test_clientId client_secret: test_clientSecret responses: '200': description: An access token has been granted content: application/json: schema: type: object properties: access_token: description: > an access token to pass to our API as the `Authorization` header with `Bearer` appended before the token, e.g. `Bearer {access_token}` type: string servers: - url: https://api.justifi.ai /disputes: get: summary: List Disputes description: > Any disputes associated with a payment are also included in the response of the [get payment API](https://docs.justifi.tech/api-spec#tag/Payments/operation/GetPayment) and the [list payments API](https://docs.justifi.tech/api-spec#tag/Payments/operation/ListPayments) response operationId: ListDisputes tags: - Disputes parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' responses: '200': description: Successfully list disputes content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/Dispute' /disputes/{id}: get: summary: Get a Dispute description: Get information about a dispute. operationId: GetDispute tags: - Disputes parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a dispute content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: dispute data: $ref: '#/components/schemas/Dispute' patch: summary: Update a Dispute description: Change a dispute's metadata. operationId: UpdateDispute parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' tags: - Disputes requestBody: required: true content: application/json: schema: properties: metadata: type: object format: json description: >- any useful information you'd like to store alongside this dispute; when you update metadata, any previous metadata will be overwritten responses: '200': description: Dispute update was successful content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: dispute data: $ref: '#/components/schemas/Dispute' /disputes/{id}/evidence: put: summary: Create dispute evidence description: > Creates dispute evidence and generate presigned url > ⚠️ **Not available for Canada accounts** > > The dispute response and evidence endpoints are not available for Canada accounts. operationId: CreateDisputeEvidence parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' tags: - Disputes requestBody: required: true content: application/json: schema: required: - file_name - file_type - dispute_evidence_type properties: file_name: type: string example: receipt.pdf description: dispute evidence file name file_type: type: string description: dispute evidence file type example: application/pdf enum: - image/jpeg - image/png - application/pdf - application/zip - application/x-zip-compressed dispute_evidence_type: type: string description: >- dispute evidence type matching the file that will be uploaded example: receipt enum: - cancellation_policy - customer_communication - customer_signature - duplicate_charge_documentation - receipt - refund_policy - service_documentation - shipping_documentation - uncategorized_file description: type: string description: >- description of the dispute evidence file that will be uploaded metadata: type: object format: json description: >- any useful information you'd like to store alongside the dispute evidence responses: '201': description: Dispute evidence created and presigned url generated content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: dispute evidence data: $ref: '#/components/schemas/DisputeEvidence' /disputes/{id}/response: patch: summary: Update dispute response description: > Updates the dispute response > ⚠️ **Not available for Canada accounts** > > The dispute response and evidence endpoints are not available for Canada accounts. operationId: UpdateDisputeResponse parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' tags: - Disputes requestBody: required: true content: application/json: schema: properties: additional_statement: type: string description: any additional evidence or statements cancellation_policy_disclosure: type: string description: >- an explanation of how and when the customer was shown your cancellation policy prior to purchase cancellation_rebuttal: type: string description: >- a justification for why the customer’s subscription was not canceled customer_billing_address: type: string description: the billing address provided by the customer customer_email_address: type: string description: the email address of the customer customer_name: type: string description: the name of the customer customer_purchase_ip_address: type: string description: >- the IP address that the customer used when making the purchase duplicate_charge_explanation: type: string description: >- an explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate product_description: type: string description: a description of the product or service that was sold refund_policy_disclosure: type: string description: >- documentation demonstrating that the customer was shown your refund policy prior to purchase refund_refusal_explanation: type: string description: >- justification for why the customer is not entitled to a refund service_date: type: string description: >- the date on which the customer received or began receiving the purchased service example: '2024-10-31' shipping_address: type: string description: the address to which a physical product was shipped shipping_carrier: type: string description: >- the delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas shipping_date: type: string description: >- the date on which a physical product began its route to the shipping address example: '2024-10-31' shipping_tracking_number: type: string description: >- the tracking number for a physical product. If multiple tracking numbers were generated for this purchase, please separate them with commas duplicate_charge_original_payment_id: type: string description: >- the payment id for the prior charge which appears to be a duplicate of the disputed charge responses: '200': description: Dispute response updated content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: dispute response data: $ref: '#/components/schemas/DisputeResponse' post: summary: Submit dispute response description: > Submits the dispute response > ⚠️ **Not available for Canada accounts** > > The dispute response and evidence endpoints are not available for Canada accounts. operationId: SubmitDisputeResponse parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' tags: - Disputes requestBody: required: true content: application/json: schema: required: - forfeit properties: forfeit: type: boolean description: >- when true forfeits the dispute and all other parameters passed in are ignored additional_statement: type: string description: any additional evidence or statements cancellation_policy_disclosure: type: string description: >- an explanation of how and when the customer was shown your cancellation policy prior to purchase cancellation_rebuttal: type: string description: >- a justification for why the customer’s subscription was not canceled customer_billing_address: type: string description: the billing address provided by the customer customer_email_address: type: string description: the email address of the customer customer_name: type: string description: the name of the customer customer_purchase_ip_address: type: string description: >- the IP address that the customer used when making the purchase duplicate_charge_explanation: type: string description: >- an explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate product_description: type: string description: a description of the product or service that was sold refund_policy_disclosure: type: string description: >- documentation demonstrating that the customer was shown your refund policy prior to purchase refund_refusal_explanation: type: string description: >- justification for why the customer is not entitled to a refund service_date: type: string description: >- the date on which the customer received or began receiving the purchased service example: '2024-10-31' shipping_address: type: string description: the address to which a physical product was shipped shipping_carrier: type: string description: >- the delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas shipping_date: type: string description: >- the date on which a physical product began its route to the shipping address example: '2024-10-31' shipping_tracking_number: type: string description: >- the tracking number for a physical product. If multiple tracking numbers were generated for this purchase, please separate them with commas duplicate_charge_original_payment_id: type: string description: >- the payment id for the prior charge which appears to be a duplicate of the disputed charge responses: '200': description: Dispute response submitted content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: dispute data: $ref: '#/components/schemas/Dispute' /insurance/bind: post: summary: Bind an Insurance Policy description: | Used to bind an insurance policy with a JustiFi insurance partner operationId: BindInsurance tags: - Bind Insurance parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: payment_method_id: type: string format: uuid example: pm_123 description: Payment method to charge for insurance policy amount: type: number example: 10000 description: amount to charge in cents currency: type: string enum: - usd - cad example: usd partner_quote_id: type: string example: ins-test-123 description: quote id provided by partner provider partner_name: type: string enum: - vertical_insure example: vertical_insure description: partner insurance provider metadata: type: object format: json description: >- any useful information you'd like to store alongside this record example: {} required: - payment_method_id - amount - partner_quote_id - partner_name responses: '201': description: Insurance Policy was bound successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: id: example: ins_xyz type: example: insurance_policy data: $ref: '#/components/schemas/InsurancePolicy' /entities/business: post: summary: Create a Business description: | Create a Business operationId: CreateBusiness tags: - Business parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: legal_name: type: string example: Business Name description: >- legal business entity name; must be unique among the active businesses on your platform. Archived businesses do not reserve their name, so an archived business's legal_name can be reused website_url: type: string example: https://justifi.ai description: >- website for this business (if they don't have a website, can send their social media business page, app store link, or a product description instead) email: type: string example: business@justifi.ai description: email address of business entity or representative phone: type: string example: '6124011111' description: business phone number doing_business_as: type: string example: Best Business description: >- only needed if registered with DBA/Trade Name on SS-4 tax document business_type: type: string enum: - for_profit - non_profit - government_entity - individual description: >- (deprecated) use classification instead - see [classification mapping table](https://docs.justifi.tech/api-spec#tag/Business) business_structure: type: string enum: - sole_proprietorship - single_llc - multi_llc - private_partnership - private_corporation - unincorporated_association - public_partnership - public_corporation - incorporated - unincorporated - government_unit - government_instrumentality - tax_exempt_government_instrumentality description: >- (deprecated) use classification instead - see [classification mapping table](https://docs.justifi.tech/api-spec#tag/Business) classification: type: string enum: - government - limited - non_profit - partnership - corporation - public_company - sole_proprietor description: >- simplified classification, use instead of business_type and business_structure - see [classification mapping table](https://docs.justifi.tech/api-spec#tag/Business) industry: type: string example: Big Business description: >- to help us identify this business entity's category code (MCC), please provide a concise description of what service they offer mcc: type: string example: '8021' description: >- merchant category code for this business, if known. Please note, the JustiFi underwriting team may modify this. If you are unsure, just submit a description in the industry field instead of an MCC tax_id: type: string description: >- the federal tax identification number/EIN issued to this sub account by the IRS (for Individual type, this will be their full SSN), the value is saved but not returned in any API response date_of_incorporation: type: string example: '2015-02-20' description: >- the specific day when this business was officially registered with a relevant government authority and was then permitted to carry out its activities country_of_establishment: type: string enum: - USA - CAN example: USA description: >- country where the business was established. Defaults to "USA" if not provided (_cannot be changed after creation_) metadata: type: object description: >- any useful information you'd like to store alongside this business additionalProperties: true example: arr: 1200 social_network: '@business' additional_questions: additionalProperties: true $ref: '#/components/schemas/AdditionalQuestions' legal_address: oneOf: - $ref: '#/components/schemas/Address' - type: object properties: id: type: string example: addr_xyz representative: oneOf: - $ref: '#/components/schemas/Identity' - type: object properties: id: type: string example: idty_xyz owners: type: array description: up to four business owners total items: oneOf: - $ref: '#/components/schemas/Identity' - type: object properties: id: type: string example: idty_xyz responses: '201': description: Business entity was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: business data: $ref: '#/components/schemas/BusinessResponse' get: summary: List Businesses description: > List businesses for your platform. Archived businesses are not returned. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListBusinesses tags: - Business parameters: - $ref: '#/components/parameters/authorization-header' - in: query name: business_name schema: type: string required: false example: '"Company Name"' description: filter businesses by name responses: '200': description: Successfully list businesses content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/BusinessResponse' /entities/business/{id}: patch: summary: Update a Business description: Update information about a Business operationId: UpdateBusiness tags: - Business parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: archived: type: boolean example: true description: >- set to true to archive this business. Test mode businesses can always be archived. A live mode business can only be archived while it has not been provisioned; once a product has been provisioned for it, or a sub account is associated with it, archiving returns an error. Archiving frees the business's legal_name for reuse, so setting this back to false returns an error if another active business on your platform has taken that name in the meantime legal_name: type: string example: Business Name description: legal business entity name website_url: type: string example: https://justifi.ai description: >- website for this business (if they don't have a website, can send their social media business page, app store link, or a product description instead) email: type: string example: business@justifi.ai description: email address of business entity or representative phone: type: string example: '6124011111' description: business phone number doing_business_as: type: string example: Best Business description: >- only needed if registered with DBA/Trade Name on SS-4 tax document business_type: type: string enum: - for_profit - non_profit - government_entity - individual business_structure: type: string enum: - sole_proprietorship - single_llc - multi_llc - private_partnership - private_corporation - unincorporated_association - public_partnership - public_corporation - incorporated - unincorporated - government_unit - government_instrumentality - tax_exempt_government_instrumentality industry: type: string example: Big Business description: >- to help us identify this business entity's category code (MCC), please provide a concise description of what service they offer mcc: type: string example: '8021' description: >- merchant category code for this business, if known. Please note, the JustiFi underwriting team may modify this. If you are unsure, just submit a description in the industry field instead of an MCC tax_id: type: string description: >- the federal tax identification number/EIN issued to this sub account by the IRS (for Individual type, this will be their full SSN), the value is saved but not returned in any API response date_of_incorporation: type: string example: '2015-02-20' description: >- the specific day when this business was officially registered with a relevant government authority and was then permitted to carry out its activities metadata: type: object description: >- any useful information you'd like to store alongside this business additionalProperties: true example: arr: 1200 social_network: '@business' additional_questions: additionalProperties: true $ref: '#/components/schemas/AdditionalQuestions' legal_address: oneOf: - $ref: '#/components/schemas/Address' - type: object properties: id: type: string example: addr_xyz representative: oneOf: - $ref: '#/components/schemas/Identity' - type: object properties: id: type: string example: idty_xyz responses: '200': description: Successfully update a business content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: business data: $ref: '#/components/schemas/BusinessResponse' get: summary: Get a Business description: Get information about a Business operationId: GetBusiness tags: - Business parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a business content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: business data: $ref: '#/components/schemas/BusinessResponse' /entities/identity: post: summary: Create an Identity description: | Create an Identity operationId: CreateIdentity tags: - Identity parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: name: type: string example: Person Name description: legal name title: type: string example: President description: job title email: type: string example: person.name@justifi.ai description: email address phone: type: string example: '6124011111' description: phone number dob_day: type: string example: '01' description: two-digit birth day dob_month: type: string example: '01' description: two-digit birth month dob_year: type: string example: '1980' description: four-digit birth year (must be at least 18 years old) identification_number: type: string example: '123456789' description: full social security number is_owner: type: boolean example: true description: >- if an identity owns 25% or more of the business, they are considered an owner ownership_percentage: type: integer minimum: 0 maximum: 100 example: 25 description: >- percentage of the business owned by this identity (0–100); applies when is_owner is true metadata: type: object description: >- any useful information you'd like to store alongside this identity additionalProperties: true example: language: english social_network: '@person' address: oneOf: - $ref: '#/components/schemas/Address' - type: object properties: id: type: string example: addr_xyz responses: '201': description: Identity was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: identity data: $ref: '#/components/schemas/IdentityResponse' get: summary: List Identities description: > List identities for your platform. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListIdentities tags: - Identity parameters: - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully list identities content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/IdentityResponse' /entities/identity/{id}: patch: summary: Update an Identity description: Update information about an Identity operationId: UpdateIdentity tags: - Identity parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: name: type: string example: Person Name description: legal name title: type: string example: President description: job title email: type: string example: person.name@justifi.ai description: email address phone: type: string example: '6124011111' description: phone number dob_day: type: string example: '01' description: two-digit birth day dob_month: type: string example: '01' description: two-digit birth month dob_year: type: string example: '1980' description: four-digit birth year (must be at least 18 years old) identification_number: type: string example: '123456789' description: full social security number is_owner: type: boolean description: >- if an identity owns 25% or more of the business, they are considered an owner ownership_percentage: type: integer minimum: 0 maximum: 100 example: 25 description: >- percentage of the business owned by this identity (0–100); applies when is_owner is true metadata: type: object description: >- any useful information you'd like to store alongside this identity additionalProperties: true example: language: english social_network: '@person' responses: '200': description: Identity updated content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: identity data: $ref: '#/components/schemas/IdentityResponse' get: summary: Get an Identity description: Get information about an Identity operationId: GetIdentity tags: - Identity parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Get Identity content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: identity data: $ref: '#/components/schemas/IdentityResponse' /entities/address: post: summary: Create an Address description: | Create an Address operationId: CreateAddress tags: - Address parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: line1: type: string example: 123 Example St line2: type: string example: '# 61157' city: type: string example: Minneapolis state: type: string example: MN postal_code: type: string example: '55555' country: type: string example: USA responses: '201': description: Address was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: address data: $ref: '#/components/schemas/AddressResponse' get: summary: List Addresses description: > List addresses for your platform. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListAddresses tags: - Address parameters: - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully list addresses content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/AddressResponse' /entities/address/{id}: patch: summary: Update an Address description: Update information about an Address operationId: UpdateAddress tags: - Address parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: line1: type: string example: 123 Example St line2: type: string example: '# 61157' city: type: string example: Minneapolis state: type: string example: MN postal_code: type: string example: '55555' country: type: string example: USA responses: '200': description: Address updated content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: address data: $ref: '#/components/schemas/AddressResponse' get: summary: Get an Address description: Get information about an Address operationId: GetAddress tags: - Address parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Get Address content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: address data: $ref: '#/components/schemas/AddressResponse' /entities/document: post: summary: Create a Document description: > Create a reference to a document, and receive a presigned URL for uploading the document operationId: CreateDocument tags: - Document parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: description: type: string example: My Document file_name: type: string example: the_file_name file_type: type: string example: application/pdf description: >- the file media type/extension of the file you are uploading. For example, text/plain, application/pdf, image/png document_type: type: string enum: - articles_of_incorporation - balance_sheet - bank_statement - birth_certificate - business_registration - citizenship_card - driver_license - foreign_passport - government_id - nexus_card - passport - profit_and_loss_statement - resident_card - sin_card - ssn_card - status_card - tax_return - voided_check - other example: balance_sheet business_id: type: string format: uuid example: biz_abc123 description: >- the business id to associate with this document (one of business id or identity id is required) identity_id: type: string format: uuid example: idty_abc123 description: >- the identity id to associate with this document (one of business id or identity id is required) metadata: type: object description: >- any useful information you'd like to store alongside this document example: my_id: '123' required: - file_name - file_type - document_type responses: '201': description: Document was created and presigned successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: document data: $ref: '#/components/schemas/Document' get: summary: List Documents description: >- List the documents you have uploaded. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListDocuments tags: - Document parameters: - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully list documents content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/Document' /entities/document/{id}: get: summary: Get a Document description: Get details about a document, and a presigned download URL operationId: GetDocument tags: - Document parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Get Document content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: document data: $ref: '#/components/schemas/Document' /entities/bank_accounts: post: summary: Create a Bank Account description: | Create a bank account operationId: CreateBankAccount tags: - Bank Account parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: account_owner_name: type: string description: name of the account owner example: Napheesa Collier account_type: type: string description: type of account enum: - checking - savings example: checking account_number: type: string description: the account number example: '000123456789' routing_number: type: string description: routing number example: '110000000' business_id: type: string description: business id which owns the account format: uuid example: biz_abc123 bank_name: type: string description: bank name example: Wells Fargo nickname: type: string description: nickname for the bank account example: Phee's Money metadata: type: object description: >- any useful information you'd like to store alongside this bank account example: my_id: '123' required: - account_owner_name - account_type - account_number - routing_number - business_id - bank_name responses: '201': description: Bank Account was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: bank_account data: $ref: '#/components/schemas/EntityBankAccount' get: summary: List Bank Accounts description: >- List the bank accounts you have created for a business. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListBankAccounts tags: - Bank Account parameters: - $ref: '#/components/parameters/authorization-header' - in: query name: business_id schema: type: string required: false example: biz_xyz description: filter bank accounts which are associated with a business responses: '200': description: Successfully list bank accounts content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/EntityBankAccount' /entities/bank_accounts/{id}: get: summary: Get a Bank Account description: Get details about a bank account operationId: GetBankAccount tags: - Bank Account parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Get Bank Account content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: bank_account data: $ref: '#/components/schemas/EntityBankAccount' /entities/terms_and_conditions: post: summary: Terms and Conditions description: | Accept current Terms and Conditions operationId: TermsAndConditions tags: - Terms and Conditions parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: business_id: type: string example: biz_xyz description: business id accepted: type: boolean example: true description: accepts terms and conditions ip: type: string example: 142.250.219.46 description: client ip address user_agent: type: string example: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Safari/605.1.15 description: client identification information required: - business_id - accepted - ip responses: '201': description: Terms and Conditions successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: onboarding data: properties: id: description: unique terms and conditions id type: string format: uuid example: tac_xyz business_id: type: string example: biz_xyz accepted: type: boolean example: true ip: type: string example: 142.250.219.46 user_agent: type: string example: >- Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1 Safari/605.1.15 /entities/provisioning: post: summary: Product Provisioning description: > Product Provisioning An archived business cannot be provisioned. Un-archive it first by sending `archived: false` to the update business endpoint. operationId: ProductProvisioning tags: - Provisioning parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: business_id: type: string example: biz_123 description: business associated with the account product_category: type: string example: payment description: type of product to be provisioned required: - business_id - product_category responses: '201': description: Provisioning successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: onboarding data: $ref: '#/components/schemas/ProvisioningResponse' /ach_return_fees/{id}: get: summary: Get an Ach Return Fee description: Get information about ach return fee. operationId: GetAchReturnFee tags: - Ach Return Fees parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get an ach return fee content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: account_ach_return_fee data: $ref: '#/components/schemas/AchReturnFee' /terminals/pay: post: summary: Pay via Terminal description: >- Send a checkout to be processed via terminal, listen for checkout events (recommended) or poll checkout API for payment outcome operationId: payTerminal tags: - Terminals parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: payment_intent_id: type: string format: uuid example: pi_abc123 description: > (deprecated, use checkout id) id for the payment intent which you want to process via terminal checkout_id: type: string format: uuid example: cho_abc123 description: | id of the checkout which you want to process via terminal terminal_id: type: string format: uuid example: trm_abc123 description: > id of the terminal on which you want to process a transaction required: - checkout_id - terminal_id responses: '201': description: Checkout sent to terminal for processing content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: terminal_sessions id: example: tses_FQz6I0hMTrcU9Ur7TpOPZ data: properties: id: type: string format: uuid example: tses_FQz6I0hMTrcU9Ur7TpOPZ session_type: type: string example: payment status: type: string example: created payment_id: type: string format: uuid example: py_abc123 payment_intent_id: type: string format: uuid terminal_id: type: string format: uuid example: trm_abc123 account_id: type: string format: uuid example: acc_abc123 platform_account_id: type: string format: uuid example: acc_abc123 checkout_id: type: string format: uuid example: cho_abc123 /terminals: get: summary: List Terminals operationId: listTerminals tags: - Terminals parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - in: query name: status schema: type: string enum: - connected - disconnected - unknown - pending_configuration - archived required: false example: active description: > filter records by the terminal status. Accepts multiple comma separated status values. - in: query name: terminal_id schema: type: string required: false example: trm_abc123 description: | filter records by terminal id - in: query name: provider_id schema: type: string required: false example: '23456789' description: > filter records by provider id, also called device id (DID). Accepts multiple comma separated provider ids. - in: query name: terminal_order_id schema: type: string required: false example: tord_123xyz description: | filter records by terminal order id - in: query name: verified_after schema: type: string format: date-time required: false example: '2024-01-01T00:00:00Z' description: > filter records which were verified after the date and time (UTC) specified. Dates without time specified will default to 00:00:00 - in: query name: verified_before schema: type: string format: date-time required: false example: '2024-01-01T00:00:00Z' description: > filter records which were verified before the date and time (UTC) specified. Dates without time specified will default to 00:00:00 - in: query name: verified_on schema: type: string format: date required: false example: '2024-01-01' description: > filter records which were verified on the date specified between 00:00:00 and 23:59:59 (UTC) responses: '200': description: Successfully list terminals content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/Terminal' /terminals/{id}: get: summary: Get a Terminal operationId: getTerminal tags: - Terminals parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a terminal content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: terminal data: $ref: '#/components/schemas/Terminal' patch: summary: Update a Terminal operationId: updateTerminal tags: - Terminals parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: nickname: type: string description: terminal nickname example: My Favorite Terminal responses: '200': description: Successfully update a terminal content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: terminal data: $ref: '#/components/schemas/Terminal' /terminals/{id}/status: get: summary: Get Terminal Status operationId: getTerminalStatus tags: - Terminals parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get terminal status content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: terminal data: $ref: '#/components/schemas/TerminalStatus' /terminals/{id}/identify: post: summary: Identify Terminal operationId: postIdentifyTerminal description: | This API will attempt to display the nickname or serial number on the screen of the given terminal for 20 seconds. tags: - Terminals parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '204': description: The request was sent to the terminal /terminals/orders/{id}: get: summary: Get Terminals Order operationId: GetTerminalsOrder description: Get information about terminals order tags: - Terminals Orders parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' responses: '200': description: Successfully get a terminal order content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: terminals_order data: $ref: '#/components/schemas/TerminalsOrder' /terminals/orders: get: summary: List Terminal Orders description: >- Retrieve a list of terminal orders for your account. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListTerminalsOrders tags: - Terminals Orders parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/created-before' - $ref: '#/components/parameters/created-after' - in: query name: order_type schema: type: string enum: - boarding_only - boarding_shipping required: false example: boarding_only description: | filter terminal orders of a specific type - in: query name: order_status schema: type: string enum: - created - submitted - completed required: false example: created description: | filter terminal orders of a specific status - in: query name: sub_account_id schema: type: string required: false example: acc_123xyz description: | filter terminal orders of a specific sub account responses: '200': description: Successful response content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: terminals_orders data: type: array items: $ref: '#/components/schemas/TerminalsOrder' post: summary: Order Terminals description: Order (one or multiple) terminals from one of our technology partners operationId: terminalsOrder tags: - Terminals Orders parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: business_id: type: string format: uuid example: biz_abc123 description: id of the business entity ordering a terminal sub_account_id: type: string format: uuid example: acc_abc123 description: >- id of the account all terminals from this order will be associated order_type: type: string enum: - boarding_only - boarding_shipping example: boarding_only order_items: type: array description: list of terminals being ordered items: type: object properties: model_name: type: string enum: - V400m - P400 - E285 example: V400m quantity: type: integer example: 1 required: - business_id - sub_account_id - provider - order_type - order_items responses: '201': description: Successful place a Terminal Order content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: terminals_order data: $ref: '#/components/schemas/TerminalsOrder' /web_component_tokens: post: summary: Generate A Token description: > The web component token provides permission to render a web component on your frontend. To get a web component token post your [access token](https://docs.justifi.tech/api-spec#tag/API-Credentials/operation/CreateAccessToken) in the header and the `business_id` or `account_id` as part of the `resources` array in the body. For a list of resources needed for each web component please refer to [Roles need for each component](https://docs.justifi.tech/infrastructure/webComponentTokens#roles-need-for-each-component). The token will be valid for 60 minutes. operationId: CreateWebComponentToken tags: - Web Component Tokens parameters: - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: resources: type: array description: >- Build an array of concatenated role (read/write), resource (account/business) and resource id which you need the web component to access. For example ["write:business:biz_123"] items: type: string example: resources: - write:business:biz_abc - write:account:account_123 responses: '200': description: A web component token has been created content: application/json: schema: type: object properties: access_token: description: > Use this field in the `auth-token` parameter of the web component you would like to render type: string expires_in: description: | The amount of seconds until the token expires type: number token_type: description: | Type of token, this will always return Bearer type: string /checkouts: post: summary: Create a Checkout description: > Create a checkout to initiate the collection of a Card Payment, ACH Payment, Insurance Quote Payment, BNPL Payment (not yet available via API), or Card Reader payment in a single flow. Checkouts have the following statuses: `created` after creating a checkout, `attempted` when a checkout payment is attempted, `completed` when a payment is collected for a checkout, `expired` when a checkout has not been completed after one week since being created operationId: CreateCheckout tags: - Checkouts parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account-required' requestBody: required: true content: application/json: schema: properties: amount: type: number example: 10000 description: >- amount to charge in cents, must be an integer greater than 50 (equivalent to $0.50) description: type: string description: >- your meaningful description of the checkout (e.g. an order number or other value from your system) example: order_xyz origin_url: type: string description: >- the domain on which the web component will be rendered, required for web component usage only example: http://localhost:3000 payment_method_group_id: type: string description: payment method group to associate with the checkout example: pmg_xyz123 statement_descriptor: type: string description: >- description of the payment that will be available on the account's bank statement, must have between 5-22 alphanumeric characters and can include dash or underscore example: Big Business metadata: type: object format: json description: >- any useful information you'd like to store alongside this checkout example: {} application_fees: type: object description: >- Sets a custom application fee amount by payment method type. **New integrations** should use `payment.fees` instead for selective refund support. See [Enhanced Fee Management](#section/Enhanced-Fee-Management). (card/ach and card present only, not available for bnpl). **Not available for CAD payments** — fees are determined during merchant onboarding. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments). properties: card: type: object properties: amount: type: number description: >- custom application fee amount that applies to card payment method. example: 300 bank_account: type: object properties: amount: type: number description: >- custom application fee amount that applies to bank account payment method. example: 150 payment: type: object description: >- Overrides the information saved on the Payment when a checkout is paid via JustiFi card/ach payment properties: description: type: string description: >- Overrides the default payment description of "Checkout [checkout id]" example: Pay David for great work metadata: type: object format: json description: Adds metadata to the payment record example: {} expedited: type: boolean description: >- settlement priority of the payment, only applies to ACH payments fees: type: array description: > *Recommended for new integrations.* Fees to apply to the payment. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation. Each fee object specifies: - `type`: `processing_fee` or `platform_fee` (required) - `amount`: Fee amount in cents (required) Cannot be used together with `application_fees`. > **Note:** The `fees` array will be empty in the create response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee details, or poll with a subsequent Get Payment request. > **CAD Payments:** This parameter is not available for CAD payments. Fees for Canadian dollar payments are determined during merchant onboarding and are not configurable via the API. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments) for details. items: $ref: '#/components/schemas/Fee' example: - type: processing_fee amount: 350 - type: platform_fee amount: 500 required: - amount - description responses: '201': description: Checkout was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: checkout data: $ref: '#/components/schemas/Checkout' get: summary: List Checkouts description: >- List Checkouts for your account. This endpoint supports [pagination](https://docs.justifi.tech/api-spec#section/Pagination). operationId: ListCheckouts tags: - Checkouts parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - in: query name: payment_mode schema: type: string enum: - bnpl - ecom - card_present - apple_pay required: false example: bnpl description: | the mode in which the checkout was completed - in: query name: status schema: type: string enum: - created - completed - attempted - expired required: false example: completed description: | the checkout status - in: query name: payment_status schema: type: string enum: - succeeded - failed - canceled - skipped - pending required: false example: succeeded description: | the status of the payment which was use to complete the checkout responses: '200': description: Successfully list checkouts content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: $ref: '#/components/schemas/Checkout' /checkouts/{id}: get: summary: Get Checkout description: Get information about a checkout operationId: GetCheckout tags: - Checkouts parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' responses: '200': description: Successfully get a checkout content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: checkout data: $ref: '#/components/schemas/Checkout' patch: summary: Update a Checkout description: Change a checkout's amount or description operationId: UpdateCheckout parameters: - $ref: '#/components/parameters/id-path' - $ref: '#/components/parameters/authorization-header' tags: - Checkouts requestBody: required: true content: application/json: schema: properties: amount: type: number example: 10000 description: >- amount to charge in cents, must be an integer greater than 50 (equivalent to $0.50) description: type: string description: >- your meaningful description of the checkout (e.g. an order number or other value from your system) example: order_xyz statement_descriptor: type: string description: >- description of the payment that will be available on the account's bank statement, must have between 5-22 alphanumeric characters and can include dash or underscore example: Big Business metadata: type: object format: json description: >- any useful information you'd like to store alongside this checkout; when you update metadata, any previous metadata will be overwritten application_fees: type: object description: >- (card/ach and card present only, not available for bnpl) sets a custom application fee amount that applies to this payment, instead of relying on application fee rates configured at the platform account level. Must be greater than zero. properties: card: type: object properties: amount: type: number description: >- custom application fee amount that applies to card payment method. example: 300 bank_account: type: object properties: amount: type: number description: >- custom application fee amount that applies to bank account payment method. example: 150 payment: type: object description: >- Overrides the information saved on the Payment when a checkout is paid via JustiFi card/ach payment properties: description: type: string description: >- Overrides the default payment description of "Checkout [checkout id]" example: Pay David for great work metadata: type: object format: json description: Adds metadata to the payment record example: {} expedited: type: boolean description: >- settlement priority of the payment, only applies to ACH payments fees: type: array description: > *Recommended for new integrations.* Fees to apply to the payment. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation. Each fee object specifies: - `type`: `processing_fee` or `platform_fee` (required) - `amount`: Fee amount in cents (required) Cannot be used together with `application_fees`. > **Note:** The `fees` array will be empty in the create response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee details, or poll with a subsequent Get Payment request. > **CAD Payments:** This parameter is not available for CAD payments. Fees for Canadian dollar payments are determined during merchant onboarding and are not configurable via the API. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments) for details. items: $ref: '#/components/schemas/Fee' example: - type: processing_fee amount: 350 - type: platform_fee amount: 500 responses: '200': description: Checkout update was successful content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: object data: $ref: '#/components/schemas/Checkout' /checkouts/{id}/complete: post: summary: Complete a Checkout description: > Use to complete a checkout and capture a payment, requires an idempotency key for payment processing operationId: CompleteCheckout tags: - Checkouts parameters: - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' requestBody: required: true content: application/json: schema: properties: payment_token: type: string example: pm_asdfakjsd23 description: >- Payment Method token which you want to use to complete the payment payment_mode: type: string example: ecom enum: - ecom - bnpl - card_present - apple_pay description: >- The mode in which the checkout is being completed. If not provided, defaults to `ecom` required: - payment_token examples: Complete_a_checkout: value: payment_token: pm_asdfakjsd23 payment_mode: ecom responses: '201': description: Checkout was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: checkout_completion data: $ref: '#/components/schemas/CheckoutCompletion' /checkouts/{id}/refunds: post: summary: Refund a Checkout description: > Use to refund a checkout. You may refund the full amount or just a portion. When refunding a portion, multiple refunds are supported up until the full payment amount has been refunded. operationId: RefundCheckout tags: - Checkouts parameters: - $ref: '#/components/parameters/idempotency-key-header' - $ref: '#/components/parameters/authorization-header' requestBody: required: false content: application/json: schema: properties: amount: type: integer example: 4900 description: >- Amount to be refunded. If missing, the total amount will be used. fees: type: array description: > Fees to return to the merchant as part of this refund. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation. Each fee object specifies: - `type`: The fee type to return (`processing_fee` or `platform_fee`) - `amount`: Amount to return in cents If omitted, no fees are returned. Only supported for card/ach and card present payments completed with the `fees` array. > **CAD Payments:** This parameter is not available for CAD payments. See [Canadian Payments](https://docs.justifi.tech/payments/canadianPayments) for details. items: type: object properties: type: type: string enum: - processing_fee - platform_fee description: The type of fee to return example: processing_fee amount: type: integer description: Amount to return in cents example: 175 required: - type - amount examples: Partial_refund: value: amount: 1000 fees: - type: processing_fee amount: 100 - type: platform_fee amount: 100 responses: '200': description: Refund was created successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: checkout_completion data: $ref: '#/components/schemas/CheckoutRefund' /reports: post: summary: Create a report description: | Create a report for any of the available report types operationId: CreateReport tags: - Reports parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' requestBody: required: true content: application/json: schema: anyOf: - $ref: '#/components/schemas/ReportInterchangeFeeParameters' - $ref: '#/components/schemas/ReportProceedsParameters' - $ref: '#/components/schemas/ReportPayoutParameters' - $ref: '#/components/schemas/ReportSubAccountSummaryParameters' - $ref: '#/components/schemas/ReportPaymentListParameters' responses: '200': description: Report was queued successfully content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: report data: $ref: '#/components/schemas/Report' get: summary: List Reports description: | List all generated reports operationId: ListSubAccounts tags: - Reports parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - in: query name: nickname schema: type: string required: false example: '"My Report"' description: | the nickname of the report responses: '200': description: Successfully list reports content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope-list' - properties: type: example: array data: items: $ref: '#/components/schemas/Report' /reports/{id}: get: summary: Get a report description: Get and generate the download url for a report operationId: GetReport tags: - Reports parameters: - $ref: '#/components/parameters/authorization-header' - $ref: '#/components/parameters/sub-account' - $ref: '#/components/parameters/id-path' responses: '200': description: Successfully get a report content: application/json: schema: allOf: - $ref: '#/components/schemas/Envelope' - properties: type: example: refund data: $ref: '#/components/schemas/Report' /payables/payer_accounts: get: summary: List Payer Accounts description: > List the payer accounts your credentials can access — the platform-level (Tier 2) read backing the cross-account view and account switcher; scoped credentials return only the ones they cover. Payer accounts are provisioned when a platform onboards a business — there is no customer-facing create endpoint. operationId: PayablesListPayerAccounts tags: - Payer Accounts parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: query name: after_cursor description: >- token to fetch the next page of a list (the `end_cursor` from a previous response's `page_info`) schema: type: string - in: query name: before_cursor description: >- token to fetch the previous page of a list (the `start_cursor` from a previous response's `page_info`) schema: type: string - in: query name: limit description: the number of resources to retrieve per page (default 25, max 100) schema: type: integer default: 25 minimum: 1 maximum: 100 - in: query name: status required: false schema: type: string enum: - pending - active - disabled - archived description: filter payer accounts by status - in: query name: business required: false schema: type: string example: biz_123xyz description: >+ filter to the payer accounts belonging to a single business. Use this to resolve a business's payer account(s) from the `biz_…` id you already hold — a business holds one payer account, so it returns a single record. - in: query name: name required: false schema: type: string example: northside description: > filter payer accounts to those whose `name` contains this value, case-insensitively. Partial matches count, so `northside` matches "Northside Physical Therapy" — this backs the type-ahead in the account switcher rather than an exact-name lookup. - in: query name: payer_id required: false schema: type: string example: payer_123xyz description: > filter to a single payer account by its `payer_…` id. Matches exactly; an id that is not a `payer_…` id is rejected with `400`. responses: '200': description: Successfully listed payer accounts content: application/json: schema: allOf: - type: object description: >- the standard JustiFi response envelope for a list of records properties: id: description: >- always null for list responses — a list has no id of its own; the ids are on `data` type: 'null' type: description: the object type type: string example: array data: description: the list of objects type: array items: type: object page_info: type: object description: cursor pagination info properties: start_cursor: description: >- the encoded id of the first record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd end_cursor: description: >- the encoded id of the last record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd has_next: description: >- true if there are records following the current page type: boolean default: false has_previous: description: >- true if there are records ahead of the current page type: boolean default: false required: - id - type - data - page_info - properties: type: example: array data: type: array items: type: object description: > A payer account is the payer in Payables — a first-class Payables entity with its own `payer_…` id. Every payee, bank account, and payment is scoped to one payer account. Each payer account belongs to a JustiFi business (`business_id`). The record is created (`pending`) when a platform begins provisioning Payables, and becomes `active` once JustiFi's risk platform reports the business has met Payables's onboarding requirements — a lighter bar than our payments-processing product, so a business can be Payables-ready before it is enabled for payments. The customer-facing API exposes payer accounts read-only. properties: id: description: unique payer account id type: string example: payer_123xyz type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payer_account business_id: description: > the JustiFi business this payer account belongs to. Requests operate *within* a payer account (see the `/v1/payables/payer_accounts/{payer_id}/…` routes); `business_id` records the owning business for reporting and cross-account grouping, it is not the request scope. Discover a business's payer accounts with `GET /v1/payables/payer_accounts?business=biz_…`. type: string example: biz_123xyz name: description: display name for the payer account type: string example: Northside Physical Therapy mode: description: > whether this payer account operates against real money. Inherited from the JustiFi account it belongs to — a test account and a live account are different accounts with different ids, so a payer account is one or the other for its life and cannot be switched. In `test`, payments run against a simulated ACH network: they complete in seconds rather than banking days, and no money moves. type: string enum: - test - live example: live status: description: > the payer account's Payables lifecycle state, and what each state prevents. `pending` — provisioning has begun but the risk platform has not yet reported the business Payables-ready; `active` — Payables-ready, and the only state under which anything can be created; `disabled` — was active previously, and can no longer schedule payments, create payees or register bank accounts; `archived` — the same, and permanent: an archived payer account cannot be reactivated. A payment whose payee credit is already held is not paid out while the account is not `active`. It stays held until the account is active again, rather than failing. type: string enum: - pending - active - disabled - archived example: active provisioned_at: description: >- when the payer account was provisioned to use Payables; null until provisioning completes type: string nullable: true format: date-time example: '2026-01-01T12:00:00Z' funding_bank_account_id: description: > pointer to the payer account's active funding bank account. In this version a payer account has a single active funding account. Null until one is registered and verified. type: string nullable: true example: ba_fund456 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '400': description: > The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: bad_request message: payee pe_abc123 is archived and cannot be paid '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/payer_accounts/{id}: get: summary: Get a Payer Account description: Retrieve a single payer account by its `payer_…` id. operationId: PayablesGetPayerAccount tags: - Payer Accounts parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: id schema: type: string required: true description: the id of the resource responses: '200': description: Successfully retrieved the payer account content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: payer_account data: type: object description: > A payer account is the payer in Payables — a first-class Payables entity with its own `payer_…` id. Every payee, bank account, and payment is scoped to one payer account. Each payer account belongs to a JustiFi business (`business_id`). The record is created (`pending`) when a platform begins provisioning Payables, and becomes `active` once JustiFi's risk platform reports the business has met Payables's onboarding requirements — a lighter bar than our payments-processing product, so a business can be Payables-ready before it is enabled for payments. The customer-facing API exposes payer accounts read-only. properties: id: description: unique payer account id type: string example: payer_123xyz type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payer_account business_id: description: > the JustiFi business this payer account belongs to. Requests operate *within* a payer account (see the `/v1/payables/payer_accounts/{payer_id}/…` routes); `business_id` records the owning business for reporting and cross-account grouping, it is not the request scope. Discover a business's payer accounts with `GET /v1/payables/payer_accounts?business=biz_…`. type: string example: biz_123xyz name: description: display name for the payer account type: string example: Northside Physical Therapy mode: description: > whether this payer account operates against real money. Inherited from the JustiFi account it belongs to — a test account and a live account are different accounts with different ids, so a payer account is one or the other for its life and cannot be switched. In `test`, payments run against a simulated ACH network: they complete in seconds rather than banking days, and no money moves. type: string enum: - test - live example: live status: description: > the payer account's Payables lifecycle state, and what each state prevents. `pending` — provisioning has begun but the risk platform has not yet reported the business Payables-ready; `active` — Payables-ready, and the only state under which anything can be created; `disabled` — was active previously, and can no longer schedule payments, create payees or register bank accounts; `archived` — the same, and permanent: an archived payer account cannot be reactivated. A payment whose payee credit is already held is not paid out while the account is not `active`. It stays held until the account is active again, rather than failing. type: string enum: - pending - active - disabled - archived example: active provisioned_at: description: >- when the payer account was provisioned to use Payables; null until provisioning completes type: string nullable: true format: date-time example: '2026-01-01T12:00:00Z' funding_bank_account_id: description: > pointer to the payer account's active funding bank account. In this version a payer account has a single active funding account. Null until one is registered and verified. type: string nullable: true example: ba_fund456 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/payer_accounts/{payer_id}/payees: get: summary: List Payees description: > List the payees under this payer account. Supports cursor pagination. Archived payees are excluded unless you ask for them with `?status=archived`. operationId: PayablesListPayees tags: - Payees parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. - in: query name: after_cursor description: >- token to fetch the next page of a list (the `end_cursor` from a previous response's `page_info`) schema: type: string - in: query name: before_cursor description: >- token to fetch the previous page of a list (the `start_cursor` from a previous response's `page_info`) schema: type: string - in: query name: limit description: the number of resources to retrieve per page (default 25, max 100) schema: type: integer default: 25 minimum: 1 maximum: 100 - in: query name: created_after schema: type: string format: date-time required: false example: '2026-01-01T00:00:00Z' description: > filter records created after the date and time (UTC) specified. Dates without a time default to 00:00:00 - in: query name: created_before schema: type: string format: date-time required: false example: '2026-01-01T00:00:00Z' description: > filter records created before the date and time (UTC) specified. Dates without a time default to 00:00:00 - in: query name: status required: false schema: type: string enum: - pending - active - disabled - archived description: > filter payees by status. Omit it and every payee except `archived` is returned; archiving is a soft delete, so archived payees are visible only when asked for by name. responses: '200': description: Successfully listed payees content: application/json: schema: allOf: - type: object description: >- the standard JustiFi response envelope for a list of records properties: id: description: >- always null for list responses — a list has no id of its own; the ids are on `data` type: 'null' type: description: the object type type: string example: array data: description: the list of objects type: array items: type: object page_info: type: object description: cursor pagination info properties: start_cursor: description: >- the encoded id of the first record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd end_cursor: description: >- the encoded id of the last record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd has_next: description: >- true if there are records following the current page type: boolean default: false has_previous: description: >- true if there are records ahead of the current page type: boolean default: false required: - id - type - data - page_info - properties: type: example: array data: type: array items: type: object description: > A payee is a party that receives Payables payments. Payees are standalone: they can exist and be paid without being tied to a business. `business_id` reports a link to a JustiFi business where there is one, and is null by default. properties: id: description: unique payee id type: string example: pe_abc123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee payer_account_id: description: >- the id of the payer account this payee is scoped to type: string example: payer_123xyz name: description: the payee's legal name. Required on create. type: string example: Acme Plumbing LLC entity_type: description: > the payee's IRS entity classification. Required on create, with no default — it decides both the tax form filed for the payee and, for `sole_proprietorship`, how the ACH credit to them is classified. Immutable — with `tax_id` it is the taxpayer this payee is filed against. The set is open and may grow; unknown values should be treated as a business entity. type: string enum: - c_corporation - s_corporation - partnership - limited_liability_company - sole_proprietorship example: limited_liability_company email: description: contact email for the payee, when provided type: string nullable: true format: email example: billing@acmeplumbing.com tax_id_last4: description: > the last four digits of the payee's taxpayer identification number — an EIN, or an SSN where the payee is a `sole_proprietorship`. The number itself is required on create and never returned — it is stored encrypted, and this is what reads back. Immutable, on the same terms as `entity_type`. type: string example: '4021' address: type: object description: the payee's address. Required on create. properties: line1: description: street address type: string example: 123 Example St line2: description: suite, unit or floor, when there is one type: string nullable: true example: Suite 101 city: type: string example: Minneapolis state: description: > two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. type: string pattern: ^[A-Z]{2}$ example: MN postal_code: description: ZIP or ZIP+4 type: string pattern: ^\d{5}(-\d{4})?$ example: '55555' country: description: > ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. type: string enum: - USA default: USA example: USA receiving_bank_account_id: description: > pointer to the payee's active receiving bank account (denormalized for lookup, like capital's `accounts.payout_account_id`). In this version a payee has a single active account. Null until one is registered. type: string nullable: true example: ba_recv123 business_id: description: >+ the business this payee belongs to, where JustiFi has linked one. Null for standalone payees, and a payee is created and paid without one. type: string nullable: true example: null status: description: > the payee's status. `pending` — created but not cleared for payments; `active` — able to receive payments, and the only state a payment can be scheduled or paid out under; `disabled` — was active previously and can no longer be paid; `archived` — was active previously and can never be paid again. A payment whose payee credit is already held is not paid out while the payee is not `active`. It stays held until the payee is active again, rather than failing. **Payables disables a payee when its bank says the account cannot be paid.** Either the bank returned a credit for a reason a retry will not change — the account is closed, frozen, not a transaction account, or does not exist — or it sent a notification of change we cannot act on, because it named no corrected numbers or corrects something Payables does not hold. Both mean the next payment would go to an account the bank has already refused. A correction about the entry rather than the account — the payee's name, the entry description — changes nothing. **Registering a corrected receiving bank account returns the payee to `active`**, and any payment held for it pays out on the next cycle. Until then those payments wait rather than failing, which is what stops a queue of payments following the first one into a closed account. type: string enum: - pending - active - disabled - archived example: active metadata: description: >- any useful information you'd like to store alongside this payee type: object example: erp_payee_id: V-4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '400': description: > The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: bad_request message: payee pe_abc123 is archived and cannot be paid '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded post: summary: Create a Payee description: > Create a payee under this payer account. `name`, `entity_type`, `tax_id` and `address` are all required — together they are the identity a payee is paid and filed against, and none of them has a sensible default. A payee is still created without a bank account and has one registered later, through `CreateBankAccount`. `entity_type` and `tax_id` are fixed here — they are the taxpayer the payee is filed against, and `UpdatePayee` does not accept them. **The payer account must be `active`.** A payer account that is `pending`, `disabled` or `archived` creates nothing, and a payee create under one is refused with a `400`. operationId: PayablesCreatePayee tags: - Payees parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. requestBody: required: true content: application/json: schema: type: object required: - name - entity_type - tax_id - address properties: name: description: the payee's legal name type: string example: Acme Plumbing LLC entity_type: description: >- the payee's IRS entity classification; no default, and not changeable later type: string enum: - c_corporation - s_corporation - partnership - limited_liability_company - sole_proprietorship example: limited_liability_company tax_id: description: > the payee's taxpayer identification number — **an EIN or an SSN**, nine digits with or without separators. Which one it is follows `entity_type`: a `sole_proprietorship` files under the proprietor's SSN, or under an EIN where it has one; every other entity type files under an EIN. Write-only — it is stored encrypted and never returned; responses carry `tax_id_last4`. Payables does not validate it against the IRS, and does not check it against the entity type. type: string example: 12-3454021 address: type: object description: > A postal address, in the shape JustiFi's other APIs use. The shape is enforced; the address itself is not — Payables does not verify that it exists, and stores it as given without normalizing case or spacing. properties: line1: description: street address type: string example: 123 Example St line2: description: suite, unit or floor, when there is one type: string nullable: true example: Suite 101 city: type: string example: Minneapolis state: description: > two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. type: string pattern: ^[A-Z]{2}$ example: MN postal_code: description: ZIP or ZIP+4 type: string pattern: ^\d{5}(-\d{4})?$ example: '55555' country: description: > ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. type: string enum: - USA default: USA example: USA email: type: string format: email example: billing@acmeplumbing.com metadata: type: object example: erp_payee_id: V-4021 responses: '201': description: Payee was created successfully content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: payee data: type: object description: > A payee is a party that receives Payables payments. Payees are standalone: they can exist and be paid without being tied to a business. `business_id` reports a link to a JustiFi business where there is one, and is null by default. properties: id: description: unique payee id type: string example: pe_abc123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee payer_account_id: description: >- the id of the payer account this payee is scoped to type: string example: payer_123xyz name: description: the payee's legal name. Required on create. type: string example: Acme Plumbing LLC entity_type: description: > the payee's IRS entity classification. Required on create, with no default — it decides both the tax form filed for the payee and, for `sole_proprietorship`, how the ACH credit to them is classified. Immutable — with `tax_id` it is the taxpayer this payee is filed against. The set is open and may grow; unknown values should be treated as a business entity. type: string enum: - c_corporation - s_corporation - partnership - limited_liability_company - sole_proprietorship example: limited_liability_company email: description: contact email for the payee, when provided type: string nullable: true format: email example: billing@acmeplumbing.com tax_id_last4: description: > the last four digits of the payee's taxpayer identification number — an EIN, or an SSN where the payee is a `sole_proprietorship`. The number itself is required on create and never returned — it is stored encrypted, and this is what reads back. Immutable, on the same terms as `entity_type`. type: string example: '4021' address: type: object description: the payee's address. Required on create. properties: line1: description: street address type: string example: 123 Example St line2: description: suite, unit or floor, when there is one type: string nullable: true example: Suite 101 city: type: string example: Minneapolis state: description: > two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. type: string pattern: ^[A-Z]{2}$ example: MN postal_code: description: ZIP or ZIP+4 type: string pattern: ^\d{5}(-\d{4})?$ example: '55555' country: description: > ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. type: string enum: - USA default: USA example: USA receiving_bank_account_id: description: > pointer to the payee's active receiving bank account (denormalized for lookup, like capital's `accounts.payout_account_id`). In this version a payee has a single active account. Null until one is registered. type: string nullable: true example: ba_recv123 business_id: description: >+ the business this payee belongs to, where JustiFi has linked one. Null for standalone payees, and a payee is created and paid without one. type: string nullable: true example: null status: description: > the payee's status. `pending` — created but not cleared for payments; `active` — able to receive payments, and the only state a payment can be scheduled or paid out under; `disabled` — was active previously and can no longer be paid; `archived` — was active previously and can never be paid again. A payment whose payee credit is already held is not paid out while the payee is not `active`. It stays held until the payee is active again, rather than failing. **Payables disables a payee when its bank says the account cannot be paid.** Either the bank returned a credit for a reason a retry will not change — the account is closed, frozen, not a transaction account, or does not exist — or it sent a notification of change we cannot act on, because it named no corrected numbers or corrects something Payables does not hold. Both mean the next payment would go to an account the bank has already refused. A correction about the entry rather than the account — the payee's name, the entry description — changes nothing. **Registering a corrected receiving bank account returns the payee to `active`**, and any payment held for it pays out on the next cycle. Until then those payments wait rather than failing, which is what stops a queue of payments following the first one into a closed account. type: string enum: - pending - active - disabled - archived example: active metadata: description: >- any useful information you'd like to store alongside this payee type: object example: erp_payee_id: V-4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '400': description: > The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: bad_request message: payee pe_abc123 is archived and cannot be paid '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '422': description: > The request was well-formed and passed field validation, but a business rule rejected it — for example a payer funding account that is not `verified`, or a payee with no receiving bank account to credit. Field-level validation failures return `400`, not this. `error.details` carries per-attribute messages where the rule is attributable to one. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: unprocessable_entity message: The request could not be processed details: amount: - must be greater than 0 payee_id: - is required '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/payer_accounts/{payer_id}/payees/{id}: get: summary: Get a Payee operationId: PayablesGetPayee tags: - Payees parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. - in: path name: id schema: type: string required: true description: the id of the resource responses: '200': description: Successfully retrieved the payee content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: payee data: type: object description: > A payee is a party that receives Payables payments. Payees are standalone: they can exist and be paid without being tied to a business. `business_id` reports a link to a JustiFi business where there is one, and is null by default. properties: id: description: unique payee id type: string example: pe_abc123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee payer_account_id: description: >- the id of the payer account this payee is scoped to type: string example: payer_123xyz name: description: the payee's legal name. Required on create. type: string example: Acme Plumbing LLC entity_type: description: > the payee's IRS entity classification. Required on create, with no default — it decides both the tax form filed for the payee and, for `sole_proprietorship`, how the ACH credit to them is classified. Immutable — with `tax_id` it is the taxpayer this payee is filed against. The set is open and may grow; unknown values should be treated as a business entity. type: string enum: - c_corporation - s_corporation - partnership - limited_liability_company - sole_proprietorship example: limited_liability_company email: description: contact email for the payee, when provided type: string nullable: true format: email example: billing@acmeplumbing.com tax_id_last4: description: > the last four digits of the payee's taxpayer identification number — an EIN, or an SSN where the payee is a `sole_proprietorship`. The number itself is required on create and never returned — it is stored encrypted, and this is what reads back. Immutable, on the same terms as `entity_type`. type: string example: '4021' address: type: object description: the payee's address. Required on create. properties: line1: description: street address type: string example: 123 Example St line2: description: suite, unit or floor, when there is one type: string nullable: true example: Suite 101 city: type: string example: Minneapolis state: description: > two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. type: string pattern: ^[A-Z]{2}$ example: MN postal_code: description: ZIP or ZIP+4 type: string pattern: ^\d{5}(-\d{4})?$ example: '55555' country: description: > ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. type: string enum: - USA default: USA example: USA receiving_bank_account_id: description: > pointer to the payee's active receiving bank account (denormalized for lookup, like capital's `accounts.payout_account_id`). In this version a payee has a single active account. Null until one is registered. type: string nullable: true example: ba_recv123 business_id: description: >+ the business this payee belongs to, where JustiFi has linked one. Null for standalone payees, and a payee is created and paid without one. type: string nullable: true example: null status: description: > the payee's status. `pending` — created but not cleared for payments; `active` — able to receive payments, and the only state a payment can be scheduled or paid out under; `disabled` — was active previously and can no longer be paid; `archived` — was active previously and can never be paid again. A payment whose payee credit is already held is not paid out while the payee is not `active`. It stays held until the payee is active again, rather than failing. **Payables disables a payee when its bank says the account cannot be paid.** Either the bank returned a credit for a reason a retry will not change — the account is closed, frozen, not a transaction account, or does not exist — or it sent a notification of change we cannot act on, because it named no corrected numbers or corrects something Payables does not hold. Both mean the next payment would go to an account the bank has already refused. A correction about the entry rather than the account — the payee's name, the entry description — changes nothing. **Registering a corrected receiving bank account returns the payee to `active`**, and any payment held for it pays out on the next cycle. Until then those payments wait rather than failing, which is what stops a queue of payments following the first one into a closed account. type: string enum: - pending - active - disabled - archived example: active metadata: description: >- any useful information you'd like to store alongside this payee type: object example: erp_payee_id: V-4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded patch: summary: Update a Payee description: > Update mutable fields on a payee. Only the fields you send are changed, except `address`, which is replaced whole rather than merged field by field. `entity_type` and `tax_id` are not updatable. They are the taxpayer the payee is filed against and are fixed at create; a name or address change does not make a payee a different taxpayer, and a change to either of those two does. operationId: PayablesUpdatePayee tags: - Payees parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. - in: path name: id schema: type: string required: true description: the id of the resource requestBody: required: true content: application/json: schema: type: object properties: name: description: the payee's legal name type: string example: Acme Plumbing LLC address: type: object description: >- replaces the whole address. Partial addresses are not merged. properties: line1: description: street address type: string example: 123 Example St line2: description: suite, unit or floor, when there is one type: string nullable: true example: Suite 101 city: type: string example: Minneapolis state: description: > two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. type: string pattern: ^[A-Z]{2}$ example: MN postal_code: description: ZIP or ZIP+4 type: string pattern: ^\d{5}(-\d{4})?$ example: '55555' country: description: > ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. type: string enum: - USA default: USA example: USA email: type: string format: email example: ap@acmeplumbing.com metadata: type: object responses: '200': description: Payee was updated successfully content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: payee data: type: object description: > A payee is a party that receives Payables payments. Payees are standalone: they can exist and be paid without being tied to a business. `business_id` reports a link to a JustiFi business where there is one, and is null by default. properties: id: description: unique payee id type: string example: pe_abc123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee payer_account_id: description: >- the id of the payer account this payee is scoped to type: string example: payer_123xyz name: description: the payee's legal name. Required on create. type: string example: Acme Plumbing LLC entity_type: description: > the payee's IRS entity classification. Required on create, with no default — it decides both the tax form filed for the payee and, for `sole_proprietorship`, how the ACH credit to them is classified. Immutable — with `tax_id` it is the taxpayer this payee is filed against. The set is open and may grow; unknown values should be treated as a business entity. type: string enum: - c_corporation - s_corporation - partnership - limited_liability_company - sole_proprietorship example: limited_liability_company email: description: contact email for the payee, when provided type: string nullable: true format: email example: billing@acmeplumbing.com tax_id_last4: description: > the last four digits of the payee's taxpayer identification number — an EIN, or an SSN where the payee is a `sole_proprietorship`. The number itself is required on create and never returned — it is stored encrypted, and this is what reads back. Immutable, on the same terms as `entity_type`. type: string example: '4021' address: type: object description: the payee's address. Required on create. properties: line1: description: street address type: string example: 123 Example St line2: description: suite, unit or floor, when there is one type: string nullable: true example: Suite 101 city: type: string example: Minneapolis state: description: > two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. type: string pattern: ^[A-Z]{2}$ example: MN postal_code: description: ZIP or ZIP+4 type: string pattern: ^\d{5}(-\d{4})?$ example: '55555' country: description: > ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. type: string enum: - USA default: USA example: USA receiving_bank_account_id: description: > pointer to the payee's active receiving bank account (denormalized for lookup, like capital's `accounts.payout_account_id`). In this version a payee has a single active account. Null until one is registered. type: string nullable: true example: ba_recv123 business_id: description: >+ the business this payee belongs to, where JustiFi has linked one. Null for standalone payees, and a payee is created and paid without one. type: string nullable: true example: null status: description: > the payee's status. `pending` — created but not cleared for payments; `active` — able to receive payments, and the only state a payment can be scheduled or paid out under; `disabled` — was active previously and can no longer be paid; `archived` — was active previously and can never be paid again. A payment whose payee credit is already held is not paid out while the payee is not `active`. It stays held until the payee is active again, rather than failing. **Payables disables a payee when its bank says the account cannot be paid.** Either the bank returned a credit for a reason a retry will not change — the account is closed, frozen, not a transaction account, or does not exist — or it sent a notification of change we cannot act on, because it named no corrected numbers or corrects something Payables does not hold. Both mean the next payment would go to an account the bank has already refused. A correction about the entry rather than the account — the payee's name, the entry description — changes nothing. **Registering a corrected receiving bank account returns the payee to `active`**, and any payment held for it pays out on the next cycle. Until then those payments wait rather than failing, which is what stops a queue of payments following the first one into a closed account. type: string enum: - pending - active - disabled - archived example: active metadata: description: >- any useful information you'd like to store alongside this payee type: object example: erp_payee_id: V-4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '422': description: > The request was well-formed and passed field validation, but a business rule rejected it — for example a payer funding account that is not `verified`, or a payee with no receiving bank account to credit. Field-level validation failures return `400`, not this. `error.details` carries per-attribute messages where the rule is attributable to one. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: unprocessable_entity message: The request could not be processed details: amount: - must be greater than 0 payee_id: - is required '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded delete: summary: Archive a Payee description: > Archive a payee. Archiving is a soft delete: the payee's record and payment history are retained, but the payee can no longer be paid. Returns the archived payee. **Archiving reaches the payments already in flight, up to a point.** A credit already submitted to the network completes — nothing recalls an ACH entry. A payment still holding the payer's funds is not paid out: it stays held rather than failing, and would resume only if the payee were active again, which archiving rules out. Archiving is also always allowed, whatever the payer account's status. Archiving is one-way — there is no unarchive operation, and `status` is not writable through `UpdatePayee`. To pay a party again after archiving it, create a new payee. operationId: PayablesArchivePayee tags: - Payees parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. - in: path name: id schema: type: string required: true description: the id of the resource responses: '200': description: Payee was archived successfully content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: payee data: type: object description: > A payee is a party that receives Payables payments. Payees are standalone: they can exist and be paid without being tied to a business. `business_id` reports a link to a JustiFi business where there is one, and is null by default. properties: id: description: unique payee id type: string example: pe_abc123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee payer_account_id: description: >- the id of the payer account this payee is scoped to type: string example: payer_123xyz name: description: the payee's legal name. Required on create. type: string example: Acme Plumbing LLC entity_type: description: > the payee's IRS entity classification. Required on create, with no default — it decides both the tax form filed for the payee and, for `sole_proprietorship`, how the ACH credit to them is classified. Immutable — with `tax_id` it is the taxpayer this payee is filed against. The set is open and may grow; unknown values should be treated as a business entity. type: string enum: - c_corporation - s_corporation - partnership - limited_liability_company - sole_proprietorship example: limited_liability_company email: description: contact email for the payee, when provided type: string nullable: true format: email example: billing@acmeplumbing.com tax_id_last4: description: > the last four digits of the payee's taxpayer identification number — an EIN, or an SSN where the payee is a `sole_proprietorship`. The number itself is required on create and never returned — it is stored encrypted, and this is what reads back. Immutable, on the same terms as `entity_type`. type: string example: '4021' address: type: object description: the payee's address. Required on create. properties: line1: description: street address type: string example: 123 Example St line2: description: suite, unit or floor, when there is one type: string nullable: true example: Suite 101 city: type: string example: Minneapolis state: description: > two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. type: string pattern: ^[A-Z]{2}$ example: MN postal_code: description: ZIP or ZIP+4 type: string pattern: ^\d{5}(-\d{4})?$ example: '55555' country: description: > ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. type: string enum: - USA default: USA example: USA receiving_bank_account_id: description: > pointer to the payee's active receiving bank account (denormalized for lookup, like capital's `accounts.payout_account_id`). In this version a payee has a single active account. Null until one is registered. type: string nullable: true example: ba_recv123 business_id: description: >+ the business this payee belongs to, where JustiFi has linked one. Null for standalone payees, and a payee is created and paid without one. type: string nullable: true example: null status: description: > the payee's status. `pending` — created but not cleared for payments; `active` — able to receive payments, and the only state a payment can be scheduled or paid out under; `disabled` — was active previously and can no longer be paid; `archived` — was active previously and can never be paid again. A payment whose payee credit is already held is not paid out while the payee is not `active`. It stays held until the payee is active again, rather than failing. **Payables disables a payee when its bank says the account cannot be paid.** Either the bank returned a credit for a reason a retry will not change — the account is closed, frozen, not a transaction account, or does not exist — or it sent a notification of change we cannot act on, because it named no corrected numbers or corrects something Payables does not hold. Both mean the next payment would go to an account the bank has already refused. A correction about the entry rather than the account — the payee's name, the entry description — changes nothing. **Registering a corrected receiving bank account returns the payee to `active`**, and any payment held for it pays out on the next cycle. Until then those payments wait rather than failing, which is what stops a queue of payments following the first one into a closed account. type: string enum: - pending - active - disabled - archived example: active metadata: description: >- any useful information you'd like to store alongside this payee type: object example: erp_payee_id: V-4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/payer_accounts/{payer_id}/bank_accounts: get: summary: List Bank Accounts description: >- List bank accounts under this payer account, optionally filtered by owner. operationId: PayablesListBankAccounts tags: - Payee Bank Accounts parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. - in: query name: after_cursor description: >- token to fetch the next page of a list (the `end_cursor` from a previous response's `page_info`) schema: type: string - in: query name: before_cursor description: >- token to fetch the previous page of a list (the `start_cursor` from a previous response's `page_info`) schema: type: string - in: query name: limit description: the number of resources to retrieve per page (default 25, max 100) schema: type: integer default: 25 minimum: 1 maximum: 100 - in: query name: payee_id required: false schema: type: string description: > filter to a specific payee's receiving accounts. Ordered by `created_at`, this gives that payee's full bank account history — the current one is whichever `payee.receiving_bank_account_id` names. - in: query name: funding required: false schema: type: boolean description: > `true` returns only the payer account's funding accounts (those with `payer_account_id` set); `false` returns only payee receiving accounts responses: '200': description: Successfully listed bank accounts content: application/json: schema: allOf: - type: object description: >- the standard JustiFi response envelope for a list of records properties: id: description: >- always null for list responses — a list has no id of its own; the ids are on `data` type: 'null' type: description: the object type type: string example: array data: description: the list of objects type: array items: type: object page_info: type: object description: cursor pagination info properties: start_cursor: description: >- the encoded id of the first record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd end_cursor: description: >- the encoded id of the last record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd has_next: description: >- true if there are records following the current page type: boolean default: false has_previous: description: >- true if there are records ahead of the current page type: boolean default: false required: - id - type - data - page_info - properties: type: example: array data: type: array items: type: object description: > A bank account used for Payables money movement. Exactly one of `payer_account_id` or `payee_id` is set: the former for a funding account (the principal is pulled from it), the latter for a payee's receiving account (the principal is paid to it). Account numbers are write-only — accepted on create, never returned; responses expose only the last four digits. Bank accounts are immutable: to correct details (e.g. after a NOC), a new record is created rather than edited in place. **Which record is active is determined by the owner**, via `payer_account.funding_bank_account_id` or `payee.receiving_bank_account_id` — so registering a new account and pointing the owner at it supersedes the previous one. Listing an owner's bank accounts by `created_at` therefore gives its full account history. properties: id: description: unique bank account id type: string example: ba_recv123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: bank_account payer_account_id: description: > the payer account that owns this bank account, when it is a **funding** account. Null on a payee's receiving account. Exactly one of `payer_account_id` and `payee_id` is non-null. type: string nullable: true example: null account_holder_name: description: the name on the bank account type: string example: Acme Plumbing LLC routing_number: description: the 9-digit ABA routing number type: string example: '021000021' account_number_last4: description: >- the last four digits of the account number (the full number is never returned) type: string example: '6789' account_type: description: the type of bank account type: string enum: - checking - savings example: checking payee_id: description: > the payee that owns this bank account, when it is a **receiving** account. Null on a payer's funding account. Exactly one of `payer_account_id` and `payee_id` is non-null. type: string nullable: true example: pe_abc123 verification_status: description: > the state of bank account verification. Read together with which owner field is set, this is the model's signal for how the account is handled: - `not_required` — a payee (receiving) account. Payables does not verify payee accounts; payments are sent without upfront validation, and a bad account surfaces as a returned credit. This is a settled state rather than a "not yet verified" one. - `pending` — a payer (funding) account whose validation is in progress. Payer funding accounts are validated in-app (e.g. during portal funding setup). - `verified` — a payer funding account that has been validated; only a `verified` funding account may fund a payment. - `failed` — validation of a payer funding account failed; it cannot fund payments. type: string enum: - not_required - pending - verified - failed example: verified created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '400': description: > The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: bad_request message: payee pe_abc123 is archived and cannot be paid '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded post: summary: Create a Payee Bank Account description: > Register a **receiving** bank account for a payee under this payer account (the account a payment is paid to). The `account_number` is write-only — it is accepted here but never returned; responses expose only `account_number_last4`. **Funding accounts cannot be created here.** The payer account's own funding account — the one payments are pulled from — is set during provisioning and replaced by JustiFi rather than through this API, because it decides where money is taken from. This endpoint creates payee receiving accounts only, and they are created `not_required`: Payables does not validate payee accounts. You can still *read* funding accounts through `ListBankAccounts` and `GetBankAccount`. In this version an owner has a single active bank account — creating one for a payee that already has an active account supersedes the previous one. **The payer account must be `active` and the payee must not be archived.** Either one is a `400`: a payer account that is not active registers nothing, and an archived payee can never be paid, so it has nothing to be paid to. **A `disabled` payee may still register an account, and doing so returns it to `active`.** That is the way back for a payee Payables disabled because its bank refused the credit or corrected the account without saying what to: register the corrected numbers and the payee is payable again, along with any payment still held for it. operationId: PayablesCreateBankAccount tags: - Payee Bank Accounts parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. requestBody: required: true content: application/json: schema: type: object required: - payee_id - account_holder_name - routing_number - account_number - account_type properties: account_holder_name: type: string example: Acme Plumbing LLC routing_number: type: string example: '021000021' account_number: description: the full account number; write-only, never returned type: string writeOnly: true example: '123456789' account_type: type: string enum: - checking - savings example: checking payee_id: description: > the payee this receiving account belongs to. The payee must be scoped to the payer account in the path. type: string example: pe_abc123 responses: '201': description: Bank account was created successfully content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: bank_account data: type: object description: > A bank account used for Payables money movement. Exactly one of `payer_account_id` or `payee_id` is set: the former for a funding account (the principal is pulled from it), the latter for a payee's receiving account (the principal is paid to it). Account numbers are write-only — accepted on create, never returned; responses expose only the last four digits. Bank accounts are immutable: to correct details (e.g. after a NOC), a new record is created rather than edited in place. **Which record is active is determined by the owner**, via `payer_account.funding_bank_account_id` or `payee.receiving_bank_account_id` — so registering a new account and pointing the owner at it supersedes the previous one. Listing an owner's bank accounts by `created_at` therefore gives its full account history. properties: id: description: unique bank account id type: string example: ba_recv123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: bank_account payer_account_id: description: > the payer account that owns this bank account, when it is a **funding** account. Null on a payee's receiving account. Exactly one of `payer_account_id` and `payee_id` is non-null. type: string nullable: true example: null account_holder_name: description: the name on the bank account type: string example: Acme Plumbing LLC routing_number: description: the 9-digit ABA routing number type: string example: '021000021' account_number_last4: description: >- the last four digits of the account number (the full number is never returned) type: string example: '6789' account_type: description: the type of bank account type: string enum: - checking - savings example: checking payee_id: description: > the payee that owns this bank account, when it is a **receiving** account. Null on a payer's funding account. Exactly one of `payer_account_id` and `payee_id` is non-null. type: string nullable: true example: pe_abc123 verification_status: description: > the state of bank account verification. Read together with which owner field is set, this is the model's signal for how the account is handled: - `not_required` — a payee (receiving) account. Payables does not verify payee accounts; payments are sent without upfront validation, and a bad account surfaces as a returned credit. This is a settled state rather than a "not yet verified" one. - `pending` — a payer (funding) account whose validation is in progress. Payer funding accounts are validated in-app (e.g. during portal funding setup). - `verified` — a payer funding account that has been validated; only a `verified` funding account may fund a payment. - `failed` — validation of a payer funding account failed; it cannot fund payments. type: string enum: - not_required - pending - verified - failed example: verified created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '400': description: > The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: bad_request message: payee pe_abc123 is archived and cannot be paid '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '422': description: > The request was well-formed and passed field validation, but a business rule rejected it — for example a payer funding account that is not `verified`, or a payee with no receiving bank account to credit. Field-level validation failures return `400`, not this. `error.details` carries per-attribute messages where the rule is attributable to one. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: unprocessable_entity message: The request could not be processed details: amount: - must be greater than 0 payee_id: - is required '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/payer_accounts/{payer_id}/bank_accounts/{id}: get: summary: Get a Bank Account operationId: PayablesGetBankAccount tags: - Payee Bank Accounts parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. - in: path name: id schema: type: string required: true description: the id of the resource responses: '200': description: Successfully retrieved the bank account content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: bank_account data: type: object description: > A bank account used for Payables money movement. Exactly one of `payer_account_id` or `payee_id` is set: the former for a funding account (the principal is pulled from it), the latter for a payee's receiving account (the principal is paid to it). Account numbers are write-only — accepted on create, never returned; responses expose only the last four digits. Bank accounts are immutable: to correct details (e.g. after a NOC), a new record is created rather than edited in place. **Which record is active is determined by the owner**, via `payer_account.funding_bank_account_id` or `payee.receiving_bank_account_id` — so registering a new account and pointing the owner at it supersedes the previous one. Listing an owner's bank accounts by `created_at` therefore gives its full account history. properties: id: description: unique bank account id type: string example: ba_recv123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: bank_account payer_account_id: description: > the payer account that owns this bank account, when it is a **funding** account. Null on a payee's receiving account. Exactly one of `payer_account_id` and `payee_id` is non-null. type: string nullable: true example: null account_holder_name: description: the name on the bank account type: string example: Acme Plumbing LLC routing_number: description: the 9-digit ABA routing number type: string example: '021000021' account_number_last4: description: >- the last four digits of the account number (the full number is never returned) type: string example: '6789' account_type: description: the type of bank account type: string enum: - checking - savings example: checking payee_id: description: > the payee that owns this bank account, when it is a **receiving** account. Null on a payer's funding account. Exactly one of `payer_account_id` and `payee_id` is non-null. type: string nullable: true example: pe_abc123 verification_status: description: > the state of bank account verification. Read together with which owner field is set, this is the model's signal for how the account is handled: - `not_required` — a payee (receiving) account. Payables does not verify payee accounts; payments are sent without upfront validation, and a bad account surfaces as a returned credit. This is a settled state rather than a "not yet verified" one. - `pending` — a payer (funding) account whose validation is in progress. Payer funding accounts are validated in-app (e.g. during portal funding setup). - `verified` — a payer funding account that has been validated; only a `verified` funding account may fund a payment. - `failed` — validation of a payer funding account failed; it cannot fund payments. type: string enum: - not_required - pending - verified - failed example: verified created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/payer_accounts/{payer_id}/payee_payments: get: summary: List Payee Payments description: >- List payee payments under this payer account. Supports cursor pagination and filtering. operationId: PayablesListPayeePayments tags: - Payee Payments parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. - in: query name: after_cursor description: >- token to fetch the next page of a list (the `end_cursor` from a previous response's `page_info`) schema: type: string - in: query name: before_cursor description: >- token to fetch the previous page of a list (the `start_cursor` from a previous response's `page_info`) schema: type: string - in: query name: limit description: the number of resources to retrieve per page (default 25, max 100) schema: type: integer default: 25 minimum: 1 maximum: 100 - in: query name: created_after schema: type: string format: date-time required: false example: '2026-01-01T00:00:00Z' description: > filter records created after the date and time (UTC) specified. Dates without a time default to 00:00:00 - in: query name: created_before schema: type: string format: date-time required: false example: '2026-01-01T00:00:00Z' description: > filter records created before the date and time (UTC) specified. Dates without a time default to 00:00:00 - in: query name: status required: false schema: type: string enum: - initiated - inbound_submitted - holding - outbound_submitted - succeeded - failed - refunding_payer - refunded description: filter payments by lifecycle status - in: query name: payee_id required: false schema: type: string description: filter payments to a single payee responses: '200': description: Successfully listed payee payments content: application/json: schema: allOf: - type: object description: >- the standard JustiFi response envelope for a list of records properties: id: description: >- always null for list responses — a list has no id of its own; the ids are on `data` type: 'null' type: description: the object type type: string example: array data: description: the list of objects type: array items: type: object page_info: type: object description: cursor pagination info properties: start_cursor: description: >- the encoded id of the first record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd end_cursor: description: >- the encoded id of the last record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd has_next: description: >- true if there are records following the current page type: boolean default: false has_previous: description: >- true if there are records ahead of the current page type: boolean default: false required: - id - type - data - page_info - properties: type: example: array data: type: array items: type: object description: > A payee payment moves money from the account's funding bank account to a payee's receiving account over ACH. It orchestrates an inbound debit-pull, a hold, and an outbound credit, accruing fees along the way. There is no automatic retry, and a payment cannot be cancelled once initiated. A return ends the payment either at `failed` or, when the payer has already been debited, at `refunding_payer` — see `status`. properties: id: description: unique payee payment id type: string example: pp_123xyz type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee_payment payer_account_id: description: >- the id of the payer account this payment is scoped to type: string example: payer_123xyz amount: description: > the gross amount debited from the payer, in cents. The payee receives `amount` minus the sum of `fees` (e.g. `amount` 91000 with a 1000 fee pays the payee 90000). type: integer example: 91000 currency: type: string enum: - usd example: usd status: description: > the payment's position in its lifecycle. `initiated` → `inbound_submitted` → `holding` → `outbound_submitted` → `succeeded` is the happy path. **`holding` is a real wait.** Once the payer's funding has settled, the payee's credit is held until the next banking day before it is submitted, so a payment rests in `holding` rather than passing through it. Read `deposits_at` for when the payee is expected to be deposited; the hold is already in that estimate. **The hold only lifts for an active payer account and an active payee.** When the wait is up, the payee's credit is sent if both are `active`; if either is not, the payment stays in `holding` and is reconsidered periodically, so it pays out once both are active again. A hold that persists pushes the deposit past the `deposits_at` estimate, which is why that field is an estimate. Which return path a payment takes depends on whose money was already moved. A returned **inbound** debit-pull means nothing settled, so the payment is `failed` and no one is owed anything. A returned **outbound** credit means the payer was already debited, so the payment moves to `refunding_payer` and then `refunded` once the payer has their money back. Both `failed` and `refunded` are terminal. **`succeeded` is not the end.** ACH lets a return arrive days after an entry settled, so one can land after a payment has succeeded. That moves the payment to `failed_late_return`, which is terminal — JustiFi works the break by hand and records the corrective movement as a further leg on the same payment. See "A return that arrives after a payment succeeded" in the overview. **`failed_late_return` does not mean the payee holds nothing.** It reports that the payment did not stick, and the two ways that happens are opposites: a returned **outbound** credit means the payee never kept the money, while a returned **inbound** debit-pull means the payer's funding was clawed back *after* the payee was paid — so the payee still has it. **Re-sending on this status can pay a payee twice.** Read the payment's `transfers` to see which leg returned before acting. type: string enum: - initiated - inbound_submitted - holding - outbound_submitted - succeeded - failed - refunding_payer - refunded - failed_late_return example: succeeded payment_type: description: >+ how the funds move. ACH is the only option. Named `payment_type` rather than `payment_method`, which in the JustiFi API denotes a stored instrument object, not a rail. type: string enum: - ach example: ach payee_id: description: the payee being paid type: string example: pe_abc123 funding_bank_account_id: description: >- the account's funding bank account the principal is debit-pulled from type: string example: ba_fund456 receiving_bank_account_id: description: >- the payee's receiving account the principal is credited to type: string example: ba_recv123 debits_at: description: > in UTC, the estimated date and time the payer's funding account is debited (from the inbound leg); null until scheduled. Normally three banking days after the payment is submitted. type: string nullable: true format: date-time example: '2026-01-01T12:00:00Z' deposits_at: description: > in UTC, the estimated date and time the payee is deposited (from the outbound leg); null until scheduled. Each ACH leg takes three banking days and the payee's credit is held for one banking day after the payer's funding settles, so this is normally four banking days after `debits_at`. Estimated, and may shift if the provider revises an effective entry date. type: string nullable: true format: date-time example: '2026-01-04T12:00:00Z' description: type: string nullable: true example: Invoice 4021 fees: description: > the fees charged on this payment (v2 fee convention), carved out of `amount`. Supplied in the create request (required, no default) and echoed here. Fees incurred later by NOCs or returns are not shown here — they are billed to the platform monthly. type: array items: type: object description: > A fee charged on a payee payment, following the JustiFi v2 fee convention. Fees are **carved out of the payment `amount`** (the gross debited from the payer): the payee receives `amount` minus the sum of `fees`. The `fees` array is **required** on create with **no default** — the platform sets the fee explicitly (e.g. to net a payee 90000, pass `amount` 91000 with a 1000 fee). properties: type: type: string enum: - processing_fee description: > the fee type (v2 convention): - `processing_fee` — payment-processing cost, passed by platform example: processing_fee amount: type: integer description: fee amount in cents example: 1000 required: - type - amount transfers: description: the ACH legs that make up this payment type: array items: type: object description: >+ One leg of a payee payment. A payment has at least one inbound leg (debit-pull from the account's funding bank account) and one outbound leg (credit to the payee); refunds, reversals, and recoveries add further legs. Most legs are ACH; a leg JustiFi records off the ACH network (e.g. a manual recovery) carries a non-`ach` `transfer_type`. Scheduling values assigned by the bank are deliberately absent: the dates to read are `debits_at` and `deposits_at` on the payment, which are derived from these legs. properties: id: description: unique transfer leg id type: string example: ptr_123 direction: description: >- the direction of funds for this leg (a refund is an outbound, a recovery an inbound) type: string enum: - inbound - outbound example: inbound purpose: description: >- what this leg is — moves the principal, refunds the payer, or recovers owed funds from the payer type: string enum: - principal - refund - recovery example: principal transfer_type: description: > how the money moved. `ach` — over the ACH network; `manual` — a movement JustiFi recorded off it. Widens to further rails (e.g. `rtp`) without a breaking change. type: string enum: - ach - manual example: ach amount: description: the leg amount in cents type: integer example: 50000 status: description: the state of this leg type: string enum: - initiated - submitted - settled - returned - failed example: settled error_code: description: > normalised, rail-agnostic reason the leg failed, in snake_case (e.g. `insufficient_funds`). Stable across rails — **branch on this, not on `network_error_code`**, which is the network's own code and changes meaning between rails. Set when a leg is `failed` or `returned`, and null otherwise. A correction is not a failure: a leg that settled after a notification of change carries `network_error_code` but no `error_code`. A return code with no normalised equivalent reports `unclassified_return`, so this is never null on a leg that failed — the raw code is always there to fall back on. type: string nullable: true example: insufficient_funds error_description: description: >+ human-readable text for `error_code`, in English — for support and logs, not for branching. Null whenever `error_code` is. type: string nullable: true example: Insufficient funds in the account network_error_code: description: > the raw code from the network, verbatim — an ACH return code (`R01`). Preserved for reconciliation. Present whenever the network said anything about this leg, which is not only when it went wrong: a notification of change carries an advisory code (`C01`) on a leg that **settled** normally. Read it together with `status` — the code alone does not mean the money did not move. type: string nullable: true example: null metadata: description: >- any useful information you'd like to store alongside this payment type: object example: invoice_id: inv_4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-05T12:00:00Z' '400': description: > The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: bad_request message: payee pe_abc123 is archived and cannot be paid '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded post: summary: Schedule a Payee Payment description: > Schedule a payment to a payee. This debit-pulls the gross `amount` from the payer's funding bank account, holds it, then credits the payee's receiving account with `amount` minus `fees`. The `fees` array is required (no default) and is carved out of `amount`. There is no automatic retry: a returned debit-pull fails the payment, and a returned credit to the payee refunds the payer. **You name the payee; everything else about the routing is resolved for you.** The funding account comes from the payer account in the path and the receiving account from the payee, so neither is a request field — a payment can only ever move money between the two accounts those records already point at. The schedule is set by the system: each leg takes three banking days, and `debits_at` and `deposits_at` are returned once known. `payment_type` and `currency` are optional and default to `ach` and `usd`, the only values either accepts. **The payer account and the payee must both be `active`**, and either one that is not is a `400` rather than a `422` — a status is the state of a record the request refers to, not a problem with the body. A payee that is `pending`, `disabled` or `archived` cannot be paid. Both accounts must be usable, and the bar differs by side. The payer account's funding account must be **verified**. The payee's receiving account does **not** need to be verified — `not_required` is the normal state for one — but it must **exist** and must not have **failed** verification: a payee can be created without a bank account, and naming one that has none leaves the payment with nothing to credit. Either failure is a `422`. operationId: PayablesCreatePayeePayment tags: - Payee Payments parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. - in: header name: Idempotency-Key schema: type: string required: true example: my-request-123abc description: > a string to uniquely identify your request (we recommend a generated uuid, but any unique string works). Replaying the same key returns `200` with the payment that key already created — as it stands now, not a cached copy of the first response — instead of performing the operation twice. Reusing a key with a different request body is a `409`. Keys are scoped to the payer account, so two payer accounts may use the same key without colliding. requestBody: required: true content: application/json: schema: type: object required: - amount - payee_id - fees properties: amount: description: > the gross amount debited from the payer, in cents. The payee receives `amount` minus the sum of `fees` (pass 91000 with a 1000 fee to net the payee 90000). type: integer example: 91000 currency: description: defaults to `usd`, the only supported currency type: string enum: - usd default: usd example: usd payee_id: type: string example: pe_abc123 fees: description: > fees to charge on this payment (v2 fee convention), carved out of `amount`. **Required, no default** — the platform sets the fee explicitly. type: array minItems: 1 items: type: object description: > A fee charged on a payee payment, following the JustiFi v2 fee convention. Fees are **carved out of the payment `amount`** (the gross debited from the payer): the payee receives `amount` minus the sum of `fees`. The `fees` array is **required** on create with **no default** — the platform sets the fee explicitly (e.g. to net a payee 90000, pass `amount` 91000 with a 1000 fee). properties: type: type: string enum: - processing_fee description: > the fee type (v2 convention): - `processing_fee` — payment-processing cost, passed by platform example: processing_fee amount: type: integer description: fee amount in cents example: 1000 required: - type - amount example: - type: processing_fee amount: 1000 payment_type: description: > the rail the payment moves over. **Optional, and defaults to `ach`** — ACH is the only rail Payables moves money over, so there is nothing to select. type: string enum: - ach default: ach example: ach description: type: string example: Invoice 4021 metadata: type: object example: invoice_id: inv_4021 responses: '200': description: > This `Idempotency-Key` already scheduled a payment for this payer account, and the request body matches. The payment is returned **as it stands now** — not a cached copy of the first response — so it may have advanced past `initiated`. Nothing was scheduled a second time. content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: payee_payment data: type: object description: > A payee payment moves money from the account's funding bank account to a payee's receiving account over ACH. It orchestrates an inbound debit-pull, a hold, and an outbound credit, accruing fees along the way. There is no automatic retry, and a payment cannot be cancelled once initiated. A return ends the payment either at `failed` or, when the payer has already been debited, at `refunding_payer` — see `status`. properties: id: description: unique payee payment id type: string example: pp_123xyz type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee_payment payer_account_id: description: >- the id of the payer account this payment is scoped to type: string example: payer_123xyz amount: description: > the gross amount debited from the payer, in cents. The payee receives `amount` minus the sum of `fees` (e.g. `amount` 91000 with a 1000 fee pays the payee 90000). type: integer example: 91000 currency: type: string enum: - usd example: usd status: description: > the payment's position in its lifecycle. `initiated` → `inbound_submitted` → `holding` → `outbound_submitted` → `succeeded` is the happy path. **`holding` is a real wait.** Once the payer's funding has settled, the payee's credit is held until the next banking day before it is submitted, so a payment rests in `holding` rather than passing through it. Read `deposits_at` for when the payee is expected to be deposited; the hold is already in that estimate. **The hold only lifts for an active payer account and an active payee.** When the wait is up, the payee's credit is sent if both are `active`; if either is not, the payment stays in `holding` and is reconsidered periodically, so it pays out once both are active again. A hold that persists pushes the deposit past the `deposits_at` estimate, which is why that field is an estimate. Which return path a payment takes depends on whose money was already moved. A returned **inbound** debit-pull means nothing settled, so the payment is `failed` and no one is owed anything. A returned **outbound** credit means the payer was already debited, so the payment moves to `refunding_payer` and then `refunded` once the payer has their money back. Both `failed` and `refunded` are terminal. **`succeeded` is not the end.** ACH lets a return arrive days after an entry settled, so one can land after a payment has succeeded. That moves the payment to `failed_late_return`, which is terminal — JustiFi works the break by hand and records the corrective movement as a further leg on the same payment. See "A return that arrives after a payment succeeded" in the overview. **`failed_late_return` does not mean the payee holds nothing.** It reports that the payment did not stick, and the two ways that happens are opposites: a returned **outbound** credit means the payee never kept the money, while a returned **inbound** debit-pull means the payer's funding was clawed back *after* the payee was paid — so the payee still has it. **Re-sending on this status can pay a payee twice.** Read the payment's `transfers` to see which leg returned before acting. type: string enum: - initiated - inbound_submitted - holding - outbound_submitted - succeeded - failed - refunding_payer - refunded - failed_late_return example: succeeded payment_type: description: >+ how the funds move. ACH is the only option. Named `payment_type` rather than `payment_method`, which in the JustiFi API denotes a stored instrument object, not a rail. type: string enum: - ach example: ach payee_id: description: the payee being paid type: string example: pe_abc123 funding_bank_account_id: description: >- the account's funding bank account the principal is debit-pulled from type: string example: ba_fund456 receiving_bank_account_id: description: >- the payee's receiving account the principal is credited to type: string example: ba_recv123 debits_at: description: > in UTC, the estimated date and time the payer's funding account is debited (from the inbound leg); null until scheduled. Normally three banking days after the payment is submitted. type: string nullable: true format: date-time example: '2026-01-01T12:00:00Z' deposits_at: description: > in UTC, the estimated date and time the payee is deposited (from the outbound leg); null until scheduled. Each ACH leg takes three banking days and the payee's credit is held for one banking day after the payer's funding settles, so this is normally four banking days after `debits_at`. Estimated, and may shift if the provider revises an effective entry date. type: string nullable: true format: date-time example: '2026-01-04T12:00:00Z' description: type: string nullable: true example: Invoice 4021 fees: description: > the fees charged on this payment (v2 fee convention), carved out of `amount`. Supplied in the create request (required, no default) and echoed here. Fees incurred later by NOCs or returns are not shown here — they are billed to the platform monthly. type: array items: type: object description: > A fee charged on a payee payment, following the JustiFi v2 fee convention. Fees are **carved out of the payment `amount`** (the gross debited from the payer): the payee receives `amount` minus the sum of `fees`. The `fees` array is **required** on create with **no default** — the platform sets the fee explicitly (e.g. to net a payee 90000, pass `amount` 91000 with a 1000 fee). properties: type: type: string enum: - processing_fee description: > the fee type (v2 convention): - `processing_fee` — payment-processing cost, passed by platform example: processing_fee amount: type: integer description: fee amount in cents example: 1000 required: - type - amount transfers: description: the ACH legs that make up this payment type: array items: type: object description: >+ One leg of a payee payment. A payment has at least one inbound leg (debit-pull from the account's funding bank account) and one outbound leg (credit to the payee); refunds, reversals, and recoveries add further legs. Most legs are ACH; a leg JustiFi records off the ACH network (e.g. a manual recovery) carries a non-`ach` `transfer_type`. Scheduling values assigned by the bank are deliberately absent: the dates to read are `debits_at` and `deposits_at` on the payment, which are derived from these legs. properties: id: description: unique transfer leg id type: string example: ptr_123 direction: description: >- the direction of funds for this leg (a refund is an outbound, a recovery an inbound) type: string enum: - inbound - outbound example: inbound purpose: description: >- what this leg is — moves the principal, refunds the payer, or recovers owed funds from the payer type: string enum: - principal - refund - recovery example: principal transfer_type: description: > how the money moved. `ach` — over the ACH network; `manual` — a movement JustiFi recorded off it. Widens to further rails (e.g. `rtp`) without a breaking change. type: string enum: - ach - manual example: ach amount: description: the leg amount in cents type: integer example: 50000 status: description: the state of this leg type: string enum: - initiated - submitted - settled - returned - failed example: settled error_code: description: > normalised, rail-agnostic reason the leg failed, in snake_case (e.g. `insufficient_funds`). Stable across rails — **branch on this, not on `network_error_code`**, which is the network's own code and changes meaning between rails. Set when a leg is `failed` or `returned`, and null otherwise. A correction is not a failure: a leg that settled after a notification of change carries `network_error_code` but no `error_code`. A return code with no normalised equivalent reports `unclassified_return`, so this is never null on a leg that failed — the raw code is always there to fall back on. type: string nullable: true example: insufficient_funds error_description: description: >+ human-readable text for `error_code`, in English — for support and logs, not for branching. Null whenever `error_code` is. type: string nullable: true example: Insufficient funds in the account network_error_code: description: > the raw code from the network, verbatim — an ACH return code (`R01`). Preserved for reconciliation. Present whenever the network said anything about this leg, which is not only when it went wrong: a notification of change carries an advisory code (`C01`) on a leg that **settled** normally. Read it together with `status` — the code alone does not mean the money did not move. type: string nullable: true example: null metadata: description: >- any useful information you'd like to store alongside this payment type: object example: invoice_id: inv_4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-05T12:00:00Z' '201': description: Payee payment was scheduled successfully content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: payee_payment data: type: object description: > A payee payment moves money from the account's funding bank account to a payee's receiving account over ACH. It orchestrates an inbound debit-pull, a hold, and an outbound credit, accruing fees along the way. There is no automatic retry, and a payment cannot be cancelled once initiated. A return ends the payment either at `failed` or, when the payer has already been debited, at `refunding_payer` — see `status`. properties: id: description: unique payee payment id type: string example: pp_123xyz type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee_payment payer_account_id: description: >- the id of the payer account this payment is scoped to type: string example: payer_123xyz amount: description: > the gross amount debited from the payer, in cents. The payee receives `amount` minus the sum of `fees` (e.g. `amount` 91000 with a 1000 fee pays the payee 90000). type: integer example: 91000 currency: type: string enum: - usd example: usd status: description: > the payment's position in its lifecycle. `initiated` → `inbound_submitted` → `holding` → `outbound_submitted` → `succeeded` is the happy path. **`holding` is a real wait.** Once the payer's funding has settled, the payee's credit is held until the next banking day before it is submitted, so a payment rests in `holding` rather than passing through it. Read `deposits_at` for when the payee is expected to be deposited; the hold is already in that estimate. **The hold only lifts for an active payer account and an active payee.** When the wait is up, the payee's credit is sent if both are `active`; if either is not, the payment stays in `holding` and is reconsidered periodically, so it pays out once both are active again. A hold that persists pushes the deposit past the `deposits_at` estimate, which is why that field is an estimate. Which return path a payment takes depends on whose money was already moved. A returned **inbound** debit-pull means nothing settled, so the payment is `failed` and no one is owed anything. A returned **outbound** credit means the payer was already debited, so the payment moves to `refunding_payer` and then `refunded` once the payer has their money back. Both `failed` and `refunded` are terminal. **`succeeded` is not the end.** ACH lets a return arrive days after an entry settled, so one can land after a payment has succeeded. That moves the payment to `failed_late_return`, which is terminal — JustiFi works the break by hand and records the corrective movement as a further leg on the same payment. See "A return that arrives after a payment succeeded" in the overview. **`failed_late_return` does not mean the payee holds nothing.** It reports that the payment did not stick, and the two ways that happens are opposites: a returned **outbound** credit means the payee never kept the money, while a returned **inbound** debit-pull means the payer's funding was clawed back *after* the payee was paid — so the payee still has it. **Re-sending on this status can pay a payee twice.** Read the payment's `transfers` to see which leg returned before acting. type: string enum: - initiated - inbound_submitted - holding - outbound_submitted - succeeded - failed - refunding_payer - refunded - failed_late_return example: succeeded payment_type: description: >+ how the funds move. ACH is the only option. Named `payment_type` rather than `payment_method`, which in the JustiFi API denotes a stored instrument object, not a rail. type: string enum: - ach example: ach payee_id: description: the payee being paid type: string example: pe_abc123 funding_bank_account_id: description: >- the account's funding bank account the principal is debit-pulled from type: string example: ba_fund456 receiving_bank_account_id: description: >- the payee's receiving account the principal is credited to type: string example: ba_recv123 debits_at: description: > in UTC, the estimated date and time the payer's funding account is debited (from the inbound leg); null until scheduled. Normally three banking days after the payment is submitted. type: string nullable: true format: date-time example: '2026-01-01T12:00:00Z' deposits_at: description: > in UTC, the estimated date and time the payee is deposited (from the outbound leg); null until scheduled. Each ACH leg takes three banking days and the payee's credit is held for one banking day after the payer's funding settles, so this is normally four banking days after `debits_at`. Estimated, and may shift if the provider revises an effective entry date. type: string nullable: true format: date-time example: '2026-01-04T12:00:00Z' description: type: string nullable: true example: Invoice 4021 fees: description: > the fees charged on this payment (v2 fee convention), carved out of `amount`. Supplied in the create request (required, no default) and echoed here. Fees incurred later by NOCs or returns are not shown here — they are billed to the platform monthly. type: array items: type: object description: > A fee charged on a payee payment, following the JustiFi v2 fee convention. Fees are **carved out of the payment `amount`** (the gross debited from the payer): the payee receives `amount` minus the sum of `fees`. The `fees` array is **required** on create with **no default** — the platform sets the fee explicitly (e.g. to net a payee 90000, pass `amount` 91000 with a 1000 fee). properties: type: type: string enum: - processing_fee description: > the fee type (v2 convention): - `processing_fee` — payment-processing cost, passed by platform example: processing_fee amount: type: integer description: fee amount in cents example: 1000 required: - type - amount transfers: description: the ACH legs that make up this payment type: array items: type: object description: >+ One leg of a payee payment. A payment has at least one inbound leg (debit-pull from the account's funding bank account) and one outbound leg (credit to the payee); refunds, reversals, and recoveries add further legs. Most legs are ACH; a leg JustiFi records off the ACH network (e.g. a manual recovery) carries a non-`ach` `transfer_type`. Scheduling values assigned by the bank are deliberately absent: the dates to read are `debits_at` and `deposits_at` on the payment, which are derived from these legs. properties: id: description: unique transfer leg id type: string example: ptr_123 direction: description: >- the direction of funds for this leg (a refund is an outbound, a recovery an inbound) type: string enum: - inbound - outbound example: inbound purpose: description: >- what this leg is — moves the principal, refunds the payer, or recovers owed funds from the payer type: string enum: - principal - refund - recovery example: principal transfer_type: description: > how the money moved. `ach` — over the ACH network; `manual` — a movement JustiFi recorded off it. Widens to further rails (e.g. `rtp`) without a breaking change. type: string enum: - ach - manual example: ach amount: description: the leg amount in cents type: integer example: 50000 status: description: the state of this leg type: string enum: - initiated - submitted - settled - returned - failed example: settled error_code: description: > normalised, rail-agnostic reason the leg failed, in snake_case (e.g. `insufficient_funds`). Stable across rails — **branch on this, not on `network_error_code`**, which is the network's own code and changes meaning between rails. Set when a leg is `failed` or `returned`, and null otherwise. A correction is not a failure: a leg that settled after a notification of change carries `network_error_code` but no `error_code`. A return code with no normalised equivalent reports `unclassified_return`, so this is never null on a leg that failed — the raw code is always there to fall back on. type: string nullable: true example: insufficient_funds error_description: description: >+ human-readable text for `error_code`, in English — for support and logs, not for branching. Null whenever `error_code` is. type: string nullable: true example: Insufficient funds in the account network_error_code: description: > the raw code from the network, verbatim — an ACH return code (`R01`). Preserved for reconciliation. Present whenever the network said anything about this leg, which is not only when it went wrong: a notification of change carries an advisory code (`C01`) on a leg that **settled** normally. Read it together with `status` — the code alone does not mean the money did not move. type: string nullable: true example: null metadata: description: >- any useful information you'd like to store alongside this payment type: object example: invoice_id: inv_4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-05T12:00:00Z' '400': description: > The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: bad_request message: payee pe_abc123 is archived and cannot be paid '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '409': description: > An `Idempotency-Key` was reused with a different request body. Retry with a fresh key, or resend the original body to get the payment that key already created. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: conflict message: This Idempotency-Key was used with a different request body '422': description: > The request was well-formed and passed field validation, but a business rule rejected it — for example a payer funding account that is not `verified`, or a payee with no receiving bank account to credit. Field-level validation failures return `400`, not this. `error.details` carries per-attribute messages where the rule is attributable to one. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: unprocessable_entity message: The request could not be processed details: amount: - must be greater than 0 payee_id: - is required '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/payer_accounts/{payer_id}/payee_payments/{id}: get: summary: Get a Payee Payment description: Retrieve a payee payment, including its fees and ACH legs. operationId: PayablesGetPayeePayment tags: - Payee Payments parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: payer_id schema: type: string required: true example: payer_123xyz description: > the payer account this request is scoped to. Every payee, bank account, and payment lives under one payer account, so it is part of the path on all operate (Tier 1) routes. - in: path name: id schema: type: string required: true description: the id of the resource responses: '200': description: Successfully retrieved the payee payment content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: payee_payment data: type: object description: > A payee payment moves money from the account's funding bank account to a payee's receiving account over ACH. It orchestrates an inbound debit-pull, a hold, and an outbound credit, accruing fees along the way. There is no automatic retry, and a payment cannot be cancelled once initiated. A return ends the payment either at `failed` or, when the payer has already been debited, at `refunding_payer` — see `status`. properties: id: description: unique payee payment id type: string example: pp_123xyz type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee_payment payer_account_id: description: >- the id of the payer account this payment is scoped to type: string example: payer_123xyz amount: description: > the gross amount debited from the payer, in cents. The payee receives `amount` minus the sum of `fees` (e.g. `amount` 91000 with a 1000 fee pays the payee 90000). type: integer example: 91000 currency: type: string enum: - usd example: usd status: description: > the payment's position in its lifecycle. `initiated` → `inbound_submitted` → `holding` → `outbound_submitted` → `succeeded` is the happy path. **`holding` is a real wait.** Once the payer's funding has settled, the payee's credit is held until the next banking day before it is submitted, so a payment rests in `holding` rather than passing through it. Read `deposits_at` for when the payee is expected to be deposited; the hold is already in that estimate. **The hold only lifts for an active payer account and an active payee.** When the wait is up, the payee's credit is sent if both are `active`; if either is not, the payment stays in `holding` and is reconsidered periodically, so it pays out once both are active again. A hold that persists pushes the deposit past the `deposits_at` estimate, which is why that field is an estimate. Which return path a payment takes depends on whose money was already moved. A returned **inbound** debit-pull means nothing settled, so the payment is `failed` and no one is owed anything. A returned **outbound** credit means the payer was already debited, so the payment moves to `refunding_payer` and then `refunded` once the payer has their money back. Both `failed` and `refunded` are terminal. **`succeeded` is not the end.** ACH lets a return arrive days after an entry settled, so one can land after a payment has succeeded. That moves the payment to `failed_late_return`, which is terminal — JustiFi works the break by hand and records the corrective movement as a further leg on the same payment. See "A return that arrives after a payment succeeded" in the overview. **`failed_late_return` does not mean the payee holds nothing.** It reports that the payment did not stick, and the two ways that happens are opposites: a returned **outbound** credit means the payee never kept the money, while a returned **inbound** debit-pull means the payer's funding was clawed back *after* the payee was paid — so the payee still has it. **Re-sending on this status can pay a payee twice.** Read the payment's `transfers` to see which leg returned before acting. type: string enum: - initiated - inbound_submitted - holding - outbound_submitted - succeeded - failed - refunding_payer - refunded - failed_late_return example: succeeded payment_type: description: >+ how the funds move. ACH is the only option. Named `payment_type` rather than `payment_method`, which in the JustiFi API denotes a stored instrument object, not a rail. type: string enum: - ach example: ach payee_id: description: the payee being paid type: string example: pe_abc123 funding_bank_account_id: description: >- the account's funding bank account the principal is debit-pulled from type: string example: ba_fund456 receiving_bank_account_id: description: >- the payee's receiving account the principal is credited to type: string example: ba_recv123 debits_at: description: > in UTC, the estimated date and time the payer's funding account is debited (from the inbound leg); null until scheduled. Normally three banking days after the payment is submitted. type: string nullable: true format: date-time example: '2026-01-01T12:00:00Z' deposits_at: description: > in UTC, the estimated date and time the payee is deposited (from the outbound leg); null until scheduled. Each ACH leg takes three banking days and the payee's credit is held for one banking day after the payer's funding settles, so this is normally four banking days after `debits_at`. Estimated, and may shift if the provider revises an effective entry date. type: string nullable: true format: date-time example: '2026-01-04T12:00:00Z' description: type: string nullable: true example: Invoice 4021 fees: description: > the fees charged on this payment (v2 fee convention), carved out of `amount`. Supplied in the create request (required, no default) and echoed here. Fees incurred later by NOCs or returns are not shown here — they are billed to the platform monthly. type: array items: type: object description: > A fee charged on a payee payment, following the JustiFi v2 fee convention. Fees are **carved out of the payment `amount`** (the gross debited from the payer): the payee receives `amount` minus the sum of `fees`. The `fees` array is **required** on create with **no default** — the platform sets the fee explicitly (e.g. to net a payee 90000, pass `amount` 91000 with a 1000 fee). properties: type: type: string enum: - processing_fee description: > the fee type (v2 convention): - `processing_fee` — payment-processing cost, passed by platform example: processing_fee amount: type: integer description: fee amount in cents example: 1000 required: - type - amount transfers: description: the ACH legs that make up this payment type: array items: type: object description: >+ One leg of a payee payment. A payment has at least one inbound leg (debit-pull from the account's funding bank account) and one outbound leg (credit to the payee); refunds, reversals, and recoveries add further legs. Most legs are ACH; a leg JustiFi records off the ACH network (e.g. a manual recovery) carries a non-`ach` `transfer_type`. Scheduling values assigned by the bank are deliberately absent: the dates to read are `debits_at` and `deposits_at` on the payment, which are derived from these legs. properties: id: description: unique transfer leg id type: string example: ptr_123 direction: description: >- the direction of funds for this leg (a refund is an outbound, a recovery an inbound) type: string enum: - inbound - outbound example: inbound purpose: description: >- what this leg is — moves the principal, refunds the payer, or recovers owed funds from the payer type: string enum: - principal - refund - recovery example: principal transfer_type: description: > how the money moved. `ach` — over the ACH network; `manual` — a movement JustiFi recorded off it. Widens to further rails (e.g. `rtp`) without a breaking change. type: string enum: - ach - manual example: ach amount: description: the leg amount in cents type: integer example: 50000 status: description: the state of this leg type: string enum: - initiated - submitted - settled - returned - failed example: settled error_code: description: > normalised, rail-agnostic reason the leg failed, in snake_case (e.g. `insufficient_funds`). Stable across rails — **branch on this, not on `network_error_code`**, which is the network's own code and changes meaning between rails. Set when a leg is `failed` or `returned`, and null otherwise. A correction is not a failure: a leg that settled after a notification of change carries `network_error_code` but no `error_code`. A return code with no normalised equivalent reports `unclassified_return`, so this is never null on a leg that failed — the raw code is always there to fall back on. type: string nullable: true example: insufficient_funds error_description: description: >+ human-readable text for `error_code`, in English — for support and logs, not for branching. Null whenever `error_code` is. type: string nullable: true example: Insufficient funds in the account network_error_code: description: > the raw code from the network, verbatim — an ACH return code (`R01`). Preserved for reconciliation. Present whenever the network said anything about this leg, which is not only when it went wrong: a notification of change carries an advisory code (`C01`) on a leg that **settled** normally. Read it together with `status` — the code alone does not mean the money did not move. type: string nullable: true example: null metadata: description: >- any useful information you'd like to store alongside this payment type: object example: invoice_id: inv_4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-05T12:00:00Z' '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/platform_ledger: get: summary: List Platform Ledger Entries description: > List the platform's ledger entries — one per fee the platform earned, per JustiFi fee (payment, return handling, NOC handling), or per `settlement` paying the platform its balance, each referencing its source. Read-only and append-only; scoped to the platform your credentials belong to. The platform's outstanding balance is the **sum** of these entries; a `settlement` nets it toward zero. Optionally narrow to a window (`created_after`/`created_before`), a `txn_type`, or whether the entry has been settled (`settled`). operationId: PayablesListPlatformLedger tags: - Platform Ledger parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: query name: after_cursor description: >- token to fetch the next page of a list (the `end_cursor` from a previous response's `page_info`) schema: type: string - in: query name: before_cursor description: >- token to fetch the previous page of a list (the `start_cursor` from a previous response's `page_info`) schema: type: string - in: query name: limit description: the number of resources to retrieve per page (default 25, max 100) schema: type: integer default: 25 minimum: 1 maximum: 100 - in: query name: created_after schema: type: string format: date-time required: false example: '2026-01-01T00:00:00Z' description: > filter records created after the date and time (UTC) specified. Dates without a time default to 00:00:00 - in: query name: created_before schema: type: string format: date-time required: false example: '2026-01-01T00:00:00Z' description: > filter records created before the date and time (UTC) specified. Dates without a time default to 00:00:00 - in: query name: txn_type required: false schema: type: string enum: - processing_fee - justifi_fee - return_fee - noc_fee - settlement - adjustment description: filter entries by transaction type - in: query name: settled required: false schema: type: boolean description: > `false` returns the outstanding entries — those no `settlement` has covered yet, which together sum to the platform's current balance. responses: '200': description: Successfully listed platform ledger entries content: application/json: schema: allOf: - type: object description: >- the standard JustiFi response envelope for a list of records properties: id: description: >- always null for list responses — a list has no id of its own; the ids are on `data` type: 'null' type: description: the object type type: string example: array data: description: the list of objects type: array items: type: object page_info: type: object description: cursor pagination info properties: start_cursor: description: >- the encoded id of the first record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd end_cursor: description: >- the encoded id of the last record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd has_next: description: >- true if there are records following the current page type: boolean default: false has_previous: description: >- true if there are records ahead of the current page type: boolean default: false required: - id - type - data - page_info - properties: type: example: array data: type: array items: type: object description: > One entry in the platform's single-entry ledger — a fee the platform earned, a JustiFi fee, or a `settlement` squaring the balance up — each referencing its source. Read-only and append-only. Sign follows the balance convention: **positive** increases what JustiFi owes the platform (fees earned), **negative** decreases it (JustiFi fees, return and NOC handling). The platform's balance is the sum of its entries. **A `settlement` takes whichever sign closes the set it covers**, so it is normally negative — paying a platform the balance its fees accrued — and positive when the balance being squared up is one the platform owes, which happens when JustiFi's fees on a payment exceeded the platform's own. properties: id: type: string example: ple_123xyz type: description: >- the object type, matching the enclosing envelope's `type` type: string example: ledger_entry platform_account_id: description: the platform ledger this entry posts to type: string example: acc_123xyz txn_type: description: > the kind of entry. `settlement` is JustiFi squaring up with the platform — it closes the balance the other entries accrued, and its `settlement_id` names the entries it covers. `adjustment` is a correction: entries are never edited, so a correction to an already-settled entry posts as a new `adjustment` and is swept by the next settlement. Not to be confused with an ACH leg reaching `settled` — that is money clearing the network, and it is reported on the payment's legs rather than here. type: string enum: - processing_fee - justifi_fee - return_fee - noc_fee - settlement - adjustment example: justifi_fee amount_cents: description: > signed amount, in cents. Positive = owed to the platform; negative = charged to, or paid out to, the platform. On a `settlement`, whichever of those closes the set it covers. type: integer example: 1000 currency: type: string enum: - usd example: usd payer_account_id: description: >- the payer account whose payment this entry derives from; set on fee entries, null on a `settlement` type: string nullable: true example: payer_123xyz payee_payment_id: description: >- the payee payment this entry derives from, if any (payment / JustiFi fees) type: string nullable: true example: pp_9 payee_payment_fee_id: description: > on a `processing_fee` entry — the submitted fee this entry was posted from. Links the platform's declared intent to the frozen ledger entry. type: string nullable: true example: null source_type: description: >+ the kind of object that caused this entry, mirroring how balance transactions identify their source elsewhere in the JustiFi API. A return or NOC fee names the `transfer` it arose from. type: string nullable: true enum: - payee_payment - transfer - settlement - null example: transfer source_id: description: >+ the id of the object named by `source_type`. On a `settlement` this is the **platform settlement** (`pst_`) the entry was written for. type: string nullable: true example: ptr_123 external_reference: description: > on a `settlement` — the external ACH/wire/manual reference for the money that moved. An identifier from outside Payables rather than a Payables id, which is why it is not folded into `source_id`. type: string nullable: true example: null settlement_id: description: > the **platform settlement** (`pst_`) that covered this entry, if any — **null means the entry is still outstanding**. Every entry sharing a `settlement_id` sums to zero, so the ledger balance is exactly the sum of the entries where this is null. The `settlement` entry that balances a set carries the same value as the entries it closes, because it is one of them. Its `source_id` is that id too: a balancing entry both belongs to a settlement and is the entry written for it. type: string nullable: true example: pst_987abc created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/platform_settlements: get: summary: List Platform Settlements description: > List the disbursements between JustiFi and your platform — when each happens, how much, which way the money goes, and the reference to reconcile it against your bank statement. Read-only and scoped to the platform your credentials belong to. This answers "when were we paid" directly. The same facts are derivable from `/v1/payables/platform_ledger` by filtering to `txn_type=settlement`, but a ledger entry is one line: it carries neither the reference nor what the disbursement covered, and it does not exist until after the money has moved. A settlement appears here while it is still `scheduled`. Optionally narrow to a `status` or a window (`created_after`/`created_before`). operationId: PayablesListPlatformSettlements tags: - Platform Settlements parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: query name: after_cursor description: >- token to fetch the next page of a list (the `end_cursor` from a previous response's `page_info`) schema: type: string - in: query name: before_cursor description: >- token to fetch the previous page of a list (the `start_cursor` from a previous response's `page_info`) schema: type: string - in: query name: limit description: the number of resources to retrieve per page (default 25, max 100) schema: type: integer default: 25 minimum: 1 maximum: 100 - in: query name: created_after schema: type: string format: date-time required: false example: '2026-01-01T00:00:00Z' description: > filter records created after the date and time (UTC) specified. Dates without a time default to 00:00:00 - in: query name: created_before schema: type: string format: date-time required: false example: '2026-01-01T00:00:00Z' description: > filter records created before the date and time (UTC) specified. Dates without a time default to 00:00:00 - in: query name: status required: false schema: type: string enum: - scheduled - in_transit - paid - failed - canceled - forwarded description: filter settlements by status responses: '200': description: Successfully listed platform settlements content: application/json: schema: allOf: - type: object description: >- the standard JustiFi response envelope for a list of records properties: id: description: >- always null for list responses — a list has no id of its own; the ids are on `data` type: 'null' type: description: the object type type: string example: array data: description: the list of objects type: array items: type: object page_info: type: object description: cursor pagination info properties: start_cursor: description: >- the encoded id of the first record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd end_cursor: description: >- the encoded id of the last record in the current page type: string example: >- WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd has_next: description: >- true if there are records following the current page type: boolean default: false has_previous: description: >- true if there are records ahead of the current page type: boolean default: false required: - id - type - data - page_info - properties: type: example: array data: type: array items: type: object description: > One disbursement between JustiFi and your platform: when it happens, how much, which way the money goes, and the reference to reconcile it against your bank statement. A settlement is **declared and then recorded**. It is `scheduled` with a frozen amount before any money moves, and only reaches `paid` once it has. A scheduled settlement is a statement of intent, not a promise — `failed` and `canceled` can still take it away. properties: id: description: unique settlement id type: string example: pst_abc123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: platform_settlement platform_account_id: description: >- the platform this settlement is between JustiFi and type: string example: acc_123xyz status: description: > where the disbursement is in its lifecycle. `scheduled` — the amount is frozen and the disbursement is queued to be paid; `in_transit` — instructed, with a reference attached, not yet confirmed; `paid` — the money moved; `failed` — it did not, and the balance it covered is owed again; `canceled` — withdrawn before it moved, same effect; `forwarded` — a later settlement took over what this one failed to pay. type: string enum: - scheduled - in_transit - paid - failed - canceled - forwarded example: paid direction: description: > which way the money goes. `paid_out` — JustiFi pays your platform its accrued balance; `charged` — JustiFi collects, because the fees it levied over the period exceeded the ones your platform earned. Read this rather than a sign: `amount_cents` is always positive. type: string enum: - paid_out - charged example: paid_out amount_cents: description: >- the amount of the disbursement, always positive — `direction` says which way it goes type: integer example: 124500 currency: type: string enum: - usd example: usd entries_count: description: > how many platform ledger entries this settlement covers, its own balancing entry included. To read the entries themselves, list `/v1/payables/platform_ledger` and match on `settlement_id`. type: integer example: 42 ledger_entry_id: description: >- the `settlement` entry on your platform ledger that balances what this covers type: string example: ple_123xyz external_reference: description: > the ACH, wire or manual reference for the money movement — what to match against your bank statement. Null until the disbursement is instructed. type: string nullable: true example: WIRE-20260819-0042 scheduled_at: description: >- when the amount was frozen and the disbursement was queued type: string format: date-time example: '2026-08-19T12:00:00Z' recorded_at: description: when the money moved; null until it has type: string nullable: true format: date-time example: '2026-08-21T09:30:00Z' created_at: type: string format: date-time example: '2026-08-19T12:00:00Z' updated_at: type: string format: date-time example: '2026-08-21T09:30:00Z' '400': description: > The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: bad_request message: payee pe_abc123 is archived and cannot be paid '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded /payables/platform_settlements/{id}: get: summary: Get a Platform Settlement operationId: PayablesGetPlatformSettlement tags: - Platform Settlements parameters: - in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) - in: path name: id schema: type: string required: true description: the id of the resource responses: '200': description: Successfully retrieved the settlement content: application/json: schema: allOf: - type: object description: the standard JustiFi response envelope for a single record properties: id: description: the object id, also found in the data object type: string example: prefix_xyz (same as id of data object) type: description: the object type type: string example: payee_payment data: description: the attributes for the object type: object page_info: description: cursor pagination info; always null for single records type: 'null' required: - id - type - data - page_info - properties: type: example: platform_settlement data: type: object description: > One disbursement between JustiFi and your platform: when it happens, how much, which way the money goes, and the reference to reconcile it against your bank statement. A settlement is **declared and then recorded**. It is `scheduled` with a frozen amount before any money moves, and only reaches `paid` once it has. A scheduled settlement is a statement of intent, not a promise — `failed` and `canceled` can still take it away. properties: id: description: unique settlement id type: string example: pst_abc123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: platform_settlement platform_account_id: description: >- the platform this settlement is between JustiFi and type: string example: acc_123xyz status: description: > where the disbursement is in its lifecycle. `scheduled` — the amount is frozen and the disbursement is queued to be paid; `in_transit` — instructed, with a reference attached, not yet confirmed; `paid` — the money moved; `failed` — it did not, and the balance it covered is owed again; `canceled` — withdrawn before it moved, same effect; `forwarded` — a later settlement took over what this one failed to pay. type: string enum: - scheduled - in_transit - paid - failed - canceled - forwarded example: paid direction: description: > which way the money goes. `paid_out` — JustiFi pays your platform its accrued balance; `charged` — JustiFi collects, because the fees it levied over the period exceeded the ones your platform earned. Read this rather than a sign: `amount_cents` is always positive. type: string enum: - paid_out - charged example: paid_out amount_cents: description: >- the amount of the disbursement, always positive — `direction` says which way it goes type: integer example: 124500 currency: type: string enum: - usd example: usd entries_count: description: > how many platform ledger entries this settlement covers, its own balancing entry included. To read the entries themselves, list `/v1/payables/platform_ledger` and match on `settlement_id`. type: integer example: 42 ledger_entry_id: description: >- the `settlement` entry on your platform ledger that balances what this covers type: string example: ple_123xyz external_reference: description: > the ACH, wire or manual reference for the money movement — what to match against your bank statement. Null until the disbursement is instructed. type: string nullable: true example: WIRE-20260819-0042 scheduled_at: description: >- when the amount was frozen and the disbursement was queued type: string format: date-time example: '2026-08-19T12:00:00Z' recorded_at: description: when the money moved; null until it has type: string nullable: true format: date-time example: '2026-08-21T09:30:00Z' created_at: type: string format: date-time example: '2026-08-19T12:00:00Z' updated_at: type: string format: date-time example: '2026-08-21T09:30:00Z' '400': description: > The request was malformed, failed validation, or referenced a resource that cannot be used in its current state — for example scheduling a payment to a payee that is not active, or creating anything under a payer account that is not active. When the failure is field-level, `error.details` carries one array of messages per rejected attribute. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: bad_request message: payee pe_abc123 is archived and cannot be paid '401': description: The access token is missing, expired, or invalid. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authenticated message: The access token provided is invalid or has expired '403': description: The credentials are valid but not permitted to access this resource. content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: not_authorized message: >- Your credentials do not have access to the requested payer account '404': description: >- No resource exists for the given id (within the scoped payer account). content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: resource_not_found message: No payee_payment found with id pp_123xyz '429': description: >- The rate limit has been exceeded. Back off and retry after the interval indicated by the `Retry-After` header. headers: Retry-After: description: the number of seconds to wait before retrying schema: type: integer example: 30 content: application/json: schema: type: object description: > the standard error envelope. Every non-2xx response returns this shape so clients can branch on a stable machine-readable `code` and surface `message` to users. properties: error: type: object required: - code - message properties: code: description: a stable, machine-readable error code type: string example: unprocessable_entity message: description: a human-readable description of what went wrong type: string example: payee_id is required details: description: >- optional field-level detail, keyed by request attribute type: object additionalProperties: type: array items: type: string example: amount: - must be greater than 0 required: - error example: error: code: too_many_requests message: Rate limit exceeded x-webhooks: payments: post: description: > Received for the following events: payment.created, payment.succeeded, payment.failed, payment.pending, payment.authorized, payment.captured, payment.canceled tags: - Events operationId: paymentEvent summary: Payments requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: oneOf: - $ref: '#/components/schemas/CardPayment' - $ref: '#/components/schemas/BankAccountPayment' example: null examples: Card_payment_created_event: value: id: evt_123xyz account_id: acc_123xyz account_type: test platform_account_id: acc_987zyx idempotency_key: string request_id: req_123 version: v1 data: id: py_xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: my order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz refunded: false returned: false status: succeeded terminal_id: trm_123_xyz updated_at: '2021-01-01T12:00:00Z' payment_method: card: id: pm_123xyz acct_last_four: '4242' brand: visa name: Sylvia Fowles token: pm_123xyz metadata: {} bin_details: type: Debit card_brand: Visa card_class: Consumer country: United States of America issuer: WELLS FARGO BANK funding_source: Debit created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: null signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] event_name: payment.created Bank_account_payment_created_event: value: id: evt_123xyz account_id: acc_123xyz account_type: test platform_account_id: acc_987zyx idempotency_key: string request_id: req_123 version: v1 data: id: py_xyz account_id: acc_123xyz amount_disputed: 0 amount_refunded: 0 amount_returned: 0 amount: 10000 amount_refundable: 10000 application_fee_rate_id: afr_123xyz balance: 99850 capture_strategy: automatic captured: true created_at: '2021-01-01T12:00:00Z' currency: usd description: my order xyz disputed: false error_code: null error_description: null fee_amount: 150 financial_transaction_id: ft_123xyz is_test: true metadata: {} payment_intent_id: pi_xyz refunded: false returned: false status: succeeded updated_at: '2021-01-01T12:00:00Z' payment_method: bank_account: id: pm_123xyz acct_last_four: '4242' name: Sylvia Fowles brand: Wells Fargo token: pm_123xyz created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' customer_id: cust_123xyz signature: 123abc application_fee: id: fee_123xyz amount: 150 currency: usd created_at: '2021-01-01T12:00:00Z' updated_at: '2021-01-01T12:00:00Z' transaction_hold: id: th_123xyz financial_transaction_id: ft_123xyz refunds: [] disputes: [] event_name: payment.created responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. payment_methods: post: description: > Received for the following events: payment_method.created, payment_method.updated, payment_method.bin_mapped tags: - Events operationId: paymentMethodEvent summary: Payment Methods requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: allOf: - oneOf: - $ref: '#/components/schemas/CardPaymentMethod' - $ref: '#/components/schemas/BankAccountPaymentMethod' - type: object properties: id: description: unique id of the payment method type: string example: pm_123xyz example: null examples: Card_payment_method_created_event: value: id: evt_123xyz account_id: acc_123xyz account_type: test platform_account_id: acc_456abc idempotency_key: 30abie390hjag49h request_id: req_100abc version: v1 data: id: pm_123xyz signature: 9fxy123 customer_id: cust_987zyx status: valid invalid_reason: nil card: id: pm_123xyz name: Sylvia Fowles acct_last_four: '4242' brand: visa token: pm_123xyz month: '5' year: '2042' metadata: {} address_line1_check: pass address_postal_code_check: pass event_name: payment_method.created Bank_account_payment_method_created_event: value: id: evt_123xyz account_id: acc_123xyz account_type: test platform_account_id: acc_456abc idempotency_key: 30abie390hjag49h request_id: req_100abc version: v1 data: id: pm_123xyz signature: 9fxy123 customer_id: cust_987zyx status: valid invalid_reason: nil bank_account: id: pm_123xyz acct_last_four: '9876' brand: Wells Fargo name: Phil Kessel token: pm_123xyz metadata: {} event_name: payment_method.created Card_payment_method_bin_mapped_event: value: id: evt_123xyz account_id: acc_123xyz account_type: test platform_account_id: acc_456abc idempotency_key: 30abie390hjag49h request_id: req_100abc version: v1 data: id: pm_123xyz signature: 9fxy123 customer_id: cust_987zyx status: valid invalid_reason: nil card: id: pm_123xyz name: Sylvia Fowles acct_last_four: '4242' brand: visa token: pm_123xyz month: '5' year: '2042' metadata: {} address_line1_check: pass address_postal_code_check: pass bin_details: type: Debit card_brand: Visa card_class: Consumer country: United States of America issuer: WELLS FARGO BANK funding_source: Debit event_name: payment_method.bin_mapped responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. refunds: post: description: > Received for the following events: payment.refunded, payment.refund.updated tags: - Events operationId: refundEvent summary: Refunds requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/Refund' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. disputes: post: description: > Received for the following events: payment.dispute.created, payment.dispute.closed, payment.dispute.forfeited, payment.dispute.submitted tags: - Events operationId: disputeEvent summary: Disputes requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/Dispute' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. dispute_evidence: post: description: > Received for the following events: payment.dispute_evidence.created, payment.dispute_evidence.uploaded tags: - Events operationId: disputeEvidenceEvent summary: Dispute Evidence requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/DisputeEvidence' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. payouts: post: description: > Received for the following events: payout.created, payout.paid, payout.failed, proceeds.payout.created tags: - Events operationId: payoutEvent summary: Payouts requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/Payout' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. sub_accounts: post: description: > Received for the following events: sub_account.updated. This is published when an account's status changes. tags: - Events operationId: subAccountEvent summary: Sub Accounts requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/SubAccount' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. application_fee_rates: post: description: > Received for the following events: application_fee_rate.created, application_fee_rate.updated tags: - Events operationId: applicationFeeRateEvent summary: Application Fee Rates requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/ApplicationFeeRate' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. checkouts: post: description: | Received for the following events: checkout.created, checkout.completed tags: - Events operationId: checkoutEvent summary: Checkouts requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/Checkout' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. checkout_completions: post: description: > Received for the following events: checkout.completion.succeeded, checkout.completion.failed, and checkout.completion.processing. Note checkout.completion.processing is only sent for terminal payments when a payment amount is sent to a terminal for processing. tags: - Events operationId: checkoutCompletionEvent summary: Checkout Completions requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/CheckoutCompletion' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. payment_setting_updated: post: description: | Received for the following event: account.payment_setting.updated tags: - Events operationId: accountPaymentSettingUpdatedEvent summary: Account Payment Setting Updated requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/PaymentSetting' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. payout_setting_updated: post: description: | Received for the following event: account.payout_setting.updated tags: - Events operationId: accountPayoutSettingUpdatedEvent summary: Account Payout Setting Updated requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/PayoutSetting' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. terminal_orders: post: description: > Received for the following events: terminal_order.created, terminal_order.updated tags: - Events operationId: terminalOrderEvent summary: Terminal Orders requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/TerminalsOrder' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. reports: post: description: > Received for the following events: report.scheduled, report.processing, report.completed, report.failed, report.canceled tags: - Events operationId: reportEvent summary: Reports requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/Report' responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. forwarding_requests: post: description: > Received for the following events: forwarding_request.completed, forwarding_request.failed `forwarding_request.completed` means the destination answered. Check `data.response.status_code` to see whether the request was accepted. `forwarding_request.failed` means the destination could not be reached, and `data.failure_reason` explains why. Forwarding requests are attempted once and are not retried, so exactly one of these two events is published per forwarding request. tags: - Events operationId: forwardingRequestEvent summary: Forwarding Requests (Beta) requestBody: content: application/json: schema: allOf: - $ref: '#/components/schemas/Event' - properties: data: $ref: '#/components/schemas/ForwardingRequest' example: null examples: Forwarding_request_completed_event: value: id: evt_123xyz account_id: acc_123xyz account_type: test platform_account_id: acc_456abc idempotency_key: 30abie390hjag49h request_id: req_100abc version: v1 data: id: fwd_123xyz account_id: acc_123xyz payment_method_id: pm_123xyz url: https://api.stripe.com/v1/payment_methods http_method: POST provider: stripe status: completed failure_reason: null replacements: - card_number - card_expiry_month - card_expiry_year - cardholder_name request: body: type: card card: number: '4242' exp_month: 5 exp_year: 2042 billing_details: name: Lindsay Whalen headers: Authorization: '[FILTERED]' response: id: fwdr_123xyz status_code: 200 body: id: pm_1QabcStripeExample object: payment_method card: last4: '4242' headers: content-type: application/json response_time_ms: 512 attempted_at: '2024-01-01T12:00:01Z' created_at: '2024-01-01T12:00:00Z' updated_at: '2024-01-01T12:00:02Z' event_name: forwarding_request.completed Forwarding_request_failed_event: value: id: evt_123xyz account_id: acc_123xyz account_type: test platform_account_id: acc_456abc idempotency_key: 30abie390hjag49h request_id: req_100abc version: v1 data: id: fwd_123xyz account_id: acc_123xyz payment_method_id: pm_123xyz url: https://api.stripe.com/v1/payment_methods http_method: POST provider: stripe status: failed failure_reason: timeout replacements: - card_number request: body: card: number: '4242' headers: Authorization: '[FILTERED]' response: null attempted_at: '2024-01-01T12:00:01Z' created_at: '2024-01-01T12:00:00Z' updated_at: '2024-01-01T12:01:31Z' event_name: forwarding_request.failed responses: '200': description: >- Return a 200 status to indicate that the data was received successfully. You must respond within 5 seconds. payer_account: post: summary: Payer account events description: > Delivered as a payer account is provisioned for Payables and as its state changes. The `data` object is the full `PayerAccount`. | Event | Meaning | | ----- | ------- | | `payables.payer_account.provisioned` | the business was provisioned to use Payables (now `active`) | | `payables.payer_account.updated` | the account's details changed | | `payables.payer_account.disabled` | the account can no longer initiate payments, create payees or register bank accounts | | `payables.payer_account.archived` | the account was archived | Return a `200` within 5 seconds to acknowledge receipt; non-2xx responses are retried with backoff. operationId: PayablesPayerAccountEvent tags: - Payables Events security: [] requestBody: content: application/json: schema: allOf: - type: object description: the envelope wrapping every webhook event JustiFi delivers properties: id: description: event unique id type: string example: evt_123xyz event_name: description: > name of the event, namespaced under `payables.` (e.g. payables.payee_payment.succeeded, payables.bank_account.corrected) type: string example: payables.payee_payment.succeeded idempotency_key: description: >- idempotency key of the request that produced the event, when available type: string nullable: true account_id: description: > the sub account the event is scoped to, where one applies. **Always null for Payables** — a payer account is a first-class entity with its own `payer_…` id and is not a sub account, so there is nothing of this shape to report. The field is retained because the event envelope is shared across JustiFi services. type: string nullable: true example: null platform_account_id: description: the platform account the event is scoped to type: string nullable: true example: acc_987zyx version: description: version of the event payload type: string example: v1 data: description: the attributes for the object the event concerns type: object created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' - properties: event_name: enum: - payables.payer_account.provisioned - payables.payer_account.updated - payables.payer_account.disabled - payables.payer_account.archived data: type: object description: > A payer account is the payer in Payables — a first-class Payables entity with its own `payer_…` id. Every payee, bank account, and payment is scoped to one payer account. Each payer account belongs to a JustiFi business (`business_id`). The record is created (`pending`) when a platform begins provisioning Payables, and becomes `active` once JustiFi's risk platform reports the business has met Payables's onboarding requirements — a lighter bar than our payments-processing product, so a business can be Payables-ready before it is enabled for payments. The customer-facing API exposes payer accounts read-only. properties: id: description: unique payer account id type: string example: payer_123xyz type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payer_account business_id: description: > the JustiFi business this payer account belongs to. Requests operate *within* a payer account (see the `/v1/payables/payer_accounts/{payer_id}/…` routes); `business_id` records the owning business for reporting and cross-account grouping, it is not the request scope. Discover a business's payer accounts with `GET /v1/payables/payer_accounts?business=biz_…`. type: string example: biz_123xyz name: description: display name for the payer account type: string example: Northside Physical Therapy mode: description: > whether this payer account operates against real money. Inherited from the JustiFi account it belongs to — a test account and a live account are different accounts with different ids, so a payer account is one or the other for its life and cannot be switched. In `test`, payments run against a simulated ACH network: they complete in seconds rather than banking days, and no money moves. type: string enum: - test - live example: live status: description: > the payer account's Payables lifecycle state, and what each state prevents. `pending` — provisioning has begun but the risk platform has not yet reported the business Payables-ready; `active` — Payables-ready, and the only state under which anything can be created; `disabled` — was active previously, and can no longer schedule payments, create payees or register bank accounts; `archived` — the same, and permanent: an archived payer account cannot be reactivated. A payment whose payee credit is already held is not paid out while the account is not `active`. It stays held until the account is active again, rather than failing. type: string enum: - pending - active - disabled - archived example: active provisioned_at: description: >- when the payer account was provisioned to use Payables; null until provisioning completes type: string nullable: true format: date-time example: '2026-01-01T12:00:00Z' funding_bank_account_id: description: > pointer to the payer account's active funding bank account. In this version a payer account has a single active funding account. Null until one is registered and verified. type: string nullable: true example: ba_fund456 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' responses: '200': description: >- Return a 200 status to indicate the event was received successfully (within 5 seconds). payee: post: summary: Payee events description: > Delivered as payees are created, updated, or archived — useful for keeping your own records in sync. The `data` object is the full `Payee`. | Event | Meaning | | ----- | ------- | | `payables.payee.created` | a payee was created | | `payables.payee.updated` | a payee's details changed (name, address, email, default account) | | `payables.payee.disabled` | a payee was disabled and can no longer be paid — including when its bank refuses the credit or corrects the account without saying what to. Register a corrected receiving account to make it payable again | | `payables.payee.archived` | a payee was archived and can no longer be paid | `entity_type` and `tax_id` never move, so no event reports them changing. Return a `200` within 5 seconds to acknowledge receipt; non-2xx responses are retried with backoff. operationId: PayablesPayeeEvent tags: - Payables Events security: [] requestBody: content: application/json: schema: allOf: - type: object description: the envelope wrapping every webhook event JustiFi delivers properties: id: description: event unique id type: string example: evt_123xyz event_name: description: > name of the event, namespaced under `payables.` (e.g. payables.payee_payment.succeeded, payables.bank_account.corrected) type: string example: payables.payee_payment.succeeded idempotency_key: description: >- idempotency key of the request that produced the event, when available type: string nullable: true account_id: description: > the sub account the event is scoped to, where one applies. **Always null for Payables** — a payer account is a first-class entity with its own `payer_…` id and is not a sub account, so there is nothing of this shape to report. The field is retained because the event envelope is shared across JustiFi services. type: string nullable: true example: null platform_account_id: description: the platform account the event is scoped to type: string nullable: true example: acc_987zyx version: description: version of the event payload type: string example: v1 data: description: the attributes for the object the event concerns type: object created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' - properties: event_name: enum: - payables.payee.created - payables.payee.updated - payables.payee.disabled - payables.payee.archived data: type: object description: > A payee is a party that receives Payables payments. Payees are standalone: they can exist and be paid without being tied to a business. `business_id` reports a link to a JustiFi business where there is one, and is null by default. properties: id: description: unique payee id type: string example: pe_abc123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee payer_account_id: description: the id of the payer account this payee is scoped to type: string example: payer_123xyz name: description: the payee's legal name. Required on create. type: string example: Acme Plumbing LLC entity_type: description: > the payee's IRS entity classification. Required on create, with no default — it decides both the tax form filed for the payee and, for `sole_proprietorship`, how the ACH credit to them is classified. Immutable — with `tax_id` it is the taxpayer this payee is filed against. The set is open and may grow; unknown values should be treated as a business entity. type: string enum: - c_corporation - s_corporation - partnership - limited_liability_company - sole_proprietorship example: limited_liability_company email: description: contact email for the payee, when provided type: string nullable: true format: email example: billing@acmeplumbing.com tax_id_last4: description: > the last four digits of the payee's taxpayer identification number — an EIN, or an SSN where the payee is a `sole_proprietorship`. The number itself is required on create and never returned — it is stored encrypted, and this is what reads back. Immutable, on the same terms as `entity_type`. type: string example: '4021' address: type: object description: the payee's address. Required on create. properties: line1: description: street address type: string example: 123 Example St line2: description: suite, unit or floor, when there is one type: string nullable: true example: Suite 101 city: type: string example: Minneapolis state: description: > two-letter state or territory code, uppercase. Not normalized — `mn` is rejected rather than corrected. type: string pattern: ^[A-Z]{2}$ example: MN postal_code: description: ZIP or ZIP+4 type: string pattern: ^\d{5}(-\d{4})?$ example: '55555' country: description: > ISO 3166-1 alpha-3 country code, matching the rest of JustiFi. `USA` is the only value Payables accepts — it pays by US domestic ACH and files US tax forms — and it is what a payee gets when the field is omitted. type: string enum: - USA default: USA example: USA receiving_bank_account_id: description: > pointer to the payee's active receiving bank account (denormalized for lookup, like capital's `accounts.payout_account_id`). In this version a payee has a single active account. Null until one is registered. type: string nullable: true example: ba_recv123 business_id: description: >+ the business this payee belongs to, where JustiFi has linked one. Null for standalone payees, and a payee is created and paid without one. type: string nullable: true example: null status: description: > the payee's status. `pending` — created but not cleared for payments; `active` — able to receive payments, and the only state a payment can be scheduled or paid out under; `disabled` — was active previously and can no longer be paid; `archived` — was active previously and can never be paid again. A payment whose payee credit is already held is not paid out while the payee is not `active`. It stays held until the payee is active again, rather than failing. **Payables disables a payee when its bank says the account cannot be paid.** Either the bank returned a credit for a reason a retry will not change — the account is closed, frozen, not a transaction account, or does not exist — or it sent a notification of change we cannot act on, because it named no corrected numbers or corrects something Payables does not hold. Both mean the next payment would go to an account the bank has already refused. A correction about the entry rather than the account — the payee's name, the entry description — changes nothing. **Registering a corrected receiving bank account returns the payee to `active`**, and any payment held for it pays out on the next cycle. Until then those payments wait rather than failing, which is what stops a queue of payments following the first one into a closed account. type: string enum: - pending - active - disabled - archived example: active metadata: description: >- any useful information you'd like to store alongside this payee type: object example: erp_payee_id: V-4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' responses: '200': description: >- Return a 200 status to indicate the event was received successfully (within 5 seconds). payee_payment: post: summary: Payee payment lifecycle events description: > Delivered as a payee payment moves through its lifecycle. One webhook fires per transition. All Payables events are namespaced under `payables.` so they never collide with JustiFi's core `payment.*` events. | Event | Meaning | | ----- | ------- | | `payables.payee_payment.initiated` | the payment was accepted and scheduled | | `payables.payee_payment.inbound_submitted` | the debit-pull from the payer has been submitted | | `payables.payee_payment.holding` | the debit-pull settled and the funds are held | | `payables.payee_payment.outbound_submitted` | the credit to the payee has been submitted | | `payables.payee_payment.succeeded` | the outbound credit to the payee has settled | | `payables.payee_payment.failed` | the debit-pull was returned, or a leg failed before the payee was paid (no automatic retry) | | `payables.payee_payment.refunding_payer` | the payee credit failed and the payer is being refunded | | `payables.payee_payment.refunded` | the payer has been refunded (`amount` less any retained fees) | | `payables.payee_payment.failed_late_return` | a return arrived after the payment succeeded, so the payment did not stick — the returned leg is on `transfers` | **Events are named for what happened**, and every payment status has one. Read the payload rather than the name to know where a payment stands. `failed_late_return` is worth reading twice: it does **not** mean the payee holds nothing. A returned outbound credit means the payee never kept the money; a returned inbound debit-pull means the payer's funding was clawed back after the payee was paid. **Re-sending on this event can pay a payee twice.** The `data` object is the full `PayeePayment`. Return a `200` within 5 seconds to acknowledge receipt; non-2xx responses are retried with backoff. operationId: PayablesPayeePaymentEvent tags: - Payables Events security: [] requestBody: content: application/json: schema: allOf: - type: object description: the envelope wrapping every webhook event JustiFi delivers properties: id: description: event unique id type: string example: evt_123xyz event_name: description: > name of the event, namespaced under `payables.` (e.g. payables.payee_payment.succeeded, payables.bank_account.corrected) type: string example: payables.payee_payment.succeeded idempotency_key: description: >- idempotency key of the request that produced the event, when available type: string nullable: true account_id: description: > the sub account the event is scoped to, where one applies. **Always null for Payables** — a payer account is a first-class entity with its own `payer_…` id and is not a sub account, so there is nothing of this shape to report. The field is retained because the event envelope is shared across JustiFi services. type: string nullable: true example: null platform_account_id: description: the platform account the event is scoped to type: string nullable: true example: acc_987zyx version: description: version of the event payload type: string example: v1 data: description: the attributes for the object the event concerns type: object created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' - properties: event_name: enum: - payables.payee_payment.initiated - payables.payee_payment.inbound_submitted - payables.payee_payment.holding - payables.payee_payment.outbound_submitted - payables.payee_payment.succeeded - payables.payee_payment.failed - payables.payee_payment.refunding_payer - payables.payee_payment.refunded - payables.payee_payment.failed_late_return data: type: object description: > A payee payment moves money from the account's funding bank account to a payee's receiving account over ACH. It orchestrates an inbound debit-pull, a hold, and an outbound credit, accruing fees along the way. There is no automatic retry, and a payment cannot be cancelled once initiated. A return ends the payment either at `failed` or, when the payer has already been debited, at `refunding_payer` — see `status`. properties: id: description: unique payee payment id type: string example: pp_123xyz type: description: >- the object type, matching the enclosing envelope's `type` type: string example: payee_payment payer_account_id: description: >- the id of the payer account this payment is scoped to type: string example: payer_123xyz amount: description: > the gross amount debited from the payer, in cents. The payee receives `amount` minus the sum of `fees` (e.g. `amount` 91000 with a 1000 fee pays the payee 90000). type: integer example: 91000 currency: type: string enum: - usd example: usd status: description: > the payment's position in its lifecycle. `initiated` → `inbound_submitted` → `holding` → `outbound_submitted` → `succeeded` is the happy path. **`holding` is a real wait.** Once the payer's funding has settled, the payee's credit is held until the next banking day before it is submitted, so a payment rests in `holding` rather than passing through it. Read `deposits_at` for when the payee is expected to be deposited; the hold is already in that estimate. **The hold only lifts for an active payer account and an active payee.** When the wait is up, the payee's credit is sent if both are `active`; if either is not, the payment stays in `holding` and is reconsidered periodically, so it pays out once both are active again. A hold that persists pushes the deposit past the `deposits_at` estimate, which is why that field is an estimate. Which return path a payment takes depends on whose money was already moved. A returned **inbound** debit-pull means nothing settled, so the payment is `failed` and no one is owed anything. A returned **outbound** credit means the payer was already debited, so the payment moves to `refunding_payer` and then `refunded` once the payer has their money back. Both `failed` and `refunded` are terminal. **`succeeded` is not the end.** ACH lets a return arrive days after an entry settled, so one can land after a payment has succeeded. That moves the payment to `failed_late_return`, which is terminal — JustiFi works the break by hand and records the corrective movement as a further leg on the same payment. See "A return that arrives after a payment succeeded" in the overview. **`failed_late_return` does not mean the payee holds nothing.** It reports that the payment did not stick, and the two ways that happens are opposites: a returned **outbound** credit means the payee never kept the money, while a returned **inbound** debit-pull means the payer's funding was clawed back *after* the payee was paid — so the payee still has it. **Re-sending on this status can pay a payee twice.** Read the payment's `transfers` to see which leg returned before acting. type: string enum: - initiated - inbound_submitted - holding - outbound_submitted - succeeded - failed - refunding_payer - refunded - failed_late_return example: succeeded payment_type: description: >+ how the funds move. ACH is the only option. Named `payment_type` rather than `payment_method`, which in the JustiFi API denotes a stored instrument object, not a rail. type: string enum: - ach example: ach payee_id: description: the payee being paid type: string example: pe_abc123 funding_bank_account_id: description: >- the account's funding bank account the principal is debit-pulled from type: string example: ba_fund456 receiving_bank_account_id: description: >- the payee's receiving account the principal is credited to type: string example: ba_recv123 debits_at: description: > in UTC, the estimated date and time the payer's funding account is debited (from the inbound leg); null until scheduled. Normally three banking days after the payment is submitted. type: string nullable: true format: date-time example: '2026-01-01T12:00:00Z' deposits_at: description: > in UTC, the estimated date and time the payee is deposited (from the outbound leg); null until scheduled. Each ACH leg takes three banking days and the payee's credit is held for one banking day after the payer's funding settles, so this is normally four banking days after `debits_at`. Estimated, and may shift if the provider revises an effective entry date. type: string nullable: true format: date-time example: '2026-01-04T12:00:00Z' description: type: string nullable: true example: Invoice 4021 fees: description: > the fees charged on this payment (v2 fee convention), carved out of `amount`. Supplied in the create request (required, no default) and echoed here. Fees incurred later by NOCs or returns are not shown here — they are billed to the platform monthly. type: array items: type: object description: > A fee charged on a payee payment, following the JustiFi v2 fee convention. Fees are **carved out of the payment `amount`** (the gross debited from the payer): the payee receives `amount` minus the sum of `fees`. The `fees` array is **required** on create with **no default** — the platform sets the fee explicitly (e.g. to net a payee 90000, pass `amount` 91000 with a 1000 fee). properties: type: type: string enum: - processing_fee description: > the fee type (v2 convention): - `processing_fee` — payment-processing cost, passed by platform example: processing_fee amount: type: integer description: fee amount in cents example: 1000 required: - type - amount transfers: description: the ACH legs that make up this payment type: array items: type: object description: >+ One leg of a payee payment. A payment has at least one inbound leg (debit-pull from the account's funding bank account) and one outbound leg (credit to the payee); refunds, reversals, and recoveries add further legs. Most legs are ACH; a leg JustiFi records off the ACH network (e.g. a manual recovery) carries a non-`ach` `transfer_type`. Scheduling values assigned by the bank are deliberately absent: the dates to read are `debits_at` and `deposits_at` on the payment, which are derived from these legs. properties: id: description: unique transfer leg id type: string example: ptr_123 direction: description: >- the direction of funds for this leg (a refund is an outbound, a recovery an inbound) type: string enum: - inbound - outbound example: inbound purpose: description: >- what this leg is — moves the principal, refunds the payer, or recovers owed funds from the payer type: string enum: - principal - refund - recovery example: principal transfer_type: description: > how the money moved. `ach` — over the ACH network; `manual` — a movement JustiFi recorded off it. Widens to further rails (e.g. `rtp`) without a breaking change. type: string enum: - ach - manual example: ach amount: description: the leg amount in cents type: integer example: 50000 status: description: the state of this leg type: string enum: - initiated - submitted - settled - returned - failed example: settled error_code: description: > normalised, rail-agnostic reason the leg failed, in snake_case (e.g. `insufficient_funds`). Stable across rails — **branch on this, not on `network_error_code`**, which is the network's own code and changes meaning between rails. Set when a leg is `failed` or `returned`, and null otherwise. A correction is not a failure: a leg that settled after a notification of change carries `network_error_code` but no `error_code`. A return code with no normalised equivalent reports `unclassified_return`, so this is never null on a leg that failed — the raw code is always there to fall back on. type: string nullable: true example: insufficient_funds error_description: description: >+ human-readable text for `error_code`, in English — for support and logs, not for branching. Null whenever `error_code` is. type: string nullable: true example: Insufficient funds in the account network_error_code: description: > the raw code from the network, verbatim — an ACH return code (`R01`). Preserved for reconciliation. Present whenever the network said anything about this leg, which is not only when it went wrong: a notification of change carries an advisory code (`C01`) on a leg that **settled** normally. Read it together with `status` — the code alone does not mean the money did not move. type: string nullable: true example: null metadata: description: >- any useful information you'd like to store alongside this payment type: object example: invoice_id: inv_4021 created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-05T12:00:00Z' responses: '200': description: >- Return a 200 status to indicate the event was received successfully (within 5 seconds). bank_account: post: summary: Bank account events description: > Delivered as a funding account's verification changes, and when any account is corrected. The `data` object is the `BankAccount` record. | Event | Meaning | | ----- | ------- | | `payables.bank_account.verified` | a funding account passed verification and can now fund payments | | `payables.bank_account.failed` | a funding account did not pass verification and cannot fund payments; register a different account | | `payables.bank_account.pending` | a funding account's verification was reopened — it can no longer fund payments until it is verified again | | `payables.bank_account.corrected` | an account was corrected following an ACH Notification of Change (NOC); the new record is the one to use and the previous one is superseded | The verification events are the ones to watch when onboarding. They arrive from underwriting rather than from anything you did, so nothing in your own request flow tells you the answer, and together they are what say whether a payer account can fund. All three are worth handling: waiting on a `verified` that is never coming looks exactly like waiting on one that has not arrived yet, and an account that was verified can go back to `pending` if underwriting reopens it. Only funding accounts are verified — payee receiving accounts are `not_required` and raise none of the three. > An NOC always carries the correction code, but the network does not always supply the corrected > account or routing number. Where it does not, `bank_account.corrected` reports that a correction is > required without carrying the new value. Return a `200` within 5 seconds to acknowledge receipt. operationId: PayablesBankAccountEvent tags: - Payables Events security: [] requestBody: content: application/json: schema: allOf: - type: object description: the envelope wrapping every webhook event JustiFi delivers properties: id: description: event unique id type: string example: evt_123xyz event_name: description: > name of the event, namespaced under `payables.` (e.g. payables.payee_payment.succeeded, payables.bank_account.corrected) type: string example: payables.payee_payment.succeeded idempotency_key: description: >- idempotency key of the request that produced the event, when available type: string nullable: true account_id: description: > the sub account the event is scoped to, where one applies. **Always null for Payables** — a payer account is a first-class entity with its own `payer_…` id and is not a sub account, so there is nothing of this shape to report. The field is retained because the event envelope is shared across JustiFi services. type: string nullable: true example: null platform_account_id: description: the platform account the event is scoped to type: string nullable: true example: acc_987zyx version: description: version of the event payload type: string example: v1 data: description: the attributes for the object the event concerns type: object created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' - properties: event_name: enum: - payables.bank_account.verified - payables.bank_account.failed - payables.bank_account.pending - payables.bank_account.corrected data: type: object description: > A bank account used for Payables money movement. Exactly one of `payer_account_id` or `payee_id` is set: the former for a funding account (the principal is pulled from it), the latter for a payee's receiving account (the principal is paid to it). Account numbers are write-only — accepted on create, never returned; responses expose only the last four digits. Bank accounts are immutable: to correct details (e.g. after a NOC), a new record is created rather than edited in place. **Which record is active is determined by the owner**, via `payer_account.funding_bank_account_id` or `payee.receiving_bank_account_id` — so registering a new account and pointing the owner at it supersedes the previous one. Listing an owner's bank accounts by `created_at` therefore gives its full account history. properties: id: description: unique bank account id type: string example: ba_recv123 type: description: >- the object type, matching the enclosing envelope's `type` type: string example: bank_account payer_account_id: description: > the payer account that owns this bank account, when it is a **funding** account. Null on a payee's receiving account. Exactly one of `payer_account_id` and `payee_id` is non-null. type: string nullable: true example: null account_holder_name: description: the name on the bank account type: string example: Acme Plumbing LLC routing_number: description: the 9-digit ABA routing number type: string example: '021000021' account_number_last4: description: >- the last four digits of the account number (the full number is never returned) type: string example: '6789' account_type: description: the type of bank account type: string enum: - checking - savings example: checking payee_id: description: > the payee that owns this bank account, when it is a **receiving** account. Null on a payer's funding account. Exactly one of `payer_account_id` and `payee_id` is non-null. type: string nullable: true example: pe_abc123 verification_status: description: > the state of bank account verification. Read together with which owner field is set, this is the model's signal for how the account is handled: - `not_required` — a payee (receiving) account. Payables does not verify payee accounts; payments are sent without upfront validation, and a bad account surfaces as a returned credit. This is a settled state rather than a "not yet verified" one. - `pending` — a payer (funding) account whose validation is in progress. Payer funding accounts are validated in-app (e.g. during portal funding setup). - `verified` — a payer funding account that has been validated; only a `verified` funding account may fund a payment. - `failed` — validation of a payer funding account failed; it cannot fund payments. type: string enum: - not_required - pending - verified - failed example: verified created_at: type: string format: date-time example: '2026-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2026-01-01T12:00:00Z' responses: '200': description: >- Return a 200 status to indicate the event was received successfully (within 5 seconds). components: parameters: authorization-header: in: header name: Authorization schema: type: string required: true example: Bearer {access_token} description: >- the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token) id-path: in: path name: id schema: type: string format: uuid required: true pagination-limit: in: query name: limit description: the number of resources to retrieve schema: type: integer pagination-after: in: query name: after_cursor description: token to fetch the next page of a list schema: type: string pagination-before: in: query name: before_cursor description: token to fetch the previous page of a list schema: type: string idempotency-key-header: in: header name: Idempotency-Key schema: type: string format: uuid required: true example: my-request-123abc description: >- a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see [Idempotent Requests](https://docs.justifi.tech/api-spec#section/Idempotent-Requests) created-before: in: query name: created_before schema: type: string format: date-time required: false example: '2022-01-01T00:00:00Z' description: > filter records which were created before the date and time (UTC) specified. Dates without time specified will default to 00:00:00 created-after: in: query name: created_after schema: type: string format: date-time required: false example: '2022-01-01T00:00:00Z' description: > filter records which were created after the date and time (UTC) specified. Dates without time specified will default to 00:00:00 deposits-before: in: query name: deposits_before schema: type: string format: date-time required: false example: '2022-01-01T00:00:00Z' description: > filter records which deposit before the date and time (UTC) specified. Dates without time specified will default to 00:00:00 deposits-after: in: query name: deposits_after schema: type: string format: date-time required: false example: '2022-01-01T00:00:00Z' description: > filter records which deposit after the date and time (UTC) specified. Dates without time specified will default to 00:00:00 sub-account: in: header name: Sub-Account schema: type: string required: false example: acc_123xyz description: > the id of the [sub account](https://docs.justifi.tech/api-spec#tag/Sub-Accounts) that this request applies to payment-method-id: in: query name: payment_method_id schema: type: string required: false example: pm_123xyz description: | filter records which are associated with a payment method. void-id: in: query name: void_id schema: type: string required: false example: vo_123xyz description: | filter records which are associated with a void. sub-account-required: in: header name: Sub-Account schema: type: string required: true example: acc_123xyz description: > the id of the [sub account](https://docs.justifi.tech/api-spec#tag/Sub-Accounts) that this request applies to customer-id: in: query name: customer_id schema: type: string required: false example: cust_123xyz description: > Note: customer_id is a deprecated field. Please use our payment method groups instead. filter records which are associated with a customer. payment-method-group-id: in: query name: payment_method_group_id schema: type: string required: false example: pmg_123xyz description: | filter records which are associated with a payment method group. token-path: in: path name: token schema: type: string required: true start-date-before: in: query name: start_date_before schema: type: string format: date required: false example: '2024-01-31' description: Filter by start date before the specified date (ISO 8601 format) start-date-after: in: query name: start_date_after schema: type: string format: date required: false example: '2024-01-01' description: Filter by start date after the specified date (ISO 8601 format) end-date-before: in: query name: end_date_before schema: type: string format: date required: false example: '2024-01-31' description: Filter by end date before the specified date (ISO 8601 format) end-date-after: in: query name: end_date_after schema: type: string format: date required: false example: '2024-01-01' description: Filter by end date after the specified date (ISO 8601 format) payout-hold-id-path: in: path name: payout_hold_id schema: type: string required: true example: poh_abc123xyz description: Payout hold public ID with poh_ prefix schemas: PageInfo: type: object properties: end_cursor: description: the encoded id of the last record in the current list type: string example: >- WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd has_next: description: true if the collection contains records following the current list type: boolean default: false has_previous: description: true if the collection contains records ahead of the current list type: boolean default: false start_cursor: description: the encoded id of the first record in the current list type: string example: >- WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd Envelope-list: type: object properties: id: description: the object id type: number example: 1 type: description: the object type, or array of objects type: string example: account data: description: the list of objects type: array page_info: description: information for cursor style pagination $ref: '#/components/schemas/PageInfo' SubAccount: type: object properties: id: description: sub account id type: string format: uuid example: acc_xyz name: description: sub account name type: string example: The Shire Haberdashery account_type: description: sub account type (live or test) type: string example: live status: description: sub account status type: string enum: - created - submitted - information_needed - rejected - enabled - disabled - archived example: enabled currency: type: string enum: - usd - cad example: usd platform_account_id: description: id of associated platform account type: string format: uuid example: acc_xyz payout_account_id: description: id of active payout bank account type: string format: uuid example: ba_xyz business_id: description: id of associated business type: string format: uuid example: biz_xyz application_fee_rates: type: array description: list of associated application fee rates processing_ready: description: sub account ready for processing type: boolean example: false payout_ready: description: sub account ready for payouts type: boolean example: false related_accounts: description: >- when a live sub account is created, a related test account is automatically created; this provides both ids type: object properties: live_account_id: type: string format: uuid description: >- live sub account id (this will be nil if a sub account was created with test credentials) example: acc_xyz test_account_id: type: string format: uuid description: test sub account id example: acc_xyz payments_activated_on: description: >- date and time when the first successful payment was processed on this sub account type: string format: date-time nullable: true example: '2021-01-15T12:00:00Z' created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' Envelope: type: object properties: id: description: the object id, also found in the data object type: string format: uuid example: prefix_xyz (same as id of data object) type: description: the object type, or array of objects type: string example: account data: description: the attributes for the object type: object page_info: description: information for cursor style pagination, is null for single records type: null nullable: true PayoutBankAccount: type: object properties: id: description: unique bank account id type: string format: uuid full_name: description: account holder's full name type: string bank_name: description: name of bank type: string account_number_last4: description: last 4 digits of the account number type: string example: 1111 routing_number: type: string country: type: string enum: - US - CA example: US currency: type: string enum: - usd - cad example: usd nickname: type: string account_type: type: string enum: - checking SubAccountSettings: type: object properties: payments: type: object properties: id: description: unique payment settings id type: string example: stpy_7KRQzIYhUGxNscgLJP0Aum account_id: type: string description: unique sub account id this setting is applied to example: acc_123xyz mcc_code: description: merchant category code configured type: string example: '5045' credit_card_payments: description: credit card payments enabled for processing type: boolean example: true ach_payments: description: ach payments enabled for processing type: boolean example: true card_present: description: card present feature enabled for processing type: boolean example: false bnpl_payments: description: buy now pay later feature enabled type: boolean example: false apple_payments: description: apple payments feature enabled type: boolean example: false google_payments: description: google payments feature enabled type: boolean example: false bank_account_verification: description: bank account verification feature enabled type: boolean example: false insurance_payments: description: insurance feature enabled type: boolean example: false platform_wallet_account: description: platform_wallet_account feature enabled type: boolean example: false payouts: type: object properties: id: description: unique payout settings id type: string example: stpo_1FrQmV9ByJEKjpKf5diaA4 enabled: description: payouts enabled for the sub account type: boolean example: true statement_descriptor: description: statement descriptor for the payout type: string example: JustiFi settlement_priority: description: null type: enum[standard expedited] example: standard StandardFeeConfiguration: type: object properties: id: description: unique identifier for the fee configuration type: string example: sfc_abc123 account_id: description: the sub account this configuration applies to type: string format: uuid example: acc_xyz platform_account_id: description: the platform account that created this configuration type: string format: uuid nullable: true example: acc_yyy fee_type: description: | the type of fee this configuration applies to: - `processing_ecomm` — card-not-present (online) payments - `processing_card_present` — card-present (terminal) payments - `processing_ach` — ACH payments - `processing_ach_expedited` — expedited ACH payments - `visa_brand_ecomm` — Visa online payments - `visa_brand_card_present` — Visa terminal payments - `mastercard_brand_ecomm` — Mastercard online payments - `mastercard_brand_card_present` — Mastercard terminal payments - `amex_brand_ecomm` — Amex online payments - `amex_brand_card_present` — Amex terminal payments - `discover_brand_ecomm` — Discover online payments - `discover_brand_card_present` — Discover terminal payments - `platform` — platform service fee applied to all payments type: string enum: - processing_ecomm - processing_card_present - processing_ach - processing_ach_expedited - visa_brand_ecomm - visa_brand_card_present - mastercard_brand_ecomm - mastercard_brand_card_present - amex_brand_ecomm - amex_brand_card_present - discover_brand_ecomm - discover_brand_card_present - platform example: processing_ecomm variable_rate: description: percentage rate applied to the payment amount. `2.75` = 2.75% type: number example: 2.75 transaction_fee_cents: description: flat fee in cents added to each transaction type: integer example: 25 transaction_fee_currency: description: currency of the transaction fee type: string enum: - usd example: usd fee_cap_cents: description: >- maximum fee amount in cents; if the calculated fee exceeds this, the cap is used instead type: integer nullable: true example: 1000 effective_start: description: when this configuration takes effect (UTC) type: string format: date-time example: '2026-02-25T00:00:00Z' effective_end: description: >- when this configuration expires (UTC); `null` means it stays active indefinitely type: string format: date-time nullable: true example: null Proceed: type: object properties: id: description: unique proceeds payout id type: string example: po_xyz account_id: description: id of the account associated with the proceeds payout type: string format: uuid amount: description: proceeds payout amount in cents type: number example: 100000 bank_account: $ref: '#/components/schemas/PayoutBankAccount' currency: type: string enum: - usd - cad example: usd delivery_method: description: how the proceeds payout is delivered type: string enum: - standard description: type: string nullable: true deposits_at: description: >- in UTC, the date and time of the proceeds payout deposit (or in rare cases, withdrawal) type: string format: date-time example: '2021-01-01T12:00:00Z' refunds_count: description: number of refunds that impacted the proceeds payout type: number example: 5 refunds_total: description: >- sum deducted from the proceeds payout as a result of accounts' refunds, in cents type: number example: 10000 payments_count: description: number of payments that impacted the proceeds payout type: number example: 50 payments_total: description: >- sum added to the proceeds payout as a result of accounts' payments, in cents type: number example: 110000 payout_type: description: >- proceeds payouts are always of the type "proceeds" (other types apply only to sub accounts payouts) type: string enum: - proceeds other_total: description: >- sum of other less common transactions that impacted the proceeds payout, in cents type: number example: 100 platform_fees_total: description: >- gross fees your platform charged its sub accounts in the proceeds payout, in cents, before JustiFi's processing fees, null until calculated shortly after the payout is created type: number nullable: true example: 271961 justifi_fees_total: description: >- processing fees JustiFi charged your platform in the proceeds payout, in cents, always positive, null until calculated shortly after the payout is created type: number nullable: true example: 703 interchange_network_fees: description: >- interchange and card network fees passed through to your platform in the proceeds payout, in cents, negative when charged and positive when refunds credit interchange back, null until calculated shortly after the payout is created type: number nullable: true example: -10318 status: description: status of the proceeds payout type: string example: scheduled enum: - scheduled paid failed pending in_transit canceled metadata: type: object format: json description: >- any useful information you'd like to store alongside this proceeds payout example: platform_payout_id: cp_12345 created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' ProceedsReport: type: object properties: id: description: unique proceeds payout id type: string example: po_xyz csv_url: description: url that links to downloadable CSV report for proceeds payout type: string example: >- https://justifi-test-platform-proceeds-reports.s3.amazonaws.com/acc_1234lkj/po_23jdfi36dqhj.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test report_url: description: url that links to downloadable JSON report for proceeds payout type: string example: >- https://justifi-test-platform-proceeds-reports.s3.amazonaws.com/acc_1234lkj/po_23jdfi36dqhj.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test Card: type: object properties: id: description: unique card id type: string format: uuid example: pm_123xyz acct_last_four: description: last 4 digits of the card number type: string example: 4242 brand: description: card brand or bank name example: Visa digital_wallet: description: which digital wallet provider the card is tied to type: string enum: - apple_pay - google_pay - null example: apple_pay nullable: true name: description: card or account holder name type: string example: Amanda Kessel nullable: true token: description: > same value as unique card id; can be saved and used to process multiple payments with the same card example: pm_123xyz month: description: expiration date month example: '5' year: description: expiration date year example: '2042' metadata: type: object format: json description: any useful information you'd like to store alongside this card example: {} nullable: true created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' address_line1_check: description: >- Result of the address line 1 verification check. `pass` — matches the cardholder's address on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no address was provided for verification. type: string example: unchecked enum: - fail - pass - unavailable - unchecked address_postal_code_check: description: >- Result of the postal code verification check. `pass` — matches the cardholder's postal code on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no postal code was provided for verification. type: string example: unchecked enum: - fail - pass - unavailable - unchecked CardPaymentMethod: type: object properties: card: $ref: '#/components/schemas/Card' customer_id: description: >- customer_id is a deprecated field. Please use our payment method groups instead. type: string example: cust_xyz nullable: true signature: description: >- signature that uniquely identifies a credit card or bank account across payment methods type: string example: 4guAJNkVA3lRLVlanNVoBK nullable: true account_id: description: account id associated with payment method type: string example: acc_123 nullable: true ApplicationFee: type: object properties: id: description: unique application fee id type: string format: uuid example: fee_123xyz amount: description: application fee amount, in cents type: number example: 150 currency: type: string enum: - usd - cad example: usd created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' FeeResponse: type: object description: > A fee object in API responses. The `fees` array is empty in the Create Payment response — subscribe to payment webhook events (recommended) to receive the full fee objects, or poll with a subsequent Get Payment request. properties: id: type: string description: Unique identifier for this fee. Present when fetching a payment. example: pyfee_xyz type: type: string enum: - processing_fee - platform_fee - refund_processing_fee description: > The type of fee: - `processing_fee`: Fees related to payment processing costs - `platform_fee`: Fees for your platform's services - `refund_processing_fee`: A processing fee charged when a refund is processed. Currently applies to CAD payments only. example: processing_fee amount: type: integer description: Fee amount in cents example: 350 currency: type: string description: Currency of the fee amount. Present when fetching a payment. enum: - usd - cad example: usd remaining_amount: type: integer description: >- Amount still available for refund in cents. Updates after each partial refund. Present when fetching a payment. example: 350 source_configuration_id: type: string nullable: true description: >- The public ID of the Standard Fee Configuration used to calculate this fee. Null when the fee was explicitly provided in the payment request rather than auto-calculated. example: sfc_abc123 source_fee_type: type: string nullable: true description: > The fee type from the Standard Fee Configuration that generated this fee (e.g., `processing_ecomm`, `amex_brand_ecomm`, `platform`). Null when the fee was explicitly provided in the payment request. example: amex_brand_ecomm refund_id: type: string nullable: true description: >- The public ID of the refund this fee is associated with. Populated for `refund_processing_fee` fees (currently CAD payments only); null for all other fees. Present when fetching a payment. example: re_xyz required: - type - amount TransactionHold: type: object properties: id: description: unique transaction hold id type: string example: th_123xyz financial_transaction_id: type: string description: financial transaction id the transaction hold is associated to format: uuid example: ft_123xyz CardPayment: type: object properties: id: description: unique payment id type: string example: py_xyz account_id: type: string format: uuid example: acc_xyz amount: description: payment amount in cents type: number example: 10000 amount_disputed: description: sum of open or lost disputes for this payment, in cents type: number example: 0 amount_refunded: description: sum of refunds for this payment, in cents type: number example: 0 amount_refundable: description: amount of this payment currently able to be refunded, in cents type: number example: 10000 balance: description: >- sum of debits and credits for this payment, in cents (reflects the amount this account has earned from this payment). Compiled and calculated value, eventually consistent. To see all changes affecting the payment's balance call [Get Balance Transactions](#operation/GetPaymentBalanceTransactions) type: number example: 99850 fee_amount: type: number description: sum of fees for this payment example: 150 financial_transaction_id: type: string description: associated financial transaction id example: ft_123xyz captured: description: whether or not this payment is captured type: boolean example: true capture_strategy: type: string example: automatic enum: - automatic - manual currency: type: string enum: - usd - cad example: usd description: type: string description: >- your meaningful description of the payment (e.g. an order number or other value from your system) example: my_order_xyz disputed: type: boolean description: whether or not this payment has any open or lost disputes example: false disputes: type: array description: list of associated disputes example: [] error_code: type: string description: error code if the payment fails example: credit_card_number_invalid error_description: type: string description: text description of the error code example: Credit Card Number Invalid (Failed LUHN checksum) is_test: type: boolean description: whether or not this payment was made using the test account example: true metadata: type: object format: json description: any useful information you'd like to store alongside this payment example: {} payment_intent_id: type: string description: unique id of associated payment intent example: pi_123xyz checkout_id: type: string description: unique id of associated checkout example: cho_123xyz payment_method: $ref: '#/components/schemas/CardPaymentMethod' application_fee: $ref: '#/components/schemas/ApplicationFee' application_fee_rate_id: type: string description: unique id of application fee rate applied to this payment, if any example: afr_123xyz fees: type: array description: > Array of fee objects showing the fees charged on this payment with their remaining refundable amounts. Populated whether the fees were provided via the `fees` array in the payment request or calculated automatically (for example, from a Standard Fee Configuration, or the `processing_fee` on a CAD payment). **Note:** This array is empty in the Create Payment response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee objects (with `id`, `remaining_amount`, and `currency`), or poll with a subsequent Get Payment request. See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation. items: $ref: '#/components/schemas/FeeResponse' example: - id: pyfee_abc type: processing_fee amount: 350 currency: usd remaining_amount: 350 source_configuration_id: sfc_abc123 source_fee_type: processing_ecomm refund_id: null - id: pyfee_xyz type: platform_fee amount: 500 currency: usd remaining_amount: 500 source_configuration_id: sfc_abc123 source_fee_type: platform refund_id: null refunded: type: boolean description: whether or not this payment has any refunds example: false status: type: string enum: - pending - authorized - canceled - succeeded - failed - partially_refunded - fully_refunded - disputed description: status of the payment payment_mode: type: string example: ecom enum: - ecom - ach - card_present terminal_id: type: string description: id of terminal used to process the card payment, if any example: trm_123xyz transaction_hold: allOf: - type: object - description: >- present when the payment has been flagged for review and held from payouts - $ref: '#/components/schemas/TransactionHold' expedited: type: boolean nullable: true description: settlement priority of the payment, only applies to ACH payments example: null created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' BankAccount: type: object properties: id: description: unique bank account payment method id type: string format: uuid example: pm_123xyz account_owner_name: description: account owner name type: string example: Lindsay Whalen account_type: description: type of account (checking, savings, etc.) type: string example: checking bank_name: description: bank name type: string example: Wells Fargo nullable: true acct_last_four: description: last 4 digits of the account number type: string example: 1111 token: description: > same value as unique bank account id; can be saved and used to process multiple payments with the same bank account example: pm_123xyz metadata: type: object format: json description: >- any useful information you'd like to store alongside this bank account example: new: info nullable: true BankAccountPaymentMethod: type: object properties: bank_account: $ref: '#/components/schemas/BankAccount' customer_id: description: >- customer_id is a deprecated field. Please use our payment method groups instead. type: string example: cust_xyz nullable: true signature: description: >- signature that uniquely identifies a credit card or bank account across payment methods type: string example: 4guAJNkVA3lRLVlanNVoBK nullable: true account_id: description: account id associated with payment method type: string example: acc_123 nullable: true BankAccountPayment: type: object properties: id: description: unique payment id type: string example: py_xyz account_id: type: string format: uuid example: acc_xyz amount: description: payment amount in cents type: number example: 10000 amount_disputed: description: sum of open or lost disputes for this payment, in cents type: number example: 0 amount_refunded: description: sum of refunds for this payment, in cents type: number example: 0 amount_refundable: description: amount of this payment currently able to be refunded, in cents type: number example: 10000 amount_returned: description: >- amount of this payment reversed by an ACH return, in cents. See [ACH Returns](https://docs.justifi.tech/paymentMethods/achReturns) type: number example: 0 balance: description: > Sum of debits and credits for this payment, in cents (reflects the amount this account has earned from this payment). Compiled and calculated value, eventually consistent. To see all changes affecting the payment's balance see [Get Payment Balance Transactions](#operation/GetPaymentBalanceTransactions). When an ACH payment is returned, the payment amount and its original fees are both reversed, so any remaining negative `balance` is the ACH return fee. type: number example: 99850 fee_amount: type: number description: > Sum of fees for this payment. Payments using an application fee include the ACH return fee here once the payment is returned; payments using [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) do not. Either way the return fee is recorded as a balance transaction. See [ACH Returns](https://docs.justifi.tech/paymentMethods/achReturns). example: 150 financial_transaction_id: type: string description: associated financial transaction id example: ft_123xyz captured: description: whether or not this payment is captured type: boolean example: true capture_strategy: type: string example: automatic enum: - automatic - manual currency: type: string enum: - usd example: usd description: type: string description: >- your meaningful description of the payment (e.g. an order number or other value from your system) example: my_order_xyz disputed: type: boolean description: whether or not this payment has any open or lost disputes example: false disputes: type: array description: list of associated disputes example: [] error_code: type: string description: error code if the payment fails example: credit_card_number_invalid error_description: type: string description: text description of the error code example: Credit Card Number Invalid (Failed LUHN checksum) is_test: type: boolean description: whether or not this payment was made using the test account example: true metadata: type: object format: json description: any useful information you'd like to store alongside this payment example: {} payment_intent_id: type: string description: unique id of associated payment intent example: pi_123xyz checkout_id: type: string description: unique id of associated checkout example: cho_123 payment_method: $ref: '#/components/schemas/BankAccountPaymentMethod' application_fee: $ref: '#/components/schemas/ApplicationFee' application_fee_rate_id: type: string description: unique id of application fee rate applied to this payment, if any example: afr_123xyz fees: type: array description: > Array of fee objects showing the fees charged on this payment with their remaining refundable amounts. Populated whether the fees were provided via the `fees` array in the payment request or calculated automatically (for example, from a Standard Fee Configuration). **Note:** This array is empty in the Create Payment response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee objects (with `id`, `remaining_amount`, and `currency`), or poll with a subsequent Get Payment request. See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation. items: $ref: '#/components/schemas/FeeResponse' example: - id: pyfee_abc type: processing_fee amount: 50 currency: usd remaining_amount: 50 source_configuration_id: sfc_abc123 source_fee_type: processing_ecomm refund_id: null - id: pyfee_xyz type: platform_fee amount: 150 currency: usd remaining_amount: 150 source_configuration_id: sfc_abc123 source_fee_type: platform refund_id: null refunded: type: boolean description: whether or not this payment has any refunds example: false returned: type: boolean description: whether or not this payment was reversed by an ACH return example: false status: type: string enum: - pending - authorized - canceled - succeeded - failed - partially_refunded - fully_refunded - disputed description: status of the payment payment_mode: type: string example: ecom enum: - ecom - ach - card_present terminal_id: type: string description: >- id of terminal used to process a card payment, null for bank account payments example: trm_123xyz transaction_hold: allOf: - type: object - description: >- present when the payment has been flagged for review and held from payouts - $ref: '#/components/schemas/TransactionHold' expedited: type: boolean nullable: true description: settlement priority of the payment, only applies to ACH payments example: true created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' Fee: type: object description: A fee object specifying type and amount properties: type: type: string enum: - processing_fee - platform_fee description: | The type of fee: - `processing_fee`: Fees related to payment processing costs - `platform_fee`: Fees for your platform's services example: processing_fee amount: type: integer description: Fee amount in cents example: 350 required: - type - amount PaymentError: type: object properties: error: type: object properties: code: description: error code if the payment fails type: string example: card_declined decline_code: description: decline code if the payment fails type: string example: do_not_retry message: description: text description of the error code type: string example: >- This card has been rejected. Please try a different card or payment method network: description: card network used for payment type: string nullable: true example: MASTERCARD network_error_category: description: network error category code type: string nullable: true example: '03' network_error_code: description: network error code type: string nullable: true example: '504' ReturnedFeeResponse: type: object description: >- A returned fee object showing fee details returned to the merchant with a refund properties: id: type: string description: Unique identifier for this returned fee example: rtfee_xyz payment_fee_id: type: string description: >- Unique identifier for the original payment fee that was partially or fully returned example: pyfee_abc type: type: string enum: - processing_fee - platform_fee description: | The type of fee that was returned: - `processing_fee`: Processing fee returned to merchant - `platform_fee`: Platform fee returned to merchant example: processing_fee returned_amount: type: integer description: Amount returned to the merchant in cents example: 175 original_amount: type: integer description: Original fee amount in cents from the payment example: 350 currency: type: string description: Currency of the fee amounts example: usd remaining_amount: type: integer description: >- Amount still available for refund on the original payment fee in cents example: 175 required: - id - payment_fee_id - type - returned_amount - original_amount - currency - remaining_amount Refund: type: object properties: id: description: refund unique id type: string example: re_xyz payment_id: description: the payment for which this refund is being issued type: string format: uuid example: py_xyz amount: description: the amount of this refund in cents type: number example: 100 description: type: string description: an optional note about this refund example: customer canceled their order reason: description: the reason this refund is being issued type: string example: duplicate enum: - duplicate - fraudulent - customer_request status: description: the status of this refund type: string example: succeeded enum: - pending - succeeded - failed metadata: type: object format: json description: any useful information you'd like to store alongside this refund example: {} returned_fees: type: array description: > Array of returned fee objects showing the fees returned to the merchant with this refund. Present when fees were specified in the refund request. See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation. items: $ref: '#/components/schemas/ReturnedFeeResponse' example: - id: rtfee_xyz payment_fee_id: pyfee_abc type: processing_fee returned_amount: 175 original_amount: 350 currency: usd remaining_amount: 175 created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' PaymentBalanceTransaction: type: object properties: id: description: unique payment balance transaction id type: string format: uuid example: pbt_123xyz amount: description: payment balance transaction amount, in cents type: number example: 40145 balance: description: balance amount of the payment balance transaction, in cents type: number example: 53550 currency: type: string enum: - usd - cad example: usd financial_transaction_id: description: >- id of the financial transaction associated with the payment balance transaction type: string format: uuid example: ft_123xyz payment_id: description: id of the payment associated with the payment balance transaction type: string format: uuid example: py_123xyz payment_balance_txn_type: description: > Type of the transaction object associated with the payment balance transaction. - `payment`: Payment amount credited to the merchant - `payment_fee`: Application fee charged on the payment - `processing_fee`, `platform_fee`: Fees charged on the payment under [Enhanced Fee Management](#section/Enhanced-Fee-Management) - `refund`, `refund_failure`, `fee_refund`, `refund_processing_fee`: Refund and the fees returned or charged with it - `void`: Payment voided before settlement - `dispute`, `dispute_fee`, `dispute_refund`, `dispute_fee_refund`: Dispute amount and fee, and their reversals - `ach_return`: Payment amount reversed when an ACH payment is returned - `ach_return_fee`: Flat fee charged when an ACH payment is returned by the bank - `application_fee_returned`, `processing_fee_return`, `platform_fee_return`: Fees from the original payment returned on an ACH return See [ACH Returns](https://docs.justifi.tech/paymentMethods/achReturns) for how these combine on a returned ACH payment. type: string enum: - payment - payment_fee - processing_fee - platform_fee - payout - refund - refund_failure - refund_processing_fee - fee_refund - void - dispute - dispute_fee - dispute_fee_refund - dispute_refund - ach_return - ach_return_fee - application_fee_returned - processing_fee_return - platform_fee_return example: fee_refund source_id: description: >- id of the source object associated with the payment balance transaction type: string format: uuid example: fee_123xyz source_type: description: >- type of the source object associated with the payment balance transaction (for example `Payment`, `ApplicationFee`, `PaymentFee`, `Refund`, `Dispute`, `AchReturnFee`) type: string example: ApplicationFee created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' BinDetails: description: >- BIN (Bank Identification Number) details for a card. bin_details are not guaranteed to be present on every card payment method — availability depends on the card network and issuer. When unavailable, this field will be null. type: object nullable: true properties: type: description: Type of card issued, values include Credit, Debit, Prepaid, Unknown type: string example: Credit card_brand: description: >- Brand or network associated with card. Possible values include Visa, Mastercard, American Express, Discover type: string example: Visa card_class: type: string example: Consumer country: description: Long form country name which issued the card type: string example: United States of America issuer: description: Issuing bank type: string example: WELLS FARGO BANK, N.A. funding_source: description: >- Source of funds defined by BIN for a given card. Values include Charge, Credit, Debit, Deferred Debit (Visa Only), Network Only, Prepaid type: string example: Credit CardWithBinDetails: type: object properties: id: description: unique card id type: string format: uuid example: pm_123xyz acct_last_four: description: last 4 digits of the card number type: string example: 4242 brand: description: card brand or bank name example: Visa digital_wallet: description: which digital wallet provider the card is tied to type: string enum: - apple_pay - google_pay - null example: apple_pay nullable: true name: description: card or account holder name type: string example: Amanda Kessel nullable: true token: description: > same value as unique card id; can be saved and used to process multiple payments with the same card example: pm_123xyz month: description: expiration date month example: '5' year: description: expiration date year example: '2042' metadata: type: object format: json description: any useful information you'd like to store alongside this card example: {} nullable: true address_line1_check: description: >- Result of the address line 1 verification check. `pass` — matches the cardholder's address on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no address was provided for verification. type: string example: unchecked enum: - fail - pass - unavailable - unchecked address_postal_code_check: description: >- Result of the postal code verification check. `pass` — matches the cardholder's postal code on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no postal code was provided for verification. type: string example: unchecked enum: - fail - pass - unavailable - unchecked bin_details: description: >- BIN details for this card. Not guaranteed to be present — availability depends on the card network and issuer. nullable: true allOf: - $ref: '#/components/schemas/BinDetails' CardPaymentMethodWithBinDetails: type: object properties: id: description: unique id of the payment method type: string example: pm_123xyz status: description: signals whether the payment method is valid or invalid type: string example: valid invalid_reason: description: >- informs reason that the payment method has been marked invalid, if status is invalid type: string example: nil nullable: true created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' card: $ref: '#/components/schemas/CardWithBinDetails' customer_id: description: id of the customer associated with the payment method type: string example: cust_xyz nullable: true signature: description: >- signature that uniquely identifies a credit card or bank account across payment methods type: string example: 4guAJNkVA3lRLVlanNVoBK nullable: true account_id: description: account id associated with payment method type: string example: acc_123 nullable: true BankAccountPaymentMethodWithStatus: type: object properties: id: description: unique id of the payment method type: string example: pm_123xyz status: description: signals whether the payment method is valid or invalid type: string example: valid invalid_reason: description: >- informs reason that the payment method has been marked invalid, if status is invalid type: string example: nil nullable: true created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' bank_account: $ref: '#/components/schemas/BankAccount' customer_id: description: id of the customer associated with the payment method type: string example: cust_xyz nullable: true signature: description: >- signature that uniquely identifies a credit card or bank account across payment methods type: string example: 4guAJNkVA3lRLVlanNVoBK nullable: true account_id: description: account id associated with payment method type: string example: acc_123 nullable: true CardPresentPaymentMethod: type: object properties: id: description: unique id of the payment method type: string example: pm_123xyz status: description: signals whether the payment method is valid or invalid type: string example: valid invalid_reason: description: >- informs reason that the payment method has been marked invalid, if status is invalid type: string example: nil nullable: true created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' card_present: type: object properties: id: description: unique card present payment method id type: string format: uuid example: cp_7SdSRKRMADOn2Yi5expjej brand: description: card brand or institution type: string example: visa cardholder_name: description: name of the cardholder type: string example: CARDHOLDER/VISA last4: description: last 4 digits of the card number type: string example: '2970' expiry: description: card expiration date in MM/YY format type: string example: 11/30 type: description: the payment method type type: string example: card_present customer_id: description: id of the customer associated with the payment method type: string example: cust_xyz nullable: true signature: description: >- signature that uniquely identifies a credit card or bank account across payment methods type: string example: 4guAJNkVA3lRLVlanNVoBK nullable: true account_id: description: account id associated with payment method type: string example: acc_123 nullable: true CreateCard: type: object properties: name: description: cardholder full name type: string example: Kevin Garnett number: description: card number type: string example: 4242424242424242 verification: description: card verification number type: string example: 123 month: description: card expiration month type: string example: 5 year: description: card expiration year type: string example: 2042 address_line1: description: card address street type: string example: 123 Fake St address_line2: description: card address apartment, suite, etc. type: string example: Suite 101 address_city: description: card address city type: string example: Cityville address_state: description: card address state type: string example: MN address_postal_code: description: card address ZIP type: string example: 55555 address_country: description: card address 2-character country code type: string example: US brand: description: card brand or institution type: string example: Visa metadata: type: object format: json description: any useful information you'd like to store alongside this card example: {} required: - name - number - month - year - address_postal_code CreateBankAccount: type: object description: Bank Account properties: account_owner_name: description: account owner name type: string example: Lindsay Whalen routing_number: description: routing number type: string example: '110000000' account_number: description: bank account number type: string example: '000123456789' account_type: description: type of account type: string example: checking enum: - checking - savings account_owner_type: description: type of account holder type: string example: individual enum: - individual - company country: description: country associated with the bank account type: string example: US currency: description: currency of the bank account type: string example: usd enum: - usd - cad bank_name: description: bank name type: string example: Wells Fargo metadata: type: object format: json description: >- any useful information you'd like to store alongside this bank account example: {} required: - account_owner_name - routing_number - account_number - account_type - account_owner_type - country - currency CardResponse: type: object properties: id: description: the object id type: number example: pm_123xyz type: description: the object type, or array of objects type: string example: payment_method data: description: the attributes for the object type: object properties: id: description: unique id of the payment method type: string example: pm_123xyz signature: description: unique signature associated with the payment_method type: string example: 3aGWnUznQ nullable: true customer_id: description: >- customer_id is a deprecated field. Please use our payment method groups instead. type: string example: cust_123abc nullable: true account_id: description: account id associated with payment method type: string example: acc_123 nullable: true status: description: signals whether the payment method is valid or invalid type: string example: valid invalid_reason: description: >- informs reason that the payment method has been marked invalid, if status is invalid type: string example: INVALID_ACCOUNT_NUMBER nullable: true created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' card: description: the card associated with the payment_method type: object properties: id: description: unique card payment method id type: string format: uuid example: pm_123xyz name: description: card holder name type: string example: Lindsay Whalen nullable: true acct_last_four: description: last 4 digits of the account number type: string example: 1111 brand: description: card brand or institution type: string example: visa digital_wallet: description: which digital wallet provider the card is tied to type: string enum: - apple_pay - google_pay - null example: apple_pay nullable: true token: description: > same value as unique bank account id; can be saved and used to process multiple payments with the same bank account example: pm_123xyz month: description: expiration date month example: '5' year: description: expiration date year example: '2042' metadata: type: object format: json description: >- any useful information you'd like to store alongside this card example: new: info nullable: true address_line1_check: description: >- Result of the address line 1 verification check. `pass` — matches the cardholder's address on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no address was provided for verification. type: string example: pass enum: - fail - pass - unavailable - unchecked address_postal_code_check: description: >- Result of the postal code verification check. `pass` — matches the cardholder's postal code on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no postal code was provided for verification. type: string example: pass enum: - fail - pass - unavailable - unchecked bin_details: description: >- BIN details for this card. Not guaranteed to be present — availability depends on the card network and issuer. nullable: true allOf: - $ref: '#/components/schemas/BinDetails' page_info: description: information for cursor style pagination, is null for single records type: string nullable: true BankAccountResponse: type: object properties: id: description: the object id type: number example: pm_123xyz type: description: the object type, or array of objects type: string example: payment_method data: description: the attributes for the object type: object properties: id: description: unique id of the payment method type: string example: pm_123xyz signature: description: unique signature associated with the payment_method type: string example: 3aGWnUznQ nullable: true customer_id: description: >- customer_id is a deprecated field. Please use our payment method groups instead. type: string example: cust_123abc nullable: true account_id: description: account id associated with payment method type: string example: acc_123 status: description: signals whether the payment method is valid or invalid type: string example: valid invalid_reason: description: >- informs reason that the payment method has been marked invalid, if status is invalid type: string example: nil nullable: true created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' bank_account: description: the bank account associated with the payment_method type: object properties: id: description: unique bank account payment method id type: string format: uuid example: pm_123xyz account_owner_name: description: account owner name type: string example: Lindsay Whalen account_type: description: type of account (checking, savings, etc.) type: string example: checking bank_name: description: bank name type: string example: Wells Fargo nullable: true acct_last_four: description: last 4 digits of the account number type: string example: 1111 token: description: > same value as unique bank account id; can be saved and used to process multiple payments with the same bank account example: pm_123xyz metadata: type: object format: json description: >- any useful information you'd like to store alongside this bank account example: new: info nullable: true page_info: description: information for cursor style pagination, is null for single records type: string nullable: true CardPresentResponse: type: object properties: id: description: the object id type: number example: pm_123xyz type: description: the object type, or array of objects type: string example: payment_method data: description: the attributes for the object type: object properties: id: description: unique id of the payment method type: string example: pm_123xyz signature: description: unique signature associated with the payment_method type: string example: 3aGWnUznQ nullable: true customer_id: description: >- customer_id is a deprecated field. Please use our payment method groups instead. type: string example: cust_123abc nullable: true account_id: description: account id associated with payment method type: string example: acc_123 nullable: true status: description: signals whether the payment method is valid or invalid type: string example: valid invalid_reason: description: >- informs reason that the payment method has been marked invalid, if status is invalid type: string example: INVALID_ACCOUNT_NUMBER nullable: true created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' card_present: description: the card present payment method type: object properties: id: description: unique card present payment method id type: string format: uuid example: cp_7SdSRKRMADOn2Yi5expjej brand: description: card brand or institution type: string example: visa cardholder_name: description: name of the cardholder type: string example: CARDHOLDER/VISA last4: description: last 4 digits of the card number type: string example: '2970' expiry: description: card expiration date in MM/YY format type: string example: 11/30 type: description: the payment method type type: string example: card_present page_info: description: information for cursor style pagination, is null for single records type: string nullable: true UpdateCard: type: object properties: month: description: new expiration month type: string example: 5 year: description: new expiration year type: string example: 2042 address_line1: description: new card address street type: string example: 123 Fake St address_line2: description: new card address apartment, suite, etc. type: string example: Suite 101 address_city: description: new card address city type: string example: Cityville address_state: description: new card address state type: string example: MN address_postal_code: description: new card address ZIP type: string example: 55555 address_country: description: new card address 2-character country code type: string example: US metadata: type: object format: json description: >- any useful information you'd like to store alongside this card; when you update metadata, any previous metadata will be overwritten example: new: info ForwardingRequest: type: object properties: id: description: unique id of the forwarding request type: string example: fwd_123xyz account_id: description: >- the sub account that owns the payment method the request was created from type: string example: acc_123xyz nullable: true payment_method_id: description: >- the payment method whose card details are substituted into the request body type: string example: pm_123xyz nullable: true url: description: the allow-listed destination the request is sent to type: string example: https://api.stripe.com/v1/payment_methods http_method: description: >- the HTTP method used to reach the destination, determined by the destination itself type: string enum: - POST example: POST provider: description: the destination provider, determined by the destination itself type: string enum: - stripe example: stripe status: description: >- `pending` — accepted and queued, nothing has been sent yet; `processing` — the request is being sent and the outcome is not known yet; `completed` — the destination answered, see `data.response.status_code` for the outcome; `failed` — the destination could not be reached, see `failure_reason`. type: string enum: - pending - processing - completed - failed example: completed failure_reason: description: >- why the destination could not be reached, `null` unless `status` is `failed`. `timeout` — the destination did not answer in time; `connection_error` — the connection or TLS handshake failed; `internal_error` — JustiFi failed to send the request. type: string enum: - timeout - connection_error - internal_error example: timeout nullable: true replacements: description: >- the card tags JustiFi found in the request body and substituted before sending type: array items: type: string enum: - card_number - card_expiry_month - card_expiry_year - cardholder_name example: - card_number - card_expiry_month - card_expiry_year - cardholder_name request: description: what was sent to the destination, masked type: object properties: body: description: >- the request body as it was sent, with card details masked. The card number renders as its last four digits; the expiration date and cardholder name render in the clear. type: object nullable: true example: type: card card: number: '4242' exp_month: 5 exp_year: 2042 billing_details: name: Lindsay Whalen headers: description: >- the headers as they were sent, with every value replaced by `[FILTERED]`. Header names are kept so you can confirm what was relayed; values are never stored in readable form. type: object additionalProperties: type: string example: Authorization: '[FILTERED]' Content-Type: '[FILTERED]' response: description: >- the destination's response, `null` until the destination has answered type: object nullable: true properties: id: description: unique id of the forwarding response type: string example: fwdr_123xyz status_code: description: the HTTP status code the destination answered with type: integer example: 200 body: description: >- the response body, scrubbed of anything that looks like a card number nullable: true example: id: pm_1QabcStripeExample object: payment_method card: last4: '4242' headers: description: >- the response headers, scrubbed of anything that looks like a card number nullable: true example: content-type: application/json request-id: req_stripe_123 response_time_ms: description: how long the destination took to answer, in milliseconds type: integer example: 512 nullable: true attempted_at: description: >- when JustiFi started sending the request (in UTC), `null` while the request is still queued type: string format: date-time example: '2024-01-01T12:00:01Z' nullable: true created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:02Z' PaymentMethodGroupResponse: type: object properties: id: description: the object id type: string example: pm_123xyz account_id: description: the account_id associated with the object type: string example: acc_123xyz platform_account_id: description: the account_id for the platform account associated with the object type: string example: acc_321abc Payout: type: object properties: id: description: unique payout id type: string example: po_xyz account_id: description: id of the account associated with the payout type: string format: uuid amount: description: payout amount in cents type: number example: 100000 bank_account: $ref: '#/components/schemas/PayoutBankAccount' currency: type: string enum: - usd - cad example: usd delivery_method: description: how the payout is delivered type: string enum: - standard description: type: string nullable: true deposits_at: description: >- in UTC, the estimated date and time of the payout deposit (or in rare cases, withdrawal) type: string format: date-time example: '2021-01-01T12:00:00Z' fees_total: description: sum of fees in the payout, in cents type: number example: 5000 refunds_count: description: number of refunds in the payout type: number example: 5 refunds_total: description: sum of refunds in the payout, in cents type: number example: 10000 payments_count: description: number of payments in the payout type: number example: 50 payments_total: description: sum of payments in the payout, in cents type: number example: 110000 payout_type: description: >- type of payment method used for the payments in the payout (funds from different types of payment methods settle at different intervals; in order to pay out your funds ASAP, we batch separate payouts for each payment method type) type: string enum: - ach cc other_total: description: sum of other less common transactions in the payout, in cents type: number example: 100 platform_fees_total: description: >- gross fees your platform charged its sub accounts in a proceeds payout, in cents, null for sub account payouts type: number nullable: true justifi_fees_total: description: >- processing fees JustiFi charged your platform in a proceeds payout, in cents, always positive, null for sub account payouts type: number nullable: true interchange_network_fees: description: >- interchange and card network fees passed through to your platform in a proceeds payout, in cents, usually negative, null for sub account payouts type: number nullable: true status: description: status of the payout type: string example: paid enum: - paid failed forwarded scheduled in_transit canceled settlement_priority: description: settlement priority of the payout, either standard or expedited. type: string example: standard enum: - standard expedited metadata: type: object format: json description: any useful information you'd like to store alongside this payout example: customer_payout_id: cp_12345 created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' PayoutCsvReport: type: object properties: id: description: unique payout id type: string example: po_xyz csv_url: description: url that links to downloadable CSV report for payout. type: string example: >- https://justifi-test-payouts-reports.s3.amazonaws.com/acc_1234lkj/po_23jdfi36dqhj.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test PayoutHold: type: object properties: id: type: string example: poh_abc123xyz account_id: type: string example: acc_sub123 hold_type: type: string enum: - first_payment - manual example: manual issued_by: type: string enum: - system - platform example: platform start_date: type: string format: date example: '2024-01-01' end_date: type: string format: date nullable: true example: '2024-01-31' active: type: boolean example: true created_at: type: string format: date-time example: '2024-01-01T10:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T10:00:00Z' BalanceTransaction: type: object properties: id: description: unique balance transaction id type: string example: bt_xyz account_id: description: id of the account associated with the balance transaction type: string format: uuid example: acc_xyz amount: description: balance transaction amount, in cents type: number example: 100000 available_on: type: string format: date-time example: '2021-01-01T12:00:00Z' currency: type: string enum: - usd - cad example: usd description: type: string nullable: true fee: description: >- amount of fees deducted from the balance transaction amount, in cents type: number example: 5000 financial_transaction_id: description: >- id of the financial transaction associated with the balance transaction type: string format: uuid example: ft_xyz net: description: >- net amount of the balance transaction (after fees are deducted), in cents type: number example: 600 payout_id: description: id of the payout associated with the balance transaction type: string format: uuid example: po_xyz source_id: description: id of the source object associated with the balance transaction type: string format: uuid example: py_xyz source_type: description: >- type of source object associated with the balance transaction (for example payment, refund, dispute, payout) type: string example: payment source_payment_id: description: >- id of the payment associated with the source of the balance transaction type: string nullable: true example: py_xyz txn_type: description: > Type of transaction object associated with the balance transaction. Common types include: - `seller_payment`: Payment amount credited to merchant - `seller_payment_refund`: Payment refund debited from merchant - `processing_fee`: Processing fee deducted from merchant - `processing_fee_credit`: Processing fee credited to platform - `platform_fee`: Platform fee deducted from merchant - `platform_fee_credit`: Platform fee credited to platform - `processing_fee_return`: Processing fee returned on refund/void/ACH return - `platform_fee_return`: Platform fee returned on refund/void/ACH return - `partner_platform_discount_fee`: JustiFi basis point fee deducted from platform - `partner_platform_transaction_fee`: JustiFi per-transaction fee deducted from platform - `payout`: Payout to bank account - `refund`: Refund transaction - `ach_return_collected`: Returned ACH payment amount debited from merchant - `ach_return_fee_collected`: ACH return fee debited from merchant - `application_fee_refund`: Application fee returned to merchant on refund/void/ACH return - `dispute_amount_collected`: Disputed payment amount debited from merchant - `dispute_fee_collected`: Dispute fee debited from merchant - `refund_reversal`: Returned ACH refund credited back to merchant - `payout_failed`: Returned payout credited back to merchant A `_collected` suffix means the amount was taken from this account to fund a recovery, so it is recorded as a debit. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for details on fee-related transaction types, and [ACH Returns](https://docs.justifi.tech/paymentMethods/achReturns) for the transactions a returned ACH payment produces. type: string example: seller_payment created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' DisputeResponse: type: object properties: additional_statement: type: string description: any additional evidence or statements cancellation_policy_disclosure: type: string description: >- an explanation of how and when the customer was shown your cancellation policy prior to purchase cancellation_rebuttal: type: string description: a justification for why the customer’s subscription was not canceled customer_billing_address: type: string description: the billing address provided by the customer customer_email_address: type: string description: the email address of the customer customer_name: type: string description: the name of the customer customer_purchase_ip_address: type: string description: the IP address that the customer used when making the purchase duplicate_charge_explanation: type: string description: >- an explanation of the difference between the disputed charge versus the prior charge that appears to be a duplicate product_description: type: string description: a description of the product or service that was sold refund_policy_disclosure: type: string description: >- documentation demonstrating that the customer was shown your refund policy prior to purchase refund_refusal_explanation: type: string description: justification for why the customer is not entitled to a refund service_date: type: string description: >- the date on which the customer received or began receiving the purchased service example: '2024-10-31' shipping_address: type: string description: the address to which a physical product was shipped shipping_carrier: type: string description: >- the delivery service that shipped a physical product, such as Fedex, UPS, USPS, etc. If multiple carriers were used for this purchase, please separate them with commas shipping_date: type: string description: >- the date on which a physical product began its route to the shipping address example: '2024-10-31' shipping_tracking_number: type: string description: >- the tracking number for a physical product. If multiple tracking numbers were generated for this purchase, please separate them with commas duplicate_charge_original_payment_id: type: string description: >- the payment id for the prior charge which appears to be a duplicate of the disputed charge Dispute: type: object properties: id: description: unique dispute id type: string example: dp_xyz payment_id: description: the disputed payment type: string format: uuid example: py_xyz account_id: description: id of the account associated with the dispute type: string format: uuid example: acc_xyz amount: description: amount disputed in cents type: number example: 100 currency: type: string enum: - usd - cad example: usd reason: type: string description: the reason this payment was disputed example: fraudulent due_date: type: string format: date description: due date for evidence submission to counter the dispute example: '2025-02-23' status: description: status of the dispute type: string example: won enum: - needs_response - under_review - won - lost metadata: type: object format: json description: any useful information you'd like to store alongside this dispute example: {} created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' dispute_response: allOf: - type: object - description: present when evidence was submitted to counter dispute - $ref: '#/components/schemas/DisputeResponse' - nullable: true dispute_reversal: type: object description: present when dispute gets reversed from lost to won properties: description: type: string example: Dispute was reversed created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' nullable: true DisputeEvidence: type: object properties: id: description: unique dispute evidence id type: string example: dpe_xyz file_name: type: string example: receipt.pdf description: dispute evidence file name file_type: type: string description: dispute evidence file type example: application/pdf enum: - image/jpeg - image/png - application/pdf - application/zip - application/x-zip-compressed dispute_evidence_type: type: string description: dispute evidence type matching the file that will be uploaded example: receipt enum: - cancellation_policy - customer_communication - customer_signature - duplicate_charge_documentation - receipt - refund_policy - service_documentation - shipping_documentation - uncategorized_file status: type: string description: dispute evidence status enum: - pending - uploaded description: type: string description: description of the dispute evidence file that will be uploaded presigned_url: type: string description: >- url that should be used to submit a put request to upload the evidence file InsurancePolicy: type: object properties: id: description: unique record id type: string example: ins_xyz account_id: type: string format: uuid example: acc_xyz amount: description: the amount charged in cents type: number example: 10000 currency: type: string enum: - usd - cad example: usd partner_name: type: string description: partner insurance provider name example: vertical_insure partner_quote_id: type: string description: quote id provided by partner provider example: test-123 metadata: type: object format: json description: >- any useful information you'd like to store alongside this payment intent example: {} status: type: string enum: - created - bound description: status of the payment intent created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' AddressResponse: type: object properties: id: description: unique address id type: string example: addr_123xyz line1: type: string example: 123 Example St line2: type: string example: Suite 101 city: type: string example: Minneapolis state: type: string example: MN postal_code: type: string example: '55555' country: type: string example: USA created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' Document: type: object properties: id: type: string format: uuid example: doc_abc123 description: type: string example: My Document description: description of the document, used for your reference file_name: type: string example: my_document description: file name of the document file_type: type: string example: pdf description: >- the file media type/extension of the file you are uploading. For example, text/plain, application/pdf, image/png document_type: type: string enum: - articles_of_incorporation - balance_sheet - bank_statement - birth_certificate - business_registration - citizenship_card - driver_license - foreign_passport - government_id - nexus_card - passport - profit_and_loss_statement - resident_card - sin_card - ssn_card - status_card - tax_return - voided_check - other example: balance_sheet business_id: type: string format: uuid example: biz_abc123 description: >- the business id to associate with this document (one of business id or identity id is required) identity_id: type: string format: uuid example: idty_abc123 description: >- the identity id to associate with this document (one of business id or identity id is required) presigned_url: type: string format: url description: >- url used to PUT or GET the document to our cloud provider. This is not returned via the list API example: https://test.test/doc_abc123/file_name.pdf metadata: type: object format: json description: any useful information you'd like to store alongside this document additionalProperties: true example: language: english social_network: '@person' status: type: string enum: - pending uploaded canceled created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' IdentityResponse: type: object properties: id: description: unique identity id type: string example: idty_xyz platform_account_id: type: string format: uuid example: acc_xyz business_id: type: string format: uuid example: biz_xyz description: associated business name: type: string example: Person Name description: legal name title: type: string example: President description: job title email: type: string example: person.name@justifi.ai description: email address phone: type: string example: '6124011111' description: phone number dob_day: type: string example: '01' description: two-digit birth day dob_month: type: string example: '01' description: two-digit birth month dob_year: type: string example: '1980' description: four-digit birth year (must be at least 18 years old) ssn_last4: type: string example: '6789' description: >- last four digits of social security number (computed from identification_number) is_owner: type: boolean example: true description: >- if an identity owns 25% or more of the business, they are considered an owner ownership_percentage: type: integer minimum: 0 maximum: 100 example: 25 description: >- percentage of the business owned by this identity (0–100); only returned when is_owner is true metadata: type: object format: json description: any useful information you'd like to store alongside this identity address: $ref: '#/components/schemas/AddressResponse' documents: type: array items: $ref: '#/components/schemas/Document' created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' EntityBankAccount: type: object properties: id: description: unique bank account id type: string format: uuid example: ba_123xyz account_owner_name: description: name of the account owner type: string example: Napheesa Collier account_type: description: type of the account type: string enum: - checking - savings example: checking acct_last_four: description: last 4 digits of the account number type: string example: '6789' routing_number: description: routing number for account type: string example: '110000000' bank_name: description: name of the bank type: string example: Wells Fargo country: description: country for the bank account type: string enum: - US - CA currency: description: currency for the bank account type: string enum: - usd - cad nickname: description: nickname for the bank account type: string example: Phee's money metadata: type: object format: json description: >- any useful information you'd like to store alongside this bank account example: {} business_id: type: string format: uuid example: biz_123abc platform_account_id: type: string format: uuid example: acc_123abc created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' AdditionalQuestions: type: object properties: business_revenue: type: string example: '84220' description: >- amount of money the company receives from its primary business activities business_payment_volume: type: string example: '1000000' description: annual credit card & ACH volume anticipated to process with Justifi business_when_service_received: type: string example: Within 7 days description: >- how long after paying will your customers typically receive their goods or services business_recurring_payments: type: string example: 'true' description: business offer recurring payments business_recurring_payments_percentage: type: string example: 50% monthly, 50% annual description: >- percentage of revenue is generated from each recurring payment type offered business_seasonal: type: string example: No. The business revenue is generated evenly throughout the year description: is the business seasonal business_other_payment_details: type: string example: >- 50% of revenue is taken 90 days in advance of service and 50% of revenue is taken 30 days in advance of service description: >- anything else you would like us to know about how your customers pay the business business_purchase_order_volume: type: string example: '150' description: total number of purchase orders made by a business business_invoice_volume: type: string example: '500' description: total number of invoices generated by a business business_fund_use_intent: type: string example: expanding marketing efforts description: planned purpose for which a business intends to use funds equipment_invoice: type: string example: $10,000 invoice for computer equipment description: document specifying the cost and details of equipment purchased business_invoice_number: type: string example: 202105-001 description: >- unique identifier assigned to a specific invoice issued by a business business_invoice_amount: type: string example: $4500 description: total monetary value stated on an invoice issued by a business business_purchase_order_number: type: string example: '120' description: number of unique purchase orders made by a business industry_code: type: string example: '541512' description: >- numerical or alphanumeric code that classifies businesses according to their industry duns_number: type: string example: '123456789' description: >- unique nine-digit identification number assigned to a business entity business_payment_decline_volume: type: string example: '500' description: total number of payment declines experienced by a business business_refund_volume: type: string example: '100' description: total number of refunds issued by a business business_dispute_volume: type: string example: '50' description: total number of disputes raised by customers against a business business_receivable_volume: type: string example: US $100,000 description: total value of outstanding payments owed to a business business_future_scheduled_payment_volume: type: string example: '200' description: total number of future scheduled payments for a business business_dispute_win_rate: type: string example: 75% description: >- percentage of business disputes won out of the total number of disputes length_of_business_relationship: type: string example: 5 years description: duration of a business relationship between two parties BusinessResponse: type: object properties: id: description: unique business id type: string example: biz_xyz platform_account_id: type: string format: uuid example: acc_xyz mode: type: string enum: - test - live example: test description: >- whether this business is a test or live business, set from the credentials used to create it and fixed for the life of the business archived: type: boolean example: false description: >- indicates whether this business has been archived. Test mode businesses can always be archived; a live mode business can only be archived while it has not been provisioned. Archived businesses are excluded from the list businesses endpoint legal_name: type: string example: Business Name description: legal business entity name website_url: type: string example: https://justifi.ai description: >- website for this business (if they don't have a website, can send their social media business page, app store link, or a product description instead) email: type: string example: business@justifi.ai description: email address of business entity or representative phone: type: string example: '6124011111' description: business phone number doing_business_as: type: string example: Best Business description: only needed if registered with DBA/Trade Name on SS-4 tax document business_type: type: string enum: - for_profit - non_profit - government_entity - individual business_structure: type: string enum: - sole_proprietorship - single_llc - multi_llc - private_partnership - private_corporation - unincorporated_association - public_partnership - public_corporation - incorporated - unincorporated - government_unit - government_instrumentality - tax_exempt_government_instrumentality classification: type: string enum: - government - limited - non_profit - partnership - corporation - public_company - sole_proprietor industry: type: string example: Big Business description: >- to help us identify this business entity's category code (MCC), please provide a concise description of what service they offer mcc: type: string example: '8021' description: >- merchant category code for this business, if known. Please note, the JustiFi underwriting team may modify this. If you are unsure, just submit a description in the industry field instead of an MCC tax_id: type: string description: >- the federal tax identification number/EIN issued to this sub account by the IRS (for Individual type, this will be their full SSN), the value is not returned in any API response tax_id_last4: type: string description: >- last 4 digits of the federal tax identification number/EIN issued to this sub account by the IRS (for Individual type, this will be the last 4 digits of their SSN) date_of_incorporation: type: string example: '2015-02-20' country_of_establishment: type: string enum: - USA - CAN example: USA description: country where the business was established terms_conditions_accepted: type: boolean example: false description: returns true if terms and conditions were accepted metadata: type: object format: json description: any useful information you'd like to store alongside this business associated_accounts: type: array description: >- the sub account associated with this business, populated once the business has been provisioned items: type: object properties: id: type: string example: acc_123xyz example: - id: acc_123xyz provisioned: type: array description: >- products successfully provisioned for this business, empty until a provisioning request succeeds. This list reflects completed provisioning only. A business whose provisioning is still in flight, or that already has a sub account associated, reports an empty list but can no longer be archived items: type: string enum: - payments - underwriting - boarding - bank_account_verification example: - payments - underwriting legal_address: $ref: '#/components/schemas/AddressResponse' representative: $ref: '#/components/schemas/IdentityResponse' owners: type: array items: $ref: '#/components/schemas/IdentityResponse' documents: type: array items: $ref: '#/components/schemas/Document' bank_accounts: type: array items: $ref: '#/components/schemas/EntityBankAccount' additional_questions: $ref: '#/components/schemas/AdditionalQuestions' created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' Address: type: object properties: line1: type: string example: 123 Example St line2: type: string example: Suite 101 city: type: string example: Minneapolis state: type: string example: MN postal_code: type: string example: '55555' country: type: string example: USA Identity: type: object properties: name: type: string example: Person Name description: legal name title: type: string example: President description: job title email: type: string example: person.name@justifi.ai description: email address phone: type: string example: '6124011111' description: phone number dob_day: type: string example: '01' description: two-digit birth day dob_month: type: string example: '01' description: two-digit birth month dob_year: type: string example: '1980' description: four-digit birth year (must be at least 18 years old) identification_number: type: string example: '123456789' description: full social security number is_owner: type: boolean description: >- if an identity owns 25% or more of the business, they are considered an owner ownership_percentage: type: integer minimum: 0 maximum: 100 example: 25 description: >- percentage of the business owned by this identity (0–100); only returned when the identity owns a business (proprietor_id set), not based on the is_owner column. Only owners with at least 25% ownership should be included. metadata: type: object format: json description: any useful information you'd like to store alongside this identity additionalProperties: true example: language: english social_network: '@person' address: oneOf: - $ref: '#/components/schemas/Address' - type: object properties: id: type: string ProvisioningResponse: type: object properties: account_type: description: account type (live or test) type: string example: test sub_account_id: type: string format: uuid example: acc_xyz platform_account_id: type: string format: uuid example: acc_123 payload: type: object description: business information AchReturnFee: type: object properties: id: description: unique ach return fee id type: string example: arf_123xyz payment_id: description: the payment for which this ach return fee is being issued type: string example: py_123xyz amount: description: ach return fee amount, in cents type: number example: 150 currency: type: string enum: - usd example: usd created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' Terminal: type: object properties: id: description: unique terminal id type: string example: trm_abc123 account_id: description: id of the account associated with the terminal type: string format: uuid example: acc_123xyz platform_account_id: type: string format: uuid description: id of the platform account associated with the terminal example: acct_789abc provider: description: terminal provider type: enum[verifone verifone_simulator] example: verifone status: description: >- last known terminal status. For performance reasons, this field is only updated when you check the terminal status via API. type: >- enum[connected, disconnected, unknown, pending_configuration, archived] example: disconnected provider_id: description: terminal identification from provider, also called device id (DID) type: string example: '23456789' provider_serial_number: description: >- serial number of the terminal device. Present after device was configured by entering the provider id (also called device id) into device. type: string example: 888-222-444 nickname: description: >- terminal custom identification, can be added and modified via update terminal API type: string example: My Favorite Terminal verified_at: type: string format: date-time example: '2024-01-01T15:00:00Z' model_name: type: string description: name of terminal device model example: e285 terminal_order_created_at: type: string format: date-time description: timestamp of when the terminal order was placed example: '2024-01-01T15:00:00Z' status_last_requested_at: type: string format: date-time description: timestamp of last terminal status request example: '2024-01-01T15:00:00Z' created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' TerminalStatus: type: object properties: id: description: unique terminal id type: string example: trm_abc123 status: description: current terminal status example: CONNECTED type: string last_date_time_connected: type: string format: date-time example: '2021-01-01T12:00:00Z' last_date_time_active: type: string format: date-time example: '2021-01-01T12:00:00Z' TerminalsOrder: type: object properties: id: description: unique terminal order id type: string example: tord_xyz business_id: type: string format: uuid example: biz_xyz account_id: type: string format: uuid example: acc_xyz order_type: type: string enum: - boarding_only - boarding_shipping example: boarding_only order_status: type: string enum: - created - submitted - in_progress - completed - on_hold - canceled description: status of the order company_name: type: string description: business legal name when the terminal order was created example: Business Name mcc: type: string description: Merchant Category Code example: 7998 receiver_name: type: string description: name of the person receiving the terminal example: John Doe contact_first_name: type: string description: company's representative first name example: John contact_last_name: type: string description: company's representative last name example: Doe contact_email: type: string description: company's contact email example: john.doe@example.com contact_phone_number: type: string description: company's contact phone number example: 2125554567 line1: type: string example: 123 Main St line2: type: string example: Apt 4B city: type: string example: Minneapolis state: type: string example: MN postal_code: type: string example: 55401 time_zone: type: string description: determined by postal code example: US/Central country: type: string example: USA shipping_tracking_reference: type: string description: >- FedEx tracking number associated with the terminal order shipment. This field is populated only when the terminal order status is completed and the order includes a physical shipment. Always null for boarding_only terminal orders, as no shipment occurs. example: 12345678 created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' terminals: type: array description: list of ordered terminals items: type: object properties: terminal_id: type: string format: uuid description: unique terminal id example: tmn_abc terminal_did: type: string description: terminal device identification example: '12345678' model_name: type: string enum: - V400m - P400 - E285 example: V400m CardPaymentWithEnvelope: type: object properties: id: description: unique payment id, same as id in data object type: string example: py_xyz type: description: the object type type: string example: payment data: $ref: '#/components/schemas/CardPayment' page_info: description: information for cursor style pagination, is null for single records type: null nullable: true CheckoutCompletionAttempt: type: object properties: id: description: unique checkout completion id type: string example: chc_xyz123 payment_mode: type: string example: ecom enum: - ecom - bnpl - card_present payment_token: type: string example: pm_xyz123 description: >- the payment method token used to process the payment, only for ecom payments status: type: string enum: - succeeded - failed - processing example: succeeded description: the status of the completion, only succeeded or failed payment_status: type: string enum: - succeeded - failed - pending - canceled - skipped example: succeeded description: >- depending upon payment mode, the status of the payment API call, bnpl transaction, or card reader transaction. payment_error_code: type: string example: card_declined description: when payment fails, related error code payment_error_description: type: string example: Your card was declined description: when payment fails, related error description payment_response: allOf: - type: object - description: >- payment object if completion attempt was successful, error object if not successful - $ref: '#/components/schemas/CardPaymentWithEnvelope' checkout_id: type: string format: uuid example: cho_xyz123 description: id of the checkout for this completion additional_transactions: type: array of objects description: >- legacy attribute, any other transactions processed during checkout completion. For example, insurance payments example: [] payment_id: type: string format: uuid example: py_xyz123 description: id of the payment associated with this checkout, when successful payment_method_id: type: string format: uuid example: pm_xyz123 description: >- id of the payment method associated with this checkout, when successful terminal_id: type: string format: uuid example: trm_xyz123 description: id of the terminal used for this checkout, when mode is card present created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' Checkout: type: object properties: id: description: unique checkout id type: string format: uuid example: cho_xyz account_id: description: id of the account associated with the checkout type: string format: uuid example: acc_xyz platform_account_id: description: id of the platform account associated with the checkout type: string format: uuid example: acc_xyz payment_intent_id: description: id of the payment intent associated with the checkout type: string format: uuid example: pi_xyz payment_amount: description: the amount charged in cents type: number example: 10000 payment_currency: type: string enum: - USD - CAD example: USD payment_description: type: string description: >- your custom description of the payment if passed in the `payment` property during checkout creation, otherwise "Checkout [checkout id]" example: my order xyz payment_methods: type: array description: >- if `payment_method_group_id` was provided, list of payment methods contained in that payment method group example: - id: pm_123xyz type: card status: valid invalid_reason: null name: John Doe brand: visa acct_last_four: '4321' month: '12' year: '2031' address_line1_check: pass address_postal_code_check: pass bin_details: {} - id: pm_789abc type: bank_account status: valid invalid_reason: null account_owner_name: Mary Lane account_type: checking bank_name: Altra acct_last_four: '4512' payment_method_group_id: type: string description: id of payment method group used for checkout, if provided format: uuid example: pmg_xyz status: type: string enum: - created - completed - attempted - expired description: status of the checkout mode: type: string enum: - test - live description: mode of the checkout example: test successful_payment_id: type: string format: uuid example: py_123xyz description: payment id, if this checkout was paid for successfully statement_descriptor: type: string description: >- description of the payment that will be available on the account's bank statement example: Big Business metadata: type: object example: {} application_fees: type: object deprecated: true description: > **Deprecated**: Use the `fees` object instead for granular control over fee types and selective refunds. **New integrations** should use `payment.fees` instead for selective refund support. See [Enhanced Fee Management](#section/Enhanced-Fee-Management). properties: card: type: object properties: amount: description: >- custom application fee amount that applies to card payment method example: 300 bank_account: type: object properties: amount: description: >- custom application fee amount that applies to bank account payment method example: 150 payment_settings: type: object description: payment configuration information for the checkout example: ach_payments: true bnpl_payments: false credit_card_payments: true insurance_payments: false bank_account_verification: false payment: type: object description: >- data passed to the `payment` property during checkout creation, or null properties: description: type: string description: >- your meaningful description of the payment (e.g. an order number or other value from your system) example: my order xyz metadata: type: object format: json description: any useful custom information stored alongside this payment example: new: info expedited: type: boolean description: settlement priority of the payment, defaults to false example: true fees: type: array description: > Array of fee objects specifying the fees to be applied when the checkout is completed. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation. items: $ref: '#/components/schemas/Fee' example: - type: processing_fee amount: 295 - type: platform_fee amount: 150 created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' completions: type: array description: list of checkout completion attempts, if any items: $ref: '#/components/schemas/CheckoutCompletionAttempt' CheckoutCompletion: type: object properties: id: description: unique checkout completion id type: string example: chc_xyz payment_mode: type: string example: ecom enum: - ecom - bnpl - card_present payment_token: type: string example: pm_xyz123 description: >- the payment method token used to process the payment, only for ecom payments status: type: string enum: - succeeded - failed - processing example: succeeded description: the status of the completion, only succeeded or failed payment_status: type: string enum: - succeeded - failed - pending - canceled - skipped example: succeeded description: >- depending upon payment mode, the status of the payment API call, bnpl transaction, or card reader transaction. payment_error_code: type: string example: card_declined description: when payment fails, related error code payment_error_description: type: string example: Your card was declined description: when payment fails, related error description payment_response: allOf: - type: object - description: >- payment object if completion attempt was successful, error object if not successful - $ref: '#/components/schemas/CardPaymentWithEnvelope' checkout_id: type: string format: uuid description: id of the checkout for this completion example: cho_xyz123 additional_transactions: type: array of objects description: >- legacy attribute, other transactions processed during checkout completion. For example, insurance payments checkout: $ref: '#/components/schemas/Checkout' payment_id: type: string format: uuid example: py_xyz123 description: id of the payment associated with this checkout, when successful payment_method_id: type: string format: uuid example: pm_xyz123 description: id of the payment associated with this checkout, when successful terminal_id: type: string format: uuid example: trm_xyz123 description: id of the terminal used for this checkout, when mode is card present created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' CheckoutRefund: type: object properties: id: description: unique checkout refund id type: string example: chr_xyz checkout_id: type: string format: uuid description: id of the checkout for this refund status: type: string enum: - succeeded - failed example: succeeded description: the status of the refund, only succeeded or failed refund_response: type: string example: invalid_amount description: >- when refund fails, related error description. when refund succeeded additional refund info (or null). refund_amount: type: integer example: 4900 description: the amount requested to refund (or full checkout amount) returned_fees: type: array description: > Fees returned to the merchant as part of this refund. See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation. items: type: object properties: type: type: string enum: - processing_fee - platform_fee description: The type of fee that was returned example: processing_fee amount: type: integer description: Amount returned in cents example: 175 created_at: type: string format: date-time example: '2024-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2024-01-01T12:00:00Z' ReportType: description: which report was generated type: string example: proceeds enum: - proceeds - payout - interchange_fee - sub_account_summary - payment_list ReportProceedsParameters: type: object required: - report_type properties: report_type: type: string enum: - proceeds start_date: type: string format: date example: '2025-12-25' description: Start date to filter by. Maximum allowed date rage is 1 month end_date: type: string format: date example: '2025-12-30' description: End date to filter by. Maximum allowed date rage is 1 month nickname: description: the report nickname type: string example: My Report ReportPayoutParameters: type: object required: - report_type properties: report_type: type: string enum: - payout start_date: type: string format: date example: '2025-12-25' description: Start date to filter by. Maximum allowed date rage is 1 month end_date: type: string format: date example: '2025-12-30' description: End date to filter by. Maximum allowed date rage is 1 month nickname: description: the report nickname type: string example: My Report ReportInterchangeFeeParameters: type: object required: - report_type properties: report_type: type: string enum: - interchange_fee start_date: type: string format: date example: '2025-12-25' description: Start date to filter by. Maximum allowed date rage is 1 month end_date: type: string format: date example: '2025-12-30' description: End date to filter by. Maximum allowed date rage is 1 month nickname: description: the report nickname type: string example: My Report ReportSubAccountSummaryParameters: type: object required: - report_type properties: report_type: type: string enum: - sub_account_summary start_date: type: string format: date example: '2025-12-25' description: Start date to filter by. Maximum allowed date rage is 1 month end_date: type: string format: date example: '2025-12-30' description: End date to filter by. Maximum allowed date rage is 1 month nickname: description: the report nickname type: string example: My Report ReportPaymentListParameters: type: object required: - report_type properties: report_type: type: string enum: - payment_list payment_status: description: the payment status to filter by type: string enum: - authorized - failed - succeeded - canceled example: succeeded payment_method_id: description: the payment method id to filter by type: string example: pm_xyz terminal_id: description: the terminal_id to filter by type: string example: trm_xyz start_date: type: string format: date example: '2025-12-25' description: Start date to filter by. Maximum allowed date rage is 1 month end_date: type: string format: date example: '2025-12-30' description: End date to filter by. Maximum allowed date rage is 1 month nickname: description: the report nickname type: string example: My Report ReportParameters: oneOf: - allOf: - $ref: '#/components/schemas/ReportProceedsParameters' - type: object properties: account_id: type: string example: acc_xyz platform_account_id: type: string example: acc_xyz - allOf: - $ref: '#/components/schemas/ReportPayoutParameters' - type: object properties: account_id: type: string example: acc_xyz platform_account_id: type: string example: acc_xyz - allOf: - $ref: '#/components/schemas/ReportInterchangeFeeParameters' - type: object properties: account_id: type: string example: acc_xyz platform_account_id: type: string example: acc_xyz - allOf: - $ref: '#/components/schemas/ReportSubAccountSummaryParameters' - type: object properties: account_id: type: string example: acc_xyz platform_account_id: type: string example: acc_xyz - allOf: - $ref: '#/components/schemas/ReportPaymentListParameters' - type: object properties: account_id: type: string example: acc_xyz platform_account_id: type: string example: acc_xyz Report: type: object properties: id: description: report unique id type: string example: rpt_xyz report_type: $ref: '#/components/schemas/ReportType' nickname: description: the report nickname type: string example: My Report nullable: true status: description: the report status type: string example: scheduled enum: - scheduled - processing - completed - failed - canceled - expired scheduled_at: description: when the report was scheduled type: string format: date example: '2025-12-25T14:44:45.026Z' run_at: description: when the report started processing type: string format: date example: '2025-12-30T14:44:45.026Z' created_at: description: when the report was created type: string format: date example: '2025-12-31T14:44:45.026Z' error_description: description: error description in case of errors type: string account_id: description: the account id the report was created for type: string example: acc_xyz presigned_url: description: the url to download the report when completed type: string format: url platform_account_id: description: the platform account id the report was created for type: string example: acc_xyz parameters: $ref: '#/components/schemas/ReportParameters' Event: type: object properties: id: description: event unique id type: string example: evt_123xyz idempotency_key: description: idempotency key for request, when available type: string nullable: true request_id: description: id for request, when available type: string nullable: true account_id: description: sub account id for event type: string example: acc_123xyz account_type: description: live or test account type: string example: test platform_account_id: description: platform account id for event, when available type: string example: acc_123xyz nullable: true data: description: the attributes for the object type: object version: description: version of the event payload type: string example: v1 event_name: description: name of the event (payment.succeeded, sub_account.updated, etc.) example: payment.succeeded type: string ApplicationFeeRate: type: object properties: id: description: unique application fee rate id type: string format: uuid example: afr_123xyz transaction_fee: description: transaction fee amount, in cents type: number example: 50 currency: type: string enum: - usd - cad example: usd basis_point_rate: description: >- variable percentage of the payment amount that, combined with transaction fee, will be charged as the application fee. Expressed as the number of basis points type: number example: 250 rate_type: type: string enum: - cc - ach example: cc created_at: type: string format: date-time example: '2021-01-01T12:00:00Z' updated_at: type: string format: date-time example: '2021-01-01T12:00:00Z' effective_start: description: date and time (UTC) application fee rate went into effect type: string format: date-time example: '2021-01-01T12:00:00Z' effective_end: description: >- date and time (UTC) application fee rate is effectively archived. If null, no end date is currently assigned and application fee rate is currently effective type: string format: date-time example: '2021-01-01T12:00:00Z' PaymentSetting: type: object properties: id: description: unique payment setting id type: string example: stpy_123abc account_id: description: unique id of the associated account type: string example: acc_123abc mcc_code: description: merchant category code configured type: string example: '5045' credit_card_payments: description: credit card payments enabled for processing type: boolean example: true ach_payments: description: ach payments enabled for processing type: boolean example: true card_present: description: card present feature enabled for processing type: boolean example: false bnpl_payments: description: buy now pay later feature enabled type: boolean example: false insurance_payments: description: insurance feature enabled type: boolean example: false platform_wallet_account: description: wether this account is configured as platform_wallet_account type: boolean example: false PayoutSetting: type: object properties: public_id: description: unique payout setting id type: string example: stpo_213abc account_id: description: unique id of the associated account type: string example: acc_123abc enabled: description: whether the payout setting is currently enabled type: boolean example: true interval: description: payout frequency type: string example: daily statement_descriptor: description: custom text to appear on bank statements type: string example: Name of Account