Accept a payment

Get your test API keyCopy Anchor Link

1. Log in to the merchant portal at https://merchant.secure.vayapay.com.
2. Create a project in test mode, or open an existing test project.
3. Go to Settings > API Key and copy the key.

Store the key as an environment variable on your server, so it doesn't end up in your code:

export API_KEY="your-test-api-key"

The API uses HTTP Basic authentication: your API key is the username and the password is empty. Retrieve your project to check that the key works:

curl https://api.secure.vayapay.com/v1/merchants/self/projects/self/ \
  --user "$API_KEY:"

A 200 OK response with your project details means you're connected. A 401 Unauthorized response means the API key is wrong.

Create an orderCopy Anchor Link

When your customer checks out, your server creates an order. This example creates an order for € 9.95. The amount is in cents.

curl https://api.secure.vayapay.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "EUR",
    "amount": 995,
    "merchant_order_id": "EXAMPLE001",
    "description": "Example order",
    "return_url": "https://www.example.com/order/EXAMPLE001",
    "webhook_url": "https://www.example.com/webhook"
  }'

Replace the return_url and webhook_url with URLs of your own server. The API responds with the new order:

{
  "id": "1c969951-f5f1-4290-ae41-6177961fb3cb",
  "currency": "EUR",
  "amount": 995,
  "merchant_order_id": "EXAMPLE001",
  "description": "Example order",
  "return_url": "https://www.example.com/order/EXAMPLE001",
  "webhook_url": "https://www.example.com/webhook",
  "created": "2026-10-12T11:41:57.121017+00:00",
  "modified": "2026-10-12T11:41:57.183822+00:00",
  "expiration_period": "PT1H",
  "order_url": "https://api.secure.vayapay.com/pay/1c969951-f5f1-4290-ae41-6177961fb3cb/",
  "status": "new"
}

Save the id with your order: you need it to look up the order later.

Only currency and amount are required. The amount is in the smallest currency unit: 995 is € 9.95. See Create an order in the API reference for all fields.

Redirect your customerCopy Anchor Link

Redirect your customer to the order_url. For this test, open it in your browser.

The hosted payment page shows every payment method that's active in your project. Select one and complete the payment with test details from Test data. After the payment, the browser goes to your return_url.

Handle the webhookCopy Anchor Link

When the order status changes, Vayapay sends a POST request to your webhook_url:

{
  "event": "status_changed",
  "order_id": "1c969951-f5f1-4290-ae41-6177961fb3cb",
  "project_id": "b5f39273-44e7-4385-8e08-44612ef3e117"
}

The webhook deliberately doesn't contain the status. Retrieve the order from the API, update your order with its status, and respond with 200 OK within 4 seconds. Vayapay retries a failed webhook, so handle the same notification safely more than once.

See Confirm the payment for an example handler in Node.js and Python, and the full delivery rules.

Check the statusCopy Anchor Link

Retrieve the order when you receive the webhook, and when your customer lands on your return_url:

curl https://api.secure.vayapay.com/v1/orders/1c969951-f5f1-4290-ae41-6177961fb3cb/ \
  --user "$API_KEY:"

{
  "id": "1c969951-f5f1-4290-ae41-6177961fb3cb",
  "amount": 995,
  "currency": "EUR",
  "merchant_order_id": "EXAMPLE001",
  "status": "completed",
  "completed": "2026-10-12T11:43:12.402150+00:00",
  "transactions": [
    {
      "id": "058cf70d-7a84-4957-941c-532c065cef72",
      "payment_method": "credit-card",
      "status": "completed"
    }
  ]
}

The response is shortened. Act on the order status:

Webhooks can be delayed or lost: also check orders that aren't final after a while. See Confirm the payment.