Bank Card Tokenization

Tokenization is a mechanism that allows the Partner to request card details from the user once and store them in the secure OCTO environment, exchanging them for a unique token. This token can be stored on the Partner's servers and linked to the customer's account. Subsequent purchases are initiated by sending the token to OCTO, only requiring the CVV2/CVC2 code.

Important!

The notification of the final status of card tokenization is sent by the OCTO PS (callback) via a POST request to the address specified by the Partner in the bind_notify_url parameter in the bind_card method.

Blocking a Card Token.

To block an issued bank card token, the Partner's server must send a request to /block_card_token.

Humo/Uzcard Tokenization Algorithm

1. The client initiates card tokenization.
2. The Partner calls the card binding method bind_card.
3. Our BE sends a request to Humo/Uzcard to verify the card details.
4. Humo/Uzcard confirms the details.
5. Our BE confirms to the Partner.
6. The Partner calls the OTP validity method verificationInfo.
7. Our BE confirms the Partner's request.
8. Humo/Uzcard sends an OTP code to the client.
9. The client provides the OTP code to the Partner.
10. The Partner calls the code verification method /bind_card/check_sms.
11. Our BE sends the code to Humo/Uzcard.
12. Humo/Uzcard confirms the transaction.
13. Our BE notifies the Partner.
14. Our BE sends a refund request to Humo/Uzcard.
15. Humo/Uzcard confirms the refund.
16. Our BE sends a callback about the status to the Partner.
17. Our BE sends the token to the Partner.
18. The Partner sends a receipt confirmation.*

Note

If the Partner does not send a receipt confirmation, our BE will resend requests up to three times. If no response is received, the token will be canceled.

*BE - Back End

---

Tokenization of Humo/Uzcard

Visa/MC Tokenization Algorithm

1. The client initiates card tokenization.
2. The partner calls the card binding method bind_card.
3. Our backend (BE) sends a request to Visa/MC to verify the card details and perform a test transaction.
4. Visa/MC confirms the details and provides a link to the OTP entry form.
5. Visa/MC sends an OTP code to the client.
6. The client submits the OTP code.
7. Visa/MC confirms the transaction.
8. Our BE notifies the partner.
9. Our BE sends a refund request to Visa/MC.
10. Visa/MC confirms the refund.
11. Our BE sends a callback with the status to the partner.
12. Our BE sends the token to the partner.
13. The partner sends a confirmation of receipt.

Note

If the partner does not confirm receipt, our BE will resend the request up to three times. If no response is received, the token will be canceled.

*BE - Back End

Tokenization of Visa/MC

Methods

/bind_card

• URL: https://secure.octo.uz/bind_card
• Method: POST
• Content-type: application/json

Request Example

{
  "octo_shop_id": 10000,
  "octo_secret": "merchant_secret",
  "shop_transaction_id": "randomUUID",
  "pan": "9860240101226506",
  "exp": "2805",
  "phone": "998901234567",
  "cardHolderName": "Card Holder Name",
  "cvc2": "",
  "method": "humo",
  "return_url": "https://notify-url.uz",
  "notify_url": "https://notify-url.uz",
  "bind_notify_url": "https://notify-url.uz"
}

Request Parameters

Parameter	Type	Mandatory	Description
octo_shop_id	Integer	Yes	The shop's unique ID (available in the shop's Personal Account).
octo_secret	String	Yes	The shop's personal secret key, generated in the shop's Personal Account.
shop_transaction_id	String	Yes	The unique transaction ID on the shop's side.
pan	String	Yes	The Client's card number used for the transaction.
exp	String	Yes	Card validity period in YYMM format.
phone	String	Yes	The Client's phone number linked to the card.
cardHolderName	String	Yes	Cardholder's name as indicated on the card.
cvc2	String	No	Card's security code (CVV2), used for verification.
method	String	Yes	Payment method: humo, uzcard, or bank_card.
return_url	String	Yes	URL to redirect the user after completing the payment.
notify_url	String	No	URL for payment status notifications.
bind_notify_url	String	No	URL for notifications about card linking success.

Successful Response Example

{
  "error": 0,
  "data": {
    "shop_transaction_id": "123431321323334132333",
    "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
    "status": "created",
    "octo_pay_url": "https://pay-dev.octo.uz/uzcard/sms/06000144-db56-47b6-9eba-021ad4ff246b",
    "refunded_sum": 0,
    "total_sum": 1000
  }
}

Response Parameters

Parameter	Type	Mandatory	Description
error	Integer	Yes	Error code. 0 indicates a successful operation.
data	Object	Yes	Contains transaction details.
shop_transaction_id	String	Yes	Unique transaction ID on the shop's side.
octo_payment_UUID	String	Yes	Unique payment ID created by the Octo system.
status	String	Yes	Payment status (e.g., created, succeeded).
octo_pay_url	String	Yes	Link to the payment page.
refunded_sum	Decimal	Yes	Refund amount. Default is 0 if no refund made.
total_sum	Decimal	Yes	Total transaction amount.

---

Unsuccessful Response Example

{
  "error": 20,
  "errMessage": "Active or pending token already exists",
  "data": null
}

Error Response Parameters

Parameter	Type	Mandatory	Description
error	Integer	Yes	Error code.
errMessage	String	Yes	Error message.
data	Object	No	Additional error details (if available).

---

---

verificationInfo

• URL: https://secure.octo.uz/verificationInfo/
• Method: POST
• Content-type: application/json

Note

Only the octo_payment_UUID is sent.

Successful response example

{
    "error": 0,
    "errMessage": "",
    "data": {
        "verifyId": 819,
        "phone": "+998** *****33",
        "secondsLeft": 221
    }
}

Successful response parameters

Parameter	Type	Required	Description
error	Integer	Yes	Error code (0 means no errors).
errMessage	String	No	Error message, empty if no error.
data	Object	Yes	Object with verification process details.
verifyId	Integer	Yes	Unique ID of the verification process.
phone	String	Yes	Phone number associated with verification (partially hidden).
secondsLeft	Integer	Yes	Remaining time (in seconds) until the verification period expires.

---

Unsuccessful response example

{
    "error": 0,
    "errMessage": "",
    "data": {
        "verifyId": 819,
        "phone": "+998** *****33",
        "secondsLeft": 0
    }
}

Unsuccessful response parameters

Parameter	Type	Required	Description
error	Integer	Yes	Error code (0 means no errors, but secondsLeft=0 indicates that the verification period has expired or is inactive).
errMessage	String	No	Error message, empty if no error.
data	Object	Yes	Object with verification process details.
verifyId	Integer	Yes	Unique ID of the verification process.
phone	String	Yes	Phone number associated with verification (partially hidden).
secondsLeft	Integer	Yes	Remaining time (in seconds) until the verification period expires (0 if verification failed).

Important!

If secondsLeft=0, then the verification time has expired or the verification process is inactive. If you have any questions about integration, please contact Octo technical support.

---

/bind_card/check_sms_key

• URL: https://secure.octo.uz/bind_card/check_sms_key
• Method: POST
• Content-type: application/json

Request Example

{
  "octo_shop_id": "{{merchant_id}}",
  "octo_secret": "{{merchant_secret}}",
  "smsKey": "61135",
  "paymentUUID": "{{bind_octo_payment_UUID}}",
  "verifyId": "{{bind_verifyId}}"
}

Request Parameters

Parameter	Type	Mandatory	Description
octo_shop_id	Integer	Yes	The shop's unique ID.
octo_secret	String	Yes	The shop's personal secret key.
smsKey	String	Yes	SMS-code for confirmation.
paymentUUID	String	Yes	Unique payment ID for the card linking operation.
verifyId	Integer	Yes	Verification ID for card linking.

Successful Response Example

{
  "error": 0,
  "data": {
    "shop_transaction_id": "123431321323334132333",
    "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
    "status": "succeeded",
    "octo_pay_url": "https://pay-dev.octo.uz/status/06000144-db56-47b6-9eba-021ad4ff246b",
    "processor_key": "023205044087",
    "processing_reference": "1735210612392_71229",
    "transfer_sum": 980.0000,
    "refunded_sum": 1000.00,
    "total_sum": 1000.00,
    "payed_time": "2024-12-26 15:56:52",
    "first6": "860050",
    "last4": "2744"
  },
  "apiMessageForDevelopers": "Поле errorMessage устарело, просим перейти на errMessage для унификации ответов. Так же пожалуйста знайте, что в дальнейшем все поля кроме error и errMessage будут передаваться в data. Для более подробного ознакомление свяжитесь с технической поддержкой сервиса",
  "shop_transaction_id": "123431321323334132333",
  "octo_payment_UUID": "06000144-db56-47b6-9eba-021ad4ff246b",
  "status": "succeeded",
  "octo_pay_url": "https://pay-dev.octo.uz/status/06000144-db56-47b6-9eba-021ad4ff246b",
  "processor_key": "023205044087",
  "processing_reference": "1735210612392_71229",
  "transfer_sum": 980.0000,
  "refunded_sum": 1000.00,
  "total_sum": 1000.00,
  "payed_time": "2024-12-26 15:56:52"
}

Response Parameters

Parameter	Type	Mandatory	Description
error	Integer	Yes	Error code. 0 indicates a successful operation.
data	Object	Yes	Data of the response, containing payment details.
shop_transaction_id	String	Yes	Unique transaction ID on the shop's side.
octo_payment_UUID	String	Yes	Unique payment ID created by the OCTO system.
status	String	Yes	Current status of the payment (succeeded, etc.).
octo_pay_url	String	Yes	URL for verification or obtaining the payment status.
processor_key	String	No	Unique processor key for identification of the transaction.
processing_reference	String	No	Reference of the transaction in the system.
transfer_sum	Decimal	No	Amount transferred to the recipient post-deductions.
refunded_sum	Decimal	No	Refunded amount, if applicable.
total_sum	Decimal	Yes	Total transaction amount.
payed_time	String	No	Date and time of the payment completion.
first6	String	No	First 6 digits of the card used for payment.
last4	String	No	Last 4 digits of the card used for payment.
apiMessageForDevelopers	String	No	Additional details for developers.

Unsuccessful Response Example

{
    "title": "Internal Server Error",
    "status": 500,
    "detail": "Cannot invoke \"com.octo.uzcard.dto.CardInfo.getCardtype()\" because the return value of \"com.octo.uzcard.dto.CardNewVerifyResponse.getResult()\" is null"
}

callback

Request Example

{
    "shop_transaction_id": "d87f4hd8d76f4h58d",
    "pan": "4276380012341025",
    "exp": "2006",
    "cardHolderName": "BOB MARLEY",
    "card_token": "sdf9g87sd6f9g876sdf9g876sdf98g",
    "status": "active"
}

Request Parameters

Parameter	Type	Required	Description
shop_transaction_id	String	Yes	Unique transaction identifier in the shop.
pan	String	Yes	Original PAN (card number).
exp	String	Yes	Card expiration date in the format YYMM.
cardHolderName	String	Yes	Cardholder's name.
card_token	String	Yes	Card token obtained after binding.
status	String	Yes	Card status: active (successfully bound) or failed (binding failed).

Expected Response - HTTP Status: 200

Important!

• If the response is successful, the OCTO system considers the request processed.
• If the response is unsuccessful, the OCTO system will retry the request up to three times.
• If no successful response is received after three attempts, OCTO will stop sending requests and invalidate the token.

Successful Response Example - HTTP Status: 200

{
    "status": "success",
    "message": "Callback processed successfully"
}

Unsuccessful Response Example - HTTP Status: 400 and above

{
    "status": "error",
    "message": "Invalid shop_transaction_id"
}

block_card_token

• URL: https://secure.octo.uz/block_card_token
• Method: POST
• Content-type: application/json

Request Example

{
    "octo_shop_id": 242,
    "octo_secret": "1d45df74-bb95-47cf-a616-8d6dcee2e10d",
    "card_token": "sdf9g87sd6f9g876sdf9g876sdf98g"
}

Request Body Parameters Description

Parameter	Type	Required	Description
octo_shop_id	Integer	Yes	Unique shop identifier in the Octo system.
octo_secret	String	Yes	Secret key for request authentication.
card_token	String	Yes	Card token used for the transaction.

Successful Response Example

{
    "error": 0,
    "errMessage": null,
    "status": "blocked"
}

Response Parameters Description

Parameter	Type	Required	Description
error	Integer	Yes	Error code. 0 indicates no errors.
errMessage	String	No	Error message, if any.
status	String	Yes	Operation status. For example, blocked.

Possible Error Codes

Code	Description
0	No errors.
1	Data format error.
2	Authorization error.
4	Internal service error.
5	Token not found.
6	Token was not in the active status.

Possible Token Statuses

Status	Description
active	Ready for payment.
blocked	Blocked.
init	Card authorization in progress.
failed	Authorization failed.