Collaborative Authorization

Collaborative authorization empowers you to approve or decline transactions in real time based on your business logic. The following steps outline an example of how collaborative authorization typically works on a card product:

1. An account holder makes a purchase.
2. The account holder's purchase is passed through your business logic, for example, your configured spend rules.
3. If the purchase passes your business logic, an HTTPS POST request is sent to your configured collaborative authorization endpoint for approval.
4. You respond to the request with an approval or denial decision.
5. If you fail to respond to the request in time or you respond with an incorrect HTTP response code, Highnote uses your default authorization settings to approve or decline the transaction.

This guide covers how to configure and activate a collaborative authorization endpoint, verify requests, make real-time authorization decisions, and simulate authorizations in the test environment.

Collaborative authorization is self-service in your test environment. In the live environment, the Highnote team must enable the feature for your product.

To start using collaborative authorization, you must complete the following steps:

1. Have the Highnote team enable the feature for your card product. For more information, contact support@highnote.com.
2. Register a collaborative authorization endpoint.
3. Activate the collaborative authorization endpoint.
4. Configure your request and response process.
5. Optional - Test the feature.

CollaborativeAuthorizationEndpoints may be managed in Highnote’s Dashboard, as well as via our GraphQL API. You may add up to 5 endpoints, and only one endpoint may be active at a time. Collaborative authorization requests are sent as HTTPS POST requests with JSON bodies. The following headers will be included on each request:

• user-agent - HightnotePlatform/1.0.0
• highnote-signature - The result of computing an HMAC 256 signature of the request body
• content-type - application/json

For information on managing your collaborative authorization endpoints using the Highnote dashboard, see Collaborative authorization.

Keep the following in mind when managing endpoints using the Highnote API:

• You can have up to five collaborative authorization endpoints, but only one endpoint can be active at a time.
• Collaborative authorization requests are sent as HTTPS POST requests with JSON bodies. The following headers will be included on each request:
  • user-agent: HightnotePlatform/1.0.0
  • highnote-signature: The result of computing an HMAC 256 signature of the request body
  • content-type: application/json

You can use the following mutation to register and add a collaborative authorization endpoint. By default, collaborative authorization endpoints are inactive at creation. Refer to the following requirements when registering a collaborative authorization endpoint:

• Make the endpoint highly available
• The endpoint must be capable of returning a 2XX response. All other status codes will result in the transaction being declined
• The endpoint requests and responses must be served via HTTPS

Activating an endpoint will automatically deactivate any existing ACTIVE endpoints. Only one endpoint can be ACTIVE at a time.

Once a collaborative authorization endpoint has been registered, it be me activated and verified before Highnote can begin sending requests for approval. Use the following mutation to activate a collaborative authorization endpoint:

The collaborativeAuthorizationRequest.id is an idempotent key. In the event of a retry, Highnote will resend the same request to your collaborative authorization endpoint with the same id.

Note the following guidelines about collaborative authorization requests and responses:

• You have up to two seconds to respond to a collaborative authorization request with an approval or denial decision
• Returning any HTTP response code except 2XX will cause the collaborative authorization request to fail and trigger your default authorization settings
• Failure to respond to a request within two seconds will cause the collaborative authorization request to fail and trigger your default authorization settings

A collaborative authorization request is an HTTPS POST request with a JSON body. Within a collaborative authorization request body, there are several Amount fields that relate to the money movement of a transaction. These Amount fields may differ depending on the scenario and use case.

Refer to the following table for an overview of the various Amount fields in a request body:

Client Request Example Payload

The following code snippet provides an example of a collaborative authorization client request body:

Copy code snippet
{
  "data": {
    "collaborativeAuthorizationRequest": {
      "__typename": "PaymentCardAuthorizationRequest",
      "id": "te_24e941a34ac44852a6677c879c9d7bcb",
      "transaction": { "id": "tx_2288ccdcc9fbe44b42a2becaa3c3ae5fb8" },
      "transactionTimestamp": "2022-12-07T20:57:26.052000000Z",
      "paymentCard": { "id": "cd_4994a1abb4ab1b6993839ab85904141" },
      "networkRetrievalReferenceNumber": null,
      "transactionAmount": { "value": 1000, "currencyCode": "USD" },
      "settlementAmount": { "value": 1000, "currencyCode": "USD" },
      "requestedAmount": { "value": 1000, "currencyCode": "USD" },
      "surchargeFee": null,
      "merchantDetails": {
        "merchantId": null,
        "category": "MISCELLANEOUS_SPECIALTY_RETAIL",
        "countryCodeAlpha3": "USA",
        "categoryCode": "5999",
        "description": null,
        "name": null,
        "address": {
          "streetAddress": null,
          "extendedAddress": null,
          "postalCode": "00000",
          "region": null,
          "locality": null,
          "countryCodeAlpha3": "USA"
        }
      },
      "responseCode": null,
      "avsResponseCode": null,
      "postalCodeResponseCode": null,
      "cvvResponseCode": null,
      "pointOfSaleDetails": {
        "panEntryMode": null,
        "pinEntryMode": null,
        "terminalAttendance": "UNATTENDED",
        "isCardHolderPresent": false,
        "isCardPresent": false,
        "purchaseAmountOnlyCapable": false,
        "isRecurring": null,
        "terminalSupportsPartialApproval": false
      },
      "createdAt": "2022-12-07T20:57:26.052000000Z"
    }
  },
  "extensions": { "signatureTimestamp": 1670446646658 }
}

Reponse bodies may have the following fields:

For a full list of collaborative authorization response codes, see the CollaborativeAuthorizationReponseCode API reference.

When your endpoint responds with the following payload, an AuthorizationEvent will reflect a status of APPROVED.

Copy code snippet
{
  "transaction": {
    "id": "MC44LnR4XzIyYzQ2ZGUyYjJkNzhkNGJhZGI3NmMxYWNjNzkxYzgyY2U="
  },
  "responseCode": "APPROVED"
}

The authorizedAmount cannot be greater than the requestedAmount and must be expressed in the same currency.

When your endpoint responds with the following payload, an AuthorizationEvent will reflect a status of PARTIAL_AMOUNT_APPROVED. The merchant must report whether their point of sale is capable of accepting a partial amount via the terminalSupportsPartialApproval field in the pointOfSaleDetails object.

Copy code snippet
{
  "transaction": {
    "id": "efcf86001d4c43ea90f4184da45f576f"
  },
  "authorizedAmount": {
    "value": 100,
    "currencyCode": "USD"
  },
  "responseCode": "PARTIAL_AMOUNT_APPROVED"
}

When you need to decline an AuthorizationEvent, your endpoint will pass back an appropriate response code reflecting why your system declined the authorization.

Copy code snippet
{
  "transaction": {
    "id": "MC44LnR4XzIyYzQ2ZGUyYjJkNzhkNGJhZGI3NmMxYWNjNzkxYzgyY2U="
  },
  "responseCode": "INSUFFICIENT_FUNDS"
}

You may test your collaborative authorization functionality in your Test Environment by adding and activating a CollaborativeAuthorizationEndpoint and invoking the simulateAuthorization mutation.