---
title: "Create payin config"
method: POST
path: "/v1/payin_configs"
tags: ["Payin Configs"]
---

# Create payin config

`POST /v1/payin_configs`

Create the configuration for a payin request. The configuration contains basic information about the payin such as the merchant, idempotency key, payin amount, currency, and optional information such as billing contact, level 2 and 3, and metadata. If the billing contact is provided in the payin config, then the web component will not prompt for this data. These fields include country and postal code for a CARD payment method and name for an ACH payment method. This allows a payin to be set up before collecting the sensitive payin details (i.e the card number) via the web component. The merchant status must be `ACTIVE` to create a payin config.

## Parameters

- `#/paths/~1v1~1payins/get/parameters/0` — unresolved $ref

## Request body

- Data — unresolved $ref

## Response `200`

OK

- object
  - `status` Status — unresolved $ref
  - `data` object
    - `payin_config_id` PayinConfigId — unresolved $ref
    - `payment_method_config_id` string — The unique payment method config identifier. Prefix is "pmc" in production and "sbx_pmc" in sandbox.
    - `merchant_id` MerchantId — unresolved $ref
    - `merchant` object
      - `id` MerchantId — unresolved $ref
      - `name` string — The unique identifier for the merchant business name.
      - `dba_name` string — The merchant’s public-facing name. This may be the same as the legal name if the merchant does not operate under a different name.
    - `idempotency_key` IdempotencyKey — unresolved $ref
    - `amount` integer — The total amount allowed to process, in minor units. For example, 1000 is 10.00 USD.
    - `currency_code` CurrencyCode — unresolved $ref
    - `amount_splits` object[] — Represents how the payin should be allocated between the originating merchant, the platform, and one or more other merchants.<br/><br/> A `PLATFORM` split defines a platform fee on the payin. A maximum of one `PLATFORM` split is permitted per payin.<br/><br/> A `MERCHANT` split allocates a portion of the payin to the specified merchant. Multiple `MERCHANT` splits are permitted. Each `MERCHANT` split must specify a unique merchant_id.<br/><br/> Any remaining amount not specified by the amount splits will be allocated to the originating merchant associated with the payin.<br/><br/> If no amount splits are provided, the total amount will be allocated to the originating merchant.<br/><br/> The amount split is defined as a rate and amount. The split is calculated based on the authorized amount of the payin.<br/><br/> For example, to assess a platform fee of 1% + $5.00, specify 1000 in the rate and 500 in the amount. Be careful to account for any processing fees that will be netted before computing amount splits.
      - `rate` integer — The amount split defined as a rate, in percent mille (1 PCM = 0.001%). The amount split will be calculated on the authorized amount of the payin. For example, 3000 is 3%.
      - `rate_cap` integer — The amount split rate cap, in minor units. Used to cap the rate to a specified amount. For example, 1000 is 10.00 USD. The following validation must be met: If the rate is greater than 0%, then the rate_cap must be greater than $0. For example, to bill a rate of 1% up to $100 set the value to 10000. If the rate is 0%, then the rate_cap must be $0.
      - `amount` integer, required — The amount split, in minor units. For example, 1000 is 10.00 USD.
      - `currency_code` CurrencyCode, required — unresolved $ref
      - `type` 'PLATFORM' | 'MERCHANT', required — The type of receiver for this split.<br/><br/> `PLATFORM` allocates the split amount to the platform. `MERCHANT` allocates the split amount to the merchant specified by merchant_id.
      - `merchant_id` string — Required when type is `MERCHANT`.<br/><br/> The unique identifier of the merchant receiving this split. The merchant status must be ACTIVE.<br/><br/> The following constraints must be met: - Cannot match the merchant_id of the originating merchant on the payin. - Cannot be duplicated within the same amount_splits array. - Not valid when type is `PLATFORM`.<br/><br/> Prefix is mid in production and sbx_mid in sandbox.
      - `amount_split_reversal_config` object — Controls whether this amount split is reversed on a refund for the full amount or an ACH return. When not provided, both attributes default to false.
        - `on_full_refund` boolean — Determines whether this amount split is reversed when a refund for the full amount is processed on this payin.<br/><br/> When `true`, the receiver's allocation is pulled back on the refund. When `false`, the receiver retains their allocation and the originating merchant absorbs this amount of the refund.<br/><br/> This configuration only applies to full refunds. For partial refunds, amount_splits on the refund request can be provided to specify the reversal amounts.
        - `on_ach_return` boolean — Determines whether this amount split is reversed when an ACH return is processed on this payin.<br/><br/> When `true`, the receiver's allocation is pulled back on the ACH return. When `false`, the receiver retains their allocation and the originating merchant absorbs this amount of the ACH return.
    - `billing_fees_reversal_config` object — Controls whether the billing fees for this payin are returned to the originating merchant on a refund for the full amount or an ACH return. When not provided, both attributes default to the merchant's configuration.
      - `on_full_refund` boolean — Determines whether the billing fees for this payin are returned to the merchant when a refund for the full amount is processed.<br/><br/> When `true`, the billing fee is credited back to the merchant and included in the refund's computed billing fee.<br/><br/> This field can also be defined on the refund request and will take precedence over the configuration defined on this payin config.
      - `on_ach_return` boolean — Determines whether the billing fees for this payin are returned to the merchant when an ACH return is processed.<br/><br/> When `true`, the billing fee is credited back to the merchant and included in the ACH return's computed billing fee.
    - `merchant_billing` object — The billing rate and fee to calculate the merchant's billing fee on the authorized amount of the payin. If set, then this rate and fee will be used to determine the billing fee for the payin and will override the merchant's billing profile.
      - `rate` integer — Rate, in percent mille (1 PCM = 0.001%). For example, 3000 is 3%.
      - `rate_cap` integer — Rate cap, in minor units. Used to cap the rate to a specified amount. For example, 1000 is 10.00 USD. The following validation must be met: - If the `rate` is greater than 0%, then the `rate_cap` must be greater than $0. For example, to bill a rate of 1% up to $100 set the value to `10000`. - If the `rate` is 0%, then the `rate_cap` must be $0.
      - `fee` integer — Fee, in minor units. For example, 1000 is 10.00 USD. The fee can be up to $10, regardless of the amount of the payin. However, if the fee is greater than $10, then the fee cannot be greater than the `amount` field. Valid requests: - Fee of $10 on a $5 payin. - Fee of $11 on a $20 payin. Invalid requests: - Fee of $11 on a $5 payin.
      - `currency_code` CurrencyCode — unresolved $ref
    - `allow_bin_lookup` boolean — Boolean indicating if BIN data is returned when a user is inputting the card number into the Payment Component.
    - `allow_partial_authorization` boolean — Boolean indicating if partial amount can be authorized on a card payment, if supported by the issuing bank.
    - `billing_contact` object — Billing contact details.
      - `name` string — First and last name.
      - `address_line_1` string — First line of street address.
      - `address_line_2` string — Second line of street address, if required.
      - `city` string — City for address.
      - `state` string — State, province, or region for address.
      - `postal_code` string — Postal code or ZIP code for address.
      - `country` string — 2-digit country code. Find country codes here: https://www.iso.org/obp
      - `email` string — Email address.
      - `phone` string — Phone number, including extension.
    - `shipping_address` object
      - `name` string — Recipient's first and last name.
      - `address_line_1` AddressLine1 — unresolved $ref
      - `address_line_2` AddressLine2 — unresolved $ref
      - `city` City — unresolved $ref
      - `state` State — unresolved $ref
      - `postal_code` PostalCode — unresolved $ref
      - `country` Country — unresolved $ref
    - `risk_data` object — Platform payment data that provides additional context to the risk review of the payin.
      - `external_ref` string — Platform identifier for the payin, such as an invoice ID or order ID.
      - `end_user_ref` string — Platform identifier for the end user processing the payin with the merchant, such as an account ID.
    - `level_2_3` object — Level 2 and Level 3 data is submitted with a business or commercial card to provide additional benefit to the cardholder through enhanced payin information, and benefits the merchant with lower interchange rates.
      - `tax_amount` integer — The sales tax included in the total payin amount associated with the item(s) being purchased, in minor units. For example, 1000 is 10.00 USD.
      - `shipping_amount` integer — The freight or shipping amount included in the total payin amount, in minor units. For example, 1000 is 10.00 USD.
      - `order_number` string — The purchase order number.
      - `shipping_country` string — The 2-digit country code for the delivery address of the item(s) being purchased. Find country codes here: https://www.iso.org/obp
      - `shipping_postal_code` string — Postal code or ZIP code for the delivery address of the item(s) being purchased. This field can be identical to the `shipping_from_postal_code` if the customer is present and takes immediate possession of the item(s).
      - `shipping_from_postal_code` string — Postal code or ZIP code of the address the item(s) being purchased are shipped from.
      - `commodity_code` string — The commodity code of the item(s) being purchased.
      - `line_items` object[] — The details on the item(s) being purchased.
        - `product_code` string — The merchant defined product code of the item being purchased.
        - `commodity_code` string — The commodity code of the item being purchased.
        - `description` string — The description of the item being purchased.
        - `unit_amount` integer — The amount of the item being purchased, in minor units. Defaults to 0. For example, 1000 is 10.00 USD.
        - `unit_of_measure` string — A unit of measure as used in international trade, such as each, gallons, feet, etc. Defaults to EACH.
        - `quantity` integer — The quantity of the item.
        - `total_amount` integer — The total amount of the item being purchased, in minor units. Defaults to (unit_amount x quantity) - discount_amount, rounded to the nearest penny. For example, 1000 is 10.00 USD.
        - `tax_amount` integer — The sales tax on the item being purchased, in minor units. Defaults to 0. For example, 1000 is 10.00 USD.
        - `tax_rate` integer — The percentage representing the value-added tax applied, in per cent mille. Defaults to 0. For example, 1000 is 1%.
        - `discount_amount` integer — The discount on the item being purchased, in minor units. Defaults to 0. For example, 1000 is 10.00 USD.
        - `discount_rate` integer — The percentage representing the discount applied, in per cent mille. Defaults to 0. For example 1000 is 1%.
    - `metadata` Schema — unresolved $ref
    - `method_metadata` object — Valid JSON key-value object specified by the platform to store additional information on the payment method. Keys are queryable in list endpoints. Do not use the metadata field to store sensitive or confidential data. Metadata must be less than 8 KB in size.
    - `processing_mode` 'AUTHORIZE' | 'AUTHORIZE_AND_CAPTURE' — Determines how to process the payin when [creating the payin](https://docs.rainforestpay.com/reference/create_payin) via the Payment Component or the API. Options: * `AUTHORIZE` - Only authorize the payin, separating the authorization and capture of funds. Authorize will place a hold on the funds and the payin must be [captured](https://docs.rainforestpay.com/reference/capture_payin) in a separate request. * `AUTHORIZE_AND_CAPTURE` - Authorize and capture the payin in a single request (default).
    - `threeds_mode` 'NONE' | 'ATTEMPT' — Determines how 3D Secure authentication should be run on this payment to verify that the customer initiating the payment is actually the cardholder. 3D Secure is only available on credit card payments via the Rainforest payment component. This mode is ignored if the payment is made by ACH, or when charging a stored payment method. Options: * `NONE` - 3D Secure will not be run (default). * `ATTEMPT`- The payment component will attempt to run 3D Secure. If 3D Secure is not available or fails, the payment will process without 3D Secure verification.
    - `device_signature_mode` 'NONE' | 'ATTEMPT' — Determines if a signature should be collected when processing a payment on a device Options: * `NONE` - Signature will not be collected * `ATTEMPT` - Only prompt for a signature on devices that support the signature capability
    - `ach_balance_check_mode` 'NONE' | 'ATTEMPT' — ACH Balance Check is in beta: please contact your Customer Success contact for more information. Determines if the balance of the account will be checked when processing a Validated ACH payin. If the balance does not cover the amount of the payin, the payin will fail with the refusal reason of insufficient funds. Options: * `NONE` - Account balance will not be checked * `ATTEMPT` - Attempt to check the account balance is sufficient to process the payin
    - `payin` object, nullable — The minimal representation of the payin successfully processed with the payin config, if applicable. If no payin has been successfully processed with the payin config, `payin` will be `null`.
      - `payin_id` PayinId — unresolved $ref
  - `errors` Errors — unresolved $ref

## Other responses

- `400` — unresolved $ref
- `401` — unresolved $ref
- `403` — unresolved $ref
- `5XX` — unresolved $ref

---

[API](https://skmtc.dev/rainforestpay/apis/authentication.md) · [All operations](https://skmtc.dev/rainforestpay/apis/authentication/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/rainforestpay/authentication/revisions/529a0dab0f90/schema)