Key Summary

The most dangerous prompt when entrusting payment functionality to AI is simply asking it to “handle the payment.” Payment is not just a code for receiving money; it is an operational, accounting, and customer support system responsible for managing the flow of funds.

Technically, AI can quickly implement payment window integration, API calls for authorization, webhook reception, and order storage. However, if the following policies are not established, real-world services may face issues such as phantom orders, duplicate payments, delayed refunds, customer service overload, and missing legal disclosures.

Decision Area Questions to Define in Advance Risks of Failure
Order Status What sequence of statuses does an order go through? Ghost orders occur where payment is processed but no order exists
Refund Deadline How will we account for the deadlines for cancellation of purchase and refund processing? Violation of statutory deadlines, late payment interest, risk of disputes
Partial Refunds How will we calculate refunds for partial returns, coupons, and shipping costs? Operators must calculate manually each time, leading to customer distrust
Double Payments How can we prevent the same order from being charged twice? Customer complaints based on credit card statements, loss of trust
Failure Notifications How should we notify customers of credit limit exceeded, insufficient balance, or authentication failure? Decreased retry conversion rate, increase in unnecessary inquiries
Payment History Where can customers check the status of their payments and refunds? Increased customer service inquiries, lack of transparency
Refund Notices Where should refund policies and the cancel button be placed? Controversy over “dark patterns,” regulatory risks

1. Order Status Design: Status Is the Language of Operations

When building a payment feature, you shouldn’t limit order statuses to just “Order Complete.” Actual orders go through multiple stages, such as payment attempt, approval, cancellation, refund, failure, and expiration.

Example Status Codes Status Visible to the Customer Meaning
payment_pending Payment Pending The order has been created, but payment is not yet complete
paid Payment Complete Payment has been approved, and the order is valid
payment_failed Payment Failed The payment attempt failed, and you must determine whether a retry is possible
cancel_requested Cancellation Request The customer has requested a cancellation, and it is pending processing
cancelled Cancellation Complete The order was canceled before payment, or the authorization was revoked
refund_requested Refund Request A refund request was received after payment
refund_processing Refund in Progress The refund is being processed or the funds are being returned to the payment method
partially_refunded Partial Refund Complete Only a portion of the order amount has been refunded
refunded Refund Complete Refund processing is complete
expired Order Expired The order has been invalidated because the payment waiting period has expired

Status Design Principles

  • Order status and payment status are not considered entirely equivalent. An order may exist even if payment fails, and payment may be approved even if the order fails to be saved.
  • For every status change, the time of occurrence, processor, reason, payment transaction ID, and refund transaction ID must be logged.
  • The customer interface, admin interface, and customer service responses must all use the same status definitions.
  • Status transitions are designed to be unidirectional, and exception recovery is handled by logging the event with separate administrative permissions.

If you operate consumer-facing e-commerce in South Korea, you must comply with the Act on Consumer Protection in Electronic Commerce, etc. Generally, consumers may withdraw their purchase within a specified period, and businesses must refund the payment within a set timeframe following a refund request or return process.

The following criteria are particularly important in practice:

  • In principle, consumers may withdraw from a contract within 7 days from the date they received the goods or other items, or from another date specified by law.
  • Businesses must refund the payment within the statutory deadline after the grounds for a refund arise; delays may result in claims for compensation for delay or late payment interest.
  • Exceptions may apply to digital content, custom-made products, and goods whose value significantly diminishes with use; however, to apply these exceptions, requirements such as prior notice and consent must be carefully verified.
  • Actual application may vary depending on the type of product, contract method, notices provided to the consumer, and whether use has commenced; therefore, legal review is necessary.

How to Convert These into Development Requirements

It is not sufficient to simply include legal standards in the terms and conditions. They must also be converted into system requirements.

Legal/Policy Requirements System Requirements
Determining eligibility for withdrawal within 7 days Automatically calculate the refund period based on the order receipt date or service provision date
Refunds must be processed within 3 business days Display the refund request date and processing deadline on the admin dashboard
Risk of refund delays Display notifications for approaching deadlines and missed deadlines
Requirement to notify customers of exempt products Clearly indicate before payment that the product is subject to refund restrictions and store consent logs
Requirement to handle disputes Retain records of terms and conditions version, notification time, consent time, and customer IP or account logs

3. Partial Refund Rules: Predefine Coupons, Shipping Fees, and Taxes

Partial refunds are much more complex than full cancellations. When a customer orders multiple products at once and returns only some of them, you must determine how to allocate the original discounts and shipping fees.

Items That Must Be Determined

  • How to allocate the payment amount per item
  • Whether to allocate order-wide coupons proportionally across items
  • Whether coupons for specific items should apply only to those items
  • Whether to deduct shipping fees when free shipping conditions are no longer met
  • How to distinguish between shipping fees for returns due to buyer’s remorse and those for defective products
  • In what order should refunds be issued for payments made with points, stored credit, and gift cards?
  • How should the information on tax invoices, cash receipts, and sales receipts be updated after a partial refund?

Example of Partial Refund Calculation

Item Amount
Product A 30,000 KRW
Product B 70,000 KRW
Order-wide Coupon -10,000 KRW
Actual Payment Amount 90,000 KRW

If the coupon is allocated based on the proportion of each item’s price, Product A receives a 3,000 KRW discount and Product B receives a 7,000 KRW discount. In this case, if only Product A is refunded, the refund base amount is 27,000 KRW, not 30,000 KRW. The final refund amount may vary further if there are free shipping conditions, return shipping fees, or refund restrictions based on the payment method.

There is no single “correct” answer. What matters is establishing consistent rules in advance and clearly communicating them to customers so they can understand them before making a payment or requesting a refund.

4. Preventing Double Charges: Simply Disabling the Button Is Not Enough

Double charges are the payment issues customers notice most quickly. Customers see their card approval text messages and credit card statements before they check the order status within the service. If the same order is charged twice, trust in the service plummets.

Causes

  • The customer clicks the payment button repeatedly
  • The customer refreshes the page or clicks the “Back” button immediately after payment
  • The same request is resent due to mobile network latency
  • The payment authorization response was successful, but saving to the service server failed
  • A webhook and client redirect simultaneously change the order status

Defense Design

Defense Mechanism Description
Client Button Lock Prevents repeated clicks on the payment button after the initial click, but should only be used as a secondary measure
Server-Side Order Lock Ensures that payment approval requests for the same order ID are not executed simultaneously
Idempotency Key Uses an identifier that ensures only one result is generated even if the same payment request is sent multiple times
Unique Transaction ID Prevents duplicate storage of order numbers and payment transaction IDs via database constraints
State-Based Validation Prevents additional authorization requests for orders already marked as paid
Duplicate Webhook Handling Ensures that even if the same webhook event is received multiple times, the state is updated only once

When requesting a payment code from an AI, it is best to specify that “payment approval and payment completion for the same order must behave idempotently,” rather than simply stating “prevent duplicate clicks.”

5. Payment Failure Messages: Failure Is Not an Accident, but a Normal Part of the Process

Payment failures are normal occurrences that happen every day. Exceeding spending limits, insufficient funds, failed card authentication, incorrect passwords, failed 3D Secure authentication, unresponsive mobile payment apps, and network errors are all common cases.

A poor error message is one that simply ends with “An error has occurred.” Customers have no way of knowing whether the payment went through, if they should try again, or if their order has been canceled.

Example Error Messages

Situation Recommended Message
Insufficient Balance The payment could not be completed because the balance on your payment method is insufficient. Please select a different payment method or check your balance and try again.
Limit Exceeded The payment failed because it exceeded your card limit or the single-transaction limit. Please check your limit in the card issuer’s app or pay with a different card.
Authentication Failed Payment authentication was not completed, so the order remains in a pending status. You can try again within 30 minutes.
Network Error There is a delay in confirming the payment result. To prevent duplicate payments, please check your payment history after a short while.
Order Expired The payment waiting period has expired, and the order has been canceled. Please select the items again and place a new order.

Key Elements of Failure Notifications

  • Clearly states that the payment was not actually completed.
  • Indicates how long the order will remain active.
  • Provides guidance on whether to retry or use a different payment method.
  • Displays the order number needed when contacting customer support.
  • If the payment result is uncertain, do not automatically prompt the user to pay again; instead, display a “Verifying” status.

6. Payment History Page: The Key Screen for Reducing Customer Support Inquiries

Without a payment history page, customers will contact customer support to check the status of their payments, cancellations, and refunds. The payment history is not just a simple receipt screen; it is a trust mechanism that allows customers to verify the current status of their funds.

Information to Include on the Payment History Page

  • Order number
  • Order date and time, and payment date and time
  • Product name, quantity, and options
  • Payment method and authorization number or transaction identifier
  • Product price, discounts, shipping fees, points used, and final payment amount
  • Current order status and refund status
  • Refund request date, refund approval date, and expected refund completion date
  • Whether cancellation or refund is possible
  • Links to view the receipt, transaction statement, and cash receipt
  • Information needed when contacting customer service

Integration with the Administrator Dashboard

The customer interface and the administrator dashboard must display the same data. If a customer sees “Refund in Progress” but the administrator dashboard shows “Processed,” it will cause confusion when handling customer service inquiries. While status names may be expressed differently, the internal status codes and transition rules must be consistent.

7. Location of Refund Policy Notice: Hiding It Turns a Policy into a Risk

It is not enough to place the refund policy in a corner of the Terms and Conditions page. Customers must be able to easily check the refund window, restrictions, and cancellation methods on the screen where they make their payment decision.

  • Near the price or “Buy” button on the product detail page
  • On the shopping cart or order summary screen
  • In the terms and conditions and refund policy consent section immediately above the checkout button
  • On the payment confirmation page
  • On the order details screen in the “My Account” section
  • On the refund request screen

Designs to Avoid

  • Designs where sign-up and payment occur simultaneously, but cancellation or refunds are only possible by calling customer service
  • Designs that hide the cancellation button deep within multiple steps
  • Designs that only display refund restrictions after payment has been made
  • Designs that arrange button colors, text, and order in a way that misleads customers
  • Designs that fail to clearly notify customers of automatic billing after a free trial ends

Such designs not only harm the customer experience but may also be classified as dark patterns. In particular, it is safest to design the difficulty of cancellation and termination so that it is not significantly different from that of sign-up and payment.

Checklist to Include in the Prompt for the AI

When requesting the implementation of payment functionality from an AI development tool, you must first provide the policies as shown below.

Example Prompt for Payment Functionality

Implement payment functionality for an e-commerce service targeting Korean consumers.
Be sure to incorporate the following policies:

1. Use the following order statuses: payment_pending, paid, payment_failed, cancel_requested, cancelled, refund_requested, refund_processing, partially_refunded, refunded, and expired.
2. Change pending orders to “expired” after 30 minutes.
3. Allow only one payment approval per order, and use server-side order locking and an idempotency key.
4. Since payment webhooks may be received multiple times, process each event ID only once.
5. Store the refund request date, refund processing deadline, processor, reason, and refund transaction number.
6. Calculate partial refunds based on the actual payment amount per item, and allocate order-wide coupons proportionally based on the item prices.
7. In the event of a payment failure, return a customer notification message specific to the reason for the failure.
8. Allow customers to view their payment history and refund status on their My Page.
9. Display a link to the refund policy and a consent checkbox before payment, and save the time of consent and the terms and conditions version.
10. If there are any unspecified policies, please ask before writing any code.

The last sentence, “If there are any unspecified policies, please ask first,” is important. It allows the AI to prompt for clarification on policies that humans might easily overlook, such as whether refunds are automatically approved, who has approval authority, and how shipping fees are deducted.

Required Features for the Admin Dashboard

The payment functionality isn’t complete with just the customer interface. Since refunds and cancellations are daily operational tasks, an admin interface is essential.

Admin Features Reason
Pending Refunds List Necessary to ensure no pending refunds are missed
Display of Legal Processing Deadlines Necessary to reduce the risk of delayed refunds
Upcoming and Overdue Alerts Necessary so operators can immediately recognize internal deadlines, such as 3 business days
Refund Reason Selection Necessary for statistics and cost allocation (e.g., change of mind, defective product, incorrect delivery)
Partial Refund Calculation Preview Required to reduce manual calculation errors by operators
Processing Log Required for dispute resolution and audit compliance
Permissions Management Required to restrict refund approvals and forced status changes

Minimum Configuration of the Payment Data Model

Although data structures vary by service, it is recommended to at least separate the data into the levels listed below.

Table or Object Key Fields
Order Order ID, Customer ID, Order Status, Order Amount, Discount Amount, Shipping Cost, Creation Date/Time, Expiration Date/Time
Order Items Item ID, Item Name, Options, Quantity, Amount per Item, Discount Allocation per Item
Payment Payment ID, Order ID, Payment Method, Authorization Number, Authorized Amount, Payment Status, Authorization Date and Time
Refund Refund ID, Order ID, Refund Amount, Refund Reason, Refund Status, Request Date/Time, Completion Date/Time
Status History Target ID, Previous Status, New Status, Modifier, Reason for Change, Date/Time of Change
Terms of Service Agreement Terms Type, Terms Version, Agreement Status, Agreement Date/Time, Customer ID

It is crucial not to overwrite the approved payment amount, refund amount, or total order amount. Values related to money should be preserved by transaction and history unit whenever possible to ensure consistency with accounting records and customer service later on.

Pre-Launch Checklist

  • If the payment button is clicked 10 times for the same order, is the payment approved only once?
  • If server storage fails after payment approval, can the data be recovered?
  • If the payment webhook sends the same event multiple times, is it processed without duplication?
  • Can customers understand the reason for payment failure and how to retry?
  • Do pending payment orders automatically expire after a certain period?
  • Do partial refund amounts comply with coupon, point, and shipping fee policies?
  • Are refund requests displayed on the admin dashboard from the request date until the processing deadline?
  • Are the refund policies easily visible on the pre-payment screen?
  • Are there prior notifications and consent logs for digital content or products with refund restrictions?
  • Can customers check their payment history and refund status directly in their account dashboard?

Conclusion

AI can quickly generate code for payment functionality. However, a secure and legally compliant payment system begins with policy decisions made before any code is written.

By first defining order statuses, statutory refund deadlines, partial refund calculation formulas, measures to prevent duplicate payments, payment failure notifications, the payment history page, and the location for displaying refund policies—and then entrusting the implementation to AI—you can achieve much more stable results. Payment systems should be designed from the perspective that they are not merely a “function for receiving money,” but a “function for managing money.”