API Reference
Start typing to search…

Create payin config

post
https://api.sandbox.rainforestpay.com/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.

Body Params
string
required

The unique merchant identifier.

Prefix is "mid" in production and "sbx_mid" in sandbox.

merchant
object
string
required
length between 1 and 255

A unique identifier provided by the platform. This key will be used to detect subsequent retries of the same request. Subsequent requests with the same key will return the result of the first request, regardless if the first request succeeded or failed. This identifier should be generated by the platform and can be max 255 characters.

integer
required
≥ 1

The total amount allowed to process, in minor units.

For example, 1000 is 10.00 USD.

string
enum
required
length between 3 and 3

Three-letter ISO currency code, in uppercase. Currently, only USD is supported.

Allowed:
amount_splits
array of objects
length between 0 and 1

Represents how the payin should be split between the merchant and the platform.

An amount split can be used to define a platform fee on the payin by specifying a PLATFORM amount split. Any remaining amount not specified by the amount split will be allocated to the merchant whose merchant_id is associated with the payin.

If no amount splits are provided, the total amount will be allocated to the merchant whose merchant_id is associated with the payin.

The amount split is defined as a rate and amount and calculated based on the authorized amount of the payin.

For example, to assess a platform fee of 1% + $5.00, you would 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.

amount_splits
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.

boolean
Defaults to false

Boolean indicating if BIN data is returned when a user is inputting the card number into the Payment Component.

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.

shipping_address
object
risk_data
object

Platform payment data that provides additional context to the risk review of the payin.

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.

metadata
object

Valid JSON key-value object specified by the platform to store additional information. 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.

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.

string
enum
Defaults to AUTHORIZE_AND_CAPTURE

Determines how to process the payin when creating the 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 in a separate request.
  • AUTHORIZE_AND_CAPTURE - Authorize and capture the payin in a single request (default).
Allowed:
string
enum
Defaults to NONE

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.
Allowed:
string
enum
Defaults to NONE

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
Allowed:
string
enum
Defaults to NONE

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
Allowed:
Headers
string
enum
Defaults to 2024-10-16
Allowed:
Responses

Updated 7 months ago

Language
Credentials
Bearer
APIKey
URL
Response 
Click Try It! to start a request and see the response here! Or choose an example:
application/json
Updated 7 months ago