Auth

Use Auth API to authorize a PayBright transaction

Authorize Transaction

The Auth API Endpoint is used to authorize a PayBright transaction, and initiates a customer's application. This API should be used when the merchant would like to execute two distinct authorization and capture events, as opposed to a singular event that both authorizes and captures the transaction.

📘

Tip: Please ensure that your authentication and capture preferences are shared with the PayBright team beforehand so that we can ensure your merchant account is configured correctly.

📘

Refer to the API Reference guide for a description of the contents in the API and to identify the mandatory fields.

📘

BOPIS

For Buy Online Pay In-store (BOPIS) transactions, store address should not be passed as the shipping address in x_customer_shipping_address1 field in the body of the Auth request.

To authorize a transaction, you will need to create the signature using the API Key and API Token shared with you by the PayBright team.

curl --location --request POST 'https://app.paybright.com/CheckOut/ApplicationForm.aspx' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-raw 'x_account_id=Z9s7Yt0Txsqbbx&x_amount=1100.00&x_currency=CAD&x_customer_billing_address1=22+Viewcrest+Cir&x_customer_billing_city=Etobicoke&x_customer_billing_country=CA&x_customer_billing_phone=5196152481&x_customer_billing_state=ON&
x_customer_billing_zip=M9W7G5&x_customer_email=test%40paybright.com&x_customer_first_name=Jamie&x_customer_last_name=Testhet&x_customer_phone=6139876543&x_customer_shipping_address1=22+Viewcrest+Cir&x_customer_shipping_city=Etobicoke&x_customer_shipping_country=CA
&x_customer_shipping_first_name=Jamie&x_customer_shipping_last_name=Testhet&x_customer_shipping_phone=6139876543&x_customer_shipping_state=ON&x_customer_shipping_zip=M9W7G5&
x_reference=2194779&x_shop_country=CA&x_shop_name=Paybright+Test+Store&x_test=true&
x_url_callback=https%3A%2F%2Fmystore.io%2Fping%2F1&x_url_cancel=https%3A%2F%2Fmystore.io&x_url_complete=https%3A%2F%2Fmystore.io%2Forders%2F1%2Fdone&x_signature=ce85f1a19ce81ffcb0d09648cca17fe996198b1fbe84b3e26d6d4bbfe01868b2'
<?php
$body = array(
    'x_account_id' => 'Z9s7Yt0Txsqbbx',
    'x_amount' => '1100.00',
    'x_currency' => 'CAD',
    'x_customer_billing_address1' => '22 Viewcrest Cir',
    'x_customer_billing_city' => 'Etobicoke',
    'x_customer_billing_country' => 'CA',
    'x_customer_billing_phone' => '5196152481',
    'x_customer_billing_state' => 'ON',
    'x_customer_billing_zip' => 'M9W7G5',
    'x_customer_email' => '[email protected]',
    'x_customer_first_name' => 'Jamie',
    'x_customer_last_name' => 'Testhet',
    'x_customer_phone' => '6139876543',
    'x_customer_shipping_address1' => '22 Viewcrest Cir',
    'x_customer_shipping_city' => 'Etobicoke',
    'x_customer_shipping_country' => 'CA',
    'x_customer_shipping_first_name' => 'Jamie',
    'x_customer_shipping_last_name' => 'Testhet',
    'x_customer_shipping_phone' => '6139876543',
    'x_customer_shipping_state' => 'ON',
    'x_customer_shipping_zip' => 'M9W7G5',
    'x_reference' => '2194779',
    'x_shop_country' => 'CA',
    'x_shop_name' => 'Paybright Test Store',
    'x_test' => 'true',
    'x_url_callback' => 'https://mystore.io/ping/1',
    'x_url_cancel' => 'https://mystore.io',
    'x_url_complete' => 'https://mystore.io/orders/1/done'
);

$bodyString = http_build_query($body);
$signatureString = '';

foreach (explode('&', $bodyString) as $chunk) {
    $param = explode("=", $chunk);
    if ($param && $param[1] != '') { 
        $signatureString = $signatureString . urldecode($param[0]) . urldecode($param[1]);
    }
}
$pb_sig = hash_hmac('sha256', $signatureString, "gyB8ELayUsE8tPxZ9s7Yt0Txsqbbx");
$bodyString = $bodyString . '&x_signature=' . $pb_sig; 

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://sandbox.paybright.com/CheckOut/ApplicationForm.aspx");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $bodyString);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded'));
curl_setopt($ch, CURLOPT_FOLLOWLOCATION, true);

$response = curl_exec($ch);

Rendering PayBright Application

The Auth API returns an HTML Page in the response, which is then to be rendered on your website. This page allows your customers to complete a single-field application within 30 to 60 seconds. Customers are redirected back to the merchant website once they have completed the PayBright application.

Auth API: Application FlowAuth API: Application Flow

Auth API: Application Flow

Response

You will receive the final decision on a customer's PayBright application through:

A POST callback notification is sent asynchronously and a second GET request is sent to the Redirect URL when the Auth API call was made.

📘

Tip: PayBright recommends using the Checkout page's URL as x_url_complete for a seamless customer experience.

🚧

Tip: PayBright will receive a 200 OK from the POST request made to x_url_callback to avoid any order synchronization issues; best practice is to wait for the POST callback before finalizing a customer order

You should see a request that looks like this with x_result and x_gateway_reference.

x_account_id=Z9s7Yt0Txsqbbx
&x_amount=1100.00
&x_currency=CAD
&x_gateway_reference=50732
&x_message=Success
&x_reference=2194779
&x_result=Completed
&x_test=true
&x_timestamp=2020-07-20T14:31:20Z
&x_transaction_type=authorization
&x_signature=e52654894ae51e8b26ca71d106fe4862300acb861b45f7138ded3f3a909ac114

Processing the Request

A transaction ID (x_gateway_reference) is provided in the POST and GET request you receive from PayBright to reference this transaction moving forward.

The decision on the customer's application with PayBright is returned in x_result field. You can receive different statuses in x_result and will have to build your back-end accordingly:

Completed

If x_result == Completed is in the request you receive on the callback url and complete url, it means that the customer application was successfully approved by PayBright and you can call the capture API to capture payment for this transaction.

Pending

Pending in x_result means that the transaction was flagged by PayBright's system as a potential fraud case, and requires a manual review. PayBright will make a final decision within 48 hours and you will receive a POST Request on the callback URL you passed in the initial auth API call.

You will receive x_result == Completed if PayBright's Fraud team approves the transaction and x_result == Failed if the transaction is marked as Fraud. You will cancel any of the orders marked as 'fraud' on your end.

👍

Tip: A successful auth call must be followed by a capture call in order for the merchant to receive payment for their customer's purchase. This is only true if you do not want to settle using Virtual Cards

VCN Settlement:
Please refer to VCN Settlement APIs if you want to settle funds through Virtual Cards instead of Order Management API Section


What's Next

Now that you've authorized a transaction, let's learn more about capturing and managing the auth action.