List returns and notices of change

get

https://test-api.payology.io/returns/api/v1/returns

Get returns for one bank account and a date window. The result is an array. The repository applies the window to return creation time (r.created_at), not to return_date. return_type is a string code: A identifies X9 NSF, while R01 identifies ACH insufficient funds.

This request has no JSON body. Use the path/query examples below.

Request examples

DateWindow

GET /returns/api/v1/returns?oba_token=33333333-3333-4333-8333-333333333333&start_date=2026-09-01&end_date=2026-09-08 HTTP/1.1
Authorization: <PAYOLOGY_API_KEY>
Accept: application/json

Result codes in the response examples

HTTP status and result code are operation-specific. Field-validation messages can include the affected field name.

HTTP	Code	Result	Meaning
400	R0002	Error	Field is not properly formatted
400	R0102	Error	Organization Bank Account token is invalid
400	R0243	Error	Organization associated with the Organization Bank Account is inactive
401	R0999	Error	Authentication token is invalid
403	R0999	Error	Access not allowed
500	R0999	Error	Something went wrong

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Responses

default

Other infrastructure or forwarded downstream response. HTTP status and body must be preserved; do not assume every error has a Payology R-code. No fixed payload is guaranteed.

200Matching returns; an empty array means no returns for the window.

400Invalid fields, selector, or business rule. Consult the individual example code.

401Authentication failed. Some services also use 401 for organization access denial. Gateway bodies can differ.

403Permission or organization access denied; the gateway can reject the request before it reaches the service.

429Gateway throttling or quota. Exact quota, retry headers and deployed body were not verified. This is a platform possibility, not an observed Payology response.

500Unhandled service failure. Gateway configuration/authorizer failures can also return 500.

504Gateway integration timeout or failure. The service may still have committed a create request. This is a platform possibility, not an observed Payology response.