NowgateDocs

Sandbox

Simulate what payers do without testnet coins, and payouts without a chain.

On this page

In the sandbox, every case a payer can cause is one call away: paying, paying too little or too much, paying again, sending the wrong asset, paying late, and running out of time. See testing in the sandbox.

Payouts and refunds in the sandbox are simulated too. They go through the same API, limits, reservations, statuses and webhooks as live ones, but no chain: a payout is sending at once, with a sim: transaction hash, and finished about 10 seconds later. Its network fee is a fixed notional amount. The sandbox's balance is its simulated deposits, so a balance that came from a real testnet deposit can't be paid out there: such a payout fails with simulated_funds_insufficient. A new destination waits 5 minutes, or activate it at once.

Simulate a payer#

POST/v1/sandbox/payments/{id}/simulateAPI key, payments scope

In the sandbox (and dev and test), makes up what a payer does to one of your payments, so you can test every case without testnet coins. A simulated deposit is pending at first and settles about 10 seconds later; from then on it is processed like any deposit, with the same statuses, credits and webhooks. Simulated money is never swept. In live this route doesn't exist: 404.

await nowgate.sandbox.simulatePayment(id, { … });

Headers

  • Idempotency-Keystringrequired

    A unique key for this request, such as a UUID: 1-255 visible ASCII characters, without spaces. Retrying with the same key and the same request replays the original response (for at least 24 hours); the same key with a different request is refused with 422 idempotency_key_reused. Failed requests are not stored, so they can be retried with the same key.

    1 to 255 characters. Pattern: ^[!-~]+$.

Path parameters

  • idPaymentID (string)required

Body

  • actionstringrequired

    pay: a deposit of exactly what is due. underpay and overpay: short or over by amount, or by half. repeat: a second deposit after the payment finished. wrong_asset: another asset of the network to the payment's address, which goes to suspense. late: the payment expires now, then what was due arrives. expire: the payment expires now.

    One of: pay, underpay, overpay, repeat, wrong_asset, late, expire.

  • amountAmount (string)

    In the payment's asset (the other asset's, for wrong_asset).

Responses

202 Done; a deposit, if any, settles shortly.

The Simulation object
  • object"simulation"required
  • actionstringrequired
  • paymentPayment (object)required

    The Payment object

  • depositobject

    The simulated deposit, when the action made one.

    3 fields
    • assetAssetSymbol (string)required

      Asset symbol on the network; see GET /assets.

    • amountAmount (string)required

      A non-negative decimal amount in the asset's units, e.g. "12.5".

    • settles_atTimestamp (string (date-time))required

4xx, 5xx An error, as problem details.

Fail a payout#

POST/v1/sandbox/payouts/{id}/simulateAPI key, payouts scope

In the sandbox, where payouts are simulated (sent at once, finished about 10 seconds later, and never on a chain), fails one of your payouts that hasn't finished: one waiting or scheduled, or one within its 10 seconds of sending. Its amount and fees return to your available balance, and payout.failed is sent, with failure_reason simulated_failure. Where payouts are sent for real, this route doesn't exist: 404.

await nowgate.sandbox.simulatePayout(id, { … });

Headers

  • Idempotency-Keystringrequired

    A unique key for this request, such as a UUID: 1-255 visible ASCII characters, without spaces. Retrying with the same key and the same request replays the original response (for at least 24 hours); the same key with a different request is refused with 422 idempotency_key_reused. Failed requests are not stored, so they can be retried with the same key.

    1 to 255 characters. Pattern: ^[!-~]+$.

Path parameters

  • idPayoutID (string)required

Body

  • actionstringrequired

    fail: the payout fails, and what it reserved is released.

    One of: fail.

Responses

200 The failed payout.

The Payout object
  • idPayoutID (string)required
  • object"payout"required
  • statusPayoutStatus (string)required

    One of: awaiting_address, awaiting_approval, scheduled, waiting_destination, queued, sending, finished, failed, canceled.

  • networkNetwork (string)required

    Network identifier; see GET /assets. New networks may be added.

  • assetAssetSymbol (string)required

    Asset symbol on the network; see GET /assets.

  • amountAmount (string)required

    A non-negative decimal amount in the asset's units, e.g. "12.5".

  • amount_sentAmount (string)required

    What the destination gets.

  • network_feeAmount (string)required

    The network fee, quoted in this asset when the payout was created.

  • payout_feeAmount (string)required

    Nowgate's payout fee.

  • amount_debitedAmount (string)required

    What your balance pays for it.

  • fee_paid_byPayoutFeePaidBy (string)required

    Who pays the network fee: merchant on top of the amount (the destination gets the whole amount), or payee out of it.

    One of: merchant, payee.

  • destinationPayoutDestination (object)required
    12 fields of PayoutDestination
    • idPayoutDestinationID (string)required
    • object"payout_destination"required
    • statusstringrequired

      One of: pending, active, disabled.

    • networkNetwork (string)required

      Network identifier; see GET /assets. New networks may be added.

    • addressstringrequired

      The address in its canonical form.

    • memo_typeMemoType (string)

      A Stellar memo's type. id is a number up to 2^64-1, text at most 28 bytes.

      One of: id, text.

    • memostring
    • labelstring
    • kindstringrequired

      refund when a payer gave it for a refund.

      One of: payout, refund.

    • active_atTimestamp (string (date-time))required

      When it became, or will become, payable.

    • created_atTimestamp (string (date-time))required
    • disabled_atTimestamp (string (date-time))
  • waiting_reasonstring

    Present on a queued payout that is waiting for something on Nowgate's side.

    One of: liquidity, gas_funding, fees, signer_limit.

  • failure_reasonstring

    Present on a failed payout.

  • external_idstring
  • batchPayoutBatchID (string)
  • send_atTimestamp (string (date-time))
  • approved_atTimestamp (string (date-time))
  • transactionstring

    The transaction that carries it

  • metadatamap of stringrequired
  • created_atTimestamp (string (date-time))required
  • updated_atTimestamp (string (date-time))required
  • closed_atTimestamp (string (date-time))
  • versioninteger (int64)required

    Increases with every change; use it to ignore stale webhook events.

4xx, 5xx An error, as problem details.

Activate a destination now#

POST/v1/sandbox/payout-destinations/{id}/activateAPI key, payouts scope

In the sandbox, makes one of your destinations that still waits usable at once, instead of 5 minutes after it was added, and queues the payouts that waited for it. destination.active is sent. Where payouts are sent for real, this route doesn't exist: 404.

await nowgate.sandbox.activatePayoutDestination(id);

Headers

  • Idempotency-Keystringrequired

    A unique key for this request, such as a UUID: 1-255 visible ASCII characters, without spaces. Retrying with the same key and the same request replays the original response (for at least 24 hours); the same key with a different request is refused with 422 idempotency_key_reused. Failed requests are not stored, so they can be retried with the same key.

    1 to 255 characters. Pattern: ^[!-~]+$.

Path parameters

  • idPayoutDestinationID (string)required

Responses

200 The destination, now active.

The PayoutDestination object
  • idPayoutDestinationID (string)required
  • object"payout_destination"required
  • statusstringrequired

    One of: pending, active, disabled.

  • networkNetwork (string)required

    Network identifier; see GET /assets. New networks may be added.

  • addressstringrequired

    The address in its canonical form.

  • memo_typeMemoType (string)

    A Stellar memo's type. id is a number up to 2^64-1, text at most 28 bytes.

    One of: id, text.

  • memostring
  • labelstring
  • kindstringrequired

    refund when a payer gave it for a refund.

    One of: payout, refund.

  • active_atTimestamp (string (date-time))required

    When it became, or will become, payable.

  • created_atTimestamp (string (date-time))required
  • disabled_atTimestamp (string (date-time))

4xx, 5xx An error, as problem details.

The simulation object#

  • object"simulation"required
  • actionstringrequired
  • paymentPayment (object)required

    The Payment object

  • depositobject

    The simulated deposit, when the action made one.

    3 fields
    • assetAssetSymbol (string)required

      Asset symbol on the network; see GET /assets.

    • amountAmount (string)required

      A non-negative decimal amount in the asset's units, e.g. "12.5".

    • settles_atTimestamp (string (date-time))required