Credit Card Sale

A Sale operation is basically a combined transaction; an Authorization operation and a Capture operation. A Sale not only checks that the credit card being used in a transaction contains sufficient funds to cover the amount of the transaction, it also flags the transaction as captured meaning it is to be sent for settlement in the next settlement period. The Sale operation is the most used transaction type in relation to trading of online services where the product or service is delivered to the customer online.

Endpoints

HTTP Method	API URL	API Version
POST	https://api.payxpert.com/transaction/sale/creditcard	>= 002

Accepted parameters

Field	Type	Max Length	Required	Description	Version
customerIP	String	40	yes	Customer request IP
amount	Integer	10	yes	Number in minor unit, e.g. cents; 100 dollar cent equals to 1 dollar
currency	String	3	yes	ISO-4217 currency codes
orderID	String	100	yes	Unique reference to current transaction request
				Credit Card Payment fields
cardNumber	String	40	yes	Credit card number
cardSecurityCode	String	4	yes	CVV number from credit card
cardHolderName	String	80	yes
cardExpireMonth	String	2	yes	Month of the card expire: 09
cardExpireYear	String	4	yes	Year of the card expire ie: 2017
processingScheme	String	10	no	Scheme network to process the transaction through. Possible values are MCRD, VISA, CB, VPAY, MAES or ELECTRON
				Shopper fields
shopperName	String	80	yes	Use ‘NA’ if unavailable
shopperAddress	String	255	yes	Use ‘NA’ if unavailable
shopperZipcode	String	10	yes	Use ‘NA’ if unavailable
shopperCity	String	50	yes	Use ‘NA’ if unavailable
shopperState	String	30	yes	ISO 3166-2 country subdivision codes if exist; 2 letters in USA, 3 letters in Australia, etc. Use ‘NA’ if unavailable
shopperCountryCode	String	2	yes	ISO-3166-1 country codes. Use “ZZ” if the country is unknown
shopperPhone	String	20	yes	Use ‘NA’ if unavailable
shopperEmail	String	100	yes	Use ‘NA’ if unavailable
shopperBirthDate	String	8	no	Use format YYYYMMDD	>= 0206
shopperIDNumber	String	32	no	Customers document (passport number, ID number,taxpayer ID,… )	>= 0206
				Optional AVS fields
AVSPolicy	String	20	no	AVS and FS policy
FSPolicy	String	20	no	AVS and FS policy
				Optional e-commerce fields
orderAmount	String	10	no	Number in minor unit, e.g. cents; 100 dollar cent equals to 1 dollar
productID	String	32	no	Unique ID of the ordered product (separate multiple IDs by commas).
comment	String	255	no	Merchant comments
shipToName	String	80	no	Name of shipping address
shipToAddress	String	255	no	Address of shipping address
shipToZipcode	String	10	no	Zip code of shipping address
shipToCity	String	50	no	City of shipping address
shipToState	String	30	no	ISO 3166-2 country subdivision codes if exist; 2 letters in USA, 3 letters in Australia, etc
shipToCountryCode	String	2	no	ISO-3166-1 country codes.
shipToPhone	String	20	no	Phone of shipping address
orderDescription	String	500	no	Order description
merchantIdentifier	String	128	no	Identifier from the merchant side. Can be used to do grouping later on.
				Optional 3D secure fields
PaRes	String	16384	no	PaRes returned from 3D secure authentication, will take precedence on individual fields below.	>= 0207
CRes	String	8192	yes for 3DS v2	The challenge result received after 3DSAuth call.	>= 02331
ECI	String	4	no	Electronic Commerce Indicator returned from 3D secure authentication (Only to be used by special agreement)
XID	String	28	no	Xid returned from 3D secure authentication (Only to be used by special agreement)
CAVV	String	40	no	Cavv returned from 3D secure authentication (Only to be used by special agreement)
CAVVAlgorithm	String	32	no	CAVVAlgorithm returned from 3D secure authentication (Only to be used by special agreement)
				Optional automated subscription fields
offerID	Integer	16	no	Predefined price point with initial and rebill period
				Optional manual subscription fields
subscriptionType	String	32	no	can be normal, partpayment, infinite, onetime or lifetime. See Subscription Types (Only to be used by special agreement)
rebillAmount	Integer	10	no	Number in minor unit, e.g. cents; 100 dollar cent equals to 1 dollar. Amount to be rebilled after the initial period. (Only to be used by special agreement)
rebillPeriod	String	10	no	Frequency of the iterations in ISO 8601 duration format. (Only to be used by special agreement)
rebillMaxIteration	Integer	2	no	Number of re-billing transaction that will be settled. Use 0 for unlimited rebill. (Only to be used by special agreement)
trialPeriod	String	10	no	Duration of the trial period (if any) in ISO 8601 duration format. (Only to be used by special agreement)
				Optional affiliate fields
affiliateID	String	16	no	This is the affiliate id from your affiliate program. This variable help you and the Risk Management team to manage the transactions coming from your affiliates.
campaignName	String	128	no	Affiliate campaign name
				Optional fraud fields
threatmetrixSession	String	100	no	Threatmetrix session id generated on the payment page

Code samples

Note: Gateway API transactions are done with a different library than payment-page API. See the code sample comments for more info:

PHP
Java
JavaScript
C#


  /*
  *   Transaction name is 'CCSale', once you create a new transaction passing this as parameter, 
  *   you need to set the mandatory data using the follow methods:
  *    setTransactionInformation() 
  *    setCardInformation()
  *    setShopperInformation()
  *
  *    Additionally, you can call the following methods for extra parameters:
  *    setAVSPolicy(), setOrder(), setShippingAddress(), set3DSecure(), setAutomaticSubscription(),
  *    setAutomaticPartPayment(),  setManualSubscription(), setAffiliate()
  *
  *    IMPORTANT!! setManualSubscription, setAutomaticPartPayment and setAutomaticSubscription cannot be used concurrently on the same transaction.
  */

  $client = new GatewayClient();

  $transaction = $client->newTransaction('CCSale', 'testMerchant', 'testPassword');
  $transaction->setTransactionInformation(2000, 'USD', 'order1456', '10.10.254.10');
  $transaction->setCardInformation('4111111111111111', '000', 'John Smith', '10', '2014');
  $transaction->setShopperInformation('Jane Smith', '334 Some Drive', '90001', 'Los Angeles', 'CA', 'US', '+1 213-XXX-XXXX', 'test@mail.com');
  $transaction->setAutomaticSubscription(999999999);

  $response = $transaction->send();

  if ('000' === $response->errorCode) {
      $transactionID  = $response->transactionID;
      $subscriptionID = $response->subscriptionID;
      // If account is allowed to access payment mean info
      echo "Credit card type is " . $response->paymentMeanInfo->cardBrand;
  } else {
      echo "Error {$response->errorCode} with message {$response->errorMessage}";
  }

  ###########################################################################
  # Sale transaction using 3DS, an order information and a shipping address #
  ###########################################################################

  $transaction = $client->newTransaction('CCSale', 'testMerchant', 'testPassword');
  $transaction->setTransactionInformation(15000, 'EUR', 'order1456', '10.10.254.10');
  $transaction->setCardInformation('4111111111111111', '000', 'John Smith', '10', '2014');
  $transaction->setShopperInformation('John Smith', '123 Some Street', 'WC1A1AA', 'London', 'NA', 'GB', 'NA', 'test@mail.com');
  $transaction->setShippingAddress('Jane Smith', '999 Some Lane', 'WC1B1BB', 'London', 'NA', 'GB', '020 XXXX XXXX');
  $transaction->setOrder(15000, 'NT94498', '', 'A nice set of tableware');
  $transaction->set3DSecure('04', 'DQS5A031202952O2DOP', 'ABCCBAaKDOlYcRJyQocUAZZZAA=', '2');

  $response = $transaction->send();

  if ('000' === $response->errorCode) {
      $transactionID  = $response->transactionID;
      // If account is allowed to access payment mean info
      echo "Credit card type is " . $response->paymentMeanInfo->cardBrand;
      if ($response->paymentMeanInfo->is3DSecure) {
        echo "The payment is 3D Secure";
      } else {
        echo "The payment is not 3D Secure";
      }
  } else {
      echo "Error {$response->errorCode} with message {$response->errorMessage}";
  }


  PaymentGatewayConnector connector = new PaymentGatewayConnector(API_URL, ORIGINATOR, PASSWORD);

  CCSaleResponse response = null;
  CCSaleRequest request = new CCSaleRequest();
  request.setOrderId("order1456");
  request.setCustomerIP("10.10.254.10");
  request.setAmount(2000).setCurrency("USD");
  request.setShopperName("Jane Smith").setShopperAddress("334 Some Drive");
  request.setShopperZipcode("90001").setShopperCity("Los Angeles").setShopperState("CA").setShopperCountryCode("US");
  request.setShopperPhone("+1 213-XXX-XXXX");
  request.setShopperEmail("test@mail.com");

  request.setCardNumber("4111111111111111").setCardSecurityCode("000");
  request.setCardExpireMonth("10").setCardExpireYear("2014");
  request.setCardHolderName("John Smith");

  request.setOfferId(999999999L);

  try {
    response = connector.doCCSaleTransaction(request);
  } catch (Exception e) {
    e.printStackTrace();
  }

  if (response != null) {
    if (TransactionResultCode.TRANSACTION_SUCCESSFULLY.equals(response.getErrorCode()) {
      System.out.println("Success: " + response.getErrorMessage());
    } else {
      System.out.println("Failure: " + response.getErrorMessage());
    }
  }

  /*
   * 
   * Sale transaction using 3DS, an order information and a shipping address
   *
   */

  CCSaleResponse response = null;
  CCSaleRequest request = new CCSaleRequest();
  request.setOrderId("1234567");
  request.setCustomerIP("10.10.254.10");
  request.setAmount(15000).setCurrency("EUR");
  request.setShopperName("John Smith");
  request.setShopperAddress("123 Some Street").setShopperZipcode("WC1A1AA").setShopperCity("London");
  request.setShopperState("NA").setShopperCountryCode("GB");
  request.setShopperPhone("NA").setShopperEmail("test@mail.com");

  request.setShipToName("Jane Smith");
  request.setShipToAddress("999 Some Lane");
  request.setShipToZipcode("WC1B1BB").setShipToCity("London").setShipToState("NA").setShipToCountryCode("GB");
  request.setShipToPhone("020 XXXX XXXX");

  request.setCardNumber("4111111111111111").setCardSecurityCode("000");
  request.setCardExpireMonth("10").setCardExpireYear("2014");
  request.setCardHolderName("John Smith");

  request.setOrderAmount(15000).setProductId('NT94498');
  request.setComment("").setOrderDescription("A nice set of tableware");

  request.setECI("04").setXID("DQS5A031202952O2DOP").setCAVV("ABCCBAaKDOlYcRJyQocUAZZZAA=").setCavvAlgorithm("2");

  try {
    response = connector.doCCSaleTransaction(request);
  } catch (Exception e) {
    e.printStackTrace();
  }

  if (response != null) {
    if (TransactionResultCode.TRANSACTION_SUCCESSFULLY.equals(response.getErrorCode()) {
      System.out.println("Success: " + response.getErrorMessage());
      System.out.println("Transaction ID is " + response.getTransactionId());
      // If account is allowed to access payment mean info
      System.out.println("Credit card was a " + response.getPaymentMeanInfo().getCardBrand().getFormattedMessage(Locale.ENGLISH));
    } else {
      System.out.println("Failure: " + response.getErrorMessage());
    }
  }

const gateway = require("payxpert")("123456", "GreatP4ssw0rd").gateway;

const body = {
    customerIP: "8.8.4.4",
    amount: 1500,
    currency: "EUR",
    orderID: "HELLO NODEJS",

    cardNumber: "4111111111111111",
    cardSecurityCode: "000",
    cardHolderName: "CARDHOLDER NAME",
    cardExpireMonth: "10",
    cardExpireYear: "2024",

    shopperName: "NodeJS Test",
    shopperAddress: "NA",
    shopperZipcode: "NA",
    shopperCity: "NA",
    shopperState: "NA",
    shopperCountryCode: "NA",
    shopperPhone: "NA",
    shopperEmail: "NA"
};

const responseCreatePayment = await gateway.creditCardSale(body);

if (responseCreatePayment.code == "000") {
    // Success
}


var client = new GatewayClient(OriginatorConfig.ORIGINATOR_ID, OriginatorConfig.ORIGINATOR_PASSWORD);
var transaction = client.NewSaleTransaction();

var amount = 1000;

transaction.SetTransactionInformation(amount, "EUR", "50", "8.8.8.8");
transaction.SetCardInformation("4111111111111111", "000", "CSHARP SDK", "10", "2024");
transaction.SetShopperInformation("CSHARP SDK", "MICROSOFT HELL", "666", "REDMOND", "WA", "US", "12445", "x@x.rr");

var response = await transaction.Send();

if (response.IsSuccessfull())
{
    Console.WriteLine("Sale operation ok. Transaction ID: " + response.transactionID);
}

Copy to Clipboard

Response

The body of the response is in JSON format.

The following fields are present in the response :

Name	Type	Description
transactionID	String	Transaction reference returned by the system
errorCode	String	See API Response Codes
errorMessage	String	See API Response Codes
statementDescriptor	String	ie: onlinemerchant.com
	Optional Payment Mean fields
paymentMeanInfo	Object	Details of the payment mean (only with special agreement), see Payment Mean Info
paymentMeanToken	String(36)	Internal token of the payment mean (only with special agreement)
schemeTransactionId	String(50)	Unique Transaction Identifier generated by the Scheme (only with special agreement)
	Optional AVS fields
AVSResult	String	See Address Verification System (AVS) policy result codes
FSResult	String	See Fraud Screening (FS) policy result codes
FSStatus	String	See Fraud Screening (FS) policy result codes
	Optional automated subscription fields
subscriptionID	String	Subscription reference returned by the system