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:
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:
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.
The following information must be received for interaction:
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.
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.
Payment type (one-step or two-step) is setup on iPay side.
To make a payment you must to execute one request PaymentCreate, requested amount is debited from client's card.
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.
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "Check", "body": { "msisdn": "380931234567", "user_id": "720500" } } }
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "List", "body": { "msisdn": "380931234567", "user_id": "720500" } } }
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": { "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 } } }
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "Check", "body": { "msisdn": "380931234567", "user_id": "720500" } } }
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": { "user_status": "notexists" } }
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "Invite", "body": { "msisdn": "380931234567", "user_id": "720500" } } }
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": { "verify": "mpin", "token": "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF ..." } }
Field | Type | Description |
---|---|---|
Mandatory fields | ||
msisdn | string | Telephone number, 12 digits (e.g., 380931234567) |
{ "request": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "UnlinkUser", "body": { "msisdn": "380931234567" } } }
Field | Type | Description |
---|---|---|
response | object | Response body |
response.status | string | Request status: success or error |
{ "response": { "status": "success" } }
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": { "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" } } }
Field | Type | Description |
---|---|---|
response | object | Response body |
response.url | string | Link to a page to redirect a client to link an existing wallet |
{ "response": { "url": "https://walletmp.ipay.ua/ru/partner/link" } }
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.
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "TestInvite", "body": { "msisdn": "380931234567", "user_id": "720500", "lang": "ru" } } }
Field | Type | Description |
---|---|---|
response | object | Response body |
response.url | string | Link to a page to redirect a client to add a card |
{ "response": { "url": "https://walletmp.ipay.ua/ua/partner/example/register?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R" } }
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": { "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" } } }
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": { "url": "https://walletmp.ipay.ua/ru/partner/example/register?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R" } }
If user's transaction is successful, a Merchant will receive a notification via POST method in XML format. Notification documentation is provided separately.
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": { "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" } } }
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": { "url": "https://walletmp.ipay.ua/ru/partner/example/registerpurchase?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R" } }
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": { "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" } } }
Field | Type | Description |
---|---|---|
response | object | Response body |
response.url | string | Link to a page to redirect a client to add a card |
{ "response": { "url": "https://walletmp.ipay.ua/ru/partner/example/addcard?hash=7edP4Z3q3ebQ4ubB3C8Zbv76cRd02m3R" } }
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "Otp", "body": { "msisdn": "380931234567", "user_id": "720500", "token": "ED7461B42BDAFC0554EC6452436C84151FC38A52D1C7B1CED19915A1911B3620BC4B6CB16F15EBF252D0D85C531C0 ...", "value": "625348" } } }
Field | Type | Description |
---|---|---|
response | object | Response body |
response.status | string | Transaction status may have two values: "OK" and "FAIL" |
{ "response": { "status": "OK" } }
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": { "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": "" } } }
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "CalcPaymentAmount", "body": { "msisdn": "380931234567", "user_id": "750200", "invoice": 100 } } }
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": { "invoice": 100, "amount": 102 } }
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": { "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" } } }
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": { "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": { "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.
<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.
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": { "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" } } }
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": { "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": "" } } }
This request is performed only in case of two-stage payment.
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "PaymentSale", "body": { "pmt_id": "1234567", "invoice": 100, "guid": "e55f613987964042a92bfc2d4f0d610d" } } }
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": { "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": "" } } }
Field | Type | Description |
---|---|---|
Mandatory fields | ||
pmt_id | integer | Payment ID in iPay system |
Optional fields | ||
amount | integer | Refund amount, in coins |
{ "request": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "PaymentCancel", "body": { "pmt_id": "1234567", "guid": "e55f613987964042a92bfc2d4f0d610d" } } }
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": { "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": "" } } }
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "GetPaymentInvoice", "body": { "msisdn": "380931234567", "user_id": "720500", "pmt_id": "1234567" } } }
Field | Type | Description |
---|---|---|
response | object | Response body |
response.invoice | string | Link to a receipt |
{ "response": { "invoice": "https://example.com/invoice/23d53e29722d2b03c954718c1d54b53787985090" } }
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "DeleteCard", "body": { "msisdn": "380931234567", "user_id": "720500", "card_alias": "TEST" } } }
Field | Type | Description |
---|---|---|
response | object | Response body |
response.status | string | Transaction status may have two values: "OK" and "FAIL" |
{ "response": { "status": "OK" } }
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": { "auth": { "login": "test", "time": "2017-01-01 00:00:00", "sign": "e55f613987964042a92bfc2d4f0d610d" }, "action": "StatusRequest", "body": { "msisdn": "380931234567", "user_id": "720500", "guid": "e55f613987964042a92bfc2d4f0d610d" } } }
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": [ { "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" } ] }
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": { "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 } } } }
Field | Type | Description |
---|---|---|
response | object | Response body |
response.session | string | Session ID |
{ "response": { "session": "487fcwbg7xafbT3R652mc8c2794r7l5C" } }
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 |
Field | Type | Description |
---|---|---|
response | object | Response body |
response.error | string | Error name |
{ "response": { "error": "invalid request structure" } }
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 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 |
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:
If user's transaction is successful, a Merchant will receive a notification via POST method in XML format. Notification documentation is provided separately.
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. |