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/signature.md
View on GitHub# Flitt Signature Reference
Source checked on 2026-05-12:
- https://docs.flitt.com/api/building-signature/
Use this reference for Flitt request/response/callback signature generation and signature mismatch debugging.
## Signature Algorithm
Flitt uses SHA1 for the `signature` parameter in:
- create-order requests
- create-order responses
- callbacks
- redirect/response payloads
Build the signature string as:
1. Start with the merchant payment secret key.
2. Add all non-empty request or response parameter values.
3. Sort parameters alphabetically by key before taking values.
4. Exclude `signature`.
5. When verifying responses/callbacks, also exclude `response_signature_string`.
6. Join values with `|`.
7. Hash the UTF-8 encoded string with SHA1.
8. Use lowercase hex output.
Example string from the docs:
```text
test|1000|GEL|1549901|Test payment|TestOrder2|http://myshop/callback/
```
If a parameter is absent or empty, do not include its separator.
## Official Python Example
The Flitt docs provide this Python logic:
```python
from hashlib import sha1
def get_signature(secret_key, params):
data = [secret_key]
data.extend(
[
str(params[key])
for key in sorted(iter(params.keys()))
if params[key] != "" and params[key] is not None and key != "signature"
]
)
return sha1("|".join(data).encode("utf-8")).hexdigest()
```
For callback/response verification, remove `response_signature_string` before applying the same algorithm.
## Request And Callback Verification
The bundled helper in this skill matches the documented flat-parameter algorithm:
```bash
python3 ~/.codex/skills/flitt-payments/scripts/flitt_signature.py \
--secret "$FLITT_PAYMENT_KEY" \
--params-file payload.json
```
To verify against a known signature:
```bash
python3 ~/.codex/skills/flitt-payments/scripts/flitt_signature.py \
--secret "$FLITT_PAYMENT_KEY" \
--params-file payload.json \
--verify "$EXPECTED_SIGNATURE"
```
The helper automatically signs the inner `request` or `response` object when present.
## Troubleshooting Invalid Signature
When Flitt returns `error_message: "Invalid signature"` for an API call, the docs recommend checking:
- the correct payment secret key for the environment/merchant
- UTF-8 encoding for non-Latin input
- that a numeric `0` value was not converted to null/empty
- the exact pre-hash string used by your code
- omission of separators for empty parameters
- lowercase SHA1 output
- exclusion of the `signature` parameter from the calculation
- endpoint-specific parameter sets, especially `/api/recurring`
The docs also suggest comparing your pre-hash string with Flitt’s returned `response_signature_string` diagnostic when it is present in an error context.
## Callback Or Redirect Signature Mismatch
When verifying a POST callback to `server_callback_url` or a POST redirect to `response_url`, common causes are:
- forgetting to remove `response_signature_string`
- including empty values in the signature string
- uppercasing the SHA1 digest
- signing the wrong JSON level
- using the wrong secret key
For callback/redirect payloads, verify the flat payload object and exclude:
- `signature`
- `response_signature_string`
## Recurring Endpoint Caveat
Flitt explicitly notes that `/api/recurring` should include only the parameters necessary for that endpoint in the signature calculation. Do not accidentally sign parameters that belong to redirect or other flows.
## Implementation Checklist
- Generate signatures only on the server.
- Log the pre-hash string locally when debugging, but never expose the unmasked secret in shared logs.
- Exclude `signature` from all calculations.
- Exclude `response_signature_string` from response/callback verification.
- Omit empty/null fields entirely.
- Preserve zero values.
- Encode as UTF-8.
- Keep SHA1 output lowercase.
- Use endpoint-specific parameter sets.
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 |