logo

Payments

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

Create a Payment

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

Request
header Parameters
Idempotency-Key
required
string <uuid>

a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see Idempotent Requests

Example: my-request-123abc
Authorization
required
string

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

Example: Bearer {access_token}
Sub-Account
string

for platforms, the id of the sub account that this request applies to

Example: acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
Deprecated

for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account

Request Body schema: application/json
amount
required
number

amount to charge in cents

currency
required
string
Value: "usd"
capture_strategy
required
string

automatic will authorize and capture the payment in the same request, manual will only authorize the payment (which will need to be captured in a subsequent request). Not supported by bank account (ACH) payment methods.

Enum: "automatic" "manual"
email
string <email>

email address to associate with payment method

required
object
application_fee_amount
integer

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

description
string

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

metadata
object <json>

any useful information you'd like to store alongside this payment

Responses
201

Payment was created successfully

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

List Payments

List the payments for your account. This endpoint supports pagination.

Request
query Parameters
financial_transaction_id
string

Filter records which are associated with a financial transaction.

Example: financial_transaction_id=ft_123xyz
created_after
string <datetime>

Filter records which were created after the date or datetime specified. UTC time. Dates without time specified will default to 00:00:00

Example: created_after=2022-01-01T00:00:00Z
payment_status
string

Filter to payments which have request payment_status

Enum: "succeeded" "failed" "pending" "authorized" "refunded" "disputed"
Example: payment_status=refunded
header Parameters
Authorization
required
string

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

Example: Bearer {access_token}
Sub-Account
string

for platforms, the id of the sub account that this request applies to

Example: acc_2IdMEOjIG6lJAncakgdBF2
Seller-Account
string
Deprecated

for platforms, the id of the seller account that this request applies to
Note: seller account is deprecated, please use sub account

Responses
200

Successfully list payments

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


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


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


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


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


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


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


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


 
Responses 
200
Payment update was successful


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


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


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


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


201
Payment was captured successfully


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


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


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


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


 
description
string
an optional note about this refund


 
reason
string
the reason this refund is being issued


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


 
Responses 
201
Refund was created successfully


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


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


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


get/payments/{id}/payment_balance_transactions
Request samples 
Response samples 
application/json
{
  • "id": 1,
  • "type": "array",
  • "data": [
    ],
  • "page_info": {
    }
}
➔ Next to Payment Intents