NAV Navbar
Logo

Introduction

NextPay develops and markets an integrated payment processing gateway with built-in database management, decision support and application designed for our client’s needs. The system allows our clients to connect to payment gateway in flexible and intuitive way.

This guide assumes that you have a basic understanding of analysis, software design and of relational databases.

Hosted Payment Form

Logical Structure

The following flow chart explains main process which is very simple:

rss feed

Payment Gateway exchanges data with its clients (Merchants) by Request-Response type of process.

Merchant always initiates the connection process by sending an HTTP POST request to the NextPay Interface.

We answer with a response in the same socket while the average response time is about 1.5-2 seconds.

Request/Response process is identified by sets of fields these provide a safe and reliable connectivity mechanism between merchant and NextPay Payment Gateway.

Operation Steps

  1. Cardholder enters Merchant web store and Clicks “Buy Now”.
  2. Merchant validates and deliverers details to the NextPay Interface.
  3. NextPay interface display the payment form to client.
  4. Client enter the card data on payment form and send to process.
  5. NextPay uses the Bank system interface to process the request and Bank system returns to NextPay a result of the processing request.
  6. NextPay send a Instant Payment Notification return by HTTPS/GET Response by back-office process, this message contain the payment result data.
  7. NextPay display a result page to client.
  8. Client do click on return to commerce button.
  9. Result page resend the payment result data.
  10. Commerce send an email to confirm the order payment approved.

The data exchange is based on several assumptions:

The request and response have different types of fields:

Field Type Description
Mandatory fields are required for the current service request type;
Conditional fields are obligatory in case of using supplementary functions or services provided by NextPay Payment Gateway
Optional fields are included in service request to provide merchant with an extra processing flow visibility and audit on merchant’s side.

Protocol Structure Specification

As an example - the following set of fields can be sent by merchant as one of the permitted service requests by means of HTTPS method within request’s body in an application/www-form-urlencoded" format:

client_name=John& client_lastname=White& client_address=7675+North+street& client_city=Miami&client_state=Florida& client_country=USA& client_postcode=05690& client_phone=5777567567& client_email=mail@example.com& id_commerce=EG456456gfgR& order=10021&amount=1.00& urlreturn=https://www.yoursite.com/urlreturn.php& currency=US

Transaction Types

Sale (sale)

Transaction sales are submitted and immediately flagged for settlement. These transactions will automatically be settled.

Pre-autorization (Auth)

Pre-authorized transactions are submitted but not immediately flagged for settlement. For the transaction to be settled, the merchant must login NextPay Commerce and capture the specific transaction.

Account Information

After your merchant account is approved, you should get the following fields from the NextPay Commerce Support Area:

Data item Description
IDCOM Merchant unique ID to identify you, one for all accounts
Gateway URL URL that will be used for the transaction processing

Default Gateway URL address production account is:

https://nextpay-payments.com/interface/process.do

Pay attention to the following information:

  1. Before sending data to the gateway, it must be checked on your side.
  2. Some fields can be non-mandatory, due to the anti-fraud module settings for your account. For more information, contact your account manager.
    3 No HTML tags are allowed in the filed values, all the HTML code will be removed.
  3. The received data will be url-decoded before the processing.
  4. If you’ll send a transaction with a merchant transaction ID, which already exists for your account, the gateway will reject it. It means that you should avoid multiple submits of the transaction data.
  5. The amount field format must be consistent to ISO currency decimal point (.)

Sale

Request Fields

Following the field descriptions :

Example in php


<?php

$DataKey = '***data key***';

$CommID = '***idCom****';
$BillingName = 'Max';
$BillingLast = 'More';
$BillingAddress = '1st avenue';
$BillingCity = 'London';
$BillingState = 'London';
$BillingCountry = 'GBR';
$BillingZip = '123';
$BillingEmail = 'test@mail.com';
$ClientPhone = '123';
$Order = 'PO54346';
$Amount = '1.0';
$Currency = 'USD';
$TransType = '0';
$URLReturn = 'https://www.test.test.php?';

$linkBuf = $DataKey . "?id_commerce=" . $CommID
        . "&client_name=" . $BillingName
        . "&client_lastname=" . $BillingLast
        . "&client_address=" . $BillingAddress
        . "&client_city=" . $BillingCity
        . "&client_state=" . $BillingState
        . "&client_country=" . $BillingCountry
        . "&client_postcode=" . $BillingZip
        . "&client_email=" . $BillingEmail
        . "&client_phone=" . $ClientPhone
        . "&order=" . $Order
        . "&amount=" . $Amount
        . "&currency=" . $Currency
        . "&trans_type=" . $TransType
        . "&urlreturn=" . $URLReturn
;

$sign = hash("sha256", $linkBuf);
?>

<form method="post" 
      action="https://nextpay-payments.com/interface/process.do">
    <input name="client_name" type="text" value="<?php echo $BillingName; ?>" />
    <input name="client_lastname" type="text" value="<?php echo $BillingLast; ?>" />
    <input name="client_address" type="text" value="<?php echo $BillingAddress; ?>" />
    <input name="client_city" type="text" value="<?php echo $BillingCity; ?>" />
    <input name="client_state" type="text" value="<?php echo $BillingState; ?>" />
    <input name="client_country" type="text" value="<?php echo $BillingCountry; ?>" />
    <input name="client_postcode" type="text" value="<?php echo $BillingZip; ?>" />
    <input name="client_phone" type="text" value="<?php echo $ClientPhone; ?>" />
    <input name="client_email" type="text" value="<?php echo $BillingEmail; ?>" />
    <input name="id_commerce" type="text" value="<?php echo $CommID; ?>" />
    <input name="order" type="text" value="<?php echo $Order; ?>" />
    <input name="amount" type="text" value="<?php echo $Amount; ?>" />
    <input name="currency" type="text" value="<?php echo $Currency; ?>" />
    <input name="urlreturn" type="text" value="<?php echo $URLReturn; ?>" />
    <input name="trans_type" type="text" value="<?php echo $TransType; ?>" />
    <input name="sign" type="text" value="<?php echo $sign; ?>" />
</form>

A Server to server POST request must contain values listed in the table below. All fields are mandatory.

Field Description
id_commerce Your merchant Unique ID. IDCOM value from Commerce Area. The code is necessary for NextPay Gateway to identify the merchant we got request from (the request to start transaction).
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency
urlreturn Redirect URL to return customer after submit payment form or if customer cancel the order.
client_name Cardholder’s first name
client_lastname Cardholder’s last name
client_address Cardholder’s billing address
client_city Cardholder’s billing city
client_state Cardholder’s billing state
client_country Cardholder’s billing country
client_postcode Cardholder’s billing postal code/zip code.
client_phone Cardholder’s billing phone
client_email Cardholder’s billing email
currency Transaction currency, ISO 4217 3-character code (USD, EUR, CHF and other).

Response Fields

After submitting the payment, a response will be returned to commerce “urlreturn” field with the following POST values.

Field Description
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
payment_status Number that describes the payment state.
payment_desc Message that describes the payment result.
authcode Authorization code, if any.
nextpay_order_id NextPay Order id.
cardtype Code that describes the card type used by the Cardholder’s, see card types codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
risk Risk score from 10 to 100, where 100 stands for the highest risk and 0 for the lowest risk

Pre-Authorization

Example in php


<?php
$TransType = '1';
?>

Request Fields

A Server to server POST request must contain values listed in the table below. All fields are mandatory

Field Description
id_commerce Your merchant Unique ID. IDCOM value from Commerce Area. The code is necessary for NextPay Gateway to identify the merchant we got request from (the request to start transaction).
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency
urlreturn Redirect URL to return customer after submit payment form or if customer cancel the order.
client_name Cardholder’s first name
client_lastname Cardholder’s last name
client_address Cardholder’s billing address
client_city Cardholder’s billing city
client_state Cardholder’s billing state
client_country Cardholder’s billing country
client_postcode Cardholder’s billing postal code/zip code.
client_phone Cardholder’s billing phone
client_email Cardholder’s billing email
currency Transaction currency, ISO 4217 3-character code (USD, EUR, CHF and other).
trans_type This field specifies the type of transaction (0=sales,1=pre-authorization)

Response Fields

After submitting the payment, a response will be returned to commerce “urlreturn” field with the following POST values.

Field Description
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
payment_status Number that describes the payment state.
payment_desc Message that describes the payment result.
authcode Authorization code, if any.
nextpay_order_id NextPay Order id.
cardtype Code that describes the card type used by the Cardholder’s, see card types codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
trans_type the type of transaction that was process

Hosted Recurring Form

Concept

The recurring payments is another feature that NextPay offers to its merchants. The system allows setting a range of products, together with the pricing and billing cycle and allowing customers to subscribe to these products in order to access the services sold on the merchant website.

Logical Structure

The subscription request is similar to a single payment; the difference is the data send to the processor and the additional data that NextPay interface returns. The following flow chart explains the main process:

rss feed

Payment Gateway exchanges data with its clients (Merchants) by Request-Response process type.

Merchant always initiates the connection process by sending an HTTP POST request to the NextPay Interface.

NextPay provides an answer with a response in the same socket. Average response time is about 1.5-2 seconds.

Request/Response process is identified by sets of fields, these provide a safe and reliable connectivity mechanism between merchant and NextPay Payment Gateway.

Operation Steps

The first part of the integration is the request to create a new subscriber to the commerce product.

  1. Cardholder enters merchant’s web store and clicks “Buy Now”.
  2. Merchant validates and deliverers details to the Backend System.
  3. Merchant Backend System sends to Nextpay HTTPS/POST Request.
  4. NextPay uses the Bank System interface to process the request.
  5. Bank system returns to NextPay a result of the processing request.
  6. NextPay replies to the Merchant Backend System in HTTPS/POST Response.
  7. Merchant Backend System parses and stores response locally. Translates the response to the cardholder.
  8. Cardholder gets the final response from the Merchant web store.

Attention Pay attention to the following information:

  1. All data must be checked on merchant side before sending to NextPay gateway.
  2. Some fields can be non-mandatory, due to the anti-fraud module settings for your account. For more information, contact your account manager.
  3. No HTML tags are allowed in the filed values, all the HTML code will be removed.
  4. The received data will be url-decoded before the processing.
  5. All transactions sent with repeated merchant transaction ID’s will be rejected by NextPay gateway system. It means that you should avoid multiple submits of the transaction data.

Protocol Structure Specification

As an example - the following set of fields can be sent by merchant as one of the permitted service requests by means of HTTPS method within request’s body in an application/www-form-urlencoded" format:

client_name=John& client_lastname=White& client_address=7675+North+street& client_city=Miami&client_state=Florida& client_country=USA& client_postcode=05690& client_phone=5777567567& client_email=mail@example.com& id_commerce=EG456456gfgR& order=10021&amount=1.00& urlreturn=https://www.yoursite.com/urlreturn.php& currency=USD

Account Information

The following fields are available from the NextPay Commerce GUI:

Data item Description
IDCOM Merchant unique ID to identify you, one for all accounts
Gateway URL URL that will be used for the transaction processing
Product key The product key, when you create a recurring product.

Default Gateway URL address for production stage:

https://nextpay-payments.com/interface/subcription.do

Product Settings (Back Office)

The merchant must contact NextPay customer service in order to activate the recurring payment feature.

rss feed

When the recurring payment feature is active, the commerce must set up the products sold in their store in the NextPay Commerce GUI.

rss feed

After setting up the product in the NextPay Commerce GUI, you must obtain the product key in the Product View:

rss feed

Subscriptions

Subscription Request Fields

Example in php


<?php

$DataKey = '***data key***';

$CommID = '***idCom****';
$BillingName = 'Max';
$BillingLast = 'More';
$BillingAddress = '1st avenue';
$BillingCity = 'London';
$BillingState = 'London';
$BillingCountry = 'GBR';
$BillingZip = '123';
$BillingEmail = 'test@mail.com';
$ClientPhone = '123';
$Order = 'PO54346';
$ProductKey = 'i920131014102651s3Q';
$TransType = '0';
$URLReturn = 'https://www.test.test.php?';

$linkBuf = $DataKey . "?id_commerce=" . $CommID
        . "&client_name=" . $BillingName
        . "&client_lastname=" . $BillingLast
        . "&client_address=" . $BillingAddress
        . "&client_city=" . $BillingCity
        . "&client_state=" . $BillingState
        . "&client_country=" . $BillingCountry
        . "&client_postcode=" . $BillingZip
        . "&client_email=" . $BillingEmail
        . "&client_phone=" . $ClientPhone
        . "&order=" . $Order
        . "&product_key”=" . $ProductKey
        . "&trans_type=" . $TransType
        . "&urlreturn=" . $URLReturn
;

$sign = hash("sha256", $linkBuf);
?>

<form method="post" 
      action="https://nextpay-payments.com/interface/subcription.do">
    <input name="client_name" type="text" value="<?php echo $BillingName; ?>" />
    <input name="client_lastname" type="text" value="<?php echo $BillingLast; ?>" />
    <input name="client_address" type="text" value="<?php echo $BillingAddress; ?>" />
    <input name="client_city" type="text" value="<?php echo $BillingCity; ?>" />
    <input name="client_state" type="text" value="<?php echo $BillingState; ?>" />
    <input name="client_country" type="text" value="<?php echo $BillingCountry; ?>" />
    <input name="client_postcode" type="text" value="<?php echo $BillingZip; ?>" />
    <input name="client_phone" type="text" value="<?php echo $ClientPhone; ?>" />
    <input name="client_email" type="text" value="<?php echo $BillingEmail; ?>" />
    <input name="id_commerce" type="text" value="<?php echo $CommID; ?>" />
    <input name="order" type="text" value="<?php echo $Order; ?>" />
    <input type="hidden" name="product_key" value="<?php echo ProductKey; ?>" />  
    <input name="urlreturn" type="text" value="<?php echo $URLReturn; ?>" />
    <input name="trans_type" type="text" value="<?php echo $TransType; ?>" />
    <input name="sign" type="text" value="<?php echo $sign; ?>" />
</form>

A server-to-server POST request must contain values listed in the table below. All fields are mandatory.

Field Description
id_commerce Your merchant Unique ID. IDCOM value available NextPay Commerce GUI. This code is necessary for Nextpay Gateway to identify the merchant we get request from (the request to start transaction).
order Merchant order ID/invoice (e.g. INV10001)
urlreturn Redirect URL to return customer after submit payment form or if customer cancel the order or accept the order.
client_name Cardholder’s first name
client_lastname Cardholder’s last name
client_address Cardholder’s billing address
client_city Cardholder’s billing city
client_state Cardholder’s billing state
client_country Cardholder’s billing country
client_postcode Cardholder’s billing postal code/zip code.
client_phone Cardholder’s billing phone
client_email Cardholder’s billing email
product_key The product key, when you create a recurring product.

Subscription Response Fields

After payment has been submitted, a response will be returned to commerce “urlreturn” field with the following POST values.

Field Description
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency
payment_status Number that describes the payment state sees payment states.
payment_desc Message that describes the payment result authcode Authorization code, if any.
nextpay_order_id NextPay Order id
cardtype Code that describes the card type used by the Cardholder, see cardtype codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process.
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
subcription_id The success subscription id.
sub_creation The subscription created date.
sub_card_status The card status.
card_bin The first 6 card numbers.
card_last4 The last 4 card numbers.
pay_attemps The number of success payment, initial must be “1” to subscriptions success results.
sub_status The subscription status. last_payment Last payment date.
sub_acumulate The result between the pay_attemps * product amount.
sub_cancelled Subscription cancelled date.

Subscription Check Status

The second part of the integration is the subscription status check, with different data send to NextPay Interface.

Example in php

<form method="post" 
      action="https://nextpay-payments.com/interface/recurring/status.do">  
<input type="hidden" name="id_commerce" value="EG456456gfgR" />  
<input type="hidden" name=" subcription_id” value=" 0001 " />  
<input type="hidden" name="urlreturn" value="https://www.yoursite.com/urlreturn.php" />   
</form>

Request Fields

A server-to-server POST request must contain values listed in the table below. All fields are mandatory

Field Description
id_commerce Your merchant Unique ID. IDCOM value available NextPay Commerce GUI. This code is necessary for NextPay Gateway to identify the merchant we get request from (the request to start transaction).
urlreturn Redirect URL to return customer after submit payment form or if customer cancel the order or accept the order.
subcription_id The subscription id to check info.

Default Gateway URL address for production stage is:

https://nextpay-payments.com/interface/recurring/status.do

Response Fields

After payment has been submitted, a response will be returned to commerce “urlreturn” field with the following POST values.

Field Description
order Merchant order ID/invoice (e.g. INV10001)
product_amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency
payment_status Number that describes the payment state sees payment states.
payment_desc Message that describes the payment result authcode Authorization code, if any.
nextpay_order_id Nextpay Order ID cardtype Code that describes the card type used by the Cardholder’s, see cardtype codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process.
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
subcription_id The success subscription id.
sub_creation The subscription created date.
sub_card_status The card status.
card_bin The first 6 card numbers.
card_last4 The last 4 card numbers.
pay_attemps The number of success payment, initial must be “1” to subscriptions success results.
sub_status The subscription status.
last_payment Last payment date. sub_acumulate The result between the pay_attemps * product amount.
sub_cancelled Subscription cancelled date.
product_id The product id for this subscription.
start_pay The subscription start payment date
product_time_frame The product time frame name.
product_pay_cycles The product pay cycles until cancelled subscription.
product_sku The product SKU.

Subscription Cancel

The third part of the integration is the subscription cancel, with different data send to NextPay Interface.

Example in php

<form method="post" 
      action="https://nextpay-payments.com/interface/recurring/cancel.do">  
<input type="hidden" name="id_commerce" value="EG456456gfgR" />  
<input type="hidden" name=" subcription_id” value=" 0001 " />  
<input type="hidden" name="urlreturn" value="https://www.yoursite.com/urlreturn.php" />   
</form>

Request Fields

A server-to-server POST request must contain values listed in the table below. All fields are mandatory.

Field Description
id_commerce Your merchant Unique ID. IDCOM value available NextPay Commerce GUI. This code is necessary for NextPay Gateway to identify the merchant we get request from (the request to start transaction).
urlreturn Redirect URL to return customer after submit payment form or if customer cancel the order or accept the order.
subcription_id The subscription id to check info.

Default Gateway URL address for production stage is:

https://nextpay-payments.com/interface/recurring/cancel.do

Response Fields

After payment has been submitted, a response will be returned to commerce “urlreturn” field with the following POST values.

Field Description
order Merchant order ID/invoice (e.g. INV10001)
product_amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency
payment_status Number that describes the payment state sees payment states.
payment_desc Message that describes the payment result authcode Authorization code, if any.
nextpay_order_id Nextpay Order ID
cardtype Code that describes the card type used by the Cardholder, see cardtype codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process.
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
subcription_id The success subscription id. sub_creation The subscription created date.
sub_card_status The card status.
card_bin The first 6 card numbers.
card_last4 The last 4 card numbers.
pay_attemps The number of success payment, initial must be “1” to subscriptions success results.
sub_status The subscription status.
last_payment Last payment date.
sub_acumulate The result between the pay_attemps * product amount.
sub_cancelled Subscription cancelled date.
product_id The product id for this subscription.
start_pay The subscription start payment date
product_time_frame The product time frame name.
product_pay_cycles The product pay cycles until cancelled subscription.
product_sku The product SKU.

Recurring Payment Service

This service runs each day at the 23:30, the subscription processing result is sent to the merchant administrative contact via email.

For each subscription, the system sends an email to the cardholder and another email to the merchant administrative contact.

Subscription Cancelled Conditions

The subscriptions have a lifecycle of 4 years, if the time cycle is defined “until cancelled”.

Also one subscription is cancelled when the charge cycle it’s over.

Light Checkout

Example in php/html


 <script src="https://nextpay-payments.com/interface/dynamic/js/dynamic.js"></script>


<?php

$DataKey = '***data key***';

$CommID = '***idCom****';
$BillingName = 'Max';
$BillingLast = 'More';
$BillingAddress = '1st avenue';
$BillingCity = 'London';
$BillingState = 'London';
$BillingCountry = 'GBR';
$BillingZip = '123';
$BillingEmail = 'test@mail.com';
$ClientPhone = '123';
$Order = 'PO54346';
$Amount = '1.0';
$Currency = 'USD';
$TransType = '0';
$URLReturn = 'https://www.test.test.php?';

$linkBuf = $DataKey . "?id_commerce=" . $CommID
        . "&client_name=" . $BillingName
        . "&client_lastname=" . $BillingLast
        . "&client_address=" . $BillingAddress
        . "&client_city=" . $BillingCity
        . "&client_state=" . $BillingState
        . "&client_country=" . $BillingCountry
        . "&client_postcode=" . $BillingZip
        . "&client_email=" . $BillingEmail
        . "&client_phone=" . $ClientPhone
        . "&order=" . $Order
        . "&amount=" . $Amount
        . "&currency=" . $Currency
        . "&trans_type=" . $TransType
        . "&urlreturn=" . $URLReturn
;

$sign = hash("sha256", $linkBuf);
?>

 <form method="post"  action="https://nextpay-payments.com/interface/dynamic/">
    <input name="client_name" type="text" value="<?php echo $BillingName; ?>" />
    <input name="client_lastname" type="text" value="<?php echo $BillingLast; ?>" />
    <input name="client_address" type="text" value="<?php echo $BillingAddress; ?>" />
    <input name="client_city" type="text" value="<?php echo $BillingCity; ?>" />
    <input name="client_state" type="text" value="<?php echo $BillingState; ?>" />
    <input name="client_country" type="text" value="<?php echo $BillingCountry; ?>" />
    <input name="client_postcode" type="text" value="<?php echo $BillingZip; ?>" />
    <input name="client_phone" type="text" value="<?php echo $ClientPhone; ?>" />
    <input name="client_email" type="text" value="<?php echo $BillingEmail; ?>" />
    <input name="id_commerce" type="text" value="<?php echo $CommID; ?>" />
    <input name="order" type="text" value="<?php echo $Order; ?>" />
    <input name="amount" type="text" value="<?php echo $Amount; ?>" />
    <input name="currency" type="text" value="<?php echo $Currency; ?>" />
    <input name="urlreturn" type="text" value="<?php echo $URLReturn; ?>" />
    <input name="trans_type" type="text" value="<?php echo $TransType; ?>" />
    <input name="sign" type="text" value="<?php echo $sign; ?>" />
</form>

To use the “Light Checkout” service you must add to your website the following javascrip link at the head of your website

https://nextpay-payments.com/interface/dynamic/js/dynamic.js

Once this is done, you must add an html form in your html render area, this form will be responsible for sending the data to the Light Checkout page

Please note that the target link is:

https://nextpay-payments.com/interface/dynamic/

Soap API Integration

Developers can access to the WSDL in the following link:

https://nextpay-payments.com/interface/serv/api.php?wsdl

Here can find the different services provide by NextPay Gateway. The developer should also have knowledge of complex-type, this because the main fields are of this type of data. On the following link you can find the testing environment to prepare your website to process on live mode.

API mode is an integration of your website to NextPay Payment Gateway which allows to receive credit cards on a web page without having customers redirect to another web page.

Secure Communication

For the highest level of security when an order is processed through the API, NextPay implemented digital certificates to encrypt the XML files they are sent to NextPay Interface.

The certificates using the RSA algorithm based on public and private key. Following some Cert creation examples:

  1. Create merchant private key

openssl genrsa –out COMMERCENAME.PRIVATE.pem 1024

  1. Create merchant public key

openssl rsa –in COMMERCENAME.PRIVATE.pem –out COMMERCENAME.PUBLIC.pem – pubout

The software recommended to generate the key pair is OpenSSL, please find on the following link:

www.slproweb.com/products/Win32OpenSSL.html

Key Settings

The merchant must generate their own RSA key pair (Public and private), to generate the keys you can use the OPENSSL library. Next download the NextPay public key from NextPay Commerce in the following link:

https://nextpay-payments.com/commerce/login.php

In the next image can be helpful to us to find the website keys section.

rss feed

Afterwards that you have been generated the pair keys you can save the merchant public key in the NextPay commerce APIS keys section.

rss feed

Also you can get the idcom in the website section on the site.

Services

The services that NextPay API Provide are the next:

  1. sendPayment
  2. sendCapture
  3. sendVoid
  4. sendRefund
  5. sendSub

All messages fields are mandatories. Each service has 4 main complex-type fields

Field Description
IDCOM Set the merchant Unique ID. IDCOM value from Commerce web area. The code is necessary for NextPay Gateway to identify the merchant we got request from (the request to start transaction).
SIGN Set the result of the process of signed with private key.
KEY Set the result of the process of signed with public key.
DATA Set the encrypted XML, this XML must have all fields in the desired service.

Example in


<?php 
require_once('lib/nusoap.php');

$sSoapServiceURL = 'http://nextpay-payments.com/testing/serv/api.php?wsdl'; 
$sMerchantPrivate = 'SET HERE THE MERCHANT PRIVATE KEY'; 
$sNextPayPublic = ' SET HERE THE NEXTPAY PUBLIC KEY '; 
$IDCOM = 'SET HERE THE IDCOM'; 
////////////////////////////////////////////////////////////////////////////////////////////// 

$oSOAP = new \nusoap_client($sSoapServiceURL, true); 

$oXml = new SimpleXMLElement('<data></data>'); 
$oBilling = $oXml->addChild('Billing'); 
$oBilling->addChild('client_name', 'MATT'); 
$oBilling->addChild('client_lastname', 'SMITH'); 
$oBilling->addChild('client_address', '2ND STREET'); 
$oBilling->addChild('client_city', 'MIAMI'); 
$oBilling->addChild('client_state', 'FLORIDA'); 
$oBilling->addChild('client_country', 'USA'); 
$oBilling->addChild('client_postcode', '01234'); 
$oBilling->addChild('client_phone', '555555555'); 
$oBilling->addChild('client_email', 'test@somecommerce.com'); 

$oCard = $oXml->addChild('Card'); 
$oCard->addChild('Number', '4111111111111111'); 
$oCard->addChild('Name', 'MATT SMITH'); 
$oCard->addChild('Year', '2020'); 
$oCard->addChild('Month', '01'); 
$oCard->addChild('CSC', '999'); 

$oOrder = $oXml->addChild('Order'); 
$oOrder->addChild('order_num', 'INV_001'); 
$oOrder->addChild('amount', '2.00'); 
$oOrder->addChild('trans_type', '1'); 
$oOrder->addChild('currency', 'USD'); 
$oOrder->addChild('csid', '-----csid data about the client---'); //if is required 

$sXML = $oXml->asXML(); 

//////////////////////////////////////////////////////////////////////////////// 
// start encryption process 
// sign unencrypted data 
$sMerchantPrivateID = openssl_get_privatekey($sMerchantPrivate); 
if (openssl_sign($sXML, $sFirma, $sMerchantPrivateID)) {     
echo '<br>Signing OK!<br>'; 
} 
else {     
echo '<br>Signing FAILED! ' . openssl_error_string() . '<br>'; 
};

openssl_free_key($sMerchantPrivateID); 

//////////////////////////////////////////////////////////////////////////////// 
// encrypt data 
$sMerchantPublicID = openssl_get_publickey($sNextPayPublic); 
if (openssl_seal($sXML, $sData, $ekeys, array($sMerchantPublicID))) {     
$sKey = $ekeys[0];     
echo '<br>Encrypting OK!<br>'; 
} 
else {     
echo '<br>Encrypting FAILED! ' . openssl_error_string() . '<br>'; 
}; 
openssl_free_key($sMerchantPublicID); 

//encode signature, key and data to Base64 
////////////////////////////////////////////////////////////////////////////////
// END ENCRYPTION PROCESS   
//ENCODE IN BASE64 AFTER TO SEND 
$sFirma = base64_encode($sFirma); 
$sKey = base64_encode($sKey); 
$sData = base64_encode($sData); 

// SET THE VALUES IN COMPLEX TYPES 
$v_req = new StdClass(); 
$v_req->IDCOM = $IDCOM; 
$v_req->SIGN = $sFirma; 
$v_req->KEY = $sKey; 
$v_req->DATA = $sData; 

$error = $oSOAP->getError(); 
if ($error) {     
echo "<h2>Constructor error</h2><pre>" . $error . "</pre>"; 
} 
//////////////////////////////////////////////////////////////////////////////// 
//// CALL SERVICE 
$sResult = $oSOAP->call('sendPayment', array("input" => $v_req)); 

if ($oSOAP->fault) {     
echo "<h2>Fault</h2><pre>";     
print_r($sResult);     
echo "</pre>"; 
} 
else {     
$error = $oSOAP->getError();     
if ($error) {         
echo "<h2>Error</h2><pre>" . $error . "</pre>";     
} 
else {         
echo "<h2>Books</h2><pre>";         
var_dump($sResult);         
echo "</pre>";     
} 

} //////////////////////////////////////////////////////////////////////////////// 
//DECODE IN BASE64 AFTER TO SEND 
$sign = base64_decode($sResult['SIGN']); 
$key = base64_decode($sResult['KEY']); 
$data = base64_decode($sResult['DATA']); 

//////////////////////////////////////////////////////////////////////////////// 
// decrypt data 
$merchantkeyid = openssl_get_privatekey($sMerchantPrivate); 
if (openssl_open($data, $data, $key, $merchantkeyid)) {     
echo '<br><br>Decrypting OK!<br>'; 
} 
else {     
echo '<br><br>Decrypting FAILED! ' . openssl_error_string() . '<br>'; 
};
openssl_free_key($merchantkeyid); 

//////////////////////////////////////////////////////////////////////////////// 
// verify signature 
$systemkeyid = openssl_get_publickey($sNextPayPublic); 
if (openssl_verify($data, $sign, $systemkeyid) == 1) {     

echo '<br>Verifying OK!<br>';     

$xml = simplexml_load_string($data); 

} 
else {     

unset($xml);     

echo '<br>Verifying FAILED! ' . openssl_error_string() . '<br>'; 

}; 
openssl_free_key($systemkeyid); 

//////////////////////////////////////////////////////////////////////////////// 
//PRINT RESULT FIELD 
echo var_dump($xml); ?> 

sendPayment

Transaction sales are submitted and immediately flagged for settlement. These transactions will automatically be settled.

The following fields are parameters for this operation:

Field Description
order_num Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency
urlreturn Redirect URL to return customer after submit payment form or if customer cancel the order.
client_name Cardholder’s first name
client_lastname Cardholder’s last name
client_address Cardholder’s billing address
client_city Cardholder’s billing city
client_state Cardholder’s billing state
client_country Cardholder’s billing country, should be in ISO 3166 format 3-chars
client_postcode Cardholder’s billing postal code/zip code.
client_phone Cardholder’s billing phone
client_email Cardholder’s billing email currency Transaction currency, ISO 4217 3-character code (USD, EUR, CHF and other).
trans_type Identifies if a transaction is a pre-authorization or a simple sale.
number Card number
name Card name
year Expiration date 4 chars
month Expiration date 2 chars
csc Card CVV
csid Optional, please ask to the NextPay account manager if this field is required

sendCapture

Perform a capture transaction for one existing transaction already approved, is necessary for finish the charge for a pre-authorization request.

The following fields are parameters for this operation:

Field Description
nextpay_order_id The NextPay transaction id

sendVoid

Perform a void transaction for one existing transaction already approved, is necessary for cancel a pre-authorization request.

The following fields are parameters for this operation:

Field Description
nextpay_order_id The NextPay transaction id

sendRefund

This service is required to return the amount of payment previously done. The following fields are parameters for this operation:

Field Description
nextpay_order_id The NextPay transaction id

sendSub

Transaction sales are submitted and immediately flagged for settlement. These transactions will automatically be settled.

The following fields are parameters for this operation:

Field Description
Order_num Merchant order ID/invoice (e.g. INV10001)
client_name Cardholder’s first name
client_lastname Cardholder’s last name
client_address Cardholder’s billing address
client_city Cardholder’s billing city
client_state Cardholder’s billing state
client_country Cardholder’s billing country, should be in ISO 3166 format 3-chars
client_postcode Cardholder’s billing postal code/zip code.
client_phone Cardholder’s billing phone
client_email Cardholder’s billing email
Number Card number
Name Card name
Year Expiration date 4 chars
Month Expiration date 2 chars
CSC Card CVV
CSID Optional, please ask to the NextPay account manager if this field is required

Response Fields

The NextPay response is standard message for most of NextPay operations except sendSub that have more fields to notify to the merchant about the recurring status.

Following the response standard fields:

Field Description
order_num Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
payment_status Number that describes the payment state.
payment_desc Message that describes the payment result.
authcode Authorization code, if any.
nextpay_order_id NextPay Order id.
cardtype Code that describes the card type used by the Cardholder’s, see card-type codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
trans_type Transaction type sale or pre-authorizations
msg A user friendly message, can you use to show on screen to card member notify
subcription_id Subscription identifier id sub_creation Creation date
sub_card_status Card status card_bin Card BIN
card_last4 Last four digit of the card number
pay_attemps Total Pay attempts for this Subscription
sub_status Status for this Subscription active/cancelled last_payment Last payment date
sub_acumulate Payments done for this Subscription
sub_cancelled Cancelled date for this Subscription

CSID

Example in php

On the xml soap request


<?php
$oOrder->addChild('csid', '----------here the long text------'); 
?>

Sometime on a few cases the banks need an additional parameter to use in their own antifraud system. The merchant must send the CSID parameter the following way:

Next, find the library addition on your website, with the following script to catch the CSID information:

Added the library

<script type='text/javascript' charset='utf-8' src='https://onlinesafest.com/pub/csid.js'></script> 

For CSID data settings, this field is about antifraud data. This library collects data from client browser, to use it you can put a hidden field that the library will take care of filling

Send the data

<input name="csid" type="hidden" id='csid'> 

WSDL

WSDL stands for Web Services Description Language.

WSDL is a document written in XML. The document describes a Web service. It specifies the location of the service and the operations (or methods) the service exposes.

API Call Log

This testing environment is like a sand-box that can return a decline messages to the merchant if the data fields are send on a wrong way. The Integration Assistant returns to the merchant an exact error about the issue. When a decline transaction is detected the IA system create a log record that the merchant can see on NextPay Commerce on “API call Logs”

rss feed

Here the merchant can find more messages about the decline reason, on red rectangle the merchant order number.

rss feed

Rest API Integration

API mode is an integration of your website to NextPay Payment Gateway which allows to receive credit cards on a web page without having customers redirect to another web page.

Authorizations

Request

Example in php


 <?php

$DataKey = '*** data key ***';

$PrivateKey = '*** merchant private key ***';

$aDatos['id_commerce'] = '*** id com ***';
$aDatos['billing_name'] = 'Max';
$aDatos['billing_lastname'] = 'Moore';
$aDatos['billing_address'] = '1st avenue';
$aDatos['billing_city'] = 'London';
$aDatos['billing_state'] = 'London';
$aDatos['billing_country'] = 'GBR';
$aDatos['billing_zip'] = '123';
$aDatos['billing_phone'] = '555666788';
$aDatos['billing_email'] = 'test@mail.com';
$aDatos['order'] = 'PO54346';
$aDatos['amount'] = '1.0';
$aDatos['currency'] = 'USD';
$aDatos['trans_type'] = '0';

$CardName = 'Test Card';
$CardMonth = '12';
$CardYear = '2020';
$CardNumber = '4111111111111111';
$CardCSC = '123';

$linkBuf = $DataKey . "?id_commerce=" . $aDatos['id_commerce']
        . "&billing_name=" . $aDatos['billing_name']
        . "&billing_lastname=" . $aDatos['billing_lastname']
        . "&billing_address=" . $aDatos['billing_address']
        . "&billing_city=" . $aDatos['billing_city']
        . "&billing_state=" . $aDatos['billing_state']
        . "&billing_country=" . $aDatos['billing_country']
        . "&billing_zip=" . $aDatos['billing_zip']
        . "&billing_phone=" . $aDatos['billing_phone']
        . "&billing_email=" . $aDatos['billing_email']
        . "&order=" . $aDatos['order']
        . "&amount=" . $aDatos['amount']
        . "&currency=" . $aDatos['currency']
        . "&trans_type=" . $aDatos['trans_type']
        . "&card_name=" . $CardName
        . "&card_month=" . $CardMonth
        . "&card_year=" . $CardYear
        . "&card_number=" . $CardNumber
        . "&card_csc=" . $CardCSC;

$sign = hash("sha256", $linkBuf);

$SiteTarget = "https://nextpay-payments.com/interface/serv-rest/api.php?request=Authorizations";
$aDatos['csid'] = 'test';
$aDatos['sign'] = $sign;

//card encrypt
$CardData = $CardName . "|" . $CardNumber . "|" . $CardMonth . "|" . $CardYear . "|" . $CardCSC;
$KeyLoaded = openssl_pkey_get_private($PrivateKey);
openssl_private_encrypt($CardData, $Encrypted, $KeyLoaded);
$CardDataEncrypted = base64_encode($Encrypted);

$aDatos['card'] = $CardDataEncrypted;

$Conn = curl_init($SiteTarget);
curl_setopt($Conn, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt($Conn, CURLOPT_USERAGENT, "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)");
curl_setopt($Conn, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($Conn, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($Conn, CURLOPT_POST, TRUE);
curl_setopt($Conn, CURLOPT_POSTFIELDS, http_build_query($aDatos, '', '&'));

$R = curl_exec($Conn);
curl_close($Conn);

var_dump($R);
?>

Field Description
billing_name Cardholder’s first name
billing_lastname Cardholder’s last name
billing_address Cardholder’s billing address
billing_city Cardholder’s billing city
billing_state Cardholder’s billing state
billing_country Cardholder’s billing country, should be in ISO 3166 format 3-chars
billing_zip Cardholder’s billing postal code/zip code.
billing_phone Cardholder’s billing phone
billing_email Cardholder’s billing email currency Transaction currency, ISO 4217 3-character code (USD, EUR, CHF and other).
trans_type Identifies if a transaction is a pre-authorization or a simple sale.
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency
card all card data encrypted. See “Card Encryption” section.
csid Optional, please ask to the NextPay account manager if this field is required
id_commerce commerce account identifier
sign checksum key

Response

Json response

{
"trans_type":"0",
"order":"170531030116",
"payment_status":"10",
"payment_desc":"Accepted",
"amount":"1.00",
"authcode":"2323026",
"nextpay_order_id":"2323026",
"cardtype":"Visa",
"currency":"USD",
"risk":"1.26",
"msg":"Transaction received correctly.",
"nextpay_refund_id":""
}
Field Description
trans_type Identifies if a transaction is a pre-authorization or a simple sale.
order Merchant order ID/invoice (e.g. INV10001)
payment_status Number that describes the payment state.
payment_desc Message that describes the payment result.
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
authcode Authorization code, if any.
nextpay_order_id NextPay Order id.
cardtype Code that describes the card type used by the Cardholder’s, see cardtype codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
msg A user friendly message, can you use to show on screen to cardmember notify

Refunds

Request

Example in php


<?php

$DataKey = '*** data key ***';

$aDatos['id_commerce'] = '*** id com ***';
$aDatos['nextpay_order_id'] = '3245345345'; 

$linkBuf = $DataKey . "?id_commerce=" . $aDatos['id_commerce']
        . "&nextpay_order_id=" . $aDatos['nextpay_order_id'] ;

$sign = hash("sha256", $linkBuf);

$SiteTarget = "https://nextpay-payments.com/interface/serv-rest/api.php?request=Refunds";
$aDatos['csid'] = 'test';
$aDatos['sign'] = $sign;
$FieldString = http_build_query($aDatos, '', '&');


$Conn = curl_init($SiteTarget);
curl_setopt($Conn, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt($Conn, CURLOPT_USERAGENT, "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)");
curl_setopt($Conn, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($Conn, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($Conn, CURLOPT_POST, TRUE);
curl_setopt($Conn, CURLOPT_POSTFIELDS, $FieldString);

$R = curl_exec($Conn);
curl_close($Conn);

var_dump($R);
?>

Field Description
nextpay_order_id The NextPay transaction id
id_commerce commerce account identifier
sign checksum key

Response

Json response

{
"trans_type":"0",
"order":"",
"payment_status":"10",
"payment_desc":"Accepted",
"amount":"",
"authcode":"",
"nextpay_order_id":"",
"cardtype":"",
"currency":"",
"risk":0,
"msg":"Accepted",
"nextpay_refund_id":""
}
Field Description
trans_type Identifies if a transaction is a pre-authorization or a simple sale.
order Merchant order ID/invoice (e.g. INV10001)
payment_status Number that describes the payment state.
payment_desc Message that describes the payment result.
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
authcode Authorization code, if any.
nextpay_order_id NextPay Order id.
cardtype Code that describes the card type used by the Cardholder’s, see cardtype codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
msg A user friendly message, can you use to show on screen to cardmember notify

Captures

Request

Example in php


<?php

$DataKey = '*** data key ***';

$aDatos['id_commerce'] = '*** id com ***';
$aDatos['nextpay_order_id'] = '3245345345'; 

$linkBuf = $DataKey . "?id_commerce=" . $aDatos['id_commerce']
        . "&nextpay_order_id=" . $aDatos['nextpay_order_id'] ;

$sign = hash("sha256", $linkBuf);

$SiteTarget = "https://nextpay-payments.com/interface/serv-rest/api.php?request=Captures";
$aDatos['csid'] = 'test';
$aDatos['sign'] = $sign;
$FieldString = http_build_query($aDatos, '', '&');


$Conn = curl_init($SiteTarget);
curl_setopt($Conn, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt($Conn, CURLOPT_USERAGENT, "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)");
curl_setopt($Conn, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($Conn, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($Conn, CURLOPT_POST, TRUE);
curl_setopt($Conn, CURLOPT_POSTFIELDS, $FieldString);

$R = curl_exec($Conn);
curl_close($Conn);

var_dump($R);
?>

Field Description
nextpay_order_id The NextPay transaction id
id_commerce commerce account identifier
sign checksum key

Response

Json response

{
"trans_type":"0",
"order":"",
"payment_status":"10",
"payment_desc":"Accepted",
"amount":"",
"authcode":"",
"nextpay_order_id":"",
"cardtype":"",
"currency":"",
"risk":0,
"msg":"Accepted",
"nextpay_refund_id":""
}
Field Description
trans_type Identifies if a transaction is a pre-authorization or a simple sale.
order Merchant order ID/invoice (e.g. INV10001)
payment_status Number that describes the payment state.
payment_desc Message that describes the payment result.
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
authcode Authorization code, if any.
nextpay_order_id NextPay Order id.
cardtype Code that describes the card type used by the Cardholder’s, see cardtype codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
msg A user friendly message, can you use to show on screen to cardmember notify

Voids

Request

Example in php


<?php

$DataKey = '*** data key ***';

$aDatos['id_commerce'] = '*** id com ***';
$aDatos['nextpay_order_id'] = '3245345345'; 

$linkBuf = $DataKey . "?id_commerce=" . $aDatos['id_commerce']
        . "&nextpay_order_id=" . $aDatos['nextpay_order_id'] ;

$sign = hash("sha256", $linkBuf);

$SiteTarget = "https://nextpay-payments.com/interface/serv-rest/api.php?request=Voids";
$aDatos['csid'] = 'test';
$aDatos['sign'] = $sign;
$FieldString = http_build_query($aDatos, '', '&');


$Conn = curl_init($SiteTarget);
curl_setopt($Conn, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt($Conn, CURLOPT_USERAGENT, "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)");
curl_setopt($Conn, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($Conn, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($Conn, CURLOPT_POST, TRUE);
curl_setopt($Conn, CURLOPT_POSTFIELDS, $FieldString);

$R = curl_exec($Conn);
curl_close($Conn);

var_dump($R);
?>


Field Description
nextpay_order_id The NextPay transaction id
id_commerce commerce account identifier
sign checksum key

Response

Json response

{
"trans_type":"0",
"order":"",
"payment_status":"10",
"payment_desc":"Accepted",
"amount":"",
"authcode":"",
"nextpay_order_id":"",
"cardtype":"",
"currency":"",
"risk":0,
"msg":"Accepted",
"nextpay_refund_id":""
}
Field Description
trans_type Identifies if a transaction is a pre-authorization or a simple sale.
order Merchant order ID/invoice (e.g. INV10001)
payment_status Number that describes the payment state.
payment_desc Message that describes the payment result.
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
authcode Authorization code, if any.
nextpay_order_id NextPay Order id.
cardtype Code that describes the card type used by the Cardholder’s, see cardtype codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
msg A user friendly message, can you use to show on screen to cardmember notify

Subscriptions

Request

Example in php


<?php

$DataKey = '*** data key ***';

$PrivateKey = '*** merchant private key ***';

$aDatos['id_commerce'] = '*** id com ***';
$aDatos['billing_name'] = 'Max';
$aDatos['billing_lastname'] = 'Moore';
$aDatos['billing_address'] = '1st avenue';
$aDatos['billing_city'] = 'London';
$aDatos['billing_state'] = 'London';
$aDatos['billing_country'] = 'GBR';
$aDatos['billing_zip'] = '123';
$aDatos['billing_phone'] = '555666788';
$aDatos['billing_email'] = 'test@mail.com';
$aDatos['order'] = 'PO54346';
$aDatos['product_key'] = 'PROD123';
$aDatos['trans_type'] = '0';

$CardName = 'Test Card';
$CardMonth = '12';
$CardYear = '2020';
$CardNumber = '4111111111111111';
$CardCSC = '123';

$linkBuf = $DataKey . "?id_commerce=" . $aDatos['id_commerce']
        . "&billing_name=" . $aDatos['billing_name']
        . "&billing_lastname=" . $aDatos['billing_lastname']
        . "&billing_address=" . $aDatos['billing_address']
        . "&billing_city=" . $aDatos['billing_city']
        . "&billing_state=" . $aDatos['billing_state']
        . "&billing_country=" . $aDatos['billing_country']
        . "&billing_zip=" . $aDatos['billing_zip']
        . "&billing_phone=" . $aDatos['billing_phone']
        . "&billing_email=" . $aDatos['billing_email']
        . "&order=" . $aDatos['order']
        . "&product_key=" . $aDatos['product_key']
        . "&trans_type=" . $aDatos['trans_type']
        . "&card_name=" . $CardName
        . "&card_month=" . $CardMonth
        . "&card_year=" . $CardYear
        . "&card_number=" . $CardNumber
        . "&card_csc=" . $CardCSC;

$sign = hash("sha256", $linkBuf);

$SiteTarget = "https://testing.nextpay-payments.com/interface/serv-rest/api.php?request=Subscriptions";
$aDatos['csid'] = 'test';
$aDatos['sign'] = $sign;

//card encrypt
$CardData = $CardName . "|" . $CardNumber . "|" . $CardMonth . "|" . $CardYear . "|" . $CardCSC;
$KeyLoaded = openssl_pkey_get_private($PrivateKey);
openssl_private_encrypt($CardData, $Encrypted, $KeyLoaded);
$CardDataEncrypted = base64_encode($Encrypted);

$aDatos['card'] = $CardDataEncrypted;

$Conn = curl_init($SiteTarget);
curl_setopt($Conn, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt($Conn, CURLOPT_USERAGENT, "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)");
curl_setopt($Conn, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($Conn, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($Conn, CURLOPT_POST, TRUE);
curl_setopt($Conn, CURLOPT_POSTFIELDS, http_build_query($aDatos, '', '&'));

$R = curl_exec($Conn);
curl_close($Conn);

var_dump($R);
?>

Field Description
billing_name Cardholder’s first name
billing_lastname Cardholder’s last name
billing_address Cardholder’s billing address
billing_city Cardholder’s billing city
billing_state Cardholder’s billing state
billing_country Cardholder’s billing country, should be in ISO 3166 format 3-chars
billing_zip Cardholder’s billing postal code/zip code.
billing_phone Cardholder’s billing phone
billing_email Cardholder’s billing email currency Transaction currency, ISO 4217 3-character code (USD, EUR, CHF and other).
trans_type Identifies if a transaction is a pre-authorization or a simple sale.
order Merchant order ID/invoice (e.g. INV10001)
product_key The product key
card all card data encrypted. See “Card Encryption” section.
csid Optional, please ask to the NextPay account manager if this field is required
id_commerce commerce account identifier
sign checksum key

Response

Json response

{
"trans_type":"0",
"order":"170604121346",
"payment_status":"10",
"payment_desc":"APPROVED",
"amount":"9.99","
authcode":"2323027",
"nextpay_order_id":"2323027",
"cardtype":"Visa",
"currency":"USD",
"risk":"1.43",
"msg":"Approved",
"nextpay_refund_id":"",
"subcription_id":"227",
"sub_creation":"2017-06-04 12:13:49",
"sub_card_status":"Active",
"card_bin":"411111",
"card_last4":"1111",
"pay_attemps":"1",
"sub_status":"Active",
"last_payment":"2017-06-04 12:13:49",
"sub_acumulate":9.99,
"sub_cancelled":"0000-00-00 00:00:00"
}
Field Description
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
payment_status Number that describes the payment state.
payment_desc Message that describes the payment result.
authcode Authorization code, if any.
nextpay_order_id NextPay Order id.
cardtype Code that describes the card type used by the Cardholder’s, see card-type codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
trans_type Transaction type sale or pre-authorizations
msg A user friendly message, can you use to show on screen to card member notify
subcription_id Subscription identifier id
sub_creation Creation date
sub_card_status Card status card_bin Card BIN
card_last4 Last four digit of the card number
pay_attemps Total Pay attempts for this Subscription
sub_status Status for this Subscription active/cancelled
last_payment Last payment date
sub_acumulate Payments done for this Subscription
sub_cancelled Cancelled date for this Subscription

Cancels

Request

Example in php


<?php

$DataKey = '*** data key ***';

$aDatos['id_commerce'] = '*** id com ***';
$aDatos['subcription_id'] = 'SUB1234';

$linkBuf = $DataKey . "?id_commerce=" . $aDatos['id_commerce']
        . "&subcription_id=" . $aDatos['subcription_id'];

$sign = hash("sha256", $linkBuf);

$SiteTarget = "https://nextpay-payments.com/interface/serv-rest/api.php?request=Cancels";
$aDatos['csid'] = 'test';
$aDatos['sign'] = $sign;
$FieldString = http_build_query($aDatos, '', '&');


$Conn = curl_init($SiteTarget);
curl_setopt($Conn, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt($Conn, CURLOPT_USERAGENT, "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)");
curl_setopt($Conn, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($Conn, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($Conn, CURLOPT_POST, TRUE);
curl_setopt($Conn, CURLOPT_POSTFIELDS, $FieldString);

$R = curl_exec($Conn);
curl_close($Conn);

var_dump($R);
?>

Field Description
subcription_id The NextPay subscription id
id_commerce commerce account identifier
sign checksum key

Response

Json response


{
"order":"161106010841",
"amount":"7.5",
"currency":"USD",
"subcription_id":"219",
"sub_creation":"2016-11-06 13:09:18",
"sub_card_status":"Active",
"cardtype":"Visa",
"card_bin":"411111",
"card_last4":"1111",
"pay_attemps":"1",
"sub_status":"Cancelled",
"last_payment":"2016-11-06 13:09:18",
"sub_acumulate":7.5,
"sub_cancelled":"2017-06-06 10:07:19",
"product_id":"49"
}

Field Description
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
msg A user friendly message, can you use to show on screen to card member notify
subcription_id Subscription identifier id
sub_creation Creation date
cardtype Code that describes the card type used by the Cardholder’s, see card-type codes.
sub_card_status Card status card_bin Card BIN
card_last4 Last four digit of the card number
pay_attemps Total Pay attempts for this Subscription
sub_status Status for this Subscription active/cancelled
last_payment Last payment date
sub_acumulate Payments done for this Subscription
sub_cancelled Cancelled date for this Subscription
product_id The product id

Check Status

Request

Example in php


<?php

$DataKey = '*** data key ***';

$aDatos['id_commerce'] = '*** id com ***';
$aDatos['subcription_id'] = 'SUB1234';

$linkBuf = $DataKey . "?id_commerce=" . $aDatos['id_commerce']
        . "&subcription_id=" . $aDatos['subcription_id'];

$sign = hash("sha256", $linkBuf);

$SiteTarget = "https://nextpay-payments.com/interface/serv-rest/api.php?request=Status";
$aDatos['csid'] = 'test';
$aDatos['sign'] = $sign;
$FieldString = http_build_query($aDatos, '', '&');


$Conn = curl_init($SiteTarget);
curl_setopt($Conn, CURLOPT_CONNECTTIMEOUT, 30);
curl_setopt($Conn, CURLOPT_USERAGENT, "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1)");
curl_setopt($Conn, CURLOPT_RETURNTRANSFER, TRUE);
curl_setopt($Conn, CURLOPT_FOLLOWLOCATION, 1);
curl_setopt($Conn, CURLOPT_POST, TRUE);
curl_setopt($Conn, CURLOPT_POSTFIELDS, $FieldString);

$R = curl_exec($Conn);
curl_close($Conn);

var_dump($R);
?>

Field Description
subcription_id The NextPay subscription id
id_commerce commerce account identifier
sign checksum key

Response

Json response


{
"order":"161106010841",
"amount":"7.5",
"currency":"USD",
"subcription_id":"219",
"sub_creation":"2016-11-06 13:09:18",
"sub_card_status":"Active",
"cardtype":"Visa",
"card_bin":"411111",
"card_last4":"1111",
"pay_attemps":"1",
"sub_status":"Cancelled",
"last_payment":"2016-11-06 13:09:18",
"sub_acumulate":7.5,
"sub_cancelled":"2017-06-06 10:07:19",
"product_id":"49"
}

Field Description
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
msg A user friendly message, can you use to show on screen to card member notify
subcription_id Subscription identifier id
sub_creation Creation date
cardtype Code that describes the card type used by the Cardholder’s, see card-type codes.
sub_card_status Card status card_bin Card BIN
card_last4 Last four digit of the card number
pay_attemps Total Pay attempts for this Subscription
sub_status Status for this Subscription active/cancelled
last_payment Last payment date
sub_acumulate Payments done for this Subscription
sub_cancelled Cancelled date for this Subscription
product_id The product id

3-D Secure Payment

Request

“Please check the Authorizations section from REST API documentation and verify with the NextPay support team if the 3-D Secure feature is activated for your account

Response

Json response

{
"trans_type":"0",
"order":"170531030116",
"payment_status":"10",
"payment_desc":"3D Verifing",
"amount":"1.00",
"authcode":"2323026",
"nextpay_order_id":"2323026",
"cardtype":"Visa",
"currency":"USD",
"risk":"1.26",
"msg":"Transaction received correctly. 
You will be notified by email once we verify and process the payment",
"nextpay_refund_id":"",
"3d":true,
"PaReq":"VERIJNVERIVHUREVHIUERVERV",
"MD":"19633-27636-68052",
"TermUrl":"https://term3d.com",
"3DURL":"https://3d-services.com"
}
Field Description
order Merchant order ID/invoice (e.g. INV10001)
amount Transaction amount, (i.e. 21.50 for $21.50 transaction). Amount format must include decimal place according the Currency.
payment_status Number that describes the payment state.
payment_desc Message that describes the payment result.
authcode Authorization code, if any.
nextpay_order_id NextPay Order id.
cardtype Code that describes the card type used by the Cardholder’s, see card-type codes.
currency Currency code (ISO 4217 alphanumeric 3 chars) used in the payment process,
risk Risk score from 1.0 to 5.0, where 5.0 stands for the highest risk and 1.0 for the lowest risk
trans_type Transaction type sale or pre-authorizations
msg A user friendly message, can you use to show on screen to card member notify
subcription_id Subscription identifier id
sub_creation Creation date
sub_card_status Card status card_bin Card BIN
card_last4 Last four digit of the card number
pay_attemps Total Pay attempts for this Subscription
sub_status Status for this Subscription active/cancelled
last_payment Last payment date
sub_acumulate Payments done for this Subscription
sub_cancelled Cancelled date for this Subscription
3d The current card is enorroled
PaReq Mpi tocken data
MD Mpi data
TermUrl Mpi data
3DURL Redirect Url to finish 3d process. The mpi addrress

Card Encryption

This card data encryption process is valid only for the REST API integration, for the Payments/Subscriptions services. The process consists of concatenating the 5 data separated by “|”. See example.

Once the data is encrypted, the developer must assign the data to the “card” field. Please check not send card data in the request in plain-text

Example in php


<?php

$CardData = $CardName . "|" . $CardNumber . "|" . $CardMonth . "|" . $CardYear . "|" . $CardCSC;

//encrypt process
$KeyLoaded = openssl_pkey_get_private($PrivateKey);
openssl_private_encrypt($CardData, $Encrypted, $KeyLoaded);
$CardDataEncrypted = base64_encode($Encrypted);

?>

Field Description
card_name Card name
card_number Card number
card_month Expiration date 2 chars
card_year Expiration date 4 chars
card_csc Card CVV

Test Data

NextPay Gateway offers a full test environment for developers to make all necessary test cases before moving to live.

Cards For simulating payments will have on hand test card numbers:

Links For perform a payment in testing ambient you should verify that redirects the following link

https://nextpay-payments.com/testing/process.do

NextPay Commerce test mode The merchant can view the testing payment result Swicht the mode live to test on NextPay commerce site.

rss feed

Subscription links For perform a payment in testing ambient you should verify that redirects the following link

Data Key

Example in php


 <?php

$DataKey = '*** data key ***';

$aDatos['id_commerce'] = '*** id com ***';
$aDatos['billing_name'] = 'Max';
$aDatos['billing_lastname'] = 'Moore';
$aDatos['billing_address'] = '1st avenue';
$aDatos['billing_city'] = 'London';
$aDatos['billing_state'] = 'London';
$aDatos['billing_country'] = 'GBR';
$aDatos['billing_zip'] = '123';
$aDatos['billing_phone'] = '555666788';
$aDatos['billing_email'] = 'test@mail.com';
$aDatos['order'] = 'PO54346';
$aDatos['amount'] = '1.0';
$aDatos['currency'] = 'USD';
$aDatos['trans_type'] = '0';

$aDatos['card_name'] = 'Test Card';
$aDatos['card_month'] = '12';
$aDatos['card_year'] = '2020';
$aDatos['card_number'] = '4111111111111111';
$aDatos['card_csc'] = '123';

$linkBuf = $DataKey . "?id_commerce=" . $aDatos['id_commerce']
        . "&billing_name=" . $aDatos['billing_name']
        . "&billing_lastname=" . $aDatos['billing_lastname']
        . "&billing_address=" . $aDatos['billing_address']
        . "&billing_city=" . $aDatos['billing_city']
        . "&billing_state=" . $aDatos['billing_state']
        . "&billing_country=" . $aDatos['billing_country']
        . "&billing_zip=" . $aDatos['billing_zip']
        . "&billing_phone=" . $aDatos['billing_phone']
        . "&billing_email=" . $aDatos['billing_email']
        . "&order=" . $aDatos['order']
        . "&amount=" . $aDatos['amount']
        . "&currency=" . $aDatos['currency']
        . "&trans_type=" . $aDatos['trans_type']
        . "&card_name=" . $aDatos['card_name']
        . "&card_month=" . $aDatos['card_month']
        . "&card_year=" . $aDatos['card_year']
        . "&card_number=" . $aDatos['card_number']
        . "&card_csc=" . $aDatos['card_csc'];

$sign = hash("sha256", $linkBuf);

var_dump($sign);

?>

The “Data Key” parameter is a field that allows corroborating the integrity of the message. By means of a check sum, the value sent is compared to be congruent with the fields that have been received

The amount of data concatenated to form the sign, depends on the type of message to send. Please review the examples described for each REQUEST

On the right you can see an example of a sign for authorizations request

Instant Payment Notification

Example in php


<?php

echo $_POST['order'];
echo $_POST['payment_status'];
echo $_POST['payment_desc'];
echo $_POST['ComerceOrderID'];
echo $_POST['URLReturn'];
echo $_POST['amount'];
echo $_POST['risk'] ;
echo $_POST['CardType'] ;
echo $_POST['Currency'] ;
echo $_POST['TransIDNextpay'] ;
echo $_POST['BIN'] ;
echo $_POST['LAST4'] ;
echo $_POST['PP'] ;
echo $_POST['SubscriptionId'] ;

var_dump($_POST);
?>

For update the merchant data bases with the order payment, is necessary setting up the Instant Payment Notification URL.

This feature is efficient to collect the response data of NextPay processing to update the order with this data.

Setting up on NextPay Commerce

You can setting up the response URL on NextPay Commerce in the section “website settings”, on bottom page you can find the Instant Payment Notification form.

rss feed

To save the URL you must enter a full, valid and existing URL to collect the payment result.

The message will be sent just before the NextPay payment result page is display to customer.

rss feed

Plugins

Magento

Our payment platform offers our customers who use Magento as your e-commerce platform, a plugin to perform a easy integration between your e-commerce with our online payment system. This add-on is very intuitive only use your Magento Connect to install and configure a few simple parameters and start processing.

Follow this link to access the plugin go to the following website:

NextPay Payment Extension

rss feed

Errors and Codes

Payment states

Following NextPay the payment states:

State Description
2 Declined, the order been declined
10 Approved, the order been approved
11 Processing, the order has been captured in our system, but the payment process has not yet been executed.
12 Failed, the payment process is complete, but the transaction could not be approved
13 Pending capture
14 Cancelled

Card Type Codes

Code Description
MasterCard MasterCard
Visa Visa
Amex Amex
Diners Diners Club
Discover Discover
JBC JBC

HTTP Codes

The Rest API uses the following error codes:

Error Code Meaning
400 Bad Request
401 Unauthorized – Your API key is wrong
403 Forbidden – The requested is hidden for administrators only
404 Not Found – The specified could not be found
405 Method Not Allowed – You tried to access with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The requested has been removed from our servers
429 Too Many Requests
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Subscription states

Following NextPay the subscription states:

State Description
0 Cancelled
1 Activated