1.2.4. PAN Eligibility

PAN Eligibility services allow to detect whether card is eligible for Money Transfer (either as sending or as receiving card) along with information about card issuer, card product and so on.

PaynetEasy has three ways to call PAN Eligibility service:

  1. Just for the sending card
  2. Just for the receiving card
  3. For both the sending and receiving cards

Any of these requests may be initiated either via asynchronous POST API, or using a hosted form. In the latter case, card data is not sent using POST by the merchant, instead user enters that data at PaynetEasy side.

Direct integration

Authorization through OAuth 1.0a

OAuth 1.0a signatures are used to sign requests to all API calls described here:

  • POST PAN Eligibility calls
  • Form PAN Eligibility calls
  • PAN Eligibility status call

See OAuth

POST PAN Eligibility API

Here, flow is the following:

Merchant makes an HTTPS POST request to the appropriate API method
PaynetEasy immediately returns order identification and starts processing it
Merchant may continously poll the PAN Eligibility Status method to get transaction status
When processing reaches some final state (approved, error, unknown), PaynetEasy issues a callback to the merchant site

Card data may be passed in one of two ways:

  1. It may be specified in the request as PAN, expiration date, cardholder info
  2. It may be specified by reference using card-ref-id.

Sending-only PAN Eligibility call

Sending-only PAN Eligibility API URL
Such transactions are initiated through HTTPS POST request by using URL in the following format:
https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/send/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only PaynetEasy object which is exposed via API.

Sending-only PAN Eligibility Request Parameters
In order to initiate a Sending-only PAN Eligibility transaction, Merchant sends an HTTPS POST request with the parameters specified in Sending-only PAN Eligibility Request Parameters Table below:
PAN Eligibility Request Parameter Length/Type Comment Necessity*
client-order-id 128/String Merchant order identifier. Mandatory
sending-card-number 19/Numeric The sending card number. Mandatory (if sending-card-ref-id is not specified).
card-printed-name 128/String The Sending card printed name Mandatory (if sending-card-ref-id is not specified).
expire-month 2/Numeric The sending card expiration month Mandatory (if sending-card-ref-id is not specified).
expire-year 4/Numeric The sending card expiration year Mandatory (if sending-card-ref-id is not specified).
sending-card-ref-id Numeric The sending card ref ID. Mandatory (if sending-card-number is not specified).
server-callback-url 128/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect data in Merchant’s database. See more details at Merchant Callbacks Optional

PAN Send Eligibility Request Example (with PAN)

card-printed-name=Ded Moroz
client-order-id=MID-f29bf1c3-bd52-4343-ba99-c49c11b853d7
expire-month=12
sending-card-number=5432333322221111
expire-year=2023

PAN Send Eligibility Request Example (with card-ref-id)

client-order-id=MID-394f58aa-890f-4875-a2e5-1d2afc4f28da
sending-card-ref-id=6

Receiving-only PAN Eligibility call

Receiving-only PAN Eligibility API URL
Such transactions are initiated through HTTPS POST request by using URL in the following format:
https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/receive/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only PaynetEasy object which is exposed via API.

Receiving-only PAN Eligibility Request Parameters
In order to initiate a Receiving-only PAN Eligibility transaction, Merchant sends an HTTPS POST request with the parameters specified in Receiving-only PAN Eligibility Request Parameters Table below:
PAN Eligibility Request Parameter Length/Type Comment Necessity*
client-order-id 128/String Merchant order identifier. Mandatory
receiving-card-number 19/Numeric The receiving card number. Mandatory (if receiving-card-ref-id is not specified).
receiving-card-ref-id Numeric The receiving card ref ID. Mandatory (if receiving-card-number is not specified).
server-callback-url 128/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect data in Merchant’s database. See more details at Merchant Callbacks Optional

PAN Receive Eligibility Request Example (with PAN)

client-order-id=MID-f29bf1c3-bd52-4343-ba99-c49c11b853d7
receiving-card-number=5432333322221111

PAN Receive Eligibility Request Example (with card-ref-id)

client-order-id=MID-394f58aa-890f-4875-a2e5-1d2afc4f28da
receiving-card-ref-id=6

Full PAN Eligibility call

Full PAN Eligibility API URL Such transactions are initiated through HTTPS POST request by using URL in the following format:

https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/both/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only PaynetEasy object which is exposed via API.

Full PAN Eligibility Request Parameters In order to initiate a Full PAN Eligibility transaction, Merchant sends an HTTPS POST request with the parameters specified in Full PAN Eligibility Request Parameters Table below:

PAN Eligibility Request Parameter Length/Type Comment Necessity*
client-order-id 128/String Merchant order identifier. Mandatory
sending-card-number 19/Numeric The sending card number. Mandatory (if sending-card-ref-id is not specified).
card-printed-name 128/String The Sending card printed name Mandatory (if sending-card-ref-id is not specified).
expire-month 2/Numeric The sending card expiration month Mandatory (if sending-card-ref-id is not specified).
expire-year 4/Numeric The sending card expiration year Mandatory (if sending-card-ref-id is not specified).
sending-card-ref-id Numeric The sending card ref ID. Mandatory (if sending-card-number is not specified).
receiving-card-number 19/Numeric The receiving card number. Mandatory (if receiving-card-ref-id is not specified).
receiving-card-ref-id Numeric The receiving card ref ID. Mandatory (if receiving-card-number is not specified).
server-callback-url 128/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect data in Merchant’s database. See more details at Merchant Callbacks Optional

PAN Full Eligibility Request Example (with PAN)

card-printed-name=Ded Moroz
client-order-id=MID-f29bf1c3-bd52-4343-ba99-c49c11b853d7
expire-month=12
sending-card-number=5432333322221111
expire-year=2023

PAN Full Eligibility Request Example (with card-ref-id)

client-order-id=MID-394f58aa-890f-4875-a2e5-1d2afc4f28da
sending-card-ref-id=6

PAN Eligibility Response

This is a response to any of the three above-mentioned calls.

PAN Eligibility Response parameter Description
type The type of response. May be async-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Order id assigned to the order by PaynetEasy
merchant-order-id Merchant order id (same as client-order-id)
serial-number Unique number assigned by PaynetEasy server to particular request from the Merchant.
error-message If status is error this parameter contains the reason for decline or error details
error-code The error code is case of error status

PAN Eligibility Response Example

type=async-response
&serial-number=00000000-0000-0000-0000-0000000624e8
&merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4
&paynet-order-id=94935

Hosted Form PAN Eligibility API

When using a Hosted Form PAN Eligibility API, card data is not sent in the initial API call but instead a user is redirected to a form hosted by PaynetEasy on which user enters card data.

Form-related flow is the following:

Merchant makes an HTTPS POST request to initiate an order
PaynetEasy creates an order and returns a URL to which user needs to be redirected using redirect-url response field
Merchant redirects a user to that URL
User enters card data to the form hosted by that URL
PaynetEasy processes the order
When the order is processed, user is redirected to the server-redirect-url supplied in the initial request
When the order is processed, a callback is made to the merchant server (if server-callback-url is specified)
This API includes three calls. Each of them has the same parameters and produces similar responses.

PAN Eligibility Form Request Parameters

In order to initiate a PAN Eligibility transaction via form, Merchant sends an HTTPS POST request with the parameters specified in PAN Eligibility Form Request Parameters Table below:

PAN Eligibility Form Request Parameter Length/Type Comment Necessity*
client-order-id 128/String Merchant order identifier. Mandatory
redirect_url 128/String URL the cardholder will be redirected to upon completion of the transaction. Please note that the cardholder will be redirected in any case, no matter whether the transaction is approved or declined. You should not use this parameter to retrieve results from PaynetEasy gateway, because all parameters go through client’s browser and can be lost during transmission. To deliver the correct payment result to your backend use server_callback_url instead. Mandatory
server-callback-url 128/String URL the transaction result will be sent to. Merchant may use this URL for custom processing of the transaction completion, e.g. to collect data in Merchant’s database. See more details at Merchant Callbacks Optional

PAN Eligibility Form Request Example

client-order-id=MID-ca70f915-ddfe-4ff8-8b60-446deae2b0d4
redirect-url=http://my.cool.site.com/pan-eligibility-form-redirect

PAN Eligibility Form Response

This is a response to any of the three form-related calls.

PAN Eligibility Form Response Parameter Description
type The type of response. May be async-form-response, validation-error, error. If type equals validation-error or error, error-message and error-code parameters contain error details.
paynet-order-id Order id assigned to the order by PaynetEasy
merchant-order-id Merchant order id (same as client-order-id)
serial-number Unique number assigned by PaynetEasy server to particular request from the Merchant.
redirect_url URL to which merchant must redirect a user to fill the form.
error-message If status is error this parameter contains the reason for decline or error details
error-code The error code is case of error status

PAN Eligibility Form Response Example

type=async-form-response
&serial-number=00000000-0000-0000-0000-000000000235
&merchant-order-id=MID-ca70f915-ddfe-4ff8-8b60-446deae2b0d4
&paynet-order-id=96
&redirect-url=https://gate.PaynetEasy.com/paynet/form/pan-eligibility/init/BB3242586A313257494D4863666575796B6E625868484342337353546651466D4D

Sending-only PAN Eligibility Form call

Sending-only PAN Eligibility Form API URL
Such transactions are initiated through HTTPS POST request by using URL in the following format:
https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/send-form/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only PaynetEasy object which is exposed via API.

Receiving-only PAN Eligibility Form call

Receiving-only PAN Eligibility Form API URL
Such transactions are initiated through HTTPS POST request by using URL in the following format:
https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/receive-form/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only PaynetEasy object which is exposed via API.

Full PAN Eligibility Form call

Full PAN Eligibility Form API URL
Such transactions are initiated through HTTPS POST request by using URL in the following format:
https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/both-form/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only PaynetEasy object which is exposed via API.

Server callback result

Upon completion by the request processing, PaynetEasy sends the result to the specified server-callback-url with the following parameters described in Merchant Callbacks

The checksum is used to ensure that the callback is initiated for a particular Merchant, and not for anybody else claiming to be such Merchant. This SHA-1 checksum, the control parameter, is created by concatenation of the parameters values in the following order:

  • status
  • orderid
  • client_orderid
  • merchant_control

A complete string example may look as follows:

approvedS279G323P4T1209294c258d6536ababe653E8E45B5-7682-42D8-6ECC-FB794F6B11B1

Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter. For the above-mentioned example the control will take the following value:

e04bd50531f45f9fc76917ac78a82f3efaf0049c

All parameters are sent via POST method.

Server callback result example

status=declined
&error-message=Decline, refer to card issuer
&error-code=107
&paynet-order-id=S279G323P4T1209294
&merchant-order-id=c258d6536ababe65

PAN Eligibility Order status

Merchant must use PAN Eligibility Order status API call to get the customer’s order transaction status. After a transaction is sent to PaynetEasy server and order id is returned, Merchant should poll for transaction status. When transaction is processed on PaynetEasy server side, it returns its status back to Merchant and at this moment the Merchant is ready to show the customer transaction result.

PAN Eligibility Status API URL

PAN Eligibility Status API calls are initiated through HTTPS POST request by using URL in the following format:
https://gate.payneteasy.com/paynet/api/v2/pan-eligibility/status/ENDPOINTID
for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

The End point ID is an entry point for incoming Merchant’s transactions and is actually the only PaynetEasy object which is exposed via API.

PAN Eligibility Order status call parameters

PAN Eligibility Status Request Parameter Description
client-order-id Merchant order identifier of the transaction for which the status is requested
paynet-order-id Order id assigned to the order by PaynetEasy

If paynet-order-id is specified, it’s used to find an order. Otherwise, client-order-id is used for that. In the latter case, as client-order-id is not checked for uniqueness by PaynetEasy, it may happen that several orders are found by the given client-order-id. In such a case, system will behave as nothing was found, so be sure to generate unique client-order-id

PAN Eligibility Order Status Response

PAN Eligibility Status Response Parameter Description
type The type of response. May be pan-eligibility-status-response
status See Status List for details.
paynet-order-id Order id assigned to the order by PaynetEasy
client-order-id Merchant order id
serial-number Unique number assigned by PaynetEasy server to particular request from the Merchant.
processor-tx-id ID assigned by the processor to the transaction.
error-message If status is filtered or error this parameter contains the reason for error
error-code The error code is case of filtered or error status
sending-eligible Whether the sending card is eligible for sending funds. Possible values: true/false/unknown
sending-ica ICA of the sending card
sending-bank-name Bank name of the sending card
sending-currency-code Ahpla-3 code of the sending card currency (for instance, USD)
sending-country-code Ahpla-3 code of the sending card country (for instance, USA)
sending-acceptance-brand-code Acceptance brand code of the sending card
sending-acceptance-brand-name Acceptance brand name of the sending card
sending-product-brand-code Product brand code of the sending card
sending-product-brand-name Product brand name of the sending card
sending-visa-fast-funds Visa fast funds support
sending-eft-brand-code EFT brand V MCC
sending-eft-brand-name EFT brand name VISA MASTERCARD CREDIT
receiving-eligible Whether the receiving card is eligible for receiving funds. Possible values: true/false/unknown
receiving-ica ICA of the receiving card
receiving-bank-name Bank name of the receiving card
receiving-currency-code Ahpla-3 code of the receiving card currency (for instance, USD)
receiving-country-code Ahpla-3 code of the receiving card country (for instance, USA)
receiving-acceptance-brand-code Acceptance brand code of the receiving card
receiving-acceptance-brand-name Acceptance brand name of the receiving card
receiving-product-brand-code Product brand code of the receiving card
receiving-product-brand-name Product brand name of the receiving card
receiving-visa-fast-funds Visa fast funds support
receiving-eft-brand-code EFT brand V MCC
receiving-eft-brand-name EFT brand name VISA MASTERCARD CREDIT

PAN Eligibility Order Status Response Example

Visa

type=pan-eligibility-status-response
&serial-number=00000000-0000-0000-0000-00000aa8c1c7
&client-order-id=6f368eb1-3273-436a-9909-29f7b108c293
&processor-tx-id=PE-70F65942-C962-7EC8-D1FD-9EE15C7D699A
&paynet-order-id=15314166
&status=approved
&sending-eligible=true
&sending-ica=959
&sending-bank-name=STANDARD+BANK+%28MAURITIUS%29+LIMITED
&sending-currency-code=MUR
&sending-country-code=MUS
&sending-acceptance-brand-code=DEBIT
&sending-acceptance-brand-name=VISA+DEBIT
&sending-product-brand-code=N
&sending-product-brand-name=Visa+Platinum
&sending-visa-fast-funds=No
&sending-eft-brand-code=V
&sending-eft-brand-name=VISA

MasterCard

type=pan-eligibility-status-response
&serial-number=00000000-0000-0000-0000-00000aa8c2bb
&client-order-id=d879186b-2501-4d90-af95-3a614a1dd589
&processor-tx-id=372067
&paynet-order-id=15212466
&status=approved
&sending-eligible=true
&sending-ica=12486
&sending-bank-name=VTB24
&sending-currency-code=RUB
&sending-country-code=RUS
&sending-acceptance-brand-code=MCC
&sending-acceptance-brand-name=MASTERCARD+CREDIT
&sending-product-brand-code=WBE
&sending-product-brand-name=MASTERCARD+WORLD+BLACK+EDITION
&sending-eft-brand-code=MCC
&sending-eft-brand-name=MASTERCARD+CREDIT

PAN Eligibility Order status Debug

endpointid input your ENDPOINTID
login
client_orderid input your Invoice Number
orderid
merchant_control input your Control Key

String to sign
Signature
				  
				
			 
		
			
		

Merchant Callbacks

When Endpoint is created for Merchant’s website, PAN eligibility callback URL may be defined.

This callback URL will be called when a PAN Eligibility transaction is completed, whether approved or filtered/error. Also, a callback is made to URL specified via server-callback-url parameter.

Callback simple URL

Simple form of a callback is just a URL to Merchant’s target page or script without any parameters, for example https://www.i-cool-merchant.com/pan-eligibility-callback.php. In this case the system automatically adds the following parameters to callback URL:

Callback Parameters

PAN Eligibility Callback Parameter Description
status See Status List for details.
serial-number Unique serial number assinged by PaynetEasy to the given request.
client-order-id Merchant order identifier, client-order-id
paynet-order-id PaynetEasy-generated order id
processor-tx-id Processor-generated transaction id
type Transaction type, pan_eligibility
sending-card-type Card type of the sending card (VISA, MASTERCARD, etc)
sending-cardholder Cardholder of the sending card
sending-bin Bank identification number of the sending card
sending-last-four-digits Last 4 digits of the sending card number
sending-eligible Whether the sending card is eligible for sending funds. Possible values: true/false/unknown
sending-ica ICA of the sending card
sending-bank-name Bank name of the sending card
sending-currency-code Alpha-3 currency code of the sending card
sending-country-code Alpha-3 country code of the sending card
sending-acceptance-brand-code Acceptance brand code of the sending card
sending-acceptance-brand-name Acceptance brand name of the sending card
sending-product-brand-code Product brand code of the sending card
sending-product-brand-name Product brand name of the sending card
receiving-card-type Card type of the receiving card (VISA, MASTERCARD, etc)
receiving-cardholder Cardholder of the receiving card
receiving-bin Bank identification number of the receiving card
receiving-last-four-digits Last 4 digits of the receiving card number
receiving-eligible Whether the receiving card is eligible for receiving funds. Possible values: true/false/unknown
receiving-ica ICA of the receiving card
receiving-bank-name Bank name of the receiving card
receiving-currency-code Alpha-3 currency code of the receiving card
receiving-country-code Alpha-3 country code of the receiving card
receiving-acceptance-brand-code Acceptance brand code of the receiving card
receiving-acceptance-brand-name Acceptance brand name of the receiving card
receiving-product-brand-code Product brand code of the receiving card
receiving-product-brand-name Product brand name of the receiving card
error-code Error Code
error-message Error Message
control Checksum is used to ensure that it is PaynetEasy (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation status + orderid + merchant_order + merchant_control. The callback script MUST check this parameter by comparing it to SHA-1 checksum of the above concatenation. See Callback authorization through control parameter for more details about generating control checksum.

Customizable callback URL

Customizable callback URL is a fully defined URL with all the parameters Merchant’s target page or script would require. Customizable URL allows defining Merchant’s own parameter names, whereas the actual parameters values are defined by use of macros with the following format ${parameter_name}. Thus PaynetEasy substitutes respective parameter values into final customized URL before calling it.

Example:

https://www.i-cool-merchant.com/pan_eligibility_completed.php?the_control= ${control}&tx_status=${status}&order_id=${merchant_order}

Callback Macros

PAN Eligibility Callback Macros Parameter Description
${status} The status code of the order. May be approved, processing, error or filtered.
${serial-number} Unique serial number assinged by PaynetEasy to the given request.
${client-order-id} Merchant order identifier, client-order-id
${paynet-order-id} PaynetEasy-generated order id
${processor-tx-id} Processor-generated transaction id
${type} Transaction type, pan_eligibility
${sending-card-type} Card type of the sending card (VISA, MASTERCARD, etc)
${sending-cardholder} Cardholder of the sending card
${sending-bin} Bank identification number of the sending card
${sending-last-four-digits} Last 4 digits of the sending card number
${sending-eligible} Whether the sending card is eligible for sending funds. Possible values: true/false/unknown
${sending-ica} ICA of the sending card
${sending-bank-name} Bank name of the sending card
${sending-currency-code} Alpha-3 currency code of the sending card
${sending-country-code} Alpha-3 country code of the sending card
${sending-acceptance-brand-code} Acceptance brand code of the sending card
${sending-acceptance-brand-name} Acceptance brand name of the sending card
${sending-product-brand-code} Product brand code of the sending card
${sending-product-brand-name} Product brand name of the sending card
${receiving-card-type} Card type of the receiving card (VISA, MASTERCARD, etc)
${receiving-bin} Bank identification number of the receiving card
${receiving-last-four-digits} Last 4 digits of the receiving card number
${receiving-eligible} Whether the receiving card is eligible for receiving funds. Possible values: true/false/unknown
${receiving-ica} ICA of the receiving card
${receiving-bank-name} Bank name of the receiving card
${receiving-currency-code} Alpha-3 currency code of the receiving card
${receiving-country-code} Alpha-3 country code of the receiving card
${receiving-acceptance-brand-code} Acceptance brand code of the receiving card
${receiving-acceptance-brand-name} Acceptance brand name of the receiving card
${receiving-product-brand-code} Product brand code of the receiving card
${receiving-product-brand-name} Product brand name of the receiving card
${error-code} Error Code
${error-message} Error Message
${control} Checksum is used to ensure that it is PaynetEasy (and not a fraudster) that initiates the callback for a particular Merchant. This is SHA-1 checksum of the concatenation status + orderid + merchant_order + merchant_control. The callback script MUST check this parameter by comparing it to SHA-1 checksum of the above concatenation. See Callback authorization through control parameter for more details about generating control checksum.

Callback authorization through control parameter

The checksum is used to ensure that the callback is sent to the merchant by PaynetEasy, and not by a fraudster. WARNING! If the Merchant does not check control parameter in the callback script a fraudster might use the callback URL to carry out fraudulent activities on the Merchant’s system. This SHA-1 checksum, the parameter control, is created by concatenating of the values of the parameters in the following order:

  • status
  • paynet-order-id
  • client-order-id
  • merchant control

The complete string example may look as follows:

59I098765444455556666111125263E8E45B5-7682-42D8-6ECC-FB794F6B11B1 Encrypt the string using SHA-1 algorithm. The resultant string yields the control parameter which is required for authorizing the callback. For the example the control above will take the following value:

5b1da0a20a1b9f350f4d66caaba15a9533e7ee13