> For the complete documentation index, see [llms.txt](https://invoice4u.gitbook.io/invoice4u-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://invoice4u.gitbook.io/invoice4u-docs/clearing-payments/tokens-and-standing-orders.md). # Tokens & Standing Orders Save a customer's card as a **token** for later server-side charges, or set up a **standing order** (recurring monthly charge). All flows go through [`ProcessApiRequestV2`](/invoice4u-docs/clearing-payments/process-api-request-v2.md) with the flags below. {% hint style="info" %} Tokens and standing orders must be enabled on your clearing terminal. Otherwise you get `ApiTokenizationNotApprovedInClearingTerminal` (309) / `ApiStandingOrderNotApprovedInClearingTerminal` (310). {% endhint %} ## Save a token โ€” `AddToken` Opens a hosted page that captures the card and stores a token, **without charging**. ```json { "request": { "Invoice4UUserApiKey": "", "AddToken": true, "FullName": "Israel Israeli", "Phone": "0501234567", "Email": "israel@example.com", "CustomerId": 88231, "ReturnUrl": "https://shop.example/card-saved", "CallBackUrl": "https://shop.example/api/i4u-callback" } } ``` Redirect the customer to the returned `ClearingRedirectUrl`. The token is stored against the customer (`CustomerId` recommended so the token is retrievable later). ```mermaid flowchart LR classDef step fill:#E7D9FC,stroke:#9B6DD6,color:#333 classDef dec fill:#D2F0D2,stroke:#4CAF50,color:#333 classDef err fill:#FFD9A0,stroke:#E8A33D,color:#333 classDef cb fill:#BBDEFB,stroke:#42A5F5,color:#333 classDef page fill:#F5F5F5,stroke:#999,color:#333 A[ProcessApiRequestV2
AddToken]:::step --> B{Tokens enabled
on terminal?}:::dec B -- "โœ— / expired" --> E1[ApiTokenizationNotApproved
InClearingTerminal 309]:::err B -- โœ“ --> C[๐Ÿ–ฅ Card capture page
NO charge]:::page C --> D{Capture OK?}:::dec D -- โœ“ --> F[Token stored for CustomerId โ€”
replaces previous token]:::step F --> G[CallBackUrl notified]:::cb D -- โœ— --> H[Failure posted
to CallBackUrl]:::err ``` ## Save + charge โ€” `AddTokenAndCharge` Same as above but also charges `Sum` immediately. Cannot be combined with `IsStandingOrderClearance` (`ApiBadRequestChargeMethodMustBeSelected`, 319). ```mermaid flowchart LR classDef step fill:#E7D9FC,stroke:#9B6DD6,color:#333 classDef dec fill:#D2F0D2,stroke:#4CAF50,color:#333 classDef err fill:#FFD9A0,stroke:#E8A33D,color:#333 classDef cb fill:#BBDEFB,stroke:#42A5F5,color:#333 classDef page fill:#F5F5F5,stroke:#999,color:#333 A[ProcessApiRequestV2
AddTokenAndCharge]:::step --> B{Also
IsStandingOrderClearance?}:::dec B -- โœ“ --> E1[ApiBadRequestChargeMethod
MustBeSelected 319]:::err B -- โœ— --> C{Tokens enabled?}:::dec C -- โœ— --> E2[ApiTokenizationNotApproved
InClearingTerminal 309]:::err C -- โœ“ --> D[๐Ÿ–ฅ Capture + charge page
Sum charged]:::page D --> F{Result}:::dec F -- "token + charge โœ“" --> G[Token stored ยท CallBackUrl
doc if IsDocCreate]:::cb F -- "token โœ“, charge โœ—" --> E3[ApiTokenWasCreatedChargeFailed 313
token kept]:::err F -- "capture โœ—" --> E4[Failure posted
to CallBackUrl]:::err ``` ## Charge a saved token โ€” `ChargeWithToken` Server-to-server, synchronous โ€” no redirect: ```json { "request": { "Invoice4UUserApiKey": "", "ChargeWithToken": true, "CustomerId": 88231, "Sum": 117.0, "Description": "Monthly subscription - July", "IsDocCreate": true, "DocHeadline": "Monthly subscription - July" } } ``` The stored token for the customer is resolved automatically. A stored token must exist for the customer โ€” otherwise `ApiTokenDoesntExistForThatCustomer` (304). Saving a new card for the customer **replaces** the previous token, so at most one token is kept per customer. On success the response carries the confirmation and, with `IsDocCreate`, the created document fields. If the token was created but a follow-up charge failed: `ApiTokenWasCreatedChargeFailed` (313). ```mermaid flowchart LR classDef step fill:#E7D9FC,stroke:#9B6DD6,color:#333 classDef dec fill:#D2F0D2,stroke:#4CAF50,color:#333 classDef err fill:#FFD9A0,stroke:#E8A33D,color:#333 classDef cb fill:#BBDEFB,stroke:#42A5F5,color:#333 A[ProcessApiRequestV2
ChargeWithToken]:::step --> B{Stored token found
for customer?}:::dec B -- โœ— --> E1[ApiTokenDoesntExist
ForThatCustomer 304]:::err B -- โœ“ --> C[Sync charge at provider
no redirect]:::step C --> D{Charge OK?}:::dec D -- โœ“ --> F[Log + confirmation
+ doc if IsDocCreate]:::step F --> G[Result inline
in response]:::cb D -- โœ— --> H[ClearingError 32
in response]:::err ``` ## Standing order โ€” `IsStandingOrderClearance` Sets up a recurring monthly charge via the hosted page: | Field | Type | Required | Description | | -------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------- | | `IsStandingOrderClearance` | boolean | Yes | Standing-order mode. | | `StandingOrderDuration` | int | **Yes** | Number of monthly charges (`ApiStandingOrderDurationNotFilled`, 301). | | `DocHeadline` | string | **Yes** | Subject for the recurring documents (`ApiStandingOrderDocSubjectNotFilled`, 302). | | `Sum` | double | Yes | Monthly amount. | | `StandingOrderFirstChargeAmount` | double | No | Different amount for the first charge. | | `StandingOrderCallBackUrl` | string | No | Called on every recurring charge. Must be a well-formed absolute URL (`ApiStandingOrderCallbackurlInvalid`, 318). | ```json { "request": { "Invoice4UUserApiKey": "", "IsStandingOrderClearance": true, "StandingOrderDuration": 12, "Sum": 99.0, "DocHeadline": "Pro plan subscription", "FullName": "Israel Israeli", "Phone": "0501234567", "Email": "israel@example.com", "ReturnUrl": "https://shop.example/subscribed", "StandingOrderCallBackUrl": "https://shop.example/api/i4u-recurring" } } ``` ```mermaid flowchart LR classDef step fill:#E7D9FC,stroke:#9B6DD6,color:#333 classDef dec fill:#D2F0D2,stroke:#4CAF50,color:#333 classDef err fill:#FFD9A0,stroke:#E8A33D,color:#333 classDef cb fill:#BBDEFB,stroke:#42A5F5,color:#333 classDef page fill:#F5F5F5,stroke:#999,color:#333 A[ProcessApiRequestV2
IsStandingOrderClearance]:::step --> B{Standing-order
request valid?}:::dec B -- โœ— --> E1[ApiStandingOrderDurationNotFilled 301
ApiStandingOrderDocSubjectNotFilled 302
ApiStandingOrderCallbackurlInvalid 318
ApiStandingOrderNotApprovedInClearingTerminal 310]:::err B -- โœ“ --> C[๐Ÿ–ฅ Setup page โ€” card
captured as token]:::page C --> D{First charge OK?
FirstChargeAmount override}:::dec D -- โœ— --> E2[Failure posted
to callback]:::err D -- โœ“ --> L subgraph L[๐Ÿ” Monthly ร— StandingOrderDuration] direction LR M[Charge token]:::step --> N{OK?}:::dec N -- โœ“ --> O[Create doc]:::step --> P[POST StandingOrder
CallBackUrl]:::cb N -- โœ— --> Q[Failure posted
to callback]:::err P --> R[Next month]:::step --> M end ``` ## Errors | Error (ID) | Meaning | | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | | `ApiTokenizationNotApprovedInClearingTerminal` (309) | Tokens not enabled on the terminal (or token feature expired). | | `ApiStandingOrderNotApprovedInClearingTerminal` (310) | Standing orders not enabled. | | `ApiTokenDoesntExistForThatCustomer` (304) | No (or multiple) stored token for the customer. | | `ApiTokenWasCreatedChargeFailed` (313) | Token stored, charge declined. | | `ApiStandingOrderDurationNotFilled` (301) / `ApiStandingOrderDocSubjectNotFilled` (302) / `ApiStandingOrderCallbackurlInvalid` (318) | Standing-order validation. | | `ApiBadRequestChargeMethodMustBeSelected` (319) | Conflicting mode flags. |