Collaborative Authorization

Collaborative authorization empowers you to approve or decline transactions in real time based on your business logic. Collaborative authorization requests are for initial authorizations only, not refund authorizations.

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.

The following steps demonstrate how collaborative authorization typically works on a card product:

1. An account holder makes a purchase which is sent to Highnote.
2. The purchase is passed through financial account balance checks and spend rules configured on the Highnote platform.
3. If the purchase passes these, an HTTPS POST request is sent to your collaborative authorization endpoint for approval.
4. You respond to the request with an approval or denial decision.
5. The authorization response is sent to the merchant with the decision.

These steps are depicted in the following graphic:

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

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

1. Have the Highnote team enable the feature for your card product. 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.

You can manage collaborative authorization endpoints using the Highnote Dashboard or API.

For information on managing your collaborative authorization endpoints using the Highnote Dashboard, see the Collaborative authorization in the Support docs.

Refer to the following guidelines when managing collaborative authorization endpoints using the Highnote API:

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

Use the following mutation to register and add a collaborative authorization endpoint. By default, collaborative authorization endpoints are inactive at creation.

When registering a collaborative authorization endpoint, refer to the following requirements:

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

Only 1 endpoint can be ACTIVE at a time. Activating an endpoint automatically deactivates any existing active endpoints.

Once a collaborative authorization endpoint has been registered, you must activate and verify it. Use the following mutation to activate a collaborative authorization endpoint:

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

Collaborative authorization request events differ from payment card authorization notification events.

Refer to the following guidelines for handling collaborative authorization requests and responses:

• You have up to 2 seconds to respond to a collaborative authorization request with an approval or denial decision.
• Returning any HTTP response code except 2XX causes the collaborative authorization request to fail and trigger your stand-in authorization settings.
• Failure to respond to a request within 2 seconds causes the collaborative authorization request to fail and trigger your stand-in authorization settings.

When your endpoint fails to respond (timeout or non-2XX), Highnote uses your card product's stand-in settings to approve or decline the transaction. Contact support@highnote.com to configure stand-in behavior.

Collaborative authorization request events differ from payment card authorization notification events.

A collaborative authorization request is an HTTPS POST request with a JSON body.

Amount fields:

A collaborative authorization request body has several amount fields relating to a transaction's money movement. These amount fields may differ from one request to another.

Other notes:

• The field "responseCode": "APPROVED" refers to Highnote's preliminary authorization decision before calling your endpoint.
• The extensions object contains metadata about the request, specifically the signatureTimestamp which is the Unix timestamp (milliseconds) when the request was signed. Use this to verify request freshness and prevent replay attacks.

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

The following code snippet provides an example of a cross-border collaborative authorization request body:

Collaborative authorization response bodies may have the following fields:

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

When your endpoint responds with the following payload, an AuthorizationEvent will reflect a status of APPROVED. The following code snippet provides an example APPROVED response body:

For partial approvals, 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 reflects a status of PARTIAL_AMOUNT_APPROVED. The merchant must report whether their point of sale can accept a partial amount via the terminalSupportsPartialApproval field in the pointOfSaleDetails object:

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

During collaborative authorization, when Highnote receives an authorization from the payment network, Highnote responds with one of three initial response codes:

• APPROVED
• PARTIAL_AMOUNT_APPROVED
• DO_NOT_HONOR

You will only see a collaborative authorization request in your system if Highnote sends an APPROVED or PARTIAL_AMOUNT_APPROVED response. When your system responds to the collaborative authorization request, the resulting response code from Highnote's platform follows the pattern described in the following tables.

The following table provides an overview of scenarios when Highnote provides an APPROVED response to a IssuerPreliminaryAuthorizationEvent:

The following table provides an overview of scenarios when Highnote provides an PARTIAL_AMOUNT_APPROVED response to a IssuerPreliminaryAuthorizationEvent:

When you register a collaborative authorization endpoint, the API returns a secret key. If you need to retrieve this key again, you can query the CollaborativeAuthorizationEndpoint object to retrieve the signingKeys field.

Use the following query to retrieve a collaborative authorization endpoint's secret key:

Use the collaborative authorization simulation to test your endpoints in the test environment. For more information, see Simulate Collaborative Authorization.