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 nameDescriptionRequired/optional
amountРayment amountRequired
currencyCurrencyRequired
nameCardholder nameRequired
cryptogramEncrypted payment card parametersRequired
InvoiceIDThe 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 charactersRequired
invoiceIdAltThe order number generated by the merchant must be unique for each new order, from 6 to 15 digitsOptional
descriptionThis field contains information about the goods or services for which payment is madeRequired
AccountIdCustomer ID in the merchant's system or other additional parameter at the merchant's discretionOptional
emailClient's emailOptional
phoneClient's phoneOptional
postLinkLink for sending the authorization result to the storeoptional
failurePostLinkLink for sending an unsuccessful authorization result or error information to the store.Optional
cardSaveParameter saving the card, true - save the card, false - do not save, boolean typeRequired
dataAdditional field is shown in the report false when filledOptional

Payment processing

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

Method: POST

Request body:

{
    "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:

AmountPayment amount in the currency specified in the currency field
currencyPayment currency in ISO 4217 format (e.g. "KZT" for Kazakhstani tenge)
nameName of the payer
terminalIdIdentifier of the terminal or shop for payment processing
invoiceIdThe identifier of the invoice or purchase order associated with the payment
descriptionDescription of the payment
accountIdPayer’s account identifier
emailPayer’s email address
phonePayer’s telephone number (if applicable)
backLinkURL to redirect the user to after successful payment
FailureBacklinkURL to redirect the user to if the payment is not successfully completed
postlinkURL to which the payment provider will send feedback on the payment status after successful completion
failurePostlinkURL to which the payment provider will send feedback on the payment status if the payment fails
cardSaveFlag indicating whether the payer's card details should be stored for future payments (set to false in this case)
useBonusFlag indicating whether the payer's bonus funds should be used for payment (set to false in this case)
paymentTypeType of payment set to googlePay in this case)
googlePayAn object with information on the Google Pay payment
apiVersionMinorAPI Google Pay version (set to 0 in this case)
apiVersionGoogle Pay API version (set to 2 in this case)
paymentMethodDataAn object with information on the payment method used
descrptionDescription of the payment method (for example, “Visa •••• 1111”)
tokenizationDataAn object with information about tokenization of payment data
typeTokenization type (in this case it is set to PAYMENT_GATEWAY)
tokenToken value received from Google
typeType of payment method (in this case it is set to CARD)
infoAn object with information about payment card
cardNetworkPayment card network (for example, “VISA”)
cardDetailsThe 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 nameDescription
grant typeType of authorization , client_credentials type is used to make a payment
scopeResource
client idThe merchant identifier can be obtained in the personal account. It is issued during registration
client secretMerchant access key can be obtained in the personal account. It is issued during registration
terminal idThe 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 nameDescription
access tokenToken for the transaction
expires inToken expiry time
refresh tokenNot used for this type of authorization
scopeResource. The resource is used to make the payment
token typeType of authorization
Headers
    Authorization: Bearer dGVzdGNsaWVudDpzZWNyZXQ=

HTTP CODE 200

Response 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 nameDescription
100SuccessThe success of the request execution. Payment status can be viewed using statusName
101RejectUnsuccessful transaction
102Invoice 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
103Try again or contact supportThe request must be repeated or you should contact the Support Service
104Field terminal absent in tokenTerminalID parameter missing when a token is requested
106Error, incorrect terminalIDIncorrect TerminalID when a token is requested
107In progressTransaction is in progress, please ask for status later

statusName

Field nameDescription
REFUNDThe debited amount was refunded
AUTHAmount blocked
CANCELAmount unblocked
CHARGEAmount debited
CANCEL_OLDThe Issuer cancels the authorization when theCHARGE/CANCEL transaction expires.
FAILEDUnsuccessful transaction
3DError at the 3D verification stage
NEWThe 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)
REJECTUnsuccessful payment attempt

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