# Creating QR payment for external systems
## Test service settings
| | |
|--|--|
| Base url | https://testapi.onlinebank.kz/internal/qr-service/internal |
| Basic Auth Username | |
| Basic Auth Password | |
| Kafka topic for callbacks | ob-qr-service-status-events |
| Kafka bootstrap server | 10.0.67.22:31097, 10.0.67.21:31096, 10.0.67.20:31095 |
## QR generation
### Request `POST: /generate/code?channel=SMART_POS`
```json
{
"amount": "float64",
"terminal": "string",
"mpan": "string",
"pointOfSale": "string",
"invoiceId": "string",
"isSkipFin": "string"
}
```
| Name | Type | Mandatory | Description |
|--------------|---------|----------------|------------------------------------------------------|
| amount | Float64 | yes | Sum |
| terminal | String | yes | Terminal ID for making a payment, visa terminal id |
| mpan | String | no | Merchant's mVisa ID for making a payment (16-digit merchant PAN) |
| pointOfSale | String | yes | Store name, (in Latin, maximum length 25 characters) |
| invoiceId | String | yes | Payment ID must be unique in connection with the terminal |
| isSkipFin | String | no | Skip financial document generation in osuvox(Y - yes, N - no), if the value is Y, financial document generation must be on the integrated side, otherwise the payment will not be completed |
| channel(query) | String | no | QR generation channel, can be entered manually (example SMART_POS and HALYK_POS) |
### Response
```json
{
"qrcode": "string",
"homebankLink": "string",
"onlinebankLink": "string",
"status": "string"
}
```
| Name | Type | Mandatory | Description |
|----------------|--------|----------------|------------------------------------------------------|
| billNumber | int64 | yes | Unique qr code identifier|
| qrcode | String | yes | Generated QR string |
| homebankLink | String | yes | Deeplink to switch to payment via Homebank |
| onlinebankLink | String | yes | Deeplink to switch to payment via Homebank |
| status | String | yes | QR payment status (NEW, SCANNED, BLOCKED, AUTH, PAID, REJECTED)|
## Sample
### Request
```
curl --request POST \
--url https://testapi.onlinebank.kz/internal/qr-service/internal/generate/code \
--header 'Authorization: Basic RVBBWTpFUEFZMTExMQ==' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{ \
"amount": "250", \
"terminal": "92059431", \
"mpan": "4598958946319737", \
"pointOfSale": "THE KITCHEN", \
"invoiceId": "1000001", \
"isSkipFin": "Y", \
}'
```
### Response
```json
{
"billNumber": 2532191,
"qrcode": "00020101021226730008HSBKKZKX0120KZ6760101310000507320208710003430310ONLINEBANK0407205681902164598957668810444520459125303398540413245802KZ5906АЛМАТЫ6006АЛМАТЫ62110107253219163042750",
"homebankLink": "-",
"onlinebankLink": "-",
"status": "NEW"
}
```
<br>
<br>
<br>
## Get QR status
### Request `GET: /status/{terminal}/{invoiceId}`
| Name | Type | Mandatory | Description |
|--------------|---------|----------------|------------------------------------------------------|
| terminal | String | yes | Terminal ID for making a payment |
| invoiceId | String | yes | Payment ID must be unique in connection with the terminal |
<br>
### You can use `billNumber` Request `GET: /status/{billNumber}`
| Name | Type | Mandatory | Description |
|--------------|---------|----------------|------------------------------------------------------|
| billNumber | int64 | yes | Unique qr code identifier |
### Response
```json
{
"qrcode": "string",
"status": "string",
"reference": "string",
"cardId": "string",
"cardType": "string",
"trType": "string",
"secure3D": "boolean",
"openwayId": "string",
"issuer": "string",
"issuerBankCountry": "string",
"fee": "float64",
"amount": "float64",
"bonusAmount": "float64",
"currency": "string",
"channel": "string",
"paymentChannel": "string",
"errDescription": "string",
"retCode": "string",
"cardMask": "string",
"terminal": "string",
"invoiceId": "string",
"createdDate": "2021-07-09T11:14:40",
"paymentDate": "2021-07-09T11:14:58",
"details": ObjectArray([{"label": string, "value": string}]),
"isSkipFin": "string"
}
```
| Name | Type | Mandatory | Description |
| ----------------- | ------------------------------------------------- | -------------- | ----------------------------------------------------------- |
| qrcode | String | yes | Generated QR string |
| status | String | yes | Payment status via QR (NEW, SCANNED, BLOCKED, AUTH, PAID, REJECTED) | |
| reference | String | yes | Transaction reference in Osuwox |
| cardId | String | yes | Cards ID in Osuwox |
| cardType | String | yes | Card type(Visa/Mastercard) |
| trType | String | yes | Transaction type (RETAIL, LOCALQR) |
| secure3D | Boolean | yes | Indicator that a transaction is 3D or not |
| openwayId | String | yes | Client ID in Openway |
| issuer | String | yes | Issuing bank, default HSBKKZKX |
| issuerBankCountry | String | yes | Issuing bank country, default KZ |
| fee | Float64 | yes | Commission |
| amount | Float64 | yes | Payment amount including commission and bonuses |
| bonusAmount | Float64 | yes | Amount paid in bonuses |
| currency | string | yes | Сurrency code, default 398 |
| channel | string | yes | QR generation channel |
| paymentChannel | string | yes | Payment channel |
| errDescription | string | no | Payment Error details |
| retCode | string | no | Response code from the card system |
| cardMask | string | no | Card mask |
| terminal | String | yes | Terminal ID for making a payment |
| invoiceId | String | yes | Payment ID must be unique in conjunction with terminal |
| createdDate | DateTime | yes | Date and time of QR code creation |
| paymentDate | DateTime | no | Date and time of payment |
| details | ObjectArray([{"label": string, "value": string}]) | no | Transaction details to display on invoice |
| isSkipFin | String | no | Skip financial document generation in osuvox (Y - yes, N - no) |
## Sample
### Request
```
curl --request GET \
--url https://testapi.onlinebank.kz/internal/qr-service/internal/status/92059431/1000001 \
--header 'Authorization: Basic RVBBWTpFUEFZMTExMQ==' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```
### Response
```json
{
"qrcode": "00020101021226730008HSBKKZKX0120KZ6760101310000507320208710003430310ONLINEBANK0407205681902164598957668810444520459125303398540413245802KZ5906АЛМАТЫ6006АЛМАТЫ62110107253219163042750",
"status": "PAID",
"reference": "ONB111111223301",
"cardId": "50902325",
"cardType": "Visa",
"trType": "LOCALQR",
"secure3D": false,
"openwayId": "19963913",
"issuer": "HSBKKZKX",
"issuerBankCountry": "KZ",
"fee": "0",
"amount": "250",
"bonusAmount": "0",
"currency": "398",
"channel": "EPAY",
"paymentChannel": "EPAY",
"errDescription": null,
"retCode": "0",
"cardMask": "440563XXXXXX3134",
"terminal": "92059431",
"invoiceId": "1000001",
"createdDate": "2021-07-09T11:14:40",
"paymentDate": "2021-07-09T11:14:58",
"details": [
{
"label": "Loan terms"",
"value": "2 month"
},
{
"label": "Effective rate",
"value": "5%"
}
],
"isSkipFin": "Y"
}
```
<br>
<br>
<br>
## Getting QR status via Kafka topic
### Topic `ob-qr-service-status-events`
### QrCode
| Name | Type | Mandatory | Description |
|-------------------|---------|----------------|------------------------------------------------------|
| billId | String | yes | QR ID |
| qrcode | String | yes | Generated QR string |
| status | String | yes | QR payment status (NEW, SCANNED, BLOCKED, AUTH, PAID, REJECTED) |
| reference | String | no | Transaction reference in Osuwox |
| cardId | String | no | Card ID in Osuwox |
| cardType | String | yes | Card type(Visa/Mastercard) |
| trType | String | yes | Transaction type(RETAIL, LOCALQR) |
| secure3D | Boolean | no |Indicator that a transaction is 3D or not |
| openwayId | String | no | Cliend ID in Openway |
| issuer | String | no |Issuing bank, default HSBKKZKX |
| issuerBankCountry | String | no | Issuing bank country, default KZ |
| fee | Float64 | no | Commission |
| amount | Float64 | yes | Payment amount including commission and bonuses |
| bonusAmount | Float64 | yes | Amount paid in bonuses |
| currency | string | no | Currency code, default 398 |
| channel | string | yes | QR generation channel |
| paymentChannel | string | yes | Payment channel |
| errDescription | string | no | Payment Error Details |
| retCode | string | no | Response code from the card system |
| cardMask | string | no | Card mask |
| terminal | String | yes | Terminal ID for making a payment |
| invoiceId | String | yes | Payment ID must be unique in connection with the terminal |
| createdDate | DateTime | yes |Date and time of QR code creation |
| paymentDate | DateTime | no | Date and time of payment |
| details | ObjectArray([{"label": string, "value": string}]) | no | Transaction details to display on invoice |
| isSkipFin | String | no | Skip financial document generation in osuvox (Y - yes, N - no) |
### Response
```json
{
"billId": "int64",
"qrcode": "string",
"status": "string",
"reference": "string",
"cardId": "string",
"cardType": "string",
"trType": "string",
"secure3D": "boolean",
"openwayId": "string",
"issuer": "string",
"issuerBankCountry": "string",
"fee": "float64",
"amount": "float64",
"bonusAmount": "float64",
"currency": "string",
"channel": "string",
"paymentChannel": "string",
"errDescription": "string",
"retCode": "string",
"cardMask": "string",
"terminal": "string",
"invoiceId": "string",
"createdDate": "datetime",
"paymentDate": "datetime",
"details": ObjectArray([{"label": string, "value": string}]),
"isSkipFin": "string"
}
```
## Sample
### NEW
```json
{
"billId": 2532191,
"qrcode": "00020101021226730008HSBKKZKX0120KZ6760101310000507320208710003430310ONLINEBANK0407205681902164598957668810444520459125303398540413245802KZ5906АЛМАТЫ6006АЛМАТЫ62110107253219163042750",
"status": "NEW",
"reference": null,
"cardId": null,
"cardType": null,
"trType": "LOCALQR",
"secure3D": false,
"openwayId": null,
"issuer": null,
"issuerBankCountry": null,
"fee": null,
"amount": null,
"bonusAmount": null,
"currency": null,
"channel": "EPAY",
"paymentChannel": "EPAY",
"errDescription": null,
"retCode": "0",
"cardMask": "440563XXXXXX3134",
"terminal": "92059431",
"invoiceId": "1000001",
"createdDate": "2021-07-09T11:14:40",
"paymentDate": "2021-07-09T11:14:58",
"details": [
{
"label": "Loan terms"",
"value": "2 month"
},
{
"label": "Effective rate",
"value": "5%"
}
],
"isSkipFin": "Y"
}
```
### SCANNED
```json
{
"billId": 2532191,
"qrcode": "00020101021226730008HSBKKZKX0120KZ6760101310000507320208710003430310ONLINEBANK0407205681902164598957668810444520459125303398540413245802KZ5906АЛМАТЫ6006АЛМАТЫ62110107253219163042750",
"status": "SCANNED",
"reference": null,
"cardId": null,
"cardType": null,
"trType": "LOCALQR",
"secure3D": false,
"openwayId": null,
"issuer": null,
"issuerBankCountry": null,
"fee": null,
"amount": null,
"bonusAmount": null,
"currency": null,
"paymentChannel": "EPAY",
"errDescription": null,
"retCode": null,
"cardMask": null,
"terminal": "92059431",
"invoiceId": "1000001",
"createdDate": "2021-07-09T11:14:40",
"paymentDate": "2021-07-09T11:14:58",
"details": [
{
"label": "Loan terms"",
"value": "2 month"
},
{
"label": "Effective rate",
"value": "5%"
}
],
"isSkipFin": "Y"
}
```
### BLOCKED
```json
{
"billId": 2532191,
"qrcode": "00020101021226730008HSBKKZKX0120KZ6760101310000507320208710003430310ONLINEBANK0407205681902164598957668810444520459125303398540413245802KZ5906АЛМАТЫ6006АЛМАТЫ62110107253219163042750",
"status": "BLOCKED",
"reference": null,
"cardId": null,
"cardType": null,
"trType": "LOCALQR",
"secure3D": false,
"openwayId": null,
"issuer": null,
"issuerBankCountry": null,
"fee": null,
"amount": null,
"bonusAmount": null,
"currency": null,
"paymentChannel": "EPAY",
"errDescription": null,
"retCode": "0",
"cardMask": "440563XXXXXX3134",
"terminal": "92059431",
"invoiceId": "1000001",
"createdDate": "2021-07-09T11:14:40",
"paymentDate": "2021-07-09T11:14:58",
"details": [
{
"label": "Loan terms"",
"value": "2 month"
},
{
"label": "Effective rate",
"value": "5%"
}
],
"isSkipFin": "Y"
}
```
### REJECTED
```json
{
"billId": 2532191,
"qrcode": "00020101021226730008HSBKKZKX0120KZ6760101310000507320208710003430310ONLINEBANK0407205681902164598957668810444520459125303398540413245802KZ5906АЛМАТЫ6006АЛМАТЫ62110107253219163042750",
"status": "REJECTED",
"reference": "ONB111111223301",
"cardId": "50902325",
"cardType": "Visa",
"trType": "LOCALQR",
"secure3D": false,
"openwayId": "19963913",
"issuer": "HSBKKZKX",
"issuerBankCountry": "KZ",
"fee": "0",
"amount": "250",
"bonusAmount": "0",
"currency": "398",
"channel": "EPAY",
"paymentChannel": "EPAY",
"errDescription": "Недостаточно средств на карте",
"retCode": "0",
"cardMask": "440563XXXXXX3134",
"terminal": "92059431",
"invoiceId": "1000001",
"createdDate": "2021-07-09T11:14:40",
"paymentDate": "2021-07-09T11:14:58",
"details": [
{
"label": "Loan terms"",
"value": "2 month"
},
{
"label": "Effective rate",
"value": "5%"
}
],
"isSkipFin": "Y"
}
```
### PAID
```json
{
"billId": 2532191,
"qrcode": "00020101021226730008HSBKKZKX0120KZ6760101310000507320208710003430310ONLINEBANK0407205681902164598957668810444520459125303398540413245802KZ5906АЛМАТЫ6006АЛМАТЫ62110107253219163042750",
"status": "PAID",
"reference": "ONB111111223301",
"cardId": "50902325",
"cardType": "Visa",
"trType": "LOCALQR",
"secure3D": false,
"openwayId": "19963913",
"issuer": "HSBKKZKX",
"issuerBankCountry": "KZ",
"fee": "0",
"amount": "250",
"bonusAmount": "0",
"currency": "398",
"channel": "EPAY",
"paymentChannel": "EPAY",
"errDescription": null,
"retCode": "0",
"cardMask": "440563XXXXXX3134",
"terminal": "92059431",
"invoiceId": "1000001",
"createdDate": "2021-07-09T11:14:40",
"paymentDate": "2021-07-09T11:14:58",
"details": [
{
"label": "Loan terms"",
"value": "2 month"
},
{
"label": "Effective rate",
"value": "5%"
}
],
"isSkipFin": "Y"
}
```
## QR status change policy
```
NEW -> SCANNED
SCANNED -> BLOCKED
BLOCKED -> AUTH
AUTH -> PAID
BLOCKED -> PAID
SCANNED -> REJECTED
BLOCKED -> REJECTED
AUTH -> REJECTED
```
<br>
<br>
<br>
## Changing QR status
`POST https://testapi.onlinebank.kz/internal/qr-service/internal/status/6076034`
Sample:
```
{
"billId": "6076034",
"status": "BLOCKED",
"reference": "HBLQR118907055931675",
"cardId": "366117530",
"cardType": "VISA",
"openwayId": "9477923",
"issuer": null,
"issuerBankCountry": null,
"fee": "0.00",
"amount": null,
"bonusAmount": null,
"currency": null,
"retCode": null,
"retMsg": null,
"maskedCardNumber": "440563XXXXXX3134"
}
```
| Name | Type | Mandatory | Description |
|-------------------|---------|----------------|------------------------------------------------------|
| billId | String | yes | QR ID |
| status | String | yes | QR payment status (NEW, SCANNED, BLOCKED, PAID, REJECTED) |
| reference | String | no | Transaction reference in Osuwox |
| cardId | String | no | Card ID in Osuwox |
| cardType | String | no | Card type (Visa/Mastercard) |
| openwayId | String | no | Cliend ID Openway |
| issuer | String | no | Issuing bank, default HSBKKZKX |
| issuerBankCountry | String | no | Issuing bank country, default KZ |
| fee | Float64 | no | Commission |
| amount | Float64 | yes | Payment amount including commission and bonuses |
| bonusAmount | Float64 | yes | Amount paid in bonuses |
| currency | string | no | Currency code, default 398 |
| retCode | string | no | Response code from the card system |
| maskedCardNumber | string | no | Card mask |
| retMsg | String | no | Message from the card system |
| details | ObjectArray([{"label": string, "value": string}]) | no | Transaction details to display on invoice |
```
{
"billNumber": 6076034,
"qrcode": "00020101021228730008HSBKKZKX0120KZ5460101310000689110208610504430310ONLINEBANK04075436130021645989550869266695204799353033985402105802KZ5902236006ALMATY6211010760760346304657A",
"homebankLink": null,
"onlinebankLink": null,
"status": "BLOCKED"
}
```
### This method is used in cases
#### Refusal to accept payment via QR
If the waiting time for payment in an application or service ends, you must send a request to Refuse Payment Acceptance so that if the cashier refuses, the buyer’s payment will not go through
Sample:
```
{
"billId": "6076034",
"status": "REJECTED"
}
```
#### Service for changing the status and filling out information on a invoice
Method for updating the QR status and details of the completed transaction for other payment methods other than cards - installments, credit.
Sample:
```
{
"billId": "6076034",
"status": "REJECTED",
"details": [
{
"label": "Credit amount",
"value": "5 000 000 tenger"
},
{
"label": "Term",
"value": "2 years"
},
{
"label": "Payment date",
"value": "12"
}
]
}
```
## Refund QR payment
### Request `POST: /generate/refund?channel=SMART_POS`
```json
{
"amount": "float64",
"billId": "string"
}
```
| Name | Type | Mandatory | Description |
|--------------|---------|----------------|------------------------------------------------------|
| amount | Float64 | yes | Sum |
| billId | int64 | no | Payment ID. You need to send either billId or rrn |
| rrn | String | no | Payment SRN. You need to send either billId or rrn |
| channel(query) | String | no | QR generation channel, can be entered manually (example SMART_POS and HALYK_POS) |
### Response
```json
{
"billNumber": "string",
"qrcode": "string",
"homebankLink": "string",
"onlinebankLink": "string",
"status": "string"
}
```
##### ! It is important to take into account that the return occurs asynchronously, so the status of the return can be tracked by messages in Kafka, or through an http request for “Getting QR status” using billNumber
| Name | Type | Mandatory | Description |
|----------------|--------|----------------|------------------------------------------------------|
| billNumber | int64 | yes | QR ID |
| qrcode | String | yes | Generated QR string |
| homebankLink | String | yes | Deeplink to switch to payment via Homebank |
| onlinebankLink | String | yes | Deeplink to switch to payment via Homebank |
| status | String | yes | Payment status via QR (NEW, PAID, REJECTED) |
## Sample
### Request
```
curl --request POST \
--url https://testapi.onlinebank.kz/internal/qr-service/internal/generate/refund \
--header 'Authorization: Basic RVBBWTpFUEFZMTExMQ==' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data '{ \
"amount": "250", \
"rrn": "OBLQR123502391607" \
}'
```
### Response
```json
{
"billNumber": 2532191,
"qrcode": "00020101021226730008HSBKKZKX0120KZ6760101310000507320208710003430310ONLINEBANK0407205681902164598957668810444520459125303398540413245802KZ5906АЛМАТЫ6006АЛМАТЫ62110107253219163042750",
"homebankLink": "-",
"onlinebankLink": "-",
"status": "NEW"
}
```
<br>
<br>
<br>
Sign in with Wallet
Connect another wallet