POST
Record an indirect tip — a passenger tipped this goal's owner on the platform's own surface, and we recover it through the owner's mandate. INDIRECT contributor-token auth: the tenant comes from the token, never the body.

Headers

x-user-id
string | null

The beneficiary, when the contributor token is not bound to one. Ignored when the token names its own.

Path Parameters

goal_id
string
required

Goal UUID

Body

application/json
amount
object
required

Represents a monetary amount with its associated currency

external_reference_id
string
required

Response

Tip intent recorded (or the existing order for this reference)

account_id
string
required
amount
object
required

Represents a monetary amount with its associated currency

created_at
string
required
goal_credited
boolean
required
id
string
required
initial_order_id
string
required
last_modified_at
string
required
medium
enum<string>
required

How an order's money moves — the settlement rail, orthogonal to source (whose money). PAYMENT = a user-initiated Juspay collect (manual self top-up); MANDATE = a debit against the user's registered mandate (scheduled autopay, and tips); SPONSOR = an internal PBA transfer from the sponsor's account. Autopay-self and tip share MANDATE and split on source; the credit doorbell keys the goal leg off source, not medium.

Available options:
PAYMENT,
MANDATE,
SPONSOR
metadata
object
required

Typed wrapper over the orders.metadata jsonb column, also returned verbatim as OrderResponse.metadata.

payment_method_type / payment_method are filled later from Juspay's order-status response.

The Juspay /session blob is deliberately absent. The frontend needs it once, to open the payment page, so the create response carries it straight from the session call as OrderResponse.payload; nothing reads it back afterwards, and storing it only parked a large provider blob per order.

retry_count
integer<int32>
required
source
string
required
status
enum<string>
required

Local lifecycle status of an order, independent of the provider's external_status (Juspay vocabulary). Inserted as Initiated before the Juspay /session call so the row is always traceable, advances to Pending once the session is created, and lands on Success/Failed from the first terminal poll. See From<&ExternalOrderStatus> for the provider-status mapping.

Three states are tip-only and sit outside that arc. Expressed precedes Initiated: a contributor has declared a tip, but the upstream has not finished so nothing is collectable yet. Declined is terminal and no provider status can produce it — the upstream finished without the tip being collected, which is distinct from Failed (a collection was attempted and refused) and from ExternalOrderStatus::JuspayDeclined (a declined payment). RecoveryFailed is the one that matters operationally: the tip WAS collected upstream and already sits in the beneficiary's platform earnings, but the mandate debit that recovers it onto the goal failed. Unlike Failed, where no money moved anywhere, this leaves a real-world imbalance — the money exists, we could not retrieve it — so it is a distinct state a follow-up can act on rather than a generic failure. Backed by a Postgres enum: adding a variant needs an ALTER TYPE ... ADD VALUE migration alongside the Smithy edit.

Available options:
EXPRESSED,
INITIATED,
PENDING,
SUCCESS,
FAILED,
DECLINED,
RECOVERY_FAILED
user_id
string
required

A validated 12-digit numeric user identifier.

Every external entry point validates:

  • JSON Deserialize runs [UserId::parse] (outer whitespace trimmed, length and digit-only enforced) via #[serde(try_from = "String")].
  • DB FromSql runs [UserId::parse] on every row read.

Display / Deref<Target = str> / AsRef<str> / Into<String> are derived via derive_more — the inner String is pass-through for every read-only borrow, display, and move-out.

Example:

"012345678901"

wallet_txn_data
object
required

Lifecycle status of the wallet-side transaction attached to an order.

Wallet-agnostic — today PBA, tomorrow any other wallet integration. The lifecycle has five observable states:

  • Initiated — order row inserted; no wallet call has been made yet. Set at row create-time. Single-phase (interactive add-money) advances straight to Success; two-phase (mandate-autopay) advances to Pending.
  • Pending(deposit_id) — two-phase Phase 1 succeeded: the wallet provider accepted the deposit and returned its id, but it is still parked on the provider side waiting for an external settlement signal. Carried between the Juspay /txns ack and the /orders/{id}=Charged reconciliation.
  • Success(deposit_id) — terminal: the deposit has been finalised at the wallet provider (Phase 2 confirm, or single-phase commit). The provider's id is the single dedup signal for any further status poll.
  • Voided(deposit_id) — terminal: a parked Pending deposit was explicitly released back to the source because the originating charge reached a terminal failure. The provider's id is preserved for audit.
  • Failed — terminal: the originating charge failed before any wallet-side deposit was held (Phase 1 never ran or itself failed).

Serialized to text as:

  • initiated → Initiated
  • pending:<deposit_id> → Pending(deposit_id)
  • success:<deposit_id> → Success(deposit_id)
  • voided:<deposit_id> → Voided(deposit_id)
  • failed → Failed
external_reference_id
string | null
external_status
string | null
goal_id
string | null
job_id
string | null
latest_retry_order_id
string | null
payload
any