Skip to content
GiftUdevelopers
⌘ K
GuidesAPI referencev1.0.1

Orders / API v1

Purchase a card

POST/api/partner/v1/orders

Creates exactly one card order. partnerReference is the case-sensitive idempotency identity; replay the same body after an ambiguous transport outcome. This operation does not accept or require an Idempotency-Key header. Price is resolved again in the server transaction before charge.

Authentication

Authorization: Bearer <PARTNER_API_KEY>

Keys, environments, and IP policy
Keep the same purchase identity on retry

Persist partnerReference and sku before sending. Resending with a new reference can create another purchase.

Read the retry guide

Request body application/json

partnerReferencestringrequired

Case-sensitive purchase idempotency identity.

min length: 1 · max length: 100

^[A-Za-z0-9._:-]+$

skustringrequired

min length: 1 · max length: 100

Response

New order or exact replay of the original order.

Cache-Control no-store

dataobjectrequired
Show fields
orderobjectrequired
Show fields
orderobjectrequired
Show fields
orderIdstringrequired

uuid

partnerReferencestringrequired
statusstringrequired

"PROCESSING" · "COMPLETED" · "FAILED"

totalMinorintegerrequired

int64 · min: 1 · max: 9007199254740991

currencystringrequired

"SAR"

skustringrequired
productNameArstringrequired
productNameEnstringrequired
chargedPriceMinorintegerrequired

int64 · min: 1 · max: 9007199254740991

chargedCurrencystringrequired

"SAR"

faceValuestring | nullrequired

Frozen original provider denomination when supplied, not the charged SAR price. SKU-only OneCard orders may return null.

faceValueCurrencystring | nullrequired

Paired with faceValue; both fields are null when denomination metadata is unavailable.

min length: 3 · max length: 3

supportReferencestring | nullrequired
pollAfterSecondsinteger | nullrequired

Always non-null while status is PROCESSING, including manual review.

min: 1

createdAtstringrequired

date-time

updatedAtstringrequired

date-time

completedAtstring | nullrequired

date-time

howToUseArstringrequired
howToUseEnstringrequired
credentialsobject | nullrequired

Null until fulfillment completes; populated credentials match OrderCredentials.

Show fields
serialstring | nullrequired
pinstring | nullrequired
usernamestring | nullrequired
replayedbooleanrequired
requestIdstringrequired
errorobject | nullrequired

null

Need help with your integration?Talk to the GiftU team