Collaborative Authorization

Collaborative Authorization is self-service in your Test Environment. In the Live Environment, the feature must be enabled for your Product by the Highnote Team.

Collaborative authorization empowers you to approve or decline each transaction in real-time based on your business logic. When an account holder makes a purchase and associated spend rules have passed, if you have a configured CollaborativeAuthorizationEndpoint, you will receive an HTTPS POST request with a JSON body containing a PaymentCardAuthorizationRequest for approval.

In order to begin participating in the authorization decision on payment card transactions, you will need to:

1. Register a Collaborative Authorization Endpoint
2. Activate the Collaborative Authorization Endpoint
3. Work with your Highnote integration team to enable the CollaborativeAuthorizationCardProductFeature on your Card Product

The remainder of this guide will cover how to:

• Configure a Collaborative Authorization Endpoint
• Verify a request sent from Highnote to your registered Collaborative Authorization Endpoint
• Make real-time authorization decisions on your account holders' payment card transactions
• Simulate authorizations to test your Collaborative Authorization Endpoint

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

The CollaborativeAuthorizationEndpoint must be:

• Highly available
• Capable of returning a 2XX response. All other status codes will result in the transaction being declined
• Served via HTTPS

Once a CollaborativeAuthorizationEndpoint has been registered, it must be verified in order for Highnote to begin sending real-time CollaborativeAuthorizationRequests for approval. A 2XX response from the endpoint will result in its status transitioning to ACTIVE, while all other HTTP response codes will result in the status transitioning to ACTIVATION_FAILED. Activating an endpoint will automatically deactivate any existing endpoints that are ACTIVE. Only one endpoint can be ACTIVE at one time.

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.

When an Account Holder makes a purchase with a valid payment instrument issued by the Highnote Platform, an authorization request is sent to Highnote. First, any associated spend rules are run and provided they pass, an HTTP POST request containing a CollaborativeAuthorizationPayload will be sent to the configured CollaborativeAuthorizationEndpoint. You have up to 2 seconds to respond to the request to approve or decline the transaction. Returning any other HTTP response codes or failing to respond within 2 seconds, Highnote will use your default settings to approve or decline the authorization.

Client Request

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 }
}

Client Response

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

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.