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:
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:
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 bodycontent-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:
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 declinedActivating 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:
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:
Field | Description | Notes |
---|---|---|
transactionAmount | The amount of money processed in the transaction | 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 settlemAmount 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 | In USD, includes surcharge fees |
The following code snippet provides an example of a collaborative authorization client request body:
{ "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:
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
.
{ "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.
{ "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.
{ "transaction": { "id": "MC44LnR4XzIyYzQ2ZGUyYjJkNzhkNGJhZGI3NmMxYWNjNzkxYzgyY2U=" }, "responseCode": "INSUFFICIENT_FUNDS" }
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 your collaborative authorization functionality in your Test Environment by adding and activating a CollaborativeAuthorizationEndpoint
and invoking the simulateAuthorization
mutation.