Take your first test payment

OverviewCopy Anchor Link

This guide takes you from nothing to a paid test checkout in about ten minutes. You use a test key, so no real money moves, and it works before your business is approved.

What you build:

1. Your server trades its API key and secret for an access token.
2. It creates a checkout session for an order and gets back a url.
3. Your customer opens that url, a checkout hosted by Vezmo, and pays.
4. Vezmo sends a payment.success event to your webhook endpoint, and you confirm the payment over the API.

Every request goes to one base URL, in test and in live: https://api.vezmo.com/api/v1. The key you use decides the mode. Each step links to its call in the API reference, which has the request and response examples.

You need: a Vezmo account with VezmoPay, and an https address that can receive a POST (for the webhook). On your own computer, use an https tunnel.

1. Get a test keyCopy Anchor Link

1. Open Developers

   In the dashboard, go to Payments › VezmoPay, then Developers in VezmoPay's menu. The API keys tab opens.

2. Generate a test key

   Under Test keys, select Generate test key (Generate key once you have one). Give the key a Key name, check the Expires field, then select Generate key.

3. Enter the emailed code

   We email you a 6-digit code. Type it in: every new API key needs one.

4. Save the key and the secret

   The key (vzm_ and 16 characters) and the secret (32 characters) are shown once. Store them on your server, for example as VEZMO_API_KEY and VEZMO_API_SECRET, then select I've saved them — done.

2. Add a webhook endpointCopy Anchor Link

1. Add an endpoint

   In Developers, open the Webhooks tab and select Add endpoint.

2. Enter your address and pick events

   Enter your Endpoint URL (it must start with https://). Under Select Events, tick payment.success and payment.failed. Select Create Webhook and type the code we email you.

3. Save the signing secret

   The signing secret (whsec_ and 64 characters) is shown once. Store it on your server, for example as VEZMO_WEBHOOK_SECRET. Your handler uses it to check that each event really came from Vezmo.

For this test, a handler that logs the body and answers 200 is enough. How to check that an event really came from Vezmo is in Webhooks.

3. Get an access tokenCopy Anchor Link

Send the key and the secret to POST /merchant/api-auth/login, in the x-api-key and x-api-secret headers, with no body. The answer holds two tokens: the access token (data.accessToken.token) and a refresh token. The access token lasts 30 minutes: reuse it for every call until then.

The request and the response, with examples: Create an access token.

4. Create a checkout sessionCopy Anchor Link

Create the session for your order with POST /merchant/secure-payments, sending the access token as Authorization: Bearer and the token. In the body, send the order's title, amount and currency, the customer in client (name, email, country and postal code), and the successUrl and cancelUrl to send the customer back to. The amount is set here, on your server, and the customer can't change it.

The answer holds the payment in data.payment (its id, and the status INITIATED) and the checkout in data.securePayment (its url, and when it expires). Here amount comes back as a string; in events and in the Payments API it is a number.

Save data.payment.id with your order. The same id comes back on the redirect, in the webhook and from the Payments API, and it is how you match a payment to your order: the session has no field for your own order number.

Every field, with request and response examples: Secure payments.

5. Pay with a test cardCopy Anchor Link

Open the url in a browser. It is your checkout, hosted by Vezmo: your business name, the order and the amount, and an orange Test mode · no real money moves mark. The customer's name, country and ZIP code come from client.

1. Enter the test card

   Card number 4242 4242 4242 4242, any future expiry date, any security code.

2. Finish the billing details

   Fill in the rest of the billing address: street, city and state.

3. Pay

   Select Pay $49.99.

When the payment goes through, the checkout sends the customer to your successUrl, with paymentId (the payment id) and status=success added to the address.

6. Receive payment.successCopy Anchor Link

A few seconds later, your endpoint receives a POST with the event. Its X-Webhook-Event header names the event, and X-Webhook-Signature-V2 signs it. The body holds the event's id, its name in event, and the payment in data: paymentId, amount, currency, status, method and livemode. A full example is in the Webhooks reference.

• data.paymentId is the id you saved in step 4.
• livemode is false: a test payment. Never ship a real order on an event where it is false.
• Answer with any 2xx status within 5 seconds, or we try again later.

Nothing arrived? Open Developers › Webhooks: Deliveries lists every attempt with your server's answer.

7. Check the paymentCopy Anchor Link

Read the payment with GET /merchant/payment/:id, using the id you saved in step 4. The answer holds its state, livemode, amount, currency, the card's brand and last 4 digits, and the customer. Request and response examples: Payments.

Branch on state. A session nobody has paid yet reads pending; a paid one reads succeeded; a declined one reads failed. Bank payments take a few business days and read processing until they settle; bank details typed in by hand read awaiting_verification first, until the customer confirms the test deposits. The full list is in the Payments reference.

To see the payment in the dashboard, turn on Test mode in VezmoPay and open Transactions.

Next stepsCopy Anchor Link

• Hosted checkout: every session field, redirects, expiry and fulfilling orders.
• Webhooks: all 43 events, the signature check, retries and recovering missed events.
• Test mode for developers: test cards for 3D Secure, declines, disputes and bank payments.
• Go-live checklist: what to change before you take real payments.

QuestionsCopy Anchor Link

Login answers 401 "API secret does not match"Copy Anchor Link

The key is right but the secret isn't. Check for a missing character or a space. If the secret is lost, generate a new key: it replaces the old one at once.

The checkout says "The sandbox account is still being prepared"Copy Anchor Link

Your business's test setup isn't ready yet. Wait a moment and open the url again.

Creating a session answers 403Copy Anchor Link

With a live key, sessions open only while VezmoPay is approved for your business. A test key always works. Other 403 answers are in API keys and access tokens.

Can I make more test sessions?Copy Anchor Link

Yes. Each new session has its own url and payment id. Sign-in allows 5 requests a minute from one IP address: if it answers 429, wait a minute.