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 keyin 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-Signatureheader 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
- Extract the body of the request
- Compute an HMAC using SHA-256 with the body of the request as the message and the
signing keyfound in the client portal as the key. - 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 type | Description |
| 0100 | Authorization (most common type). | Card is used for a transaction. Could be a preauth, auth, ATM, balance inquiry, and so on. |
| 0120 | Authorization Advice | They might not affect the OTB. This could be force posts, completions, tokenization updates, etc. These cannot be declined. |
| 0400 | Reversal | A reversal of a previous auth. Should reference a previous transaction, but is not required to. |
| 0420 | Reversal Advice | They 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
| Field | Purpose | Example | ISO-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_number | Unique reference used to retrieve the original message. | "BFullreve002" | 37: Retrieval reference number |
| transmission_date_time | Date and time the message was transmitted to Berkeley | "09-15 12:20:30" | 7: Transmission date & time |
| advice_reason_code | Indicates the reason the advice is being given. | "1910000" | 60: Reserved |
| acquirer_institiution_code | Acquiring institution | 32: Acquiring institution identification code | |
| forwarding_institution_code | The institution forwarding the request if different from acquirer_institiution_code | 33: Forwarding institution identification code | |
| message_type | ISO-8583 Message Type Indicator (described above) | "0100" | |
| reversal_type | Only Applies to Reversal Messages. Indicates that this is a full or partial reversal. | "full" or "partial" | |
| account | Berkeley cardholder account information | ||
| transaction | Information about the client transaction, including amounts, currency codes and transaction dates. | ||
| billing | What the customer will ultimately be billed and the currency the customer will be billed in | ||
| card_acceptor | Who accepted the card | ||
| original_data | Only Applies to Reversal Messages. Contains values as they were in the original authorization request. | ||
| original_approval | Only Applies to Reversal Messages. The action and approval codes as they were given in the original authorization | ||
| replacement_amounts | Only 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.
| Field | Purpose | Example | ISO-8583 Data Field |
| account_id | Berkeley account Id | 123 | |
| cardholder_id | Berkeley card holder Id | 27 | |
| program_id | Berkeley program id | 12 |
Transaction
For reversals (0400 and 0420) these fields refer to the original transaction.
| Field | Purpose | Example | ISO-8583 Data Field |
| transaction_type | The type of transaction requested | One 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_from | The account type of the account that the money will be coming from | 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} |
| account_type_to | The 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} |
| amount | The amount of the transaction in lowest currency units | 1000 for $10.00 in Canadian currency | 4: Amount Transaction |
| currency_code | "840" for Canadian dollars | ||
| local_transaction_date_time | The date and time the transaction was made | "09-15 12:20:30" | 12 & 13: Local transaction time (hhmmss) Local transaction date (MMDD) |
| settlement_date | Settlement date of transaction | 09-15 | 15: Settlement date |
| merchant_catagory_code | Merchants type of business | 18: Merchant type, or merchant category code |
Billing
For reversals (0400 and 0420) these fields refer to the original transaction.
| Field | Purpose | Example | ISO-8583 Data Field |
| currency_code | The currency code that the billing amount is in. | "840" for Canadian dollars | 51: Currency code, cardholder billing |
| amount | Amount the customer will be billed in lowest currency unit. | 1000 for $10.00 in Canadian currency | 6: Amount, cardholder billing |
| conversion_rate | 1.10000 | 10: Conversion rate, cardholder billing | |
| date_conversion | The effective date of conversion_rate | 09-15 | 16: Currency conversion date |
Card Acceptor
For reversals (0400 and 0420) these fields refer to the original transaction.
| Field | Purpose | Example | ISO-8583 Data Field |
| terminal_id | |||
| identification_code | |||
| name_location |
Original Data
This information displays as part of a reversal request
| Field | Purpose | Example | ISO-8583 Data Field |
| message_type | ISO-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_time | Date and time the message was transmitted to Berkeley | {Under review} | |
| acquirer_institution_code | Acquiring institution | {Under review} | |
| forwarding_institution_code | The institution forwarding the request if different from acquirer_institiution_code | {Under review} |
Original Approval
This information displays as part of a reversal request
| Field | Purpose | Example | ISO-8583 Data Field |
| approval_code | A 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_code | The action taken for the original transaction | "000" | 39: Response code |
Replacement Amounts
This information displays as part of a partial reversal request
| Field | Purpose | Example | ISO-8583 Data Field |
| transaction_actual_amount | Transaction amount to be changed. Currency is in transaction currency. | 1000 for $10.00 in Canadian currency | 95: Replacement amounts |
| settlement_actual_amount | Settlement amount to be changed. Currency is in transaction currency. | 1000 for $10.00 in Canadian currency | 95: Replacement amounts |
| cardholder_billing_actual_amount | Billing amount to be changed. Currency is in billing currency. | 1000 for $10.00 in Canadian currency | 95: Replacement amounts |
Response Message Formats
Authorization And Reversal
| Field | Purpose | Example | ISO-8583 Data Field |
| approval_code | A 6 character code that will identify the authorization. This code should be unique for that day but is not required to be. | DEMO10 | |
| action | How the authorization should be handled. Will be used to populate the approval code. | One of:approvedecline* 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