Authorization Requests

Authorization requests occur when a purchase is being made through a card on the Penny system. These requests allow Penny and your business to approve or deny any incoming transaction allowing full control and monitoring of spendings.

When a purchase is made using an issued card, an authorization request is generated. The outcome of this request determines whether a transaction is approved or declined.

Transaction authorization uses the following process:

1. Penny verifies the following:
   1. The card making the purchase is active
   2. There is sufficient funds for the authorization
   3. Your spending controls permit the authorization
2. Penny initiates an authorization request event. If an authorization webhook has been set up by your business, this event will be sent to that webhook for approval.
3. If your webhook does not respond in time, your default business settings will be used to approve or decline the authorization. Otherwise your webhook's response will be used and the authorization will be approved/declined accordingly

Regardless of approval status, an authorization creation event will be generated to inform you of the finalized authorization.

The following is a flow chart summarizing the above process:

Setting Up Transaction Decisioning

Transactions can be allowed to denied through a webhook interface which allows for your company to receive the transaction details, and respond with an approval or denial for the purchase being completed. These decioning controls can be set on a global business level, or on a per wallet level, allowing complete control of purchases for seperate subsets of cards if desired. In order to setup your transaction decisioing endpoint the following steps must be completed.

1. A new webhook is created with the trigger_event_identifier set to transaction.authorization.pending
2. Using the webhook_id retrieved from the previous step, update your Business or Wallet's authentication_webhook_id to be this ID
3. Set your authentication_default in either your Business or Wallet to True or False, indicating whether a transaction should be allowed or denied if we are unable to reach your decisioning webhook

Now that the webhook has been setup to start transaction decisioning, when a purchase is made a Transaction event is passed in with all the details of the transaction. In order to approve or deny the transaction a response must be given with an approved field in the body, which must be either True or False. As well an optional message field can be passed through, which will be attached to the authorization of the transaction.

Please find examples of the transaction event and approval response JSON below:

Transaction Event Object

{
    "event_id": "7846-3fd5-f84e-4806adb0b0ab-a081-1a64",
    "event_identifier": "transaction.authorization.pending",
    "data": {
        "transaction_id": "2bd9-feb73cac464e-9fb9-b44d-14d0-f85d",
        "version": 0,
        "version_time": "2023-07-12T01:03:29.700507+00:00",
        "tags": {},
        "card_id": "431d-8e6aaf9847ed-8cca-8095-0091-1ba7",
        "wallet_id": "482d-978a-be12410e-ac09c1d8-b512-dbe5",
        "user_id": null,
        "status": "Authorization Approved",
        "status_message": "Transaction Authorized Approved",
        "amount": 10.0,
        "available_balance": 1000.0,
        "currency_code": "USD",
        "network": "Visa",
        "original_amount": 14.9,
        "original_currency_code": "AUD",
        "authorization_currency_code": "AUD",
        "authorization_amount": 14.9,
        "event_identifier": "transaction.authorization.approved",
        "card_acceptor": {
            "name": "Testing Acceptor",
            "city": "Test-topia",
            "state": "TT",
            "country": "US",
            "zip_code": "12345",
            "mid": "123456789",
            "mcc": "12345"
        },
        "authorization": {
            "authorized": true,
            "authorization_message": "Approved",
            "authorizor": "The Penny Inc"
        },
        "interchange_fee": {
            "percentage_rate": 1.5,
            "flat_rate": 0.0,
            "amount": 0.15
        },
        "retrieval_reference_number": "987654321"
    },
    "transaction_id": "2bd9-feb73cac464e-9fb9-b44d-14d0-f85d"
}

Approval Response Object

{
  "approved": True,
  "message": "Approval Message",
}

Transaction Completion

Once an authorization is accepted and captured, its status changes to closed and a transaction is generated. This typically occurs within a 24-hour time-frame. Regardless, hotels, airlines, and car rental firms can capture the authorization up to 30 days later.

Upon capturing an authorization, the following takes place:

1. The authorization status is changed to "Closed", freeing the held purchase amount associated with that authorization. A balance transaction is generated to represent this action.
2. The purchase amount is subtracted from the balance allocated for issuing.