SoFi Tech Solutions Events API

{"openapi":"3.0.2","x-explorer-enabled":false,"x-samples-enabled":false,"info":{"title":"Events API","description":"Events API (also known as Alerts API) is a collection of webhooks that clients\ncan use to get events from Galileo. For example, when a card authorization happens,\nGalileo can send an event to the client's authorization event webhook with information\nabout the authorization.\n\nEvents are grouped into the following categories:\n* Account Events\n* Authorization Events\n* Settlement Events\n* Transaction Events\n\nEach category is posted to a separate webhook. For example, account events are\nposted to `/AccountEvent`; transaction events are posted to `/Transaction`.\n\nEvents are identified by the `type` field in the request body. For example, when a\ncardholder has successfully completed the enrollment process for a card,\nthe event type will be `app_completed`. Some events have further distinguishing\nfields; for example, for mobile tokenization events, there is a `wallet_type`\nfield that identifes the wallet \"vendor\" (Apple, Google, Samsung, etc.).\n\nGalileo also uses 4-character codes for the events in other systems like the\nCustomer Service Tool (CST). For example, `CAPP` corresponds to the `app_completed`\nAPI type.\n\nEach category has an index (in subsequent pages below) that lists each event along\nwith its description, 4-character code, API type field, and the fields that are sent\nin the event.\n\n[block:callout]\n{\n  \"type\": \"info\",\n  \"title\": \"Note\",\n  \"body\": \"Galileo sends all events asynchronously so that it doesn't block or slow\n    down transaction and backoffice processing. Unlike Auth API and External Trans API,\n    the response that clients send back does not control the outcome of a transaction.\"\n}\n[/block]\n\n\n### Paths and Content Types\n\nClients provide a base URL, hosted by a server in the client's system. Paths\nare relative to that URL.\n\nAs mentioned in the Overview, events are grouped into categories, and posted\nto the webhook for that category:\n* Account Events: `/AccountEvent`\n* Authorization Events: `/Authorization`\n* Settlement Events: `/Settlement`\n* Transaction Events: `/Transaction`\n\nGalileo can send the event information as JSON or form data, and Galileo\ncan receive the client response as JSON or XML. **All fields are sent as\nstrings.** For example, the dollar amount `500.00` is sent as `\"500.00\"`.\n\n### Security\n\nThe client server should use HTTPS/SSL/TLS. The Events API supports TLS 1.2.\n\nTo authenticate with the client server, and to ensure message integrity,\nGalileo will compute a signature (HMAC) over the request, using a shared secret\nkey. The signature will be in the `Signature` field, base64 encoded.\n\nCompute the signature as follows:\n1. Create the following hash map, using header fields from the request:\n   ```python\n   data = {\n       \"Content-Length\": request[\"Content-Length\"],\n       \"Encryption-Type\": request[\"Encryption-Type\"],\n       \"User-ID\": request[\"User-ID\"],\n       \"Content-Type\": request[\"Content-Type\"],\n       \"Date\": request[\"Date\"]\n   }\n   ```\n2. Add the JSON/form values from the request body to the hash map. For\n   example, if the request body contains `{\"type\": \"auth\"}`, you should\n   add `data[\"type\"] = \"auth\"`.\n3. Sort the hash map, by key, alphabetically, with all parameters that\n   are capatalized first, then lower case. Most sorting functions in\n   programming languages will sort by ASCII code value, which will work\n   here.\n4. Compute the string `key + \"|\" + base64(dict[key])` for every key\n   in the hash map, and concatenate all such strings.\n5. Compute the HMAC-SHA256 signature over this string, using the shared\n   secret key.\n\n   [block:callout]\n    {\n      \"type\": \"warning\",\n      \"title\": \"Warning\",\n      \"body\": \"Make sure all capitalization, whitespace, etc. is maintained\nwhen computing the signature. In addition, some HTTP libraries will\nlowercase the `D` in `User-ID` resulting in `User-Id`. Please ensure\nyou use `User-ID` for the header field name, for computing the\nsignature (otherwise you will get the wrong value).\"\n    }\n    [/block]\n\n\n### Retry\n\nGalileo can resend messages if a successful response code is not received,\nusing standard exponential backoff. Work with your PM/AM to set product parameters\n`RTRDL`, the initial delay (in seconds), and `RETRY`, the total number of retries.\n\nTo be concrete, the following table shows an example, assuming `RTRDL` is set to\n60 seconds and `RETRY` is 5.\n* `Attempt` is the total number of attempts, over time. The first attempt is the\n  first time Galileo tries to send the event to the client, so with `RETRY = 5`,\n  there will be 6 attempts total.\n* `Retry Delay Seconds` is how many seconds Galileo will wait to do the next attempt\n  if the current attempt fails. (`Retry Delay Minutes` and `Retry Delay Hours` is the same\n  information but in different units.)\n\n`Retry Seconds` increases exponentially for each retry by multiplying\n`RTRDL` by `Attempt^2`. The first retry attempt has a value of 1, so the first\ndelay will be `RTRDL`.\n\n| Attempt | Retry Delay Seconds | Retry Delay Minutes | Retry Delay Hours |\n|:-------:|:-------------------:|:-------------------:|:-----------------:|\n| 1       | 60                  | 1.0                 |              0.02 |\n| 2       | 240                 | 4.0                 |              0.07 |\n| 3       | 540                 | 9.0                 |              0.15 |\n| 4       | 960                 | 16.0                |              0.27 |\n| 5       | 1500                | 25.0                |              0.42 |\n| 6       | 2160                | 36.0                |              0.60 |\n","version":"1.0.0"},"paths":{"/AccountEvent":{"post":{"summary":"Account Events Webhook","description":"Galileo `POST`s to `/AccountEvent` to send Account Events to the client. An Account Event is triggered when an event occurs on an account (card activated, updated profile, card shipped, etc.).\n\n### Requests\n\nThe event data (described in the index pages that follow) will be in the body of the request, as JSON or form data.\n\n#### JSON example (`application/json`)\n```json\n{\n  \"type\": \"card_shipped\",\n  \"account_id\": \"2011\",\n  \"balance\": \"500.00\",\n  \"cad\": \"12534\",\n  \"pmt_ref_no\": \"155200002022\",\n  \"prod_id\": \"1701\",\n  \"prog_id\": \"305\",\n  \"timestamp\": \"2019-10-09 11:20:33 MST\",\n  \"msg_event_id\": \"1234567891\"\n}\n```\n\n#### Form example (`application/x-www-form-urlencoded`)\n```\ntype=card_shipped&prod_id=1619&prog_id=255&pmt_ref_no=199999999998&open_to_buy=4.05&timestamp=2019-10-09+11%3A20%3A33+MST\n```\n\n### Responses\n\nValid values for `success_code`.\n\n| Value | Description | Retransmit |\n| :---: | --- | :---: |\n| 0 | Success | No |\n| 1 | Parameters do not pass validation (parsing error) | No |\n| 2 | Cardholder account not in system | No |\n| 3 | General system failure | No |\n| 4 | Authentication failed | No |\n| 5 | Not ready to accept messages | Yes |\n\n#### JSON response example\n```json\n{\n  \"success_code\": \"0\"\n}\n```\n\nXML responses should use the webhook name (`AccountEvent`) as the envelope.\n#### XML example\n```xml\n<AccountEvent><success_code>0</success_code></AccountEvent>\n```\n","operationId":"webhook_account_event_post","tags":["Account Events Webhook"],"parameters":[{"name":"X-Request-ID","in":"header","description":"A unique identifier for the HTTP request.","schema":{"type":"string","format":"uuid"},"required":true},{"name":"Encryption-Type","in":"header","description":"Signature algorithm. For now, always `\"HMAC-SHA256\"`.","schema":{"type":"string","enum":["HMAC-SHA256"],"default":"HMAC-SHA256"},"required":true},{"name":"User-ID","in":"header","description":"Identifies request as coming from Galileo. Hard-coded to `\"galileo\"`.","schema":{"type":"string","enum":["galileo"],"default":"galileo"},"required":true},{"name":"Date","in":"header","description":"UTC timestamp when request is sent. Format: `\"<timestamp><timezone>\"` where `timestamp = YYYYMMDD:HHMMSS` and `timezone = UTC`. Example: `20170504:141752UTC`.","schema":{"type":"string"},"required":true},{"name":"Signature","in":"header","description":"Signature of request. See overview for more details.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Response from client.","content":{"application/json":{"schema":{"type":"object","properties":{"success_code":{"type":"string","description":"Response (\"success\") codes. Possible values:\n\n* `0` - Success\n* `1` - Parameters do not pass validation\n* `2` - Cardholder account not in system\n* `3` - General system failure\n* `4` - Authentication failed\n* `5` - Not ready to accept messages. Event will be retransmitted.\n\nFor all but `5`, the event will not be retransmitted.\n","enum":["0","1","2","3","4","5"]}}},"examples":{"response":{"value":"{\n  \"success_code\": \"0\"\n}\n"}}},"application/xml":{"schema":{"type":"object","properties":{"success_code":{"type":"string","description":"Response (\"success\") codes. Possible values:\n\n* `0` - Success\n* `1` - Parameters do not pass validation\n* `2` - Cardholder account not in system\n* `3` - General system failure\n* `4` - Authentication failed\n* `5` - Not ready to accept messages. Event will be retransmitted.\n\nFor all but `5`, the event will not be retransmitted.\n","enum":["0","1","2","3","4","5"]}},"xml":{"name":"Account Event"}},"examples":{"response":{"value":"<AccountEvent>\n  <success_code>0</success_code>\n</AccountEvent>\n"}}}}}}}},"/Authorization":{"post":{"summary":"Authorization Events Webhook","description":"Galileo `POST`s to `/Authorization` to send Authorization Events to the client. An Authorization Event is triggered when a card financial transaction with an association occurs. This includes card authorizations and denied card authorizations due to invalid PIN, insufficient funds, inactive card, etc.\n\n### Requests\n\nThe event data (described in the index pages that follow) will be in the body of the request, as JSON or form data.\n\n#### JSON example (`application/json`)\n```json\n{\n  \"type\": \"denied_auth_gas\",\n  \"account_id\": \"2011\",\n  \"amount\": \"10.25\",\n  \"balance\": \"500.00\",\n  \"card_id\": \"12534\",\n  \"mcc\": \"5712\",\n  \"merch_loc\": \"NEW YORK, NY\",\n  \"merch_name\": \"Widgets Incorporated\",\n  \"merch_num\": \"L4DIV6D5LM4X7LF\",\n  \"network\": \"V\",\n  \"pmt_ref_no\": \"155200002022\",\n  \"prod_id\": \"1701\",\n  \"prog_id\": \"305\",\n  \"timestamp\": \"2019-10-09 11:20:33 MST\",\n  \"auth_id\": \"12303090\"\n}\n```\n\n#### Form example (`application/x-www-form-urlencoded`)\n```\ntype=denied_auth_gas&prod_id=1504&prog_id=255&pmt_ref_no=199999999998&merchant_name=DISCOUNT+FM+1&merchant_number=231000000129001&mcc=5541&merch_loc=ARCHER%2C+FLUS&auth_tran_type=5&amount=30.65&network=V&open_to_buy=2.95&auth_id=29143890&timestamp=2019-10-09+11%3A20%3A33+MST&account_id=388750&card_id=740724\n```\n\n### Responses\n\n| Value | Description | Retransmit |\n| :---: | --- | :---: |\n| 0 | Success | No |\n| 1 | Parameters do not pass validation (parsing error) | No |\n| 2 | Cardholder account not in system | No |\n| 3 | General system failure | No |\n| 4 | Authentication failed | No |\n| 5 | Not ready to accept messages | Yes |\n\n#### JSON example\n```json\n{\n  \"success_code\": \"0\"\n}\n```\n\nXML responses should use the webhook name (`Authorization`) as the envelope. \n#### XML example\n```xml\n<Authorization><success_code>0</success_code></Authorization>\n```\n","operationId":"webhook_authorization_event_post","tags":["Authorization Events Webhook"],"parameters":[{"name":"X-Request-ID","in":"header","description":"A unique identifier for the HTTP request.","schema":{"type":"string","format":"uuid"},"required":true},{"name":"Encryption-Type","in":"header","description":"Signature algorithm. For now, always `\"HMAC-SHA256\"`.","schema":{"type":"string","enum":["HMAC-SHA256"],"default":"HMAC-SHA256"},"required":true},{"name":"User-ID","in":"header","description":"Identifies request as coming from Galileo. Hard-coded to `\"galileo\"`.","schema":{"type":"string","enum":["galileo"],"default":"galileo"},"required":true},{"name":"Date","in":"header","description":"UTC timestamp when request is sent. Format: `\"<timestamp><timezone>\"` where `timestamp = YYYYMMDD:HHMMSS` and `timezone = UTC`. Example: `20170504:141752UTC`.","schema":{"type":"string"},"required":true},{"name":"Signature","in":"header","description":"Signature of request. See overview for more details.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Response from client.","content":{"application/json":{"schema":{"type":"object","properties":{"success_code":{"type":"string","description":"Response (\"success\") codes. Possible values:\n\n* `0` - Success\n* `1` - Parameters do not pass validation\n* `2` - Cardholder account not in system\n* `3` - General system failure\n* `4` - Authentication failed\n* `5` - Not ready to accept messages. Event will be retransmitted.\n\nFor all but `5`, the event will not be retransmitted.\n","enum":["0","1","2","3","4","5"]}}},"examples":{"response":{"value":"{\n  \"success_code\": \"0\"\n}\n"}}},"application/xml":{"schema":{"type":"object","properties":{"success_code":{"type":"string","description":"Response (\"success\") codes. Possible values:\n\n* `0` - Success\n* `1` - Parameters do not pass validation\n* `2` - Cardholder account not in system\n* `3` - General system failure\n* `4` - Authentication failed\n* `5` - Not ready to accept messages. Event will be retransmitted.\n\nFor all but `5`, the event will not be retransmitted.\n","enum":["0","1","2","3","4","5"]}},"xml":{"name":"Authorization"}},"examples":{"response":{"value":"<Authorization>\n  <success_code>0</success_code>\n</Authorization>\n"}}}}}}}},"/Settlement":{"post":{"summary":"Settlement Events Webhook","description":"Galileo `POST`s to `/Settlement` to send Settlement Events to the client. A Settlement Event is triggered when a card financial transaction is settled or force posted.\n\n### Requests\n\nThe event data (described in the index pages that follow) will be in the body of the request, as JSON or form data.\n\n#### JSON example (`application/json`)\n```json\n{\n  \"type\": \"setl\",\n  \"act_type\": \"VI\",\n  \"amount\": \"10.75\",\n  \"auth_id\": \"254568\",\n  \"balance_id\": \"2011\",\n  \"cad\": \"12534\",\n  \"mcc\": \"5712\",\n  \"merchant_location\": \"NEW YORK, NY\",\n  \"merchant_name\": \"Widgets Incorporated\",\n  \"merchant_number\": \"L4DIV6D5LM4X7LF\",\n  \"network\": \"V\",\n  \"open_to_buy\": \"500.00\",\n  \"otype\": \"10\",\n  \"pmt_ref_no\": \"155200002022\",\n  \"prod_id\": \"1701\",\n  \"prog_id\": \"305\",\n  \"timestamp\": \"2019-10-09 11:20:33 MST\"\n}\n```\n\n#### Form example (`application/x-www-form-urlencoded`)\n```\ntype=setl&act_type=VI&amount=10.75&auth_id=254568&balance_id=2011&cad=12534&mcc=5712&merchant_location=NEW+YORK%2C+NY&merchant_name=Widgets+Incorporated&merchant_number=L4DIV6D5LM4X7LF&network=V&open_to_buy=500&otype=10&pmt_ref_no=155200002022&prod_id=1701&prog_id=305&timestamp=2019-10-09+11%3A20%3A33+MST\n```\n\n### Responses\n\n| Value | Description | Retransmit |\n| :---: | --- | :---: |\n| 0 | Success | No |\n| 1 | Parameters do not pass validation (parsing error) | No |\n| 2 | Cardholder account not in system | No |\n| 3 | General system failure | No |\n| 4 | Authentication failed | No |\n| 5 | Not ready to accept messages | Yes |\n\n#### JSON example\n```json\n{\n  \"success_code\": \"0\"\n}\n```\n\nXML responses should use the webhook name (`Settlement`) as the envelope. \n#### XML example\n```xml\n<Settlement><success_code>0</success_code></Settlement>\n```\n","operationId":"webhook_settlement_event_post","tags":["Settlement Events Webhook"],"parameters":[{"name":"X-Request-ID","in":"header","description":"A unique identifier for the HTTP request.","schema":{"type":"string","format":"uuid"},"required":true},{"name":"Encryption-Type","in":"header","description":"Signature algorithm. For now, always `\"HMAC-SHA256\"`.","schema":{"type":"string","enum":["HMAC-SHA256"],"default":"HMAC-SHA256"},"required":true},{"name":"User-ID","in":"header","description":"Identifies request as coming from Galileo. Hard-coded to `\"galileo\"`.","schema":{"type":"string","enum":["galileo"],"default":"galileo"},"required":true},{"name":"Date","in":"header","description":"UTC timestamp when request is sent. Format: `\"<timestamp><timezone>\"` where `timestamp = YYYYMMDD:HHMMSS` and `timezone = UTC`. Example: `20170504:141752UTC`.","schema":{"type":"string"},"required":true},{"name":"Signature","in":"header","description":"Signature of request. See overview for more details.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Response from client.","content":{"application/json":{"schema":{"type":"object","properties":{"success_code":{"type":"string","description":"Response (\"success\") codes. Possible values:\n\n* `0` - Success\n* `1` - Parameters do not pass validation\n* `2` - Cardholder account not in system\n* `3` - General system failure\n* `4` - Authentication failed\n* `5` - Not ready to accept messages. Event will be retransmitted.\n\nFor all but `5`, the event will not be retransmitted.\n","enum":["0","1","2","3","4","5"]}}},"examples":{"response":{"value":"{\n  \"success_code\": \"0\"\n}\n"}}},"application/xml":{"schema":{"type":"object","properties":{"success_code":{"type":"string","description":"Response (\"success\") codes. Possible values:\n\n* `0` - Success\n* `1` - Parameters do not pass validation\n* `2` - Cardholder account not in system\n* `3` - General system failure\n* `4` - Authentication failed\n* `5` - Not ready to accept messages. Event will be retransmitted.\n\nFor all but `5`, the event will not be retransmitted.\n","enum":["0","1","2","3","4","5"]}},"xml":{"name":"Settlement"}},"examples":{"response":{"value":"<Settlement>\n  <success_code>0</success_code>\n</Settlement>\n"}}}}}}}},"/Transaction":{"post":{"summary":"Transaction Events Webhook","description":"Galileo `POST`s to `/Transaction` to send Transaction Events to the client. A Transaction Event is triggered for all other financial transactions that occur against an account, but don't go through an association (fee, payments, adjustments, etc.).\n\n### Requests\n\nThe event data (described in the index pages that follow) will be in the\nbody of the request, as JSON or form data.\n\n#### JSON example (`application/json`)\n```json\n{\n  \"type\": \"ach_credit_fail\",\n  \"account_id\": \"2011\",\n  \"amount\": \"45.00\",\n  \"pmt_ref_no\": \"155200002022\",\n  \"prod_id\": \"1701\",\n  \"prog_id\": \"305\",\n  \"return_code\": \"R01\",\n  \"source\": \"Chase Bank\",\n  \"source_id\": \"6426460\",\n  \"timestamp\": \"2019-10-09 11:20:33 MST\"\n}\n```\n\n#### Form example (`application/x-www-form-urlencoded`)\n```\ntype=ach_credit_fail&account_id=2011&amount=45&pmt_ref_no=155200002022&prod_id=1701&prog_id=305&return_code=R01&source=Chase+Bank&source_id=6426460&timestamp=2019-10-09+11%3A20%3A33+MST\n```\n\n### Responses\n\n| Value | Description | Retransmit |\n| :---: | --- | :---: |\n| 0 | Success | No |\n| 1 | Parameters do not pass validation (parsing error) | No |\n| 2 | Cardholder account not in system | No |\n| 3 | General system failure | No |\n| 4 | Authentication failed | No |\n| 5 | Not ready to accept messages | Yes |\n\n#### JSON example\n```json\n{\n  \"success_code\": \"0\"\n}\n```\n\nXML responses should use the webhook name (`Transaction`) as the envelope. \n#### XML example\n```xml\n<Transaction><success_code>0</success_code></Transaction>\n```\n","operationId":"webhook_transaction_event_post","tags":["Transaction Events Webhook"],"parameters":[{"name":"X-Request-ID","in":"header","description":"A unique identifier for the HTTP request.","schema":{"type":"string","format":"uuid"},"required":true},{"name":"Encryption-Type","in":"header","description":"Signature algorithm. For now, always `\"HMAC-SHA256\"`.","schema":{"type":"string","enum":["HMAC-SHA256"],"default":"HMAC-SHA256"},"required":true},{"name":"User-ID","in":"header","description":"Identifies request as coming from Galileo. Hard-coded to `\"galileo\"`.","schema":{"type":"string","enum":["galileo"],"default":"galileo"},"required":true},{"name":"Date","in":"header","description":"UTC timestamp when request is sent. Format: `\"<timestamp><timezone>\"` where `timestamp = YYYYMMDD:HHMMSS` and `timezone = UTC`. Example: `20170504:141752UTC`.","schema":{"type":"string"},"required":true},{"name":"Signature","in":"header","description":"Signature of request. See overview for more details.","schema":{"type":"string"},"required":true}],"responses":{"200":{"description":"Response from client.","content":{"application/json":{"schema":{"type":"object","properties":{"success_code":{"type":"string","description":"Response (\"success\") codes. Possible values:\n\n* `0` - Success\n* `1` - Parameters do not pass validation\n* `2` - Cardholder account not in system\n* `3` - General system failure\n* `4` - Authentication failed\n* `5` - Not ready to accept messages. Event will be retransmitted.\n\nFor all but `5`, the event will not be retransmitted.\n","enum":["0","1","2","3","4","5"]}}},"examples":{"response":{"value":"{\n  \"success_code\": \"0\"\n}\n"}}},"application/xml":{"schema":{"type":"object","properties":{"success_code":{"type":"string","description":"Response (\"success\") codes. Possible values:\n\n* `0` - Success\n* `1` - Parameters do not pass validation\n* `2` - Cardholder account not in system\n* `3` - General system failure\n* `4` - Authentication failed\n* `5` - Not ready to accept messages. Event will be retransmitted.\n\nFor all but `5`, the event will not be retransmitted.\n","enum":["0","1","2","3","4","5"]}},"xml":{"name":"Transaction"}},"examples":{"response":{"value":"<Transaction>\n  <success_code>0</success_code>\n</Transaction>\n"}}}}}}}}},"x-readme":{"proxy-enabled":true}}