Secondary Authorizations

This page is currently under review. Updates to improve the clarity of the documentation are in progress.

Intro

Secondary Authorization allows a client the ability to approve or decline an authorization request on a given payment card. Authorization messages will be forwarded from the card processor to the client and the client will then use the information to trigger another process, (ex load additional funds onto a card, filter based on the MCC code of the merchant who has initiated the transaction). The client can then respond back with an accept of decline response which will be forwarded to the processor who will either decline or accept the transaction on the Card network.

Use Cases Supported

Use Case 1

  • The Processor manages the Balance on the cardholder.  This means the card has to have enough balance for a purchase transaction to move forward to the Auth stage.
  • If the Processor internal checks pass, then the Authorization is sent to Berkeley.
  • Berkeley then forwards the Authorization to the Client via an API request transaction.  
  • If the client Approves the authorization, they send it back to Berkeley as part of the API response within 500ms.
  • Berkeley then sends the approval message to the Processor.
  • The Processor will debit/credit the available balance of the cardholder and send the response to Mastercard.

Use Case 2

  • The Processor manages the Balance at the Escrow level.  This means that the Processor will check the balance of the Client Escrow Funding account associated with the cardholder.
  • If the Escrow Funding account has enough funds, the Processor will send the authorization to Berkeley to approve/decline.
  • Berkeley then forwards the Authorization to the Client via an API request transaction.  
  • If the client Approves the authorization, they send it back to Berkeley as part of the API response within 500ms.
  • Berkeley then sends the approval message to the Processor.
  • The Processor will debit/credit the available balance of the cardholder and send the response to Mastercard.

Process

Setup

In order to enable Secondary Authentication you will need to do the following

  • Register a callback URL with the Berkeley Platform, which will receive authorization requests as they are sent from the Payment Card Processor. You will be able to enter/update the callback URL through the client portal.
  • In the client portal you will be able to access the signing key in order to validate incoming Webhook messages from the Berkeley Platform
  • Contact Berkeley to enable the forwarding of Authentication Messages to the callback URL

Approving / Declining Authorizations

  • When an Authorization Message is received from the Card Processor, the Berkeley Platform will forward the message to the callback URL registered in the Client Portal
  • You should extract the signature from the X-BPS-Signature header and compare the value to the expected value to ensure the message originated from the Berkeley Platform
  • You can then inspect the contents of the Authorization message in order to make a determination on this authorization.
  • A response is then sent back to the Berkeley Platform containing the action to be relayed to the Card Processor.

Time Constraints

  • A transaction must be completed within a short amount of time or it will be timed out by the network or card processor.
  • The ideal response time for a message from Berkeley should be under 500ms, although lower is preferable. That is, from the time you receive the request to the time your response is sent.

Message Signatures

Every Webhook message received from the Berkeley Platform will contain the following header

1X-BPS-Signature: XXXX

This header is the signature generated by the Berkeley Platform. You will need to use the process described below in order to generate the signature and compare it against the value sent in the header.

Signature Generation

The signature can be generated using the following process

  1. Extract the body of the request
  2. Compute an HMAC using SHA-256 with the body of the request as the message and the signing key found in the client portal as the key.
  3. The value in the header can then be compared to the generated signature to confirm the message originated from the Berkeley Platform. NOTE: When comparing the values use a constant time" string comparison" algorithm to protect from certain timing attacks

Message types (MTI)

Message Type Indicator (MTI)Message typeDescription
0100Authorization (most common type).Card is used for a transaction. Could be a preauth, auth, ATM, balance inquiry, and so on.
0120Authorization AdviceThey might not affect the OTB. This could be force posts, completions, tokenization updates, etc. These cannot be declined.
0400ReversalA reversal of a previous auth. Should reference a previous transaction, but is not required to.
0420Reversal AdviceThey might not affect the OTB. This could be force posts, completions, tokenization updates, etc. These cannot be declined.

Authorization Message Formats

The Webhook will be sent as an HTTP Post request and the body for each request will follow the format described below.

The column ‘ISO-8583 data field’ defines the applicable ‘ISO-defined data elements (ver 1987)’ of ISO-8583, further information on the data format can be found at the https://www.iso.org/standard/79451.html or freely at W ISO 8583 . Note

Base Request Body

FieldPurposeExampleISO-8583 Data Field
stan (system_trace_audit_number)A network reference number that may be used to identify the transaction."000052"10: Conversion rate, cardholder billing
retrieval_reference_numberUnique reference used to retrieve the original message."BFullreve002"37: Retrieval reference number
transmission_date_timeDate and time the message was transmitted to Berkeley"09-15 12:20:30"7: Transmission date & time
advice_reason_codeIndicates the reason the advice is being given."1910000"60: Reserved
acquirer_institiution_codeAcquiring institution32: Acquiring institution identification code
forwarding_institution_codeThe institution forwarding the request if different from acquirer_institiution_code33: Forwarding institution identification code
message_typeISO-8583 Message Type Indicator (described above)"0100"
reversal_typeOnly Applies to Reversal Messages. Indicates that this is a full or partial reversal."full" or "partial"
accountBerkeley cardholder account information
transactionInformation about the client transaction, including amounts, currency codes and transaction dates.
billingWhat the customer will ultimately be billed and the currency the customer will be billed in
card_acceptorWho accepted the card
original_dataOnly Applies to Reversal Messages. Contains values as they were in the original authorization request.
original_approvalOnly Applies to Reversal Messages. The action and approval codes as they were given in the original authorization
replacement_amountsOnly Applies to partial Reversal Messages. The amounts that will be reversed if the reversal is approved

Account

This refers to the account information in the Berkeley system.

FieldPurposeExampleISO-8583 Data Field
account_idBerkeley account Id123
cardholder_idBerkeley card holder Id27
program_idBerkeley program id12

Transaction

For reversals (0400 and 0420) these fields refer to the original transaction.

FieldPurposeExampleISO-8583 Data Field
transaction_typeThe type of transaction requestedOne of:

"purchases_and_services"

"cash_withdrawal"

"money_send_funding"

"manual_cash_advance"

"payment"

"balance_inquiry"

"pin_change_request"

"e_commerce"

"pin_unblock_request"

"money_send_payment"


Or a two character code if the transaction type is unknown to Berkeley
{Under review}
account_type_fromThe account type of the account that the money will be coming fromOne of:

"not_specified"

"savings"

"checking"

"credit_card"

"universal_account"

"carta_internal"


Or a two character code if the account type is unknown to Berkeley
{Under review}
account_type_toThe account type of the account the money will be going to.One of:

"not_specified"

"savings"

"checking"

"credit_card"

"universal_account"

"carta_internal"


Or a two character code if the account type is unknown to Berkeley
{Under review}
amountThe amount of the transaction in lowest currency units1000 for $10.00 in Canadian currency4: Amount Transaction
currency_code"840" for Canadian dollars
local_transaction_date_timeThe date and time the transaction was made"09-15 12:20:30"12 & 13: Local transaction time (hhmmss) Local transaction date (MMDD)
settlement_dateSettlement date of transaction09-1515: Settlement date
merchant_catagory_codeMerchants type of business18: Merchant type, or merchant category code

Billing

For reversals (0400 and 0420) these fields refer to the original transaction.

FieldPurposeExampleISO-8583 Data Field
currency_codeThe currency code that the billing amount is in."840" for Canadian dollars51: Currency code, cardholder billing
amountAmount the customer will be billed in lowest currency unit.1000 for $10.00 in Canadian currency6: Amount, cardholder billing
conversion_rate1.1000010: Conversion rate, cardholder billing
date_conversionThe effective date of conversion_rate09-1516: Currency conversion date

Card Acceptor

For reversals (0400 and 0420) these fields refer to the original transaction.

FieldPurposeExampleISO-8583 Data Field
terminal_id
identification_code
name_location

Original Data

This information displays as part of a reversal request

FieldPurposeExampleISO-8583 Data Field
message_typeISO-8583 Message Type (described above){Under review}
stan (system_trace_audit_number)A network reference number that may be used to identify the transaction.{Under review}
transmission_date_timeDate and time the message was transmitted to Berkeley{Under review}
acquirer_institution_codeAcquiring institution{Under review}
forwarding_institution_codeThe institution forwarding the request if different from acquirer_institiution_code{Under review}

Original Approval

This information displays as part of a reversal request

FieldPurposeExampleISO-8583 Data Field
approval_codeA 6 character code that will identify the authorization. This code should be unique for that day but is not required to be."DEMO10"38: Authorization identification response
action_codeThe action taken for the original transaction"000"39: Response code

Replacement Amounts

This information displays as part of a partial reversal request

FieldPurposeExampleISO-8583 Data Field
transaction_actual_amountTransaction amount to be changed. Currency is in transaction currency.1000 for $10.00 in Canadian currency95: Replacement amounts
settlement_actual_amountSettlement amount to be changed. Currency is in transaction currency.1000 for $10.00 in Canadian currency95: Replacement amounts
cardholder_billing_actual_amountBilling amount to be changed. Currency is in billing currency.1000 for $10.00 in Canadian currency95: Replacement amounts

Response Message Formats

Authorization And Reversal

FieldPurposeExampleISO-8583 Data Field
approval_codeA 6 character code that will identify the authorization. This code should be unique for that day but is not required to be.DEMO10
actionHow the authorization should be handled. Will be used to populate the approval code.One of:

approve

decline

* internal_error

Advice

The response to any advice is always an empty JSON object.

Examples

0100 Authorization

{
   "system_trace_audit_number":"000051",
   "retrieval_reference_number":"000051",
   "transmission_date_time":"07-23 06:11:47",
   "acquirer_institiution_code":"009685",
   "account":{
      "cardholder_id":3,
      "account_id":3,
      "program_id":99
   },
   "message_type":"0100",
   "transaction":{
      "transaction_type":"cash_withdrawal",
      "account_type_from":"not_specified",
      "account_type_to":"not_specified",
      "amount":500,
      "currency_code":"124",
      "local_transaction_date_time":"07-23 06:11:47",
      "settlement_date":"07-23",
      "merchant_catagory_code":"6011"
   },
   "billing":{
      "currency_code":"124",
      "amount":500,
      "conversion_rate":"1.000000",
      "date_conversion":"07-23"
   },
   "card_acceptor":{
      "terminal_id":"Term0004",
      "identification_code":"ID-Code06      ",
      "name_location":"Offsite ATM01          St. Louis      MO"
   }
}

Response

{
    "action": "approve",
    "approval_code": "DEMO10"
}

0120 Authorization Advice

{
   "system_trace_audit_number":"000053",
   "retrieval_reference_number":"000053",
   "transmission_date_time":"07-23 06:12:35",
   "advice_reason_code":"1910000",
   "acquirer_institiution_code":"009685",
   "account":{
      "cardholder_id":3,
      "account_id":3,
      "program_id":99
   },
   "message_type":"0120",
   "transaction":{
      "transaction_type":"cash_withdrawal",
      "account_type_from":"not_specified",
      "account_type_to":"not_specified",
      "amount":500,
      "currency_code":"124",
      "local_transaction_date_time":"07-23 06:12:35",
      "settlement_date":"07-23",
      "merchant_catagory_code":"6011"
   },
   "billing":{
      "currency_code":"124",
      "amount":500,
      "conversion_rate":"1.000000",
      "date_conversion":"07-23"
   },
   "card_acceptor":{
      "terminal_id":"Term0004",
      "identification_code":"ID-Code06      "
   },
   "approval":{
      "action_code":"000"
   }
}

Response

{ }

0400 Full Reversal

{
   "system_trace_audit_number":"000052",
   "retrieval_reference_number":"000052",
   "transmission_date_time":"07-23 06:11:47",
   "acquirer_institiution_code":"009685",
   "account":{
      "cardholder_id":3,
      "account_id":3,
      "program_id":99
   },
   "message_type":"0400",
   "reversal_type":"full",
   "transaction":{
      "transaction_type":"cash_withdrawal",
      "account_type_from":"not_specified",
      "account_type_to":"not_specified",
      "amount":500,
      "currency_code":"124",
      "local_transaction_date_time":"07-23 06:11:47",
      "settlement_date":"07-23",
      "merchant_catagory_code":"6011"
   },
   "billing":{
      "currency_code":"124",
      "amount":500,
      "conversion_rate":"1.000000",
      "date_conversion":"07-23"
   },
   "card_acceptor":{
      "terminal_id":"Term0004",
      "identification_code":"ID-Code06      ",
      "name_location":"Offsite ATM01          St. Louis      MO"
   },
   "original_data":{
      "message_type":"0100",
      "system_trace_audit_number":"000051",
      "transmission_date_time":"07-23 06:11:47",
      "acquirer_institution_code":"00000009685",
      "forwarding_institution_code":"00000000000"
   },
   "original_approval":{
      "action_code":"000"
   }
}

Response

{
    "action": "approve",
    "approval_code": "DEMO10"
}

0400 Partial Reversal

{
   "system_trace_audit_number":"000054",
   "retrieval_reference_number":"000054",
   "transmission_date_time":"07-23 06:12:35",
   "acquirer_institiution_code":"009685",
   "account":{
      "cardholder_id":3,
      "account_id":3,
      "program_id":99
   },
   "message_type":"0400",
   "reversal_type":"partial",
   "transaction":{
      "transaction_type":"cash_withdrawal",
      "account_type_from":"not_specified",
      "account_type_to":"not_specified",
      "amount":500,
      "currency_code":"124",
      "local_transaction_date_time":"07-23 06:12:35",
      "settlement_date":"07-23",
      "merchant_catagory_code":"6011"
   },
   "billing":{
      "currency_code":"124",
      "amount":500,
      "conversion_rate":"1.000000",
      "date_conversion":"07-23"
   },
   "card_acceptor":{
      "terminal_id":"Term0004",
      "identification_code":"ID-Code06      ",
      "name_location":"Offsite ATM01          St. Louis      MO"
   },
   "original_data":{
      "message_type":"0100",
      "system_trace_audit_number":"000053",
      "transmission_date_time":"07-23 06:12:35",
      "acquirer_institution_code":"00000009685",
      "forwarding_institution_code":"00000000000"
   },
   "original_approval":{
      "action_code":"000"
   },
   "replacement_amounts":{
      "transaction_actual_amount":200,
      "settlement_actual_amount":0,
      "cardholder_billing_actual_amount":200
   }
}

Response

{
    "action": "approve",
    "approval_code": "DEMO10"
}

0420 Reversal Advice

{
   "system_trace_audit_number":"000052",
   "retrieval_reference_number":"000052",
   "transmission_date_time":"07-23 06:11:47",
   "acquirer_institiution_code":"009685",
   "account":{
      "cardholder_id":3,
      "account_id":3,
      "program_id":99
   },
   "message_type":"0420",
   "reversal_type":"full",
   "transaction":{
      "transaction_type":"cash_withdrawal",
      "account_type_from":"not_specified",
      "account_type_to":"not_specified",
      "amount":500,
      "currency_code":"124",
      "local_transaction_date_time":"07-23 06:11:47",
      "settlement_date":"07-23",
      "merchant_catagory_code":"6011"
   },
   "billing":{
      "currency_code":"124",
      "amount":500,
      "conversion_rate":"1.000000",
      "date_conversion":"07-23"
   },
   "card_acceptor":{
      "terminal_id":"Term0004",
      "identification_code":"ID-Code06      ",
      "name_location":"Offsite ATM01          St. Louis      MO"
   },
   "original_data":{
      "message_type":"0100",
      "system_trace_audit_number":"000051",
      "transmission_date_time":"07-23 06:11:47",
      "acquirer_institution_code":"00000009685",
      "forwarding_institution_code":"00000000000"
   },
   "original_approval":{
      "action_code":"000"
   }
}

Response

{}

📘

Related pages:

Codes, Statuses and Errors
Card Issuing Certification and Onboarding
Simulate Authorization and Settlement