Getting started
Requirements
Section titled “Requirements”- Node.js 22.12 or later, current Bun, or Deno 2+ (
import { AmeriaClient } from "npm:@ameria/vpos-sdk"). The package is ESM; CommonJS code on Node 22.12+ can load it withrequire(). - A vPOS merchant account with Ameriabank. The bank issues a client ID, a username and a password for the test environment first, and separate ones for production.
Install
Section titled “Install”npm install @ameria/vpos-sdkCreate a client
Section titled “Create a client”Keep the credentials out of your code — environment variables or a secret store.
import { AmeriaClient } from "@ameria/vpos-sdk";
export const ameria = new AmeriaClient({ clientId: process.env.AMERIA_CLIENT_ID!, username: process.env.AMERIA_USERNAME!, password: process.env.AMERIA_PASSWORD!, isTest: process.env.NODE_ENV !== "production",});isTest: true sends requests to servicestest.ameriabank.am; leave it out for production.
Requests time out after 30 seconds; pass timeoutMs to change that.
Take a payment
Section titled “Take a payment”-
Register the payment.
initPaymentreturns aurlto the bank’s card page.create-payment.ts import { ameria } from "./client.js";const payment = await ameria.initPayment({orderId: 2350301, // in test, use an ID from the range the bank gave youamount: 10, // the test environment only accepts 10 AMDcurrency: "AMD",description: "Order #1042",backUrl: "https://shop.example/payment/back",opaque: "order-1042",lang: "en",});if (payment.url) {// Send the payer to the bank's card page.console.log("Redirect to", payment.url);} else {console.error("Bank refused:", payment.ResponseMessage);} -
Redirect the payer to that
url. They enter their card details on the bank’s page — card data never touches your server. -
Verify on return. The bank sends the payer back to your
backUrl. That redirect is not signed, so ask the bank for the result before fulfilling the order — see Accept a payment.
- Test environment — what the bank’s sandbox accepts.
- Security — what to check before going live.