Bank card (GrataPay side)

Acquiring. Card data is collecting on the GrataPay side. Additional fields for /deposit/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.CardGate
notestringYesPayment description for client.Account deposit 321
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > client_idstringNoClient ID in the Merchant system321

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "CardGate",
    "note": "Account deposit 321",
    "system_fields": {
        "client_id": "321"
    },
    "url": {
        "callback_url": "https://site.com/callback",
        "fail_url": "https://site.com/fail",
        "pending_url": "https://site.com/pending",
        "success_url": "https://site.com/success"
    }
}
                    

Answer is common GrataPay response with Redirect block to GrataPay checkout page. After checkout client will be redirected to 3DS and then returned according the url block if present.

Bank card (Merchant side)

Acquiring. Card data is collecting on the Merchant side. Additional fields for /deposit/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.CardGateS2S
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > client_idstringYesClient ID in the Merchant system321
system_fields > card_numberstringYesCard number4111111111111111
system_fields > card_monthinteger(2)YesCard expiry month1
system_fields > card_yearinteger(4)YesCard expiry year2020
system_fields > cardholder_namestringYesCardholder nameMr Cardholder
system_fields > card_cvvintegerYesCard security code345
system_fields > client_emailstringNoClient e-mailtest@test.com
system_fields > client_phonestringNoClient phone in international format+37111111111
system_fields > client_ipstringNoClient ip-address192.168.1.1
system_fields > client_user_agentstringNoUser-agent of client browserMozilla/5.0 (Windows NT 6.2; WOW64) AppleWebKit/534.57.2 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2

Optional fields can be needed in live mode. Please specify it before going live.

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "CardGateS2S",
    "note": "Account deposit 321",
    "system_fields": {
        "client_id": "321",
        "card_number": "4111111111111111",
        "card_month": "01",
        "card_year": "2020",
        "cardholder_name": "Mr Cardholder",
        "card_cvv": "345"
    },
    "url": {
        "callback_url": "https://site.com/callback",
        "fail_url": "https://site.com/fail",
        "pending_url": "https://site.com/pending",
        "success_url": "https://site.com/success"
    }
}
                    

Answer is common GrataPay response with Redirect block to 3DS page. After passing 3DS client will be returned according the url block if present.

Attention! Redirect block can contain different "url", "method" and "params".

The example of the common response:

{
    "status": "created",
    "id": "300",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.3",
    "amount_client": "10.00",
    "currency": "RUB",
    "payment_system": "CardGateS2S",
    "redirect": {
        "url": "https://bank.com/3ds",
        "method": "POST",
        "params": {
            "pareq": "12345678"
        }
    }
}
                    

In some cases answer may not contain redirect block. It could happen in some cases like not enrolled in 3DS card or some unexpected system behavior. Merchant system should await for callback with final status or check status of the transaction by itself.

The example of that kind of response:

{
    "status": "created",
    "id": "300",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "10.00",
    "amount_merchant": "9.3",
    "amount_client": "10.00",
    "currency": "RUB",
    "payment_system": "CardGateS2S"
}
                    

3DSv2 (Merchant side)

Additional request data needs to be sent to use 3DSv2 authentication method.

Additional fields for /deposit/create request:

FieldTypeMandatoryDescriptionExample
three_ds_v2objectOnly for 3DSv2Container for 3DSv2 parameters
three_ds_v2 > accept_headerstringYesExact content of the HTTP accept headers as sent to the 3DS Requester from the Cardholder browser.text/html,application/xhtml+xml,application/xml
three_ds_v2 > java_enabledbooleanYesBoolean that represents the ability of the cardholder browser to execute Java. The value can be retrieved by accessing a property of the navigator with JavaScript, navigator.javaEnabled.true
three_ds_v2 > languagestringYesValue representing the browser language as defined in IETF BCP47. The value can be retrieved by accessing a property of the navigator with JavaScript, navigator.language.en-EN
three_ds_v2 > color_depthintegerYesValue representing the bit depth of the colour palette for displaying images, in bits per pixel. Obtained from Cardholder browser using the screen.colorDepth property. The value can be one of 1, 4, 8, 15, 16, 24, 32, 48.48
three_ds_v2 > screen_heightintegerYesTotal height of the Cardholder's screen in pixels. Value is returned from the screen.height property.800
three_ds_v2 > screen_widthintegerYesTotal width of the Cardholder's screen in pixels. Value is returned from the screen.width property.600
three_ds_v2 > time_zone_offsetstringYesTime difference between UTC time and the Cardholder browser local time, in minutes. The value can be retrieved using Javascript getTimezoneOffset() method.-300
three_ds_v2 > user_agentstringYesExact content of the HTTP user-agent header.AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0
three_ds_v2 > ipstringYesCardholder's IP address.127.0.0.1

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "CardGateS2S",
    "note": "Account deposit 321",
    "system_fields": {
        "client_id": "321",
        "card_number": "4111111111111111",
        "card_month": "01",
        "card_year": "2020",
        "cardholder_name": "Mr Cardholder",
        "card_cvv": "345"
    },
    "url": {
        "callback_url": "https://site.com/callback",
        "fail_url": "https://site.com/fail",
        "pending_url": "https://site.com/pending",
        "success_url": "https://site.com/success"
    },
    "three_ds_v2": {
        "accept_header": "text/html,application/xhtml+xml,application/xml",
        "java_enabled": true,
        "language": "en-EN",
        "color_depth": 48,
        "screen_height": 800,
        "screen_width": 600,
        "time_zone_offset": "-300",
        "user_agent": "AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0",
        "ip": "127.0.0.1",
    }
}
                    

Qiwi Wallet

Additional fields for /deposit/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.Qiwi
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > qiwi_walletstringYesQiwi wallet number+79008007000
system_fields > qiwi_commentstringYesPayment description showing on Qiwi checkout pageAccount deposit 321
system_fields > qiwi_lifetimedate(Y-m-d\TH:i:s)YesLifetime of payment after it will be considered as failed in the GMT+3 timezone. Default value: +3 days.2020-01-30T01:02:03
system_fields > qiwi_successUrlurlYesURL for client redirection in case of successhttp://site.com/success
system_fields > qiwi_failUrlurlYesURL for client redirection in case of failhttp://site.com/fail

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "Qiwi",
    "note": "Account deposit 321",
    "system_fields": {
        "qiwi_wallet": "+79008007000",
        "qiwi_comment": "Account deposit 321",
        "qiwi_lifetime": "2020-01-30T01:02:03",
        "qiwi_successUrl": "http://site.com/success",
        "qiwi_failUrl": "http://site.com/fail"
    },
    "url": {
        "callback_url": "https://site.com/callback",
        "fail_url": "https://site.com/fail",
        "pending_url": "https://site.com/pending",
        "success_url": "https://site.com/success"
    }
}
                    

Answer is common GrataPay response with Redirect block to Qiwi checkout page. After checkout client will be returned according the qiwi_successUrl and qiwi_failUrl.

Additional fields for /deduce/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.Qiwi
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > qiwi_walletstringYesTarget wallet number in the Qiwi system to payout funds+79008007000

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "Qiwi",
    "note": "Account payout 321",
    "system_fields": {
        "qiwi_wallet": "+79008007000"
    },
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
                    

Answer is common GrataPay payout response.

Yandex Wallet

Additional fields for /deposit/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.YandexMoney
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > client_redirect_urlurlYesURL for client redirection after payment processhttp://site.com/return

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "YandexMoney",
    "note": "Account deposit 321",
    "system_fields": {
        "client_redirect_url": "http://site.com/return"
    },
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
                    

Answer is common GrataPay response with Redirect block to Yandex Money checkout page. After checkout client will be returned according the client_redirect_url.

Additional fields for /deduce/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.YandexMoney
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > wallet_numberstringYesTarget wallet number in the Yandex Money system to payout funds41001234567890

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "YandexMoney",
    "note": "Account payout 321",
    "system_fields": {
        "wallet_number": "41001234567890"
    },
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
                    

Answer is common GrataPay payout response.

WebMoney

Additional fields for /deposit/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.WebMoney
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > client_success_urlurlYesURL for client redirection after successful paymenthttp://site.com/success
system_fields > client_fail_urlurlYesURL for client redirection after unsuccessful paymenthttp://site.com/fail

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "RUB",
    "payment_system": "WebMoney",
    "note": "Account deposit 321",
    "system_fields": {
        "client_success_url": "http://site.com/success",
        "client_fail_url": "http://site.com/fail"
    },
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
                    

Answer is common GrataPay response with Redirect block to WebMoney checkout page. After checkout client will be returned to client_success_url or client_fail_url.

Additional fields for /deduce/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.WebMoney
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > wallet_numberstringYesTarget wallet number in the WebMoney system to payout fundsZ112233445566

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "USD",
    "payment_system": "WebMoney",
    "note": "Account payout 321",
    "system_fields": {
        "wallet_number": "Z112233445566"
    },
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
                    

Answer is common GrataPay payout response.

GrataPay Vouchers

Check voucher status request:

POST https://gratapay.com/api/voucher/check

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.Voucher
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > voucher_numberstringYesVoucher number.111122223333444455

Example of the request:

{
    "payment_system": "Voucher",
    "system_fields": {
        "voucher_number": "111122223333444455"
    }
}
                    

Response contains voucher face value and currency or error details. You get successful response only if voucher is ready to be redeemed.

Successful response:

FieldTypeMandatoryDescriptionExample
statusstringYesStatus of the request.ok
voucher_amountstringYesVoucher face value.1000.00
voucher_currencystringYesVoucher currency code.RUB

Example of the successful response:

{
    "status": "ok",
    "voucher_amount": "1000.00",
    "voucher_currency": "RUB"
}
                    

Failed response:

FieldTypeMandatoryDescriptionExample
statusstringYesStatus of the request.error
codestringYesError code.201
messagestringYesText description of an error.Mandatory field `voucher_number` is not present

Example of the failed response:

{
    "status": "error",
    "code": "201",
    "message": "Mandatory field `voucher_number` is not present"
}
                    

Redeem voucher request:

POST https://gratapay.com/api/voucher/redeem

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.Voucher
transaction_idstringNoTransaction number in the Merchant system.123
notestringNoTransaction description for the Merchant.Account deposit 321
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > voucher_numberstringYesVoucher number.111122223333444455
system_fields > voucher_passwordstringYesVoucher password.123456
urlobjectNoContainer for URL addresses transmitting.
url > callback_urlurlNoURL for transmitting notification of a payment to the Merchant system.http://site.com/callback

Example of the request:

{
    "payment_system": "Voucher",
    "transaction_id": "123",
    "note": "Account deposit 321",
    "system_fields": {
        "voucher_number": "111122223333444455",
        "voucher_password": "123456"
    },
    "url": {
        "callback_url": "http://site.com/callback"
    }
}
                    

Response is common GrataPay deposit response with ok status and without redirect block. Example of the successful response:

{
    "status": "ok",
    "id": "300",
    "transaction_id": "123",
    "type": "deposit",
    "amount_to_pay": "1000.00",
    "amount_merchant": "950.00",
    "amount_client": "1000.00",
    "currency": "RUB",
    "payment_system": "Voucher"
}
                    

Example of the failed response:

{
    "status": "error",
    "code": "201",
    "message": "Mandatory field `voucher_number` is not present"
}
                    

For testing purposes:

Use "payment_system": "TestVoucher"

Test vouchers:

360046146009394524, password 123456 - successful payment

360046146009399184 - unavailable for payout

360046146009400339 - a voucher of a blocked user

Any other voucher will return a 'Not found' error.

The vouchers may be tested with the 'check' method as well as 'redeemed'.

The value of the successful voucher is 100 RUB.

The example fee is 5%.

ecoPayz

Additional fields for /deposit/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.Ecopayz
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > client_first_namestringYesFirst name in ecoPayz systemIvan
system_fields > client_last_namestringYesLast name in ecoPayz systemIvanov
system_fields > client_date_birthdate(Y-m-d)YesDate of birth user (in ecoPayz system).1991-02-13

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "EUR",
    "payment_system": "Ecopayz",
    "note": "Account deposit 321",
    "system_fields": {
        "client_first_name": "Ivan",
        "client_last_name": "Ivanov",
        "client_date_birth": "1991-02-13"
    },
    "url": {
        "callback_url": "https://site.com/callback",
        "fail_url": "https://site.com/fail",
        "pending_url": "https://site.com/pending",
        "success_url": "https://site.com/success"
    }
}
                    

Additional fields for /deduce/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.Ecopayz
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > client_account_numberstringYesAccount number user in ecopayz system1234567890

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "EUR",
    "payment_system": "Ecopayz",
    "note": "Account payout 321",
    "system_fields": {
        "client_account_number": "1234567890"
    },
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
                    

Answer is common GrataPay payout response.

Privat24

Additional fields for /deposit/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.DepositUA
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > user_idstringYesClient ID in the Merchant system321
system_fields > emailstringYesClient e-mailtest@test.com
system_fields > return_urlstringYesURL for client redirection after payment processhttp://site.com/return

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "UAH",
    "payment_system": "DepositUA",
    "note": "Account deposit 321",
    "system_fields": {
        "user_id": "321",
        "email": "test@test.com",
        "return_url": "http://site.com/return"
    },
    "url": {
        "callback_url": "https://site.com/callback"
    }
}
                    

Answer is common GrataPay response with Redirect block to Privat24 checkout page. After checkout client will be returned according the redirect_url.

paysafecard

Additional fields for /deposit/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.Paysafecard
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > client_success_urlstringYesURL for client redirection after successful paymenthttps://site.com/success
system_fields > client_failure_urlstringYesURL for client redirection after unsuccessful paymenthttps://site.com/fail
system_fields > client_idstringYesClient ID in the Merchant system321

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "EUR",
    "payment_system": "Paysafecard",
    "note": "Account deposit 321",
    "system_fields": {
        "client_success_url": "https://site.com/success",
        "client_failure_url": "https://site.com/fail",
        "client_id": "321"
    },
    "url": {
        "callback_url": "https://site.com/callback",
    }
}
                    

Additional fields for /deduce/create request:

FieldTypeMandatoryDescriptionExample
payment_systemstringYesPayment system name.Paysafecard
system_fieldsobjectYesContainer for additional fields of payment system.
system_fields > client_idstringYesClient ID in the Merchant system321
system_fields > client_emailstringNoClient e-mailtest@test.com
system_fields > client_date_of_birthdate(Y-m-d)YesDate of birth user (in Paysafecard system).1991-02-13
system_fields > client_first_namestringYesFirst name in Paysafecard systemIvan
system_fields > client_last_namestringYesLast name in Paysafecard systemIvanov

The example of the request:

{
    "transaction_id": "123",
    "amount": "10.00",
    "currency": "EUR",
    "payment_system": "Paysafecard",
    "note": "Account payout 321",
    "system_fields": {
        "client_id":"321",
        "client_email": "test@test.com",
        "client_date_birth": "1991-02-13",
        "client_first_name": "Ivan",
        "client_last_name": "Ivanov"
    },
    "url": {
        "callback_url": "https://site.com/callback",
    }
}
                    

Answer is common GrataPay payout response.