Create wallet top up

Path parameters

• currencystringRequired
  The wallet's settlement currency, ISO-4217

Query parameters

• environmentstringOptional
  Which side of the sandbox/production tenant pair to read or act on.Show more

  Which side of the sandbox/production tenant pair to read or act on. An API key is bound to its own side (mo_test_ = SANDBOX, mo_live_ = PRODUCTION): absent means that side, and naming the other is 400 VALIDATION details.reason ENVIRONMENT_MISMATCH. A human session may name either; absent means SANDBOX while the tenant is TRIAL and PRODUCTION once it is LIVE.
  • PRODUCTION
  • SANDBOX

Headers

• Idempotency-KeystringRequired
  Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate…Show more

  Mandatory on mutations: **48h TTL**; replay with same body-hash returns the original response with Idempotency-Replayed true; same key + different body is 409 IDEMPOTENCY_CONFLICT; in-flight duplicate is 409 IDEMPOTENCY_IN_PROGRESS.

Request bodyWalletTopUpRequest

• amountMoneyRequired
  Integer minor units + ISO-4217, never floats (platform law)
  5 child attributes

  • amountintegerRequired
    Minor units
  • currencystringRequired
    ISO-4217
  • fxAppliedbooleanOptional
    True when the amount was converted from the supplier's currency.
  • fxSnapshotIdstringOptional
    The exchange-rate snapshot the amount was converted with, fixed when the price was quoted.
  • breakdownarray of PriceBreakdownLineOptional
    Sell-side component lines summing to amount; the platform may send it empty.Show more

    Sell-side component lines summing to amount; the platform may send it empty. One line shape everywhere — the same PriceBreakdownLine the rule simulation answers. Never carries a supplier net.
    13 child attributes

    • typestringRequired
      The kind of line, for example BASE, TAX, FEE or DISCOUNT.
    • amountintegerRequired
      Minor units
    • feeTypestringOptional
      For FEE lines produced by a FEE_LINE rule — the tenant's fee label
    • labelstringOptional
      Display label in the request locale
    • taxComponentstringOptional
      For GST / TAX lines — CGST | SGST | IGST | UTGST | CESS | VAT | SALES_TAX | OCCUPANCY_TAX; open string
    • taxCodeTaxCodeOptional
      The statutory classification of a taxed line (SAC/HSN in India, VAT codes elsewhere)
      2 child attributes

      • schemestringRequired
        SAC | HSN | VAT | GST | OTHER; open string
      • codestringRequired
        The tax code, for example a SAC or HSN code in India or a VAT code elsewhere.
    • rateBasisPointsintegerOptional
      The tax or fee rate in basis points when the line is rate-based (1800 = 18%)
    • collectedBystringOptional
      PLATFORM | SUPPLIER | PROPERTY — who takes the money; a non-PLATFORM line outside Offer.price is a pay-at-property disclosure
    • payableAtstringOptional
      BOOKING | PROPERTY | DESK | AFTER_SERVICE
    • includedbooleanOptional
      True when the line is inside the enclosing amount (default); false for a disclosed line outside it
    • quantityintegerOptional
      How many units the line covers, when more than one.
    • unitAmountintegerOptional
      Minor units per unit when quantity is given
    • currencystringOptional
      ISO-4217 code of this line's amount and unitAmount.Show more

      ISO-4217 code of this line's amount and unitAmount. Set ONLY on a disclosed line (included false) that is NOT in the enclosing price's currency, for example a resort fee payable at the property in its local currency. Absent means the enclosing price's currency, as before; a line inside the total never carries it.
• paymentMethodPaymentMethodTokenOptional
  A card the CLIENT tokenised with the payment-method vault.Show more

  A card the CLIENT tokenised with the payment-method vault. TOKEN ONLY: this object has no field for a card number, an expiry or a security code, and the platform never receives, stores or logs one. The client collects the card in the vault's own iframe (Spreedly iFrame or Express), receives a payment-method token and sends it here; the platform passes the token to the supplier (Example Dining's credit_card object) and keeps only provider, brand and last4 on the order. A digit run that looks like a card number in ANY field of the request is 400 VALIDATION details.reason INSTRUMENT_DATA_REFUSED (PanGuard), and the token itself is never echoed or logged. threeDs is sent only on the RETRY of an order the supplier refused with details.reason SCA_REQUIRED: the same token plus the result of the 3-D Secure challenge the client ran with the vault.
  6 child attributes

  • providerstringRequired
    The vault that issued the token. Closed on purpose; a new vault is a contract change
    • SPREEDLY
  • tokenstringRequired
    The vault's payment-method token. Treated like a credential; never returned
  • typestringOptional
    The payment method kind (Example Dining paymentMethod); absent = credit_card
    • credit_card
  • last4stringOptional
    The last four digits the vault returned, for display and for the supplier
  • brandstringOptional
    Card brand the vault returned (visa, master, american_express and others)
  • threeDsPaymentThreeDsOptional
    The 3-D Secure / SCA result a client sends when it retries an order that was refused with details.reason SCA_REQUIRED.Show more

    The 3-D Secure / SCA result a client sends when it retries an order that was refused with details.reason SCA_REQUIRED. The client runs the challenge with the vault (Spreedly) using details.intent from the refusal, then retries POST /v1/orders with a NEW Idempotency-Key, the same payment-method token and this object: redirectUrl plus setupIntent when details.retryWith is setupIntent (card-vault SCA), or paymentIntent when it is paymentIntent (payment SCA); mpiData when the client's own MPI authenticated the card. The platform passes these to the supplier and never stores them.
    4 child attributes

    • redirectUrlstring · uriOptional
      Where the vault sent the diner back after the challenge
    • mpiDataobjectOptional
      Authentication data from a merchant plug-in (MPI)
      4 child attributes

      • threeDSVersionstringRequired
        e.g. 2.2.0
      • ecistringRequired
        Electronic Commerce Indicator
      • cavvstringRequired
        SENSITIVE authentication data: the cardholder authentication verification value.Show more

        SENSITIVE authentication data: the cardholder authentication verification value. Passed to the supplier for this one order and never stored, logged, echoed or returned; treated like a credential.
      • dsTransIdstringOptional
        The 3-D Secure directory-server transaction id
    • setupIntentstringOptional
      The vault's setup-intent id (card-vault SCA, details.retryWith setupIntent)
    • paymentIntentstringOptional
      The vault's payment-intent id (payment SCA, details.retryWith paymentIntent)

Responses

• 201Credited (simulated)WalletTopUp
• 400VALIDATION or UNKNOWN_DOMAINApiErrorResponse
• 401
  UNAUTHENTICATED — missing or expired token.Show more

  UNAUTHENTICATED — missing or expired token. Declared on every operation because `security` is declared globally at the document root: every route is authenticated, so every route can answer 401.
  ApiErrorResponse
• 403ApiErrorResponse
• 404NOT_FOUND — unknown or expired ref (unguessable refs, 15)ApiErrorResponse
• 405
  VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge).Show more

  VALIDATION — the public edge serves GET, POST, PUT, PATCH and DELETE only; any other method is refused before the platform sees it (details.reason METHOD_NOT_ALLOWED, details.source edge). Not retryable as sent.
  ApiErrorResponse
• 409IDEMPOTENCY_CONFLICT | IDEMPOTENCY_IN_PROGRESS — the only 409s of a mutation with no domain conflictApiErrorResponse
• 413
  VALIDATION — the request body is larger than the surface's limit.Show more

  VALIDATION — the request body is larger than the surface's limit. Not retryable as sent: shrink the body. Declared on every operation that takes a request body. details carries exactly one key, maxBodyBytes (integer): the limit that applies to this surface, in bytes.
  ApiErrorResponse
• 414
  VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge).Show more

  VALIDATION — the request URI (path and query string) is longer than 8 KiB; the public edge refuses it before the platform sees it (details.reason URI_TOO_LONG, details.source edge). Not retryable as sent: send long input in the body of a POST.
  ApiErrorResponse
• 415
  VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes).Show more

  VALIDATION — a request body that is not JSON (application/json or application/*+json; a form body only on the OAuth token routes). The public edge refuses it before the platform sees it (details.reason UNSUPPORTED_MEDIA_TYPE, details.source edge). Not retryable as sent: send Content-Type application/json. Declared on every operation that takes a JSON request body.
  ApiErrorResponse
• 500INTERNAL — a bug, and traceId is the support handle.ApiErrorResponse
• 501NOT_IMPLEMENTED WALLET_TOPUP_UNAVAILABLE — top-ups are simulated in sandbox only in this phaseApiErrorResponse

Errors you should handle

Branch on code and honour retryable — never on the HTTP status alone.