1.2.10. MFO Scoring

Making direct requests

MFO scoring allows to score card for purposes of MFO (Micro-Financial Organization).

MFO scoring flow

Merchant initiates request for MFO scoring by sending HTTPS POST request to the specified URL of the Merchant`s endpoint on gate.payneteasy.com. After that, Payneteasy system returns response with MFO scoring response data set.

MFO scoring URL

https://gate.payneteasy.com/paynet/api/mfo/scoring/<ENDPOINT_ID>/<CLIENT_ORDER_ID>

for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

Each request is supposed to have its own unique client order ID. A request must be made using the HTTP POST method with UTF-8 encoding. Each parameter is to be supplied as a POST request parameter (using application/x-www-form-urlencoded).

Each request must be signed (see below). The signature must be put to X-Authorization request header.

A response is in JSON format (in UTF-8 encoding).

Request parameters

MFO scoring HTTP POST request body may have three different sets of parameters which are accepted by the system, as you may see below:

1. first6PanDigits and last4PanDigits
2. cardRefId
3. cardNumber

Note

Request must have content-type=application/x-www-form-urlencoded and Authorization headers.

Request parameter name	Format	Description
first6PanDigits	N6	First 6 digits of the card number
last4PanDigits	N4	Last 4 digits of the card number
cardRefId	N{1-*}	the card-ref-id created earlier using create-card-ref call that can be used to find the specific card that is needed
cardNumber	N{13-19}	Full card number
cardExpiryMonth	N{1-2}	Card expiration month, if first6PanDigits and last4PanDigits are used (optional)
cardExpiryYear	N4	Card expiration year, if first6PanDigits and last4PanDigits are used (optional)

Response data

Note

Response has Content-Type: text/html;charset=utf-8 header. All parameters in response are x-www-form-urlencoded, with (0xA) character at the end of each parameter’s value.

Parameter name	Value example	Format	Description
error		String	If error occurs, here you may see brief error description
bankBin	444444	Integer	Card`s bank identification number (As a rule, first 6 digits of the card number)
cardFound	true	Boolean	This parameter shows if the system has mfo scoring information on this card or not
countIssuedFor180Days	1	Integer	The number of transactions for the issuance of MFI loans for the last 180 days
countIssuedFor30Days	1	Integer	The number of transactions for the issuance of MFI loans for the last 30 days
countIssuedFor90Days	1	Integer	The number of transactions for the issuance of MFI loans for the last 90 days
expiredMonth	12	Integer	Card expiration month
expiredYear	2099	Integer	Card expiration year
incomingTransferAmountFor30Days	100.25	Decimal	Incoming transfer amount for 30 days
incomingTransferAmountFor365Days	100.25	Decimal	Incoming transfer amount for 365 days
incomingTransferAmountFor60Days	100.25	Decimal	Incoming transfer amount for 60 days
incomingTransferAmountFor90Days	100.25	Decimal	Incoming transfer amount for 90 days
lastDischargeAmount	111.400	Decimal	Amount of last repayment
lastDischargeDate	2015.07.24	yyyy.MM.dd	Date of last repayment
lastFourDigits	1234	Integer	Last 4 digits of the card number
lastSuccessfulDischargeAmount	1.400	Decimal	The amount of the last successful repayment
lastSuccessfulDischargeDate	2015.07.24	yyyy.MM.dd	The date of the last successful repayment
mfoCountFor180Days	1	Integer	Number of unique MFIs conducting transactions in the last 180 days
mfoCountFor30Days	1	Integer	Number of unique MFIs conducting transactions in the last 30 days
mfoCountFor90Days	1	Integer	Number of unique MFIs conducting transactions in the last 90 days
mfoIssuedFor180Days	1	Integer	Number of unique MFIs that issued loans in the last 180 days
mfoIssuedFor30Days	1	Integer	Number of unique MFIs that issued loans in the last 30 days
mfoIssuedFor90Days	1	Integer	Number of unique MFIs that issued loans in the last 90 days
orderId	3623277	Integer	Number of the order generated in the system
outgoingTransferAmountFor30Days	100.25	Decimal	Outgoing transfer amount for 30 days
outgoingTransferAmountFor365Days	100.25	Decimal	Outgoing transfer amount for 365 days
outgoingTransferAmountFor60Days	100.25	Decimal	Outgoing transfer amount for 60 days
outgoingTransferAmountFor90Days	100.25	Decimal	Outgoing transfer amount for 90 days
totalDischargeAmount	15.410	Decimal	Amount of all issued funds
totalIssuedAmount	10.420	Decimal	Amount of all disbursed funds
totalRecurrentAmount	9.000	Decimal	Amount of all forcibly written-off funds
transfersFromMFO	true	true/false	Indicator of MFI loans

Signature computation

To compute the signature, do the following:

1. Sort POSTed parameters by their keys, alphabetically.
2. Concatenate values of these parameters in that order inserting the semicolon character ; between the values (only values for which there is an actual value presents need to be considered). This will produce a base string that will be signed.
3. Remove any gyphens - from your merchant control key, then decode it using HEX encoding; this will produce a HMAC key.
4. Compute hmac_sha1(base_string, hmac_key).
5. Encode the result as HEX this will produce the signature.

That signature needs to be put to the X-Authorization request header.

HMAC Debug

End Point
URL
Card expiry month
Card expiry year
BIN
Last four digits
CardRefID
uniqueCardRefId
CardNumber
merchant_control
Invoice No

X-Authorization

• CURL
• PHP
• Ruby

Copy to clipboard

Copy to clipboard

Copy to clipboard

Request and response examples

To get random data on staging environment sandbox.payneteasy.com use card number 4455 5555 5555 5544 or card-ref-id 555555.

Request examples:

Request with cardNumber parameter:

cardNumber=4731543184191796

Request with cardRefId parameter:

cardRefId=12345

Request with first6PanDigits and last4PanDigits parameters (expiration date is optional):

first6PanDigits=499939
last4PanDigits=5721
cardExpiryMonth=12
cardExpiryYear=2099

Response:

{
 "bankBin":499939,
 "cardFound":true,
 "countIssuedFor180Days":1,
 "countIssuedFor30Days":1,
 "countIssuedFor90Days":1,
 "incomingTransferAmountFor30Days":30.000,
 "incomingTransferAmountFor365Days":100.000,
 "incomingTransferAmountFor60Days":40.000,
 "incomingTransferAmountFor90Days":50.000,
 "lastDischargeAmount":10.000,
 "lastDischargeDate":"2018.03.26",
 "lastFourDigits":"5721",
 "lastSuccessfulDischargeAmount":10.000,
 "lastSuccessfulDischargeDate":"2018.03.26",
 "mfoCountFor180Days":1,
 "mfoCountFor30Days":1,
 "mfoCountFor90Days":1,
 "mfoIssuedFor180Days":1,
 "mfoIssuedFor30Days":1,
 "mfoIssuedFor90Days":1,
 "orderId":2709907,
 "outgoingTransferAmountFor30Days":10.000,
 "outgoingTransferAmountFor365Days":60.000,
 "outgoingTransferAmountFor60Days":20.000,
 "outgoingTransferAmountFor90Days":30.000,
 "totalDischargeAmount":200.000,
 "totalIssuedAmount":150.000,
 "totalRecurrentAmount":200.000
 "transfersFromMFO":false
}

Making scoring form requests

MFO scoring form requests allow to get html form template for MFO scoring procedure as a response. Html form template for MFO scoring accepts the card number which will be scored and then redirects customer to redirect url.

MFO scoring form flow

Merchant initiates request for MFO scoring form by sending HTTPS POST request to the specified URL of the Merchant`s endpoint on gate.payneteasy.com. After that, Payneteasy system returns response with url to MFO scoring form where customer will be redirected to input card information for MFO scoring request. Customer fills the MFO scoring form and sends request for MFO scoring to Payneteasy. Request is registered in the system. After that, Merchant initiates request to special MFO scoring form results URL and gets response with MFO scoring information.

MFO scoring form URL

https://gate.payneteasy.com/paynet/api/mfo/v2/scoring-form/{endpointId}/{clientOrderId}

for integration purposes use staging environment sandbox.payneteasy.com instead of production gate.payneteasy.com

Each request is supposed to have its own unique clientOrderId (merchant order ID). A request must be made using the HTTP POST method with UTF-8 encoding. Each parameter is to be supplied as a POST request parameter (using application/x-www-form-urlencoded).

Each request must be signed (see below). The signature must be put to Authorization request header.

Request parameters

MFO scoring form HTTP POST request body has one parameter which is accepted by the system, as you may see below:

Request parameter name	Format	Description
redirectUrl	String(128)	URL the customer will be redirected to upon completion of the mfo scoring request

Response data

A response is in JSON format (in UTF-8 encoding).

Response data has the following parameters:

Response parameter name	Format	Description
error	String	Error description (if error occurs)
orderId	String	Order id on payment gateway
redirectUrl	String	URL the customer will be redirected to fill the mfo scoring request data

If an error occurs, other two parameters are absent (only error parameter returned).

Receiving MFO scoring form request results

MFO scoring form request results URL

https://gate.payneteasy.com/paynet/api/mfo/v2/scoring-result/{endpointId}/{orderId}

orderId - order id on payment gateway. A request must be made using the HTTP POST method with UTF-8 encoding. Each parameter is to be supplied as a POST request parameter (using application/x-www-form-urlencoded).

This type of request has no parameters. Response to such request has the same set of response parameters as direct MFO scoring response which is described above.

Signature

MFO scoring form requests use oAuth 1.0a library - OAuth.