OpenAPI Specification
openapi: 3.1.0
info:
title: Authentication ACH Returns Payins 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: Payins
description: Resources for payin functions.
paths:
/v1/payins:
get:
operationId: list_payins
summary: List payins
description: Query a list of payins given optional search criteria.
parameters:
- in: header
name: Rainforest-Api-Version
schema:
type: string
default: '2024-10-16'
enum:
- '2024-10-16'
- '2023-12-01'
- $ref: '#/paths/~1v1~1device_registrations/post/responses/200/content/application~1json/schema/properties/data/properties/merchant_id'
in: query
- in: query
name: merchant_name
description: Optional merchant name by which to filter.
schema:
type: string
examples:
partial:
value: Merchant
summary: Match a partial merchant name value.
full:
value: Merchant LLC
summary: Match a full merchant name value.
- in: query
name: method_type
description: Payment method type to filter by. Provide parameter multiple times to filter by multiple payment method types.
schema:
description: The type of payment method.
type: string
enum:
- CARD
- APPLE_PAY
- ACH
- PLAID_ACH
- in: query
name: billing_contact_name
description: Optional billing contact name by which to filter.
schema:
type: string
maxLength: 50
minLength: 1
examples:
partial:
value: Doe
summary: Match a partial billing contact name value.
full:
value: John Doe
summary: Match a full billing contact name value.
- name: status
in: query
description: 'One or more payin statuses to filter by. Provide parameter multiple times to filter by multiple payin status types.
`AUTHORIZED` `CANCELED` `CREATED` `FAILED` `IN_REVIEW` `PRESENTING` `PROCESSING` `RETURNED` `SUCCEEDED`'
schema:
type: array
items:
description: The status of the payin.
type: string
enum:
- AUTHORIZED
- CANCELED
- CREATED
- FAILED
- IN_REVIEW
- PRESENTING
- PROCESSING
- RETURNED
- SUCCEEDED
example: PROCESSING
- in: query
name: source
description: 'One or more payin sources to filter by. Provide parameter multiple times to filter by multiple payin sources. '
schema:
type: array
items:
description: The source of the payin. Indicates the integration that created the payin.
type: string
nullable: false
enum:
- API_DIRECT
- API_STORED_PAYMENT_METHOD
- COMPONENT
- DEVICE
- EXTERNAL
- IVR
- TAP_TO_PHONE
- in: query
name: metadata
schema:
type: string
description: "Filter by metadata stored on the entity by passing a map of key-value pairs to filter on. The `key` should be valid JSONPath to a corresponding metadata key.\n\nFor example, an entity created with the following metadata\n```\n\"account\": {\n \"id\": \"acct_123\"\n}\n```\ncould have the following metadata filter to find entities with the metadata account id: \n```\n?metadata[$.account.id]=acct_123\n```"
- in: query
name: created_at.start
description: Created on or after in UTC RFC 3339 format.
schema:
type: string
format: date-time
example: '2022-01-01T12:00:00Z'
- in: query
name: created_at.end
description: Created on or before in UTC RFC 3339 format.
schema:
type: string
format: date-time
example: '2022-01-01T12:00:00Z'
- in: query
name: expected_deposit_date.start
description: Expected to be deposited on or after in UTC RFC 3339 format.
schema:
type: string
format: date
example: '2022-01-01'
- in: query
name: expected_deposit_date.end
description: Expected to be deposited on or before in UTC RFC 3339 format.
schema:
type: string
format: date
example: '2022-01-01'
- name: sort_by
in: query
description: Optional value by which to sort the result set. Default sort by is created_at.
schema:
type: string
enum:
- amount
- billing_contact_name
- created_at
- expected_deposit_date
- merchant_id
- method_type
- payin_id
- status
- in: query
name: sort_order
description: Order in which to return the sorted results; ascending or descending. Default sort order is descending.
schema:
type: string
enum:
- asc
- desc
- in: query
name: limit
schema:
type: number
default: 1000
maximum: 1000
description: The maximum number of results to return.
- in: query
name: start_key
schema:
type: string
description: A key used to indicate the starting point for the next page of results. This value should be set to the last_key returned by the previous paginated request.
- in: query
deprecated: true
name: offset
schema:
type: number
default: 0
minimum: 0
description: 'Offset has been deprecated. Utilize start_key and last_key for pagination.
The offset of the first result to return; zero-based.'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
status:
description: 'Status of the request.
If the request status code is 2XX, then the `status` will be `SUCCESS`. If the request status code is 4XX or 5XX, then the `status` will be `ERROR`.'
type: string
enum:
- SUCCESS
- ERROR
example: SUCCESS
data:
allOf:
- type: object
properties:
total_results:
type: integer
description: Total number of results available. This value will be -1 if the query parameter `omit_total_results` is set to true.
- type: object
properties:
last_key:
name: last_key
schema:
type: string
description: 'Last ID in this result set.
This value can be be used as `start_key` in subsequent paginated requests to retrieve additional results whose IDs are greater than the `last_key` value.'
results:
description: List of payins.
type: array
items:
$ref: '#/paths/~1v1~1payins/post/responses/200/content/application~1json/schema/properties/data'
errors:
description: List of errors, if applicable.
type: array
items:
type: object
description: Details of the error.
properties:
field:
description: The field in the request that had an error, if applicable.
type: string
code:
description: The code describing the error.
type: string
message:
description: The description of the error related to the field.
type: string
example: null
'400':
description: Bad request, check for validation errors.
content:
application/json:
schema:
description: Default response object.
type: object
properties:
status:
$ref: '#/paths/~1v1~1payins/get/responses/200/content/application~1json/schema/properties/status'
data:
description: Generic data object specified per resource, null if there are request errors.
type: object
example: null
nullable: true
readOnly: true
errors:
$ref: '#/paths/~1v1~1payins/get/responses/200/content/application~1json/schema/properties/errors'
example:
status: ERROR
data: null
errors:
- field: string
code: RequestBody
message: Invalid request payload
'401':
description: Authorization missing or invalid.
content:
application/json:
schema:
$ref: '#/paths/~1v1~1payins/get/responses/400/content/application~1json/schema'
example:
status: ERROR
data: null
errors:
- field: string
code: AuthUnauthorized
message: Unauthorized
'403':
description: Authorization insufficient for requested action.
content:
application/json:
schema:
$ref: '#/paths/~1v1~1payins/get/responses/400/content/application~1json/schema'
example:
status: ERROR
data: null
errors:
- field: string
code: AuthForbidden
message: Forbidden
5XX:
description: Unexpected error.
content:
application/json:
schema:
$ref: '#/paths/~1v1~1payins/get/responses/400/content/application~1json/schema'
example:
status: ERROR
data: null
errors:
- field: string
code: string
message: Internal Server Error
tags:
- Payins
post:
operationId: create_payin
summary: Create payin
description: '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:
- $ref: '#/paths/~1v1~1payins/get/parameters/0'
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
method_type:
description: The type of payment method.
type: string
enum:
- CARD
- ACH
card:
description: Card payment method. Required for method_type CARD.
type: object
properties:
card_number:
description: The card number, formatted with no spaces (e.g 0000000000000000).
type: string
example: '4111111111111111'
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
cvc:
description: The card CVC, temporarily available for 5 minutes for payment processing.
type: integer
example: '123'
ach:
description: ACH payment method details. Required for method_type ACH.
type: object
properties:
account_number:
description: The bank account number.
type: string
example: '12345678'
routing_number:
description: The 9-digit routing number.
type: string
example: 091000019
maxLength: 9
minLength: 9
account_type:
description: The account type. Defaulted to CHECKING if omitted.
type: string
example: CHECKING
enum:
- CHECKING
- SAVINGS
account_holder_type:
description: The account holder type.
type: string
example: PERSONAL
enum:
- PERSONAL
- BUSINESS
billing_contact:
$ref: '#/paths/~1v1~1payin_configs/post/requestBody/content/application~1json/schema/properties/billing_contact'
description: 'Billing contact details. The following billing contact fields are **_required_** for payment processing depending on the payment method type:
* Card: `postal_code`
* ACH: `name`
The billing contact fields can also be passed in the payin config.'
required:
- payin_config_id
- method_type
examples:
card:
value:
payin_config_id: cfg_2A4d6U0tMyovzTbVT1ktmRzdRaD
method_type: CARD
card:
card_number: '4111111111111111'
exp_month: 12
exp_year: 2027
cvc: '123'
billing_contact:
name: Jane Smith
address_line_1: 3423 Piedmont Rd
address_line_2: Suite 123
city: Atlanta
state: GA
postal_code: '30305'
country: US
email: janesmith@example.com
phone: '4041234567'
ach:
value:
payin_config_id: cfg_2A4d6U0tMyovzTbVT1ktmRzdRaD
method_type: ACH
ach:
account_number: '12345678'
routing_number: 091000019
account_type: CHECKING
account_holder_type: PERSONAL
billing_contact:
name: Jane Smith
address_line_1: 3423 Piedmont Rd
address_line_2: Suite 123
city: Atlanta
state: GA
postal_code: '30305'
country: US
email: janesmith@example.com
phone: '4041234567'
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
status:
$ref: '#/paths/~1v1~1payins/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~1payins/post/responses/200/content/application~1json/schema/properties/data/properties/threeds_attempt/properties/payin_config_id'
readOnly: true
merchant_id:
$ref: '#/paths/~1v1~1device_registrations/post/requestBody/content/application~1json/schema/properties/merchant_id'
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:
$ref: '#/paths/~1v1~1payin_configs/post/requestBody/content/application~1json/schema/properties/payment_method_config_id'
readOnly: true
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~1refunds~1%7Brefund_id%7D~1void/post/requestBody/content/application~1json/schema/properties/idempotency_key'
billing_type:
description: The merchant billing type.
type: string
enum:
- NET
- GROSS
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~1payins~1%7Bpayin_id%7D~1void_or_refund/post/requestBody/content/application~1json/schema/properties/amount_splits/items/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:
$ref: '#/paths/~1v1~1payins/get/parameters/5/schema/items'
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~1payins~1%7Bpayin_id%7D~1void_or_refund/post/requestBody/content/application~1json/schema/properties/amount_splits/items/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`.
$ref: '#/paths/~1v1~1payment_method_configs/post/requestBody/content/application~1json/schema/properties/platform'
merchant:
description: The minimal representation of the merchant receiving this split. Present when type is `MERCHANT`.
$ref: '#/paths/~1v1~1payin_configs/post/requestBody/content/application~1json/schema/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~1payins~1%7Bpayin_id%7D~1void_or_refund/post/requestBody/content/application~1json/schema/properties/amount_splits/items/properties/currency_code'
example:
total_amount:
amount: 2
currency_code: USD
method_type:
description: The type of payment method.
# --- truncated at 32 KB (74 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/rainforest/refs/heads/main/openapi/rainforest-payins-api-openapi.yml