Accept card payments with GetPay payment links

01How it works

A payment link is a hosted payment page for one order. Your server creates it with your order details, and GetPay takes care of the rest.

1. Your serverCreates a payment link with the items, amount and your order number. GetPay returns a url.
2. Your websiteRedirects the customer to that url.
3. CustomerReviews the order, enters their details and pays by card on the bank’s secure page. If the card is declined, they can try again on the same link.
4. GetPayChecks the result with the bank, sends the customer to your success_url, and sends a payment_link.completed webhook to your server.
5. Your serverConfirms the payment and fulfils the order.

sequenceDiagram
    participant S as Your server
    participant C as Customer
    participant G as GetPay
    participant B as Bank (vPOS)
    S->>G: POST /payment-links
    G-->>S: { id, url }
    S->>C: Redirect to url
    C->>G: Opens payment page, presses Pay
    G->>B: Register payment
    C->>B: Enters card, 3-D Secure
    B->>G: Result
    G->>C: Redirect to success_url
    G->>S: Webhook payment_link.completed
    S->>G: GET /payment-links/{id} (confirm)
      

02Before you start

Your domain and base URL

The API runs on your own domain, not on getpay.am. In the GetPay dashboard open the Domain tab, enter your domain (for example shopx.am) and add the four DNS records it shows, all pointing to the GetPay IP address:

Then press Check connection. Once all records are found, the dashboard shows your API base URL. Requests sent to any other address, including api.getpay.am, are refused with 403.

API keys

Find your keys in the GetPay dashboard under Home → API keys. You have two, one per environment:

Send the key in the Authorization header of every request:

Conventions

• Amounts are in minor units. 150000 means 1,500.00 AMD. Always send whole numbers.
• Currency: the currencies GetPay has enabled — GET /meta/currencies (AMD for now). Others return CURRENCY_NOT_SUPPORTED.
• Requests and responses are JSON. Send Content-Type: application/json.
• Times are UTC in ISO 8601, for example 2026-09-30T10:15:00Z.
• IDs are UUIDs. Store the payment link id next to your order.

03Create a payment link

Call this from your server when the customer is ready to pay. Send what they are buying, who they are (if you know), and where to send them afterwards.

Parameters

Send either line_items or amount, not both. Everything else is optional.

Response

201 Created with the payment link. Save id with your order and send the customer to url.

04Send the customer to the payment page

Redirect the customer’s browser to the url from the response. The page shows your business name, the items and total, asks for the fields you chose, and offers card payment. The customer can switch between Armenian, English and Russian.

What happens next

05Confirm the payment

Use either way, or both. Webhooks are the reliable way because they arrive even if the customer closes the browser before reaching your success page.

• Webhook: handle payment_link.completed (see Webhooks).
• API: when the customer lands on your success_url, fetch the link.

Fulfil the order only when status is complete and payment_status is paid, and the amount_total and currency match your order. This call also re-checks a pending payment with the bank.

Payment link statuses

Payment statuses

Each attempt to pay is a payment, returned in the link’s payment field and by the payments API.

06Webhooks

GetPay sends an HTTPS POST to your server when something happens, so you don’t have to poll. Each request is signed with a secret only you and GetPay know.

Set up an endpoint

• In the dashboard, open Webhooks, choose Sandbox or Live, and add your URL, e.g. https://your-site.am/webhooks/getpay.
• Choose all events or only the ones you need.
• Copy the signing secret (whsec_…) and store it on your server as GETPAY_WEBHOOK_SECRET. It is different from your API key.
• Press Send test to check your endpoint. The dashboard shows every delivery with your server’s response.

Live endpoints must use https://. Sandbox endpoints may use http://. GetPay cannot reach localhost; to receive events on your computer while developing, use a tunnel such as ngrok http 8001 and register the public URL it gives you.

Events

Request format

data.object has exactly the same shape as the API response for that object.

Verify the signature

The signature is HMAC-SHA256(secret, t + "." + raw_body) in hex. Compute it over the raw request body (re-encoded JSON will not match), compare in constant time, and reject requests older than 5 minutes.

Respond and retry

• Return any 2xx within 10 seconds. Do slow work (emails, stock updates, ERP sync) in a background job after responding.
• Anything else is retried after 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours, 12 hours and 24 hours. After that the delivery is marked failed, and you can resend it from the dashboard.
• Expect duplicates. The same event can arrive more than once. Store processed GetPay-Event-Id values and skip repeats.
• Don’t rely on order. Events can arrive out of order. Use the status inside data.object, or fetch the latest from the API.
• Double-check if unsure. Fetch the event with GET /events/{id} using your secret key.

07Test in sandbox

With your sk_sandbox_… key, everything works like live, but pressing Pay opens the GetPay test page instead of a bank. You choose how the payment ends. Webhooks, redirects, decline messages and refunds behave exactly as they will in live mode. No bank credentials are needed.

Test these before going live: a successful payment, a decline followed by a successful retry, a customer who closes the browser after paying (your webhook must still fulfil the order), and a refund.

08Refunds and reversals

There are two ways to give money back. Both return it to the customer’s card through the bank.

Every payment tells you what is possible right now, so you don’t have to track the rules yourself:

Reverse a payment

Cancels the whole payment at the bank. Use it when an order is canceled shortly after payment. After 72 hours, or once anything has been refunded, the request returns 409 and you need a refund instead. A payment.reversed webhook follows.

Refund a payment

Send {"amount": 500000} for a partial refund of up to amount_refundable. Send an empty body or {} for a full refund of everything that remains. You can make several partial refunds. A payment.refunded webhook follows each one.

Both requests return the updated payment. The payment ID is in the link’s payment.id field and in the payment_id added to your success URL.

09Receipts

Every paid payment gets a receipt, much like Stripe receipts: a short number the customer can quote, such as 4821-0937, and a receipt page hosted by GetPay on your domain at https://receipt.your-domain.am/…. The page shows your business details, the items, the card used, any refunds, and a button to save it as a PDF. It is available in Armenian, English and Russian.

The receipt is issued the moment the payment is paid, so the link is already there when the customer returns to your site and when the webhooks arrive. There is nothing to create or enable.

Where you get the receipt link

Receipt object

10Fiscal receipts (EHDM)

If your business must issue cash register receipts, GetPay can register every successful payment with the State Revenue Committee through the PayX electronic cash register (Է-ՀԴՄ, ehdm.am). You need your own contract with PayX. Connect the API login they give you in the dashboard under Settings → EHDM.

While EHDM is enabled, every payment link must say what is sold: the classifier code, the name in Armenian and the unit. GetPay issues the fiscal receipt automatically once the payment succeeds, and the return receipt after a reversal or a full refund.

Check whether EHDM is enabled

enabled: true means your payment links must carry fiscal data (or skip it). dep is the tax department you chose in your EHDM settings; it is used for line items that send no dep.

Fiscal data on a payment link

After the payment

The receipt is registered in the background, usually within seconds. The customer’s receipt page (receipt_url) shows it like a cash register receipt, with the fiscal number, QR code and a link to the PayX PDF. You get it in three places:

Fiscal receipt statuses

11API reference

All endpoints use your secret key. A sandbox key only sees sandbox data, and a live key only sees live data.

Lists return { "object": "list", "items": [...], "total", "limit", "offset" }.

12Errors

Errors return a JSON body with the HTTP status, a stable message_code to check in your code, and a readable message.

13Go-live checklist

• Your domain is connected under Domain, and your server uses the API base URL shown there.
• Your merchant account has completed onboarding and is switched to live in the dashboard.
• Your bank (Ameriabank vPOS) credentials are connected and enabled under Payment gateways → Live.
• Your server uses the sk_live_… key from an environment variable, never from code.
• A live webhook endpoint is added with an https:// URL, and its whsec_… secret is on your server.
• Your webhook handler verifies signatures, rejects old timestamps and ignores duplicate event IDs.
• You fulfil orders only after confirming complete / paid and matching amount and currency.
• Your thank-you page or order email shows the customer the receipt_url.
• If you use EHDM: PayX is connected and enabled under Settings → EHDM, and your links send line_items[].ehdm.
• You made one small real payment and refunded it.