Accept payments

Create & verify payments

Initialize a charge, direct the customer to checkout, and confirm what happened.

Create on your server

POST /payments starts a payment through a connected provider. The provider field selects a provider; its connection must belong to the key’s environment. Calculate the amount from trusted order data.

create a payment

curl https://api.veyqo.org/api/v1/payments \
  -H "Authorization: Bearer $VEYQO_SECRET_KEY" \
  -H "Idempotency-Key: $ORDER_PAYMENT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "currency": "NGN",
    "reference": "ORDER-1001",
    "provider": "paystack",
    "customer": { "email": "customer@example.com" },
    "metadata": { "order_id": "1001" }
  }'

Payment request fields

Field	Meaning
amount	Required positive integer in the smallest currency unit.
currency	Required three-letter currency code, supported by the provider.
customer.email	Required customer email for the nested customer form.
reference	Your order reference; if omitted, the payment ID becomes the reference.
provider	Provider slug, such as paystack.
callback_url	Optional HTTPS URL the provider can return the customer to.
metadata	Optional application context, such as an internal order ID.

Retry the same operation safely

Send an Idempotency-Key on POST requests. Generate and persist it before the first attempt. If the request times out, retry with the same key and exactly the same body. A different body with the same key returns a conflict.

Use a new key for a new logical operation. Your order reference and idempotency key serve different purposes: one identifies the order; the other identifies a request attempt across retries.

Verify before fulfilment

GET /payments/{id} retrieves the stored payment. POST /payments/{id}/verify queries the provider and updates the payment result. Both require payments:read.

Pending is not a successful payment. Store the payment ID and reconcile webhooks against the order’s reference, expected amount and currency. Deduplicate fulfilment even if the same confirmation arrives more than once.