Refunds

Returns a payment's asset to its payer, from your available balance: by default all it credited (before Nowgate's fee, which Nowgate keeps) less its other refunds. The network fee comes out of the refund unless you pay it (fee_paid_by: merchant). Without the payer's address, the refund waits in awaiting_address with a refund_url you send them, where they give it once. Their address then waits like any new destination before it is paid: 24 hours in live.

await nowgate.refunds.create(id, { … });

client.refunds.create(id, …)

$nowgate->refunds->create($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

• amountAmount (string)

  By default, all the payment can still return.

• addressstring

  The payer's address, when you have it; without it they give it on the refund's page.

  1 to 128 characters.

• 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

  1 to 28 characters.

• fee_paid_byPayoutFeePaidBy (string)

  payee by default: the network fee comes out of the refund.

  One of: merchant, payee.

• external_idstring

  1 to 100 characters.

• webhook_urlstring
• metadatamap of string

Responses

await nowgate.refunds.retrieve(id);

client.refunds.retrieve(id)

$nowgate->refunds->retrieve($id);

Path parameters

• idRefundID (string)required

Responses

await nowgate.refunds.list({ … });
for await (const item of nowgate.refunds.listAll({ … })) { … }

client.refunds.list(…)
for item in client.refunds.list_all(…): …

$nowgate->refunds->list([…]);
foreach ($nowgate->refunds->listAll([…]) as $item) { … }

Query parameters

• limitinteger

  From 1 to 100. Default: 20.

• starting_afterRefundID (string)

  Return the page after (older than) this ID.

• ending_beforeRefundID (string)

  Return the page before (newer than) this ID.

• paymentPaymentID (string)

  Only this payment's refunds.

• statusPayoutStatus (string)

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

Responses

Cancels a refund that hasn't been signed yet, from any status before sending, and returns its amount to your available balance.

await nowgate.refunds.cancel(id);

client.refunds.cancel(id)

$nowgate->refunds->cancel($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

• idRefundID (string)required

Responses

Nowgate POSTs refund.created, then refund.<status> on every change of a refund's status, signed and retried as payment events are. A refund with its own webhook_url sends its events there instead. The payment gets payment.refunded once its refunds return all it credited.

Headers

• Nowgate-Signaturestringrequired
• Nowgate-Event-IdEventID (string)required

Body

• idEventID (string)required
• object"event"required
• typestringrequired

  refund.created or refund.<status>.

  Example: "refund.finished".

• api_versionstringrequired

  Example: "2026-11-01".

• environmentstringrequired

  One of: live, sandbox, dev, test.

• created_atTimestamp (string (date-time))required
• dataobjectrequired
  1 fields

  • objectRefund (object)required
    24 fields of Refund

    • idRefundID (string)required
    • object"refund"required
    • paymentPaymentID (string)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 payer gets.

    • network_feeAmount (string)required

      The network fee, quoted in this asset when the refund 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)

      The payer's address, once given.

      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))
    • refund_urlstring

      While it is awaiting_address, the page where the payer gives their address. Send it to them.

    • waiting_reasonstring

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

      One of: liquidity, gas_funding, fees, signer_limit.

    • failure_reasonstring

      Present on a failed refund.

    • external_idstring
    • 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.

Responses

• idRefundID (string)required
• object"refund"required
• paymentPaymentID (string)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 payer gets.

• network_feeAmount (string)required

  The network fee, quoted in this asset when the refund 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)

  The payer's address, once given.

  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))
• refund_urlstring

  While it is awaiting_address, the page where the payer gives their address. Send it to them.

• waiting_reasonstring

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

  One of: liquidity, gas_funding, fees, signer_limit.

• failure_reasonstring

  Present on a failed refund.

• external_idstring
• 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.