Instructions for Joys Digital Payments

What the add-on does

The add-on adds a Joys Digital payment method to CS-Cart. It creates a payment for the order, redirects the customer to the payment page, receives the payment result notification, and records transaction data in the order.

The add-on works with one-step payments. There are no hold/capture, two-step payment, or separate API token settings in the interface: the connection uses the POS terminal ID and RSA keys. Test mode is not enabled by a separate setting — credentials and access mode are configured on the Joys Digital side.

Where to find the add-on

• Add-on page: Add-ons → Manage add-ons → Joys Digital Payments.
• Payment method setup: Administration → Payment methods, then a payment method with the Joys Digital processor.
• Transaction actions: the order page in the admin panel.

What to prepare in Joys Digital

1. Create or get a POS terminal in the Joys Digital account.
2. Copy the POS terminal ID — it is entered in the POS terminal ID field.
3. Prepare RSA keys. A key pair can be generated in CS-Cart payment method settings.
4. Add the store public RSA key to the Joys Digital account. The private key remains in CS-Cart.
5. Copy the callback URL from payment method settings and add it in Joys Digital as the POST notification URL for payment status updates.
6. If Joys Digital fiscalization or 54-FZ receipts are used, configure them in the payment service account. The add-on sends order items in the payment request, but it does not add separate receipt, DigitalKassa, or 54-FZ settings in CS-Cart.

How to configure the payment method

1. Open Administration → Payment methods.
2. Create a new payment method or edit an existing one.
3. Select Joys Digital as the processor.
4. Enter the terminal identifier from Joys Digital in the POS terminal ID field.
5. If the keys are not ready yet, click Generate keys.
6. Copy the displayed public key and add it to the Joys Digital account.
7. Check the Private key field. The private key is used for request signing and must not be sent to customers or published.
8. Copy the POST request URL for payment status updates and add it to Joys Digital notification settings.
9. If needed, use the CSS file URL for the payment page if Joys Digital allows connecting an external style for the payment page.
10. Check the Store page URL for returning from the payment status page.
11. Select order statuses for successful payments, payment errors, and refunds.
12. Save the payment method and make sure it is available for the required storefronts, user groups, and shipping methods.

How payment works

1. The customer selects Joys Digital during checkout.
2. The add-on builds a request with the POS terminal, unique payment sequence, order amount, and cart contents.
3. The request is signed with the private RSA key and sent to Joys Digital.
4. If Joys Digital returns a payment URL, the customer is redirected to the service payment page.
5. After payment, Joys Digital sends a POST notification to the store callback URL.
6. If the notification contains Paid = true, the order receives the successful payment status. Otherwise, the error status is applied.
7. The internal Joys Digital payment sequence and the external transaction ID are saved in order payment information.

Refunds and status refresh

If an order has been paid, an external transaction ID is saved, and the current order status matches the successful payment status, the order page shows the Process a refund action. The refund is sent to Joys Digital for the order amount. When the response contains Paid = true and Processed = true, the order is moved to the status selected for refunds.

If an order has a payment sequence but the current status does not yet match the successful payment status, the order page shows the Refresh payment status action. The add-on requests the current Joys Digital transaction state and updates the order status according to the response.

How to test

1. Create a test order on the storefront and select Joys Digital as the payment method.
2. Check that the customer is redirected to the Joys Digital payment page after order placement.
3. Complete the payment on the Joys Digital side.
4. Open the order in the admin panel and check the order status.
5. Check order payment information: the payment sequence and Joys Digital transaction ID should be saved.
6. If the automatic notification was not received, use the payment status refresh action on the order page.
7. To test a refund, make sure refunds are allowed in Joys Digital, then run the refund action from the order page.

Common issues

• The customer is not redirected to the payment page. Check the POS terminal ID, private RSA key, and Joys Digital availability.
• Joys Digital reports a signature error. Compare the private key in CS-Cart with the public key in the Joys Digital account.
• The order status is not updated. Check the callback URL in Joys Digital and make sure the storefront is reachable from outside.
• Refunds do not work. Check that the order has a Joys Digital transaction ID and that refunds are allowed for the terminal.
• Receipts or 54-FZ are required. Configure fiscalization on the Joys Digital side: the add-on has no separate receipt settings block.