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.

@startuml
participant Merchant
participant "PaynetEasy"
Merchant -> "PaynetEasy":MFO scoring order request
activate "PaynetEasy"
"PaynetEasy" -> Merchant:MFO scoring response
deactivate "PaynetEasy"
@enduml

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
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

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
CardNumber
merchant_control
Invoice No

X-Authorization
              
            
               
            
              
            

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.

@startuml
participant Merchant
participant "PaynetEasy"
Merchant -> "PaynetEasy":MFO scoring form request
activate "PaynetEasy"
"PaynetEasy" -> Merchant:"PaynetEasy" returns URL where Merchant should redirect customer for filling MFO scoring form
Merchant -> Merchant
note right: Merchant redirects customer to page\nwith MFO scoring form
Merchant -> "PaynetEasy":Merchant sends POST request with parameters from MFO scoring form to "PaynetEasy"
"PaynetEasy" -> "PaynetEasy"
note right: "PaynetEasy" accept and validate mfo scoring request
"PaynetEasy" -> Merchant:"PaynetEasy" response that request was accepted/not accepted
deactivate "PaynetEasy"
Merchant -> "PaynetEasy":Merchant sends request to get results of accepted MFO scoring form request
activate "PaynetEasy"
"PaynetEasy" -> Merchant:"PaynetEasy" returns MFO scoring results
deactivate "PaynetEasy"
@enduml

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 identificator). 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).

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.