JUjustifi
Payments

Create a Payment

Authorize, capture, and charge a payment method. We limit concurrency to 10 concurrent requests per platform. This is due to the nature of the payments API, to reduce rejections, and false positive fraud detection during bulk payment processing.

Payment methods must be tokenized before creating a payment. Tokenize payment methods use the embedded JustiFi Tokenize Payment Method Web Component to securely collect and tokenize card or bank account details.

Once you have a payment method token (e.g. pm_justifi123), pass it in the payment_method.token field to create a payment.

Note: Passing raw card or bank account details directly to this endpoint requires prior approval. Contact JustiFi Customer Success if you have a use case that requires direct PAN submission. At minimum, a completed SAQ (Self-Assessment Questionnaire) is required to allow raw PAN submissions.

Note: If the sub account status is not enabled, 400 will be returned.

post/payments

Request

Headers

Idempotency-Keystring uuid required

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

Authorizationstring required

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

Sub-Accountstring required

the id of the sub account that this request applies to

Request body

amountnumber required

amount to charge in cents

currency'usd' | 'cad' required
capture_strategy'automatic' | 'manual' required

automatic will authorize and capture the payment in the same request; manual will only authorize the payment. An authorized payment will need to be captured in a subsequent capture payment request. If not captured within 7 days the payment will be canceled. Not supported by bank account (ACH) payment methods.

emailstring email

email address to associate with payment method

application_fee_amountinteger

Sets a custom application fee amount that applies to this payment, instead of relying on application fee rates configured at the platform account level (only Platforms may set application_fee_amount). Must be greater than zero.

New integrations should use the fees array instead for granular control over fee types and selective refunds. See Enhanced Fee Management.

Cannot be used together with fees.

CAD Payments: This parameter is not available for CAD payments. Fees for Canadian dollar payments are determined during merchant onboarding and are not configurable via the API. See Canadian Payments for details.

descriptionstring

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

statement_descriptorstring

description of the payment that will be available on the account's bank statement, must have between 5-22 alphanumeric characters and can include dash or underscore

metadataobject

Any useful information you'd like to store alongside this payment.

Testing Disputes: Include dispute_test_spec to create test disputes:

  • expected_result: "won" or "lost" - Final dispute outcome
  • reason: Dispute reason ("fraudulent", "unrecognized", "duplicate", "subscription_canceled", "product_unacceptable", "product_not_received", "processing_error", "credit_not_processed", "general")
  • due_date: Response deadline in YYYY-MM-DD format
  • event_publish_delay_in_seconds: Delay before dispute creation (default: 0)
expeditedboolean nullable

settlement priority of the payment, only applies to ACH payments

Example request

{
  "amount": 10000,
  "currency": "usd",
  "capture_strategy": "automatic",
  "payment_method": {
    "token": "pm_xyz"
  },
  "application_fee_amount": 400,
  "fees": [
    {
      "type": "processing_fee",
      "amount": 350
    },
    {
      "type": "platform_fee",
      "amount": 500
    }
  ],
  "description": "order_xyz",
  "metadata": {}
}

Response

Payment was created successfully

idstring uuid

the object id, also found in the data object

typestring

the object type, or array of objects

page_infounknown

Example response

{
  "id": "prefix_xyz (same as id of data object)",
  "type": "payment",
  "data": {
    "id": "py_xyz",
    "account_id": "acc_xyz",
    "amount": 10000,
    "amount_refundable": 10000,
    "balance": 99850,
    "fee_amount": 150,
    "financial_transaction_id": "ft_123xyz",
    "captured": true,
    "capture_strategy": "automatic",
    "currency": "usd",
    "description": "my_order_xyz",
    "disputes": [],
    "error_code": "credit_card_number_invalid",
    "error_description": "Credit Card Number Invalid (Failed LUHN checksum)",
    "is_test": true,
    "metadata": {},
    "payment_intent_id": "pi_123xyz",
    "checkout_id": "cho_123xyz",
    "payment_method": {
      "card": {
        "id": "pm_123xyz",
        "brand": "Visa",
        "digital_wallet": "apple_pay",
        "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"
    },
    "application_fee_rate_id": "afr_123xyz",
    "fees": [
      {
        "id": "pyfee_abc",
        "type": "processing_fee",
        "amount": 350,
        "currency": "usd",
        "remaining_amount": 350,
        "source_configuration_id": "sfc_abc123",
        "source_fee_type": "processing_ecomm",
        "refund_id": null
      },
      {
        "id": "pyfee_xyz",
        "type": "platform_fee",
        "amount": 500,
        "currency": "usd",
        "remaining_amount": 500,
        "source_configuration_id": "sfc_abc123",
        "source_fee_type": "platform",
        "refund_id": null
      }
    ],
    "payment_mode": "ecom",
    "terminal_id": "trm_123xyz",
    "transaction_hold": {
      "id": "th_123xyz",
      "financial_transaction_id": "ft_123xyz"
    },
    "created_at": "2021-01-01T12:00:00Z",
    "updated_at": "2021-01-01T12:00:00Z"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.