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.
HTTP Method | API URL | API Version |
---|---|---|
POST | https://api.payzone.ma/transaction/sale/creditcard | >= 002 |
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 | |
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 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 | |
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) | |
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 |
Note: Gateway API transactions are done with a different library than payment-page API. See the code sample comments for more info:
/*
* 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}";
}
// Instantiate the client and send the transaction information request
// Second argument is the originator ID, third one is the associated API key
Connect2payClient c2p = new Connect2payClient("https://paiement.payzone.ma", "123456",
"GreatP4ssw0rd");
AccountInformationRequest request = new AccountInformationRequest();
AccountInformationResponse response = null;
try {
response = c2p.getAccountInformation(request);
if (response != null) {
System.out.println(response.getName());
System.out.println(response.getSupportUrl());
System.out.println(response.getNotificationSenderName());
System.out.println(response.getNotificationSenderEmail());
// ...
List<PaymentMethodInformation> paymentMethods = response.getPaymentMethods();
if (paymentMethods != null) {
for (PaymentMethodInformation paymentMethod : paymentMethods) {
System.out.println(paymentMethod.getPaymentMethod());
System.out.println(paymentMethod.getPaymentNetwork());
System.out.println(paymentMethod.getDefaultOperation());
System.out.println(paymentMethod.getCurrencies().stream().collect(Collectors.joining(", ")));
List<PaymentMethodOption> pmOptions = ccMethod.getOptions();
if (pmOptions != null) {
for (PaymentMethodOption pmOption : pmOptions) {
System.out.println(pmOption.getName() + ": " + pmOption.getValue());
}
}
}
}
// ...
}
} catch (Exception e) {
logger.error("Ooops, an error occurred getting account information: " + e.getMessage());
// Handle the error...
}
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);
}
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 |
paymentMeanInfo | Object | Details of the payment mean. |
Optional automated subscription fields | ||
subscriptionID | String | Subscription reference returned by the system |