WaldenPay API

Overview

A typical integration is three steps:

1. Create a payment server-side and receive a one-time charge token.
2. Charge the card using the token, with card data collected on your page.
3. Confirm the outcome via webhook or by retrieving the payment.

Host-to-host mode requires PCI DSS compliance on your side, since card data passes through your pages and servers. Contact support to confirm your compliance status before going live.

How it works

The full payment lifecycle, from order to confirmation. Your customer never leaves your site except for an optional, issuer-hosted 3D Secure challenge.

1. The customer places an order on your website.
2. Your server creates a payment (POST /v1/payments) with your callback_url, return_url and the payer's customer profile, and receives a payment ID and a one-time charge token.
3. You render your own card form. The customer enters their card details.
4. Your server (or the payment page) submits the card data with the charge token (POST /v1/charges).
5. If the issuer requires 3D Secure, the response contains an action — render it as an auto-submitting form; the customer completes the challenge on the issuer's page and returns to your return_url.
6. WaldenPay records the final result and sends a signed payment.updated webhook.
7. Your server confirms the outcome from the webhook — or by retrieving the payment — and shows the customer the result.

For transitional results (a charge response with status: "processing" and no action), don't poll in a tight loop — wait for the webhook, or reconcile after a short delay.

Authentication

All /v1 endpoints (except card charges) use HTTP Basic auth:

curl https://gw.waldenpay.com/v1/payments \
  -u "wma_your_merchant_id:wk_your_api_key" \
  -H "Content-Type: application/json"

Card charges (POST /v1/charges) instead use Authorization: Bearer <charge token> — the single-use wgt_… token returned when the payment is created. Keep your API key server-side only; the charge token is safe to use from the page performing the charge.

Domains

Every payment must be associated with a domain you are approved to accept payments from. This domain is sent with the payment as its merchant_url, so a terminal cannot take payments until at least one domain is enabled for it.

How domains are set up:

1. WaldenPay approves the set of domains allowed for your account. If you need a new domain added, contact support.
2. In the Terminals page you choose which of your approved domains are enabled on each terminal. The Primary terminal always has every approved domain enabled.
3. When you create a payment on a terminal, WaldenPay sends one of that terminal's enabled domains as the merchant_url.

In your API call, merchant_url is optional:

• Omit it and WaldenPay uses the terminal's first enabled domain automatically — no code change is required if your terminal has domains enabled.
• Send it to pick a specific domain when a terminal has several enabled. The value may be a bare host (shop.example.com) or a full URL (https://shop.example.com/checkout); it is normalized to the host. It must be one of that terminal's enabled domains.

Create a payment

Creates a payment and returns a charge token for submitting card data. Call this from your server when the customer starts checkout. The terminal must have at least one enabled domain — see Domains.

Request body

The customer object

Acquiring and anti-fraud rules require a complete payer profile with every payment. All fields below are validated at creation time; the first missing or malformed field is reported in the 422 invalid_customer error message.

Example request

curl https://gw.waldenpay.com/v1/payments \
  -u "wma_your_merchant_id:wk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "reference_id": "order-1001",
    "amount": 42.5,
    "currency": "EUR",
    "test_mode": true,
    "merchant_url": "shop.example.com",
    "callback_url": "https://merchant.example/webhook",
    "return_url": "https://merchant.example/thanks",
    "description": "Order 1001",
    "customer": {
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "[email protected]",
      "phone": "+14155550101",
      "date_of_birth": "1991-02-03",
      "address": {
        "address": "Main Str. 123",
        "city": "Frankfurt",
        "country": "Germany",
        "postal_code": "54321"
      }
    }
  }'

Response 201

{
  "payment": {
    "id": "wpi_k2m4x8p1q9r7s5t3",
    "reference_id": "order-1001",
    "status": "new",
    "is_final": false,
    "reason": null,
    "amount": 42.5,
    "currency": "EUR",
    "amount_paid": null,
    "amount_refunded": null,
    "test_mode": true,
    "description": "Order 1001",
    "metadata": null,
    "card": null,
    "charge": {
      "token": "wgt_7d2f9a1c4e6b8035",
      "url": "https://gw.waldenpay.com/v1/charges"
    },
    "callback_url": "https://merchant.example/webhook",
    "created": 1752566400,
    "updated": 1752566400
  }
}

Store payment.id and use charge.token in the next step. A duplicate reference_id returns 409 duplicate_reference_id.

Charge a card

Submits card data for a payment. Authenticate with the charge token — no Basic auth:

Authorization: Bearer wgt_7d2f9a1c4e6b8035

Request body

browser_info fields

Acquiring and anti-fraud rules require the payer's real browser environment with every charge; accurate values improve frictionless 3DS approval rates. Collect them with JavaScript in the payer's browser (the expressions below) and pass them through unchanged. All fields are validated; the first missing or malformed field is reported in the 422 invalid_browser_info error message.

Example request

curl https://gw.waldenpay.com/v1/charges \
  -H "Authorization: Bearer wgt_7d2f9a1c4e6b8035" \
  -H "Content-Type: application/json" \
  -d '{
    "card_number": "4242424242424242",
    "card_holder": "JANE DOE",
    "cvv": "111",
    "exp_month": "12",
    "exp_year": "99",
    "browser_info": {
      "accept_header": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
      "color_depth": 24,
      "java_enabled": false,
      "language": "en-US",
      "screen_width": 1920,
      "screen_height": 1080,
      "timezone": "Europe/Berlin",
      "user_agent": "Mozilla/5.0 ...",
      "window_width": 1920,
      "window_height": 1000
    }
  }'

Response 200

{
  "status": "processing",
  "is_final": false,
  "reason": null,
  "requires_action": true,
  "action": {
    "url": "https://gw.waldenpay.com/v1/continue/wpi_k2m4x8p1q9r7s5t3/challenge",
    "method": "POST",
    "params": { "creq": "eyJ0aHJlZURTU2VydmVy..." }
  }
}

3D Secure flow

When a charge returns requires_action: true, render the action as an auto-submitting form in the customer's browser: send action.params to action.url via action.method. Param names vary by acquirer — always iterate over whatever params contains.

<form id="challenge" action="{action.url}" method="{action.method}">
  <!-- one hidden input per entry in action.params -->
  <input type="hidden" name="creq" value="..." />
</form>
<script>document.getElementById("challenge").submit();</script>

After the customer completes the challenge they are returned to your return_url. The final result is delivered by webhook — always confirm the outcome server-side rather than trusting the browser redirect.

Retrieve a payment

Fetches the live payment status. Use either the WaldenPay payment ID or your own reference_id. Both return { "payment": … } in the same shape as payment creation.

curl https://gw.waldenpay.com/v1/payments/wpi_k2m4x8p1q9r7s5t3 \
  -u "wma_your_merchant_id:wk_your_api_key"

Payment statuses

Only status determines the outcome. reason is a lower-case failure/decline code (e.g. insufficient_funds, invalid_cvv) or null.

Webhooks

On every status change WaldenPay POSTs to the payment's callback_url (falling back to your default callback URL):

{
  "event": "payment.updated",
  "payment": {
    "id": "wpi_k2m4x8p1q9r7s5t3",
    "reference_id": "order-1001",
    "status": "succeeded",
    "is_final": true,
    "amount": 42.5,
    "currency": "EUR"
  }
}

Verifying signatures

Every webhook carries an X-Signature header computed over the exact raw request body with your callback signing secret (ws_…):

X-Signature = base64( sha1( secret + rawBody + secret ) )

const crypto = require("node:crypto");

function verifySignature(secret, rawBody, header) {
  const expected = crypto
    .createHash("sha1")
    .update(secret + rawBody + secret)
    .digest("base64");
  return expected === header;
}

Delivery semantics

• Respond 200 to acknowledge. Any other status is retried with a linearly increasing delay (1 minute, 2 minutes, 3 minutes...), up to 50 attempts.
• Respond 429 to permanently stop delivery for that event.
• Webhooks may arrive duplicated or out of order — deduplicate per delivery and order by payment.updated.

Testing

Pass "test_mode": true when creating a payment to run the whole flow against the test environment — test payments never move funds and never affect balances.

Never use real card numbers in test mode, and never send live orders through test payments. Use only the test cards below.

Test cards

Test cards come in batches matching the processing configuration of your account: the EUR batch for EUR accounts, and one of the two USD batches (A or B) for USD accounts — your account manager can confirm which one applies to each of your terminals. Cards from a batch that doesn't match your account are simply declined.

EUR batch

All EUR test cards share the same expiry and CVV: expiry 12/2099 (send exp_month: "12" and exp_year: "99" or "2099") and CVV 111. The card number selects the scenario:

Any other card number (or a wrong CVV/expiry) is declined without 3DS. The four decline cards each return a distinct reason code with the failed status, so you can exercise your decline handling (including any Payment Retry logic).

USD batch A

* Use any valid expiry except 07/77. Expiry 07/77 leaves the payment in a transitional processing status on reconciliation — useful for testing your pending-payment handling.

** With the failing USD cards, the expiry date selects the decline reason returned with the failed status, so you can exercise each decline path (including your Payment Retry logic). Any expiry not listed below returns general_fatal_error.

USD batch A: decline reasons by expiry date

USD batch B

All USD batch B cards accept any CVV and any future expiry. Successful test deposits must stay below 10,000,000. The card number selects the scenario:

What to test before going live

• A successful 3DS payment (challenge form rendering and return flow).
• A successful frictionless (non-3DS) payment.
• Several declines — each decline card / expiry surfaces a different reason with status: "failed".
• Webhook signature verification, deduplication and out-of-order delivery.
• A payment that stays in processing before settling (EUR batch: 3434 3434 3434 0000; USD batch A: expiry 07/77) — poll or wait for the webhook.

Errors

All errors share one envelope:

{
  "error": {
    "code": "invalid_amount",
    "message": "'amount' must be a positive number"
  }
}