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=6471111111&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 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
Updated about 1 year ago
Now that you've authorized a transaction, let's learn more about capturing and managing the auth action.