--- title: "Setup Payin Component" method: POST path: "/billing/payment-terminal/payin-config" tags: ["provider", "billing"] --- # Setup Payin Component `POST /billing/payment-terminal/payin-config` ## Request - Base URL: `https://docs.decodahealth.com` (the document declares no server; this is the origin it was published from) - URL: `https://docs.decodahealth.com/billing/payment-terminal/payin-config` - Auth: none declared. Required headers: `TENANT`, `API-KEY` - TypeScript: (a function with typed inputs; its response is checked against the schema) Sets up a payin component for completing a given Transaction. ## Headers - `TENANT` string, required - `API-KEY` string, required ## Request body - PayinConfigCreate - `paymentAmount` integer, nullable - `savePaymentMethod` boolean - `textReceipt` boolean - `paymentMedium` 'POS' | 'VIRTUAL_TERMINAL' | 'PAYMENT_LINK' | 'PAYMENT_PLAN' | 'SUBSCRIPTION' | 'SAVED_PAYMENT_METHOD' | 'MEMBERSHIP' | 'CASH' | 'CHECK' | 'CARE_CREDIT' | 'PATIENT_CREDIT', required: Payment medium types supported by the system. These fall into two categories: 1. Payment Processor Mediums: Require Rainforest/Stripe payin (card processing) 2. External Settlement Mediums: Settled outside the system (cash, check, etc.) - `paymentPlan` PaymentPlanCreateWithoutID: Represents the creation of a payment plan without an ID. This model defines the structure for creating a new payment plan, including details about the initial payment, associated charge, frequency of payments, number of installments, and the amount for each installment. - `initialAmount` integer, required: The initial payment amount for the payment plan - `chargeIds` string[], required: The IDs of the associated charges - `frequency` 'WEEKLY' | 'BIWEEKLY' | 'MONTHLY', required - `installments` integer, required: The number of installment payments - `installmentAmount` integer, required: The amount of each installment payment - `locationId` string, nullable: The ID of the associated location - `startDate` string, date, nullable: Optional start date for the first payment (only allowed for $0 down payment plans) - `isSurcharged` boolean - `locationId` string, nullable - `creatorId` string, nullable - `membershipId` string, nullable - `membershipStartDate` string, date-time, nullable - `soldByProviderId` string, nullable - `merchantAccountId` string, nullable - `charges` ChargeSummaryInput[], required - `id` string, nullable: A unique identifier for the charge. Auto-generated if not provided. - `patientId` string, required: Identifier of the patient being charged. - `patient` PatientSummary - `id` string, required: The unique identifier for the user. - `firstName` string, nullable: The user's first name. - `lastName` string, nullable: The user's last name. - `phoneNumber` string, nullable: The user's phone number. - `email` string, nullable: The user's email address. - `type` 'PROVIDER' | 'PATIENT' | 'ASSISTANT', required - `locationId` string, nullable: The location of the user. - `externalId` string, nullable: The user's external identifier if available. - `address` string, nullable: The user's primary address. - `addressLineTwo` string, nullable: Additional address information. - `city` string, nullable: The city of the user's address. - `state` string, nullable: The state of the user's address. - `zipCode` string, nullable: The postal code of the user's address. - `country` string, nullable: The country of the user's address. - `createdDate` string, date-time, required: The date and time when the user was created. - `addressValid` boolean, nullable: Whether the user's address is valid. - `meta` object, nullable: Any additional metadata about the user relevant to your system. - `isArchived` boolean, nullable: Whether the user is archived. - `primaryLocationId` string, nullable: The primary location of the user. - `gender` string, nullable: The gender of the patient. - `dateOfBirth` string, date, nullable: The date of birth of the patient. - `patientMedications` string[], nullable: List of patient's self-reported medications. - `onSchedulingBlacklist` boolean, nullable: Whether the patient is on the scheduling blacklist. - `surchargeDisabled` boolean, nullable: Whether surcharges are disabled for this patient. - `tags` PatientTagSummary[], nullable: List of patient tags - `id` string, required: Unique identifier for the patient tag - `name` string, required: Name of the patient tag - `emoji` string, nullable: Emoji associated with the tag - `color` string, nullable: Color code for the tag (hex format) - `isActive` boolean, required: Whether the tag is active - `createdDate` string, date-time, required: Date and time when the tag was created - `updatedDate` string, date-time, nullable: Date and time when the tag was last updated - `creditBalance` integer, nullable: Patient's credit balance in cents. - `preferredProviderId` string, nullable: The preferred provider ID for this patient. - `total` integer: Total amount of the charge. - `totalOutstanding` integer, required: Total outstanding amount that is yet to be paid. - `description` string, nullable: Description of the charge. - `status` 'OUTSTANDING' | 'PAID' | 'EXTERNAL_SETTLEMENT' | 'VOID' | 'WRITE_OFF' | 'REFUNDED' | 'CHARGEBACK' | 'PAYMENT_PLAN' | 'COLLECTIONS' - `discountAmount` integer, nullable: Any discount applied to the total outstanding. - `discountPercentage` number, nullable: Percentage of discount applied to the charge. - `externalId` string, nullable: External identifier for the charge, if applicable. - `externalCreatedDate` string, date-time, nullable: The creation date of the charge in your external system, if applicable. - `ruleSetId` string, nullable: Identifier for the `RuleSet` applied to this `Charge`, if any. - `createdDate` string, date-time, nullable: The date when the charge was created. - `creatorId` string, nullable: Identifier of the `Provider` who created the charge (i.e. the Clinician, or relevant Biller). - `items` ChargeItem[]: List of `Items` in the `Charge`. - `id` string, nullable: Unique identifier for the charge item - `itemId` string, nullable: Optional unique identifier for the item - `chargeId` string, required: Identifier of the charge this item is associated with - `name` string, nullable: Name of the item (None for items with associated inventory item) - `description` string, nullable: Description of the item - `quantity` integer, required: Quantity of the item being charged - `discountAmount` integer, nullable: Discount amount for the item - `discountPercentage` number, nullable: Discount percentage for the item - `discountReason` string, nullable: Reason for discount - `price` integer, required: Price of the item in cents - `soldPackageId` string, nullable: Unique identifier for the sold package usage - `bankedQuantity` integer, nullable: Quantity to bank for later use - `bankedItemId` string, nullable: ID of banked item being used (for tracking usage) - `issuedDiscountId` string, nullable: Unique identifier for the specific issued discount instance used - `soldByProviderId` string, nullable: Unique identifier for the provider who sold the item - `taxAmount` integer, nullable: Tax amount for the item in cents - `pricingId` string, nullable: Unique identifier for the pricing for the item - `shipmentIds` string[], nullable: Optional list of shipment IDs to reduce the stock quantity of - `tips` TipDetail[]: List of `Tips` in the `Charge`. - `chargeId` string, required: Charge ID this tip belongs to - `amount` integer, required: Tip amount in cents - `providerId` string, required: Provider ID receiving the tip - `id` string: Unique identifier for the tip - `provider` ProviderTiny - `id` string, required - `firstName` string, required - `lastName` string, nullable - `email` string, nullable - `createdDate` string, date-time, nullable - `locationId` string, nullable: Identifier of the `Location` where the charge was created. - `eventId` string, nullable: Identifier of the `Event` this charge is associated with, if any. - `memberId` string, nullable: Identifier of the `Member` this charge is associated with, if any. - `comment` string, nullable: Any additional comments about the charge. - `meta` object, nullable: Any additional metadata about the charge relevant to your system. - `merchantAccountId` string, nullable: Identifier of the `MerchantAccount` this charge is associated with. ## Response `200` Successful Response - PayinComponentSetupResponse - `sessionKey` string, required - `payinConfigId` string, required - `paymentMethods` PaymentMethodSummary[] - `id` string, required - `patientId` string, nullable, required - `rainforestPaymentMethodId` string, required - `brand` string, nullable, required - `last4` string, nullable, required - `expMonth` integer, nullable, required - `expYear` integer, nullable, required - `accountHolderType` string, nullable, required - `accountNumberLast4` integer, nullable, required - `bankName` string, nullable, required - `routingNumber` integer, nullable, required - `description` string, nullable, required - `type` 'CARD' | 'ACH' | 'APPLE_PAY', required - `isDefault` boolean - `isArchived` boolean - `sandbox` boolean, required ## Other responses - `422`: Validation Error --- [API](https://skmtc.dev/decodahealth/apis/decoda-api.md) - [All operations](https://skmtc.dev/decodahealth/apis/decoda-api/llms.txt) - [OpenAPI document](https://skmtc.dev/decodahealth/apis/decoda-api/revisions/4ab18c80f9e9?raw)