---
title: "Complete a Checkout"
method: POST
path: "/checkouts/{id}/complete"
tags: ["Checkouts"]
---

# Complete a Checkout

`POST /checkouts/{id}/complete`

## Request

- Base URL: `https://api.justifi.ai/v1`
- URL: `https://api.justifi.ai/v1/checkouts/{id}/complete`
- Auth: none declared. Required headers: `Idempotency-Key`, `Authorization`
- TypeScript: <https://skmtc.dev/justifi/apis/justifi-api-documentation/docs/checkouts/:id/complete/post.ts> (a function with typed inputs; its response is checked against the schema)

Use to complete a checkout and capture a payment, requires an idempotency key for payment processing

## Headers

- `Idempotency-Key` string, uuid, required
- `Authorization` string, required

## Request body

- object
  - `payment_token` string, required: Payment Method token which you want to use to complete the payment
  - `payment_mode` 'ecom' | 'bnpl' | 'card_present' | 'apple_pay': The mode in which the checkout is being completed. If not provided, defaults to `ecom`

## Response `201`

Checkout was created successfully

- object
  - `id` string, uuid: the object id, also found in the data object
  - `type` string: the object type, or array of objects
  - `data` object: the attributes for the object
    - `id` string: unique checkout completion id
    - `payment_mode` 'ecom' | 'bnpl' | 'card_present'
    - `payment_token` string: the payment method token used to process the payment, only for ecom payments
    - `status` 'succeeded' | 'failed' | 'processing': the status of the completion, only succeeded or failed
    - `payment_status` 'succeeded' | 'failed' | 'pending' | 'canceled' | 'skipped': depending upon payment mode, the status of the payment API call, bnpl transaction, or card reader transaction.
    - `payment_error_code` string: when payment fails, related error code
    - `payment_error_description` string: when payment fails, related error description
    - `payment_response` object: payment object if completion attempt was successful, error object if not successful
      - `id` string: unique payment id, same as id in data object
      - `type` string: the object type
      - `data` CardPayment
        - `id` string: unique payment id
        - `account_id` string, uuid
        - `amount` number: payment amount in cents
        - `amount_disputed` number: sum of open or lost disputes for this payment, in cents
        - `amount_refunded` number: sum of refunds for this payment, in cents
        - `amount_refundable` number: amount of this payment currently able to be refunded, in cents
        - `balance` number: sum of debits and credits for this payment, in cents (reflects the amount this account has earned from this payment). Compiled and calculated value, eventually consistent. To see all changes affecting the payment's balance call [Get Balance Transactions](#operation/GetPaymentBalanceTransactions)
        - `fee_amount` number: sum of fees for this payment
        - `financial_transaction_id` string: associated financial transaction id
        - `captured` boolean: whether or not this payment is captured
        - `capture_strategy` 'automatic' | 'manual'
        - `currency` 'usd' | 'cad'
        - `description` string: your meaningful description of the payment (e.g. an order number or other value from your system)
        - `disputed` boolean: whether or not this payment has any open or lost disputes
        - `disputes` unknown[]: list of associated disputes
          - unknown
        - `error_code` string: error code if the payment fails
        - `error_description` string: text description of the error code
        - `is_test` boolean: whether or not this payment was made using the test account
        - `metadata` object: any useful information you'd like to store alongside this payment
        - `payment_intent_id` string: unique id of associated payment intent
        - `checkout_id` string: unique id of associated checkout
        - `payment_method` CardPaymentMethod
          - `card` Card
            - `id` string, uuid: unique card id
            - `acct_last_four` string: last 4 digits of the card number
            - `brand` string: card brand or bank name
            - `digital_wallet` 'apple_pay' | 'google_pay' | 'null', nullable: which digital wallet provider the card is tied to
            - `name` string, nullable: card or account holder name
            - `token` string: same value as unique card id; can be saved and used to process multiple payments with the same card
            - `month` string: expiration date month
            - `year` string: expiration date year
            - `metadata` object, nullable: any useful information you'd like to store alongside this card
            - `created_at` string, date-time
            - `updated_at` string, date-time
            - `address_line1_check` 'fail' | 'pass' | 'unavailable' | 'unchecked': Result of the address line 1 verification check. `pass` — matches the cardholder's address on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no address was provided for verification.
            - `address_postal_code_check` 'fail' | 'pass' | 'unavailable' | 'unchecked': Result of the postal code verification check. `pass` — matches the cardholder's postal code on file; `fail` — does not match; `unavailable` — verification could not be performed; `unchecked` — no postal code was provided for verification.
          - `customer_id` string, nullable: customer_id is a deprecated field. Please use our payment method groups instead.
          - `signature` string, nullable: signature that uniquely identifies a credit card or bank account across payment methods
          - `account_id` string, nullable: account id associated with payment method
        - `application_fee` ApplicationFee
          - `id` string, uuid: unique application fee id
          - `amount` number: application fee amount, in cents
          - `currency` 'usd' | 'cad'
          - `created_at` string, date-time
          - `updated_at` string, date-time
        - `application_fee_rate_id` string: unique id of application fee rate applied to this payment, if any
        - `fees` FeeResponse[]: Array of fee objects showing the fees charged on this payment with their remaining refundable amounts. Populated whether the fees were provided via the `fees` array in the payment request or calculated automatically (for example, from a Standard Fee Configuration, or the `processing_fee` on a CAD payment). **Note:** This array is empty in the Create Payment response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee objects (with `id`, `remaining_amount`, and `currency`), or poll with a subsequent Get Payment request. See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation.
          - `id` string: Unique identifier for this fee. Present when fetching a payment.
          - `type` 'processing_fee' | 'platform_fee' | 'refund_processing_fee', required: The type of fee: - `processing_fee`: Fees related to payment processing costs - `platform_fee`: Fees for your platform's services - `refund_processing_fee`: A processing fee charged when a refund is processed. Currently applies to CAD payments only.
          - `amount` integer, required: Fee amount in cents
          - `currency` 'usd' | 'cad': Currency of the fee amount. Present when fetching a payment.
          - `remaining_amount` integer: Amount still available for refund in cents. Updates after each partial refund. Present when fetching a payment.
          - `source_configuration_id` string, nullable: The public ID of the Standard Fee Configuration used to calculate this fee. Null when the fee was explicitly provided in the payment request rather than auto-calculated.
          - `source_fee_type` string, nullable: The fee type from the Standard Fee Configuration that generated this fee (e.g., `processing_ecomm`, `amex_brand_ecomm`, `platform`). Null when the fee was explicitly provided in the payment request.
          - `refund_id` string, nullable: The public ID of the refund this fee is associated with. Populated for `refund_processing_fee` fees (currently CAD payments only); null for all other fees. Present when fetching a payment.
        - `refunded` boolean: whether or not this payment has any refunds
        - `status` 'pending' | 'authorized' | 'canceled' | 'succeeded' | 'failed' | 'partially_refunded' | 'fully_refunded' | 'disputed': status of the payment
        - `payment_mode` 'ecom' | 'ach' | 'card_present'
        - `terminal_id` string: id of terminal used to process the card payment, if any
        - `transaction_hold` object: present when the payment has been flagged for review and held from payouts
          - `id` string: unique transaction hold id
          - `financial_transaction_id` string, uuid: financial transaction id the transaction hold is associated to
        - `expedited` boolean, nullable: settlement priority of the payment, only applies to ACH payments
        - `created_at` string, date-time
        - `updated_at` string, date-time
      - `page_info` unknown
    - `checkout_id` string, uuid: id of the checkout for this completion
    - `additional_transactions` unknown
    - `checkout` Checkout
      - `id` string, uuid: unique checkout id
      - `account_id` string, uuid: id of the account associated with the checkout
      - `platform_account_id` string, uuid: id of the platform account associated with the checkout
      - `payment_intent_id` string, uuid: id of the payment intent associated with the checkout
      - `payment_amount` number: the amount charged in cents
      - `payment_currency` 'USD' | 'CAD'
      - `payment_description` string: your custom description of the payment if passed in the `payment` property during checkout creation, otherwise "Checkout [checkout id]"
      - `payment_methods` unknown[]: if `payment_method_group_id` was provided, list of payment methods contained in that payment method group
        - unknown
      - `payment_method_group_id` string, uuid: id of payment method group used for checkout, if provided
      - `status` 'created' | 'completed' | 'attempted' | 'expired': status of the checkout
      - `mode` 'test' | 'live': mode of the checkout
      - `successful_payment_id` string, uuid: payment id, if this checkout was paid for successfully
      - `statement_descriptor` string: description of the payment that will be available on the account's bank statement
      - `metadata` object
      - `application_fees` object: **Deprecated**: Use the `fees` object instead for granular control over fee types and selective refunds. **New integrations** should use `payment.fees` instead for selective refund support. See [Enhanced Fee Management](#section/Enhanced-Fee-Management).
        - `card` object
          - `amount` unknown
        - `bank_account` object
          - `amount` unknown
      - `payment_settings` object: payment configuration information for the checkout
      - `payment` object: data passed to the `payment` property during checkout creation, or null
        - `description` string: your meaningful description of the payment (e.g. an order number or other value from your system)
        - `metadata` object: any useful custom information stored alongside this payment
        - `expedited` boolean: settlement priority of the payment, defaults to false
        - `fees` Fee[]: Array of fee objects specifying the fees to be applied when the checkout is completed. See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for full documentation.
          - `type` 'processing_fee' | 'platform_fee', required: The type of fee: - `processing_fee`: Fees related to payment processing costs - `platform_fee`: Fees for your platform's services
          - `amount` integer, required: Fee amount in cents
      - `created_at` string, date-time
      - `updated_at` string, date-time
      - `completions` CheckoutCompletionAttempt[]: list of checkout completion attempts, if any
        - `id` string: unique checkout completion id
        - `payment_mode` 'ecom' | 'bnpl' | 'card_present'
        - `payment_token` string: the payment method token used to process the payment, only for ecom payments
        - `status` 'succeeded' | 'failed' | 'processing': the status of the completion, only succeeded or failed
        - `payment_status` 'succeeded' | 'failed' | 'pending' | 'canceled' | 'skipped': depending upon payment mode, the status of the payment API call, bnpl transaction, or card reader transaction.
        - `payment_error_code` string: when payment fails, related error code
        - `payment_error_description` string: when payment fails, related error description
        - `payment_response` object: payment object if completion attempt was successful, error object if not successful
          - `id` string: unique payment id, same as id in data object
          - `type` string: the object type
          - `data` CardPayment
            - `id` string: unique payment id
            - `account_id` string, uuid
            - `amount` number: payment amount in cents
            - `amount_disputed` number: sum of open or lost disputes for this payment, in cents
            - `amount_refunded` number: sum of refunds for this payment, in cents
            - `amount_refundable` number: amount of this payment currently able to be refunded, in cents
            - `balance` number: sum of debits and credits for this payment, in cents (reflects the amount this account has earned from this payment). Compiled and calculated value, eventually consistent. To see all changes affecting the payment's balance call [Get Balance Transactions](#operation/GetPaymentBalanceTransactions)
            - `fee_amount` number: sum of fees for this payment
            - `financial_transaction_id` string: associated financial transaction id
            - `captured` boolean: whether or not this payment is captured
            - `capture_strategy` 'automatic' | 'manual'
            - `currency` 'usd' | 'cad'
            - `description` string: your meaningful description of the payment (e.g. an order number or other value from your system)
            - `disputed` boolean: whether or not this payment has any open or lost disputes
            - `disputes` unknown[]: list of associated disputes
              - …
            - `error_code` string: error code if the payment fails
            - `error_description` string: text description of the error code
            - `is_test` boolean: whether or not this payment was made using the test account
            - `metadata` object: any useful information you'd like to store alongside this payment
            - `payment_intent_id` string: unique id of associated payment intent
            - `checkout_id` string: unique id of associated checkout
            - `payment_method` CardPaymentMethod
              - …
            - `application_fee` ApplicationFee
              - …
            - `application_fee_rate_id` string: unique id of application fee rate applied to this payment, if any
            - `fees` FeeResponse[]: Array of fee objects showing the fees charged on this payment with their remaining refundable amounts. Populated whether the fees were provided via the `fees` array in the payment request or calculated automatically (for example, from a Standard Fee Configuration, or the `processing_fee` on a CAD payment). **Note:** This array is empty in the Create Payment response. Fees are processed asynchronously — subscribe to payment webhook events (recommended) to receive the full fee objects (with `id`, `remaining_amount`, and `currency`), or poll with a subsequent Get Payment request. See [Enhanced Fee Management](https://docs.justifi.tech/api-spec#section/Enhanced-Fee-Management) for full documentation.
              - …
            - `refunded` boolean: whether or not this payment has any refunds
            - `status` 'pending' | 'authorized' | 'canceled' | 'succeeded' | 'failed' | 'partially_refunded' | 'fully_refunded' | 'disputed': status of the payment
            - `payment_mode` 'ecom' | 'ach' | 'card_present'
            - `terminal_id` string: id of terminal used to process the card payment, if any
            - `transaction_hold` object: present when the payment has been flagged for review and held from payouts
              - …
            - `expedited` boolean, nullable: settlement priority of the payment, only applies to ACH payments
            - `created_at` string, date-time
            - `updated_at` string, date-time
          - `page_info` unknown
        - `checkout_id` string, uuid: id of the checkout for this completion
        - `additional_transactions` unknown
        - `payment_id` string, uuid: id of the payment associated with this checkout, when successful
        - `payment_method_id` string, uuid: id of the payment method associated with this checkout, when successful
        - `terminal_id` string, uuid: id of the terminal used for this checkout, when mode is card present
        - `created_at` string, date-time
        - `updated_at` string, date-time
    - `payment_id` string, uuid: id of the payment associated with this checkout, when successful
    - `payment_method_id` string, uuid: id of the payment associated with this checkout, when successful
    - `terminal_id` string, uuid: id of the terminal used for this checkout, when mode is card present
    - `created_at` string, date-time
    - `updated_at` string, date-time
  - `page_info` unknown

---

[API](https://skmtc.dev/justifi/apis/justifi-api-documentation.md) - [All operations](https://skmtc.dev/justifi/apis/justifi-api-documentation/llms.txt) - [OpenAPI document](https://skmtc.dev/justifi/apis/justifi-api-documentation/revisions/dd9f3fed7e46?raw)