Rainforest ACH Returns API
Resources for ACH return functions.
Operations 3
Documentation
APIReference
https://docs.rainforestpay.com/reference
Documentation
https://docs.rainforestpay.com/docs/overview
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/rainforest:rainforest-ach-returns-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Payments ACH Returns API
version: 1.0.0
description: This resource is used for payment 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: ACH Returns
description: Resources for ACH return functions.
paths:
/v1/ach_returns/{ach_return_id}:
get:
operationId: get_ach_return
summary: Get ACH return
description: Get ACH return details by the ach return ID.
parameters:
- $ref: '#/paths/~1v1~1payins/get/parameters/0'
- in: path
required: true
name: ach_return_id
schema:
type: string
description: "The unique ACH return identifier. \n\nPrefix is \"ret\" in production and \"sbx_ret\" in sandbox."
examples:
production:
value: ret_2db5NydANlaU0UJu4EUnGoR24hD
sandbox:
value: sbx_ret_2db5NydANlaU0UJu4EUnGoR24hD
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 ACH return details.
type: object
properties:
ach_return_id:
description: "The unique ACH return identifier. \n\nPrefix is \"ret\" in production and \"sbx_ret\" in sandbox."
type: string
example: ret_2DrDKk5NIMbpuNGqm109SkpGDHh
merchant_id:
$ref: '#/paths/~1v1~1device_registrations/post/requestBody/content/application~1json/schema/properties/merchant_id'
payin_id:
description: 'The unique payin identifier. This will only be set if there is not a refund_id set.
Prefix is "pyi" in production and "sbx_pyi" in sandbox.'
$ref: '#/paths/~1v1~1payins/post/responses/200/content/application~1json/schema/properties/data/properties/payin_id'
refund_id:
description: 'The unique refund identifier. This will only be set if there is not a payin_id set.
Prefix is "rfd_" in production and "sbx_rfd_" in sandbox.'
type: string
example: rfd_2DrDU206kzAhclm1WrZbuwDERRk
status:
description: The status of the ACH return.
type: string
enum:
- SUCCEEDED
example: SUCCEEDED
return_code:
description: The code explaining the reason the ACH payment was returned.
type: string
nullable: false
enum:
- R01
- R02
- R03
- R05
- R06
- R07
- R08
- R09
- R10
- R11
- R12
- R13
- R14
- R15
- R16
- R17
- R18
- R19
- R20
- R21
- R22
- R23
- R24
- R25
- R26
- R27
- R28
- R29
- R30
- R31
- R32
- R33
- R34
- R35
- R36
- R37
- R38
- R39
- R40
- R41
- R42
- R43
- R44
- R45
- R46
- R47
- R50
- R51
- R52
- R53
- R61
- R62
- R67
- R68
- R69
- R70
- R71
- R72
- R73
- R74
- R75
- R76
- R77
- R80
- R81
- R82
- R83
- R84
- R85
readOnly: true
return_desc:
description: The description explaining the reason the ACH payment was returned. This will be a human-readable value that may be presented to the end user.
type: string
nullable: false
examples:
- Insufficient Funds
- Account Closed
- Corporate Customer Advises Not Authorized
readOnly: true
amount:
description: 'The amount captured by the ACH return, 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'
amount_splits:
description: 'Represents how the ACH return amount was allocated between the originating merchant, the platform, and one or more other merchants.<br/><br/>
A `PLATFORM` split defines the amount debited from the platform.<br/><br/>
A `MERCHANT` split defines the amount debited from the specified merchant.<br/><br/>
Any remaining amount not specified by the amount splits was debited from the originating merchant.'
$ref: '#/paths/~1v1~1refunds~1%7Brefund_id%7D/get/responses/200/content/application~1json/schema/properties/data/properties/amount_splits'
merchant_fees:
description: The ACH return fee billed to the merchant
type: object
properties:
total_amount:
description: The total amount of fees billed to the merchant.
type: object
properties:
amount:
$ref: '#/paths/~1v1~1payins/post/responses/200/content/application~1json/schema/properties/data/properties/merchant_fees/properties/total_amount/properties/amount'
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
metadata:
$ref: '#/paths/~1v1~1payins~1%7Bpayin_id%7D~1metadata/patch/requestBody/content/application~1json/schema'
expected_deposit_date:
$ref: '#/paths/~1v1~1payins/post/responses/200/content/application~1json/schema/properties/data/properties/expected_deposit_date'
description: Date the funds are expected to be available in a deposit.
source:
description: The source of the ACH return. Indicates the integration that created the ACH return.
type: string
nullable: false
enum:
- SYSTEM
source_desc:
description: The description of the source of the ACH return. This will be a human-readable value that may be presented to the end user.
type: string
nullable: false
created_at:
description: Date and time ACH return was created at in UTC RFC 3339 format.
type: string
format: date-time
example: '2022-01-01T12:00:00Z'
updated_at:
description: Date and time ACH return was last updated at in UTC RFC 3339 format.
type: string
format: date-time
example: '2022-01-01T12:00:00Z'
errors:
$ref: '#/paths/~1v1~1payins/get/responses/200/content/application~1json/schema/properties/errors'
'400':
$ref: '#/paths/~1v1~1payins/get/responses/400'
'401':
$ref: '#/paths/~1v1~1payins/get/responses/401'
'403':
$ref: '#/paths/~1v1~1payins/get/responses/403'
'404':
$ref: '#/paths/~1v1~1payins~1%7Bpayin_id%7D/get/responses/404'
5XX:
$ref: '#/paths/~1v1~1payins/get/responses/5XX'
tags:
- ACH Returns
/v1/ach_returns/{ach_return_id}/metadata:
patch:
operationId: update_ach_return_metadata
summary: Update ACH return metadata
description: 'The body of the request is the JSON key-value metadata to patch to the ACH return. Do not use the metadata field to store sensitive or confidential data.
Updating metadata will merge with the existing metadata stored on the ACH return by the top-level key. If the same top-level key is passed in this request, it will overwrite the value stored on the ACH return. Only keys included in the payload will be updated. To remove a key, set the key''s value to null. To remove all metadata pass null for the metadata value.
ACH return Metadata must be less than 8 KB in size.
ACH return metadata can only be updated using an API key. This request should not be made by your frontend and should only be done by backend logic that only the platform can complete.'
parameters:
- $ref: '#/paths/~1v1~1payins/get/parameters/0'
- $ref: '#/paths/~1v1~1ach_returns~1%7Bach_return_id%7D/get/parameters/1'
in: path
requestBody:
content:
application/json:
schema:
$ref: '#/paths/~1v1~1payins~1%7Bpayin_id%7D~1metadata/patch/requestBody/content/application~1json/schema'
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
status:
$ref: '#/paths/~1v1~1payins/get/responses/200/content/application~1json/schema/properties/status'
data:
$ref: '#/paths/~1v1~1ach_returns~1%7Bach_return_id%7D/get/responses/200/content/application~1json/schema/properties/data'
errors:
$ref: '#/paths/~1v1~1payins/get/responses/200/content/application~1json/schema/properties/errors'
'400':
$ref: '#/paths/~1v1~1payins/get/responses/400'
'401':
$ref: '#/paths/~1v1~1payins/get/responses/401'
'403':
$ref: '#/paths/~1v1~1payins/get/responses/403'
'404':
$ref: '#/paths/~1v1~1payins~1%7Bpayin_id%7D/get/responses/404'
5XX:
$ref: '#/paths/~1v1~1payins/get/responses/5XX'
tags:
- ACH Returns
/v1/payins/{payin_id}/simulate_ach_return:
post:
operationId: simulate_payin_ach_return
summary: Simulate payin ACH return
description: 'Only available in the Rainforest sandbox environment.
May only be called on an ACH payin in `PROCESSING` or `SUCCEEDED` statuses. An ACH return must not have already been created for the payin.
The expected webhooks will be sent as the payin''s status is advanced and when the ACH return is created.'
parameters:
- $ref: '#/paths/~1v1~1payins/get/parameters/0'
- $ref: '#/paths/~1v1~1payins~1%7Bpayin_id%7D/get/parameters/1'
in: path
responses:
'200':
description: OK
content:
application/json:
schema:
properties:
status:
$ref: '#/paths/~1v1~1payins/get/responses/200/content/application~1json/schema/properties/status'
data:
$ref: '#/paths/~1v1~1payins/post/responses/200/content/application~1json/schema/properties/data'
errors:
$ref: '#/paths/~1v1~1payins/get/responses/200/content/application~1json/schema/properties/errors'
'400':
$ref: '#/paths/~1v1~1payins/get/responses/400'
'401':
$ref: '#/paths/~1v1~1payins/get/responses/401'
'403':
$ref: '#/paths/~1v1~1payins/get/responses/403'
'404':
$ref: '#/paths/~1v1~1payins~1%7Bpayin_id%7D/get/responses/404'
5XX:
$ref: '#/paths/~1v1~1payins/get/responses/5XX'
tags:
- ACH Returns
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: APIKey
x-provenance:
method: harvested
publisher: Rainforest
source: https://docs.rainforestpay.com/openapi/payments.yaml
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)