3.39. /api/mfo/scoring

Introduction

Card scoring is initiated through HTTPS POST request to the URLs and the parameters specified below. Each request should have {client_order_ID}, generated by Connecting Party. {endpointId} in request URL is provided by Payment Gateway. Each request should be signed and the signature should be put to X-Authorization request header.

API URLs

Integration

Production

https://sandbox.payneteasy.com/paynet/api/mfo/scoring/{endpoint_id}/{client_order_id}

https://gate.payneteasy.com/paynet/api/mfo/scoring/{endpoint_id}/{client_order_id}

Request Parameters

Parameter name

Description

Format

first6PanDigits

First 6 digits of the card number. Send either cardRefId or cardNumber or a combination of first6PanDigits and last4PanDigits, not all.

N6

last4PanDigits

Last 4 digits of the card number. Send either cardRefId or cardNumber or a combination of first6PanDigits and last4PanDigits, not all.

N4

cardRefId

The card-ref-id (Card Reference ID) created earlier with /api/v2/create-card-ref/ request that can be used to find the specific card by its token. Send either cardRefId or cardNumber or a combination of first6PanDigits and last4PanDigits, not all.

N{1-*}

uniqueCardRefId

The unq-card-ref-id (Unique Card Reference ID) to each PAN created earlier with /api/v2/create-card-ref/ request that can be used by Connecting Party for loyalty programs or fraud control.

N{1-*}

cardNumber

Full card number. Send either cardNumber or cardRefId or a combination of first6PanDigits and last4PanDigits, not all.

N{13-19}

cardExpiryMonth

Card expiration month, if first6PanDigits and last4PanDigits are used (optional).

N{1-2}

cardExpiryYear

Card expiration year, if first6PanDigits and last4PanDigits are used (optional).

N4

Response Parameters

Parameter name

Description

Format

error

If error occurs, here you may see brief error description.
Type: String

bankBin

Card`s bank identification number (As a rule, first 6 digits of the card number).
Type: Integer
Example: 444444

cardFound

This parameter shows if the system has card scoring information on this card or not.
Type: Boolean
Example: true

countIssuedFor180Days

The number of transactions for the issuance of MFI loans for the last 180 days.
Type: Integer
Example: 1

countIssuedFor30Days

The number of transactions for the issuance of MFI loans for the last 30 days.
Type: Integer
Example: 1

countIssuedFor90Days

The number of transactions for the issuance of MFI loans for the last 90 days.
Type: Integer
Example: 1

expiredMonth

Card expiration month.
Type: Integer
Example: 12

expiredYear

Card expiration year.
Type: Integer
Example: 2099

incomingTransferAmountFor30Days

Incoming transfer amount for 30 days.
Type: Decimal
Example: 100.25

incomingTransferAmountFor365Days

Incoming transfer amount for 365 days.
Type: Decimal
Example: 100.25

incomingTransferAmountFor60Days

Incoming transfer amount for 60 days.
Type: Decimal
Example: 100.25

incomingTransferAmountFor90Days

Incoming transfer amount for 90 days.
Type: Decimal
Example: 100.25

lastDischargeAmount

Amount of last repayment.
Type: Decimal
Example: 111.400

lastDischargeDate

Date of last repayment.
Type: YYYY.MM.DD
Example: 2015.07.24

lastFourDigits

Last 4 digits of the card number.
Type: Integer
Example: 1234

lastSuccessfulDischargeAmount

The amount of the last successful repayment.
Type: Decimal
Example: 1.400

lastSuccessfulDischargeDate

The date of the last successful repayment.
Type: YYYY.MM.DD
Example: 2015.07.24

mfoCountFor180Days

Number of unique MFIs conducting transactions in the last 180 days.
Type: Integer
Example: 1

mfoCountFor30Days

Number of unique MFIs conducting transactions in the last 30 days.
Type: Integer
Example: 1

mfoCountFor90Days

Number of unique MFIs conducting transactions in the last 90 days.
Type: Integer
Example: 1

mfoIssuedFor180Days

Number of unique MFIs that issued loans in the last 180 days.
Type: Integer
Example: 1

mfoIssuedFor30Days

Number of unique MFIs that issued loans in the last 30 days.
Type: Integer
Example: 1

mfoIssuedFor90Days

Number of unique MFIs that issued loans in the last 90 days.
Type: Integer
Example: 1

orderId

Number of the order generated in the system.
Type: Integer
Example: 3623277

outgoingTransferAmountFor30Days

Outgoing transfer amount for 30 days.
Type: Decimal
Example: 100.25

outgoingTransferAmountFor365Days

Outgoing transfer amount for 365 days.
Type: Decimal
Example: 100.25

outgoingTransferAmountFor60Days

Outgoing transfer amount for 60 days.
Type: Decimal
Example: 100.25

outgoingTransferAmountFor90Days

Outgoing transfer amount for 90 days.
Type: Decimal
Example: 100.25

totalDischargeAmount

Amount of all issued funds.
Type: Decimal
Example: 15.410

totalIssuedAmount

Amount of all disbursed funds.
Type: Decimal
Example: 10.420

totalRecurrentAmount

Amount of all forcibly written-off funds.
Type: Decimal
Example: 9.000

transfersFromMFO

Indicator of MFI loans.
Type: true/false
Example: true

Request example

Request with cardNumber parameter:

POST /paynet/api/mfo/scoring/3772/123456
HTTP/1.1
Host: sandbox.payneteasy.com
User-Agent: curl/7.88.1
Accept: */*
X-Authorization: 3ea5d48e9354496c2576ef5ecee0324b2aabca6c
Content-Length: 27
Content-Type: application/x-www-form-urlencoded
Connection: close

cardNumber=4731543184191796
Request with cardRefId parameter:

POST /paynet/api/mfo/scoring/3772/123456 HTTP/2
Host: sandbox.payneteasy.com
User-Agent: curl/7.88.1
Accept: */*
X-Authorization: a3774b3911a833425f635e45474ecd9fe2714d3a
Content-Length: 15
Content-Type: application/x-www-form-urlencoded

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

POST /paynet/api/mfo/scoring/3772/123456
HTTP/2
Host: sandbox.payneteasy.com
User-Agent: curl/7.88.1
Accept: */*
X-Authorization: b548c006285fde742d608238be18fa0e5b559a08
Content-Length: 81
Content-Type: application/x-www-form-urlencoded

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

Success Response Example

HTTP/2 200 OK
Date: Mon, 01 Dec 2020 11:47:18 GMT
Content-Type: application/json;charset=UTF-8

{
 "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":"2023.03.26",
 "lastFourDigits":"5721",
 "lastSuccessfulDischargeAmount":10.000,
 "lastSuccessfulDischargeDate":"2023.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
}

Fail Response Example

HTTP/2 200 OK
Date: Mon, 01 Dec 2020 11:47:18 GMT
Content-Type: application/json;charset=UTF-8

{"orderId":1234567,"cardFound":false}

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 connecting party 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.


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

Request Builder

To get random data on staging environment sandbox.payneteasy.com use cardNumber = 4455555555555544 or cardRefId = 555555.

End Point
URL
Card expiry month
Card expiry year
BIN
Last four digits
CardRefID
Unique CardRefId
Card Number
Merchant Control
Client Order Id
signature method

X-Authorization