Control Board Application Programming Interface

Instruction to interface with ControlBoard API

Control Board API User Accounts

Control Board is a robust payments interface that utilizes ProPay merchant accounts to process credit cards.

Currently we offer Hosted Payment Pages so as to allow our customers to not have to worry about meeting PCI compliance standard.

Because of the nature of our API we require all customers interested in using our API to complete a User Account Request Form.

Once access has been requested, we will review your request, and if approved, we will reach out to you with your account credentials and instructions.

Request Access
How to call this method

HTTP URL(s)      https://controlboardapi.com/api/login

HTTP Verb         POST

HTTP Header    Authorization

Example Request

Multipart Form Request:
     "email" => "your_email_address_here"
     "password" => "your_password_here"

Example Response

{
    "access_token":"123456789asbcdef123",
    "token_type":"Bearer",
}

Request Values

Request Element Type Required Notes
email String Required
password String Required

Response Values

Response Element Type Notes
access_token String Store this token in a safe place, it will be used for every API call made
token_type String This is the authorization type our API requires

How to call this method

HTTP URL(s)      https://controlboardapi.com/api/payer/new

HTTP Verb         POST

HTTP Header    Authorization

Example Request

{
    "name":"John Doe",
    "email":"johndoe@testdomain.com",
    "testMode":true,
    "billerId": "1234567890987654",
    "authToken":"abc123ab-a1b2-c2d4-e5f6-123abc456def"
}

Example Response

{
    "status":"SUCCESS",
    "payerId":"1234567887654321",
}

Request Values

Request Element Type Required Notes
authToken String Required Authentication Token provided by Propay
billerId String Required Biller Id provided by Propay
name String Required Name of the customer that is paying
email String Required Email of the customer that is paying
testMode Boolean Optional Is testMode is true, then the request will be make to the testing account and not create a live payer account

Response Values

Response Element Type Notes
status String Value will be either "SUCCESS" or "FAILURE".

If value returned is "Failure" three additional response values will be present.

"errorCode", "errorMessage", "errorDetail". All error responses are tpye String.
payerId String PayerId string used when creating a hosted payment page

How to call this method

HTTP URL(s)      https://controlboardapi.com/api/hpp/new

HTTP Verb         POST

HTTP Header    Authorization

Example Request

{
    "billerId": "1234567890987654",
    "authToken":"abc123ab-a1b2-c2d4-e5f6-123abc456def"
    "PayerAccountId":1234567887654321,
    "MerchantProfileId":123456,
    "Amount":150,
    "CurrencyCode":"USD",
    "InvoiceNumber":"496d0ca5-48b9-4aca-afca-5d7094c212e2",
    "Comment1":"PropaySdkCreateHostedTransaction 1",
    "Comment2":"PropaySdkCreateHostedTransaction 2",
    "CardHolderNameRequirementType":1,
    "SecurityCodeRequirementType":1,
    "AvsRequirementType":1,
    "AuthOnly":true,
    "ProcessCard":true,
    "StoreCard":true,
    "OnlyStoreCardOnSuccessfulProcess":true,
    "CssUrl":"https://yourdomain.com/custom-style.css",
    "FraudDetectors":null,
    "PaymentTypeId":0,
    "Protected":false,
    "ReturnURL":"http://www.yourdomain.com/your-result-page"
    "testMode":true
}

Example Response

{
    "status":"SUCCESS",
    "HostedTransactionIdentifier":"abcd-123-efgh-4567-asdfjkl",
    "PaymentPageUrl":"https://protectpay.propay.com/hpp/v2/abcd-123-efgh-4567-asdfjkl",
}

Request Values

Request Element Type Required Notes
authToken String Required Authentication Token provided by Propay when initially creating the merchant account
billerId String Required Biller Id provided by Propay when initially creating the merchant account
PayerAccountId Long Required The Payer under which the PaymentMethodId should be created under.

This is the payerId value returned from our /api/payer/new endpoint.
MerchantProfileId Long Required Used to specify which processor and merchant account to process the transaction against.

This is provided from ProPay when initially creating the merchant account
Amount Integer Required The value representing the number of pennies in USD, or the number of [currency] without decimals.
CurrencyCode String Required ISO 4217 standard 3 character currency code.
InvoiceNumber String Optional Highly recommended. Transaction descriptor-only passed if supported by the gateway.
Comment1 String Optional Comment 1 to be displayed to the user on the Hosted Page.
Comment2 String Optional Comment 2 to be displayed to the user on the Hosted Page.
CardHolderNameRequirementType Integer Required Indicates if the 'CardHolderName' section should be required, optional, or hidden.
1= CH Name displayed, required
2= CH Name displayed, optional
3=CH Name hidden
SecurityCodeRequirementType Integer Required Indicates if the 'SecurityCode' section should be required, optional, or hidden.
1=CVV displayed, required
2=CVV displayed, optional
3=CVV hidden
AvsRequirementType Integer Required Indicates if the 'AVS' section should be required, optional, or hidden.
1=AVS displayed, required
2=AVS displayed, optional
3=AVS hidden
AuthOnly Boolean Required* Valid values are:
true
false

Authorize the card transaction. This property is ignored if the "ProcessCard" property is true.
ProcessCard Boolean Required* Valid values are:
true
false

Process (authorize and capture) the card transaction. This property is ignored if the "AuthOnly" property is true.
StoreCard Boolean Required* Valid values are:
true
false

Always store the card information. This is ignored if the "OnlyStoreCardOnSuccessfulProcess" property is true.
OnlyStoreCardOnSuccessfulProcess Boolean Required* Valid values are:
true
false

Only stored the card information if the card transaction was successful.

* This is ignored if the "StoreCard" property is set to true
CssUrl String Optional The fully qualified URL to use for the CSS that drives the look of the page.

Must be hosted HTTPS

Sending empty value removes default style
FraudDetectors Object Optional Please See ProtectPay ProtectPay Appendix A for details concerning the FrauddetectorsObject
PaymentTypeId String Required Valid Values are:
0=credit card
1=ACH

If set to 1 overrides display options and displays Name and ACH field only
ReturnURL String Optional The fully qualified URL to redirect once transaction is completed.

* Sending an empty value will not allow to perform a transaction.
testMode Boolean Optional Is testMode is true, then the request will return a hosted payment page that can be used for testing purposes only

Response Values

Response Element Type Notes
status String Value will be either "SUCCESS" or "FAILURE".

If value returned is "Failure" three additional response values will be present.

"errorCode", "errorMessage", "errorDetail". All error responses are tpye String.
HostedTransactionIdentifier String This is the unique ID set for the payment page created using the setting provided in this request
PaymentPageUrl String You will need to redirect your customers to this URL after a successful request. This is the URL where the customer will be able to complete their payment.

How to call this method

HTTP URL(s)      https://controlboardapi.com/api/hpp/results

HTTP Verb         POST

HTTP Header    Authorization

Example Request

{
    "billerId": "1234567890987654",
    "authToken":"abc123ab-a1b2-c2d4-e5f6-123abc456def"
    "hostedTransactionInfo":abcd-123-efgh-4567-asdfjkl,
}

Example Response

{
    "status":"SUCCESS",
    "transactionData":{
        "CreationDate":"2021-11-15T14:48:07.1532326",
        "HostedTransactionIdentifier":"ae7eb1d2-a3496-4124-995x-2d38ec27bb21",
        "PayerId":123456789,
        "TransactionResultMessage":"",
        "AuthCode":"A11111",
        "TransactionHistoryId":2900619,
        "TransactionId":"5",
        "TransactionResult":"00",
        "AvsResponse":"T",
        "PaymentMethodInfo":{
            "PaymentMethodID":"dfa321sa-fda2-csa3-9316-821ac63dfc82f8",
            "PaymentMethodType":"Visa",
            "ObfuscatedAccountNumber":"474747******4747",
            "ExpirationDate":"0422",
            "AccountName":"John Doe",
            "BillingInformation":{
                "Address1":"123 Anywhere St",
                "Address2":"",
                "Address3":"",
                "City":"Anytown",
                "State":"CA",
                "ZipCode":"90210",
                "Country":"USA",
                "TelephoneNumber":"",
                "Email":""
            },
            "Description":"",
            "Priority":1,
            "DateCreated":"2021-11-15T14:48:06.84",
            "Protected":false
        },
        "GrossAmt":150,
        "NetAmt":110,
        "PerTransFee":35,
        "Rate":3.5,
        "GrossAmtLessNetAmt":40,
        "CVVResponseCode":"M",
        "CurrencyConversionRate":1,
        "CurrencyConvertedAmount":150,
        "CurrencyConvertedCurrencyCode":840
    }
}

Request Values

Request Element Type Required Notes
authToken String Required Authentication Token provided by Propay when initially creating the merchant account
billerId String Required Biller Id provided by Propay when initially creating the merchant account
hostedTransactionInfo String Required This is the HostedTransactionIdentifier from our /api/hpp/new endpoint.

Response Values

Response Element Type Notes
status String Value will be either "SUCCESS" or "FAILURE".

If value returned is "Failure" three additional response values will be present.

"errorCode", "errorMessage", "errorDetail". All error responses are tpye String.
HostedTransactionIdentifier String This is the unique ID set for the payment page created using the setting provided in this request
PaymentPageUrl String You will need to redirect your customers to this URL after a successful request. This is the URL where the customer will be able to complete their payment.

How to call this method

HTTP URL(s)      https://controlboardapi.com/api/transaction/voidRefund

HTTP Verb         POST

HTTP Header    Authorization

Example Request

{
    "certStr": "abcde1234asdf234asdc234",
    "termid":"a123b",
    "accountNum":01234565,
    "transNum":5
}

Example Response

{
    "status":"SUCCESS",
    "payerId":"1234567887654321",
}

Request Values

Request Element Type Required Notes
certStr String Required certStr provided by Propay when merchant account was created
termid String Required termid provided by Propay when merchant account was created
accountNum String Required Account number provided by Propay when merchant account was created
transNum String Required This is the transaction id to be cancelled or voided. There is no need to specify if the transaction needs to be cancelled or voided. The API will determine this for you based on the current status of the transaction. If the transaction number returned in the API response is the SAME then it was VOIDED, if a new transaction number is provided in the API response than the transaction was refunded, and the refund transaction id was returned to you.
testMode Boolean Optional Is testMode is true, then the request will be make to the testing account a live refund or void will not take place

Response Values

Response Element Type Notes
status String Value will be either "SUCCESS" or "FAILURE".

If value returned is "Failure" three additional response values will be present.

"errorCode", "errorMessage", "errorDetail". All error responses are tpye String.
type String This will either be Void or Refund.
transNum Integer If the transaction number returned in the API response is the SAME then it was VOIDED, if a new transaction number is provided in the API response than the transaction was refunded, and the refund transaction id was returned to you.