Documentation on how to send a Google Pay payment request with encrypted data (PAYMENT_GATEWAY):

Obtaining a token to make a payment (an original token must be obtained and used for each transaction)

TEST URL POST https://testoauth.homebank.kz/epay2/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token

Request:

grant_type: "client_credentials" scope: "webapi usermanagement email_send verification statement statistics payment" client_id: "ClientID" client_secret: "clientSecret" InvoiceID: "Order number" amount: 100 currency: "KZT" terminal: "67e34d63-102f-4bd1-898e-370781d0074d"

Response:

{
"access_token":"DCEB8O_ZM5U7SO_T_U5EJQ",
"expires_in": 7200,
"scope":"webapi usermanagement email_send verification statement statistics payment",
"token_type":"Bearer"
}

Input parameters:

Field name	Description	Required/optional
amount	payment amount	required
currency	currency	required
name	cardholder name	required
cryptogram	encrypted payment card parameters	required
InvoiceID	The order number generated by the merchant must be unique for each new order, from 6 to 15 digits. If your order number contains more than 6 characters, then additionally the uniqueness should be observed for the last 6 characters	required
invoiceIdAlt	The order number generated by the merchant must be unique for each new order, from 6 to 15 digits	optional
description	This field contains information about the goods or services for which payment is made	required
AccountId	Customer ID in the merchant's system or other additional parameter at the merchant's discretion	optional
email	client's email	optional
phone	client's phone	optional
postLink	Link for sending the authorization result to the store.	optional
failurePostLink	Link for sending an unsuccessful authorization result or error information to the store.	optional
cardSave	parameter saving the card, true - save the card, false - do not save, boolean type	required
data	additional field is shown in the report false when filled	optional

Payment processing

URL: https://epay-api.homebank.kz/payment/cryptopay

Method: POST

Request body:

json

{
    "amount": 10,
    "currency": "KZT",
    "name": "Test test",
    "terminalId": "b861ab50-8387-46c3-be6e-f439d4492c3c",
    "invoiceId": "80000148",
    "description": "Оплата",
    "accountId": "",
    "email": "nemesis_311@gmail.com",
    "phone": "+77078071180",
    "backLink": "http://example/backLink",
    "failureBackLink": "http://example/failureBackLink",
    "postLink": "http://example/postLink",
    "failurePostLink": "http://example/failurePostLink",
    "cardSave": false,
    "useBonus": false,
    "paymentType": "googlePay",
    "googlePay": {
        "apiVersionMinor": 0,
        "apiVersion": 2,
        "paymentMethodData": {
            "description": "Visa •••• 1111",
            "tokenizationData": {
                "type": "PAYMENT_GATEWAY",
               "token": "{\"signature\":\"MEQCIG0Pt0VSb8/W00fzbPLtO5z3DYNrG1IrU94YI0U3VZw3AiAekJRW2Bcq1+hPbcbBniw9vRNSH2w3+qFX5EcQwkJo1w\\u003d\\u003d\",\"intermediateSigningKey\":{\"signedKey\":\"{\\\"keyValue\\\":\\\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEwIIrniC3/DfJjejVaHVsBGZLO9LW9ggLXWaoEVnpZuFgLSH4qEanNlHvZkr6A04aVq/7HgYaxLkotk6ZKSr3qQ\\\\u003d\\\\u003d\\\",\\\"keyExpiration\\\":\\\"1695271732552\\\"}\",\"signatures\":[\"MEQCIFurLZqmGGY9jZ+ZL+8iHtdxFRY3VMdKwcxrO0tunvuoAiBywEKS7Q2qwh4SmjY99tNaVYrfr8/Cygd8c/0XoP2K4Q\\u003d\\u003d\"]},\"protocolVersion\":\"ECv2\",\"signedMessage\":\"{\\\"encryptedMessage\\\":\\\"5XrIV3etzcSBdH8fgO+eCIxH3jWrGSUPPVXci3s22nD5Ab+9EtihPz/Zc3ODVwINNWOtkqfJxiu3UUaz1LbICfM1I2rhqyANCc35fK+Fd/JZNQv7eFNVVNxVdt2eBiQxPod+2K5v4jCJJkGevdbqQUW1OncL1QXpt8e/dNj1o7CTGCxxV6iN+8DjAo4xyvZJqKsjA3PzzKDhfNdM6zohKcgNqtPP30uI8EGK1PdGQDFCuPYFRYpKCVOx3qibRuI5x46pHV86GLUmMDbETSNOIYnwpOu0RVcMLdb74xQ9awoiXILSSM/IGhQUJnxeUbckzYsqwbZ88Ks6kmbHmCs3oHcgL4Lblt7hE07vW1Y1VJQ05/oTcT98R9WWzKeOTSvA8ru7o3oUxdwww1QIb9VytOz2IbGiI+ZepGehImTxsOUJkG3QwoFevDVDV67cf6KfTxUd97OarcE6Nk3crwO+GIASJw/U5lycj74HRd/h25Fme8TFf6BMmcOHUezy6Tx+iHO5j3P0QMDT0a4bVb8wuUPa0CE1DQH75E+EVSUb2tmRURkqDrDKCN6GP2VCvxqsSzV26zZbl8Xv\\\",\\\"ephemeralPublicKey\\\":\\\"BOmDg7vgShCeyoYT5EgzyV8NGdh3AbDe1yHmf2WRv+tKYlfjd8bhGJnc1hkLVjY80VKFBxUw2eDhqd1bGzXoxQ0\\\\u003d\\\",\\\"tag\\\":\\\"I9P/hCUvJTg+cVO7H+snaOAtACB9J0gySh/LEih0yH8\\\\u003d\\\"}\"}"
               },
            "type": "CARD",
            "info": {
                "cardNetwork": "VISA",
                "cardDetails": "1111"
            }
        }
    }
}

Enquiry fields:

amount	Payment amount in the currency specified in the currency field
currency	Payment currency in ISO 4217 format (e.g. "KZT" for Kazakhstani tenge)
name	Name of the payer
terminalId	Identifier of the terminal or shop for payment processing
invoiceId	The identifier of the invoice or purchase order associated with the payment.
description	Description of the payment.
accountId	Payer’s account identifier.
email	Payer’s email address.
phone	Payer’s telephone number (if applicable).
backLink	URL to redirect the user to after successful payment.P
FailureBacklink	URL to redirect the user to if the payment is not successfully completed.
postlink	URL to which the payment provider will send feedback on the payment status after successful completion.
failurePostlink	URL to which the payment provider will send feedback on the payment status if the payment fails.
cardSave	Flag indicating whether the payer's card details should be stored for future payments (set to false in this case).
useBonus	Flag indicating whether the payer's bonus funds should be used for payment (set to false in this case).
paymentType	Type of payment set to googlePay in this case).
googlePay	An object with information on the Google Pay payment.
apiVersionMinor	API Google Pay version (set to 0 in this case).
apiVersion	Google Pay API version (set to 2 in this case).
paymentMethodData	An object with information on the payment method used.
descrption	Description of the payment method (for example, “Visa •••• 1111”).
tokenizationData	An object with information about tokenization of payment data.
type	Tokenization type (in this case it is set to PAYMENT_GATEWAY).
token	Token value received from Google
type	Type of payment method (in this case it is set to CARD)
info	An object with information about payment card
cardNetwork	Payment card network (for example, “VISA”).
cardDetails	The last four digits of the payment card number (for example, “1111”)

After submitting a request to the payment API, you expect to receive a response with payment status information. Process the response accordingly in your system using the Payment Status Check service

TEST URL: GET https://testepay.homebank.kz/api/check-status/payment/transaction/:invoiceid

PROD URL: GET https://epay-api.homebank.kz/check-status/payment/transaction/:invoiceid

Authorisation required: client credentials

Request Receiving token

TEST URL POST https://testoauth.homebank.kz/epay2/oauth2/token
PROD URL POST https://epay-oauth.homebank.kz/oauth2/token

Body: form-data

grant_type:"client_credentials"
scope:"webapi usermanagement email_send verification statement statistics payment"
client_id:"test"
client_secret:"yF587AV9Ms94qN2QShFzVR3vFnWkhjbAK3sG"
terminal:"67e34d63-102f-4bd1-898e-370781d0074d"

Field name	Description
grant type	type of authorization , client_credentials type is used to make a payment
scope	resource
client id	The merchant identifier can be obtained in the personal account. It is issued during registration
client secret	Merchant access key can be obtained in the personal account. It is issued during registration
terminal id	The identifier of the point of sale can be obtained in the personal account. It is issued during registration

Response:

{
"access_token":"DCEB8O_ZM5U7SO_T_U5EJQ",
"expires_in": 7200,
"scope":"webapi usermanagement email_send verification statement statistics payment",
"token_type":"Bearer"
}

Field name	Description
access token	Token for the transaction
expires in	Token expiry time
refresh token	Not used for this type of authorization
scope	Resource. The resource is used to make the payment
token type	Type of authorization

Headers
    Authorization: Bearer dGVzdGNsaWVudDpzZWNyZXQ=

HTTP CODE 200

Responce Body JSON:

{
    "resultCode": "100",
    "resultMessage": "SUCCESS",
    "transaction": {
        "id": "af2089fe-43b1-47eb-a61f-c78dd196e18d",
        "createdDate": "2022-11-15T03:52:17.289853+06:00",
        "invoiceID": "205218074",
        "amount": 12.22,
        "amountBonus": 0,
        "payoutAmount": 10,
        "orgAmount":22.22,
        "approvalCode": "170243",
        "data": "{\"custom_id\":\"2023.03.10-15:03:58\",\"email\":\"epay@halykbank.kz\",\"deal_number\":\"1111111\",\"offer_code\":\"1111111\",\"sum\":33900}",
        "currency": "KZT",
        "terminal": "98120001",
        "terminalID":"67e34d63-102f-4bd1-898e-370781d0074d",
        "accountID": "",
        "description": "order 205218074",
        "language": "RU",
        "cardMask": "400303...9821",
        "cardType": "VISA",
        "issuer": "Казкоммерцбанк",
        "reference": "231951411351",
        "reason": "Successfully",
        "reasonCode": "00",
        "intReference": "67140D7DE97139A7",
        "secure": false,
        "statusID": "5bbb7dd5-4691-41ee-a6a5-755a3d23a218",
        "statusName": "REFUND",
        "name": "ARMAN ALI",
        "email": "epay@halykbank.kz",
        "phone": "",
        "cardID": "e8a09f98-04b4-71a6-e053-1d1a000aa0d2",
        "xlsRRN": "",
        "ip": "46.148.239.182",
        "ipCountry": "Kazakhstan",
        "ipCity": "",
        "ipRegion": "",
        "ipDistrict": "",
        "ipLatitude": 55.7386,
        "ipLongitude": 37.6068
    }
}

Error:

{
    "resultCode": "101",
    "resultMessage": "reject",
    "transaction": null
}

resultcode

Field name	Description
100	success	The success of the request execution. Payment status can be viewed using statusName
101	reject	unsuccessful transaction
102	invoice not found, try again later or check transaction type (payment/p2p)	Your transaction may have been made using a P2P service if the invoiceId number is not found in the system.
103	try again or contact support	The request must be repeated or you should contact the Support Service
104	field terminal absent in token	TerminalID parameter missing when a token is requested
106	error, incorrect terminalID	incorrect TerminalID when a token is requested
107	IN PROGRESS	transaction is in progress, please ask for status later

status name

Field name	Description
REFUND	the debited amount was refunded
AUTH	amount blocked
CANCEL	amount unblocked
CHARGE	amount debited
CANCEL_OLD	The Issuer cancels the authorization when theCHARGE/CANCEL transaction expires.
FAILED	unsuccessful transaction
3D	error at the 3D verification stage
NEW	The transaction has been created but is still in an intermediate state (if you received this status when manually requesting the transaction status, please note that it may change)
REJECT	unsuccessful payment attempt

The probable reasonCode that will be returned by the system is available at https://epayment.kz/docs/kody-oshibok