> For the complete documentation index, see [llms.txt](https://docs.flowretail.com/api/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flowretail.com/api/prepayment.md).

# PrePayment

PrePayment

## Create a pre-payment on order

> Create a pre-payment on order.\
> Returns a settlementUid, and is handled at the settlements/{settlementUid} endpoint\
> \
> Required permissions: SALES\_ORDER,RETURN\_ORDER

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"PrePayment","description":"PrePayment"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]},{"integrationToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"},"integrationToken":{"scheme":"bearer","type":"http"}},"responses":{"SettlementResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementResponseSchema"}}},"description":"Example response"}},"schemas":{"SettlementResponseSchema":{"title":"SettlementResponseSchema","type":"object","required":["amount","createdAt","displayMessages","externalId","externalPaymentReference","idMethod","lastModifiedAt","parameters","settlementCode","settlementUid","settlementName","state","status","storeSettlementIssuer","tenantUserDisplayName","tenantUserUid","storePaymentMethodUid","currency","additionalDetails","creditCount","creditAmount","paymentCount","paymentAmount","storeUid","storeName","orderReceiptUid","transactions","receiptText"],"properties":{"amount":{"type":"integer"},"createdAt":{"format":"date-time","type":"string"},"displayMessages":{"type":"array","items":{"$ref":"#/components/schemas/SettlementDisplayMessageSchema"}},"externalId":{"type":"string"},"externalPaymentReference":{"type":"string","description":"The external payment reference for this settlement.\nFor invoices, this could contain the KID"},"idMethod":{"$ref":"#/components/schemas/SettlementIdMethodENUM"},"lastModifiedAt":{"format":"date-time","type":"string"},"ledgerNumber":{"description":"Ledger number must be a valid number with possible leading zeros","type":"string"},"ledgerType":{"$ref":"#/components/schemas/LedgerTypeENUM"},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/SettlementParameterResponseSchema"}},"settledAt":{"format":"date-time","type":"string"},"settlementCode":{"type":"string"},"settlementUid":{"$ref":"#/components/schemas/UID"},"settlementName":{"type":"string"},"state":{"$ref":"#/components/schemas/SettlementStateENUM"},"status":{"$ref":"#/components/schemas/SettlementStatusENUM"},"storeSettlementIssuer":{"$ref":"#/components/schemas/storeSettlementIssuerSchema"},"tenantUserDisplayName":{"type":"string"},"tenantUserUid":{"$ref":"#/components/schemas/UID"},"storePaymentMethodUid":{"$ref":"#/components/schemas/UID"},"currency":{"$ref":"#/components/schemas/SettlementCurrencySchema"},"additionalDetails":{"type":"array","items":{"$ref":"#/components/schemas/SettlementAdditionalDetailsSchema"}},"creditCount":{"type":"integer","description":"Number of credits on this settlement. Only applicable for invoice"},"creditAmount":{"type":"integer","description":"The total amount credited. Only applicable for invoice"},"paymentCount":{"type":"integer","description":"Number of payments on this settlement. Only applicable for invoice"},"paymentAmount":{"type":"integer","description":"The total amount of payments. Only applicable for invoice"},"tillUid":{"$ref":"#/components/schemas/OptionalUID"},"tillName":{"type":"string","description":"Display name of the till where the payment was registered."},"tillNumber":{"type":"integer","description":"Till register number where the payment was registered."},"storeUid":{"$ref":"#/components/schemas/OptionalUID"},"storeName":{"type":"string","description":"Display name of the store where the payment was registered."},"orderReceiptUid":{"$ref":"#/components/schemas/OptionalUID"},"authorizedAmount":{"type":"integer","description":"The total authorized amount on this settlement, calculated from authorize transactions."},"capturedAmount":{"type":"integer","description":"The total captured amount on this settlement, calculated from capture transactions."},"refundedAmount":{"type":"integer","description":"The total refunded amount on this settlement, calculated from refund transactions."},"receiptText":{"type":"string","maxLength":500,"description":"Text printed on the receipt for this payment method when configured on the tenant payment method. Empty when not set, when suppressed for this settlement type (e.g. store credit, gift cards), or when cleared."},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/SettlementTransactionSchema"}}}},"SettlementDisplayMessageSchema":{"description":"Settlement display messages","properties":{"key":{"type":"string"},"message":{"type":"string"},"timestamp":{"format":"date-time","type":"string"}},"required":["key","message","timestamp"],"title":"SettlementDisplayMessageSchema","type":"object"},"SettlementIdMethodENUM":{"enum":["NO_CVM_RULE_PERFORMED","SIGNATURE","PIN_ONLINE","PIN_OFFLINE","PIN_ONLINE_AND_SIGNATURE","PIN_OFFLINE_AND_SIGNATURE","NO_CVM","FAILED","ON_DEVICE","REFUND"],"title":"SettlementIdMethodENUM","type":"string"},"LedgerTypeENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n|LEDGER | Ledger |\n|GENERAL_LEDGER | General ledger |\n|CUSTOMER_LEDGER | Customer ledger |","enum":["LEDGER","GENERAL_LEDGER","CUSTOMER_LEDGER"],"title":"LedgerTypeENUM","type":"string"},"SettlementParameterResponseSchema":{"description":"settlement parameters response","title":"SettlementParameterResponseSchema","type":"object","required":["key","value","name","type"],"properties":{"key":{"type":"string"},"value":{"type":"string"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/TenantPaymentMethodParameterTypeENUM"}}},"TenantPaymentMethodParameterTypeENUM":{"title":"TenantPaymentMethodParameterTypeENUM","type":"string","enum":["TEXT","INTEGER","NUMERIC","DATE","MOBILE","MODULUS10","MODULUS11"]},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"SettlementStateENUM":{"enum":["NOT_STARTED","IN_PROGRESS","COMPLETE","TERMINATED"],"title":"SettlementCodeENUM","type":"string"},"SettlementStatusENUM":{"enum":["NEW","PROCESSING","AUTHORIZED","CAPTURED","REFUNDED","PARTIALLY_REFUNDED","PENDING_REFUND","FAILED","CANCELLED_BY_MERCHANT","CANCELLED_BY_USER","CANCELLED_FORCE","DELETED","DENIED","REJECTED"],"title":"SettlementCodeENUM","type":"string"},"storeSettlementIssuerSchema":{"title":"storeSettlementIssuerSchema","type":"object","description":"Settlement issuer information","required":["storeSettlementIssuerUid","name","code"],"properties":{"storeSettlementIssuerUid":{"$ref":"#/components/schemas/UID"},"name":{"type":"string","description":"The name of the settlement issuer"},"code":{"type":"string","description":"The code of the settlement issuer"}}},"SettlementCurrencySchema":{"title":"SettlementCurrencySchema","type":"object","required":["amount","code","exchangeRate"],"properties":{"amount":{"type":"integer"},"code":{"type":"string"},"exchangeRate":{"type":"integer"}}},"SettlementAdditionalDetailsSchema":{"title":"SettlementAdditionalDetailsSchema","type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}},"OptionalUID":{"title":"OptionalUID","type":"string","pattern":"^[A-Za-z0-9-_]*"},"SettlementTransactionSchema":{"title":"SettlementTransactionSchema","type":"object","required":["transactionType","transactionAmount","orderReceiptUid"],"properties":{"transactionType":{"type":"string"},"pspTransactionId":{"type":"string"},"transactionAmount":{"type":"integer"},"orderReceiptUid":{"$ref":"#/components/schemas/OptionalUID"}}},"SettlementCreateRequestSchema":{"description":"Create a new settlement","title":"SettlementCreateRequestSchema","type":"object","required":["amount","settlementCode"],"properties":{"amount":{"description":"in cents, e.g. 1,50 as 150","type":"integer"},"externalId":{"description":"External reference for the settlement","type":"string"},"settlementCode":{"type":"string"},"parameters":{"description":"Refer to each payment type's options for available parameters, e.g. 'mobile' for VIPPS.","type":"array","items":{"$ref":"#/components/schemas/SettlementParameterRequestSchema"}},"settlementUid":{"$ref":"#/components/schemas/UID"}}},"SettlementParameterRequestSchema":{"description":"settlement parameters request","title":"SettlementParameterRequestSchema","type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"requestBodies":{"SettlementCreateRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementCreateRequestSchema"}}}}}},"paths":{"/tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/pre-payments":{"post":{"summary":"Create a pre-payment on order","tags":["PrePayment"],"responses":{"201":{"$ref":"#/components/responses/SettlementResponse"}},"operationId":"post-orders-pre-payments","description":"Create a pre-payment on order.\nReturns a settlementUid, and is handled at the settlements/{settlementUid} endpoint\n\nRequired permissions: SALES_ORDER,RETURN_ORDER","requestBody":{"$ref":"#/components/requestBodies/SettlementCreateRequest"}}}}}
```

## Create a pre-payment refund on order

> Create a pre-payment refund on order.\
> Returns a settlementUid, and is handled at the settlements/{settlementUid} endpoint\
> \
> Required permissions: SALES\_ORDER,RETURN\_ORDER

```json
{"openapi":"3.0.2","info":{"title":"Flow Retail API version 2","version":"2.0.0"},"tags":[{"name":"PrePayment","description":"PrePayment"}],"servers":[{"description":"Flow Retail Production","url":"https://api.flowretail.com/v2"},{"description":"Flow Retail Stage","url":"https://api.stage.flowretail.com/v2"}],"security":[{"accessToken":[]},{"authToken":[]},{"integrationToken":[]}],"components":{"securitySchemes":{"accessToken":{"description":"Access token recevied after user login with a deviceToken","scheme":"bearer","type":"http"},"authToken":{"description":"Token received from the auth service","scheme":"bearer","type":"http"},"integrationToken":{"scheme":"bearer","type":"http"}},"responses":{"SettlementResponse":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementResponseSchema"}}},"description":"Example response"}},"schemas":{"SettlementResponseSchema":{"title":"SettlementResponseSchema","type":"object","required":["amount","createdAt","displayMessages","externalId","externalPaymentReference","idMethod","lastModifiedAt","parameters","settlementCode","settlementUid","settlementName","state","status","storeSettlementIssuer","tenantUserDisplayName","tenantUserUid","storePaymentMethodUid","currency","additionalDetails","creditCount","creditAmount","paymentCount","paymentAmount","storeUid","storeName","orderReceiptUid","transactions","receiptText"],"properties":{"amount":{"type":"integer"},"createdAt":{"format":"date-time","type":"string"},"displayMessages":{"type":"array","items":{"$ref":"#/components/schemas/SettlementDisplayMessageSchema"}},"externalId":{"type":"string"},"externalPaymentReference":{"type":"string","description":"The external payment reference for this settlement.\nFor invoices, this could contain the KID"},"idMethod":{"$ref":"#/components/schemas/SettlementIdMethodENUM"},"lastModifiedAt":{"format":"date-time","type":"string"},"ledgerNumber":{"description":"Ledger number must be a valid number with possible leading zeros","type":"string"},"ledgerType":{"$ref":"#/components/schemas/LedgerTypeENUM"},"parameters":{"type":"array","items":{"$ref":"#/components/schemas/SettlementParameterResponseSchema"}},"settledAt":{"format":"date-time","type":"string"},"settlementCode":{"type":"string"},"settlementUid":{"$ref":"#/components/schemas/UID"},"settlementName":{"type":"string"},"state":{"$ref":"#/components/schemas/SettlementStateENUM"},"status":{"$ref":"#/components/schemas/SettlementStatusENUM"},"storeSettlementIssuer":{"$ref":"#/components/schemas/storeSettlementIssuerSchema"},"tenantUserDisplayName":{"type":"string"},"tenantUserUid":{"$ref":"#/components/schemas/UID"},"storePaymentMethodUid":{"$ref":"#/components/schemas/UID"},"currency":{"$ref":"#/components/schemas/SettlementCurrencySchema"},"additionalDetails":{"type":"array","items":{"$ref":"#/components/schemas/SettlementAdditionalDetailsSchema"}},"creditCount":{"type":"integer","description":"Number of credits on this settlement. Only applicable for invoice"},"creditAmount":{"type":"integer","description":"The total amount credited. Only applicable for invoice"},"paymentCount":{"type":"integer","description":"Number of payments on this settlement. Only applicable for invoice"},"paymentAmount":{"type":"integer","description":"The total amount of payments. Only applicable for invoice"},"tillUid":{"$ref":"#/components/schemas/OptionalUID"},"tillName":{"type":"string","description":"Display name of the till where the payment was registered."},"tillNumber":{"type":"integer","description":"Till register number where the payment was registered."},"storeUid":{"$ref":"#/components/schemas/OptionalUID"},"storeName":{"type":"string","description":"Display name of the store where the payment was registered."},"orderReceiptUid":{"$ref":"#/components/schemas/OptionalUID"},"authorizedAmount":{"type":"integer","description":"The total authorized amount on this settlement, calculated from authorize transactions."},"capturedAmount":{"type":"integer","description":"The total captured amount on this settlement, calculated from capture transactions."},"refundedAmount":{"type":"integer","description":"The total refunded amount on this settlement, calculated from refund transactions."},"receiptText":{"type":"string","maxLength":500,"description":"Text printed on the receipt for this payment method when configured on the tenant payment method. Empty when not set, when suppressed for this settlement type (e.g. store credit, gift cards), or when cleared."},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/SettlementTransactionSchema"}}}},"SettlementDisplayMessageSchema":{"description":"Settlement display messages","properties":{"key":{"type":"string"},"message":{"type":"string"},"timestamp":{"format":"date-time","type":"string"}},"required":["key","message","timestamp"],"title":"SettlementDisplayMessageSchema","type":"object"},"SettlementIdMethodENUM":{"enum":["NO_CVM_RULE_PERFORMED","SIGNATURE","PIN_ONLINE","PIN_OFFLINE","PIN_ONLINE_AND_SIGNATURE","PIN_OFFLINE_AND_SIGNATURE","NO_CVM","FAILED","ON_DEVICE","REFUND"],"title":"SettlementIdMethodENUM","type":"string"},"LedgerTypeENUM":{"description":"|ENUM      | Description |\n| ---------------- | ------------ |\n|LEDGER | Ledger |\n|GENERAL_LEDGER | General ledger |\n|CUSTOMER_LEDGER | Customer ledger |","enum":["LEDGER","GENERAL_LEDGER","CUSTOMER_LEDGER"],"title":"LedgerTypeENUM","type":"string"},"SettlementParameterResponseSchema":{"description":"settlement parameters response","title":"SettlementParameterResponseSchema","type":"object","required":["key","value","name","type"],"properties":{"key":{"type":"string"},"value":{"type":"string"},"name":{"type":"string"},"type":{"$ref":"#/components/schemas/TenantPaymentMethodParameterTypeENUM"}}},"TenantPaymentMethodParameterTypeENUM":{"title":"TenantPaymentMethodParameterTypeENUM","type":"string","enum":["TEXT","INTEGER","NUMERIC","DATE","MOBILE","MODULUS10","MODULUS11"]},"UID":{"title":"UID","type":"string","pattern":"^[A-Za-z0-9-_]+"},"SettlementStateENUM":{"enum":["NOT_STARTED","IN_PROGRESS","COMPLETE","TERMINATED"],"title":"SettlementCodeENUM","type":"string"},"SettlementStatusENUM":{"enum":["NEW","PROCESSING","AUTHORIZED","CAPTURED","REFUNDED","PARTIALLY_REFUNDED","PENDING_REFUND","FAILED","CANCELLED_BY_MERCHANT","CANCELLED_BY_USER","CANCELLED_FORCE","DELETED","DENIED","REJECTED"],"title":"SettlementCodeENUM","type":"string"},"storeSettlementIssuerSchema":{"title":"storeSettlementIssuerSchema","type":"object","description":"Settlement issuer information","required":["storeSettlementIssuerUid","name","code"],"properties":{"storeSettlementIssuerUid":{"$ref":"#/components/schemas/UID"},"name":{"type":"string","description":"The name of the settlement issuer"},"code":{"type":"string","description":"The code of the settlement issuer"}}},"SettlementCurrencySchema":{"title":"SettlementCurrencySchema","type":"object","required":["amount","code","exchangeRate"],"properties":{"amount":{"type":"integer"},"code":{"type":"string"},"exchangeRate":{"type":"integer"}}},"SettlementAdditionalDetailsSchema":{"title":"SettlementAdditionalDetailsSchema","type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}},"OptionalUID":{"title":"OptionalUID","type":"string","pattern":"^[A-Za-z0-9-_]*"},"SettlementTransactionSchema":{"title":"SettlementTransactionSchema","type":"object","required":["transactionType","transactionAmount","orderReceiptUid"],"properties":{"transactionType":{"type":"string"},"pspTransactionId":{"type":"string"},"transactionAmount":{"type":"integer"},"orderReceiptUid":{"$ref":"#/components/schemas/OptionalUID"}}},"SettlementRefundCreateRequestSchema":{"description":"Create a new settlement refund","title":"SettlementRefundCreateRequestSchema","type":"object","required":["amount","settlementCode","referencingSettlementUid"],"properties":{"amount":{"description":"in cents, e.g. 1,50 as 150","type":"integer"},"externalId":{"description":"External reference for the settlement","type":"string"},"settlementCode":{"type":"string"},"parameters":{"description":"Refer to each payment type's options for available parameters, e.g. 'mobile' for VIPPS.","type":"array","items":{"$ref":"#/components/schemas/SettlementParameterRequestSchema"}},"settlementUid":{"description":"The settlement uid","$ref":"#/components/schemas/UID"},"referencingSettlementUid":{"description":"The settlement that is being refunded","$ref":"#/components/schemas/UID"}}},"SettlementParameterRequestSchema":{"description":"settlement parameters request","title":"SettlementParameterRequestSchema","type":"object","required":["key","value"],"properties":{"key":{"type":"string"},"value":{"type":"string"}}}},"requestBodies":{"SettlementRefundCreateRequest":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementRefundCreateRequestSchema"}}}}}},"paths":{"/tenants/{tenantUid}/stores/{storeUid}/orders/{orderUid}/pre-payments/refund":{"post":{"summary":"Create a pre-payment refund on order","tags":["PrePayment"],"responses":{"201":{"$ref":"#/components/responses/SettlementResponse"}},"operationId":"post-orders-pre-payments-refund","description":"Create a pre-payment refund on order.\nReturns a settlementUid, and is handled at the settlements/{settlementUid} endpoint\n\nRequired permissions: SALES_ORDER,RETURN_ORDER","requestBody":{"$ref":"#/components/requestBodies/SettlementRefundCreateRequest"}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.flowretail.com/api/prepayment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.