{"openapi": "3.0.0", "info": {"title": "Public REST API", "version": "v1", "description": "All the endpoints below have a prefix of `https://portal.klix.app/api/v1/` (e.g. `POST https://portal.klix.app/api/v1/purchases/`).\n\nYou will need your API key that you can obtain in the Developers section in your account. Please use this key as a bearer token in the Authorization header included in every request: `Authorization: Bearer `.\n\nBefore starting the development, we recommend checking out the list of ready-to-go connectors to the popular platforms we\u2019ve already built for you. It might save you some precious time if you use one of these to develop your project.\n\nPlugins: [WooCommerce](https://portal.klix.app/apis/plugins/WooCommerce%20v3.5+), [OpenCart](https://portal.klix.app/apis/plugins/OpenCart%20v3.0+), [Magento](https://portal.klix.app/apis/plugins/Magento%20v2.0+), [PrestaShop](https://portal.klix.app/apis/plugins/PrestaShop%20v1.7+)\n\n\n\nLibraries: [PHP](https://portal.klix.app/apis/libraries/PHP), [Java](https://portal.klix.app/apis/libraries/Java), [C#](https://portal.klix.app/apis/libraries/C%23), [Node.js](https://portal.klix.app/apis/libraries/Node.js)\n\nSDKs: [iOS](https://portal.klix.app/apis/sdks/iOS), [Android](https://portal.klix.app/apis/sdks/Android)\n***\n\n# Online Purchases\n\n## Prebuilt checkout (Redirect)\n\nRedirect integration allows running payments using the prebuilt payment flow.\n\nTo accept payments in your application or website via redirect, use `POST /purchases/` request to create the `Purchase` and receive the `checkout_url`. Redirect the customer to the `checkout_url` to enter their card details for processing. After the payment is processed, the system will redirect the customer back to your website (take note of `success_redirect`, `failure_redirect`).\n\n*You have three options to check payment status:*\n\n1. Use `success_callback` parameter of the `Purchase` object.\n\n2. Use `GET /purchases//` request.\n\n3. Set up a Webhook using the Developers section of your account or use Webhook API to listen to `purchase.paid`, or `purchase.payment_failure` event on your server.\n\nSetting the `skip_capture` flag to `true` allows you to separate the authentication and payment execution steps, allowing you to reserve funds on the customer's card account for some time.\n\nThis flag can also enable preauthorization capability, allowing you to save the card without a financial transaction, if possible.\n\nIf the customer agrees to store his card for future purchases, there will be an option to pay with a single click next time. To enable this, create a `Client` object for each of your clients and provide `client_id` parameter value in your Purchase creation requests.\n\nTo create a Purchase or a BillingTemplate, you must specify the `Brand ID` and `API key`. You can find both in the Developers section of your account.\n\n\n\n***\n\n# Billing\n\n## Invoicing\n\nTo send one-off invoices, use `POST /billing/` request. It's similar to `POST /purchases/` except that customers are an array, allowing you to bulk-issue invoices to several customers at once.\n\nTo send invoices using a template, use a separate `POST /billing_templates/` request (without `clients`!). Then, for each of your clients, use `POST /billing_templates/{billing_template_id}/send_invoice/`.\n\nIf the customer agrees to store his card for future purchases, then the next time the option to pay with a single click will appear if the payment channel supports tokenization.\n\n***\n\n## Subscriptions\n\nSubscriptions allow you to automate recurring purchases. You can create a subscription using the same request `POST /billing_templates/` as for invoices. To create a subscription billing template, specify `is_subscription: true` and `subscription_*` fields in `POST /billing_templates/` request body. Then, add subscribers using the `POST /billing_templates//add_subscriber/` request.\n\nIf the payment channel supports tokenization and the customer agreed to store his datafor future purchases, payments will be processed automatically, while the customer will get a receipt for each purchase. Note that whenever a subscription payment fails, your customer will automatically receive an invoice he can pay (and store a new card for upcoming payments in the process). Your system will also receive the `purchase.subscription_charge_failure` webhook event, if configured.\n\nBy default, the system generates invoices and processes subscription payments at the beginning of the billing cycle.\n\nIf you want to send an invoice or charge a customer at the end of the billing cycle, just set `subscription_charge_period_end` to `true` in `POST /billing_templates/` request.\n\nThe API also provides you with an option to give a trial to your customers before enabling paid subscription period. To do that just set `subscription_trial_periods` in `POST /billing_templates/` request.\n\n***\n\n# Callbacks\n\nTwo methods for defining asynchronous callbacks are supported - `Purchase` success callbacks and webhooks.\n\n## Purchase success callbacks\n\n`Purchase` success callbacks are defined by providing a target URL in the `success_callback` field on `Purchase` creation (see [POST /purchases/](#/Purchases/purchases_create)). The system will generate a callback when:\n* a `Purchase` with `skip_capture=false` is successfully paid;\n* a `Purchase` with `skip_capture=true` is successfully captured (see [POST /purchases/{id}/capture/](#/Purchases/purchases_capture));\n* a `Purchase` is successfully paid using a recurring token (see [POST /purchases/{id}/charge/](#/Purchases/purchases_charge));\n\nThese callbacks pass a JSON-encoded `Purchase` as their payload. The payload represents a snapshot of the state of the `Purchase` when the event was created. The payload will include an `event_type` field to indicate which specific event (see [Event schema](#model-Event)) triggered the callback.\n\nThe payload is signed using a company-wide key pair. You can obtain the public key with `GET /public_key/`. See the `Authentication` section below for more details.\n\n## Webhooks\n\nFor creating and modifying webhooks, see the Webhook [CRUD API specification](#operations-tag-Webhooks).\n\n`Webhook` callback payloads are signed using a dedicated key pair. You can obtain the public key from `Webhook.public_key`. See the [Authentication](#callback-auth) section below for more details.\n\n## Delivery protocol\n\nWhen a callback is not successfully delivered (received by the target server and responded to with a 200 series HTTP response code), the system will make up to 8 additional attempts at exponentially increasing intervals between attempts. No further delivery attempts will be made if the callback is not successfully delivered 36 hours after triggering.\n\nPlease note that due to the asynchronous nature of network requests, it is possible for a callback delivery confirmation (HTTP response with a 200 series status code) to not properly arrive from the callback's target server. Therefore it is possible in case of severe network faults for the target server to receive a callback, respond to it with a 200 series HTTP status code and then receive the same callback after an interval.\n\nCallback deliveries are guaranteed to be sequential to events triggered on their source objects. For example, when registering webhooks for both the `purchase.created` and `purchase.paid` events, there will be no `purchase.paid` callbacks for this `Purchase` until all `purchase.created` callbacks for this `Purchase` are successfully delivered.\n\n## Authentication\n\nPayloads are signed using asymmetric A.K.A. public-key cryptography to guarantee the authenticity of delivered callbacks. Each callback delivery request includes an X-Signature header field. This field contains a base64-encoded RSA PKCS#1 v1.5 signature of the SHA256 digest of the request body buffer.\n\nYou can obtain the public key for `Webhook` authentication from `Webhook.public_key` of the corresponding `Webhook`.\n\nYou can obtain the public key for success callback authentication from [GET /public_key/](#operations-Public_Key-public_key).\n\nPlease note the provider is not responsible for any financial losses incurred due to not implementing payload signature verification.\n"}, "servers": [{"url": "/api/v1"}], "paths": {"/purchases/": {"post": {"operationId": "purchases_create", "responses": {"201": {"$ref": "#/components/responses/Purchase"}, "400": {"$ref": "#/components/responses/400"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Purchase"}, "example": {"client": {"email": "test@test.com"}, "purchase": {"products": [{"name": "Bulk Part 1", "price": 500, "quantity": 1}, {"name": "Bulk Part 2", "price": 500, "quantity": 2}], "payment_method_details": {"pis_bulk_purchase": [{"creditor_name": "John Doe", "creditor_iban": "LV55HABA1111111111111"}, {"creditor_name": "Jane Doe", "creditor_iban": "LV55HABA1111111111112"}], "pis_purchase": {"creditor": {"name": "Jenny Doe", "iban": "LV55HABA1111111111113"}}}}, "brand_id": "409eb80e-3782-4b1d-afa8-b779759266a5"}}}}, "summary": "Create a purchase \u2013 the main request for any e-commerce integration.", "description": "To run payments in your application use `POST /purchases/`, request to register payments and receive the checkout link (`checkout_url`). After the payment is processed, gateway will redirect the client back to your website (take note of `success_redirect`, `failure_redirect`).\n\nYou have three options to check payment status: 1) use `success_callback` parameter of `Purchase` object; 2) use `GET /purchases//` request; 3) set up a Webhook using the UI or Webhook API to listen to `purchase.paid` or `purchase.payment_failure` event on your server.\n\nUsing `skip_capture` flag allows you to separate the authentication and payment execution steps, allowing you to reserve funds on payer\u2019s card account for some time. This flag can also enable preauthorization capability, allowing you to save the card without a financial transaction, if available.\n\nIn case making a purchase client agrees to store his card for the upcoming purchases, next time he will be able to pay in a single click. \n\nBulk purchase products must be provided in `purchase.products` and must match the number of creditors. Creditors must be provided in `purchase.payment_method_details.pis_bulk_purchase`.\n\nPayment Initiation Service (PIS) purchase creditors can be overridden by specifying the creditor details under the `purchase.payment_method_details.pis_purchase` key.", "tags": ["Purchases"]}}, "/purchases/{id}/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "purchases_read", "responses": {"200": {"$ref": "#/components/responses/Purchase"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Retrieve an object by ID.", "tags": ["Purchases"]}}, "/purchases/{id}/cancel/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "purchases_cancel", "responses": {"200": {"$ref": "#/components/responses/Purchase"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Cancel a pending purchase.", "description": "If you have a Purchase that payment is possible for, using this request you can guarantee that it won't be paid.", "tags": ["Purchases"]}}, "/purchases/{id}/release/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "purchases_release", "responses": {"200": {"$ref": "#/components/responses/Purchase"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Release funds on hold.", "description": "Release funds reserved for a Purchase (`status == hold`). You can place a `hold` (authenticate the payment) using `skip_capture == true` when creating the Purchase and ensuring your client submits the payment form.\n\nIf this operation takes too long to be processed on the acquirer side - you will get a response with status code 200 and a Purchase object having `status` = `pending_release` in body (you will receive a corresponding Webhook callback too for a `purchase.pending_release` event). To be notified of a successful operation completion, please subscribe to `purchase.released` callback event - it will deliver an updated Purchase with `status` = `released`.\n\nIf fund release fails due to payment processing error, you will receive HTTP response code 400 with error code `purchase_release_error`. In this case, to get more details about the error, you should perform a `GET /purchase/` request for the Purchase you tried to release funds for. In `transaction_data.attempts[]` array (newest element first) you'll find the corresponding attempt with error code and description in `.error` parameter.", "tags": ["Purchases"]}}, "/purchases/{id}/capture/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "purchases_capture", "requestBody": {"required": false, "content": {"application/json": {"schema": {"properties": {"amount": {"type": "integer", "description": "Amount to be captured. Used to perform partial captures. Remainder will be automatically released."}}}}}}, "responses": {"200": {"$ref": "#/components/responses/Purchase"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Capture a previously authorized payment.", "description": "Capture funds reserved for a Purchase (`status == hold`). You can place a `hold` (authenticate the payment) using `skip_capture == true` when creating the Purchase and ensuring your client submits the payment form.\n\nIf this operation takes too long to be processed on the acquirer side - you will get a response with status code 200 and a Purchase object having `status` = `pending_capture` in body (you will receive a corresponding Webhook callback too for a `purchase.pending_capture` event). To be notified of a successful operation completion, please subscribe to `purchase.captured` callback event - it will deliver an updated Purchase with `status` = `paid`.\n\nIf capture fails due to payment processing error, you will receive HTTP response code 400 with error code `purchase_capture_error`. In this case, to get more details about the error, you should perform a `GET /purchase/` request for the Purchase you tried to capture. In `transaction_data.attempts[]` array (newest element first) you'll find the corresponding attempt with error code and description in `.error` parameter. By default the full amount is captured, the `amount` body param is optional.", "tags": ["Purchases"]}}, "/purchases/{id}/charge/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "purchases_charge", "responses": {"200": {"$ref": "#/components/responses/Purchase"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"properties": {"recurring_token": {"type": "string", "format": "uuid", "description": "ID of a recurring token (Purchase having `is_recurring_token == true`) to use."}}}, "example": {"recurring_token": "ea582899-78ec-4c3a-9cb3-08f922e556b6"}}}}, "summary": "Charge or Hold a purchase using a saved token.", "description": "Charge or Hold a purchase using a `recurring_token` provided in the request body. Its value should be an `id` of a Purchase that has `is_recurring_token == true`. This purchase will be paid using the same method (e.g. same card) as the one used to pay the `recurring_token` purchase. The Hold will be performed if the Purchase this method is used on has `skip_capture`: `true`.\n\nIf this operation takes too long to be processed on the acquirer side - you will get a response with status code 200 and a Purchase object having `status` = `pending_charge` in body (you will receive a corresponding Webhook callback too for a `purchase.pending_charge` event). To be notified of a successful operation completion, please subscribe to `purchase.paid` (or `purchase.hold`) callback event - it will deliver an updated Purchase with `status` = `paid` or `hold` respectively. Alternatively, if charge fails, you will receive a `purchase.payment_failure` callback event.\n\nIf recurring charge fails due to payment processing error, you will receive HTTP response code 400 with error code `purchase_charge_error`. In this case, to get more details about the error, you should perform a `GET /purchase/` request for the Purchase you tried to charge. In `transaction_data.attempts[]` array (newest element first) you'll find the corresponding attempt with error code and description in `.error` parameter.", "tags": ["Purchases"]}}, "/purchases/{id}/delete_recurring_token/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "purchases_delete_recurring_token", "responses": {"200": {"$ref": "#/components/responses/Purchase"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Delete a recurring token associated with a purchase.", "description": "Will set `is_recurring_token` to `false`. You won't be able to use this Purchase's ID as a `recurring_token` anymore. The respective ClientRecurringToken, if any, will also be deleted.\n\nIf this operation takes too long to be processed on the acquirer side - you will get a response with status code 200 a corresponding Webhook callback for a `purchase.pending_recurring_token_delete` event. To be notified of a successful operation completion, please subscribe to `purchase.recurring_token_deleted` callback event.", "tags": ["Purchases"]}}, "/purchases/{id}/refund/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "purchases_refund", "responses": {"200": {"$ref": "#/components/responses/Payment"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "requestBody": {"required": false, "content": {"application/json": {"schema": {"required": ["client_name"], "properties": {"client_name": {"type": "string", "maxLength": 70, "description": "Name and surname of a client"}, "amount": {"type": "integer", "description": "Amount to refund in minor units of the purchase's currency - e.g. `100` for \u20ac1.00. Should not be more than `Purchase.refundable_amount`. \n\nOptional; if not provided, a full refund will be executed. See the description for `Purchase.refund_availability` field."}}}, "example": {"client_name": "Janis Kalnins", "amount": 100}}}}, "summary": "Refund a paid purchase.", "description": "Will generate a Payment object and return it as a successful response. \n\nOptional `amount` argument can be included in the request body to request a partial refund. \n\nRequired `client_name` argument can be included in the request body to specify client name, otherwise, will be taken from `purchase.client.full_name` or `purchase.full_name`. \n\nConsult `refund_availability` field on Purchase on details whether this Purchase can be refunded or not. \n\nIf `refund_availability` is `pis_all` or `pis_partial`, then modify your request body as in request body example below. \n\nIf this operation takes too long to be processed on the acquirer side - you will get a response with status code 200 and a Purchase object having `status` = `pending_refund` in body (you will receive a corresponding Webhook callback too for a `purchase.pending_refund` event). To be notified of a successful operation completion, please subscribe to `payment.refunded` callback event - it will deliver a Payment generated by this refund. \n\nIf refund fails due to payment processing error, you will receive HTTP response code 400 with error code `purchase_refund_error`. In this case, to get more details about the error, you should perform a `GET /purchase/` request for the Purchase you tried to refund. In `transaction_data.attempts[]` array (newest element first) you'll find the corresponding attempt with error code and description in `.error` parameter.", "tags": ["Purchases"]}}, "/purchases/{id}/mark_as_paid/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "purchases_mark_as_paid", "responses": {"200": {"$ref": "#/components/responses/Purchase"}, "404": {"$ref": "#/components/responses/404"}}, "requestBody": {"required": false, "content": {"application/json": {"schema": {"properties": {"paid_on": {"type": "number", "description": "UTC timestamp at which this purchase was paid. Current time will be used if omitted."}}}, "example": {"paid_on": 1635162311}}}}, "summary": "Mark a purchase as paid.", "description": "Will set the purchase's status to `paid`. `purchase.marked_as_paid` field will also be set to true to distinguish this purchase.", "tags": ["Purchases"]}}, "/purchases/{id}/resend_invoice/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "purchases_resend_invoice", "responses": {"200": {"$ref": "#/components/responses/Purchase"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Re-sends invoice", "description": "Will re-send the invoice.", "tags": ["Purchases"]}}, "/payment_methods/": {"get": {"operationId": "payment_methods", "summary": "Get the list of payment methods available for your purchase.", "description": "Send this request providing, at the very least, the `brand_id` and `currency` query parameters having the same values you'd use to create your Purchase. Be sure to use the same API key you'll create your Purchase with; it will define the test_mode setting used in the lookup.\n\nIn the response body you'll receive an object with `available_payment_methods` property containing the list of payment method names available to use with your Purchase (e.g. those codes can be used in `payment_method_whitelist` field or with `?preferred={payment_method}` option of `checkout_url`).\n\nPlease note that all lookup arguments must be provided via query parameters after the endpoint, e.g. the minimal call would be similar to: `GET /api/v1/payment_methods/?brand_id=75a76529-91c7-4d98-90a9-8a641d70ee52¤cy=EUR`", "parameters": [{"name": "brand_id", "in": "query", "description": "Which brand would you like to lookup the available payment methods for. Use the same value (UUID) you'd set the `Purchase.brand_id` to.", "required": true, "schema": {"type": "string"}}, {"name": "currency", "in": "query", "description": "Currency you'd use in your Purchase in ISO 4217 format, e.g. `EUR`.", "required": true, "schema": {"type": "string"}}, {"name": "country", "in": "query", "description": "Country code in the ISO 3166-1 alpha-2 format (e.g. `GB`). Optional.", "schema": {"type": "string"}}, {"name": "recurring", "in": "query", "description": "If provided in the format of `recurring=true`, will filter out the methods that don't support recurring charges (see `POST /purchases/{id}/charge/`).", "schema": {"type": "boolean"}}, {"name": "skip_capture", "in": "query", "description": "If provided in the format of `skip_capture=true`, will filter out the methods that don't support `skip_capture` functionality (see the description for `Purchase.skip_capture field`).", "schema": {"type": "boolean"}}, {"name": "preauthorization", "in": "query", "description": "If provided in the format of `preauthorization=true`, will filter out the methods that don't support preauthorization functionality (see the description for `Purchase.skip_capture field`).", "schema": {"type": "boolean"}}, {"name": "language", "in": "query", "description": "Language code in the ISO 639-1 format (e.g. 'en'). Optional.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"available_payment_methods": {"type": "array", "items": {"type": "string", "description": "Name of the payment method, e.g. `visa`."}}, "by_country": {"type": "object", "description": "Payment method names (as returned by `available_payment_methods`) grouped by country codes they are available in. `any` key returns names of payment method available in all countries.", "properties": {"any": {"type": "array", "items": {"type": "string", "description": "Name of the payment method, e.g. `visa`."}}}, "additionalProperties": {"type": "array", "items": {"type": "string", "description": "Name of the payment method, e.g. `visa`."}}}, "country_names": {"type": "object", "description": "Human-readable names corresponding to country codes as returned by `by_country` property. `any` code is also decoded to `Other`.", "additionalProperties": {"type": "string", "description": "Human-readable name of the country."}}, "names": {"type": "object", "description": "Human-readable names of payment methods as returned by `available_payment_methods` property.", "additionalProperties": {"type": "string", "description": "Human-readable name of the payment method."}}, "logos": {"type": "object", "description": "Mapping of payment method names to respective logo file paths (relative to the hostname of API host). Some methods can be displayed as an array of logos.", "additionalProperties": {"oneOf": [{"type": "string", "description": "Path to the payment method logo file relative to API host."}, {"type": "array", "items": {"type": "string", "description": "Path to the payment method logo file relative to API host."}}]}}, "card_methods": {"type": "array", "items": {"type": "string", "description": "Names of the card methods listed in `available_payment_methods` property. All of these are grouped under `card` in other properties like `by_country`."}}, "payment_method_groups": {"type": "array", "items": {"type": "object", "properties": {"name": {"type": "string", "description": "Name of the payment method group."}, "logo": {"type": "string", "description": "Path to the logo file for the payment method group."}, "label": {"type": "string", "description": "Display label for the payment method group."}, "methods": {"type": "array", "items": {"type": "string", "description": "Names of payment methods included in this group."}}}}}}, "example": {"available_payment_methods": ["visa", "mastercard", "some_method"], "by_country": {"any": ["card"], "GB": ["some_method"]}, "country_names": {"any": "Other", "GB": "United Kingdom"}, "names": {"visa": "Visa", "mastercard": "Mastercard", "some_method": "Some method"}, "logos": {"some_method": ["/static/images/icon-visa.svg", "/static/images/icon-mastercard.svg", "/static/images/icon-maestro.svg"], "visa": "/static/images/icon-visa.svg", "mastercard": "/static/images/icon-mastercard.svg"}, "card_methods": ["american_express", "visa"], "payment_method_groups": [{"name": "klix", "logo": "/static/images/icon-klix.svg", "label": "Maks\u0101t ar karti", "methods": []}, {"name": "klix_pay_later", "logo": "/static/images/icon-klix_pay_later.svg", "label": "Maks\u0101t pa da\u013c\u0101m", "methods": ["klix_pay_later", "klix_pay_later_lv", "klix_pay_later_lt", "klix_pay_later_ee"]}, {"name": "klix_card", "logo": "/static/images/icon-klix-and-apple-pay-google-pay.svg", "label": "Maks\u0101t ar karti", "methods": ["klix", "klix_apple_pay", "klix_google_pay"]}, {"name": "bank_transfer", "logo": "/static/images/1x1transparent.gif", "label": "Bankas konts", "methods": ["citadele_ee_digilink", "citadele_lt_digilink", "citadele_lv_digilink", "swedbank_ee_pis", "swedbank_lt_pis", "swedbank_lv_pis", "seb_ee_pis", "seb_lt_pis", "seb_lv_pis", "lhv_ee_pis", "luminor_ee_pis", "luminor_lt_pis", "luminor_lv_pis"]}]}}}}}, "400": {"$ref": "#/components/responses/400"}}, "tags": ["Payment methods"]}}, "/payout_methods/": {"get": {"operationId": "payout_methods", "summary": "Get the list of payout methods available for your payout.", "description": "Send this request providing, at the very least, the `brand_id` and `currency` query parameters having the same values you'd use to create your Payout. Be sure to use the same API key you'll create your Payout with; it will define the test_mode setting used in the lookup.\n\nIn the response body you'll receive an object with `available_payout_methods` property containing the list of payout method names available to use with your Payout (e.g. those codes can be used in `payout_method_whitelist` field).\n\nPlease note that all lookup arguments must be provided via query parameters after the endpoint, e.g. the minimal call would be similar to: `GET /api/v1/payout_methods/?brand_id=75a76529-91c7-4d98-90a9-8a641d70ee52¤cy=EUR`", "parameters": [{"name": "brand_id", "in": "query", "description": "Which brand would you like to lookup the available payout methods for. Use the same value (UUID) you'd set the `Payout.brand_id` to.", "required": true, "schema": {"type": "string"}}, {"name": "currency", "in": "query", "description": "Currency you'd use in your Payout in ISO 4217 format, e.g. `EUR`.", "required": true, "schema": {"type": "string"}}, {"name": "language", "in": "query", "description": "Language code in the ISO 639-1 format (e.g. 'en'). Optional.", "schema": {"type": "string"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"available_payout_methods": {"type": "array", "items": {"type": "string", "description": "Name of the payout method, e.g. `visa`."}}, "names": {"type": "object", "description": "Human-readable names of payout methods as returned by `available_payout_methods` property.", "additionalProperties": {"type": "string", "description": "Human-readable name of the payout method."}}, "logos": {"type": "object", "description": "Mapping of payout method names to respective logo file paths (relative to the hostname of API host). Some methods can be displayed as an array of logos.", "additionalProperties": {"oneOf": [{"type": "string", "description": "Path to the payout method logo file relative to API host."}, {"type": "array", "items": {"type": "string", "description": "Path to the payout method logo file relative to API host."}}]}}, "card_methods": {"type": "array", "items": {"type": "string", "description": "Names of the card methods listed in `available_payout_methods` property. All of these are grouped under `card`."}}}, "example": {"available_payout_methods": ["visa", "mastercard", "some_method"], "names": {"visa": "Visa", "mastercard": "Mastercard", "some_method": "Some method"}, "logos": {"some_method": ["/static/images/icon-visa.svg", "/static/images/icon-mastercard.svg", "/static/images/icon-maestro.svg"], "visa": "/static/images/icon-visa.svg", "mastercard": "/static/images/icon-mastercard.svg"}, "card_methods": ["american_express", "visa"]}}}}}, "400": {"$ref": "#/components/responses/400"}}, "tags": ["Payout methods"]}}, "/billing/": {"post": {"operationId": "billing_templates_one_time_invoices", "summary": "Send an invoice to one or several clients.", "description": "Use this endpoint to send a one time invoice(-s). Provide all data of a `BillingTemplate` (see Schemas below) and, additionally, an array of one or more BillingTemplateClients in `clients`. Purchases will be created and invoices sent, one for every Client you have specified. \n\nA BillingTemplate won't be created; if you need to be able to issue repeated, similar invoices, see `POST /billing_templates/` and `POST /billing_templates/{id}/send_invoice/`. \n\nNote that unlike for other requests where you can send BillingTemplate data (like `POST /billing_templates/`), `title` and `is_subscription` are read-only for `POST /billing/`.", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"description": "A list of Purchase IDs created.", "type": "array", "items": {"$ref": "#/components/parameters/id"}, "example": ["720e2c96-ef94-4baa-90b6-d61ef6fd675a"]}}}}, "400": {"$ref": "#/components/responses/400"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"allOf": [{"required": ["clients"], "properties": {"clients": {"type": "array", "items": {"$ref": "#/components/schemas/BillingTemplateClient"}}}}, {"$ref": "#/components/schemas/BillingTemplate"}]}}}}, "tags": ["Billing"]}}, "/billing_templates/": {"post": {"operationId": "billing_templates_create", "summary": "Create a template to issue repeated invoices from in the future, with or without a subscription.", "description": "BillingTemplate generates Purchase objects, either to issue one-time invoices or in a subscription.\n\nIt does so by copying over its' `PurchaseDetails`, one of its `BillingTemplateClient`-s and generating other fields from BillingTemplate's fields as necessary into a new `Purchase` object.\n\nIf `is_subscription` is `true`, it is considered to be a subscription's BillingTemplate. You will need to specify `subscription_*` fields like `subscription_period` when creating it and add BillingTemplateClient objects to its billing cycle (`POST /billing_templates/{id}/add_subscriber/`). After that the clients will receive recurring invoices (that will be paid for automatically if client saves their card) according to the BillingTemplate settings you have specified.\n\nIf `is_subscription` is `false`, this BillingTemplate is used to send one-time invoices. After creating it and specifying `invoice_*` fields, use `POST /billing_templates/{id}/send_invoice/` request to send the actual invoices. BillingTemplateClients for non-subscription BillingTemplates are not saved.", "responses": {"201": {"$ref": "#/components/responses/BillingTemplate"}, "400": {"$ref": "#/components/responses/400"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BillingTemplate"}}}}, "tags": ["Billing"]}, "get": {"operationId": "billing_templates_list", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/BillingTemplate"}}, "next": {"nullable": true, "type": "string", "description": "The next page of pagination results. `null` if there are no more results."}, "previous": {"nullable": true, "type": "string", "description": "The previous page of pagination results. `null` if there was no previous page."}}}}}}}, "summary": "List all billing templates.", "tags": ["Billing"]}}, "/billing_templates/{id}/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "billing_templates_read", "responses": {"200": {"$ref": "#/components/responses/BillingTemplate"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Retrieve a billing template by ID.", "tags": ["Billing"]}, "put": {"operationId": "billing_templates_update", "responses": {"200": {"$ref": "#/components/responses/BillingTemplate"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BillingTemplate"}}}}, "summary": "Update a billing template by ID.", "tags": ["Billing"]}, "delete": {"operationId": "billing_templates_delete", "responses": {"204": {"description": "OK"}}, "summary": "Delete a billing template by ID.", "tags": ["Billing"]}}, "/billing_templates/{id}/send_invoice/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "billing_templates_send_invoice", "summary": "Send an invoice, generating a purchase from billing template data.", "description": "Use this request with a BillingTemplate having `is_subscription == false`. Specify the BillingTemplateClient data (only `client_id` field is needed) in the request body. The request will issue a Purchase by combining data of `BillingTemplate.purchase` and `BillingTemplateClient.client` and will send an invoice to your Client. Response will contain data of a created Purchase. The BillingTemplateClient will not be saved.", "responses": {"200": {"$ref": "#/components/responses/Purchase"}, "400": {"$ref": "#/components/responses/400"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BillingTemplateClient"}, "example": {"client_id": "b79d3df6-2f69-4426-acee-eda049d83e18"}}}}, "tags": ["Billing"]}}, "/billing_templates/{id}/add_subscriber/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "billing_templates_add_subscriber", "summary": "Add a billing template client and activate recurring billing (is_subscription: true).", "description": "Use this request with a BillingTemplate having `is_subscription == true`. Two scenarios are possible: \n\n\u2022 If `subscription_charge_period_end == true` and/or `subscription_trial_periods > 0` (first billing should happen after 1 or more billing periods, not today), the request will create a BillingTemplateClient and start trial/schedule billing for it (as required by subscription settings). Successful response will be of form `{billing_template_client: , purchase: null}`: no Purchase is created, `BillingTemplateClient.status` is `active` immediately. \n\n\u2022 If `subscription_charge_period_end == false` and `subscription_trial_periods == 0` (first billing should occur today), the request will create a BillingTemplateClient with `status == pending` and create a Purchase. When such a Purchase is paid, the respective BillingTemplateClient will have its' subscription activated (starting from the day of payment), with its `status` changing to `active`. Successful response will be of form `{billing_template_client: , purchase: }`: you should redirect your client to `purchase.checkout_url` for him to pay immediately (as you do with `POST /purchases/`).", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"properties": {"billing_template_client": {"$ref": "#/components/schemas/BillingTemplateClient"}, "purchase": {"description": "Nullable in `POST /billing_templates/{id}/add_subscriber/` response.", "allOf": [{"$ref": "#/components/schemas/Purchase"}]}}}}}}, "400": {"$ref": "#/components/responses/400"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BillingTemplateClient"}, "example": {"client_id": "b79d3df6-2f69-4426-acee-eda049d83e18"}}}}, "tags": ["Billing"]}}, "/billing_templates/{id}/clients/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "billing_templates_clients_list", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/BillingTemplateClient"}}, "next": {"nullable": true, "type": "string", "description": "The next page of pagination results. `null` if there are no more results."}, "previous": {"nullable": true, "type": "string", "description": "The previous page of pagination results. `null` if there was no previous page."}}}}}}}, "summary": "List all billing template clients for this billing template.", "tags": ["Billing"]}}, "/billing_templates/{id}/clients/{id}/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "billing_templates_clients_read", "responses": {"200": {"$ref": "#/components/responses/BillingTemplateClient"}, "404": {"$ref": "#/components/responses/404"}}, "parameters": [{"$ref": "#/components/parameters/id"}], "summary": "Retrieve a billing template client by client's ID.", "tags": ["Billing"]}, "patch": {"operationId": "billing_templates_clients_partial_update", "responses": {"200": {"$ref": "#/components/responses/BillingTemplateClient"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "parameters": [{"$ref": "#/components/parameters/id"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BillingTemplateClient"}, "example": {"status": "active"}}}}, "summary": "Partially update a billing template client by client's ID.", "tags": ["Billing"]}}, "/clients/": {"post": {"operationId": "clients_create", "description": "Client is a record of a single customer of your business. Create one for each of your clients; you will be able to issue invoices/subscriptions for them later easily using `/billing_templates/` API.\n\nEach BillingTemplateClient (there can be many attached to a single BillingTemplate) will bind a single Client to a BillingTemplate.", "responses": {"201": {"$ref": "#/components/responses/Client"}, "400": {"$ref": "#/components/responses/400"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Client"}}}}, "summary": "Create a new client.", "tags": ["Clients"]}, "get": {"operationId": "clients_list", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/Client"}}, "next": {"nullable": true, "type": "string", "description": "The next page of pagination results. `null` if there are no more results."}, "previous": {"nullable": true, "type": "string", "description": "The previous page of pagination results. `null` if there was no previous page."}}}}}}}, "summary": "List all clients.", "tags": ["Clients"]}}, "/clients/{id}/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "clients_read", "responses": {"200": {"$ref": "#/components/responses/Client"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Retrieve an object by ID.", "tags": ["Clients"]}, "put": {"operationId": "clients_update", "responses": {"200": {"$ref": "#/components/responses/Client"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Client"}}}}, "summary": "Update a client by ID.", "tags": ["Clients"]}, "patch": {"operationId": "clients_partial_update", "responses": {"200": {"$ref": "#/components/responses/Client"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Client"}}}}, "summary": "Partially update a client by ID.", "tags": ["Clients"]}, "delete": {"operationId": "clients_delete", "responses": {"204": {"description": "OK"}}, "summary": "Delete a client by ID.", "tags": ["Clients"]}}, "/clients/{id}/recurring_tokens/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "client_recurring_tokens_list", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/ClientRecurringToken"}}, "next": {"nullable": true, "type": "string", "description": "The next page of pagination results. `null` if there are no more results."}, "previous": {"nullable": true, "type": "string", "description": "The previous page of pagination results. `null` if there was no previous page."}}}}}}}, "summary": "List recurring tokens saved for a client.", "description": "All of these tokens will be available in a checkout (see `Purchase.checkout_url`) if you create a Purchase with this client's ID in `client_id` field. \n\nYou can use one in `POST /purchases/{id}/charge/`, too. Note that you can use one client's `recurring_token` to pay a Purchase created for a different `client_id` or created with no `client_id` at all; it's not recommended to do this.", "tags": ["Clients"]}}, "/clients/{id}/recurring_tokens/{id}/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "client_recurring_tokens_read", "responses": {"200": {"$ref": "#/components/responses/ClientRecurringToken"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Retrieve an object by ID.", "tags": ["Clients"]}, "delete": {"operationId": "client_recurring_tokens_delete", "responses": {"204": {"description": "OK"}}, "summary": "Delete a client recurring token by ID.", "description": "If you create the Purchase with the respective Client's ID (in `.client_id`), he won't see this token as available on checkout page anymore. \n\nYou also won't be able to use the ID of this object as a `recurring_token` in `POST /purchases/{id}/charge/`. The respective Purchase will have `is_recurring_token` set to `false` (as if `POST /purchases/{recurring_token}/delete_recurring_token/` was issued).", "tags": ["Clients"]}}, "/webhooks/": {"post": {"operationId": "webhooks_create", "responses": {"201": {"$ref": "#/components/responses/Webhook"}, "400": {"$ref": "#/components/responses/400"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Webhook"}}}}, "summary": "Create a new webhook.", "tags": ["Webhooks"]}, "get": {"operationId": "webhooks_list", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/Webhook"}}, "next": {"nullable": true, "type": "string", "description": "The next page of pagination results. `null` if there are no more results."}, "previous": {"nullable": true, "type": "string", "description": "The previous page of pagination results. `null` if there was no previous page."}}}}}}}, "summary": "List all webhooks.", "tags": ["Webhooks"]}}, "/webhooks/{id}/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "webhooks_read", "responses": {"200": {"$ref": "#/components/responses/Webhook"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Retrieve an object by ID.", "tags": ["Webhooks"]}, "put": {"operationId": "webhooks_update", "responses": {"200": {"$ref": "#/components/responses/Webhook"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Webhook"}}}}, "summary": "Update a webhook by ID.", "tags": ["Webhooks"]}, "patch": {"operationId": "webhooks_partial_update", "responses": {"200": {"$ref": "#/components/responses/Webhook"}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Webhook"}}}}, "summary": "Partially update a webhook by ID.", "tags": ["Webhooks"]}, "delete": {"operationId": "webhooks_delete", "responses": {"204": {"description": "OK"}}, "summary": "Delete a webhook by ID.", "tags": ["Webhooks"]}}, "/webhooks/deliveries/": {"get": {"operationId": "webhooks_deliveries_list", "parameters": [{"name": "id", "in": "query", "description": "ID of the source object (Purchase, Payment, Payout, or BillingTemplateClient) to retrieve webhook deliveries for.", "required": true, "schema": {"type": "string", "format": "uuid"}}, {"name": "source_type", "in": "query", "description": "Type of the source object.", "required": true, "schema": {"$ref": "#/components/schemas/WebhookSourceType"}}], "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookDelivery"}}, "next": {"nullable": true, "type": "string", "description": "The next page of pagination results. `null` if there are no more results."}, "previous": {"nullable": true, "type": "string", "description": "The previous page of pagination results. `null` if there was no previous page."}}, "example": {"next": null, "previous": null, "results": [{"created_on": "2025-08-19T07:29:25.612314Z", "delivered_on": null, "attempts": 0, "delivery_attempts": [], "url": "https://example.com/webhook", "event": "purchase.created", "payload": {"example": "value"}}]}}}}}, "400": {"$ref": "#/components/responses/400"}, "404": {"$ref": "#/components/responses/404"}}, "summary": "List webhook deliveries for a specific object.", "description": "Returns a paginated list of webhook deliveries for a specific source object (Purchase, Payment, Payout, or BillingTemplateClient).\n\nYou must provide both `id` and `source_type` query parameters to identify the object whose webhook deliveries you want to retrieve.\n\nDeliveries show the complete history of webhook attempts for the specified object, including successful deliveries, failures, and retries.", "tags": ["Webhooks"]}}, "/public_key/": {"get": {"description": "Returns public key for authenticating company callback payloads", "summary": "Get a callback public key.", "parameters": [], "operationId": "public_key", "responses": {"200": {"description": "Public key for authenticating callback payloads", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PublicKey"}}}}}, "tags": ["Public Key"]}}, "/balance/": {"get": {"operationId": "balance", "responses": {"200": {"description": "Balance data successfully retrieved", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CompanyBalance"}}}}, "400": {"$ref": "#/components/responses/400"}}, "summary": "Get balance data.", "description": "Returns balance data, including ecommerce and bank accounts.", "tags": ["Balance"]}}, "/company_statements/": {"post": {"operationId": "company_statements_create", "summary": "Schedule a statement generation.", "description": "With this request, you can schedule a statement generation for a company. \n\nIn a response, you will get an object with the following structure. Main fields to look out for here are `id`, `status` and `download_url`.", "parameters": [{"$ref": "#/components/parameters/from"}, {"$ref": "#/components/parameters/to"}, {"$ref": "#/components/parameters/paid_from"}, {"$ref": "#/components/parameters/paid_to"}, {"$ref": "#/components/parameters/updated_from"}, {"$ref": "#/components/parameters/updated_to"}, {"$ref": "#/components/parameters/brand_id"}, {"$ref": "#/components/parameters/shop_id"}, {"$ref": "#/components/parameters/q"}, {"$ref": "#/components/parameters/products"}, {"$ref": "#/components/parameters/total"}, {"$ref": "#/components/parameters/currency"}, {"$ref": "#/components/parameters/payment_method"}, {"$ref": "#/components/parameters/three_d_secure"}, {"$ref": "#/components/parameters/country"}, {"$ref": "#/components/parameters/status"}, {"$ref": "#/components/parameters/product"}], "responses": {"201": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CompanyStatement"}}}}, "400": {"$ref": "#/components/responses/400"}}, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CompanyStatement"}, "example": {"format": "csv", "timezone": "UTC"}}}}, "tags": ["Company Statements"]}, "get": {"operationId": "company_statements_list", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"type": "object", "properties": {"results": {"type": "array", "items": {"$ref": "#/components/schemas/CompanyStatement"}}, "next": {"nullable": true, "type": "string", "description": "The next page of pagination results. `null` if there are no more results."}, "previous": {"nullable": true, "type": "string", "description": "The previous page of pagination results. `null` if there was no previous page."}}}}}}}, "summary": "List all generated statements.", "tags": ["Company Statements"]}}, "/company_statements/{id}/": {"parameters": [{"$ref": "#/components/parameters/id"}], "get": {"operationId": "company_statements_read", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CompanyStatement"}}}}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Retrieve a statement by ID.", "tags": ["Company Statements"]}}, "/company_statements/{id}/cancel/": {"parameters": [{"$ref": "#/components/parameters/id"}], "post": {"operationId": "company_statements_cancel", "responses": {"200": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CompanyStatement"}}}}, "404": {"$ref": "#/components/responses/404"}}, "summary": "Cancel a statement generation by ID.", "tags": ["Company Statements"]}}}, "components": {"parameters": {"id": {"name": "id", "required": true, "in": "path", "description": "Object ID (UUID)", "schema": {"type": "string", "format": "uuid"}}, "tokenized": {"in": "query", "name": "tokenized", "description": "Filter result set by whether the transaction was performed using a recurring execution token", "schema": {"type": "boolean"}}, "from": {"in": "query", "name": "from", "description": "Filter result set to only include values older or equal to the provided Unix timestamp", "schema": {"type": "integer"}}, "paid_from": {"in": "query", "name": "paid_from", "description": "Filter paid result set to only include values older or equal to the provided Unix timestamp", "schema": {"type": "integer"}}, "paid_to": {"in": "query", "name": "paid_to", "description": "Filter paid result set to only include values younger than the provided Unix timestamp", "schema": {"type": "integer"}}, "updated_to": {"in": "query", "name": "updated_to", "description": "Filter result set to only include values younger than the provided last modification time Unix timestamp", "schema": {"type": "integer"}}, "updated_from": {"in": "query", "name": "updated_from", "description": "Filter result set to only include values older or equal to the provided last modification time Unix timestamp", "schema": {"type": "integer"}}, "brand_id": {"in": "query", "name": "brand_id", "description": "Filter result set to only include the specified brand UUID(s)", "schema": {"type": "string", "format": "uuid"}}, "shop_id": {"in": "query", "name": "shop_id", "description": "Filter result set to only include the specified shop UUID(s)", "schema": {"type": "string", "format": "uuid"}}, "q": {"in": "query", "name": "q", "description": "Filter result set to only include results including a specified text (search over a ton of text fields)", "schema": {"type": "string", "format": "string"}}, "products": {"in": "query", "name": "products", "description": "Filter result set to only include results including a specified text in products", "schema": {"type": "string", "format": "string"}}, "total": {"in": "query", "name": "total", "description": "Filter result set to only include results with a total between min and max value. Must include 2 values, if any - (min, max).", "schema": {"type": "string", "format": "float"}}, "three_d_secure": {"in": "query", "name": "three_d_secure", "description": "Filter result set to only include results with a 3-D verification.", "schema": {"type": "string", "format": "bool"}}, "status": {"in": "query", "name": "status", "description": "Filter result set to only include results with a specific status. See Purchase and Payout for more information.", "schema": {"type": "string", "format": "string"}}, "to": {"in": "query", "name": "to", "description": "Filter result set to only include values younger than the provided Unix timestamp", "schema": {"type": "integer"}}, "brand": {"in": "query", "name": "brand", "description": "Filter result set to only include the specified brand UUID(s)", "schema": {"type": "string", "format": "uuid"}}, "terminal_uid": {"in": "query", "name": "terminal_uid", "description": "Filter result set to only include the specified terminal UUID(s)", "schema": {"type": "string", "format": "uuid"}}, "currency": {"in": "query", "name": "currency", "description": "Filter result set to only include specified currency(ies)", "schema": {"type": "string"}}, "payment_method": {"in": "query", "name": "payment_method", "description": "Filter result set to only include specified payment methods(s). See PaymentMethod fro more information.", "schema": {"$ref": "#/components/schemas/PaymentMethod"}}, "product": {"in": "query", "name": "product", "description": "Filter result set to only include specified products(s). See TransactionProduct fro more information.", "schema": {"$ref": "#/components/schemas/TransactionProduct"}}, "flow": {"in": "query", "name": "flow", "description": "Filter result set to only include specified transaction creation or execution flow(s). See TransactionFlow fro more information.", "schema": {"$ref": "#/components/schemas/TransactionFlow"}}, "country": {"in": "query", "name": "country", "description": "Filter result set to only include specified client country(ies) in ISO 3166-1 alpha-2 format", "schema": {"type": "string", "format": "ISO 3166-1 alpha-2"}}, "banking_account": {"in": "query", "name": "banking_account", "description": "Filter result set to only include specified banking account UUID(s)", "schema": {"type": "string", "format": "uuid"}}}, "responses": {"400": {"description": "Invalid data submitted or request processing error", "content": {"application/json": {"schema": {"type": "object", "example": "{\n \"__all__\": {\n \"message\": \"descriptive error message\",\n \"code\": \"error_code\"\n }\n}\n"}}}}, "404": {"description": "No such object"}, "BillingTemplateClient": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BillingTemplateClient"}}}}, "BillingTemplate": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/BillingTemplate"}}}}, "Purchase": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Purchase"}}}}, "Payout": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Payout"}}}}, "Payment": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Payment"}}}}, "Client": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Client"}}}}, "ClientRecurringToken": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ClientRecurringToken"}}}}, "Webhook": {"description": "OK", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Webhook"}}}}}, "schemas": {"BankAccount": {"type": "object", "description": "Bank account", "properties": {"id": {"$ref": "#/components/parameters/id", "description": "Bank account ID"}, "iban": {"type": "string", "description": "International Bank Account Number (IBAN)"}, "swift": {"type": "string", "description": "Society for Worldwide Interbank Financial Telecommunication (SWIFT) code"}, "bank_account": {"type": "string", "description": "Bank account number"}, "bank_code": {"type": "string", "description": "Bank code"}, "real_bank_account": {"type": "string", "description": "Real bank account number"}, "real_bank_code": {"type": "string", "description": "Real bank code"}, "currency": {"$ref": "#/components/schemas/Currency", "description": "Currency code"}, "status": {"type": "string", "description": "Bank account status"}, "name": {"type": "string", "description": "Bank account name"}, "reference": {"type": "string", "description": "Bank account reference"}, "available_balance": {"$ref": "#/components/schemas/MoneyAmount", "description": "Available balance"}, "reserved_balance": {"$ref": "#/components/schemas/MoneyAmount", "description": "Reserved balance"}, "extended_ui": {"type": "string", "description": "Extended UI"}, "fx_currencies": {"type": "array", "description": "Foreign exchange currencies", "items": {"$ref": "#/components/schemas/Currency"}}}}, "BankAccountMixin": {"type": "object", "properties": {"bank_account": {"type": "string", "maxLength": 34, "description": "Bank account number (e.g. IBAN)"}, "bank_code": {"type": "string", "maxLength": 11, "description": "SWIFT/BIC code of the bank"}}}, "BaseModel": {"type": "object", "properties": {"type": {"type": "string", "readOnly": true, "description": "Object type identifier"}, "id": {"type": "string", "format": "uuid", "readOnly": true}, "created_on": {"readOnly": true, "description": "Object creation time", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "updated_on": {"readOnly": true, "description": "Object last modification time", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}}}, "BillingTemplate": {"description": "BillingTemplate generates Purchase objects, either to issue one-time invoices or in a subscription.\n\nIt does so by copying over its' `PurchaseDetails`, one of its `BillingTemplateClient`-s and generating other fields from BillingTemplate's fields as necessary into a new `Purchase` object.\n\nIf `is_subscription` is `true`, it is considered to be a subscription's BillingTemplate. You will need to specify `subscription_*` fields like `subscription_period` when creating it and add BillingTemplateClient objects to its billing cycle (`POST /billing_templates/{id}/add_subscriber/`). After that the clients will receive recurring invoices (that will be paid for automatically if client saves their card) according to the BillingTemplate settings you have specified.\n\nIf `is_subscription` is `false`, this BillingTemplate is used to send one-time invoices. After creating it and specifying `invoice_*` fields, use `POST /billing_templates/{id}/send_invoice/` request to send the actual invoices. BillingTemplateClients for non-subscription BillingTemplates are not saved.", "required": ["purchase", "is_subscription"], "properties": {"purchase": {"$ref": "#/components/schemas/PurchaseDetails"}, "company_id": {"type": "string", "format": "uuid", "readOnly": true}, "number_of_billing_cycles": {"type": "integer", "description": "Limits number of billing cycles for each client if set to a non-zero value"}, "is_test": {"type": "boolean", "readOnly": true, "description": "Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode."}, "user_id": {"type": "string", "format": "uuid", "nullable": true, "readOnly": true, "description": "ID of user who has created this object in the Billing UI, if applicable."}, "brand_id": {"type": "string", "format": "uuid", "description": "ID of the brand to create this BillingTemplate for. You can copy it down in the API section, see the \"specify the ID of the Brand\" link in answer to \"How to setup payments on website or in mobile app?\"."}, "title": {"type": "string", "maxLength": 256}, "is_subscription": {"type": "boolean", "description": "Defines whether this BillingTemplate issues invoices in a recurring manner - it's a subscription - or it sends invoices only once. You can't change this parameter when you edit the BillingTemplate. If this field is `true`, you will need to specify `subscription_*` fields and `invoice_*` fields are read-only, and vice-versa."}, "invoice_issued": {"nullable": true, "description": "Sets `issued` on the Purchase objects generated. Generated from current day in `purchase.timezone` if not provided. Read-only if `is_subscription == true`.", "allOf": [{"$ref": "#/components/schemas/Timestamp"}]}, "invoice_due": {"nullable": true, "description": "Sets `due` on the Purchase objects generated. Required if `is_subscription == false`, read-only otherwise.", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "invoice_skip_capture": {"type": "boolean", "default": false, "description": "Sets `skip_capture` on the Purchase objects generated. `false` by default. Read-only if `is_subscription == true`."}, "invoice_send_receipt": {"type": "boolean", "default": false, "description": "Sets `send_receipt` on the Purchase objects generated. `true` by default (unlike in Purchases API, where by default receipts are not sent). Read-only if `is_subscription == true`."}, "subscription_period": {"description": "Defines how often are the subscription Purchases generated. Used together with `subscription_period_units`: to issue Purchases once a month, use `\"...period\": 1` and `\"...period_units\" == \"months\"`. \n\nVariable number of days in a month is respected; e.g. if subscription has a period of 1 month, a client had its billing cycle activated on January 30 and there are 28 days in February that year - billing scheduled for February will happen on 28th.\n\nBoth fields are required when creating a BillingTemplate with `is_subscription == true`/editing a BillingTemplate with `is_subscription == true` as long as there aren't any launched subscribers; they are read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if `is_subscription == false`.", "type": "integer", "minimum": 1, "maximum": 256, "default": 1}, "subscription_period_units": {"description": "See `subscription_period`.", "default": "months", "allOf": [{"$ref": "#/components/schemas/PeriodUnits"}]}, "subscription_due_period": {"description": "Used to generate `due` on the Purchase objects generated. Used together with `subscription_due_period_units`: to set the final `Purchase.due` to a week after it's generated/invoice is sent, use `\"...period\": 1` and `\"...period_units\" == \"weeks\". Required if `is_subscription == true`, read-only otherwise.", "type": "integer", "minimum": 1, "maximum": 256, "default": 7}, "subscription_due_period_units": {"description": "See `subscription_due_period`.", "default": "days", "allOf": [{"$ref": "#/components/schemas/PeriodUnits"}]}, "subscription_charge_period_end": {"description": "If this is `true`, clients are charged at the end of billing periods, and vice-versa. E.g. if you add a subscriber client to a BillingTemplate, with this value being set to `false`, he will receive first invoice today, otherwise - after a single billing period (defined by `subscription_period`/`subscription_period_units`) passes. \n\nRequired when creating a BillingTemplate with `is_subscription == true`/editing a BillingTemplate with `is_subscription == true` as long as there aren't any launched subscribers; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if `is_subscription == false`.", "type": "boolean", "default": false}, "subscription_trial_periods": {"description": "How many trial periods to give the client prior to starting his billing cycle. If billing period is 1 month and you set this value to 2, subscription will automatically adjust to giving your client 2 months without payments and then charging him for the 3rd month (when exactly depends on `subscription_charge_period_end`: 3 months after the subscriber was launched for `false`, 4 for `true`). `\"subscription_trial_periods\": 0` disables this feature. \n\nRequired when creating a BillingTemplate with `is_subscription == true`/editing a BillingTemplate with `is_subscription == true` as long as there aren't any launched subscribers; read-only otherwise, whether it's BillingTemplate's editing when there already are clients activated or if `is_subscription == false`.", "type": "integer", "minimum": 0, "maximum": 256, "default": 0}, "subscription_active": {"description": "Whether this subscription is paused. Has the same effect as setting `\"status\": \"subscription_paused\"` for every BillingTemplateClient launched for this subscription, see the description of `status` on BillingTemplateClient for more details.\n\nIgnored (read-only) if `is_subscription == false`.", "type": "boolean", "default": false}, "subscription_has_active_clients": {"description": "If this is `true`, there were launched clients (`POST /billing_templates/{id}/add_subscriber/` - or subscribers that were added via the gateway system UI) for this subscription.\n\nWhile this is `false` (it will be as long as you're only just created the template and haven't launched any subscribers), you can edit all of `subscription_*` fields. \n\nIf this is `true`, you're only allowed to edit `subscription_due_period`, `subscription_due_period_units` and `subscription_active`. \n\nIs always `false` if `is_subscription == false`.", "type": "boolean", "readOnly": true}, "force_recurring": {"type": "boolean", "default": false, "description": "If the used payment method supports recurring payment functionality, forces the customer's payment credentials to be saved for possible later recurring payments, without giving the customer a choice in the matter."}, "upsell_campaigns": {"type": "array", "items": {"type": "string", "format": "uuid"}, "description": "Array of IDs of related Upsell campaigns."}, "referral_campaign_id": {"type": "string", "format": "uuid", "nullable": true, "description": "ID of Referral campaign."}}, "allOf": [{"$ref": "#/components/schemas/BaseModel"}]}, "BillingTemplateClient": {"description": "Connects a Client object to a BillingTemplate having `is_subscription = true` to store information about a single subscriber.\n\n You will be able to pause an individual subscription client's cycle by PATCH-ing its' `status` field to the value of `subscription_paused`.", "required": ["client_id"], "properties": {"client_id": {"type": "string", "format": "uuid", "description": "ID of the Client object to add to the BillingTemplate. Read-only after the BillingTemplateClient has been created. Note that the same Client can be added to a BillingTemplate several times."}, "number_of_billing_cycles_passed": {"type": "integer", "readOnly": true, "description": "Only used together with number_of_billing_cycles on BillingTemplate. Shows number of billing cycles passed when number of cycles is limited"}, "invoice_reference": {"type": "string", "maxLength": 128, "nullable": true, "description": "When present overrides reference for invoices generated for this client"}, "status": {"type": "string", "default": "inactive", "enum": ["pending", "inactive", "active", "subscription_paused"], "description": "For subscriptions, you can edit (`PATCH /billing_templates/{id}/clients/{id}/`) this status between `active` and `subscription_paused` values to pause the client's subscription. Paused subscriptions run as normal, except for purchases not being created and invoices sent for them. It means that if you pause a BillingTemplateClient's monthly subscription cycle a day before the billing date, the next day the invoice will not be issued; but, if you unpause the client a day after the planned billing would have taken place, the planned billing in a month (minus one day) will happen as usual.\n\nRead-only if the BillingTemplateClient is in `inactive` (internal status not managed through public API) or `pending` (see documentation for `POST /billing_templates/{id}/add_subscriber/`) statuses."}, "subscription_billing_scheduled_on": {"description": "If not null, reports the date when the next billing is scheduled for this client.", "readOnly": true, "nullable": true, "default": null, "allOf": [{"$ref": "#/components/schemas/Timestamp"}]}, "payment_method_whitelist": {"type": "array", "minItems": 1, "description": "An optional whitelist of payment methods availble for purchases generated for this BillingTemplateClient. Copied 1:1 to `Purchase.payment_method_whitelist` field on created Purchases (see its description).", "items": {"type": "string", "description": "Payment method name as returned by `GET /payment_methods/`."}}, "send_invoice_on_charge_failure": {"type": "boolean", "default": true, "description": "Sends invoice when subscription charge fails if this is `true`"}, "send_invoice_on_add_subscriber": {"type": "boolean", "default": false, "description": "Sends invoice when `POST /billing_templates/{id}/add_subscriber/` is called if this is `true`"}, "send_receipt": {"type": "boolean", "default": true, "description": "Sends receipt when subscription charge succeeds if this is `true`"}}, "allOf": [{"$ref": "#/components/schemas/BaseModel"}]}, "City": {"type": "string", "maxLength": 128, "description": "City name"}, "Client": {"description": "Record of a single customer of your business. Create one for each of your clients; you will be able to issue invoices/subscriptions for them later easily using `/billing_templates/` API.\n\nEach BillingTemplateClient (there can be many attached to a single BillingTemplate) will bind a single Client to a BillingTemplate.", "allOf": [{"$ref": "#/components/schemas/BaseModel"}, {"$ref": "#/components/schemas/ClientDetails"}]}, "ClientDetails": {"description": "Contains details about the client of a purchase or payment - the remote payer/fund recipient party.", "required": ["email"], "properties": {"email": {"$ref": "#/components/schemas/Email"}, "phone": {"$ref": "#/components/schemas/Phone"}, "full_name": {"type": "string", "maxLength": 128, "description": "Name and surname of client"}, "personal_code": {"type": "string", "maxLength": 32, "description": "Personal identification code of client"}, "street_address": {"$ref": "#/components/schemas/StreetAddress"}, "country": {"$ref": "#/components/schemas/Country"}, "city": {"$ref": "#/components/schemas/City"}, "zip_code": {"$ref": "#/components/schemas/ZIPCode"}, "state": {"$ref": "#/components/schemas/State"}, "shipping_street_address": {"$ref": "#/components/schemas/StreetAddress"}, "shipping_country": {"$ref": "#/components/schemas/Country"}, "shipping_city": {"$ref": "#/components/schemas/City"}, "shipping_zip_code": {"$ref": "#/components/schemas/ZIPCode"}, "shipping_state": {"$ref": "#/components/schemas/State"}, "cc": {"type": "array", "items": {"$ref": "#/components/schemas/Email"}, "description": "Email addresses to receive a carbon copy of all notification emails"}, "bcc": {"type": "array", "items": {"$ref": "#/components/schemas/Email"}, "description": "Email addresses to receive a blind carbon copy of all notification emails"}, "legal_name": {"type": "string", "maxLength": 128, "description": "Legal name of company"}, "brand_name": {"type": "string", "maxLength": 128, "description": "Company brand name"}, "registration_number": {"type": "string", "maxLength": 32, "description": "Registration number of company"}, "tax_number": {"type": "string", "maxLength": 32, "description": "Tax payer registration number"}, "delivery_methods": {"type": "array", "items": {"type": "object", "properties": {"method": {"type": "string", "enum": ["email", "text_message"], "description": "The method of invoice delivery"}, "options": {"type": "object", "description": "Additional options for the delivery method", "properties": {"custom_message": {"type": "string", "description": "Custom message for text message delivery"}}}}, "required": ["method", "options"]}, "description": "List of delivery methods for invoices", "default": [{"method": "email", "options": {}}]}}, "allOf": [{"$ref": "#/components/schemas/BankAccountMixin"}]}, "ClientRecurringToken": {"allOf": [{"$ref": "#/components/schemas/BaseModel"}, {"description": "A record of one of `recurring_token`-s saved for a specific client. `id` of this object will be the same as the `recurring_token` saved.", "properties": {"payment_method": {"type": "string", "readOnly": true, "description": "Payment method used to create this token, e.g. `card`."}, "description": {"type": "string", "readOnly": true, "description": "Description of this token, if available. For card payments, this field will contain the masked card number."}}}]}, "CompanyBalance": {"type": "object", "description": "Balance data", "properties": {"ecommerce": {"description": "Ecommerce data", "type": "array", "items": {"$ref": "#/components/schemas/EcommerceItem"}}, "bank_accounts": {"description": "Bank account data", "type": "array", "items": {"$ref": "#/components/schemas/BankAccount"}}, "payout_balances_enabled": {"type": "object", "additionalProperties": {"type": "boolean"}}}, "example": {"ecommerce": [{"currency": "GBP", "gross_balance": 3232409, "balance": 3232409, "available_balance": 3185444, "reserved": 0, "pending_outgoing": 46965, "fee_sell": 0, "payout_gross_balance": 0, "payout_balance": 0, "available_payout_balance": 0, "pending_payouts": 0, "payout_overdraft": 0, "payout_fee_sell": 0}, {"currency": "USD", "gross_balance": 3827891, "balance": 3827891, "available_balance": 3802744, "reserved": 0, "pending_outgoing": 25147, "fee_sell": 0, "payout_gross_balance": 0, "payout_balance": 0, "available_payout_balance": 0, "pending_payouts": 0, "payout_overdraft": 0, "payout_fee_sell": 0}, {"currency": "EUR", "gross_balance": 7763713, "balance": 7763713, "available_balance": 7729281, "reserved": 0, "pending_outgoing": 34432, "fee_sell": 0, "payout_gross_balance": 0, "payout_balance": 0, "available_payout_balance": 0, "pending_payouts": 0, "payout_overdraft": 0, "payout_fee_sell": 0}], "bank_accounts": [{"id": "9088acbc-54e5-4ff0-8b94-d08f855aa09c", "iban": "GB29NWBK60161331926819", "swift": "SPELGB11", "bank_account": "TEST", "bank_code": "SG0000000001", "real_bank_account": "GB29NWBK60161331926819", "real_bank_code": "SPELGB11", "currency": "GBP", "status": "active", "name": "", "reference": "SPELGB11", "available_balance": 9996003, "reserved_balance": 3385, "extended_ui": null, "fx_currencies": ["EUR", "USD", "GBP"]}, {"id": "d6f63e07-4954-42e0-a87c-45167bd2e401", "iban": "DE00SPEL00000000005882", "swift": "SPELDE66", "bank_account": "", "bank_code": "", "real_bank_account": "DE00SPEL00000000005882", "real_bank_code": "SPELDE66", "currency": "EUR", "status": "active", "name": "Account 1", "reference": null, "available_balance": 12567256, "reserved_balance": 0, "extended_ui": null, "fx_currencies": []}], "payout_balances_enabled": {"EUR": false, "GBP": false, "USD": false}}}, "CompanyStatement": {"type": "object", "properties": {"format": {"type": "string", "maxLength": 32, "description": "Statement format, available formats: `csv`, `xlsx`."}, "timezone": {"type": "string", "format": "TZ database name", "description": "Timezone to localize statement-specific timestamps", "example": "Europe/Oslo"}, "is_test": {"type": "boolean", "readOnly": true, "description": "Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode."}, "company_uid": {"type": "string", "format": "uuid", "readOnly": true, "description": "ID of the Company."}, "query_string": {"type": "string", "readOnly": true, "description": "Query parameters used to generate statement."}, "status": {"type": "string", "readOnly": true, "description": "Status of statement generation e.g. `pending`, `processing`, `success`."}, "download_url": {"type": "string", "readOnly": true, "description": "Download URL of a statement."}, "began_on": {"readOnly": true, "description": "Date and time for the beginning of statement generation process.", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "finished_on": {"readOnly": true, "description": "Date and time for finishing the statement generation process.", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "created_on": {"readOnly": true, "description": "Object creation time", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "updated_on": {"readOnly": true, "description": "Object last modification time", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "type": {"type": "string", "readOnly": true, "description": "Statement request type"}, "id": {"type": "string", "format": "uuid", "readOnly": true, "description": "ID of a statement"}}}, "Country": {"type": "string", "maxLength": 2, "format": "ISO 3166-1 alpha-2", "description": "Country code in the ISO 3166-1 alpha-2 format (e.g. 'GB')"}, "Currency": {"type": "string", "maxLength": 3, "format": "ISO 4217", "description": "Currency code in the ISO 4217 standard (e.g. 'EUR'). Default currency is `EUR`."}, "EcommerceItem": {"type": "object", "description": "Ecommerce item", "properties": {"currency": {"$ref": "#/components/schemas/Currency"}, "gross_balance": {"$ref": "#/components/schemas/MoneyAmount"}, "balance": {"$ref": "#/components/schemas/MoneyAmount"}, "available_balance": {"$ref": "#/components/schemas/MoneyAmount"}, "reserved": {"$ref": "#/components/schemas/MoneyAmount"}, "pending_outgoing": {"$ref": "#/components/schemas/MoneyAmount"}, "fee_sell": {"$ref": "#/components/schemas/MoneyAmount"}, "payout_gross_balance": {"$ref": "#/components/schemas/MoneyAmount"}, "payout_balance": {"$ref": "#/components/schemas/MoneyAmount"}, "available_payout_balance": {"$ref": "#/components/schemas/MoneyAmount"}, "pending_payouts": {"$ref": "#/components/schemas/MoneyAmount"}, "payout_overdraft": {"$ref": "#/components/schemas/MoneyAmount"}, "payout_fee_sell": {"$ref": "#/components/schemas/MoneyAmount"}}}, "Email": {"type": "string", "format": "email", "maxLength": 254, "description": "Email address"}, "Event": {"type": "string", "description": "Available event types and when they are emitted:\n\n`purchase.created`: Emitted when a Purchase is created. This happens as a result of POST /purchases/ request executed successfully or of any of the Billing API methods, including scheduled billing run by a BillingTemplate with is_subscription = true. Purchase.status will be == `created` in the received payload.\n\n---\n\n`purchase.paid`: Emitted when a Purchase is paid for. Purchase.status will be == `paid`. Happens when a payform is submitted (for a Purchase having `skip_capture == false`) and a successful payment is done by the payer or in case of /capture/ or /charge/ API requests executed successfully.\n\n---\n\n`purchase.payment_failure`: Emitted when payer submits a payment using the payform, but it doesn't complete successfully (e.g. because payer's account balance is insufficient). Purchase.status will be == `error`.\n\n---\n\n`purchase.refund_failure`: Emitted when a pending refund fails.\n\n---\n\n`purchase.capture_failure`:Emitted when a pending capture fails. The Purchase status is expected to be 'hold' after that.\n\n---\n\n`purchase.release_failure`: Emitted when a pending release fails. The Purchase status is expected to be 'hold' after that.\n\n---\n\n`purchase.pending_execute`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_execute` Purchase status. When transaction becomes finalized, a `purchase.paid`, `purchase.hold` or `purchase.payment_failed` callback will be emitted.\n\n---\n\n`purchase.pending_charge`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_charge` Purchase status. When transaction becomes finalized, a `purchase.paid` or `purchase.payment_failed` callback will be emitted.\n\n---\n\n`purchase.cancelled`: Emitted once POST /purchases/{id}/cancel/ request succeeds. It won't be possible to pay for the related Purchase after that. Purchase.status will be == `cancelled`.\n\n---\n\n`purchase.hold`: Emitted when a Purchase having `skip_capture == true` has its payform submitted and \"payment\" performed successfully. The specified amount of funds will be placed on hold. Purchase.status will be == `hold`.\n\n---\n\n`purchase.captured`: Emitted when the POST /purchases/{id}/capture/ request for a Purchase that previously had the status of `hold` succeeds. Purchase.status will be == `paid`.\n\n---\n\n`purchase.pending_capture`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_capture` Purchase status. When transaction becomes finalized, a `purchase.captured` callback will be emitted.\n\n---\n\n`purchase.released`: Emitted when the POST /purchases/{id}/release/ request for a Purchase that previously had the status of `hold` succeeds. Funds reserved will be released with no payment performed. Purchase.status will be == `released`.\n\n---\n\n`purchase.pending_release`: Emitted when transaction execution takes longer than expected on the acquirer side. See `pending_release` Purchase status. When transaction becomes finalized, a `purchase.released` callback will be emitted.\n\n---\n\n`purchase.preauthorized`: Emitted when preauthorization scenario (see description for the Purchase.skip_capture field) is executed successfully. Purchase will have a status of `preauthorized`.\n\n---\n\n`purchase.recurring_token_deleted`: Emitted when the POST /purchases/{id}/delete_recurring_token/ request is executed successfully, deleting the recurring token associated with a Purchase. Purchase status will be the same as it were prior to this event.\n\n---\n\n`purchase.pending_recurring_token_delete`: Emitted when token deletion takes longer than expected on the acquirer side. When operation is finalized, a `purchase.recurring_token_deleted` callback will be emitted.\n\n---\n\n`purchase.subscription_charge_failure`: Emitted when an attempt to charge some Client's subscription-generated Purchase, using the token (e.g. card) they saved for their subscription, fails. Can only be emitted for a Purchase spawned from a BillingTemplate having is_subscription == true. Usually means the system can't charge the subscriber Client's card because e.g. their account balance is insufficient or card is expired, hence an invoice to be paid manually will be automatically mailed to them. Purchase.status in the returned payload will be == `sent`.\n\n---\n\n`purchase.pending_refund`: Emitted when refund transaction execution takes longer than expected on the acquirer side. See `pending_refund` Purchase status. When refund becomes finalized, a `payment.refunded` callback will ne emitted.\n\n---\n\n`payment.refunded`: Emitted when a Purchase is refunded (as a result of POST /purchases/{id}/capture/ request done successfully or action performed in company's frontoffice system). The returned data will be a Payment object generated as a result of this action. A link to the original Purchase (that will have a status of `refunded`) will be present in the `related_to` field of this Payment.\n\n---\n\n`billing_template_client.subscription_billing_cancelled`: Emitted when a subscriber represented by this event's related BillingTemplateClient cancels their subscription using an email link available in the receipts he receives. The respective BillingTemplateClient will have its `status` set to `subscription_paused` as a result.\n\n---\n\n`payout.pending`: Emitted when Payout execution has been initiated and is currently processing.\n\n---\n\n`payout.failed`: Emitted when a Payout processing was completed with an error. Payout.status will be == `error`. Note that payouts can spend up to 3-5 days (depending on the payout provider) in processing after being initiated.\n\n---\n\n`payout.success`: Emitted when a Payout is successfully processed. Payout.status will be == `success`. Note that payouts can spend up to 3-5 days (depending on the payout provider) in processing after being initiated.\n\n---\n\n`payment.charged_back`: Emitted when a Payment is charged_back.\n\n---\n\n`purchase.viewed`: Emitted when a Purchase is viewed.\n\n---\n\n`purchase.settled`: Emitted when a Purchase is settled.\n\n---\n\n`payout.created`: Emitted when a Payout is created.\n\n---\n\n`payment.chargeback_reversed`: Emitted when a Payment chargeback is reversed.", "enum": ["purchase.created", "purchase.paid", "purchase.payment_failure", "purchase.refund_failure", "purchase.capture_failure", "purchase.release_failure", "purchase.pending_execute", "purchase.pending_charge", "purchase.cancelled", "purchase.hold", "purchase.captured", "purchase.pending_capture", "purchase.released", "purchase.pending_release", "purchase.preauthorized", "purchase.pending_recurring_token_delete", "purchase.recurring_token_deleted", "purchase.subscription_charge_failure", "purchase.pending_refund", "payment.refunded", "billing_template_client.subscription_billing_cancelled", "payout.pending", "payout.failed", "payout.success", "payment.charged_back", "purchase.viewed", "purchase.settled", "payout.created", "payment.chargeback_reversed"]}, "FeeSell": {"allOf": [{"$ref": "#/components/schemas/MoneyAmount"}, {"description": "Fees applied to transactions"}]}, "IssuerDetails": {"description": "Read-only details of issuer company/brand, persisted for invoice display.", "readOnly": true, "properties": {"website": {"readOnly": true, "description": "Company website URL", "allOf": [{"$ref": "#/components/schemas/URL"}]}, "legal_street_address": {"readOnly": true, "allOf": [{"$ref": "#/components/schemas/StreetAddress"}]}, "legal_country": {"readOnly": true, "allOf": [{"$ref": "#/components/schemas/Country"}]}, "legal_city": {"readOnly": true, "allOf": [{"$ref": "#/components/schemas/City"}]}, "legal_zip_code": {"readOnly": true, "allOf": [{"$ref": "#/components/schemas/ZIPCode"}]}, "bank_accounts": {"type": "array", "readOnly": true, "items": {"$ref": "#/components/schemas/BankAccountMixin"}}, "legal_name": {"type": "string", "maxLength": 128, "description": "Legal name of company", "readOnly": true}, "brand_name": {"type": "string", "maxLength": 128, "description": "Company brand name", "readOnly": true}, "registration_number": {"type": "string", "maxLength": 32, "description": "Registration number of company", "readOnly": true}, "tax_number": {"type": "string", "maxLength": 32, "description": "Tax payer registration number", "readOnly": true}}}, "MoneyAmount": {"type": "integer", "description": "Amount of money as the smallest indivisible units of the currency. Examples: 1 cent for EUR and 1 Yen for JPY."}, "Payment": {"description": "A record of a performed financial transaction. Can be generated e.g. as a result of refund operation.", "properties": {"client": {"readOnly": true, "allOf": [{"$ref": "#/components/schemas/ClientDetails"}]}, "payment": {"readOnly": true, "allOf": [{"$ref": "#/components/schemas/PaymentDetails"}]}, "transaction_data": {"type": "object", "description": "Payment method-specific, read-only, internal transaction data. Will contain information about all the transaction attempts, if available.", "nullable": true, "readOnly": true}, "related_to": {"type": "object", "nullable": true, "readOnly": true, "description": "The object type and id this object is related to, if any. E.g. refund Payments are related to a specific Purchase, so this object will contain `type: purchase` and `id: `.", "properties": {"type": {"type": "string", "readOnly": true, "description": "Object type identifier"}, "id": {"type": "string", "format": "uuid", "readOnly": true}}}, "reference_generated": {"type": "string", "readOnly": true, "description": "If an explicit invoice `reference` wasn't provided, this autogenerated value will be used as a reference instead."}, "reference": {"type": "string", "maxLength": 128, "readOnly": true, "description": "Invoice reference."}, "account_id": {"type": "string", "format": "uuid", "readOnly": true, "description": "ID of an account this Payment is associated with."}, "company_id": {"type": "string", "format": "uuid", "readOnly": true}, "is_test": {"type": "boolean", "readOnly": true, "description": "Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode."}, "user_id": {"type": "string", "format": "uuid", "nullable": true, "readOnly": true, "description": "ID of user who has created this object in the Billing UI, if applicable."}, "brand_id": {"type": "string", "format": "uuid", "readOnly": true, "description": "ID of the brand this Payment is associated with."}}, "allOf": [{"$ref": "#/components/schemas/BaseModel"}]}, "PaymentDetails": {"description": "Details of an executed transaction. Read-only for `Purchase`s and `Payout`s. For an unpaid `Purchase`, this object will be `null`.", "properties": {"is_outgoing": {"type": "boolean", "default": false, "description": "Denotes the direction of payment, e.g. for a paid Purchase, is granted to be `false`, `true` for payouts."}, "payment_type": {"type": "string", "readOnly": true, "enum": ["purchase", "purchase_charge", "payout", "bank_payment", "refund", "custom"]}, "amount": {"$ref": "#/components/schemas/MoneyAmount"}, "currency": {"$ref": "#/components/schemas/Currency"}, "net_amount": {"x-summary": "Net amount of payment with all fees and pending amount subtracted. `amount` = `net_amount` + `fee_amount` + `pending_amount`. The respective account is credited or debited with this value.", "readOnly": true, "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "fee_amount": {"x-summary": "Amount of fees for this payment. For a Purchase's PurchaseDetails this is the calculated transaction fee.", "readOnly": true, "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "pending_amount": {"x-summary": "Pending amount for this payment that will be unfrozen later. If e.g. it's a Purchase's PaymentDetails and a part of transaction sum is withheld to form a rolling reserve, this field will be equal to the frozen part amount.", "readOnly": true, "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "pending_unfreeze_on": {"x-summary": "Informs when the `pending_amount` will be unfrozen.", "readOnly": true, "nullable": true, "default": null, "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "description": {"type": "string", "maxLength": 256}, "paid_on": {"readOnly": true, "description": "When the payment was accepted in (`is_outgoing == false`) or sent from (`is_outgoing == true`) the gateway system.", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "remote_paid_on": {"readOnly": true, "description": "If available, this field will report the date the payment was sent by the remote payer (`is_outgoing == false`) or when funds arrived to the remote beneficiary (`is_outgoing == true`).", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}}}, "PaymentMethod": {"type": "string", "description": "Payment method used to execute the transaction.\n\n- citadele_ee_digilink: Citadele Estonia\n- citadele_ee_pis: Citadele Estonia Payment Initiation Service\n- citadele_lt_digilink: Citadele Lithuania\n- citadele_lt_pis: Citadele Lithuania Payment Initiation Service\n- citadele_lv_digilink: Citadele Latvia\n- citadele_lv_pis: Citadele Latvia Payment Initiation Service\n- coop_pank_ee_pis: Coop Pank Estonia Payment Initiation Service\n- indexo_ee_pis: Indexo Estonia Payment Initiation Service\n- indexo_lt_pis: Indexo Lithuania Payment Initiation Service\n- indexo_lv_pis: Indexo Latvia Payment Initiation Service\n- indexo_pis: Indexo Payment Initiation Service\n- klix: Klix Payment Gateway\n- klix_apple_pay: Klix Apple Pay\n- klix_google_pay: Klix Google Pay\n- klix_pay_later: Klix Pay Later\n- klix_pay_later_ee: Klix Pay Later Ee\n- klix_pay_later_lt: Klix Pay Later Lt\n- klix_pay_later_lv: Klix Pay Later Lv\n- lhv_ee_pis: LHV Estonia Payment Initiation Service\n- lku_lt_pis: LKU Lithuania Payment Initiation Service\n- luminor_ee_pis: Luminor Estonia Payment Initiation Service\n- luminor_lt_pis: Luminor Lithuania Payment Initiation Service\n- luminor_lv_pis: Luminor Latvia Payment Initiation Service\n- paysera_ee_pis: Paysera Estonia Payment Initiation Service\n- paysera_lt_pis: Paysera Lithuania Payment Initiation Service\n- paysera_lv_pis: Paysera Latvia Payment Initiation Service\n- revolut_pis: Revolut Payment Initiation Service\n- seb_ee_pis: SEB Estonia Payment Initiation Service\n- seb_lt_pis: SEB Lithuania Payment Initiation Service\n- seb_lv_pis: SEB Latvia Payment Initiation Service\n- siauliu_lt_pis: Artea Bankas Lithuania Payment Initiation Service\n- swedbank_ee_pis: Swedbank Estonia Payment Initiation Service\n- swedbank_lt_pis: Swedbank Lithuania Payment Initiation Service\n- swedbank_lv_pis: Swedbank Latvia Payment Initiation Service\n- unknown: Payment method could not be determinded", "enum": ["citadele_ee_digilink", "citadele_ee_pis", "citadele_lt_digilink", "citadele_lt_pis", "citadele_lv_digilink", "citadele_lv_pis", "coop_pank_ee_pis", "indexo_ee_pis", "indexo_lt_pis", "indexo_lv_pis", "indexo_pis", "klix", "klix_apple_pay", "klix_google_pay", "klix_pay_later", "klix_pay_later_ee", "klix_pay_later_lt", "klix_pay_later_lv", "lhv_ee_pis", "lku_lt_pis", "luminor_ee_pis", "luminor_lt_pis", "luminor_lv_pis", "paysera_ee_pis", "paysera_lt_pis", "paysera_lv_pis", "revolut_pis", "seb_ee_pis", "seb_lt_pis", "seb_lv_pis", "siauliu_lt_pis", "swedbank_ee_pis", "swedbank_lt_pis", "swedbank_lv_pis", "unknown"]}, "Payout": {"description": "Record of a single payout operation. Has a status attribute, e.g. can be initialized, error or success.", "required": ["payment", "client", "brand_id"], "properties": {"payment": {"required": ["amount", "currency"], "allOf": [{"$ref": "#/components/schemas/PaymentDetails"}]}, "client": {"required": ["email"], "allOf": [{"$ref": "#/components/schemas/ClientDetails"}]}, "transaction_data": {"type": "object", "description": "Payment method-specific, read-only transaction data. Will contain information about all the transaction attempts and possible errors, if available.", "readOnly": true, "properties": {"payment_method": {"type": "string", "description": "Payment method used if Payout was paid, blank string otherwise."}, "extra": {"type": "object", "description": "Extra data associated with selected payment method if Payout was paid, empty object otherwise. Dataset depends on payment method. E.g. for card payment methods like `visa` or `mastercard` it will contain properties `masked_pan: string`, `three_d_secure: boolean`, `expiry_month: int`, `expiry_year: int` and `cardholder_name: string`."}, "country": {"type": "string", "description": "Country code (in the ISO 3166-1 alpha-2 format e.g. 'GB') where payment tool used originates (e.g. in case of card payments, the card issuing country). Will be blank if Payout was not paid or country could not be detected."}, "attempts": {"type": "array", "description": "Will contain information about all the payment attempts made and errors encountered, if any.", "items": {"type": "object", "properties": {"successful": {"type": "boolean", "description": "If this attempt was successful or not. For `false`, `error` of this attempt will be not null."}, "payment_method": {"type": "string", "description": "Payment method used for this attempt."}, "extra": {"type": "object", "description": "Extra data associated with selected payment method. Dataset depends on payment method. E.g. for card payment methods like `visa` or `mastercard` it will contain properties `masked_pan: string`, `three_d_secure: boolean`, `expiry_month: int`, `expiry_year: int` and `cardholder_name: string`."}, "country": {"type": "string", "description": "Country code (in the ISO 3166-1 alpha-2 format e.g. 'GB') where payment tool used originates (e.g. in case of card payments, the card issuing country). Will be blank if country could not be detected."}, "client_ip": {"type": "string", "format": "IP", "description": "IP the paying client made this attempt from, if available."}, "processing_time": {"description": "Time (if possible, fetched from the remot processing system) this attempt happened at.", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "error": {"type": "object", "nullable": true, "description": "Code and description of the error encountered. Not-null if `successful` parameter of this attempt is `false`.", "properties": {"code": {"type": "string", "description": "Available error codes: \n\n---\n\n`unknown_payment_method`: Unknown payment method\n\n---\n\n`invalid_card_number`: Invalid card number\n\n---\n\n`invalid_expires`: Invalid expires\n\n---\n\n`no_matching_terminal`: No matching terminal\n\n---\n\n`blacklisted_tx`: Blacklisted transaction: blocked (general)\n\n---\n\n`timeout_3ds_enrollment_check`: 3DS enrollment check timeout\n\n---\n\n`timeout_acquirer_status_check`: Timeout checking payment status with acquirer\n\n---\n\n`validation_card_details_missing`: Card data field values are missing from request\n\n---\n\n`validation_cvc_not_provided`: `cvc` field not provided\n\n---\n\n`validation_cardholder_name_not_provided`: `cardholder_name` field not provided\n\n---\n\n`validation_card_number_not_provided`: `card_number` field not provided\n\n---\n\n`validation_expires_not_provided`: `expires` field not provided\n\n---\n\n`validation_cvc_too_long`: `cvc` is too long\n\n---\n\n`validation_cardholder_name_too_long`: `cardholder_name` is too long\n\n---\n\n`validation_card_number_too_long`: `card_number` is too long\n\n---\n\n`validation_expires_too_long`: `expires` is too long\n\n---\n\n`3ds_authentication_failed`: 3DS authentication failed\n\n---\n\n`validation_cvc_invalid`: `cvc` is invalid\n\n---\n\n`validation_cardholder_name_invalid`: `cardholder_name` is too long or invalid\n\n---\n\n`validation_card_number_invalid`: `card_number` is invalid\n\n---\n\n`validation_expires_invalid`: `expires` is invalid\n\n---\n\n`acquirer_connection_error`: Acquirer connection error\n\n---\n\n`blacklisted_tx_issuing_country`: Blacklisted transaction: issuing country\n\n---\n\n`s2s_not_supported`: Server-to-server flow not supported by processing\n\n---\n\n`timeout`: Operation timeout\n\n---\n\n`general_transaction_error`: Unrecognized transaction error\n\n---\n\n`antifraud_general`: Decline, fraud\n\n---\n\n`acquirer_internal_error`: Acquirer internal error\n\n---\n\n`exceeds_frequency_limit`: Exceeds frequency limit\n\n---\n\n`insufficient_funds`: Insufficient funds\n\n---\n\n`purchase_already_paid_for`: Purchase is already paid for\n\n---\n\n`issuer_not_available`: Issuer Not Available\n\n---\n\n`do_not_honour`: Do not honour (the transaction was declined by the Issuer without definition or reason).\n\n---\n\n`exceeds_withdrawal_limit`: Exceeds withdrawal limit\n\n---\n\n`exceeded_account_limit`: Exceeded account limit\n\n---\n\n`expired_card`: Expired card\n\n---\n\n`blacklisted_tx_risk_score`: Blacklisted transaction: risk score\n\n---\n\n`transaction_not_supported_or_not_valid_for_card`: The transaction request presented is not supported or is not valid for the card number presented.\n\n---\n\n`exceeded_acquirer_refund_amount`: Exceeded refundable amount defined by acquirer\n\n---\n\n`transaction_not_permitted_on_terminal`: Transaction not permitted on terminal (this card does not support the type of transaction requested).\n\n---\n\n`acquirer_configuration_error`: Acquirer configuration error\n\n---\n\n`transaction_not_permitted_to_cardholder`: Transaction not permitted to cardholder\n\n---\n\n`invalid_issuer_number`: No such issuer (the Issuer number is not valid).\n\n---\n\n`restricted_card`: Restricted card\n\n---\n\n`merchant_response_timeout`: Timeout of merchant response exceeded\n\n---\n\n`reconcile_error`: Reconcilation error\n\n---\n\n`lost_card`: Lost card\n\n---\n\n`stolen_card`: Stolen card\n\n---\n\n`invalid_amount`: Invalid amount\n\n---\n\n`re_enter_transaction`: Re enter transaction\n\n---\n\n`security_violation`: Security violation\n\n---\n\n`partial_forbidden`: Intervene, bank approval required for partial amount\n\n---\n\n`suspected_fraud`: Decline, suspected fraud\n\n---\n\n`acquirer_routing_error`: Acquirer routing error\n\n---\n\n`payment_rejected_other_reason`: Payment rejected (other reason)\n\n---\n\n`authorization_failed`: Payment authorization failed\n\n---\n\n`acquirer_error_cs`: Internal acquirer error. Please, contact support.\n\n---\n\n`decline_irregular_transaction_pattern`: Declined by acquirer - irregular transaction pattern, please contact support\n\n---\n\n`invalid_card_data`: Invalid card data provided\n\n---\n\n`exceeded_terminal_limit`: Exceeded terminal limit\n\n---\n\n`recurring_token_expired`: recurring token expired\n\n---\n\n`soft_decline_contact_support`: Soft Decline - Please contact support for manual settlement of this purchase\n\n---\n\n`payment_method_details_missing`: Missing payment_method_details\n\n---\n\n`validation_phone_invalid`: `phone` is invalid\n\n---\n\n`validation_address_invalid`: address is invalid\n\n---\n\n`validation_email_invalid`: Email is invalid\n\n---\n\n`validation_email_not_provided`: Email address is not provided\n\n---\n\n`validation_email_too_long`: Email address is too long\n\n---\n\n`user_cancelled`: transaction cancelled by user\n\n---\n\n`payment_expired`: Payment session or authorization has expired"}, "message": {"type": "string", "description": "Verbose name and explanation of this error."}}}}}}}}, "reference_generated": {"type": "string", "readOnly": true, "description": "If you don't provide an invoice `reference` yourself, this autogenerated value will be used as a reference instead."}, "reference": {"type": "string", "maxLength": 128, "description": "Payout reference."}, "status": {"$ref": "#/components/schemas/PayoutStatus"}, "status_history": {"type": "array", "readOnly": true, "description": "History of status changes, latest last.", "items": {"properties": {"status": {"$ref": "#/components/schemas/PayoutStatus"}, "timestamp": {"$ref": "#/components/schemas/UnixTimestamp"}}}}, "sender_name": {"type": "string", "maxLength": 40, "description": "Name of payout sender."}, "recipient_card_country": {"type": "string", "readOnly": true, "description": "Recipient's card's registration country. Country code in the ISO 3166-1 alpha-2 format (e.g. `GB`)."}, "recipient_card_brand": {"type": "string", "readOnly": true, "description": "Recipient's card's brand, e.g. `visa` or `mastercard`."}, "payout_method_whitelist": {"type": "array", "minItems": 1, "description": "An optional whitelist of payment methods availble for this Payout. Use this field if you want to restrict your payer to pay using only one or several specific methods.", "items": {"type": "string", "description": "Payment method name as communicated to you by your account manager."}}, "execution_url": {"type": "string", "readOnly": true, "description": "URL that must be used for payout execution. See details in description."}, "brand_id": {"type": "string", "format": "uuid", "description": "ID of the brand to create this Payout for. You can copy it down in the API section, see the \"specify the ID of the Brand\" link in answer to \"How to setup payments on website or in mobile app?\"."}, "issuer_details": {"readOnly": true, "type": "object", "properties": {"legal_name": {"type": "string", "maxLength": 128, "description": "Legal name of company", "readOnly": true}, "brand_name": {"type": "string", "maxLength": 128, "description": "Company brand name", "readOnly": true}}}, "company_id": {"type": "string", "format": "uuid", "readOnly": true}, "is_test": {"type": "boolean", "readOnly": true, "description": "Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode."}, "user_id": {"type": "string", "format": "uuid", "nullable": true, "readOnly": true, "description": "ID of user who has created this object in the Billing UI, if applicable."}}, "allOf": [{"$ref": "#/components/schemas/BaseModel"}]}, "PayoutStatus": {"type": "string", "description": "`Payout` status. Can have the following values: \n\n`initialized`: `Payout` was created, but not executed. Initial status to new `Payout`s.\n\n---\n\n`pending`: `Payout`'s execution is currently pending \n\n---\n\n`error`: An error has occurred during the execution. Execution can be attempted again.\n\n---\n\n`success`: `Payout` was executed successfully.", "default": "initialized", "readOnly": true, "enum": ["initialized", "pending", "error", "success"]}, "PeriodUnits": {"type": "string", "enum": ["days", "weeks", "months"]}, "Phone": {"type": "string", "format": "phone", "maxLength": 32, "description": "Phone number in the ` ` format", "example": "+44 45643564564"}, "Product": {"required": ["name", "price"], "properties": {"name": {"type": "string", "maxLength": 256, "description": "Product name"}, "quantity": {"type": "string", "format": "float", "minimum": 0, "default": 1, "description": "Quantity of these products in invoice"}, "price": {"minimum": 0, "description": "Amount of money as the smallest indivisible units of the currency. Examples: 1 cent for EUR and 1 Yen for JPY. You can use this field or `total_override` with a value of 0 to activate preauthorization scenario. See the description of the `Purchase.skip_capture` field.", "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "discount": {"minimum": 0, "description": "Total discount per this product in invoice", "default": 0, "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "tax_percent": {"type": "string", "format": "float", "minimum": 0, "maximum": 100, "default": 0, "description": "Percent of tax added to the price of this product"}, "category": {"type": "string", "maxLength": 256, "description": "Product category"}, "total_price_override": {"default": null, "nullable": true, "x-summary": "If specified and not null, will override the total by product and will impact `total`", "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}}}, "PublicKey": {"type": "string", "description": "PEM-encoded RSA public key for authenticating webhook or callback payloads", "readOnly": true, "example": "-----BEGIN PUBLIC KEY-----\nMIIBojANBgkqhkiG9w0BAQEFAAOCAY8AMIIBigKCAYEA6gLlBKxCB5dxPJbinCzl\nhOfKSgQtOWQQBxmnWIkEVUbqhpnqr3xNYiAvDyMUxYUwuzN44eHO+mR9MZWcSx3c\nbXmKa3gsOzR6GdcOxMGaVxvfje+fujCAlCtO1BP+A9/FS3KcPgCYG1wtAPwA5IAf\nHylL3TsUVIJQFBgiBr6N4Bgapr9eloaFfeYIBRsXmxPKAMJivqxYpLh0V3N4ZFd5\nTGqSEAa4b1ULDr6p0sB2L3QikTdsF0zp03zNceKA6fXDOzD0xWtg9buXvyKwePK4\nM2kcnWBNfsWghrdg0fG3O9bmkaS1oEXydrmJfuiI8h6a64J/1nzooi2yLC9D6Ta0\nS63bbuAHymnQtiNuV7Ixp6IoTGFaS88aTiHaP8rdyWV8JTDFx0qeDzyaGWiYGwEF\nmj/buHCEcRhoajbGkPhYA4YEdn4jy1wZhEr2OMdBPM7mPPI0Hy3hcNJVMVVlrpHe\nIltQATpjlNaJMlRPjbcaiW7dsO3BuF9ZOMGksSOnyYm/AgMBAAE=\n-----END PUBLIC KEY-----"}, "Purchase": {"description": "Record of a single purchase operation, either a transaction originating from e-commerce integration or invoice sent. Has a status attribute, e.g. can be `created`, `paid` or `refunded`.", "required": ["client", "purchase", "brand_id"], "properties": {"client": {"description": "Either this or `.client_id` is required.", "allOf": [{"$ref": "#/components/schemas/ClientDetails"}]}, "purchase": {"$ref": "#/components/schemas/PurchaseDetails"}, "payment": {"readOnly": true, "nullable": true, "allOf": [{"$ref": "#/components/schemas/PaymentDetails"}]}, "issuer_details": {"readOnly": true, "allOf": [{"$ref": "#/components/schemas/IssuerDetails"}]}, "transaction_data": {"type": "object", "description": "Payment method-specific, read-only transaction data. Will contain information about all the transaction attempts and possible errors, if available.", "readOnly": true, "properties": {"payment_method": {"type": "string", "description": "Payment method used if Purchase was paid, blank string otherwise."}, "extra": {"type": "object", "description": "Extra data associated with selected payment method if Purchase was paid, empty object otherwise. Dataset depends on payment method. E.g. for card payment methods like `visa` or `mastercard` it will contain properties `masked_pan: string`, `three_d_secure: boolean`, `expiry_month: int`, `expiry_year: int` and `cardholder_name: string`. For klix payment method it may contain property `customer_created: bool` to indicate that a new klix profile was created."}, "country": {"type": "string", "description": "Country code (in the ISO 3166-1 alpha-2 format e.g. 'GB') where payment tool used originates (e.g. in case of card payments, the card issuing country). Will be blank if Purchase was not paid or country could not be detected."}, "attempts": {"type": "array", "description": "Will contain information about all the payment attempts made and errors encountered, if any.", "items": {"type": "object", "properties": {"type": {"type": "string", "description": "Type of action attempted", "enum": ["execute", "authorize", "release", "capture", "recurring_execute", "delete_recurring_token", "refund"]}, "successful": {"type": "boolean", "description": "If this attempt was successful or not. For `false`, `error` of this attempt will be not null."}, "payment_method": {"type": "string", "description": "Payment method used for this attempt."}, "extra": {"type": "object", "description": "Extra data associated with selected payment method. Dataset depends on payment method. E.g. for card payment methods like `visa` or `mastercard` it will contain properties `masked_pan: string`, `three_d_secure: boolean`, `expiry_month: int`, `expiry_year: int` and `cardholder_name: string`."}, "country": {"type": "string", "description": "Country code (in the ISO 3166-1 alpha-2 format e.g. 'GB') where payment tool used originates (e.g. in case of card payments, the card issuing country). Will be blank if country could not be detected."}, "client_ip": {"type": "string", "format": "IP", "description": "IP the paying client made this attempt from, if available."}, "processing_time": {"description": "Time (if possible, fetched from the remot processing system) this attempt happened at.", "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "error": {"type": "object", "nullable": true, "description": "Code and description of the error encountered. Not-null if `successful` parameter of this attempt is `false`.", "properties": {"code": {"type": "string", "description": "Available error codes: \n\n---\n\n`unknown_payment_method`: Unknown payment method\n\n---\n\n`invalid_card_number`: Invalid card number\n\n---\n\n`invalid_expires`: Invalid expires\n\n---\n\n`no_matching_terminal`: No matching terminal\n\n---\n\n`blacklisted_tx`: Blacklisted transaction: blocked (general)\n\n---\n\n`timeout_3ds_enrollment_check`: 3DS enrollment check timeout\n\n---\n\n`timeout_acquirer_status_check`: Timeout checking payment status with acquirer\n\n---\n\n`validation_card_details_missing`: Card data field values are missing from request\n\n---\n\n`validation_cvc_not_provided`: `cvc` field not provided\n\n---\n\n`validation_cardholder_name_not_provided`: `cardholder_name` field not provided\n\n---\n\n`validation_card_number_not_provided`: `card_number` field not provided\n\n---\n\n`validation_expires_not_provided`: `expires` field not provided\n\n---\n\n`validation_cvc_too_long`: `cvc` is too long\n\n---\n\n`validation_cardholder_name_too_long`: `cardholder_name` is too long\n\n---\n\n`validation_card_number_too_long`: `card_number` is too long\n\n---\n\n`validation_expires_too_long`: `expires` is too long\n\n---\n\n`3ds_authentication_failed`: 3DS authentication failed\n\n---\n\n`validation_cvc_invalid`: `cvc` is invalid\n\n---\n\n`validation_cardholder_name_invalid`: `cardholder_name` is too long or invalid\n\n---\n\n`validation_card_number_invalid`: `card_number` is invalid\n\n---\n\n`validation_expires_invalid`: `expires` is invalid\n\n---\n\n`acquirer_connection_error`: Acquirer connection error\n\n---\n\n`blacklisted_tx_issuing_country`: Blacklisted transaction: issuing country\n\n---\n\n`s2s_not_supported`: Server-to-server flow not supported by processing\n\n---\n\n`timeout`: Operation timeout\n\n---\n\n`general_transaction_error`: Unrecognized transaction error\n\n---\n\n`antifraud_general`: Decline, fraud\n\n---\n\n`acquirer_internal_error`: Acquirer internal error\n\n---\n\n`exceeds_frequency_limit`: Exceeds frequency limit\n\n---\n\n`insufficient_funds`: Insufficient funds\n\n---\n\n`purchase_already_paid_for`: Purchase is already paid for\n\n---\n\n`issuer_not_available`: Issuer Not Available\n\n---\n\n`do_not_honour`: Do not honour (the transaction was declined by the Issuer without definition or reason).\n\n---\n\n`exceeds_withdrawal_limit`: Exceeds withdrawal limit\n\n---\n\n`exceeded_account_limit`: Exceeded account limit\n\n---\n\n`expired_card`: Expired card\n\n---\n\n`blacklisted_tx_risk_score`: Blacklisted transaction: risk score\n\n---\n\n`transaction_not_supported_or_not_valid_for_card`: The transaction request presented is not supported or is not valid for the card number presented.\n\n---\n\n`exceeded_acquirer_refund_amount`: Exceeded refundable amount defined by acquirer\n\n---\n\n`transaction_not_permitted_on_terminal`: Transaction not permitted on terminal (this card does not support the type of transaction requested).\n\n---\n\n`acquirer_configuration_error`: Acquirer configuration error\n\n---\n\n`transaction_not_permitted_to_cardholder`: Transaction not permitted to cardholder\n\n---\n\n`invalid_issuer_number`: No such issuer (the Issuer number is not valid).\n\n---\n\n`restricted_card`: Restricted card\n\n---\n\n`merchant_response_timeout`: Timeout of merchant response exceeded\n\n---\n\n`reconcile_error`: Reconcilation error\n\n---\n\n`lost_card`: Lost card\n\n---\n\n`stolen_card`: Stolen card\n\n---\n\n`invalid_amount`: Invalid amount\n\n---\n\n`re_enter_transaction`: Re enter transaction\n\n---\n\n`security_violation`: Security violation\n\n---\n\n`partial_forbidden`: Intervene, bank approval required for partial amount\n\n---\n\n`suspected_fraud`: Decline, suspected fraud\n\n---\n\n`acquirer_routing_error`: Acquirer routing error\n\n---\n\n`payment_rejected_other_reason`: Payment rejected (other reason)\n\n---\n\n`authorization_failed`: Payment authorization failed\n\n---\n\n`acquirer_error_cs`: Internal acquirer error. Please, contact support.\n\n---\n\n`decline_irregular_transaction_pattern`: Declined by acquirer - irregular transaction pattern, please contact support\n\n---\n\n`invalid_card_data`: Invalid card data provided\n\n---\n\n`exceeded_terminal_limit`: Exceeded terminal limit\n\n---\n\n`recurring_token_expired`: recurring token expired\n\n---\n\n`soft_decline_contact_support`: Soft Decline - Please contact support for manual settlement of this purchase\n\n---\n\n`payment_method_details_missing`: Missing payment_method_details\n\n---\n\n`validation_phone_invalid`: `phone` is invalid\n\n---\n\n`validation_address_invalid`: address is invalid\n\n---\n\n`validation_email_invalid`: Email is invalid\n\n---\n\n`validation_email_not_provided`: Email address is not provided\n\n---\n\n`validation_email_too_long`: Email address is too long\n\n---\n\n`user_cancelled`: transaction cancelled by user\n\n---\n\n`payment_expired`: Payment session or authorization has expired"}, "message": {"type": "string", "description": "Verbose name and explanation of this error."}}}}}}}}, "status": {"$ref": "#/components/schemas/PurchaseStatus"}, "status_history": {"type": "array", "readOnly": true, "description": "History of status changes, latest last. Might contain entry about a related object, e.g. status change to `refunded` will contain a reference to the refund Payment.", "items": {"properties": {"status": {"$ref": "#/components/schemas/PurchaseStatus"}, "timestamp": {"$ref": "#/components/schemas/UnixTimestamp"}, "related_object": {"nullable": true, "properties": {"type": {"type": "string"}, "id": {"type": "string", "format": "uuid"}}}}}}, "viewed_on": {"description": "Time the payment form or invoice page was first viewed on", "readOnly": true, "nullable": true, "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "company_id": {"type": "string", "format": "uuid", "readOnly": true}, "is_test": {"type": "boolean", "readOnly": true, "description": "Indicates this is a test object, created using test API keys or using Billing section of UI while in test mode."}, "user_id": {"type": "string", "format": "uuid", "nullable": true, "readOnly": true, "description": "ID of user who has created this object in the Billing UI, if applicable."}, "brand_id": {"type": "string", "format": "uuid", "description": "ID of the brand to create this Purchase for. You can copy it down in the API section, see the \"specify the ID of the Brand\" link in answer to \"How to setup payments on website or in mobile app?\"."}, "billing_template_id": {"type": "string", "format": "uuid", "nullable": true, "readOnly": true, "description": "ID of a BillingTemplate that has spawned this Purchase, if any."}, "client_id": {"type": "string", "format": "uuid", "nullable": true, "default": null, "description": "ID of a Client object used to initialize ClientDetails (`.client`) of this Purchase. Either this field or specifying `.client` object is required (you can only specify a value for one of these fields). All `ClientDetails` fields from the Client will be copied to `.client` object. Note that editing Client object won't change the respective fields in already created Purchases. \n\nIf you specify this field and your client saves a `recurring_token` (for instance, by saving their card), the respective ClientRecurringToken will be created. See the `/clients/{id}/recurring_tokens/` endpoint."}, "send_receipt": {"type": "boolean", "default": false, "description": "Whether to send receipt email for this Purchase when it's paid."}, "is_recurring_token": {"type": "boolean", "readOnly": true, "description": "Indicates whether a recurring token (e.g. for card payments - card token) was saved for this Purchase. If this is `true`, the `id` of this Purchase can be used as a `recurring_token` in `POST /purchases/{id}/charge/`, enabling you to pay for that Purchase using the same method (same card for card payments) that this one was paid with."}, "recurring_token": {"type": "string", "format": "uuid", "readOnly": true, "nullable": true, "description": "ID of a recurring token (Purchase having `is_recurring_token == true`) that was used to pay this Purchase, if any."}, "skip_capture": {"type": "boolean", "default": false, "description": "Card payment-specific: if set to true, only authorize the payment (place funds on hold) when payer enters his card data and pays. This option requires a `POST /capture/` or `POST /release/` later on. \n\nYou can use the preauthorization feature if you set this parameter to true and make the Purchase with `purchase.total == 0` (this can be achieved by providing a list of `purchase.products` with a total `price` of 0, or simply overriding the total using `purchase.total_override` to 0). The resulting Purchase can only be \"paid\" by the client (only cardholder data verification will happen, without a financial transaction) by card and will enforce saving the client's card. When this happens, the Purchase will have `status` of `preauthorized` and the `purchase.preauthorized` webhook callbacks will be emitted. \n\nTrying to use skip_capture (or preauthorization) without any payment methods that support the respective actions (this can be a result of `payment_method_whitelist` field being used) will result in an error on Purchase creation request step. Please check the `GET /payment_methods/` response for your desired Purchase parameters and/or consult with your account manager."}, "force_recurring": {"type": "boolean", "default": false, "description": "If the used payment method supports recurring payment functionality, forces the customer's payment credentials to be saved for possible later recurring payments, without giving the customer a choice in the matter."}, "reference_generated": {"type": "string", "readOnly": true, "description": "If you don't provide an invoice `reference` yourself, this autogenerated value will be used as a reference instead."}, "reference": {"type": "string", "maxLength": 128, "description": "Invoice reference."}, "issued": {"description": "Value for 'Invoice issued' field. Display-only, does not get validated. If not provided, will be generated as the current date in `purchase.timezone` at the moment of Purchase's creation.", "nullable": true, "allOf": [{"$ref": "#/components/schemas/Timestamp"}]}, "due": {"description": "When the payment is due for this Purchase. The default behaviour is to still allow payment once this moment passes. To change that, set `purchase.due_strict` to true.", "nullable": true, "allOf": [{"$ref": "#/components/schemas/UnixTimestamp"}]}, "refund_availability": {"description": "Specifies, if the purchase can be refunded fully and partially, only fully, partially or not at all.", "type": "string", "readOnly": true, "enum": ["all", "full_only", "partial_only", "pis_all", "pis_partial", "none"]}, "refundable_amount": {"x-summary": "Amount available for refunds.", "readOnly": true, "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "currency_conversion": {"type": "object", "readOnly": true, "nullable": true, "description": "This object is present when automatic currency conversion has occurred upon creation of the purchase. Purchase's original currency was changed and its original amount was converted using the exchange rate shown here.", "properties": {"original_currency": {"readOnly": true, "type": "string", "description": "Currency this purchase was initially created with"}, "original_amount": {"readOnly": true, "type": "integer", "description": "Amount this purchase was initially created with"}, "exchange_rate": {"readOnly": true, "type": "number", "description": "Exchanged rate that was used for currency conversion. Original amount was multiplied by this number to calculate the new purchase amount."}}}, "payment_method_whitelist": {"type": "array", "minItems": 1, "description": "An optional whitelist of payment methods availble for this purchase. Use this field if you want to restrict your payer to pay using only one or several specific methods. \n\nUsing this field and at the same time trying to use specific capabilities of a Purchase (e.g. `skip_capture` or charging it using a saved card token using `POST /purchases/{id}/charge/`) can cause a situation when there are no payment methods available for paying this Purchase. This will cause a validation error on Purchase creation. Please check the `GET /payment_methods/` response for your desired Purchase parameters and/or consult with your account manager.", "items": {"type": "string", "description": "Payment method name as returned by `GET /payment_methods/`."}}, "success_redirect": {"description": "When Purchase is paid for successfully, your customer will be taken to this link. Otherwise a standard screen will be displayed.", "allOf": [{"$ref": "#/components/schemas/URL"}]}, "failure_redirect": {"description": "If there's a payment failure for this Purchase, your customer will be taken to this link. Otherwise a standard screen will be displayed.", "allOf": [{"$ref": "#/components/schemas/URL"}]}, "cancel_redirect": {"description": "If you provide this link, customer will have an option to go to it instead of making payment (a button with 'Return to seller' text will be displayed). Can't contain any of the following symbols: `<>'\"` .\n\nBe aware that this does not cancel the payment (e.g. does not do the equivalent of doing the `POST /purchases/{id}/cancel/` request); the client will still be able to press 'Back' in the browser and perform the payment.", "allOf": [{"$ref": "#/components/schemas/URL"}]}, "success_callback": {"description": "When Purchase is paid for successfully, the `success_callback` URL will receive a POST request with the Purchase object's data in body.", "allOf": [{"$ref": "#/components/schemas/URL"}]}, "creator_agent": {"type": "string", "maxLength": 32, "description": "Identification of software (e.g. an ecommerce module and version) used to create this purchase, if any."}, "platform": {"type": "string", "enum": ["web", "api", "ios", "android", "macos", "windows"], "description": "Platform this Purchase was created on."}, "product": {"type": "string", "readOnly": true, "enum": ["purchases", "billing_invoices", "billing_subscriptions", "billing_subscriptions_invoice"], "description": "Defines which gateway product was used to create this Purchase."}, "created_from_ip": {"type": "string", "format": "IP", "readOnly": true, "description": "IP the Purchase was created from."}, "invoice_url": {"description": "URL you will be able to access invoice for this Purchase at, if applicable", "readOnly": true, "nullable": true, "allOf": [{"$ref": "#/components/schemas/URL"}]}, "checkout_url": {"description": "URL you will be able to access the checkout for this Purchase at, if payment for it is possible. When building integrations, redirect the customer to this URL once purchase is created. \n\nYou can add the `preferred` query arg to the `checkout_url` in order to force redirect the client straight to the checkout for a specific payment method (`?preferred={payment_method}`, where `{payment_method}` is the payment method name as returned by `GET /payment_methods/`). If this method redirects the client further to a different system and no customer data entry is needed on gateway's checkout page, your payer will be taken straight to that page (not seeing the gateway's checkout UI); otherwise, he will see the payment method entry UI on the gateway checkout page.", "readOnly": true, "allOf": [{"$ref": "#/components/schemas/URL"}]}, "marked_as_paid": {"type": "boolean", "readOnly": true, "description": "True if a purchase was manually marked as paid."}, "order_id": {"type": "string", "readOnly": true, "description": "ID of corresponding order."}, "upsell_campaigns": {"type": "array", "items": {"type": "string", "format": "uuid"}, "description": "Array of IDs of related Upsell campaigns."}, "referral_campaign_id": {"type": "string", "format": "uuid", "nullable": true, "description": "ID of Referral campaign."}, "referral_code": {"type": "string", "readOnly": true, "description": "Referral code used with purchase."}, "referral_code_generated": {"type": "string", "readOnly": true, "description": "Referral code created by purchase."}, "referral_code_details": {"type": "object", "readOnly": true, "description": "Referral code detailed information for purchase.", "properties": {"campaign_id": {"type": "string", "format": "uuid", "readOnly": true, "description": "Referral campaign ID."}, "reward_type": {"type": "string", "enum": ["gift", "discount", "money"], "readOnly": true, "description": "Reward type of applied Referral code."}, "discount_amount": {"readOnly": true, "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "discount_percent": {"type": "number", "format": "float", "readOnly": true, "description": "Discount percent of applied Referral code"}}}, "retain_level_details": {"type": "object", "readOnly": true, "description": "Retain level detailed information for purchase.", "properties": {"campaign_id": {"type": "string", "format": "uuid", "readOnly": true, "description": "Retain campaign ID."}, "discount_amount": {"readOnly": true, "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "discount_percent": {"type": "number", "format": "float", "readOnly": true, "description": "Discount percent of applied Retain level."}}}}, "allOf": [{"$ref": "#/components/schemas/BaseModel"}]}, "PurchaseDetails": {"description": "Core information about the Purchase, including the products, total, currency and invoice fields. If you're using invoicing via `/billing/` or `/billing_templates/`, this object will be copied 1:1 from BillingTemplate you specify to the resulting Purchases (also to subscription Purchases).", "required": ["products"], "properties": {"currency": {"$ref": "#/components/schemas/Currency"}, "products": {"type": "array", "minItems": 1, "description": "Line items of the invoice. In case of a transaction with no invoice sent, specify a single Product forming the cost of transaction.", "items": {"$ref": "#/components/schemas/Product"}}, "total": {"readOnly": true, "x-summary": "Calculated from `products`. You don't need to specify it.", "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "language": {"x-summary": "Language of invoice/payment forms.", "type": "string", "format": "ISO 639-1", "maxLength": 2, "description": "Language code in the ISO 639-1 format (e.g. 'en'). Supported values: `en`, `et`, `lt`, `lv`, `ru`.", "default": "Default value is controlled in Company -> Brand section of merchant portal separately per each Brand used (default value, if no changes are made, is `en`). Brand to be used with corresponding Purchase/BillingTemplate specified using brand_id."}, "notes": {"x-summary": "Invoice notes.", "type": "string", "maxLength": 10000}, "debt": {"default": 0, "x-summary": "Will be added/substracted to the invoice total, if present.", "x-minValue": "`total` * -1", "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "subtotal_override": {"default": null, "nullable": true, "x-summary": "If specified and not null, will override the grand subtotal. This field is visual-only, setting it won't impact `total`.", "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "total_tax_override": {"default": null, "nullable": true, "x-summary": "If specified and not null, will override the total tax. This field is visual-only, setting it won't impact `total`.", "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "total_discount_override": {"default": null, "nullable": true, "x-summary": "If specified and not null, will override the total discount. This field is visual-only, setting it won't impact `total`.", "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "total_override": {"default": null, "nullable": true, "x-summary": "If specified and not null, will override the total (unlike the rest of `total_*_override` fields).\n\nYou can use this field or `products[].total` with a value of 0 to activate preauthorization scenario. See the description of the `Purchase.skip_capture` field.", "allOf": [{"$ref": "#/components/schemas/MoneyAmount"}]}, "request_client_details": {"type": "array", "description": "ClientDetails fields to request from the client before the payment. If a value is passed for a field in ClientDetails, it will be automatically removed from this list.", "default": [], "uniqueItems": true, "items": {"type": "string", "enum": ["email", "phone", "full_name", "personal_code", "brand_name", "legal_name", "registration_number", "tax_number", "bank_account", "bank_code", "billing_address", "shipping_address"]}}, "timezone": {"type": "string", "format": "TZ database name", "description": "Timezone to localize invoice-specific timestamps in, e.g. to display a concrete date for a `due` timestamp on the invoice.", "example": "Europe/Oslo"}, "due_strict": {"type": "boolean", "default": false, "description": "Whether to permit payments when Purchase's `due` has passed. By default those are permitted (and status will be set to `overdue` once `due` moment is passed). If this is set to `true`, it won't be possible to pay for an overdue invoice, and when `due` is passed the Purchase's status will be set to `expired`."}, "email_message": {"type": "string", "readOnly": true, "maxLength": 256, "description": "An optional message to display to your customer in invoice email, e.g. \"Your invoice for June\"."}, "shipping_options": {"required": false, "type": "array", "minItems": 0, "description": "A list of shipping methods to be displayed on klix checkout form.", "items": {"type": "object", "properties": {"id": {"type": "string", "description": "Shipping method id configured in the klix backoffice. Must match exactly."}, "price": {"type": "integer", "description": "Price of shipping for this shipping method. Will be added to the order total. Amount of money as the smallest indivisible units of the currency. Examples: 1 cent for EUR and 1 Yen for JPY."}}}}, "metadata": {"description": "Custom information with maximum length of 10000 characters", "type": "object", "x-maxLength": 10000}, "single_attempt": {"type": "boolean", "default": false, "description": "When set to true, prevents retry attempts if the payment fails. The purchase will be immediately marked as cancelled upon failure, and the payer will not see a retry button on the failure page. If not provided, inherits the value from the Company's `single_attempt` setting."}}}, "PurchaseStatus": {"type": "string", "description": "Purchase status. Can have the following values: \n\n`created`: Purchase was created using POST /purchases/ or Billing API capabilities.\n\n---\n\n`sent`: Invoice for this purchase was sent over email using Billing API capabilities.\n\n---\n\n`viewed`: The client has viewed the payform and/or invoice details for this purchase.\n\n---\n\n`error`: There was a failed payment attempt for this purchase because of a problem with customer's payment instrument (e.g. low account balance). You can analyze the `.transaction_data` to get information on reason of the failure.\n\n---\n\n`cancelled`: Purchase was cancelled using the `POST /purchases/{id}/cancel/` endpoint; payment for it is not possible anymore.\n\n---\n\n`overdue`: Purchase is past its' `.due`, but payment for it is still possible (unless e.g. POST /purchases/{id}/cancel/ is used).\n\n---\n\n`expired`: Purchase is past its' `.due` and payment for it isn't possible anymore (as a result of `purchase.due_strict` having been set to `true`). It\u2019s still possible to have a `paid` status after `expired` if the transaction was initiated before `expired` and the acquirer returned the successful status with delay. \n\n---\n\n`hold`: Funds are on hold for this Purchase (`.skip_capture: true` was used). You can now run `POST /capture/` or `POST /release/` for this payment to capture the payment or return funds to the client, respectively.\n\n---\n\n`released`: This Purchase previously had `hold` status, but funds have since been released and returned to the customer's card.\n\n---\n\n`pending_release`: release of funds for this Purchase is in processing, but is not finalized on the acquirer side yet. Is set by `POST /purchases/{id}/release/` operation when it takes longer than expected to process on the acquirer side.\n\n---\n\n`pending_capture`: capture of funds for this Purchase is in processing, but is not finalized on the acquirer side yet. Is set by `POST /purchases/{id}/capture/` operation when it takes longer than expected to process on the acquirer side.\n\n---\n\n`preauthorized`: A preauthorization of a card (authorization of card data without a financial transaction) was executed successfully using this Purchase. See the description of the `.skip_capture` field for more details.\n\n---\n\n`paid`: Purchase was successfully paid for.\n\n---\n\n`pending_execute`: Payment (or `hold` in case of `skip_capture`) for this Purchase is in processing, but is not finalized on the acquirer side yet.\n\n---\n\n`pending_charge`: Recurring payment for this Purchase is in processing, but is not finalized on the acquirer side yet. Is set by `POST /purchases/{id}/charge/` operation when it takes longer than expected to process on the acquirer side.\n\n---\n\n`retrieved`: A retrieval request was registered for this, previously paid, Purchase.\n\n---\n\n`charged_back`: A chargeback was registered for this, previously paid, Purchase.\n\n---\n\n`pending_refund`: a refund (full or partial) for this Purchase is in processing, but is not finalized on the acquirer side yet. Is set by `POST /purchases/{id}/refund/` operation when it takes longer than expected to process on the acquirer side.\n\n---\n\n`refunded`: This Purchase had its payment refunded, fully or partially.", "default": "created", "readOnly": true, "enum": ["created", "sent", "viewed", "error", "cancelled", "overdue", "expired", "hold", "released", "pending_release", "pending_capture", "preauthorized", "paid", "pending_execute", "pending_charge", "chargeback", "pending_refund", "refunded"]}, "State": {"type": "string", "maxLength": 128, "description": "State code"}, "StreetAddress": {"type": "string", "maxLength": 128, "description": "Street house number and flat address where applicable"}, "Timestamp": {"type": "string", "format": "ISO 8601 (YYYY-MM-DD)", "example": "2020-04-30"}, "TransactionFlow": {"type": "string", "description": "Flow or pathway used to initiate or execute a transaction.\n\n- api: transaction initiated via the merchant API\n- edd: transaction intialized from Easy Digital Downloads module\n- fluentcart: transaction intialized from FluentCart integration\n- fluentforms: transaction intialized from Fluentforms integration\n- formidableforms: transaction intialized from Formidableforms integration\n- givewp: transaction intialized from GiveWP integration\n- gohighlevel: transaction intialized from GoHighLevel integration\n- gravityforms: transaction intialized from Gravity Forms integration\n- hostbill: transaction intialized from Hostbill integration\n- import: transaction imported from external system\n- link: transaction initiated via shared link\n- magento: transaction intialized from Magento module\n- opencart: transaction intialized from OpenCart module\n- payform: transaction executed via the gateway payform\n- paymattic: transaction intialized from Paymattic integration\n- perfexcrm: transaction intialized from Perfex CRM\n- pos: transaction initiated via point of sale terminal\n- prestashop: transaction intialized from PrestaShop module\n- shopify: transaction intialized from Shopify integration\n- web_office: transaction initiated via the merchant portal\n- whmcs: transaction intialized from WHMCS integration\n- woocommerce: transaction intialized from Woocommerce module\n- woocommerce_subscriptions: transaction intialized from Woocommerce subscriptions module\n- wpcharitable: transaction intialized from WPCharitable integration\n- wpfunnels: transaction intialized from WPFunnels Pro module", "enum": ["api", "edd", "fluentcart", "fluentforms", "formidableforms", "givewp", "gohighlevel", "gravityforms", "hostbill", "import", "link", "magento", "opencart", "payform", "paymattic", "perfexcrm", "pos", "prestashop", "shopify", "web_office", "whmcs", "woocommerce", "woocommerce_subscriptions", "wpcharitable", "wpfunnels"]}, "TransactionProduct": {"type": "string", "description": "Product category the transaction belongs to.\n\n- atm_cash: atm_cash (Payment.payment_type == \"atm_cash\")\n- atm_cash_reversal: atm_cash_reversal (Payment.payment_type == \"atm_cash_reversal\")\n- bank_payment: bank_payment (Payment.payment_type == \"bank_payment\")\n- cashback: cashback (Payment.payment_type == \"cashback\")\n- cashback_reversal: cashback_reversal (Payment.payment_type == \"cashback_reversal\")\n- chargeback: Purchase chargeback created through the merchant API (Purchase.product == \"chargeback\")\n- chargeback_reversal: Purchase chargeback reversal created through the Wizard UI\n- custom_payment: custom_payment (Payment.payment_type == \"custom_payment\")\n- deposit: deposit (Payment.payment_type == \"deposit\")\n- deposit_reversal: deposit_reversal (Payment.payment_type == \"deposit_reversal\")\n- invoice: Purchase created as an invoice through the merchant portal (Purchase.product == \"billing_invoices\")\n- manual_cash: manual_cash (Payment.payment_type == \"manual_cash\")\n- manual_cash_reversal: manual_cash_reversal (Payment.payment_type == \"manual_cash_reversal\")\n- purchase: Purchase created through the merchant API (Purchase.product == \"purchases\")\n- refund: refund (Payment.payment_type == \"refund\")\n- refund_reversal: refund_reversal (Payment.payment_type == \"refund_reversal\")\n- subscription: Purchase created using a subscription (Purchase.product is either \"billing_subscriptions\" or \"billing_subscriptions_invoice\")", "enum": ["atm_cash", "atm_cash_reversal", "bank_payment", "cashback", "cashback_reversal", "chargeback", "chargeback_reversal", "custom_payment", "deposit", "deposit_reversal", "invoice", "manual_cash", "manual_cash_reversal", "purchase", "refund", "refund_reversal", "subscription"]}, "URL": {"type": "string", "format": "url", "maxLength": 500}, "UnixTimestamp": {"type": "integer", "format": "Unix timestamp (seconds)", "example": 1619740800}, "Webhook": {"allOf": [{"$ref": "#/components/schemas/BaseModel"}, {"description": "Defines a webhook rule to an external server. The `callback` URL will receive a POST request with the related object's (e.g. Purchase for `purchase.*` webhooks) data in body when any of the events (see the description of `events` field below) it is configured to listen for are triggered.\nThe payload object will additionally include an \"event_type\" field to indicate which event type (see the Webhook.events field) triggered the webhook.\n\n Note that, as well as with the rest of dataset, test and live Webhooks are separate; test webhooks will not handle events caused by live Purchases, and vice-versa.", "required": ["title", "events", "callback"], "properties": {"title": {"type": "string", "maxLength": 100, "description": "Arbitrary title of webhook"}, "all_events": {"type": "boolean", "default": false, "description": "Specifies this webhook should trigger on all event types. Either this or `events` is required."}, "public_key": {"$ref": "#/components/schemas/PublicKey"}, "events": {"type": "array", "minItems": 1, "uniqueItems": true, "description": "List of events to trigger webhook callbacks for. Either this or `all_events` is required.", "items": {"$ref": "#/components/schemas/Event"}}, "callback": {"$ref": "#/components/schemas/URL"}}}]}, "WebhookDelivery": {"type": "object", "description": "Record of a webhook delivery attempt, including the event data sent, delivery status, and retry attempts.", "properties": {"created_on": {"type": "string", "format": "date-time", "description": "Timestamp when the webhook delivery was created.", "example": "2025-08-19T07:29:25.612314Z"}, "delivered_on": {"type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when the webhook was successfully delivered. Null if not yet delivered or failed.", "example": null}, "attempts": {"type": "integer", "description": "Number of delivery attempts made for this webhook.", "example": 0}, "delivery_attempts": {"type": "array", "description": "List of delivery attempts made for this webhook, ordered by most recent first.", "items": {"$ref": "#/components/schemas/WebhookDeliveryAttempt"}}, "url": {"type": "string", "format": "url", "description": "The URL the webhook is being (or was) delivered to.", "example": "https://webhook.example.com/endpoint"}, "event": {"description": "The event type that triggered this delivery.", "allOf": [{"$ref": "#/components/schemas/Event"}]}, "payload": {"type": "object", "nullable": true, "description": "The actual payload that was sent (or will be sent) to the webhook endpoint. Contains the full object data for the event.", "example": {"title": "Test is_internal=False"}}}}, "WebhookDeliveryAttempt": {"type": "object", "description": "Record of an individual webhook delivery attempt.", "properties": {"attempted_on": {"type": "string", "format": "date-time", "description": "Timestamp when this delivery attempt was made.", "example": "2025-08-19T07:30:15.123456Z"}, "error_message": {"type": "string", "maxLength": 100, "description": "Error message if the delivery attempt failed, describing what went wrong.", "example": "Connection timeout after 30 seconds"}}}, "WebhookSourceType": {"type": "string", "description": "Type of object that can trigger webhook events.", "enum": ["purchase", "payment", "payout", "billing_template_client"]}, "ZIPCode": {"type": "string", "maxLength": 32, "description": "ZIP or postal code"}}}}