Control Board - Powered by DigiPro Payments

Control Board Application Programming Interface

Instruction to interface with ControlBoard API

How to register for API access
Authentication
Payer Management
Hosted Payment Page Management
Transaction Management

Request API Access

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

Requesting Your Authentication Token

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

Create new Payer Account

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

Create A New 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.

Get Hosted Payment Page Results

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.

Void/Refund Transaction

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.