Flitt Payments

Core Workflow

Use this skill for Flitt payment API work, starting with authentication and testing.

1. Read references/testing-auth.md when the task involves sandbox credentials, test cards, request shape, response interpretation, or signature troubleshooting.
2. Read references/sending-request.md when the task involves checkout flow design, redirect endpoints, request/response envelopes, callback handling, or choosing between browser form POST and host-to-host checkout URL creation.
3. Read references/payment-redirect.md when the task involves Payment (redirect) parameters, checkout URL creation, HTML form redirect creation, embedded checkout token creation, or /api/status/order_id polling.
4. Read references/payment-direct.md when the task involves Payment (direct), raw card parameters, PCI DSS merchant flows, or /api/3dsecure_step1 and /api/3dsecure_step2.
5. Read references/payment-saved-card.md when the task involves Payment with saved card, rectoken, recurring/tokenized charges, or /api/recurring.
6. Read references/saving-cards.md when the task involves obtaining rectoken, required_rectoken=Y, verification-based tokenization, or the first-purchase card-save flow.
7. Read references/reversal.md when the task involves refunds, reversals, partial/full reverse, reverse_id, /api/reverse/order_id, or reversal status.
8. Read references/capture.md when the task involves capture, preauth hold completion, partial capture, /api/capture/order_id, or capture status.
9. Read references/subscriptions.md when the task involves scheduled subscriptions, subscription=Y, recurring_data, /api/subscription, or starting/stopping subscriptions.
10. Read references/additional-data.md when the task involves reservation_data, checkout custom fields, fiscalisation products, payer metadata, or forcing/relaxing 3DS behavior through additional data.
11. Read references/currencies.md when the task involves validating the currency field, merchant-country currency support, or payment currency selection.
12. Read references/callbacks.md when the task involves server_callback_url, webhook endpoints, retries, firewall/IP allowlists, or verifying asynchronous payment notifications.
13. Read references/signature.md when the task is specifically about Flitt signature generation, verification failures, lowercasing, empty parameters, /api/recurring signing, or callback/redirect signature mismatches.
14. Read references/response-codes.md when the task involves response_code, API failures, embedded-checkout JavaScript error codes, decline interpretation, or deciding whether merchant, issuer, or Flitt must solve the problem.
15. Use scripts/flitt_signature.py instead of hand-writing SHA1 signature code for flat request/response parameters.
16. Keep public Flitt test credentials out of production code. Use environment variables or the app's secret manager for real merchant credentials.
17. Treat response_status as the HTTP/API processing status, not the payment result. Inspect payment-specific fields such as order_status, reverse_status, reversal_amount, capture_status, subscription status, and response_code for operation outcome.

Authentication

Flitt API requests are HTTPS POST requests. Every signed request includes a signature parameter inside the root request object.

Generate the signature from:

1. The merchant payment secret key.
2. All non-empty request or response parameters except signature and response_signature_string.
3. Parameters sorted alphabetically by key.
4. Values joined with |, encoded as UTF-8, then hashed with SHA1.

Use the helper:

python3 ~/.codex/skills/flitt-payments/scripts/flitt_signature.py \
  --secret test \
  --params '{"merchant_id":1549901,"amount":1000,"currency":"GEL","order_desc":"Test payment","order_id":"TestOrder2","server_callback_url":"http://myshop/callback/"}'

To verify a received signature:

python3 ~/.codex/skills/flitt-payments/scripts/flitt_signature.py \
  --secret "$FLITT_PAYMENT_KEY" \
  --params-file response.json \
  --verify "$FLITT_RESPONSE_SIGNATURE"

If response.json has a root response or request object, the helper signs that inner object automatically.

Testing

Use Flitt test merchant data only for sandbox work:

• Purchase merchant: merchant_id=1549901, secret key test
• Payout secret key: testcredit
• Test card data: load references/testing-auth.md

For manual test flows, choose cards deliberately:

• Use an approve card for happy-path checkout.
• Use a decline card when verifying failure UI and webhook handling.
• Use 3DS challenge/frictionless cards when validating redirect and callback handling.
• Use Open Banking payment_method=x only for Demo Bank testing.

Sending Requests

Use the hosted checkout flow unless the user explicitly needs direct card entry or another specialized Flitt API.

• Scheme A: create an HTML form and submit the customer browser to https://pay.flitt.com/api/checkout/redirect/ with HTTPS POST.
• Scheme B: send a server-to-server JSON request to https://pay.flitt.com/api/checkout/url/, read checkout_url from the response, then redirect the customer there.
• Always include Flitt parameters under a root request object for JSON requests.
• Always handle both customer return (response_url) and server-to-server callback (server_callback_url) when available; use the callback as the reliable status update.

For Payment (redirect) details, load references/payment-redirect.md.

Direct Payments

Use Payment (direct) only when the merchant is intentionally PCI DSS compliant and the app is allowed to collect/process card data directly.

• Direct card requests include raw card_number, cvv2, and expiry_date values; never log or persist those values unless the project has explicit compliant storage controls.
• Start direct 3DS authentication with POST /api/3dsecure_step1.
• If 3DS is required, submit the customer to acs_url with PaReq, MD, and TermUrl.
• Complete the transaction with POST /api/3dsecure_step2 using returned pares and md.
• For details, load references/payment-direct.md.

Saved Card Payments

Use Payment with saved card when charging a previously issued Flitt rectoken.

• Create saved-card charges with POST /api/recurring.
• Send JSON with root request; the endpoint is always host-to-host.
• Redirect and 3DS flows are not available on /api/recurring; use Payment (direct) if 3DS is required.
• Treat rectoken as sensitive payment data and avoid logging it.
• For details, load references/payment-saved-card.md.

Saving Cards

Use the saving-cards reference when the task is about obtaining a new rectoken, not charging an existing one.

• Request token issuance with required_rectoken=Y during create-order flow.
• Option 1: save card during verification with verification=Y and a small amount that is held then reversed.
• Option 2: save card during the first real purchase and return the token alongside the purchase result.
• rectoken is returned to response_url and server_callback_url.
• For details, load references/saving-cards.md.

Reversals

Use reversals to refund or reverse an approved payment fully or partially.

• Create a reversal with POST /api/reverse/order_id.
• For a full reversal, send amount equal to the original order actual_amount.
• Multiple partial reversals are allowed while their sum is less than or equal to actual_amount.
• Use reverse_id as an idempotency key for safe retry of partial reversals.
• Check reversal status through POST /api/status/order_id; compare accumulated reversal_amount with actual_amount.
• For details, load references/reversal.md.

Captures

Use capture to charge funds previously held by a card preauthorization.

• Create the original payment with preauth=Y.
• Capture with POST /api/capture/order_id.
• Card payments support preauth/capture; other payment methods use one-stage charge behavior.
• Multiple captures are not allowed. A single full or partial capture is available.
• Check capture status through POST /api/status/order_id; parse additional_info.capture_status and additional_info.capture_amount.
• For details, load references/capture.md.

Subscriptions

Use subscriptions for fixed scheduled charges such as daily, weekly, monthly, or yearly billing.

• Create subscription checkout by adding subscription=Y and recurring_data to /api/checkout/redirect, /api/checkout/token, or /api/checkout/url.
• Do not use subscriptions with Payment (direct) integration or Open Banking.
• Supported methods are Visa/MasterCard/Amex cards, Apple Pay, and Google Pay.
• Start or stop an existing subscription with POST /api/subscription and action=start or action=stop.
• For details, load references/subscriptions.md.

Additional Data

Use reservation_data when the merchant needs to attach extra payer, device, checkout-field, or product/fiscalisation metadata to a purchase request.

• reservation_data is BASE64-encoded JSON attached to create-purchase requests.
• Keep keys and values ASCII/Latin-alphanumeric plus separator symbols as documented.
• Use it for customer metadata, fields_custom[], products[], settlement_id, and risk/fiscalisation-related extras.
• Be careful with 3ds_mandatory: the docs say it can be used only after approval from the Flitt risk team.
• For details, load references/additional-data.md.

Currencies

Use the currency matrix before wiring or validating the Flitt currency field.

• Supported bank-card processing currencies depend on merchant country.
• Do not assume USD or EUR are available for every merchant geography.
• For details, load references/currencies.md.

Callbacks

Use Flitt callbacks as the reliable asynchronous status source for payments and follow-up operations.

• Flitt sends JSON POST callbacks to server_callback_url.
• Treat the callback as successfully processed only when your endpoint returns HTTP 200 OK.
• Flitt does not follow redirects, so callback endpoints must respond directly.
• Verify callback signatures before trusting payment state, and process callbacks idempotently by order_id and/or payment_id.
• For details, load references/callbacks.md.

Signatures

Use the dedicated signature reference when implementing or debugging request, response, callback, or redirect signature handling.

• Flitt signs request and response data with SHA1 over secret|sorted-nonempty-values.
• Exclude signature and, for verification, response_signature_string.
• Keep SHA1 hex lowercase.
• Be especially careful with zero values, empty values, UTF-8 encoding, and endpoint-specific parameter sets such as /api/recurring.
• For details, load references/signature.md.

Response Codes

Use the response-code reference when deciding whether a failure is caused by merchant input, issuer decline, or Flitt/platform configuration.

• API response_code values and embedded-checkout JavaScript codes have different ranges and meanings.
• Many codes are operationally actionable only after you classify ownership: merchant, issuer bank, or Flitt.
• For details, load references/response-codes.md.

Troubleshooting

When Flitt returns Invalid signature:

1. Confirm the secret key belongs to the same merchant and environment.
2. Log the exact pre-hash signature string locally, redacting the secret in shared logs.
3. Ensure empty values are omitted completely, including their | separator.
4. Ensure numeric zero is preserved as 0, not converted to empty or null.
5. Ensure signature and response_signature_string are excluded.
6. Ensure non-Latin text is sent and hashed as UTF-8.
7. Ensure the final SHA1 hex digest is lowercase.

When testing callbacks or redirects in test mode, Flitt may return response_signature_string; use it only as a diagnostic hint and never include it in verification.