logo

Payment Intents

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

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.

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"
description
string

your meaningful description of the payment intent (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 intent

Responses
201

Payment intent was created successfully

post/payment_intents
Request samples
application/json
{
  • "amount": 1000,
  • "currency": "usd",
  • "description": "ORDER 1235ABC: Charging $10 to the test card",
  • "metadata": {
    }
}
Response samples
application/json
{
  • "id": "pi_xyz",
  • "account_id": "acc_xyz",
  • "amount": 10000,
  • "currency": "usd",
  • "description": "my_order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "status": "requires_payment_method",
  • "created_at": "2021-01-01T12:00:00Z",
  • "updated_at": "2021-01-01T12:00:00Z"
}

List Payment Intents

List the payment intents for your account. This endpoint supports pagination.

Request
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 payment intents

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


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 intent


get/payment_intents/{id}
Request samples 
Response samples 
application/json
{
  • "id": "pi_xyz",
  • "account_id": "acc_xyz",
  • "amount": 10000,
  • "currency": "usd",
  • "description": "my_order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "status": "requires_payment_method",
  • "created_at": "2021-01-01T12:00:00Z",
  • "updated_at": "2021-01-01T12:00:00Z"
}
Update a Payment Intent
Change a payment intent's description or metadata; attach a payment method.


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 intent (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 intent; when you update metadata, any previous metadata will be overwritten


 
object
can be updated if the payment intent status is requires_payment_method or pending


 
amount
integer
payment intent amount, in cents; can be updated if the payment intent status is requires_payment_method or pending


 
Responses 
200
Payment intent update was successful


patch/payment_intents/{id}
Request samples 
application/json
{
  • "description": "order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "amount": 10000
}
Response samples 
application/json
{
  • "id": "pi_xyz",
  • "account_id": "acc_xyz",
  • "amount": 10000,
  • "currency": "usd",
  • "description": "my_order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "status": "requires_payment_method",
  • "created_at": "2021-01-01T12:00:00Z",
  • "updated_at": "2021-01-01T12:00:00Z"
}
Capture a Payment Intent
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.


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
object
 
Responses 
201
Payment intent was captured successfully


post/payment_intents/{id}/capture
Request samples 
application/json
{
  • "payment_method": {
    }
}
Response samples 
application/json
{
  • "id": "pi_xyz",
  • "account_id": "acc_xyz",
  • "amount": 10000,
  • "currency": "usd",
  • "description": "my_order_xyz",
  • "metadata": { },
  • "payment_method": {
    },
  • "status": "requires_payment_method",
  • "created_at": "2021-01-01T12:00:00Z",
  • "updated_at": "2021-01-01T12:00:00Z"
}
Get Payments for a Payment Intent
Get information about the payments associated with a payment intent.


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 payments for a payment intent


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