Overview
Collaborative Authorization Summary
Collaborative Authorization is a card service that empowers you to authorize or decline card actions based on your business logic and use case. It gives you the opportunity to step beyond the default decisioning process included with all our card-issuing services and customize the way in which card actions are authorized case-by-case. When you subscribe to the Collaborative Authorization service, each time we receive a financial transaction card-originated message pertaining to an issued card, we will parse the message into a user-friendly, informative format and send a single POST webhook to your preset webhook URL.
What is the Collaborative Authorization Webhook?
When a financial transaction card-originated message is received from the card issuer, it is formatted according to the ISO 8583 Standard. This standard, also known as "Financial Transaction Card-Originated Messages - Interchange Message Specifications" is an international standard used for exchanging electronic card transaction data. The Collaborative Authorization service in connectFi parses the complex standardized communication and interprets it into an easy to read, informative, JSON formatted structure, which is then sent to your (the client's) preset webhook URL via POST request. This webhook format is specific to transactions for cards/accounts issued through the /ibis endpoints.
What Are the Collaborative Authorization Action Types?
Each Collaborative Authorization webhook will be sent once by connectFi, and will contain an "actionType" property. The "actionType" property value is explained below.
| actionType value | Action Required? | Description |
|---|---|---|
| "request" | yes | The webhook will contain details of a request related to the transaction specified by the "transaction.authTransactionId" webhook field. This actionType requires the "00" response code (or other allowed response code) within a set time frame. Your response must be received within 2800ms. If the connection is broken due to any unforeseen circumstances before a response has been received, connectFi will use your preconfigured default to determine the response that is returned to the card issuer. Possible use cases for this actionType may include a request to approve a purchase, a withdrawal, a deposit, a refund, etc. |
| "advice" | no | The webhook will contain details about a transaction specified by the "transaction.authTransactionId" webhook field. This actionType is informative only and does not require decisioning. When the actionType is "advice", you should reply as soon as you receive the webhook with a "00" response code to acknowledge receipt and close the connection. The advice webhook will not be repeated. Possible "advice" webhooks include notifications informing you of a transaction's success, a status change, and/or whether the transaction is a reversal. |
What Action is Required?
When a "request" actionType Collaborative Authorization webhook is received by your server at the preset webhook URL, the connectFi server will, in turn, expect a response from you with the following JSON body.
The table below specifies allowed "responseCode" values.
| responseCode value | Description |
|---|---|
| "00" | Approved |
| "05" | Do not Honor |
| "34" | Suspect Fraud |
| "61" | Exceeds Withdrawal Amount Limit |
| "65" | Exceeds Withdrawal Frequency Limit |
Default Strategy
When a webhook is received by you (the client) that requires action, there is a limited amount of time to provide a response. Thus, a default strategy must be configured. The default strategy will be used in the case that a webhook requiring action is sent to your webhook URL and a response is not received within the time limit due to unforeseen circumstances. For example, you may request a default strategy of "00", which means that request webhooks requiring action will be approved if you are unable to provide a timely response. You should make every attempt to respond within the given time limit and rely on the default only in case of extenuating circumstances, such as an outage or loss of connection. Limits and/or restrictions may apply to the number or amount total of webhooks that may be approved by default. Contact support in order to configure your default strategy.
The configured time frame within which connectFi must receive a response from your webhook URL is approximately 2800ms.
Providing the Webhook URL
In order to receive Collaborative Authorization Webhooks from the connectFi service, you will need to provide the webhook URL that you wish to use for your instance. The webhook URL that is provided will be where all Collaborative Authorization webhooks related to cards issued through /ibis endpoints will be received by you (the client) from connectFi.