Payments API
All payment endpoints live under /api/apps/{appId}/payments on https://api.paymenthood.com. {appId} is your App ID and every call needs the Authorization header.
Create a hosted-page payment
The usual starting point: creates a payment and returns a redirectUrl for the PaymentHood checkout page, where the customer chooses a provider and pays.
Minimum request
This is the smallest body that creates a working checkout. Everything else is optional and layers on top of it.
{
"referenceId": "1f8c3b52-2a4e-4d61-9f0b-7c2f5a9e4d10",
"amount": 1,
"returnUrl": "https://your-store.example/checkout/return",
"currency": "USD",
"autoCapture": false,
"showPayRecurringInCheckout": true,
"customerOrder": {
"customer": {
"customerId": "66d99d177234"
}
}
}
referenceId is the idempotency key. It must be unique across your app — PaymentHood will not create a second payment for a value it has already seen. Send a value you can regenerate deterministically (your order number) or a GUID you store with the order, and retrying a failed create is then safe.
Required fields
| Parameter | Type | Description |
|---|---|---|
referenceId |
string | Your order identifier, and the idempotency key. Unique per app; also how you fetch the payment later. |
amount |
number | Total to charge, as a decimal in major units with up to two decimal places — 10.23, 20.00, 1. Not minor units: do not send cents. |
currency |
string | Three-letter code from the supported currencies. |
returnUrl |
string | Where the checkout sends the customer's browser when they finish. Without it they have nowhere to land. |
autoCapture |
boolean | true captures as soon as the payment is authorised; false authorises only and you capture later. |
showPayRecurringInCheckout |
boolean | Whether the checkout offers the customer a recurring/save-my-method option. |
customerOrder.customer.customerId |
string | Your identifier for the buyer. Reuse it across orders and they build up one customer record with reusable payment methods. |
Optional fields
| Parameter | Type | Description |
|---|---|---|
webhookUrl |
string | Per-payment webhook endpoint. Falls back to the app-level URL configured in the Console. |
registerAutoPayment |
boolean | Store the payment method for later charges without the customer present. Defaults to false; see auto payments. |
expirationTime |
string | ISO-8601 instant after which the checkout link stops working. |
paymentProfiles |
integer[] | Restrict the checkout to specific provider profiles. Omit to offer everything active on the app. |
checkoutMethods |
string[] | Restrict which payment method types appear — CreditCard, ElectronicCheck, Crypto, Paypal. |
fraudPolicyId |
integer | Apply a specific fraud policy instead of the app default. |
customerOrder.* |
object | Buyer contact detail and the basket breakdown — see below. Providers use it for risk scoring and receipts. |
customerOrder
| Field | Type | Required | Description |
|---|---|---|---|
customer.customerId |
string | Yes | The one required member — your identifier for the buyer. |
customer.firstName, lastName, email, phoneNumber |
string | No | Buyer contact detail shown on the checkout and passed to the provider. |
orderId |
string | No | Order number as the buyer sees it. |
description |
string | No | Shown on the checkout page and in the Console. |
amount.total, shipping, totalTax, discount, handling, insurance |
number | No | Order breakdown. Some providers require it to itemise the charge. |
amount.items[] |
array | No | Line items: name, amount, quantity and category (DigitalGoods or PhysicalGoods) are required per item; sku, tax and description are optional. |
Create a payment
Creates a payment without pre-selecting the hosted checkout flow, and returns the same payment object. It takes referenceId, amount, currency, customerOrder, autoCapture and registerAutoPayment; the checkout-only fields (showPayRecurringInCheckout, paymentProfiles, checkoutMethods) do not apply here.
A companion endpoint, POST /api/apps/{appId}/payments/provider-hosted-page, sends the customer straight to one provider's own hosted page; it takes the same fields plus a required paymentProfileId naming that provider profile.
Capture an authorised payment
Settles a payment that was authorised with autoCapture: false. {paymentId} is the numeric paymentId from the create call — not your referenceId.
curl -X POST https://api.paymenthood.com/api/apps/YOUR_APP_ID/payments/90210/capture \ -H "Authorization: Bearer YOUR_API_KEY"
The payment moves through Capturing to Captured; a webhook is sent for each state change. Authorisations expire — capture within the window your provider allows, or the funds are released.
Retrieve a payment by your reference
Looks a payment up by the referenceId you supplied — your order number — so you never have to store ours. GET /api/apps/{appId}/payments/{paymentId} does the same by numeric id.
This is the call to make when a webhook arrives: the webhook tells you something changed, this tells you what is true now.
curl "https://api.paymenthood.com/api/apps/YOUR_APP_ID/payments/referenceId:order-1001" \ -H "Authorization: Bearer YOUR_API_KEY"
Response (abridged)
{
"appId": "YOUR_APP_ID",
"paymentId": 90210,
"paymentState": "Captured",
"paymentStateId": 7,
"amount": 20.00,
"capturedAmount": 20.00,
"referenceId": "order-1001",
"currency": "USD",
"autoCapture": true,
"autoPayment": "None",
"fraudStatus": "Verified",
"customerId": "cus-42",
"payerIp": "203.0.113.9",
"createdTime": "2026-08-03T09:15:00Z",
"payInfo": {
"providerReferenceId": "PROVIDER-REF-123",
"authorizeId": "AUTH-123",
"captureId": "CAP-456",
"providerFee": 0.88,
"paymentProfile": {
"paymentProfileId": 12,
"paymentProfileName": "Stripe USD",
"paymentMethodTypeString": "CreditCard",
"isActive": true
},
"payer": {
"fullName": "Ada Lovelace",
"email": "[email protected]",
"country": "GB",
"card": { "cardBrand": "visa", "cardType": "Credit", "cardExpiryMonth": 12, "cardExpiryYear": 2029 }
}
}
}
Card data in payer.card is limited to non-sensitive metadata — brand, type and expiry. The full number is never stored by PaymentHood and never returned by the API.