Generate a hosted payment gateway URL for a gift card purchase.
Header Parameters
Optional client-generated unique key (UUID v4 recommended) that lets Spendstream safely ignore duplicate submissions of this state-changing request. Retries using the same key within 24 hours return the original response rather than re-processing.
Media type the client can parse. Always application/json for this API.
application/jsonBody Parameters
End-user UID. From PR
End-user display name. Used to auto-create the user if user_id is not already registered against your publisher (PR
End-user email. Used to auto-create the user if user_id is not already registered against your publisher (PR
User consent indicator.
ISO 4217 currency code.
Monetary amount in the specified currency — the face value the end-user receives.
Response
Hosted payment URL returned. Redirect the user to payment_link.
Response Attributes
Hosted payment-gateway URL. Redirect the user to this URL; they complete payment there.
Echoes the HTTP status code.
Spendstream's internal order ID, retained for reconciliation.
For publishers with a discount-type configuration (PR #355), the amount the end-user is actually charged at checkout after the applicable commission is deducted from amount. For non-discount publishers this equals amount. Emitted from PR #355 onwards.
Request failed validation. Body shape is {"message": "<reason>"}; the message
distinguishes the specific failure. Most common is "no valid user" — the user_id
is not registered under your publisher (call POST /addNewUser first).
Response Attributes
Human-readable failure reason. Safe to surface to integrators but not end-users.
Alternative error message field used by a subset of endpoints (notably getToken
and authentication failures). Integrators should check for both message and
error when parsing failure responses.
Numeric status code echoing the HTTP status (e.g. 400, 401). Populated on
most error paths; a few auth-layer failures omit it.
Authentication failed. Common causes: missing Authorization header, malformed bearer
token, token expired (tokens live 10 hours), or — on getToken itself — HMAC signature
mismatch due to clock drift or wrong secret.
Response Attributes
Human-readable failure reason. Safe to surface to integrators but not end-users.
Alternative error message field used by a subset of endpoints (notably getToken
and authentication failures). Integrators should check for both message and
error when parsing failure responses.
Numeric status code echoing the HTTP status (e.g. 400, 401). Populated on
most error paths; a few auth-layer failures omit it.
Rate limit exceeded. The POST /getToken endpoint is rate-limited to five requests
per minute per source IP; other endpoints may be throttled at the reverse-proxy layer
in response to abusive traffic. Wait and retry with exponential backoff; the
Retry-After header tells you the minimum wait in seconds.
Response Attributes
Human-readable failure reason. Safe to surface to integrators but not end-users.
Alternative error message field used by a subset of endpoints (notably getToken
and authentication failures). Integrators should check for both message and
error when parsing failure responses.
Numeric status code echoing the HTTP status (e.g. 400, 401). Populated on
most error paths; a few auth-layer failures omit it.
Response