{"openapi":"3.0.2","x-explorer-enabled":false,"x-samples-enabled":false,"info":{"title":"External Trans API","description":"# Overview\n\nExternal Trans API is a webhook that allows clients to participate in\nthe decisioning for:\n* Approving/denying bill payments\n* Approving/denying ACH debits\n\nIt's similar to Auth API, but for bill pay and ACH debits.\n\nWhen the SoFi Tech Solutions backoffice system processes a bill payment or ACH debit\n(i.e., an ACH transaction that will pull funds from an account),\nit can call out to a client system, giving the client the opportunity to\napprove or deny the transaction. We will provide information\nabout the transaction (the amount, the biller for bill payments, the\nrecipient for ACH debits, etc.), and the client responds with a response\ncode that indicates how it wants the transaction to be processed (approved,\ndenied, denied with a specific ACH return code, retry the webhook\nlater, etc.).\n\nThere are currently two endpoints (paths): One for billpay, and one for\nACH debit. The entire endpoint is configurable. For example, a client\ncould use these endpoints:\n* `https://client.example.com/path/foo/achdebit`\n* `https://client.example.com/bar/billpay`\n\nwhile another client could use these endpoints:\n* `https://www.bar.com/ach`\n* `https://www.bar.com/v2/bp`\n\n# Security\n\nClients should use HTTPS for their External Trans API webhook to ensure\nfundamental security is in place.\n\nThe client's product can be configured so that SoFi Tech Solutions will use a JSON\nWeb Token (JWT) for authenticating with the client's webhook. (While it\nis optional, it is strongly encouraged that clients configure their\nproduct to use JWT.) A shared secret will be used for encoding and decoding\nthe token. The payload will have the following claims:\n* `iat` - Issued At\n* `exp` - Expiration TIme\n* `iss` - \"galileo\"\n\nThe token will be created using the following Python code:\n```python\nimport jwt\nfrom datetime import datetime, timedelta\npayload = {\n    'exp': datetime.utcnow() + timedelta(seconds=5),\n    'iat': datetime.utcnow(),\n    'iss': 'galileo'\n}\ntoken = jwt.encode(payload, secret, algorithm='HS256')\n```\n\nwhere `secret` is the shared secret.\n\n**The token will be placed in the body of the request, in the `jwt`\nproperty.** (This will likely change in a future release.)\n\n## Security Example\n\nHere is the value for `exp = 1534274886` and `iat = 1534274881` that\nwould appear in the request body:\n```json\n{\n    ...\n    \"jwt\": \"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnYWxpbGVvIiwiaWF0IjoxNTM0Mjc0ODgxLCJleHAiOjE1MzQyNzQ4ODZ9.1xUk4iNFGWLo01MyJUHXRlyrNlzwPvDMSXpN38TrblU\"\n}\n```\n\n# Retries\n\nNote: This feature requires enabling a product configuration setting.\n\nIf SoFi Tech Solutions reaches a timeout when invoking a client's webhook, or the client\nresponds with response code `\"99\"`, we will retry the webhook later,\na configurable number of times, using exponential backoff.\n\n# API Versioning\n\nFor both endpoints, an API version is sent in the request body. This is\ncurrently hard-coded to `\"1.0\"`.\n","version":"1.0.0"},"servers":[{"url":"https://client.domain.com","description":"Clients will provide the URLs they would like to use for External Trans API. The URLs should use HTTPS."}],"paths":{"/achdebit":{"post":{"summary":"ACH Debit Webhook","description":"Use the ACH Debit webhook to approve or deny incoming ACH debits. Use the `response_code`  field in the response to communicate your decision to SoFi Tech Solutions. \n","operationId":"webhook_ach_debit_post","tags":["ACH Debit Webhook"],"parameters":[{"name":"X-Request-ID","in":"header","description":"A unique identifier for the HTTP request.","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"description":"Information about the ACH debit transaction.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account_number":{"type":"string","minLength":12,"maxLength":12,"description":"<a href=\"doc:about-accounts#prn\" target=\"_blank\">Payment reference number</a> for the account Example: `\"999200002022\"`","example":"999200002022"},"account_status":{"type":"string","description":"Account status code. See the possible values in the <a href=\"ref:api-reference-account-statuses\" target=\"_blank\">Account Statuses</a> enumeration.\n\nExample: `\"N\"`"},"transaction_amount":{"type":"number","format":"float","description":"The amount of the ACH debit. Example: `150.00`","example":150},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"The three-digit currency code for the amounts. ISO 4217 Numeric Currency Code. 3 digits. Example: `\"840\"`","example":"840"},"available_funds":{"type":"number","format":"float","description":"Amount of funds available to the account holder. Example: `500.00`","example":500},"ach_name":{"type":"string","maxLength":30,"description":"Name of the ACH account holder. Example: `\"John Doe\"`","example":"John Doe"},"recipient":{"type":"string","maxLength":35,"description":"Name of the <<glossary:ODFI>> that receives the debited funds. Example: `\"Widgets Incorporated\"`","example":"Widgets Incorporated"},"sec":{"type":"string","minLength":3,"maxLength":3,"description":"The three-character <a href=\"ref:api-reference-sec-codes-requirements-for-ach\" target=\"_blank\">standard entry class (SEC)</a> code. Example: `\"WEB\"`","example":"WEB"},"is_international":{"type":"boolean","description":"Whether this is an international transaction. Example: `\"false\"`","example":false},"description":{"type":"string","maxLength":10,"description":"Description from the ACH header. Example: `\"PAYROLL   \"`","example":"PAYROLL  "},"timestamp":{"type":"string","description":"Timestamp when this webhook message was sent. Format is `<timestamp><timezone>` where `timestamp` is `YYYYmmdd:HHMMSS` and `timezone` is always `MST`. Example: `\"20270315:121504MST\"`","example":"20270315:121504MST"},"transaction_id":{"type":"integer","maxLength":18,"description":"The unique identifier of the ACH transaction. Also called `ach_trans_id` and `deposit_transaction_id` in the Program API. Example: `32146803`","example":32146803},"version":{"type":"string","maxLength":16,"description":"The version of this API. Hard-coded to `\"1.0\"`.","enum":["1.0"]},"batch_header":{"type":"string","maxLength":94,"description":"The batch header for the <<glossary:Nacha file>> that contained this ACH debit entry detail record. Example: `\"5225WIDGET INC      DISCRETIONARY DATA  1234567890POSPAYROLL   2027052003070642123456780000001\"`","example":"5225WIDGET INC      DISCRETIONARY DATA  1234567890POSPAYROLL   2027052003070642123456780000001"},"source_trace":{"type":"string","maxLength":20,"description":"The source trace number from the ACH record. Example: `\"123456781234567\"`","example":"123456781234567"},"jwt":{"type":"string","description":"The JSON web token (JWT) that authenticates the HTTP request from SoFi Tech Solutions. See the <a href=\"ref:api-reference-external-trans-api-about-external-trans-api-security\" target=\"_blank\">security overview</a> for more information and an example.","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnYWxpbGVvIiwiaWF0IjoxNTM0Mjc0ODgxLCJleHAiOjE1MzQyNzQ4ODZ9.1xUk4iNFGWLo01MyJUHXRlyrNlzwPvDMSXpN38TrblU"}},"required":["account_number","account_status","transaction_amount","currency","available_funds","ach_name","recipient","sec","is_international","description","timestamp","transaction_id","version","batch_header","source_trace"]}}}},"responses":{"200":{"description":"Your decision and instructions for SoFi Tech Solutions.","content":{"application/json":{"schema":{"type":"object","properties":{"response_code":{"type":"string","description":"Response code indicating how to process the ACH debit transaction. Possible response codes:\n\n- `00` &mdash; Approve\n\n- `R01` &mdash; Reject; Insufficient funds\n\n- `R07` &mdash; Reject; Authorization revoked by customer\n\n- `R08` &mdash; Reject; Payment stopped\n\n- `R10` &mdash; Reject; Customer advises not authorized\n\n- `R16` &mdash; Reject; Bank account frozen\n\n- `R20` &mdash; Reject; Non-payment bank account\n\n- `98` &mdash; System Error; Reject and do not retry\n\n- `99` &mdash; System Error; Retry later\n\n\nYou can use `99` to tell SoFi Tech Solutions to retry later if your product is configured for retries. \n"}},"required":["response_code"]},"examples":{"response":{"value":"{\n  \"response_code\": \"00\"\n}\n"}}}}}}}},"/billpay":{"post":{"summary":"Billpay Webhook","description":"Use the Billpay webhook to approve or deny billpay transactions. Use the `response_code`  field in the response to communicate your decision to SoFi Tech Solutions.\n","operationId":"webhook_billpay_post","tags":["Billpay Webhook"],"parameters":[{"name":"X-Request-ID","in":"header","description":"A unique identifier for the HTTP request.","schema":{"type":"string","format":"uuid"},"required":true}],"requestBody":{"description":"Information about the billpay transaction.","required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"account":{"type":"object","properties":{"xid":{"type":"integer","description":"Internal system account ID. Example: `5398373`.","example":5398373},"prn":{"type":"string","minLength":12,"maxLength":12,"description":"<a href=\"doc:about-accounts#prn\" target=\"_blank\">Payment reference number</a> for the account. Example: `\"999200002022\"`.","example":"999200002022"},"account_status":{"type":"string","description":"Account status code. See the possible values in the <a href=\"ref:api-reference-account-statuses\" target=\"_blank\">Account Statuses</a> enumeration.\n\nExample: `\"N\"`"}},"required":["xid","prn","account_status"]},"amounts":{"type":"object","properties":{"trans_amount":{"type":"number","format":"float","description":"Amount of the billpay transaction. Example: `150.00`","example":150},"available_funds":{"type":"number","format":"float","description":"Amount of funds available to the account holder for this transaction. Example: `500.00`","example":500},"currency":{"type":"string","minLength":3,"maxLength":3,"description":"The currency code for `trans_amount` and `fee_amount`. ISO 4217 numeric currency code. 3 digits. Example: `\"840\"`","example":"840"},"fee_amount":{"type":"number","format":"float","description":"Amount of fees for this transaction, if any. Example: `3.00`","example":3}},"required":["trans_amount","available_funds","currency","fee_amount"]},"timestamp":{"type":"string","description":"Timestamp when this webhook message was sent. Format is `<timestamp><timezone>` where `timestamp` is `YYYYmmdd:HHMMSS` and `timezone` is always `MST`. Example: `\"20200315:121504MST\"`","example":"20200315:121504MST"},"billpay_trans_id":{"type":"integer","description":"Unique system-generated billpay transaction ID. Example: `559386`.","example":559386},"biller":{"type":"object","description":"Biller information. The information sent in this object is configurable (or the `biller` object can be skipped or not sent entirely).","properties":{"biller_id":{"type":"integer","description":"Registry ID for the biller. Example: `1024930`","example":1024930},"nickname":{"type":"string","nullable":true,"description":"Account holder's nickname for the biller. Nullable. Example: `\"Questar\"`.","example":"Questar"},"name":{"type":"string","nullable":true,"description":"Registry name for the biller. Nullable. Example: `\"Questar Gas\"`.","example":"Questar Gas"},"type":{"type":"string","description":"Biller type. Possible values:\n- `R` &mdash; Electronic\n- `Z` &mdash; Paper","enum":["R","Z"]},"address_1":{"type":"string","nullable":true,"description":"Biller address line 1. Nullable. Example: `\"123 Las Vegas Blvd.\"`","example":"123 Las Vegas Blvd."},"address_2":{"type":"string","nullable":true,"description":"Biller address line 2. Nullable. Example: `\"Suite 300\"`","example":"Suite 300"},"city":{"type":"string","nullable":true,"description":"Biller city. Nullable. Example: `\"Las Vegas\"`","example":"Las Vegas"},"state_province":{"type":"string","nullable":true,"description":"Biller state or province. Nullable. Example: `\"NV\"`","example":"NV"},"postal_code":{"type":"string","nullable":true,"description":"Biller postal code. Nullable. Example: `\"88901\"`","example":"88901"},"phone":{"type":"string","nullable":true,"description":"Biller phone number. Nullable. Example: `\"7021231234\"`","example":"7021231234"}}},"version":{"type":"string","description":"The version of this API. Hard-coded to `\"1.0\"`.","enum":["1.0"]},"jwt":{"type":"string","description":"The JSON web token (JWT) that authenticates the HTTP request from SoFi Tech Solutions. See the <a href=\"ref:api-reference-external-trans-api-about-external-trans-api-security\" target=\"_blank\">security overview</a> for more information and an example.","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJnYWxpbGVvIiwiaWF0IjoxNTM0Mjc0ODgxLCJleHAiOjE1MzQyNzQ4ODZ9.1xUk4iNFGWLo01MyJUHXRlyrNlzwPvDMSXpN38TrblU"}},"required":["account","amounts","timestamp","billpay_trans_id","version"]}}}},"responses":{"200":{"description":"Your decision and instructions for SoFi Tech Solutions.","content":{"application/json":{"schema":{"type":"object","properties":{"response_code":{"type":"string","description":"Response code indicating how to process the billpay transaction. Possible response codes:\n\n* `00` &mdash; Approve\n\n* `01` &mdash; Reject; Insufficient funds\n\n* `98` &mdash; System Error; Reject and do not retry\n\n* `99` &mdash; System Error; Retry later\n\n\nYou can use `99` to tell SoFi Tech Solutions to retry later if your product is configured for retries. \n"}},"required":["response_code"]},"examples":{"response":{"value":"{\n  \"response_code\": \"00\"\n}\n"}}}}}}}}},"x-readme":{"proxy-enabled":true}}