Process a gift card fulfilment from a pre-existing order in the publisher's database.
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
Your internal order ID. Spendstream reads the order detail from your connected database using this key.
Numeric user ID (not UID).
User's consent to purchase (GDPR).
01Defaults to GBP if omitted.
Monetary amount in the specified currency.
External payment gateway transaction reference.
External payment gateway status.
Human-readable payment type (e.g. Visa, Mastercard).
Machine-readable payment type code.
Response
Gift card issued. Response contains the card URL, reference, face value, and expiry.
Response Attributes
Brand's numeric Spendstream ID.
Human-readable brand name.
Gift-card supplier reference ID. Pass this as transactionid to /giftCardBalanceCheck.
Branded URL where the user views and redeems their gift card.
Cost to the publisher (may differ from face value if there's a discount).
ISO 4217 currency code.
Expiry date/time. Format YYYY-MM-DD HH:MM:SS.
Echoes the HTTP status code.
The gift-card supplier rejected the issuance (insufficient brand stock, invalid denomination, etc.).
Response includes the supplier's error message in message and any partial order context.
Response Attributes
Brand's numeric Spendstream ID.
Human-readable brand name.
Gift-card supplier reference ID. Pass this as transactionid to /giftCardBalanceCheck.
Branded URL where the user views and redeems their gift card.
Cost to the publisher (may differ from face value if there's a discount).
ISO 4217 currency code.
Expiry date/time. Format YYYY-MM-DD HH:MM:SS.
Echoes the HTTP status code.
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