API Docs

Quickstart Guide | @Pay.js v3

Docs > API Docs

Registering Credit Cards

This document is intended for site developers who will be utilizing @Pay.js to capture a customer’s payment method. It will guide you through the process of registering a credit card with @Pay, which is required before a card can be charged for transactions.

js_cc_registration


1. Include @Pay.js On Your Page

To include the @Pay.js in your web application, you will want to include the following 3 script tags:

<script src="//ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js"></script>
<script type="text/javascript" src="https://dashboard.atpay.com/sdk/v3.js"></script>
<script type="text/javascript">
 $(function(){
   atpay.config({
     merchant_id: 1 # Make sure to include your Merchant ID if you registered for a Sandbox account
   });
 });
</script>

Copy   -   Expand

For additional detailed information on configuring @Pay.js, please visit our @Pay.js Documentation.

2. Create a Registration Form

You’ll need a form on your site that accepts credit card details. We will validate the content of this form and remove sensitive information before it hits your servers.

Our system uses the data-atpay attribute for the field name, which leaves you free to use any names you would like for additional data. This allows you to integrate @Pay into existing forms without changing server-side logic, as well. Sensitive information should be marked with a data-atpay-protected attribute, which will ensure the fields are removed from the form entirely before submission (though any field without a name attribute is never sent to your server, regardless).

For a detailed example on how to build a registration form, see Creating a Registration Form.

Any element that does not include a data-atpay attribute will be posted only to your server, not to @Pay. This allows you to collect data for your application at the same time as submitting credit card information to @Pay.

Note: When an input element has a data-atpay-protected attribute, it must not have a name attribute. If the name attribute is present, it is possible for this sensitive information to be posted to your server.

Given the input fields referenced at Creating a Registration Form, an assembled form would look similar to the following:

<form id="atpay-card">
 <!-- Any input element without a data-atpay attribute will be posted only to your server on form submission -->
 <input type="text" name="some_non_atpay_related_field" />


 <!-- Any input element with both a data-atpay attribute and a name attribute will be passed both to @Pay and your server on form submission-->
 <input type="text" name="firstName" data-atpay="first_name" />
 <input type="text" name="lastName" data-atpay="last_name" />
 <input type="text" name="email" data-atpay="email" />
 <input type="text" name="street" data-atpay="street" />
 <input type="text" name="street_continued" data-atpay="street2" />
 <input type="text" name="city" data-atpay="city" />
 <input type="text" name="state" data-atpay="state" />
 <input type="text" name="zipCode" data-atpay="zip" />
 <input type="text" name="country" data-atpay="country" />
 <input type="text" name="phoneNumber" data-atpay="phone" />
 <input type="text" name="saleAmount" data-atpay="amount" />


 <!-- Any input element with both a data-atpay and data-atpay-protected attribute, but not a name attribute, is passed to @Pay and removed from the form before submission to your server -->
 <input type="text" data-atpay="card_number" data-atpay-protected="true" />
 <input type="text" data-atpay="card_type" data-atpay-protected="true" />
 <input type="text" data-atpay="cvc" data-atpay-protected="true" />


 <input type="text" name="cardExpirationMonth" data-atpay="exp_month" />
 <input type="text" name="cardExpirationYear" data-atpay="exp_year" />
 <input type="submit" value="Submit">
</form>

Copy   -   Expand

Now that that’s done, we just need a method to handle the response we will receive from @Pay when we submit the form.

3. Validating the Response

When you submit data to @Pay, you will need a way of handling the response that is returned. This response will be handled by a callback function.

When a form is submitted to @Pay, we will return a response in the form of a variable named ‘response’, which will be fed as an argument to your callback function. The response variable will contain all information related to the registration of the credit card, which you can then access directly.

Successful Registration

If your registration succeeds, you will receive a successful registration response. An successful registration response looks as follows:

{
  atpay_token:      "XYZ",
  message:          "registration_response",
  referrer_context: "sku-11",
  signature:        "a5ac216fd6d43c424da4e743291ac01e87b9a414",
  transaction:      {
    balance:          "40.0",
    created_at:       "2013-08-12 00:00:00 -0600",
    fee:              "0.0",
    id:               "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX",
    signature:        "b6bd327ge7e53c424da4e33256adccf82lsla1xy"
  }
} 

Copy   -   Expand

If the registration succeeded, as with this example response, you will be given an @Pay token, which is stored in the atpay_token field of the response. This is the token that you will want to store, as it will be used for processing transactions for the credit card.

Signature Verification

Since the client can easily falsify information you act upon within the browser, you must assume that the transaction confirmation you’ve received in your callback function is tampered. If you rely on the @Pay email messaging and don’t redeem the transaction for a good without subsequent confirmation from the @Pay hook, you don’t need to worry about this. If you need to provide your Customers with immediate confirmation and deliver a good directly (digital goods and downloads), we recommend you check the signature value of the response.

The signature on a successful registration is the HMAC-SHA1 hex digest value of the returned credit card token signed with your private key. Verify this on your server (note that the transaction on the response object will not exist if you don’t perform a transaction on the registration request):

$.post("/token/verification", {
  signature: response.signature,
  transaction_id: response.transaction.id,
  transaction_signature: response.transaction.signature,
  transaction_balance: response.transaction.balance,
  token: response.atpay_token,
}, function(response){
  if(response.status == "ok"){
    alert("OK");
  }else if(response.status == "fail"){
    alert("FAIL");
  }
});

Copy   -   Expand

And on the server (sample in ruby):

require 'openssl'

# ...
digest = OpenSSL::HMAC.hexdigest("sha1", ATPAY_PRIVATE_KEY, params[:token])
transaction_digest = OpenSSL::HMAC.hexdigest("sha1", ATPAY_PRIVATE_KEY, "\#{params[:transaction_id]}/\#{params[:transaction_balance]}")

if digest == params[:signature] and transaction_digest == params[:transaction_signature]
  render :json => { :status => "ok" }
else
  render :json => { :status => "fail" }
end
# ...

Copy   -   Expand

<script type="text/javascript">
   $(document).ready(function() {
       $("#form-id").submit(function(e) {
          e.preventDefault();
          atpay.register("#form-id",function(response){
            // validate response
          });
       });
    });
</script>

Copy   -   Expand

Failed Registration

If registration fails, you will be given a response similar to the one below:

{
  "message":"registration_response",
  "atpay_token":null,
  "referrer_context":null,
  "error_type":"error",
  "errors":{
     "exp_year":"is invalid",
     "general":"One or more fields contain invalid data.",
     "type":"error"
  },
  "error":{
     "exp_year":"is invalid",
     "general":"One or more fields contain invalid data.",
     "type":"error"
  }
}

Copy   -   Expand

You can access the response.error object to obtain the general error message, as well as the reason that the error occurred.

Callbacks

Both response cases will need to be handled within your callback method. Here is an example of a callback method which handles both cases:

<script type="text/javascript">
   function atpayCallback(response)
   {
       // If the response doesn't include an atpay_token, we know the registration failed.
       if (response.atpay_token == null)
       {
           // Do something with the registration error message.
           var registrationErrorMessage = response.error.general;
           console.log(registrationErrorMessage);
       }
       else
       {
           // Do something with the atpay_token.
           var atpayToken = response.atpay_token;
           console.log(atpayToken);
       }
   }
</script>

Copy   -   Expand

4. Submitting the Form

Now that we have both our form and our callback, we are ready to send the credit card information to @Pay! We will execute the correct method, as demonstrated below:

<script type=”text/javascript”>
  atpay.register(form, callback);
</script>

Copy   -   Expand

Once the register call is made, the appropriate response will be received and handled by our callback. Once you receive an @Pay token, you’re ready to make transactions!

5. Full Example

Here is an example page that will successfully communicate with @Pay and attempt to retrieve a valid @Pay token. Testing credit card information has been included within the form.

Note: To use the below example, you will need to have registered for an account with @Pay. Once registered, include your Merchant ID in the Javascript below.

<html>
 <head>
   <title>@Pay Example</title>
 </head>

 <body>
   <script src="http://code.jquery.com/jquery-1.10.1.min.js"></script>
   <script type="text/javascript" src="https://dashboard.atpay.com/sdk/v3.js"></script>
   <script type="text/javascript">
     $(function(){
       atpay.config({
         merchant_id: 10
       });
     });
   function atpayCallback(response)
   {
       // If the response doesn't include an atpay_token, we know the registration failed.
       if (response.atpay_token == null)
       {
           // Do something with the registration error message.
           var registrationErrorMessage = response.error.general;
           console.log(registrationErrorMessage);
           console.log(response.error);
       }
       else
       {
           // Do something with the atpay_token.
           var atpayToken = response.atpay_token;
           console.log("Successfully received @Pay token");
           console.log(response.atpay_token);
       }
   }
   </script>


     <form id="atpay-card" onsubmit="atpay.register(this, atpayCallback); return false;">
       <!-- Any input element without a data-atpay attribute will be posted only to your server on form submission -->
       Non-Atpay Field: <input type="text" name="some_non_atpay_related_field" value="foo"/><br>

       <!-- Any input element with both a data-atpay attribute and a name attribute will be passed both to @Pay and your server on form submission-->
       First Name: <input type="text" name="firstName" data-atpay="first_name"  /><br>
       Last Name: <input type="text" name="lastName" data-atpay="last_name" /><br>
       E-mail: <input type="text" name="email" data-atpay="email" /><br>
       Street: <input type="text" name="street" data-atpay="street" /><br>
       Street (cont): <input type="text" name="street_continued" data-atpay="street2" /><br>
       City: <input type="text" name="city" data-atpay="city" /><br>
       State: <input type="text" name="state" data-atpay="state" /><br>
       Zip Code: <input type="text" name="zipCode" data-atpay="zip" /><br>
       Country: <input type="text" name="country" data-atpay="country" value="United States" /><br>
       Phone: <input type="text" name="phoneNumber" data-atpay="phone" /><br>
       Amount: <input type="text" name="saleAmount" data-atpay="amount" /><br>

       <!-- Any input element with both a data-atpay and data-atpay-protected attribute, but not a name attribute, is passed to @Pay and removed from the form before submission to your server -->
       Card #: <input type="text" data-atpay="card_number" data-atpay-protected="true" value="4111111111111111"/><br>
       Card Type: <input type="text" data-atpay="card_type" data-atpay-protected="true" value="001"/><br>
       CVC: <input type="text" data-atpay="cvc" data-atpay-protected="true" value="123"/><br>
       Exp Month: <input type="text" name="cardExpirationMonth" data-atpay="exp_month" value="10"/><br>
       Exp Year: <input type="text" name="cardExpirationYear" data-atpay="exp_year" value="2015"/><br>
       <input type="submit" value="Submit" >
     </form>
 </body>
</html> 

Copy   -   Expand

Top