Home / Issuing / Control Authorizations
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:
These steps are outlined in the following graphic:
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.
Note: 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:
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 support guide.
Refer to the following guidelines when managing collaborative authorization endpoints using the Highnote API:
user-agent
: HightnotePlatform/1.0.0
highnote-signature
: The result of computing an HMAC 256 signature of the request bodycontent-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:
2XX
response. All other status codes will result in the transaction being declined.Warning: 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, you must activate and verify it. Use the following mutation to activate a collaborative authorization endpoint:
Warning: 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 for handling collaborative authorization requests and responses:
A collaborative authorization request is an HTTPS POST request with a JSON body. 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.
Refer to the following table for an overview of the various Amount
fields in a request body:
Field | Description | Notes |
---|---|---|
transactionAmount | The amount of money processed in the transaction | Displayed in the cardholder's currency |
settlementAmount | The amount of money settled in Highnote | Differs from transactionAmount when both fields are in different currencies. For example, if a transactionAmount reflects funds in EUR, the settlementAmount will reflect USD and differ. |
requestedAmount | The amount of money Highnote authorized based on the card's available balance, applied spend rules, and any other processing rules | Displayed in USD and includes surcharge fees |
The following code snippet provides an example of a collaborative authorization request body:
Collaborative authorization reponse bodies may have the following fields:
Field | Description |
---|---|
transaction.id | Unique identifier of the transaction |
reponseCode | Transaction authorization response |
authorizedAmount | An Amount object |
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
. The following code snippet provides an example APPROVED
response body:
Note: 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
will reflect 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 will pass back an appropriate response code reflecting why your system declined the authorization:
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:
Warning: The Highnote test environment allows you to freely explore the platform features and functionality. It is intended for experimenting, building integrations, and training your team.
To ensure the security of your real-world data, please refrain from entering production data into the test environment. Production data includes sensitive information like customer details, financial data, or personally identifiable information (PII).
Use only dummy or test data explicitly created for testing purposes in the test environment.
You may test collaborative authorization in your test environment by adding and activating a CollaborativeAuthorizationEndpoint
and using a simulateAuthorization
mutation: