Bank outreach for ArmPay: getting VPOS test credentials

Why this is the bottleneck nothing else solves for us

Almost every other part of ArmPay is a code problem. The schema is in prisma/schema.prisma, the ArCa client is in app/lib/arca.server.ts, the webhooks are under app/routes/webhooks.*.tsx, and all of them are edits to files we already own. The bank-credentials problem is not a code problem. The only way to test register.do against an actual ArCa-issued userName and password is for an Armenian bank to decide to email those to us.

That is the slowest piece of the build. docs/VPOS-Research.md documents the protocol; docs/bank-outreach.md documents the path to actually being allowed to use it.

The bank-outreach doc, and why it exists

docs/bank-outreach.md started as a scratchpad and ended up as a permanent file because the question which bank did we email, when, and what did they reply came up enough times that we needed a single source. The structure is small: a list of banks in our preferred order, the phone number for each one's relevant department, a single email template, and a section labelled What to expect.

The shape of the doc tells you what the work actually is. There is no API to call. There is no developer portal with a self-serve sandbox. The bank's reply is the input, followed by a phone call when the reply does not arrive.

Inecobank first, by deliberate ordering

The doc orders banks by developer-friendliness — our judgement, not the banks'. Inecobank is first; their VPOS page (https://www.inecobank.am/en/Business/business-tools/payment-solutions/vpos) is the most accessibly-documented one we found, a normal product page rather than a download buried in a PDF. The contact line lists business development / e-commerce; the phone number is +374 10 510 510.

Going to a developer-facing bank first matters because of what we are actually asking for: a username, a password, and an environment URL, when we have not yet signed a merchant agreement. A bank with an established e-commerce team will route that request to someone who has answered it before. A bank without one will route it to whichever business banker happens to be available, who is unlikely to recognise the request as routine.

The second bank in the doc is Ameria Bank, the third ACBA, the fourth Evocabank. All are real Armenian banks; none of the contact details we list are guesses. They came from the banks' own published pages, and we treat the doc as the source of truth that gets updated if any of them changes.

Ameria's own protocol, and the second mailbox

Ameria is the one bank in our four-bank list that does not run on ArCa's standard REST protocol. docs/bank-outreach.md is explicit about this: Ameria Bank has own API at services.ameriabank.am/VPOS/. It forces two parallel workstreams: a separate provider implementation and a separate mailbox.

On the integration side, the multi-bank provider system (commit 6910996 Add multi-bank provider system with AmeriaBank vPOS integration) routes Ameria-backed merchants through a separate provider implementation. On the outreach side, Ameria's e-commerce / card-acquiring team is a different group from Ameria's general business banking, and a request that lands in the wrong inbox will not find its way to the right one without nudging. The phone number we use is +374 10 56 11 11.

Two mailboxes, two protocols, two test environments — ipaytest.arca.am:8445 for the ArCa banks and servicestest.ameriabank.am/VPOS/ for Ameria.

What we ask for, in order

The email template in docs/bank-outreach.md is a copy-paste with four enumerated requests:

1. Test merchant credentials — userName and password for API access
2. Test card numbers for simulating payments
3. Test environment URL (if different from ipaytest.arca.am:8445)
4. Any integration documentation or merchant manual

The order is deliberate. Item 1 is what we cannot proceed without. Item 2 is what makes the integration end-to-end testable rather than partially mocked. Items 3 and 4 are nice-to-haves; we know the public test host already, and the protocol documentation lives in docs/vPOS_Eng_3.1.docx, which we already have a copy of.

The email also pre-answers the technical questions we expect the bank to ask:

• We use the hosted payment page model (the customer is redirected to the bank's page).
• Card data never touches our servers — PCI SAQ-A.
• We support one-stage, two-stage (pre-auth + capture), refunds (partial and full), and reversals.
• 3D Secure is fully supported.

Those four bullets are not marketing; they correspond to the subset of the VPOS specification we have implemented or wired through in app/lib/arca.server.ts (with the Ameria adapter alongside). Putting them above the asks shortens the round-trip: the bank's e-commerce team can see we already understand the protocol they would otherwise send us a primer on.

What banks ask for back

docs/bank-outreach.md has a section called What to expect. The honest summary, as written there:

• Banks typically respond within 3-5 business days.
• They may require a merchant agreement even for test access.
• Test credentials come with test card numbers.
• Test environment is at ipaytest.arca.am:8445 for ArCa banks; Ameria has its own test environment at servicestest.ameriabank.am/VPOS/.

The middle one is the one that catches first-timers off guard. Some Armenian banks will not issue test credentials to a developer who is not already a merchant customer. The framing is reasonable from their side — they want to know who is calling their VPOS — but it changes the shape of the outreach. The request stops being please send us a test username and becomes please tell us what your onboarding process looks like, because we want to be both a test integrator and a future merchant customer.

We will sign a merchant agreement to unblock test access if the bank requires it. We have not yet had to.

Why the email leads with technical detail, not positioning

The template does not lead with the first Armenian payment gateway integration for Shopify line as a selling point. It mentions it once, in the closing context paragraph, and not above the bulleted technical asks. That ordering is deliberate. The reader at the bank is an e-commerce / acquiring person, not someone who needs to be convinced that Shopify is a platform. They need to decide whether we are a serious enough integrator to issue credentials to.

The two things that earn that, from the template, are: a precise list of what we are asking for, and an accurate description of what we have already built. We have a Remix app, an ArCa client at app/lib/arca.server.ts, and a Prisma schema for PaymentSession, RefundSession, and MerchantConfig in prisma/schema.prisma. Each item is a path we can point a reader at.

What this work cannot be replaced by

The temptation, when an external dependency is slow, is to mock it and move on. We have not done that with VPOS credentials, and the reason is specific to payments.

Mocking register.do against fake credentials is easy. The bytes are form-encoded; the response shape is documented. Where the real bank deviates from the documented behaviour — the kind of drift we expect from any hosted gateway, particularly around 3DS at status 5 and the exact populations of paymentAmountInfo — is exactly where mocks lie to you. A mock will return a clean status 2 (paid) every time you ask. A real bank will, occasionally and for reasons we do not get to investigate, return something else. Until app/lib/arca.server.ts has parsed a real bank response — including a non-0 actionCode from a real transaction — it is only contract-tested.

So the bank outreach is what gates the integration's ready claim. Not the only gate — the Payments Partner Program reply from partners@shopify.com (per docs/shopify-outreach.md) is the other half of the same gate — but the one that decides whether app/lib/arca.server.ts has handled a real bank response or only the mocked one.

What this means for the App Store timeline

The App Store listing in docs/app-listing.md enumerates eight banks under Supported Banks: Ameria, Inecobank, Ardshinbank, ACBA, IDBank, Converse, Evocabank, VTB. The README adds AraratBank. Realistically, the supported list at submission time will not be eight; it will be however many of those banks have actually returned test credentials and let us run a real transaction end-to-end. The list in the listing is the aspiration; the list of banks we can name in a review reply is the truth.

That gap is fine. Works with any Armenian bank in the listing is followed by an enumeration that the reviewer can test against; the enumeration is bounded by which banks we have heard back from. We would rather submit with a shorter list and the right ones working than with a longer list and a reviewer who clicks Inecobank and ends in an authentication failure on register.do.

What is still rough on the outreach side

A few honest items:

• We do not track the outreach in docs/bank-outreach.md itself beyond the templates. The "we emailed X on Y, they replied Z" history lives in a separate inbox thread, which is not version-controlled. A dated log inside the doc would make it easier to pick up after a quiet stretch.
• The doc lists four banks (Inecobank, Ameria, ACBA, Evocabank) by developer-friendliness; the App Store listing enumerates eight. The other four — Ardshinbank, IDBank, Converse, VTB — do not yet have outreach entries with phone numbers and notes. Adding them is the next outreach task.
• The email template has not been translated. Armenian banks' e-commerce teams generally read English, but a parallel Armenian version would unstick the conversations that get bogged down in translation lag.
• We are still working out the merchant-agreement question for banks that require one for test access. We have not yet decided whether ArmPay-the-company signs that, or whether the first real merchant on each bank does.

None of these are technical. They are not blocked on app/lib/arca.server.ts. The next concrete piece of work is filling in the four missing outreach entries inside docs/bank-outreach.md, with phone numbers and a dated log alongside them.