Payment Solution VN v1

Creating Payments

POSThttps://api-merchant.alikassa.com/v1/payment📋

Headers

Header	Value
Content-Type	application/json
Account	Your account uuid, you can find in Accounts
Sign	Request signature

Certificate Setup

Go to API Certificate Settings, generate "API certificate for payment", save the archive, and unpack it.

You'll get:

• password.txt
• private.pem
• public.pem

We keep only public.pem for signature verification.

Signature Generation

Wrap all POST data in JSON (in the same order) and sign:

$data = json_encode($data);

$privateKey = openssl_pkey_get_private(
    file_get_contents('private.pem'),
    file_get_contents('password.txt')
);

if ($privateKey === false) {
    throw new \Exception('Error cert.');
}

openssl_sign($data, $sign, $privateKey);
$sign = base64_encode($sign);

import { readFileSync } from 'fs';
import { createSign } from 'crypto';

const dataStr = JSON.stringify(data);
const key = readFileSync('private.pem', 'utf8');
const passphrase = readFileSync('password.txt', 'utf8').trim();
const signer = createSign('SHA256');
signer.update(dataStr);
signer.end();
const sign = signer.sign({ key, passphrase }, 'base64');

import json, base64
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding

data_bytes = json.dumps(data).encode()
with open('password.txt','rb') as f:
    password = f.read().strip()
with open('private.pem','rb') as f:
    private_key = serialization.load_pem_private_key(f.read(), password=password)
signature = private_key.sign(data_bytes, padding.PKCS1v15(), hashes.SHA256())
sign = base64.b64encode(signature).decode()

import java.nio.file.Files;
import java.nio.file.Paths;
import java.security.Signature;
import java.util.Base64;
import org.bouncycastle.openssl.PEMEncryptedKeyPair;
import org.bouncycastle.openssl.PEMParser;
import org.bouncycastle.openssl.jcajce.JcePEMDecryptorProviderBuilder;
import org.bouncycastle.openssl.jcajce.JcaPEMKeyConverter;

byte[] dataBytes = new com.fasterxml.jackson.databind.ObjectMapper().writeValueAsBytes(data);
char[] pass = Files.readString(Paths.get("password.txt")).toCharArray();
PEMParser parser = new PEMParser(Files.newBufferedReader(Paths.get("private.pem")));
PEMEncryptedKeyPair ckp = (PEMEncryptedKeyPair) parser.readObject();
var privateKey = new JcaPEMKeyConverter()
    .getKeyPair(ckp.decryptKeyPair(new JcePEMDecryptorProviderBuilder().build(pass)))
    .getPrivate();
Signature sig = Signature.getInstance("SHA256withRSA");
sig.initSign(privateKey);
sig.update(dataBytes);
String sign = Base64.getEncoder().encodeToString(sig.sign());

import (
    "crypto"
    "crypto/rand"
    "crypto/rsa"
    "crypto/sha256"
    "crypto/x509"
    "encoding/base64"
    "encoding/json"
    "encoding/pem"
    "io/ioutil"
)

dataBytes, _ := json.Marshal(data)
pemBytes, _ := ioutil.ReadFile("private.pem")
passBytes, _ := ioutil.ReadFile("password.txt")
block, _ := pem.Decode(pemBytes)
der, _ := x509.DecryptPEMBlock(block, passBytes)
priv, _ := x509.ParsePKCS1PrivateKey(der)
hash := sha256.Sum256(dataBytes)
sigBytes, _ := rsa.SignPKCS1v15(rand.Reader, priv, crypto.SHA256, hash[:])
sign := base64.StdEncoding.EncodeToString(sigBytes)

Pass the received $sign in the Sign header.

Request Parameters

* - Required fields

Name	Type	Description
amount*	decimal (11.2)	Amount
order_id*	string (128)	Your id must be unique
service*	string (100)	Service type: online_banking_vnd_hpp, qr_code_vnd_hpp, e_wallet_vnd_hpp, local_bank_transfer_vnd_hpp
customer_ip*	ip	Payer's IP address
customer_code*	string (100)	Deposit Bank Code
success_redirect_id	int	Id of redirect upon successful payment
fail_redirect_id	int	Id of redirect in case of unsuccessful payment
notification_endpoint_id	int	Notification id
success_redirect_url	string|max:255	Link to redirect after successful payment
fail_redirect_url	string|max:255	Link to redirect after unsuccessful payment
notification_endpoint_url	string|max:255	Link to send a callback after the statuses are finalized

Response

Name	Description
url	Link to payment
payment_status	Payment status (wait — in the process of payment)
id	AliKassa payment id
uuid	AliKassa payment uuid
success_redirect_url	Link to your page for client redirect after successful payment

Important

When creating, always wait, check the payment status via the API or wait for a notification!

Example Response

Successful HTTP CODE 200:

{
  "url": "https://pay-merchant.alikassa.com/bd291fe1-5c19-4113-ae62-a2d3c4d01d20",
  "payment_status": "wait",
  "id": 108465371,
  "uuid": "bd291fe1-5c19-4113-ae62-a2d3c4d01d20",
  "success_redirect_url": null
}

Unsuccessful HTTP CODE 400:

{
   "message": "The given data was invalid.",
   "errors": {
      "..."
   }
}

After receiving the URL, redirect the client to the link.

❗ Notification

caution

If you passed notification_endpoint_id or notification_endpoint_url, you will receive a notification about the payment status change

Deposit Bank Codes

Online Banking VND HPP (online_banking_vnd_hpp)

customer_code	Bank Name
ACB	Asia Commercial Bank
AGB	Agribank
BIDV	Bank for Investment and Development of Vietnam
DAB	DongA Bank
EXIM	Eximbank Vietnam
HDB	HDB Bank
MB	Military Commercial Joint Stock Bank
MTMB	Maritime Bank
OCB	Orient Commercial Joint Stock Bank
SACOM	Sacombank
TCB	Techcombank
TPB	Tien Phong Bank
VCB	Vietcombank
VIB	Vietnam International Bank
VPB	VP Bank
VTB	Vietinbank

QR Code VND HPP (qr_code_vnd_hpp)

customer_code	Bank Name
VIETQR	VietQRpay

E-Wallet VND HPP (e_wallet_vnd_hpp)

customer_code	Bank Name
VIETQRMOMO	VietQR MOMO
VIETQRZALO	VietQR Zalo Pay
VIETQRVIETTEL	VietQR Viettel Pay

Local Bank Transfer VND HPP (local_bank_transfer_vnd_hpp)

customer_code	Bank Name
VSTB	VND Semi Transfer Bank
VCBLBT	Vietcom Bank Local Bank Transfer
DABLBT	Donga Bank Local Bank Transfer

Creating Payouts

POSThttps://api-merchant.alikassa.com/v1/payout📋

Headers

Header	Value
Content-Type	application/json
Account	Your account uuid, you can find in Accounts
Sign	Request signature

Request Parameters

* - Required fields

Name	Type	Description
amount*	decimal (11.2)	Amount
order_id*	string (128)	Your unique order id (e.g., "1234")
service*	string (100)	payment_card_vnd
number*	string (100)	Recipient account number
customer_code*	string (100)	Payout Bank Code
customer_first_name*	string (100)	Payer's first name
customer_last_name*	string (100)	Payer's last name
notification_endpoint_id	int	Notification id
notification_endpoint_url	string|max:255	Link to send a callback after the statuses are finalized

Response

Name	Description
id	AliKassa payment id
payment_status	Payment status (wait — in the process of payment)

Payout Bank Codes

Payment Card VND (payment_card_vnd)

customer_code	Bank Name
ABCJS	An Binh Commercial Join Stock Bank
CITIV	Citibank Vietnam
HDB	HoChiMinh City Development Joint Stock Commercial Bank
HSBCV	HSBC Vietnam
NAMA	Nam A Commercial Joint Stock Bank (NamaBank)
PBBV	Public Bank Vietnam
PVCB	PVcomBank
SCBV	Standard Chartered Bank Vietnam
SGCB	Saigon Commercial Bank (Ngân hàng TMCP Sài Gòn)
SHBV	Shinhan Bank Vietnam
SHCB	Saigon-Hanoi Commercial Joint Stock Bank
VCPTB	Viet Capital Bank (Ngan Hang Ban Viet)
OCB	Orient Commercial Joint Stock Bank
DBVN	Deutsche Bank
WBVN	Woori Bank VN
SEAVN	SeAbank
LVPB	LienVietPostBank
VAB	VIET A BANK
BAB	Bac A Commercial Joint Stock Bank
NCB	National Citizen Bank
KLB	Kien Long Commercial Joint Stock Bank
VB	Vietbank
CB	Vietnam Construction Bank-CB
BSHB	SHB Bank
ABB	AB BANK
PGB	PG Bank
OCEANB	Ocean Bank Viet Nam