Card Sales and Consent

Learn to make credit card sales and collect consent with Number

Card present sales and consent

To make sales or collect consent when a card is present using Number, you have several options:

1

Integration with a Verifone card reader

You can use Verifone card readers. They are secure devices that connect to your computer via USB. They encrypt cardholder data during transmission to ensure security.

2

USB card reader through the Virtual Terminal or our desktop app

When you have a USB card reader connected to your machine, you can log into the Virtual Terminal to make card present sales and to collect consent.

We also have a custom desktop application which can be convenient in an office setting to collect card present payments. It offers similar functionality to the Virtual Terminal.

3

Custom integration with our REST API

Our REST API offers methods for handling card present transactions.

If you have your own PCI level one compliance program, you may write your own custom code calling our APIs to collect card present payments and consent. You can read more about PCI compliance in the short PCI Compliance section of our Integration Options guide.

Verifone integration

There are a few approaches to integration, You can either use the browser-based interface option or the Desktop integration with SDK .

For an in-depth tutorial on how to integrate and use your Verifone card reader with Number, see our Verifone integration guide.

Before you start, you'll need to download the Verifone Windows service to your machine, connect your card reader device to a free USB port, allow it to initialize, extract the archive with the service and run the EXE as an administrator. After the installation is complete, reboot the system.

You can issue commands to the service by calling https://localhost:8031 from your website.

Verifone card present sales

Here's an simplified example of how you can invoke the service for a card present sale:

JavaScript

// Initiates CHIP transaction
function initiateEMVTransaction() {
    // // You must either supply a session key for Live credit card authorizations or modify your eptools profile to point to a particular account
    // You may modify your stored profile at c:\ProgramData\EasyPay\Eptools\eptools\profiles
    const sessKey = getSessKey(); //  your server application can pass this down to your client script 
    
    // Each account can have multiple merchant records. Normally this can be '1' for default if you only have one merchant on account.
    const merchID = getMerchId();
    
    // Note: any 'address' field should be an object consisting of:
    // 'Address1', 'Address2', 'City', 'State', 'ZIP', and 'Country'
    
    // The account holder and end customer JSONs should consist of:
    // 'Firstname', 'Lastname', 'address' (see above), 'Email', and 'Phone'
    const acctHolderJson = getAcctHolderJson();
    const endCustJson = getEndCustJson();
    
    // Purchase details should consist of the following fields:
    // 'REFID' and 'RPGUID' (your custom defined values), and 'ServiceDesc'
    const purchDetailsJson = getPurchDetailsJson();

    // The amount needs to be stripped from '$' and ',' symbols
    let amount = getAmount();
    amount = amount.replace('$', "").replace(',', ""); 

    const url = `https://localhost:8031/VerifoneSVC/service/GetEmvJson?SessKey=${sessKey}&AcctHolderJson=${acctHolderJson}&EndCustJson=${endCustJson}&PurchDetailsJson=${purchDetailsJson}&MerchID=${merchID}&Amount=${amount}`;

    // Make the call to the service and do basic error/success handling
    $.ajax({
        type: "GET",
        url: url,
        success: function (data) {
            // Hex to byte array, then UTF text, and alert the XML object
            alert(stringFromUTF8Array(hexToBytes(data)));
        },
        error: function (xhr, status, error) {
            console.error("Verifone Middleware Error", {
                statusCode: xhr.status,
                statusText: xhr.statusText,
                error: error
            });
            alert(`Verifone Middleware Error: ${error}`);
        }
    });
}

Verifone card present annual consent

Here's an simplified example of how you can invoke the service to collect annual consent:

JavaScript

// Save card chip for annual consent
function saveCardChip() {
    // You must either supply a session key for authentication or modify your eptools profile to point to a particular account
    // You may modify your stored profile at c:\ProgramData\EasyPay\Eptools\eptools\profiles
    const sessKey = getSessKey();
    
    // Each account can have multiple merchant records. Normally this can be '1' for default if you only have one merchant on account.
    const merchID = getMerchId();
    
    // Note: any 'address' field should be an object consisting of:
    // 'Address1', 'Address2', 'City', 'State', 'ZIP', and 'Country'
    
    // The account holder and end customer JSONs should consist of:
    // 'Firstname', 'Lastname', 'address' (see above), 'Email', and 'Phone'
    const acctHolderJson = getAcctHolderJson();
    const endCustJson = getEndCustJson();
    
    // Purchase details should consist of the following fields:
    // 'REFID' and 'RPGUID' (your custom defined values), and 'ServiceDesc'
    const purchDetailsJson = getPurchDetailsJson();
    
    // Annual params should consist of the following fields:
    // 'StartDate' in yyyy-mm-dd format, 'NumDays' the consent should be active, 'LimitPerCharge' in $, 'LimitLifeTime' in $
    // The amounts need to be stripped from '$' and ',' symbols
    const annualParamsJson = getAnnualParamsJson();

    const url = `https://localhost:8031/VerifoneSVC/service/GetAnnualJson?SessKey=${sessKey}&AcctHolderJson=${acctHolderJson}&EndCustJson=${endCustJson}&PurchDetailsJson=${purchDetailsJson}&MerchID=${merchID}&AnnualParams=${annualParamsJson}&IsManual=False`;

    // Make the call to the service and do basic error/success handling
    $.ajax({
        type: "GET",
        url: url,
        success: function (data) {
            // Hex to byte array, then UTF text, and alert the XML object
            alert(stringFromUTF8Array(hexToBytes(data)));
        },
        error: function (xhr, status, error) {
            console.error("Verifone Middleware Error", {
                statusCode: xhr.status,
                statusText: xhr.statusText,
                error: error
            });
            alert(`Verifone Middleware Error: ${error}`);
        }
    });
}

Virtual Terminal or desktop application

When you want to use your Verifone with the Virtual Terminal, you have to first install the very same Windows service that is used when doing a Verifone browser-based integration. After installation, contact the Number support team to get the card reader features activated.

To learn more about using the Virtual Terminal, see the Virtual Terminal user guide.

Read more about using our custom desktop application for sales in the Integration Options guide or contact Number to get access.

Virtual Terminal card present sales

When you visit the Virtual Terminal, log in and expand Credit Cards in the navigation on the left. You'll see options for a sale, an EMV sale, authorization, forced auth, and adjustments.

As long as your USB card reader is connected to your machine, it will seamlessly integrate with the Virtual Terminal for card present transactions.

Virtual Terminal card present consent

When you visit the Virtual Terminal, log in and expand Consents in the navigation on the left. You'll see options for annual consent, EMV annual consent, and one-time consent. You can also expand the Recurring tab to find options to create recurring consent, EMV recurring consent, and subscription consent.

As long as your USB card reader is connected to your machine, it will seamlessly integrate with the Virtual Terminal for card present transactions.

REST / SOAP API integration

Our APIs are useful for any Integration as you can apply a credit, void, query, charge a stored card etc. For integrators who are PCI Level one compliant you may also pass cardholder data directly through the API. Most integrations will use our PayForms to collect Cardholder data while the API will be used for all remaining activity.

To learn more about our APIs, see the REST API and SOAP API integration guides.

When you scan the credit card and collect the track data alongside the other payment details, if using the REST API, prepare the HMAC secured header like shown in Authentication quickstart guide, and encrypt the card number using our RSA certificate.

Follow the instructions in the API reference to prepare and handle the request.

API card present sales

You can use the following API operations:

• For the REST API, use POST /APIcardProcREST/v1.0.0/CardSale/CardPresent
• For the SOAP API, use Credit Card Sale - Card Present

API card present consent

You can use the following API operations:

• For the REST API, you can use POST /APIcardProcREST/v1.0.0/ConsentAnnual/Create_CP and POST /APIcardProcREST/v1.0.0/ConsentRecurring/Create.
• For the SOAP API, you can use Create Annual Consent - Card Present, Create Recurring Consent, and Create Subscription Consent - Card Present.

---

Manual card sales and consent

To make credit card sales and collect consent using Number when you want to enter the card details manually, you have the following options:

1

PayForm widget

You can configure and customize our PayForm widget and redirect your users to a separate page with the form or embed it as an IFrame in your existing web application.

2

Virtual Terminal or our desktop application

The Virtual Terminal website allows you to handle manual card sales and consent collection by default. This approach requires no coding and is perfect for a physical point-of-sale.

We also have a custom desktop application which can be convenient way to collect manual card payments and consent. It offers much of the same functionality as the Virtual Terminal.

3

Android or iOS SDK integration

If you have a mobile application that needs to handle payments and consent, our SDKs implement secure forms which can collect cardholder information from your users.

4

REST API or SOAP API integration

For more customization, you can call our APIs for sales and consent.

If you have your own PCI level one compliance program, you may write your own custom code calling our APIs to collect manual card payments and consent. You can read more about PCI compliance in the short PCI Compliance section of our integration guide.

PayForm widget

The PayForm is designed to be a highly flexible and secure payment form for your users. To start collecting payments and consent with the PayForm, you'll want to use our builder tool for configuration, then our REST API to generate a payment URL.

Learn more about how to configure and use the PayForm in the PayForm guide.

Use the PayForm builder to build the request body, and to determine styling options.

You can read about configuration specifics in the PayForm builder section of our full PayForm guide. For the purpose of this tutorial, you can follow the example below; we'll briefly explain each configuration step.

PayForm manual card sale

In the example below, the PayForm has been setup for an instant card payment.

1

Visible and read-only fields

The cardholder will need to provide their first and last names, full address, email, and click a checkbox to agree to pay and give their permissions to receive an email.

Additionally, they'll see the amount field, but it'll be read-only.

2

Submission options

The PayForm will redirect the user to an external URL. An encrypted query string containing the POST data will also be appended to the URL

3

Styling and colors

The styling and colors were left as default, only switching out the button background and border to different shades of green.

4

Pre-filled values

The amount will be pre-filled as $25, the redirect URL is using an example URL to your website, and the EIndex is using the sandbox value for encryption key. Endpoint value should always be left as default.

The JSON will look like the following:

PayForm JSON example

{
  "InitParams": {
    "MerchID": 1,
    "WTYPE": "PF",
    "PostURL": "",
    "RedirectURL": "https://yourwebsite.com/success",
    "REF_ID": "",
    "RPGUID": "",
    "EndPoint": "PayForm/PF.aspx",
    "EINDEX": "300",
    "Amounts": {
      "Amount": 25,
      "Surcharge": 0,
      "TotalAmt": 25
    },
    "Payer": {
      "Firstname": "",
      "Lastname": "",
      "BillingAddress": {
        "StreetAddress": "",
        "City": "",
        "State": "",
        "ZIP": "",
        "Country": ""
      },
      "Email": "",
      "Phone": ""
    },
    "WidOptions": {
      "eVisible": "6E7F",
      "eReadOnly": "0040",
      "eStyles": "0001",
      "eSubmission": "0201",
      "eColors": "#ffffff,#6cca44,#59ff00,#212121,#ffffff,#212121,#ffffff"
    }
  }
}

This JSON can be used to make a REST API request to generate the actual payment form.

You may re-use this JSON to generate the same type of form for multiple different users. You may also want to dynamically configure values like the amounts from your code.

To generate a PayForm, make a request to POST /PayForm/Initialize.

If you include a valid session key, the PayForm will be accessible under the PaymentUrl included in the response. You can embed it into your site or redirect the user to the page.

Once the user fills out and submits the form, we'll handle the payment.

If you want to handle the query string when redirecting back to your website to store the transaction ID in your database, read the Redirect with query string section of our full PayForm guide.

PayForm manual consent

To use the PayForm to save a card on file, follow the steps in PayForm manual card sale, change the transaction type to collecting cardholder data, and skip the amount field.

You may also collect an instant payment and consent at the same time by choosing the combo widget as your transaction type.

Virtual Terminal or desktop application

The Virtual Terminal is a web application that allows you to manually enter credit card details and process transactions through your browser.

To learn more about using the Virtual Terminal, see the Virtual Terminal user guide.

Read more about using our custom desktop application for sales in the Integration Options guide or contact Number to get access.

Virtual Terminal manual card sale

When you visit the Virtual Terminal, log in and expand Credit Cards in the navigation on the left. You'll see options for a sale, an EMV sale, authorization, forced auth, and adjustments. Follow the instructions and manually enter the cardholder details to make a sale.

Virtual Terminal manual consent

Using the Virtual Terminal, you can create annual, one-time, recurring, and subscription consents. Log in and expand Consents and Recurring tabs on the left side of the screen. Choose the type of consent you're interested in and follow the instructions to manually enter the cardholder details and store a card on file.

Android / iOS SDK integration

If you are developing an Android or iOS application, you can utilize our SDKs to charge credit cards and collect consent manually by having users enter their own details.

We recommend following the Android SDK and iOS SDK guides to learn how to integrate Number with your mobile applications.

Mobile manual card sale

The relevant methods are described in 1. Charge credit card section of the Android SDK guide and 1. Charge credit card section of the iOS SDK guide.

Mobile manual consent annual

The relevant methods are described in 3. Create annual consent section of the Android SDK guide and 3. Create annual consent section of the iOS SDK guide.

REST / SOAP API integration

If you wish to have more control over the integration and you are PCI Level 1 compliant, you can try using our APIs. They provide methods for all payment types available using our other services, including manual card sales and collecting different types of consent.

To learn more about our APIs, see the REST API and SOAP API integration guides.

After authenticating, when you collect cardholder data alongside the other payment details, if using the REST API, prepare the HMAC secured header like shown in Authentication quickstart guide, and encrypt the card number using our RSA certificate. Follow the instructions in the API reference to prepare and handle the request.

Manual card sale

You can use the following API operations:

• For the REST API, use POST /APIcardProcREST/v1.0.0/CardSale/Manual.
• For the SOAP API, use Credit Card Sale - Manual.

Manual consent

You can use the following API operations:

• For the REST API, use POST /APIcardProcREST/v1.0.0/ConsentAnnual/Create_MAN for annual consent and POST /APIcardProcREST/v1.0.0/ConsentRecurring/Create for recurring consent.
• For the SOAP API, use Create Annual Consent - Manual for annual, Create Recurring Consent for recurring, and Create Subscription Consent - Card Presentfor subscription consent.