SDP 1644 create direct payment #693

dpohr · 2025-05-30T06:51:36Z

What

Implements POST /payments API endpoint for direct payments to existing receivers without creating disbursements. Adds new "DIRECT" payment type with flexible entity reference system (by ID, email, phone, wallet address) and integrates with existing payment processing pipeline.

Why

Enables on-demand, single payments for API integrations that don't fit the batch disbursement workflow. Critical for use cases like instant payments, manual corrections, and external system integrations that need immediate payment capability without disbursement overhead.

Known limitations

Existing receivers only - does not create new receivers (by design for this iteration)
Contract/Fiat assets - marked as future implementation, returns proper "not supported" errors
Legacy auth - still uses token extraction method (TODO: migrate to API keys when available)

Checklist

Title follows SDP-1234: Add new feature or Chore: Refactor package xyz format. The Jira ticket code was included if available.
PR has a focused scope and doesn't mix features with refactoring
Tests are included (if applicable)
CHANGELOG.md is updated (if applicable)
CONFIG/SECRETS changes are updated in helmcharts and deployments (if applicable)
Preview deployment works as expected
Ready for production

…rect-payment

stellar-jenkins · 2025-05-30T06:55:58Z

Something went wrong with PR preview build please check

stellar-jenkins · 2025-05-30T06:55:58Z

stellar-disbursement-platform-backend-preview is available here:
SDP: https://sdp-backend-pr693.previews.kube001.services.stellar-ops.com/health
AP: https://sdp-ap-pr693.previews.kube001.services.stellar-ops.com/health
Frontend: https://sdp-backend-dashboard-pr693.previews.kube001.services.stellar-ops.com

stellar-jenkins · 2025-05-30T07:26:15Z

stellar-disbursement-platform-backend-preview is available here:
SDP: https://sdp-backend-pr693.previews.kube001.services.stellar-ops.com/health
AP: https://sdp-ap-pr693.previews.kube001.services.stellar-ops.com/health
Frontend: https://sdp-backend-dashboard-pr693.previews.kube001.services.stellar-ops.com

stellar-jenkins · 2025-05-30T07:55:19Z

stellar-disbursement-platform-backend-preview is available here:
SDP: https://sdp-backend-pr693.previews.kube001.services.stellar-ops.com/health
AP: https://sdp-ap-pr693.previews.kube001.services.stellar-ops.com/health
Frontend: https://sdp-backend-dashboard-pr693.previews.kube001.services.stellar-ops.com

stellar-jenkins · 2025-06-02T13:05:21Z

stellar-disbursement-platform-backend-preview is available here:
SDP: https://sdp-backend-pr693.previews.kube001.services.stellar-ops.com/health
AP: https://sdp-ap-pr693.previews.kube001.services.stellar-ops.com/health
Frontend: https://sdp-backend-dashboard-pr693.previews.kube001.services.stellar-ops.com

philipliu · 2025-06-06T17:43:18Z

internal/data/payments.go

+            asset_id,
+            receiver_id,
+            disbursement_id,
+			receiver_wallet_id,


nit: formatting

this keep happening since the default golang linter uses tabs, but current codebase uses spaces, this is not regular choice. I'll fix it, however we need to consider reformat files to be consistent with go style

internal/data/payments.go

philipliu · 2025-06-06T17:57:17Z

internal/data/payments.go

+		insert.Amount,
+		insert.AssetID,
+		insert.ReceiverID,
+		insert.DisbursementID, // Will be NULL


If DisbursementID is null, can we just exclude it from the query?

philipliu · 2025-06-06T18:16:38Z

internal/serve/httphandler/payments_handler.go

+			errToMatch = err
+		}
+
+		switch e := errToMatch.(type) {


Should we be using errors.Is instead?

good idea, but it's better to use .As() then, will fix it, thank you

philipliu · 2025-06-06T18:26:10Z

internal/serve/httphandler/payments_handler.go

+			httperror.BadRequest(e.Error(), err, nil).Render(w)
+
+		default:
+			if strings.Contains(err.Error(), "receiver wallet not found") {


Matching against the receiver wallet not found string seems brittle. Is there a way to avoid this?

philipliu · 2025-06-09T14:29:56Z

internal/services/direct_payment_service_test.go

+				err = unwrapTransactionError(err)
+				var walletErr WalletNotEnabledError
+				assert.True(t, errors.As(err, &walletErr))
+				assert.Contains(t, err.Error(), "Calth Reserve")


nit: Can we replace this with assert.Contains(t, err.Error(), &disabledWallet.Name), so it's clear that this is the disabled wallet?

philipliu · 2025-06-09T14:31:53Z

internal/services/direct_payment_service_test.go

+				var assetErr AssetNotSupportedByWalletError
+				assert.True(t, errors.As(err, &assetErr))
+				assert.Contains(t, err.Error(), "XLM")
+				assert.Contains(t, err.Error(), "Macragge Treasury")


nit: Can we replace Macragge Treasury with &enabledWallet.Name?

philipliu · 2025-06-09T14:36:07Z

internal/services/direct_payment_service.go

+		return fmt.Errorf("parsing amount: %w", err)
+	}
+
+	// Skip balance validation for user-managed wallets since they manage their own balance


Do we also skip this validation for the regular disbursement flow? I'm wondering why we skip the validation if the account is managed outside of SDP.

Additionally, can we refer to this as something other than "user-managed wallet" in both this comment and the test cases? It sounds like we are validating the balances of the receiver wallets, otherwise.

philipliu · 2025-06-09T14:41:28Z

internal/services/direct_payment_service_test.go

+				// Create user-managed wallet
+				userManagedWallet := data.CreateWalletFixture(t, ctx, dbConnectionPool, "User Wallet", "stellar.org", "stellar.org", "stellar://")
+				data.MakeWalletUserManaged(t, ctx, dbConnectionPool, userManagedWallet.ID)
+
+				// Create receiver wallet with specific address
+				rw := data.CreateReceiverWalletFixture(t, ctx, dbConnectionPool, receiver.ID, userManagedWallet.ID, data.RegisteredReceiversWalletStatus)
+
+				// Update with the specific stellar address
+				stellarAddress := "GBXGQJWVLWOYHFLVTKWV5FGHA3LNYY2JQKM7OAJAUEQFU6LPCSEFVXON"
+				err := models.ReceiverWallet.Update(ctx, rw.ID, data.ReceiverWalletUpdate{
+					StellarAddress: stellarAddress,
+				}, dbConnectionPool)
+				require.NoError(t, err)


I thought "user-managed wallet" refers to the distribution account being managed outside of SDP. Does the receiver wallet, which is also user-managed, affect the test?

philipliu · 2025-06-09T14:42:55Z

internal/services/direct_payment_service_test.go

+			expectedAmount: 50.00,
+		},
+		{
+			name: "terminal and draft statuses ignored",


Can this test be merged with sum for all in-progress statuses?

marwen-abid

Lots of great stuff in this PR. This is my first stab at a review, will add more comments as I test this more.

marwen-abid · 2025-06-03T18:04:57Z

db/migrations/sdp-migrations/2025-05-23.1-alter-disbursment-id-constraint.sql

+ADD CONSTRAINT check_payment_type_disbursement 
+CHECK (
+    (payment_type = 'DISBURSEMENT' AND disbursement_id IS NOT NULL) OR
+    (payment_type = 'DIRECT' AND disbursement_id IS NULL)


nice! Thank you for adding this check

marwen-abid · 2025-06-09T21:28:03Z

db/migrations/sdp-migrations/2025-05-23.0-add-payment-type-column copy.sql

Name of this file has copy at the end. Also please make sure when merging these PRs that the date in the name of the file remains chronological.

marwen-abid · 2025-06-09T22:25:30Z

internal/services/direct_payment_service.go

+	"github.com/stellar/stellar-disbursement-platform-backend/stellar-auth/pkg/auth"
+)
+
+// DirectPaymentRequest represents service-level request for creating direct payment


Suggested change

// DirectPaymentRequest represents service-level request for creating direct payment

// CreateDirectPaymentRequest represents service-level request for creating direct payment.

marwen-abid · 2025-06-09T23:03:32Z

internal/services/direct_payment_service.go

+func (s *DirectPaymentService) CreateDirectPayment(
+	ctx context.Context,
+	req CreateDirectPaymentRequest,
+	user *auth.User,


🚨Doesn't seem like user is being used in the code. We should probably add a field to the payments table to keep track of the user that submits the payment in the context of Direct Payments.

If you want to tackle that later, you can start by adding the user_id to the status_message field in status_history. E.g. Payment submitted by user_id xxx .

marwen-abid · 2025-06-10T00:16:34Z

internal/services/direct_payment_service.go

+
+// DirectPaymentRequest represents service-level request for creating direct payment
+type CreateDirectPaymentRequest struct {
+	Amount            string            `json:"amount" validate:"required"`


❓For the tagvalidate:"required", what validator is being used ? I don't see one called.

marwen-abid · 2025-06-10T00:37:35Z

internal/serve/httphandler/payments_handler.go

+			httperror.BadRequest("invalid reference in request", err, nil).Render(w)
+
+		case services.NotFoundError:
+			httperror.NotFound("resource not found", err, nil).Render(w)


We should improve the error being returned here. It currently doesn't specify which resource was not found.
Request

{ "asset": { "code": "USDC", "issuer": "GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5", "type": "classic" }, "amount": "10.44", "receiver": { "email": "[email protected]" } }

Response:

{ "error": "resource not found" }

Logs :

receiver not found: no receiver found with contact info: [email protected]"

marwen-abid · 2025-06-10T00:47:52Z

internal/services/direct_payment_service.go

+	}
+
+	// Skip balance validation for user-managed wallets since they manage their own balance
+	if distributionAccount.Type != schema.DistributionAccountStellarDBVault {


I don't believe this check is necessary. We are able and we should check the balance for other distribution account types like DistributionAccountStellarEnv or DistributionAccountCircleDBVault

marwen-abid · 2025-06-10T00:53:02Z

internal/services/direct_payment_service.go

+	// Get available balance for vault-managed accounts
+	availableBalance, err := s.DistributionAccountService.GetBalance(ctx, distributionAccount, *asset)
+	if err != nil {
+		return fmt.Errorf("getting balance: %w", err)


When the distribution account doesn't have a trustline for the target asset, this balance check causes the API call to fail with 500

{ "error": "creating payment" }

Logs are:

level=error msg="[DRY_RUN Crash Reporter] creating payment: transaction execution error: getting balance: balance for asset {722eb29d-5133-4e5a-8780-8eb3adb3d59c USDC GBBD47IF6LWK7P7MDEVSCWR7DPUWV3NY3DTQEVFL4NAT4AQH3ZLLFLA5 2024-07-26 23:45:48.617281 +0000 UTC 2024-07-26 23:45:48.617281 +0000 UTC <nil>} not found for distribution account"

This is not the desired behavior. We should do one of two things:

Validate that the distribution account has a trustline for the target asset.

Or, Return an error that informs the end-user about why this balance check failed so that they can know to either change the asset, or add a trustline to their distribution account.

marwen-abid · 2025-06-10T01:03:29Z

internal/services/direct_payment_service.go

+				return nil, fmt.Errorf("creating payment: %w", err)
+			}
+
+			// 7. Update payment status based on receiver wallet status


🚨 This is not needed. DRAFT Payment doesn't exist in the context of Direct Payments, it only exists in the context of Disbursements. Furthermore, if you set the payment to Draft, it will get stuck in that state even after the Wallet is registered.

For Direct Payment, the lifecycle of a payment should start with READY status. Once the wallet is REGISTERED, The payment will be processed and moved to the PENDING state automatically.

marwen-abid · 2025-06-10T03:43:21Z

internal/data/payments.go

@@ -221,7 +250,7 @@ func (p *PaymentModel) GetBatchForUpdate(ctx context.Context, sqlExec db.SQLExec
 	}

 	query := getReadyPaymentsBaseQuery + `


🚨 I haven't been able to dispatch a payment (using schedule jobs), because getReadyPaymentsBaseQuery still checks that the disbursemen.status = 'STARTED'

dpohr added 7 commits May 23, 2025 20:03

SDP-1644 create direct payment

bdda140

SDP-1644

55fa6c7

Merge remote-tracking branch 'origin/develop' into SDP-1644-create-di…

13ba133

…rect-payment

SDP-1644

a97ca78

SDP-1644 fix existing tests

23bac55

SDP-1644 add tests

a23b280

SDP-1644 add direct payment tests and additional error types

df5827e

dpohr temporarily deployed to Receiver Registration - E2E Integration Tests (Stellar) May 30, 2025 06:51 — with GitHub Actions Inactive

dpohr temporarily deployed to Anchor Integration Tests May 30, 2025 06:51 — with GitHub Actions Inactive

github-actions bot assigned dpohr May 30, 2025

Merge branch 'develop' into SDP-1644-create-direct-payment

60280a5

dpohr temporarily deployed to Anchor Integration Tests May 30, 2025 06:51 — with GitHub Actions Inactive

dpohr temporarily deployed to Receiver Registration - E2E Integration Tests (Stellar) May 30, 2025 06:51 — with GitHub Actions Inactive

SDP-1644

646cdd0

dpohr temporarily deployed to Receiver Registration - E2E Integration Tests (Stellar) May 30, 2025 07:23 — with GitHub Actions Inactive

dpohr temporarily deployed to Anchor Integration Tests May 30, 2025 07:23 — with GitHub Actions Inactive

SDP-1644 update changelog

1b9885c

dpohr temporarily deployed to Receiver Registration - E2E Integration Tests (Stellar) May 30, 2025 07:52 — with GitHub Actions Inactive

dpohr temporarily deployed to Anchor Integration Tests May 30, 2025 07:52 — with GitHub Actions Inactive

dpohr mentioned this pull request May 30, 2025

SDP 1645 fetch direct payments #694

Open

7 tasks

dpohr requested a review from marwen-abid June 2, 2025 09:17

SDP-1644 change service init

fc7b386

dpohr temporarily deployed to Receiver Registration - E2E Integration Tests (Stellar) June 2, 2025 13:02 — with GitHub Actions Inactive

dpohr temporarily deployed to Anchor Integration Tests June 2, 2025 13:02 — with GitHub Actions Inactive

marwen-abid requested a review from marcelosalloum June 3, 2025 18:01

marwen-abid requested a review from philipliu June 3, 2025 18:01

dpohr marked this pull request as ready for review June 4, 2025 10:52

philipliu reviewed Jun 9, 2025

View reviewed changes

marwen-abid reviewed Jun 10, 2025

View reviewed changes

	// DirectPaymentRequest represents service-level request for creating direct payment
	// CreateDirectPaymentRequest represents service-level request for creating direct payment.

		@@ -221,7 +250,7 @@ func (p *PaymentModel) GetBatchForUpdate(ctx context.Context, sqlExec db.SQLExec
		}

		query := getReadyPaymentsBaseQuery + `

SDP 1644 create direct payment #693

Are you sure you want to change the base?

SDP 1644 create direct payment #693

Uh oh!

Conversation

dpohr commented May 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What

Why

Known limitations

Checklist

Uh oh!

stellar-jenkins commented May 30, 2025

Uh oh!

stellar-jenkins commented May 30, 2025

Uh oh!

stellar-jenkins commented May 30, 2025

Uh oh!

stellar-jenkins commented May 30, 2025

Uh oh!

stellar-jenkins commented Jun 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

marwen-abid left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

dpohr commented May 30, 2025 •

edited

Loading