Quick Start Guide

Take a sandbox payment end to end in about five minutes.

1. Get your App ID and API key

Create an account in the PaymentHood Console (opens in new tab), add a payment provider profile, and copy the credentials for the app you want to use:

  • App IDIdentifies your app; it is part of every API path.
  • API keySent as a bearer credential in the Authorization header.

Sandbox and live are separate apps with separate IDs, API keys and provider configuration — see Environments.

2. Create a payment

Post your order to the hosted-page endpoint. referenceId is your own order number, and it doubles as the idempotency key — it must be unique within your app.

cURL
curl -X POST https://api.paymenthood.com/api/apps/YOUR_APP_ID/payments/hosted-page \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "referenceId": "order-1001",
    "amount": 20.00,
    "currency": "USD",
    "returnUrl": "https://your-store.example/checkout/return?order=1001",
    "autoCapture": true,
    "showPayRecurringInCheckout": false,
    "customerOrder": {
      "customer": {
        "customerId": "cus-42"
      }
    },
    "webhookUrl": "https://your-store.example/paymenthood/webhook"
  }'

Those are the required fields plus webhookUrl. Buyer contact detail, a basket breakdown, provider restrictions and stored-method registration are all optional — see Payments API.

3. Send the customer to the checkout page

A successful call returns 201 Created with the payment and its redirectUrl. Redirect the browser there; PaymentHood renders the checkout, the customer picks a provider, and we return them to your returnUrl.

JSON
{
  "appId": "YOUR_APP_ID",
  "paymentId": 90210,
  "paymentState": "Created",
  "paymentStateId": 1,
  "amount": 20.00,
  "capturedAmount": 0,
  "referenceId": "order-1001",
  "currency": "USD",
  "autoCapture": true,
  "paymentFlow": "HostedPage",
  "autoPayment": "None",
  "fraudStatus": "Unknown",
  "redirectUrl": "https://checkout.paymenthood.com/...",
  "returnUrl": "https://your-store.example/checkout/return?order=1001",
  "webhookUrl": "https://your-store.example/paymenthood/webhook",
  "createdTime": "2026-08-03T09:15:00Z"
}

Never treat the return URL as proof of payment. The customer's browser can be closed, refreshed or replayed. The webhook — and the API read that follows it — is the only authoritative signal.

4. Confirm the payment

When we notify you, read the payment back by your own order number and act on the state you get from the API:

cURL
curl https://api.paymenthood.com/api/apps/YOUR_APP_ID/payments/referenceId:order-1001 \
  -H "Authorization: Bearer YOUR_API_KEY"

A Captured state means the money is settled with the provider and the order can be fulfilled. The full list is in Payment States.