Rainforest Deposit Methods API
Resources for deposit method functions.
OpenAPI Specification
openapi: 3.1.0
info:
title: Authentication ACH Returns Deposit Methods API
version: 1.0.0
description: This resource is used for authentication actions
contact:
name: Rainforest
email: support@rainforestpay.com
url: https://rainforestpay.com
servers:
- url: https://api.sandbox.rainforestpay.com
description: Sandbox server
- url: https://api.rainforestpay.com
description: Production server
security:
- BearerAuth: []
tags:
- name: Deposit Methods
description: Resources for deposit method functions.
paths:
/v1/deposit_methods/{deposit_method_id}:
get:
operationId: get_deposit_method
summary: Get deposit method
description: Get deposit method details by the deposit method ID.
parameters:
- $ref: '#/paths/~1v1~1deposits/get/parameters/0'
- in: path
required: true
name: deposit_method_id
schema:
type: string
description: "The unique deposit method identifier. \n\nPrefix is \"dmt\" in production and \"sbx_dmt\" in sandbox."
examples:
production:
value: dmt_2DrDRpyAdp5MPUJnrJmoZcMmtfF
sandbox:
value: sbx_dmt_2DrDRpyAdp5MPUJnrJmoZcMmtfF
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
status:
$ref: '#/paths/~1v1~1deposits/get/responses/200/content/application~1json/schema/properties/status'
data:
$ref: '#/paths/~1v1~1deposit_methods/post/responses/200/content/application~1json/schema/properties/data'
errors:
$ref: '#/paths/~1v1~1deposits/get/responses/200/content/application~1json/schema/properties/errors'
'400':
$ref: '#/paths/~1v1~1deposits/get/responses/400'
'401':
$ref: '#/paths/~1v1~1deposits/get/responses/401'
'403':
$ref: '#/paths/~1v1~1deposits/get/responses/403'
'404':
$ref: '#/paths/~1v1~1deposits~1%7Bdeposit_id%7D/get/responses/404'
5XX:
$ref: '#/paths/~1v1~1deposits/get/responses/5XX'
tags:
- Deposit Methods
/v1/deposit_methods/{deposit_method_id}/payin:
post:
operationId: create_deposit_method_payin
summary: Create payin from deposit method
description: 'Create and process a payin using a payin configuration and a deposit method. The merchant status must be ACTIVE to create a payin.
The deposit method details (i.e bank account number and billing contact) will be duplicated to a payment method and a payin will process against the newly created payment method. Metadata, method metadata, and new billing contact details can be defined on the [Payin Config](ref:create_payin_config).
This endpoint requires Rainforest approval.'
parameters:
- in: header
name: Rainforest-Api-Version
schema:
type: string
default: '2024-10-16'
enum:
- '2024-10-16'
- $ref: '#/paths/~1v1~1deposit_methods~1%7Bdeposit_method_id%7D/get/parameters/1'
in: path
requestBody:
content:
application/json:
schema:
type: object
properties:
payin_config_id:
description: '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.'
type: string
example: cfg_2A4d6U0tMyovzTbVT1ktmRzdRaD
required:
- payin_config_id
example:
payin_config_id: cfg_2A4d6U0tMyovzTbVT1ktmRzdRaD
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
status:
$ref: '#/paths/~1v1~1deposits/get/responses/200/content/application~1json/schema/properties/status'
data:
description: The payin details.
type: object
properties:
payin_id:
description: "The unique payin identifier. \n\nPrefix is \"pyi\" in production and \"sbx_pyi\" in sandbox."
type: string
example: pyi_2DrDKk5NIMbpuNGqm109SkpGDHh
payin_config_id:
$ref: '#/paths/~1v1~1deposit_methods~1%7Bdeposit_method_id%7D~1payin/post/responses/200/content/application~1json/schema/properties/data/properties/threeds_attempt/properties/payin_config_id'
readOnly: true
merchant_id:
description: "The unique merchant identifier. \n\nPrefix is \"mid\" in production and \"sbx_mid\" in sandbox."
type: string
example: mid_2DrDFJPutxE5AIbJSopAnqniEbr
payment_method_id:
description: "The unique payment method identifier. \n\nPrefix is \"mtd\" in production and \"sbx_mtd\" in sandbox."
type: string
example: mtd_2DrDRpyAdp5MPUJnrJmoZcMmtfF
payment_method_config_id:
readOnly: true
description: "The unique payment method config identifier. \n\nPrefix is \"pmc\" in production and \"sbx_pmc\" in sandbox."
type: string
example: pmc_2DrDPKzdQypRudLd8DhQKZX27dA
device_registration_id:
description: 'The unique device registration identifier.
Prefix is "dvc" in production and "sbx_dvc" in sandbox.'
type: string
example: dvc_2DrDKk5NIMbpuNGqm109SkpGDHh
threeds_attempt_id:
nullable: true
description: "The unique threeds attempt identifier. \n\nPrefix is \"tds\" in production and \"sbx_tds\" in sandbox."
type: string
example: tds_2DrDFJPutxE5AIbJSopAnqniEbr
idempotency_key:
$ref: '#/paths/~1v1~1deposit_method_configs/post/requestBody/content/application~1json/schema/properties/idempotency_key'
billing_type:
$ref: '#/paths/~1v1~1deposits~1%7Bdeposit_id%7D/get/responses/200/content/application~1json/schema/properties/data/properties/billing_type'
amount:
description: 'The amount of the payin, in minor units.
For example, 1000 is 10.00 USD.'
type: integer
example: 100
currency_code:
$ref: '#/paths/~1v1~1deposits~1%7Bdeposit_id%7D/get/responses/200/content/application~1json/schema/properties/data/properties/currency_code'
is_partially_authorized:
description: Boolean indicating if payin was authorized for a partial amount.
type: boolean
authorized_amount:
description: 'The amount of the payin that was authorized, in minor units.
For example, 1000 is 10.00 USD.'
type: integer
example: 100
readOnly: true
captured_amount:
description: 'The amount of the payin that was captured, in minor units.
For example, 1000 is 10.00 USD.'
type: integer
example: 100
readOnly: true
refundable_amount:
description: 'The amount of the payin that can still be refunded, in minor units.
For example, 1000 is 10.00 USD.'
type: integer
example: 100
readOnly: true
non_refundable_reason_code:
description: Why the payin is nonrefundable. Provided when refundable_amount is 0.
type: string
nullable: true
readOnly: true
enum:
- VOIDED
- FAILED
- FULLY_REFUNDED
- HAS_CHARGEBACKS
- HAS_ACH_RETURN
- IN_ACH_RETURN_WINDOW
- IN_SETTLEMENT_WINDOW
status:
description: The status of the payin.
type: string
enum:
- AUTHORIZED
- CANCELED
- CREATED
- FAILED
- IN_REVIEW
- PRESENTING
- PROCESSING
- RETURNED
- SUCCEEDED
example: PROCESSING
refusal_code:
description: '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.'
type: string
enum:
- null
- AUTHORIZATION_EXPIRED
- DECLINED
- DO_NOT_HONOR
- EXPIRED_CARD
- FRAUDULENT_CARD
- INCORRECT_PAYMENT_INFORMATION
- INSUFFICIENT_FUNDS
- INVALID_CARD_SECURITY_CODE
- INVALID_EXPIRATION_DATE
- INVALID_PIN
- LOST_CARD
- NO_CARD_NUMBER_ON_FILE_WITH_ISSUER
- NO_SUCH_CARD_ISSUER
- OVER_LIMIT
- PROCESSING_ERROR
- RESTRICTED_CARD_TYPE
- RETRY
- RETRY_WITH_THREEDS
- RISK_DECLINE
- STOLEN_CARD
- THREEDS_CHALLENGE_FAILED
- UNEXPECTED_PAYIN_TOKEN
- UNSUPPORTED_CARD_TYPE
readOnly: true
refusal_desc:
description: '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.'
type: string
enum:
- null
- Authorization expired
- Declined
- Do not honor
- Expired card
- Fraudulent card
- Incorrect payment information
- Insufficient funds
- Invalid card security code
- Invalid expiration date
- Invalid PIN
- Lost card
- No card number on file with issuer
- No such card issuer
- Over limit
- Processing error
- Restricted card type
- Retry
- Retry with 3DS
- Risk decline
- Stolen card
- 3DS challenge failed
- Unexpected payin token
- Unsupported card type
readOnly: true
detailed_refusal_code:
description: '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.'
type: string
enum:
- null
- AUTHORIZATION_EXPIRED
- DECLINED
- DO_NOT_HONOR
- EXPIRED_CARD
- FRAUDULENT_CARD
- INCORRECT_PAYMENT_INFORMATION
- INSUFFICIENT_FUNDS
- INVALID_CARD_SECURITY_CODE
- INVALID_EXPIRATION_DATE
- INVALID_PIN
- LOST_CARD
- NO_CARD_NUMBER_ON_FILE_WITH_ISSUER
- NO_SUCH_CARD_ISSUER
- OVER_LIMIT
- PROCESSING_ERROR
- RESTRICTED_CARD_TYPE
- RETRY
- RETRY_WITH_THREEDS
- RISK_DECLINE
- STOLEN_CARD
- THREEDS_CHALLENGE_FAILED
- UNEXPECTED_PAYIN_TOKEN
- UNSUPPORTED_CARD_TYPE
readOnly: true
detailed_refusal_desc:
description: '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.'
type: string
enum:
- null
- Authorization expired
- Declined
- Do not honor
- Expired card
- Fraudulent card
- Incorrect payment information
- Insufficient funds
- Invalid card security code
- Invalid expiration date
- Invalid PIN
- Lost card
- No card number on file with issuer
- No such card issuer
- Over limit
- Processing error
- Restricted card type
- Retry
- Retry with 3DS
- Risk decline
- Stolen card
- 3DS challenge failed
- Unexpected payin token
- Unsupported card type
readOnly: true
auth_code:
description: The authorization code if the payin was approved.
type: string
example: '12345'
avs_result_code:
description: The address verification service result code.
type: string
example: Y
cvc_result_code:
description: The card verification code result code.
type: string
example: M
amount_splits:
description: 'Represents how the payin amount was allocated to the originating merchant, the platform and one or more other merchants.<br/><br/>
A `PLATFORM` split defines a platform fee on the payin.<br/><br/>
A `MERCHANT` split allocates a portion of the payin to the specified merchant.<br/><br/>
Any remaining amount not specified by the amount splits was allocated to the originating merchant associated with the payin.'
type: array
items:
type: object
properties:
amount:
description: 'The amount allocated, in minor units.
For example, 1000 is 10.00 USD.'
type: integer
example: 3
currency_code:
$ref: '#/paths/~1v1~1deposits~1%7Bdeposit_id%7D/get/responses/200/content/application~1json/schema/properties/data/properties/currency_code'
type:
description: '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.'
type: string
enum:
- PLATFORM
- MERCHANT
merchant_id:
description: 'Required when type is `MERCHANT`.<br/><br/>
The unique identifier of the merchant receiving this split. The merchant must be fully onboarded and in an ACTIVE status.<br/><br/>
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`.<br/><br/>
Prefix: mid in production, sbx_mid in sandbox.'
type: string
example: mid_abc123
platform:
description: The minimal representation of the platform receiving this split. Present when type is `PLATFORM`.
type: object
properties:
platform_id:
$ref: '#/paths/~1v1~1deposit_method_configs/post/requestBody/content/application~1json/schema/properties/platform_id'
readOnly: true
name:
readOnly: true
description: The platform name.
type: string
example: Platform Name
merchant:
description: The minimal representation of the merchant receiving this split. Present when type is `MERCHANT`.
$ref: '#/paths/~1v1~1deposits~1%7Bdeposit_id%7D~1activity/get/responses/200/content/application~1json/schema/properties/data/properties/activities/items/properties/merchant'
required:
- amount
- currency_code
- type
example:
- amount: 3
currency_code: USD
type: PLATFORM
merchant_fees:
description: The amount of the payin billed to the merchant.
type: object
properties:
total_amount:
description: The total amount of fees billed to the merchant.
type: object
properties:
amount:
description: 'The amount, in minor units.
For example, 1000 is 10.00 USD.'
type: integer
minimum: 0
currency_code:
$ref: '#/paths/~1v1~1deposits~1%7Bdeposit_id%7D/get/responses/200/content/application~1json/schema/properties/data/properties/currency_code'
example:
total_amount:
amount: 2
currency_code: USD
method_type:
description: The type of payment method.
type: string
enum:
- CARD
- APPLE_PAY
- ACH
- PLAID_ACH
- PAYPAL_WALLET
- VENMO
- PAYPAL_PAYLATER
card:
description: Card payment method details.
type: object
properties:
type:
description: Card type.
type: string
enum:
- CREDIT
- DEBIT
- PREPAID
brand:
description: Card brand.
type: string
example: MASTERCARD
enum:
- VISA
- MASTERCARD
- DISCOVER
- AMERICAN_EXPRESS
- OTHER
brand_desc:
description: Card brand in a friendly language.
type: string
example: Mastercard
enum:
- Visa
- Mastercard
- Discover
- American Express
- Other
last_4:
description: Last 4 digits of the card number.
type: string
example: '4444'
exp_month:
description: The card expiration month.
type: integer
example: 12
maximum: 12
minimum: 1
exp_year:
description: The card expiration year, in 4-digits.
type: integer
example: 2027
maximum: 2099
minimum: 2000
apple_pay:
description: Apple Pay payment method details.
type: object
properties:
type:
$ref: '#/paths/~1v1~1deposit_methods~1%7Bdeposit_method_id%7D~1payin/post/responses/200/content/application~1json/schema/properties/data/properties/card/properties/type'
brand:
$ref: '#/paths/~1v1~1deposit_methods~1%7Bdeposit_method_id%7D~1payin/post/responses/200/content/application~1json/schema/properties/data/properties/card/properties/brand'
brand_desc:
$ref: '#/paths/~1v1~1deposit_methods~1%7Bdeposit_method_id%7D~1payin/post/responses/200/content/application~1json/schema/properties/data/properties/card/properties/brand_desc'
description:
description: A human-readable description of the payment method provided by Apple.
type: string
example: Visa 1234
ach:
description: ACH payment method details.
type: object
properties:
account_number_last_4:
description: The last 4 digits of the account number.
type: string
example: '5678'
routing_number:
$ref: '#/paths/~1v1~1deposit_methods/post/requestBody/content/application~1json/schema/properties/ach/properties/routing_number'
bank_name:
description: The bank name.
type: string
example: Wells Fargo Bank
account_type:
$ref: '#/paths/~1v1~1deposit_methods/post/requestBody/content/application~1json/schema/properties/ach/properties/account_type'
account_holder_type:
$ref: '#/paths/~1v1~1deposit_methods/post/requestBody/content/application~1json/schema/properties/ach/properties/account_holder_type'
plaid_ach:
$ref: '#/paths/~1v1~1deposit_methods/post/responses/200/content/application~1json/schema/properties/data/properties/plaid_ach'
description: ACH payment method details from Plaid.
paypal_wallet:
description: PayPal Wallet payment method. Required for method_type PAYPAL_WALLET.
type: object
properties:
email:
description: The email address of the PayPal user
type: string
example: janesmith@example.com
venmo:
description: Venmo payment method. Required for method_type VENMO.
type: object
properties:
email:
description: The email address of the Venmo user
type: string
example: janesmith@example.com
paypal_paylater:
description: PayPal PayLater payment method. Required for method_type PAYPAL_PAYLATER.
type: object
properties:
email:
description: The email address of the PayPal user
type: string
example: janesmith@example.com
billing_contact:
$ref: '#/paths/~1v1~1deposit_methods/post/requestBody/content/application~1json/schema/properties/billing_contact'
device_data:
description: Device data
type: object
properties:
application_identifier:
description: Identifies the application that the device used on the payin or payment method as described in ISO/IEC 7816-5.
type: string
example: A0000000031010
application_label:
description: The human-readable name associated with the application identifier according to ISO/IEC 7816-5.
type: string
example: VISA CREDIT
application_preferred_name:
description: The human-readable name associated with the application identifier in the cardholder’s local language.
type: string
example: VISA CREDIT
transaction_status_information:
description: 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).
type: string
example: E800
application_pan_sequence_number:
description: Identifies and differentiates cards with the same PAN.
type: string
example: 1
entry_type:
description: The entry type used on the device.
type: string
example: TAPPED
enum:
- TAPPED
- SWIPED
- DIPPED
- KEYED
- INVALID
- UNKNOWN
verification_type:
description: '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.'
type: string
enum:
- SIGNATURE
- OFFLINE_PIN
- ONLINE_PIN
- OFFLINE_PIN_SIGNATURE
- NONE
signature:
description: A signature image, formatted as a base64 encoded data URI
type: string
readOnly: true
method_metadata:
$ref: '#/paths/~1v1~1deposit_method_configs/post/requestBody/content/application~1json/schema/properties/metadata'
metadata:
$ref: '#/paths/~1v1~1deposit_methods/post/responses/200/content/application~1json/schema/properties/data/properties/metadata'
refunds:
type: array
items:
description: The refund details.
type: object
properties:
refund_id:
description: "The unique refund identifier. \n\nPrefix is \"rfd\" in production and \"sbx_rfd\" in sandbox."
type: string
example: rfd_2DrDU206kzAhclm1WrZbuwDERRk
payin_id:
description: "The unique payin identifier that was voided or refunded. \n\nPrefix is \"pyi\" in production and \"sbx_pyi\" in sandbox."
type: string
example: pyi_2DrDKk5NIMbpuNGqm109SkpGDHh
merchant_id:
$ref: '#/paths/~1v1~1deposit_methods~1%7Bdeposit_method_id%7D~1payin/post/responses/200/content/application~1json/schema/properties/data/properties/merchant_id'
billing_type:
$ref: '#/paths/~1v1~1deposits~1%7Bdeposit_id%7D/get/responses/200/content/application~1json/schema/properties/data/properties/billing_type'
amount:
description: 'The amount refunded, in minor units.
For example, 1000 is 10.00 USD.'
type: integer
example: 100
currency_code:
$ref: '#/paths/~1v1~1deposits~1%7Bdeposit_id%7D/get/responses/200/content/application~1json/schema/properties/data/properties/currency_code'
merchant_fees:
description: The refund fee b
# --- truncated at 32 KB (94 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rainforest/refs/heads/main/openapi/rainforest-deposit-methods-api-openapi.yml