Payouts: Show Bank Reference Key on Payout details page.

[nagpai]

Description

We recently added a Bank reference key column on the Payouts list report page and it's CSV exports. - #9832

We need to now show the Bank reference key in the Payout details page.

Acceptance criteria

The Bank reference key of a payout should be visible on its details page.

Designs

We will need help from design to figure out the best place to show the reference number. Based on documents from banks etc, the length of the key is not more than 40 characters. But the key that is included in test payout objects show upto 41 characters in length.

Here are some sample keys and patterns I have spotted in last 50 payouts in the server DB:

• 12 digit number
• ST-<20 alphanumeric characters> ( total 23 characters )
• WOOPAYMEN-<25 alphanumeric characters> ( total 35 characters )
• WOOPAYMEN-<5 alphabets> ( total 15 characters )

A very rough mockup of how this looks with 41 characters, if we were to add it below the existing header

Additional context

• Bank reference key added in client - Payouts: Add payout bank reference key to payout reports and CSV #9832
• This key helps merchants reconcile their bank statements with our payout reports. The reference key appears in their bank statement descriptors.

[haszari]

This seems like an obviously-useful enhancement to me, I think we can prioritise for maintenance.

Next steps:

• Prototype to explore where we can show this on the page – could be a PR or design/hacking screenshots.
• Validate that design with product/design/stakeholders.

I removed needs design – this might benefit from input from design but I don't think it's blocked on design! FYI @rogermattic - you might be interested or have ideas for how it should work.

[rogermattic]

Thanks @haszari ! Like I mentioned in the PR I will explore some options for design we might consider to improve the UI!

[nagpai]

Moving back to In Progress to improve the code based on feedback from @haszari and a very useful pair code session we had!

[rogermattic]

Hey @nagpai @haszari !
As I started thinking about this issue, a few questions came to mind:

1. Does the user need to see the bank reference key at the top level of the page?
2. Could we simplify the header to make it less cluttered?
3. Do we anticipate adding more details to the Payouts page in the future? (Probably yes.)
4. Should we consider a more scalable approach?

I was thinking we could add a dedicated section for this on the page. For instance, the Payouts page could share the same template as a Transaction Single. In that case, we could use the "details" box from the Transaction Single page for consistency.

I made a quick mockup to show how this might look on the Payout Details page (still a work in progress, but I wanted to run it past you first to see if it’s worth exploring further).

The Payout details box could be at the bottom of the page, if we could add a max height + pagination to the table:

Or otherwise just above the table so it isn't easy to miss:

Overall, I believe this approach is more future-proof. The closer the single pages (e.g., payment and payout) are in structure, the better. Ideally, they could share a template so that any future improvements to these components would automatically apply across all instances, ensuring a consistent and predictable design.

What do you think?

We could further align the single pages as a separate scope.

[nagpai]

@rogermattic - Thanks! The approach you have suggested is certainly more scalable, and frees us from the pitfall of cluttering the main header.

Between the two screenshots you've shared, I prefer the details to be shown on top ( option 2 ). This is because the merchant would want to copy the reference ID in case they wish to send it to their bank on an email e.t.c. Deposit date is redundant since we are showing it on top as Payout date . It makes sense to show it, should we go for the first option ( showing details at the bottom ) .

Tagging @souravdebnath1986 and @aheckler for your views 🙌🏼

[aheckler]

Also prefer the payout details on top. Looks good!

[haszari]

Thanks @rogermattic 🙌

Slight preference for details at bottom for me – don't want to push the table of payout details down too far. But either layout works, and this is definitely an improvement.

As well as decluttering the header visually, there is some complex code to manage all the different content for the header (instant payouts, negative payouts have subtle differences). This clean layout will help us simplify the code too 🚀

[rogermattic]

Great! Thanks for your feedback! Is there any other detail or information we could display there?

Personally, I slightly prefer placing it at the bottom since it’s additional information. However, I noticed that the table can get quite long, and since users currently don’t expect anything else on the page—and the table doesn’t include pagination (?)—placing it at the top might be a better option.

I’ll finalize the designs tomorrow and share the updated version here! :)

[rogermattic]

Hey @nagpai @haszari @aheckler

I’ve created the mockups and some basic flows—let me know if I missed anything!

Here’s what I’ve updated:

• The Payout Details box is now at the top.
  

• I removed the date field.
  

• I illustrated the hover interaction and added snackbar feedback for the copy action.
  

• I included mockups for cases where the bank reference is not available.
  

Would you mind helping me brainstorm reasons (or any additional information) we could display to the user if the bank reference is unavailable?

Designs in Figma

By the way,

Is there any other detail or information we could display there?

This is still a valid question if anyone has any feedback / ideas.

[haszari]

Looks good @rogermattic !

copy button appears on hover

I think this is overcomplicating things (also hover is not a thing on mobile). Could we just show the copy icon at all times? And if you tap/click the ID or the label or the button, it copies 🎉 with light feedback e.g. green or checkmark icon or similar.

Would you mind helping me brainstorm reasons (or any additional information) we could display to the user if the bank reference is unavailable?

I don't know if it's worthwhile having a tooltip here, it's a low-importance thing so maybe don't need the clutter. If we get a lot of feedback then we can add a tooltip later. I think we can just use not available (means exactly what it says!) and maybe mention in docs that these come from banks and might not be available for all payouts.

@nagpai curious – is there another copy button in the UI somewhere (that you used as a model for the PR)? I thought this would be on payment details page for payment ID, but it's not copiable.

@rogermattic are you aware of other copiable IDs like this elsewhere in the UI? Maybe we could make a component for this.

[haszari]

One last thing … maybe it's a little heavy having two cards, and an extra heading?

Could we just have two sections within the one card?

The Payout date: label might be redundant now also.

[nagpai]

@nagpai curious – is there another copy button in the UI somewhere (that you used as a model for the PR)? I thought this would be on payment details page for payment ID, but it's not copiable.

I picked up hints from a copy button that was recently introduced in checkout on the front end.

I was unable to find any copy button in the admin though. I have created a copy button component in my linked PR which should be reusable for any long ID's that are often copied by merchants.

I think this is overcomplicating things (also hover is not a thing on mobile). Could we just show the copy icon at all times? And if you tap/click the ID or the label or the button, it copies 🎉 with light feedback e.g. green or checkmark icon or similar.

I agree. Here is how it looks currently with the copy-button component @rogermattic

YROMR4.mp4

[nagpai]

@rogermattic - Can you share a mockup on how this would appear on a desktop screen ( would that be 1920 wide ? ) and a mobile / narrow tablet screen?

I did a quick test and found the following issue:

1. Unlike the details page of transaction and disputes, the payout details page container does not have a max-width ( 1032px in case of transaction and disputes detail page ) . This could be because the payout details page has a transactions list below with many columns, that's absent on other details templates.

2. If the screen size increases to a larger number like 1920, the Detail titles and the values go farther apart, perhaps not desirable. Screenshot of screen at 1920px width:

[nagpai]

@rogermattic I played a bit with CSS and managed to get this. Let me know what you think. I will also share a test site with you.

111-Screen.Capture.on.2024-12-20.at.13-26-12.mp4