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

# Create payin config

`POST /v1/payin_configs`

## Request

- Base URL: `https://api.sandbox.rainforestpay.com`
- URL: `https://api.sandbox.rainforestpay.com/v1/payin_configs`
- Auth: HTTP bearer

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. When creating or updating a merchant, this must be at least 5 characters. Existing merchants may have shorter values from before this requirement was introduced.
    - `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` AmountSplits (unresolved $ref)
    - `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. When `true`, the billing fee is credited back to the merchant and included in the refund's computed billing fee. 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. 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. Set the top-level rate, rate cap, and fee to define a billing fee regardless of the payment method the end user pays with. Set one or more payment method objects to define separate billing fees for each payment method. See the [dynamic payment billing fees guide](https://docs.rainforestpay.com/docs/dynamic-payment-billing-fees) for additional details on how Rainforest determines the billing fees for the payment.
      - `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)
      - `card` Ach (unresolved $ref)
      - `ach` object: The billing rate and fee to calculate the merchant's billing fee for this specific payment method. This takes precedence and overrides the rate and fee defined by the top-level merchant_billing object and 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.
        - `currency_code` CurrencyCode (unresolved $ref)
      - `validated_ach` Ach (unresolved $ref)
      - `accelerated_ach` Ach (unresolved $ref)
      - `paypal_wallet` Ach (unresolved $ref)
      - `venmo` Ach (unresolved $ref)
      - `paypal_paylater` Ach (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.
    - `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](ref: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](ref: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
    - `device_allow_manual_entry` boolean: Boolean indicating if the cardholder can manually key in their card details when processing a payment on a device, instead of presenting the card.
    - `device_tip_config` object, nullable: Configures a preset tip prompt of percentages or amounts to request a tip when processing a payment on a device. When requesting a tip, the end user will also have the ability to input a custom tip amount on the device. Exactly one of `tip_percentages` or `tip_amounts` must be set. Not supported for separate authorization and capture (`processing_mode` of `AUTHORIZE`). The payment must be authorized and captured in a single request in order to request a tip. Up to 4 presets may be configured, but some devices can only display up to 3 presets. Presets displayed will be in the order they are provided and any beyond the number supported on the device will not be displayed. For example, if tip_percentages is set to [20000, 18000, 15000, 10000] and the device only supports 3 presets, then the device will display 20%, 18%, and 15%.
      - `tip_percentages` integer[]: Preset tip percentages, in percent mille (1 PCM = 0.001%). For example, [20000, 18000, 15000, 10000] will display 20%, 18%, 15%, and 10% on the device.
      - `tip_amounts` integer[]: Preset tip amounts, in minor units. For example, [1000, 500, 200, 100] will display $10.00, $5.00, $2.00, $1.00 on the device.
    - `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/payments.md) - [All operations](https://skmtc.dev/rainforestpay/apis/payments/llms.txt) - [OpenAPI document](https://skmtc.dev/rainforestpay/apis/payments/revisions/9d7d0b1553a8?raw)