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/capture.md
View on GitHub# Flitt Capture Reference
Sources checked on 2026-05-12:
- https://docs.flitt.com/api/capture-parameters/
- https://docs.flitt.com/api/create-capture/
- https://docs.flitt.com/api/get-capture-status/
Use this reference for capture workflows: completing a card preauthorization, partial capture, and checking capture status through order status.
## Scope
Capture charges an amount previously held on a card.
Important constraints:
- The original payment must be a pre-payment/preauthorization with `preauth=Y`.
- Preauth/capture is available only for card payment methods.
- Other payment methods do not support two-stage capture and are charged in a one-stage flow.
- Capture can be full or partial.
- Multiple captures are not allowed.
- A capture with the same `amount` can be retried safely; Flitt returns the current `capture_status`.
For full capture, send `amount` equal to the original order `actual_amount`. For partial capture, send a smaller amount. If a partial capture is performed, the rest of the held amount is automatically returned to the payer card; do not also reverse the remaining held amount.
## Create Capture
Endpoint:
```text
POST https://pay.flitt.com/api/capture/order_id
Content-Type: application/json
```
Required request parameters:
| Parameter | Type | Required | Notes |
| --- | --- | --- | --- |
| `order_id` | string | yes | Merchant-generated order ID of the preauthorized order. |
| `merchant_id` | integer | yes | Flitt merchant ID. |
| `amount` | integer | yes | Capture amount without decimal separator. For full capture, equal original `actual_amount`. |
| `currency` | string | yes | Original order currency, for example `GEL`, `USD`, `EUR`, `GBP`, `CZK`, `UZS`. |
| `signature` | string | yes | SHA1 request signature. |
Optional request parameters:
| Parameter | Notes |
| --- | --- |
| `version` | Protocol version. Default `1.0.1`; version `1.0` is deprecated. |
Example request:
```json
{
"request": {
"version": "1.0.1",
"order_id": "test_12343242113",
"currency": "GEL",
"merchant_id": 1549901,
"amount": 100,
"signature": "..."
}
}
```
Normal response:
```json
{
"response": {
"capture_status": "captured",
"order_id": "test_12343242113",
"response_description": "",
"response_code": "",
"merchant_id": 1549901,
"response_status": "success"
}
}
```
Failure response contains `response_status=failure` with `error_code`, `error_message`, and `request_id`.
## Capture Status
Direct capture response contains `capture_status`:
| `capture_status` | Meaning |
| --- | --- |
| `hold` | Capture has been created but is not approved yet; continue checking order status. |
| `captured` | Capture completed successfully; funds are charged and merchant can provide service or ship goods. |
Capture status should also be checked through normal order status:
```text
POST https://pay.flitt.com/api/status/order_id
Content-Type: application/json
```
In the order status response, parse `response.additional_info` as JSON and inspect:
| Field | Meaning |
| --- | --- |
| `capture_status` | Capture state, for example `captured`. |
| `capture_amount` | Captured amount. If lower than `actual_amount`, the order was partially captured. |
Rules:
- `capture_amount = actual_amount`: full capture.
- `0 < capture_amount < actual_amount`: partial capture.
- Missing/null `capture_amount`: capture not completed or not applicable.
## Reverse Of Pre-Payment
Before capture is completed:
- Acquiring fee is not charged for pre-payment and reverse operations.
- Reversal instantly cancels the held amount.
- Only full reversal of the held amount is available; partial reverse is not allowed for pre-payment.
If only part of the held amount should be charged, perform a partial capture for the amount to charge. The rest is automatically returned. Do not reverse the difference after a partial capture.
Example:
- Held amount: `1000`
- Desired charge: `800`
- Correct action: capture `800`
- Do not additionally reverse `200`, because the remainder is returned automatically
After a payment is captured, several sequential partial reversals are available through the reversal flow.
## Implementation Checklist
- Confirm original payment was created with `preauth=Y`.
- Confirm payment method is card.
- Confirm capture has not already been completed; multiple captures are not allowed.
- Decide full vs partial capture.
- For full capture, use original `actual_amount`.
- For partial capture, use the amount to charge and let the rest return automatically.
- Sign all non-empty capture request parameters, excluding `signature`.
- Send JSON under root `request`.
- Verify response data and store `capture_status`.
- If result is uncertain or `hold`, poll `/api/status/order_id`.
- Parse `additional_info` JSON to read `capture_status` and `capture_amount`.
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 |