API Credentials

Brick provides you with the following API credentials:

Public API Key - used for building the Frontend credit card form. This can be publicly available to your end-users.

Private API Key - used for charging cards from your backend. Keep this private at all times.

A pair of test API keys can be retrieved further at this page or by Signing Up.

Step 1: Front End

To charge a credit card, you will first need to collect the credit card details from the end-user and pass them to your backend. Brick helps you to do this in a PCI DSS compliant manner by creating a one-time token that you can further use to charge the card on Step 2.

Please note: payment pages are required to be loaded via https:// (At least TLSv1.1 is recommended).

The code sample below will build the credit card form (or add event listeners to your own custom form) and will tokenize the credit card data once the form is submitted and then will send the token to your backend controller specified by action parameter. More details about the client-side library for tokenization can be found in Brick.js documentation.

script src="https://api.paymentwall.com/brick/brick.1.3.js"> </script>
<div id="payment-form-container"> </div>
        <script>
var brick = new Brick({
    public_key: 'YOUR_PUBLIC_API_KEY',
    amount: 9.99,
    currency: 'USD',
    container: 'payment-form-container',
    action: 'billing.php',
    form: {
        merchant: 'Merchant Name',
        product: 'Product Name',
        pay_button: 'Pay'
    }
});

brick.showPaymentForm(function(data) {
    // handle success
}, function(errors) {
    // handle errors
});
</script>

<script src="https://api.paymentwall.com/brick/brick.1.3.js"> </script>
<form id="brick-creditcard-form" action="billing.php" method="POST">
<input name="custom_parameter" type="hidden" value="custom_value"/>
<div>
    <label>
        <span>Card number</span>
        <input data-brick="card-number" type="text"/>
    </label>
</div>
<div>
    <label>
        <span>Card expiration</span>
        <input data-brick="card-expiration-month" type="text" size="2"/> /
        <input data-brick="card-expiration-year" type="text" size="4"/>
    </label>
</div>
<div>
    <label>
        <span>Card CVV</span>
        <input data-brick="card-cvv" type="text"/>
    </label>
</div>
<button type="submit">Submit</button>
</form>
<script>
Brick({public_key: 'YOUR_PUBLIC_API_KEY', form: {id: 'brick-creditcard-form'}, onTokenized: function() {/* submit form */}, onError: function(errors) {/* show errors */}}, 'custom');
</script>

<script src="https://api.paymentwall.com/brick/brick.1.3.js"> </script>
<form id="brick-creditcard-form" action="billing.php" method="POST">
<input name="custom_parameter" type="hidden" value="custom_value"/>
<div>
    <label>
        <span>Card number</span>
        <input data-brick="card-number" type="text" id="card-number"/>
    </label>
</div>
<div>
    <label>
        <span>Card expiration</span>
        <input data-brick="card-expiration-month" type="text" size="2" id="card-exp-month"/> /
        <input data-brick="card-expiration-year" type="text" size="4" id="card-exp-year"/>
    </label>
</div>
<div>
    <label>
        <span>Card CVV</span>
        <input data-brick="card-cvv" type="text" id="card-cvv"/>
    </label>
</div>
<button type="submit">Submit</button>
</form>
<script>
// using jQuery
var $form = $('#brick-creditcard-form');
var brick = new Brick({
    public_key: 'YOUR_PUBLIC_API_KEY',
    form: { formatter: true }
}, 'custom');

$form.submit(function(e) {
    e.preventDefault();

    $form.find('button').prop('disabled', true);

    brick.tokenizeCard({
        card_number: $('#card-number').val(),
        card_expiration_month: $('#card-exp-month').val(),
        card_expiration_year: $('#card-exp-year').val(),
        card_cvv: $('#card-cvv').val()
    }, function(response) {
        if (response.type == 'Error') {
            // handle errors
        } else {
            $form.append($('<input type="hidden" name="brick_token"/>').val(response.token));
            $form.append($('<input type="hidden" name="brick_fingerprint"/>').val(Brick.getFingerprint()));
            $form.get(0).submit();
        }
    });

    return false;
});
</script>

Step 2: Back End

Below is the code sample for your backend script (billing.php) that uses the credit card token obtained on Step 1 to charge the card. The code sample below uses Brick PHP Library.


12345678910
11121314151617181920212223
232425262728293031


require_once 'path/to/lib/paymentwall.php';
Paymentwall_Config::getInstance()->set(array(
    'private_key' => 'YOUR_PRIVATE_KEY'
));

$parameters = $_POST;
$cardInfo = array(
    'email' => $parameters['email'],
    'amount' => 9.99,
    'currency' => 'USD',
    'token' => $parameters['brick_token'],
    'fingerprint' => $parameters['brick_fingerprint'],
    'description' => 'Order #123'
);

$charge = new Paymentwall_Charge();
$charge->create($cardInfo);
$response = $charge->getPublicData();

if ($charge->isSuccessful()) {
    if ($charge->isCaptured()) {
        // deliver a product
    } elseif ($charge->isUnderReview()) {
        // decide on risk charge
    }
} else {
    $errors = json_decode($response, true);
}

echo $response;

Step 3: Testing

Using your Test API Keys available in your merchant area upon activating Brick, you can use one of the cards below for performing tests:

4242424242424242

4000000000000002

Test CVV/CSC values:

Value	Outcome
111	Error: Please ensure the CVV/CVC number is correct before retrying the transaction.
222	Error: Please contact your credit card company to check your available balance.
333	Error: Please contact your credit card company to approve your payment.
555	Payment is under risk review. Payment is accepted after 2 minutes and respective pingback is sent (type=201). See Preventing Fraud.
556	Payment is under risk review. Payment is declined after 2 minutes and respective pingback is sent (type=202). See Preventing Fraud.
Other	Success

Brick.js

Brick.js is a powerful JavaScript library for building Brick standard credit card forms, tokenizing credit card data, adding submit listeners for tokenizing your custom credit card forms, as well as generating fingerprints for risk scoring.

Brick(options[, type])

Initializes Brick.js

options - required - object - list of options for Brick.js:.

public_key - required - Your project's Public Key

container - required - ID of the container where payment form will be placed

amount - required - Payment amount

currency - required - Payment currency

action - required - Pyment form action URL

form - optional - Payment form configuration object

id - optional - ID of the pyment form. Used for one-line tokenization of custom forms

merchant - Your company name

product - Your product name

pay_button - Text for submit button

lang - optional - ISO alpha-2 language code to localize the payment form into

onTokenized(data) - optional - Callback after custom payment form is tokenized and hidden inputs brick_token and brick_fingerprint are added to the form. Used for one-line tokenization of custom forms.

data - optional - object - Data format is similar to response from Tokenization API.

onError(errors) - optional - Callback for errors that occurred during one-line tokenization.

errors - optional - object - Returns error response object. For example, {"success": "0", "error": {"code": "3004", "message": "Expiration month is invalid"}}

type - optional - payment form type. Possible value: default, custom

Brick.showPaymentForm(onSuccess, onError)

onSuccess(data) - required - object - Callback on successful payment

data - optional - object - Returns object. For example, {"success": "1"}

onError(errors) - required - Callback when something went wrong

errors - optional - object - Returns error response object. For example, {"success": "0", "error": {"code": "3004", "message": "Expiration month is invalid"}}

Brick.tokenizeCard(data, callback)

data - required - Tokenization data. Possible values: HTMLElement | jQuery object | JavaScript Object // HTMLElement

document.getElementById('my-payment-form') // JavaScript object
card_number - Card number
card_expiration - Card expiration date. Format (MM / YY), for example: "10 / 22"
card_expiration_month - Card expiration month
card_expiration_year - Card expiration year
card_cvv - Card CVV

callback(data) - required - Callback returning tokenization data on success.

data - optional - object - Data format is similar to response from Tokenization API

Brick.localize(form, language, options)

Localizes a custom payment form.

form - required - Payment form HTML Element / jQuery element
language - optional - string - Language used for translations. Available options: 'de', 'ja', 'fr'. English is set by default.
options - optional - object - Config for translations. Format: {element: 'label|span|div', position: 'adjacent|inner'}

API Reference

Authentication

HTTP Header

All API endpoints except One-time Token expect the Private API key to be sent as custom HTTP header "X-ApiKey". For example, "X-ApiKey: YOUR_PRIVATE_KEY". The API libraries supporting Brick automatically add this API header.

Please note that the Private API key can only be used for server-to-server calls and should never be exposed to end-users. For this reason One-time Token API accepts Public API key via public_key parameter instead of the Private API key header. Paymentwall is also expecting header Content-Type: application/x-www-form-urlencoded Client-side libraries supporting Brick automatically add X-ApiKey and Content-Type into API requests.

One-Time Token

Create a One-Time Token

This section describes how to create a one-time token that can be used for charging a card. The one-token is valid for 5 minutes to further perform a charge.

One-time token can be created utilizing Brick.js - see Step 1: Frontend. Alternatively, for merchants who are PCI DSS compliant, the API below can be used.

Request
POST https://pwgateway.com/api/token
(If you're using test keys - POST https://api.paymentwall.com/api/brick/token)

Parameter	Description
public_key	Merchant's public API key
card[number]	Card number, digits only
card[exp_month]	Expiration month, 2 digits from 01 to 12
card[exp_year]	Expiration year, 4 digits
card[cvv]	CVC/CVV, 3-4 digits

Simple Request


curl https://pwgateway.com/api/token \
-d "public_key=YOUR_PUBLIC_API_KEY" \
-d "card[number]=4000000000000002" \
-d "card[exp_month]=01" \
-d "card[exp_year]=2021" \
-d "card[cvv]=123"

Sample Response - Success


{  
  "type":"token",
  "token":"dc71be025bdcbc2c538e8dca871a8e7b",
  "expires_in":290,
  "active":1,
  "card":{  
    "type":"Visa",
    "last4":"0002",
    "bin":"400000",
    "exp_month":"01",
    "exp_year":"2020"
  }
}

Sample Response - Error


{  
  "type":"Error",
  "error":"Card number is empty or invalid",
  "code":224
}

One-Time Token Error Codes

200 - Submited request is empty
223 - Expiration date is empty or invalid
224 - Card number is empty or invalid
225 - CVV is empty or invalid
231 - Internal Error
700 - Internal Error
2111 - Public key is missed or invalid

Charge

Create a Charge

Request
POST https://api.paymentwall.com/api/brick/charge

parameter	required	description
amount	yes	Amount to be charged, positive decimal, no commas. E.g. 9999.99
currency	yes	Code of the currency to be charged in ISO 4217 format
browser_ip	yes, if no fingerprint	End-user's IP address
browser_domain	yes, if no fingerprint	Domain of the website where the payment is originating from
custom	no	Array of custom parameters, e.g. custom[field1]=1, custom[field2]=2. To receive these values via Pingbacks, please add Custom Pingback Parameter with name=custom and value=OWN
description	yes	Description for the payment
email	yes	End-user's email
fingerprint	yes	Brick-generated unique fingerprint of a purchase, used for fraud protection as well as advanced analytics. This field is automatically added as a hidden field to your credit card form when brick.js is used on frontend
lang	no	ISO alpha-2 language code for email receipt localization, supported languages
options[capture]	no	Whether or not to immediately capture the charge. Default is true
plan	no	Identifies the product ID, send back as goodsid parameter in Pingbacks
store_card	no	Whether to tokenize credit card details for subsequent purchases and return Permanent Token parameter in Charge object. Default value is 1
token	yes	One-time Token generated for the card or Permanent Token returned in card.token in Charge object
uid	no	Identifies the internal end-user ID within merchant's system. Used for uid parameter in Pingbacks. If omitted, email is used as uid parameter in Pingbacks
User Profile API parameters	yes	Parameters for enhanced Risk Scoring, such as customer[lastname], customer[firstname], address, engagement history. Refer to User Profile API

Sample Request


curl https://api.paymentwall.com/api/brick/charge \
-H "X-ApiKey: [YOUR_PRIVATE_KEY]" \
-d "token=[TOKEN]" \
-d "amount=9.99" \
-d "currency=USD" \
-d "email=user@host.com" \
-d "fingerprint=[FINGERPRINT_BY_BRICK.JS]" \
-d "description=TestItem"

Response - Returns a Charge Object


{
  "object":"charge",
  "id":"52859",
  "created":1392053429,
  "amount":"9.99",
  "currency":"USD",
  "refunded":false,
  "captured":false,
  "risk":"approved",
  "card":{
    "last4":"4242",
    "type":"Visa",
    "exp_month":"12",
    "exp_year":"2019",
    "country":null,
    "name":"John Doe",
    "token":"2857a8cefec761ef7cdb3f97abf4c7b1"
  },
  "secure":false,
  "support_link":"https://api.paymentwall.com/api/account/email-viewer?...",
  "paid_amount":"9.99", 
  "paid_currency":"USD" // may vary from the requested value in case the user is billed in a different currency
}

Preventing Fraud

Brick has an in-house risk scoring system assessing the risk level of every transaction in real time based on various such as velocity metrics, geolocation, transaction history, engagement, device information. Brick also has a 24/7 in-house team of risk analysts that perform agent review of transactions with high risk score on behalf of merchants. To ensure that Brick's risk engine has all the necessary data to score transactions accurately, please ensure to pass as much User Profile API information as possible along with every Charge or Subscription API creation request.

In case a payment is currently under risk review by Brick, the following fields will be returned in the charge object among the others:


{
  ...
  "risk":"pending",
  "captured":false,
  ...
}

At the same time, pingback with type=200 is sent to your server letting you know that the payment is pending risk review. Once the risk review is over (which normally takes only a few minutes), Brick will send a Pingback with the respective decision: type=201 if the payment is accepted; type=202 if the payment is declined. You can use Test CVV numbers 555 and 556 to emulate accepted and declined after risk review scenarios, respectively.

Storing a Card After a Charge

If you want to store the credit card for future use, you can store the permanent token (card.token field of charge response object) and use it for a new charge later on. For this you can use the following example utilizing Brick PHP library:


// Library initialization section
$charge = new Paymentwall_Charge(/* charge details */);
if ($charge->isSuccessful()) {
   store($charge->card->token);
}

Please note that during charge you can pass options[capture]=true, thus only creating a temporary authorization without charging the funds from the user's card. You can then void the charge and return funds to the user.

Get Charge Details

Request
GET https://api.paymentwall.com/api/brick/charge/$id

Response
Charge object

Refund a Charge

Request
GET https://api.paymentwall.com/api/brick/charge/$id/refund

Response
Charge Object

Capture a Charge

Request
GET https://api.paymentwall.com/api/brick/charge/$id/capture

Response
Charge object

Void a Charge

Request
GET https://api.paymentwall.com/api/brick/charge/$id/void Code example using Brick PHP library:


// Library initialization section
$charge = new Paymentwall_Charge('CHARGE_ID');
$charge->void();

Response
Charge object

Subscriptions

Create a Subscription

Request
POST https://api.paymentwall.com/api/brick/subscription

parameter	required	description
amount	yes	Amount to be charged, positive decimal, no commas. E.g. 9999.99
currency	yes	Code of the currency to be charged in ISO 4217 format
custom	no	Array of custom parameters, e.g. custom[field1]=1, custom[field2]=2. To receive these values via Pingbacks, please add Custom Pingback Parameter with name=custom and value=OWN
description	yes	Description for the payment
email	yes	End-user's email
fingerprint	yes	Paymentwall-generated unique fingerprint of a purchase, used for fraud protection as well as advanced analytics. This field is automatically added as a hidden field to your credit card form when brick.js is used on frontend
lang	no	ISO alpha-2 language code for email receipt localization, supported languages
plan	yes, if trial	Identifies the product ID, send back as goodsid parameter in Pingbacks
period	yes	day/week/month/year
period_duration	yes	Number of periods mentioned in the period parameter. By default minimum duration for recurring is 3 days. This can be adjusted by contacting devsupport@paymentwall.com
token	yes	One-time Token generated for the card or Permanent Token returned in card.token in Charge object
trial	optional	Trial subscription details array
trial[amount]	yes, if trial	Trial amount. Free trials are also supported (to have free trials active for your account please contact devsupport@brickpayments.com)
trial[currency]	yes, if trial	Trial currency
trial[period]	yes, if trial	Trial recurring period
trial[period_duration]	yes, if trial	Trial recurring period duration. By default minimum duration is 3 days. This can be adjusted by contacting devsupport@brickpayments.com
uid	no	Identifies the internal end-user ID within merchant's system. Used for uid parameter in Pingbacks. If omitted, email is used as uid parameter in Pingbacks
User Profile API parameters	yes	Parameters for enhanced Risk Scoring, such as lastname, firstname, address, engagement history. Refer to User Profile API

Response - Returns a subscription object


{
  "object":"subscription",
  "id":"VCBZT392SW",
  "period":"day",
  "period_duration":3,
  "payments_limit":122,
  "is_trial":0,
  "started":1,
  "expired":0,
  "active":1,
  "date_started":1419525232,
  "date_next":1419784432,
  "trial":{
    "object":"subscription",
    "id":"VCBZT392SW",
    "period":"day",
    "period_duration":1,
    "payments_limit":1,
    "is_trial":1,
    "started":1,
    "expired":1,
    "active":0,
    "date_started":1419438832,
    "date_next":1419525232,
  }
  "charges":[
    49393608,
    49393609
  ]
}

Every time a user is charged, a Pingback will be sent to your servers using the URL specified as the Pingback URL in your project settings.

Get Subscription Details

Request
GET https://api.paymentwall.com/api/brick/subscription/$id

Response
Subscription object

Cancel a Subscription

Request
GET https://api.paymentwall.com/api/brick/subscritpion/$id

Response
Susbscritpion object

Error

Error object

{ "type":"Error", "error":"Wrong charge amount", "code":3002 }

In case of an error, Paymentwall responds back with 4xx HTTP Response Status Codes. For example, error 4007 (API key is invalid) is sent back with 401 status code. In order to fetch the response body for error object, please make sure your application is able to read response body for requests that return 4xx status code.

List of Error Codes

1000 Internal error
1001 Project isn't loaded, please double-check the API keys
1003 Requested payment method is not active for the given project - contact devsupport@brickpayments.com
3000 Charge not found
3001 Permission denied
3002 Wrong charge amount
3003 Card number is missing or invalid
3004 Expiration month is invalid
3005 Expiration year is invalid
3006 Expiration date is invalid
3007 Currency is missing or invalid
3008 Please fill in all required fields
3009 Please correct the billing address and retry the transaction
3010 Please contact your credit card company to approve your payment
3011 Please contact your credit card company to check your available balance
3012 Transaction was declined
3013 Transaction was declined due to issues with the card
3014 Wrong CVV
3101 Please verify the credit card number and retry the transaction
3102 You submitted an expired credit card number. Please ensure the credit card is valid
3103 You have submitted a card which is not supported. Please, use Visa, MasterCard, AmEx or Discover credit card
3104 Country of the card is not supported
3111 Token was not found
3112 One-time token is invalid
3113 Test credentials are invalid
3114 Token was deleted
3115 Charge amount is too small. Default minimum is 0.50 USD. Please contact devsupport@brickpayments.com to adjust
3116 Charge amount is too high. Default maximum is 500 USD. Please contact devsupport@brickpayments.com to adjust
3200 Please retry the transaction or use another credit card
3201 The charge has already been fully refunded
3202 You can't cancel this transaction
3203 This charge is not found or already captured
3204 You can't refund this transaction
3205 Duplicate charge
3206 Authorization for this card has expired
3301 Please check first name
3302 Please check last name
3303 Please check address
3304 Please check city
3305 Please check state
3306 Please check Zip / Postal Code
3401 Wrong subscription period
3402 Subscription not found
3403 Wrong subscription period duration
3404 Some subscription trial parameters are missing
3405 Subscription trial period is invalid
3406 Subscription trial period duration is invalid
3407 Subscription trial amount is invalid
3408 Number of repeated payments in case of subscription failure is invalid
4004 Undefined method
4005 Request is empty
4006 API key is not provided
4007 API key is invalid
4008 Decryption failed
4010 This API is not activated for the given project
5000 Customer is not allowed to pay

Getting Started