BluePay 2.0 POST Method for Rebilling Updates
For automated integration. This interface is NOT for Posting directly from a web form!

Last Updated: 2021-02-26

The URL of this interface is currently:
https://secure.bluepay.com/interfaces/bp20rebadmin

PLEASE NOTE: This URL may change in the future. In integrating your system, please remember to 
make the URL a parameter you can easily change. If you are coding a shopping cart, please make 
the URL a parameter the merchant can easily set.

REQUEST FORMAT:
Expected input format is that of a standard HTTPS POST. All parameters are uri-encoded in the 
body of the request, for example:

### BEGIN REQUEST EXAMPLE ###
POST https://secure.bluepay.com/interfaces/bp20rebadmin
Content-Type: application/x-www-form-urlencoded

ACCOUNT_ID=123412341234&REBILL_ID=4321432143214321&TRANS_TYPE=GET
### END REQUEST EXAMPLE ###

RESPONSE FORMAT:
Expected output is that of a standard HTTPS response. The HTTP Status will be '200' for a 
successfully-processed request and '400' for an error. All response parameters are uri-encoded 
in the body of the response, for example:

### BEGIN RESPONSE EXAMPLE ###
HTTP/1.1 200 OK
Cache-Control: max-age=0
Connection: close
Date: Tue, 07 Dec 2004 17:31:12 GMT
Server: Apache
Content-Type: text/html; charset=ISO-8859-1
Expires: Tue, 07 Dec 2004 17:31:12 GMT

rebill_id=123123123123&account_id=321321321321&user_id=321123321123&status=active
### END RESPONSE EXAMPLE ###

Input Parameters are:

ACCOUNT_ID        = Your 12-digit BluePay 2.0 Account ID
USER_ID           = Optional. Your 12-digit BluePay 2.0 User ID
REBILL_ID         = Required. The 12-digit ID of the Rebilling to modify/view
TAMPER_PROOF_SEAL = Hash for security, using selected algorithm (either TPS_HASH_TYPE or 
                    account's 'Hash Type in APIs' value). See TAMPER_PROOF_SEAL section below 
                    for more details. 
TPS_DEF           = **  NOTICE: THE USE OF THIS FIELD CAN POSSIBLY WEAKEN YOUR SECURITY. PLEASE 
                        BE SURE YOU UNDERSTAND HOW THE TAMPER_PROOF_SEAL WORKS BEFORE YOU 
                        CONSIDER USING THIS OPTION. ** 
                    Optional. Space-separated list of input field names in the order they are 
                    to be used in the calculation of the TAMPER_PROOF_SEAL. If set as blank or 
                    not sent, it will default to: "ACCOUNT_ID TRANS_TYPE REBILL_ID". The 
                    merchant's Secret Key is always used in the calculation of the 
                    TAMPER_PROOF_SEAL, but should NOT be included in the TPS_DEF. See 
                    TAMPER_PROOF_SEAL section below for more details. 
TPS_HASH_TYPE     = Optional. The algorithm used to compute the TAMPER_PROOF_SEAL. Accepted 
                    values are 'MD5', 'SHA256', 'SHA512', 'HMAC_SHA256', or 'HMAC_SHA512'. 
                    Merchant's 'Hash Type in APIs' value is used if this parameter is not 
                    present. See TAMPER_PROOF_SEAL section below for more details. 
TRANS_TYPE        = Optional. GET or SET (defaults to SET)
                    If set to GET, then you are only required to send the ACCOUNT_ID, 
                    TAMPER_PROOF_SEAL, and REBILL_ID.
                    If "SET" then you must also send at least one field, below, to set the 
                    value of:
  
TEMPLATE_ID       = Optional - selects a new transaction ID to act as the template for this 
                               rebilling sequence.
CUST_TOKEN        = Optional - selects a new Customer Token to act as the template for this 
                               rebilling sequence.
NEXT_DATE         = Set the next rebill date to this date.
REB_EXPR          = Set the rebilling expression to this expression.
REB_CYCLES        = Set the number of remaining rebilling cycles to this number.
REB_AMOUNT        = Set the regular rebilling amount to this amount.
NEXT_AMOUNT       = Set the *next* rebilling only to this amount; all other rebillings will 
                    continue at the regular (REB_AMOUNT) amount.
STATUS            = Set the status of this rebilling. Valid statuses at the time of writing are:
                      active:  Rebilling profile will create new transactions as scheduled
                      deleted: The rebilling profile has been disabled from either the BluePay 
                               gateway website or the bp20rebadmin API. It is no longer visible 
                               in the BluePay gateway website.
                      stopped: The rebilling profile has been disabled from either the BluePay 
                               gateway website or the bp20rebadmin API.
                      expired: The rebilling profile was for a fixed number of cycles and those 
                               cycles have been completed.
                      failed:  The last transaction created by the rebilling profile was declined. 
                               No more transactions will be created until the status is changed 
                               back to active. ( Optionally declined transactions can be retried 
                               for a defined number of times before the status is changed to 
                               failed. The default is no retries. Contact 
                               bluepayintegration@fiserv.com if retries are needed.)
                      error:   The last transaction created by the rebilling profile had an error. 
                               The most common error is that the card has expired. No more 
                               transactions will be created until the status is changed back to 
                               active.



Output Parameters are returned for GET and SET transactions - if you perform a SET, the 
returned parameters should reflect your changes:

REBILL_ID     = The 12-digit ID specifying this rebilling.
ACCOUNT_ID    = The 12-digit ID of the account owning this rebilling.
USER_ID       = The 12-digit ID of the user owning this rebilling.
TEMPLATE_ID   = The 12-digit ID of the template for this rebilling.
CUST_TOKEN    = The 6-16 character Customer Token used as a template for this rebilling.
STATUS        = The current status of the rebilling
CREATION_DATE = The date the rebilling sequence was originally created.
NEXT_DATE     = The next day this rebilling will be run.
LAST_DATE     = The last day this rebilling was run.
SCHED_EXPR    = The current rebilling expression for this rebilling
CYCLES_REMAIN = The number of remaining rebilling cycles for this rebilling.
REB_AMOUNT    = the regular amount this rebilling will charge the customer.
NEXT_AMOUNT   = The amount this rebilling will charge on the next billing only.

Output HTTP status code is 200 for a successfully processed request.
Output HTTP status code is 400 for an error request.


###############################
# TAMPER_PROOF_SEAL 
###############################

BluePay uses cryptographic hash (or "digest") functions as a means of both protecting 
transaction data from being altered and ensuring that the transaction is genuine. A 
cryptographic hash function is an algorithm that maps data of any size to a bit string of a 
fixed size that cannot be deciphered. 

All merchants have a default hash type assigned to their account. This can be viewed and 
updated on the merchant's Account Admin page of BluePay's Gateway (https://secure.bluepay.com) 
under "Hash Type in APIs". Merchants may override their default by including the TPS_HASH_TYPE 
field in the transaction request. 

The default hash type and the TPS_HASH_TYPE may be any of the following algorithms (in 
hexadecimal form):

MD5           Use md5sum or a similar program to calculate a 128-bit hash, then convert it 
              into hexadecimal form; result is 32 hexadecimal characters.
SHA256        Use sha256sum or a similar program to calculate a 256-bit hash, then convert it 
              into hexadecimal form; result is 64 hexadecimal characters.
SHA512        Use sha512sum or a similar program to calculate a 512-bit hash, then convert it 
              into hexadecimal form; result is 128 hexadecimal characters.

HMAC_SHA256   A 128-bit hash, resulting in a sequence of 64 hexadecimal characters.
HMAC_SHA512   A 128-bit hash, resulting in a sequence of 128 hexadecimal characters.

Steps to find the HMAC of either SHA256 (HMAC_SHA256) or SHA512 (HMAC_SHA512):

1. Compare the length of the key (the merchant's Secret Key) to the hash's input blocksize.
   SHA256 blocksize = 64, SHA512 blocksize = 128.
   If length of key is > blocksize, set the key's value to the hash of the original key.
   If length of key is < blocksize, pad the key to the right with zeros until its length 
   equals the blocksize.

2. Create the inner key (inner_key):
   Create an inner padding value of 0x36 repeated the blocksize number of times.
   Perform a bitwise exclusive-OR (XOR) on the key and the inner padding to create the inner 
   key.

3. Create the outer key (outer_key):
   Create an outer padding value of 0x5c repeated the blocksize number of times.
   Perform a bitwise exclusive-OR (XOR) on the key and the outer padding to create the outer 
   key.

4. Calculate the hash of the inner key concatenated with the text string, then calculate the 
   hash of the outer key concatenated with the previous hash result:
   hash(outer_key + hash(inner_key + string))

5. Convert the result into a hex string.
 
When using a program or function to calculate the TAMPER_PROOF_SEAL, make sure that it will 
accept a text string (or "message") argument and will return the hashed string (or "message 
digest") in hexadecimal form. 


####################################
# Calculating the TAMPER_PROOF_SEAL
####################################

STEP ONE
Concatenate the values of the fields that make up the TPS_DEF in same order that they are 
listed. Use ""(empty string - no space) as the value for any fields that are empty or 
unsent. When no TPS_DEF is sent ('+' represents string concatenation, and the field names 
represent the contents of the respective fields):

message  = ACCOUNT_ID + TRANS_TYPE + REBILL_ID

STEP TWO
- If TPS_HASH_TYPE is "" or is not sent, the merchant's 'Hash Type in APIs' value will 
  determine which hash function to use.

- If TPS_HASH_TYPE is 'MD5', 'SHA256', or 'SHA512', find the md5sum, sha256sum, or sha512sum 
  of (the merchant's Secret Key + message) in hex format.

- If TPS_HASH_TYPE is 'HMAC_SHA256' or 'HMAC_SHA512', find the HMAC_SHA256 or HMAC_SHA512 of 
  (the merchant's Secret Key, message) in hex format.


EXAMPLE:
Merchant A's account information is as follows:
  Secret Key = "abcdabcdabcdabcd"
  ACCOUNT_ID = "123412341234"
  Hash Type in APIs (default hash type) = "MD5"

If Merchant A set their TPS_DEF to "ACCOUNT_ID TRANS_TYPE STATUS REBILL_ID" and wanted to view 
the rebilling with ID 987654321012, the request would include:
  TPS_DEF = "ACCOUNT_ID TRANS_TYPE STATUS REBILL_ID"
  ACCOUNT_ID = "123412341234"
  REBILL_ID = "987654321012"
  TRANS_TYPE = "GET"

To calculate the TAMPER_PROOF_SEAL, Merchant A would need to:

STEP ONE
Concatenate the values in the TPS_DEF to create a message string. Remember, if the field isn't 
sent or if the value is undefined, use an empty string as that field's value.
message  = ACCOUNT_ID + TRANS_TYPE + STATUS + REBILL_ID
         = "123412341234" + "GET" + "" + "987654321012" 
         = "123412341234GET987654321012"

STEP TWO
This step will vary depending on which TPS_HASH_TYPE is sent (if any).

-- If TPS_HASH_TYPE = "" or was not sent, the merchant's default hash type must be used
TAMPER_PROOF_SEAL = md5sum( Secret Key + message ) in hex format
                  = md5sum("abcdabcdabcdabcd" + "123412341234GET987654321012") in hex format 
                  = "8b9505fa795955e67497cac8197cc686"

-- If TPS_HASH_TYPE = "SHA256"
TAMPER_PROOF_SEAL = sha256sum( Secret Key + message ) in hex format
                  = sha256sum("abcdabcdabcdabcd" + "123412341234GET987654321012") in hex format
                  = "354eae0f02c2c51d970768640bac1f2ecdb87995c593c781aac1c8d5cb9a4410"

-- If TPS_HASH_TYPE = "HMAC_SHA256"
TAMPER_PROOF_SEAL = HMAC_SHA256( Secret Key, message ) in hex format
                  = HMAC_SHA256("abcdabcdabcdabcd", "123412341234GET987654321012") in hex format
                  = "8e6238abf3ad6343df368eb2d50325b1a362cb5a9c935131c90a4b1be7269315"