Download OpenAPI specification:Download
The JustiFi API is a REST-based payment processing API. Our API has predictable, resource-oriented URLs, accepts JSON, and returns JSON. We use HTTP status codes and supply detailed error codes whenever possible. We'll provide you with both a test
and live
account with which to use our API. Each account will have its own API key, and the key you use to authenticate each request will determine whether to use your test
or live
account. When you use your test
account, it won't affect your live
data or move any real money.
To process a payment with JustiFi, follow these steps
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.
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.
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]"}'
{
"access_token": "... this will be a very long string and is valid for 24 hours"
}
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.
curl -X POST https://api.justifi.ai/v1/payments \
-H 'Authorization: Bearer [access_token]' \
-H 'Accept: application/json'
-H 'Idempotency-Key: a-unique-string-for-the-transaction'
In order to guarantee that payments and other important transactions are only ever processed a single time, we leverage the Idempotency-Key
header in our payments APIs. This means that you MUST provide an Idempotency-Key
header along with your request, otherwise you'll receive an error. If a second request with same idempotent key is processed concurrently, it will result in a 409
error instead of double processing.
If these requests fail with a network timeout or a 5XX
error, they should be retried with the same exact parameters. Once they're fully successful, you'll receive a 2XX
response. If you POST the same request and Idempotency-Key
again, you'll get the response you originally received back. If you receive a 4XX
error, do not retry the request, unless the response code is a 409
.
If you try the same Idempotency-Key
with different parameters, your request will error and won't be possible to process. The Idempotency-Key
header is only meant for a single transaction; it's there to protect against processing the same exact thing more than once. Once the parameters change, a request is considered distinct from the original request.
You may use any string to identify your Idempotency-Key
; we generally recommend using a generated uuid, but you may use any unique string.
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'
{
"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.
array
API Request ParametersParameter | 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.
All of our responses are contained in the same envelope, for arrays the id field will be null and the object will be an array.
Attribute | Description |
---|---|
id |
The id of the object returned. Will be null for arrays. type: string default: "a uuid"
|
type |
The type of object returned. type: string default: "array"
|
data |
The resource OR an array of the requested resources. type: array | object Notes: May be an empty array [] if no resources are available. |
page_info |
The object containing pagination information. type: object Notes: Contains has_previous , has_next , start_cursor and end_cursor
|
Use these card numbers to test successful transactions as well as various error scenarios. Make sure to authenticate your requests using your test
API key (these cards won't work for live
payments).
Number | Brand | CVC | Date |
---|---|---|---|
4242424242424242 |
Visa | Any 3 digits | Any future date |
4000056655665556 |
Visa (debit) | Any 3 digits | Any future date |
5555555555554444 |
Mastercard | Any 3 digits | Any future date |
2223003122003222 |
Mastercard (2-series) | Any 3 digits | Any future date |
5200828282828210 |
Mastercard (debit) | Any 3 digits | Any future date |
5105105105105100 |
Mastercard (prepaid) | Any 3 digits | Any future date |
378282246310005 |
American Express | Any 4 digits | Any future date |
371449635398431 |
American Express | Any 4 digits | Any future date |
6011000990139424 |
Discover | Any 3 digits | Any future date |
3056930009020004 |
Diners Club | Any 3 digits | Any future date |
36227206271667 |
Diners Club (14 digit card) | Any 3 digits | Any future date |
3566002020360505 |
JCB | Any 3 digits | Any future date |
6200000000000005 |
UnionPay | Any 3 digits | Any future date |
Number | Description |
---|---|
4000000000000101 |
If a CVC number is provided, the cvc_check fails. |
4000000000000341 |
Tokenizing this card succeeds, but attempts to make a payment fail. |
4000000000000002 |
Payment is declined with a card_declined code. |
4000000000009995 |
Payment is declined with a card_declined code. The decline_code attribute is insufficient_funds. |
4000000000009987 |
Payment is declined with a card_declined code. The decline_code attribute is lost_card. |
4000000000009979 |
Payment is declined with a card_declined code. The decline_code attribute is stolen_card. |
4000000000000069 |
Payment is declined with an expired_card code. |
4000000000000127 |
Payment is declined with an invalid_cvc code. |
4000000000000119 |
Payment is declined with a gateway_error code. |
4242424242424241 |
Payment is declined with an card_number_invalid code as the card number fails the Luhn check. |
Routing Number | Account Number |
---|---|
110000000 |
000123456789 |
Routing Number | Account Number | Payment Error |
---|---|---|
110000000 |
000222222227 |
Insufficient Funds |
110000000 |
000333333335 |
The account doesn't support debits |
110000000 |
000111111113 |
The account is closed |
110000000 |
000111111116 |
The account doesn't exist |
The JustiFi API may return a number of standard HTTP errors due to invalid requests. Some common errors are described below to help you build with JustiFi.
The server cannot process the request. This error is most likely due to malformed request syntax.
400
Bad Request
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.
401
Unauthorized
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.
402
Payment Required
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.
403
Forbidden
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.
404
Not Found
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.
409
Conflict
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.
422
Unprocessable Entity
An internal server error occurred due to an unexpected condition. This error is most likely due to an issue with our servers.
500
Internal Server Error
Many of our 4XX
errors will provide an error code in addition to their HTTP status. Here is a list of our error codes and a brief description of the error to provide more context when applicable.
Error Code | Description |
---|---|
acct_last_four_required |
Missing required parameter: acct_last_four |
amount_below_minimum |
Amount must be greater than 50 |
amount_must_be_an_integer |
Amount must be an integer |
amount_required |
Missing required parameter: amount |
amount_too_large |
The specified amount is greater than the maximum amount allowed. Use a lower amount and try again. |
amount_too_small |
The specified amount is less than the minimum amount allowed. Use a higher amount and try again. |
application_fee_rate_id_required |
Missing required parameter: application_fee_rate_id |
application_fee_required |
Missing required parameter: application_fee |
brand_required |
Missing required parameter: brand |
capture_strategy_invalid |
Format is invalid for parameter: capture_strategy |
card_decline_rate_limit_exceeded |
This card has been declined too many times. You can try to charge this card again after 24 hours. We suggest reaching out to your customer to make sure they have entered all of their information correctly and that there are no issues with their card. |
card_declined |
The card has been declined. When a card is declined, the error returned also includes the decline_code attribute with the reason why the card was declined. |
card_name_required |
Missing required parameter: card_name |
card_number_invalid |
Format is invalid for parameter: card_number |
card_number_required |
Missing required parameter: card_number |
charge_expired_for_capture |
The charge cannot be captured as the authorization has expired. Auth and capture charges must be captured within 7 days. |
country_invalid |
Format is invalid for parameter: country |
currency_invalid |
Format is invalid for parameter: currency |
currency_required |
Missing required parameter: currency |
customer_id_required |
Missing required parameter: customer_id |
customer_max_payment_methods |
The maximum number of PaymentMethods for this Customer has been reached. Either detach some PaymentMethods from this Customer or proceed with a different Customer. |
email_invalid |
The email address is invalid (e.g., not properly formatted). Check that the email address is properly formatted and only includes allowed characters. |
email_required |
Missing required parameter: email |
expired_card |
The card has expired. Check the expiration date or use a different card. |
gateway_account_id_required |
Missing required parameter: gateway_account_id |
gateway_authentication_error |
The payment network returned an authentication error |
gateway_error |
There was an issue processing your payment with the gateway. Please try again later. |
gateway_idempotency_error |
The gateway detected concurrent requests using this idempotency key |
gateway_rate_limit_error |
Too many requests hit the API too quickly. We recommend an exponential back-off of your requests. |
gateway_ref_id_required |
Missing required parameter: gateway_ref_id |
gateway_timeout_error |
There was a timeout with the gateway, we recommend retrying using the Should-Retry header |
idempotency_concurrent_request |
We detected concurrent requests using this idempotency key |
idempotency_key_required |
Idempotency-Key is a required header |
idempotency_params_mismatch |
The request parameters do not match those of a previous request using this idempotency key |
idempotency_request_in_progress |
Another request using this idempotency key is currently in progress |
internal_server_error |
An unexpected error has occurred. JustiFi engineers will investigate the error and contact you if any remediation steps are necessary. |
invalid_address |
The card’s address is incorrect. Check the card’s address or use a different card. |
invalid_card_number |
The card number is incorrect. Check the card number or use a different card. |
invalid_characters |
This value provided to the field contains characters that are unsupported by the field |
invalid_charge_amount |
The specified amount is invalid. The charge amount must be a positive integer in the smallest currency unit, and not exceed the minimum or maximum amount. |
invalid_cvc |
The card’s security code is incorrect. Check the card’s security code or use a different card. |
invalid_expiry_month |
The card’s expiration month is incorrect. Check the expiration date or use a different card. |
invalid_expiry_year |
The card’s expiration year is incorrect. Check the expiration date or use a different card. |
invalid_zip_code |
The card’s postal code is incorrect. Check the card’s postal code or use a different card. |
month_invalid |
Format is invalid for parameter: month |
not_authenticated |
Not authenticated |
not_authorized |
Not authorized |
parameter_missing |
Missing required parameter |
payment_fully_refunded |
The refund cannot be processed because the associated payment is fully refunded |
payment_intent_cannot_be_captured |
Payment Intent status is '%{status}' so it cannot be captured |
payment_intent_not_found |
Payment intent not found |
payment_intent_unexpected_state |
You cannot provide a new payment method to a PaymentIntent when it has a status of requires_capture, canceled, or succeeded |
payment_method_not_found |
Payment method not found |
payment_method_required |
Missing required parameter: payment_method |
payment_method_token_required |
Missing required parameter: payment_method_token |
payment_outside_refund_window |
The refund cannot be processed because the associated payment is outside the refund window |
postal_code_invalid |
Format is invalid for parameter: postal_code |
refund_exceeds_amount_available |
The refund cannot be processed because the refund amount exceeds the available funds |
refund_exceeds_payment_amount |
The refund cannot be processed because the refund amount exceeds the associated payment amount |
refund_reason_invalid |
Refund reason must be one of the following: %{Refund::REASONS} |
resource_not_found |
Resource not found |
state_invalid |
Format is invalid for parameter: state |
token_already_used |
The token provided has already been used. You must create a new token before you can retry this request. |
token_in_use |
The token provided is currently being used in another request. This occurs if your integration is making duplicate requests simultaneously. |
transfer_required |
Missing required parameter: transfer |
unexpected_parameter |
Unexpected parameter for this request |
verification_invalid |
Format is invalid for parameter: verification |
year_invalid |
Format is invalid for parameter: year |
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}
.
An access token has been granted
{- "client_id": "test_clientId",
- "client_secret": "test_clientSecret"
}
{- "access_token": "string"
}
Sub Accounts are the representation of your platform's customers in JustiFi. Payments are processed through sub accounts, each of which is associated with your platform account. To gain approval for payment processing, each sub account must submit the required onboarding information. You may send this to us through either our hosted onboarding or the API, and you'll be able to monitor each sub account's onboarding status along the way.
Status | Description |
---|---|
created | this sub account has been created (via Sub Accounts API), but we haven't received their onboarding entry yet |
submitted | we've received this sub account's onboarding entry (via hosted onboarding or API) and we're reviewing their information |
information_needed | we reviewed this sub account's onboarding entry and found an issue; we need more information before we can enable this account |
enabled | this sub account is approved to process payments note: test accounts are automatically enabled |
rejected | this sub account didn't pass approval, so they won't be able to process payments |
disabled | this sub account was previously approved, but has since become ineligible to process payments (e.g. due to fraud) |
archived | this sub account has been archived; they won't be able to process payments (but their record will remain for historical reasons) |
Create a 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.
Sub account was created successfully
{- "name": "Sub account name"
}
{- "id": 1,
- "type": "sub_account",
- "data": {
- "id": "acc_xyz",
- "name": "The Shire Haberdashery",
- "account_type": "live",
- "status": "enabled",
- "currency": "usd",
- "platform_account_id": "acc_xyz",
- "application_fee_rates": [ ],
- "processing_ready": false,
- "payout_ready": false,
- "related_accounts": {
- "live_account_id": "acc_xyz",
- "test_account_id": "acc_xyz"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
List the sub accounts for your platform. This endpoint supports pagination.
Note: By default, all sub accounts which are not archived will be returned. To list archived sub accounts, use the optional status parameter set to archived
Successfully list sub accounts
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "acc_xyz",
- "name": "The Shire Haberdashery",
- "account_type": "live",
- "status": "enabled",
- "currency": "usd",
- "platform_account_id": "acc_xyz",
- "application_fee_rates": [ ],
- "processing_ready": false,
- "payout_ready": false,
- "related_accounts": {
- "live_account_id": "acc_xyz",
- "test_account_id": "acc_xyz"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
Get information about a sub account.
Successfully get a sub account
{- "id": 1,
- "type": "sub_account",
- "data": {
- "id": "acc_xyz",
- "name": "The Shire Haberdashery",
- "account_type": "live",
- "status": "enabled",
- "currency": "usd",
- "platform_account_id": "acc_xyz",
- "application_fee_rates": [ ],
- "processing_ready": false,
- "payout_ready": false,
- "related_accounts": {
- "live_account_id": "acc_xyz",
- "test_account_id": "acc_xyz"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
Note: the term seller account has been deprecated and will be removed in future versions. Please use sub account instead
Create a JustiFi account for your customer, so they can process payments (once approved by JustiFi). The seller will be created as part of your platform. If you use your test credentials, the seller you create will have one account with the account_type
of test
. If you use your live credentials, the seller you create will have two accounts -- one with the account_type
of test
and another with the account_type
of live
. This allows you to perform test operations on your real sellers by using their test
account. When viewing the data payload for any seller account, you can reference the related_accounts
attribute to get the test_account_id
and live_account_id
(if present) for that seller.
Note: seller account is deprecated, please use sub account
Seller account was created successfully
{- "name": "Seller account name"
}
{- "id": 1,
- "type": "seller_account",
- "data": {
- "id": "acc_xyz",
- "name": "The Shire Haberdashery",
- "account_type": "live",
- "status": "enabled",
- "currency": "usd",
- "platform_account_id": "acc_xyz",
- "application_fee_rates": [ ],
- "processing_ready": false,
- "payout_ready": false,
- "related_accounts": {
- "live_account_id": "acc_xyz",
- "test_account_id": "acc_xyz"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
List the sellers for your account. This endpoint supports pagination.
Note: By default, all sellers which are not archived will be returned. To list archived sellers, use the optional status parameter set to archived
Note: seller account is deprecated, please use sub account
Successfully list seller accounts
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "acc_xyz",
- "name": "The Shire Haberdashery",
- "account_type": "live",
- "status": "enabled",
- "currency": "usd",
- "platform_account_id": "acc_xyz",
- "application_fee_rates": [ ],
- "processing_ready": false,
- "payout_ready": false,
- "related_accounts": {
- "live_account_id": "acc_xyz",
- "test_account_id": "acc_xyz"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
Get information about a seller account.
Note: seller account is deprecated, please use sub account
Successfully get a seller account
{- "id": 1,
- "type": "seller_account",
- "data": {
- "id": "acc_xyz",
- "name": "The Shire Haberdashery",
- "account_type": "live",
- "status": "enabled",
- "currency": "usd",
- "platform_account_id": "acc_xyz",
- "application_fee_rates": [ ],
- "processing_ready": false,
- "payout_ready": false,
- "related_accounts": {
- "live_account_id": "acc_xyz",
- "test_account_id": "acc_xyz"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
In order to process payments, each of your customers (whom we refer to as sub accounts
) will go through an approval process. JustiFi's hosted onboarding provides you with an easy-to-implement, user-friendly way to collect the required business and financial information from each sub accounts within your platform. Once approved, your sub account can process payments through JustiFi.
To onboard a new sub account via hosted onboarding
curl -X POST \
https://api.justifi.ai/v1/sub_accounts \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Sub account name"
}'
Use the sub accounts API to create a sub account on JustiFi that is associated with your platform. You will need the account_id
from the account you create for the next step.
To present the JustiFi hosted onboarding form to your user, create an iframe with a source of https://accounts.justifi.ai/onboarding/SUB_ACCOUNT_ID
, where SUB_ACCOUNT_ID
is the account_id
that was created in the previous step. This iframe will present your user with a multi-step form where they can enter the business and financial information needed for approval. Upon submission, a success message will display.
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.
curl -X GET https://api.justifi.ai/v1/sub_accounts/ACCOUNT_ID \
-H 'Authorization: Bearer [access_token]' \
-H 'Accept: application/json'
Once your sub account submits the onboarding form, we'll review their information. This approval process can take up to a few business days. In order to check the account's onboarding status, call the Get a Sub Account endpoint or use an event publisher to subscribe to the sub_account.updated
events.Note: seller_account.updated event has been deprecated
In order to process payments, each of your customers (whom we refer to as sub accounts
) will go through an approval process. JustiFi's onboarding API allows you to utilize your own onboarding frontend to collect the required business and financial information from each of your sub accounts. Once approved, your sub account can process payments through JustiFi.
To onboard a new sub account via the API
curl -X POST \
https://api.justifi.ai/v1/sub_accounts \
-H 'Authorization: Bearer {access_token}' \
-H 'Content-Type: application/json' \
-d '{
"name": "Sub account name"
}'
Use the sub accounts API to create a sub account on JustiFi that is associated with your platform. You will need the account_id
from the sub account you create for the next step.
Use the onboarding API to create an onboarding entry containing the required information for the sub account you made.
curl -X GET https://api.justifi.ai/v1/sub_accounts/ACCOUNT_ID \
-H 'Authorization: Bearer [access_token]' \
-H 'Accept: application/json'
Once you create the account's onboarding entry, we'll review their information. This approval process can take up to a few business days. In order to check the account's onboarding status, call the Get a Sub Account endpoint or use an event publisher to subscribe to the sub_account.updated
events.Note: seller_account.updated event has been deprecated
First, you'll need to create a sub account so you can use that sub account id in the path for this API.
Create an onboarding entry for a sub account, which will send their required onboarding information to the JustiFi team for review. This will change the sub account's status to submitted
. Upon review, if we require additional verification in the form of an ID document (which is rare), we'll work with your sub account to obtain the documentation we need.
Depending on each sub account's business type and structure, the onboarding information you'll need to collect will vary. Use the table below to check the requirements for each. You can also get a head start by copying the payloads from the request samples on the right; just choose the type of business you need from the dropdown first. Note: The payload, response, and restrictions are all subject to change based on gateway requirements.
For-Profit | Non-Profit | Government Entity | |||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|
Individual | Sole Proprietorship | Single Member LLC | Multi Member LLC | Private Partnership | Private Corporation | Unincorporated Association | Public Partnership | Public Corporation | Incorporated | Unincorporated | Governmental Unit | Government Instrumentality | |
business_details.url | Required for all | ||||||||||||
business_details.type | Required for all | ||||||||||||
business_details.structure | Required for all | ||||||||||||
business_details.industry | Required for all | ||||||||||||
business_details.tax_id | - | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
business_details.phone | - | - | - | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
business_details.email | - | - | - | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
business_details.legal.name | - | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
business_details.legal.address* fields | - | - | - | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
business_details.doing_business_as.name | Required for none | ||||||||||||
representative.name | Required for all | ||||||||||||
representative.title | - | - | - | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
representative.email | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - | - | ✅ | ✅ | - | - |
representative.phone | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - | - | ✅ | ✅ | - | - |
representative.ssn_last4 | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - | - | ✅ | ✅ | ✅ | ✅ |
representative.is_owner | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - | - | ✅ | ✅ | - | - |
representative.dob* fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - | - | ✅ | ✅ | ✅ | ✅ |
representative.address* fields | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ | - | - | ✅ | ✅ | - | - |
owners list |
- | - | - | ✅ | ✅ | ✅ | ✅ | - | - | - | - | - | - |
bank_account | Required for all | ||||||||||||
terms_and_conditions.accepted | Required for all | ||||||||||||
terms_and_conditions.ip | Required for all | ||||||||||||
terms_and_conditions.user_agent | Required for none |
Onboarding entry was created successfully
{- "business_details": {
- "type": "individual",
- "industry": "Landscaping Services"
}, - "representative": {
- "name": "Individual Personname",
- "email": "just.an.individual@justifi.ai",
- "dob_month": "01",
- "dob_day": "01",
- "dob_year": "1980",
- "address_line1": "123 Example St",
- "address_city": "Minneapolis",
- "address_state": "MN",
- "address_postal_code": "55555",
- "address_country": "USA",
- "phone": "6124011111",
- "ssn_last4": "6789",
- "is_owner": false
}, - "bank_account": {
- "bank_name": "Wells Fargo",
- "account_type": "checking",
- "routing_number": "111111111",
- "account_number": "111111112",
- "account_nickname": "My payout account",
- "account_owner_name": "Paper holder"
}, - "terms_and_conditions": {
- "accepted": true,
- "ip": "127.0.0.1",
- "user_agent": "Safari"
}
}
{- "id": 1,
- "type": "onboarding_entry",
- "data": {
- "account_type": "string",
- "seller_account_id": "string",
- "sub_account_id": "string",
- "platform_account_id": "string",
- "payload": {
- "onboarding_version": "v1.0",
- "business_details": {
- "type": "for_profit",
- "structure": "sole_proprietorship",
- "industry": "string",
- "tax_id": "string",
- "phone": "string",
- "email": "string",
- "legal": {
- "name": "string",
- "address_line1": "string",
- "address_line2": "string",
- "address_city": "string",
- "address_state": "string",
- "address_postal_code": "string",
- "address_country": "string"
}, - "doing_business_as": {
- "name": "string"
}
}, - "representative": {
- "name": "string",
- "title": "string",
- "email": "user@example.com",
- "dob_month": "string",
- "dob_day": "string",
- "dob_year": "string",
- "address_line1": "string",
- "address_line2": "string",
- "address_city": "string",
- "address_state": "string",
- "address_postal_code": "string",
- "address_country": "string",
- "phone": "string",
- "ssn_last4": "string",
- "is_owner": true
}, - "owners": [
- {
- "name": "string",
- "email": "user@example.com"
}
], - "bank_account": {
- "bank_name": "string",
- "account_nickname": "string",
- "routing_number": "string",
- "account_number": "string",
- "account_type": "checking",
- "account_owner_name": "string"
}, - "terms_and_conditions": {
- "accepted": true,
- "ip": "string",
- "user_agent": "string"
}
}
}, - "page_info": null
}
Proceeds represent your platform's take-home portion of the fees from your sellers' financial transactions. Proceeds are batched together according to the payout schedule configured on your account, then transferred to your active bank account.
List the proceeds payouts for your account. This endpoint supports pagination.
Successfully list proceeds
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "po_xyz",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "amount": 100000,
- "bank_account": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "full_name": "string",
- "bank_name": "string",
- "account_number_last4": 1111,
- "routing_number": "string",
- "country": "US",
- "currency": "usd",
- "nickname": "string",
- "account_type": "checking"
}, - "currency": "usd",
- "delivery_method": "standard",
- "description": "string",
- "deposits_at": "2021-01-01T12:00:00Z",
- "refunds_count": 5,
- "refunds_total": 10000,
- "payments_count": 50,
- "payments_total": 110000,
- "payout_type": "proceeds",
- "other_total": 100,
- "status": "scheduled",
- "metadata": {
- "platform_payout_id": "cp_12345"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
Get information about a proceeds payout.
Successfully get a proceeds payout
{- "id": 1,
- "type": "payout",
- "data": [
- {
- "id": "po_xyz",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "amount": 100000,
- "bank_account": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "full_name": "string",
- "bank_name": "string",
- "account_number_last4": 1111,
- "routing_number": "string",
- "country": "US",
- "currency": "usd",
- "nickname": "string",
- "account_type": "checking"
}, - "currency": "usd",
- "delivery_method": "standard",
- "description": "string",
- "deposits_at": "2021-01-01T12:00:00Z",
- "refunds_count": 5,
- "refunds_total": 10000,
- "payments_count": 50,
- "payments_total": 110000,
- "payout_type": "proceeds",
- "other_total": 100,
- "status": "scheduled",
- "metadata": {
- "platform_payout_id": "cp_12345"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
JustiFi provides a hosted checkout solution which allows you to collect a payment via a checkout form which we host. This solution provides less customization compared to using our PaymentsJS / Payment Web Components, however it requires less frontend integration work on your platform.
To collect a payment via hosted checkout, you must first ensure you ask the JustiFi team to enable the hosted checkout feature for your platform. We will also configure the branding for the checkout at this time.
Once you have configured hosted checkout, you must complete the following steps to complete a payment:
Create a Payment Intent with the amount you'd like to capture, and a description of the payment.
Create a checkout session which will be used to redirect your customer to the JustiFi checkout page. This in includes the payment intent, a url to redirect for a back/cancel action, and a url for redirect after completing the payment. At this point You have 24 hours to complete the checkout.
Using the checkout session id returned from the previous step, redirect to https://checkout.justifi.ai/r/{checkout_session_id}, this will redirect your customer our checkout form with your branding.
If the checkout is completed, we will redirect to the after payment url provided when the checkout session was created. Please note, it is possible the payment may not be in a pending, or failed status, so please interrogate the payment via API.
If a customer decides not to pay, we have a back button on the checkout form. If you provide a back_url, we will redirect the customer back to that url.
In addition to the after payment redirect, we recommend creating an Event Publisher which publishes payment_intent.succeeded
events. This will provide a secondary means to ensure the payment was successful if there are network issues with the redirect.
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.
Authorize, capture, and charge a payment method.
Note: For platforms, if the sub account status is not enabled
, 400
will be returned.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Sub-Account | string for platforms, the id of the sub account that this request applies to Example: acc_2IdMEOjIG6lJAncakgdBF2 |
Seller-Account | string Deprecated for platforms, the id of the seller account that this request applies to |
Payment was created successfully
{- "amount": 1000,
- "currency": "usd",
- "capture_strategy": "automatic",
- "email": "example@test.com",
- "description": "Charging $10 to the test card",
- "payment_method": {
- "card": {
- "name": "Sylvia Fowles",
- "number": "4111111111111111",
- "verification": "123",
- "month": "3",
- "year": "2040",
- "address_postal_code": "55555"
}
}
}
{- "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",
- "refunded": false,
- "returned": false,
- "status": "succeeded",
- "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
}
List the payments for your account. This endpoint supports pagination.
Authorization required | string the Example: Bearer {access_token} |
Sub-Account | string for platforms, the id of the sub account that this request applies to Example: acc_2IdMEOjIG6lJAncakgdBF2 |
Seller-Account | string Deprecated for platforms, the id of the seller account that this request applies to |
Successfully list payments
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "py_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "amount_disputed": 0,
- "amount_refunded": 0,
- "amount_refundable": 10000,
- "balance": 99850,
- "fee_amount": 150,
- "financial_transaction_id": "ft_123xyz",
- "captured": true,
- "capture_strategy": "automatic",
- "currency": "usd",
- "description": "my_order_xyz",
- "disputed": false,
- "disputes": [ ],
- "error_code": "credit_card_number_invalid",
- "error_description": "Credit Card Number Invalid (Failed LUHN checksum)",
- "is_test": true,
- "metadata": { },
- "payment_intent_id": "py_xyz",
- "payment_method": {
- "card": {
- "id": "pm_123xyz",
- "acct_last_four": 4242,
- "brand": "Visa",
- "name": "Amanda Kessel",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z",
- "address_line1_check": "unchecked",
- "address_postal_code_check": "unchecked"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "application_fee": {
- "id": "fee_123xyz",
- "amount": 150,
- "currency": "usd",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "refunded": false,
- "status": "pending",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - {
- "id": "py_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "amount_disputed": 0,
- "amount_refunded": 0,
- "amount_refundable": 10000,
- "balance": 99850,
- "fee_amount": 150,
- "financial_transaction_id": "ft_123xyz",
- "captured": true,
- "capture_strategy": "automatic",
- "currency": "usd",
- "description": "my_order_xyz",
- "disputed": false,
- "disputes": [ ],
- "error_code": "credit_card_number_invalid",
- "error_description": "Credit Card Number Invalid (Failed LUHN checksum)",
- "is_test": true,
- "metadata": { },
- "payment_intent_id": "py_xyz",
- "payment_method": {
- "bank_account": {
- "id": "pm_123xyz",
- "acct_last_four": 1111,
- "brand": "Wells Fargo",
- "name": "Phil Kessel",
- "token": "pm_123xyz",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "application_fee": {
- "id": "fee_123xyz",
- "amount": 150,
- "currency": "usd",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "refunded": false,
- "status": "pending",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
{- "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",
- "refunded": false,
- "returned": false,
- "status": "succeeded",
- "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
}
Change a payment's description or metadata.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Payment update was successful
{- "description": "order_xyz new description",
- "metadata": { }
}
{- "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",
- "refunded": false,
- "returned": false,
- "status": "succeeded",
- "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
}
To charge a payment method and capture a previously authorized payment. Returns a payment_already_captured
error if the payment is in a captured state.
Note: For platforms, if the sub account status is not enabled
, 400
will be returned.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Payment with identical idempotency key was captured
Payment was captured successfully
{- "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": "succeeded",
- "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
}
Issue a refund for a payment. You may refund the full payment amount or just a portion. When refunding a portion, multiple refunds are supported up until the full payment amount has been refunded.
Note: For platforms, if the seller account status is not enabled
, 400
will be returned.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Refund was created successfully
{- "amount": 10000,
- "description": "string",
- "reason": "duplicate",
- "metadata": { }
}
{- "id": 1,
- "type": "refund",
- "data": {
- "id": "re_xyz",
- "payment_id": "py_xyz",
- "amount": 100,
- "description": "customer canceled their order",
- "reason": "duplicate",
- "status": "succeeded",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
Get information about the payment-balance-transactions associated with a payment.
Successfully retrieve the payment-balance-transactions for a payment
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "pbt_123xyz",
- "amount": 40145,
- "balance": 53550,
- "currency": "usd",
- "financial_transaction_id": "py_2644edn",
- "payment_id": "py_2644edn",
- "payment_balance_txn_type": "fee_refund",
- "source_id": "fee_6Vt2jlZZVh",
- "source_type": "ApplicationFee",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
If you'd like to track the payment method and all associated payment attempts for a particular payment, you can use payment intents. Once you've tokenized a payment method and attached it to a payment intent, capturing the payment intent will let JustiFi know to charge the payment method and create a payment. If the capture fails, you can attempt again on the same payment intent.
Create a payment intent if you'd like a place to track the payment method along with all payment attempts for a payment.
Note: For platforms, if the seller account status is not enabled
, 400
will be returned.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Sub-Account | string for platforms, the id of the sub account that this request applies to Example: acc_2IdMEOjIG6lJAncakgdBF2 |
Seller-Account | string Deprecated for platforms, the id of the seller account that this request applies to |
Payment intent was created successfully
{- "amount": 1000,
- "currency": "usd",
- "description": "ORDER 1235ABC: Charging $10 to the test card",
- "metadata": {
- "order_number": "12345ABC"
}
}
{- "id": "pi_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "currency": "usd",
- "description": "my_order_xyz",
- "metadata": { },
- "payment_method": {
- "card": {
- "id": "pm_123xyz",
- "acct_last_four": 4242,
- "brand": "Visa",
- "name": "Amanda Kessel",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z",
- "address_line1_check": "unchecked",
- "address_postal_code_check": "unchecked"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "status": "requires_payment_method",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
List the payment intents for your account. This endpoint supports pagination.
Authorization required | string the Example: Bearer {access_token} |
Sub-Account | string for platforms, the id of the sub account that this request applies to Example: acc_2IdMEOjIG6lJAncakgdBF2 |
Seller-Account | string Deprecated for platforms, the id of the seller account that this request applies to |
Successfully list payment intents
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "pi_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "currency": "usd",
- "description": "my_order_xyz",
- "metadata": { },
- "payment_method": {
- "card": {
- "id": "pm_123xyz",
- "acct_last_four": 4242,
- "brand": "Visa",
- "name": "Amanda Kessel",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z",
- "address_line1_check": "unchecked",
- "address_postal_code_check": "unchecked"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "status": "requires_payment_method",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - {
- "id": "pi_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "currency": "usd",
- "description": "my_order_xyz",
- "metadata": { },
- "payment_method": {
- "bank_account": {
- "id": "pm_123xyz",
- "acct_last_four": 1111,
- "brand": "Wells Fargo",
- "name": "Phil Kessel",
- "token": "pm_123xyz",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "status": "requires_payment_method",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
Get information about a payment intent.
Successfully get a payment intent
{- "id": "pi_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "currency": "usd",
- "description": "my_order_xyz",
- "metadata": { },
- "payment_method": {
- "card": {
- "id": "pm_123xyz",
- "acct_last_four": 4242,
- "brand": "Visa",
- "name": "Amanda Kessel",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z",
- "address_line1_check": "unchecked",
- "address_postal_code_check": "unchecked"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "status": "requires_payment_method",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
Change a payment intent's description or metadata; attach a payment method.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Payment intent update was successful
{- "description": "order_xyz",
- "metadata": { },
- "payment_method": {
- "card": {
- "name": "Kevin Garnett",
- "number": 4242424242424242,
- "verification": 123,
- "month": 5,
- "year": 2042,
- "address_line1": "123 Fake St",
- "address_line2": "Suite 101",
- "address_city": "Cityville",
- "address_state": "MN",
- "address_postal_code": 55555,
- "address_country": "US",
- "brand": "Visa",
- "metadata": { }
}, - "token": "pm_xyz"
}, - "amount": 10000
}
{- "id": "pi_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "currency": "usd",
- "description": "my_order_xyz",
- "metadata": { },
- "payment_method": {
- "card": {
- "id": "pm_123xyz",
- "acct_last_four": 4242,
- "brand": "Visa",
- "name": "Amanda Kessel",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z",
- "address_line1_check": "unchecked",
- "address_postal_code_check": "unchecked"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "status": "requires_payment_method",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
Capturing a payment intent lets JustiFi know you intend to process a payment. JustiFi will charge the attached payment method and create a payment.
Note: For platforms, if the sub account status is not enabled
, 400
will be returned.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
object |
Payment intent was captured successfully
{- "payment_method": {
- "card": {
- "name": "Kevin Garnett",
- "number": 4242424242424242,
- "verification": 123,
- "month": 5,
- "year": 2042,
- "address_line1": "123 Fake St",
- "address_line2": "Suite 101",
- "address_city": "Cityville",
- "address_state": "MN",
- "address_postal_code": 55555,
- "address_country": "US",
- "brand": "Visa",
- "metadata": { }
}, - "token": "pm_xyz"
}
}
{- "id": "pi_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "currency": "usd",
- "description": "my_order_xyz",
- "metadata": { },
- "payment_method": {
- "card": {
- "id": "pm_123xyz",
- "acct_last_four": 4242,
- "brand": "Visa",
- "name": "Amanda Kessel",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z",
- "address_line1_check": "unchecked",
- "address_postal_code_check": "unchecked"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "status": "requires_payment_method",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
Get information about the payments associated with a payment intent.
Successfully retrieve the payments for a payment intent
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "py_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "amount_disputed": 0,
- "amount_refunded": 0,
- "amount_refundable": 10000,
- "balance": 99850,
- "fee_amount": 150,
- "financial_transaction_id": "ft_123xyz",
- "captured": true,
- "capture_strategy": "automatic",
- "currency": "usd",
- "description": "my_order_xyz",
- "disputed": false,
- "disputes": [ ],
- "error_code": "credit_card_number_invalid",
- "error_description": "Credit Card Number Invalid (Failed LUHN checksum)",
- "is_test": true,
- "metadata": { },
- "payment_intent_id": "py_xyz",
- "payment_method": {
- "card": {
- "id": "pm_123xyz",
- "acct_last_four": 4242,
- "brand": "Visa",
- "name": "Amanda Kessel",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z",
- "address_line1_check": "unchecked",
- "address_postal_code_check": "unchecked"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "application_fee": {
- "id": "fee_123xyz",
- "amount": 150,
- "currency": "usd",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "refunded": false,
- "status": "pending",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - {
- "id": "py_xyz",
- "account_id": "acc_xyz",
- "amount": 10000,
- "amount_disputed": 0,
- "amount_refunded": 0,
- "amount_refundable": 10000,
- "balance": 99850,
- "fee_amount": 150,
- "financial_transaction_id": "ft_123xyz",
- "captured": true,
- "capture_strategy": "automatic",
- "currency": "usd",
- "description": "my_order_xyz",
- "disputed": false,
- "disputes": [ ],
- "error_code": "credit_card_number_invalid",
- "error_description": "Credit Card Number Invalid (Failed LUHN checksum)",
- "is_test": true,
- "metadata": { },
- "payment_intent_id": "py_xyz",
- "payment_method": {
- "bank_account": {
- "id": "pm_123xyz",
- "acct_last_four": 1111,
- "brand": "Wells Fargo",
- "name": "Phil Kessel",
- "token": "pm_123xyz",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - "application_fee": {
- "id": "fee_123xyz",
- "amount": 150,
- "currency": "usd",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "refunded": false,
- "status": "pending",
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
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.
You can create payment methods ahead of time, then pass their existing tokens to payments.
Alternatively, you can create and tokenize payment methods inline when processing payments.
Note: For platforms, if the seller account status is not enabled
, 400
will be returned.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Sub-Account | string for platforms, the id of the sub account that this request applies to Example: acc_2IdMEOjIG6lJAncakgdBF2 |
Seller-Account | string Deprecated for platforms, the id of the seller account that this request applies to |
Payment method was created successfully
{- "payment_method": {
- "card": {
- "name": "Lindsay Whalen",
- "number": 4242424242421111,
- "verification": 123,
- "month": 5,
- "year": 2042,
- "address_postal_code": 55555,
- "metadata": {
- "new": "info"
}
}
}
}
{- "id": "pm_123xyz",
- "type": "payment_method",
- "data": {
- "signature": "3aGWnUznQ",
- "customer_id": "cust_123abc",
- "account_id": "acc_123",
- "card": {
- "id": "pm_123xyz",
- "name": "Lindsay Whalen",
- "acct_last_four": 1111,
- "brand": "visa",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": {
- "new": "info"
}, - "address_line1_check": "pass",
- "address_postal_code_check": "pass"
}
}, - "page_info": null
}
List the payment methods for your account. This endpoint supports pagination.
Authorization required | string the Example: Bearer {access_token} |
Sub-Account | string for platforms, the id of the sub account that this request applies to Example: acc_2IdMEOjIG6lJAncakgdBF2 |
Seller-Account | string Deprecated for platforms, the id of the seller account that this request applies to |
Successfully list payment methods
{- "id": 1,
- "type": "array",
- "data": [
- {
- "card": {
- "id": "pm_123xyz",
- "acct_last_four": 4242,
- "brand": "Visa",
- "name": "Amanda Kessel",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z",
- "address_line1_check": "unchecked",
- "address_postal_code_check": "unchecked"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}, - {
- "bank_account": {
- "id": "pm_123xyz",
- "acct_last_four": 1111,
- "brand": "Wells Fargo",
- "name": "Phil Kessel",
- "token": "pm_123xyz",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "customer_id": "cust_xyz",
- "signature": "4guAJNkVA3lRLVlanNVoBK",
- "account_id": "acc_123"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
Get information about a payment method.
Successfully get a payment method
{- "id": "pm_123xyz",
- "type": "payment_method",
- "data": {
- "signature": "3aGWnUznQ",
- "customer_id": "cust_123abc",
- "account_id": "acc_123",
- "card": {
- "id": "pm_123xyz",
- "name": "Lindsay Whalen",
- "acct_last_four": 1111,
- "brand": "visa",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": {
- "new": "info"
}, - "address_line1_check": "pass",
- "address_postal_code_check": "pass"
}
}, - "page_info": null
}
Change a payment method's expiration date, address, or metadata.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
object (UpdateCard) | |
object (UpdateBankAccount) Bank Account |
Payment method update was successful
{- "card": {
- "month": 5,
- "year": 2042,
- "address_line1": "123 Fake St",
- "address_line2": "Suite 101",
- "address_city": "Cityville",
- "address_state": "MN",
- "address_postal_code": 55555,
- "address_country": "US",
- "metadata": {
- "new": "info"
}
}, - "bank_account": {
- "metadata": {
- "new": "info"
}
}
}
{- "id": "pm_123xyz",
- "type": "payment_method",
- "data": {
- "signature": "3aGWnUznQ",
- "customer_id": "cust_123abc",
- "account_id": "acc_123",
- "card": {
- "id": "pm_123xyz",
- "name": "Lindsay Whalen",
- "acct_last_four": 1111,
- "brand": "visa",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": {
- "new": "info"
}, - "address_line1_check": "pass",
- "address_postal_code_check": "pass"
}
}, - "page_info": null
}
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.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Payment method clone was successful
{- "destination_account_id": "acc_xyz123"
}
{- "id": "pm_123xyz",
- "type": "payment_method",
- "data": {
- "signature": "3aGWnUznQ",
- "customer_id": "cust_123abc",
- "account_id": "acc_123",
- "card": {
- "id": "pm_123xyz",
- "name": "Lindsay Whalen",
- "acct_last_four": 1111,
- "brand": "visa",
- "token": "pm_123xyz",
- "month": "5",
- "year": "2042",
- "metadata": {
- "new": "info"
}, - "address_line1_check": "pass",
- "address_postal_code_check": "pass"
}
}, - "page_info": null
}
When you refund a payment, a refund object is created. You can retrieve information about the refunds you've issued.
List the refunds for your account. This endpoint supports pagination.
Authorization required | string the Example: Bearer {access_token} |
Sub-Account | string for platforms, the id of the sub account that this request applies to Example: acc_2IdMEOjIG6lJAncakgdBF2 |
Seller-Account | string Deprecated for platforms, the id of the seller account that this request applies to |
Successfully list refunds
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "re_xyz",
- "payment_id": "py_xyz",
- "amount": 100,
- "description": "customer canceled their order",
- "reason": "duplicate",
- "status": "succeeded",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
{- "id": 1,
- "type": "refund",
- "data": {
- "id": "re_xyz",
- "payment_id": "py_xyz",
- "amount": 100,
- "description": "customer canceled their order",
- "reason": "duplicate",
- "status": "succeeded",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
Update the refund metadata.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Refund update was successful
{- "metadata": { }
}
{- "id": 1,
- "type": "refund",
- "data": {
- "id": "re_xyz",
- "payment_id": "py_xyz",
- "amount": 100,
- "description": "customer canceled their order",
- "reason": "duplicate",
- "status": "succeeded",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
A customer may dispute their payment with the card issuer/bank if they believe the charge is erroneous. When this happens, a dispute record is created and associated with their original payment.
List the disputes for your account. This endpoint supports pagination. The disputes for a specific payment are also included in the payments API response.
Authorization required | string the Example: Bearer {access_token} |
Sub-Account | string for platforms, the id of the sub account that this request applies to Example: acc_2IdMEOjIG6lJAncakgdBF2 |
Seller-Account | string Deprecated for platforms, the id of the seller account that this request applies to |
Successfully list disputes
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "dp_xyz",
- "amount": 100,
- "currency": "usd",
- "payment_id": "py_xyz",
- "reason": "fraudulent",
- "status": "won",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
{- "id": 1,
- "type": "dispute",
- "data": {
- "id": "dp_xyz",
- "amount": 100,
- "currency": "usd",
- "payment_id": "py_xyz",
- "reason": "fraudulent",
- "status": "won",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
Change a dispute's metadata.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Dispute update was successful
{- "metadata": { }
}
{- "id": 1,
- "type": "dispute",
- "data": {
- "id": "dp_xyz",
- "amount": 100,
- "currency": "usd",
- "payment_id": "py_xyz",
- "reason": "fraudulent",
- "status": "won",
- "metadata": { },
- "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
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.
Successfully list payouts
{- "id": 1,
- "type": "array",
- "data": [
- {
- "id": "po_xyz",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "amount": 100000,
- "bank_account": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "full_name": "string",
- "bank_name": "string",
- "account_number_last4": 1111,
- "routing_number": "string",
- "country": "US",
- "currency": "usd",
- "nickname": "string",
- "account_type": "checking"
}, - "currency": "usd",
- "delivery_method": "standard",
- "description": "string",
- "deposits_at": "2021-01-01T12:00:00Z",
- "fees_total": 5000,
- "refunds_count": 5,
- "refunds_total": 10000,
- "payments_count": 50,
- "payments_total": 110000,
- "payout_type": "ach cc",
- "other_total": 100,
- "status": "paid",
- "metadata": {
- "customer_payout_id": "cp_12345"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}
], - "page_info": {
- "end_cursor": "WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd",
- "has_next": false,
- "has_previous": false,
- "start_cursor": "WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd"
}
}
{- "id": 1,
- "type": "payout",
- "data": {
- "id": "po_xyz",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "amount": 100000,
- "bank_account": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "full_name": "string",
- "bank_name": "string",
- "account_number_last4": 1111,
- "routing_number": "string",
- "country": "US",
- "currency": "usd",
- "nickname": "string",
- "account_type": "checking"
}, - "currency": "usd",
- "delivery_method": "standard",
- "description": "string",
- "deposits_at": "2021-01-01T12:00:00Z",
- "fees_total": 5000,
- "refunds_count": 5,
- "refunds_total": 10000,
- "payments_count": 50,
- "payments_total": 110000,
- "payout_type": "ach cc",
- "other_total": 100,
- "status": "paid",
- "metadata": {
- "customer_payout_id": "cp_12345"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
Change a payout's metadata.
Idempotency-Key required | string <uuid> a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests Example: my-request-123abc |
Authorization required | string the Example: Bearer {access_token} |
Payout update was successful
{- "metadata": {
- "customer_payout_id": "cp_12345"
}
}
{- "id": 1,
- "type": "payout",
- "data": {
- "id": "po_xyz",
- "account_id": "449e7a5c-69d3-4b8a-aaaf-5c9b713ebc65",
- "amount": 100000,
- "bank_account": {
- "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
- "full_name": "string",
- "bank_name": "string",
- "account_number_last4": 1111,
- "routing_number": "string",
- "country": "US",
- "currency": "usd",
- "nickname": "string",
- "account_type": "checking"
}, - "currency": "usd",
- "delivery_method": "standard",
- "description": "string",
- "deposits_at": "2021-01-01T12:00:00Z",
- "fees_total": 5000,
- "refunds_count": 5,
- "refunds_total": 10000,
- "payments_count": 50,
- "payments_total": 110000,
- "payout_type": "ach cc",
- "other_total": 100,
- "status": "paid",
- "metadata": {
- "customer_payout_id": "cp_12345"
}, - "created_at": "2021-01-01T12:00:00Z",
- "updated_at": "2021-01-01T12:00:00Z"
}, - "page_info": null
}
Get a link to a CSV report with information a payout and balance transactions related to that payout. CSV report headers include id, currency, amount, fee, net, source_id, source_account_id, source_type, source_amount, available_on and created_at.
Successfully get a link to a csv report for a payout