Partner API: connecting merchants

The merchant stays the owner of its business in VCR. You act under a grant: access to one business that its owner can withdraw at any time. One partner key reaches every business that has given you access.

Everything you do is recorded in the business's audit log under your partner's name and the key used, so an owner can always see who did what.

1. We add your VCR account to your partner's team. You get an email with these steps.
2. Someone entitled to sign contracts for your company accepts the Partner Terms, once. You need them to attest access on a merchant's written authorization; asking owners to confirm works without them. Accept the Partner Terms
3. A team member issues an API key in the partner cabinet. It is shown once; send it in the X-API-Key header. Open the partner cabinet

Check the key: GET /whoami answers with your partner, the key and whether the current Terms are accepted.

curl https://vcr.am/api/partner/v1/whoami \
  -H "X-API-Key: $VCR_PARTNER_KEY"

Ask for access with POST /entities and the merchant's TIN. If VCR does not know the TIN yet, it looks the business up in the state registry and creates it. Access rests on one of two bases.

The owner confirms

The owner gets an email with a one-click link, valid for 7 days. Until they click, the grant is pending. For a business VCR already holds with owners, leave owner out: the request goes to its current owners, never to an address you name.

curl -X POST https://vcr.am/api/partner/v1/entities \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tin": "01234567",
    "access": {
      "basis": "owner_confirmation",
      "owner": { "email": "owner@merchant.am", "language": "hy" }
    }
  }'

You attest

If your contract with the merchant authorizes you in writing, cite it and the grant is active at once. endsOn is the last day of the term the authorization states, at most three years from signedOn; leave it out when it states none, and the grant runs one year from signing.

curl -X POST https://vcr.am/api/partner/v1/entities \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tin": "01234567",
    "access": {
      "basis": "partner_attestation",
      "merchantAuthorization": {
        "reference": "Service agreement No. 17, clause 4.2",
        "signedOn": "2026-10-01",
        "endsOn": "2027-09-30"
      }
    }
  }'

While a grant is pending, on a business you brought into VCR you can already create registers, get the CSR and upload the certificate; activation and receipts wait for the owner's click. On a business that was in VCR before you, nothing is allowed until the grant is active.

To give access up yourself, call DELETE /entities/{entityId}/grant: it cancels a request the owner has not answered, or ends access in force. The Partner Terms require it within three business days of the merchant's authorization ending. grant.ended arrives with the reason relinquished.

curl -X DELETE https://vcr.am/api/partner/v1/entities/42/grant \
  -H "X-API-Key: $VCR_PARTNER_KEY"

POST /entities/{entityId}/registers creates a register with a fresh key pair and the CSR for application 101. tradingPlatformName is field 5.4 of the application and prints on receipts; website is field 5.3.

curl -X POST https://vcr.am/api/partner/v1/entities/42/registers \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "tradingPlatformName": "Merchant Cafe Abovyan",
    "website": "https://cafe.merchant.am",
    "mode": "production"
  }'

A retry after a timeout would create a second register, so send an Idempotency-Key header (a UUID): the retry then answers with the register the first call made and carries Idempotent-Replay: true.

GET /registers/{registerId}/application returns what to enter in application 101 and the CSR to attach to it.

curl https://vcr.am/api/partner/v1/registers/104/application \
  -H "X-API-Key: $VCR_PARTNER_KEY"
# -> { "tin": "...", "website": "...", "applicationName": "...", "csr": "-----BEGIN CERTIFICATE REQUEST-----..." }

The taxpayer files application 101 in the SRC portal, signed with their own electronic signature, and SRC issues a certificate. Upload it as PEM. It must chain to the SRC root, carry this business's TIN and match the register's CSR; uploading the same certificate again changes nothing. The certificate gives the register its CRN.

curl -X PUT https://vcr.am/api/partner/v1/registers/104/certificate \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile pem certificate.crt '{certificate: $pem}')"

A sandbox register takes its certificate from the sandbox CA instead of application 101:

curl -X POST https://vcr.am/api/partner/v1/registers/104/sandbox-certificate \
  -H "X-API-Key: $VCR_PARTNER_KEY"
# -> { "certificate": "-----BEGIN CERTIFICATE-----...", "crn": "99123456" }
# Upload it with PUT /registers/104/certificate, as you would SRC's.

Activation needs an active grant. Choose the tax regime of the register's first department: vat, vat_exempt, turnover_tax or micro_enterprise. It prints on every receipt, and the owners are emailed your choice. Repeating the call is safe.

curl -X POST https://vcr.am/api/partner/v1/registers/104/activation \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taxRegime": "turnover_tax" }'

GET /registers/{registerId} says where a register stands:

Sales, refunds, cashiers and departments go through the regular API, /api/v1, with your partner key. Name the register by its id in the VCR-Register header. Without the header the answer is 400; a register you have no access to answers 404; a grant still waiting for the owner answers 403.

# The regular API, with the partner key and the register named in a header.
curl https://vcr.am/api/v1/cashiers \
  -H "X-API-Key: $VCR_PARTNER_KEY" \
  -H "VCR-Register: 104"

The endpoints are the same as with a register's own key: API documentation

Add up to 5 endpoints in the partner cabinet; each must be https on the public internet. Every request is signed by the Standard Webhooks spec (webhook-id, webhook-timestamp, webhook-signature): check it with the endpoint's secret, shown once when you add it.

A failed delivery is retried for about a day. The body of each event is in the reference, under webhooks. The cabinet can send a test event to check an endpoint.

A refusal answers JSON with error, a sentence for a person, and code, stable for a program. Codes never change meaning; new ones may be added, so treat an unknown code by its HTTP status. The reference lists the statuses of each endpoint.

POST /registers/{registerId}/closure closes a register in VCR: its keys stop working and register.closed is sent.

curl -X POST https://vcr.am/api/partner/v1/registers/104/closure \
  -H "X-API-Key: $VCR_PARTNER_KEY"

SRC is not told: deregistering a register is the taxpayer's own application in the tax portal. How to deregister a register