iPay masterpass API v1.7.6

General Information

Masterpass is a digital wallet that stores card data in a MasterCard database. This wallet can store cards of any payment system, including VISA.

Masterpass OneClick solution, described in this documentation, can greatly simplify payments for goods and services over the Internet for a client.

Masterpass wallet has following parameters:

  1. Client’s login is a mobile phone number, format +380 ХХ ХХХ ХХ ХХ.
  2. Cards numbers - up to 5 different cards can be stored in a wallet.

Logic of interaction beetween Merchant and Masterpass is following. Merchant’s site must have an authorized zone, i.e. a personal account. Login or mandatory parameter must be client's phone number. IMPORTANT! A phone number cannot be changed by a user without additional verification (confirmation that he/she is an owner of this phone number. The best way to do it with one-time SMS-code).

When a client in Merchant’s Personal Account log-in for the first time after MasterPass OneClick installation, one of following options must be offered to a client:

  1. If a client has a masterpass wallet, offer him/her to link it to his/her personal account. Linking process means that a client trust this Merchant to initiate an authorization requests concerning his/her wallet.
  2. If a client has a wallet and it is already linked, a client must display cards that have been registered in his/her wallet.
  3. 3. If a client does not have a wallet, offer to register his/her first card for more convenient payments.
    (all options above are made on iPay.ua side while redirecting a client to specific URL)

A menu to manage cards in Masterpass wallet (adding, removing cards) must be implemented on Merchant’s site. Important to understand that Masterpass wallet is a global wallet. When a client adds or removes a card, it is added/removed in a global database, thus for all Merchants to whom this client has already linked his/her wallet.

After a client has registered in Merchant’s Personal Account and has linked his/her wallet, he/she can make a payment with one of his/her cards selecting it from a list. A Merchant does not redirect a client to service provider or acquirer's page to enter card data. Everything is done on Merchant's side in ONE CLICK. Funds are debited from a card using a special method.

iPay.ua may set up a one-time SMS-password verification (OTP_SMS) to secure a payment. Thus to execute transaction a client will receive 6-digit sms on his/her phone number registered in masterpass . A client must enter this code on Merchant’s site for confirmation. This client confirmation mechanism is set up for transactions exceeding a certain amount.

Access and settings

The following information must be received for interaction:

- login - merchant ID
- sign_key - signature key

URL for requests - https://walletmc.ipay.ua/

Transmission format - JSON методом POST

Encoding in UTF-8

Signature algorithm (a sign field in a request):
Two strings must be combined into one: “request time” (a time field in a request) and “signature key”. A result is encrypted by SHA-512 algorithm.

For example:
The time field in a request is "2017-01-01 00:00:00", sign_key is "12347b6ac566d63de29becf2a7e148ef".
We combine two strings into one: “2017-01-01 00: 00: 0012347b6ac566d63de29becf2a7e148ef” and encrypt a result by SHA-512 algorithm, encryption result "b0e540ef2db2505a8a646513785b5e370ad3958430934fe584f89a5e8b17e6d347ad43c763eb34736f4389b73fffc9a3303c3c25aa0081832dfd9a48f2e5a46d" will be a value of sign field in a request.

Request execution procedure

Flowchart

diagram

Sequence diagram

sequense

Adding a card to a wallet procedure

Prior to adding a NEW card, a request to check a phone number availability in MasterPass must be done (Check request).

There are 2 possible responses:
- notexists - there is no active MasterPass account;
- invite - a phone number has already been registered in MasterPass, and has a linked card/cards.

In case of notexists response, you must:
Execute RegisterByURL request and receive url registration form to redirect a client.

Registration has the following steps:
- card data and card name are entered;
- OTP verification of a phone number owner is performed (SMS with a code to be received and must be entered in a registration form);
- Card LookUp verification is performed (an amount of UAH 1 is blocked on a card and authorization code value must be entered in a registration form).

In case of invite response, you must:

Option 1: Execute InviteByURL request and receive url registration form to redirect a client.
- LookUp verification of a card already registered in MasterPass is performed (an amount of UAH 1 is blocked on a card, authorization code value must be entered in a registration form).

Option 2: Perform an Invite request and you will receive a token you must remember to execute a next request.
LookUp code of a card registered in MasterPass will be sent in sms to a phone number, thsi code must be transferred to "Otp" request.
Other fields to send Mpin request are executed by an application.

To add an ADDITIONAL card, you must:
Execute RegisterByURL request and receive url registration form to redirect a client.

Registration of an additional card has following steps:
- card data and card name are entered;
- card LookUp verification is performed (an amount of UAH 1 is blocked on a card, authorization code value must be entered in a registration form).

Payment creation and confirmation procedure

Payment type (one-step or two-step) is setup on iPay side.

One-step payment

To make a payment you must to execute one request PaymentCreate, requested amount is debited from client's card.

Two-step payment

When PaymentCreate request is executed, requested amount is blocked on client’s card.

After PaymentCreate request, payment must be completed with PaymentSale request.

During PaymentSale request following system response options are possible:
- if "invoice" field is filled, final debiting of requested amount is performed. Difference in amount is returned to a card.

General request structure

Request structures differ by action (request name) and body (request body) fields.

Field Type Description
request object Request object
request.auth object Authentification object
request.auth.login string Merchant ID
request.auth.time string Request time in Europe/Kiev time zone
request.auth.sign string Request signature
request.action string Request name
request.body object Request body object

Request example

{
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Check",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

List of requests

  1. List (list of available cards)

    2. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "List",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.{card_alias}.card_alias string Card name selected by a client
    response.{card_alias}.mask string Card mask (the first 6 digits and the last 2 digits of a card number)
    response.{card_alias}.uid string Unique card ID
    response.{card_alias}.is_expired integer 0 - active card
    1 - expired card
    response.{card_alias}.is_corporate integer 0 - not a corporate card
    1 - corporate card

    Response example

    {
    "response": {
        "TEST_CARD": {
            "card_alias": "TEST_CARD",
            "mask": "111122********44",
            "uid": "1B149F911665EBD54331CC3E7DD1BA5496F8F77590455A61511A190231B0FEC6",
            "is_expired": 0,
            "is_corporate": 0

        },
        "TEST_CARD_2": {
            "card_alias": "TEST_CARD_2",
            "mask": "111122********44",
            "uid": "5B149F911665EBD54331CC3E7DD1BA5496F8F77590455A61511A190231B0FEC6",
            "is_expired": 1,
            "is_corporate": 1
        }
    }
}

  2. Check (Client check)

    3. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Check",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.user_status string User status. May have the following values:

    - notexists - not a registered user;
    - exists - registered user and cards are available;
    - invite - registered user but confirmation is required to use cards;
    - blocked - masterpass wallet is blocked.

    Response example

    {
    "response": {
        "user_status": "notexists"
    }
}

  3. Invite (Client invitation)

    4. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Invite",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.verify string MPin verification must be performed
    response.token string Temporary unique token value (must be saved for transaction completion), string length of 192

    Response example

    {
    "response": {
        "verify": "mpin",
        "token": "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF ..."
    }
}

  4. UnlinkUser (Unlink client from merchant)

    5. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "UnlinkUser",
        "body": {
            "msisdn": "380931234567"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.status string Request status: success or error

    Response example

    {
    "response": {
        "status": "success"
    }
}

  5. InviteByURL (Client invitation through web interface)

    6. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    lang string Interface language may be one of the following values: ua | ru | en
    Optional fields
    success_url string Link to merchant's page after a successful request
    error_url string Link to merchant's page after a failed request

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "InviteByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.url string Link to a page to redirect a client to link an existing wallet

    Response example

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/link"
    }
}

  6. TestInvite (Client invitation testing)

    7. A service request that allows case independent testing when a client already has Masterpass wallet and it has to be linked to a Merchant. In response, a request returns to a page where new Masterpass wallet must be registered, following by Check request with the same phone number will respond that Masterpass wallet exists and must be linked to a Merchant.

    Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    lang string Interface language may be one of the following values: ua | ru | en

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "TestInvite",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.url string Link to a page to redirect a client to add a card

    Response example

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ua/partner/example/register?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  7. 6. RegisterByURL (Wallet registration with adding the first card through web interface)

    8. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    lang string Interface language may be one of the following values: ua | ru | en
    Optional fields
    success_url string Link to merchant's page after a successful request
    error_url string Link to merchant's page after a failed request

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "RegisterByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.url string Link to a page to redirect a client to add a card and register a wallet

    Response example

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/example/register?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  8. RegisterPurchaseByURL (Wallet registration with adding the first card and paying through web interface)

    9. If user's transaction is successful, a Merchant will receive a notification via POST method in XML format. Notification documentation is provided separately.

    Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    lang string Interface language may be one of the following values: ua | ru | en
    success_url string Link to merchant's page after a successful request
    error_url string Link to merchant's page after a failed request
    invoice integer Payment amount, in kopecks
    pmt_desc string Payment description provided by a merchant while being created (in a text format up to 100 characters)
    pmt_info object Payment information provided by a merchant while being created
    guid string Request ID generated by a merchant

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "RegisterPurchaseByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error",
            "invoice": 100,
            "pmt_desc": "Service: Internet; Account: 1234567; Amount: 100.00 UAH",
            "pmt_info": {
                "custom_field_1": 1234567,
                "custom_field_2": 100
            },
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.url string Link to a page to redirect a client to register a wallet and make a payment

    Response example

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/example/registerpurchase?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  9. AddcardByURL (Adding a card to an existing wallet through web interface)

    10. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    lang string Interface language may be one of the following values: ua | ru | en
    Optional fields
    success_url string Link to merchant's page after a successful request
    error_url string Link to merchant's page after a failed request

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "AddcardByURL",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "lang": "ru",
            "success_url": "http://localhost/success",
            "error_url": "http://localhost/error"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.url string Link to a page to redirect a client to add a card

    Response example

    {
    "response": {
        "url": "https://walletmp.ipay.ua/ru/partner/example/addcard?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R"
    }
}

  10. Otp (Card or payment verification using a one-time password)

    11. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    token string Temporary unique token value (must be saved for transaction completion), string length of 192
    value string Verification code

    Request example

     
{
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "Otp",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "token": "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF252D0D85C531C0 ...",
            "value": "625348"
        }
    }
}

    Card verification (MPin)

    Response structure

    Field Type Description
    response object Response body
    response.status string Transaction status may have two values: "OK" and "FAIL"

    Response example

    {
    "response": {
        "status": "OK"
    }
}

    Payment verification

    Response structure

    An indication of successful payment verification is status 5 (for one-step payment) or status 1 (for two-step payment) in response to a request.

    Field Type Description
    response object Response body
    response.pmt_id string Payment ID in iPay system
    response.invoice string Payment amount, in kopecks
    response.amount string Amount to be paid (including commission fees), in kopecks
    response.pmt_status string Payment status (1- registered, 4 - failed, 5 - successful)
    response.card_alias string Card name selected by a client
    response.card_mask string Card mask (the first 6 digits and the last 2 digits of a card number)
    response.msisdn string Telephone number, 12 digits (e.g., 380931234567)
    response.bank_response object Bank response
    response.bank_response.bank_id string Bank ID
    response.bank_response.rc string Response code
    response.bank_response.action string Request code (optional)
    response.bank_response.error_group string Error group

    Response example

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "5",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "bank_id": "28",
            "rc": "00",
            "action": "0",
            "error_group": ""
        }
    }
}

  11. CalcPaymentAmount (Calculating an amount to be paid, including a commission fee)

    12. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    invoice integer Payment amount, in kopecks

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "CalcPaymentAmount",
        "body": {
            "msisdn": "380931234567",
            "user_id": "750200",
            "invoice": 100
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.invoice integer Payment amount, in kopecks
    response.amount integer Amount to be paid (including a commission fee), in kopecks

    Response example

    {
    "response": {
        "invoice": 100,
        "amount": 102
    }
}

  12. 10. PaymentCreate (Payment creation)

    13. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    invoice integer Payment amount, in kopecks
    card_alias string Card name selected by a client
    pmt_desc string Payment description provided by a merchant while being created (in a text format up to 100 characters)
    pmt_info object Payment information provided by a merchant while being created
    Optional fields
    guid string Request ID generated by a merchant

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentCreate",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "invoice": 100,
            "card_alias": "TEST",
            "pmt_desc": "Service: Internet; Account: 1234567; Amount: 100.00 UAH",
            "pmt_info": {
                "custom_field_1": 1234567,
                "custom_field_2": 100
            },
            "guid": "AD68E7675FE111E79A65005056B960DF"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.pmt_id string Payment ID in iPay system
    response.invoice string Payment amount, in kopecks
    response.amount string Amount to be paid (including commission fees), in kopecks
    response.pmt_status string Payment status (0 - additional verification is required, 1 - registered, 4 - failed, 5 - successful)
    response.card_alias string Card name selected by a client
    response.card_mask string Card mask (the first 6 digits and the last 2 digits of a card number)
    response.msisdn string Telephone number, 12 digits (e.g., 380931234567)
    response.bank_response object Bank response
    response.bank_response.bank_id string Bank ID
    response.bank_response.rc string Response code
    response.bank_response.action string Request code (optional)
    response.bank_response.error_group string Error group
    In case a payment to be verified, additional fields are returned
    response.secure string Payment verification type may have one of the following values:
    - "otp" (OTP verification)
    - "3ds" (3DS verification)
    OTP verification
    response.token string Temporary unique token value (must be saved for transaction completion), string length of 192
    3DS verification
    response.ascUrl string A link to redirect a client to pass 3DS verification
    response.pareq string 3D Secure authentication results
    response.md string Unique transaction ID

    Response example (without verification)

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": "100",
        "amount": "102",
        "pmt_status": "1",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "bank_id": "28",
            "rc": "00",
            "action": "0",
            "error_group": ""
        }
    }
}
    Response example (OTP verification) 
    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "0",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "bank_id": "28",
            "rc": "00",
            "action": "0",
            "error_group": ""
        },
        "secure": "otp",
        "token" : "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF ..."
    }
}
    In case of OTP verification, a code was sent in sms to card owner mobile phone. This code and token received on request must be submitted to “Otp” request; and in case of successful verification, an amount on client’s account will be debited or blocked depending on a payment type - one-step or two-step payment.

    Response example (3DS verification) 
    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "0",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "bank_id": "28",
            "rc": "00",
            "action": "0",
            "error_group": ""
        },
        "secure": "3ds",
        "ascUrl": "https://example.com/acs",
        "pareq": "eJxlUttygjAQ\/RXHDzAJIoKzZgbr1MEp3mBa7UsnQkZRucjFol\/fhFKlbV5y9uTs7kk24O5TzscO ...",
        "md": "CmD2M2QzYmItOBJjZS00YWAjLTlhMTctNjRiOWYzNWQyNTFk"
    }
}

    In case of 3DS verification, the following fields are returned in response: ascUrl, pareq, md.
    ascUrl field is a link to redirect a client to do 3DS verification.
    ares and md fields must be transferred to ascUrl using POST method.

    An example of a form directing a client to do 3DS verification: 
                
<form name="MPIform" action='{url}' method="POST">
    <input type="hidden" name="PaReq" value='{pareq}'>
    <input type="hidden" name="MD" value='{md}'>
    <input type="hidden" name="TermUrl" value='{TermUrl}'>
</form>
    TermUrl field is a link to Merchant's page where a bank redirects a client after verification and returns using POST method results that contain the following fields: PaRes, MD. These results have to be sent on "PaymentVerify3DS" request, and if verification is successful an amount on a client’s account will be debited or blocked depending on a payment type - one-step or two-step payment.

  13. PaymentVerify3DS (Perform 3DS verification of a payment)

    14. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    pmt_id integer Payment ID in iPay system
    pares string 3DS verification results
    md string Unique transaction ID

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentVerify3DS",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_id": "1234567",
            "pares": "eJxlUttygjAQ\/RXHDzAJIoKzZgbr1MEp3mBa7UsnQkZRucjFol\/fhFKlbV5y9uTs7kk24O5TzscO ...",
            "md": "CmD2M2QzYmItOBJjZS00YWAjLTlhMTctNjRiOWYzNWQyNTFk"
        }
    }
}

    Response structure

    Indication of successful payment verification is status 5 (for one-step payment) or status 1 (for two-step payment) in response to a request.

    Field Type Description
    response object Response body
    response.pmt_id string Payment ID in iPay system
    response.invoice string Payment amount, in kopecks
    response.amount string Amount to be paid (including a commission fee), in kopecks
    response.pmt_status string Статус платежу (1 - зареєстрований, 4 - неуспішний, 5 - успішний)
    response.card_alias string Card name selected by a client
    response.card_mask string Card mask (the first 6 digits and the last 2 digits of a card number)
    response.msisdn string Telephone number, 12 digits (e.g., 380931234567)
    response.bank_response object Bank response
    response.bank_response.bank_id string Bank ID
    response.bank_response.rc string Response code
    response.bank_response.action string Request code (optional)
    response.bank_response.error_group string Error group

    Response example

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "1",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "bank_id": "28",
            "rc": "00",
            "action": "0",
            "error_group": ""
        }
    }
}

  14. PaymentSale (Make a payment)

    15. This request is performed only in case of two-stage payment.

    Request body structure

    Field Type Description
    Mandatory fields
    pmt_id integer Payment ID in iPay system
    invoice integer Final purchase amount in kopecks
    Optional fields
    guid string Request ID generated by a merchant

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentSale",
        "body": {
            "pmt_id": "1234567",
            "invoice": 100,
            "guid": "e55f613987964042a92bfc2d4f0d610d"
        }
    }
}

    Response structure

    Indication of successfully verified payment is status 5 in response to a request.

    Field Type Description
    response object Response body
    response.pmt_id string Payment ID in iPay system
    response.invoice string Payment amount, in kopecks
    response.amount string Amount to be paid (including commission fees), in kopecks
    response.pmt_status string Payment status (1- registered, 4 - failed, 5 - successful, 9 - canceled)
    response.card_alias string Card name selected by a client
    response.card_mask string Card mask (the first 6 digits and the last 2 digits of a card number)
    response.msisdn string Telephone number, 12 digits (e.g., 380931234567)
    response.bank_response object Bank response
    response.bank_response.bank_id string Bank ID
    response.bank_response.rc string Response code
    response.bank_response.action string Request code (optional)
    response.bank_response.error_group string Error group

    Response example

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "5",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "bank_id": "28",
            "rc": "00",
            "action": "0",
            "error_group": ""
        }
    }
}

  15. PaymentCancel (Payment cancel)

    16. Request body structure

    Field Type Description
    Mandatory fields
    pmt_id integer Payment ID in iPay system
    Optional fields
    amount integer Refund amount, in coins

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "PaymentCancel",
        "body": {
            "pmt_id": "1234567",
            "guid": "e55f613987964042a92bfc2d4f0d610d"
        }
    }
}

    Response structure

    Indication of successfully canceled payment is status 9 in response to a request.

    Field Type Description
    response object Response body
    response.pmt_id string Payment ID in iPay system
    response.invoice string Payment amount, in kopecks
    response.amount string Amount to be paid (including a commission fee), in kopecks
    response.pmt_status string Payment status (1- registered, 4 - failed, 5 - successful, 9 - canceled)
    response.card_alias string Card name selected by a client
    response.card_mask string Card mask (the first 6 digits and the last 2 digits of a card number)
    response.msisdn string Telephone number, 12 digits (e.g., 380931234567)
    response.bank_response object Bank response
    response.bank_response.bank_id string Bank ID
    response.bank_response.rc string Response code
    response.bank_response.action string Request code (optional)
    response.bank_response.error_group string Error group

    Response example

    {
    "response": {
        "pmt_id": "1234567",
        "invoice": 100,
        "amount": 102,
        "pmt_status": "9",
        "card_alias": "TEST",
        "card_mask": "111122********44",
        "msisdn": "380931234567",
        "bank_response":  {
            "bank_id": "28",
            "rc": "00",
            "action": "0",
            "error_group": ""
        }
    }
}

  16. GetPaymentInvoice (Request a receipt)

    17. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    pmt_id integer Payment ID in iPay system

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "GetPaymentInvoice",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_id": "1234567"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.invoice string Link to a receipt

    Response example

    {
    "response": {
        "invoice": "https://example.com/invoice/23d53e29722d2b03c954718c1d54b53787985090"
    }
}

  17. DeleteCard (Card deletion)

    18. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    card_alias string Card name that to be removed from a wallet

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "DeleteCard",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "card_alias": "TEST"
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.status string Transaction status may have two values: "OK" and "FAIL"

    Response example

    {
    "response": {
        "status": "OK"
    }
}

  18. StatusRequest (Request status)

    19. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    guid string Merchant's request ID that was transferred in previous requests

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "StatusRequest",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "guid": "e55f613987964042a92bfc2d4f0d610d"
        }
    }
}

    Response structure

    Field Type Description
    response array Response body
    response[].type string Request type
    response[].msisdn string Telephone number, 12 digits (e.g., 380931234567)
    response[].response string Response in JSON format
    response[].date string Date when request was done

    Response example

    {
    "response": [
        {
            "type": "PaymentCreate",
            "msisdn": "380931234567",
            "response": "{"pmt_id":"1234567","invoice":"200000","amount":"200000","pmt_status":"1",
                        "card_alias":"TEST","card_mask":"111122********44","msisdn":"380931234567",
                        "bank_response":"{"bank_id":28,"rc":"00","action":"0","error_group":""}"}",
            "date": "2017-01-01 15:47:27"
        }
    ]
}

  19. Widget session initiation (InitWidgetSession)

    20. Request body structure

    Field Type Description
    Mandatory fields
    msisdn string Telephone number, 12 digits (e.g., 380931234567)
    user_id string Merchant's internal client ID, letters, hyphen, figures may be used, up to 45 characters
    pmt_desc string Payment description provided by a merchant while being created (in a text format up to 100 characters)
    pmt_info object Payment information provided by a merchant while being created
    pmt_info.invoice integer Payment amount, in kopecks

    Request example

    {
    "request": {
        "auth": {
            "login": "test",
            "time": "2017-01-01 00:00:00",
            "sign": "e55f613987964042a92bfc2d4f0d610d"
        },
        "action": "InitWidgetSession",
        "body": {
            "msisdn": "380931234567",
            "user_id": "720500",
            "pmt_desc": "Service: Internet; Account: 1234567; Amount: 100.00 UAH",
            "pmt_info": {
                "invoice": 100
            }
        }
    }
}

    Response structure

    Field Type Description
    response object Response body
    response.session string Session ID

    Response example

    {
    "response": {
        "session": "487fcwbg7xafbT3R652mc8c2794r7l5C"
    }
}

Test cards

During testing payment verification is enabled for amounts over UAH 5 (500 kopecks); a payment will be made without verification if an amount is less.

OTP password for OTP payment verification is static: 471771

Card number CVC2/CVV2 Expiration date Description
5506900140100107 [Any] [Any] Successful payment, 3DS verification
5506900140100206 [Any] [Any] Failed payment, 3DS verification
5204740009900048 [Any] [Any] Successful payment, OTP verification
5204740009900055 [Any] [Any] Failed payment, OTP verification

General system errors

Response structure

Field Type Description
response object Response body
response.error string Error name

Response example

{
    "response": {
        "error": "invalid request structure"
    }
}

List of possible errors

Error Description
overall error General error
invalid request structure Incorrect request structure
user validation failed Field "user_id" validation error. Phone number already exists in different user profile at merchant personal area.
unknown field {field_name} A field unknown to a system transferred in a request
invalid expm Invalid expm value
invalid expy Invalid expy value
invalid cvv Invalid cvv value
invalid value Invalid value
invalid pan Invalid pan value
invalid auth Authentication error
invalid auth time Invalid request time
access denied Access denied
invalid msisdn Invalid msisdn value
invalid clientIp Invalid clientIp value
card is expired Card is expired
no card Card not found
try again later Please try to repeat your request later

Bank error codes

Bank ID is returned in bank_response field on PaymentCreate, PaymentSale, PaymentCancel requests.

Bank ID URL
28 (Oshadbank) Error codes
29 (Privatbank) Error codes
31 (Raiffeisen Bank Aval) Error codes

Enabling MasterPass widget

1. InitWidgetSession request must be executed, response received is session ID that is valid within 30 minutes.
2. Place widget request code on a page. Example of a page with enabled widget:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta content="width=device-width, initial-scale=1.0" name="viewport">
    <title>iPay Masterpass Widget</title>
    <script type="text/javascript" src="https://widgetmp.ipay.ua/widget.js"></script>
</head>
<body>
<a href="#" onclick="MasterpassWidget.open(
            {
                partner: 'test',
                lang: 'ru', 
                session: '123fcwbg7xafbT3R652mc4c2794r7l5C'
            },
            // callback function after widget close
            function() {},
            // callback function after success payment
            function() {},
            // callback function after failed payment
            function() {}
);">
    <img src="https://widgetmp.ipay.ua/mp-button.svg">
</a>
</body>
</html>
To use MasterpassWidget.open method an object has to be transferred with the following fields:
- partner - Merchant ID (login);
- lang - interface language (ru | ua);
- session - session ID received on InitWidgetSession request.

If user's transaction is successful, a Merchant will receive a notification via POST method in XML format. Notification documentation is provided separately.

History of changes

Date Version Description
2016-09-14 1.1 Set up PaymentCreate, PaymentSale requests.
2016-12-02 1.2 Set up RegisterByURL, DeleteCard requests.
2016-12-12 1.3 Set up InviteByURL request.
2017-02-13 1.4 Flowchart and sequence diagram were added.

PaymentStatus, PaymentCancel methods were removed from production environment due to modification.
2017-02-17 1.4.1 Amount field in PaymentSale request and possibility of partial refund after cancellation were added.
2017-02-21 1.4.2 Errors were corrected in documentation section "Payment creation and confirmation procedure" and in PaymentSale request.
2017-02-22 1.5 PaymentCancel request (payment cancellation) was added.
2017-02-24 1.6 StatusRequest request (request verification) was added.

PaymentCancel request was changed: mandatory "msisdn" parameter was added to get correct StatusRequest response using this method.
2017-03-06 1.6.1 Optional "guid" parameter was added to check request status.
2017-03-10 1.6.2 Invite method was returned to documentation.
2017-03-15 1.6.5 AddcardByURL method was added - adding a card to existing wallet.
2017-03-22 1.6.7 Section "General Information" was updated.
2017-04-11 1.6.8 PaymentCreate, PaymentSale, PaymentCancel requests were updated: bank_response field was added to a response.

Section "Bank error codes" was added.
2017-05-16 1.6.9 PaymentCareate request was updated: OTP, 3DS payment verifications were added.

Privatbank as a new acquirer bank was added.
2017-06-02 1.7.0 Additional parameters success_url, error_url were added to AddcardByURL, InviteByURL and RegisterByURL methods
(link to Merchant’s page after successful or failed request)
2017-06-15 1.7.1 The following requests were added:
- CalcPaymentAmount (calculating an amount to be paid (including a commission fee))
- TestInvite (client invitation testing)
2017-06-22 1.7.2 Field user_id was added to each request (Merchant’s internal user ID)
2017-07-03 1.7.3 RegisterPurchaseByURL request (wallet registration with adding the first card and paying through web interface) was added
2017-07-13 1.7.4 One-step payment was added.
2017-07-24 1.7.5 Field is_expired (if a card has expired or not) was added to List request response.
2017-09-11 1.7.6 Raiffeisen Bank Aval as a new bank-acquirer was added.

Field is_corporate (if a card is corporate or not) was added to List request response.