Record Payment Results

Treat the Wallet API transaction as the source of truth for payment completion. A network timeout or missing create response does not prove that the transfer failed.

Confirm by transaction ID

When the create response returned a withdrawal_id, retrieve the transaction directly.

payment_result="$(wallet_request GET "/withdrawals/$PAYMENT_WITHDRAWAL_ID")"
printf '%s\n' "$payment_result" | jq

Mark the order as paid only when both status and user_status are COMPLETED and request_type is INTERNAL.

Recover a lost create response

If the request timed out before your backend received withdrawal_id, query the original client_request_id. Do not create a second payment with a new ID.

payment_recovery_response="$(
  wallet_request GET "/withdrawals/client-request/$PAYMENT_REQUEST_ID"
)"

export PAYMENT_WITHDRAWAL_ID="$(
  printf '%s' "$payment_recovery_response" | jq -r '.data.withdrawal_id'
)"

wallet_request GET "/withdrawals/$PAYMENT_WITHDRAWAL_ID" | jq

Use client_request_id for response-loss recovery and business idempotency tracking. Use withdrawal_id for detailed transaction state.

Verify the recovery response's success and withdrawal_id before querying detail. A single WITHDRAWAL_NOT_FOUND response is not grounds for a new payment: the original request may still be processing. Keep the original request ID, repeat the lookup at bounded intervals, and follow Idempotency and Duplicate Prevention if it remains unresolved.

Persist the payment record

Store at least:

Field	Purpose
Your order ID	Joins the wallet transaction to the business order
client_request_id	Prevents and recovers duplicate payment submissions
withdrawal_id	Retrieves authoritative transaction status
Customer and merchant account IDs	Preserves transfer direction
Asset, amount, and final status	Supports reconciliation
Completion time	Supports settlement and reporting

After completion, verify both balances as a consistency check.

wallet_request GET "/accounts/$USER_ACCOUNT_ID/balances/$ASSET_TYPE_ID" | jq
wallet_request GET "/accounts/$PAYMENT_ACCOUNT_ID/balances/$ASSET_TYPE_ID" | jq

Do not determine a single order's result from balance differences alone; concurrent payments can change both balances.

Next: Settle to an external address.