--- title: "Create payin" method: POST path: "/v1/payins" tags: ["Payins"] --- # Create payin `POST /v1/payins` ## Request - Base URL: `https://api.sandbox.rainforestpay.com` - URL: `https://api.sandbox.rainforestpay.com/v1/payins` - Auth: HTTP bearer Create and process a payin with sensitive PCI data using a payin configuration. The merchant status must be `ACTIVE` to create a payin. This endpoint requires Rainforest approval. Platforms that meet all [requirements](doc:send-sensitive-data-via-api#requirements) and are approved by Rainforest can send the full card and bank account numbers to Rainforest via a server-to-serve direct API integration. ## Parameters - `#/paths/~1v1~1payins/get/parameters/0` (unresolved $ref) ## Request body - object - `payin_config_id` string, required: The unique payin config identifier. A payin must be configured prior to this request. See "Create a Payin Config" if a payin configuration has not been created yet. Prefix is "cfg" in production and "sbx_cfg" in sandbox. - `method_type` 'CARD' | 'ACH', required: The type of payment method. - `card` object: Card payment method. Required for method_type CARD. - `card_number` string: The card number, formatted with no spaces (e.g 0000000000000000). - `exp_month` integer: The card expiration month. - `exp_year` integer: The card expiration year, in 4-digits. - `cvc` integer: The card CVC, temporarily available for 5 minutes for payment processing. - `ach` object: ACH payment method details. Required for method_type ACH. - `account_number` string: The bank account number. - `routing_number` string: The 9-digit routing number. - `account_type` 'CHECKING' | 'SAVINGS': The account type. Defaulted to CHECKING if omitted. - `account_holder_type` 'PERSONAL' | 'BUSINESS': The account holder type. - `billing_contact` BillingContact (unresolved $ref) ## Response `200` OK - object - `status` Status (unresolved $ref) - `data` object: The payin details. - `payin_id` PayinId (unresolved $ref) - `payin_config_id` PayinConfigId (unresolved $ref) - `merchant_id` MerchantId (unresolved $ref) - `payment_method_id` string: The unique payment method identifier. Prefix is "mtd" in production and "sbx_mtd" in sandbox. - `payment_method_config_id` PaymentMethodConfigId (unresolved $ref) - `device_registration_id` string: The unique device registration identifier. Prefix is "dvc" in production and "sbx_dvc" in sandbox. - `threeds_attempt_id` string, nullable: The unique threeds attempt identifier. Prefix is "tds" in production and "sbx_tds" in sandbox. - `idempotency_key` IdempotencyKey (unresolved $ref) - `billing_type` 'NET' | 'GROSS': The merchant billing type. - `amount` integer: The amount of the payin, in minor units. For example, 1000 is 10.00 USD. - `currency_code` CurrencyCode (unresolved $ref) - `is_partially_authorized` boolean: Boolean indicating if payin was authorized for a partial amount. - `authorized_amount` integer: The amount of the payin that was authorized, in minor units. For example, 1000 is 10.00 USD. - `captured_amount` integer: The amount of the payin that was captured, in minor units. For example, 1000 is 10.00 USD. - `tip_amount` integer: The amount of the payin that was collected as a tip from processing on a device, in minor units. For example, 1000 is 10.00 USD. - `refundable_amount` integer: The amount of the payin that can still be refunded, in minor units. For example, 1000 is 10.00 USD. - `non_refundable_reason_code` 'VOIDED' | 'FAILED' | 'FULLY_REFUNDED' | 'HAS_CHARGEBACKS' | 'HAS_ACH_RETURN' | 'IN_ACH_RETURN_WINDOW' | 'IN_SETTLEMENT_WINDOW', nullable: Why the payin is nonrefundable. Provided when refundable_amount is 0. - `status` Items (unresolved $ref) - `refusal_code` string: The code explaining the reason for the refusal if the payin or refund failed to process. This value will be `null` if the payin or refund succeeded. - `refusal_desc` string: The description explaining the reason for the refusal if the payin or refund failed to process. This will be a human-readable value that may be presented to the end user. This value will be `null` if the payin or refund succeeded. - `detailed_refusal_code` string: The detailed refusal code that could be more descriptive than the refusal code. It may take up to 5 minutes for the detailed refusal code to populate after the payment fails. This value will be `null` if the payment succeeded. - `detailed_refusal_desc` string: The description explaining the detailed refusal reason if the payin or refund failed to process. This will be a human-readable value that may be presented to the end user. This value will be `null` if the payment succeeded. - `auth_code` string: The authorization code if the payin was approved. - `avs_result_code` string: The address verification service result code. - `cvc_result_code` string: The card verification code result code. - `amount_splits` object[]: Represents how the payin amount was allocated to the originating merchant, the platform and one or more other merchants. A `PLATFORM` split defines a platform fee on the payin. A `MERCHANT` split allocates a portion of the payin to the specified merchant. Any remaining amount not specified by the amount splits was allocated to the originating merchant associated with the payin. - `amount` integer, required: The amount allocated, 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. `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`. The unique identifier of the merchant receiving this split. The merchant must be fully onboarded and in an ACTIVE status. Must not match the merchant_id of the originating merchant on the payin. Must not be duplicated within the same amount_splits array. Not valid when object type is `PLATFORM`. Prefix: mid in production, sbx_mid in sandbox. - `platform` 0 (unresolved $ref) - `merchant` Merchant (unresolved $ref) - `merchant_fees` object: The amount of the payin billed to the merchant. - `total_amount` object: The total amount of fees billed to the merchant. - `amount` integer: The amount, in minor units. For example, 1000 is 10.00 USD. - `currency_code` CurrencyCode (unresolved $ref) - `applied_billing` object: The rate, rate cap, and fee applied to calculate the billing fee, along with the source that determined the billing fee. - `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. - `fee` integer: Fee, in minor units. For example, 1000 is 10.00 USD. - `currency_code` CurrencyCode (unresolved $ref) - `source` 'BILLING_PROFILE' | 'MERCHANT_BILLING' | 'MERCHANT_BILLING_METHOD': The source that determined the billing fee. `BILLING_PROFILE` - the merchant's billing profile `MERCHANT_BILLING` - the top-level rate, rate cap, and fee in the payin config's merchant billing object `MERCHANT_BILLING_METHOD` - the payment method object in the payin config's merchant billing object - `merchant_billing_method_type` 'card' | 'ach' | 'validated_ach' | 'accelerated_ach' | 'paypal_wallet' | 'venmo' | 'paypal_paylater': The payment method object in the payin config's merchant billing object utilized to calculate the billing fee. Applicable when the source is `MERCHANT_BILLING_METHOD`. - `method_type` 'CARD' | 'APPLE_PAY' | 'GOOGLE_PAY' | 'ACH' | 'PLAID_ACH' | 'PAYPAL_WALLET' | 'VENMO' | 'PAYPAL_PAYLATER': The type of payment method. - `card` object: Card payment method details. - `type` 'CREDIT' | 'DEBIT' | 'PREPAID': Card type. - `brand` Brand (unresolved $ref) - `brand_desc` 'Visa' | 'Mastercard' | 'Discover' | 'American Express' | 'Other': Card brand in a friendly language. - `last_4` string: Last 4 digits of the card number. - `exp_month` ExpMonth (unresolved $ref) - `exp_year` ExpYear (unresolved $ref) - `country` Country (unresolved $ref) - `is_business` IsBusiness (unresolved $ref) - `is_healthcare` IsHealthcare (unresolved $ref) - `apple_pay` object: Apple Pay payment method details. - `type` Type (unresolved $ref) - `brand` Brand (unresolved $ref) - `brand_desc` BrandDesc (unresolved $ref) - `description` string: A human-readable description of the payment method provided by Apple. - `google_pay` object: Google Pay payment method details. - `type` Type (unresolved $ref) - `brand` Brand (unresolved $ref) - `brand_desc` BrandDesc (unresolved $ref) - `description` string: A human-readable description of the payment method provided by Google. - `ach` object: ACH payment method details. - `account_number_last_4` string: The last 4 digits of the account number. - `routing_number` RoutingNumber (unresolved $ref) - `bank_name` string: The bank name. - `account_type` AccountType (unresolved $ref) - `account_holder_type` AccountHolderType (unresolved $ref) - `plaid_ach` PlaidAch (unresolved $ref) - `paypal_wallet` object: PayPal Wallet payment method. Required for method_type PAYPAL_WALLET. - `email` string: The email address of the PayPal user - `venmo` object: Venmo payment method. Required for method_type VENMO. - `email` string: The email address of the Venmo user - `paypal_paylater` object: PayPal PayLater payment method. Required for method_type PAYPAL_PAYLATER. - `email` string: The email address of the PayPal user - `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) - `device_data` object: Device data - `application_identifier` string: Identifies the application that the device used on the payin or payment method as described in ISO/IEC 7816-5. - `application_label` string: The human-readable name associated with the application identifier according to ISO/IEC 7816-5. - `application_preferred_name` string: The human-readable name associated with the application identifier in the cardholder’s local language. - `transaction_status_information` string: A collection of indicators that the device will set to show what processing steps have been performed on the current transaction (e.g. Cardholder Verification, Data Authentication). - `application_pan_sequence_number` string: Identifies and differentiates cards with the same PAN. - `entry_type` 'TAPPED' | 'SWIPED' | 'DIPPED' | 'KEYED' | 'INVALID' | 'UNKNOWN': The entry type used on the device. - `verification_type` 'SIGNATURE' | 'OFFLINE_PIN' | 'ONLINE_PIN' | 'OFFLINE_PIN_SIGNATURE' | 'NONE': The verification type for verifying the user processing the payment is the cardholder. Types: * `SIGNATURE` - The user provided a signature on the device. * `OFFLINE_PIN` - The user entered their pin on the device and it was verified by the EMV chip card. * `ONLINE_PIN` - The user entered their pin on the device and it was verified by the card issuer. * `OFFLINE_PIN_SIGNATURE` - The user entered their PIN and provided a signature on the device. * `NONE` - The user could not be verified. - `signature` string: A signature image, formatted as a base64 encoded data URI - `method_metadata` MethodMetadata (unresolved $ref) - `metadata` Schema (unresolved $ref) - `refunds` Data[] (unresolved $ref) - `has_refunds` boolean: Boolean indicating that the payin has one or more refunds created. - `chargebacks` Data[] (unresolved $ref) - `has_chargebacks` boolean: Boolean indicating that the payin has one or more chargebacks created. - `ach_return` Data (unresolved $ref) - `has_ach_return` boolean: Boolean indicating that the payin has an ACH return. - `payin_config` object: Payin config details. - `payin_config_id` PayinConfigId (unresolved $ref) - `processing_mode` ProcessingMode (unresolved $ref) - `amount` integer: The total amount requested for processing, in minor units. For example, 1000 is 10.00 USD. - `currency_code` CurrencyCode (unresolved $ref) - `amount_splits` AmountSplits (unresolved $ref) - `threeds_attempt` object, nullable: 3DS attempt details. - `threeds_attempt_id` string: The unique threeds attempt identifier. Prefix is "tds" in production and "sbx_tds" in sandbox. - `merchant_id` MerchantId (unresolved $ref) - `payin_config_id` string: The unique payin config identifier. Prefix is "cfg" in production and "sbx_cfg" in sandbox. - `status` 'CREATED' | 'FINGERPRINTED' | 'SUCCEEDED' | 'CHALLENGED' | 'FAILED': The status of the threeds attempt. - `failed_reason_code` '3DS_ATTEMPT_TIMED_OUT' | 'CARD_NOT_ENROLLED' | 'CHALLENGE_FAILED' | 'MERCHANT_NOT_BOARDED' | 'UNEXPECTED_ERROR' | 'UNSUPPORTED_PAYMENT_DATA', nullable: The code explaining the reason for the 3DS request failure. This value will be set if the 3DS attempt status is `FAILED`. - `failed_reason_desc` string, nullable: The description explaining the reason for the payin's 3DS request failure. This will be a human-readable value that may be presented to the end user. This value will be `null` if the 3DS request succeeded or if not applicable. - `created_at` CreatedAt (unresolved $ref) - `updated_at` CreatedAt (unresolved $ref) - `fingerprinted_at` CreatedAt (unresolved $ref) - `challenged_at` CreatedAt (unresolved $ref) - `succeeded_at` CreatedAt (unresolved $ref) - `failed_at` CreatedAt (unresolved $ref) - `expected_deposit_date` string, date: Date the funds are expected to be available in a deposit. - `source` Items (unresolved $ref) - `source_desc` string: The description of the source of the payin. This will be a human-readable value that may be presented to the end user. - `created_at` string, date-time: Date and time payin was created at in UTC RFC 3339 format. - `updated_at` string, date-time: Date and time payin was last updated at in UTC RFC 3339 format. - `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)