zittme Pay module
zittme Pay is Zittme's payment gateway module. It handles payments for other modules such as Commerce and Reservation in one place, and provides payment history, cancellation, and log management. Third-party modules can also add payments through zittme Pay as long as they follow the defined conventions.
Installation
- Install the zittme Pay module from the Store.
- In Admin > zittme Pay, use the Settings · Gateways · Payment history · Logs tabs.
- Sign up at panel.conekta.com and enter via "Explorar panel" (explore the panel); a test company is created without business review.
- Turn on "Modo pruebas" (test mode) at the bottom left, then in Desarrolladores > "Consultar API Keys de prueba", create a private key with "Crear nueva llave privada." The private key is shown only once when created, so copy it right away.
- Enter the private key in the Gateways tab and click "Test connection" to see the mode (sandbox / live). Test keys have no distinct prefix, so the mode is determined from Conekta's response. Until you create an order once, it may show as "Needs checking."
- In Desarrolladores > Webhooks > "Crear Webhook", enter the webhook URL above and turn on all events. Whatever event arrives, zittme Pay looks up the order again through the Conekta API before confirming, so forged notifications cannot confirm a payment.
- Approved cards: 4242 4242 4242 4242 (Visa), 5555 5555 5555 4444 (Mastercard). Any name and CVC, and a future expiry date.
- Declined card: 4000 0000 0000 0002, insufficient funds: 4000 0000 0000 0127.
- For bank transfer (SPEI), calling Conekta's sandbox deposit notification API (
/sandbox/spei/payment_notifications) with the issued CLABE processes the deposit. Cash (OXXO) is marked as deposited automatically after a short while in the sandbox. - On the linked module's (Commerce, etc.) checkout page, the buyer chooses a payment method and clicks Pay.
- Card: approval in the Toss Payments payment window → result page. / Bank transfer: result page showing account details and the deposit deadline → Paid when an admin confirms the deposit.
- Payment status changes are reflected in the linked module immediately and double-checked via gateway webhooks.
- Payment history: Search all payments by status · period · payment method, and view each payment's approval details · the linked module's order number · processing history.
- Cancellation: Run a full or partial cancellation (if allowed) from a payment. Card payments are canceled through the gateway, and bank transfers are recorded as refunds. Choose the cancellation reason from the reasons list in settings.
- Payments past the PG auto-cancel limit: You are guided to process a manual refund instead of a PG cancellation.
- Logs: Gateway requests/responses and received webhooks are recorded and cleaned up after the retention period. Check them when investigating payment problems.
- If the provider sent a failure reason, that text is shown as is, for example
카드 한도 초과(card limit exceeded) or유효하지 않은 카드번호(invalid card number). - For bank transfer payments, the issued account · depositor name · deposit deadline are summarized.
- If there is nothing worth summarizing, the beginning of the raw response is shown, truncated.
- When calling payment creation (createOrder), pass your module's order number in the
source_codeparameter. - That number is then shown as the primary "Order number" on the payment page · result page · admin history, and the zittme Pay code is shown as the "Payment number."
- Update your module's order status in the payment completion · cancellation callbacks.
- Test payments don't work: Check whether test mode is on and whether your Toss Payments keys are test keys.
- Bank transfer orders stay in Awaiting payment: Bank transfers become Paid only when an admin clicks confirm deposit. Setting a deposit deadline cleans up abandoned unpaid orders automatically.
- I don't see the partial cancellation button: If Allow partial cancellation is off in settings, only full cancellation is possible.
- Canceling an old card payment fails: Card cancellation is blocked once the PG has settled the payment. Process a manual refund according to the PG auto-cancel limit setting.
- Webhooks aren't coming in: Make sure the gateway's IPs are not missing from the webhook IP allowlist. Leave it blank to accept without restriction.
- A new payment method doesn't appear on the payment page: It appears only after you turn it on in the Gateways tab and enter its keys. If the keys are blank, it is not listed.
- PayPal is inactive: Besides the Client ID · Secret, the shared exchange rates must have a rate for the payment currency (default USD).
- Changing the payment page skin keeps reverting: Fixed in 0.2.0. Update the module.
- After paying and returning, I see "This HTTP method is not allowed for this request": This happens in 0.2.9 and earlier with PGs like Conekta · PortOne, where the payment window goes to another site and returns via GET. From 0.2.10, callbacks accept both GET · POST, so update zittme Pay in Admin > Store. The payment itself was processed normally by the PG, so re-querying the failed order in Payment history brings it to approved status.
All Settings tab options
| Setting | Description |
|---|---|
| Enabled | Turns the whole payment feature on/off |
| Test mode | Checks the payment flow without real approvals. Use test keys for the gateways too |
| Currency | Default KRW |
| Order number prefix | A marker for recognizing your orders in the PG admin (up to 8 letters·digits) |
| Allow partial cancellation | Whether only part of a payment can be canceled. When off, only full cancellation is possible |
| Cancellation reasons | Reasons to choose from when canceling. Enter one per line |
| PG auto-cancel limit (days) | After this many days from payment, PG cancellation is not attempted and the case is handed over to a manual refund. This is because PG cancellation is blocked for card payments that have already been settled. 0 means no limit |
| Allow forced cancellation of confirmed payments | Lets admins cancel payments even after purchase confirmation. When off, nothing can cancel a payment once it is confirmed |
| Admin notification email | Address to receive notifications |
| Notification events | Whether to send on payment completion / on cancellation, separately |
| Log retention days | How long payment logs are kept (0=indefinite) |
| Webhook IP allowlist | Restricts which IPs gateway webhooks are accepted from. Leave blank for no restriction |
| Payment page notice | Text shown at the bottom of the payment page, such as your mail-order business registration number |
| Payment page skin | Skin for the payment · result pages |
Gateways tab (payment methods)
Turn on the payment methods you want to use and enter the details for each.
Toss Payments (cards, etc.)
| Setting | Description |
|---|---|
| Client key | Issued in the Toss Payments Developer Center |
| Secret key | Same as above. Never expose it publicly |
We recommend checking the flow with test keys + test mode first, then switching to live keys. If the key type (test/live) and mode do not match, approval fails.
KG Inicis
| Setting | Description |
|---|---|
| Merchant ID (MID) | Issued in the Inicis merchant admin |
| Sign Key | Used to sign the payment window |
| INIAPI Key | Key for cancellations · refunds only. Issued separately in the merchant admin |
In test mode, you can check everything up to the payment window even before signing a contract, using the keys of the public test merchant (mid INIpayTest). If the approval connection drops or the amount does not match, the transaction is automatically voided to prevent double charges.
NHN KCP
| Setting | Description |
|---|---|
| Site code (site_cd) | Issued by KCP. For testing, T0000 |
| Service certificate | Paste the contents of the PEM file from the KCP admin certificate center as is |
| Merchant private key · password | Used only for the digital signature of cancellation · refund requests |
NICEPAY
| Setting | Description |
|---|---|
| Client ID | Issued in the NICEPAY Developer Center (developers.nicepay.co.kr) |
| Secret Key | Same as above |
Signing up for the Developer Center alone gets you sandbox keys, so you can test the payment · cancellation flow before signing a contract. When test mode is on, it connects to the sandbox server automatically.
PortOne (V2)
| Setting | Description |
|---|---|
| Store ID | Issued in the PortOne console (portone.io) |
| Channel key | Which PG processes the payment is set in the channel settings of the PortOne console |
| V2 API Secret | Used for server-side approval · cancellation |
A single driver lets you use multiple PGs connected to PortOne. For testing, enter the keys of a test channel.
PayPal (international payments)
| Setting | Description |
|---|---|
| Client ID · Secret | Issued from an app in the PayPal Developer console (developer.paypal.com). In test mode, use sandbox app keys |
| Payment currency | PayPal does not support KRW. KRW orders are converted to this currency for payment (default USD) |
Conversion uses the shared exchange rates below, and refunds are processed at the rate at the time of payment. Foreign-currency orders (Commerce multi-currency) are paid directly in that currency without conversion.
Conekta (Mexico · Latin America)
Accepts cards, cash (OXXO convenience stores), and bank transfers (SPEI) through the hosted payment page of Conekta, a Mexican payment provider. Clicking Pay takes the customer to the Conekta payment page, and they return to the site after paying. Cash and bank transfers come back in "Awaiting deposit" status with only a reference number or account issued, and the actual deposit is confirmed by webhook.
| Setting | Description |
|---|---|
| Conekta private key | The private key (starting with key_) created in Conekta panel > Desarrolladores > API Keys. The public key is not used |
| Webhook URL | Register the URL shown on screen in Conekta panel > Desarrolladores > Webhooks. Required to confirm cash · bank transfer deposits |
| Payment methods | Choose the methods to offer on the payment page: Card / Cash (OXXO) / Bank transfer (SPEI). Leave blank for all |
| Payment currency | Currency to convert KRW orders into. Default MXN. OXXO and SPEI support MXN only, and USD card payments are available depending on your Conekta account type |
| Allow KRW orders | When on, KRW orders are converted at the shared exchange rate for payment. The exchange rate table must have a row for the payment currency (MXN) |
Getting test keys
Test payments
Live keys
Under Conekta's terms, a live account requires a business incorporated under Mexican law (with an RFC) and a Mexican settlement account. Once review is done, just put the panel's live key in the same field. Refunds are processed via API only for card payments; cash · bank transfer payments are handed over to manual refunds.
Bank transfer
| Setting | Description |
|---|---|
| Deposit accounts | Register multiple bank · account number · account holder entries. The buyer chooses an account when ordering |
| Deposit deadline (days) | 1–30 days. Unpaid orders past the deadline become subject to automatic cancellation |
Deposits are confirmed by an admin in Payment history, and on confirmation the linked module's order moves to Paid.
Shared exchange rates
Manage per-currency exchange rates (KRW per 1 unit of currency) in the Gateways tab. This is the single reference used by both zittme Pay's payment conversion and the Commerce module's multi-currency prices.
| Setting | Description |
|---|---|
| Exchange rate table | Register currency codes (USD, etc.) and rates |
| Manual lock | Checked currencies are not overwritten by automatic updates |
| Automatic update | Updates once a day. Choose the source: open.er-api.com (no key needed) or the Export-Import Bank of Korea (API key required) |
If an automatic update fails, the last successful value is kept, and each order stores the rate at the time of payment, so later rate changes do not affect it.
Foreign-currency payments
When a linked module such as Commerce passes a foreign-currency order, it is paid in that currency. Payment methods that do not support the order currency do not appear on the payment page (domestic Korean PGs are KRW-only; PayPal supports 24 major currencies). Amounts are formatted automatically with the right currency symbol and decimal places.
Payment flow
Order number and payment number
Showing buyers two numbers is confusing, so they are displayed according to these rules.
| Number | Issued by | Display |
|---|---|---|
| Order number | The module that requested payment (Commerce · Reservation, etc.) | Shown large as the primary number on the payment page · result page · history |
| Payment number | zittme Pay | Shown small as secondary. The reference for payment inquiries · cancellations |
Payment history and cancellation
Reading logs
The Logs tab accumulates, in chronological order, what was exchanged with the payment providers. Start here when a payment fails or a deposit is not confirmed.
The response column shows a one-line summary instead of the raw response.
If you need the full raw response, hover over the summary. The response the provider sent appears as is. Attach this raw response when you submit an inquiry.
If the response is empty, the request never reached the provider. Check the credentials in the Gateways tab and whether the server blocks outbound connections.
Third-party module integration (developers)
The convention for adding zittme Pay payments to another module is simple.
The Commerce and Reservation modules are reference implementations of this convention. For general module development conventions, see the "Building modules" document in the developer guide as well.