Accept a payment

How it works

The customer enters their card on our hosted page and completes 3D Secure there. Card data never touches your systems.

Currencies

EUR, USD, TRY, AZN

Result

Normally known when the customer returns to your site.

How it works

The customer chooses their bank on our hosted page and approves the payment with their bank.

Currencies

GBP by Faster Payments, EUR by SEPA

Result

Can stay processing after the customer returns. Wait for the webhook before you fulfil the order.

Before you start

What we exchange during onboarding

Keep the secret key on your server. Never put it in browser code, a mobile app or a public repository.

1Create the payment

curl https://api.sandbox.payrunner.net/payments \
  -H "api-key: $PAYRUNNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 2100,
    "currency": "EUR",
    "confirm": true,
    "capture_method": "automatic",
    "payment_method": "card_redirect",
    "payment_method_type": "card_redirect",
    "payment_method_data": { "card_redirect": { "card_redirect": {} } },
    "return_url": "https://shop.example.com/checkout/complete",
    "customer_id": "cus_8841",
    "merchant_order_reference_id": "order_10427",
    "description": "Order 10427",
    "billing": {
      "address": {
        "first_name": "Jane",
        "last_name": "Doe",
        "line1": "Teststrasse 1",
        "city": "Berlin",
        "zip": "10115",
        "country": "DE"
      },
      "phone": { "number": "15123456789", "country_code": "+49" },
      "email": "jane.doe@example.com"
    }
  }'

curl https://api.sandbox.payrunner.net/payments \
  -H "api-key: $PAYRUNNER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 900,
    "currency": "EUR",
    "confirm": true,
    "capture_method": "automatic",
    "payment_method": "bank_redirect",
    "payment_method_type": "open_banking",
    "payment_method_data": { "bank_redirect": { "open_banking": {} } },
    "return_url": "https://shop.example.com/checkout/complete",
    "customer_id": "cus_8841",
    "merchant_order_reference_id": "order_10427",
    "description": "Order 10427",
    "billing": {
      "address": { "first_name": "Jane", "last_name": "Doe" },
      "email": "jane.doe@example.com"
    },
    "browser_info": {
      "ip_address": "203.0.113.24",
      "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
      "language": "en-GB"
    }
  }'

Request fields

Response

{
  "payment_id": "pay_7Qm2Xc9LtR4vNa8KzYe1",
  "status": "requires_customer_action",
  "amount": 2100,
  "currency": "EUR",
  "merchant_order_reference_id": "order_10427",
  "next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": "https://api.sandbox.payrunner.net/payments/redirect/pay_7Qm2Xc9LtR4vNa8KzYe1/merchant_1700000000/pay_7Qm2Xc9LtR4vNa8KzYe1_1"
  }
}

{
  "payment_id": "pay_3Hd8Wp1ZsF6jGu5BnTq2",
  "status": "requires_customer_action",
  "amount": 900,
  "currency": "EUR",
  "merchant_order_reference_id": "order_10427",
  "next_action": {
    "type": "redirect_to_url",
    "redirect_to_url": "https://api.sandbox.payrunner.net/payments/redirect/pay_3Hd8Wp1ZsF6jGu5BnTq2/merchant_1700000000/pay_3Hd8Wp1ZsF6jGu5BnTq2_1"
  }
}

2Send the customer to pay

3Handle the return

https://shop.example.com/checkout/complete?status=succeeded&payment_id=pay_7Qm2Xc9LtR4vNa8KzYe1&payment_intent_client_secret=pay_7Qm2Xc9LtR4vNa8KzYe1_secret_aB3dE5gH7jK9mN1pQ3sT&amount=2100&manual_retry_allowed=false

Never mark an order as paid from this address. Anyone can edit a URL. Use payment_id to find the order, then ask the API for the status.

curl "https://api.sandbox.payrunner.net/payments/pay_7Qm2Xc9LtR4vNa8KzYe1?force_sync=true" \
  -H "api-key: $PAYRUNNER_API_KEY"

curl "https://api.sandbox.payrunner.net/payments/pay_3Hd8Wp1ZsF6jGu5BnTq2?force_sync=true" \
  -H "api-key: $PAYRUNNER_API_KEY"

{
  "payment_id": "pay_7Qm2Xc9LtR4vNa8KzYe1",
  "status": "succeeded",
  "amount": 2100,
  "amount_received": 2100,
  "currency": "EUR",
  "merchant_order_reference_id": "order_10427",
  "payment_method": "card_redirect",
  "error_code": null,
  "error_message": null
}

{
  "payment_id": "pay_3Hd8Wp1ZsF6jGu5BnTq2",
  "status": "processing",
  "amount": 900,
  "currency": "EUR",
  "merchant_order_reference_id": "order_10427",
  "payment_method": "bank_redirect",
  "error_code": null,
  "error_message": null
}

Payment statuses

Abandoned payments do not expire on their own. If the customer closes the page, the payment stays requires_customer_action. Set your own timeout and treat the order as unpaid. If a payment_succeeded webhook arrives after that, the customer has paid, so restore the order or contact them.

4Confirm by webhook

{
  "merchant_id": "merchant_1700000000",
  "event_id": "evt_019a3f7c2b1e7d4c9a6f",
  "event_type": "payment_succeeded",
  "timestamp": "2026-11-02T10:15:42.000Z",
  "content": {
    "type": "payment_details",
    "object": {
      "payment_id": "pay_7Qm2Xc9LtR4vNa8KzYe1",
      "status": "succeeded",
      "amount": 2100,
      "amount_received": 2100,
      "currency": "EUR",
      "merchant_order_reference_id": "order_10427"
    }
  }
}

{
  "merchant_id": "merchant_1700000000",
  "event_id": "evt_019a3f7c2b1e7d4c9a6f",
  "event_type": "payment_succeeded",
  "timestamp": "2026-11-02T10:15:42.000Z",
  "content": {
    "type": "payment_details",
    "object": {
      "payment_id": "pay_3Hd8Wp1ZsF6jGu5BnTq2",
      "status": "succeeded",
      "amount": 900,
      "amount_received": 900,
      "currency": "EUR",
      "merchant_order_reference_id": "order_10427"
    }
  }
}

Verify the signature

import crypto from 'node:crypto';
import express from 'express';

const app = express();

// express.raw keeps the exact bytes the signature covers.
app.post('/webhooks/payrunner', express.raw({ type: 'application/json' }), (req, res) => {
  const expected = crypto
    .createHmac('sha512', process.env.PAYRUNNER_HASH_KEY)
    .update(req.body)
    .digest('hex');
  const received = req.get('X-Webhook-Signature-512') ?? '';

  const valid =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!valid) return res.sendStatus(401);

  const { event_type, content } = JSON.parse(req.body);
  const payment = content.object;

  // Update the order for payment.payment_id here, or queue the work.

  res.sendStatus(200);
});

app.listen(3000);

<?php

// php://input keeps the exact bytes the signature covers.
$body = file_get_contents('php://input');

$expected = hash_hmac('sha512', $body, getenv('PAYRUNNER_HASH_KEY'));
$received = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE_512'] ?? '';

if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);
$payment = $event['content']['object'];

// Update the order for $payment['payment_id'] here, or queue the work.

http_response_code(200);

Handle deliveries safely

• Answer with a 2xx status. Save the event and reply quickly, then do slow work afterwards. Any other response counts as a failed delivery.
• Expect retries. We retry a failed delivery for about 24 hours: after 1 minute, then at growing intervals up to every 6 hours.
• Match on payment_id and event_type. Each retry has a new event_id, so event_id alone won't catch repeats.
• Only move an order forward. Events can arrive out of order. Ignore an event that would change a finished order.
• Check the money. Compare amount and currency with your order before you fulfil it.

Errors

The request was refused

{
  "error": {
    "type": "invalid_request",
    "message": "Missing required param: amount",
    "code": "IR_04"
  }
}

The payment failed

Test your integration

Check these before you ask for live access

• A successful payment marks the order paid, even if the customer closes the tab before returning.
• A failed payment shows the customer a clear message and lets them try again with a new payment.
• A customer who abandons the payment page leaves the order unpaid, and your timeout closes it.
• An order stays pending while the payment is processing, and is only fulfilled on payment_succeeded.
• Editing status=succeeded into the return address does not mark an order paid.
• Sending the same webhook twice updates the order once.
• A webhook with a wrong signature gets a 401 and changes nothing.

Go live

• Replace the sandbox base URL with https://api.payrunner.net.
• Store your production API key as a server secret.
• Switch to your production Payment Response Hash Key. It differs from the sandbox one.
• Send us your production Webhook URL.
• Make one small real payment and check that the order, the webhook and your records agree.