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¶
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:
- first6PanDigits and last4PanDigits
- cardRefId
- 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¶
All parameters in response are encoded in application/x-www-form-urlencoded MIME format
| 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:
- Sort POSTed parameters by their keys, alphabetically.
- 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.
- Remove any gyphens - from your merchant control key, then decode it using HEX encoding; this will produce a HMAC key.
- Compute hmac_sha1(base_string, hmac_key).
- Encode the result as HEX this will produce the signature.
That signature needs to be put to the X-Authorization request header.
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¶
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).
MFO scoring form request results URL¶
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.