Home / Issuing / Control Authorizations
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:
CollaborativeAuthorizationCardProductFeature
on your Card ProductThe remainder of this guide will cover how to:
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
The CollaborativeAuthorizationEndpoint must be:
2XX
response. All other status codes will result in the transaction being declinedOnce 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.
{ "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 } }
Field | Description |
---|---|
transaction.id | The universally unique identifier of the transaction |
responseCode | Transaction authorization response. List of allowable values. |
authorizedAmount | An Amount object |
{ "transaction": { "id": "tx_2288ccdcc9fbe44b42a2becaa3c3ae5fb8" }, "responseCode": "APPROVED" }
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" }
You may test your collaborative authorization functionality in your Test Environment by adding and activating a CollaborativeAuthorizationEndpoint
and invoking the simulateAuthorization
mutation.