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:
- Just for the sending card
- Just for the receiving card
- 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 debug in OAuth
POST PAN Eligibility API¶
Here, flow is the following:
Card data may be passed in one of two ways:
- It may be specified in the request as PAN, expiration date, cardholder info
- It may be specified by reference using card-ref-id.
Sending-only PAN Eligibility call¶
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 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¶
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 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:
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:
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¶
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¶
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¶
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 GET 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¶
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 | Alpha-3 code of the sending card currency (for instance, USD) |
| sending-country-code | Alpha-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
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 assigned 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 assigned 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