Afinis Reporting ACH Return (RET) API

{"swagger":"2.0","info":{"version":"1.0.3","title":"RET (Reporting ACH Return Payments) API","description":"Allow Originators and payment providers to share ACH return payment data to support fraud/risk mitigation.","contact":{"email":"info@afinis.org","url":"https://www.afinis.org"}},"host":"api.afinis.org","basePath":"/payments/ach/v1","securityDefinitions":{"APIKeyQueryParam":{"type":"apiKey","in":"query","name":"apikey"}},"consumes":["application/json"],"produces":["application/json"],"schemes":["https"],"paths":{"/ret":{"post":{"operationId":"Reporting ACH Return Payments","tags":["Reporting ACH Return Payments"],"description":"Alert the network of ACH users about problematic ACH payments to help mitigate the risk of suspected bad actors perpetuating fraud against other ACH users","consumes":["application/json"],"produces":["application/json"],"parameters":[{"in":"body","name":"Reporting ACH Return Payments","required":true,"schema":{"type":"object","required":["originatorName","originatorAgentName","receiverName","receiverAgent","receiverAccount","endToEndIdentification","requestedExecutionDate","settlementDate","localInstrument","amount","returnReason","purpose"],"properties":{"originatorName":{"type":"string","minLength":1,"maxLength":70,"example":"John Edison"},"originatorAgentName":{"type":"string","minLength":1,"maxLength":70,"example":"Hank's Bank, the Think Tank at Mont Blanc"},"receiverName":{"type":"string","minLength":1,"maxLength":70,"example":"Jane Edison"},"receiverAgent":{"$ref":"#/definitions/agent"},"receiverAccount":{"$ref":"#/definitions/account"},"endToEndIdentification":{"description":"Unique identification assigned by the initiating party to unambiguously identify the transaction.","type":"string","example":"ABC13609-15-18","minLength":1,"maxLength":35},"requestedExecutionDate":{"description":"Date at which the initiating party requests the clearing agent to process the payment.","type":"string","example":"2023-02-24","minLength":10,"maxLength":10},"settlementDate":{"description":"Indicates the date of settlement of the underlying.","example":"2023-02-24","type":"string","minLength":10,"maxLength":10},"localInstrument":{"type":"string","example":"WEB","minLength":3,"maxLength":3,"enum":["ARC","BOC","CCD","CIE","CTX","IAT","MTE","POP","POS","PPD","RCK","SHR","TEL","WEB","XCK"]},"amount":{"description":"Amount of money to be moved between the debtor and creditor, before deduction of charges, expressed in the currency as ordered by the initiating party","type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","format":"float","example":1.01,"maxLength":11},"currency":{"type":"string","example":"USD","minLength":3,"maxLength":3}}},"returnReason":{"type":"string","example":"R01","minLength":3,"maxLength":3,"description":"Available codes:  *  'R01' - Insufficient funds *  'R02' - Account Closed *  'R03' - No Account / Unable to Locate Account *  'R04' - Invalid Account Number Structure *  'R05' - Unauthorized Debit to Consumer Account Using Corporate SEC Code *  'R06' - Returned per ODFI's Request *  'R07' - Authorization Revoked by Customer *  'R08' - Payment Stopped *  'R09' - Uncollected Funds *  'R10' - Customer Advises Originator is Not Known to Receiver and/or Originator is Not Authorized by Receiver to Debit Receiver’s Account *  'R11' - Customer Advises Entry Not in Accordance with the Terms of the Authorization *  'R12' - Account Sold to Another DFI *  'R14' - Representative Payee Deceased or Unable to Continue in That Capacity *  'R15' - Beneficiary or Account Holder (Other Than a Representative Payee) Deceased *  'R16' - Account Frozen / Entry Returned Per OFAC Instruction *  'R17' - File Record Edit Criteria / Entry with Invalid Account Number Initated Under Questionable Circumstances / Return of Improperly Initiated Reversal *  'R20' - Non-Transaction Account *  'R21' - Invalid Company Identification *  'R22' - Invalid Individual ID Number *  'R23' - Credit Entry Refused by Receiver *  'R29' - Corporate Customer Advises Not Authorized *  'R31' - Permissible Return Entry (CCD and CTX) only *  'R32' - RDFI Non-Settlement *  'R33' - Return of XCK Entry  *  'R34' - Limited Participation DFI *  'R35' - Return of Improper Debit Entry *  'R37' - Source Document Presented for Payment *  'R38' - Stop Payment on Source Document *  'R39' - Improper Source Document / Source Document Presented for Payment  *  'R50' - State Law Affecting RCK Acceptance  *  'R51' - Item related to RCK Entry is Ineligible for RCK Entry is Improper *  'R52' - Stop Payment on Item Related to RCK Entry *  'R53' - Item and RCK Entry Presented for Payment\n","enum":["R01","R02","R03","R04","R05","R06","R07","R08","R09","R10","R11","R12","R14","R15","R16","R17","R20","R21","R22","R23","R29","R31","R32","R33","R34","R35","R37","R38","R39","R50","R51","R52","R53"]},"purpose":{"description":"Underlying reason for the payment transaction.","type":"string","example":"Pay rent","minLength":1,"maxLength":35}}}}],"responses":{"200":{"description":"OK","schema":{"$ref":"#/definitions/response-200"}},"400":{"description":"Bad request","schema":{"$ref":"#/definitions/error-400"}},"401":{"description":"Unauthorized","schema":{"$ref":"#/definitions/error-401"}},"403":{"description":"Access denied, the operation is not allowed"},"404":{"description":"Not Found","schema":{"$ref":"#/definitions/error-404"}},"500":{"description":"Internal Server error","schema":{"$ref":"#/definitions/error-500"}},"503":{"description":"Service unavailable","schema":{"$ref":"#/definitions/error-503"}}},"security":[{"APIKeyQueryParam":[]}]}}},"definitions":{"response-200":{"title":"Response","type":"object","required":["status"],"properties":{"status":{"description":"Specifies the status","type":"string","example":"RCVD","minLength":1,"maxLength":140}}},"agent":{"title":"Agent","description":"Identification of a financial institution.","type":"object","properties":{"clearingSystemIdentification":{"type":"string","example":"USABA","enum":["USABA"],"description":"Specification of a pre-agreed offering between clearing agents or the channel through which the payment instruction is processed: \n * `USABA` - Routing Transit number assigned by the ABA for US financial Institutions. \n"},"memberIdentification":{"type":"string","minLength":1,"maxLength":35,"example":"061103852"}}},"account":{"title":"Account","description":"Details to identify an account","type":"object","required":["identification"],"properties":{"identification":{"description":"Unambiguous identification of the account of the debtor to which a debit entry will be made as a result of the transaction.","type":"string","example":"111010151","minLength":1,"maxLength":17},"type":{"type":"number","example":"22","minLength":2,"maxLength":2,"description":"Specifies the nature, or use of the account. Available codes:  *  '22' - demand credit *  '27' - demand debit  *  '32' - savings credit *  '37' - savings debit *  '42' - general ledger credit *  '47' - general ledger debit *  '52' - loan account credit *  '55' - loan account debit (reversals only)        \n","enum":[22,27,32,37,42,47,52,55]}}},"error-400":{"title":"Error 400 - Bad Request","description":"The request could not be understood or required parameters were missing","type":"object","properties":{"detail":{"description":"error details","type":"array","items":{"$ref":"#/definitions/errorDetails-400"}}}},"errorDetails-400":{"title":"Error 400 - Bad Request - Details","type":"object","properties":{"errorCode":{"description":"A programmatic error code:\n  * `2000` - Invalid JSON structure.\n  * `2001` - '[Field name] is missing or invalid.'\n  * `2002` - Invalid date.\n  * `2003` - Invalid combination of fields submitted. Check the API specification for eligible combinations. \n  * `2004` - '[Field name] cannot be more than [max number] characters.'\n","example":2000,"type":"number","enum":[2000,2001,2002,2003,2004]},"message":{"description":"A human readable description of the problem","example":"Invalid JSON structure.","type":"string"}}},"error-401":{"title":"Error 401 - Unauthorized","description":"Authentication failed or user doesn’t have permissions for requested operation","type":"object","properties":{"detail":{"description":"error details","type":"array","items":{"$ref":"#/definitions/errorDetails-401"}}}},"errorDetails-401":{"title":"Error 401 - Unauthorized - Details","type":"object","properties":{"errorCode":{"example":1000,"type":"number","enum":[1000,1001],"description":"A programmatic error code:\n  * `1000` - API key is missing, invalid or expired. \n  * `1001` - API token is invalid, expired, or account associated with key does not have access to that API.\n"},"message":{"description":"A human readable description of the problem","example":"API key is missing, invalid or expired.","type":"string"}},"required":["errorcode","message"]},"error-404":{"title":"Error 404 - Not Found","description":"Resource was not found.","type":"object","required":["errorCode","message"],"properties":{"errorCode":{"example":404,"type":"number","enum":[404],"description":"A programmatic error code:\n  * `404` - Resource was not found.\n"},"message":{"description":"A human readable description of the problem","example":"Resource was not found.","type":"string"}}},"error-503":{"title":"Error 503 - Service Unavailable","description":"Service is temporarily unavailable","type":"object","required":["errorCode","message"],"properties":{"errorCode":{"example":503,"type":"number","enum":[503],"description":"A programmatic error code:\n  * `503` - Service Unavailable\n"},"message":{"description":"A human readable description of the problem","example":"Service is temporarily unavailable.","type":"string"}}},"error-500":{"title":"Error 500 - Internal server error","type":"object","properties":{"detail":{"description":"error details","type":"array","items":{"$ref":"#/definitions/errorDetails-500"}}}},"errorDetails-500":{"title":"Error 500 - Internal server error - Details","type":"object","properties":{"errorcode":{"description":"A programmatic error code","example":3001,"type":"number"},"message":{"description":"A human readable description of the problem","example":"Internal Server error","type":"string"}},"required":["errorcode","message"]}}}