Parsa-29/loop-config / skills/flitt-payments
flitt-payments
VerifiedFlitt payment API implementation guidance for auth, SHA1 request/callback signatures, sandbox testing, hosted checkout, Payment (redirect), Payment (direct), saved-card /api/recurring charges, card token saving, scheduled subscriptions, reversals/refunds, captures for preauth payments, reservation_data payloads, supported currencies, callback/webhook handling, response codes, 3DS steps, order status polling, and response handling. Use when Codex needs to integrate or debug Flitt payments, create payment requests, build or verify signatures, attach reservation_data, validate currency support, implement callback handlers, interpret response codes, obtain or charge a rectoken, create/cancel subscriptions, reverse/refund through /api/reverse/order_id, capture through /api/capture/order_id, poll status, or troubleshoot Flitt API failures.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 12.7 KB |
| references/additional-data.md | markdown | 5.3 KB |
| references/callbacks.md | markdown | 4.4 KB |
| references/capture.md | markdown | 4.8 KB |
| references/currencies.md | markdown | 1.1 KB |
| references/payment-direct.md | markdown | 6.7 KB |
| references/payment-redirect.md | markdown | 7.3 KB |
| references/payment-saved-card.md | markdown | 5.0 KB |
| references/response-codes.md | markdown | 8.1 KB |
| references/reversal.md | markdown | 5.4 KB |
| references/saving-cards.md | markdown | 3.3 KB |
| references/sending-request.md | markdown | 3.9 KB |
| references/signature.md | markdown | 3.9 KB |
| references/subscriptions.md | markdown | 5.6 KB |
| references/testing-auth.md | markdown | 3.5 KB |
| scripts/flitt_signature.pyexecutable | script | 2.6 KB |
references/payment-saved-card.md
View on GitHub# Flitt Payment With Saved Card Reference
Sources checked on 2026-05-12:
- https://docs.flitt.com/api/order-parameters-recurring/
- https://docs.flitt.com/api/create-order-recurring/
Use this reference for Payment with saved card: charging an existing `rectoken` with `/api/recurring`.
## Scope
Payment with saved card charges a previously saved card token (`rectoken`). This is a host-to-host JSON API flow.
Important Flitt constraints:
- Endpoint: `POST https://pay.flitt.com/api/recurring`
- Request format: JSON with root `request`
- Response is returned in the same host-to-host request
- Redirect is not available on this endpoint
- 3DSecure is not available on this endpoint
- If 3DSecure is required, use Payment (direct) specifications instead
Treat `rectoken` as sensitive tokenized payment data. Do not log it in full; redact it in traces, errors, and analytics.
## Request Parameters
Minimum signed saved-card charge fields:
| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `order_id` | string | yes | Merchant-generated order ID. |
| `merchant_id` | integer | yes | Flitt merchant ID. |
| `order_desc` | string | yes | Merchant order description, always UTF-8. |
| `amount` | integer | yes | Amount without decimal separator; `1020` GEL means 10 lari and 20 tetri. |
| `currency` | string | yes | Currency code, for example `GEL`, `USD`, `EUR`, `GBP`, `CZK`, `UZS`. |
| `rectoken` | string | yes | Card token for recurring/saved-card transaction. |
| `signature` | string | yes | SHA1 request signature. |
Common optional fields:
| Parameter | Notes |
| --- | --- |
| `version` | Protocol version. Default `1.0.1`; version `1.0` is deprecated. |
| `cvv2` | Card CVV2/CVC2 code when required by the payment scenario. Do not store or log it. |
| `client_ip` | Customer IP address. |
| `server_callback_url` | Server-to-server callback URL after payment completion. |
| `lifetime` | Order lifetime in seconds. Default `36000`; maximum `69120000`. |
| `merchant_data` | Arbitrary data returned in callbacks and reports. |
| `preauth` | `N` charges immediately; `Y` authorizes for later capture. Default `N`. Visa/MasterCard only. |
| `sender_email` | Customer email. |
| `product_id` | Merchant product or service ID. |
## Create Saved-Card Order
Endpoint:
```text
POST https://pay.flitt.com/api/recurring
Content-Type: application/json
```
Request body:
```json
{
"request": {
"order_id": "test_recurring_payment123",
"order_desc": "Debit by token transaction",
"currency": "GEL",
"amount": 4600,
"rectoken": "REDACTED_RECTOKEN",
"merchant_id": 1549901,
"signature": "..."
}
}
```
Normal response contains standard payment response parameters:
```json
{
"response": {
"response_status": "success",
"order_status": "approved",
"payment_id": 822895805,
"rectoken": "REDACTED_RECTOKEN",
"actual_amount": "4600",
"currency": "GEL"
}
}
```
Failure response contains `response_status=failure` with `error_code`, `error_message`, and `request_id`.
## Response Handling
Use the same final-payment rules as other Flitt payment flows:
- Verify response/callback signatures before trusting final payment data.
- Treat `response_status` as API request processing state, not payment approval.
- Treat `order_status=approved` as the successful payment result.
- Store `payment_id` when returned.
- Parse `additional_info` as JSON when bank/card/payment-method metadata is needed.
- Expect `rectoken` to be present in the response and redact it in logs.
Common response fields:
| Field | Meaning |
| --- | --- |
| `order_status` | Payment state such as `approved` or `declined`. |
| `payment_id` | Unique Flitt payment ID. |
| `rectoken` | Saved card token used for/returned by the transaction. |
| `actual_amount` / `actual_currency` | Amount/currency actually charged. |
| `response_code` / `response_description` | Decline code and description when declined. |
| `additional_info.schemeid` | Scheme/client-initiated transaction identifier when returned. |
| `response_signature_string` | Test-mode diagnostic only; exclude from signature verification. |
## Obtaining A Rectoken
This reference covers charging with an existing token. To obtain a token, use a flow that requests token return, such as:
- Payment (redirect) or embedded/tokenized checkout with `required_rectoken=Y`
- Payment (direct) where token return is enabled and PCI scope is intentional
Persist tokens using the project's secure storage conventions. Associate tokens with the customer/payment method record, not only with a single order.
## Implementation Checklist
- Confirm a valid `rectoken` exists before creating `/api/recurring` order.
- Generate and persist a new merchant `order_id` for each saved-card charge.
- Sign all non-empty request parameters, including `rectoken`, excluding `signature`.
- Send JSON under root `request`.
- Do not attempt redirect or 3DS on `/api/recurring`.
- Include `server_callback_url` when possible.
- Redact `rectoken` and `cvv2` from logs.
- Verify callback/final response signature and update order idempotently.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |