4.3. PAN Eligibility

Introduction

PAN Eligibility services allow Connecting Party to detect whether card is eligible for Money Transfer (either as sending or as receiving card) along with providing extended information about card issuer and card product before making a financial transaction request.

PAN Eligibility Direct Flow

skinparam roundcorner 20
skinparam sequenceArrowThickness 1
skinparam maxmessagesize 1200
skinparam sequenceParticipant underline
actor Payer
participant "Connecting Party" as A
participant Billblend as B
autonumber
Payer -> A: Checkout
activate A
A -> B: /api/v2/pan-eligibility/send/
activate B
A -> B: /api/v2/pan-eligibility/receive/
A -> B: /api/v2/pan-eligibility/both/
B --> A: Order ID
B -> B: Process\npan-eligibility
group Get Final Status
== Receive Connecting Party Callback ==
A <- B: Callback with Final Status
A --> B: HTTP 200
deactivate B
== Order Status Request ==
A -> B: Get Status by Order ID
activate B
B --> A: Final Status
deactivate B
end
A --> Payer: Show result
deactivate Payer
deactivate A

(2,3,4) To implement PAN eligibility direct flow request see /api/v2/pan-eligibility/. PAN eligibility information can be requested for Payer card (also referred as Sender), Recipient card (also referred as Receiver) or both cards at once.
(5) To implement callback with final status handling see Connecting Party Callback.
(7) To implement order status request see /api/v2/status/. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.

PAN Eligibility Form Flow

  skinparam roundcorner 20
  skinparam sequenceArrowThickness 2
  skinparam ParticipantPadding 30
  actor Payer as Customer
  participant "Connecting Party\nwebsite" as Merchant
  participant "Payment Gateway" as g
  autonumber
  Customer -> Merchant: Checkout
  activate Merchant
  == Purchase payment request ==
  Merchant -> g: api/v2/pan-eligibility/send-form
  activate g
  Merchant -> g: api/v2/pan-eligibility/receive-form
  Merchant -> g: api/v2/pan-eligibility/both-form
  g --> Merchant: Redirect-url, orderId
  deactivate g
  Merchant -> Customer: Provide redirect-url \nto payer’s browser
  deactivate Merchant
  activate Customer
  Customer -> g: GET redirect-url
  deactivate Customer
  activate g
  g --> Customer: Payment Form
  deactivate g
  activate Customer
  Customer -> g: Submit form
  deactivate Customer
  activate g
  g --> g: Process PAN Eligibility
  == Final redirect of customer ==
  g -> Customer: Connecting Party website redirect_url
  activate Customer
  Customer -> Merchant: POST redirect_url\nstatus, orderid
  deactivate Customer
  activate Merchant
  group Get Final Status
  == Receive Connecting Party Callback ==
  Merchant <- g: Сallback with final status
  g <-- Merchant: HTTP 200
  deactivate g
  == Order Status Request ==
  Merchant -> g: api/v2/status
  activate g
  g --> Merchant: Response \nstatus, order-stage
  deactivate g
  end
  Merchant --> Customer: Show result
  deactivate Merchant

(2,3,4) To implement PAN eligibility form flow request see /api/v2/pan-eligibility-form/. PAN eligibility information can be requested for Payer card (also referred as Sender), Recipient card (also referred as Receiver) or both cards at once.
(5) To implement callback with final status handling see Connecting Party Callback.
(7) To implement order status request see /api/v2/status/. Status should be requested multiple times with 3-5 seconds interval until final status will be received in response.

PAN Eligibility Callback

Callback Parameters

Additional parameters are sent in callbacks for PAN Eligibility transactions. For more information see Connecting Party Callback Parameters.

Callback Parameter

Description

status

See Status List for details.

serial-number

Serial number of the request.

client_orderid

Connecting Party order identifier.

paynet-order-id

Order id set by Billblend.

processor-tx-id

Transaction id set by processor.

type

Transaction type, sale reversal chargeback

sending-card-type

The sending card type (VISA, MASTERCARD).

sending-cardholder

Cardholder of the sending card.

sending-bin

The sending card Bank identification number.

sending-last-four-digits

The sending card last 4 digits.

sending-eligible

Whether the sending card is eligible for sending funds. Possible values: true/false/unknown.

sending-ica

The sending card ICA.

sending-bank-name

The sending card Bank name.

sending-currency-code

The sending card currency code.

sending-country-code

The sending card country code.

sending-acceptance-brand-code

The sending card Acceptance brand code.

sending-acceptance-brand-name

The sending card Acceptance brand name.

sending-product-brand-code

The sending card Product brand code.

sending-product-brand-name

The sending card Product brand name.

receiving-card-type

The receiving card type (VISA, MASTERCARD).

receiving-bin

The receiving card Bank identification number.

receiving-last-four-digits

The receiving card last 4 digits.

receiving-eligible

Whether the receiving card is eligible for sending funds. Possible values: true/false/unknown.

receiving-ica

The receiving card ICA.

receiving-bank-name

The receiving card Bank name.

receiving-currency-code

The receiving card currency code.

receiving-country-code

The receiving card country code.

receiving-acceptance-brand-code

The receiving card Acceptance brand code.

receiving-acceptance-brand-name

The receiving card Acceptance brand name.

receiving-product-brand-code

The receiving card Product brand code.

receiving-product-brand-name

The receiving card Product brand name.

error-code

Error Code.

error-message

Error Message.

control

Checksum generated by SHA-1. Control string is represented as concatenation of the following parameters:
1. Callback parameter: status.
2. Callback parameter: orderid.
3. Callback parameter: merchant_order.
4. merchant_control (Control key assigned to Merchant account in the Billblend Payment Gateway).

Callback Macros

Simple callback URL contains all parameters listed in Callback Parameters. Customizable URL allows Connecting Party to define own parameter names, whereas the actual parameters values are defined by use of macros with the following format ${parameter_name}. Available macros are listed in Callback Macros.

Field Name Macro

Field Value Macro

Description

${status}

n/a

Transaction status, approved declined processing.

${serial-number}

n/a

Unique number assigned by Billblend server to particular request from the Connecting Party.

${client-order-id}

n/a

Unique order identifier assigned by Connecting Party.

${paynet-order-id}

n/a

Billblend-generated order id.

${processor-tx-id}

n/a

Processor-generated transaction id.

${type}

n/a

Transaction type, ex. sale, return, chargeback, etc.

${sending-card-type}

n/a

The sending card type (VISA, MASTERCARD).

${sending-cardholder}

n/a

Cardholder of the sending card.

${sending-bin}

n/a

The sending card Bank identification number.

${sending-last-four-digits}

n/a

The sending card last 4 digits.

${sending-eligible}

n/a

Whether the sending card is eligible for sending funds. Possible values: true/false/unknown.

${sending-ica}

n/a

The sending card ICA.

${sending-bank-name}

n/a

The sending card Bank name.

${sending-currency-code}

n/a

The sending card currency code.

${sending-country-code}

n/a

The sending card country code.

${sending-acceptance-brand-code}

n/a

The sending card Acceptance brand code.

${sending-acceptance-brand-name}

n/a

The sending card Acceptance brand name.

${sending-product-brand-code}

n/a

The sending card Product brand code.

${sending-product-brand-name}

n/a

The sending card Product brand name.

${receiving-card-type}

n/a

The receiving card type (VISA, MASTERCARD).

${receiving-bin}

n/a

The receiving card Bank identification number.

${receiving-last-four-digits}

n/a

The receiving card last 4 digits.

${receiving-eligible}

n/a

Whether the receiving card is eligible for sending funds. Possible values: true/false/unknown.

${receiving-ica}

n/a

The receiving card ICA.

${receiving-bank-name}

n/a

The receiving card Bank name.

${receiving-currency-code}

n/a

The receiving card currency code.

${receiving-country-code}

n/a

The receiving card country code.

${receiving-acceptance-brand-code}

n/a

The receiving card Acceptance brand code.

${receiving-acceptance-brand-name}

n/a

The receiving card Acceptance brand name.

${receiving-product-brand-code}

n/a

The receiving card Product brand code.

${receiving-product-brand-name}

n/a

The receiving card Product brand name.

${error-code}

n/a

Error Code.

${error-message}

n/a

Error Message.

${control}

n/a

Checksum generated by SHA-1. Control string is represented as concatenation of the following parameters:
1. Callback parameter: status.
2. Callback parameter: orderid.
3. Callback parameter: merchant_order.
4. merchant_control (Control key assigned to Merchant account in the Billblend Payment Gateway).